# Build boundaries and contributor checks

> Understand the fast checks, selective VM suites, and build boundaries.

Canonical page: https://docs.tentaflake.dev/reference/builds/

> Source: [`docs/17-builds.md`](https://github.com/timfewi/tentaflake/blob/e21be475a3afc6e95c5087003edd0b7f780e4df4/docs/17-builds.md) at `e21be475a3af` · docs version **0.4.37**

Start with `just fast`. It runs formatting, Nix lint, ShellCheck, Rust checks,
the CI-selection/source-boundary regressions, read-only flake evaluation and
the generated installed flake, including focused adapter evaluation.
`checks.*.agent-adapters` covers compatible mappings, JSON, inventory, lazy
selection, stopped OpenClaw, quota declarations and generated quota-helper refusal
regressions without mounts. Required research closure preparation uses
non-VM builds. `just e2e` still runs the complete gate, both VM suites and the
installer ISO. Run an affected VM suite when changing runtime or security
behavior; use the ISO gate when changing installation.

## Rust cache boundaries

Cargo remains the Rust build definition. `[workspace.package]` in `Cargo.toml`
supplies the shared version; each crate supplies its package description.
Nix packages and the worker image read those manifests. A replaced worker
image supplies its default local reference through `imageName`/`imageTag`;
images without those attributes require an explicit `worker.imageReference`.

Each Rust Nix source contains root Cargo files, all member manifests, and the
selected crate's complete source. Cargo can resolve the workspace while an
unrelated crate source edit leaves the other package derivations unchanged.
Shared manifests, dependencies or toolchain changes still invalidate affected
builds. Declare additional root build inputs explicitly; add shared/path
dependencies to the fileset when introducing them.

A comparison of actual Nix derivation paths with a temporary CLI source edit
invalidated all three packages before this boundary and only the CLI after it.
All three focused-source packages built successfully. This establishes cache
isolation, not a fixed wall-clock speedup. `checks.*.rust-package-sources`
guards manifest availability, source isolation and the worker image version.

## GitHub check selection

The imported policy is `.github/ci-paths.json`; its consumer is
`scripts/ci_changes.py`. One ordered policy selects non-VM checks and the two
VM suites independently. Component paths take precedence over Markdown suffixes.

| Change | Non-VM checks | VM suite |
| --- | --- | --- |
| Docs and listed presentation metadata | Routing regression and whitespace; no Nix setup/cache | None |
| CI routing/workflow/test definition | Routing regression, focused selection package and static checks | None |
| One Rust crate/package | Rust workspace checks, that package and source-boundary check; worker includes its image | Runtime |
| Worker module | Rust workspace/worker package and image; actual worker configuration and policy in the runtime fixture | Runtime |
| Shared Cargo inputs | Rust workspace and all three packages/image; no Research/configuration preparation | Runtime |
| Installer scripts or host VM fixture | Static checks and generated installed flake | Runtime |
| Installer Nix | Configuration evaluation, static checks and generated installed flake | Runtime |
| Research module/client/fixture or research-only input pin | Research/configuration preparation and evaluation, static checks and generated installed flake | Research |
| Dev Container inputs | Dev Container package and static checks | None |
| Generated-flake script or module-evaluation fixture | Its generated-flake or configuration gate and static checks | None |
| Onboarding validator/fixture | Installed preset/generic CLI fixture and static checks; no Research preparation | None |
| Operator onboarding CLI module | Rust/CLI package, source-boundary and installed fixture checks; no Research preparation | None |
| Shared JSON agent parser | Installed fixture and static checks; no Research preparation | Runtime |
| Adapters, shared modules/helpers, other lock updates, unknown paths/history | Full gate | Both |

The selector reads NUL-delimited Git paths and includes deleted/old rename
paths. Invalid lock data requires the full gate. The real-Git regression check
runs on every event directly on the runner; `checks.*.ci-vm-selection` also
packages it for the contributor gate. CI metadata changes are covered by these
regressions rather than building unchanged guest systems.

Documentation does not start Nix installation, cache upload, Research closure
materialization, full flake evaluation or Rust/system builds. A Rust-only change
does not build the separate Research service. Worker-module changes use the
same focused package/runtime gates: the Research fixture enables no workers.
Mixing these changes with shared security paths retains the full gate.
Non-VM package builds run in
groups of at most four. Configuration evaluation still prepares the exact
Research closures because the full flake/module fixtures need them; shared
configuration changes retain their applicable runtime and Research evidence.
Onboarding validation uses the installed fixture rather than full flake checks;
its CLI binary is a small selected package or an explicitly supplied local binary.
The standalone host build runs only for configuration changes affecting the
runtime, not for a Research-only or documentation change. Full VM/ISO/system
workloads remain separate from local fast checks and require their own scope.
New pushes cancel superseded runs for the same PR or branch.

## Nix and Bazel

[Nix + Bazel](https://nix-bazel.build/) and the linked
[rules_nixpkgs guide](https://github.com/tweag/rules_nixpkgs/blob/master/guide.md)
describe providing Nix toolchains/dependencies to Bazel's finer build actions.
That approach can help a large code graph with reusable remote actions.

Tentaflake currently has three independent Rust binaries, plus NixOS modules
and VM tests. Cargo already provides incremental development builds. Narrower
Nix sources retain the other binaries' cached packages, and VM selection avoids
irrelevant guest boots. Bazel would require another target/dependency graph and
cache configuration while the NixOS/VM work remains. No Bazel speedup has been
measured here. Keep Cargo/Nix as the build definition for now; reconsider a
bounded Bazel prototype if measurements show compilation dominates after these
changes or the workspace grows into a larger shared code graph.