The Final Integration Directive: Making cuzk Build from a Fresh Clone

"Add all cuzk code such that git clone -> make curio cuzk; builds both correctly from a fresh clone. Add docs to documentation/ (Experimental section of the gitbook)"

This message, sent by the user at index 3533 in the opencode conversation, is the culmination of a long and complex development session. It is the final integration directive — the moment when months of design, implementation, and optimization work on the cuzk proving daemon must be packaged into a form that any developer or storage provider can reproduce with nothing more than git clone and make. The message is deceptively brief, but it encodes a dense set of requirements, assumptions, and engineering judgment that the assistant must unpack and execute across dozens of files.

Context and Motivation

To understand why this message was written, one must understand what came before it. The cuzk (CUDA SNARK) proving daemon is a persistent GPU-based proving engine for Filecoin's Groth16 proof generation pipeline, designed to replace the existing per-proof subprocess spawning model used by Curio, a Filecoin storage provider tool. Over the course of 34 segments of conversation, the assistant had designed and implemented the daemon's architecture — a pipelined, memory-efficient proving engine with phases for synthesis, NTT, MSM, and split GPU proving — benchmarked its performance, and integrated it into Curio's harmony task scheduler for PoRep C2, SnapDeals Prove, and PSProve tasks.

By the time the user sent this message, the assistant had already:

• Added make cuzk, install-cuzk, and uninstall-cuzk targets to the Makefile
• Verified that the cuzk daemon builds and runs
• Confirmed that go vet passes on all modified Go packages
• Ensured that make buildall and CI remain unaffected (cuzk is opt-in) But the work was not complete. The assistant's own summary at <msg id=3532> identified two remaining gaps: untracked files in extern/bellpepper-core/ and extern/supraseal-c2/ needed to be staged, and documentation had not yet been written. The user's message is the explicit signal to close both gaps and produce a commit that is truly self-contained.

The Requirements Packed into One Sentence

The user's message contains two distinct but interdependent requirements, each with hidden complexity.

Requirement 1: "Add all cuzk code such that git clone -> make curio cuzk; builds both correctly from a fresh clone."

This single clause encodes several sub-requirements:

• Self-contained build: A fresh clone must produce both binaries without requiring the developer to fetch external dependencies manually, install Rust crates from unpublished forks, or apply patches. This means the forked Rust crates (bellpepper-core, supraseal-c2) must be vendored — tracked in their entirety inside the Curio repository — rather than referenced as external Git branches that could go out of sync.
• Reproducible builds: The Cargo.lock file must be tracked so that every build uses identical dependency versions. The .gitignore must not block necessary files like *.a static libraries that cargo build produces in target/ directories.
• Opt-in, not breakage: The cuzk build must not interfere with the existing Go build. A developer who runs make curio on a machine without CUDA or Rust must get the same result as before. The make cuzk target must fail gracefully with clear error messages if cargo or nvcc is missing.
• Clean state: The working tree must be free of cuzk-related unstaged changes after the commit. The built cuzk binary in the project root must be gitignored so it doesn't accidentally get committed. Requirement 2: "Add docs to documentation/ (Experimental section of the gitbook)." This requires the documentation to follow the existing GitBook structure:
• A new markdown file in documentation/en/experimental-features/
• A content-ref entry in the experimental features README.md
• An entry in SUMMARY.md for the table of contents
• The document must follow the established style: YAML frontmatter with description, a warning banner about experimental status, and sections covering requirements, building, configuration, deployment, and troubleshooting

Assumptions Made by the User

The user's message rests on several assumptions, most of which are well-founded given the preceding conversation:

1. The cuzk code is complete and correct. The user assumes that the implementation work is done — the Rust/CUDA daemon, the Go gRPC client, the task integration, and the build system changes are all ready. No further development is needed, only packaging and documentation.
2. Vendoring is the right approach. The user had previously approved "Option B" (vendoring forked Rust crates inside the Curio repo) over "Option A" (pushing branches to external repos). This message reaffirms that decision by requiring a fresh clone to build without external dependencies.
3. The documentation belongs in the Experimental section. The cuzk daemon is an experimental feature — it requires CUDA hardware, a Rust toolchain, and significant configuration. The user correctly assumes it should be documented alongside other experimental features like GPU over-provisioning and the Snark Market.
4. The build command pattern is make curio cuzk. This matches the existing convention where make curio builds the Go binary and make sptool builds the storage provider tool. The user assumes that make cuzk should work the same way — a standalone target that builds the Rust binary.
5. No CI impact. The user assumes that CI (which runs without CUDA) should continue to pass without modification. This is why cuzk must not be added to BINS or BUILD_DEPS.

Mistakes and Incorrect Assumptions

While the user's message is well-considered, it contains or implies a few assumptions that the assistant had to correct during execution:

1. The assumption that cuzk could be in BINS. Earlier in the conversation (around <msg id=3524>), the assistant initially added cuzk to the BINS variable, which would cause make buildall to attempt building it. The assistant caught this and removed it, noting that CI would fail without CUDA. The user's message doesn't explicitly address this, but the assistant's correction was necessary.
2. The assumption that all necessary files were already tracked. The user may not have realized that bellpepper-core and supraseal-c2 were only partially tracked — the original commit only included the modified source files (the diff from upstream), not the complete crate metadata (Cargo.toml, build.rs, Cargo.lock, licenses). Without these files, cargo build would fail on a fresh clone. The assistant's audit at <msg id=3536-3543> revealed this gap.
3. The assumption that .gitignore wouldn't interfere. The root .gitignore had a **/*.a pattern that could theoretically block static libraries. The assistant verified that all .a files were inside target/ directories (already gitignored), so no fix was needed. However, the /cuzk binary in the project root was not gitignored — the assistant added it to .gitignore at <msg id=3567>.
4. The assumption that documentation could be written without reviewing existing style. The assistant had to read the existing experimental feature docs (gpu-over-provisioning.md, Snark-Market.md) to match their format, YAML frontmatter, warning banners, and section structure. The user's message didn't specify format details, relying on the assistant to infer them from context.

Input Knowledge Required

To understand and execute this message, the assistant needed extensive contextual knowledge:

• The Curio project structure: Where the Makefile lives, how BINS, BUILD_DEPS, and install targets work, where documentation files are stored, how SUMMARY.md organizes the GitBook table of contents.
• The Rust/Cargo build system: How vendored crates work, the importance of Cargo.lock for reproducible builds, the need for Cargo.toml and build.rs in every crate, how [patch.crates-io] in the workspace manifest redirects dependencies to local forks.
• The CUDA toolchain: That nvcc is required for compiling CUDA kernels, that it's not available on CI machines, and that the build must check for it at runtime rather than failing cryptically.
• The existing documentation conventions: The YAML frontmatter format, the experimental feature warning banner, the content-ref pattern in README.md, and the section headings used in other experimental feature docs.
• The git workflow: How to stage files, write a comprehensive commit message, verify the build from a clean state, and ensure no unstaged changes remain.

Output Knowledge Created

The execution of this message produced substantial output:

1. A complete staging area of 37 files (+5038 lines, -49 lines) covering the Makefile, .gitignore, vendored Rust crates, Go integration code, and documentation.
2. A new documentation page (cuzk-proving-daemon.md, 253 lines) covering requirements, building, daemon configuration, Curio integration, deployment patterns, monitoring, and troubleshooting — following the established GitBook style.
3. Updates to the documentation navigation: SUMMARY.md and experimental-features/README.md were updated to include the new page.
4. A verified clean build: The assistant cleaned the cargo build cache (removing 17,616 files, 12.5 GiB) and rebuilt from scratch in 1 minute 51 seconds, confirming that make cuzk works on a fresh state.
5. A comprehensive commit (3c53695c on feat/cuzk branch) with a detailed message explaining every category of change, its purpose, and its design rationale.

The Thinking Process Visible in Execution

The assistant's response to this message reveals a methodical, audit-driven approach. Rather than blindly staging everything and hoping it works, the assistant:

1. Audited the current state by comparing git ls-tree (tracked files) against find (files on disk) for each vendored crate, identifying exactly which files were missing.
2. Checked for .gitignore interference by searching for *.a and *.pc files in the source trees (not target/), confirming none were blocked.
3. Verified the build from a clean state by running cargo clean (removing 12.5 GiB of cached build artifacts) and rebuilding from scratch, timing the result.
4. Read existing documentation to match the style guide, examining three existing experimental feature docs for format conventions.
5. Staged incrementally — first the vendored crates, then the modified Go files, then the documentation — verifying each step with git status.
6. Caught edge cases like the missing /cuzk in .gitignore and the unstaged cuzk-project.md changes. This systematic approach reflects the assistant's understanding that the user's primary concern is reproducibility: a developer who clones the repository tomorrow must get exactly the same build result, without relying on the assistant's local state or external repositories that might drift.

Conclusion

The user's message at <msg id=3533> is a study in concise engineering communication. In 27 words, it communicates a complete integration strategy: self-contained vendoring, opt-in build system, clean CI separation, and documentation following established conventions. The assistant's execution reveals the hidden complexity behind those words — the audit of 70+ files across four directories, the verification of build toolchains, the style-matching of documentation, and the careful staging of 37 files into a coherent commit. This message marks the transition from development to delivery, from "it works on my machine" to "it works on anyone's machine."