v1alpha1

type Blueprint struct {
	// Kind is the blueprint type, following Kubernetes conventions.
	Kind string `yaml:"kind"`

	// ApiVersion is the API schema version of the blueprint.
	ApiVersion string `yaml:"apiVersion"`

	// Metadata includes the blueprint's name and description.
	Metadata Metadata `yaml:"metadata"`

	// Backend names the terraform component that terminates the backend tier.
	Backend string `yaml:"backend,omitempty"`

	// Repository details the source repository of the blueprint.
	Repository Repository `yaml:"repository,omitempty"`

	// Sources are external resources referenced by the blueprint.
	Sources []Source `yaml:"sources,omitempty"`

	// TerraformComponents are Terraform modules in the blueprint.
	TerraformComponents []TerraformComponent `yaml:"terraform,omitempty"`

	// Crds is the flat list of vendored CRD references the blueprint installs from the default/project
	// source (e.g. "cert-manager-1.16.2"). It is authored and asserted as a bare scalar list, the same
	// form facets use. CRDs carried by an OCI source are not listed here — they ride with that Source
	// (see Source.Crds) and install in the background when the source is install:true. The provisioner
	// materializes these into the "crds" kustomization, bound to the default source, ahead of the stack.
	Crds []string `yaml:"crds,omitempty"`

	// Kustomizations are plain Flux Kustomization configs (the kustomize: passthrough).
	Kustomizations []Kustomization `yaml:"kustomize,omitempty"`

	// FluxSystems are system entries (the flux: collection): each compiles to an install plus
	// resources-variant Kustomizations. Distinct from Kustomizations, which are 1:1 passthroughs.
	FluxSystems []FluxSystem `yaml:"flux,omitempty"`

	// Substitutions are top-level key/value pairs evaluated with facet scope and injected into
	// values-common, making them available to all kustomizations via PostBuild substitution.
	// Values may use expression syntax (e.g. "${dns.domain}") resolved against facet config blocks.
	Substitutions map[string]string `yaml:"substitutions,omitempty"`

	// ConfigMaps are standalone ConfigMaps to be created, not tied to specific kustomizations.
	// These ConfigMaps are referenced by all kustomizations in PostBuild substitution.
	ConfigMaps map[string]map[string]string `yaml:"configMaps,omitempty"`

	// Messages are operator-facing post-run notes contributed by active facets. They carry raw
	// text/when templates through composition; GenerateResolved evaluates each against composed
	// scope, keeping only the when-true entries with interpolated text for the command to print.
	Messages []Message `yaml:"messages,omitempty"`
}

type BlueprintPatch struct {
	// Path to the patch file relative to the kustomization (blueprint format).
	Path string `yaml:"path,omitempty"`

	// Patch content as YAML string (Flux format).
	Patch string `yaml:"patch,omitempty"`

	// Target selector for the patch (Flux format).
	Target *kustomize.Selector `yaml:"target,omitempty"`
}

type BoolExpression struct {
	Value  *bool
	Expr   string
	IsExpr bool
}

type ConditionalKustomization struct {
	Kustomization `yaml:",inline"`

	// When is an expression that determines if this kustomization should be applied.
	// If empty, the kustomization is always applied when the parent facet matches.
	When string `yaml:"when,omitempty"`

	// Strategy determines how this kustomization is merged into the blueprint.
	// Valid values are "merge" (default), "replace", and "remove".
	// If empty or "merge", the kustomization is merged with existing kustomizations matching the same Name.
	// If "replace", the kustomization completely replaces any existing kustomization with the same Name.
	// If "remove", the kustomization's non-index fields (everything except Name) are removed from the
	// matching existing kustomization. Remove operations are always applied last after all merge/replace operations.
	Strategy string `yaml:"strategy,omitempty"`

	// Ordinal overrides the facet ordinal for this kustomization's merge precedence. When nil, the facet's ordinal is used.
	// Higher ordinal means higher precedence when merging (processed later, wins on conflict).
	Ordinal *int `yaml:"ordinal,omitempty"`

	// Requires lists requirement blocks scoped to this kustomization. Evaluated only when the parent
	// facet is active and this kustomization's When holds; missing paths are aggregated under the
	// effective condition (facet.When && kustomization.When && block.When).
	Requires []RequirementBlock `yaml:"requires,omitempty"`
}

type ConditionalTerraformComponent struct {
	TerraformComponent `yaml:",inline"`

	// When is an expression (expr-lang/expr) that determines if this terraform
	// component should be applied. If empty, the component is always applied
	// when the parent facet matches.
	When string `yaml:"when,omitempty"`

	// Strategy determines how this component is merged into the blueprint.
	// Valid values are "merge" (default), "replace", and "remove".
	// If empty or "merge", the component is merged with existing components matching the same Path and Source.
	// If "replace", the component completely replaces any existing component with the same Path and Source.
	// If "remove", the component's non-index fields (everything except Path and Source) are removed from the
	// matching existing component. Remove operations are always applied last after all merge/replace operations.
	Strategy string `yaml:"strategy,omitempty"`

	// Ordinal overrides the facet ordinal for this component's merge precedence. When nil, the facet's ordinal is used.
	// Higher ordinal means higher precedence when merging (processed later, wins on conflict).
	Ordinal *int `yaml:"ordinal,omitempty"`

	// Requires lists requirement blocks scoped to this terraform component. Evaluated only when the
	// parent facet is active and this component's When holds; missing paths are aggregated under the
	// effective condition (facet.When && component.When && block.When).
	Requires []RequirementBlock `yaml:"requires,omitempty"`
}

type Config struct {
	Version      string               `yaml:"version"`
	ToolsManager string               `yaml:"toolsManager,omitempty"`
	Terraform    *RootTerraformConfig `yaml:"terraform,omitempty"`
	Contexts     map[string]*Context  `yaml:"contexts"`
}

type ConfigBlock struct {
	// Name identifies the block; exposed at scope root.
	Name string `yaml:"name"`
	// When is an expression that determines if this config block is evaluated; if empty, always evaluated when facet is active.
	When string `yaml:"when,omitempty"`
	// Strategy determines how this block is merged with blocks of the same name from other facets.
	// Valid values are "merge" (default), "replace", and "remove". If "merge", the block is deep-merged.
	// If "replace", the block replaces any existing block with the same name. If "remove", the block is removed from scope.
	Strategy string `yaml:"strategy,omitempty"`
	// Ordinal overrides the facet ordinal for this block's merge precedence. When nil, the facet's ordinal is used.
	// Higher ordinal means higher precedence when merging (wins on conflict).
	Ordinal *int `yaml:"ordinal,omitempty"`
	// Requires lists requirement blocks scoped to this config block. When the parent facet is active and this
	// block's optional When holds, every block in Requires is evaluated under the AND of facet.When,
	// block.When, and each Requires entry's own When. Missing paths are aggregated alongside facet- and
	// component-level misses in the user-facing error.
	Requires []RequirementBlock `yaml:"requires,omitempty"`
	// Body holds the canonical content as map[string]any{"value": <content>} for merge and evaluation. Not YAML-marshaled directly.
	Body map[string]any `yaml:"-"`
}

type Context struct {
	ID          *string                    `yaml:"id,omitempty"`
	Platform    *string                    `yaml:"platform,omitempty"`
	Provider    *string                    `yaml:"provider,omitempty"`
	Environment map[string]string          `yaml:"environment,omitempty"`
	Secrets     *secrets.SecretsConfig     `yaml:"secrets,omitempty"`
	AWS         *aws.AWSConfig             `yaml:"aws,omitempty"`
	Azure       *azure.AzureConfig         `yaml:"azure,omitempty"`
	GCP         *gcp.GCPConfig             `yaml:"gcp,omitempty"`
	VSphere     *vsphere.VSphereConfig     `yaml:"vsphere,omitempty"`
	Docker      *docker.DockerConfig       `yaml:"docker,omitempty"`
	Git         *git.GitConfig             `yaml:"git,omitempty"`
	Terraform   *terraform.TerraformConfig `yaml:"terraform,omitempty"`
	VM          *vm.VMConfig               `yaml:"vm,omitempty"`
	Cluster     *cluster.ClusterConfig     `yaml:"cluster,omitempty"`
	Network     *network.NetworkConfig     `yaml:"network,omitempty"`
	DNS         *dns.DNSConfig             `yaml:"dns,omitempty"`
}

type Decryption struct {
	// Provider is the decryption backend, e.g. "sops".
	Provider string `yaml:"provider,omitempty"`

	// SecretRef names the in-cluster Secret holding the decryption key.
	SecretRef *DecryptionSecretRef `yaml:"secretRef,omitempty"`
}

type DecryptionSecretRef struct {
	// Name is the Secret's name.
	Name string `yaml:"name,omitempty"`
}

type DurationString struct {
	Duration time.Duration
}

type Facet struct {
	// Kind is the facet type, following Kubernetes conventions.
	Kind string `yaml:"kind"`

	// ApiVersion is the API schema version of the facet.
	ApiVersion string `yaml:"apiVersion"`

	// Metadata includes the facet's name and description.
	Metadata Metadata `yaml:"metadata"`

	// Path is the file path where this facet was loaded from.
	// This is used for resolving relative paths in jsonnet() and file() functions.
	Path string `yaml:"-"`

	// Source names the blueprint source this facet came from. Set transiently during composition so a
	// globally-resolved facet can be emitted back into its own source's blueprint; never serialized.
	Source string `yaml:"-"`

	// Ordinal guides the order in which this facet is applied relative to others. Higher ordinal means higher precedence when merging.
	// When nil, the loader derives ordinal from the facet file basename (e.g. config-* 100, provider-base/platform-base 199, provider-/platform- 200, options- 300, addon-/addons- 400).
	Ordinal *int `yaml:"ordinal,omitempty"`

	// When is an expression that determines if this facet should be applied.
	// The expression is evaluated against user configuration values via the
	// expr-lang/expr library (NOT Google's CEL).
	// Examples: "platform == 'aws'", "observability.enabled == true && observability.backend == 'quickwit'"
	When string `yaml:"when,omitempty"`

	// Backend contributes Blueprint.Backend; the composer merges by ordinal precedence.
	Backend string `yaml:"backend,omitempty"`

	// Config is a list of named configuration blocks evaluated in blueprint context and exposed at scope root.
	// Terraform inputs and kustomize substitutions reference <name>.<key> (e.g. talos.controlplanes), like context (cluster.*, network.*).
	Config []ConfigBlock `yaml:"config,omitempty"`

	// Requires lists input requirement blocks. When the facet is active and a block's optional When holds,
	// every path must resolve to a present, non-empty value in the merged scope. Unsatisfied paths across
	// every active facet are aggregated into a single user-facing error.
	Requires []RequirementBlock `yaml:"requires,omitempty"`

	// TerraformComponents are Terraform modules in the facet.
	TerraformComponents []ConditionalTerraformComponent `yaml:"terraform,omitempty"`

	// Kustomizations are kustomization configs in the facet.
	Kustomizations []ConditionalKustomization `yaml:"kustomize,omitempty"`

	// FluxSystems are system entries (the flux: collection) contributed by this facet; each compiles
	// to an install plus resources-variant Kustomizations.
	FluxSystems []FluxSystem `yaml:"flux,omitempty"`

	// Crds lists references into the vendored CRD catalog (e.g. "cert-manager-1.16.2").
	// The composer emits one deduped kustomization per reference at kustomize/crds/<ref>
	// and makes every kustomization in this facet depend on it.
	Crds []string `yaml:"crds,omitempty"`

	// Substitutions are top-level key/value pairs evaluated with facet scope and injected into
	// values-common, making them available to all kustomizations via PostBuild substitution.
	// Values may use expression syntax (e.g. "${dns.domain}") resolved against facet config blocks.
	Substitutions map[string]string `yaml:"substitutions,omitempty"`

	// Messages are operator-facing notes rendered at the end of a bootstrap/apply run. Unlike a
	// requires: message (failure path, pre-flight, verbatim), a post-run message is on the success
	// path, rendered after apply, and interpolated against composed scope — so its text can carry
	// run values (e.g. terraform_output). Each entry's optional When gates it; text is the message.
	Messages []Message `yaml:"messages,omitempty"`
}

type FluxSystem struct {
	// Name identifies the system; tiers compile to "<name>-install" / "<name>-resources[-<variant>]".
	Name string `yaml:"name"`

	// Path is the base; tiers reconcile from "<path>/install" and "<path>/resources". Defaults to Name.
	Path string `yaml:"path,omitempty"`

	// Source is the blueprint source that provides the tier bases.
	Source string `yaml:"source,omitempty"`

	// Enabled includes or excludes the whole system. Defaults to true.
	Enabled *BoolExpression `yaml:"enabled,omitempty"`

	// Destroy governs whether the system's kustomizations are removed on teardown. Defaults to true.
	Destroy *BoolExpression `yaml:"destroy,omitempty"`

	// When gates the system; combined (AND) with each resources variant's own condition.
	When string `yaml:"when,omitempty"`

	// DependsOn are cross-layer edges to other systems, attached to the install tier when present
	// (resources reach them transitively) or to each resources variant otherwise. It never names the
	// intra-system install edge — that edge is implicit.
	DependsOn []string `yaml:"dependsOn,omitempty"`

	// Strategy governs how a system with this Name merges across facets (merge | replace | remove).
	Strategy string `yaml:"strategy,omitempty"`

	// Ordinal overrides the facet's ordinal for this system's merge precedence.
	Ordinal *int `yaml:"ordinal,omitempty"`

	// GlobalDependency inverts the system's edges: when true, every kustomization and system outside
	// this system's own dependency closure is wired to depend on its terminal tier — its resources tier
	// if it has one, else its install tier. It lets a cluster-wide precondition (e.g. admission policies
	// that must be enforcing before any workload lands) be declared once here rather than repeated as a
	// dependsOn on every consumer. The closure exclusion keeps the system, and anything it depends on,
	// from ordering after itself.
	GlobalDependency bool `yaml:"globalDependency,omitempty"`

	// Install is the controller/operator tier (at most one). Its Components/Substitute and operational
	// fields flow to "<name>-install"; its Name/Path/DependsOn are derived by the composer.
	Install *Kustomization `yaml:"install,omitempty"`

	// Resources are the custom-resource tier variants, all sharing "<path>/resources".
	Resources []FluxVariant `yaml:"resources,omitempty"`

	// Secrets declares Kubernetes Secrets for this system, keyed by Secret name; each entry carries the
	// Secret's data (data key -> reference to a schema property marked `sensitive: true`) and, optionally,
	// the namespaces to place it into. Unlike Substitute (plaintext ConfigMap material), Secrets back real
	// Secrets placed into the system's namespace(s) and are resolved and materialized separately — their
	// values are never rendered or written in plaintext.
	Secrets map[string]SecretEntry `yaml:"secrets,omitempty"`
}

type FluxVariant struct {
	Kustomization `yaml:",inline"`

	// When gates this variant; combined (AND) with the system's own condition.
	When string `yaml:"when,omitempty"`
}

type IntExpression struct {
	Value  *int
	Expr   string
	IsExpr bool
}

type Kustomization struct {
	// Name of the kustomization. Omitted when empty so an unnamed inline flux resources variant
	// (a Kustomization embedded in FluxVariant) does not emit a blank name: into the composed output.
	Name string `yaml:"name,omitempty"`

	// Path of the kustomization. Defaults to Name.
	Path string `yaml:"path,omitempty"`

	// Source of the kustomization.
	Source string `yaml:"source,omitempty"`

	// Namespace overrides the namespace where the Flux Kustomization object itself lives.
	// When unset, the gitops namespace is used. DependsOn references always resolve in the
	// gitops namespace, so cross-namespace dependencies are not currently supported.
	Namespace string `yaml:"namespace,omitempty"`

	// TargetNamespace populates spec.targetNamespace, instructing Flux to override the
	// namespace of every resource reconciled by this kustomization.
	TargetNamespace string `yaml:"targetNamespace,omitempty"`

	// DependsOn lists dependencies of this kustomization.
	DependsOn []string `yaml:"dependsOn,omitempty"`

	// Interval for applying the kustomization.
	Interval *DurationString `yaml:"interval,omitempty"`

	// RetryInterval before retrying a failed kustomization.
	RetryInterval *DurationString `yaml:"retryInterval,omitempty"`

	// Timeout for the kustomization to complete.
	Timeout *DurationString `yaml:"timeout,omitempty"`

	// Patches to apply to the kustomization.
	Patches []BlueprintPatch `yaml:"patches,omitempty"`

	// Wait for the kustomization to be fully applied.
	Wait *bool `yaml:"wait,omitempty"`

	// Force apply the kustomization.
	Force *bool `yaml:"force,omitempty"`

	// Prune enables garbage collection of resources that are no longer present in the source.
	Prune *bool `yaml:"prune,omitempty"`

	// Components to include in the kustomization.
	Components []string `yaml:"components,omitempty"`

	// Destroy determines if the kustomization should be destroyed during down operations.
	// Defaults to true if not specified.
	// Supports expressions in facets: use "${cluster.destroy ?? true}" for dynamic values.
	Destroy *BoolExpression `yaml:"destroy,omitempty"`

	// DestroyOnly indicates that this kustomization should only run during destroy operations.
	// When true, the kustomization is skipped during apply/up operations and only executed during destroy.
	// Destroy-only kustomizations run before regular kustomizations during destroy, in normal dependency order.
	DestroyOnly *bool `yaml:"destroyOnly,omitempty"`

	// Enabled determines if the kustomization should be included in the final blueprint.
	// Defaults to true if not specified.
	// Supports expressions in facets: use "${some.condition ?? true}" for dynamic values.
	Enabled *BoolExpression `yaml:"enabled,omitempty"`

	// Substitutions contains values for post-build variable replacement,
	// collected and stored in ConfigMaps for use by Flux postBuild substitution.
	// All values are converted to strings as required by Flux variable substitution.
	// These are used for generating ConfigMaps and are not written to the final context blueprint.yaml.
	Substitutions map[string]string `yaml:"substitutions,omitempty"`

	// Substitute is the preferred spelling of Substitutions; both keys merge into Substitutions
	// during composition. It exists so `flux:` system tiers and `kustomize:` entries can spell
	// postBuild substitutions the same short way (matching Flux's `postBuild.substitute`).
	Substitute map[string]string `yaml:"substitute,omitempty"`

	// Secrets carries a flux system's Secrets onto its compiled namespace-owning tier so the imperative
	// placement step can find them after flattening: Secret name -> SecretEntry (target namespaces plus
	// data), resolved JIT at placement, never during composition. It is yaml:"-" so it is never
	// marshaled into show/apply output or the written blueprint, keeping secret material out of every
	// serialized surface by construction.
	Secrets map[string]SecretEntry `yaml:"-"`

	// Decryption configures in-cluster decryption for this kustomization's manifests, mapping to Flux's
	// spec.decryption. Nil leaves decryption unset (Flux default: no decryption).
	Decryption *Decryption `yaml:"decryption,omitempty"`
}

type Message struct {
	// When is an optional expression gating whether this message renders. Empty means always.
	When string `yaml:"when,omitempty"`

	// Text is the message body. It is expression-evaluated against composed scope, so it may
	// reference config values and run outputs (e.g. "${terraform_output('dns-zone', 'nameservers')}").
	Text string `yaml:"text"`
}

type Metadata struct {
	// Name is the blueprint's unique identifier.
	Name string `yaml:"name"`

	// Description is a brief overview of the blueprint.
	Description string `yaml:"description,omitempty"`
}

type PostBuild struct {
	// Substitute is a map of resources to substitute from.
	Substitute map[string]string `yaml:"substitute,omitempty"`

	// SubstituteFrom is a list of resources to substitute from.
	SubstituteFrom []SubstituteReference `yaml:"substituteFrom,omitempty"`
}

type Reference struct {
	// Branch to use.
	Branch string `yaml:"branch,omitempty"`

	// Tag to use.
	Tag string `yaml:"tag,omitempty"`

	// SemVer to use.
	SemVer string `yaml:"semver,omitempty"`

	// Name of the reference.
	Name string `yaml:"name,omitempty"`

	// Commit hash to use.
	Commit string `yaml:"commit,omitempty"`
}

type Repository struct {
	// Url is the repository location.
	Url string `yaml:"url,omitempty"`

	// Ref details the branch, tag, or commit to use.
	Ref Reference `yaml:"ref,omitempty"`

	// SecretName is the secret for repository access.
	SecretName *string `yaml:"secretName,omitempty"`
}

type RequirementBlock struct {
	// When is an expression gating this block. Empty means always required while the parent facet is active.
	When string `yaml:"when,omitempty"`

	// Paths are dotted scope keys whose values must be present and non-empty.
	Paths []string `yaml:"paths"`

	// Message is optional author-supplied context surfaced under this block's heading in the aggregated error.
	Message string `yaml:"message,omitempty"`
}

type RootTerraformConfig struct {
	Driver string `yaml:"driver,omitempty"`
}

type SecretEntry struct {
	// Namespaces are the namespaces to place this Secret into. Empty means auto-resolve the single
	// namespace the owning kustomization creates; each named namespace must be one that kustomization
	// provably created.
	Namespaces []string `yaml:"namespaces,omitempty"`

	// Data is the Secret's contents: data key -> reference to a schema property, resolved JIT at
	// placement and never rendered in plaintext. Materializes as an Opaque Secret by default; a
	// ".dockerconfigjson" key, or "docker-username" plus "docker-password" (optional
	// "docker-server", defaulting to "ghcr.io"), materializes as kubernetes.io/dockerconfigjson
	// instead, for use as an imagePullSecret — see ApplySecret/secretTypeAndData.
	Data map[string]string `yaml:"data,omitempty"`
}

type Source struct {
	// Name identifies the source.
	Name string `yaml:"name"`

	// Url is the source location.
	Url string `yaml:"url,omitempty"`

	// PathPrefix is a prefix to the source path.
	PathPrefix string `yaml:"pathPrefix,omitempty"`

	// Ref details the branch, tag, or commit to use.
	Ref Reference `yaml:"ref,omitempty"`

	// SecretName is the secret for source access.
	SecretName string `yaml:"secretName,omitempty"`

	// Install determines if the source should be merged (components merged into final blueprint).
	// Defaults to false if not specified.
	// Supports expressions in facets: use "${some.condition ?? true}" for dynamic values.
	Install *BoolExpression `yaml:"install,omitempty"`

	// Crds is the flat list of CRD references this source vendors at <source>/kustomize/crds/<ref>.
	// Populated by the composer from the source's included facets. When the source is install:true,
	// the provisioner materializes these into a background "crds-<name>" kustomization bound to this
	// source, so its CRDs install ahead of the stack without the blueprint author listing them.
	Crds []string `yaml:"crds,omitempty"`
}

type SubstituteReference struct {
	// Kind of the resource to substitute from.
	Kind string `yaml:"kind"`

	// Name of the resource to substitute from.
	Name string `yaml:"name"`

	// Optional indicates if the resource is optional.
	Optional bool `yaml:"optional,omitempty"`
}

type TerraformComponent struct {
	// Name of the terraform component. If provided, this becomes the unique identifier
	// instead of Path. Used for referencing in dependencies and context variables.
	Name string `yaml:"name,omitempty"`

	// Source of the Terraform module.
	Source string `yaml:"source,omitempty"`

	// Path of the Terraform module.
	Path string `yaml:"path"`

	// FullPath is the complete path, not serialized to YAML.
	FullPath string `yaml:"-"`

	// DependsOn lists dependencies of this terraform component.
	DependsOn []string `yaml:"dependsOn,omitempty"`

	// Inputs are configuration values for the module.
	// These values can be expressions using ${} syntax (e.g., "${cluster.name}") or literals.
	// Values with ${} are evaluated as expressions, plain values are passed through as literals.
	// These are used for generating tfvars files and are not written to the final context blueprint.yaml.
	Inputs map[string]any `yaml:"inputs,omitempty"`

	// Destroy determines if the component should be destroyed during down operations.
	// Defaults to true if not specified.
	// Supports expressions in facets: use "${cluster.destroy ?? true}" for dynamic values.
	Destroy *BoolExpression `yaml:"destroy,omitempty"`

	// Parallelism limits the number of concurrent operations as Terraform walks the graph.
	// This corresponds to the -parallelism flag in terraform apply/destroy commands.
	// Supports expressions in facets: use "${cluster.parallelism ?? 10}" for dynamic values.
	Parallelism *IntExpression `yaml:"parallelism,omitempty"`

	// Enabled determines if the component should be included in the final blueprint.
	// Defaults to true if not specified.
	// Supports expressions in facets: use "${some.condition ?? true}" for dynamic values.
	Enabled *BoolExpression `yaml:"enabled,omitempty"`

	// InputOrigins maps each input key to the facet file path that defined it.
	// Used internally for resolving relative paths in deferred expression evaluation.
	InputOrigins map[string]string `yaml:"-"`
}

type TestCase struct {
	// Name is the unique identifier for this test case.
	Name string `yaml:"name"`

	// Values are configuration values to apply before composing the blueprint.
	// These override any existing configuration for the test.
	Values map[string]any `yaml:"values,omitempty"`

	// Env provides environment variables visible to env() expressions during composition.
	// Resolution is hermetic: env() sees only these entries, never the host environment.
	Env map[string]string `yaml:"env,omitempty"`

	// TerraformOutputs provides mock terraform outputs for terraform_output() expressions.
	// Keys are component IDs, values are maps of output key-value pairs.
	// Example: {"network": {"vpc_id": "vpc-123", "subnet_ids": ["subnet-1", "subnet-2"]}}
	TerraformOutputs map[string]map[string]any `yaml:"terraformOutputs,omitempty"`

	// Expect defines components that must be present in the composed blueprint.
	// Uses partial matching: only specified fields are checked.
	// Kind, ApiVersion, and Metadata are ignored for matching purposes.
	Expect *Blueprint `yaml:"expect,omitempty"`

	// Exclude defines components that must NOT be present in the composed blueprint.
	// Uses partial matching: only specified fields are checked.
	// Kind, ApiVersion, and Metadata are ignored for matching purposes.
	Exclude *Blueprint `yaml:"exclude,omitempty"`

	// ExpectError indicates that blueprint composition is expected to fail with an error.
	// If true, the test passes when composition fails and fails when composition succeeds.
	// This is useful for testing invalid configurations that should be rejected by the framework.
	ExpectError bool `yaml:"expectError,omitempty"`

	// ApplySchemaDefaults composes this case with schema `default:` values materialized, as
	// production does. The test path otherwise skips schema defaults so a facet is exercised on
	// its own defaulting logic; set this to validate a facet that relies on a schema default
	// (e.g. a read of network.cidr_block with no `?? <fallback>`). Off by default; other cases
	// are unaffected.
	ApplySchemaDefaults bool `yaml:"applySchemaDefaults,omitempty"`
}

type TestFile struct {
	// Cases is a list of test cases to execute.
	Cases []TestCase `yaml:"cases"`
}