§ 8 · Contribute
Contributing to Fidryn
On this page
This file is for people building the v0.1 reference interpreter. It is not a language tutorial and not legal advice. Product usage lives in the README and the documentation hub.
Fidryn (FID-rin) is a research fixture. Modules under examples/ and
records under tests/ exercise the interpreter. They are not operative
instruments and not a complete statement of any jurisdiction's law.
8.1 Toolchain #
Rust 1.98, edition 2024. Workspace package.rust-version is 1.98.
rust-toolchain.toml pins the 1.98.1
channel and the rustfmt and clippy components.
If cargo or git pick the wrong tools on this Mac, a working PATH is
/opt/homebrew/bin:$HOME/.cargo/bin:/usr/bin:/bin, with
DEVELOPER_DIR=/Library/Developer/CommandLineTools.
.cargo/config.toml already points the linker
at Command Line Tools clang because the Xcode license is unsigned.
8.2 Checks #
From the repository root:
cargo fmt
cargo clippy --workspace -- -D warnings
cargo test --workspace --offlinecargo xtask ci runs the tests and clippy, then the conformance
probes and the Python checks (ruff and mypy), the site check, the
JavaScript tests when Node is installed, and a bench build;
cargo xtask ci --fmt also checks Rust formatting first. The Python steps
need uv: uv run provides the Python
that .python-version names and the packages uv.lock pins. GitHub
Actions runs cargo xtask ci --fmt on every push to main and every
pull request (.github/workflows/ci.yml); the runner builds its own
.venv from uv.lock, and nothing it builds is committed.
Do not weaken no-false-determinacy to make a test pass.
8.3 Website #
The public site in site/ is generated from these guides
by the workspace task runner. After editing a guide in docs/, run:
cargo xtask siteand commit the markdown together with the regenerated files under
site/. cargo xtask site --check fails when the committed site is
stale, and cargo xtask ci runs that check. The landing page's
specimen is evaluated by the real interpreter at build time, so a
change in semantics also makes the site stale.
The stylesheet and script in site/assets/ are written by hand. The
mill, whose page lives in web/, embeds the stylesheet
fidryn.css and has its own script, web/mill.js. When Node is
installed, cargo xtask ci also runs the JavaScript unit tests in
web/tests/; Node is never needed to build or serve anything.
8.4 Pipeline #
Land a change in the crate that owns that stage:
syntax → hir → check → core → eval → handlers → verify → driver → clifidryn-kernel sits beside verify: it accepts or rejects covering
claims and does not search. fidryn-trace, fidryn-solve,
fidryn-adapt, and fidryn-render support the pipeline; they are not
extra stages.
Do not add reverse dependencies. Do not put evaluator logic in
syntax. Do not put parser logic in core. fidryn-driver must not
depend on fidryn-cli.
8.5 Crates #
Workspace members are listed in Cargo.toml.
fidryn-syntax lossless CST, parser, formatter
fidryn-core IR, types, Outcome, LegalState, diagnostics
fidryn-hir names, imports, elaboration (syntax + core)
fidryn-check types, effects, authority, time, strata (hir + core)
fidryn-eval worklist evaluator (core)
fidryn-handlers CaseFile, Scenario, Explore, Skeptical (core + eval)
fidryn-verify bounded explorer and invariants (eval + handlers)
fidryn-kernel covering-check boundary (accept/reject; no proof gen)
fidryn-driver incremental check/run memo
fidryn-trace DAG, canonical JSON, source maps (core)
fidryn-render constrained templates (missing keys fail closed)
fidryn-adapt capability-gated filing adapters
fidryn-solve bounded DPLL over declared finite domains
fidryn-cli fidryn binary and localhost mill8.6 Tests #
Tests live next to the crates they exercise (#[cfg(test)] in src,
and crates/<name>/tests/ when a crate has an integration kit).
The adversarial review kit is
tests/integration/adversarial_regressions.rs.
Those tests are regressions, not closure of the language.
Independent programs live under tests/programs/.
crates/fidryn-verify/tests/domains.rs
runs them as independently named modules. Do not rewrite compiled Core
to green fingerprint tests. Patching a CoreModule so a digest, plan,
or outcome matches is not a passing test.
8.7 Commits #
Use Conventional Commits (feat(syntax): ..., fix(eval): ...,
test(cli): ..., docs: ...). Prefer atomic commits in pipeline order,
then tests and docs. Do not dump unrelated crates into one commit.
8.8 Grammar #
The closed v0.1 grammar is grammar.ebnf at the
repository root. Unknown body fields are parse errors, not extension
points.
8.9 Implementer documents #
These files are crate contracts and evidence. They are not user tutorials.
- ARCHITECTURE.md — Frozen crate graph, public APIs, and the pipeline of total functions over trees.
- implementation-status.md — Evidence-backed capability matrix. A
.frfile is not an executable specification. - OBLIGATIONS.md — Review obligation matrix. Green workspace tests are regressions, not language closure.
- WORKSTREAM-CONTRACT.md — Shared types and acceptance for covering certificates,
seq/require, tax, and trust profiles. - INTEGRATION-CONTRACT.md — Wire existing machinery into ordinary compile, eval, and CLI paths. Do not reimplement helpers.
Mill HTTP routes are documented in mill.md, not in ARCHITECTURE.md.
8.10 Not legal advice #
This interpreter, its tests, and its example modules are not legal advice.
The modules, records, and examples here are research fixtures. They are not legal advice, not operative instruments, and not a complete statement of any jurisdiction’s law.