ARCHITECTURE.md

SovereignSurvivalKit Architecture Overview

Version Control and State Tracking Rule: This repository exclusively uses lore for version control, state management, and documentation tracking. Do NOT use git.

---

Audit Timestamp: 2026-08-20 Symbol Count: 1173 documented symbols across 7 modules (source: docc_index.json) Audit Tool: audit-architecture skill

---

1. System Overview

SovereignSurvivalKit is a modular Swift ecosystem designed for local intelligence, cryptographic vault management, hardware telemetry, off-grid peer-to-peer communication, and automated documentation generation. The codebase is organized into 10 Swift Package modules in src/SovereignSurvivalKit/Modules/, standalone tools and daemons in src/SovereignSurvivalKit/, and multi-platform application targets in SovereignSurvivalKit.xcodeproj.

---

2. Module Index

Module / Target	Documented Symbols	Target Type	Primary Purpose
SSK_Physics	15	Swift Library	Core amodal inversion mathematics, reverse provenance, and $\tau$-dynamics variance.
SSK_Abstractions	60	Swift Library	Architectural contract backbone defining domain models, GRDB schemas, and ACP protocols.
SSK_Foundation	138	Swift Library	Multi-tier storage coordinator, encrypted sparsebundles, database management, and MCP bridge.
SSK_Demucs_MLX	0	Swift Library	Apple Silicon native neural audio stem separation using Hybrid Transformer Demucs on MLX.
SSK_Hardware	27	Swift Library	Hardware sensor acquisition, real-time vDSP spectral extraction, and MLX audio pipelines.
SSK_Providers	213	Swift Library & Executable	Concrete intelligence providers, AST parsers, WireGuard tunnels, ZK identity, and SSK_StorageHost.
SSK_Orchestrator	380	Swift Library & Executable	Central intake supervisor (IngestionCoordinator), audio runtime, P2P mesh, and SSK_IngestionTester.
SSK_Intents	0	Swift Library	Programmatic intent library for headless curation and automated execution.
SSK_UI	95	Swift Library	Reusable SwiftUI presentation components, UCP commerce search, waveform visualizers, and canvas.
SSK_IntegrationTests	0	Swift Library & Test Harness	Unified integration test harness with mock hardware taps and evaluation datasets.
SSK_DocGen	0	Swift Executable	Standalone CLI worker building AST manifolds and DocC indices under sandboxed daemon control.
SSKVaultHost	0	Daemon & App	System-level launchd daemon (com.ssk.vaulthost.plist) verifying audit tokens and controlling DocGen.
SovereignSurvivalKit	0	macOS/iOS App	Primary host application coordinating background services and rendering root UI views.
SovereignSurvivalKitIntents	0	App Extension	43 App Intents exposing audio intake, vault operations, and settlement to Siri and Shortcuts.
ClipLiveActivities	0	Widget Extension	Live Activities and Dynamic Island widgets for real-time telemetry and sync monitoring.
XCPSSKPlugin	0	Xcode Plug-in	Developer plug-in bundle adding SSK intelligence and documentation tools to Apple Xcode.

---

3. Module Dependency Lattice

                           SSK_Physics
                               ▲
                               │
                        SSK_Abstractions (GRDB.swift)
                        ▲      ▲       ▲
         ┌──────────────┘      │       └─────────────┐
         │                     │                     │
   SSK_Foundation        SSK_Hardware          SSK_Demucs_MLX (mlx-swift)
   (swift-syntax, MCP)   (Accelerate, CoreML)        │
         ▲                     ▲                     │
         │                     └──────────┬──────────┘
         │                                │
         ├────────────────────────────────┘
         ▼
   SSK_Providers (swift-nio*, swift-crypto, swift-certificates, CTDLib, MCP)
   ├── SSK_StorageHost (CLI Executable)
   └── CTDLib (C Shims)
         ▲
         │
   SSK_Orchestrator (AVFoundation, Network.framework, MCP)
   ├── SSK_IngestionTester (CLI Executable)
   └── SSK_DocGen (Standalone CLI Package)
         ▲
   ┌─────┴──────────────┐
   │                    │
SSK_Intents          SSK_UI (SwiftUI, TipKit, ImagePlayground)
   │                    │
   └──────────┬─────────┘
              ▼
   SSK_IntegrationTests (All Modules)
              ▲
              │
   SovereignSurvivalKit (Main App & System Extensions)

---

4. Security Architecture

1. Subprocess Isolation: External MCP clients connect exclusively to SSK_StorageHost acp-agent. The daemon SSKVaultHost verifies caller audit tokens and spawns SSK_DocGen under restricted sandbox parameters.
2. Biometric Vault Protection: Volume decryption keys are guarded by Secure Enclave hardware and require biometric authorization through LocalAuthentication.
3. Zero-Knowledge Identity: Peer connections over P2P mesh networks are validated with zero-knowledge proofs before admitting peers to data exchange sessions.
4. Post-Quantum Digital Signatures: Ledger manifests and transactions are cryptographically signed using ML-DSA signatures.

---

5. Build and Version Control

• Version Control: Managed exclusively via lore. Do not use git.
• Packaging: Execute scripts/build_dmg.sh to assemble dist/SovereignSurvivalKit.dmg.
• Installation: Execute scripts/install_dist.sh to install exported build products.