Contribute to Chio
Work on the kernel, the CLI, and the SDKs from the public source, and run the gates every change passes.
On this page
Chio is one Rust workspace at github.com/backbay-labs/chio, with the SDKs, the protocol specification, the formal models, and the verifier fixtures beside it. Applications run on the installed chio and the published SDKs. These pages are for changing Chio itself.
The repository
Each top-level directory owns one kind of source. A change usually touches one crate family and the specification or fixtures that pin its behavior.
| Directory | Contents |
|---|---|
crates/ | The workspace, grouped by family: core, kernel, guards, protocol, trust, security, economy, platform, observability, products (the chio CLI lives at crates/), sdk, and tooling. |
sdks/ | The language SDKs: TypeScript, Python, Go, Rust, JVM, .NET, C++, Swift, and the guard SDK. |
spec/ | The normative protocol in spec/, the JSON schemas, the error registry in spec/, and the IETF draft sources. |
formal/ | Lean 4, Apalache, Aeneas, and differential- formal/ tying each model to the Rust it covers. |
fixtures/ | The signed corpora the verifiers check, including the Proof Room tree. |
examples/ | Source verifiers for each protocol edge and framework adapter, and the smoke runner that drives them. |
scripts/, xtask/, ci-gates/ | The behavioral gates, the workspace task runner, and the facet manifests the fixture gates read. |
Send a change
- Branch from
mainand keep the change to one logical unit. - Build the workspace with the toolchain the checkout pins.
- Run the verification gate: build, test, clippy, and format check.
- Update
spec/PROTOCOL.mdin the same pull request when a wire format changes, and regenerate any output the drift gates cover. - Write the commit subject as a Conventional Commit, such as
fix(guards): deny on malformed egress allowlist entry.
Report a security vulnerability through the coordinated disclosure process in SECURITY.md, never as a public issue.
House rules
- Fail closed. An error during evaluation denies the call, and an invalid policy is rejected at load. No error path may widen authority.
- No
unwraporexpect. Clippy denies both across the workspace; propagate the error. - Canonical JSON. Signed payloads use RFC 8785. Changing how a signed structure serializes changes every signature over it, so coordinate the wire and conformance impact first.
- One error code per failure. A new refusal gets a specific code in
spec/errors/registry.yamlwith help text that names the flag or value that fixes it.
In this section
Build from sourceClone the public source, install the toolchain, and build the CLI and the language server.Checks and qualificationThe verification gate, the xtask runner, the behavioral scripts, and the example smoke runner.Proof fixture corpusThe signed scenarios the verifiers prove against, their trust anchors, and how to add a negative case.