LOCALHOST1978/Modules/SSK_Abstractions/ARCHITECTURE.md

Architecture of SSK_Abstractions

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_Abstractions is the foundational contract module of the SovereignSurvivalKit architecture. It defines domain entities, database records, process algebra primitives, time-to-contact telemetry math, knowledge graph structures, and subsystem interfaces (Hardware, Intelligence, Intent, Orchestration, and ACP/UCP protocols).

By separating interfaces and data structures from concrete operational implementations, SSK_Abstractions provides strict decoupling and strong type safety across the framework.

---

2. Package Specifications and Dependencies

As defined in Package.swift:

• Target Name: SSK_Abstractions
• Swift Tools Version: 6.4
• Supported Platforms: macOS 27.0+, iOS 27.0+
• Internal Dependencies:
  • SSK_Physics — Provides physics models, telemetry primitives, and amodal measurement definitions.
• External Dependencies:
  • GRDB.swift (6.24.2+) — SQLite database persistence layer, record definitions, and schema migrators.
• Compiler and Linker Settings:
  • Defines ACCELERATE_NEW_LAPACK for modern LAPACK routines.
  • Links Apple Accelerate.framework (vDSP, cblas, LAPACK matrix routines).

---

3. Component Architecture and Source Layout

The source files in Sources/SSK_Abstractions/ are grouped into functional domains:

Sources/SSK_Abstractions/
├── Data & Storage/
│   ├── EntityContracts.swift          # Core semantic entities, CRDT LWW state, sync anchors
│   ├── GRDBSchema.swift               # GRDB SQLite table records & SSKCoreMigrations
│   ├── FileEntityProtocol.swift       # Disk file entity protocol & operations
│   ├── VaultStorageProvider.swift     # Vault mounting & remote storage provider protocol
│   ├── VaultConfigurationProtocol.swift # Vault configuration interface contracts
│   └── SaveDetails.swift              # File mutation status & persistence metadata
│
├── Telemetry & Mathematical Control/
│   ├── MultiTauState.swift            # Time-to-contact dynamic gap states & Accelerate TelemetryEngine
│   ├── EdgcumbeTypes.swift            # Process algebra operators & binary sequence serialization
│   ├── LTS.swift                      # Labelled Transition Systems, CCS events & silent transitions
│   ├── BaseManifold.swift             # Shadow model pattern for manifold geometry
│   ├── HybridLogicalClock.swift       # Causality tracking & hybrid logical timestamps
│   └── PipelineTelemetry.swift        # Pipeline telemetry collection types
│
├── Subsystem Protocols & Interfaces/
│   ├── HardwareProtocols.swift        # Audio telemetry pipeline & music understanding contracts
│   ├── IntelligenceProtocols.swift    # Foundation model/MLX generation protocols & transcript streaming
│   ├── IntentProtocols.swift          # Siri App Intent management & semantic entity querying
│   ├── OrchestratorProtocols.swift    # P2P orchestration state machine & ZK identity management
│   ├── InterfaceProtocols.swift       # AST extraction, embeddings, and spec intelligence contracts
│   ├── MeshNetworkProtocols.swift     # P2P mesh network communication protocols
│   ├── VPNProviderConfiguration.swift # WireGuard mesh VPN configuration DTO for XPC messaging
│   └── IdentitySettlementProtocol.swift # Bilateral identity settlement interfaces
│
├── Agent Client & DocGen Contracts/
│   ├── ACPSynthesisProtocol.swift     # Agent Client Protocol synthesis interface
│   ├── AudioACPContract.swift         # Audio ingestion ACP contracts & request definitions
│   ├── AudioArtifactManifest.swift    # Audio artifact metadata & cryptographic manifests
│   ├── AudioIngestionJob.swift        # Audio ingestion job state & progress structures
│   ├── AudioIngestionRequest.swift    # Audio ingestion request data types
│   ├── AudioIngestionWidgetModel.swift # Bound model for Siri & Shortcuts ingestion snippet UI
│   ├── DocGenHostCommand.swift        # DocGen XPC commands, actions & process control DTOs
│   ├── DocGenWorkerExecuting.swift    # Interface for launching isolated DocGen workers
│   ├── RemoteAudioArtifactTransport.swift # Transport interfaces for remote audio artifact sync
│   └── PromptPayload.swift            # Prompt delivery structures & context bundles
│
└── Knowledge Graphs & Domain Models/
    ├── SemanticGraph.swift            # Knowledge graph entities, relationships & async decoder actor
    ├── SemanticTriple.swift           # Subject-predicate-object semantic triples
    ├── AxiomModels.swift              # Axiom manifests, concept anchors & archives
    ├── AxiomArchiving.swift           # Protocol for writing and reading axiom archives
    ├── AxiomTranslator.swift          # Translator for axiom graph nodes
    ├── KassetModel.swift              # Universal media items, audio segments, UCP commerce
    ├── PipelineOutput.swift           # Pipeline output manifests and result payloads
    ├── PipelineOutputTypes.swift      # Ingestion pipeline outputs (DocC index, heading mappings)
    ├── PipelineError.swift            # Pipeline error enumeration and mitigation types
    ├── SpecificationRegistration.swift# Protocol specification registry (ACP-1.0, IEEE-2030.1)
    ├── GeneratedACPSchemas.swift      # Generated Agent Client Protocol (ACP) schemas
    ├── GeneratedUCPSchemas.swift      # Generated Universal Commerce Protocol (UCP) schemas
    ├── SSKURI.swift                   # Canonical URI parser and validator (ssk:// scheme)
    ├── Identity.swift                 # Identity domain models and public key containers
    ├── StandardBody.swift             # Standard body definitions and compliance models
    └── AggregatorError.swift          # Error domain for aggregator and storage coordinators

---

4. Key Functional Areas

1. Domain Entities, Persistence, and Security

• EntityContracts.swift: Defines SemanticAppEntity, LWWState, CRDTConflictResolver, SyncAnchor, SparsebundleConfig, and EphemeralKeyHolder.
• GRDBSchema.swift: Defines GRDB PersistableRecord mappings (SemanticAppEntityRecord, ConversationRecord, MessageRecord, HealthEventRecord, TransactionRecord) and database migrations via SSKCoreMigrations.
• SSKURI.swift: Implements standard URI syntax parsing for ssk:// resources (specifications, ledgers, audio time capsules, and mesh peers).

2. Telemetry and Dynamic Control Physics

• MultiTauState.swift: Models time-to-contact ($\tau = -x / \dot{x}$) and tau-dot ($\dot{\tau}$) dynamics. Uses Apple Accelerate (vDSP_convD, cblas_dgemm, LAPACK dgetrf_ / dgetri_) for polynomial smoothing.
• EdgcumbeTypes.swift & LTS.swift: Implements process algebra operators (sequential, choice, parallel, restriction) and Labelled Transition System primitives with compact binary serialization.

3. Agent Client Protocol (ACP) and Audio Contracts

• AudioACPContract.swift & AudioIngestionJob.swift: Defines ACP messages for post-production audio intake, stem separation jobs, and progress reporting.
• AudioIngestionWidgetModel.swift: Formats completed intake results into visual structures for SwiftUI snippets in Siri and Shortcuts.
• DocGenHostCommand.swift & DocGenWorkerExecuting.swift: Defines typed XPC command and response payloads for background documentation generation.

---

5. Architectural Position

+-------------------------------------------------------------------+
|               App / UI Layer & ServicesCoordinator                |
+---------------------------------+---------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                         SSK_Abstractions                          |
|  - Entity & GRDB Schemas          - MultiTau & Control Physics    |
|  - System Protocols & Interfaces  - Process Algebra & LTS         |
|  - Semantic Knowledge Graphs      - ACP / UCP Protocol Schemas    |
|  - DocGen & Audio ACP Contracts   - SSKURI Canonical Parser       |
+---------------------------------+---------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                            SSK_Physics                            |
|                 (Amodal Inversion & Physics Base)                 |
+-------------------------------------------------------------------+