Development and Operations

Development and Operations

Stack

BHCP is a Rust-only repository-owned implementation. Rust 1.97.1 is pinned in .mise.toml and in the crate manifest. Runtime dependencies are pinned Rust crates: cddl for RFC 8610 parsing/validation support and RustCrypto sha3 for SHA3-512. The repository has no project-owned Ruby, Python, Node.js, or C toolchain.

Install the pinned toolchain:

mise install

Local quality gate

Run the same four checks before delivery:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo build --release

The 17-root CDDL fixture gate is part of the Rust test suite and can be run directly with:

cargo test --test schema_fixtures

Use cargo run --bin generate-fixtures only when intentionally regenerating checked-in AST/IR fixtures, then review deterministic byte changes.

CLI smoke path

cargo run -- parse conformance/v0/fixtures/canonical-simple.bhcp > /tmp/canonical-simple.ast.cbor
cargo run -- lower conformance/v0/fixtures/canonical-simple.bhcp > /tmp/canonical-simple.ir.cbor
cargo run -- inspect conformance/v0/fixtures/canonical-simple.bhcp
cargo run -- inspect /tmp/canonical-simple.ir.cbor
cargo run -- hash conformance/v0/fixtures/canonical-simple.bhcp

parse and lower emit CBOR, inspect emits a human-readable outline, and hash emits the algorithm-tagged semantic ID. JSON is not a BHCP repository artifact format.

Delivery status

• Implemented: the Rust quality GitHub Actions workflow runs formatting, warnings-as-errors Clippy, all-target tests, a release build, and the exact 17-root CDDL fixture invariant as five independent jobs on every pull request and main push. Actions are commit-pinned and Cargo dependency caches are keyed by .mise.toml and Cargo.lock.
• Required on main: strict branch protection, including for administrators, requires Rust quality / Format, Rust quality / Clippy, Rust quality / Tests, Rust quality / Release build, and Rust quality / 17-root CDDL fixtures; force pushes and deletion are disabled and review conversations must be resolved.
• Implemented: the repository-local AGENTS.md operating contract and project-loop profile define authority, issue selection, atomic remote-ref claims, TDD, protected review/merge, fenced release, and completion reconciliation.
• Implemented: squash-only auto-merge is matched to the reviewed head SHA, merged topic branches are deleted automatically, and PR bodies use issue-closing links. Disposable probe PR #56 proved that a mismatched expected head and author approval are rejected and that one failed required check keeps queued auto-merge blocked.

Remote CI and branch protection are now authoritative. A local green run remains the required fast feedback loop, but is not a substitute for the protected hosted checks or review.

Troubleshooting principles

• Unsupported canonical syntax must return a stable diagnostic; do not silently ignore it.
• For policy failures, use the category-specific BHCP8101–BHCP8107 code or BHCP8110 for source topology. If a weakening message names the wrong earlier rule after several rules compose, inspect the governing contributor rather than provenance order. An invalid layer must return no effective policy; a partial result is always a composer bug.
• If a policy identity mismatch appears, recompute semantic ID from effective only and artifact ID from the complete document with only artifact_id removed. Source layers or provenance changing semantic ID is a projection bug; observable effective rules changing only artifact ID is also a bug.
• Reducer failures in an unselected branch are still definition failures: the whole expression tree must validate before execution. An unknown call must remain a stable kernel diagnostic, and any primitive value or satisfied conclusion that disagrees with its declared type must be rejected before generic derivation verification.
• If any chooses a different winner across equivalent source or observation arrival orders, inspect canonical child-tag ordering. Multiple sealed satisfactions must choose the lexicographically least normalized tag; explicit composition must pass the same winner type boundary as the convenience form.
• If none emits an empty record, accepts a declared output field, or drops counter-evidence from a mixed unresolved result, inspect its inferred goal signature and sealed partial-evidence aggregation. Its output is canonical Unit; satisfaction requires every child's counter-evidence.
• If chain requests or accepts a later child before its predecessor is sealed satisfied, inspect both the observed-output edge and runtime readiness validation. A later-step refutation must retain prior satisfaction evidence as derivation premises; terminal counter-evidence alone does not prove causal reachability.
• Unknown hash algorithms fail before parsing; the project manifest is an agility boundary, not arbitrary dynamic loading.
• Missing verifier registrations remain unresolved evidence gaps; contract strings are never executed as shell commands.
• When schema tests fail, compare Rust model encoding, CDDL, examples, and SEMANTICS in the same change.
• Preserve unrelated worktree changes and never regenerate fixtures incidentally.