// SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) = Clade Registry & VeriSimDB Portal Architecture Jonathan D.A. Jewell v0.1.0, 2026-03-16 :toc: left :toclevels: 4 :sectnums: :icons: font :source-highlighter: rouge == Abstract This specification defines a clade-based taxonomy system for organising 200+ repositories in the hyperpolymath ecosystem, backed by a VeriSimDB instance as the central registry, with a public ReScript/WASM portal on `hyperpolymath.github.io` and a read-only API for external consumers including LLMs. The core design principle is *map and territory*: VeriSimDB is the map — queryable, presentable, always clean. Repositories are the territory — where work happens, as messy as it needs to be. Editing the map never damages the territory. The pointer authority system ensures every datum knows where its canonical value lives. == Motivation === Current Problems 1. **Scattered state**: Project status lives in 53+ memory files, per-repo STATE.a2ml files, session queue dumps, bot logs, desktop notes, and human memory. No single source of truth. 2. **Organisational entropy**: Repositories inflated out of monorepos and deflated back in without lineage tracking. Cross-project dependencies are undocumented. Related projects (januskey, valence-shell, ochrance) solve similar problems with no shared interface. 3. **Discovery failure**: External visitors must navigate GitHub to understand the ecosystem. LLMs cannot discover project information without cloning repositories. Bot observations (echidnabot, rhodibot) go into logs that no other agent reads. 4. **Access/security tension**: Repos are either fully public or private. No middle ground for "show status publicly but control code access". 5. **Token cost**: Assessing the state of related projects requires spawning multiple agents, reading hundreds of files, at ~400K tokens per query. This is unsustainable. === Design Goals * Every repository has a unique, persistent identity with primary key (GitHub) and foreign keys (GitLab, Bitbucket, Codeberg, SourceHut, Radicle) * Alphabetical sorting of repo names reveals organisational structure * A single VCL query replaces multi-agent exploration * Public visitors see everything they need without visiting individual repositories * LLMs can query the ecosystem via a structured read-only API * Contributors get scoped access to exactly what they need * Bot findings, human TODOs, and session queues all live in one queryable system * Inflate/deflate operations are tracked as lineage, never lose identity == Clade Taxonomy === Prefix Format Every top-level repository name follows the format: ---- {clade-code}-{existing-name} ---- Where `{clade-code}` is a 2-character lowercase alphabetic code and `{existing-name}` is the current repository name unchanged. **Rationale**: 2 characters provide 676 possible codes (far more than needed), are short enough to avoid bloating names, and cause natural alphabetical grouping when sorted. [IMPORTANT] ==== *The two letters abbreviate the name of the CLADE. They never abbreviate the name of the repo.* This is a closed taxonomy of twelve categories, not an abbreviation scheme: you choose the category a repo belongs to, then write down that category's code. You do not look at the repo's name and find two letters that fit it. This is stated because the opposite was done, more than once: [cols="1,1,2,2"] |=== | Repo | Code | Read as | Actually means | `paint-type` | `pt` | "*P*ain*T*-type" | Protocols & Interop — an image editor is `ap` | `gossamer` | `gv` | "*G*raphical/*V*isual" | Governance & Standards — there is no graphical clade |=== Both codes were *valid*, so every check passed and the repos were filed under categories they have nothing to do with. A code alone cannot express a wrong belief about what it means, so it cannot be checked for one. Therefore every `CLADE.a2ml` MUST declare the clade's name alongside its code: [source,toml] ---- [clade] primary = "ap" primary-name = "Applications" # must be the taxonomy's name for `primary` ---- The redundancy is the point: the *pair* can express the wrong belief, and so the pair can be rejected. `primary = "pt"` with `primary-name = "PainT-type"` now fails <> instead of passing silently. `primary-name` must match the `name` field for that code in `verisim/seed/clades.a2ml`, which is the authority. [[clade-006]] Enforced by CLADE-006 in `contractiles/must/clade-hygiene.a2ml` (severity BLOCK, scope pre-commit). ==== === Clade Definitions [cols="1,3,4"] |=== | Code | Clade | Description | `fv` | Formal Verification & Proofs | Repositories focused on provable correctness, reversibility, dependent types, theorem proving | `nl` | Nextgen Languages | Programming language implementations, compilers, runtimes | `rm` | Repo Management & Tooling | Repository scaffolding, graph analysis, bot orchestration, template systems | `gv` | Governance & Standards | Licensing, compliance, architectural boundaries, policy enforcement | `db` | Databases | Database engines, query languages, data storage systems | `ap` | Applications | End-user applications, web apps, desktop apps, services | `ix` | Infrastructure & Cloud | Cloud management, containers, deployment, system administration | `dx` | Developer Ecosystem | Developer tools, package managers, editor integrations, language bindings | `pt` | Protocols & Interop | Internet standards, protocol implementations, interoperability frameworks | `ax` | AI & Neurosymbolic | Machine learning, neural proof synthesis, AI governance | `gm` | Games & Interactive | Game engines, interactive experiences, gamified tools | `sc` | Security | Security scanning, vulnerability management, access control |=== === Multi-Clade Membership A repository has exactly one *primary* clade (determines its prefix) and zero or more *secondary* clades (recorded in VeriSimDB only). The primary clade reflects the project's core value proposition, not its implementation details. .Example ---- januskey: primary: fv (the point is provable reversibility) secondary: [sc] (it's also a security tool) prefix: fv-januskey ---- === Exceptions * **Julia packages** (`*.jl`): Retain PascalCase naming per Julia ecosystem convention. Clade membership tracked in VeriSimDB only, no prefix rename. * **Monorepo children**: Sub-projects within monorepos (e.g., `reposystem/contractiles/`) do not get prefixed. Their parent gets the prefix. VeriSimDB tracks them as children. == Identity Model === Primary and Foreign Keys Each repository is an *octad* (8-modality entity) in VeriSimDB. Its identity is defined by: [source,toml] ---- [identity] uuid = "v5-uuid-derived-from-github.com/hyperpolymath/{name}" primary-forge = "github" primary-owner = "hyperpolymath" canonical-name = "januskey" prefixed-name = "fv-januskey" [forges] github = "hyperpolymath/januskey" gitlab = "hyperpolymath/januskey" bitbucket = "hyperpolymath/januskey" codeberg = "hyperpolymath/januskey" sourcehut = "~hyperpolymath/januskey" radicle = "" # populated if/when mirrored [clade] primary = "fv" secondary = ["sc"] assigned = "2026-03-16" rationale = "Provable reversibility is the core value proposition" [lineage] type = "standalone" # standalone | monorepo-child | inflated | deflated parent = "" # monorepo parent if applicable born = "2025-11-01" inflated-from = "" # if was monorepo child, now standalone deflated-into = "" # if was standalone, now monorepo child previous-names = [] # rename history ---- **UUID generation**: Deterministic v5 UUID derived from `github.com/hyperpolymath/{name}`. The same repo always produces the same UUID without a lookup table. This is the primary key used throughout VeriSimDB. === Per-Repo Declaration Every repository MUST contain `.machine_readable/CLADE.a2ml` with the identity block above. This is the **attestable declaration** of the repo's own identity. VeriSimDB aggregates these declarations and detects inconsistencies via drift detection. == Pointer Authority System === Problem Statement In a distributed system of 200+ repos and a central database, the question "who owns this piece of data?" must be answered for every datum. Traditional approaches (repo-authoritative or database-authoritative) are too rigid. === The Pointer Model Every datum in VeriSimDB has an *authority record* in the PROVENANCE modality: [source,toml] ---- [authority] type = "pointer" source = "repo" target = "gh:hyperpolymath/januskey/.machine_readable/STATE.a2ml" field = "completion" last-synced = "2026-03-16T14:30:00Z" hash = "sha256:abc123..." ---- Three authority types: [cols="1,3,3"] |=== | Type | Meaning | Examples | `pointer` | Canonical value lives elsewhere; VeriSimDB caches and drift-detects | Repo's STATE.a2ml owns completion %, README content | `local` | VeriSimDB owns this value; no external source | TODO items, bot observations, feedback, session state | `derived` | Computed from other values; recomputed on access | Clade health scores, cross-clade dependency counts, staleness metrics |=== **Drift detection**: When a `pointer` datum's cached value diverges from its source (detected by hash comparison during sync), VeriSimDB raises a drift alert. This replaces manual checking of whether STATE.a2ml is up to date. == VeriSimDB Octad Modalities for Repos Each of VeriSimDB's 8 modalities serves a specific role in the registry: [cols="1,3,3"] |=== | Modality | What It Stores | Replaces | Graph | Dependencies between repos, clade membership edges, monorepo parent/child, forge FK links | Scattered ECOSYSTEM.a2ml files | Vector | Embedding of repo purpose/description for similarity search | Nothing (new capability) | Tensor | Completion percentages, test counts, LOC metrics, time-series | TOPOLOGY.md percentages | Semantic | Clade taxonomy, license type, language policy compliance, version | Scattered META.a2ml | Document | README summaries, TODO items, queue entries, bot observations, feedback, setup instructions | Memory files, queue dumps, bot logs | Temporal | Last commit, last meaningful activity, session history, due dates | git log across 202 repos | Provenance | Creator, last changer, bot vs human, session ID, authority pointers, checksums | Nothing reliable | Spatial | Not currently used; reserved for future org hierarchy visualisation | N/A |=== == Portal Architecture === Layer 1: Public Frontend (hyperpolymath.github.io) A ReScript application compiled to WASM, statically hosted on GitHub Pages. **No authentication required.** Read-only access to all public data. ==== Pages * **Dashboard**: 12 clade tiles with health indicators, total repos, aggregate completion * **Clade Explorer**: Browse by clade, drill into member repos * **Project Detail**: Single project — description, completion, roadmap, dependencies, technologies, forge links, last activity, bot findings * **Tech Radar**: Visual map of all languages/frameworks used across the ecosystem * **Roadmap**: Cross-project timeline of planned work, filterable by clade * **Search**: Full-text search across all repos (uses VECTOR modality for semantic matching) * **API Docs**: Documentation for the LLM and contributor API endpoints ==== Technology [source] ---- hyperpolymath.github.io/ src/ # ReScript source App.res # Main TEA application VQLClient.res # WASM VCL query builder pages/ # Page components components/ # Shared components (CladeTree, DependencyGraph, etc.) bindings/ # Typed bindings to API index.html # Shell (loads WASM) rescript.json Justfile ---- === Layer 2: API Gateway (Cloudflare Worker) Hosted on a hyperpolymath-owned domain (e.g., `api.hyperpolymath.dev` or `registry.experience.exchange`). Backed by Cloudflare KV for sub-millisecond reads of the public snapshot. ==== Endpoints [cols="2,1,3"] |=== | Route | Auth | Purpose | `GET /v1/query` | Public | VCL read-only queries (rate-limited) | `GET /v1/repo/:id` | Public | Single repo status | `GET /v1/clade/:code` | Public | All repos in a clade | `GET /v1/roadmap` | Public | Aggregated roadmap | `GET /v1/search?q=...` | Public | Full-text search | `GET /v1/llm?q=...` | API Key | Structured output for LLM consumption | `GET /v1/contrib/repos` | OAuth | Contributor's accessible repos | `POST /v1/bot/observation` | Signed JWT | Bot writes finding | `POST /v1/bot/todo` | Signed JWT | Bot creates TODO | `POST /v1/admin/query` | Admin | Full VCL including writes |=== ==== Authentication Tiers [cols="1,2,2,1"] |=== | Tier | Auth Method | Capabilities | Rate Limit | PUBLIC | None | Read-only, no PII, no code | 100 req/min | LLM | API key (issued per consumer) | Structured output, higher limits | 1000 req/min | CONTRIB | GitHub OAuth | Scoped repo access, write TODOs | 500 req/min | BOT | Signed JWT (per bot) | Write observations, findings | 2000 req/min | ADMIN | Personal token | Full VCL, all writes | Unlimited |=== ==== LLM Endpoint Response Format [source,json] ---- { "query": "what is the reversibility stack", "results": [ { "repo": "fv-januskey", "summary": "Provably reversible file operations via Maximal Principle Reduction", "completion": 100, "status": "production-ready", "technologies": ["rust"], "clade": "fv", "last_activity": "2026-03-16", "portal_url": "https://hyperpolymath.github.io/#/project/januskey" } ], "relationships": [ { "from": "januskey", "to": "valence-shell", "type": "architectural-alignment" } ] } ---- === Layer 3: VeriSimDB Instance (Verpex VPS) The full VeriSimDB (Rust core + Elixir orchestration) running on the Verpex VPS behind Cloudflare. ==== Responsibilities * Persistent storage of all octads (repos, TODOs, feedback, bot observations) * Drift detection: compares pointer hashes against source values * Sync daemon: hourly pull of git metadata from 202 repos * Bot ingestion: receives observations via API Layer 2 * Public snapshot export: hourly push to Cloudflare KV for fast edge reads ==== Data Flow ---- VeriSimDB (VPS) ──hourly sync──> Cloudflare KV (public snapshot) | Cloudflare Worker reads KV <───────── GitHub Pages WASM app | Bot/agent writes ──> Worker ──signed──> VeriSimDB (VPS) directly ---- Public reads never hit the VPS. Writes go to VPS via authenticated API. The VPS pushes read-optimised snapshots to Cloudflare KV at the edge. == Repo Access Control === Visibility Strategy [cols="2,2,3"] |=== | Repo State | GitHub Visibility | Access Via | Active, accepting contributions | Public, branch-protected | Portal -> direct link | Active, internal only | Private or read-only | Portal shows status; OAuth grants access | Archived/complete | Public, read-only | Portal shows final state; repo is reference only | Early/experimental | Private | Portal shows roadmap placeholder; no repo link |=== === Contributor Flow 1. Visitor arrives at `hyperpolymath.github.io` 2. All public content (dashboard, search, project status) available without auth 3. "I want to contribute" triggers GitHub OAuth 4. VeriSimDB checks contributor identity against known contributors 5. Recognised: API returns scoped repo list; GitHub API grants read/write on specific repos 6. Unknown: Portal shows public view + instructions for requesting access === Use Cases Served Without Repo Access * "When was this last updated?" — Temporal modality (meaningful state change, not commit date) * "Show me the map" — Clade navigator * "Where is that version I need?" — Search -> semantic version -> download link * "What is the checksum?" — Provenance modality, attestable * "I just need the setup instructions" — Document modality, indexed README section * "What happened to my feedback?" — Feedback octad with provenance + status tracking * "Did they ever act on it?" — Pointer from feedback to resulting commit/TODO/decision None of these require GitHub literacy, git knowledge, or repository access. == Master Index Repository === Name and Location `gv-clade-index` — top-level repository, clade `gv` (governance). === Structure [source] ---- gv-clade-index/ 0-AI-MANIFEST.a2ml .machine_readable/ STATE.a2ml META.a2ml ECOSYSTEM.a2ml CLADE.a2ml verisim/ config.a2ml # DB config schema/ repo.vcl # Repo octad schema clade.vcl # Clade definitions todo.vcl # Work items observation.vcl # Bot findings feedback.vcl # External feedback forge-identity.vcl # PK/FK forge mapping lineage.vcl # Inflate/deflate history seed/ clades.a2ml # 12 clade definitions repos.a2ml # Initial 202 repo registrations forges.a2ml # GitHub/GitLab/Bitbucket accounts queries/ dashboard.vcl # Full ecosystem overview stale.vcl # Repos with no activity in 90+ days orphans.vcl # Repos without clade assignment drift.vcl # STATE.a2ml diverged from reality bot-findings.vcl # Unacknowledged bot observations blocked.vcl # TODOs blocked by other TODOs cross-clade-deps.vcl # Dependencies crossing clade boundaries feedback-status.vcl # All feedback with resolution status sync/ ingest-state.rs # Pull STATE.a2ml from repos -> octads ingest-git.rs # Pull git metadata -> temporal modality ingest-bot.rs # Pull bot logs -> observation octads export-state.rs # Push VeriSimDB state -> per-repo STATE.a2ml export-kv.rs # Push public snapshot -> Cloudflare KV contractiles/ must/ clade-hygiene.a2ml # Every repo MUST have CLADE.a2ml Justfile ---- == Implementation Phases [cols="1,3,4"] |=== | Phase | Deliverable | Outcome | 0 | Create `gv-clade-index` repo with schema and seed data for 202 repos | Clade taxonomy exists; all repos assigned | 1 | Write `CLADE.a2ml` for all repos (batch script) | Every repo declares its identity | 2 | VeriSimDB instance on VPS; ingest seed data + git metadata | Central database live | 3 | Cloudflare Worker with `/v1/repo/:id` and `/v1/clade/:code` | API exists | 4 | Replace github.io with ReScript/WASM portal calling API | Portal live | 5 | Add `/v1/llm` endpoint with API key auth | LLMs can query ecosystem | 6 | Bot write endpoints; migrate TODOs to octads | Unified work tracking | 7 | Contributor GitHub OAuth + scoped repo access | Access control live | 8 | Repo lockdown: selected repos private/read-only | Full security posture |=== Phases 0-3 are the foundation. Phase 4 is where the portal becomes real. Phases 5-8 are the access control layer. Each phase is independently valuable. == Appendix A: Example VCL Queries === Ecosystem Overview [source,sql] ---- SELECT clade.primary, COUNT(*) as repo_count, AVG(tensor.completion) as avg_completion, MAX(temporal.last_activity) as latest_activity FROM OCTAD WHERE semantic.type = 'repo' GROUP BY clade.primary ORDER BY clade.primary ---- === Stale Repos [source,sql] ---- SELECT identity.canonical_name, clade.primary, temporal.last_activity, DRIFT(document.state, temporal.activity) as staleness FROM OCTAD WHERE semantic.type = 'repo' AND temporal.last_activity < NOW() - INTERVAL '90 days' ORDER BY staleness DESC ---- === Unacknowledged Bot Findings [source,sql] ---- SELECT document.title, document.body, provenance.actor, graph.repo, temporal.created FROM OCTAD WHERE semantic.type = 'observation' AND provenance.actor_type = 'bot' AND NOT EXISTS(temporal.acknowledged) ORDER BY temporal.created DESC ---- === Cross-Clade Dependencies [source,sql] ---- SELECT source.clade.primary as from_clade, target.clade.primary as to_clade, source.identity.canonical_name as source_repo, target.identity.canonical_name as target_repo FROM OCTAD source JOIN OCTAD target ON source.graph.depends_on CONTAINS target.identity.uuid WHERE source.semantic.type = 'repo' AND source.clade.primary != target.clade.primary ---- === Feedback Resolution Status [source,sql] ---- SELECT document.title, semantic.status, provenance.actor as submitter, temporal.created, temporal.resolved, graph.resulted_in FROM OCTAD WHERE semantic.type = 'feedback' ORDER BY temporal.created DESC ---- === Inflate/Deflate History [source,sql] ---- SELECT identity.canonical_name, lineage.type, lineage.inflated_from, lineage.deflated_into, lineage.born FROM OCTAD WHERE semantic.type = 'repo' AND (lineage.inflated_from != '' OR lineage.deflated_into != '') ORDER BY lineage.born DESC ---- == Appendix B: Token Cost Comparison [cols="3,1,3,1"] |=== | Task | Current Cost | VeriSimDB Approach | New Cost | Find all repos in reversibility stack | ~400K tokens (5 agents) | VCL on clade.primary = 'fv' | ~500 tokens | Check what's stale | ~200K tokens (git log on 202 repos) | VCL WHERE days_since_activity > 90 | ~300 tokens | Read bot findings | ~150K tokens (grep bot logs) | VCL WHERE provenance.actor_type = 'bot' | ~300 tokens | Load session context | ~80K tokens (read 53 memory files) | VCL WHERE temporal.updated > last_session | ~1K tokens | Resolve repo identity question | ~50K tokens (read both repos) | VCL WHERE canonical = true | ~200 tokens |=== == Appendix C: Repo Assessment Summary The following 15 projects were assessed as derailed/scattered and are the immediate motivation for this specification: . **januskey** (fv) — 100% complete, production-ready, no connection to valence-shell . **valence-shell** (fv) — 72% complete, research prototype, no connection to januskey . **ochrance** (fv) — 0%, early scaffold, *conflicts with ochrance-framework* . **ochrance-framework** (fv) — 5%, design phase, *conflicts with ochrance* . **reposystem** (rm) — 95%, near-complete, boundary unclear (which sub-projects belong?) . **contractiles** (in reposystem) — functional, 37 repos adopted . **checky-monkey** (gm) — 0%, scaffolded only, should it be in reposystem? . **grim-repo** (rm) — 0%, scaffolded only, overlaps with reposystem's purpose . **branch-newspaper** (ap) — 0%, scaffolded only, Phoenix/Elixir . **intsoc-transactor** (pt) — 40%, most progress of the derailed set . **nexia-list** (ap) — 70%, most advanced non-reposystem project . **hyperpolymath.github.io** (gv) — 100% but static; to become WASM portal . **seamstress** (gv) — 50%, orphaned architecture tool . **palimpsest-license** (gv) — 100%, complete . **palimpsest-plasma** (gv) — 40%, OCaml engine in design, contractiles duplication All 15 projects' organisational problems are resolved by this specification's clade taxonomy, VeriSimDB registry, and portal architecture.