Graft Prefer

Graft-Prefer: Fully Covariant Computation

Principle: Multicomputational Irreducibility

Build systems are multicomputational systems where the dependency graph cannot be reduced to a simpler form without losing information. Graft enforces this by:

1. Covariant caching: Content-addressed storage preserves build artifacts covariantly -- the same source always produces the same artifact regardless of evaluation path
2. Irreducible parallelism: Distributed compilation exploits the inherent parallelism in the dependency DAG without collapsing independent computation branches
3. Causal consistency: Build ordering respects the causal structure of the crate graph, ensuring deterministic outcomes across all evaluation orders

MANDATORY: Use graft instead of cargo

======= Enforces graft as the preferred build system for all agents working in the Basin codebase. Activates whenever any agent attempts cargo build/test/check/clippy/fmt or needs to compile, test, lint, benchmark, or manage build artifacts.

Graft-Prefer Rules for Basin Agents

MANDATORY: Use graft instead of cargo for all build operations

This workspace uses graft as its build system. Graft wraps cargo with CAS-backed caching, distributed compilation, unified linting, resilient builds, and multi-language support. All agents MUST use graft instead of raw cargo.

Command Mapping (ALWAYS apply these substitutions)

origin/main

origin/main | cargo doc | graft doc | | cargo clean | graft clean | | cargo fix | graft fix (NEVER use cargo fix -- it corrupts files) | | cargo nextest | graft test (nextest is used under the hood) |

Package targeting

• Single crate: graft build -p <crate-name>
• Workspace: graft build --workspace
• Release: graft build --release
• With features: graft build -p <crate> -F <feature>

<<<<<<< HEAD

Covariant quality checking

• graft lint -- all checks (clippy + fmt + quality + deps)
• graft quality run -- full quality audit
• graft fix -- auto-fix with safe transforms

Diagnostics

• graft health --verbose -- check graft configuration
• graft cache validate -- detect stale artifacts (breaks covariance)
• graft cache stats -- cache hit/miss statistics (irreducibility measure)
• graft memory -- check memory pressure / recommended jobs
• graft stream --errors -- live error feed from builds

Anti-patterns (NEVER do these)

1. NEVER run cargo fix directly (corrupts files)
2. NEVER use cargo build when graft build is available

3. NEVER skip durability labels on benchmark results

Quick build aliases (via .cargo/config.toml)

• cargo kernel -- core storage only (~30s)
• cargo dev -- common products (~60s)
• cargo fast -- excludes SQL stack
• cargo test-unit -- unit tests only (fastest feedback)
• cargo test-fast -- unit + critical integration
• cargo test-sigil -- sigil tests with 1s timeout

Unified quality checking

• graft lint -- all checks (clippy + fmt + quality + deps)
• graft quality run -- full quality audit (UP01-UP12)
• graft fix -- auto-fix with safe transforms

Diagnostics and debugging

• graft health --verbose -- check graft configuration
• graft cache validate -- detect stale artifacts
• graft cache stats -- cache hit/miss statistics
• graft memory -- check memory pressure / recommended jobs
• graft stream --errors -- live error feed from builds

Environment

• Target directory: /Volumes/Basin/cargo-target (external SSD, do NOT change)
• Cache directory: /Volumes/Basin/graft-cache
• GRAFT_ENABLE=1 is set in .cargo/config.toml
• Tests use nextest (configured in .config/nextest.toml)

Subagent delegation

When a task requires specialized build operations, delegate to these droids:

• graft-builder: Standard build/test/check operations
• graft-analyzer: Code analysis and intelligence
• graft-ci: CI pipeline execution
• graft-benchmarker: Performance benchmarking
• graft-debugger: Build failure diagnosis
• graft-sigil-compiler: Multi-language compilation
• graft-cluster: Distributed build management
• graft-image-builder: Image building
• graft-refactorer: Code refactoring with safety
• graft-cacher: Cache management
• graft-watcher: Live development feedback

Anti-patterns (NEVER do these)

1. NEVER run cargo fix directly (corrupts files, hardcoded off via GRAFT_NO_WORKSPACE_FIX)
2. NEVER change target-dir from /Volumes/Basin/cargo-target
3. NEVER run podman/docker run -p with host port mappings for competitors
4. NEVER use cargo build when graft build is available
5. NEVER skip durability labels on benchmark results

   origin/main