LOCALHOST1978/SSK_DocGen/ARCHITECTURE.md

SSK_DocGen 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 Architectural Role

SSK_DocGen is a private, isolated documentation generation and resource extraction CLI worker in the SovereignSurvivalKit architecture.

It operates behind strict security boundaries:

1. External clients (such as Xcode Coding Intelligence or approved MCP clients) communicate exclusively with SSK_StorageHost acp-agent via stdio.
2. SSK_StorageHost sends typed XPC requests to SSKVaultHost across com.ssk.vaulthost.
3. SSKVaultHost validates caller code signatures, team identifiers, and audit tokens.
4. SSKVaultHost executes SSK_DocGen as a private subprocess to perform descriptor-relative, non-symlink reads and AST documentation generation into SSK_Ledger_Vault.

Xcode or Approved MCP Client
  │ (stdio)
  ▼
SSK_StorageHost acp-agent (External MCP Facade)
  │ (com.ssk.vaulthost Mach XPC)
  ▼
SSKVaultHost Daemon (Validates Audit Token & Code Signature)
  │ (Private Subprocess Execution)
  ▼
SSK_DocGen (Isolated Resource Worker)
  │ (Descriptor-Relative Read)
  ▼
Approved Documentation Ledger (SSK_Ledger_Vault)

---

2. Package Specifications and Dependencies

Defined in Package.swift:

• Package Name: SSK_DocGen
• Swift Tools Version: 6.4
• Supported Platforms: macOS 27.0+, iOS 27.0+
• Internal Package Dependencies:
  • SSK_Orchestrator (../Modules/SSK_Orchestrator) — Ingestion pipeline and AST coordinator (IngestionCoordinator).
  • SSK_Abstractions (../Modules/SSK_Abstractions) — Entity contracts, DocGen commands, and canonical URIs (SSKURI).
  • SSK_Providers (../Modules/SSK_Providers) — SwiftSyntax parser and redactor engines.
  • SSK_Foundation (../Modules/SSK_Foundation) — Storage and XPC command primitives.

---

3. Directory Layout and Components

src/SovereignSurvivalKit/SSK_DocGen/
├── Package.swift
├── ARCHITECTURE.md
├── README.md
├── SSK_DocGen_Manual_Testing_Guide.md
└── Sources/
    └── SSK_DocGen/
        ├── main.swift                 # CLI entry point, argument parser & execution loop
        ├── ACPService.swift           # Core ACP service handling ledger generation & queries
        ├── ACPRegistry.swift          # Registry of approved documentation ledger resources
        ├── ACPResourceReader.swift    # Sandboxed descriptor-relative file reader
        ├── ACPSecurity.swift          # Path containment validator & sanitization engine
        ├── ACPRequestContext.swift    # Request context container with audit metadata
        └── CLIConfiguration.swift     # CLI flags, path resolvers & configuration loader

---

4. Key Subsystems

1. ACPResourceReader.swift & ACPSecurity.swift

• No-Symlink Traversal: Enforces strict descriptor-relative directory traversal, preventing symlink escapes outside operator-approved ledger roots.
• Double Redaction: Ensures source tokens and sensitive paths undergo redaction before output.

2. ACPRegistry.swift

• Exposes approved logical documentation URIs:
  • ssk://spec:SSK-DocGen-P0/ledger/documentation/docc-index (docc_index.json)
  • ssk://spec:SSK-DocGen-P0/ledger/documentation/codebase-graph (graph.json)
  • ssk://spec:SSK-DocGen-P0/ledger/documentation/master-index (DocC_Index.md)

3. ACPService.swift

• Interacts with IngestionCoordinator to perform complete AST code analysis across the repository, generating searchable indexes in staging prior to atomic ledger deployment.

---

5. Architectural Position

                        SSKVaultHost
                             │
                             ▼ (Subprocess Invocation)
                        SSK_DocGen
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
   SSK_Orchestrator    SSK_Abstractions    SSK_Foundation