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:
System Architecture & Repository Topology — how the submodules and subsystems assemble.
Foundational Mechanisms — the cryptographic, wire, accounting, sync, storage, compute, and settlement mechanics.
The 29 Compartments Guide — an exhaustive, declaration-level breakdown of all 29 compartments in exact tick order across the six architectural planes.
Codebase Reference (Rest of the Tree) — module-by-module navigation for
core/(fleetmesh_core),meshnode/,meshctl/,schema/,strfry-bridge/, andfleetmesh.org/.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 |
|---|---|---|
[ |
Python (Stdlib) |
Pure reference implementation. No I/O, no network, no clock, zero non-stdlib dependencies. Verified directly by conformance vectors in |
[ |
Python ( |
Autonomous daemon node. Assembles 29 compartments, executes tick loops, operates multi-transport listeners, SQLite/PostgreSQL storage engines, and unix control socket. |
[ |
Rust |
Declarative fleet orchestration binary. Hot-reconciles YAML manifests with running |
[ |
JSON / YAML |
Canonical protocol constants ( |
[ |
Python, Shell, HTML |
Conformance test runners ( |
[ |
Python |
Write-policy plugin, bidirectional event sync bridge, and strfry config generator ( |
[ |
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:
Identity & Keys: Cryptographic identities, W3C DID documents, descriptor mining/validation, addressable projections (NIP-66, NIP-85), and presence.
Store & Persistence: Negentropy V1 set reconciliation,
sync/1.0sessions, retention sweeps, Blossom blob wire protocols, and blob replication.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).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.
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.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/1with 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), andanchor(high-availability core node, 30-day lifetime cap).Proof-of-Work: Nodes mine PoW bits into their descriptors (
noncetag) according topow_bitsconfiguration.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, alongsidedid:keyand strictdid:peer:2aliases.
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 usingshared_protocolsintersection.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.0requires 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 Modeproof.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:
FIPS-140-3 Datagram: Local hardened IPC via
SCM_RIGHTSdatagram socket (transport:fips).Iroh QUIC: Fast peer-to-peer UDP connections with DERP relay fallback (
transport:iroh).libp2p: Standard peer-to-peer transport (
transport:libp2p).Nostr WebSocket Relay: Asynchronous gift-wrapped envelopes over public relays (
transport:nostr).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.1. [01] link — Relay Link & Socket Overseer
Plane: Transport
Class: [
fleetmesh_node.planes.transport.link.compartment:Link](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/planes/transport/link/compartment.py)Role: Maintains persistent WebSocket connections to configured Nostr relays. Tracks connection health, reconnection backoffs, dropped subscriptions, and records transport-level refusals.
Declarations:
requires:()reads:('transport',)|live:()NEEDS:Need('transport'),Need('strain', late=True)
Commands:
show(displays relay subscriptions, health, drops, and pending stored message ACKs).Channels: Emits connection failures and subscription cancellations to journal.
Metrics: Drop counters, disconnect counters.
Stores:
_stored_refusals, tracking unacknowledged Kind 1059 deliveries.
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.0wire 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.0accounting 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.sqlitebacking, 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.0state 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:
serveddocument 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:
evictedcounts 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.0andcompute/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:
disputesregistry.
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:
escrowsactive 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.0andcoordinate-mediation/2.0. Allows edge nodes to act as relay mediators for mobile leaves, storing forwarded messages until queried viapickup/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:
handledmessages 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.0wire 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:
_inflighttransfer 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:
replicasmanifest 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
BlossomServerto 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:
receiptsredemption 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:
probeshealth 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:
releasesdatabase.
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_protocolsnegotiation.[
did.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/did.py): W3C DID document formatting,did:nostr,did:key, strictdid:peer:2.[
atproto.py](file:///Users/j/Code/fleetmesh/core/fleetmesh_core/identity/atproto.py): ATProtodid:plcgenesis operation signing,did:webresolution, 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.0notice 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.0ask/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 withmeshnode.[
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 forconstants.json,kinds.json,messages.json, andDIGEST.[
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 acrossMANIFEST, and assembly.[
socket.py](file:///Users/j/Code/fleetmesh/meshnode/fleetmesh_node/app/socket.py): Listens on/var/lib/meshnode/control.sock, serving themeshnode-control/1IPC 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):ProtocolPackageinterface 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 pubsubNodeEventBuswith 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 withclap.[
src/manifest.rs](file:///Users/j/Code/fleetmesh/meshctl/src/manifest.rs): Parses declarativefleetmesh.org/v1alpha1manifests (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 themeshnode-control/1IPC 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 invectors/from reference math.[
scripts/check-docs-copies.py](file:///Users/j/Code/fleetmesh/fleetmesh.org/scripts/check-docs-copies.py): Ensures identical documentation betweenfleetmesh.org/docsandmeshnode/docs.
1.9.1.5. 5. Operational Conventions & Invariants
When working in or extending Fleetmesh, the following non-negotiable rules apply:
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.
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"or30166.0are 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).
Pure-Python Reference Integrity:
core/fleetmesh_coremust 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.Declared Compartment Boundaries: A compartment must declare all its
PARAMS,CHANNELS,METRICS,COMMANDS, andSTORES. Hand-written dictionary dispatches are forbidden.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"