localhost1978/localhost/LOCALHOST1978 - Storage Bucket

SovereignSurvivalKit Source Root

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

---

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

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/. Each module maintains its own Package.swift, unit tests, and documentation.

Module	Summary and Responsibilities	Internal Dependencies
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	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	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	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	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	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	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	Provides shared intent handling models and routes execution to the main application intent targets.	SSK_Orchestrator
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	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.

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 (Main App Container)

• Entry Point: 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 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.
• 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

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)

# 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 /Applications/SSKVaultHost.app	/Applications/SovereignSurvivalKit.app /Applications/SSKVaultHost.app
CLI Binaries	/usr/local/bin/SSK_StorageHost /usr/local/bin/SSK_DocGen /usr/local/bin/SSKVaultHost	/usr/local/bin/SSK_StorageHost /usr/local/bin/SSK_DocGen /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/:

• 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:

   killall Xcode xcodebuild 2>/dev/null || true
   

2. Restore write permissions and clear DerivedData:

   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:

   ./scripts/install.sh --clean --refresh-packages