Wiring Persistence into the Pipeline: The Integration of PCE Disk Serialization

In any complex software project, the moment when a standalone component must be integrated into the live system is often the most consequential. A module that works beautifully in isolation can reveal hidden assumptions, interface mismatches, or architectural friction when it meets the production code path. Message [msg 1589] captures exactly this moment for the Pre-Compiled Constraint Evaluator (PCE) disk persistence feature in the cuzk proving engine. The assistant has just finished writing a raw binary serialization module for the 25.7 GiB PCE data structure and is now preparing to wire it into the main pipeline code — the critical step that transforms a capability into an actual improvement.

The Scene: What Came Before

To understand this message, one must appreciate the arc of the session. The assistant and user have been deep in the trenches of optimizing Groth16 proof generation for Filecoin's Proof-of-Replication (PoRep) circuit. The PCE was the centerpiece of Phase 5: a pre-compiled constraint evaluator that extracts the fixed R1CS constraint matrices (A, B, C) once and reuses them across every proof, eliminating the redundant reconstruction of ~130 million LinearCombination objects per partition. This reduced synthesis time dramatically, but introduced a 47-second "first-proof penalty" — the time required to extract the PCE from scratch on every daemon startup.

The user's plan was explicit: design doc → PCE disk → slotted pipeline → daemon integration. The assistant had just completed the first two steps. It wrote c2-optimization-proposal-6.md, a detailed design document for the Phase 6 slotted partition pipeline that would overlap synthesis and GPU work at partition granularity. It then implemented cuzk-pce/src/disk.rs, a raw binary serialization format that writes CSR vectors as bulk byte dumps with a 32-byte header and length-prefixed raw arrays, achieving a 5.4× load speedup over bincode (9.2 seconds vs 49.9 seconds from tmpfs for the full 25.7 GiB payload). The lib.rs was updated to expose the new module. The todo list was updated: PCE disk serialization was "in_progress," the slotted pipeline and daemon integration were "pending."

Now came the integration step: making the pipeline actually use the disk persistence.

The Message: A Plan in Four Steps

The subject message is deceptively brief. It consists of a single declarative sentence followed by a four-item checklist and a file read:

Now let me wire the disk persistence into cuzk-core/src/pipeline.rs. I need to: 1. Add a circuit_id_name() helper to map CircuitId to a filename string 2. Add load_or_extract_pce() that tries disk → OnceLock 3. Modify extract_and_cache_pce() to also save to disk after extraction 4. Add a startup preload function

Then it reads pipeline.rs — the file it needs to modify.

This is a planning message, not an execution message. The assistant does not yet make any edits; it states its intent and gathers the information needed to execute. The actual edits happen in the next message ([msg 1591]). This is characteristic of the assistant's working style: it thinks through the integration points before touching code, using the read as a reconnaissance step to understand the existing structure.

Why These Four Steps?

Each of the four items addresses a specific gap between the disk module and the pipeline:

1. circuit_id_name() — Naming Convention. The PCE data is deterministic per circuit topology. The 32 GiB PoRep circuit produces one set of matrices; a hypothetical different circuit would produce another. To save and load from disk, the assistant needs a way to map from the internal CircuitId enum (which might be something like CircuitId::PoRep) to a filesystem-friendly string like porep-32g. This is a small but essential piece of plumbing — without it, the pipeline cannot know which file to read.

2. load_or_extract_pce() — The Core Logic. This is the heart of the integration. The function encapsulates a two-tier strategy: try to load from disk first (fast path), and if that fails (no file, corrupted, wrong version), fall back to the existing extraction path (slow path). The result is cached in a OnceLock — a thread-safe synchronization primitive that ensures the PCE is initialized exactly once, even under concurrent access. The "disk → OnceLock" flow means that on a warm startup, the pipeline goes directly from file to ready state in ~9 seconds instead of ~47 seconds.

3. Modify extract_and_cache_pce() — Bootstrapping the Cache. The existing extraction function needs to be extended so that after it extracts the PCE from scratch, it also saves it to disk. This bootstraps the disk cache: the first-ever run on a machine extracts the PCE (47 seconds) and writes it to disk; every subsequent startup loads it in 9 seconds. Without this step, the disk would never be populated, and the fast path would never activate.

4. Startup Preload Function — Eliminating the First-Proof Penalty. The daemon startup sequence should load the PCE before any proof request arrives. This means the first proof sees zero extraction latency — the PCE is already in memory when the synthesis task begins. This is the final piece that makes the optimization invisible to the user: no more 47-second wait on the first proof after a daemon restart.

The Reasoning Process Visible in the Message

The assistant's thinking is visible in the structure of the plan. Notice the order: naming first, then loading logic, then the extraction modification, then preload. This is a dependency-ordered plan — each step builds on the previous one. You cannot write load_or_extract_pce without knowing the filename convention. You cannot modify extract_and_cache_pce without understanding the loading path. You cannot write the preload function without the loading function.

The message also reveals what the assistant does not need to think about. It does not debate whether to use OnceLock versus Arc<Mutex<>> versus a global static — that decision was already made in earlier rounds. It does not reconsider the serialization format — the raw binary format was already implemented and benchmarked. It does not question whether disk persistence is worth doing — the 5.4× speedup was already measured. The plan operates within a well-established design space, executing on decisions already made.

Assumptions and Potential Pitfalls

The assistant makes several assumptions that are worth examining:

Assumption 1: The disk path is derivable from CircuitId alone. This assumes a fixed directory structure, likely something like /data/zk/params/pce-{circuit_name}.bin. In practice, the daemon may need configurable paths, multiple data directories, or awareness of filesystem types (e.g., tmpfs vs NVMe). The assistant does not yet address configuration plumbing — that may surface as a future concern.

Assumption 2: OnceLock is the right synchronization primitive. For a 25.7 GiB data structure, OnceLock means the PCE is loaded once and never freed. This is fine for a long-running daemon, but it means the memory is permanently committed. If the daemon ever needs to handle multiple circuit types or unload the PCE to free memory for other tasks, this design would need revisiting.

Assumption 3: The existing extract_and_cache_pce() function has the right signature for modification. The assistant assumes it can add a disk-save step after extraction without breaking the existing callers. This is likely true, but it depends on the function's current structure — whether it returns the PCE directly or stores it internally, whether it has access to a filesystem path, and whether it's called from contexts where disk writes are appropriate.

Assumption 4: The daemon has a startup sequence where preloading can be injected. This assumes the daemon's initialization flow has a natural point for loading the PCE — likely after configuration parsing and before the first proof request arrives. If the daemon initializes lazily or on-demand, the preload function may need a different integration strategy.

Input Knowledge Required

To understand this message, a reader needs to know:

Output Knowledge Created

This message creates a plan that will be executed in subsequent rounds. The output is:

The Broader Significance

This message sits at a pivotal moment in the optimization project. The PCE disk persistence is the bridge between two architectural phases: Phase 5 (pre-compiled evaluation) and Phase 6 (slotted pipeline). Without disk persistence, the slotted pipeline would still pay the 47-second first-proof penalty on every daemon restart, undermining the low-latency benefits of fine-grained pipelining. With disk persistence, the daemon can preload the PCE at startup and then begin proving immediately — the slotted pipeline's 41-second single-proof latency becomes the real user experience from the very first proof.

The integration also has implications for multi-GPU deployments. If each GPU worker needs its own PCE copy (for NUMA locality or PCIe topology), the disk persistence enables fast cloning from a single file rather than re-extracting per worker. The assistant's design of a circuit_id_name() helper anticipates this scalability concern by making the naming scheme extensible.

In the end, message [msg 1589] is a quiet but essential piece of engineering communication. It does not contain dramatic breakthroughs or complex mathematics. It contains something more practical: a clear, ordered plan for connecting a new capability to the system that needs it. The four items on the checklist are the difference between code that exists and code that matters.