Module foundation 

Small shared building blocks: private files, scratch locations, JSON, time, random ids, paths and bounded parallelism. What: Small shared building blocks: private files, scratch locations, JSON, time, random ids, paths and bounded parallelism. Why: Subsystems depend on these and they depend on no subsystem.

In TS you’d write (pseudocode):

// foundation/index.ts: one `export * from './file'` per module below.

Modules

diagnostic_log

Line-oriented debug and warning diagnostics on standard error. What: Line-oriented debug and warning diagnostics on standard error, switched like the incumbent’s console sink. Why: The incumbent prints debug records only when MONOCHROMATIC_VERBOSE=true and warnings unless MONOCHROMATIC_WARN=false (package/logger/core/src/sink/console.ts), and its spec requires that diagnostics never corrupt a JSONL stream: each diagnostic is one complete line written in one call (SPEC.md, “Debug logging”).

iso_time

UTC timestamps in the exact form of JavaScript’s toISOString. What: UTC timestamps in the exact form of JavaScript’s Date.prototype.toISOString: YYYY-MM-DDTHH:MM:SS.mmmZ. Why: Transaction owner records carry createdAt and capture records invokedAt in this form; recovery orders dead transactions and the reservation grants turns by comparing these strings, so both wrappers must write the same shape.

js_text

Text operations with the exact semantics of JavaScript’s built-ins. What: Text operations with the exact semantics of the JavaScript built-ins the incumbent applies to strings it shares with the native wrapper. Why: Durable strings such as process birth identities are produced by .trim() in the incumbent; the native wrapper must produce byte-identical strings, and Rust’s str::trim uses a different whitespace set (it trims U+0085 and keeps U+FEFF).

json_record

Compact JSON records read and written with the incumbent’s JSON semantics. What: Reading and writing the compact JSON records both wrappers share, with the incumbent’s JSON.parse and JSON.stringify semantics. Why: Lock, owner, journal and capture records written by either wrapper are read by the other. A record must be read the way the incumbent reads it (numbers are doubles, a whole number in safe-integer range is an integer, the last duplicate key wins) and written with the same field order and escaping.

lexical_path

Lexical path normalization. What: Lexical path normalization, the way Node’s path.resolve does it. Why: git cli-git doctor scans each hooks directory once, so one directory named two ways (./hooks, hooks/, a/../hooks) must compare equal without touching the file system.

parallel_budget

How many workers independent items may use together, from the CPUs allowed, the memory free and a measured ceiling. What: How many workers a set of independent items may use together: the CPUs the process is allowed minus a margin, the memory that is free, an optional ceiling the shared storage was measured to need, and the person’s own cap. Why: Real jobs may use almost the whole host, so a bare constant is wrong in both directions: too low on a large host, too high inside a container with a quota or on a host whose memory other sessions already hold. The budget is derived from the facts of the moment, and the facts are a value so a control can state them.

parallel_runner

Independent items on a bounded number of threads, reported in input order with no lock. What: Runs independent items on a bounded number of threads and reports what they say and what they return in input order, as if they had run one after another. Why: Items that share nothing (one worktree each, one directory each) need not wait for each other, but a person reads one stream of lines. The calling thread is the only consumer: workers hand it lines and results over a channel, it prints the lines of the first unfinished item as they arrive (so progress stays live), holds the lines of later items until every item before them is complete, and then prints them in order. No lock is taken: the channel and one atomic counter that hands out the lanes are the whole of the sharing, and every item has exactly one owner.

private_storage

Private, crash-safe file primitives shared by every durable record. What: Private, crash-safe file primitives shared by every durable record of the wrapper: exclusive no-follow creation with private modes, file and directory sync, and no-follow reads that refuse links and non-regular files. Why: Lock records, transaction journals and capture records must survive a crash in a readable state, must never be written through a planted link, and must be private to the account. The incumbent’s src/trust/registry-io.ts defines these semantics; both wrappers write and read the same files.

random_id

Random identifiers in the layout of the incumbent’s randomUUID. What: Random identifiers in the layout of the incumbent’s randomUUID: lock tokens and the unique names of worktree-copy and auto-push scratch files, and the check for that layout. Why: A lock token must be unguessable and unique per acquisition, and the startup step recognizes the directories an earlier release named with a transaction ID in the same canonical layout (is_canonical_uuid, startup_gate.rs).

scratch_location

Where short-lived private files live: the per-user scratch directory and the repository scratch directory, never the system temporary directory. What: Where the wrapper keeps short-lived private files: the per-user scratch directory (<state>/cli-git/scratch) for work that has no repository in hand, and the repository scratch directory (<common-dir>/cli-git-scratch) for work inside one. Both are checked as private (a real directory of this user, mode 0700) and swept of entries older than a day each time they are prepared. Why: The system temporary directory is never used (issue 1809, repo rule XTD): which device backs it is unknowable (a small tmpfs, a per-user quota, a slow disk), and a full one broke every session. A file left by a killed process must not accumulate without bound, so every preparation of a directory also collects what is stale in it. doc/planning/cli-git-scratch-locations.md records the choice per site.