Protocol concepts

Definitions, refs, scopes, and graph compilation.

Definitions

defineInfra lets a provider expose a typed builder. A configured definition is an immutable structural value with provider configuration, typed environment refs, hooks, scope declarations, and protocol metadata. It contains no credentials, client, state backend, or execution context.

Definitions are recognized structurally through Symbol.for("@infra-ts/protocol/v1"), so separately installed package copies can interoperate in one JavaScript realm.

Identity

A provider identity callback returns the globally unique definition ID. infra-ts trims the callback result and rejects an empty value. Provider metadata remains separate from identity.

Refs and graph compilation

ref(definition, path) and bound environment refs create dependency edges. compileGraph validates complete definitions, globally unique IDs, own-property paths, missing targets, self references, cycles, environment collisions, and explicit renames.

The compiler returns frozen arrays and null-prototype readonly lookup records. GraphExecutor consumes that order, propagates complete outputs, blocks only dependents of failed nodes, and continues independent definitions.

Environment scopes

Providers declare scopes through the environment contract. Each field records a public path, scope, projection, OS key, sensitivity, recovery policy, ownership, and source.

const root = contract.scope("root");
const preview = contract.scope("preview", { inherits: root });

parseEnv(definition, scope, source) reads an explicitly injected record or key function. toEntries(definition, scope, values) performs the reverse projection. Neither function performs filesystem or provider I/O.

ExternalEnvRef remains a structural ref in core resolved types and values. The runtime resolves it only when an explicit runtime env source is available.

Immutability and policy functions

Provider configuration accepts primitives, arrays, plain records, refs, and opaque policy functions. Definitions deeply clone and freeze records and arrays. Policy functions retain identity and can implement pure stage, Git environment, and provider target mapping.

Execution and hooks

Runtime operations carry { stack, environment: { name, stage, source } }. Source is explicit, default, git, or ci; all names reject whitespace and NUL.

Hooks are nested under checkout, apply, fetchEnv, and destroy. Checkout has resolve, prepare, env, and activate before/after boundaries. Hooks are functions only, never wrap plan/inspect, and run stack-first then definition order. Failure unwinds definitions in reverse and the stack last.