LOCALHOST1978/Modules/SSK_Orchestrator/ARCHITECTURE.md

Architecture Overview: SSK_Orchestrator

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_Orchestrator is the central coordination module of the SovereignSurvivalKit architecture. It integrates multi-source ingestion pipelines, audio intake runtimes, off-grid peer-to-peer mesh networking, biometric vault authorization, real-time carrier clock tracking, and background documentation generation.

---

2. Package Structure and Targets

Defined in Package.swift:

Target	Type	Description
SSK_Orchestrator	Swift Library	Core orchestration engine, workflow supervisor, audio runtime, and network coordinators.
SSK_IngestionTester	Swift Executable	Headless command-line utility for testing audio time capsule ingestion and pipeline stages.
SSK_OrchestratorTests	Test Target	Unit tests for orchestration state machines, intake flows, and pipeline runners.

---

3. Directory Layout and Components

SSK_Orchestrator/
├── Package.swift
├── ARCHITECTURE.md
└── Sources/
    ├── SSK_Orchestrator/
    │   ├── Ingestion & Documentation Pipeline/
    │   │   ├── IngestionCoordinator.swift           # Primary intake engine for code, text & audio
    │   │   ├── PipelineRunner.swift                 # High-performance vDSP vector search runner
    │   │   ├── DocGenDaemon.swift                   # Background daemon supervisor for DocGen
    │   │   └── DocGenLedger.swift                   # Ledger manifest generator & path validator
    │   │
    │   ├── Audio Ingestion Runtime & ACP Routing/
    │   │   ├── AudioIngestionRuntime.swift          # Main runtime coordinator for post-production audio
    │   │   ├── AudioIngestionRuntimeDependencies.swift # Dependency container for audio ingestion
    │   │   ├── AudioIngestionSourceResolver.swift   # Resolves file bookmarks & security scopes
    │   │   ├── AudioACPCommandRouter.swift          # Routes Agent Client Protocol audio requests
    │   │   ├── AudioPipelineProgressSink.swift      # Async progress reporter for audio tasks
    │   │   └── AudioPipelineResult.swift            # Final output container for completed intake
    │   │
    │   ├── Storage & Vault Coordination/
    │   │   ├── AggregatorManager.swift              # Vault selection, biometric authorization & state
    │   │   ├── AggregatorActor.swift                # Actor-isolated database and vault transaction manager
    │   │   └── AppModel.swift                       # @MainActor @Observable root UI state binding
    │   │
    │   ├── Carrier Clock & Physics Orchestration/
    │   │   └── SystemOrchestrator.swift             # Real-time clock phase-locked to audio sample rate
    │   │
    │   ├── Multi-Stage Workflow Supervision/
    │   │   └── WorkflowSupervisor.swift             # 3-stage lifecycle supervisor (Intake, Retrain, Mint)
    │   │
    │   ├── Off-Grid Mesh Networking/
    │   │   ├── P2PMeshOrchestrator.swift            # Server (NWListener) & client (NWBrowser) mesh engine
    │   │   └── SecureMeshCoordinator.swift          # Zero-knowledge identity validator for mesh peers
    │   │
    │   ├── Acoustic Capture & Matching/
    │   │   ├── AudioCaptureService.swift            # 96kHz mono PCM microphone audio capture
    │   │   └── AudioMatcherService.swift            # ShazamKit acoustic fingerprint matching
    │   │
    │   └── Configuration/
    │       └── OrchestratorConfiguration.swift      # Global orchestration settings and thresholds
    │
    └── SSK_IngestionTester/
        └── main.swift                               # CLI testing entry point for mock pipelines

---

4. Key Subsystems and Responsibilities

1. Ingestion and Documentation Coordinator (IngestionCoordinator.swift)

• Extracts AST tensors (BaseManifoldTensor) and DocC entities (DoccEntity) from source code.
• Generates dependency graphs (graph.json), search indices (docc_index.json), and Markdown specifications (DocC_Index.md).
• Processes .wav audio time capsules and archives them into encrypted storage vaults.

2. Audio Ingestion Runtime (AudioIngestionRuntime.swift)

• Orchestrates post-production audio intake from system App Intents (IngestAudioIntent).
• Validates security-scoped file bookmarks via AudioIngestionSourceResolver.
• Emits progress events through AudioPipelineProgressSink and returns AudioIngestionWidgetModel for Siri/Shortcuts UI snippets.

3. Biometric Vault Storage (AggregatorManager.swift & AggregatorActor.swift)

• Enforces biometric authentication using LocalAuthentication (LAContext).
• Coordinates database queries and encrypted volume operations with StorageCoordinator.

4. P2P Mesh Networking (P2PMeshOrchestrator.swift)

• Discovers nearby peers over UDP/QUIC (_ssk-mesh._udp) using Apple Network.framework.
• Authenticates peer connections using zero-knowledge proofs via SecureMeshCoordinator.

---

5. Module Dependencies

Internal Package Dependencies

• SSK_Abstractions: Abstract protocol definitions and domain models.
• SSK_Foundation: Memory stores, file system models, and XPC bridges.
• SSK_Providers: Concrete intelligence providers, AST parsers, and HTTP/3 daemons.
• SSK_Hardware: Low-level audio telemetry pipelines and MLX models.

External Swift Packages

• swift-sdk (MCP): Model Context Protocol server and client integration.

System Frameworks

• AVFoundation & ShazamKit: Audio capturing and acoustic fingerprinting.
• Network: Peer discovery and QUIC mesh networking.
• LocalAuthentication: Biometric security enforcement.
• Observation: Reactive @Observable UI bindings.

---

6. Architectural Position

                           SSK_Abstractions
                                  ▲
                                  │
+---------------------------------+---------------------------------+
|                        SSK_Orchestrator                           |
|  - IngestionCoordinator           - AudioIngestionRuntime         |
|  - AggregatorManager (Biometrics) - P2PMeshOrchestrator           |
|  - SystemOrchestrator (Clock)     - WorkflowSupervisor            |
+---------------------------------+---------------------------------+
         ▲                        ▲                        ▲
         │                        │                        │
   SSK_Foundation            SSK_Providers            SSK_Hardware