🔄 Bi-Directional Live Synchronization Engine

---

1. Bi-Directional Architecture

sequenceDiagram
    participant Code as Rust Codebase (ops/core/economy)
    participant Engine as LiveDocEngine (ops/live_docs)
    participant Wiki as Markdown Wiki (docs/wiki/)
    participant K8s as Kubernetes CRD (apex-cortex)
    participant Valkey as Valkey SSOT (valkey-broker:6379)

    Note over Code,Wiki: 1. Code-to-Docs (AST Introspection)
    Engine->>Code: Scans workspace crates, routes, REPL commands
    Engine->>Wiki: Updates API-Reference.md & REPL-Commands.md
    Engine->>K8s: Applies DocumentationArtifact CRDs
    Engine->>Valkey: Caches live pages at docs:sovereign:*

    Note over Code,Wiki: 2. Docs-to-Code (Contract Validation)
    Engine->>Wiki: Parses documented routes & CLI commands
    Engine->>Code: Verifies handler bindings in http_gateway & runtime_shell
    alt Drift Detected
        Engine-->>Operator: Emits Drift Warning (Audit Report)
        Engine-->>Code: Proposes code contract migrations
    else Perfect Parity
        Engine-->>Operator: 100% Isomorphism Verified
    end

---

2. Invalidation & Reconciliation Cycle

1. **Continuous AST Extraction**:

- DocExtractor parses ops/http_gateway/src/main.rs to extract all .route("/path", method(handler)) definitions.

- DocExtractor parses ops/runtime_shell/src/main.rs to extract all CLI command branches and descriptions.

- DocExtractor reads workspace Cargo.toml to catalog all member crates.

2. **Contract Audit (DocValidator)**:

- Compares the extracted code AST with markdown tables in docs/wiki/API-Reference.md and docs/wiki/REPL-Commands.md.

- Computes a drift score $\delta \in [0.0, 1.0]$. If $\delta > 0$, the audit logs missing or undocumented items.

3. **Multi-Target Publishing (DocPublisher)**:

- Generates/updates local markdown files in docs/wiki/.

- Compiles Kubernetes CRD manifests (DocumentationArtifact) in k8s/docs/documentation-artifacts.yaml.

- Updates in-memory HTTP cache in ops/http_gateway for instant sub-millisecond serving at GET /docs.