1.9. Codebase Guide

1.9.1. Fleetmesh Codebase Architecture & Compartment Reference Guide

This document is the architectural audit and comprehensive reference guide for the Fleetmesh codebase. It covers:

  1. System Architecture & Repository Topology — how the submodules and subsystems assemble.

  2. Foundational Mechanisms — the cryptographic, wire, accounting, sync, storage, compute, and settlement mechanics.

  3. The 29 Compartments Guide — an exhaustive, declaration-level breakdown of all 29 compartments in exact tick order across the six architectural planes.

  4. Codebase Reference (Rest of the Tree) — module-by-module navigation for core/ (fleetmesh_core), meshnode/, meshctl/, schema/, strfry-bridge/, and fleetmesh.org/.

  5. Operational Conventions & Developer Invariants — the tripwires, persistence rules, strict parsing, and testing regimens.


1.9.1.1. 1. System Architecture & Repository Topology

Fleetmesh (fleetmesh.org) is a sovereign, verifiable edge compute, storage, and networking fabric. It is structured as an umbrella git repository containing specialized git submodules, maintaining a strict boundary between specification, reference implementations, daemon runtimes, and fleet orchestrators.

                                  +---------------------------------------+
                                  |              meshctl                  |
                                  |  Declarative Fleet Orchestrator (Rust)|
                                  +---------------------------------------+
                                                      |
                                             [meshnode-control/1]
                                        (Unix Domain Socket / IPC)
                                                      |
                                  +---------------------------------------+
                                  |              meshnode                 |
                                  |  Sovereign Node Daemon Engine (Python)|
                                  +---------------------------------------+
                                      |               |               |
                       +--------------+               |               +--------------+
                       |                              |                              |
               +---------------+              +---------------+              +---------------+
               | Wire Transport|              | Compute & ZK  |              | Storage & Sync|
               | - Iroh QUIC   |              | - WASM Sandboxes|            | - SQLite / PSQL|
               | - libp2p      |              | - ZK-CPU Proofs|            | - Blossom     |
               | - FIPS IPC    |              | - AI Inference|              | - Negentropy  |
               | - WebSocket   |              | - Cashu Escrows|             | - Event Stores|
               +---------------+              +---------------+              +---------------+
                                                      |
                                  +---------------------------------------+
                                  |         core (fleetmesh_core)         |
                                  | Standard Library Reference (Pure Py)  |
                                  +---------------------------------------+
                                                      |
                                  +---------------------------------------+
                                  |           schema & schemas/           |
                                  | Canonical JSON Schemas & Constants    |
                                  +---------------------------------------+

1.9.1.1.1. 1.1 The Workspace Layout

Path

Language

Role & Architectural Scope

[core/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core)

Python (Stdlib)

Pure reference implementation. No I/O, no network, no clock, zero non-stdlib dependencies. Verified directly by conformance vectors in vectors/.

[meshnode/](file:///Users/j/Code/fleetmesh/meshnode)

Python (cryptography, optional wasmtime)

Autonomous daemon node. Assembles 29 compartments, executes tick loops, operates multi-transport listeners, SQLite/PostgreSQL storage engines, and unix control socket.

[meshctl/](file:///Users/j/Code/fleetmesh/meshctl)

Rust

Declarative fleet orchestration binary. Hot-reconciles YAML manifests with running meshnode daemons via meshnode-control/1, compiles deployment targets (systemd, Quadlet, k8s, compose).

[schema/](file:///Users/j/Code/fleetmesh/schema)

JSON / YAML

Canonical protocol constants (constants.json), event kinds catalog (kinds.json), wire message catalog (messages.json), and JSON Schemas under schemas/. Source of the protocol version digest.

[fleetmesh.org/](file:///Users/j/Code/fleetmesh/fleetmesh.org)

Python, Shell, HTML

Conformance test runners (conform.py), tripwires (check-*.py), vector generators (gen-vectors.py), interop harnesses, and web documentation.

[strfry-bridge/](file:///Users/j/Code/fleetmesh/strfry-bridge)

Python

Write-policy plugin, bidirectional event sync bridge, and strfry config generator (fleetmesh_strfry) integrating strfry LMDB relays with Fleetmesh grants and policy rules.

[assets/](file:///Users/j/Code/fleetmesh/assets)

SVG / PNG

Canonical visual identity assets, logos, favicons, and architecture diagrams.

1.9.1.1.2. 1.2 The Six Architectural Planes

As enforced mechanically by [check-implementing.py](file:///Users/j/Code/fleetmesh/fleetmesh.org/scripts/check-implementing.py), every wire surface, compartment, config block, and database table resides in exactly one of six architectural planes:

  1. Identity & Keys: Cryptographic identities, W3C DID documents, descriptor mining/validation, addressable projections (NIP-66, NIP-85), and presence.

  2. Store & Persistence: Negentropy V1 set reconciliation, sync/1.0 sessions, retention sweeps, Blossom blob wire protocols, and blob replication.

  3. Peering & Trust: Bilateral peering admissions, grant negotiation (peering/1.0), token-bucket accounting (budget/1.0), strain ledgers, capacity backpressure, and complaint arbitration (complaint/1.0, standing/1.0).

  4. Transport & Overlays: Physical and overlay connectivity: WebSocket relay pools, LAN mDNS/DNS-TXT discovery, Iroh QUIC, libp2p, relay bridging, and FIPS-140-3 datagram IPC.

  5. Services & Compute: Gossip meshes (gossip/1.0), WASM compute sandboxes, Data Vending Machines (dvm), Cashu/Lightning payment settlement (settle), paid blob fetching (paidfetch), sidecar capability fronting, and Nsite static hosting.

  6. Operations & Lifecycle: Periodic task scheduling (scheduler), release inspection/revocation tracking (updates), and control socket dispatch (meshnode-control/1).


1.9.1.2. 2. Foundational Mechanisms

The core mechanisms are specified in schema/, verified in [core/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core), and implemented in [meshnode/](file:///Users/j/Code/fleetmesh/meshnode).

1.9.1.2.1. 2.1 Blinded Identifiers & Commitment Scheme

To prevent public relay traffic from leaking the peering topology graph, peer relationships use blinded identifiers:

  • Derivation: An ECDH shared secret $x$-coordinate is extracted between Node A and Node B. Identifiers are derived using HKDF-SHA256: $$\text{id} = \text{HKDF-SHA256}(ikm = \text{ECDH}_x(\text{mine}, \text{theirs}), salt = \text{“fleetmesh/grant/1”}, info = \text{“fleetmesh/grant-tag/1”}, len = 32)$$

  • Commitment Scheme: The commitment scheme uses sha256-blind/1 with fresh, random 32-byte blinding factors per commitment (defined in [constants.json](file:///Users/j/Code/fleetmesh/schema/constants.json)). Blinding factors are never reused or derived deterministically.

1.9.1.2.2. 2.2 Descriptors & Multi-Format Projections

Nodes broadcast their capabilities, classes, and endpoints via Kind 11801 / Kind 30801 events:

  • Node Classes: leaf (mobile/embedded, ephemeral, max 24h lifetime, no coverage claims), edge (standard peer, 30-day lifetime cap), and anchor (high-availability core node, 30-day lifetime cap).

  • Proof-of-Work: Nodes mine PoW bits into their descriptors (nonce tag) according to pow_bits configuration.

  • Strict Invariants: Operator pubkey must not equal node pubkey ($\text{operator} \neq \text{pubkey}$) to prevent shadow-node sybil evasion.

  • Projections:

    • NIP-66 Discovery: Kind 30166 projects the node’s relay interfaces to standard Nostr clients.

    • NIP-85 Relay Reputation: Kind 30385 projects peer quality scores derived from Kind 30802 dispute history.

    • W3C DID Document: Derived with did:nostr:<pubkey> as primary, alongside did:key and strict did:peer:2 aliases.

1.9.1.2.3. 2.3 DIDComm v2 over NIP-59 Ephemeral Gift-Wrap

All node-to-node control messages (peering/1.0, sync/1.0, budget/1.0, mediation/2.0) travel through encrypted envelopes:

  • Inner Payload: Standard DIDComm v2 message with canonical CBOR serialization where byte-exact parity is required.

  • Authenticated Encryption: ECDH-1PU for sender-authenticated sessions, and ECDH-ES for anonymous ingress.

  • Carrier: Encapsulated into Nostr Kind 1059 / Kind 21059 gift wraps using ephemeral secp256k1 keypairs and NIP-44 v2 padding, shielding message routing and metadata from public relays.

1.9.1.2.4. 2.4 Bilateral Peering & Capacity Grants

Peering is bilateral and negotiated through explicit contracts:

  • Proposal & Negotiation: A node proposes peering (peering/1.0). Peers negotiate acceptable protocols using shared_protocols intersection.

  • Dual Grants: Upon agreement, each node issues a Kind 30801 grant ciphertext to the other. Grants define strict quotas:

    • max_events: Event count capacity per window.

    • max_bytes: Raw byte capacity per window.

    • sample_window: Epoch duration in seconds.

    • rate_limit: Maximum ingress frequency.

  • Declines: Explicit decline codes (BAD_DESCRIPTOR, UNSUPPORTED_TRANSPORTS, NO_CAPACITY, POLICY_REFUSED, PEER_DECLINED) are returned rather than dropping connections silently.

1.9.1.2.5. 2.5 Token-Bucket Metering, Receipt Chains & AIMD Accounting

Accounting verifies that peer consumption respects negotiated grants:

  • Interval Windows: Time is sliced into fixed windows (epochs).

  • Hash-Chained Receipts: Ingressing nodes return periodic receipts. Receipts form a monotonic cryptographic hash chain: $$r_0 = \text{seed}, \quad r_i = \text{SHA-256}(r_{i-1} \parallel \text{counters}_i)$$ The issuer stores only the 32-byte head to hold a peer accountable for historical claims.

  • Partition vs. Misreport Classification:

    • $\text{Measured Egress} > 0$ and $\text{Receipts Missing} \implies$ S2 Misreport (peer moved data without accounting).

    • $\text{Measured Egress} = 0$ and $\text{Receipts Missing} \implies$ Graceful Partition (peer silent, no penalty, no report).

  • AIMD Adaptation: Healthy windows trigger additive increase in grant limits; receipt failures or over-budget events trigger multiplicative decrease.

1.9.1.2.6. 2.6 State Reconciliation via NIP-77 Negentropy V1

Data synchronization is handled by set reconciliation over range fingerprints:

  • Storage Dual-Engine: Abstracted via [Dialect](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/dialect.py) into [SqliteDialect](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/dialect.py) and [PostgresDialect](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/postgres.py).

  • Framing: Uses NIP-77 Negentropy V1 binary framing (NEG-OPEN, NEG-MSG, NEG-CLOSE).

  • Provenance & Dedup: [EventStoreProtocol](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/interfaces.py) tracks origin metadata (note_origin, origin_of) to prevent replication echo loops.

1.9.1.2.7. 2.7 Content-Addressed Blobs & Paid Fetch Gating

  • Blossom BUD-01..04 Integration: HTTP endpoints for /upload, /list/, /cid/, and /mirror.

  • Coverage Claims: Nodes assert blob retention using Kind 30803 coverage claims.

  • HTTP 402 Paid Fetch: Unauthenticated blob downloads are intercepted with HTTP 402 Payment Required tokens backed by Cashu e-cash (NUT-00..NUT-24) or Lightning invoices.

1.9.1.2.8. 2.8 Complaint Ladder & Dispute Arbitration

  • Severity Tiers:

    • S0: Silent window (no billable traffic).

    • S1: Minor discrepancy (counter mismatch below threshold).

    • S2: Severe misreport (traffic observed without valid receipts).

    • S3: Provable fraud (invalid cryptographic signature, split-brain grant claims).

    • S4: Terminal peer violation.

  • Notice-First Protocol: complaint/1.0 requires delivering a private dispute notice before public publication. If unacknowledged or uncorrected, a public Kind 30802 complaint is broadcast with cryptographic evidence.

1.9.1.2.9. 2.9 Verifiable Compute & Execution Engines

Fleetmesh provides a multi-runtime verified compute fabric (detailed in [verified-compute-methods.md](file:///Users/j/Code/fleetmesh/meshnode/docs/verified-compute-methods.md)):

  • WASM / WASI Sandbox (fleetmesh-wasi-v1): Computations run inside [WasmExecutor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/wasm.py) with strictly metered fuel allocations, virtual epoch clocks, and deterministic memory limits.

  • Zero-Knowledge Groth16 Verifier: Cryptographically validates proofs over the BN254 elliptic curve via [ZkGroth16Executor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/zk.py#L30) with native pairing acceleration hooks.

  • zkVM STARK-to-Groth16 Verifier: Receipt verifier in [ZkVmExecutor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/zk.py#L275) for RISC Zero and Succinct SP1 zkVM receipts binding journal hashes to image IDs under Mode proof.

  • Off-Chain ZK Prover Service: Driver in [ZkProverExecutor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/zk.py#L425) delegating witness proving over the mesh order book.

  • Bacalhau Compute-Over-Data: Batch container engine [BacalhauExecutor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/nondet.py#L198) with Blossom CAS input mounting and output packaging ([BlossomMountBridge](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/bacalhau.py#L304)), 5-state progress tracking, and cooperative cancellation.

  • AI / LLM Inference: Direct HTTP connector [LlmExecutor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/nondet.py#L26) to vLLM, Ollama, and llama-server, with Draft 2020-12 schema bounds validation and ChaCha20Poly1305 per-frame encrypted streaming over Iroh QUIC.

  • Autonomous Agents: Multi-step ReAct reasoning harness [AgentExecutor](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/executors/agent.py#L395) with AST-safe calculator, regex, SHA-256, Blossom blob fetching, recursive child Kind 30810 Asks, and honesty gate protection.

  • NIP-90 DVM Gateway: Ingress compartment [DVMGateway](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/dvm/gateway.py) translating Kinds 5000–5999 into canonical mesh jobs, settling via live Lightning HTLC hold invoices or order-book delegation.

1.9.1.2.10. 2.10 Multi-Transport Ladder

Transports are resolved via an ordered fallback ladder:

  1. FIPS-140-3 Datagram: Local hardened IPC via SCM_RIGHTS datagram socket (transport:fips).

  2. Iroh QUIC: Fast peer-to-peer UDP connections with DERP relay fallback (transport:iroh).

  3. libp2p: Standard peer-to-peer transport (transport:libp2p).

  4. Nostr WebSocket Relay: Asynchronous gift-wrapped envelopes over public relays (transport:nostr).

  5. HTTPS / DIDComm: Direct HTTP endpoints (http:/didcomm).


1.9.1.3. 3. The 29 Compartments Guide

The [NodeApp](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/core.py) executes compartments in a deterministic, declared tick order. The ordering is intentional: low-level transport links tick first, followed by trust and metering, then synchronization, publication, compute, and lastly operations.

Below is the exhaustive guide to all 29 compartments.

       +---------------------------------------------------------------------------------+
       |                              TICK ORDER PIPELINE                                |
       +---------------------------------------------------------------------------------+
[01] link ------------> [02] trust ---------> [03] strain ------> [04] peering --------->
[05] budget ----------> [06] capacity ------> [07] sync --------> [08] reporter -------->
[09] discovery -------> [10] announce ------> [11] lan ---------> [12] p2p (opt) ------->
[13] gossip (opt) ----> [14] presence ------> [15] linked ------> [16] retention ------->
[17] scheduler -------> [18] compute (opt) -> [19] compute_wire -> [20] bridge (opt) ---->
[21] settle ----------> [22] mediation -----> [23] blob_wire ---> [24] blob_replication ->
[25] paidfetch -------> [26] sidecars ------> [27] dvm (opt) ---> [28] nsite (opt) ------>
[29] updates (opt)


1.9.1.3.2. [02] trust — Operator Trust Policy & Tiers

  • Plane: Peering

  • Class: [fleetmesh_node.planes.peering.trust.compartment:Trust](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/peering/trust/compartment.py)

  • Role: Enforces the operator’s trust tier policy (anchor, partner, general, untrusted, blocked). Trust tiers set the maximum ceilings for bilateral grants and cannot be raised by wire negotiation.

  • Declarations:

    • requires: ()

    • reads: ('trust', 'policy') | live: ('trust', 'policy')

  • Commands: show, set, clear, tiers.

  • Channels: Logs tier changes, overrides, and admission bans.

  • Metrics: trust_tier_evaluations_total.

  • Stores: overrides, local trust assignments.


1.9.1.3.3. [03] strain — Physical Ingress/Egress Strain Ledger

  • Plane: Peering

  • Class: [fleetmesh_node.planes.peering.strain.compartment:StrainLedger](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/peering/strain/compartment.py)

  • Role: Measures raw physical traffic volume (bytes, messages, reconnection frequency) across all network interfaces, providing raw evidence of strain before protocol evaluation.

  • Declarations:

    • requires: ()

    • reads: () | live: ()

  • Commands: show (reports directional egress/ingress metrics and reserve requirements).

  • Channels: strain_warning, strain_critical.

  • Metrics: strain_ingress_bytes, strain_egress_bytes.

  • Stores: Directional traffic sliding-window ring buffers.


1.9.1.3.4. [04] peering — Bilateral Peering & Handshake Protocol

  • Plane: Peering

  • Class: [fleetmesh_node.planes.peering.peering.core:Peering](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/peering/peering/core.py)

  • Role: Runs the peering/1.0 wire protocol. Ingests peering requests, verifies descriptors, checks operator policies, matches shared capabilities, and issues bilateral Kind 30801 grant ciphertexts.

  • Declarations:

    • requires: ('trust', 'strain')

    • reads: ('peers', 'policy', 'endpoints') | live: ('peers',)

  • Commands: peer, unpeer, propose, decline, show.

  • Channels: peer_admitted, peer_declined, peer_terminated.

  • Metrics: peering_proposals_total, peering_admissions_total, peering_declines_total.

  • Stores: Active peering state, pending handshakes, cached peer descriptors.


1.9.1.3.5. [05] budget — Token-Bucket Metering & AIMD Accounting Loop

  • Plane: Peering

  • Class: [fleetmesh_node.planes.peering.budget.core:Budget](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/peering/budget/core.py)

  • Role: Executes the budget/1.0 accounting loop. Processes hash-chained receipts, verifies counter monotonicity, handles window rollovers, evaluates compliance, and adjusts grant limits using AIMD.

  • Declarations:

    • requires: ('peering',)

    • reads: ('policy',) | live: ()

  • Commands: show, windows, receipts, reprice, amend.

  • Channels: window_closed, receipt_refused, aimd_scaled.

  • Metrics: budget_receipts_verified, budget_windows_closed, budget_overages_total.

  • Stores: grants.sqlite backing, window history, active hash chain heads.


1.9.1.3.6. [06] capacity — Local Resource Ceiling & Backpressure Shedder

  • Plane: Peering

  • Class: [fleetmesh_node.planes.peering.capacity.compartment:Capacity](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/peering/capacity/compartment.py)

  • Role: Monitors system resources (disk utilization, memory, CPU load). When thresholds are exceeded, applies backpressure by shedding low-tier peer traffic and narrowing coverage claims.

  • Declarations:

    • requires: ('budget',)

    • reads: ('capacity',) | live: ('capacity',)

  • Commands: show, shed, restore.

  • Channels: capacity_shedding_started, capacity_normal.

  • Metrics: capacity_utilization_ratio, capacity_shed_events_total.

  • Stores: Resource utilization samples, shed-tier rosters.


1.9.1.3.7. [07] sync — Negentropy V1 State Synchronization

  • Plane: Store

  • Class: [fleetmesh_node.planes.store.sync.core:SyncPeer](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/store/sync/core.py)

  • Role: Implements the sync/1.0 state sync protocol. Coordinates Negentropy V1 reconciliation sessions across shards, parses delivery envelopes, and pulls Nostr events into local storage.

  • Declarations:

    • requires: ('budget', 'capacity')

    • reads: ('storage', 'coverage', 'peers') | live: ('peers',)

  • Commands: pull, sync, sessions, coverage.

  • Channels: sync_session_opened, sync_events_transferred, sync_failed.

  • Metrics: sync_events_pulled, sync_bytes_transferred, sync_sessions_active.

  • Stores: Active session state machines, replication cursors.


1.9.1.3.8. [08] reporter — Dispute Arbitration & Kind 30802 Reporting

  • Plane: Peering

  • Class: [fleetmesh_node.planes.peering.reporter.core:Reporter](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/peering/reporter/core.py)

  • Role: Oversees the complaint ladder (complaint/1.0, standing/1.0). Emits private dispute notices for minor infractions, publishes public Kind 30802 dispute claims for fraud, and projects NIP-85 scores.

  • Declarations:

    • requires: ('budget',)

    • reads: ('projection',) | live: ()

  • Commands: reports, notice, withdraw, standing.

  • Channels: dispute_noticed, dispute_published, dispute_withdrawn.

  • Metrics: reporter_complaints_issued, reporter_notices_sent.

  • Stores: Outbound and inbound complaint registries, dispute evidence logs.


1.9.1.3.9. [09] discovery — NIP-66 & Shard Coverage Publisher

  • Plane: Identity

  • Class: [fleetmesh_node.planes.identity.discovery.compartment:Discovery](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/identity/discovery/compartment.py)

  • Role: Publishes Kind 30166 events (NIP-66 discovery) advertising node capabilities and Kind 30803 coverage claims defining data shards retained by this node.

  • Declarations:

    • requires: ('capacity',)

    • reads: ('coverage', 'class') | live: ('coverage',)

  • Commands: show, publish_discovery, publish_coverage.

  • Channels: coverage_narrowed, coverage_downgraded.

  • Metrics: discovery_events_published, coverage_claims_published.

  • Stores: Current published descriptor tags, active coverage intervals.


1.9.1.3.10. [10] announce — Node Descriptor Miner & Heartbeat

  • Plane: Identity

  • Class: [fleetmesh_node.planes.identity.announce.compartment:Announce](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/identity/announce/compartment.py)

  • Role: Mines Proof-of-Work nonces for the node’s Kind 11801 descriptor and broadcasts periodic Kind 21801 heartbeats to keep presence alive across the mesh.

  • Declarations:

    • requires: ()

    • reads: ('name', 'class', 'operator', 'capabilities', 'endpoints', 'pow_bits', 'heartbeat') | live: ()

  • Commands: mine, publish, heartbeat.

  • Channels: descriptor_mined, heartbeat_broadcast.

  • Metrics: announce_pow_iterations, announce_heartbeats_sent.

  • Stores: Signed descriptor records, nonce state.


1.9.1.3.11. [11] lan — Local Area Network mDNS Discovery

  • Plane: Transport

  • Class: [fleetmesh_node.planes.transport.lan.compartment:Lan](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/transport/lan/compartment.py)

  • Role: Discovers local Fleetmesh nodes on the physical network using multicast DNS (_fleetmesh._tcp.local) and DNS-TXT records, establishing low-latency LAN routes.

  • Declarations:

    • requires: ()

    • reads: ('lan', 'endpoints') | live: ('lan',)

  • Commands: discover, peers.

  • Channels: lan_peer_discovered, lan_peer_lost.

  • Metrics: lan_peers_active, lan_multicast_packets_sent.

  • Stores: Local network peer routing table.


1.9.1.3.12. [12] p2p [Optional] — Direct Peer-to-Peer Transport (Iroh / libp2p)

  • Plane: Transport

  • Class: [fleetmesh_node.planes.transport.p2p.compartment:P2PTransport](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/transport/p2p/compartment.py)

  • Role: Manages direct peer-to-peer transport connections (Iroh QUIC streams and libp2p sessions) for high-bandwidth data transfers, bypassing relay hops.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'p2p'

    • reads: ('p2p', 'transport') | live: ('p2p',)

  • Commands: show, dial, listen, routes.

  • Channels: p2p_session_opened, p2p_connection_dropped.

  • Metrics: p2p_bytes_received, p2p_bytes_sent, p2p_active_streams.

  • Stores: Direct P2P stream state, ticket store.


1.9.1.3.13. [13] gossip [Optional] — Topic-Based PubSub Gossip Mesh

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.gossip.core:GossipMesh](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/gossip/core.py)

  • Role: Implements gossip/1.0. Provides decentralized topic-based publish/subscribe overlay with graft/prune mesh topology and flood publication.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'gossip'

    • reads: ('gossip',) | live: ()

  • Commands: show, topics, create, admit, leave, publish.

  • Channels: event_published, event_delivered, graft_established, prune_sent.

  • Metrics: gossip_events_published, gossip_events_delivered, gossip_peers_grafted.

  • Stores: members, peers, grafted_at, mcache, totals, published, delivered.


1.9.1.3.14. [14] presence — Mesh Peer Presence & Retiring Tracker

  • Plane: Identity

  • Class: [fleetmesh_node.planes.identity.presence.compartment:Presence](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/identity/presence/compartment.py)

  • Role: Ingests Kind 21801 peer heartbeats and Kind 11802 retirement announcements. Updates routing availability and triggers graceful handovers when peers shut down.

  • Declarations:

    • requires: ('budget', 'strain')

    • reads: ('heartbeat', 'class', 'telemetry') | live: ()

  • Commands: show.

  • Channels: peer_retiring, inbound_event.

  • Metrics: presence_peers_retiring, presence_events_inbound.

  • Stores: _seen (timestamp map), _retiring (graceful shutdown register).


1.9.1.3.15. [15] linked — Linked Data & Schema.org Semantic Face

  • Plane: Identity

  • Class: [fleetmesh_node.planes.identity.linked.compartment:LinkedFace](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/identity/linked/compartment.py)

  • Role: Exposes semantic metadata over HTTP (JSON-LD, Schema.org) describing node identity, service endpoints, and verifiable credentials. Mounted on the relay HTTP fallthrough.

  • Declarations:

    • requires: ('presence',)

    • reads: () | live: ()

  • Commands: show, service, standing, blob.

  • Channels: doc_served.

  • Metrics: linked_docs_served.

  • Stores: served document cache.


1.9.1.3.16. [16] retention — Event Store Sweeper & Retention Governor

  • Plane: Store

  • Class: [fleetmesh_node.planes.store.retention.compartment:Retention](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/store/retention/compartment.py)

  • Role: Periodically sweeps the event database, enforcing per-kind TTL policies and capacity bounds while protecting asserted coverage shards from accidental pruning.

  • Declarations:

    • requires: ()

    • reads: ('retention', 'coverage') | live: ()

  • Commands: show, sweep.

  • Channels: events_evicted, eviction_refused.

  • Metrics: retention_events_evicted, retention_evictions_refused.

  • Stores: evicted counts by kind.


1.9.1.3.17. [17] scheduler — Sync Operations & Interval Scheduler

  • Plane: Operations

  • Class: [fleetmesh_node.planes.operations.scheduler.compartment:Scheduler](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/operations/scheduler/compartment.py)

  • Role: Coordinates periodic background tasks: scheduling shard pulls against peered nodes, staggering pull cadences, and managing throttle holds.

  • Declarations:

    • requires: ('budget', 'capacity', 'strain')

    • reads: ('peers',) | live: ('peers',)

  • Commands: show.

  • Channels: pull_scheduled, pull_refused.

  • Metrics: scheduler_pulls_scheduled, scheduler_pulls_refused.

  • Stores: _last_pull, _declined, _throttled, _shed.


1.9.1.3.18. [18] compute [Optional] — Compute Market & Job Execution Engine

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.compute.compartment:Compute](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute/compartment.py)

  • Role: Manages local compute offers and asks (compute/1.0). Dispatches tasks to the WASM sandbox runtime (wasmtime), meters fuel consumed, and maintains compute order books.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'compute'

    • reads: ('compute', 'executors', 'relays') | live: ()

  • Commands: show, offer, ask, run, receipts, book, match, index_offer, index_ask, models, stream.

  • Channels: job_executed, offer_published, ask_published.

  • Metrics: compute_jobs_executed, compute_offers_published, compute_asks_published.

  • Stores: offers, asks, order_book_offers, order_book_asks, receipts_held.


1.9.1.3.19. [19] compute_wire [Optional] — Compute Protocol Transport & Quotes

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.compute_wire.compartment:ComputeWire](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/compute_wire/compartment.py)

  • Role: Implements the wire session transport for compute/1.0 and compute/1.1. Handles RFQs (Request For Quotes), quote signatures, session negotiation, and compute dispute claims.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'compute'

    • reads: ('compute', 'relays', 'transport') | live: ()

  • Commands: sessions, disputes.

  • Channels: refute_received, quote_received.

  • Metrics: compute_wire_disputes, compute_wire_quotes.

  • Stores: disputes registry.


1.9.1.3.20. [20] bridge [Optional] — Universal Nostr Relay Bridge

  • Plane: Transport

  • Class: [fleetmesh_node.planes.transport.bridge.compartment:RelayBridge](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/transport/bridge/compartment.py)

  • Role: Connects external third-party Nostr relays to the Fleetmesh fabric. Ingests events matching configured filters, queues them for ingress validation, and publishes local events out.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'bridge'

    • reads: ('bridge', 'relays') | live: ('bridge',)

  • Commands: show, publish, sync, reconcile, add_relay, remove_relay, cursor, cursors.

  • Channels: ingress_stored, ingress_refused, egress_sent.

  • Metrics: bridge_ingress_stored, bridge_ingress_refused, bridge_egress_sent.

  • Stores: egress_queue.


1.9.1.3.21. [21] settle — Cashu & Lightning Micropayment Rail

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.settle.compartment:Settlement](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/settle/compartment.py)

  • Role: Handles economic settlements across the node. Supports Cashu e-cash (NUT-00..NUT-24), NIP-61 Nutzaps, NIP-47 Nostr Wallet Connect (NWC), and Lightning hold-invoices for compute escrows and paid fetch.

  • Declarations:

    • requires: ()

    • reads: ('settlement', 'compute') | live: ()

  • Commands: show, create, hold, settle, reconcile, stream_pay, cancel, nutzap, expand_grant, nwc_pay, cashu_swap, cashu_melt.

  • Channels: escrow_created, escrow_held, escrow_settled.

  • Metrics: settlement_escrows_created, settlement_escrows_held, settlement_escrows_settled.

  • Stores: escrows active table.


1.9.1.3.22. [22] mediation — DIDComm Routing & Ingress Mediation

  • Plane: Transport

  • Class: [fleetmesh_node.planes.transport.mediation.compartment:Mediation](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/transport/mediation/compartment.py)

  • Role: Operates DIDComm routing/2.0 and coordinate-mediation/2.0. Allows edge nodes to act as relay mediators for mobile leaves, storing forwarded messages until queried via pickup/2.0.

  • Declarations:

    • requires: ()

    • reads: ('mediation', 'endpoints', 'relays') | live: ()

  • Commands: show, grant, forward, pickup.

  • Channels: message_forwarded, forward_refused, mediation_granted.

  • Metrics: mediation_messages_forwarded, mediation_forward_refused, mediation_admissions_granted.

  • Stores: handled messages register.


1.9.1.3.23. [23] blob_wire — Blossom Blob Transfer Wire Protocol

  • Plane: Store

  • Class: [fleetmesh_node.planes.store.blob_wire.core:BlobWire](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/store/blob_wire/core.py)

  • Role: Answers blob/1.0 wire queries (have, pull, offer). Directs chunked binary transfers between nodes, validating hashes against SHA-256 / CID identifiers.

  • Declarations:

    • requires: ()

    • reads: ('blob_wire',) | live: ()

  • Commands: held, drop.

  • Channels: blob_served, offer_refused.

  • Metrics: blob_wire_chunks_served, blob_wire_offers_refused.

  • Stores: _inflight transfer table.


1.9.1.3.24. [24] blob_replication — Blob Pinned Replicas & Mirroring

  • Plane: Store

  • Class: [fleetmesh_node.planes.store.blob_replication.compartment:Replication](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/store/blob_replication/compartment.py)

  • Role: Coordinates asynchronous replication of pinned blobs across peer clusters. Enforces redundancy policies and verifies blob integrity.

  • Declarations:

    • requires: ('blob_wire',)

    • reads: ('blob_replication', 'endpoints') | live: ()

  • Commands: pin, unpin, status, run, verify.

  • Channels: blob_replicated, replication_failed.

  • Metrics: blob_replication_replicated, blob_replication_failed.

  • Stores: replicas manifest and target tracking.


1.9.1.3.25. [25] paidfetch — HTTP 402 Paid Blob Fetch Pricing

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.paidfetch.compartment:PaidFetch](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/paidfetch/compartment.py)

  • Role: Consulted by BlossomServer to price blob downloads. Issues HTTP 402 tokens, defines price schedules per megabyte, and validates Cashu/Lightning payment receipts before data egress.

  • Declarations:

    • requires: ()

    • reads: ('fetch_pricing',) | live: ()

  • Commands: price_set, price_get, price_clear, prices, rails, wallet, sweep, grasp_price_set, grasp_price_get.

  • Channels: fetch_paid, payment_refused.

  • Metrics: paidfetch_fetches_paid, paidfetch_payments_refused.

  • Stores: receipts redemption records.


1.9.1.3.26. [26] sidecars — External Subprocess Probe & Capability Fronting

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.sidecars.compartment:Sidecars](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/sidecars/compartment.py)

  • Role: Manages and probes external sidecars (GRASP for NIP-34 git repos, ncontainer for OCI container registries, magpie for media caching). Publishes capability tags (c) in descriptors only when sidecar health probes succeed.

  • Declarations:

    • requires: ()

    • reads: ('sidecars', 'grasp', 'ncontainer', 'magpie') | live: ('grasp', 'ncontainer', 'magpie')

  • Commands: sidecars, sidecar_test.

  • Channels: sidecar_verified, sidecar_failed.

  • Metrics: sidecars_verified_total, sidecars_failed_total.

  • Stores: probes health results.


1.9.1.3.27. [27] dvm [Optional] — NIP-90 Data Vending Machine Gateway

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.dvm.gateway:DVMGateway](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/dvm/gateway.py)

  • Role: Ingests NIP-90 job requests (kinds 5000-5999), delegates tasks to the compute compartment, pays or requests payment, and returns results via kinds 6000-6999 and 7000.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'dvm'

    • reads: ('compute', 'dvm') | live: ('dvm',)

  • Commands: show, delegate, process.

  • Channels: job_received, job_succeeded, job_failed.

  • Metrics: dvm_jobs_received, dvm_jobs_succeeded, dvm_jobs_failed.

  • Stores: recent_jobs.


1.9.1.3.28. [28] nsite [Optional] — Decentralized Web Hosting Face

  • Plane: Services

  • Class: [fleetmesh_node.planes.services.nsite.compartment:NsiteGateway](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/services/nsite/compartment.py)

  • Role: Serves decentralized static websites over HTTP directly from Nostr Blossom blobs. Resolves NIP-05 / domain manifests, handles routing fallbacks, and verifies site signatures.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'nsite'

    • reads: ('nsite', 'relays') | live: ('nsite',)

  • Commands: domains, sites, verify, forget, publish.

  • Channels: site_served, site_published, domain_verified.

  • Metrics: nsite_requests_served, nsite_sites_published, nsite_domains_verified.

  • Stores: recent_requests.


1.9.1.3.29. [29] updates [Optional] — Release Channel & Revocation Overseer

  • Plane: Operations

  • Class: [fleetmesh_node.planes.operations.updates.core:Updates](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/operations/updates/core.py)

  • Role: Ticks last in the loop. Inspects signed release announcements (Kind 9900) and revocation notices (Kind 9901) against operator-pinned release keys, reporting available upgrades or revoked builds.

  • Declarations:

    • requires: () | optional: True | enabled_by: 'updates'

    • reads: ('updates', 'relays') | live: ('updates',)

  • Commands: check, show, ack.

  • Channels: release.available, release.revoked.

  • Metrics: release_available, release_revoked, updates_check.

  • Stores: releases database.


1.9.1.4. 4. Codebase Reference: The Rest of the Tree

Beyond the 29 compartments, the Fleetmesh codebase comprises foundational modules and standalone packages.

1.9.1.4.1. 4.1 core/ (fleetmesh_core) Reference Library

The reference is pure Python (standard library only, zero external dependencies). It defines all data shapes, cryptographic primitives, and normative protocol logic.

  • [fleetmesh_core/crypto/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/):

    • [keys.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/keys.py): Secp256k1, Ed25519, and X25519 key generation and Multikey (z6Mk...) encoding/decoding.

    • [crypto.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/crypto.py): BIP-340 Schnorr signatures, ECDH shared secret derivation, HKDF extract/expand, commitments.

    • [curve.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/curve.py): Pure-Python Weierstrass curve point arithmetic.

    • [nip44.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/nip44.py): NIP-44 v2 encryption, padding, and MAC verification.

    • [giftwrap.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/giftwrap.py): NIP-59 / Kind 1059 / Kind 21059 gift wrapping and unwrapping.

    • [bech32.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/bech32.py): Nostr entity encoding (npub, nsec, note).

    • [zk.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/zk.py): BN254 curve arithmetic and Groth16 zero-knowledge proof verification.

    • [http_signatures.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/http_signatures.py): RFC 9421 HTTP Message Signatures and Digest headers for ActivityPub federation.

    • [ssb.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/crypto/ssb.py): Secure Scuttlebutt Secret Handshake (SHS), Box Stream framing, and V1 feed verification.

  • [fleetmesh_core/identity/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/):

    • [identity.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/identity.py): Blinded tags, descriptor validation, PoW mining, shared_protocols negotiation.

    • [did.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/did.py): W3C DID document formatting, did:nostr, did:key, strict did:peer:2.

    • [atproto.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/atproto.py): ATProto did:plc genesis operation signing, did:web resolution, and K-256 ECDSA verification.

    • [didcomm.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/didcomm.py): DIDComm envelope encryption, packaging, and header validation.

    • [cid.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/cid.py): Content ID (IPFS / Blossom CIDv1) hashing and verification.

    • [iroh_ticket.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/iroh_ticket.py): Iroh NodeTicket binary serialization and base32 encoding.

    • [origin.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/origin.py): Namespace origin checking.

    • [relaylist.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/relaylist.py): NIP-65 relay list handling.

  • [fleetmesh_core/peering/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/):

    • [peering.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/peering.py): Peering handshake state machine, proposal parsing, grant generation.

    • [projection.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/projection.py): Derivation of Kind 30385 (NIP-85) relay reputation projections.

    • [coverage.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/coverage.py): Kind 30803 coverage claim validation and handover links.

    • [reports.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/reports.py): Kind 30802 dispute event admissibility.

    • [complaint.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/complaint.py): complaint/1.0 notice framing and dispute escalation.

    • [release.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/release.py): Kind 9900/9901 signed package release and revocation verification.

    • [badpeer.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/peering/badpeer.py): Synthetic adversarial test peer exhibiting all protocol offences.

  • [fleetmesh_core/accounting/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/):

    • [accounting.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/accounting.py): Monotonic receipt hash chains and counter assertions.

    • [window.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/window.py): Epoch window rollover, claim evaluation, and severity ladder.

    • [capacity.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/capacity.py): Capacity bounds and shed calculations.

    • [strain.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/strain.py): Ingress/egress strain formulas.

    • [standing.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/standing.py): standing/1.0 ask/tell gossip ledger.

    • [cashu.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/cashu.py): BDHKE blind signature arithmetic, Cashu tokens (NUT-00..24).

    • [paidfetch.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/paidfetch.py): HTTP 402 token issuance and verification.

    • [market.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/accounting/market.py): Compute market ask/offer commitments and receipt verification.

  • [fleetmesh_core/storage/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/):

    • [store.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/store.py): Abstract event store and filter matching.

    • [store_postgres.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/store_postgres.py): PostgreSQL event store reference implementation.

    • [negentropy.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/negentropy.py): NIP-77 V1 binary set reconciliation.

    • [sync.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/sync.py): Delivery envelope parsing and sync session verification.

    • [replication.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/replication.py): Range fingerprinting and replica tracking.

    • [blossom_auth.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/blossom_auth.py): Blossom BUD-01/BUD-04 authorization event validation.

    • [linked_data.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/linked_data.py): JSON-LD / Schema.org document projection.

    • [car.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/car.py): Content Addressable aRchives (CAR v1) encoder and decoder.

    • [mst.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/storage/mst.py): ATProto deterministic Merkle Search Tree (MST) implementation.

  • [fleetmesh_core/services/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/):

    • [compute.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/compute.py), [dvm.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/dvm.py), [gossip.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/gossip.py), [mediation.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/mediation.py), [nsite.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/nsite.py), [nwc.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/nwc.py), [settlement.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/settlement.py), [sidecar.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/sidecar.py), [ucan.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/services/ucan.py).

  • [fleetmesh_core/wire/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/):

    • [interfaces.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/interfaces.py): Normative TypedDict and Protocol contracts shared with meshnode.

    • [wire_types.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/wire_types.py): Core data models (GrantLimits, GrantPayload, DeliveryEnvelope).

    • [cbor.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/cbor.py): Canonical deterministic CBOR / DAG-CBOR encoder/decoder (including Tag 42 CID links).

    • [p2panda.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/p2panda.py): p2panda Ed25519 + CBOR bamboo-style append-only log operations and Blake3/SHA-256 log validation.

    • [schema_files.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/schema_files.py): Cached loader for constants.json, kinds.json, messages.json, and DIGEST.

    • [validate.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/wire/validate.py): Strict wire parser validations.

  • [fleetmesh_core/conformance/](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/conformance/):

    • [runner.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/conformance/runner.py): Reference JSON-lines conformance harness responder (python3 -m fleetmesh_core.conformance).

1.9.1.4.2. 4.2 meshnode/ Daemon Subsystems

  • [fleetmesh_node/app/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/):

    • [core.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/core.py): The main runtime daemon (NodeApp). Manages life cycle, tick loop execution across MANIFEST, and assembly.

    • [socket.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/socket.py): Listens on /var/lib/meshnode/control.sock, serving the meshnode-control/1 IPC protocol.

    • [router.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/router.py): Routes inbound wire messages and control requests to registered handlers.

    • [views.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/views.py): Queries local node status, active peer rosters, and diagnostics.

  • [fleetmesh_node/storage/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/):

    • [base.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/base.py): Base transactional store with file lease locking.

    • [dialect.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/dialect.py): Dialect abstraction protocol separating SQLite and PostgreSQL SQL syntax.

    • [postgres.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/postgres.py): PostgreSQL enterprise storage engine implementation.

    • [grants.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/grants.py): Persistent store for bilateral grants and epoch history.

    • [accounts.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/storage/accounts.py): Persistent store for accounting ledgers.

  • [fleetmesh_node/transport/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/):

    • [host.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/host.py): Shared HTTP/WebSocket ingress multiplexer (ProtocolHost) for pluggable protocol packages.

    • [router.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/router.py) & [ladder.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/ladder.py): Multi-rung transport router and circuit-breaker ladder state machine.

    • [relay_rung/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/relay_rung/), [iroh_rung/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/iroh_rung/), [fips_rung/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/fips_rung/): Built-in transport rung implementations.

    • [mdns.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/mdns.py) & [dnstxt.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/transport/dnstxt.py): LAN multicast peer beacon and DNS TXT discovery.

  • [fleetmesh_node/protocols/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/):

    • [base.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/base.py) & [registry.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/registry.py): ProtocolPackage interface and dynamic protocol loader.

    • [nostr/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/nostr/): Embedded Nostr relay server (relayserver.py), client (client.py), event store (eventstore.py), and Blossom server (blossom.py, blobstore.py).

    • [atproto/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/atproto/): ATProto PDS XRPC server, MST repository store, and firehose (subscribeRepos) broadcaster.

    • [activitypub/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/activitypub/): ActivityPub Actor, WebFinger, and RFC 9421 signed Inbox/Outbox federation package.

    • [ssb/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/ssb/): Secure Scuttlebutt SHS + Box Stream + MuxRPC TCP server, feed store, and transport rung.

    • [p2panda/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/p2panda/): p2panda append-only bamboo log store, HTTP /p2panda/* sync endpoints, and Rank 15 transport rung.

    • [rhio/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/protocols/rhio/): Rhio NATS JetStream + S3/Blossom cluster replicator package, sidecar bridge, and Rank 12 transport rung.

  • [fleetmesh_node/channels/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/channels/):

    • [bus.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/channels/bus.py): In-memory pubsub NodeEventBus with tap listeners and subscribers.

    • [journal.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/channels/journal.py): Operator-facing journal logging formatted lines and short summaries.

  • [fleetmesh_node/commands/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/commands/):

    • Subcommand dispatchers for CLI verbs: core.py, peering.py, sync.py, compute_cmds.py, gossip_cmds.py, transport_cmds.py, etc.

  • [fleetmesh_node/config/](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/config/):

    • Strict parameter validation (parameter.py), block parsers (node.py, compartments.py), and hot-reload diffing.

1.9.1.4.3. 4.3 meshctl/ Declarative Fleet Orchestrator (Rust)

Written in Rust, meshctl provides single-binary fleet management:

  • [src/main.rs](file:///Users/j/Code/fleetmesh/meshctl/src/main.rs): Entry point, argument parsing with clap.

  • [src/manifest.rs](file:///Users/j/Code/fleetmesh/meshctl/src/manifest.rs): Parses declarative fleetmesh.org/v1alpha1 manifests (MeshNode, Peering, GrantPolicy, ComputeProvider).

  • [src/diff.rs](file:///Users/j/Code/fleetmesh/meshctl/src/diff.rs): Computes structural green/red terminal diffs between declared YAML manifests and running daemon state.

  • [src/socket.rs](file:///Users/j/Code/fleetmesh/meshctl/src/socket.rs): Client for the meshnode-control/1 IPC protocol over Unix domain sockets.

  • [src/export/](file:///Users/j/Code/fleetmesh/meshctl/src/export/): Compiles abstract manifests into concrete deployment targets:

    • Systemd units and timers.

    • Podman Quadlet container files.

    • Docker Compose topologies.

    • Kubernetes manifests.

  • [src/netfetch.rs](file:///Users/j/Code/fleetmesh/meshctl/src/netfetch.rs): Paid blob downloader supporting HTTP 402 Cashu token streaming.

1.9.1.4.4. 4.4 schema/ Normative Schemas

  • [schema/constants.json](file:///Users/j/Code/fleetmesh/schema/constants.json): Canonical strings, cryptographic domain separation labels, and numeric thresholds.

  • [schema/kinds.json](file:///Users/j/Code/fleetmesh/schema/kinds.json): The definitive catalog of owned (e.g. 11801, 30801, 30802, 30803) and reused Nostr kinds.

  • [schema/messages.json](file:///Users/j/Code/fleetmesh/schema/messages.json): Catalog of all wire messages, protocols, surfaces, and planes.

  • [schemas/](file:///Users/j/Code/fleetmesh/schema/schemas/): Formal JSON Schema files (Draft 2020-12) validating all wire objects.

1.9.1.4.5. 4.5 fleetmesh.org/ Verification & Conformance

  • [scripts/check-implementing.py](file:///Users/j/Code/fleetmesh/fleetmesh.org/scripts/check-implementing.py): Architectural tripwire verifying that all 114 wire surfaces and 263 modules/tables map to exactly one plane.

  • [scripts/conform.py](file:///Users/j/Code/fleetmesh/fleetmesh.org/scripts/conform.py): Conformance harness driving an external binary through every vector.

  • [scripts/gen-vectors.py](file:///Users/j/Code/fleetmesh/fleetmesh.org/scripts/gen-vectors.py): Generates published test vectors in vectors/ from reference math.

  • [scripts/check-docs-copies.py](file:///Users/j/Code/fleetmesh/fleetmesh.org/scripts/check-docs-copies.py): Ensures identical documentation between fleetmesh.org/docs and meshnode/docs.


1.9.1.5. 5. Operational Conventions & Invariants

When working in or extending Fleetmesh, the following non-negotiable rules apply:

  1. Record Then Answer: Never acknowledge or act on a fact before persisting it to disk. State changes, received receipts, and grant commitments must be written to SQLite/PostgreSQL before returning an ACK or signing an outbound envelope.

  2. Strict Wire Reader (vectors/strict.json):

    • Wire integers must be bare ASCII digits (no signs, no floats, no exponents, no whitespace).

    • JSON integers must be native numeric types; "5" or 30166.0 are strictly rejected.

    • Keys must be exactly 64 lowercase hexadecimal digits.

    • Senders must be did:nostr:<64-hex>.

    • Relay URLs must be canonicalized (no trailing slashes, default ports removed, lowercase scheme/host).

  3. Pure-Python Reference Integrity: core/fleetmesh_core must never import I/O libraries (socket, requests, urllib, sqlite3), must never read the system clock (time.time() must be injected), and must never import external packages.

  4. Declared Compartment Boundaries: A compartment must declare all its PARAMS, CHANNELS, METRICS, COMMANDS, and STORES. Hand-written dictionary dispatches are forbidden.

  5. No Blind Derivation of Secrets: Blinding factors must be fresh entropy per commitment. Never derive them deterministically from shared keys or message contents.


1.9.1.6. 6. Verification & Test Suite Cheatsheet

# Run all core reference tests and mechanism verifications
python3 core/tests/test_peering.py
python3 core/tests/test_sync.py
python3 core/tests/test_negentropy.py
python3 core/tests/test_store.py
python3 core/tests/test_mechanisms.py

# Verify conformance against published vectors
python3 scripts/check-vectors.py
python3 scripts/check-spec.py

# Architectural plane and documentation tripwires
python3 fleetmesh.org/scripts/check-implementing.py
python3 fleetmesh.org/scripts/check-declarations.py
python3 fleetmesh.org/scripts/check-stores.py
python3 fleetmesh.org/scripts/check-commands.py
python3 fleetmesh.org/scripts/check-docs-copies.py

# Run full node integration suite
python3 -m unittest discover -s meshnode/fleetmesh_node/tests -p "test_*.py"