Skip to content

Commit 3cd3813

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
docs: add quickstart and LLM warmup documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent bf7b119 commit 3cd3813

3 files changed

Lines changed: 407 additions & 0 deletions

File tree

‎verisimdb/QUICKSTART-USER.adoc‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
//
4+
// QUICKSTART-USER.adoc — Get VeriSimDB running from zero
5+
= VeriSimDB Quickstart
6+
:toc: macro
7+
:icons: font
8+
9+
toc::[]
10+
11+
== What is VeriSimDB?
12+
13+
VeriSimDB is an 8-modality database engine. Every entity is stored
14+
simultaneously across Graph, Vector, Tensor, Semantic, Document,
15+
Temporal, Provenance, and Spatial representations (the "octad").
16+
Drift between modalities is detected and self-healed automatically.
17+
18+
The Rust core provides the modality stores. An Elixir/OTP layer
19+
orchestrates coordination, fault tolerance, and the HTTP API.
20+
21+
== Prerequisites
22+
23+
You need these tools installed before building VeriSimDB.
24+
25+
[cols="1,1,2"]
26+
|===
27+
| Tool | Version | Install (Fedora)
28+
29+
| Rust (nightly)
30+
| 1.85+
31+
| `asdf install rust nightly` or `rustup install nightly`
32+
33+
| Elixir
34+
| 1.17+
35+
| `asdf install elixir 1.17.3-otp-27`
36+
37+
| Erlang/OTP
38+
| 27+
39+
| `asdf install erlang 27.2`
40+
41+
| Zig
42+
| 0.14+
43+
| `asdf install zig 0.14.0`
44+
45+
| Idris2 _(optional, ABI layer)_
46+
| 0.7+
47+
| `asdf install idris2 0.7.0`
48+
49+
| Podman _(optional, containers)_
50+
| 4+
51+
| `sudo dnf install podman podman-compose`
52+
53+
| just
54+
| 1.0+
55+
| `cargo install just`
56+
57+
| openssl-devel
58+
| --
59+
| `sudo dnf install openssl-devel`
60+
61+
| pkg-config
62+
| --
63+
| `sudo dnf install pkg-config`
64+
|===
65+
66+
TIP: Run `just doctor` to verify all prerequisites are present.
67+
68+
== Clone and Build
69+
70+
[source,bash]
71+
----
72+
cd ~/Documents/hyperpolymath-repos
73+
# Already cloned if you have the nextgen-databases monorepo:
74+
# cd nextgen-databases/verisimdb
75+
# OR standalone:
76+
git clone https://github.com/hyperpolymath/verisimdb
77+
cd verisimdb
78+
----
79+
80+
=== Build Rust Core (release)
81+
82+
[source,bash]
83+
----
84+
just build
85+
----
86+
87+
This runs `cargo build --release` with `OPENSSL_NO_VENDOR=1`.
88+
89+
=== Build Elixir Layer
90+
91+
[source,bash]
92+
----
93+
just build-elixir
94+
----
95+
96+
Fetches Mix dependencies and compiles the OTP supervision tree.
97+
98+
=== Build Everything
99+
100+
[source,bash]
101+
----
102+
just build-all
103+
----
104+
105+
== First Run
106+
107+
=== Option A: Rust API Server (standalone)
108+
109+
[source,bash]
110+
----
111+
just serve
112+
----
113+
114+
Opens `http://localhost:8080`. The Rust API server provides direct
115+
access to the modality stores.
116+
117+
=== Option B: Elixir OTP Orchestrator
118+
119+
[source,bash]
120+
----
121+
just serve-otp
122+
----
123+
124+
Starts the full OTP supervision tree with entity servers, drift
125+
monitoring, and query routing.
126+
127+
=== Option C: Container (Podman)
128+
129+
[source,bash]
130+
----
131+
just container-build
132+
just container-run
133+
----
134+
135+
Runs VeriSimDB in a Chainguard-based container on port 8080.
136+
137+
== Verify It Works
138+
139+
[source,bash]
140+
----
141+
# Health check
142+
curl http://localhost:8080/health
143+
144+
# Create an octad entity (example)
145+
curl -X POST http://localhost:8080/api/v1/entities \
146+
-H "Content-Type: application/json" \
147+
-d '{"document": {"title": "Test", "body": "Hello"}, "types": ["test"]}'
148+
----
149+
150+
== Run Tests
151+
152+
[source,bash]
153+
----
154+
just test # Rust unit tests
155+
just test-elixir # Elixir unit tests
156+
just test-all # Both
157+
----
158+
159+
== Key Recipes
160+
161+
[source,bash]
162+
----
163+
just # List all recipes
164+
just build # Build Rust core (release)
165+
just build-all # Build Rust + Elixir
166+
just serve # Start API server (dev)
167+
just test-all # Run all tests
168+
just lint # Clippy lints
169+
just fmt # Format Rust code
170+
just doctor # Check prerequisites
171+
just tour # Guided walkthrough
172+
just help-me # What to do when stuck
173+
----
174+
175+
== Instance Policy
176+
177+
This repo is *source code and examples only*. If you are integrating
178+
VeriSimDB into another project, you MUST create your own instance:
179+
180+
1. Copy the client SDK from `connectors/clients/<lang>/`
181+
2. Add a Containerfile to YOUR project
182+
3. Choose a unique port (not 8080)
183+
4. Create a dedicated data volume
184+
185+
See `.claude/CLAUDE.md` for port assignments per project.

‎verisimdb/llm-warmup-dev.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# VeriSimDB — LLM Context (Developer)
2+
3+
## Identity
4+
5+
VeriSimDB (Veridical Simulacrum Database) — 8-modality entity consistency
6+
engine with drift detection, self-normalisation, and formally verified queries.
7+
Part of the nextgen-databases monorepo. License: PMPL-1.0-or-later.
8+
Author: Jonathan D.A. Jewell.
9+
10+
## Architecture (Marr's Three Levels)
11+
12+
**Computational**: Maintain cross-modal consistency across 8 representations.
13+
**Algorithmic**: Octad entities, drift detection with thresholds, OTP supervision.
14+
**Implementational**: Rust stores + Elixir coordination + VQL queries.
15+
16+
```
17+
Elixir OTP: EntityServer, DriftMonitor, QueryRouter, SchemaRegistry
18+
↓ HTTP
19+
Rust Core: graph, vector, tensor, semantic, document, temporal,
20+
provenance, spatial, octad, drift, normalizer, api
21+
```
22+
23+
## Rust Workspace (`Cargo.toml`)
24+
25+
10 library crates + 1 binary crate (verisim-api). Workspace at root.
26+
Build: `OPENSSL_NO_VENDOR=1 cargo build --release`
27+
oxrocksdb-sys eliminated (redb pure-Rust backend). protoc eliminated
28+
(pre-generated). No C++ deps.
29+
30+
## Elixir Layer (`elixir-orchestration/`)
31+
32+
OTP app with supervision tree. GenServer per entity.
33+
Hypatia integration: ScanIngester, PatternQuery, DispatchBridge (37 tests).
34+
Built-in VQL parser (no external runtime needed).
35+
Product telemetry: opt-in ETS collector + JSON reporter.
36+
37+
## Key Subsystems
38+
39+
### Drift Detection
40+
6 drift types: semantic_vector, graph_document, temporal_consistency,
41+
tensor, schema, quality. Configurable thresholds gate normalisation.
42+
43+
### Self-Normalisation
44+
1. Identify most authoritative modality
45+
2. Regenerate drifted modalities
46+
3. Validate consistency
47+
4. Atomic update
48+
49+
### Federation
50+
10 adapters: MongoDB, Redis, Neo4j, ClickHouse, SurrealDB, SQLite,
51+
DuckDB, VectorDB, InfluxDB, ObjectStorage.
52+
Integration tests: 105 tests across 7 adapters (need test-infra stack).
53+
54+
### VQL (VeriSim Query Language)
55+
Type system: VQL-DT. 11 proof types. Multi-proof parsing.
56+
Modality compatibility validation. ReScript playground wired to backend.
57+
58+
### Hypatia Pipeline
59+
```
60+
panic-attack assail → ScanIngester → octads → PatternQuery → DispatchBridge → gitbot-fleet
61+
```
62+
954 patterns tracked across 298 repos. Fleet dispatch logged (JSONL),
63+
live execution needs GitHub PAT.
64+
65+
## Client SDKs (`connectors/clients/`)
66+
67+
6 SDKs: Rust, V, Elixir, ReScript, Julia, Gleam.
68+
Shared: JSON Schema, OpenAPI, protobuf (`connectors/shared/`).
69+
70+
## ABI/FFI (`src/abi/`, `ffi/zig/`)
71+
72+
Idris2 ABI definitions (formal proofs). Zig FFI C-ABI bridge.
73+
Generated C headers in `generated/abi/`.
74+
75+
## Container Stack
76+
77+
Podman (never Docker). Chainguard base images.
78+
- `container/Containerfile` — main build
79+
- `container/compose.toml` — selur-compose (3 services)
80+
- `container/.gatekeeper.yaml` — svalinn edge gateway
81+
- `container/manifest.toml` — cerro-torre signing
82+
- `container/ct-build.sh` — build/sign/verify pipeline
83+
84+
Test infra: `connectors/test-infra/compose.toml` — 7 databases.
85+
86+
## Instance Policy (CRITICAL)
87+
88+
This repo = source code + examples ONLY. Each consumer runs own instance:
89+
- IDApTIK: port 8090, volume idaptik-verisimdb-data
90+
- Burble: port 8091, volume burble-verisimdb-data
91+
- Hypatia: port 8092, volume hypatia-verisimdb-data
92+
93+
Never store app data here. Never point at localhost:8080.
94+
95+
## Commands
96+
97+
```bash
98+
just build / build-all / build-elixir / build-abi / build-ffi
99+
just test / test-elixir / test-integration / test-all
100+
just serve / serve-otp
101+
just fmt / lint / fmt-elixir
102+
just container-build / container-run / deploy / deploy-stop
103+
just panic-scan / hypatia-scan / license-check / check-scm
104+
just doctor / heal / tour / help-me
105+
```
106+
107+
## Language Policy
108+
109+
Allowed: Rust, Elixir, ReScript, VQL, Idris2, Zig.
110+
Banned: Python, Go, Node.js.
111+
112+
## Code Patterns
113+
114+
### Octad creation (Rust)
115+
```rust
116+
let octad = OctadBuilder::new()
117+
.with_document("Title", "Body")
118+
.with_embedding(vec![0.1, 0.2])
119+
.with_types(vec!["http://example.org/Doc"])
120+
.build();
121+
```
122+
123+
### Entity server (Elixir)
124+
```elixir
125+
{:ok, _} = VeriSim.EntityServer.start_link("eid")
126+
{:ok, state} = VeriSim.EntityServer.get("eid")
127+
```
128+
129+
## Known Issues
130+
131+
All 25 historical issues resolved. See KNOWN-ISSUES.adoc.
132+
133+
## File Map
134+
135+
| Path | What |
136+
|------|------|
137+
| `Cargo.toml` | Workspace root |
138+
| `rust-core/verisim-*/` | 10 modality crates |
139+
| `elixir-orchestration/lib/verisim/` | OTP modules |
140+
| `elixir-orchestration/lib/verisim/hypatia/` | Hypatia integration |
141+
| `connectors/clients/` | 6 SDKs |
142+
| `connectors/test-infra/` | Integration test databases |
143+
| `container/` | Containerfiles + compose |
144+
| `playground/` | VQL playground (ReScript) |
145+
| `src/abi/` | Idris2 ABI |
146+
| `ffi/zig/` | Zig FFI |
147+
| `spec/` | Grammar EBNF |
148+
| `verification/` | Verification gateway |
149+
| `docs/` | Documentation |
150+
| `verisimdb-data/` | Git-backed flat-file data |
151+
| `.machine_readable/` | STATE.scm, META.scm, ECOSYSTEM.scm |
152+
| `.claude/CLAUDE.md` | Full AI instructions |
153+
| `0-AI-MANIFEST.a2ml` | Universal AI entry point |

0 commit comments

Comments
 (0)