INDEX.md

VeriSimDB Documentation Index

Last updated: 2026-05-25. This file is the table of contents for everything under docs/ and the top-level project documents.

Top-level (repository root)

The repo root holds only documents that need maximum visibility for new readers, plus the artefacts the RSR template requires.

File	Purpose
README.adoc	Project entry point — what VeriSimDB is, how to install/run, where to look next
ROADMAP.md	Criticality-ordered work plan (Phase 1–8)
CHANGELOG.adoc	Versioned history of all notable changes
TESTING.md	Testing & benchmarking standards (hard CI gates per language, property-test patterns, fuzz corpus location)
KNOWN-ISSUES.adoc	Honest-gaps audit trail — all 25 catalogued issues with resolution status
AUDIT.adoc	RSR audit-index pointing to KNOWN-ISSUES, TESTING, SECURITY, CHANGELOG
SECURITY.md	Threat model, disclosure process, supported versions
CONTRIBUTING.md	How to propose changes, run gates locally
MAINTAINERS.adoc	Active maintainers
CODE_OF_CONDUCT.md	Community standards
LICENSE	MPL-2.0
0-AI-MANIFEST.a2ml	AI manifest for the project
justfile	Task definitions for the just runner

docs/ tree

Architecture

• docs/architecture/abi-ffi.md — ABI/FFI contract for cross-language calls (Rust ↔ Elixir ↔ Idris2)
• docs/architecture/topology.md — Process topology and deployment shapes

Decisions (ADR-style)

• docs/decisions/rust-spark-stance.adoc — Why Rust over alternatives for the core
• docs/decisions/kraft-comparison.adoc — Why KRaft for the consensus layer
• docs/decisions/proven-coherence.md — Notes on the proven library integration

Deployment

• docs/deployment/deployment.adoc — Full deployment guide (Podman, selur-compose, Containerfile)
• docs/deployment/void-setup.md — Void Linux dev environment setup

Status & implementation tracking

• docs/status/planner.md — verisim-planner implementation status
• docs/status/implementation-plan.adoc — Original timeline-based execution plan (V1–V5)

Releases

• docs/releases/v0.1.0-alpha.md — Narrative release announcement for v0.1.0-alpha (2026-02-04)

Papers & whitepaper

• docs/papers/whitepaper.md — VeriSimDB whitepaper (Markdown source)
• docs/papers/whitepaper.pdf — Whitepaper PDF artefact
• docs/papers/arcvix-octad-data-model.tex — ARCVIX octad data-model paper (LaTeX)
• docs/papers/references.bib — BibTeX references for the papers
• docs/papers/verisimdb-federated-consistency.adoc — Federated consistency paper
• docs/papers/verisimdb-idaptik-case-study.adoc — Idaptik case study

Visualizations

• docs/visualizations/architecture.html — Interactive architecture diagram
• docs/visualizations/historiographic-custodian.html — Historiographic custodian visualization

Business

• docs/business/business-case.adoc — Business case for VeriSimDB
• docs/business/financials/ — Financial models
• docs/business/marketing/ — Marketing materials
• docs/business/pr/ — Press releases
• docs/business/strategy/ — Strategic planning

Design notes (dated, point-in-time)

• docs/design/DESIGN-2026-02-27-level-data-model.md
• docs/design/DESIGN-2026-02-27-strategic-improvements.adoc
• docs/design/DESIGN-2026-02-27-vcl-dt-assessment.adoc
• docs/design/DESIGN-2026-02-28-panll-interop-telemetry.md

VCL language

• docs/getting-started.adoc — VCL getting started
• docs/VCL-SPEC.adoc — Full VCL specification
• docs/vcl-grammar.ebnf — ISO/IEC 14977 EBNF grammar
• docs/vcl-architecture.adoc — Parser / executor architecture
• docs/vcl-type-system.adoc — VCL-DT dependent type system
• docs/vcl-formal-semantics.adoc — Formal semantics
• docs/vcl-examples.adoc — Worked examples
• docs/vcl-vs-vcl-dt.adoc — VCL vs VCL-DT comparison
• docs/vcl-vs-sql.adoc — VCL vs SQL comparison
• docs/rescript-registry-types.adoc — ReScript registry types

Operational concerns

• docs/deployment-modes.adoc — Standalone vs federated vs hybrid
• docs/error-handling-strategy.adoc — Error taxonomy
• docs/safety-and-fault-tolerance.adoc — Supervision, retry, circuit breakers
• docs/safety-theory-applied.adoc — Safety theory grounding
• docs/security-lessons.lgt — Security retrospective (Logtalk)
• docs/caching-strategy.adoc — Cache invalidation strategy
• docs/cache-sharing-strategy.adoc — Cross-process cache sharing
• docs/snapshotting-and-truncation-logic.adoc — WAL snapshots
• docs/normalization-cascade.adoc — Drift normalization cascade
• docs/drift-handling.adoc — Drift detection and remediation
• docs/reversibility-design.adoc — Reversibility/audit guarantees
• docs/backwards-compatibility.adoc — Backwards compatibility policy
• docs/adoption-strategy.adoc — Adoption strategy
• docs/federation-readiness.adoc — Federation readiness checklist
• docs/challenges-standalone.adoc — Standalone deployment challenges
• docs/challenges-federated.adoc — Federated deployment challenges
• docs/challenges-hybrid.adoc — Hybrid mode challenges

Specialized

• docs/consultation-dependent-types-zkp.adoc — Consultation paper: dependent types + ZKP
• docs/consultation-normalization-strategy.adoc — Consultation paper: normalization
• docs/zkp-and-sanctify-integration.adoc — ZKP + sanctify integration design (now implemented — see KNOWN-ISSUES #6)
• docs/query-optimization-overview.adoc — Query optimizer overview
• docs/technical-specification-kraft-metadata-log.adoc — KRaft metadata log spec
• docs/minikanren-integration-v3.adoc — miniKanren integration v3
• docs/panll-module-audit.adoc — PanLL module audit
• docs/rsr-compliance.adoc — RSR template compliance notes
• docs/CITATIONS.adoc — Bibliographic citations for the project

Machine-readable artefacts

Under .machine_readable/:

• STATE.scm — current project state and progress
• META.scm — architecture decisions and development practices
• ECOSYSTEM.scm — position in the ecosystem and related projects

Workflow & CI

Under .github/workflows/:

• rust-ci.yml — fmt, clippy, test, doc, audit, deny, bench-compile, fuzz-compile, coverage
• elixir-ci.yml — format, compile (--warnings-as-errors), test, hex.audit, coverage, bench-compile
• governance.yml — estate-wide governance bundle (workflow security, language anti-patterns, etc.)
• codeql.yml — CodeQL security analysis
• cflite_batch.yml, cflite_pr.yml — ClusterFuzzLite (PR and batch fuzzing)
• secret-scanner.yml — TruffleHog + Gitleaks
• scorecard.yml, scorecard-enforcer.yml — OpenSSF Scorecard
• spark-theatre-gate.yml — SPARK Theatre Gate
• hypatia-scan.yml — Hypatia neurosymbolic analysis
• instant-sync.yml, mirror.yml — mirror sync workflows
• jekyll-gh-pages.yml — GitHub Pages deployment

Source code

Path	Language	Purpose
rust-core/	Rust	Core database engine (8 modality stores + octad + drift + normalizer + api + planner)
elixir-orchestration/	Elixir	OTP orchestration layer (DriftMonitor, EntityServer, VCLExecutor, VCLBridge, SchemaRegistry, federation adapters)
src/	ReScript	VCL parser, type checker, federation registry
playground/	ReScript + HTML	VCL Playground web UI
connectors/	Multi	Federation adapters, client SDKs (Rust, Elixir, ReScript, Julia, Zig), test infrastructure. Other BEAM languages (Gleam, Erlang) access via the SNIFs WASM bridge — see hyperpolymath/snifs.
debugger/	Idris2 + Rust	ABI/FFI debugger
ffi/zig/	Zig	Zig FFI
v-api-gateway/	V	V-language API gateway
fuzz/, rust-core/fuzz/	Rust	Fuzz harnesses (libFuzzer via cargo-fuzz)
benches/	Rust	Criterion benchmarks (all 8 modalities + cross-modal + octad + drift)
elixir-orchestration/bench/	Elixir	Benchee benchmark scripts (DriftMonitor, QueryRouter, VCLExecutor, VCLBridge, SchemaRegistry)

Container & deployment

• container/ — Containerfile, ct-build.sh, compose.toml, manifest.toml, .gatekeeper.yaml
• .clusterfuzzlite/ — Dockerfile + build.sh for ClusterFuzzLite
• selur-compose.yml — selur-compose stack definition
• stapeln.toml — stapeln supply-chain config
• opsm.toml — operations manifest