The Planning Pivot: How a Todo List Transformed Research into Implementation in the cuzk Phase 2 Pipeline

In the long arc of building a pipelined SNARK proving engine for Filecoin's Curio project, there comes a moment where analysis must yield to construction. Message [msg 438] captures precisely that inflection point. After three intensive research tasks spanning the full call chain from filecoin-proofs-api down to bellperson's circuit synthesis internals, the assistant declares:

Now I have a thorough understanding of everything needed. Let me create the todo list and start implementing Phase 2 Steps 3-7.

It then writes a structured todo list via the todowrite tool, enumerating five implementation steps with priorities and statuses. This single message, outwardly just a task list written to a planning tool, represents the cognitive pivot from understanding to building — the moment where knowledge crystallizes into a structured implementation plan. After three intensive research tasks spanning the full call chain from filecoin-proofs-api down to bellperson's circuit synthesis internals, the assistant declares: "Now I have a thorough understanding of everything needed. Let me create the todo list and start implementing Phase 2 Steps 3-7." This single message, outwardly just a todo list written to a planning tool, represents the cognitive pivot from understanding to building — the moment where knowledge crystallizes into a structured implementation plan.

Context and Motivation: Why This Message Was Written

To understand why this message exists, one must appreciate the journey that preceded it. The cuzk project (a "proving daemon" for Filecoin's storage proofs) had already completed Phase 0 (basic gRPC daemon) and Phase 1 (multi-GPU worker pool with all four Filecoin proof types). Phase 2's goal was transformative: replace the monolithic PoRep C2 prover — which held ~136 GiB of intermediate data in memory during proof generation — with a pipelined architecture that separates CPU circuit synthesis from GPU NTT+MSM proving, reducing peak memory to ~13.6 GiB and enabling the GPU to never sit idle.

The assistant had just completed three parallel research tasks ([msg 435], [msg 436], [msg 437]) that dug deep into the upstream codebase. These tasks uncovered the exact function signatures for seal_commit_phase2_circuit_proofs, traced the call chain from filecoin-proofs-api through storage-proofs-porep into bellperson's synthesize_circuits_batch, and located critical type definitions like PoRepConfig, PrivateInputs, and PublicInputs. The research was exhaustive — it even discovered that the existing GROTH_PARAM_MEMORY_CACHE was a private global, meaning a new SRS manager would need to bypass it entirely by loading parameters directly via SuprasealParameters.

Message [msg 438] is the direct consequence of that research saturation. The assistant had reached the point where further reading would yield diminishing returns; the remaining unknowns could only be resolved by writing code and seeing what compiled. The todo list is therefore not merely a task tracker but a commitment device — a formal declaration that the research phase is complete and the implementation phase has begun.

The Todo List as a Decision Architecture

The todo list written in this message encodes a series of deliberate architectural decisions. The ordering is not arbitrary:

Step 3 (SRS Manager) comes first because every other component depends on it. The SRS (Structured Reference String) parameters — multi-gigabyte files loaded into GPU memory — are the lifeblood of Groth16 proving. The existing monolithic prover loaded them implicitly via a private global cache; the pipelined architecture needs explicit, fine-grained control over which parameters are resident at any given time. By implementing srs_manager.rs first, the assistant establishes the foundation upon which all pipeline operations depend. The CircuitId enum and its mapping to .params filenames on disk is a design decision that encodes knowledge about how the Filecoin proof system organizes its 10+ distinct circuits across sector sizes.

Step 4a (dependencies) precedes Step 4b (pipeline module) because the pipeline module cannot compile without the right dependencies. The assistant needs to add filecoin-proofs, storage-proofs-porep, storage-proofs-post, bellperson (the fork), blstrs, rayon, and ff to cuzk-core/Cargo.toml. This is a mechanical but essential step — getting the dependency graph right before writing code avoids the frustration of "cannot find crate" errors mid-implementation.

Step 4b (pipeline.rs) is the heart of Phase 2. The SynthesizedProof type and the split synthesize_porep_c2_partition() / gpu_prove() functions embody the core architectural insight: by partitioning the 10 partitions of a 32 GiB PoRep and processing them sequentially through synthesis while the GPU works on the previous partition's proofs, peak memory drops by an order of magnitude. The todo list item's truncation in the message — "SynthesizedProof type, synthesize_..." — hints at the complexity being deferred to the implementation phase.

Steps 5-7 (engine integration, pipeline config, testing) form the integration layer. The engine must be refactored to support a pipeline.enabled configuration flag, routing PoRep C2 jobs through the new pipeline when active while falling back to the Phase 1 monolithic prover for PoSt and SnapDeals proofs. This backward-compatible design is a conscious choice to minimize risk: if the pipeline has bugs, the daemon can still serve all proof types.

Assumptions Embedded in the Plan

The todo list, like any plan, rests on assumptions that may prove incorrect:

The bellperson fork's API is sufficient. The assistant assumes that the exposed synthesize_circuits_batch() and prove_from_assignments() functions in the minimal bellperson fork (created in [msg 434]'s segment) provide everything needed. If the fork missed a critical internal function or if the GPU proving path requires additional state not exposed by the fork, the plan would stall.
Per-partition pipelining is the right granularity. The design assumes that partitioning at the natural partition boundary (10 partitions for 32 GiB) is the optimal tradeoff between memory reduction and scheduling overhead. Too fine-grained would increase context-switching costs; too coarse would waste memory. The 10× reduction from ~136 GiB to ~13.6 GiB is compelling, but it assumes the synthesis output per partition fits within that budget.
The SRS manager can bypass GROTH_PARAM_MEMORY_CACHE. This is a bet on the flexibility of SuprasealParameters. If the C++/CUDA layer has hidden assumptions about parameter lifecycle tied to the global cache, the direct-loading approach could cause subtle correctness issues or GPU memory corruption.
PoSt and SnapDeals can remain monolithic. The plan explicitly limits the pipeline to PoRep C2, leaving other proof types on the Phase 1 path. This is pragmatic but assumes those proof types don't need the pipeline's memory or throughput benefits — an assumption that may be revisited in Phase 3.

Input Knowledge Required

To understand this message, a reader must grasp several layers of context:

Groth16 proving pipeline: The two-phase structure where circuit synthesis (generating the constraint system assignments a/b/c vectors) is CPU-bound, while NTT (Number Theoretic Transform) and MSM (Multi-Scalar Multiplication) are GPU-accelerated. The pipeline separates these phases so they can overlap.
Filecoin PoRep structure: A 32 GiB sector proof involves 10 partitions, each independently provable. The monolithic prover synthesizes all 10 partitions at once (~136 GiB memory), while the pipeline processes them sequentially.
SRS parameters: Multi-gigabyte files containing the proving key for each circuit type. Loading them into GPU memory is expensive (~2-3 seconds per circuit), so residency management is critical.
The cuzk project's history: Phase 0 established the gRPC daemon, Phase 1 added multi-GPU support with CUDA_VISIBLE_DEVICES isolation. Phase 2 builds on this foundation.
The bellperson fork: A minimal patch to the upstream bellperson library that exposes the internal split between synthesize_circuits_batch and prove_from_assignments, which were previously hidden inside the monolithic prove function.

Output Knowledge Created

This message produces a structured plan that serves as both a task tracker and an architectural document. The todo list captures:

The dependency ordering (SRS first, then pipeline, then integration)
The module boundaries (srs_manager.rs, pipeline.rs, modifications to engine.rs and config.rs)
The API contracts (what functions each module must expose)
The risk mitigation strategy (backward compatibility with Phase 1 monolithic prover) For anyone reading the conversation, this message is the clearest statement of "what needs to be built and in what order." It transforms the diffuse knowledge from the research tasks into actionable work items.

The Thinking Process Visible in the Message

The message reveals a methodical, engineering-minded thought process. The assistant does not dive directly into code — it first externalizes the plan via todowrite. This is characteristic of the opencode session format, where tool calls are the primary medium of action. The todowrite tool serves a dual purpose: it records the plan for the assistant's own reference in subsequent rounds, and it communicates intent to anyone reading the conversation log.

The phrase "Now I have a thorough understanding of everything needed" is significant. It signals that the assistant has reached a knowledge threshold — the point where the marginal benefit of additional research is less than the marginal benefit of starting implementation. This is a metacognitive judgment: the assistant is evaluating its own epistemic state and deciding it is sufficient for the task.

The todo list's structure also reveals priority reasoning. Step 3 (SRS manager) is marked "high" priority and placed first because it is the foundational dependency. Step 4a (dependencies) is also "high" because it's a prerequisite for compilation. The pipeline module (Step 4b) is the core value delivery. The engine integration (Steps 5-7) is the final integration. This is textbook dependency-aware planning.

Potential Pitfalls and Blind Spots

No plan survives first contact with the compiler. The todo list does not explicitly account for:

Build system complexity: The bellperson fork may have subtle version incompatibilities with the rest of the dependency tree. The Phase 2 design document estimated 2-3 weeks of effort, suggesting awareness that integration could be tricky.
GPU memory fragmentation: The SRS manager's preload/evict operations assume clean memory management, but GPU memory fragmentation from repeated load/unload cycles could cause allocation failures.
Error handling in the pipeline: The split-phase architecture introduces new failure modes — what happens if synthesis succeeds but GPU proving fails? The todo list doesn't specify error recovery strategies. These gaps are not failures of the plan; they are the normal unknowns that implementation will resolve. The todo list is a starting point, not a specification.

Conclusion

Message [msg 438] is the hinge point of the Phase 2 implementation — the moment where three research tasks' worth of knowledge crystallizes into a structured implementation plan. It is outwardly mundane (a todo list) but functionally decisive: it commits the assistant to a specific architectural path, establishes dependency ordering, and encodes design decisions about SRS management, per-partition pipelining, and backward compatibility. For anyone studying how complex software engineering unfolds in an AI-assisted coding session, this message demonstrates the critical transition from understanding to building — and the role of explicit planning tools in making that transition deliberate and trackable.