Buckets:
| # SSK_Foundation Module Architecture | |
| > [!IMPORTANT] | |
| > **Version Control and State Tracking Rule**: | |
| > This repository exclusively uses **`lore`** for version control, state management, and documentation tracking. **Do NOT use `git`**. | |
| --- | |
| ## 1. Overview and Purpose | |
| `SSK_Foundation` is the core infrastructure layer of the **SovereignSurvivalKit** application ecosystem. It provides low-level system services, multi-tier storage management, encrypted vault lifecycle, cross-process communication (XPC), peer discovery, file system abstractions, audio artifact storage, and SwiftSyntax AST parsing. | |
| `SSK_Foundation` provides thread-safe, actor-isolated services to higher-level modules (`SSK_Hardware`, `SSK_Providers`, `SSK_Orchestrator`, and `SSK_UI`). | |
| --- | |
| ## 2. Package Dependencies and Exports | |
| As defined in [`Package.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Foundation/Package.swift): | |
| - **Target Name**: `SSK_Foundation` | |
| - **Swift Tools Version**: `6.4` | |
| - **Supported Platforms**: macOS 27.0+, iOS 27.0+ | |
| - **Internal Dependencies**: | |
| - `SSK_Abstractions` — Core protocols, interfaces, and domain data types. | |
| - **External Dependencies**: | |
| - `swift-syntax` (`603.0.2`+) — `SwiftSyntax` and `SwiftParser` for AST source code analysis. | |
| - `swift-sdk` (`main` branch) — Model Context Protocol (`MCP`) integration. | |
| --- | |
| ## 3. Subsystems and Architecture Layout | |
| The source files in [`Sources/SSK_Foundation/`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Foundation/Sources/SSK_Foundation) are organized into functional subsystems: | |
| ```text | |
| Sources/SSK_Foundation/ | |
| ├── Storage & Persistence/ | |
| │ ├── StorageCoordinator.swift # Unified coordinator for DB, cache, vault & memory | |
| │ ├── DatabaseManager.swift # Thread-safe SQLite/GRDB database engine with FTS5 | |
| │ ├── MemoryStore.swift # Actor-isolated in-memory cache with TTL expiration | |
| │ ├── FileCacheManager.swift # Local disk binary caching engine | |
| │ ├── AudioArtifactStore.swift # Storage manager for audio stems & analysis artifacts | |
| │ ├── TelemetryStore.swift # Persistent storage for runtime metrics & telemetry | |
| │ └── ICloudDriveProvider.swift # iCloud Drive document sync provider | |
| │ | |
| ├── Security & Vault Lifecycle/ | |
| │ ├── EncryptedFileVaultManager.swift # AES-GCM encrypted file storage via CryptoKit | |
| │ ├── SparsebundleManager.swift # macOS encrypted disk image (.sparsebundle) lifecycle | |
| │ ├── VaultLifecycleController.swift # Vault creation, mounting, verification & teardown | |
| │ ├── VaultLifecycleModels.swift # Data models for vault states & operation results | |
| │ ├── VaultKeyManager.swift # Secure Keychain storage for master vault keys | |
| │ ├── VPNKeyManager.swift # Keychain storage for WireGuard/IKEv2 credentials | |
| │ └── KeychainUtilities/ # Low-level Apple Keychain helper utilities | |
| │ | |
| ├── Cross-Process Communication & Authorization/ | |
| │ ├── XPCBridge.swift # Bidirectional XPC bridge between app and daemons | |
| │ ├── XPCCallerAuthorization.swift # Code signature & audit token validation for XPC callers | |
| │ ├── DocGenXPCCommandRouter.swift # Routes DocGen commands across the Mach XPC service | |
| │ ├── DocGenProcessWorkerExecutor.swift # Spawns and supervises isolated DocGen worker CLI | |
| │ └── IntentDonationQueue.swift # Thread-safe queue for Siri/Shortcuts intent donations | |
| │ | |
| ├── File System & Finder Integration/ | |
| │ ├── FinderCore.swift # POSIX and Foundation file system operations | |
| │ ├── FinderModels.swift # Structural models representing files, folders & trees | |
| │ ├── FileNode.swift # Tree node data structure for directory hierarchies | |
| │ ├── FinderOwnership.swift # POSIX permission checks and ownership verification | |
| │ ├── FinderPersistence.swift # Directory scan persistence and serialized caches | |
| │ ├── FinderCacheManager.swift # In-memory caching layer for fast file lookups | |
| │ └── LoreIgnore.swift # Pattern matcher for .loreignore rule evaluation | |
| │ | |
| ├── Mesh Networking & Peer Discovery/ | |
| │ ├── SpatialDiscoveryService.swift # AWDL/Bonjour local peer discovery & signal tracking | |
| │ ├── PeerRegistry.swift # Actor-isolated registry for approved mesh peer nodes | |
| │ └── AskUCPClient.swift # Client for querying Universal Commerce Protocol nodes | |
| │ | |
| ├── Code Analysis & AST Parsing/ | |
| │ ├── Instrumenter.swift # SwiftSyntax engine for AST traversal and instrumentation | |
| │ ├── SchemaValidator.swift # JSON Schema and structural payload validator | |
| │ └── SemanticGraphEncoder.swift # Serializes AST structures into semantic graph vectors | |
| │ | |
| ├── Observability & Telemetry/ | |
| │ ├── HardwareTelemetryBridge.swift # Bridge for thermal, memory, and hardware telemetry | |
| │ ├── AudioTelemetryProjection.swift # Multi-dimensional projection of audio telemetry | |
| │ ├── AudioSignatureService.swift # Feature extraction and acoustic fingerprint helper | |
| │ ├── MXPerformanceTracer.swift # Latency measurement and performance hotspot tracer | |
| │ └── MXMetricSubscriber.swift # Apple MetricKit subscriber for CPU, GPU and memory | |
| │ | |
| └── Configuration & Workflow/ | |
| ├── FoundationConfiguration.swift # Global runtime configuration settings for Foundation | |
| ├── AppGroupConstants.swift # App Group container identifier constants | |
| └── SetupWorkflow.swift # Initial setup and bootstrapping orchestration | |
| ``` | |
| --- | |
| ## 4. Key Subsystem Responsibilities | |
| ### 1. Multi-Tier Storage Coordination | |
| `StorageCoordinator` provides a unified facade across multiple storage tiers: | |
| - Tier 0: `MemoryStore` for fast in-memory key-value caching. | |
| - Tier 1: `DatabaseManager` for structured records and full-text search via GRDB. | |
| - Tier 2: `AudioArtifactStore` and `FileCacheManager` for binary disk artifacts. | |
| - Tier 3: `EncryptedFileVaultManager` and `SparsebundleManager` for encrypted data at rest. | |
| ### 2. XPC Security and DocGen Isolation | |
| - `XPCCallerAuthorization` validates client audit tokens, team identifiers, and entitlements before processing commands. | |
| - `DocGenProcessWorkerExecutor` executes `SSK_DocGen` in an isolated subprocess with descriptor-relative path access. | |
| ### 3. File System Governance with `LoreIgnore` | |
| - `LoreIgnore` evaluates `.loreignore` rule files to exclude non-tracked files from scans, replacing Git-based ignore mechanisms. | |
| --- | |
| ## 5. Architectural Position | |
| ```text | |
| SSK_Abstractions | |
| ▲ | |
| │ | |
| +---------------------------------+---------------------------------+ | |
| | SSK_Foundation | | |
| | - StorageCoordinator - SparsebundleManager | | |
| | - XPCBridge & Authorization - DocGenProcessWorkerExecutor | | |
| | - SwiftSyntax Instrumenter - SpatialDiscoveryService | | |
| | - LoreIgnore Pattern Matching - HardwareTelemetryBridge | | |
| +---------------------------------+---------------------------------+ | |
| ▲ | |
| ┌────────────────────────┼────────────────────────┐ | |
| │ │ │ | |
| SSK_Hardware SSK_Providers SSK_Orchestrator | |
| ``` | |
Xet Storage Details
- Size:
- 7.88 kB
- Xet hash:
- 01a35ec81e855ea7e5f909a1d6b26f7e7dafcdf79d323ef1d2809eb2b34191e0
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.