LOCALHOST1978/Modules/SSK_Providers/ARCHITECTURE.md

SSK_Providers Architecture

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_Providers is the concrete service and provider implementation layer within the SovereignSurvivalKit architecture. It provides implementations for the abstract protocols defined in SSK_Abstractions, covering on-device intelligence, zero-knowledge identity, encrypted network tunnels, GPU/CPU matrix inversion solvers, HTTP/3 QUIC artifact transport, and external Model Context Protocol (MCP) facades.

---

2. Package Targets and Products

Defined in Package.swift:

Target	Type	Description
SSK_Providers	Swift Library	Core provider implementations for intelligence, cryptography, networking, and matrix math.
CTDLib	C Target	C header wrapper target for Telegram TDLib JSON client bindings (td_json_client.h).
SSK_StorageHost	Swift Executable	Standalone server daemon providing HTTP/3 QUIC file transfers and the external acp-agent MCP facade.
SSK_ProvidersTests	Test Target	Unit tests for provider services, cryptographic routines, and network tunnels.

---

3. Subsystems and Source Structure

The source files in Sources/SSK_Providers/ are structured into functional domains:

Sources/SSK_Providers/
├── Intelligence & Model Inference/
│   ├── FoundationModelsProvider.swift   # Apple Foundation Models interface
│   ├── MLXLocalProvider.swift          # On-device MLX model execution
│   ├── MLXHuggingFaceProvider.swift     # Hugging Face MLX model downloader & runner
│   ├── NativeIntelligenceEngine.swift   # Query routing across local and remote models
│   ├── IntelligenceProviderRouter.swift # Dynamic task dispatcher for LLM requests
│   ├── ContextBudgetManager.swift       # Token and context window budget calculator
│   ├── DynamicSchemaInterpreter.swift   # Dynamic schema evaluation and extraction
│   ├── DynamicSkillIngestionModule.swift # Runtime skill and prompt module ingestion
│   ├── IdiolectTrainingService.swift    # Personal token training & adaptation
│   ├── PromptInjectionDetector.swift    # Security filter detecting adversarial prompts
│   ├── NLEmbeddingProvider.swift        # NaturalLanguage framework vector embeddings
│   ├── NLTaggerExtractor.swift          # Part-of-speech and entity tagging
│   ├── ModelDownloadService.swift       # Model artifact download and checksum manager
│   ├── ContentAnalysisService.swift     # Content classification and entity analysis
│   └── IntelligenceErrors.swift         # Error domain for intelligence providers
│
├── Syntax & Code Extraction/
│   ├── NativeASTProvider.swift          # SwiftSyntax source code parser & entity extractor
│   ├── ASTExtractionService.swift       # AST extraction service wrapper
│   ├── LangChainTripleExtractor.swift   # Subject-predicate-object triple extraction
│   ├── SemanticTagExtractor.swift       # Code semantic tag annotator
│   └── TripleEmbeddingPipeline.swift    # Vector embedding pipeline for semantic triples
│
├── Cryptography & Zero-Knowledge Identity/
│   ├── ZKIdentityService.swift          # Zero-knowledge proof generation & verification
│   ├── MLDSASigner.swift                # Post-quantum digital signatures (ML-DSA)
│   ├── SecureEnclaveManager.swift       # Apple Secure Enclave key generation & attestation
│   ├── CryptographicSealer.swift        # Symmetric payload encryption and sealing
│   ├── CertificateBootstrap.swift       # X.509 certificate generation via swift-certificates
│   ├── HPKEManager.swift                # Hybrid Public Key Encryption (HPKE) manager
│   ├── MASHAuditor.swift                # Cryptographic proof auditing & integrity gate
│   ├── VerificationGate.swift           # Access control verification rules
│   └── BilateralSettlement.swift        # Peer-to-peer cryptographic settlement protocol
│
├── Networking, Mesh & Tunnels/
│   ├── WireGuardTunnelManager.swift     # WireGuard VPN tunnel lifecycle manager
│   ├── WireGuardPacketEngine.swift      # WireGuard packet encryption & encapsulation
│   ├── IKEv2ConnectionManager.swift     # IPsec/IKEv2 VPN connection controller
│   ├── TDLibJSONClient.swift            # Async JSON bridge to low-level TDLib C bindings
│   ├── TDLibTunnelManager.swift         # TDLib transport tunnel manager
│   ├── LocalMeshDiscovery.swift         # Bonjour/mDNS local network peer discovery
│   ├── WebRTCBridge.swift               # WebRTC peer-to-peer real-time data channel
│   └── BonjourAPIHandler.swift          # Bonjour API service publisher and resolver
│
├── StorageHost Daemon & HTTP/3 Transport/
│   ├── StorageHostRunner.swift          # Main daemon execution runner for SSK_StorageHost
│   ├── StorageHostCommerceSurface.swift # Headless commerce endpoint handler
│   ├── HTTP3AudioArtifactServer.swift   # SwiftNIO HTTP/3 QUIC audio artifact server
│   ├── HTTP3AudioArtifactClient.swift   # SwiftNIO HTTP/3 QUIC audio artifact client
│   ├── DocGenMCPFacade.swift            # External MCP tool facade exposing doc resources
│   ├── DocGenHostConfigurationStore.swift # Secure configuration store for approved ledger paths
│   └── DocGenExternalRedactor.swift     # Redaction engine for data leaving MCP boundaries
│
├── System Integration & Filesystem/
│   ├── SSKFileProviderExtension.swift   # NSFileProviderReenumeratePendingSetsExtension integration
│   ├── SafariExtensionHandler.swift     # Safari web extension message bridge
│   ├── ScreenShareManager.swift         # Screen capture and frame analysis manager
│   ├── VisionProcessor.swift            # Apple Vision framework image analysis
│   ├── MediaEncoder.swift               # Multi-media audio/video encoding routines
│   ├── AxiomArchiver.swift              # Archive serialization for .axiom files
│   ├── KassetMintingService.swift       # Minting service for .kasset sovereign media
│   ├── RemoteVaultManager.swift         # Remote vault synchronization controller
│   ├── RemoteInteractionSynthesizer.swift # Synthetic event dispatcher
│   ├── LegalSyncDaemon.swift            # Regulatory and legal sync automation
│   ├── DaemonModel.swift                # State machine models for daemon processes
│   ├── DeferredEventPool.swift          # Buffer pool for asynchronous event replay
│   ├── EdgcumbeToCCSMapper.swift        # Mapper from Edgcumbe algebra to CCS processes
│   ├── EdgcumbeValidator.swift          # Structural validator for process algebra expressions
│   ├── CCSProcess.swift                 # Process algebra transition state machine
│   ├── ProvidersConfiguration.swift     # Global runtime configuration for providers
│   └── JSONLTelemetryRecorder.swift     # Structured event recorder writing JSONL logs
│
└── Matrix Acceleration & Physics Solvers/
    ├── Inverter.swift                   # High-performance matrix inversion (CPU/GPU)
    ├── MetalInversionEngine.swift       # Metal GPU compute shader matrix inverter
    ├── HybridInversionOrchestrator.swift # Dynamic CPU vs GPU solver selector
    ├── ObjectiveSolver.swift            # Mathematical objective function optimizer
    ├── ThermodynamicFolding.swift       # Thermodynamic annealing state optimizer
    └── TransitionSystem.swift           # Formal state transition solver

---

4. Dependencies

Internal Package Dependencies

• SSK_Abstractions: Abstract protocol definitions and domain models.
• SSK_Foundation: Storage coordination, XPC communication, and memory stores.
• SSK_Hardware: Low-level audio processing and sensor pipelines.

External Swift Packages

• swift-syntax: AST analysis and code parsing.
• swift-nio, swift-nio-transport-services, swift-nio-http3, swift-nio-ssl, swift-nio-quic, swift-nio-quic-helpers: Asynchronous networking and HTTP/3 QUIC server/client implementations.
• swift-crypto: Cryptographic primitives.
• swift-certificates (X509): X.509 certificate generation.
• swift-collections: Ordered collections and data structures.
• swift-argument-parser: Command-line interface parsing for SSK_StorageHost.
• swift-sdk (MCP): Model Context Protocol integration for external agent tools.

System Frameworks

• Accelerate.framework: LAPACK and BLAS linear algebra acceleration (ACCELERATE_NEW_LAPACK).
• Metal: GPU compute pipelines for parallel matrix inversion.
• NaturalLanguage & Vision: On-device entity tagging and image processing.
• FileProvider: Native Apple Files app integration.

---

5. Architectural Position

                           SSK_Abstractions
                                  ▲
                                  │
+---------------------------------+---------------------------------+
|                          SSK_Providers                            |
|  - NativeIntelligenceEngine       - ZKIdentityService             |
|  - StorageHostRunner (HTTP/3)     - WireGuardTunnelManager        |
|  - DocGenMCPFacade (MCP)          - MetalInversionEngine          |
+---------------------------------+---------------------------------+
         ▲                        ▲                        ▲
         │                        │                        │
   SSK_Foundation            SSK_Hardware             mlx-swift / NIO