LibTmux.Batch

Description#

Partial outcomes, not transactions

Operation requires either acknowledgement-only or a Promise of Evidence. In command scope, Complete means a successful command acknowledgement; it does not prove an asynchronous external effect. In effect scope, Complete additionally requires matching named Evidence with satisfied=True. Evidence is supplied by the caller, who must arm and correlate its operation-specific observer before dispatch. A name match is not proof of causation. No caller callback runs inside the batch. Its deadline bounds waiting, not the caller's independent work. Evidence Promises are one-shot: rerunning effect-aware commands requires newly armed evidence, rather than treating an old observation as a new completion.

The immutable Batch captures finite membership, preserving order and rejecting duplicate names. Empty membership is a no-op. run/run-async accept an existing Runtime, Control connection or compatible CommandExecutor and never close it. Adapters must validate without effects, honor absolute deadlines and cancellation, settle their execution Promises with Receipt values, and preserve effect certainty in typed errors. All operations share one absolute deadline. A supplied :deadline(Instant) can shorten the local timeout-ms budget; it never extends that budget. The same Instant is passed to every command and retained in the report. An already expired deadline skips dispatch. The executor may use a shorter local limit. Cleanup retains the executor's own separate bounds. Cancelling a dispatched Control request can close that connection according to its documented delivery contract.

Every position receives an OperationResult. Failure stops subsequent dispatch by default; on-error=continue attempts remaining operations while time and cancellation permit. Never-dispatched suffixes are Skipped. A timed out or lost in-flight effect is Indeterminate, even if acknowledgement was received. The original exception and its outcome remain available through error/error-outcome. No rollback is attempted or promised, and reports retain no executor owner.

output-budget-bytes defaults to 8 MiB. After each operation, Batch counts receipt output and Command exception stdout/stderr, following shared Command causes only once. Reaching or exceeding the threshold stops further dispatch even under on-error=continue. The complete threshold-crossing receipt/error is retained and the undispatched suffix is Skipped. This is an admission threshold: retained output can reach the budget plus one executor-bounded response. It is not a hard RSS cap; object overhead, arbitrary adapter/evidence exceptions and independent caller-owned tasks remain outside that bound. Such adapters must accurately report Receipt.output-bytes and bound their own responses.