Skip to content

Commit fdb8080

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
chore: standardise manifest, justfile (hook-generated)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 95eeac3 commit fdb8080

2 files changed

Lines changed: 229 additions & 69 deletions

File tree

‎0-AI-MANIFEST.a2ml‎

Lines changed: 80 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
; 0-AI-MANIFEST.a2ml — Universal AI entry point for VeriSimDB
55
; Media-Type: application/a2ml
66

7+
; THIS FILE MUST BE READ FIRST BY ALL AI AGENTS
8+
79
(manifest
810
(identity
911
(name "VeriSimDB")
@@ -16,26 +18,55 @@
1618

1719
(purpose
1820
"8-modality (octad) database with self-normalization. Each entity
19-
exists simultaneously across 8 modalities — Graph, Vector, Tensor,
20-
Semantic, Document, Temporal, Provenance, Spatial — with drift
21-
detection and automatic consistency maintenance.")
21+
exists simultaneously across Graph, Vector, Tensor, Semantic,
22+
Document, Temporal, Provenance, Spatial — with drift detection
23+
and automatic consistency maintenance. Standalone or federation coordinator.")
24+
25+
;; ===================================================================
26+
;; CONTEXT TIERS
27+
;; ===================================================================
28+
29+
(context-tiers
30+
; Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only
31+
; Tier 1 (load if working on code): README.adoc, EXPLAINME.adoc, Justfile, Cargo.toml
32+
; Tier 2 (load on demand): .machine_readable/*.scm, docs/, KNOWN-ISSUES.adoc
33+
; Tier 3 (never load unless asked): tests/, generated/, CI configs, connectors/test-infra/
34+
;
35+
; DO NOT READ unless specifically asked:
36+
; tests/ — test files (run them, don't read them)
37+
; target/ — Rust build output
38+
; _build/ — Elixir build output
39+
; deps/ — Elixir dependencies
40+
; generated/ — auto-generated code
41+
; *.lock — lock files
42+
; connectors/test-infra/ — containerised test databases
43+
)
44+
45+
;; ===================================================================
46+
;; CANONICAL LOCATIONS
47+
;; ===================================================================
2248

2349
(canonical-locations
24-
(ai-instructions ".claude/CLAUDE.md")
25-
(state ".machine_readable/STATE.scm")
26-
(meta ".machine_readable/META.scm")
27-
(ecosystem ".machine_readable/ECOSYSTEM.scm")
28-
(topology "TOPOLOGY.md")
29-
(build "justfile")
50+
(ai-manifest "0-AI-MANIFEST.a2ml" "THIS FILE")
51+
(ai-instructions ".claude/CLAUDE.md" "Claude-specific patterns — DETAILED")
52+
(state ".machine_readable/STATE.scm")
53+
(meta ".machine_readable/META.scm")
54+
(ecosystem ".machine_readable/ECOSYSTEM.scm")
55+
(topology "TOPOLOGY.md")
56+
(known-issues "KNOWN-ISSUES.adoc")
3057
(container-build "container/Containerfile")
31-
(container-deploy "container/compose.toml")
32-
(test-infra "connectors/test-infra/compose.toml")
33-
(test-infra-manifest "connectors/test-infra/0-AI-MANIFEST.a2ml")
34-
(integration-tests "elixir-orchestration/test/verisim/federation/adapters/integration/")
35-
(known-issues "KNOWN-ISSUES.adoc")
36-
(changelog "CHANGELOG.adoc")
37-
(deployment "DEPLOYMENT.adoc")
38-
(security ".well-known/security.txt"))
58+
(test-infra "connectors/test-infra/compose.toml"))
59+
60+
;; ===================================================================
61+
;; ARCHITECTURE SUMMARY
62+
;; ===================================================================
63+
64+
(architecture
65+
(rust-core "rust-core/" "10 crates — modality stores, drift, normalizer, API")
66+
(elixir "elixir-orchestration/" "OTP supervision, entity servers, drift monitor, query router")
67+
(abi-ffi "src/abi/ + ffi/zig/" "Idris2 ABI + Zig FFI bridge")
68+
(connectors "connectors/" "10 federation adapters + 6 client SDKs")
69+
(query "VQL" "VeriSim Query Language — never raw SQL"))
3970

4071
(tech-stack
4172
(primary "Rust" "Elixir/OTP")
@@ -44,67 +75,47 @@
4475
(container-runtime "Podman")
4576
(base-image "cgr.dev/chainguard/wolfi-base:latest"))
4677

47-
(architecture
48-
(rust-core
49-
(description "Performance-critical modality stores")
50-
(location "rust-core/")
51-
(crates "verisim-graph" "verisim-vector" "verisim-tensor"
52-
"verisim-semantic" "verisim-document" "verisim-temporal"
53-
"verisim-octad" "verisim-drift" "verisim-normalizer"
54-
"verisim-api"))
55-
(elixir-otp
56-
(description "Distributed coordination and supervision")
57-
(location "elixir-orchestration/"))
58-
(abi-ffi
59-
(description "Idris2 ABI definitions + Zig FFI bridge")
60-
(abi-location "src/abi/")
61-
(ffi-location "ffi/zig/"))
62-
(data-store
63-
(description "Git-backed flat-file data repo")
64-
(location "verisimdb-data/"))
65-
(test-infra
66-
(description "Containerised test stack for federation adapter integration testing")
67-
(location "connectors/test-infra/")
68-
(services "mongodb" "redis-stack" "neo4j" "clickhouse" "surrealdb" "influxdb" "minio"))
69-
(connectors
70-
(description "Federation adapters (10) and client SDKs (6)")
71-
(location "connectors/")
72-
(adapters "MongoDB" "Redis" "DuckDB" "ClickHouse" "SurrealDB" "SQLite" "Neo4j" "VectorDB" "InfluxDB" "ObjectStorage")
73-
(sdks "Rust" "V" "Elixir" "ReScript" "Julia" "Gleam")))
78+
;; ===================================================================
79+
;; CRITICAL INVARIANTS
80+
;; ===================================================================
7481

7582
(critical-invariants
7683
(rule "SCM files ONLY in .machine_readable/ — never root")
77-
(rule "All shell scripts must validate untrusted input")
78-
(rule "No hardcoded secrets — use env vars with ${VAR:-} defaults")
79-
(rule "Container images MUST use Chainguard base (cgr.dev)")
80-
(rule "Container runtime is Podman — never Docker")
8184
(rule "VQL is the query language — never raw SQL")
8285
(rule "Octad entities must maintain 8-modality consistency")
83-
(rule "Drift thresholds gate all automatic normalization"))
86+
(rule "Drift thresholds gate all automatic normalization")
87+
(rule "Container: Chainguard base, Containerfile not Dockerfile, Podman not Docker")
88+
(rule "PMPL-1.0-or-later on all source files"))
8489

85-
(container-ecosystem
86-
(selur "container/compose.toml — deployment orchestration")
87-
(stapeln "stapeln.toml — layer-based container builds")
88-
(svalinn "TLS gateway with policy enforcement")
89-
(vordr "Runtime verification and formal proof checking")
90-
(cerro-torre "Image signing with ML-DSA-87 post-quantum crypto")
91-
(rokur "Secret rotation with argon2id"))
90+
;; ===================================================================
91+
;; RELATED PROJECTS
92+
;; ===================================================================
9293

9394
(related-projects
94-
(hypatia "Neurosymbolic CI/CD scanner — consumes verisimdb data")
95-
(gitbot-fleet "Bot orchestration — dispatches fixes from verisimdb findings")
96-
(panic-attacker "Static analysis scanner — produces scan data for verisimdb")
97-
(proven "Formally verified safety library — provides SafeString, SafeJson, etc.")
98-
(lithoglyph "Graph database sibling — shares GQL/GQL-DT patterns")
99-
(quandledb "Knot-theoretic database sibling — KQL query language")))
95+
(hypatia "Neurosymbolic CI/CD — consumes verisimdb data")
96+
(panic-attacker "Static analysis — produces scan data for verisimdb")
97+
(proven "Formally verified safety library — SafeString, SafeJson, etc.")
98+
(lithoglyph "Graph database sibling — shares GQL patterns")
99+
(quandledb "Knot-theoretic database sibling — KQL"))
100100

101-
## Taxonomy Index
101+
;; ===================================================================
102+
;; SESSION LIFECYCLE
103+
;; ===================================================================
102104

103-
- `spec/grammar.ebnf` — @taxonomy: spec/grammar
104-
- `spec/README.adoc` — @taxonomy: spec/index
105-
- `verification/README.adoc` — @taxonomy: verification/index
105+
(lifecycle
106+
(on-enter
107+
(step "Read THIS file first")
108+
(step "Read .claude/CLAUDE.md — contains full architecture and build commands")
109+
(step "Read .machine_readable/STATE.scm for current status"))
106110

107-
### New RSR Standard Directories
111+
(on-exit
112+
(step "Update .machine_readable/STATE.scm if changes made")
113+
(step "Summarise outcomes")))
108114

109-
- `spec/` — Canonical specification files
110-
- `verification/` — Unified verification gateway (symlinks to proofs, tests, conformance, benchmarks, fuzzing)
115+
(format-meta
116+
(version "2.1.0")
117+
(media-type "application/a2ml")
118+
(created "2026-02-20")
119+
(last-updated "2026-03-24")
120+
(maintained-by "Jonathan D.A. Jewell / hyperpolymath")
121+
(protocol "https://github.com/hyperpolymath/0-ai-gatekeeper-protocol")))

‎Justfile‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,3 +172,152 @@ clean:
172172
# Run panic-attacker pre-commit scan
173173
assail:
174174
@command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker"
175+
176+
# ── Onboarding ────────────────────────────────────────────────
177+
178+
# Check all required tools are installed
179+
doctor:
180+
#!/usr/bin/env bash
181+
set -euo pipefail
182+
ok=0; fail=0
183+
check() {
184+
if "$@" >/dev/null 2>&1; then
185+
echo " [ok] $1"
186+
((ok++))
187+
else
188+
echo " [MISSING] $1 — $2"
189+
((fail++))
190+
fi
191+
}
192+
echo "=== VeriSimDB Doctor ==="
193+
check rustc --version "install via asdf: asdf install rust nightly"
194+
check cargo --version "comes with Rust"
195+
check rustup --version "https://rustup.rs"
196+
check pkg-config --version "sudo dnf install pkg-config"
197+
if pkg-config --exists openssl 2>/dev/null; then
198+
echo " [ok] openssl-devel (pkg-config)"
199+
((ok++))
200+
else
201+
echo " [MISSING] openssl-devel — sudo dnf install openssl-devel"
202+
((fail++))
203+
fi
204+
check elixir --version "asdf install elixir 1.17.3-otp-27"
205+
check mix --version "comes with Elixir"
206+
check erl -version "asdf install erlang 27.2"
207+
check zig version "asdf install zig 0.14.0"
208+
check just --version "cargo install just"
209+
check podman --version "sudo dnf install podman (optional, for containers)"
210+
if command -v idris2 >/dev/null 2>&1; then
211+
echo " [ok] idris2 (optional — ABI layer)"
212+
((ok++))
213+
else
214+
echo " [info] idris2 not found (optional — only for ABI definitions)"
215+
fi
216+
echo ""
217+
echo "Result: $ok passed, $fail failed"
218+
if [ "$fail" -gt 0 ]; then
219+
echo "Fix the MISSING items above, then re-run: just doctor"
220+
exit 1
221+
else
222+
echo "All prerequisites satisfied."
223+
fi
224+
225+
# Auto-install missing tools where possible
226+
heal:
227+
#!/usr/bin/env bash
228+
set -euo pipefail
229+
echo "=== VeriSimDB Heal ==="
230+
if ! command -v rustc &>/dev/null; then
231+
echo "Installing Rust via asdf..."
232+
asdf install rust nightly || echo "Try: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh"
233+
fi
234+
if ! command -v just &>/dev/null; then
235+
echo "Installing just..."
236+
cargo install just
237+
fi
238+
if ! command -v elixir &>/dev/null; then
239+
echo "Installing Elixir via asdf..."
240+
asdf install elixir 1.17.3-otp-27 || echo "Try: asdf plugin add elixir && asdf install elixir 1.17.3-otp-27"
241+
fi
242+
if ! command -v zig &>/dev/null; then
243+
echo "Installing Zig via asdf..."
244+
asdf install zig 0.14.0 || echo "Try: asdf plugin add zig && asdf install zig 0.14.0"
245+
fi
246+
if ! pkg-config --exists openssl 2>/dev/null; then
247+
echo "openssl-devel missing — run: sudo dnf install openssl-devel"
248+
fi
249+
if ! command -v podman &>/dev/null; then
250+
echo "Podman missing — run: sudo dnf install podman podman-compose"
251+
fi
252+
echo ""
253+
echo "Re-run 'just doctor' to verify."
254+
255+
# Guided tour of the codebase
256+
tour:
257+
#!/usr/bin/env bash
258+
set -euo pipefail
259+
echo "=== VeriSimDB Tour ==="
260+
echo ""
261+
echo "1. ARCHITECTURE"
262+
echo " Rust core (rust-core/) provides 10 modality crates:"
263+
echo " graph, vector, tensor, semantic, document, temporal,"
264+
echo " provenance, spatial, octad, drift, normalizer, api"
265+
echo " Elixir OTP (elixir-orchestration/) coordinates them."
266+
echo ""
267+
echo "2. BUILD & RUN"
268+
echo " just build Build Rust release"
269+
echo " just build-elixir Build Elixir layer"
270+
echo " just serve Start API on :8080"
271+
echo ""
272+
echo "3. THE OCTAD"
273+
echo " Every entity is stored across 8 modalities simultaneously."
274+
echo " Drift between them is detected and self-healed."
275+
echo ""
276+
echo "4. QUERY LANGUAGE"
277+
echo " VQL (VeriSim Query Language) — NOT SQL."
278+
echo " See docs/ and playground/ for examples."
279+
echo ""
280+
echo "5. FEDERATION"
281+
echo " 10 adapters (MongoDB, Redis, Neo4j, ClickHouse, SurrealDB,"
282+
echo " SQLite, DuckDB, VectorDB, InfluxDB, ObjectStorage)."
283+
echo " 6 client SDKs (Rust, V, Elixir, ReScript, Julia, Gleam)."
284+
echo ""
285+
echo "6. CONTAINERS"
286+
echo " just container-build Build with Podman"
287+
echo " just container-run Run on :8080"
288+
echo ""
289+
echo "7. KEY FILES"
290+
echo " Cargo.toml Workspace definition"
291+
echo " elixir-orchestration/ OTP layer"
292+
echo " connectors/ Federation + SDKs"
293+
echo " container/ Containerfile + compose"
294+
echo " .claude/CLAUDE.md Full AI context"
295+
echo ""
296+
echo "Run 'just' to see all available recipes."
297+
298+
# What to do when things go wrong
299+
help-me:
300+
#!/usr/bin/env bash
301+
echo "=== VeriSimDB Help ==="
302+
echo ""
303+
echo "BUILD FAILS:"
304+
echo " 'openssl' errors -> sudo dnf install openssl-devel"
305+
echo " 'protoc' errors -> Proto code is pre-generated, check Cargo features"
306+
echo " 'oxrocksdb' errors -> Eliminated; if seen, run: cargo clean && just build"
307+
echo " Elixir errors -> cd elixir-orchestration && mix deps.get"
308+
echo ""
309+
echo "RUNTIME ISSUES:"
310+
echo " Port 8080 in use -> Change port: VERISIM_PORT=8081 just serve"
311+
echo " 'connection refused'-> Is the Rust API running? just serve"
312+
echo " Drift not detected -> Check thresholds in config/config.exs"
313+
echo ""
314+
echo "TESTING:"
315+
echo " Integration tests need the test-infra stack running:"
316+
echo " cd connectors/test-infra && podman-compose up -d"
317+
echo " Then: just test-integration"
318+
echo ""
319+
echo "STILL STUCK?"
320+
echo " 1. just doctor (check prerequisites)"
321+
echo " 2. just heal (auto-install what's missing)"
322+
echo " 3. cargo clean && just build (fresh build)"
323+
echo " 4. Read .claude/CLAUDE.md for full context"

0 commit comments

Comments
 (0)