SmartPoints Architecture Overview

This document describes the SmartPoints unified architecture as defined in ADR-088 through ADR-092. The system is organized as a six-layer protocol stack where each layer has a clear responsibility and communicates with adjacent layers through typed Rust interfaces.

Six-Layer Protocol Stack

+---------------------------------------------------------------+
|  Layer 6: Application                                         |
|  spt-appliance, spt-telemetry, spt-llm-router, spt-crew,     |
|  spt-ops-agents, spt-spatial, spt-dev-scope                   |
+---------------------------------------------------------------+
|  Layer 5: Marketplace                                         |
|  spt-discovery, spt-marketplace, spt-aic, spt-dark,          |
|  spt-p2p, spt-onion, spt-checkpoint                          |
+---------------------------------------------------------------+
|  Layer 4: Scope & Governance                                  |
|  sptos-scope, spt-connectors-core, spt-connector-github,     |
|  spt-entra, spt-federation                                   |
+---------------------------------------------------------------+
|  Layer 3: SmartPoint                                          |
|  spt-smartpoint, spt-pq-crypto, spt-vault, spt-aid           |
+---------------------------------------------------------------+
|  Layer 2: Wire                                                |
|  spt-wire, spt-wire-bridge, spt-wire-format, spt-nat,        |
|  spt-crypto-provider                                          |
+---------------------------------------------------------------+
|  Layer 1: Host                                                |
|  sptos-host-core, sptos-host-macos, sptos-host-linux,         |
|  sptos-host-ios, sptos-host-visionos, sptos-host-windows      |
+---------------------------------------------------------------+
|  Layer 0: Kernel                                              |
|  sptos-nucleus, sptos-cap, sptos-proof, sptos-boot,           |
|  sptos-queue, sptos-sched, sptos-vecgraph, sptos-types,       |
|  sptos-region, sptos-shell                                    |
+---------------------------------------------------------------+

How the Layers Connect

Kernel (Layer 0) provides the execution environment. An SPTOS kernel instance runs inside a host daemon and exposes a capability-based system call interface via sptos-cap. The kernel manages memory regions (sptos-region), task scheduling (sptos-sched), and vector graph operations (sptos-vecgraph).

Host (Layer 1) manages kernel instance lifecycles. The platform-agnostic core (sptos-host-core) defines traits for key storage, IPC, daemon lifecycle, and service discovery. Platform crates implement these traits using native APIs: Secure Enclave on macOS/iOS, TPM on Windows, etc.

Wire (Layer 2) handles network transport. spt-wire (renamed from spt-transport in ADR-101) implements DID-based addressing over QUIC with scope-aware longest-prefix routing, adaptive transport cascading (ConnectionCascade), pub/sub, and persistent store-and-forward for offline delivery. spt-wire-bridge connects the transport layer to the SmartPoint envelope layer so that every message on the wire is end-to-end encrypted. spt-crypto-provider handles DID-based QUIC authentication using post-quantum algorithms, replacing X.509/mTLS.

SmartPoint (Layer 3) is the cryptographic core. A SmartPoint pair binds two identities in an asymmetric relationship with ML-KEM key exchange, ChaCha20-Poly1305 encryption, and ML-DSA signatures. The three-layer vector envelope (routing, encrypted payload, signed content) ensures messages are tamper-evident and replay-protected.

Scope (Layer 4) governs identity and access. A Scope wraps a sovereign DID and enforces policies on actor creation, connector access, data sharing, and resource budgets. Connectors are hexagonal adapters to external services (GitHub, Entra ID). NATS is available as an external connector for bridging but is not used for internal SmartPoints communication -- all internal transport uses SPT Wire. The rendezvous protocol enables scope-sealed, time-bounded capability exchange between Scopes.

Marketplace (Layer 5) manages service discovery and engagement. Providers publish services to a Kademlia-style DHT. Consumers search by capability and reputation. Retention is metered in quarx (a metering unit, not a currency) with escrow and circuit breakers.

Application (Layer 6) provides end-user functionality: the network appliance, telemetry, LLM routing, crew orchestration, spatial computing, and developer tooling.

Cross-Cutting Concerns

Identity: The Agentic Identity Chain (spt-aic) is a Merkle DAG that records every identity event (DID creation, role binding, agent delegation, revocation). It provides W3C DID compliance and Merkle proofs for selective disclosure.

Security: Three trust boundaries enforce isolation (see security.md). Post-quantum cryptography is the default suite. Onion routing (spt-onion) and the dark overlay (spt-dark) provide traffic analysis resistance.

Bridges: spt-apple-host-bridge connects the Rust host layer to Swift/Apple platform APIs via UniFFI. spt-integration-tests provides end-to-end test harnesses across all layers.

Detailed Documentation

Document	Description
smartpoint-pairs.md	SmartPoint pair formation, envelope, crypto suites
spt-wire.md	DID-based QUIC transport, ConnectionCascade, pub/sub
sptos-host.md	Instance lifecycle, HostDaemon, platform implementations
identity-chain.md	Merkle DAG identity ledger and W3C DID compliance
scope-governance.md	Scope policies, actors, connectors, rendezvous
marketplace.md	Discovery, retention, quarx metering
security.md	Trust boundaries, DID auth, onion routing, federation

Related References

Document	Description
Crate Map	All crates organized by layer
Getting Started	Build, test, and first steps
First SmartPoint	End-to-end SmartPoint pair tutorial
Deploy Appliance	Docker Compose and Helm quickstart