Introduction

Sovereignty Foundation Inc. · The Pulse Mesh™ Daemon Book

Pulse Mesh^™ Daemon

A runner on the standard: the daemon that routes envelopes between processes through a local port, its Rust client, the dev ring, and the pms tools.

Pulse Mesh Daemon · working draft · reference implementation

Nothing in this book is a release announcement. Licensing questions go to legal@sovfound.org.

Onboard your agent Two programs through the daemon Read the reference

Pulse Mesh™ is a transport substrate built on two byte layouts. The Pulse is a 128-byte control signal that occupies two cache lines and moves through a shared-memory ring without a lock. The PulseEnvelope carries anything larger, at any size, and is addressed by the 16-byte BLAKE3 hash of its canonical bytes, so the same content produces the same identifier in every language that implements the codec. The two layouts, their codec, the ring, the store and the wire are the standard, a repository of its own; this one builds on it.

This repository is the daemon: mesh-hub, which attaches processes over a Unix socket or a WebSocket, routes envelopes between them by channel, and keeps nothing for a subscriber that is not there; the port protocol those processes speak, in JSON, with its golden fixtures; the embedded hub runtime the daemon wraps; the Rust client (Mesh: attach, send, on, tap, run); the dev ring, the general-purpose ring composed on the standard; the pms command line, the pms-mcp server for agents, the telemetry exporter and the basket query tool; the Python and Node thin clients; and the two-process and multi-language examples. It depends on the standard as a sibling checkout (../pulse-mesh) while developing and as a pinned tag at a release.

This book documents the daemon in this repository. It is organised in four parts, each answering one kind of question, and every page states at its top which kind it is and whom it is for.

The four parts

A last part, Contributing, is for people changing the tree: the workspace, the gates, the decision record, and the documentation’s own rules.

Where to start

• Seeing the daemon work: Two programs talk through the daemon, then An agent swarm. Encoding and verifying one envelope first, and sending Pulses over UDP, is Across a network, in the standard’s book.
• Talking to the mesh from another language: the Python and Node steps of Two programs talk through the daemon with the thin clients, and the Rust client; the codec bindings are in the standard’s book.
• Understanding how the pieces fit: Fabric: mesh/ and the dev ring in the Reference part, then Daemon design and Substrate versus contract.
• Contributing: Developer Onboarding, then the documentation style if you are writing.

How this book relates to the rest of the repository

Two records are authoritative, and this book defers to both. The rustdoc (cargo doc --workspace --no-deps --open) is the API contract: every crate opens with an overview, every public item is documented, and a workspace lint keeps it that way. The decision log under decisions/ records why the non-obvious calls were made, in order and without rewriting. The book is the guided path through that material. Where the book and the code disagree, one of them is wrong, and either way it is a defect to report.

The specification is the standard’s, and this book cites it by chapter; only chapter 7, the port protocol, is here, because the daemon is what speaks it.

What this book claims and what it does not

The book describes the tree at the version shown in the sidebar. It records no measured figures. Where it describes a measurement it gives the command that produces one. Where a behaviour is specified but not yet implemented, the page says so and names the test that will prove it. Refutations are welcome: the fastest way to improve a page is to show where it is wrong.

Onboard your agent

Start here · what a coding agent needs to set up Pulse Mesh, run it, and put other agents on the mesh

Pulse Mesh is built to be set up and driven by a coding agent. This page is what you hand it: one prompt to get running, what it needs to know before it changes anything, the MCP server that gives it a live mesh, and how agents talk to each other through one.

1. Paste this

Open an empty folder in your agent and paste:

Set up Pulse Mesh for me. In one empty folder, clone these three repositories side by side, from the GitHub account that publishes Pulse Mesh (the account this repository belongs to; if you are already inside one of them, its git remote names it):
  pulse-mesh
  pulse-mesh-daemon
  pulse-mesh-profiles
Install Rust with rustup if it is missing; each repository pins its version in rust-toolchain.toml.
Then in each repository read AGENTS.md and run its "Prove the tree works" steps up to scripts/gate.sh --quick.
Finally show me it working:
  1. in pulse-mesh, encode, decode and verify one envelope with the pulse command line;
  2. in pulse-mesh-daemon, run pms demo;
  3. in pulse-mesh-profiles, run the robotics example.
Explain in plain words what each step showed. Stop and tell me if anything fails.

2. What your agent needs to know

• Three repositories, side by side. pulse-mesh is the standard; pulse-mesh-daemon and pulse-mesh-profiles build on it and find it at ../pulse-mesh.
• AGENTS.md in each one is the agent’s brief: setup, the order of the first commands, a map of the tree, and the rules every change keeps.
• What is true, in order: the specification, then the test vectors and the port protocol’s fixtures, then the rustdoc, then the decision records, then the rest of this book. When two disagree, one is wrong, and the agent should say so rather than pick one.
• Done means the gate passes. scripts/gate.sh in each repository is the check a change passes before it merges.
• What it must never do: edit a test vector or a fixture to make a test pass, make a deferred feature look implemented, or rewrite an accepted decision record.

3. Give your agent the mesh: MCP

pms-mcp, in the daemon’s repository, is a Model Context Protocol server. With a daemon running, it lets an agent attach to the mesh, send envelopes, check health, query and replay what the basket captured, read a ring’s slots, and round-trip the codec on input it supplies.

cargo install --path tools/pms-mcp --locked   # from pulse-mesh-daemon
claude mcp add pms-mcp -- pms-mcp             # Claude Code; any MCP client that can launch a command works

Use the MCP server from an agent registers it with other clients and tries it by hand, and the MCP tools lists every tool’s input and output.

4. Put agents on the mesh

Agents coordinate the way any programs on the mesh do: each attaches to the daemon by name, subscribes to the channels it cares about, and sends envelopes that reach every subscriber attached at that moment. One agent can plan and others can work:

pms start --foreground                   # one daemon for the machine
pms tap --channel 'jobs/*'               # a worker listens for jobs
pms push jobs/new 'summarise report.pdf' # a planner hands one out

An agent with MCP does the same through mesh_attach and mesh_send. One without it speaks the port protocol directly over the daemon’s WebSocket, through the Python or Node thin client or plain JSON frames. Every envelope is named by a hash of its content, so a receiving agent can check it got exactly what was sent. Two programs talk through the daemon walks through it by hand.

The daemon has no authentication and no encryption, so keep it on loopback, which is its default, when agents share a machine.

An agent swarm builds this in ten minutes: a planner hands out jobs, two workers answer, and every result is checked against its job by hash.

Next

• Developer onboarding: the same setup by hand, in five minutes.
• Use the MCP server from an agent: every client, and the server’s limits.

Use the MCP server from an agent

How-to guide · for anyone giving an agent a running mesh to inspect, publish to, or prove the codec against

pms-mcp is a Model Context Protocol server over stdio: one JSON-RPC request per line in, one response per line out. Any MCP client that can launch a command can use it.

1. Install and check

just install                # installs pms, mesh-hub and pms-mcp; or: cargo install --path tools/pms-mcp --locked
pms-mcp --help

The tools introspect a running daemon (mesh_attach, mesh_send, mesh_health, mesh_query, mesh_replay), prove the codec on supplied input (codec_roundtrip, mesh_envelope_describe), read shared memory (mesh_list_rings, mesh_ring_peek) and list the optimization modules (modules_list, modules_describe). The generated tool reference has each tool’s input schema. The two probe tools are registered only when PMS_MCP_ALLOW_PROBE=1 is set.

2. Register it with the client

With Claude Code:

claude mcp add pms-mcp -- pms-mcp

With any client that reads a JSON configuration, the shape is the same everywhere: a command and, when the basket is somewhere other than the default, its path in the environment.

{ "mcpServers": { "pms-mcp": { "command": "pms-mcp", "env": { "PMS_BASKET_DB": "/path/to/basket.db" } } } }

3. Try it without a client

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | pms-mcp | head -c 400

A daemon must be running for the mesh_* tools; the codec and module tools work without one.

What the server will not do

It has no write path into the ring other than mesh_send, which is the same publish any client can make; it does not start or stop the daemon; and it redacts nothing it did not read from the mesh, so what an agent can see through it is what any attached client can see.

Developer Onboarding

Start here · five minutes from a fresh checkout to a daemon you have watched work, by hand

Working with a coding agent? Start with Onboard your agent: one prompt sets up all three repositories. This page is the same setup by hand.

By hand

1. Set up. Check out the standard at ../pulse-mesh; every manifest here reaches it there. rust-toolchain.toml pins the Rust version, and rustup installs it on the first cargo command.
2. See it work.

   cargo install --path tools/pms --locked
   cargo install --path mesh/mesh-hub --locked
   pms doctor
   pms demo
   

   pms doctor checks the toolchain and the environment. pms demo starts a daemon, passes five messages from a producer to a consumer through it, prints each one, and stops the daemon.
3. Run a mesh yourself. Two programs talk through the daemon starts a daemon and moves envelopes between terminals, programs and languages.
4. Prove the tree. scripts/gate.sh --quick runs the per-commit checks; scripts/gate.sh runs the gate a change passes before it merges. A check whose tool is missing fails and prints the command that installs it.

From there, An agent swarm puts a planner and two workers on the mesh.

Before your first change

• CONTRIBUTING.md says what a contribution means during the beta, holds the table of every check the gate runs, and gives the four-question test for where new code goes, which Workspace Layout explains.
• AGENTS.md lists the rules every change keeps, for a person as much as for an agent: a port-protocol change moves the specification, the fixtures and both thin clients together; the daemon stays on loopback; unsafe only with a // SAFETY: comment; decision records added and never rewritten.
• The specification is normative, the rustdoc is the API contract, and the Decision log records why the non-obvious calls were made. This book explains and guides; where it and the code disagree, one of them is wrong.

Where to read first

• mesh/mesh-hub-runtime/src/lib.rs: the in-process event bus (PulseHub) the mesh-hub daemon wraps.
• mesh/mesh-hub/src/: the daemon, its transports, its per-connection loop, and the bridge to the hub.
• mesh/mesh-port-protocol/src/lib.rs and fixtures/: the messages every client speaks, and the frames the thin clients are held to.
• mesh/mesh-client/src/client.rs: the Rust client (Mesh), which dev-hub re-exports.
• tools/pms/src/main.rs and src/commands/: the pms command line, the most concrete tour of what the daemon does.

Three examples

Part opener · for anyone who wants to see Pulse Mesh work before reading about it

Each example ends with something running on your machine, and each is written to be handed to a coding agent as one prompt or followed by hand. Every step names the command and shows what it prints, and every example closes with checks you can run, what happened, and what the code does not do.

1. Two programs talk through the daemon: start a daemon, publish from the command line, from two Rust programs, and from Python and Node, and watch every message named by its content.
2. An agent swarm: a planner hands out jobs, workers answer: a planner and two workers on one mesh, every result checked against its job by hash.
3. Across a network: encode, verify, send over UDP: one envelope in your hands, then Pulses over UDP between two terminals or two machines, with nothing but the standard.

The first two need the daemon’s repository; the third needs only the standard’s. Where an example lives in another book, its link goes there.

Two programs talk through the daemon

Example · for anyone running Pulse Mesh for the first time, in about fifteen minutes

You will have: a daemon on your machine, and messages moving through it from the command line, from two Rust programs, and from a Python publisher to a Node subscriber. You will have seen every message named by a hash of its content, the same name on every side, and what a subscriber misses while it is away.

You need: the daemon repository set up as Start here describes, with pms and mesh-hub installed and the Rust toolchain. For the other-language step, Python 3 with pip and Node 22 or later with npm; nothing in that step is compiled.

Hand this to your agent

Run the example "Two programs talk through the daemon" from book/src/examples/two-programs.md in the pulse-mesh-daemon repository:
1. Start a daemon in the background: pms start. It prints the process id and its log file. Confirm the log shows "websocket listening".
2. In the background, run pms tap --channel 'jobs/*' and keep its output. Then run pms push jobs/new 'first job' and show me the envelope_id it prints and the line the tap printed; the eight characters after "jobs/new |" in the tap line must be the start of that envelope_id.
3. Run pms push jobs/new 'first job' again and confirm the envelope_id is identical. Run pms push jobs/other 'first job' and confirm it differs.
4. Build and run the two Rust programs: cargo run --release -p multi-process --bin receiver in the background, wait for "attached and subscribed", then cargo run --release -p multi-process --bin sender. Show me that each "sender: sent 'job-N' as envelope X" has a matching "receiver: got 'job-N' (envelope X, 5 bytes)".
5. Install the thin clients, pip install -e clients/pms-py-thin and npm install --prefix peripheral/clients/pms-node-thin. Run node examples/multi-lang/node_subscriber.js in the background, then python3 examples/multi-lang/python_publisher.py, and show me that the identifiers match across the two languages.
6. Run pms ring inspect default_hub --count 2 and tell me what the cursor says about how many Pulses the daemon has written.
7. Stop everything you started, including the daemon (kill the process id from step 1).
Explain in plain words what each step showed. Stop and tell me if anything fails, and say which step.

Or do it by hand

1. Start the daemon

In a first terminal:

pms start --foreground

INFO uds listening path=/tmp/pms.sock
INFO websocket listening addr=127.0.0.1:9876

Those are the two endpoints clients find on their own: pms and the Rust client try the Unix socket, then the WebSocket port, unless PMS_DAEMON names an endpoint (unix:///path or ws://host:port). Leave this terminal alone. Without --foreground, pms start detaches the daemon, prints its process id and log file (~/.local/state/pms/mesh-hub.log), and returns; stop a detached daemon with kill and that id.

2. Watch a channel

In a second terminal:

pms tap --channel 'jobs/*'

tapped; Ctrl-C to stop

tap attaches under a generated name and subscribes to every channel matching jobs/*. It prints one line per event for as long as it runs. Leave it running.

3. Publish from the command line

In a third terminal:

pms push jobs/new 'first job'

envelope_id=cb05c6b8f4b696551a0b7245b6f104a2

and the tap prints:

            jobs/new |        9B | cb05c6b8 | @6b19f89f

Left to right: the channel, the payload size, the first eight characters of the envelope identifier, and the origin, the short form of the publisher’s node id. Now publish three more:

pms push jobs/new 'first job'
pms push jobs/other 'first job'
pms push jobs/new 'first job' --type-name job.created

envelope_id=cb05c6b8f4b696551a0b7245b6f104a2
envelope_id=329b893bbb06850cd40679fd0a2d98d5
envelope_id=759d3a7c705c4d63cba9a36194fc980c

The first identifier is the same as before, because the content is the same: the identifier is computed from the channel, the type name and the payload, and from nothing else. Change the channel and it changes; add a type name and it changes.

4. Two Rust programs

The two programs are in the checkout under examples/multi-process/. The receiver:

//! Template: a receiver process subscribing to channel `jobs`.
//!
//! Pairs with `sender.rs` — see that file's docs for the run order.

#![allow(clippy::print_stdout, clippy::print_stderr)] // an example prints what it does

use mesh_client::Mesh;

fn main() {
    if let Err(e) = receive() {
        eprintln!("receiver: {e}");
        std::process::exit(1);
    }
}

fn receive() -> Result<(), Box<dyn std::error::Error>> {
    let mesh = Mesh::attach("multi-process-receiver")?;
    mesh.on("jobs", |ev| {
        let payload = String::from_utf8_lossy(&ev.payload);
        println!(
            "receiver: got '{}' (envelope {}, {} bytes)",
            payload,
            &ev.envelope_id[..ev.envelope_id.len().min(8)],
            ev.payload.len()
        );
    })?;
    println!("receiver: attached and subscribed to 'jobs' (Ctrl-C to stop)");
    // Returns only when the connection ends; a lost daemon is an error here.
    mesh.run()?;
    Ok(())
}

Mesh::attach connects to the daemon and registers the process under the name you give it. mesh.on subscribes to one channel and hands every event on it to the closure for as long as mesh.run() runs. The sender:

//! Template: a sender process publishing to channel `jobs` once per second.
//!
//! Run with the daemon already running:
//!
//!     # Terminal 1
//!     cargo run -p mesh-hub --release
//!
//!     # Terminal 2
//!     cargo run -p multi-process --bin receiver
//!
//!     # Terminal 3
//!     cargo run -p multi-process --bin sender

#![allow(clippy::print_stdout, clippy::print_stderr)] // an example prints what it does

use mesh_client::Mesh;
use std::thread;
use std::time::Duration;

fn main() {
    if let Err(e) = send_jobs() {
        eprintln!("sender: {e}");
        std::process::exit(1);
    }
}

fn send_jobs() -> Result<(), Box<dyn std::error::Error>> {
    let mesh = Mesh::attach("multi-process-sender")?;
    println!("sender: attached");
    for i in 0..10 {
        let payload = format!("job-{i}");
        let env_id = mesh.send("jobs", payload.as_bytes())?;
        println!(
            "sender: sent '{}' as envelope {}",
            payload,
            &env_id[..env_id.len().min(8)]
        );
        thread::sleep(Duration::from_millis(1000));
    }
    println!("sender: done");
    Ok(())
}

mesh.send publishes the bytes on the channel and returns the identifier the daemon computed. Start the receiver in the third terminal:

cargo run --release -p multi-process --bin receiver

receiver: attached and subscribed to 'jobs' (Ctrl-C to stop)

and the sender in a fourth:

cargo run --release -p multi-process --bin sender

sender: attached
sender: sent 'job-0' as envelope 796abc6e
sender: sent 'job-1' as envelope 5fba33ce
sender: sent 'job-2' as envelope 4166531f

receiver: got 'job-0' (envelope 796abc6e, 5 bytes)
receiver: got 'job-1' (envelope 5fba33ce, 5 bytes)
receiver: got 'job-2' (envelope 4166531f, 5 bytes)

The identifiers match line for line because both sides name the same envelope, and job-0 has the same identifier on every run. After ten messages the sender prints sender: done and exits; the receiver keeps running.

5. The same exchange from Python and Node

Install the two thin clients, each a single file with six calls (attach, send, on, tap, run, detach) and no codec: the daemon computes every identifier.

pip install -e clients/pms-py-thin
npm install --prefix clients/pms-node-thin

Start the Node subscriber:

node examples/multi-lang/node_subscriber.js

node: attached; listening on multi-lang/demo (Ctrl-C to stop)

and, in another terminal, the Python publisher:

python3 examples/multi-lang/python_publisher.py

py: attached
py: sent b'hello-from-python-0' as fe531358
py: sent b'hello-from-python-1' as a2bcbef7

node: got 'hello-from-python-0' (envelope fe531358)
node: got 'hello-from-python-1' (envelope a2bcbef7)

Run pms push multi-lang/demo hello-from-python-0 and it prints the same identifier, fe531358…: three languages, one name for one content.

6. Look at the ring underneath

pms ring inspect default_hub --count 2

ring          /pms-default_hub
capacity      64 slots
write_count   …
cursor        …
recent        2 pulse(s):
  slot=    …  inst=DATA        mono_ns=     …  has_envelope=true
  slot=    …  inst=DATA        mono_ns=     …  has_envelope=true

The ring is a shared-memory object named after the hub. Every envelope published through the daemon writes one 128-byte Pulse into it, and the cursor counts them. has_envelope is true on every slot: the Pulse carries the envelope’s identifier, and a second process attached to the hub fetches the envelope from the store beside the ring by that identifier. That is how envelopes cross processes.

7. Stop the daemon

Ctrl-C in the first terminal. The daemon removes its socket and unlinks its shared memory as it exits.

Check it worked

If pms push reports it cannot reach a daemon, none is running or PMS_DAEMON points elsewhere; the daemon’s log names its endpoints. If the Node subscriber or Python publisher fails to connect, PMS_DAEMON must be a ws:// address or unset: the thin clients speak WebSocket only.

What happened

• Identity is content. The daemon names every envelope by the BLAKE3 hash of its canonical bytes: channel, type name and payload. Two envelopes with identical content share one name, in every language, so a receiver can check what it got without trusting who sent it.
• A subscription is a live stream. It delivers from the moment the daemon acknowledges the subscribe request, and the daemon keeps nothing for a subscriber that is not connected; the messages sent in a gap are gone for that subscriber. A subscriber that stays connected but stops reading is a different case: the daemon queues up to a fixed number of events for it (--subscriber-queue, 1,024 by default), drops newer ones beyond that, and reports how many when the subscription ends.
• Every subscriber gets every matching message. The daemon broadcasts to the subscriptions whose filter matches; it does not pick one.
• The ring is the signal, the store is the content. One 128-byte Pulse per envelope goes into the shared-memory ring; the envelope itself sits in the store beside it, fetched by identifier.

What the daemon does not do: it has no authentication and no encryption, so it listens on loopback by default and should stay there unless a deployment wraps it; it keeps no history for late subscribers (the basket, in Capture envelopes and query them, is the record); and mesh_health in the MCP server reports which names are attached, not whether they are alive.

Make it yours

• See a whole event: stop the tap and start it with --json; each event is one JSON object with the channel, the identifier, the origin, the capture time and the payload size.
• Speak the protocol yourself: in a browser’s console, open new WebSocket('ws://127.0.0.1:9876', ['pms-universal-port-v0']) and send three JSON frames, attach, subscribe and send, with a base64 payload; four come back, three acks and the event for your own envelope. The port protocol is the whole contract.
• Type your messages: --type-name on pms push, or the type_name argument in any client, becomes part of the identifier and a filter a subscriber can use.

Next

• An agent swarm: a planner and two workers on this daemon, every result checked against its job.
• Capture envelopes and query them: keep a record of what went through, and ask it questions.
• Run the daemon as a service: flags, launchd and systemd, what a restart costs.
• Daemon design: why it is shaped this way.

Spoken walkthrough

A script for the video and audio version of this page, about two minutes.

One daemon, and four ways to talk to it.

First the command line. We start the daemon, open a tap on the jobs channels, and push a message. The tap shows it arrive, and both sides print the same eight characters: the start of the message’s identifier. Push the same message again and the identifier is the same. Push it on another channel and it changes. That identifier is a hash of the content, so identity is the content, not who sent it or when.

Next, two Rust programs, each about a screen long. The receiver attaches and subscribes. The sender attaches and publishes ten jobs. Every job the sender names, the receiver names the same way.

Now Python and Node. Two thin clients, no codec in either; the daemon does the naming. A Python publisher, a Node subscriber, and the identifiers still match.

Finally we look underneath. Every message put one 128-byte Pulse into a shared-memory ring, and the ring’s cursor counts them. The Pulse carries the identifier; the content sits in a store beside the ring.

One thing to try: stop the receiver while the sender is running, then start it again. It picks up from the next job and never sees the ones sent while it was away. A subscription is a live stream. The record of what went by is the basket, which the next example uses.

An agent swarm: a planner hands out jobs, workers answer

Example · for anyone putting more than one agent or program on a mesh, in about ten minutes

You will have: a planner (your coding agent) and two worker programs attached to one daemon on your machine. The planner publishes jobs. Every worker receives every job and publishes a result. The planner reads the results and matches each one to the job it answers by the job’s envelope identifier, which is a hash of the job’s content.

You need: the daemon repository set up as Start here describes, with pms and mesh-hub installed; Python 3.9 or later with pip; and, for the agent path, a coding agent that can use MCP tools. Claude Code is shown. The by-hand path needs no agent.

Hand this to your agent

Run the agent-swarm example from book/src/examples/agent-swarm.md in the pulse-mesh-daemon repository:
1. Start a daemon with a basket: pms start --basket-path ~/.local/share/pms/basket.db
2. Install the Python thin client and the query tool: pip install -e clients/pms-py-thin -e tools/pms-query
3. Save the worker program from the page as worker.py. Start two workers in the background: python3 worker.py worker-1 and python3 worker.py worker-2. Wait for each to print "attached, waiting for jobs".
4. If pms-mcp is not among your MCP tools: cargo install --path tools/pms-mcp --locked, then register the command pms-mcp as an MCP server and reconnect.
5. With the mesh_send tool, as_name "planner", publish three jobs on channel jobs/new, each a short sentence, with type_name job.new. Keep the envelope_id each call returns.
6. With the mesh_query tool, list rows on channel results. Expect six rows, two per job, with origins worker-1@… and worker-2@….
7. For one result row, run pms-query get <id> in the shell, decode payload_b64, and show me the text. Its eight-character job prefix must match one of the envelope_ids from step 5.
Stop and tell me if anything fails, and say which step.

Steps 5 to 7 are the planner’s work. If your agent has no MCP, it can do the same with pms push and pms-query, as the by-hand path below does.

Or do it by hand

1. Start a daemon that keeps a record

In a first terminal:

pms start --foreground --basket-path ~/.local/share/pms/basket.db

The daemon prints where it listens (timestamps omitted):

INFO uds listening path=/tmp/pms.sock
INFO websocket listening addr=127.0.0.1:9876

--basket-path makes the daemon capture every published envelope into a SQLite file, the basket. The planner reads results from it in step 5. Leave this terminal alone.

2. Write the worker

Install the Python thin client and the query tool, from the repository root:

pip install -e clients/pms-py-thin -e tools/pms-query

Save this as worker.py:

# worker.py: attach under the name given, answer every job on jobs/new.
import sys
import pms

name = sys.argv[1] if len(sys.argv) > 1 else "worker"
mesh = pms.attach(name)


def answer(event):
    text = event.payload.decode("utf-8", errors="replace")
    result = f"{name}: {len(text.split())} words in job {event.envelope_id[:8]}"
    mesh.send("results", result.encode("utf-8"), type_name="job.done")
    print(result, flush=True)


mesh.on("jobs/new", answer)
print(f"{name}: attached, waiting for jobs", flush=True)
mesh.run()

The worker attaches to the daemon at ws://127.0.0.1:9876 (or wherever PMS_DAEMON points), subscribes to jobs/new, and for each job publishes one result on results that names the job by the first eight characters of its envelope identifier.

3. Start two workers

In a second terminal:

python3 worker.py worker-1

worker-1: attached, waiting for jobs

In a third terminal, the same with worker-2.

4. Publish a job

In a fourth terminal:

pms push jobs/new 'count the words in this job' --type-name job.new

The publisher prints the identifier the daemon gave the job:

envelope_id=cb05c6b8f4b696551a0b7245b6f104a2

Both workers print a line, each with the same eight-character prefix:

worker-1: 6 words in job cb05c6b8

worker-2: 6 words in job cb05c6b8

Publish two more jobs with different sentences.

5. Read the results

pms-query rows --channel results --since 5min

{
  "rows": [
    {
      "id": "…",
      "captured_at_unix_nanos": …,
      "channel": "results",
      "envelope_type": 0,
      "type_name": "job.done",
      "origin": "worker-2@…",
      "payload_hash": "…"
    },
    …
  ],
  "next_before": null
}

Six rows: two per job. Rows carry the result’s identifier, origin and hash, not its text; fetch one result’s text by its id:

pms-query get <id> | python3 -c 'import json,sys,base64; print(base64.b64decode(json.load(sys.stdin)["payload_b64"]).decode())'

worker-2: 6 words in job cb05c6b8

Check it worked

If rows is empty, the daemon was started without --basket-path, or pms-query is reading a different file: it uses PMS_BASKET_DB, else ~/.local/share/pms/basket.db. If a worker prints nothing when you publish, it is attached to a different daemon: both read PMS_DAEMON, and the daemon’s log names its WebSocket address.

What happened

• Broadcast is the default. The daemon delivers each envelope to every subscriber attached at that moment. That is why two workers give two answers. To split work instead of duplicating it, give each worker its own channel (jobs/worker-1), or let workers claim jobs by publishing a claim before the answer. The daemon does not assign a job to exactly one worker.
• Identifiers are hashes. The envelope identifier pms push printed is the BLAKE3 hash of the job’s canonical bytes. The same job content gives the same identifier everywhere, so a result that names it can be checked against the job without trusting the worker.
• The planner reads the record, not the stream. The MCP server publishes and queries; it has no tool that waits for events. Live listening is for programs, through the thin clients or the Rust client. The basket is the planner’s view of what happened, and mesh_query rows carry identifiers, origins and hashes; payload text comes from pms-query get.
• Nothing is kept for a worker that was not attached. A job published before a worker starts is not delivered to it later. The basket still records it.

What the daemon does not do yet: it has no authentication and no encryption, so keep it on loopback, which is its default; mesh_health reports which names are attached, not whether they are alive.

Make it yours

• More workers: start worker-3; every job now gets three answers.
• Specialists: change the worker to subscribe to jobs/<name> and publish to jobs/worker-1 from the planner. Each worker then sees only its own jobs.
• Another language: the Node thin client has the same attach, on, send and run; the Rust client in mesh/mesh-client has the same shape. Two programs talk through the daemon shows a Node subscriber and a Python publisher side by side.
• Replay a day’s jobs: mesh_replay republishes a captured channel, so a new worker can be tested against yesterday’s jobs. It reaches live subscribers too, so run it against a daemon of its own.

Next

• Two programs talk through the daemon: the same exchange from the command line, from Rust, and from Python and Node.
• Capture envelopes and query them: the basket’s filters, aggregations and retention.
• The MCP tools: every tool’s input and output.
• Trust boundaries: what the daemon protects, and what it leaves to the deployment around it.

Spoken walkthrough

A script for the video and audio version of this page, about ninety seconds.

Here’s a planner and two workers on one machine, talking through one daemon.

First, the daemon. We start it with a basket, which means it keeps a record of every message in a small database file. That record is how the planner will read results.

Next, the workers. Each one is fifteen lines of Python. It attaches to the daemon by name, subscribes to the jobs channel, and for every job it receives, it counts the words and publishes a result. The result names the job by the first eight characters of the job’s identifier.

Now the planner publishes a job. Watch both workers: each prints an answer, and each answer carries the same eight characters. That identifier is a hash of the job’s content, so the planner can check that a result belongs to a job without trusting the worker that sent it.

Finally the planner reads the results from the basket: two per job, one from each worker.

One thing to notice. Both workers answered, because the daemon broadcasts: every subscriber gets every message. If you want each job done once, give each worker its own channel. That’s the whole example. The code on the page is everything you saw.

One domain’s job, end to end

Part opener · for anyone putting Pulse Mesh to work in robotics, enterprise messaging, high-frequency trading or distributed compute

A workflow has an example’s shape and one domain’s job: what you will have, one prompt for your agent, the same steps by hand with what each prints, checks, and what the code does and does not do yet. Where a workflow uses a ring from the profiles repository, it says which of the ring’s parts are implemented and which are deferred.

• The ring inside your process: the shared-memory ring and the envelope store without the daemon, which is what the HFT ring builds on.
• HFT: one feed, many readers, no copy per reader: one writer, four readers and a ring in process memory, with the wait strategy chosen for the host and the path to several writers and NUMA placement.
• Robotics: a 4 MiB scan through shared memory: a scan in a shared-memory pool, a 16-byte reference in the Pulse, read and checked in another process, and the pool’s limits seen.
• Enterprise: Pulses between services over TLS 1.3: one frame across a verified TLS 1.3 handshake, and the stage’s own statement of which modes are deferred.
• Distributed compute: jobs across machines through linked daemons: two daemons linked over sealed UDP, a job crossing from one to a subscriber of the other, and the path to the swarm across hosts, LAN discovery and a relay.

Distributed compute: jobs across machines through linked daemons

Workflow · for anyone spreading one job over several machines, or putting an agent swarm across hosts; about twenty minutes, with the daemon repository

You will have: two daemons linked to each other, on one machine here and on two by changing two addresses; a job published to one daemon arriving at a subscriber of the other, carrying its origin qualified by the daemon it came from; the link’s counters showing the forward; and the path from here to the planner and workers of An agent swarm spread over hosts, to discovery on a LAN, and to a relay.

You need: the daemon repository set up as Start here describes, with pms and mesh-hub installed. For two machines, UDP between them on the link ports you choose.

Hand this to your agent

Run the workflow "Distributed compute" from book/src/workflows/distributed-compute.md in the pulse-mesh-daemon repository, on this machine:
1. A daemon prints its node key's public half only when its links are configured, so bootstrap each key with a placeholder peer. Start daemon A in the background: mesh-hub --hub-name lnkA --no-uds --ws-bind 127.0.0.1:9876 --node-key ./a.key --link-bind 127.0.0.1:7400 --link-peer 127.0.0.1:7401=<64 zeros>; wait for its "links to other daemons configured" log line, record the public_key it prints, and stop it. Do the same for daemon B with --hub-name lnkB, --ws-bind 127.0.0.1:9877, --node-key ./b.key, --link-bind 127.0.0.1:7401 and a placeholder peer at 127.0.0.1:7400.
2. Start both again, each naming the other's public key in --link-peer, and wait for a "link up" log line from each.
3. Against B (PMS_DAEMON=ws://127.0.0.1:9877), run pms tap --channel 'jobs/*' in the background, wait for "tapped", then a second more, so B's interest summary has reached A.
4. Against A (PMS_DAEMON=ws://127.0.0.1:9876), run pms push jobs/new 'hello from daemon A'. Show me the envelope_id and the line the tap on B printed; its origin must end in @ followed by daemon A's 16-digit id, the daemon_id from A's log.
5. Stop everything and show me each daemon's "links at exit" line: A forwards_sent=1, B forwards_received=1.
Explain in plain words how the job crossed from A to B and what the qualified origin means. Stop and tell me if anything fails, and say which step.

Or do it by hand

1. Give each daemon a node key

Links are authenticated by each daemon’s X25519 node key, which the daemon generates into the file --node-key names on its first start, and whose public half it logs. It logs it only when its links are configured, so the first start names a placeholder peer. In a first terminal:

mesh-hub --hub-name lnkA --no-uds --ws-bind 127.0.0.1:9876 --node-key ./a.key \
  --link-bind 127.0.0.1:7400 \
  --link-peer 127.0.0.1:7401=0000000000000000000000000000000000000000000000000000000000000000

INFO links to other daemons configured daemon_id=8f0882adae3fafa5 public_key=36ae5e96…f47a link_bind=127.0.0.1:7400 peers=… announce=None relay=false trusted_relays=…
INFO websocket bound bound=127.0.0.1:9876 scheme="ws"

Keep A’s public_key (64 hex digits) and daemon_id, then stop it with Ctrl-C. In a second terminal do the same for B, with --hub-name lnkB, --ws-bind 127.0.0.1:9877, --node-key ./b.key, --link-bind 127.0.0.1:7401 and the placeholder peer at 127.0.0.1:7400; keep B’s public key and stop it.

2. Link them

Start A again with B’s key, and B with A’s:

mesh-hub --hub-name lnkA --no-uds --ws-bind 127.0.0.1:9876 --node-key ./a.key \
  --link-bind 127.0.0.1:7400 --link-peer 127.0.0.1:7401=<B's public key>

mesh-hub --hub-name lnkB --no-uds --ws-bind 127.0.0.1:9877 --node-key ./b.key \
  --link-bind 127.0.0.1:7401 --link-peer 127.0.0.1:7400=<A's public key>

Each logs, within a second or two:

INFO link up peer=83cec7bc66fe3ca8 addr=Some(127.0.0.1:7401) version=3 capabilities=0 registry_match=true relays=false trusted_as_relay=false

peer is the other daemon’s id, the fingerprint of its public key. Each daemon’s --link-bind is one UDP endpoint, whatever the number of its peers; the link between two daemons is one sealed session between their endpoints.

3. A worker on B, a job from A

In a third terminal, a subscriber on B:

PMS_DAEMON=ws://127.0.0.1:9877 pms tap --channel 'jobs/*'

tapped; Ctrl-C to stop

Give it a second: B’s summary of what its subscribers want reaches A a fraction of a second after the subscription. Then, in a fourth terminal, a job published to A:

PMS_DAEMON=ws://127.0.0.1:9876 pms push jobs/new 'hello from daemon A'

envelope_id=c4ca9156f3946f9cb120990d488325d4

and the tap on B prints:

            jobs/new |       19B | c4ca9156 | pms-cli-send@8f0882adae3fafa5

The origin is qualified: the publisher’s name, @, and the 16-digit id of the daemon it attached to. A had forwarded the send to B because B had told A, in its interest summary, that a subscriber of its wanted jobs/*.

4. Stop, and read the counters

Ctrl-C the tap and both daemons. Each daemon’s last lines include:

INFO links at exit links_up=1 forwards_sent=1 forwards_received=0 duplicates_dropped=0 forwards_dropped=0

on A, and forwards_sent=0 forwards_received=1 on B.

Across two machines: give each daemon its machine’s address in --link-bind and the other machine’s in --link-peer, open the two link ports for UDP between them, and keep --ws-bind on loopback on each machine; clients attach to the daemon on their own machine. Nothing else changes.

Check it worked

If a daemon exits with status 2 saying links need --node-key, --link-bind and a peer, one of the three is missing: all three are required, which is why step 1 names a placeholder. If link up never appears, the keys are swapped or a port is blocked; a daemon admits a peer’s key only from the IP of the address its --link-peer names. If the tap prints nothing, the subscription was made after the push, or the push came before B’s interest summary reached A, a fraction of a second after the subscription; forwarding follows subscriptions, so subscribe first and give it a moment.

What happened

• Daemons link over sealed UDP. Each --link-bind is one endpoint; a link between two daemons is a Noise IK session with ChaCha20-Poly1305, keyed by their X25519 node keys, and only the configured peers’ keys are admitted, each from its address’s IP. A link begins with a Hello carrying the capability Hello of mesh-capability, inside the session.
• Forwarding follows interest. Each daemon tells its peers a summary of what its subscribers want, paced so it is sent at most a few times a second. A client’s send is forwarded once to each linked peer whose summary matches, and delivered there to the subscribers whose filters match. A daemon also announces its attached clients to its peers by qualified id, so a send with a destination can be routed to the daemon that holds it.
• The origin travels. Across a link a client is name@ and its daemon’s 16-digit id, so a worker on B knows which daemon a job came from, and a result published on B reaches a subscriber on A the same way, by B’s forward.
• One hop, or two through a relay. A send leaves its daemon with a hop limit of two. Daemons not linked to each other reach one another through a daemon started with --link-relay, which forwards once more and announces the clients reached through it; a daemon accepts relayed traffic only from a peer it names with --link-trust-relay, because a relayed origin is only as trustworthy as the relay. There is no third hop.
• Finding peers on a LAN. With --link-announce GROUP:PORT a daemon multicasts its link endpoint every five seconds and hears the others’, so --link-peer-key names a peer by key alone and its address is learned; the announcement is a hint, acted on only for a key already configured, and the handshake then authenticates it.

What this does not do yet: the link’s sealing has not had the independent cryptographic review that ADR-0018 requires before sealed mode is recommended for production, so run linked daemons between machines you control; nothing signs an envelope or its origin end to end, which is why relays must be trusted by name; and forwarding is to subscribers, not to a chosen worker, so splitting a job across machines is done the way the agent swarm does it on one, by channel or by claim.

Make it yours

• The swarm across hosts. Run the planner of An agent swarm against the daemon on one machine, start the workers against daemons on others, and start every daemon with a basket. Jobs on jobs/new reach every worker’s daemon; results on results come back the same way, each origin naming the worker’s daemon; pms-query on the planner’s basket sees them all.
• Per-machine channels. Workers on machine B tap jobs/b/*; the planner pushes to jobs/b/new; forwarding carries the job only to daemons whose subscribers want that channel.
• A relay for a third machine. Start a daemon with --link-relay linked to A and C, and name it in both with --link-trust-relay; A’s jobs reach C’s workers through it, one hop further.
• Without a daemon. For one sender and many receivers on a LAN, pulse_wire_udp’s Receiver::bind_multicast and Sender::set_multicast carry Pulses to a multicast group with no daemon between; Across a network is the two-ended version.

Next

• An agent swarm: the planner and workers this spreads across hosts.
• Run the daemon as a service: the link flags beside the rest, and what a restart costs.
• Trust boundaries: what a link protects and what it does not.
• The mesh-hub daemon: every link flag with its default.

Spoken walkthrough

A script for the video and audio version of this page, about two minutes.

Two daemons, two machines, one job.

Each daemon gets a key. It makes the key itself, the first time it starts, and prints the public half in its log. We give each daemon the other’s public key and the other’s address, and they link: one encrypted UDP session between them, and a line in each log saying the link is up and naming the other side.

Now a worker subscribes to the jobs channels on daemon B, and a planner pushes a job to daemon A. Watch the worker’s terminal: the job arrives. Look at where it came from: the publisher’s name, an at sign, and daemon A’s id. The job crossed the link because B had told A that someone on its side wanted jobs.

When we stop the daemons, each prints its counters: A forwarded one, B received one, nothing duplicated.

To do this between real machines, change two addresses. To add a third machine that is not linked to the first, add a relay, and tell the others to trust it by name, because a relay’s word is the only word you have about where a forwarded job came from.

And one plain statement: the link’s encryption has not yet had the independent review the Foundation requires before it recommends it for production. Between machines you control, this is how a job crosses the room.

Get one task done

Part 02 · How-to guides

Get one task done

Steps in order, with the result you should see after each one.

Part opener · for people who already run Pulse Mesh

A guide does not teach. It names the task, states what you need, and gives the steps in order, with the result you should see after each one. Background belongs in the Concepts part and exact facts in the Reference part; a guide links to both instead of repeating them.

• Install pms outside the workspace: the three binaries on your path.
• Run the daemon as a service: flags, launchd, systemd, and what a restart costs.
• Capture envelopes and query them: the basket and the three ways to ask it.
• Use the MCP server from an agent: register pms-mcp and try it by hand.
• Inspect and clean shared memory: read a ring, remove what a crash left.
• Troubleshoot: the errors a user meets and their remedies.
• Add a stage to a ring: where a stage goes and what declares it.

Tuning the UDP transport, writing a language binding and running the smoke bench are in the standard’s book.

Install pms outside the workspace

How-to guide · for anyone who wants `pms` and the daemon on their path rather than behind `cargo run`

You need the Rust toolchain pinned in rust-toolchain.toml (rustup picks it up) and a clone of the repository. Linux or macOS; the rings use POSIX shared memory.

1. Install the three binaries

just install

Without just, the recipe is three commands:

cargo install --path tools/pms --locked
cargo install --path mesh/mesh-hub --locked
cargo install --path tools/pms-mcp --locked

pms, mesh-hub and pms-mcp land in ~/.cargo/bin, which rustup puts on your path. pms start looks for mesh-hub beside its own executable first and on your path second, and falls back to cargo run only inside the workspace, so the installed pair works from any directory.

2. Check

pms version
pms doctor

version prints the workspace and codec versions the binary was built from; doctor checks the toolchain and the runtime preconditions and names anything missing.

3. Run

pms demo

The demo starts a daemon if none is running, exchanges five envelopes between a producer and a consumer, and stops the daemon it started. From here the examples take over.

Upgrading

Repeat step 1 after pulling a new release; cargo install replaces the binaries. The book’s version in the sidebar is the version the pages describe; pms version is the version you have.

Run the daemon as a service

How-to guide · for anyone keeping `mesh-hub` running for other processes on a machine

mesh-hub runs in the foreground and stops on SIGINT or SIGTERM; a process supervisor keeps it up. Install the binary first (Install pms outside the workspace).

1. Choose the flags

Logging goes to standard error and is controlled by MESH_HUB_LOG (for example info,mesh_hub=debug).

2. macOS: launchd

Save as ~/Library/LaunchAgents/org.sovfound.mesh-hub.plist, then launchctl load it:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>org.sovfound.mesh-hub</string>
  <key>ProgramArguments</key><array>
    <string>/Users/you/.cargo/bin/mesh-hub</string>
    <string>--hub-name</string><string>default_hub</string>
  </array>
  <key>EnvironmentVariables</key><dict><key>MESH_HUB_LOG</key><string>info</string></dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/Users/you/Library/Logs/mesh-hub.log</string>
</dict></plist>

3. Linux: systemd

Save as ~/.config/systemd/user/mesh-hub.service, then systemctl --user enable --now mesh-hub:

[Unit]
Description=Pulse Mesh daemon

[Service]
ExecStart=%h/.cargo/bin/mesh-hub --hub-name default_hub
Environment=MESH_HUB_LOG=info
Restart=on-failure

[Install]
WantedBy=default.target

4. Know what restarts cost

The shared-memory objects are unlinked when the daemon exits, so a restart begins with an empty ring and an empty store; the basket file, if any, persists. A daemon started while another is live on the same socket path refuses to start and says so; a socket file left by a daemon that was killed is reclaimed. Clients reconnect on their own terms: the Rust client’s wait() returns Disconnected, and a subscriber re-attaches and re-subscribes.

On Linux the ring and the store live in the tmpfs behind /dev/shm, and the daemon reserves their pages when it creates them: about 17 MB per hub, a 256-slot store of 64 KiB entries plus the ring. Docker’s default /dev/shm is 64 MB, room for three hubs; give a container more with docker run --shm-size=256m. Shared memory without room is refused when the daemon starts, with could not reserve … bytes of shared memory in the log, instead of a SIGBUS at the first page touched later; a store without room is logged and the daemon runs without persistence, so its send acknowledgements carry no persisted field.

5. Look at it

pms ring inspect default_hub
pms tap

The first reads the ring’s header and its most recent slots; the second attaches and prints every event until you stop it.

Capture envelopes and query them

How-to guide · for anyone who wants to ask a running mesh what went through it, without watching a live stream

The daemon can capture every published envelope into a SQLite file, the basket, and three tools query it: the pms-query command, the MCP mesh_query tool, and any SQLite client, because the schema is one table.

1. Start the daemon with a basket

mesh-hub --basket-path ~/.local/share/pms/basket.db

or pms start --basket-path <file>. A retention sweep runs every 60 seconds (--basket-retention-secs) and keeps the file to 100 MB or 24 hours of envelopes, whichever is smaller.

The daemon writes the basket on a thread of its own, so a send never waits for SQLite. Captures wait for that thread in a queue of 1,024 envelopes and 64 MiB of payload; when the disk falls that far behind, a capture is dropped, the envelope is still delivered, and the daemon logs the count at the first drop and at each doubling. Stopping the daemon writes every capture still queued.

2. Query from the command line

pms-query is a small Python package under tools/pms-query; install it with pip install -e tools/pms-query. It reads the file at PMS_BASKET_DB or ~/.local/share/pms/basket.db unless --db says otherwise.

pms-query rows --channel 'jobs/*' --since 5min --limit 20
pms-query rows --aggregate count-by-channel --since 1h
pms-query rows --aggregate time-bucket --bucket-secs 60 --since 1h
pms-query rows --origin 'worker@3f9a' --type-name event.fired
pms-query get cb05c6b8f4b696551a0b7245b6f104a2

rows takes filters that AND-combine, --channel, --type-id, --type-name, --origin, --since and --until (durations such as 5min, 1h, 1d), and --limit (50 by default). --aggregate is one of count, count-by-channel, distinct-channels, distinct-types and time-bucket (with --bucket-secs). Output is JSON: rows with the envelope id, capture time, channel, type, origin and payload hash, or the aggregate, plus next_before for paging. get fetches one envelope by identifier with its payload base64-encoded.

3. Query from an agent

The MCP server’s mesh_query tool takes the same filters and aggregations and answers with the same rows; mesh_replay republishes a captured range. See Use the MCP server from an agent.

4. Query with SQLite

One table, envelopes, with the columns id, captured_at_unix_nanos, channel, envelope_type, type_name, origin, payload_hash and payload_bytes. sqlite3 basket.db 'select channel, count(*) from envelopes group by channel' is a valid query. The mesh-basket crate owns the schema; the Python tool’s tests assert the column list.

What the basket is not

It is not the envelope store: the store is shared memory beside the ring, holds one copy per distinct envelope, and is unlinked when the daemon exits; the basket is a file, holds one row per publication, and persists. A Pulse’s envelope_ref resolves against the store, never the basket.

Inspect and clean shared memory

How-to guide · for anyone who wants to see what is in a ring, or to remove what a crashed daemon left behind

Read a ring

pms ring inspect default_hub
pms ring inspect default_hub --count 16 --json

A hub name resolves to the daemon’s ring, /pms-default_hub; a raw shared-memory name, one starting with /, is read as given. Either way the ring’s own header supplies its capacity and slot size, so nothing else is asked for:

pms ring inspect /pms-example-4242

The output is the ring’s name, its capacity, the total number of writes and the cursor, then the most recent slots with their instruction, their clock reading and whether they reference an envelope. inspect attaches as a second reader and moves nothing; a slot whose writer died mid-write reads as absent until the next publish into it.

The same from an agent

The MCP tools mesh_list_rings and mesh_ring_peek list the /pms-* objects (on Linux, where /dev/shm can be listed) and read a ring by hub name or raw name with the same two forms.

Clean up

A daemon unlinks its objects when it exits cleanly. After a crash or a kill, on Linux the objects stay under /dev/shm:

ls /dev/shm/pms-*
just clean            # cargo clean, then removes /dev/shm/pms-* owned by you

On macOS shared-memory objects have no directory; they persist until a process unlinks them or the host reboots. A daemon started under the same hub name unlinks what it finds before creating its own ring and store, and its log names each object it replaced, so the way to clear a leftover on macOS is to start and stop a daemon with that hub name.

A stale socket

/tmp/pms.sock left by a killed daemon is reclaimed by the next daemon on that path, which probes it first; a socket that answers is another live daemon and the new one refuses to start.

Add a stage to a ring

How-to guide · for a contributor adding stateful processing to a ring

Every ring has the same four crates, and a new stage goes into the ring’s stages crate, is declared in the ring’s hub, and shows up in the hub’s manifest. This guide adds a stage called dedupe to the dev ring; the enterprise, HFT and robotics rings, in the profiles repository, work the same way.

1. Decide it is a stage

A stage carries state or sits on the hot path: a router, a pool, a lane, an observer. A stateless transformation with no I/O is a function and belongs in <ring>-functions; a type several layers share and nothing else belongs in <ring>-core. CONTRIBUTING.md states the rule; when in doubt, ask whether the module owns anything between calls.

2. Add the module to the stages crate

mkdir dev_ring/dev-stages/src/dedupe

Create dev_ring/dev-stages/src/dedupe/mod.rs with the file header every source file carries, a crate-style overview (//!) that says what the stage is and what it owns, and the code. Declare it in dev_ring/dev-stages/src/lib.rs:

#![allow(unused)]
fn main() {
pub mod conflation;
pub mod dedupe;
}

Add the stage to the crate overview’s list in the same file, one line, in the same shape as the existing entries.

3. Declare it in the hub

The hub is the ring’s only import point. In dev_ring/dev-hub/src/lib.rs, add the stage to the register_stages! invocation:

#![allow(unused)]
fn main() {
mesh_stage_registry::register_stages! {
    functions: [
        dev_functions::basket,
        dev_functions::core_ops,
    ],
    stages: [
        dev_stages::conflation,
        dev_stages::dedupe,
    ],
}
}

The macro emits RING_MANIFEST and imports each listed path, so a path that names no module fails the hub’s build here rather than becoming a string in the manifest. The hub’s manifest test asserts the manifest: update dev_ring/dev-hub/tests/manifest.rs so it lists the new stage; the test is what keeps the manifest and the declaration together.

4. Check the gates

cargo clippy --workspace --all-targets -- -D warnings
cargo test -p dev-stages -p dev-hub
scripts/docs/check.sh

The first two are the code gates. The third fails if the crate overview names something that does not exist or if the ring’s page in the book no longer matches the crate table; regenerate the crate index with scripts/docs/gen-all.sh if the description in Cargo.toml changed.

5. Document it

Add one row to the ring’s table in book/src/architecture/rings/dev_ring.md and to dev_ring/README.md, in the same sentence shape as the existing rows: what the stage is and what it owns. If the stage introduces a term, the glossary gets an entry.

Troubleshoot

How-to guide · for anyone who got an error from `pms`, the daemon, the client or a ring and wants the fix

Start with pms doctor; most environment problems surface there. Every error type in the workspace is listed variant by variant in the error catalogue; the entries below are the ones a user meets from the command line, with their remedies.

When the fix is not here

The daemon design and trust boundaries pages say what the daemon will and will not do; the specification’s port protocol chapter has every error code. Refutations and gaps are defects in this page; report them.

What is exactly true

Part 03 · Reference

What is exactly true

The port protocol, the workspace crate by crate, and the tables generated from the code.

Part opener · for implementers and integrators looking something up

Reference pages state what is true and nothing else. They do not teach and they do not persuade. Where a table can be produced from the code, it is, and a check in continuous integration fails when the page and the code disagree.

The part has four layers. The specification is the standard’s; its chapter 7, the port protocol, is here because the daemon is what speaks it, and the golden fixtures under mesh/mesh-port-protocol/fixtures are its executable form. The workspace pages describe the tier and the ring, following the tree’s own structure. The API page describes the Rust client. The generated pages are produced from the code by the gate.

• The specification: the chapters, and chapter 7, the port protocol.
• Workspace: Layout, Fabric: mesh/, the dev ring, the leaves beside them. The standard’s tiers and the other rings have their pages in the standard’s book and the profiles’ book.
• Generated from the code: the pms command line, the mesh-hub daemon, the MCP tools, the modules and developer profiles, the crate index and the error catalogue; the gate regenerates them and fails on any difference.
• API: Overview and Rust; the codec bindings for Python, Node and C are in the standard’s book.
• Glossary.

The specification

Reference · normative · for anyone implementing, verifying or extending Pulse Mesh in any language

This is the Pulse Mesh Standard as the reference implementation in this repository realises it. Where a chapter describes the reference implementation rather than a requirement on every implementation, it says so at the top.

Status. Working draft, lineage draft-00. Breaking changes between draft revisions are expected and are recorded, not hidden: a superseded rule stays in the text, marked as superseded, with the revision that replaced it. The conformance vectors under pulse/pulse-spec/test-vectors are the executable form of chapters 2 and 3; the chapter text and the vectors are checked against the code by the documentation gate and the workspace tests.

How to read the requirement words. MUST, MUST NOT, SHOULD, SHOULD NOT and MAY carry their usual normative meaning. A statement without one of those words is a description of the reference implementation, not a requirement on others.

7. The Universal Port Protocol

Reference · normative for the daemon's clients · the JSON protocol between `mesh-hub` and anything that attaches to it, over a WebSocket or a Unix socket

The daemon terminates one protocol on two transports. A client attaches under a name, publishes envelopes to channels, subscribes to filtered streams, and detaches; the daemon answers each request, pushes events, and enforces a connection policy that keeps a silent, slow or oversized peer from costing the others anything. The types are defined once, in mesh-port-protocol, and the daemon and the Rust client both use them; the thin Python and Node clients and the website’s browser client speak the same JSON. Version v0.

7.1 Transports and framing

Both carry the same message stream. Every message is a JSON object whose op field names the kind. The frames of every kind, each optional field present in one frame and absent in another, are pinned under mesh/mesh-port-protocol/fixtures/ (client.json, server.json) as the Rust types serialize them; the crate’s tests keep the files current, and the Python and Node thin clients’ tests decode every server frame from them and compare the frames they write with the client frames as parsed JSON. A daemon MUST refuse to bind a Unix socket path where another daemon is live (it probes the socket first and removes only a stale file), so a second daemon never steals a live one’s clients.

7.2 Client messages

id is echoed on the matching ack or error; a request without one gets a reply without one. A FilterSpec has six optional members that AND-combine: channel (exact or glob, db/*, **/foo), type_id, type_name (exact or glob), origin (the producer’s name@suffix), health (also stream peer state changes), and snapshot (reserved; ignored by v0). Fields at their defaults are omitted on the wire.

7.3 Daemon messages

A client MUST ignore an op it does not know and an ack key it does not know, so a later revision can add either without breaking it; the existing clients do.

7.4 Error codes

An error that answers no request, one without an id or with one no request is waiting on, is the daemon’s reason for the close that follows it, and a client reports it to every call still waiting and to whatever waits for the connection’s end; a daemon that carries on after such an error, as after bad_request for a frame it could not parse, fails no call by it.

The set grows: a later daemon may send a code this table does not list. A client keeps such a code as the text it arrived in and treats the reply as a refusal it cannot classify; the Rust client’s DevError::Daemon { code, .. } holds the string, and mesh_port_protocol::ErrorCode::parse returns None for it.

7.5 The connection policy

The daemon enforces eight limits, four timers and four sizes, each a command-line flag with a default; zero disables a timer, and zero on either cap refuses everything:

Acknowledgements and errors are never dropped; only events are subject to the queue. When a connection ends for any reason the daemon releases its name and closes its subscriptions at once.

7.6 A session

→ {"op":"attach","id":"1","name":"worker","protocol_version":"v0","capabilities":["send","subscribe","tap"]}
← {"op":"ack","id":"1","node_id":"worker@3f9a…","protocol_version":"v0","granted_capabilities":["send","subscribe","tap"]}
→ {"op":"subscribe","id":"2","filter":{"channel":"jobs/*"}}
← {"op":"ack","id":"2","subscription_id":"sub-default_hub-00000001"}
→ {"op":"send","id":"3","channel":"jobs/new","payload":"aGVsbG8="}
← {"op":"ack","id":"3","envelope_id":"9c1d…","persisted":true}
← {"op":"event","subscription_id":"sub-default_hub-00000001","envelope_id":"9c1d…","channel":"jobs/new","type_id":0,"origin":"worker@3f9a…","captured_at_unix_nanos":1758700000000000000,"payload":"aGVsbG8="}
→ {"op":"unsubscribe","id":"4","subscription_id":"sub-default_hub-00000001"}
← {"op":"ack","id":"4"}
→ {"op":"detach","id":"5"}
← {"op":"ack","id":"5","__detach":true}

7.7 What would refute this chapter

The protocol crate’s round-trip tests pin every message shape; the daemon’s tests attach, publish, subscribe and detach over both transports, refuse a second daemon on a live socket, close a silent connection after the idle window and a stalled one after the write window, keep a pinged client attached, reject an oversized frame with payload_too_large, show events_dropped in the unsubscribe ack of a subscriber that stopped reading, acknowledge a send the store refused with persisted: false while still delivering it to its subscribers, refuse a send whose payload is not padded standard base64 without publishing it, refuse the subscription past the cap with limit_exceeded and admit one again after an unsubscribe, and turn away the connection past the cap on both transports. A client that receives bytes this chapter does not describe, or a daemon that keeps a silent connection past its window, contradicts it.

Workspace Layout

Reference · the fabric, the dev ring and the leaves beside them, for anyone finding their way around the tree

This repository holds tier 2 of the Pulse Mesh stack and one tier-3 ring. A tier depends only on the tiers below it: everything here depends on the standard, tiers 0 and 1, which is a sibling checkout (../pulse-mesh) while developing and a pinned tag at a release. Nothing in the standard depends on anything here.

Beside the tiers sit the leaves: they consume the tiers and are consumed by nothing.

The other rings

The enterprise, HFT and robotics rings are the profiles, a repository built on the standard beside this one. Every ring has the same four crates, and the dev ring here is one of them; Rings: domain surfaces describes the shape.

Deciding where new code goes

CONTRIBUTING.md frames this as a four-question test: does the code touch the canonical Pulse atom, touch the canonical envelope, cross a ring boundary, or sit on the hot path? Code that touches the atom or the envelope belongs in the standard, and is made there first. Code that is part of the daemon’s contract (the port protocol, routing, the client) belongs in mesh/. A stage that crosses a ring boundary belongs in a ring: the dev ring here, or a profile. Anything that only uses the tiers (a tool, a client, an example) is a leaf here. Record any non-obvious classification call as a new ADR under decisions/ rather than only justifying it in the PR.

Fabric: mesh/

Reference · the fabric tier, crate by crate

Routing and registration: the daemon, the port protocol it speaks, the embedded hub it wraps, the Rust client, and the broadcast, health, schema and basket crates around them. The vocabulary crates the fabric registers against (the Lexicon, the context and capability registries) are the standard’s, under its pulse/ tier. See also mesh/README.md in the tree.

mesh-hub is the only crate in this tier with a binary. Everything else here is a library, consumed either directly by the daemon (via mesh-hub-runtime) or by the dev ring’s dev-hub.

dev_ring

Reference · the dev ring, crate by crate

General-purpose developer ergonomics ring. Downstream code should depend on dev-hub, not the inner three crates directly.

If you’re writing an example or a peripheral tool that just needs to talk to a running mesh-hub daemon, mesh-client’s Mesh API (reachable as dev_hub::Mesh too) is almost certainly the right entry point — Two programs talk through the daemon is built on exactly this.

Peripheral surface

Reference · everything beside the tier and the ring, directory by directory

Everything that falls outside the fabric and the dev ring (per the four-question test in Workspace Layout) sits beside them at the top of the repository. The thin clients and the fuzz harness opt out of the root Cargo workspace: the clients have no Rust to build, and the harness builds on nightly with cargo-fuzz.

The standard’s leaves, the pulse command line, the codec bindings, its examples and its fuzz harness over the wire and the codec, are in its book; the profiles’ plugin and telemetry tool are in theirs.

The pms command line

Reference · generated · every subcommand and flag of `pms`, printed by the binary itself

pms

Sends, receives, encodes, and inspects pulses across the local mesh. Run pms demo first to see a producer + consumer talk through the mesh in one terminal.

pms doctor

Verify the local toolchain and mesh runtime preconditions

pms send

Send pulses to a UDP destination

pms recv

Bind a UDP address and print received pulses

pms version

Print workspace + codec version stamp

pms encode

Encode a JSON envelope spec and report the canonical wire bytes

pms decode

Decode canonical wire hex back into an envelope summary.

Exits with status 1 when the envelope does not verify: its content does not produce the identifier it carries.

pms ring

Snapshot a SHM-backed PulseRing (read-only secondary reader)

pms ring inspect

Snapshot ring header + the N most-recent slot summaries

pms modules

List the M01..M12 optimization modules, optionally by profile

pms modules ls

List modules, optionally filtered by developer profile

pms bench

Throughput and latency of pulses over UDP loopback on this host

pms bench smoke

Throughput and latency of pulses over UDP loopback on this host: the same run as pulse bench

pms start

Start the local mesh-hub daemon (UDS + WebSocket).

In the background (the default) it waits up to 60 s for the daemon to serve, and stops one that does not (SIGTERM, then SIGKILL 5 s later) before it reports the failure and exits 1.

pms attach

Attach to a running mesh-hub daemon under the given name and park

pms push

Publish a one-shot envelope to a channel

pms tap

Subscribe to a channel and print events live

pms hello

Spin up a 2-thread demo (send + recv on channel hello)

pms demo

One-command end-to-end smoke loop: auto-starts the daemon if needed, runs a 5-message producer/consumer demo, cleans up.

It exits 1, saying how many arrived, when fewer than all five messages reach the consumer within 5 s. With PMS_DAEMON set it uses the daemon that names and starts none.

pms keys

Make and read the Ed25519 keys a client proves at attach.

A key file is its owner’s alone (mode 0600), and a client refuses one its group or others may read or write. Each subcommand prints the key’s public half as a line of a daemon’s --attach-keys list: its standard base64, 44 characters.

pms keys generate

Write a new key to a new file, readable and writable by its owner alone, and print its public key.

Exits 1, replacing nothing, when the file exists or cannot be written.

pms keys public

Print the public key of a key file.

Exits 1 when the file cannot be read, holds no key, or its group or others may read or write it.

pms docs

Print the generated reference pages the book carries

pms docs cli-markdown

The pms command tree as Markdown, from the definitions that parse the real arguments

The mesh-hub daemon

Reference · generated · every flag of the daemon with its default, printed by the binary itself

mesh-hub

Pulse Mesh local daemon — Universal Port Protocol terminator over UDS + WebSocket

Exit status:

• 0: stopped by SIGINT or SIGTERM.
• 1: could not start, or could not install its signal handlers; the log says why (another daemon holds the socket, the port or the hub name, a store or a basket could not be made or opened, the WebSocket’s TLS certificate or key could not be read or was refused, the –attach-keys file could not be read or holds a line that is not a key, the –node-key file could not be read or made, the –link-bind address could not be bound, or the –link-announce group could not be joined).
• 2: the command line was refused.
• 3: displaced. The hub name’s lock file was removed while the daemon ran and another owner took the name, so the processes attached to the hub by name follow that owner and nothing sent to this daemon reaches them. The daemon notices within 1s, logs at error level what happened and who holds the name now, closes its connections, removes its socket if the path still names it, and exits. A restart under the same --hub-name is refused while that owner lives, so a supervisor should not restart the daemon on this status (systemd: RestartPreventExitStatus=3).

The MCP tools

Reference · generated · every tool `pms-mcp` registers, with its input schema, printed by the server itself

The server speaks JSON-RPC 2.0 over stdio. mesh_probe_pulse and mesh_reachability are registered only when PMS_MCP_ALLOW_PROBE=1 is set at launch.

mesh_list_rings

Enumerate POSIX SHM regions that look like Pulse Mesh rings. On Linux this scans /dev/shm/pms-*; on macOS POSIX shared-memory names are not enumerable via the filesystem, so this returns an empty list with a note field rather than failing.

mesh_ring_peek

Read-only snapshot of an existing SHM-backed PulseRing. Returns capacity, write_count, cursor, and the most-recent N slot summaries. Give a hub name (e.g. default_hub) for the daemon’s ring or a raw POSIX SHM name starting with /; the ring’s header records its capacity and slot size, so none is passed. The reader attaches as a secondary reader — it does not advance the primary cursor.

codec_roundtrip

Canonically encode a PulseEnvelope spec, round-trip decode it, and return the canonical hex + BLAKE3 content hash + size. Proves the canonical codec works for the supplied input. The same canonical_hex output is byte-identical across Rust, Python, and Node implementations of the codec, which is the byte equality the standard is built on.

mesh_envelope_describe

Decode a canonical PulseEnvelope hex string and return a structural summary: envelope_type, content_hash, monotonic_nanos, flags, payload variant + size. Pure function — does not touch live mesh state.

modules_list

List the M01..M12 optimization modules, optionally filtered to one developer profile (hft / ai / robotics / telemetry / dev). Each entry includes its M-id, crate name, one-line summary, and the profiles it is recommended for.

modules_describe

Describe one M01..M12 optimization module by its M-id: the crate or module that implements it, its one-line summary, and the developer profiles it is recommended for. The implementing crate’s rustdoc carries the full documentation.

mesh_attach

Register a process name in the mesh-hub registry. Returns the daemon’s assigned node_id. The connection is dropped at the end of the call; another call (or the dev-functions Rust crate) holds the name persistently if you need that.

mesh_send

Publish an envelope to a channel on the mesh-hub daemon. Returns the daemon’s envelope_id.

mesh_query

Structured query against the daemon’s basket SQLite store. Returns rows or aggregations; never a firehose. Supply filters (channel, type, origin, time window) + optional aggregation (count, count_by_channel, time_bucket, distinct_channels, distinct_types). Replaces unbounded mesh_tap streaming.

mesh_health

Report which names are attached to the daemon and basic liveness state. For v0 this returns a static snapshot (no heartbeat protocol yet); future revisions surface NodeState from mesh-health.

mesh_replay

Replay envelopes from the basket back through the daemon. Useful for re-running a captured workload. WARNING: also reaches subscribers — confirm with the user before using on production-relevant channels.

mesh_probe_pulse

Send a single pulse to a UDP target and return send-side duration. Bounded: exactly one frame per call. Does not echo / measure RTT — that requires a peer-side echo service not shipped by default. Use this for liveness checks and to surface kernel errors (destination unreachable, etc.). Gated on PMS_MCP_ALLOW_PROBE=1 at server launch.

mesh_reachability

Send a one-pulse Heartbeat probe to each target in turn and report whether the kernel accepted the send. UDP is connectionless so this is a send-success check, not an RTT measurement. Gated on PMS_MCP_ALLOW_PROBE=1.

Modules and developer profiles

Reference · generated · the twelve optimization modules, and the developer profiles that select them

A developer profile is a tag that pms modules ls --for and pms doctor --for take, and that the MCP modules_list tool takes as profile. It selects modules from the table below and enables nothing: pms modules ls --for lists them, and pms doctor --for adds a line naming them. An unknown profile makes pms modules ls exit 1 and pms doctor report a warning. A developer profile is not the profiles repository (pulse-mesh-profiles), which holds the enterprise, HFT and robotics rings.

The table is static, in dev_ring/dev-functions/src/core_ops/modules.rs, and this page is generated from what pms modules ls --json prints.

Developer profiles

Modules

A module is a crate of its own or a module inside one layer of a ring (crate::module). The ring column names the ring whose layer holds it, and is blank for a crate of its own.

Crate index

Reference · generated · every workspace crate by tier, with the description its manifest carries

A tier depends only on the tiers below it; the peripheral surface depends on all of them and is depended on by none. The description column is each crate’s Cargo.toml description, so this table is exactly what cargo metadata reports. The status column is the crate’s package.metadata.pulse-mesh.status: pre-integration for a crate the tree ships but does not use yet (ADR-0014), partial for one in use some of whose public entry points return a deferred error (ADR-0017), blank for one that is finished and wired in.

The fabric (tier 2, mesh/)

The dev ring (tier 3, dev_ring/, dev_ring/)

The peripheral surface (tier peripheral, tools/, examples/)

Error catalogue

Reference · generated · every public error type in the workspace, variant by variant, with the meaning its documentation states

The table is read from the source, so a variant that exists is listed and a variant that is gone disappears. The troubleshooting guide gives remedies for the errors a user meets from the command line.

ConflationError in dev_ring/dev-stages

Defined in dev_ring/dev-stages/src/conflation/mod.rs.

BasketError in mesh/mesh-basket

Defined in mesh/mesh-basket/src/lib.rs.

DevError in mesh/mesh-client

Defined in mesh/mesh-client/src/error.rs.

AttachKeysError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/attach_keys.rs.

DaemonError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/daemon.rs.

EmbedError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/embed.rs.

BridgeError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/hub_bridge.rs.

AnnounceError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/link/announce.rs.

LinkPeerError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/link/mod.rs.

LinkSetupError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/link/mod.rs.

DatagramError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/link/wire.rs.

WsTlsError in mesh/mesh-hub

Defined in mesh/mesh-hub/src/tls.rs.

HubError in mesh/mesh-hub-runtime

Defined in mesh/mesh-hub-runtime/src/lib.rs.

OwnerError in mesh/mesh-hub-runtime

Defined in mesh/mesh-hub-runtime/src/lib.rs.

LockError in mesh/mesh-hub-runtime

Defined in mesh/mesh-hub-runtime/src/owner.rs.

CodecError in mesh/mesh-link

Defined in mesh/mesh-link/src/codec.rs.

LinkError in mesh/mesh-link

Defined in mesh/mesh-link/src/link.rs.

OriginError in mesh/mesh-link

Defined in mesh/mesh-link/src/origin.rs.

RouteError in mesh/mesh-link

Defined in mesh/mesh-link/src/router.rs.

ProofError in mesh/mesh-port-protocol

Defined in mesh/mesh-port-protocol/src/attach.rs.

TextError in mesh/mesh-port-protocol

Defined in mesh/mesh-port-protocol/src/attach.rs.

Base64Error in mesh/mesh-port-protocol

Defined in mesh/mesh-port-protocol/src/base64.rs.

FrameError in mesh/mesh-port-protocol

Defined in mesh/mesh-port-protocol/src/framing.rs.

ErrorCode in mesh/mesh-port-protocol

Defined in mesh/mesh-port-protocol/src/lib.rs.

SchemaError in mesh/mesh-schema

Defined in mesh/mesh-schema/src/lib.rs.

TelemetryExportError in tools/pms-telemetry-export

Defined in tools/pms-telemetry-export/src/lib.rs.

API Reference

Reference · where each API surface is documented and how to generate it

This book is a guided path; the crate-level API reference is generated straight from source, not duplicated into book chapters where it would drift. The one hand-kept exception is the daemon client’s surface on the Rust page, small enough to keep true by reading.

• Rust: the workspace’s own crates via rustdoc, and the client’s surface (Mesh: attach, send, on, tap, run) by hand.
• The codec bindings for Python, Node and C, and the WebAssembly codec, are the standard’s and are documented in its book; the thin clients that speak to this daemon from Python and Node are run in Two programs talk through the daemon.

Every page below generates its reference locally from the code actually in this repository.

Why generate instead of write

Rustdoc already carries the authoritative signatures, types, and per-item documentation the workspace’s missing_docs lint enforces (see Developer Onboarding). A hand-written API reference in this book would either duplicate that content and drift out of sync, or omit detail the generated reference already has for free. Generating it is also how the gate keeps the pages honest: a generated page that differs from its generator fails the docs check.

Rust

Reference · the `Mesh` client's surface, and where the rest of the Rust API lives

The Mesh client

Mesh, in the mesh-client crate (and re-exported by dev-hub, its home before ADR-0012, so dev_hub::Mesh keeps working), is the Rust client for the daemon: a synchronous handle over the Universal Port Protocol. Every method blocks the calling thread and returns a Result whose error is DevError. None may be called from inside an async runtime, where it would deadlock; such a call returns DevError::ReentrantCall instead.

A MeshEvent carries subscription_id, envelope_id, channel, type_id, type_name, origin (the publisher’s node, as short@hex), captured_at_unix_nanos and payload.

DevError has one variant per failure: NoDaemon, VersionMismatch, Transport, Protocol, Daemon { code, message } (the daemon refused a request, or said why it was closing, and code is one of the protocol’s error codes as text; mesh_port_protocol::ErrorCode::parse gives the typed code, or None for one this build does not know), NotAttached, DisconnectedDuringRpc (the call got no answer because the connection had already ended when it was made, or its task stopped without answering), Timeout { op, after }, ReentrantCall and Disconnected (the connection ended other than by an acknowledged detach and without a reason from the daemon). The enum is non_exhaustive, as every error enum and configuration struct of the mesh tier is: a match on it carries a wildcard arm, since a later release can add a variant, and a configuration is built from its Default with with_* methods rather than a struct literal. The error catalogue lists them with their messages.

The rest of the API

Generate the reference for every workspace crate — pulse-canon, core-ring, mesh-hub-runtime, each ring’s *-hub crate, and so on — straight from source:

cargo doc --workspace --no-deps --open

This includes the module-level //! overview and every public item’s /// doc comment that CONTRIBUTING.md’s missing_docs lint enforces workspace-wide (see Developer Onboarding).

The three native language bindings (Python, Node, C) are Rust crates too, but sit outside the root workspace, in the standard’s repository (see Language bindings), so document them from their own directories:

cargo doc -p pulse-wire-udp --no-deps   # the transport the bindings wrap

Glossary

Reference · for every reader; the book, the website, the command line and the error messages use these words in these senses

Terms are listed alphabetically. Where a word has more than one meaning in this tree, each meaning has its own entry and the book always says which one it means. The Sovereignty stack’s names are included because Pulse Mesh sits beside them; where a component is not part of this repository the entry says so.

ACK — A 12-byte feedback datagram (magic plus a u64 cursor) the UDP receiver sends to the sender to report its cursor, one past the highest sequence it has seen. The sender’s backpressure stall is released by it. Defined in pulse-wire-udp.

Aegis™ — The bounded, typed execution layer of the Sovereignty stack (Aegis / Construct). Not part of this repository.

Attach — The first operation on a port-protocol connection: the client names itself, announces the protocol version and the capabilities it wants, and receives its node id.

Backpressure — The feedback loop that stops a UDP sender from running more than target_queue_depth frames ahead of the receiver’s ACK cursor, for at most stall_timeout before the send fails. Amber in every figure.

Basket — The SQLite capture store of envelopes that the daemon writes for structured queries (mesh-basket; pms and the MCP server query it). Distinct from the envelope store, which is shared memory.

BLAKE3-16 — The first 16 bytes of a BLAKE3 hash computed under a domain tag. The envelope id is one.

Busy claim — A store writer’s claim that found its slot held by another writer, mid-store or crashed, or already taken by a newer lap, and gave up its cursor for a fresh one. Counted in the store’s header and reported by busy_claims(); readers skip the cursors given up.

Canon™ — The canonical codec, pulse-canon: the crate that turns a Pulse and a PulseEnvelope into bytes and back, exactly the same way in every implementation. Also the Sovereignty stack’s name for that semantic layer.

Capability handshake — The 48-byte Hello exchange in mesh-capability by which two nodes on plain UDP agree on a transport upgrade (NACK retransmission, FEC, and the higher-tier backends) from the intersection of their capability bits.

Channel — The routing key an envelope is published on through the daemon (pms push --channel, Mesh::send). Subscriptions filter on it, by exact name or glob.

Content id — See envelope id.

CRC trailer — A CRC32C over bytes 8 to 124 of a Pulse, stored in bytes 124 to 128 of its slot by publish_with_crc and checked by read_slot_verify_crc. pms-crc32c owns the computation.

Cursor — The ring’s monotonic write counter. The slot a write lands in is the cursor modulo the capacity.

Daemon — mesh-hub: the local process that terminates the port protocol over a Unix socket and a WebSocket and bridges every connection to the runtime hub. One of the three meanings of hub.

Detach — The port-protocol operation that releases a client’s name and closes its subscriptions cleanly.

Developer profile — A tag, one of hft, ai, robotics, telemetry and dev, that pms modules ls --for and pms doctor --for take to select optimization modules. It installs and enables nothing. Not the profiles repository. Each profile’s modules are listed in Modules and developer profiles.

Domain tag — A fixed string mixed into a hash so that identifiers from different contexts can never collide. The envelope id uses pulse-envelope-id/v2.

Envelope — See PulseEnvelope.

Envelope id — The 16-byte BLAKE3 hash of an envelope’s canonical bytes under its domain tag. Identical content produces the identical id in Rust, Python, Node, C and WebAssembly; verify() recomputes it.

Envelope reference — The sixteen-byte envelope_ref field of a Pulse: the content id of the PulseEnvelope it names, byte for byte, or all zeros when the Pulse carries none. It has been part of the Pulse since the first commit and chapter 2 of the specification defines it; Pulse::envelope_id() reads it as a PulseEnvelopeId and set_envelope_id writes it. The daemon’s runtime fills it on the signal Pulse it writes for each stored envelope, and a second process attached to the hub fetches the envelope by it.

Envelope store — The content-addressed shared-memory store that sits beside a ring (core-store), where a Pulse’s envelope_ref resolves to the envelope it names. Layout v2 carries a magic, a version, a claim counter and per-slot sequence words, and holds each envelope as its canonical bytes, verified when read. Emerald in every figure.

FEC — Forward error correction in pulse-wire-udp: parity datagrams over a window of frames, so a receiver can rebuild a lost frame without asking for it.

Fixture — A byte-exact test vector under pulse/pulse-spec/test-vectors. Every implementation of the codec must reproduce the fixtures byte for byte; the conformance pages and the website’s scrubber are built on them.

Four-crate ring — The shape every ring under rings/ has: <ring>-core (shared types), <ring>-functions (stateless primitives), <ring>-stages (stateful processing) and <ring>-hub (the composed surface a consumer depends on). A layer with nothing to hold stays as an empty crate so the shape is uniform.

Four-question test — The rule in CONTRIBUTING.md for where new code goes: whether it touches the canonical Pulse atom, touches the canonical envelope, crosses a ring boundary or sits on the hot path decides whether it belongs in the inner stack; anything else is peripheral.

Heartbeat overlay — The HeartbeatPayload that occupies the last 32 bytes of a Pulse whose instruction is Heartbeat, read and written through heartbeat_payload and set_heartbeat_payload.

Hermes — The orchestration surface of Sov OS. Not part of this repository.

Hub — Three things, and the book says which: the daemon (mesh-hub), the runtime event bus it wraps (PulseHub in mesh-hub-runtime, combining a ring, an envelope store, the schema and broadcast registries and the health registry), and a ring’s hub crate (<ring>-hub).

Instance identifier — Sixteen random bytes a hub draws when it is created or opened, so every handle on a hub name has its own. The hub writes it into an origin_id left unset on the Pulses it publishes and skips the envelope signals that carry it, since its own listeners already had those envelopes.

Instruction — The 16-bit code in a Pulse that says what it signals: Null, Heartbeat or Data in this tree.

Knox™ — Cryptographic assertion in the Sovereignty stack (Knox / Musashi). Not part of this repository.

Kronos™ — The Sovereignty stack’s temporal authority: time as a load-bearing coordinate. The monotonic timestamp every Pulse carries and the hub’s temporal validation mode are the parts of that discipline present here.

Lane — One ring of a MultiLane set (hft-stages), named <prefix>-l<index>, so several writers can run in parallel without sharing a slot.

Lap — One pass of a ring’s or a store’s write cursor around its slots: cursor / capacity. The store’s sequence words encode the lap (2·lap + 1 in progress, 2·lap + 2 published), so a reader can tell that a slot holds the cursor it asked for and not the same slot from an earlier pass. The ring’s slot counter serves a poller the same way: each completed write adds two, so a copy whose counter shows more writes than its position’s lap needs may hold the next lap and is counted lost.

Layout version — The number a shared-memory header carries for its own layout: PMES version 2 for the envelope store, PMSR version 1 for the ring header. An open refuses a region whose version is not its own (LayoutMismatch). The ring’s header version numbers the header, not the slot format, which is version 1 at 128 bytes or version 2 at 192.

Lexicon™ — The conformance registry and the Merkle root over its public entries (mesh-lex), historically written R-LEX. The lex root anchors the published catalog; the daemon logs it at start.

Mesh — The set of processes attached to one hub, and by extension the substrate they share.

Monotonic nanoseconds — The monotonic_nanos field of a Pulse: a clock reading that must not go backwards within a hub, which the temporal validation mode enforces on the Pulses an application publishes. A hub stamps its own signals with the host’s monotonic clock (CLOCK_MONOTONIC on Linux, CLOCK_UPTIME_RAW on macOS) unless the application drives its clock.

MultiLane — N rings striped for parallel writers in the HFT ring, with NUMA placement and per-lane writer pinning.

Musashi™ — Proof-gated execution in the Sovereignty stack: authorization as witnessed mathematics. Not part of this repository.

NACK — A 12-byte feedback datagram asking the sender to retransmit one sequence number from its send cache. The receiver stages each missing sequence once, emits at most sixteen per cycle, repeats a request after four cycles and gives up after three; the sender bounds its queue and its retransmits per send.

Node id — The 16-byte identity the daemon derives from a client’s attach name (NodeId::from_name), rendered as name@hex.

Optimization module — One of twelve capabilities, M01 to M12, each a crate of its own or a module inside one layer of a ring, tagged with the developer profiles it suits. pms modules ls lists them, from a static table in the dev ring.

Origin — The producer’s node id as carried on an envelope event and matched by subscription filters.

Owl™ — Observation and telemetry in the Sovereignty stack. Not part of this repository.

Port protocol — See Universal Port Protocol.

Profiles (repository) — pulse-mesh-profiles, the repository of the enterprise, HFT and robotics rings, composed on the standard. Not a developer profile.

Pulse — The 128-byte atom: eleven fields in two cache lines, the first 8 bytes being the SeqLock word of the slot it sits in. Cyan in every figure.

Pulse Mesh™ — The wire format and the shared-memory transport this book documents, and the substrate the Sovereignty stack moves through.

PulseEnvelope™ — The variable-size, content-addressed envelope: a header, a payload that is raw bytes or a nested list of envelopes, and the envelope id computed over the canonical bytes. Violet in every figure.

PulseRegion — A shared-memory region holding exactly one Pulse under the SeqLock protocol (core-region).

PulseRing — The SeqLock ring in core-ring: a header and N slots in POSIX shared memory, one writer, whose publishes take its handle’s &mut, and any number of readers, each through a handle of its own in the writer’s process. The header records the ring’s magic, header version, capacity and slot size, and open refuses a mismatch. Version 1 slots are 128 bytes; version 2 slots are 192 bytes and add a ready line.

Ready line — The 8-byte word at bytes 128 to 136 of a version-2 slot that the writer bumps after a publish, so a hardware-wait receiver can monitor it instead of the SeqLock word. A reader may also poll it in place of the counter (PulseRing::read_position_by_ready).

Recovery window — The range of sequence numbers a UDP receiver may still ask the sender to retransmit: the sender’s send-cache capacity, 1,024 frames by default. A gap wider than the window keeps only its newest window of sequences staged; the rest are given up and counted.

Ring (buffer) — A PulseRing. When the book means the data structure it says ring buffer or PulseRing.

Ring (domain surface) — One of the four tier-3 surfaces: the dev ring, in the daemon repository, and the enterprise, HFT and robotics rings, in the profiles repository. When the book means these it says the dev ring, the HFT ring, and so on.

RITA™ — Modular role inference in the Sovereignty stack: governance mathematics as a replaceable part. Not part of this repository.

Sage™ — Deterministic governance in the Sovereignty stack. Not part of this repository.

Satellite — An external repository that implements a binding or an adapter against the conformance fixtures. modules.toml, in the profiles repository, defines the fields such a repository registers with; it lists none today.

SeqLock — The sequence-counter protocol that protects a slot: the writer marks the counter odd, copies the payload, and marks it even; a reader that sees an odd counter, or a counter that changed across its copy, retries for a bounded number of spins and then gives up.

Slot — One Pulse-sized cell of a ring, addressed by cursor modulo capacity.

Sov OS™ — The integrated experimental substrate of the Sovereignty stack, also written sovOS. The hub runtime and the module hub in this tree were vendored from its mesh core.

Stage — See four-crate ring.

Stall deadline — How long a UDP send may wait for the receiver’s cursor under backpressure before it fails with SenderError::Stalled: stall_timeout, five seconds by default, None for no deadline.

Subscription — A server-pushed stream of events matching a filter, opened by subscribe and identified by the id the ack carries. A tap is a subscription opened from the command line or Mesh::tap.

Thin client — The Python and Node clients in the daemon repository (clients/) that speak the port protocol directly, without the Rust client.

Tier — One of the four dependency layers: pulse (0), core (1), mesh (2), rings (3). A tier depends only on the tiers below it; the peripheral surface sits outside them and depends on all of them.

Type id, type name — The numeric and the named envelope type. A name-routed envelope carries its name, and its type id is 0 unless the sender gave one; a schema registered for a type id other than 0 checks it, named or not. Filters may match either.

Universal Port Protocol — Version 0 of the JSON protocol between the daemon and its clients: the operations attach, detach, send, subscribe, unsubscribe and health, and the replies ack, error, event and health, over a WebSocket (subprotocol pms-universal-port-v0) or a length-prefixed Unix socket. The types live in mesh-port-protocol.

WISP™ — The Sovereignty stack’s identity primitive. Not part of this repository; the registry at sovfound.org/registry records the mark and its status.

Why it is shaped this way

Part 04 · Concepts

Why it is shaped this way

One claim, the mechanism that makes it true, and what would refute it.

Explanation · for anyone who wants to understand the design before trusting it

An explanation page makes one claim about the design, shows the mechanism that makes it true, and says what would refute it. It does not give steps and it does not list facts for lookup; those belong in the other parts. This opener carries the first explanation, the shape of the whole system, because every later page assumes it.

• Substrate versus contract: where the standard’s substrate ends and the daemon’s contract begins; the substrate itself is The SeqLock memory model, in the standard’s book, with Why a 128-byte atom and Why content addressing before it.
• Daemon design, Trust boundaries: moving bytes between processes; between machines is Transport design, in the standard’s book.
• Decision log: what was decided.

The shape of the system

The system is four tiers, and a tier depends only on the tiers below it. This repository holds tier 2 and one tier-3 ring; the bottom two tiers are the standard, and the other rings are the profiles.

Beside the tiers, each repository has its leaves: here the pms tools, the thin clients, the basket query tool, the examples and the fuzz harness; in the standard the pulse command line, the bindings, its examples and its fuzz harness; in the profiles the XDP plugin and the HFT telemetry tool. They consume the tiers and are consumed by nothing.

Every ring has the same four crates, and the shape is deliberate. <ring>-core holds the shared types the ring’s other layers reuse, with no logic and no I/O. <ring>-functions holds stateless primitives. <ring>-stages holds the stateful processing: pipelines, lanes, delivery. <ring>-hub composes the three and is the only crate a downstream consumer depends on. A layer that has nothing to hold stays as an empty crate, so that every ring reads the same way; dev-core is one. The macro that composes a hub, register_stages!, lives in the standard’s core/mesh-stage-registry, because it depends on nothing and every hub uses it.

The colors in the table are the website’s and the book’s: cyan is the Pulse, violet the envelope, emerald the substrate that holds them, amber the transport that moves them, rose an error or a mismatch, slate whatever a figure sets aside. A figure that uses them is self-describing once the legend is known.

What would refute this

The claim is that the tiers depend only downward and that every ring keeps the four-crate shape. cargo tree over each workspace is the check, and scripts/arch-check.py runs it in every repository’s gate: a tier-2 crate here that depends on the dev ring, a crate of the standard that depends on anything here, or a ring whose hub is not the only entry point, contradicts the page.

Substrate versus contract

Explanation · for anyone who has met a "maximum envelope size" somewhere in the tree and wants to know whether it is part of the format

The claim. The envelope contract has no size limit, and every limit a reader meets belongs to the substrate that is carrying the envelope at that moment. Keeping the two apart is what lets one wire format run over a datagram, a shared-memory ring and a daemon socket without three definitions of an envelope.

The mechanism

The canonical bytes of an envelope are a function of its fields and nothing else; the specification says so and the vectors prove it. A limit on how many of those bytes a particular medium can carry is a fact about the medium. Three such facts exist in this tree, each recorded where it applies:

An implementation that carries envelopes over a medium with no such limit, shared memory between two processes for instance, MUST NOT impose one, and a transport that refuses an envelope its medium cannot hold is not violating the contract; it is reporting a property of itself.

The same separation runs through the rest of the design. The ring’s slot size is a substrate fact and the Pulse’s 128 bytes are a contract fact; they coincide by construction, and a version-2 slot that adds a ready line changes the substrate without touching the Pulse. The daemon’s protocol version and the standard’s draft revision are two counters because they change for two reasons.

Why it matters

Confusing the two produces the wrong fix in both directions. Raising an envelope limit “in the format” to suit one transport would force every other implementation to change for a property it does not have; lowering one to match the smallest medium would forbid what shared memory carries for free. Naming the limit after its medium keeps each change local.

What would refute this

A conformant decoder that rejects an envelope for its size alone, or a substrate limit that had to be written into the canonical bytes to be enforced, would refute the separation. The codec’s tests decode envelopes far larger than any substrate limit, and the transport’s tests refuse at the transport, not in the codec.

Spoken walkthrough

A script for the video and audio version of this page, about a minute.

Somewhere in the tree you meet a maximum envelope size. Is it part of the format? No. The format has no size limit; the medium carrying the envelope at that moment does.

A UDP datagram carries about thirteen hundred bytes of envelope, or about sixty-five kilobytes if you switch fragmentation on at both ends. A store entry carries sixty-four kilobytes, and says so in its header. A daemon connection carries what its policy allows. Shared memory between two processes carries whatever you like, and an implementation on a medium with no limit must not invent one.

Keeping the two apart is what lets one wire format run over a datagram, a ring and a socket without three definitions of an envelope. Raise a limit in the format to suit one transport, and every other implementation changes for a property it does not have. Name the limit after its medium, and each change stays local.

Daemon design

Explanation · for anyone running `mesh-hub` for other processes, and for anyone who wants to know what one misbehaving client can and cannot do to the rest

The claim. One misbehaving client of the daemon, whether silent, slow, greedy or duplicated, costs the other clients nothing: every resource a connection can consume is bounded by a policy the operator sets, the number of connections is bounded by the same policy, and every failure is reported to the client that caused it.

The mechanism

The daemon is a library with a binary in front of it: the crate’s run takes a DaemonConfig (the hub name and configuration, the socket and the address to serve, the connection policy, a basket) and serves until a signal or a displacement, and the binary only parses its flags into that configuration; a host that embeds the daemon calls the same surface without the signals. A connection is one task that owns its transport in both directions and a bounded queue of outbound messages. Four timers and four sizes govern it. A WebSocket client is pinged every thirty seconds and a Unix-socket client is expected to say something itself, so a connection silent for ninety seconds is closed rather than held open forever with a name nobody can reuse. A write that does not complete in ten seconds means the peer has stopped reading, and the connection is closed rather than letting its queue grow without bound. A WebSocket upgrade that does not finish in five seconds is dropped, so a connection that never speaks cannot park a task. A frame larger than a megabyte is refused with an error the client can act on, and the daemon reads a frame incrementally rather than allocating the announced length up front, so a four-byte header cannot buy sixteen megabytes. A connection holds at most sixty-four subscriptions, because every send is matched against every live subscription and the cap bounds what one connection adds to the cost of each; the subscribe past it is refused with limit_exceeded, the connection stays open, and an unsubscribe frees a place. The daemon holds at most 256 connections across both transports, counted from accept to close: past that, a Unix-socket client is turned away with one error frame and a WebSocket upgrade is answered 503, each refusal counted, logged at the first and at each doubling, and printed at exit.

Events are the one thing a client cannot be trusted to consume at the daemon’s pace, so they go through a bounded queue, 1,024 deep by default, that the publisher writes into without waiting. When the queue is full the newest event is dropped and counted; the count is logged at the first drop and at each doubling so a log does not fill either, and it is handed back to the subscriber in the acknowledgement of its unsubscribe, so the loss is the subscriber’s to see. Acknowledgements and errors bypass the queue and are never dropped. The alternative, disconnecting a slow subscriber, would turn a brief stall into a reconnect and a resubscribe that loses the same events anyway; it remains available as a policy if a deployment wants it.

A publish the envelope store refuses, because the envelope is larger than a store entry or every slot the store tried was held, is still delivered to every matching subscriber and still acknowledged. The acknowledgement says persisted: false, which the Rust client returns from send_with_receipt, the daemon counts the refusal, logs it at the first and at each doubling, prints the count when it exits, and writes no ring signal for an envelope that is not in the store, so a process reading the ring is never pointed at an envelope that is not there. Before this rule a refusal was neither counted nor reported, and the client was acknowledged as if the envelope had been stored. A store that shared memory has no room for is refused when the daemon starts, with the reason in its log, and the daemon then runs without persistence rather than failing later with a SIGBUS at the first page it touches.

An envelope published through the daemon also reaches a process that is no client of the daemon at all, one that embeds a hub of the same name. The daemon’s hub stores the envelope and writes a signal Pulse into the ring that names it and carries the hub’s own instance identity; the other hub’s poll fetches the envelope from the store by that name and delivers it to its envelope listeners. A signal the hub wrote itself is skipped, because its listeners had the envelope when it was broadcast. A signal whose envelope the store no longer holds, overwritten since it was stored, never stored, or failing verification, delivers no envelope, and is counted (unfetched_envelopes) and logged at the first and at each doubling; a Pulse the ring overwrote before the poll reached it is counted the same way (lost_pulses) and never delivered under another index or twice. The ring has one writer, the daemon’s hub, which created it: the embedded hub reads the ring and is refused with ReadOnly if it tries to publish, broadcast or route into it, with nothing stored, signalled or dispatched, and its process publishes by sending to the daemon over the port like any other client, so two writers never race for the ring’s cursor. The signals the daemon writes carry the operating system’s monotonic clock in nanoseconds, since the daemon does not drive the hub’s clock itself. Before these rules the signal left envelope_ref and the clock at zero, so a second process saw every signal and never an envelope, and a second hub on the name could have written into the ring.

Names are exclusive while a connection holds them and released the moment it ends, whether by detach, by a closed socket, or by one of the timers, together with every subscription the connection had, so nothing leaks into the hub’s registries between a client’s death and its return. A second daemon started on the same Unix socket path probes the socket before touching it: if a daemon answers, the second refuses to start and says so; only a socket file nobody answers is removed. Before this rule a second start silently took the first daemon’s socket and left it deaf.

What it costs

A timer wheel per connection, one bounded channel per connection, and a policy the operator must think about once: the defaults suit a workstation, and a busy fan-out may want a deeper queue. A Unix-socket client written against the raw protocol must send a frame within the idle window; the Rust client does this on its own.

What would refute this

A silent connection that survives its idle window, a stalled subscriber that slows a publisher, an oversized header that allocates, a name held after its connection died, a store refusal acknowledged as a success, a sixty-fifth subscription that is accepted, a connection past the cap that is admitted, a second daemon that takes over a live socket, an embedded hub that reads the daemon’s signal and never the envelope it names, or a second hub on the daemon’s name that writes into its ring would each refute the claim. The daemon’s liveness, fan-out and embed tests are the checks, and each runs in the workspace test suite.

Spoken walkthrough

A script for the video and audio version of this page, about ninety seconds.

The question a daemon has to answer is what one bad client can do to the rest. Here the answer is nothing, because every resource a connection can consume is bounded by a policy the operator sets once.

A connection is one task with a bounded queue of outbound messages. Four timers and four sizes govern it: how long it may be silent, how long a frame may take, how large a header may be, how many subscriptions it may hold. Cross a bound and the connection is closed, and told why.

Events are the one thing a client cannot be trusted to consume at the daemon’s pace, so they go through a bounded queue the publisher never waits on. Fill it and the newest event is dropped, counted, and reported back to the subscriber when it unsubscribes. Acknowledgements and errors never queue and are never dropped.

A publish the store refuses is still delivered and still acknowledged, with persisted false, and no ring signal is written for an envelope that is not there. Names are released the instant a connection ends. A second daemon on the same socket asks before it takes it.

None of this is clever. It is a list of bounds, each with a test that tries to cross it.

Trust boundaries

Explanation · for anyone deploying Pulse Mesh beyond one trusted machine, and for anyone auditing what protects what

The claim. Pulse Mesh’s integrity mechanisms detect corruption and prove content; they authenticate no one. Authentication and encryption exist, each opt-in and each at a named place: sealed UDP between nodes that know each other’s keys, TLS and proven keys on the daemon’s remote surfaces, and node keys on the links between daemons. Where none is switched on, the host’s own boundaries are the only ones, and this page says where those are.

What the integrity mechanisms prove

The CRC on a datagram detects accidental corruption in transit. It is not a signature: anyone who can send a datagram can compute a valid CRC, so a matching CRC means the bytes arrived as sent, not that a trusted party sent them. The envelope identifier proves that the content is what its name says; it does not say who produced the content, because the origin is deliberately outside the preimage. The SeqLock proves that a reader’s copy is one writer’s complete write; it assumes every process mapped into the region is trusted, because any of them could write anywhere in it. The Pulse’s chain_step and preimage fields are reserved for a replay defence that is not implemented in this release, so a Pulse carries no replay protection of its own. preimage is unused; carriers reuse chain_step (core-ring marks overruns in it, and the daemon’s links carry their hop limit in it), which proves nothing about who sent a Pulse. Replay is refused where sealing is on, at the transport, as the next section says.

What authenticates and encrypts, and where

Each of these is opt-in, by ADR-0018. Plaintext stays the default where the host already protects the path: shared memory, the Unix socket and loopback.

Sealed UDP, between nodes that know each other’s keys. A node holds one long-term X25519 key, generated on first start into a file only its owner can read, and is identified by its public key, not its name; peers are admitted by an allowlist of keys. Two nodes run a Noise IK handshake (Noise_IK_25519_ChaChaPoly_BLAKE2s, through the snow crate), then every datagram, whatever the transport would have sent in the clear, is encrypted and authenticated whole with ChaCha20-Poly1305, 36 bytes of overhead, and the inner frame keeps its CRC. A receiver drops a datagram whose seal counter is older than a window of 2,048 or already seen inside it, so replay is refused at the transport; sessions rekey every two minutes and are dropped after three idle periods; a node configured for sealing refuses plaintext from any address that is not loopback. The cryptographic-engineering review that ADR-0018 item 9 requires has not been done, so sealed mode is not yet recommended for production, and the module says so in its own documentation.

The daemon’s remote surfaces. The WebSocket is plaintext on loopback by default. With --ws-tls-cert and --ws-tls-key it is wss://: TLS 1.3 through rustls, which encrypts the connection and authenticates the daemon to clients that trust the certificate. With --attach-keys, a client attaching over the WebSocket must present a listed Ed25519 public key and answer the daemon’s challenge with a proof of it, and is then named by the key; --attach-keys-uds asks the same of the Unix socket. A --ws-bind on an address other than loopback is refused unless both are given, or unless --ws-allow-remote says the gap is meant, in which case the daemon logs a warning naming what is missing.

Links between daemons. A daemon’s links to other daemons run on sealed UDP only, keyed by its node key, and only the configured peers’ keys are admitted, each from the IP of the address its --link-peer names; a peer named by its key alone (--link-peer-key) is admitted from whatever address its handshake comes from, its key authenticated as any peer’s is. Nothing signs an envelope or its origin end to end, so what a relay says about where a forwarded send came from is as trustworthy as the relay, and a daemon takes relayed traffic only from a peer it names with --link-trust-relay. The capability Hello is the first message of each link session, inside the sealed session, so a path attacker cannot strip or forge its bits; on plain UDP nothing sends the Hello yet, and nothing acts on an agreed upgrade yet.

The enterprise ring’s TLS stage. The sender verifies the server’s certificate and name against the roots it is given; the receiver authenticates no client. A deployment that must know who connects puts that control in front of the port.

Where the boundaries are without them

Shared memory. A ring, a region and a store are POSIX objects created with owner-only permissions; every process that can open them is a peer with full write access. The boundary is the operating system’s: users and namespaces.

The daemon on its defaults. mesh-hub listens on a Unix socket with owner-only permissions and on the loopback interface, so its peers are processes of the same user on the same host. Any attached client may publish to any channel and subscribe to any filter: the daemon registers no schemas, so on its defaults there is no authorisation, and without --attach-keys no identity beyond the name a client chooses.

The UDP transport in plaintext. A data socket accepts a valid frame from any source. The feedback socket, which drives backpressure and retransmission, accepts acknowledgements and retransmission requests from any source unless BackpressureConfig::feedback_peer names one, when feedback from anyone else is dropped and counted. Source addresses can be forged, so the filter is a mitigation, not a boundary. A forged acknowledgement can only raise the sender’s cursor, which releases its stall; a forged request can only cost one bounded retransmission to the sender’s own destination. Every amplifier is bounded by design.

What is deliberately absent

Per-channel authorisation is in no layer, and any attached client may subscribe to anything. The one control on publishing is per envelope type: a hub that registers a schema with a producer list (mesh-schema, through the hub’s API; the daemon’s flags register none) refuses that type from any other node, by key when clients prove keys at attach. A schema’s consumer list is recorded and not enforced. Nothing signs an envelope’s origin end to end. Neither is in the substrate because the standard’s contract is the bytes, and a second thing to agree on before the bytes could agree would be a second standard; authority above the transport belongs to the layers the Sovereignty stack puts around it, or to the deployment.

What would refute this

A deployment guide that presented the CRC or the identifier as authentication; a daemon that bound a routable address without TLS and attach keys and without a warning; a sealed receiver that accepted a replayed datagram, or a plaintext frame from a non-loopback address; a link that admitted an unlisted key, or relayed traffic from a peer not named as a relay; or a feedback path with an unbounded amplifier would each contradict this page. The transport’s sealed-decode fuzz target and replay tests, the daemon’s attach-key and --ws-allow-remote tests, the link tests and the feedback-filter and queue-bound tests are the checks for the mechanisms; the first claim is checked by reading the code this page cites.

Spoken walkthrough

A script for the video and audio version of this page, about ninety seconds.

Three things in Pulse Mesh prove something, and none of them proves who you are talking to. The checksum proves the bytes arrived as sent. The identifier proves the content is what its name says. The ring’s counter proves a reader got one writer’s whole write. Useful, and not authentication.

Authentication and encryption exist, but you switch them on, at a named place. Between machines over UDP, sealing: each node has a key, peers are listed by key, and every datagram is encrypted and authenticated, replays refused. On the daemon’s WebSocket, TLS for the connection and a proven key for the client. On the links between daemons, the same node keys. Two caveats come with the first: the independent review the design requires has not happened yet, so sealed mode is not yet recommended for production; and a relay’s word about where a message came from is only as good as the relay, so you name the relays you trust.

Where nothing is switched on, the boundaries are the host’s: who can open the shared memory, who can reach the socket. And one thing is in no layer at all: per-channel permission. A client that may attach may publish on any channel. That is the deployment’s to add, and this page is where it says so.

Decision log

Explanation · generated · the architectural decision record under `decisions/`, in order, never rewritten

Each record states its context, the decision and its consequences, and stays in place when a later record supersedes it. The index below is read from the files; the files are the record.

A non-obvious call (where something belongs, why a crate is shaped the way it is, anything a later contributor would otherwise reverse-engineer from a pull request) gets a new record rather than only an explanation in the pull request. Number it one past the highest present, and say in its body which earlier record it supersedes, if any. Numbers are never reused, so a gap is a retired record.

Changing the tree

Part 05 · Contributing

Changing the tree

The workspace, the gates, the decision record, and the rules this book holds itself to.

Part opener · for people changing code or documentation

Contributions go through the same gates whether they change code or prose: formatting, lints, the tests, the rustdoc link check, and for the book the structural checks that keep every page reachable, every link resolving, every displayed version equal to the workspace version, and internal process language out of released text.

• Developer Onboarding: the workspace, the branch and PR flow, the gates.
• Documentation style: the page kinds, the voice, and the review checklist for anything written.
• Decision log: the decision record under decisions/ and how to add to it.

Documentation style

Contributing · for anyone writing or reviewing a page of this book, a README, a crate overview or a message a user will read

The book is held to the same standard as the code: every page has one job, states it, and can be checked. This page is the standard. The review checklist at the end is what a documentation pull request is read against.

One page, one kind

Every page is exactly one of six kinds and says which in its first line, in the label the theme renders from <p class="pm-kind"><b>Kind</b> · for whom</p>.

A page that wants to do two jobs is two pages.

Voice

The voice is the Foundation’s, as it stands on the Foundation’s website.

• Declarative and precise. State the claim, then the evidence. “A reader that sees an odd counter retries” rather than “readers will generally want to retry”.
• One idea per sentence. Short sentences carry weight; a sentence that needs a semicolon is two sentences.
• Institutional, not personal. No “we think”, no “I”, no “the author”. Tutorials and guides address the reader as “you”; reference and explanation pages address no one.
• No superlatives, no hedging, no marketing. “The ring publishes without a system call” rather than “blazingly fast”.
• Define a term before using it, and use the glossary’s word for it every time. Pulse, PulseEnvelope, the daemon, pms, the four tiers, the dev ring: never a synonym.
• Numbers carry units and a source. A measurement names the command that produced it.
• What is not yet true is said plainly. A specified behaviour that the code does not implement yet is named as such, with the test that will prove it.
• Superseded material stays in place and is marked; nothing is silently rewritten. Decisions go to decisions/ as append-only records.
• Every explanation ends with what would refute it. Refutations are welcome and the page says so.
• American spelling. Present tense. Second person only in tutorials and guides.

Names that are welcome and names that are not

The Sovereignty stack’s names are public and are used deliberately: Canon, the Lexicon, Kronos, Sov OS, Musashi, Knox, Aegis, Sage, RITA, Hermes, Owl, WISP. The glossary maps each to the component that carries it here or says it is not part of this repository.

The names the registry lists as marks (Pulse Mesh™, PulseEnvelope™, Canon™, Lexicon™, Kronos™ and the rest; the list is at sovfound.org/registry) carry ™ on their first prominent use on a page: the hero, a part opener, a glossary entry, the first mention in prose. Later mentions on the same page do not repeat it.

What released text does not carry is the language of how the tree was made rather than what it is: internal phase labels, migration process notes, and names of documents or features that no longer exist. scripts/docs/lint-terms.py holds the list and runs in the documentation gate.

Structure

• Headings are phrased as the reader’s question or task in tutorials and guides (“Publish an envelope”, “What you will need”), and as the noun they describe in reference and explanation (“Slot layout”, “Why two reads”).
• Code comes before prose in a how-to guide: the command, then what it does.
• A page stays under about 1,500 words. A page that grows past it splits along its headings.
• Rust samples are included from the examples with {{#include}} anchors rather than typed into the page, so the sample and the page cannot drift. Shell transcripts show the command and the output the reader should see.
• Every reference table that can be generated from the code is generated, and the gate regenerates it and fails on a difference.
• One figure per explanation page, from the website’s catalogue where one exists, with a caption in the label idiom (<figure class="pm-figure">). Colors mean what the legend says: cyan the Pulse, violet the envelope, emerald the substrate, amber the transport, rose an error, slate what is set aside.
• Links are relative and point at pages of this book, at files in the tree, or at the decision record. The gate checks that every link resolves and every page is reachable from the summary.

Markdown conventions

One paragraph is one line; prose is never hard-wrapped at a column. List items and table rows are one line each. Code blocks name their language. Files begin with a single # heading and then the page kind line (part openers and the introduction carry their heading inside the hero block, with the kind line after it).

The review checklist

A documentation pull request is read against these questions, and each one is answered before it merges.

1. Is the page exactly one kind, and does its first line say which and for whom?
2. Does every command in it run in the documentation gate, and does the output shown match?
3. Is every fact traceable to code, a test, a fixture, or a bench command named on the page?
4. Does an explanation page make one claim, show one figure, and say what would refute it?
5. Are all terms the glossary’s terms, used in the glossary’s senses?
6. Does the page carry no internal process language, no persona, and no name of something that does not exist?
7. Do the version, the links and the summary pass the gate (just docs)?
8. Is anything superseded marked rather than deleted, and is any decision it records in decisions/?
9. Is it under the length limit, or split?
10. Would a reader who knows nothing of how this tree was made understand every sentence?
11. Is every claim about what the code does, or lacks, checked against the code itself rather than against a comment, an earlier page or a review? A comment can be wrong from the day it was written, and a claim that is only ever checked against other claims is never refuted.