Module worktree_copy_journal 

The durable journal of one copy: exact encoding, strict validation, private storage and removal. What: The durable journal of one destination’s linked-worktree copy: its exact JSON encoding, strict validation of every field recovery will act on, private storage under <common>/cli-git-worktree-copy/v1, and removal of a finished transaction’s stage and journal. Why: A crash can happen after any step, so the journal must say which phase the copy reached and which paths it may have touched, and recovery must never act on a journal it cannot prove is its own.

In TS you’d write (pseudocode):

await writeJournal({ path, record });
const pending = await readPendingWorktreeCopyJournals(commonDir);

Structs

Journal

What: One durable journal record. Why: Every field is read back by recovery before any filesystem path is used.

PendingJournal

What: A journal and the path it was read from or written to. Why: Removal and recovery need both the record and the file that must be deleted.

Enums

Phase

What: The durable phase a copy has reached. Why: Recovery resumes an installation and finishes a completed cleanup differently.

Role

What: The role a private path plays, which selects its expected entry kind. Why: A journal file must be a single-link file; a directory must be a directory.

Constants

JOURNAL_PARENT_NAME

What: The parent directory name of the journals, beneath the common Git directory. Why: Every linked worktree of one repository shares the same journal location.

JOURNAL_VERSION_NAME

What: The schema directory of the journals. Why: A later schema gets its own directory, so an older wrapper never reads a newer record.

TEMPORARY_SUFFIX

What: The suffix of an unpublished temporary journal write. Why: An interrupted write leaves only files with this suffix, which recovery removes.

Functions

assert_private_path

What: Checks that a path is canonical, owned by this account, private, and of the role’s kind. Why: A journal or stage that another account can write, or that a link redirects, is never acted on.

create_journal

What: Creates the staged journal of one destination, durable before any destination is touched. Why: Recovery needs the stage and destination named before installation starts.

encode_installed_entry

What: One created entry as its JSON object, with the incumbent’s key order. Why: The install log and the journal share this spelling, so both wrappers read either.

encode_journal

What: The JSON text of one journal, with the incumbent’s key order and a final line feed. Why: The incumbent reads these bytes, so the order and spelling must match its JSON.stringify output.

ensure_journal_root

What: Creates and checks the journal parent and root, and returns the root. Why: Every writer needs the same private location before it writes.

installed_entry

What: One created-entry object, read strictly. Why: An identity with any wrong type is not an identity cli-git wrote.

journal_root

What: The journal root beneath a common Git directory, without creating anything. Why: Readers check for pending state before they decide whether to create it.

parse_journal

What: Parses and validates one journal’s text, refusing every shape recovery cannot trust. Why: Recovery turns journal paths into deletions, so every relation between the paths is checked first.

prepare_stage_removal

What: Makes every directory of a stage owner-accessible before its entries are deleted. Why: An installed directory can carry a mode that forbids its own removal; only the stage’s own directories are changed.

read_pending_journals

What: Lists the journal files of a common directory, validated, in journal-name order. Why: Recovery and the pending check read the same validated set.

remove_file_if_present

What: Removes one file, treating an absent file as removed. Why: The same retry reasoning as for trees.

remove_pending_journal

What: Removes one completed transaction: its stage, its unfinished temporaries, and its journal. Why: A complete phase is written first, so an interruption during cleanup resumes as cleanup, not as installation.

remove_stage

What: Removes a stage container with everything in it, whatever modes the installed directories carry. Why: Completed transactions and abandoned stages are removed the same way, and an absent stage is already removed.

string_array

What: A JSON array of strings, each quoted as JSON.stringify quotes it. Why: Repository paths are the only arrays a journal holds.

write_atomic

What: Writes one private file atomically beside its final name; a failure names subject and leaves no temporary. Why: Journals and stage claims share one rule: a reader sees a complete file or none.

write_journal

What: Writes one complete journal atomically: a private exclusive temporary, synced, renamed, and its directory synced. Why: A reader sees either the previous complete journal or the new complete one, never a fragment.