Module worktree_copy_install 

Installation of a validated stage into a new worktree, with preflight, batches and rollback on failure. What: Installation of one validated stage into a newly registered worktree: preflight of every existing destination entry, batched creation with its durable records, mode application and rollback of this installation’s own paths when it fails. Why: A destination that already holds an identical entry is accepted, and a differing entry is never overwritten, so the copy cannot destroy user state. Recording each batch before and after it runs bounds the work an interrupted run leaves unrecorded.

In TS you’d write (pseudocode):

const copied = await installSnapshot({ snapshot, destinationRoot, journalState, priorCreations });

Structs

NoRecord

What: A recorder that writes nothing, for installations whose caller keeps no durable state. Why: Such an installation is not crash-safe; it exists so the installer can be exercised before the journal lands.

Constants

INSTALL_BATCH_ENTRIES

What: The number of manifest entries claimed by one durable intent record and settled by one creation record. Why: Bounds both the number of journal appends and the work an interrupted owner can leave unrecorded. Measured with install_snapshot and a recorder that appends each batch to a file and syncs it twice, on a tree of 22,717 entries (2026-11-03, five runs each in alternating orders, other sessions running, a debug build): medians 6,542, 2,265, 983, 746, 688 and 663 ms for batches of 64, 256, 1,024, 4,096, 16,384 and one batch, so a batch costs about 16 ms of syncs and 4,096 entries add 12 percent to the install and 16,384 add 4 percent. The real journal’s append was not run; its cost per batch may differ. Kept at 4096 as the coordinator’s pick under the owner’s delegation, open to the owner’s veto (doc/planning/cli-git-shipped-limits-audit.md, “Picked for these follow-ups”, option A).

Traits

InstallRecorder

What: The durable record of an installation in progress. Why: The installation reports every claim before it creates a path and every proven creation after, so the journal slice can persist both without this module knowing the file format.

Functions

install_snapshot

What: Installs a whole stage into the destination, or rolls back its own paths and reports what it kept. Why: A failed installation ends with the destination as it was before, apart from paths the rollback could not prove were its own.

preflight_destination

What: The selected paths absent from the destination, after every existing entry has been proven identical. Why: An existing entry that differs stops the installation before any mutation, and an identical one is accepted without being overwritten.