szl-mesh
A doctrine-pinned coordination layer that keeps SZL's governance services in sync across an air-gapped fleet, even when nodes go offline
Docs · Quickstart · SZL Holdings
Deployment story: szl-fleet-overlay (UDS Operator packages) · uds-bundles (bundle manifests) · szl-uds-deployment (air-gap deploy)
Canonical status: szl-mesh is the active repo for ongoing UDS mesh / CRDT-coordination work. It supersedes the OTel-schema layer formerly declared canonical in the now-archived
szl-otel-mesh (ADR-0001, 2026-06-03); see the amendment note in that repo's
CANONICAL.md.
Control before action. Evidence after.
Product · Proof · GitHub organization
💡 Why it matters
It brings always-converging shared state and Byzantine-fault-tolerant agreement to edge and disconnected deployments, so a sovereign fleet keeps making consistent, signed governance decisions without a central server.
▶️ Live demo
This is a public repository. As a coordination/CRDT mesh layer it has no standalone hosted demo — run it locally via the Quick start below, or see docs.szlholdings.com for the public product walkthrough.
⚡ Quick start (30 seconds)
git clone https://github.com/szl-holdings/szl-mesh.git
cd szl-mesh
make quickstart # or: see docs.szlholdings.com/quickstart
🔍 How it works
In two sentences: this component is part of SZL's governed-AI mesh — it enforces policy and emits signed, replayable audit receipts so every AI action can be verified after the fact. The full mathematical foundation, formal proofs, and protocol details are documented below and in the technical docs.
📐 Full technical detail, math, and proofs (the proof, not the pitch)
SZL-MESH
Doctrine-pinned CRDT mesh layered on peat — 7 inventions beyond UDS Fleet
Doctrine: v11 LOCKED
749/14/163· Kernel commitc7c0ba17· locked-proven = 8{F1,F4,F7,F11,F12,F18,F19,F22}· Λ = Conjecture 1 (NOT theorem) · SLSA L1 honest · L2 verified-provenance on roadmap (NOT L3)
Status: Skeleton — Design complete, implementation in progress
Date: 2026-06-02
Prepared by: SZL Holdings Research (PhD Distributed Systems)
What Is SZL-MESH?
SZL-MESH is SZL Holdings' native coordination substrate for DDIL-resilient fleet state. It layers on top of peat (Defense Unicorns' CRDT mesh protocol) — it does NOT fork or replace peat. Instead, it adds a capability that peat explicitly lacks: doctrine-pinned DSSE receipt chains on top of CRDT state transitions.
Peat knows WHAT happened to fleet state. SZL-MESH knows WHETHER that change was AUTHORIZED under a locked governance doctrine and WHO signed the authorization.
This is not incremental improvement. It is a governance layer — the difference between a distributed database and a distributed governance ledger.
The 7 Inventions Beyond Peat
1. Doctrine-Pinned DSSE Receipts on CRDT State Transitions
Peat: Signs each CRDT operation with the originating node's Ed25519 key (integrity: we know WHO wrote it).
SZL-MESH adds: Every Automerge change that crosses a policy boundary is wrapped in a DSSE (Dead Simple Signing Envelope) receipt containing:
doctrine_version: "749/14/163"— the locked governance versionkernel_commit: "c7c0ba17"— the pinned kernel contextchange_hash— SHA-256 binding the receipt to the exact Automerge change chunktransition_class— PLATFORM_STATUS | DEPLOYMENT | PACKAGE | COMMAND | CELL_FORMATION
Why categorical, not incremental: Peat proves identity (who wrote). SZL-MESH proves authority (was this write authorized under current governance). Adding this to peat would require fundamental redesign — it cannot be bolted on.
2. Two-Track AUTHORIZED / OBSERVED State
Peat: All CRDT state is equivalent — formation key + Ed25519 = authoritative.
SZL-MESH adds: A dual-track state model coexisting in the same CRDT store:
| Track | Condition | Operator Display | Actionable? |
|---|---|---|---|
| AUTHORIZED | CRDT change carries valid DSSE receipt under doctrine 749/14/163 |
Solid indicator | Yes — command decisions |
| OBSERVED | CRDT change present but no valid receipt (partition, stale doctrine, peat-native node) | Dashed indicator | No — situational awareness only |
Backwards-compatible: Vanilla peat nodes' state appears as OBSERVED, not dropped. SZL-MESH never partitions the network on receipt status.
Military analogy: A soldier can observe any radio report, but will only act on authenticated command authority.
See: spec/02-two-track-state.md
3. Skip-Layer O(n) Aggregation (Λ = Conjecture 1)
Peat: O(n log n) hierarchical aggregation — every change flows through the full tree (Squad → Platoon → Company → Command).
SZL-MESH adds: Receipt-priority skip-layer routing — a receipted AUTHORIZED change bypasses intermediate aggregation and routes directly to command hub:
Without skip-layer (peat baseline):
Squad → Platoon → Company → Command (3 hops, O(n log n))
With SZL skip-layer (AUTHORIZED changes only):
Squad ──────────────────────→ Command (1 hop, O(n))
Squad → Platoon → Company → Command (OBSERVED changes: full path)
Asymptotic analysis: Let r be the fraction of receipted changes, N total nodes.
- Peat:
T(N) = O(N log N)for all changes - SZL-MESH:
T(N) = r·O(N) + (1-r)·O(N log N)→ O(N) as r → 1
⚠ Λ = Conjecture 1 (NOT theorem): The O(n) claim is a design-time conjecture pending formal verification and empirical validation on a live formation. Do not present as proven.
See: spec/03-skip-layer-aggregation.md
4. CRDT-Native Byzantine Corroboration
Peat: Assumes fail-stop nodes. A Byzantine peer with a valid formation key can inject arbitrary CRDT state.
SZL-MESH adds: k-of-n corroboration layered on top of the CRDT — NOT as a consensus protocol (which would sacrifice availability), but as a soft voting annotation that runs alongside the AP CRDT without blocking writes:
1. Any node writes state (immediately available — AP guarantee preserved)
2. Corroboration collector observes changes from multiple nodes
3. When k independent nodes report same value for a key within window T:
→ Change is annotated CORROBORATED
4. Single Byzantine node cannot achieve CORROBORATED for false state if k > 1
Key novelty: BFT consensus (PBFT, Tendermint, HotStuff) sacrifices availability. SZL-MESH achieves Byzantine soft-safety while preserving full AP availability. A different point in the BFT trade-off space.
Default policy: k=2, window=30s for PLATFORM_STATUS and COMMAND transitions.
See: spec/04-byzantine-corroboration.md
5. Doctrine-Gated Enrollment
Peat: Formation key HMAC proves physical presence. Anyone with the formation key can enroll.
SZL-MESH adds: Enrollment additionally requires claiming:
doctrine_version: "749/14/163"(cryptographically asserted in CSR)kernel_commit: "c7c0ba17"slsa_level: "L1"
A node running an older doctrine — even with the formation key — cannot enroll as AUTHORIZED. It may participate as OBSERVED (if peat-compatible) but cannot generate doctrine receipts.
Lifecycle benefit: When governance doctrine increments (new NDAA provision, new Section 889 vendor), stale nodes are automatically downgraded without explicit revocation. The governance lifecycle is encoded in the cryptographic enrollment proof.
Section 889 covered vendors checked at enrollment: Huawei, ZTE, Hytera, Hikvision, Dahua (exactly 5).
See: spec/05-doctrine-gated-enrollment.md
6. CRDT Revocation Without OCSP
Peat: TTL-based certificate expiry. No real-time revocation in air-gapped environments.
SZL-MESH adds: A CRDT-replicated revocation list that propagates revocations through the mesh using the same AP CRDT substrate — no OCSP server required:
crdt_document: "szl-mesh/revoked-certs/formation-<id>"
type: Automerge grow-only set
contents: [{ node_id, cert_fingerprint, revoked_at, reason }]
Properties:
- AP available — revocations propagate through CRDT; nodes check local replica
- Eventually consistent — revocation reaches partitioned cell when any path reconnects
- Monotonic — revocations are never un-done (grow-only set)
- Air-gap compatible — no external service required
See: spec/06-crdt-revocation.md
7. Governance Metrics (First-Class Telemetry Channel)
Peat: GetSyncStats RPC for basic sync monitoring. CDC events to Kafka/NATS.
SZL-MESH adds: Receipt health metrics fed into the a11oy policy/immune-gate — anomaly detection on governance integrity:
szl_mesh_authorized_fraction{formation_id, cell_id}
→ Ratio AUTHORIZED / total changes per time window
→ Drop below threshold = governance anomaly alert
szl_mesh_byzantine_corroboration_failures{node_id}
→ Repeated failures = Byzantine candidate alert
szl_mesh_revocation_propagation_lag_seconds{formation_id}
→ High lag = partition severity indicator
szl_mesh_doctrine_version_mismatch_count{formation_id}
→ Non-zero = stale deployment or rogue node alert
No existing mesh protocol (peat, Consul, Istio, Linkerd) exposes governance-layer integrity metrics. This is unique to SZL-MESH.
See: spec/07-sentra-governance-metrics.md — governance metrics for the CHAPAQ egress immune-inspector
(spec filename is an immutable infra coordinate, kept verbatim).
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ SZL-MESH LAYER STACK │
├─────────────────────────────────────────────────────────────────┤
│ L5: OPERATOR FLEET COCKPIT │
│ Reads verified-only state from SZL-MESH hub node │
│ Displays AUTHORIZED vs. OBSERVED distinction in UI │
├─────────────────────────────────────────────────────────────────┤
│ L4: DOCTRINE RECEIPT GATE (a11oy-receipt-substrate) │
│ DSSE envelope: doctrine_version=749/14/163 │
│ Every CRDT state transition crossing a policy boundary │
│ must carry a receipt signed under the locked doctrine │
│ Unsigned transitions: visible as OBSERVED, not dropped │
├─────────────────────────────────────────────────────────────────┤
│ L3: SZL HIERARCHICAL AGGREGATOR (new — see Invention 3) │
│ Doctrine-aware cell hierarchy │
│ Skip-layer aggregation for AUTHORIZED changes │
│ Surpasses peat's O(n log n) via receipt-priority routing │
├─────────────────────────────────────────────────────────────────┤
│ L2: CRDT MESH (peat-mesh / Automerge + Iroh QUIC) │
│ AP available under partition │
│ Strong Eventual Consistency (SEC) │
│ Ed25519-signed operations │
├─────────────────────────────────────────────────────────────────┤
│ L1: TRANSPORT (Iroh QUIC · BLE · relay · UDP) │
│ Multi-path · NAT traversal · Connection migration │
│ Air-gap: BLE tablet bridge │
└─────────────────────────────────────────────────────────────────┘
Peat vs. SZL-MESH Comparison
| Capability | Peat v0.3.6 | SZL-MESH v1 |
|---|---|---|
| CRDT engine | Automerge | Automerge (same) |
| Transport | Iroh QUIC + BLE | Iroh QUIC + BLE (same) |
| Operation signing | Ed25519 per-op | Ed25519 per-op (same) |
| RBAC | 5 roles | 5 roles + doctrine gate |
| Doctrine version pinning | ✗ | ✓ DSSE receipt |
| Governance audit trail | ✗ | ✓ Receipt ledger |
| Two-track state (AUTHORIZED/OBSERVED) | ✗ | ✓ |
| Skip-layer aggregation | ✗ | ✓ O(n) for receipted changes (Conjecture 1) |
| Byzantine corroboration | ✗ | ✓ k-of-n soft-voting |
| Air-gap CRDT revocation | ✗ | ✓ Grow-only CRDT set |
| Governance integrity metrics | ✗ | ✓ policy/immune-gate integration |
| Doctrine-gated enrollment | ✗ | ✓ |
| Section 889 vendor check | ✗ | ✓ (5 vendors) |
Repository Layout
szl-mesh/
├── README.md — this file
├── LICENSE — Apache-2.0
├── SECURITY.md — security posture, responsible disclosure
├── spec/ — formal protocol specifications (markdown)
│ ├── 01-dsse-receipts.md
│ ├── 02-two-track-state.md
│ ├── 03-skip-layer-aggregation.md
│ ├── 04-byzantine-corroboration.md
│ ├── 05-doctrine-gated-enrollment.md
│ ├── 06-crdt-revocation.md
│ └── 07-sentra-governance-metrics.md
├── proto/ — protobuf definitions (extends peat-node proto)
│ ├── szl_mesh.proto — core SZL-MESH gRPC service
│ └── szl_receipt.proto — DSSE receipt types
├── examples/ — hello-world capability integration
│ └── hello-mesh/ — minimal node participating in mesh
└── .github/
└── workflows/
└── ci.yml — lint + proto check
Quick Start (Conceptual — Implementation Pending)
# 1. Clone and review specs
git clone https://github.com/szl-holdings/szl-mesh
cd szl-mesh && cat spec/01-dsse-receipts.md
# 2. Review protobuf extensions to peat-node
cat proto/szl_mesh.proto
# 3. Run the hello-mesh example (once implemented)
cd examples/hello-mesh
# See examples/hello-mesh/README.md
Invariants (NEVER MODIFY WITHOUT NEW DOCTRINE RELEASE)
| Invariant | Value |
|---|---|
| Doctrine version | 749/14/163 (LOCKED) |
| Kernel commit | c7c0ba17 |
| SLSA level | L1 honest · L2 verified-provenance on roadmap (NOT L3) |
| Section 889 vendors | Exactly 5: Huawei, ZTE, Hytera, Hikvision, Dahua |
| Consistency model | SEC (Strong Eventual Consistency) — AP under CAP |
| Receipt algorithm | DSSE (Dead Simple Signing Envelope) |
| Node identity | Ed25519 (FIPS 186-5) |
| Transport encryption | TLS 1.3 via QUIC (no unencrypted mode) |
| Clock skew tolerance | ±5 seconds UTC |
| Λ claim | Conjecture 1 — NOT theorem |
Contributing
DCO trailers required on every commit:
Signed-off-by: Yachay <yachay@szlholdings.ai>
Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>
License
Apache-2.0. See LICENSE.
References
- peat protocol — Defense Unicorns CRDT mesh
- peat-node — Kubernetes sidecar gRPC node
- Automerge — CRDT engine
- Iroh — QUIC transport
- DSSE spec — Dead Simple Signing Envelope
- Shapiro et al. 2011 — SEC/CRDTs
- Castro & Liskov 1999 — PBFT
Getting Started (When Available)
Status: This repo is currently a design skeleton. No Zarf package has been published yet. Watch this repo for release announcements.
Prerequisites (for future deployment)
When a release ships, deployment will follow this pattern
zarf package pull oci://ghcr.io/szl-holdings/szl-mesh:<tag>
cosign verify-blob --certificate-identity-regexp "https://github.com/szl-holdings/szl-mesh/.github/workflows/.*" --certificate-oidc-issuer https://token.actions.githubusercontent.com --bundle zarf-package-szl-mesh-amd64-<tag>.tar.zst.sigstore.json zarf-package-szl-mesh-amd64-<tag>.tar.zst
uds deploy oci://ghcr.io/szl-holdings/szl-mesh:<tag>
Contributing guidelines
See CONTRIBUTING.md. All commits require DCO sign-off:
git commit -s -m "your message"
Security
See SECURITY.md for vulnerability disclosure policy.
License details
Apache-2.0. See LICENSE.
© SZL Holdings · Doctrine v11 LOCKED (749/14/163, kernel c7c0ba17) · Λ = Conjecture 1 · SLSA L1 honest · L2 verified-provenance on roadmap · Section 889 = 5 vendors
Citation & doctrine
Cite this work via CITATION.cff. Math foundations: szl-papers · lutar-lean (kernel c7c0ba17).
Λ Conjecture 1 (not a theorem) · 749/14/163 v11 LOCKED (kernel c7c0ba17) · SLSA L1 honest · L2 verified-provenance on roadmap · Section 889 = 5 vendors · SZL Holdings ·
Apache-2.0 code · CC-BY-4.0 papers
Sovereign Mesh HTTP API (src/sovereign/api.py)
The src/sovereign/api.py module exposes the sovereign agent's join/dispatch over HTTP via
FastAPI. It imports szl_mesh_agent.py and szl_mesh_coordinator.py from the same directory.
Routes
| Method | Path | Description |
|---|---|---|
POST |
/api/szl/v1/mesh/join |
Doctrine-gated node enrollment (HMAC-SHA256 proof) |
GET |
/api/szl/v1/mesh/nodes |
Live node registry (UP/DOWN/OFFLINE) |
POST |
/api/szl/v1/mesh/dispatch |
Λ advisory gate + F1 seeded dispatch → signed receipt |
GET |
/healthz |
Health check |
How to run
# Set formation key (32-byte hex secret)
export SZL_FORMATION_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))')
# Start the server
pip install fastapi uvicorn pydantic
uvicorn src.sovereign.api:app --host 0.0.0.0 --port 9090
Or mount into an existing FastAPI app:
from fastapi import FastAPI
from src.sovereign.api import register
app = FastAPI()
register(app, ns="/api/szl/v1/mesh")
Node enrollment example
# 1. Compute HMAC-SHA256 proof
FORMATION_KEY="your-formation-key-hex"
NODE_ID="my-gpu-node-01"
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
PROOF=$(python3 -c "
import hmac, hashlib, sys
k = bytes.fromhex('$FORMATION_KEY')
m = ('$NODE_ID' + '$TS' + '749/14/163' + 'c7c0ba17').encode()
print(hmac.new(k, m, hashlib.sha256).hexdigest())
")
# 2. POST join request
curl -s -X POST http://localhost:9090/api/szl/v1/mesh/join \
-H "Content-Type: application/json" \
-d "{
"node_id": "$NODE_ID",
"hardware": {"name": "RTX-4060Ti", "vram_gb": 16, "backend": "CUDA", "arch": "Ada"},
"formation_key_proof": "$PROOF",
"timestamp_utc": "$TS"
}" | python3 -m json.tool
Dispatch example (Λ advisory gate)
# Dispatch a job — lambda_score must be >= 0.5 (advisory Conjecture 1 threshold)
curl -s -X POST http://localhost:9090/api/szl/v1/mesh/dispatch \
-H "Content-Type: application/json" \
-d '{
"request_id": "job-001",
"payload": {"task": "inference", "model": "SZL-Nemo"},
"lambda_score": 0.85
}' | python3 -m json.tool
Honest labels
Every response carries honest_labels:
{
"mesh_type": "scheduler — software load-balancer, not hardware interconnect",
"vram_fusion": "ROADMAP — NVLink-only (consumer Ada/Blackwell have no NVLink)",
"lambda_label": "advisory Conjecture 1 — NEVER a theorem",
"throughput": "MODELED until founder reports MEASURED benchmark",
"join_token_signing": "HMAC-SHA256 classical — ML-DSA (FIPS 204) upgrade = ROADMAP",
"doctrine": "749/14/163",
"kernel_commit": "c7c0ba17"
}
Never claim: mesh acceleration is hardware-level; VRAM is fused across nodes; Λ is a proven theorem; throughput numbers are measured. These are all labeled ROADMAP/MODELED/CONJECTURE by Doctrine v11.
The Ouroboros loop (doctrine cross-reference)
szl-mesh does not implement the estate's Ouroboros bounded-recursion kernel — it is a CRDT coordination substrate, not a recursion engine. This section is a doctrine cross-reference plus an honest note on how the mesh's real flow relates to the loop.
The canonical definition is the receipt-closed kernel
szl-holdings/ouroboros → src/loop-kernel.ts (runLoop): bounded recursion with measurable convergence that MUST
terminate on one
of four exit conditions — converged | consistent | aborted | budgetExhausted — and emits a
governance receipt for every run. The trace is the product.
How the mesh relates to (does not equal) that primitive:
- Receipt-closed transitions.
src/szl_mesh/spine.pyfolds every mesh state transition onto the org-canonicalszl-receipt, bindingsubject / input_digest / output_digest / policy_id / energyin one record. Thatinput_digest → output_digestbinding is the mesh's concrete instance ofreceipts.in ≡ receipts.out— the loop's identity as a metaphor (doctrine, not math), not a proof of correctness. - Bounded, terminating flow. The coordinator (
src/sovereign/szl_mesh_coordinator.py) dispatches only Λ-passed work with F1 replay determinism, and the CRDT layer converges under Strong Eventual Consistency (AP under CAP). There is no unbounded recursion; the receipt log is append-only (F22 emit-monotone, F4 khipu hash-chain).
Honesty (Doctrine v11 · 749/14/163): Λ (the dispatch gate) is Conjecture 1 —
advisory, never a proven theorem. Khipu BFT is Conjecture 2. energy is the literal
"UNAVAILABLE" sentinel — the mesh measures no joules and fabricates none, so this flow
makes no perpetual-motion or zero-cost claim.
Estate on Hugging Face: models, datasets and Spaces are published under the SZLHOLDINGS org.
Metadata
Release files for szl-mesh 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| szl_mesh-0.1.0.tar.gz | 103.1 kB | With provenance | Details for szl_mesh-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| szl_mesh-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for szl_mesh-0.1.0-py3-none-any.whl |
Total release size: 176.3 kB
Release files / szl_mesh-0.1.0.tar.gz
| Download URL | szl_mesh-0.1.0.tar.gz |
|---|---|
| Size | 103.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8f685427a41689554964f51bcee2d3fc4ab211ff298d6ae8f1a4e44dbf48ccb8
|
|
BLAKE2b-256 checksum How to use checksums |
225a943845a4b856cfaadc393c723edd4f064a1f928a821fc3a15322c3b67959
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / szl_mesh-0.1.0-py3-none-any.whl
| Download URL | szl_mesh-0.1.0-py3-none-any.whl |
|---|---|
| Size | 73.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3ea5db992e84c8b7bc3117f90b0c9e2a0352b8b9b0975521ceb2d46a67e92a8e
|
|
BLAKE2b-256 checksum How to use checksums |
5ef4c10671fb8b4c97331dde50608685fcd73003b0a486d4639f72f5ce23603c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for szl-mesh 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for szl_mesh-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.