Skip to main content

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

License Build Doctrine v11 SLSA

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.

SZL Holdings — Orbit v2

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 commit c7c0ba17 · 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 version
  • kernel_commit: "c7c0ba17" — the pinned kernel context
  • change_hash — SHA-256 binding the receipt to the exact Automerge change chunk
  • transition_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.

See: spec/01-dsse-receipts.md


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


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.py folds every mesh state transition onto the org-canonical szl-receipt, binding subject / input_digest / output_digest / policy_id / energy in one record. That input_digest → output_digest binding is the mesh's concrete instance of receipts.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)

Source distribution for szl-mesh 0.1.0
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)

Table of built distributions (wheels) for szl-mesh 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page