Velnor Documentation
Guides

Development

View as Markdown

Development

This is the repository’s current development contract. Citations use path:line.

Navigation: ← Security and data · Index · Next: Contributing →

Current: build, test, lint, format

The workspace has 12 members and uses Cargo resolver 3, Rust edition 2024, and a shared dependency table. The pinned toolchain is Rust 1.98.0 with rustfmt and clippy; the workspace keeps rustfmt’s style edition at 2021. Cargo.toml:1-21 rust-toolchain.toml:1-10 rustfmt.toml:1-2

mise is the task entrypoint. Install the pinned Rust toolchain selected by rust-toolchain.toml, then install the tools declared in mise.toml: mise, actionlint, cargo-deny, cargo-nextest, cargo-zigbuild, cargo-deb, and Zig. The lockfile is mandatory, and CI/jobs use locked artifacts. Run these current gates:

mise run fmt
mise run lint
mise run test
mise run test-production-topology
mise run test-release-feature-boundary
mise run actionlint
mise run deny
mise run check
  • fmt is read-only: cargo fmt --all --check. fmt-fix is the in-place formatter.
  • lint runs workspace/all-target clippy with all targets, --locked, runner test-support, and -D warnings.
  • test runs workspace cargo nextest with --locked and runner test-support.
  • test-production-topology checks every workspace target with default production features. The release-boundary task must fail if release code is built with the loopback-only test-support feature.
  • actionlint checks workflow syntax; deny runs advisory checks. check is the aggregate gate and also runs the offline CI/fleet policy tasks. Fleet policy generation is a privileged publisher operation: set VELNOR_FLEET_POLICY_OUT_DIR to the provisioned absolute root-owned directory. audit-ci, fleet-plan, and the runtime read that same directory when the variable is set; without it, repository checks read the committed fleet/policies/ snapshots.

These commands and their exact arguments are defined in mise.toml:18-51 mise.toml:68-85 mise.toml:142-149. For a focused loop, use mise run test-focused -- -p <package> or mise run test-focused-runner; the latter enables runner fixture support. mise.toml:31-37

The current tagged release build uses:

cargo zigbuild -p velnor-runner -p velnorctl -p velnor-tools \
  --release --locked --features release-build --target "$TGT"
cargo deb -p velnor-runner --target "$TGT" --no-build --no-strip \
  --deb-version "$VERSION"

The guest-image and identity stages run separately in release CI. The runner manifest and release workflow define this cross-build/package sequence. crates/velnor-runner/Cargo.toml:25-34 release.yml:653-654 release.yml:746-749

Current: crate ownership and dependency law

Ownership is layered:

The law is enforced from cargo metadata, not by convention: the graph must be acyclic; shared crates must not depend on Clap or Axum; client must not reach daemon internals transitively; control’s direct workspace edges are allowlisted; and the legacy runner allowance is explicitly transitional. crates/velnor-client/tests/dependency_boundaries.rs:1-10 crates/velnor-client/tests/dependency_boundaries.rs:370-423 crates/velnor-client/tests/dependency_boundaries.rs:425-507 crates/velnor-client/tests/dependency_boundaries.rs:509-565

Current: fixture and golden evidence

Evidence is structured, deterministic, and fail-closed:

Current: contributor and security rules

  • Match runner protocol behavior to actions/runner before writing protocol code; do not guess. Finish migrations by deleting old paths—no compatibility shims, aliases, or deprecation periods.
  • Never cancel the named release/package workflows or release dispatches. The current tree ships no COORDINATION.md; coordinate suspected stale runs with the release owner before any external action. This is a research project and is not production-ready.
  • For bugs, inspect why the architecture allowed the bug class and related bugs; prefer a structural fix that removes the enabling condition. Use a symptom patch only when the root fix is infeasible or separately scoped, and name it.
  • Keep dependency resolution and CI commands locked. Run cargo deny check advisories; the sole current advisory exception is RUSTSEC-2023-0071, documented as the RSA Marvin timing side-channel not reachable on Velnor’s local ephemeral OAuth-JWT signing path. mise.toml:10-15 mise.toml:71-72 deny.toml:1-8
  • Keep test-only loopback support out of release builds. The release feature boundary is an explicit gate, and the runner manifest says test-support is for repository tests while release binaries reject it. mise.toml:43-51 crates/velnor-runner/Cargo.toml:154-163
  • Treat fixture and golden data as potentially sensitive. Sanitize endpoint credentials, assert secret absence, and preserve only structured evidence; the collector's fail-closed evidence behavior is implemented in tools/unit-collector/src/evidence.rs:260-291. crates/velnor-runner/tests/telemetry_integration.rs:26-35

Current: product boundary

  • Phase 0 means proving existing Rust CI/CD workflows against the public fixture first. Velnor-native workflow language, YAML scheduling, and macOS job execution are outside the current scope (docs/concepts/system.md:73-79).

Future / planned — not current procedure

  • The velnor-runner library dependency in velnorctl is interim. Plan 079 is the stated deletion point for the runner binary and remaining plumbing; do not add new dependencies to extend that transition. (crates/velnorctl/Cargo.toml:31-42).
  • unit-collector TASK-004 is not complete until the real Parallax ordinary-PR attribution report exists. Committed synthetic fixtures are current evidence, not completion proof (tools/unit-collector/tests/fixtures.rs:9-70).

Contributing documentation

Previous Page

Job execution

Next Page