Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
The Rust chassis for governed cells.
rahi is the substrate the statecrafting products stand on. It gives an application seven things it should never build twice: identity (rauthy, co-deployed, reached only through the app's own origin), replicated state (hiqlite, in-process, its own Raft cluster), a hash-chained decision ledger, a deny-by-default capability kernel, an axum edge with probes, metrics, and tracing, single-container packaging with preflight, migrate, backup, and restore, and a dev substrate that boots the real binary in tests. An app is a Rust binary that composes the crates and declares a manifest. It extends the chassis; it never forks it.
The name is the lineage: enrahitu was Encore, Rauthy, Hiqlite, Turso. Drop Encore and Turso and what remains is what this is.
This repository is a specification corpus, the harness that builds it, and the code it specifies. Spec ordinals are the build order, and each spec is bounded to one driven session's territory. Specs 036 to 043 and 045 to 049 are implementation: complete, spec 043 with the owner's waivers recorded in its D-36. Spec 044 (the split N=3 composition) is built and implementation: in-progress: its operator qualification on a real three-node cluster, its coherent export and its archive identity remain. Nine crates and the reference app exist (rahi-types, rahi-store, rahi-ledger, rahi-kernel, rahi-edge, rahi-idp, rahi-ops, rahi-cli, rahi-harness, and apps/hello-cell), every source file claimed by the spec that built it. spec-spine registry plan is the live answer to what is buildable now.
Implementation, publication, and operational proof are separate:
| State | |
|---|---|
| Implemented | spec-spine registry list reports each spec's lifecycle. A complete implementation does not imply every deployment procedure was exercised: the N=3 rollout check remains recorded rather than run (032 D-1). |
| Released or installable | Versions 0.1.0 through 0.7.0 published all nine chassis crates. 0.7.0 adds deployment epochs (041), remote identity and the split N=3 overlay for qualification (044), and syncs a cluster's raft log before acknowledging; the release record names its behavior and limits, and 0.7.1 provisions a split cell's backup admin (044 D-13). Publication and anonymous access are proven only after the tag workflows and fresh anonymous checks pass. |
| Exercised against the pinned rauthy | spec 037's live.yml runs the whole suite against rauthy 0.36.2 pinned by digest, with gated skips refused. The proof covers login, audience and scope enforcement, fresh backups, restart, and restore with the original user, note, and ledger head. See spec 037's Status for the passing run and revision. |
| Supported topology | N=1. Three replicas have run only as three processes on one host, without rauthy, in spec 035's test, which CI runs: each replica mints its own decision ids and none of thirty concurrent denials is lost. N=3 on Kubernetes has never run. |
Since 0.2.0, recovery compatibility has changed: new key sets contain an origin-bound backup passkey; old sets are not automatically upgraded and backups refuse without it. It does prevent duplicate ledger IDs after sealing, by spec 042, at the cost of a stop-the-world reindex of any chain sealed before it and one permanent resident row per decision; the CHANGELOG's "Upgrade limits (spec 042)" is the procedure. Since 0.4.0 it uses registry-published hiqlite-patched =0.15.0-patched.3, so consumers must remove the old [patch.crates-io] workaround. After restart, an expired lease is reconsidered only on a fresh request after TTL+1; restart alone does not wake a waiter. Its operational proof is N=1; Kubernetes N=3 has never run. Publication changes no consumer rollout target.
The declared 0.7.1 gaps are explicit. The transition has a backward-clock revocation gap and an old restore can revive refresh credentials. A SIGKILL or shutdown timeout before app-store shutdown completes can leave hiqlite's unclean marker, so the next boot refuses without a manual recovery decision; automatic healing is not enabled, and spec 048 removed every other exit that left the marker. The live suite does not execute Rauthy's mid-cache-rename crash, and a v0.1.0 volume has no supported crossing to this version.
docs/design/01-consumer-contract.md states what a consumer gets and what is proven, by which test, against which identity provider; docs/design/02-operational-prerequisites.md records the measurements behind the table above, the maintainer's decisions of 2026-09-12 on them (section 8.1, recorded in the specs they govern), and the decisions still open.
The corpus is built by claude-observatory, which schedules the lowest-numbered ready spec, drives one fresh session through AGENTS.md's backlog protocol, ships through this repo's own /ship skill and hooks, shepherds the PR through the CI wired here, and runs the spec's ## Verification block after merge. Done is never self-authored.
| Start here | What it is |
|---|---|
| specs/002-chassis-thesis/spec.md | the seven responsibilities, the crate topology, the three-wave build order |
| docs/design/00-lineage.md | what was carried from enrahitu, what was cut, and why |
| standards/spec/constitution.md | the fourteen principles, seven of them frozen at tier 1 |
| specs/000-rahi-bootstrap/spec.md | what a spec is, and the frozen invariants |
| AGENTS.md | the session protocol and the backlog discipline |
| docs/design/01-consumer-contract.md | how to consume the chassis today, and the exact guarantees it gives |
| docs/design/02-operational-prerequisites.md | the gaps a hosted consumer meets first, measured, with the open decisions |
The crate topology:
apps/hello-cell the reference app: manifest, one resource kind, one page (034) rahi-cli the binary composer: serve, preflight, migrate, backup, restore (030) rahi-ops the verbs, first boot, keys, the die-together supervisor (030, 031) rahi-idp rahi-edge rauthy proxy, discovery, sessions axum, middleware, probes, obs (020-024) rahi-kernel rahi-ledger manifest and adjudication decision chain, sealing (013-015) rahi-store hiqlite: txn, query, lock, notify, watermark, migrate, backup (011, 012) rahi-types Error and exit codes, Principal, Revision, Fence, config (010) rahi-harness dev-dependency only: boots the built binary, waits on /readyz (033)
Rust throughout; no Node, no Encore. rauthy is consumed as a released binary in the same container and never forked.
The corpus is governed by spec-spine 0.31.0. make gate runs the gate, read-only throughout (freshness, lint, ownership coverage, coupling, DAG check); make refresh is the writing half, for a session that can commit the regenerated shards; make ci adds the cargo gates once a workspace exists. Derived artifacts under .derived/ are committed and read only through spec-spine subcommands. Every source file inside a crate must be specifically claimed by a spec; a session that adds a file claims it in the spec it is implementing.
sh scripts/statecraft/install-spec-spine.sh # reads spec-spine.toml
make gate
spec-spine registry list
scripts/spec-dag.shcd ../claude-observatory
bun src/index.ts orchestrator projects add /path/to/rahi # registers, qualifies, arms
bun src/index.ts orchestrator dag # the readiness view
bun src/index.ts orchestrator next # the lowest-numbered ready spec
bun src/index.ts orchestrator daemon startThe orchestrator's state root for this project lives under data/, which is gitignored. Any spec can be pulled back to status: draft to hold it for human review; drafts are visible as blockers and never scheduled.
Apache-2.0, see LICENSE. aicortex is Apache-2.0 and hqgit is AGPL-3.0; Apache-2.0 into AGPL-3.0 is the sanctioned direction, so both consume this chassis and both may contribute back under Apache-2.0.