3. Non-Destructive Hot-Reconciliation

Fleetmesh is designed for continuous operation in mission-critical and edge networking environments. Modifying network topologies, bandwidth allocations, or peering policies must never require daemon restarts or cause in-flight cryptographic sessions to abort.

The meshctl apply command implements non-destructive hot-reconciliation, aligning active runtime state with desired manifest declarations without dropping active QUIC connections or interrupting sessions.

3.1. Reconciliation Architecture

The diagram below illustrates the reconciliation pipeline between meshctl and the meshnode daemon:

┌────────────────────────────────┐
│ Declarative Manifests (.yaml)  │
│ - Peering                      │
│ - GrantPolicy                  │
│ - ComputeProvider              │
└───────────────┬────────────────┘
                │
                ▼
┌────────────────────────────────┐
│ meshctl apply                  │
│ 1. Parse & validate apiVersion │
│ 2. Check diff against live     │
│ 3. Compute surgical updates    │
└───────────────┬────────────────┘
                │
                ▼ (meshnode-control/1 IPC)
┌────────────────────────────────┐
│ meshnode Host Daemon           │
│ ├─ PeeringManager              │ ◄── Updates budget & policy in-place
│ ├─ IrohTransport (QUIC)        │ ◄── Keeps active TLS/QUIC sessions alive
│ └─ GrantStore                  │ ◄── Inserts/amends bilateral grants
└────────────────────────────────┘

3.2. Reconciliation Mechanics

3.2.1. 1. Manifest Ingestion & Schema Checking

When meshctl apply -f <manifest> is invoked:

  • meshctl deserializes YAML manifests into strongly typed internal structures.

  • It validates the apiVersion. Normative manifests require apiVersion: fleetmesh.org/v1alpha1. Legacy meshstr.org/v1alpha1 manifests trigger a warning recommending meshctl convert.

  • Validates required metadata (name, namespace) and spec attributes.

3.2.2. 2. Socket Negotiation (meshnode-control/1)

meshctl locates the daemon’s control socket:

  • By default, checks /var/lib/fleetmesh/meshnode.sock or the directory specified with --dir.

  • Connects using standard Unix domain socket semantics.

  • Executes an initial handshake querying daemon health and active state.

3.2.3. 3. Granular In-Flight Mutators

Depending on the manifest kind, meshctl issues targeted control commands rather than restarting subsystems:

  • ``Peering`` manifests: - meshctl maps the spec to the peer control verb:

    {
      "peer": "did:key:z6Mkh...",
      "transport": "iroh",
      "ingress": { "max_rate_bytes": 10485760 },
      "egress": { "kinds": [11801, 21801, 31801] },
      "budget": { "sat_ceiling": 50000 }
    }
    
    • The PeeringManager in meshnode inspects active session pools. If an Iroh QUIC connection or WebSocket session is currently open with that peer, it updates the ingress/egress filters and rate limiters in memory.

    • No connection handshake is re-triggered, and open multiplexed streams continue transferring data without packet loss.

  • ``GrantPolicy`` manifests: - Dispatches updates directly to the node’s trust control interface. - Automatically updates the bilateral trust store (grants.sqlite), updating credit ceilings and payment schedules without blocking database transactions.

3.3. Offline Staging Fallback

If the meshnode daemon is not currently running (e.g., during machine provisioning or system boot):

  • meshctl apply detects that the Unix domain socket is inactive.

  • Instead of failing, it logs a notice and performs offline config staging:

  • Reads existing config.json in the node data directory, safely merges the manifest declarations into the configuration, and writes the updated state to disk atomically.

  • When meshnode subsequently boots, it initializes with the newly applied declarative state.

3.4. Dry-Run Simulation

Operators and CI/CD pipelines can evaluate the impact of changes prior to applying them using the --dry-run flag:

meshctl apply -f manifests/peering.yaml --dry-run

In dry-run mode: - All schema validations and property checks are executed. - The control socket status is queried to ensure connectivity. - A simulated reconciliation plan is printed to stdout detailing each resource that would be updated, added, or retained. - Zero mutations are applied to either memory or disk.