The Diagnostic Commit: How git ls-tree Shaped the Vendoring Decision for cuzk's Upstream Integration

In the middle of a complex integration session, a single diagnostic command can crystallize an entire architectural decision. Message [msg 3491] in this opencode session is exactly such a moment. The assistant, deep in planning how to upstream the cuzk proving daemon into the Curio Filecoin storage provider, executed:

[assistant] [bash] git ls-tree HEAD extern/
040000 tree d187a0bb35112885e286673ead0e0ee8e62fae83	extern/bellpepper-core
040000 tree 11a12c31d6a1d1a36590ab47a7317ec557652556	extern/bellperson
040000 tree 5199fa8dac9f1aa1ce02dfa51572e1ac22787ae8	extern/cuzk
160000 commit 4b398eadebe521c8c4e4f94e1ded77ccfad139f0	extern/filecoin-ffi
040000 tree b942f983c34b4767dd6321ff044c64e680358f1b	extern/supraseal-c2
040000 tree 4d094f5a58f54b537e37278847041ce4904a9069	extern/supraseal

On its surface, this is a simple inventory command — list the contents of the extern/ directory as recorded at the current HEAD commit. But in the context of the upstreaming dilemma that preceded it, this output was the decisive piece of evidence that unlocked the entire integration strategy.

The Upstreaming Dilemma

To understand why this command was written, one must step back into the conversation's immediate context. In message [msg 3483], the user had given a clear but constrained directive: "Plan how to upstream. Assume we don't want to merge bellman/etc changes with upstream repos just yet, just want a quick-to-prod route for curio. Look at build system integration too."

This instruction created a tension. The cuzk proving engine depends on several forked Rust crates — bellperson, bellpepper-core, and supraseal-c2 — each carrying modifications necessary for the pipelined GPU proving architecture. The "correct" long-term approach would be to upstream these changes to their respective repositories, publish new crate versions, and then depend on them normally. But the user explicitly ruled that out for now. The goal was speed-to-production, not architectural purity.

The assistant was thus faced with a classic software engineering trade-off: how to incorporate modified dependencies without upstream coordination, while keeping the build system clean, reproducible, and CI-friendly. Several options existed on the spectrum:

• Option A: Git submodules pointing to fork branches on GitHub.
• Option B: Vendoring — committing the forked source code directly into the Curio repository.
• Option C: Patch files applied during build.
• Option D: Cargo [patch] sections referencing local paths. The assistant had already begun exploring the terrain. In [msg 3484] through [msg 3490], it read the Makefile, examined extern/cuzk/Cargo.toml, listed directory contents, and checked git status on the extern/ directory. The git status output in [msg 3489] revealed a critical fact: the extern/ directory contained many untracked files — the actual source code of the forked crates had been placed there but not yet committed. The directories themselves (extern/bellpepper-core/, extern/bellperson/, extern/supraseal-c2/) existed in the working tree, but their relationship to git was ambiguous.

What git ls-tree HEAD extern/ Revealed

This is where message [msg 3491] became pivotal. The assistant needed to know definitively: are these extern/ subdirectories already tracked by git, and if so, in what form? The git ls-tree HEAD extern/ command answers exactly that question by showing the tree object entries at the current commit.

The output delivered three critical insights:

1. Five of the six directories are regular git trees (mode 040000) — bellpepper-core, bellperson, cuzk, supraseal-c2, and supraseal are all tracked as ordinary directories. They are not submodules, not symlinks, not ignored. This means new files can be added to them and committed normally.
2. filecoin-ffi is a git submodule (mode 160000 commit) — This directory is a pointer to commit 4b398eadebe521c8c4e4f94e1ded77ccfad139f0 in another repository. It cannot be modified in-place; changes would require pushing to the submodule's remote.
3. The forked crates are already "in" the repo — Because bellpepper-core, bellperson, and supraseal-c2 already exist as tracked trees at HEAD, the vendoring approach is straightforward: the assistant can simply git add the untracked source files into these existing directories. No submodule surgery, no external repository setup, no complex build-time patching.

The Reasoning Chain

The assistant's thinking process, visible across the preceding messages, followed a deliberate diagnostic arc. It began with the user's high-level directive, then systematically narrowed the question until it could be answered by a single git command.

First, the assistant read the Makefile ([msg 3484]) to understand the existing build system. It found that Curio already builds filecoin-ffi, blst, and supraseal from external directories. This established precedent: vendored dependencies in extern/ are a normal part of the Curio build.

Next, it examined extern/cuzk/Cargo.toml ([msg 3487]) and discovered that the workspace already uses [patch.crates-io] sections to redirect bellperson, bellpepper-core, and supraseal-c2 to local paths. This is Cargo's mechanism for overriding dependencies with local forks. The infrastructure for vendored dependencies was already in place at the Rust level.

Then the assistant checked git status extern/ ([msg 3489]), which showed a sea of untracked files — the actual source code of the forked crates sitting in the working tree, waiting to be committed. But git status alone couldn't answer whether these directories were new or pre-existing in the repository history.

Finally, git ls-tree HEAD extern/ ([msg 3491]) resolved the ambiguity. The directories existed at HEAD, meaning the repo already "owned" them. The untracked files were additions to existing tracked directories, not entirely new directory creations. This distinction matters for git operations: adding files to an existing tree is simpler and less error-prone than introducing entirely new top-level directory structures.

Assumptions and Input Knowledge

This message operates on several implicit assumptions. First, that git ls-tree is the correct tool for inspecting tree contents at a specific commit — a reasonable assumption, but one that requires familiarity with git's plumbing commands rather than the more common git ls-files or git show HEAD:extern/. Second, that the HEAD commit accurately represents the repository state relevant to the vendoring decision. Third, that the mode field (040000 tree vs 160000 commit) is the definitive way to distinguish regular directories from submodules in git's internal representation.

The input knowledge required to interpret this message is substantial. A reader must understand:

• Git's object model (trees, blobs, commits) and how ls-tree maps to it
• The distinction between a git submodule (mode 160000) and a regular tree (mode 040000)
• The context of the Curio repository structure and the cuzk project's dependency chain
• The upstreaming constraint imposed by the user in the preceding message
• How Cargo's [patch] mechanism works with local path dependencies Without this knowledge, the output is just a list of hashes and modes. With it, the output becomes a blueprint for the vendoring strategy.

Output Knowledge Created

The output of this single command created actionable knowledge that directly shaped the subsequent implementation. The assistant now knew:

• Vendoring is viable. The forked crates can be committed directly into the existing extern/ directories without restructuring the repository.
• Submodules are not required. Because the directories are regular trees, there is no need to set up remote fork repositories or manage submodule URLs.
• filecoin-ffi must remain a submodule. Its mode 160000 entry means it points to an external repository and cannot be vendored in the same way. This is acceptable because filecoin-ffi is not one of the forked crates that needed modification.
• The build system can be kept simple. A make cuzk target can invoke cargo build inside extern/cuzk/, and the [patch] sections in Cargo.toml will automatically resolve the vendored dependencies. This knowledge directly enabled the implementation seen in the subsequent chunk ([chunk 34.0]), where the assistant proceeded to vendor the forked Rust crates, extend the Makefile with build targets, and commit all 37 files with a comprehensive commit message.

A Lesson in Diagnostic Precision

Message [msg 3491] exemplifies a broader principle of effective technical work: when facing an architectural decision with multiple unknowns, the fastest path forward is often a precise diagnostic query that eliminates ambiguity. The assistant could have spent time debating the pros and cons of submodules versus vendoring, writing design documents, or prototyping both approaches. Instead, it asked a single, well-formed question of the repository itself: "What is the current state of extern/ at HEAD?"

The answer was definitive. The vendoring path was not just possible — it was the path of least resistance, requiring no repository restructuring, no external coordination, and no complex build system changes. The git ls-tree command, in its terse output of hashes and modes, provided the evidence needed to commit to a strategy and move forward with implementation.

This is the hallmark of an experienced engineer working in a complex codebase: the ability to formulate the exact question that, once answered, collapses a tree of possibilities into a single clear path forward.