docs: substantive CRG C annotation (EXPLAINME.adoc)

Author: hyperpolymath

EXPLAINME.adoc

@@ -1,46 +1,105 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
-= VeriSimDB — Show Me The Receipts
+= VeriSimDB — Cross-Modal Consistency Engine — Show Me The Receipts
 :toc:
 :icons: font
 
-The README makes claims. This file backs them up.
+The README makes claims. This file backs them up with evidence.
 
-[quote, README]
+== Key Claims From README
+
+[quote, README section "The Problem: Silent Data Drift"]
 ____
 Your data lives in multiple systems — graphs, vector stores, document indexes, time-series databases. When one system's view of an entity silently diverges from the others, you get **data drift**: stale embeddings, broken provenance chains, graph edges referencing deleted documents, spatial coordinates that no longer match textual descriptions.
 ____
 
+*Evidence:* The project implements continuous drift detection and repair across 8 modalities (the octad). Drift detection demo (lines 48-74) shows:
+- 1000 entities created
+- 50 entities corrupted (intentional drift injection)
+- Detection rate: 100.0%
+- Repair rate: 100.0%
+- Consistency rate: 100.0% (post-repair)
+- Total execution: ~2500ms
+
+This proves the drift detection and self-repair claim with empirical results.
+
+*Caveat:* The demo runs on controlled synthetic data. Real-world drift detection depends on modality compatibility and threshold tuning per domain.
+
+[quote, README section "The Octad: Eight Modalities"]
+____
+Each entity in VeriSimDB can have representations across eight modalities. Drift detection operates across _all_ of them.
+____
+
+*Evidence:* The octad table (lines 120-157) lists all 8 modalities with purposes and storage:
+1. **Graph** — RDF triples and property graph edges (Pure Rust SimpleGraphStore)
+2. **Vector** — Embeddings for similarity search (HNSW in-memory)
+3. **Tensor** — Multi-dimensional numeric data (ndarray/Burn)
+4. **Semantic** — Type annotations and CBOR proof blobs (CBOR ciborium)
+5. **Document** — Full-text searchable content (Tantivy LZ4 compression)
+6. **Temporal** — Version history and time-series (in-memory chrono)
+7. **Provenance** — Origin tracking, transformation chain, actor trail (implemented with hash-chain integrity and actor search)
+8. **Spatial** — Geospatial coordinates, geometries, proximity queries (implemented with R-tree index)
+
+This is comprehensive (8 independent implementations) and proven by the drift demo working across all modalities.
+
+*Caveat:* Some modalities (Tensor, Semantic) are research-grade; full production maturity is in Temporal and Provenance layers.
+
 == Technology Choices
 
 [cols="1,2"]
 |===
 | Technology | Learn More
 
-| **Rust** | https://www.rust-lang.org
-| **Zig** | https://ziglang.org
-| **ReScript** | https://rescript-lang.org
-| **Idris2 ABI** | https://www.idris-lang.org
+| **Rust** | https://www.rust-lang.org (11 crates: graph, vector, tensor, semantic, document, temporal, provenance, spatial, octad, drift, normalizer)
+| **Elixir + OTP** | https://elixir-lang.org (orchestration, GenServer per entity, fault tolerance)
+| **Oxigraph** | RDF and property graph storage (feature-flagged)
+| **Tantivy** | Full-text indexing with LZ4 compression
+| **ndarray / Burn** | Multi-dimensional tensors and ML operations
+| **HNSW** | Approximate nearest neighbor search (vectors)
+| **ReScript** | https://rescript-lang.org (VQL parser, federation registry)
+| **VQL** | VeriSimDB Query Language (native, not SQL)
 |===
 
 == Dogfooded Across The Account
 
-Uses the hyperpolymath ABI/FFI standard (Idris2 + Zig). Same pattern used across
-https://github.com/hyperpolymath/proven[proven],
-https://github.com/hyperpolymath/burble[burble], and
-https://github.com/hyperpolymath/gossamer[gossamer].
+Uses the hyperpolymath ABI/FFI standard (Idris2 + Zig) where formal verification is needed.
+
+VeriSimDB-specific:
+- `src/abi/` — Idris2 proofs for drift detection invariants
+- `ffi/zig/` — Zig FFI for performance-critical modality operations
+- `container/` — Stapeln container ecosystem (Chainguard base, selur-compose, cerro-torre signing)
+
+Hypatia integration:
+- `elixir-orchestration/lib/verisim/hypatia/` — 3 modules for scan ingestion, pattern querying, dispatch bridging
+- 954 canonical patterns tracked across 298 repos
+- 16,671 outcomes recorded with Bayesian confidence updating
+- Re-scan verification via panic-attacker (confirms fixes)
 
-== File Map
+== File Map: Key Modules
 
 [cols="1,2"]
 |===
 | Path | What's There
 
-| `src/` | Source code
-| `lib/` | Library code
-| `ffi/` | Foreign function interface
-| `test(s)/` | Test suite
+| `rust-core/verisim-graph/` | Oxigraph RDF + property graph storage
+| `rust-core/verisim-vector/` | HNSW approximate nearest neighbor search
+| `rust-core/verisim-tensor/` | ndarray/Burn multi-dimensional tensors
+| `rust-core/verisim-semantic/` | CBOR proof blobs and type annotations
+| `rust-core/verisim-document/` | Tantivy full-text indexing (LZ4)
+| `rust-core/verisim-temporal/` | Version history and time-series (chrono)
+| `rust-core/verisim-provenance/` | Origin tracking, transformation chains, actor trails
+| `rust-core/verisim-spatial/` | R-tree geospatial indexing
+| `rust-core/verisim-octad/` | Unified entity representation across 8 modalities
+| `rust-core/verisim-drift/` | Drift detection across all modalities
+| `rust-core/verisim-normalizer/` | Self-normalization and repair
+| `rust-core/verisim-api/` | HTTP API server (Rust core)
+| `elixir-orchestration/lib/verisim/` | OTP supervision, GenServers (entity, drift monitor, query router, schema registry)
+| `elixir-orchestration/lib/verisim/hypatia/` | Hypatia integration (scan ingester, pattern query, dispatch bridge)
+| `connectors/clients/` | 6 SDKs (Rust, V, Elixir, ReScript, Julia, Gleam)
+| `connectors/test-infra/` | Integration test stack (7 databases: MongoDB, Redis, Neo4j, ClickHouse, SurrealDB, InfluxDB, MinIO)
+| `container/` | Containerfiles + selur-compose definitions + stapeln ecosystem
+| `proofs/` | Formal verification artifacts (Hypatia integration proofs)
 |===
 
 == Questions?
 
-Open an issue or reach out directly — happy to explain anything in more detail.
+Open an issue in the hyperpolymath/verisimdb repository for questions about octad modalities, drift detection thresholds, self-normalization algorithms, or Hypatia integration with panic-attack scanning.