Runtime

Stack checkout, state, activation, and Git behavior.

defineStack combines definitions, heterogeneous provider bindings, environment policy, checkout hooks, env selection, optional materializations, and an optional pure Git resolver.

The CLI loads trusted infra.ts through jiti and executes:

resolve → prepare/reconcile graph → fetch env → activate

Prepare contains plan/apply only; env contains fetch/aggregation. Checkout rejects delete changes and every partial report before activation. Bind/plan failures stay node-local so independent definitions continue. Blocked and noop plans never apply. Destroy runs in reverse graph order and blocks upstream teardown after a dependent failure.

State

Providers declare stack, environment, or hybrid mode. Environment addresses include name and stage; source is provenance. Records use monotonic generations and delete tombstones to prevent ABA.

Filesystem state uses one atomically replaced document, fenced lease tokens/generations with lock-owned final publication and stale takeover, restrictive permissions, symlink rejection, temp+fsync+rename, and hard corruption failures.

Activation

Active checkout metadata is worktree-local, contains no values, includes config/graph/materialization fingerprints, and is written last. Secret files are opt-in, single-projection, batch-preflighted/staged, mode 0600, deterministic dotenv/JSON, and protected by a managed hash. Omitted managed files are removed only when unedited; user edits are retained and reported. The original approved hash survives staging, and recovery restores only content that still matches the transaction’s published hash.

infra-ts run -- <command> fetches the process projection without writing it, uses argv with shell: false, isolates a POSIX process group to avoid double delivery, forwards descendants, escalates repeated signals, and maps SIGHUP/SIGINT/SIGTERM to 129/130/143.

Git

Git integration is one-way: branch to logical environment. Mappings are sticky and local. The managed post-checkout hook is installed only with --trust-worktree-code, respects effective hooks paths, and refuses foreign or symlink hooks. It invokes only the worktree-local binary, warns and exits zero on sync failure. Shared/global hook files are never removed by per-repository uninstall. Sync failure invalidates active metadata before returning, so env/run cannot use previous-branch secrets. Detached HEAD is a no-op. Prune removes local mappings only.