🌐 Website: hypatia.reposystem.dev | Part of the reposystem ecosystem
Hypatia is the CI/CD governance scanner for the hyperpolymath estate (~400 repositories). It combines:
-
Symbolic reasoning — Elixir rules producing fast, deterministic findings, in 42 source files under
lib/rules/(full rule catalogue) -
Neural learning — 8 networks on a shared blackboard, learning which fixes actually stick
-
Bayesian confidence — every recipe carries a Beta-distributed confidence updated from real outcomes, which gates whether a fix is applied automatically, proposed as a PR, or merely reported
-
Machine-checked proofs — Idris2 proofs of the ABI and the decision logic (confidence bounds, safety-triangle routing, dispatch thresholds, quarantine, rollback, the Bayesian update and rate limiting), one Agda model of the Logtalk-to-Elixir migration, and a TLA+ model of the Kin gate that is model-checked on a bounded instance. The proofs are about models of the code, not the Elixir runtime itself. Proof ledger: 22 proven of 42; 0 proven-with-postulates, 11 tested-only, 2 argued, 7 open (details)
"Dumb rules from smart learning"
The system learns complex patterns through neural analysis, then distils them into simple, fast declarative rules that can be pre-emptively injected into new repositories, applied as cures to existing ones, and executed without ML inference overhead.
That loop is the design, not yet the running code. Today the rules are hand-written, and the
neural layer can only lower a recipe’s confidence or demote a finding. The promotion code in
lib/rules/learning.ex has no caller (EXPLAINME).
Every finding is routed Eliminate > Substitute > Control, in that order — remove the hazard if you can, replace it if you cannot, and only then add a control around it. Dispatch is then gated on confidence:
|
auto_execute — applied by robot-repo-automaton |
|
review — rhodibot opens a PR |
|
report_only — sustainabot advisory |
Unknown findings are forced to report_only regardless of score (novelty gating).
panic-attack scan
│ findings
verisim-data (git-backed flat-file store)
│
PatternRegistry ──> TriangleRouter ──> FleetDispatcher ──> DispatchManifest (JSONL)
│ │
└────────────── OutcomeTracker <───────────── dispatch-runner.sh
(Bayesian feedback loop)
|
155 Elixir source files — pipeline, rules, VCL, neural, safety, web, merge orchestration |
|
42 source files: rule modules and their helpers; see the catalogue |
|
8 networks + blackboard, coordinator, persistence, rebalancer |
|
VCL query layer over verisim-data: parser, file executor, cache, federation |
|
12 modules — leases, ledger, ticker |
|
Dashboard, SSE stream, Prometheus |
|
Idris2 ABI — Types, GraphQL, gRPC, REST, FFI, RuleEngine |
|
Zig C ABI bridge — 18 exports + 16 protocol connectors |
|
Rust workspace |
|
Proof ledger and proofs: Idris2, Agda, TLA+ |
See docs/architecture/topology.adoc for the full map.
Guix is the estate’s reproducible-build path; Nix was retired estate-wide on 2026-06-05.
This repository does not track a guix.scm yet. Until it does, mise.toml pins
Erlang/OTP, Elixir and Zig (its other tools float at latest), and
deploy/Containerfile builds the image. Podman, not Docker, is the
container tool.
git clone https://github.com/hyperpolymath/hypatia.git
cd hypatia
just doctor # toolchain preflight
just build-all # Rust workspace + Elixir
just build-ffi # Zig FFI
just compile-abi # Idris2 ABIjust --list shows all 45 recipes; CONTRIBUTING.md treats just as the canonical entry point.
mise.toml pins Erlang/OTP and an Elixir build for that OTP, matching the
OTP 27 / Elixir 1.17 test lane. With mise installed and activated, install and
bootstrap the Elixir dependencies from the repository root:
mise install erlang elixir
mix local.hex --force
mix local.rebar --force
mix deps.get --check-locked
mix testInstalling the toolchain and Hex does not vendor project dependencies:
mix deps.get needs network access to the configured Hex repository (normally
repo.hex.pm). In a restricted environment, use an approved Hex mirror or a
pre-populated dependency cache. Do not interpret a failed fetch as a successful
or clean test run.
The escript exposes six commands:
hypatia scan <path> [--format json|text|github|sarif] [--exit-zero] [--advisory]
hypatia report <path>
hypatia pr-eligibility --owner <owner> --repo <repo> --pr <n>
hypatia secret-alerts --owner <owner> --repo <repo>
hypatia version
hypatia helpMix tasks cover the operational surface — mix hypatia.rsr_score, mix hypatia.recipe_health,
mix hypatia.watch, mix hypatia.triage_issues and twelve more. See the
Operations wiki page.
Running the supervision tree also serves an HTML dashboard, an SSE event stream, a Prometheus
/metrics endpoint and an /api/ on port 9090. With
HYPATIA_API_BEARER_TOKEN set and not empty, every /api/ request needs that bearer
token. Without one, only loopback clients are answered unless
HYPATIA_API_ALLOW_NONLOCAL=true.
The RSR conformance oracle (mix hypatia.rsr_score) is consumed through one
reusable workflow, pinned by full commit SHA:
jobs:
rsr-score:
uses: hyperpolymath/hypatia/.github/workflows/rsr-oracle.yml@<40-char SHA>The pin decides which oracle code runs: the workflow checks this repository out
at job.workflow_sha, i.e. the commit you named, so a consumer never tracks
main. The SSOT stays explicit — the workflow always passes --ssot, defaulting
to <standards>/0-canon/rsr/rsr-criteria-v2.a2ml. See
docs/consumers/rsr-oracle.adoc, including
why an unpinned consumer broke on 2026-10-25.
Hypatia writes JSONL dispatch manifests; dispatch-runner.sh in gitbot-fleet consumes them and
routes each entry by its confidence tier. Outcomes flow back through
mix hypatia.record_outcome, which drives the Bayesian update and, when a recipe degrades,
auto-quarantine.
Development state, milestones and known gaps live in machine-readable form:
-
.machine_readable/descriptiles/STATE.a2ml— current state and milestone status -
.machine_readable/descriptiles/PLAYBOOK.a2ml— operational runbook -
ROADMAP.adoc — milestone history
Before trusting any metric or green board, read docs/DEBT-REGISTER.adoc.
It is the authoritative, evidence-backed account of what is broken, ungated or stale. That
includes the :verisim_data tests excluded from every run and the safety systems that are
built but not yet invoked by any dispatch path.
-
docs/README.adoc — the documentation index
-
Rule catalogue — every rule module and ID family
-
Debt register — what is broken and what is not gated
-
Actions pinning decision — how
uses:refs are pinned here (actions.lock, not inline SHAs) -
Consuming the RSR oracle — the SHA-pinned reusable workflow and the explicit-SSOT contract
-
Consuming the standards governance integration — the immutable standards pin, failure-category taxonomy, runtime prerequisites and bump handoff for the five shared reusables
-
Wiki — getting started, architecture, operations, FAQ
-
Palimpsest Philosophy — philosophical underpinnings (lives in hyperpolymath/standards)
-
robot-repo-automaton — automated repository management
-
git-hud — CI/CD intelligence system
-
rhodium-standard-repositories — repository standards
-
palimpsest-license — the Palimpsest licence
-
OpenSSF Best Practices Badge — security certification programme
Hypatia is licensed under the Mozilla Public License 2.0. Source files declare MPL-2.0 and
documentation declares CC-BY-SA-4.0, both via per-file SPDX headers; where a header and prose
disagree, the header governs.
The Palimpsest Licence (PMPL) is a separate licence maintained at palimpsest-license. It is not a variant or extension of MPL-2.0 and its text is not distributed here. See NOTICE.
