Concurrency And Failure

Concurrency and Failure

For work that runs beside other work, waits on a peer, or owns resources. .agents/AGENTS.md carries the always-applicable constraints; this file is the discipline behind the concurrent shapes this repository already uses.

Bound everything a new edge introduces

• Every queue, channel, batch, retained cache, and message declares a cap next to its owner, and a defined full path — drop, coalesce, or block — never unbounded growth. The subprocess relay queue holds 2 items, the filesystem watch queue coalesces at 256, image work caps batch bytes, retained pixels, decode size, and worker count.
• Waits end at cancellation or at the peer's own deadline (HTTP connect and total, handshake); they never end at a guessed wall-clock. No deadline kills a build, a hook, a lock wait, or shutdown.
• Retries are rare and deliberate, each stating why one attempt is insufficient: one rebuild retry after watches attach, at most ten bind attempts. Downloads and package fetches attempt once — a retry is not a fix for a flaky step.
• A new wait, poll, or retry loop names what ends it, where it observes cancellation, and what bounds it.

Cancellation is an outcome

• Observe the shared token between steps; polling is the whole mechanism, because no signal interrupts a running step. BuildCanceller::token is that token.
• Classification goes through the cancellation chain (is_cancelled), never string matching. Cancellation attaches no diagnostic: the CLI prints Cancelled and exits 130.
• Work that lost its reason stops at the next recheck. Staging rechecks inputs and cancellation before rename; the checked revision rechecks at handoff; a superseded or rejected candidate never becomes current.
• Recovery and rollback deliberately ignore cancellation: a restore of the previous tree or output finishes even when cancellation arrives.

Release on every exit path

• Ownership is drop-based: the value that owns a child process, temporary tree, or download terminates or removes it when dropped, and handing work on moves that owner instead of sharing it. A staged build's private tree disappears if the value drops before commit; a child's drop terminates its containment domain; an aborted download's drop cancels the task.
• Error and cancellation paths release through the same drop, not a separate cleanup branch.
• Cleanup failure after success only warns — it never revokes the committed result. A rollback path is the opposite: it must finish.

Make visibility a commit point

• Readers see whole values, never partial mutation: revisions swap atomically, a cache baseline advances only through its commit, and a published graph is never partially materialized.
• A step that can rerun leaves nothing consumed: a dropped claim consumes nothing, and a superseded attempt must not have advanced any baseline.
• Every concurrent producer declares its ordering: which error wins when two fail at once (assets before producers before the compiler, independent of completion order), and what becomes visible only after the commit.

Failures surface as diagnostics

• Errors attach a diagnostic code at the boundary that knows the operation; cancellation short-circuits before anything attaches.
• An unclassified internal failure still produces a human sentence; the fallback uses the outermost message.