The Architecture of a Plan: How Research Becomes Implementation in the cuzk Proving Engine

In the lifecycle of a complex software engineering project, there is a moment that separates exploration from execution. It is the instant when scattered facts, API signatures, serialization formats, and codebase quirks coalesce into a structured sequence of concrete actions. Message 291 in the cuzk proving engine conversation captures precisely this transition. After four intensive research tasks that spanned the entire codebase—from Rust workspace structure to Go FFI layers to protobuf definitions—the assistant declares: "Good. Now I have a complete understanding of the codebase. Let me plan the Phase 1 implementation precisely." What follows is not code, but a meticulously decomposed todo list that will guide the next several hours of implementation work. This seemingly simple message is, in fact, a rich artifact of architectural thinking, dependency analysis, and prioritization.

The Context: A Journey Through Four Research Tasks

To understand message 291, one must first appreciate the research that preceded it. The assistant had just completed a systematic exploration of the cuzk proving engine's codebase across four distinct tasks, each building on the last.

The first task ([msg 286]) was a comprehensive read of every source file in the extern/cuzk/ workspace. This revealed the workspace structure of five active crates, the existing PoRep-only proving pipeline, the priority scheduler using a BinaryHeap, and the current protobuf definition with its single vanilla_proof field. The assistant learned that the engine was currently a single-purpose daemon capable only of Groth16 (C2) proof generation for PoRep sectors.

The second task ([msg 287]) dove into the filecoin-proofs-api 19.0.0 crate to find the Rust function signatures for the three missing proof types: WinningPoSt, WindowPoSt, and SnapDeals. This research uncovered critical details: the #[repr(i32)] C FFI enum mapping RegisteredSealProof values to numeric constants, the exact parameter types for each function (slices of Vec<u8> for vanilla proofs, arrays for commitments), and the return types.

The third task ([msg 288]) examined Curio's Go FFI layer to understand how vanilla proofs are serialized for each proof type. This was perhaps the most critical piece of research, as it revealed that PoSt proofs require multiple vanilla proofs per request (one per sector), and SnapDeals requires three commitment CIDs rather than one. The assistant traced through tasks/window/compute_do.go and lib/paths/local.go to understand the exact serialization patterns.

The fourth task ([msg 289]) and its follow-up ([msg 290]) checked the current protobuf definition and service implementation, confirming that the existing vanilla_proof: bytes field would need to become repeated bytes vanilla_proofs to support multi-proof requests.

By the end of these four tasks, the assistant possessed all the information needed to implement Phase 1. Message 291 is the synthesis of this knowledge into a concrete plan.

The Message: A Blueprint Decomposed

The message itself is compact but dense. It consists of a single declarative sentence followed by a structured todo list:

Good. Now I have a complete understanding of the codebase. Let me plan the Phase 1 implementation precisely.

The todo list contains eight items, each representing a sub-phase of the implementation:

1. Phase 1.1: Update protobuf — add repeated bytes vanilla_proofs for PoSt/Snap multi-proof support
2. Phase 1.2: Update types.rs — add vanilla_proofs: Vec<Vec<u8>> field to ProofRequest
3. Phase 1.3: Implement prove_winning_post() in prover.rs
4. Phase 1.4: Implement prove_window_post() in prover.rs
5. Phase 1.5: Implement prove_snap_deals() in prover.rs
6. Phase 1.6: Update engine dispatch for new proof types
7. Phase 1.7: Update scheduler for priority-based dispatching
8. Phase 1.8: Update bench tool for all proof types The first item is marked "in_progress" while the remaining seven are "pending" with "high" priority. This status assignment is itself a decision: the assistant has chosen to begin with the protobuf definition because it is the foundation upon which all other types depend.

The Reasoning: Why This Message Was Written

Message 291 exists because the assistant recognized a critical inflection point in the workflow. The research phase had concluded—all necessary information had been gathered. But raw information does not automatically translate into correct code. The assistant needed to:

1. Sequence the work correctly: The protobuf definition must change before types.rs can be updated, because the generated Rust types from protobuf are used by the core types. Similarly, the prover implementations depend on the types being correct, and the engine dispatch depends on the prover being available. The todo list encodes this dependency chain.
2. Establish a shared mental model: By writing the plan explicitly, the assistant creates a reference that can be checked against during implementation. Each completed item can be marked off, providing progress visibility.
3. Surface the full scope: The eight sub-phases reveal that Phase 1 is not just "wire up three proof types" but involves changes across four crates (cuzk-proto, cuzk-core, cuzk-server, and the bench tool). This prevents the common mistake of implementing the prover functions only to discover that the engine dispatch logic or the bench tool also needs updating.
4. Set a starting point: Marking Phase 1.1 as "in_progress" signals that the assistant is ready to begin coding immediately. The plan is not aspirational—it is actionable.

How Decisions Were Made: The Decomposition Logic

The structure of the todo list reveals several implicit decisions:

Foundation-first ordering: The plan starts with the protobuf definition (1.1), then the core types (1.2), then the prover implementations (1.3-1.5), then the engine and scheduler (1.6-1.7), and finally the bench tool (1.8). This is a classic bottom-up dependency ordering: change the lowest-level representation first, then propagate changes upward.

Parallelism within phases: Items 1.3, 1.4, and 1.5 are separate but could conceptually be implemented in any order. The assistant chose to list them sequentially (WinningPoSt, WindowPoSt, SnapDeals), which likely reflects the order of complexity or the order in which the APIs were discovered during research.

Separation of concerns: The engine dispatch update (1.6) is separate from the scheduler update (1.7), even though both touch the engine module. This reflects an understanding that dispatch logic (routing proof requests to the correct prover function) and scheduling logic (prioritizing and dispatching to workers) are architecturally distinct concerns.

Tooling included: The bench tool update (1.8) is listed as a separate phase, acknowledging that testing the new proof types requires the benchmarking infrastructure to support them. This prevents the "implemented but untestable" trap.

Assumptions and Their Validity

The plan makes several assumptions, most of which proved correct based on the subsequent implementation:

Assumption 1: The research is complete. The assistant assumes that the four research tasks have uncovered all necessary information. In practice, this held true—the implementation that followed ([msg 292] through [msg 316]) proceeded without requiring additional research detours.

Assumption 2: The serialization format is correct. The assistant assumes that the vanilla proof serialization patterns observed in Curio's Go code are the definitive format. This was validated when the implementation compiled and the unit tests passed.

Assumption 3: The implementation order is optimal. The assistant assumes that starting with the protobuf definition and working upward is the correct sequence. The chunk summary confirms this was effective: "The implementation touched four crates" in exactly the order specified.

Assumption 4: Eight sub-phases are sufficient. The plan does not account for multi-GPU worker pool design or GPU affinity tracking, which were later identified as Phase 1 deliverables in the project plan. However, the assistant's subsequent review after the commit ([msg 317]) correctly identified that GPU affinity scheduling should be deferred to Phase 2 because the current process-global GROTH_PARAM_MEMORY_CACHE makes per-GPU SRS tracking unnecessary. This shows that the plan was not rigid—it was revisited and adjusted.

Input Knowledge Required

To understand message 291, a reader needs knowledge of:

• The cuzk workspace structure: Five active crates (cuzk-proto, cuzk-core, cuzk-server, cuzk-bench, cuzk-ffi) with specific dependency relationships.
• The Filecoin proof types: PoRep (already implemented), WinningPoSt, WindowPoSt, and SnapDeals, each with different parameter requirements.
• The filecoin-proofs-api signatures: The exact function names, parameter types, and return types for each proof type's generation function.
• The protobuf serialization format: How repeated bytes differs from bytes in proto3, and how tonic generates Rust types from each.
• The Curio Go FFI layer: How vanilla proofs are serialized and passed across the Go/Rust boundary, particularly the multi-proof pattern for PoSt.
• The existing engine architecture: The Engine struct, the ProofRequest type, the scheduler's BinaryHeap, and the service layer that bridges gRPC to core types. Without this knowledge, the todo list items would appear arbitrary. With it, each item maps directly to a specific file and a specific change.

Output Knowledge Created

Message 291 produces several forms of knowledge:

1. A concrete implementation roadmap: The eight sub-phases serve as a checklist that can be tracked, verified, and committed incrementally.
2. A dependency graph: The ordering of items reveals which changes must precede others.
3. A scope definition: The plan implicitly defines what Phase 1 includes (and excludes). GPU affinity scheduling, for example, is notably absent from the plan.
4. A starting state: Marking Phase 1.1 as "in_progress" establishes a baseline from which progress can be measured.

The Thinking Process: From Research to Architecture

The most striking aspect of message 291 is what it reveals about the assistant's cognitive process. The declaration "Good. Now I have a complete understanding of the codebase" is not merely a status update—it is a self-assessment that sufficient information has been gathered. The assistant is performing a gating decision: research complete, implementation may begin.

The todo list itself is a form of architectural decomposition. Each item represents a unit of work that:

• Maps to a specific file or module
• Has a clear completion criterion (the code compiles, the feature works)
• Depends on previous items but not on subsequent ones
• Is independently testable This decomposition reflects an understanding of the system's architecture. The assistant knows that the protobuf definition is the "contract" that both the gRPC service and the core types depend on, so it must change first. It knows that the prover implementations are the "business logic" that can be developed once the types are settled. It knows that the engine dispatch and scheduler are "plumbing" that integrates the provers into the existing infrastructure. The plan also shows awareness of the full development lifecycle. The inclusion of the bench tool update (1.8) demonstrates that the assistant is thinking not just about implementation but about testing and validation. A plan that ended at "implement the provers" would be incomplete—the bench tool is how the new proof types will be exercised and verified.

Conclusion

Message 291 is a masterclass in the art of planning. It sits at the critical juncture between research and implementation, transforming a mountain of gathered information into a structured, actionable sequence of changes. The eight sub-phases encode not just what needs to be done, but the order in which it must be done, the dependencies between components, and the scope of the effort. The plan proved remarkably accurate: the subsequent implementation followed it closely, all changes compiled successfully, and the milestone was committed as d8aa4f1d. In the broader narrative of the cuzk proving engine, message 291 is the architectural blueprint that turned scattered knowledge into working code.