topology

type Block struct {
	// Name uniquely identifies the block and is used by block selection.
	Name string `yaml:"name"`

	// Parallel bounds concurrent runners for this block.
	Parallel int `yaml:"parallel"`

	// Components are the systems this block runs. A component may declare a database
	// matrix, which expands the block into one variant per engine.
	Components []Component `yaml:"components"`

	// Wiring configures components by name through their typed wiring specifications.
	Wiring map[string]yaml.Node `yaml:"wiring"`

	// Runners are the feature groups to execute.
	Runners []Runner `yaml:"runners"`

	// RunnersFrom names a source that supplies the block's runners instead of Runners.
	// The only supported source is RunnersFromPolicies: each policy in the block's
	// platform-gateway addPoliciesFrom tree declares its own runners in
	// <policy>/it/it.yaml.
	RunnersFrom string `yaml:"runnersFrom"`
}

type BlockSummary struct {
	Name       string
	DB         string
	Parallel   int
	Components []string
	Runners    []RunnerSummary
}

type Cleanup struct {
	// MaxAttempts is the total number of cleanup attempts for one resource. Zero disables
	// retries and is the default.
	MaxAttempts int `yaml:"max-attempts"`
}

type Component struct {
	// Name references a component in the registry.
	Name string `yaml:"name"`

	// AddPoliciesFrom selects a local policy tree used to build a custom platform gateway.
	// The path is resolved against the repository root when the build is prepared.
	AddPoliciesFrom string `yaml:"addPoliciesFrom"`

	// ReleasedPoliciesOnly, with addPoliciesFrom on a released Gateway version, builds only the
	// policies that release ships — the ones its users would upgrade. The rest of the tree can
	// need what the release's gateway-builder lacks. Ignored for a source build.
	ReleasedPoliciesOnly bool `yaml:"releasedPoliciesOnly"`

	// Overlay is an optional component configuration overlay.
	Overlay string `yaml:"overlay"`

	// StagedFiles overrides declared component resource sources for this block.
	// Keys are the staged target names already owned by the component definition.
	StagedFiles map[string]string `yaml:"stagedFiles"`

	// DB selects the component's engine or declares its matrix.
	DB DBSpec `yaml:"db"`

	// Version overrides the image version for this block's component instance.
	Version string `yaml:"version"`

	// Replicas is the number of instances to run.
	Replicas int `yaml:"replicas"`

	// DependsOn adds block-specific boot-order dependencies.
	DependsOn []string `yaml:"dependsOn"`
}

type ComponentDefaults struct {
	// DB selects the component's default engine. Matrix values are not allowed here.
	DB DBSpec `yaml:"db"`

	// DBCompatibility restricts database engines to Platform Gateway releases that
	// support them. Each engine maps to a strict gateway-version comparison, such
	// as sqlserver: "gateway-version>=1.2.0".
	DBCompatibility GatewayDBCompatibility `yaml:"dbCompatibility"`

	// Version overrides the version read from the component's VERSION file.
	Version string `yaml:"version"`
}

type DBSpec struct {
	// One is the single engine, set by the scalar form.
	One components.DBType

	// Variant is the selected supported variant key for scalar values.
	Variant string

	// Matrix is the engine list, set by the mapping form. At most one component per block
	// may set it — see expandMatrix.
	Matrix []components.DBType

	// Variants contains versioned variant keys from YAML matrix values.
	Variants []string
}

type DBVariant struct {
	Engine components.DBType
	Image  components.ImageRef
}

type Defaults struct {
	// Parallel bounds the number of blocks that run concurrently.
	Parallel int `yaml:"parallel"`

	// Components contains component-specific suite fallbacks.
	Components map[string]ComponentDefaults `yaml:"components"`

	// DB is retained as a compatibility alias for older suite files. New files should use
	// Components so database and image-version defaults share one component entry.
	DB map[string]DBSpec `yaml:"db"`

	// Timeouts are the suite-wide time limits.
	Timeouts Timeouts `yaml:"timeouts"`

	// Cleanup controls resource cleanup retries. A zero value logs deletion failures and
	// moves on without retrying.
	Cleanup Cleanup `yaml:"cleanup"`
}

type GatewayDBCompatibility map[components.DBType]gatewayVersionConstraint

type PolicyDescriptor struct {
	// Policy is the policy directory name.
	Policy string `yaml:"policy"`

	// Runners are the runners the policy contributes.
	Runners []PolicyRunner `yaml:"runners"`
}

type PolicyRunner struct {
	// Name identifies the runner within the policy.
	Name string `yaml:"name"`

	// Tags has the same form as Runner.Tags, including the optional gateway-version selector.
	Tags string `yaml:"tags"`

	// Features lists feature files relative to the policy's integration directory.
	Features []string `yaml:"features"`
}

type Resolved struct {
	Name     string
	Parallel int
	Timeouts Timeouts
	Cleanup  Cleanup

	// Blocks are fully expanded matrix variants.
	Blocks []ResolvedBlock

	// SkippedRunners records runners excluded by framework compatibility selection.
	SkippedRunners []SkippedRunner

	// SkippedBlocks records database variants excluded by framework compatibility selection.
	SkippedBlocks []SkippedBlock
}

type ResolvedBlock struct {
	// Name is the unique block identifier, including any matrix variant.
	Name string

	// Source is the block name as written, before matrix expansion.
	Source string

	// DB is the matrix engine for this variant, or empty when no matrix is declared.
	DB components.DBType

	Parallel   int
	Components []ResolvedComponent
	Runners    []Runner

	// RunnersFrom is the source that supplies Runners at selection time, or empty when the
	// block declares them itself.
	RunnersFrom string
}

type ResolvedComponent struct {
	// Def is the registered definition.
	Def *components.Definition

	// Version is the resolved image version, if one was configured.
	Version string

	// BuildFromSource indicates that the component has no configured image version and
	// should be built from the checked-out source.
	BuildFromSource bool

	// AddPoliciesFrom is the local policy tree used to build a custom gateway image.
	AddPoliciesFrom string

	// ReleasedPoliciesOnly builds only the policies a released Gateway ships; see Component.
	ReleasedPoliciesOnly bool

	// DB is the resolved component engine, or empty for a stateless component.
	DB components.DBType

	// DBCompatibility restricts a Platform Gateway database engine to compatible releases.
	DBCompatibility GatewayDBCompatibility

	// Image is the database server image selected for this component.
	Image components.ImageRef

	// Overlay is the block-supplied configuration overlay, if any.
	Overlay string

	// StagedFiles are block-scoped component resource source overrides.
	StagedFiles map[string]string

	// Replicas is the instance count.
	Replicas int

	// Wiring is the decoded, validated wiring value, or nil when the block supplied none.
	Wiring any

	// ExternalParameters are selection-time values passed to an external resolver.
	ExternalParameters map[string]string

	// DependsOn are block-specific boot-order dependencies.
	DependsOn []string
}

type Runner struct {
	// Name identifies the runner within its block.
	Name string `yaml:"name"`

	// Features lists feature files in execution order.
	Features []string `yaml:"features"`

	// Tags optionally begins with a framework gateway-version selector followed by ';', then
	// filters which scenarios in these features run using a Gherkin tag expression.
	Tags string `yaml:"tags"`

	// GatewayVersion is parsed from the optional framework selector in Tags. It is not a
	// suite-file field and must never be passed to Godog as a Gherkin tag expression.
	GatewayVersion *gatewayVersionConstraint `yaml:"-"`

	// Hook names an optional registered runner hook.
	Hook string `yaml:"hook"`
}

type RunnerSummary struct {
	Name     string
	Features []string
	Tags     string
}

type Selection struct {
	// Blocks names blocks to run. Empty means all. A matrix-generated variant is named
	// with its axis value, so "gateway-core/postgres" selects one variant.
	Blocks []string

	// SkipBlocks names blocks to exclude, applied after Blocks.
	SkipBlocks []string

	// Tags is a Gherkin tag expression applied on top of each runner's own tags, for
	// selecting a subset such as a smoke run.
	Tags string

	// Parallel overrides the suite's concurrent-block bound. Zero keeps the declared value.
	//
	Parallel int

	// RunnerParallel overrides every block's concurrent-runner bound. Zero keeps the
	// declared values.
	//
	RunnerParallel int

	// Coverage enables instrumented images and runtime coverage collection.
	Coverage bool

	// GatewayVersion overrides the image version for platform-gateway components. A release
	// such as "1.2.0" pulls that release and uses its configuration and contract. "latest"
	// pulls the images published nightly from main, and uses the current configuration and
	// contract, as a source build does.
	GatewayVersion string

	// GatewayHost overrides the image repository prefix for platform-gateway
	// controller and runtime images.
	GatewayHost string

	// CloudEnvironment selects the external cloud environment used by cloud-console.
	CloudEnvironment string

	// Policies names the policies whose integration runners are taken from the policy tree
	// by blocks declaring runnersFrom. Empty means every policy that declares runners.
	Policies []string

	// RepoRoot is the project root that relative policy trees resolve against. It is required
	// when a block takes its runners from a policy tree.
	RepoRoot string
}

type SkippedBlock struct {
	Block  string
	Reason string
}

type SkippedRunner struct {
	Block  string
	Runner string
	Reason string
}

type Suite struct {

	// Name identifies the suite in reports and in --list output.
	Name string `yaml:"suite"`

	// Defaults apply to every block that does not override them.
	Defaults Defaults `yaml:"defaults"`

	// Blocks are the topologies this suite runs.
	Blocks []Block `yaml:"blocks"`
}

type Timeouts struct {
	// Boot bounds bringing one block's topology up.
	Boot time.Duration `yaml:"boot"`

	// Propagation bounds asynchronous runtime propagation checks.
	Propagation time.Duration `yaml:"propagation"`
}