Contributing

Contributing

Thank you for looking. The full guide is CONTRIBUTING.md; this page is the short version.

The licence, first

• The server (crates/, gui/, root files) is BUSL-1.1, not open source in the OSI sense. You may read, build, modify and use it for anything that is not Production Use. It converts to Apache-2.0 on the Change Date in LICENSE.
• An Additional Use Grant states that verification is not Production Use: running verify-cert on a certificate is permitted for any purpose, commercial included.
• The SDKs (sdk/python, sdk/typescript) are Apache-2.0.

By submitting a contribution you agree that contributions to sdk/ are licensed under Apache-2.0, and contributions to the BUSL-1.1 directories are licensed by you under Apache-2.0 to the Licensor named in LICENSE, so they can be distributed under BUSL-1.1, under Apache-2.0 on the Change Date, and under commercial licences without a separate contributor licence agreement.

Before you open a pull request

make verify          # fmt --check, clippy -D warnings, build --all-targets, commit trailers
make test            # cargo test --workspace
cd gui && npm run check
make test-e2e        # if you touched the agent, guard, sandbox, policies or the app (needs Ollama)

If your change touches PostgreSQL behaviour and you have Docker:

./scripts/test-integration.sh

Requirements: Rust 1.94 or newer; Python 3.11 or newer for the check scripts in scripts/ (the Python SDK itself supports 3.10); Node 22.13 or newer for the GUI unit tests.

cargo test --workspace alone is not enough: it builds only what the tests need. make verify runs --all-targets, which catches a bench, example or ignored test that no longer compiles.

CI is manual

Every workflow is workflow_dispatch-only. Nothing runs on a push or pull request, on this repository or on forks. A maintainer starts CI by hand, so make verify locally is the real gate. Coding agents must not dispatch or rerun workflows; run checks locally.

Commit messages

• make verify fails on AI-assistant attribution trailers (Co-Authored-By lines for an assistant, "Generated with" footers, session URLs). Use an assistant if you like; leave its footer out. python3 scripts/check-commit-trailers.py --all audits the whole history.
• Say what changed and why the alternative was rejected.

Structural rules

• crates/core has no I/O. Pure domain logic only.
• The hash chain and signing code is a compatibility contract. crates/core/src/hash.rs, crates/host/src/signing.rs and crates/host/src/ledger/ decide whether existing ledgers still verify. Migration fixtures must keep passing.
• crates/guest and crates/guard_unikernel stay outside the workspace. crates/elc-wasm is a member, built by make wasm-verifier.
• Recording and preventing are different products. docs/guides/integrations.md keeps a matrix of what each surface sees and can stop. A change that blurs the two cannot be accepted.
• Say what you did not check. A pull request that adds an honest limit to docs/reference/threat-model.md is as welcome as one that removes one.

Documents that must stay in sync

If you change	Update
crates/core/src/schema.rs, migrations	docs/reference/schema.md
main.rs arguments	docs/guides/cli.md
config.rs, feature flags	docs/guides/configuration.md, .env.example
The .elc format	docs/reference/elc-spec.md and examples/verified-session/verify_elc.py

The test suite enforces some of these. The Python verifier in examples/verified-session/ is written from the specification, not the Rust, and a test fails if the two disagree: change the spec first.

Useful make targets

Target	Does
make help	Lists the targets
make setup	Build the CLI and install GUI dependencies (no servers started)
make start	Start the desktop GUI with its embedded backend
make demo	Zero-config demo: SQLite ledger, demo mode, no Docker or Postgres
make demo-hook	Hook denial demo, no model or Postgres needed
make test-qa	Workspace tests, workflow and Tauri guards, hook demo
make test-api	Black-box HTTP API suite against a fresh server
make check-sdk	Every server route wrapped by both SDKs
make test-gui-unit	GUI unit tests
make wasm-verifier	Rebuild the browser verifier

Where things are

• Crates and layout: docs/reference/architecture.md
• What is tested and how: docs/reference/testing.md
• Feature flags and variables: docs/guides/configuration.md

Security problems: not in issues or pull requests. See Security and Reporting.