Buckets:

localhost1978
/

localhost

Files

xet

localhost1978/localhost / LOCALHOST1978 /SovereignSurvivalKit /README.md

localhost1978

3 months ago

preview code

download

raw

20.1 kB

![[SovereignSurvivalKit_Modular_Architecture_Diagram.png]]
# SovereignSurvivalKit Source Root
> [!IMPORTANT]
> **Version Control Rule**: This repository exclusively uses `lore` for version control, state tracking, and documentation. **Do not use `git`**.
---
### 0. User Value
The **SovereignSurvivalKit (SSK)** host app and the **SSKVaultHost** are the two primary pillars of the ecosystem, designed to separate user experience from high-security system management.
![[SSK_Sovereign_Intelligence_Ecosystem_Architecture.jpg]]
### **SovereignSurvivalKit (The Experience Layer)**
This app is the "face" of the system, though it is designed with a **headless-first paradigm** to minimize traditional user interface friction.
- **Invisible, System-Wide Intelligence**: Operates as a background agent that integrates directly into Siri, Spotlight, and Shortcuts, removing the need to manage a traditional app window.
- **Contextual Interaction**: Delivers information through **lightweight, interactive "Snippets"** that appear natively inside Siri or Spotlight when you trigger a search or a command.
- **Zero-Egress Privacy**: Ensures all intelligence is processed **exclusively on-device** via Apple Silicon, preventing your data from being sent to external clouds.
- **Unified Extension Ecosystem**: Acts as the central hub for specialized features like secure **iMessage** sharing, **App Clips** for instant off-grid pairing, and **Live Activities** for monitoring vault status.
### **SSKVaultHost (The Engine and Guardian)**
This is a high-security background utility that acts as the "engine room" for the SovereignSurvivalKit, managing the underlying infrastructure.
- **Silent Infrastructure Management**: Runs as a low-level system daemon to **start, stop, and monitor** critical background services like storage hosts and documentation workers.
- **Transparency at a Glance**: Features a resident **macOS menu bar extra** that provides real-time status indicators for vault reachability and system health.
- **Strict Security Gatekeeping**: Protects your private data by **authenticating process identities** (audit tokens and team identifiers) before allowing any local app to access secure vault resources.
- **Secure Path Authorization**: Validates and manages the physical directories where your encrypted vaults and workspaces live, ensuring they are **authorized by the operator** and stored securely.
## 1. Overview and Purpose
This directory (`src/SovereignSurvivalKit/`) contains the source code for the **SovereignSurvivalKit** application suite. It brings together modular Swift packages, the primary application targets for macOS and iOS, background system daemons, documentation utilities, developer tools, and system extensions.
The system provides:
- **Encrypted Local Vaults**: Hardware-backed AES-GCM and `.sparsebundle` storage managed with Apple CryptoKit and the Apple Secure Enclave.
- **On-Device Machine Learning and Audio Telemetry**: Apple Silicon neural audio source separation (HTDemucs via Apple MLX), real-time $\tau$-dynamics, and 12-bin FFT chromagram feature extraction.
- **Zero-Knowledge Identity and Settlement**: Privacy-preserving peer authentication, post-quantum ML-DSA signatures, and bilateral asset settlement.
- **Encrypted Mesh Networking**: WireGuard and UDP/QUIC peer-to-peer mesh networking (`10.0.0.0/24` subnet).
- **Model Context Protocol (MCP) and Tooling**: Embedded ACP agent integration (`SSK_StorageHost acp-agent`), Xcode build plugins (`XCPSSKPlugin`), and automated documentation generation (`SSK_DocGen`).
---
## 2. Directory Layout and Target Hierarchy
```text
src/SovereignSurvivalKit/
├── Modules/                                     # Modular Swift Packages (10 packages)
│   ├── SSK_Physics/                             # Core physics, amodal inversion & reverse provenance
│   ├── SSK_Abstractions/                        # Domain protocols, entity contracts & GRDB schema
│   ├── SSK_Foundation/                          # Storage coordinator, SQLite DB, keys & XPC bridge
│   ├── SSK_Demucs_MLX/                          # MLX-powered HTDemucs 4-stem audio separation
│   ├── SSK_Hardware/                            # Hardware audio telemetry & ML pipelines
│   ├── SSK_Providers/                           # Concrete intelligence, ZK, VPN & server providers
│   ├── SSK_Orchestrator/                        # Ingestion engine, RTC carrier clock & workflow supervisor
│   ├── SSK_Intents/                             # Siri App Intents delegation & routing
│   ├── SSK_UI/                                  # SwiftUI presentation components & interactive views
│   └── SSK_IntegrationTests/                    # Centralized cross-module integration test suite
│
├── SovereignSurvivalKit/                        # Main Application Target (macOS & iOS)
│   ├── SovereignSurvivalKitApp.swift            # SwiftUI @main application entry point
│   ├── ServicesCoordinator.swift                # Daemon bootstrapping, agent symlinking & VPN setup
│   ├── SovereignSurvivalKit.entitlements        # App Sandbox & NetworkExtension entitlements
│   ├── Info.plist                               # Bundle metadata & configuration
│   ├── Assets.xcassets                          # Application icons, color sets & visual assets
│   └── data/docs/SSK_Ledger_Vault/              # Auto-generated documentation store & search index
│
├── SSKVaultHost/                                # Background Service & Launchd Daemon
│   ├── main.swift                               # Standalone daemon process entry point
│   └── com.ssk.vaulthost.plist                  # macOS LaunchAgent property list definition
│
├── SSK_DocGen/                                  # Standalone Documentation Generator CLI
│   ├── Package.swift                            # SPM manifest for SSK_DocGen executable
│   ├── Sources/SSK_DocGen/                      # AST scanning & ledger artifact generation logic
│   ├── README.md                                # DocGen worker architecture & topology
│   ├── AGENTS.md                                # DocGen agent guidelines & security constraints
│   └── SSK_DocGen_Manual_Testing_Guide.md       # Verification & manual test procedures
│
├── XCPSSKPlugin/                                # Xcode Developer Plug-in Target
│   ├── XCPSSKPlugin.swift                       # Xcode integration & MCP service bridge
│   └── ssk-intelligence-plugin.json             # Plug-in capability manifest
│
├── ClipLiveActivities/                          # WidgetKit & Live Activity Target
│   ├── ClipLiveActivities.swift                 # Widget configuration & timeline provider
│   ├── ClipLiveActivitiesBundle.swift           # Widget bundle entry point
│   └── AppIntent.swift                          # Background Live Activity control intents
│
├── SovereignSurvivalKitIntents/                 # Siri App Intents Target
├── SovereignSurvivalKitIntentsUI/               # Siri Snippet UI Overlay Extension Target
├── SovereignSurvivalKitMeshClip/                # App Clip Target (Zero-install mesh workflows)
├── SovereignSurvivalKitMessenger/               # iMessage Application Target
├── SovereignSurvivalKitMessenger MessagesExtension/ # Messages Extension Target (P2P asset transfer)
├── IntegrationTests/                            # Xcode Project Integration Test Bundle
└── SovereignSurvivalKit.xcodeproj/              # Primary multi-platform Xcode project
```
---
## 3. Modular Swift Packages (`Modules/`)
The architecture uses 10 local Swift packages in [`Modules/`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules). Each module maintains its own `Package.swift`, unit tests, and documentation.
| Module | Summary and Responsibilities | Internal Dependencies |
| :--- | :--- | :--- |
| [**`SSK_Physics`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Physics) | Computes multi-dimensional $\tau$-tensors, amodal state inversion, and reverse provenance deviation checks using Metal GPU shaders and Accelerate `vDSP`. | None |
| [**`SSK_Abstractions`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Abstractions) | Defines the architectural backbone: entity contracts (`SemanticAppEntity`), GRDB SQLite migrations, MultiTau control theory (`TelemetryEngine`), process algebra (CCS/LTS), and protocol schemas (ACP/UCP). | `SSK_Physics`, `GRDB.swift` |
| [**`SSK_Foundation`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Foundation) | Implements multi-tier storage (`StorageCoordinator`), SQLite persistence (`DatabaseManager`), Keychain management (`VaultKeyManager`), encrypted `.sparsebundle` volumes, Finder integration, `.loreignore` evaluation (`LoreIgnore`), and XPC IPC (`XPCBridge`). | `SSK_Abstractions`, `swift-syntax`, `swift-sdk` (MCP) |
| [**`SSK_Demucs_MLX`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Demucs_MLX) | Neural music source separation engine utilizing the Hybrid Transformer Demucs (HTDemucs) model on Apple Silicon via `mlx-swift`. Isolates Vocals, Drums, Bass, and Other stems. | `mlx-swift` (`MLX`, `MLXNN`, `MLXRandom`, `MLXOptimizers`) |
| [**`SSK_Hardware`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Hardware) | Manages low-level audio telemetry pipelines, 12-bin FFT chromagrams, $\tau$-dynamics calculations, parallel subframe telemetry extraction, and CoreMedia `MusicUnderstanding` pre-processing. | `SSK_Abstractions`, `SSK_Foundation`, `SSK_Demucs_MLX`, `SSK_Physics` |
| [**`SSK_Providers`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Providers) | Delivers concrete implementations: Foundation Models, on-device MLX LLMs, Zero-Knowledge identity (`ZKIdentityService`), post-quantum ML-DSA signatures, WireGuard VPN tunneling, TDLib client (`CTDLib`), C++ driving license verification (`CLongfellow`), and `SSK_StorageHost` daemon. | `SSK_Foundation`, `SSK_Abstractions`, `SSK_Hardware`, `swift-syntax`, `swift-nio*`, `swift-crypto`, `swift-certificates`, `CLongfellow`, `CTDLib`, `swift-sdk` |
| [**`SSK_Orchestrator`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Orchestrator) | Central intake and coordination engine: `IngestionCoordinator` (AST and DocC extraction), `AggregatorManager`/`AggregatorActor` (biometric vault access), real-time RTC carrier clock (`SystemOrchestrator`), P2P mesh discovery, and `WorkflowSupervisor`. Includes `SSK_IngestionTester` CLI. | `SSK_Abstractions`, `SSK_Foundation`, `SSK_Providers`, `SSK_Hardware`, `SSK_Physics`, `swift-sdk` |
| [**`SSK_Intents`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Intents) | Provides shared intent handling models and routes execution to the main application intent targets. | `SSK_Orchestrator` |
| [**`SSK_UI`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_UI) | Presentation layer: Offline UCP commerce search (`CommerceSearchView`), multi-format asset quicklook (`QuickLookBrowserView`), chromagram node visualizer (`TimeCapsuleNodeView`), dynamic canvas (`TopographicalCanvas`), and PIN erasure (`PinEntryView`). | `SSK_Foundation`, `SSK_Providers`, `SSK_Orchestrator`, `SSK_Hardware` |
| [**`SSK_IntegrationTests`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_IntegrationTests) | Comprehensive end-to-end integration and UI test suite evaluating cross-module interactions, synchronization, and intent workflows. | All Modules |

---

## 4. Standalone Tools and Background Daemons

### 1. `SSKVaultHost` (`SSKVaultHost/`)
- **Type**: Background launchd daemon and lifecycle service.
- **Function**: Hosts the local HTTP/3 QUIC storage server on macOS, managed via `SMAppService` and registered using `com.ssk.vaulthost.plist`.
- **Inter-Process Communication**: Serves as the XPC Mach service endpoint responding to main app requests and coordinating VPN network configuration.

### 2. `SSK_DocGen` (`SSK_DocGen/`)
- **Type**: Private documentation generator and resource worker CLI.
- **Function**: Scans codebase AST structures and generates documentation ledger artifacts (`docc_index.json`, `graph.json`, and Markdown specifications).
- **Protocol**: Interfaces with approved MCP clients through `SSK_StorageHost acp-agent` over standard I/O and typed XPC commands (`DocGenHostCommand`).
- **Roadmap**: See [next/dev/SSK_DOCGEN_PHASE_ROADMAP.md](file:///Users/voxels/SovereignSurvivalKit/next/dev/SSK_DOCGEN_PHASE_ROADMAP.md).

### 3. `XCPSSKPlugin` (`XCPSSKPlugin/`)
- **Type**: Xcode Developer Plug-in (`.xcplugin`).
- **Function**: Bridges Apple Xcode Coding Intelligence features directly to local ACP agents (`SSK_StorageHost acp-agent`) for AI assistance, documentation inspection, and codebase indexing.

---

## 5. Main Application and System Extensions

### [**`SovereignSurvivalKit`**](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit) (Main App Container)
- **Entry Point**: [`SovereignSurvivalKitApp.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/SovereignSurvivalKitApp.swift) initializes the application lifecycle, registers MetricKit subscribers, handles OS process termination signals (`SIGINT`, `SIGTERM`), and presents primary navigation (`MainContentView`).
- **Services Bootstrapping**: [`ServicesCoordinator.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/ServicesCoordinator.swift) starts the background daemon, symlinks the stable agent executable (`~/Library/Application Support/SovereignSurvivalKit/Agent/SSK_Agent` -> `/usr/local/bin/SSK_StorageHost`), connects XPC channels, and configures OS WireGuard VPN profiles (`NETunnelProviderManager`).

### Extension Targets
- **`ClipLiveActivities`**: WidgetKit extension presenting Live Activities for vault status and background processing via [`VaultLiveActivityIntent`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/ClipLiveActivities/AppIntent.swift).
- **`SovereignSurvivalKitIntents` & `SovereignSurvivalKitIntentsUI`**: Provides system-level Siri and Shortcuts integrations with custom snippet UI views.
- **`SovereignSurvivalKitMeshClip`**: Lightweight App Clip target enabling quick peer pairing and zero-installation mesh communication.
- **`SovereignSurvivalKitMessenger` & `MessagesExtension`**: iMessage extension for sharing encrypted assets, transaction summaries, and verifiable credentials.

---

## 6. Architecture and Dependency Flow

```mermaid
graph TD
    subgraph Presentation & Entry
        APP[SovereignSurvivalKit App Target]
        EXT[Extensions: Clip, Intents, Messages, Widgets]
        UI[SSK_UI]
        INTENTS[SSK_Intents]
    end
    subgraph Orchestration & Intake
        ORCH[SSK_Orchestrator]
        DOCGEN[SSK_DocGen]
    end
    subgraph Service & Hardware Providers
        PROV[SSK_Providers]
        HW[SSK_Hardware]
        DEMUCS[SSK_Demucs_MLX]
    end
    subgraph Core Foundation & Abstractions
        FOUND[SSK_Foundation]
        ABS[SSK_Abstractions]
        PHYS[SSK_Physics]
    end
    APP --> UI
    APP --> ORCH
    APP --> FOUND
    APP --> ABS
    EXT --> ORCH
    UI --> ORCH
    UI --> PROV
    UI --> HW
    UI --> FOUND
    INTENTS --> ORCH
    DOCGEN --> ORCH
    ORCH --> PROV
    ORCH --> HW
    ORCH --> FOUND
    ORCH --> ABS
    ORCH --> PHYS
    PROV --> HW
    PROV --> FOUND
    PROV --> ABS
    HW --> DEMUCS
    HW --> FOUND
    HW --> ABS
    HW --> PHYS
    FOUND --> ABS
    ABS --> PHYS
```

---

## 7. Master Build and Installation Lifecycle

Use the unified scripts in `scripts/` from the repository root:

### 1. Master Build and Installation (Standard)
```bash
# Full clean build and system installation
./scripts/install.sh --clean
# Clean build without system installation
./scripts/install.sh --build-only --clean
# Direct installation from existing dist/ artifacts
./scripts/install.sh --install-only
# Uninstall applications, CLI tools, and plug-ins
./scripts/install.sh --uninstall
# Clean build and reset application databases, vaults, and caches
./scripts/install.sh --clean --reset-data
```

### 2. Multi-Platform Build Conditioning Rules
- **macOS Desktop Schemes**: Build `SovereignSurvivalKit`, `SSKVaultHost`, and `XCPSSKPlugin` using destination `generic/platform=macOS`.
- **iOS-Only Extensions**: Target dependencies such as `SovereignSurvivalKitMeshClip`, `ClipLiveActivities`, `SovereignSurvivalKitIntents`, and `SovereignSurvivalKitMessenger` have `platformFilter = ios;` configured in `project.pbxproj` and are excluded during macOS desktop builds.

### 3. Installation Target Destinations

| Component | Direct Script Install (`install_dist.sh`) | Signed Package (`build_pkg.sh` / `.pkg`) |
| :--- | :--- | :--- |
| **Desktop Applications** | `/Applications/SovereignSurvivalKit.app`<br>`/Applications/SSKVaultHost.app` | `/Applications/SovereignSurvivalKit.app`<br>`/Applications/SSKVaultHost.app` |
| **CLI Binaries** | `/usr/local/bin/SSK_StorageHost`<br>`/usr/local/bin/SSK_DocGen`<br>`/usr/local/bin/SSKVaultHost` | `/usr/local/bin/SSK_StorageHost`<br>`/usr/local/bin/SSK_DocGen`<br>`/usr/local/bin/SSKVaultHost` |
| **Shell Paths** | `/etc/paths.d/SovereignSurvivalKit` | `/etc/paths.d/SovereignSurvivalKit` |
| **Xcode Plug-in** | `~/Library/Developer/Xcode/Plug-ins/XCPSSKPlugin.xcplugin` | `/Library/Application Support/Developer/Shared/Xcode/Plug-ins/XCPSSKPlugin.xcplugin` |

---

## 8. Documentation Ledger Vault (`data/docs/SSK_Ledger_Vault`)

The repository maintains an automated documentation ledger in [`SovereignSurvivalKit/data/docs/SSK_Ledger_Vault/`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/data/docs/SSK_Ledger_Vault):

- **`docc_index.json`**: Search index mapping symbols, structs, functions, and protocols to source file paths and line numbers.
- **`graph.json`**: Structural dependency and semantic relationship graph across all framework components.
- **`DocC_Index.md`**: Master index linking human-readable entity specifications for all documented symbols.

---

## 9. Security, Privacy, and Cryptography Boundaries

- **Local Storage Encryption**: AES-GCM 256-bit encryption with key material stored in the macOS Keychain (`VaultKeyManager`) or backed by the Apple Secure Enclave (`SecureEnclaveManager`).
- **Zero-Knowledge Authentication**: Peer authentication verified through `ZKIdentityService` and native C++ driving license verification (`CLongfellow`).
- **Post-Quantum Signatures**: Digital signatures computed with Module-Lattice-Based Digital Signature Algorithm (`MLDSASigner`).
- **Network Privacy**: Isolated mesh subnet (`10.0.0.0/24`) over WireGuard tunnels and mTLS encrypted QUIC streams.
- **Secure Memory Sanitization**: Cryptographic keys wrapped in `EphemeralKeyHolder` with zeroization on deallocation.

---

## 10. Troubleshooting

### Dependency Resolution and Permission Errors
During the execution of `./scripts/install.sh --clean` or `xcodebuild -resolvePackageDependencies`, if permission errors or file lock conflicts occur:

1. Stop active Xcode and build processes:
   ```bash
   killall Xcode xcodebuild 2>/dev/null || true
   ```
2. Restore write permissions and clear DerivedData:
   ```bash
   chmod -R u+w ~/Library/Developer/Xcode/DerivedData/SovereignSurvivalKit-* 2>/dev/null || true
   rm -rf ~/Library/Developer/Xcode/DerivedData/SovereignSurvivalKit-*
   ```
3. Restart the build pipeline with package refresh:
   ```bash
   ./scripts/install.sh --clean --refresh-packages
   ```

Xet Storage Details

Size:: 20.1 kB
Xet hash:: 8e16d85f51bc1a1cb2eb307bd031b6e95cf1fdd9bee6aec1cde06f801e5bec67

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	![[SovereignSurvivalKit_Modular_Architecture_Diagram.png]]

	# SovereignSurvivalKit Source Root

	> [!IMPORTANT]
	> Version Control Rule: This repository exclusively uses `lore` for version control, state tracking, and documentation. Do not use `git`.

	---

	### 0. User Value

	The SovereignSurvivalKit (SSK) host app and the SSKVaultHost are the two primary pillars of the ecosystem, designed to separate user experience from high-security system management.

	![[SSK_Sovereign_Intelligence_Ecosystem_Architecture.jpg]]

	### SovereignSurvivalKit (The Experience Layer)

	This app is the "face" of the system, though it is designed with a headless-first paradigm to minimize traditional user interface friction.

	- Invisible, System-Wide Intelligence: Operates as a background agent that integrates directly into Siri, Spotlight, and Shortcuts, removing the need to manage a traditional app window.
	- Contextual Interaction: Delivers information through lightweight, interactive "Snippets" that appear natively inside Siri or Spotlight when you trigger a search or a command.
	- Zero-Egress Privacy: Ensures all intelligence is processed exclusively on-device via Apple Silicon, preventing your data from being sent to external clouds.
	- Unified Extension Ecosystem: Acts as the central hub for specialized features like secure iMessage sharing, App Clips for instant off-grid pairing, and Live Activities for monitoring vault status.

	### SSKVaultHost (The Engine and Guardian)

	This is a high-security background utility that acts as the "engine room" for the SovereignSurvivalKit, managing the underlying infrastructure.

	- Silent Infrastructure Management: Runs as a low-level system daemon to start, stop, and monitor critical background services like storage hosts and documentation workers.
	- Transparency at a Glance: Features a resident macOS menu bar extra that provides real-time status indicators for vault reachability and system health.
	- Strict Security Gatekeeping: Protects your private data by authenticating process identities (audit tokens and team identifiers) before allowing any local app to access secure vault resources.
	- Secure Path Authorization: Validates and manages the physical directories where your encrypted vaults and workspaces live, ensuring they are authorized by the operator and stored securely.

	## 1. Overview and Purpose

	This directory (`src/SovereignSurvivalKit/`) contains the source code for the SovereignSurvivalKit application suite. It brings together modular Swift packages, the primary application targets for macOS and iOS, background system daemons, documentation utilities, developer tools, and system extensions.

	The system provides:
	- Encrypted Local Vaults: Hardware-backed AES-GCM and `.sparsebundle` storage managed with Apple CryptoKit and the Apple Secure Enclave.
	- On-Device Machine Learning and Audio Telemetry: Apple Silicon neural audio source separation (HTDemucs via Apple MLX), real-time $\tau$-dynamics, and 12-bin FFT chromagram feature extraction.
	- Zero-Knowledge Identity and Settlement: Privacy-preserving peer authentication, post-quantum ML-DSA signatures, and bilateral asset settlement.
	- Encrypted Mesh Networking: WireGuard and UDP/QUIC peer-to-peer mesh networking (`10.0.0.0/24` subnet).
	- Model Context Protocol (MCP) and Tooling: Embedded ACP agent integration (`SSK_StorageHost acp-agent`), Xcode build plugins (`XCPSSKPlugin`), and automated documentation generation (`SSK_DocGen`).

	---

	## 2. Directory Layout and Target Hierarchy

	```text
	src/SovereignSurvivalKit/
	├── Modules/ # Modular Swift Packages (10 packages)
	│ ├── SSK_Physics/ # Core physics, amodal inversion & reverse provenance
	│ ├── SSK_Abstractions/ # Domain protocols, entity contracts & GRDB schema
	│ ├── SSK_Foundation/ # Storage coordinator, SQLite DB, keys & XPC bridge
	│ ├── SSK_Demucs_MLX/ # MLX-powered HTDemucs 4-stem audio separation
	│ ├── SSK_Hardware/ # Hardware audio telemetry & ML pipelines
	│ ├── SSK_Providers/ # Concrete intelligence, ZK, VPN & server providers
	│ ├── SSK_Orchestrator/ # Ingestion engine, RTC carrier clock & workflow supervisor
	│ ├── SSK_Intents/ # Siri App Intents delegation & routing
	│ ├── SSK_UI/ # SwiftUI presentation components & interactive views
	│ └── SSK_IntegrationTests/ # Centralized cross-module integration test suite
	│
	├── SovereignSurvivalKit/ # Main Application Target (macOS & iOS)
	│ ├── SovereignSurvivalKitApp.swift # SwiftUI @main application entry point
	│ ├── ServicesCoordinator.swift # Daemon bootstrapping, agent symlinking & VPN setup
	│ ├── SovereignSurvivalKit.entitlements # App Sandbox & NetworkExtension entitlements
	│ ├── Info.plist # Bundle metadata & configuration
	│ ├── Assets.xcassets # Application icons, color sets & visual assets
	│ └── data/docs/SSK_Ledger_Vault/ # Auto-generated documentation store & search index
	│
	├── SSKVaultHost/ # Background Service & Launchd Daemon
	│ ├── main.swift # Standalone daemon process entry point
	│ └── com.ssk.vaulthost.plist # macOS LaunchAgent property list definition
	│
	├── SSK_DocGen/ # Standalone Documentation Generator CLI
	│ ├── Package.swift # SPM manifest for SSK_DocGen executable
	│ ├── Sources/SSK_DocGen/ # AST scanning & ledger artifact generation logic
	│ ├── README.md # DocGen worker architecture & topology
	│ ├── AGENTS.md # DocGen agent guidelines & security constraints
	│ └── SSK_DocGen_Manual_Testing_Guide.md # Verification & manual test procedures
	│
	├── XCPSSKPlugin/ # Xcode Developer Plug-in Target
	│ ├── XCPSSKPlugin.swift # Xcode integration & MCP service bridge
	│ └── ssk-intelligence-plugin.json # Plug-in capability manifest
	│
	├── ClipLiveActivities/ # WidgetKit & Live Activity Target
	│ ├── ClipLiveActivities.swift # Widget configuration & timeline provider
	│ ├── ClipLiveActivitiesBundle.swift # Widget bundle entry point
	│ └── AppIntent.swift # Background Live Activity control intents
	│
	├── SovereignSurvivalKitIntents/ # Siri App Intents Target
	├── SovereignSurvivalKitIntentsUI/ # Siri Snippet UI Overlay Extension Target
	├── SovereignSurvivalKitMeshClip/ # App Clip Target (Zero-install mesh workflows)
	├── SovereignSurvivalKitMessenger/ # iMessage Application Target
	├── SovereignSurvivalKitMessenger MessagesExtension/ # Messages Extension Target (P2P asset transfer)
	├── IntegrationTests/ # Xcode Project Integration Test Bundle
	└── SovereignSurvivalKit.xcodeproj/ # Primary multi-platform Xcode project
	```

	---

	## 3. Modular Swift Packages (`Modules/`)

	The architecture uses 10 local Swift packages in [`Modules/`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules). Each module maintains its own `Package.swift`, unit tests, and documentation.

	\| Module \| Summary and Responsibilities \| Internal Dependencies \|
	\| :--- \| :--- \| :--- \|
	\| [`SSK_Physics`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Physics) \| Computes multi-dimensional $\tau$-tensors, amodal state inversion, and reverse provenance deviation checks using Metal GPU shaders and Accelerate `vDSP`. \| None \|
	\| [`SSK_Abstractions`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Abstractions) \| Defines the architectural backbone: entity contracts (`SemanticAppEntity`), GRDB SQLite migrations, MultiTau control theory (`TelemetryEngine`), process algebra (CCS/LTS), and protocol schemas (ACP/UCP). \| `SSK_Physics`, `GRDB.swift` \|
	\| [`SSK_Foundation`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Foundation) \| Implements multi-tier storage (`StorageCoordinator`), SQLite persistence (`DatabaseManager`), Keychain management (`VaultKeyManager`), encrypted `.sparsebundle` volumes, Finder integration, `.loreignore` evaluation (`LoreIgnore`), and XPC IPC (`XPCBridge`). \| `SSK_Abstractions`, `swift-syntax`, `swift-sdk` (MCP) \|
	\| [`SSK_Demucs_MLX`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Demucs_MLX) \| Neural music source separation engine utilizing the Hybrid Transformer Demucs (HTDemucs) model on Apple Silicon via `mlx-swift`. Isolates Vocals, Drums, Bass, and Other stems. \| `mlx-swift` (`MLX`, `MLXNN`, `MLXRandom`, `MLXOptimizers`) \|
	\| [`SSK_Hardware`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Hardware) \| Manages low-level audio telemetry pipelines, 12-bin FFT chromagrams, $\tau$-dynamics calculations, parallel subframe telemetry extraction, and CoreMedia `MusicUnderstanding` pre-processing. \| `SSK_Abstractions`, `SSK_Foundation`, `SSK_Demucs_MLX`, `SSK_Physics` \|
	\| [`SSK_Providers`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Providers) \| Delivers concrete implementations: Foundation Models, on-device MLX LLMs, Zero-Knowledge identity (`ZKIdentityService`), post-quantum ML-DSA signatures, WireGuard VPN tunneling, TDLib client (`CTDLib`), C++ driving license verification (`CLongfellow`), and `SSK_StorageHost` daemon. \| `SSK_Foundation`, `SSK_Abstractions`, `SSK_Hardware`, `swift-syntax`, `swift-nio*`, `swift-crypto`, `swift-certificates`, `CLongfellow`, `CTDLib`, `swift-sdk` \|
	\| [`SSK_Orchestrator`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Orchestrator) \| Central intake and coordination engine: `IngestionCoordinator` (AST and DocC extraction), `AggregatorManager`/`AggregatorActor` (biometric vault access), real-time RTC carrier clock (`SystemOrchestrator`), P2P mesh discovery, and `WorkflowSupervisor`. Includes `SSK_IngestionTester` CLI. \| `SSK_Abstractions`, `SSK_Foundation`, `SSK_Providers`, `SSK_Hardware`, `SSK_Physics`, `swift-sdk` \|
	\| [`SSK_Intents`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_Intents) \| Provides shared intent handling models and routes execution to the main application intent targets. \| `SSK_Orchestrator` \|
	\| [`SSK_UI`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_UI) \| Presentation layer: Offline UCP commerce search (`CommerceSearchView`), multi-format asset quicklook (`QuickLookBrowserView`), chromagram node visualizer (`TimeCapsuleNodeView`), dynamic canvas (`TopographicalCanvas`), and PIN erasure (`PinEntryView`). \| `SSK_Foundation`, `SSK_Providers`, `SSK_Orchestrator`, `SSK_Hardware` \|
	\| [`SSK_IntegrationTests`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/Modules/SSK_IntegrationTests) \| Comprehensive end-to-end integration and UI test suite evaluating cross-module interactions, synchronization, and intent workflows. \| All Modules \|

	---

	## 4. Standalone Tools and Background Daemons

	### 1. `SSKVaultHost` (`SSKVaultHost/`)
	- Type: Background launchd daemon and lifecycle service.
	- Function: Hosts the local HTTP/3 QUIC storage server on macOS, managed via `SMAppService` and registered using `com.ssk.vaulthost.plist`.
	- Inter-Process Communication: Serves as the XPC Mach service endpoint responding to main app requests and coordinating VPN network configuration.

	### 2. `SSK_DocGen` (`SSK_DocGen/`)
	- Type: Private documentation generator and resource worker CLI.
	- Function: Scans codebase AST structures and generates documentation ledger artifacts (`docc_index.json`, `graph.json`, and Markdown specifications).
	- Protocol: Interfaces with approved MCP clients through `SSK_StorageHost acp-agent` over standard I/O and typed XPC commands (`DocGenHostCommand`).
	- Roadmap: See [next/dev/SSK_DOCGEN_PHASE_ROADMAP.md](file:///Users/voxels/SovereignSurvivalKit/next/dev/SSK_DOCGEN_PHASE_ROADMAP.md).

	### 3. `XCPSSKPlugin` (`XCPSSKPlugin/`)
	- Type: Xcode Developer Plug-in (`.xcplugin`).
	- Function: Bridges Apple Xcode Coding Intelligence features directly to local ACP agents (`SSK_StorageHost acp-agent`) for AI assistance, documentation inspection, and codebase indexing.

	---

	## 5. Main Application and System Extensions

	### [`SovereignSurvivalKit`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit) (Main App Container)
	- Entry Point: [`SovereignSurvivalKitApp.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/SovereignSurvivalKitApp.swift) initializes the application lifecycle, registers MetricKit subscribers, handles OS process termination signals (`SIGINT`, `SIGTERM`), and presents primary navigation (`MainContentView`).
	- Services Bootstrapping: [`ServicesCoordinator.swift`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/ServicesCoordinator.swift) starts the background daemon, symlinks the stable agent executable (`~/Library/Application Support/SovereignSurvivalKit/Agent/SSK_Agent` -> `/usr/local/bin/SSK_StorageHost`), connects XPC channels, and configures OS WireGuard VPN profiles (`NETunnelProviderManager`).

	### Extension Targets
	- `ClipLiveActivities`: WidgetKit extension presenting Live Activities for vault status and background processing via [`VaultLiveActivityIntent`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/ClipLiveActivities/AppIntent.swift).
	- `SovereignSurvivalKitIntents` & `SovereignSurvivalKitIntentsUI`: Provides system-level Siri and Shortcuts integrations with custom snippet UI views.
	- `SovereignSurvivalKitMeshClip`: Lightweight App Clip target enabling quick peer pairing and zero-installation mesh communication.
	- `SovereignSurvivalKitMessenger` & `MessagesExtension`: iMessage extension for sharing encrypted assets, transaction summaries, and verifiable credentials.

	---

	## 6. Architecture and Dependency Flow

	```mermaid
	graph TD
	subgraph Presentation & Entry
	APP[SovereignSurvivalKit App Target]
	EXT[Extensions: Clip, Intents, Messages, Widgets]
	UI[SSK_UI]
	INTENTS[SSK_Intents]
	end

	subgraph Orchestration & Intake
	ORCH[SSK_Orchestrator]
	DOCGEN[SSK_DocGen]
	end

	subgraph Service & Hardware Providers
	PROV[SSK_Providers]
	HW[SSK_Hardware]
	DEMUCS[SSK_Demucs_MLX]
	end

	subgraph Core Foundation & Abstractions
	FOUND[SSK_Foundation]
	ABS[SSK_Abstractions]
	PHYS[SSK_Physics]
	end

	APP --> UI
	APP --> ORCH
	APP --> FOUND
	APP --> ABS
	EXT --> ORCH

	UI --> ORCH
	UI --> PROV
	UI --> HW
	UI --> FOUND

	INTENTS --> ORCH
	DOCGEN --> ORCH

	ORCH --> PROV
	ORCH --> HW
	ORCH --> FOUND
	ORCH --> ABS
	ORCH --> PHYS

	PROV --> HW
	PROV --> FOUND
	PROV --> ABS

	HW --> DEMUCS
	HW --> FOUND
	HW --> ABS
	HW --> PHYS

	FOUND --> ABS
	ABS --> PHYS
	```

	---

	## 7. Master Build and Installation Lifecycle

	Use the unified scripts in `scripts/` from the repository root:

	### 1. Master Build and Installation (Standard)
	```bash
	# Full clean build and system installation
	./scripts/install.sh --clean

	# Clean build without system installation
	./scripts/install.sh --build-only --clean

	# Direct installation from existing dist/ artifacts
	./scripts/install.sh --install-only

	# Uninstall applications, CLI tools, and plug-ins
	./scripts/install.sh --uninstall

	# Clean build and reset application databases, vaults, and caches
	./scripts/install.sh --clean --reset-data
	```

	### 2. Multi-Platform Build Conditioning Rules
	- macOS Desktop Schemes: Build `SovereignSurvivalKit`, `SSKVaultHost`, and `XCPSSKPlugin` using destination `generic/platform=macOS`.
	- iOS-Only Extensions: Target dependencies such as `SovereignSurvivalKitMeshClip`, `ClipLiveActivities`, `SovereignSurvivalKitIntents`, and `SovereignSurvivalKitMessenger` have `platformFilter = ios;` configured in `project.pbxproj` and are excluded during macOS desktop builds.

	### 3. Installation Target Destinations

	\| Component \| Direct Script Install (`install_dist.sh`) \| Signed Package (`build_pkg.sh` / `.pkg`) \|
	\| :--- \| :--- \| :--- \|
	\| Desktop Applications \| `/Applications/SovereignSurvivalKit.app`<br>`/Applications/SSKVaultHost.app` \| `/Applications/SovereignSurvivalKit.app`<br>`/Applications/SSKVaultHost.app` \|
	\| CLI Binaries \| `/usr/local/bin/SSK_StorageHost`<br>`/usr/local/bin/SSK_DocGen`<br>`/usr/local/bin/SSKVaultHost` \| `/usr/local/bin/SSK_StorageHost`<br>`/usr/local/bin/SSK_DocGen`<br>`/usr/local/bin/SSKVaultHost` \|
	\| Shell Paths \| `/etc/paths.d/SovereignSurvivalKit` \| `/etc/paths.d/SovereignSurvivalKit` \|
	\| Xcode Plug-in \| `~/Library/Developer/Xcode/Plug-ins/XCPSSKPlugin.xcplugin` \| `/Library/Application Support/Developer/Shared/Xcode/Plug-ins/XCPSSKPlugin.xcplugin` \|

	---

	## 8. Documentation Ledger Vault (`data/docs/SSK_Ledger_Vault`)

	The repository maintains an automated documentation ledger in [`SovereignSurvivalKit/data/docs/SSK_Ledger_Vault/`](file:///Users/voxels/SovereignSurvivalKit/src/SovereignSurvivalKit/SovereignSurvivalKit/data/docs/SSK_Ledger_Vault):

	- `docc_index.json`: Search index mapping symbols, structs, functions, and protocols to source file paths and line numbers.
	- `graph.json`: Structural dependency and semantic relationship graph across all framework components.
	- `DocC_Index.md`: Master index linking human-readable entity specifications for all documented symbols.

	---

	## 9. Security, Privacy, and Cryptography Boundaries

	- Local Storage Encryption: AES-GCM 256-bit encryption with key material stored in the macOS Keychain (`VaultKeyManager`) or backed by the Apple Secure Enclave (`SecureEnclaveManager`).
	- Zero-Knowledge Authentication: Peer authentication verified through `ZKIdentityService` and native C++ driving license verification (`CLongfellow`).
	- Post-Quantum Signatures: Digital signatures computed with Module-Lattice-Based Digital Signature Algorithm (`MLDSASigner`).
	- Network Privacy: Isolated mesh subnet (`10.0.0.0/24`) over WireGuard tunnels and mTLS encrypted QUIC streams.
	- Secure Memory Sanitization: Cryptographic keys wrapped in `EphemeralKeyHolder` with zeroization on deallocation.

	---

	## 10. Troubleshooting

	### Dependency Resolution and Permission Errors
	During the execution of `./scripts/install.sh --clean` or `xcodebuild -resolvePackageDependencies`, if permission errors or file lock conflicts occur:

	1. Stop active Xcode and build processes:
	```bash
	killall Xcode xcodebuild 2>/dev/null \|\| true
	```
	2. Restore write permissions and clear DerivedData:
	```bash
	chmod -R u+w ~/Library/Developer/Xcode/DerivedData/SovereignSurvivalKit-* 2>/dev/null \|\| true
	rm -rf ~/Library/Developer/Xcode/DerivedData/SovereignSurvivalKit-*
	```
	3. Restart the build pipeline with package refresh:
	```bash
	./scripts/install.sh --clean --refresh-packages
	```