Module matrix 

EnvMatrixSpec — the ephemeral-environment permutation generator.

One (defenvmatrix …) declaration fans a single EphemeralSpec base out across a set of named axes into the whole permutation set of environments, spawned together. This is generation-over-composition (Pillar 12) applied to environments: author the matrix once, get every variant.

Each permutation overlays its axis values into the base’s aplicacao.values_overlay (or a well-known @-target like @version), yielding a distinct canonical spec — so each variant gets its own deterministic EphemeralEnvId (blake3(spec)[:8]) and FQDN ({app}.{envId}.{cluster}.{location}.{domain}) for free, via the existing crate::hostname machinery. The matrix is workload-agnostic: the base can install any OCI chart, so the same primitive sweeps echo servers, gateways, migrations, or test suites.

Lisp authoring:

(defenvmatrix echo-sweep
  :base (:aplicacao (:chart-ref "oci://ghcr.io/pleme-io/charts/echo"
                     :version "0.1.0" :profile "minimal" :values-overlay ())
         :ttl "2h" :teardown Always)
  :axes ((:name "version"  :path "@version"     :values ("0.1.0" "0.2.0"))
         (:name "replicas" :path "replicaCount" :values (1 3))
         (:name "flag"     :path "feature.flag" :values ("on" "off")))
  :select Cartesian
  :budget (:max-envs 12 :cost-ceiling "$5/h")
  :breathe (:dimensions ((:kind "memory" :floor "128Mi" :ceiling "1Gi")
                         (:kind "cpu"    :floor "100m"  :ceiling "1"))
            :cooldown-seconds 60 :dry-run #t))

→ 2×2×2 = 8 named EphemeralSpecs. tatara-lispc renders each as a Process CR plus its breathe Band CRs (one per dimension), so the whole sweep is cost-bounded under the shared :budget and auto-scales within the :breathe floor/ceiling limits.

Structs

BreatheDimension

One banded resource dimension: which breathe Band kind and its bounds.

BreatheEnvelope

The breathe envelope inherited by every env in a sweep — the per-dimension homeostasis bounds plus dev-loop-tuned cadence.

EnvMatrixSpec

EnvMatrixSpec — authors (defenvmatrix …). Expands to a set of named EphemeralSpec values via EnvMatrixSpec::expand.

MatrixAxis

One permutation axis: a named dimension and the values it ranges over.

MatrixBudget

Shared budget across the sweep.

NamedEphemeral

A single generated environment: a deterministic name plus the lowered EphemeralSpec. The name is {matrix}-{axis-value}…; the env’s EphemeralEnvId is derived downstream from the spec’s canonical hash, so distinct overlays ⇒ distinct ids ⇒ distinct FQDNs automatically.

UnknownSelectStrategyKind

Enums

BreatheDimensionKind

Closed-set typed identifier for the three reachable breathe Band CR kinds a BreatheDimension::kind keyword can target — Self::Memory → MemoryBand, Self::Cpu → CpuBand, Self::Storage → StorageBand — as a Rust enum, so the (keyword-set, CR-kind, name-segment) triple binds at ONE site on the typed algebra rather than at three byte-identical string-literal sites scattered across EnvMatrixSpec::breathe_bands and the deleted band_kind_for helper.

MatrixTarget

Closed-set typed identifier for the @-prefixed magic targets a MatrixAxis::path can write into on the base EphemeralSpec — the three reachable aplicacao-field write targets (Self::Version → aplicacao.version, Self::Profile → aplicacao.profile, Self::ChartRef → aplicacao.chart_ref) — as a Rust enum, so the three-way (path-string, aplicacao-field) pairing binds at ONE site on the typed algebra rather than at three byte-identical inline arms in [apply_axis].

SelectStrategy

How the permutation set is drawn from the axes.

SelectStrategyKind

The closed set of SelectStrategy kinds — the discriminator view, payload-stripped, that sibling closed-set enums in this crate carry (see crate::lifetime_clock::TerminateReasonKind, MatrixTarget, BreatheDimensionKind).

Functions

compile_env_matrix_source

Compile a (defenvmatrix …) Lisp source into named EnvMatrixSpec values.