MERIDIAN

0 Two rules that govern every number on this page

Both are binding contract in AGENTS.md, not editorial preference. If you take nothing else from this page, take these — they are why the document is longer than a slide.

1 The stack — three tiers, and what each may never do

Before the traffic-class argument makes sense, the shape has to. MERIDIAN is one self-hosted repository: source, builds and deployment all live in it, and there is no sibling pipeline to coordinate with. What runs is three tiers with one enforcement point between them. Source: DIAGRAM.md § Part I, ARCHITECTURE.md.

  CLIENT TIER — TWO EDGES, ONE RELAY

    NOSTR CLIENT EDGE  [in tree]                    MACHINE EDGE  [committed]

    Desktop     Mobile     Web        Agents        Feeders · IoT · server-to-server
    Tauri 2 +   Flutter +  repo       meridian-cli  peers. Speaks Zenoh natively —
    React 19    Riverpod   browser    ACP·dev-MCP   NOT NIP-01. MIP-XP link profile.
        │          │          │           │                        │
        └──────────┴────┬─────┴───────────┘                        │
                        │                                          │
     WSS · NIP-01 EVENT / REQ / CLOSE / AUTH        opaque frames · fixed header
     HTTPS · /events /query /count /media           never parsed · never stored
              /git /hooks /info                     MIP-OF envelope
                        │                                          │
                        └────────────────┬─────────────────────────┘
                                         │
  RELAY TIER — meridian-relay, ONE Axum process, the ONLY enforcement point

    STEP 0 · community bind      resolve_host → TenantContext
                                 runs BEFORE auth, event, req, REST, media, git
        │
    STEP 1 · admission           NIP-42 challenge / NIP-98 · connection semaphore
        │                        handler semaphore (1024)
        ├─────────────────────────────┬───────────────────────────────
        ▼                             ▼
    STEP 2 · EVENT pipeline       STEP 3 · REQ pipeline
    kind gate · BIP-340 verify    access check BEFORE registration
    drift · size · identity       historical query, then EOSE
    scope · membership
        └─────────────┬───────────────┘
                      ▼
    STEP 4 · SubscriptionRegistry — DashMap, 3-tier fan-out index

    SUBSYSTEMS, called only by the relay and never by each other:
    meridian-core · -db · -auth · -pubsub · -search · -audit · -workflow · -media
                                    │
                                    ▼
  STACK TIER — one system of record per fact

    Postgres 17            Dragonfly              MinIO / S3         Opt-in profiles
    THE EVENT LOG          STATE, never events    BYTES, never       keycloak · prometheus
    events · channels      pub/sub · presence     events             adminer · artifacts
    members · workflows    typing · rate windows  media blobs          │
    audit chain · FTS      caches                 git objects (CAS)    │
                                                       │              ▼
                                                       ▼         ReductStore
                                                  IPFS [planned]  [opt-in · no
                                                  CID replicas     call sites]

Tier contracts — what each owns, and what it must never do

What is actually in the repository

Deployment is in-repo too: deploy/charts/ (Helm) and deploy/compose/, images at registry.r2d2.office.ilab.zone/meridian-*, hosts under *.meridian.r2d2.office.ilab.zone. A separate control plane provisions per-account relays and is deliberately not a second source of truth for tenancy — it stores the community_id → host bridge and executes every mutation against the relay's own NIP-98 operator API.

2 The one mental model: two relays in one binary

Almost every wrong intuition about this system comes from collapsing these two paths into one. They share a process and almost nothing else. Making that seam a deliberate module boundary — rather than an emergent property discovered when someone adds a parse() to the hot loop — is tracked as meridian-tg1. ARCHITECTURE.md states the same fact from the ingress side — "one binary, two data planes", reached through the two edges in §1 — and the two framings are the same seam seen from opposite ends.

  HUMAN + AGENT PATH  ── NIP-01 over WebSocket ─────────────────────────────────
    parse JSON → BIP-340 verify → Postgres INSERT → FTS index → audit chain
                 └─ 34–37.7 µs ─┘   └───── the durability boundary ─────┘
    ceiling: ~250–320k events/s per 16-core pod (verify-bound)
             ~10–30k/s once stored AND indexed

  MACHINE PATH  ── opaque frames, ephemeral kinds, trusted link ───────────────
    read ~44 B fixed header → match key expression → forward bytes, never parsed
                 └─ no signature, no store, no index, no audit ─┘
    ceiling: ~600k msg/s ≈ 0.44 Gbps in   (ESTIMATE — path not yet in tree)
    target:  1.0–1.5M msg/s per pod after the batching refactor  (TARGET, gated)

  SHARED:  the community/tenant fence · admission · interest routing · the bus
  NOT SHARED:  parsing · crypto · durability · query surface · client shape

What the header carries, and why each field is there

≈ 44 B fixed-width, no allocation, no parse tree. Spec: MIP-OF (meridian-tdq) — DRAFT. The encoder is postcard, already a workspace dependency. A worked budget exists: MIP-CT's ≤37 B core track payload on this header is ≤81 B fixed-width, ~75 B after varints — for a track carried without source attachment, which is exactly the kind of profile this page refuses to drop.

3 Replacing TBMQ — what is drop-in, what needs an adapter

The honest version of the claim, and the one the Architecture & Scale council approved: Meridian replaces the broker's bus, policy and audit role. A broker remains legitimate — often correct — at the constrained-device edge, feeding the spine through a feeder and never as a routing peer. Read the three tables below in order; the third is the one that keeps us honest.

Drop-in today — the same job, done differently

Needs an adapter — real work, sized and owned

Why the broker shape stops working as we scale

Eight arguments, all decidable from shape rather than from a benchmark:

  THE RATIFIED TOPOLOGY — hub and leaf, never peer

   constrained devices       EDGE — MQTT bridge          FEEDER              SPINE
   MQTT clients,        ──►  + LEAF RELAY          ──►   decode        ──►   ONE authoritative
   intermittent links        persistent sessions         dedup               relay per community
   need offline queues       QoS 1/2 · retained          routing header      admission
                             LWT · shared subs           MAC or sign         verification
                             store-and-forward           batch               tenancy fence
                             across outages                                  audit · fan-out

   ✕ REFUSED: the leaf as a routing peer.
     A leaf outage would become a spine routing failure, and a compromised
     leaf could transit between communities.   (Refusal R4 · Law 2)

4 The decentralized story — five axes, and eight refusals

A broker scales one way: more broker nodes, more partitions. We scale five ways, and the discipline that makes that safe is the refusal register — the moves this architecture will not make, each with its reason and its review-time tell.

If a proposed split's failure story is not one of those five sentences, it is on the wrong axis.

The refusals — bring these to design review

Four invariants every axis must preserve

1. The edge cannot tell — NIP-01 unchanged; no client learns the internal shape.
2. One system of record per fact — everything else is a cursor-bearing, freshness-stamped projection.
3. Stale, never wrong — a scaled-out part may lag, with the lag published; it may never lose or reject.
4. No new authorizer — scale-out never adds a place where policy is decided.

5 Throughput goals — every figure with its profile

This is the table to memorize. Note how many rows say estimate. That is the point: the discipline is what makes the measured rows worth quoting.

What the target costs on each path — the argument in one table

Ingest CPU required to sustain 1,337,000 msg/s on one host, profile ingress, QoS 0 equivalent, small payload, never stored:

The target is architecturally reachable on the opaque-frame path and architecturally unreachable on the signed path. That is the whole case, and it must always be published with both halves — a figure quoted without the second row is exactly the obligation rule ① exists to prevent.

Where the machine path's constraint actually sits: egress, not ingest

    egress  =  R_in  ×  Σ  f_s        f_s = the fraction of the keyspace
                        s              subscriber s declared interest in

    Ingest is a fixed ~0.44 Gbps at 600k msg/s.   EGRESS MULTIPLIES.

    10 subscribers, all want everything (f=1)  →  6M msg/s  ≈ 4.4 Gbps
    10 subscribers, 1% of cells each           →  60k msg/s ≈  44 Mbps
   100 subscribers, 1% of cells each           → 600k msg/s ≈ 0.44 Gbps

Ingest cost model at 600k msg/s, transmission only

Ingest is cheap; the relay can carry the firehose directly — if and only if it never parses it. Aggregation is an optimisation, not a precondition. The single structural fix for the dominant row is meridian-0zd: make the batch the type flowing through the pipeline (mpsc::Sender<FrameBatch>, not <Frame>), with a synchronous inner loop. Estimated 10–20×.

6 Transport and the adapter contract — latency, lanes, buffers

Two pieces of work sit between a device feed and the spine, and they are the highest-leverage reusable assets in the program.

Zenoh as the spine — surface by surface

Zenoh is the transport spine for everything except the Nostr client edge. That exception is not a compromise; it is what lets the spine exist at all, and it keeps Nostr interoperability — the project's stated core value — intact.

Three properties keep this checkable in review: Zenoh adds no event kind and no client-facing NIP (MIP-SF adds a message type, SFRAME, in the existing ephemeral range); Zenoh is never a store — zenoh-backend-* storages exist and are not a transactional store with FTS, partitioning and an audit chain; Dragonfly is narrowed, not displaced — presence TTLs, rate-limit INCR+EXPIRE, the NIP-98 replay set and the fenced arbiter all need a keyspace with atomics, and Zenoh is a pub/sub fabric, not a keyspace.

The adapter / feeder contract — build once, second feed is configuration

MIP-AD (meridian-qi7f) is now a written spec, and it is the mechanism that makes every subsequent protocol profile thin. It pins the four things every feed argues about and no envelope can infer: units, coordinate reference system, time base, and declared lossiness. Profiles built on it — MAVLink, NMEA 0183, Remote ID, ROS 2/DDS, AIS — add no mechanism of their own. Six obligations:

QoS lanes — the buffers each class needs

Today all of these share one undifferentiated lane, so a burst of typing indicators can consume buffer that chat needs. The map below is designed (Zenoh Phase 3); the bottom two rows are the proposed drone/machine additions.

Dynamic buffering — the three knobs that matter

Topology — and where zenohd optionally enters

  TODAY          Pod A ──┐                        two hops per cross-pod event
  [in tree]      Pod B ──┼──► Dragonfly ──►       SPOF + broker hop
                 Pod C ──┘

  PHASE 2        Pod A ◄──► Pod B                 peer mode, ONE hop.
  [committed]       ▲  ╲   ╱  ▲                   THE PEER IS IN-PROCESS in
   meridian-bem     │    ╳    │                   every relay pod — this is
                    └─► Pod C ┘                   the destination, not a
                                                  waypoint.

                                                  Dragonfly stays — STATE ONLY:
                                                  presence TTL, rate limits,
                                                  replay set, fence generation

  PHASE 4        region 1: Pod A ─┐                    ┌─ Pod C :region 2
  [OPTIONAL]                      ├─ zenohd ◄─► zenohd ─┤
   meridian-0ps  region 1: Pod B ─┘                    └─ Pod D :region 2

                 Added ONLY where a full peer mesh stops being viable
                 (peer links grow with the square of the pod count).
                 Opt-in `bus` compose profile, default off.

7 Anti-shredding — time-based, not transactional

This is the trade the brief names, and it deserves its own vocabulary because it is the single most likely thing for a team arriving from MQTT to get backwards.

Three movement contracts — and why this is protocol, not a buffer policy

What the client has to do — the consumer half

design proposal The relay-side contract is specified (meridian-9j8); the client-side twin below is derived from it here and is not yet a bead. It is the first thing this team should file.

1. Hold last-known-state, keyed by conflation key — not a message queue. The client's model is a table of targets, not a log of updates.
2. Age by header timestamp, never by arrival — staleness is a property of the observation, not of the delivery. This is what makes the picture correct across reconnects and route changes.
3. Render staleness rather than hiding it — a target that has not updated in n seconds should look different from one that just did. Silence and a stale value are not the same thing, and the operator is the one who must be able to tell.
4. Use sequence for gap detection, not for reassembly — a gap in a conflated stream is expected and benign; a gap in a volatile stream is data loss. Same field, two different meanings, decided by the declared contract.
5. Beacons are the liveness channel, and they are separate — a health beacon (proposed 21002) says the platform is alive. Position silence says nothing new to report, or the link is down, and the client cannot distinguish them without the beacon. This is the closest thing we have to Last Will & Testament, and it is a beacon rather than a broker primitive precisely because we are time-based.

8 The MIP register — 23 proposals, a lifecycle, and zero enforced

This section has grown more than any other since the page was written. It described four specs under an editorial naming convention; it now describes a governed register with a state machine, a CI guard, and a hard rule about what a relay may advertise. Read the lifecycle before the register — the register's size is a measure of design work, not of shipped work, and the two are easy to confuse in exactly the direction that flatters us.

The lifecycle — and the one state that permits advertisement

The register — 23 proposals, and what each owns

Mechanism MIPs add machinery. A profile MIP adds none — it binds an existing envelope, payload schema and link profile to one real-world feed, and states which enforcement point rejects a non-conforming frame. That distinction is what keeps the register from becoming a wish list.

Layering is strict and one-directional: MIP-XP → MIP-OF → MIP-QC → MIP-LF → MIP-MQ, with MIP-SF, MIP-KN and MIP-TL hanging off the envelope. A payload MIP may never require the relay to read it — that is the enabling property, not a limitation.

Machine kinds — the block moved, and the axis changed with it

This page previously proposed 21000/21001/21002 split by payload type — kinematic frame, telemetry frame, health beacon (that proposal survives on meridian-41a and is now superseded). The register consolidated on a single ephemeral machine block, 24400–24419, and split it by symbol set — that is, by domain:

All five track kinds are conflated. Why domain and not payload type: air refreshes at 1–10 Hz and subsurface at ~0.01 Hz — three orders of magnitude apart — so the domain genuinely is a traffic class, which is sanctioned axis A4. Splitting by payload type would have put a 10 Hz and a 0.01 Hz stream in one lane. 24400 is a narrower profile of 24405, not a competitor: AIS is one source of sea-surface tracks, so a consumer wanting all surface tracks subscribes to both. KIND_TRACK_SPACE carries a hard consumer obligation — orbital motion MUST NOT be dead-reckoned; course and speed encode unknown by construction.

Three dependencies that are easy to miss

9 Symbology — SIDC / MIL-STD-2525 / APP-6, and the kinematics extension

The two layers — and why there are two

Q1 · Header or payload? — answered, and this page had it partly wrong

The earlier answer was a clean blanket rule: the SIDC struct belongs in the payload, never in the header. MIP-CT keeps the reasoning and rejects the blanket. The discriminator is not "is it symbology" — it is mutability.

Q2 · What the payload carries

Three design calls worth knowing before you argue with them. (1) Track phase is not SIDC status. SIDC status (pos 7) is operational condition — present, planned, damaged, destroyed. Phase is track quality. A destroyed target can still be a well-tracked object, so both travel. (2) Confidence has no "unknown" codepoint — ten buckets, and an unsourced confidence still picks one: the lowest defensible. Confidence ≤ 0.35 SHOULD pair with standard identity Pending or Unknown. (3) Elevation is f32 metres, not fixed-point — the kinematic core spans crush depth to beyond GEO, eleven orders of magnitude, and a fixed-point integer that reaches 36 000 km cannot also resolve a drone at 840 m. Relative precision is what elevation needs.

Byte budget: ≤37 B fixed-width core plus the empty extension-vector byte, so header plus bare payload is ≤82 B, landing near ~76 B after postcard varints — for a track carried without source attachment or populated payload extensions. Quoting 76 B for an attachment- or amplifier-bearing track would be exactly the profile-free figure rule ① forbids.

Q3 · Adapters — additive, never destructive

Q4 · Trap 2 is the one thing here still genuinely open

Q5 · The custom kinematics extension

• It is a MIP, not a NIP — mechanically, by the two-letter rule in §8. It is MIP-CT, extending MIP-KN.
• It must not re-encode what MIP-KN already carries. Position, velocity, heading and altitude are already the payload. If the extension restates them in symbology terms there are two answers to "where is it", and the converter between them is where provenance gets lost.
• It needs an enforcement point on day one, or it fails just check-kinds. The five track kinds each need a QoS row for the same reason — do not merge a kind constant without a QoS class.
• Version it in the payload, at the same fence as the encoding (sidc_defaults_version). Subscribers on the old version simply never see the new one.

10 Where to start — the plan of record

The binding constraint on this program is WIP, not knowledge, and it has grown since this page was first written — and it is still growing faster than it drains. Live tracker state: 485 issues total — 305 open, 235 ready to work, 16 in progress, 70 blocked, 164 closed.

Phasing — greenfield core first, bridge second, and the order is the point

Building the bridge first would let MQTT semantics — per-message topic ACLs, broker-held delivery state, topic-string tenancy — leak into the core, which is precisely what this program exists to remove.

The eight epics

Sprints, and the one gate that can stop the program

Ten constraints a story is rejected for violating, regardless of its benchmark

C-1 every published figure carries its profile · C-2 no vocabulary without an enforcement point · C-3 names never encode ownership — no org/site/device prefixes in key expressions, storage keys or ACLs · C-4 add attributes, not mechanisms — no policy DSL, rules engine or plugin runtime in the bridge · C-5 no third shim — the bridge holds no ACL copy and no sync job · C-6 explicit denial, never a silent drop · C-7 revocation is monotonic — no second writer or peering link before meridian-3wh · C-8 nothing closes on green CI alone · C-9 scale by replica / function / tenant / traffic class, never by vocabulary · C-10 measure before optimizing; machinery for absent load is inventory.

And four refusals this program will be asked to reverse, named now so they are declined by citation rather than re-argued: "put Kafka behind the relay for durability" (R2) · "shard telemetry kinds onto their own relays" (R1) · "let the edge relay peer with the spine" (R4 / Law 2) · "cache grants at the bridge for speed" (R5 / C-5).

Parked — designed and sized, waiting on a named trigger

Parking is not rejection. Each of these is designed, sized and cross-linked, and ready the day a driver appears:

Day one — get the stack up

. ./bin/activate-hermit     # pinned toolchain — do this first, always
cp .env.example .env
./run.sh doctor            # toolchain, Docker, port conflicts, stale processes, env drift
./run.sh all               # services + relay + web in background, desktop in foreground
just ci                    # the full local gate — run before every PR

# The four guards that keep this page from rotting. Read them before trusting it.
just check-gauntlet        # every G-row's state against its evidence
just check-mips            # the MIP register against the client's generated registry
just check-kinds           # no vocabulary without an enforcement point
just check-architecture-map # the crate map, asserted in both directions

bd ready                   # what is actually available to work on
bd show meridian-tdq       # read any bead cited on this page

just bench                 # ALL seven bench groups, and it prints the profile with
                           #   them — CPU, cores, OS, traffic class, auth profile,
                           #   parsed/stored — so no figure can be lifted out bare
just bench --quick         # same groups, shorter sample
./perf/relay_bus_scaling.py --mode redis   # interest-scoping reduction

Prefer just bench over a bare cargo bench. The recipe exists precisely because cargo bench appeared in no recipe and no workflow while its numbers were being published (finding F062), and because a figure without its profile is an unsupported claim under rule ①.

Commit with git commit -s — the DCO check fails any PR with a commit missing a Signed-off-by trailer. run.sh wraps just and adds port deconfliction; it does not replace it.

11 Council record — review of this document

Convened per AGENTS.md § User Preferences. Decision under review: publish this page as the standing introduction for the incoming Program Development Team, framing Meridian as a modular replacement for a TBMQ central-broker deployment and as a scalable alternative for decentralized adoption. Each seat gives a position, one falsifiable objection, and what would change it.