platform

type AuthzPolicy struct {
	// Role is the tier role this policy applies to.
	Role TierRole

	// AllowedTiers is the set of tiers the role may access.
	AllowedTiers []Tier

	// AllowedOperations is the set of operation names the role may perform.
	// An empty slice means no operations are allowed.
	AllowedOperations []string
}

type CapabilityConfig struct {
	// Name is the unique identifier for this capability within its tier.
	Name string `yaml:"name" json:"name"`

	// Type is the abstract capability type (e.g., "container_runtime", "database").
	Type string `yaml:"type" json:"type"`

	// Properties are provider-agnostic configuration values.
	Properties map[string]any `yaml:"properties,omitempty" json:"properties,omitempty"`

	// DependsOn lists other capability names that must be provisioned first.
	DependsOn []string `yaml:"dependsOn,omitempty" json:"dependsOn,omitempty"`
}

type CapabilityDeclaration struct {
	// Name is the unique identifier for this capability within a tier.
	Name string `yaml:"name" json:"name"`

	// Type is the abstract capability type (e.g., "container_runtime", "database", "message_queue").
	Type string `yaml:"type" json:"type"`

	// Tier indicates which infrastructure tier this capability belongs to.
	Tier Tier `yaml:"tier" json:"tier"`

	// Properties are abstract, provider-agnostic configuration values
	// (e.g., replicas, memory, ports).
	Properties map[string]any `yaml:"properties" json:"properties"`

	// Constraints are hard limits imposed by parent tiers.
	Constraints []Constraint `yaml:"constraints" json:"constraints"`

	// DependsOn lists other capability names that must be provisioned first.
	DependsOn []string `yaml:"dependsOn" json:"dependsOn"`
}

type CapabilityMapper interface {
	// CanMap returns true if this mapper can handle the given capability type.
	CanMap(capabilityType string) bool

	// Map translates a capability declaration into one or more resource plans.
	// The PlatformContext provides parent tier outputs and constraints.
	Map(decl CapabilityDeclaration, pctx *PlatformContext) ([]ResourcePlan, error)

	// ValidateConstraints checks if a capability declaration satisfies all
	// constraints imposed by parent tiers. Returns any constraint violations found.
	ValidateConstraints(decl CapabilityDeclaration, constraints []Constraint) []ConstraintViolation
}

type CapabilityType struct {
	// Name is the capability type identifier (e.g., "container_runtime", "database").
	Name string `json:"name"`

	// Description is a human-readable description of the capability.
	Description string `json:"description"`

	// Tier indicates which infrastructure tier this capability belongs to.
	Tier Tier `json:"tier"`

	// Properties are the property schemas this capability accepts.
	Properties []PropertySchema `json:"properties"`

	// Constraints are the constraint schemas this capability can enforce.
	Constraints []PropertySchema `json:"constraints"`

	// Fidelity indicates how faithfully this provider implements the capability.
	Fidelity FidelityLevel `json:"fidelity"`
}

type CapabilityUnsupportedError struct {
	// Capability is the unsupported capability type.
	Capability string

	// Provider is the provider that does not support it.
	Provider string
}

type Constraint struct {
	// Field is the property being constrained (e.g., "memory", "replicas", "cpu").
	Field string `yaml:"field" json:"field"`

	// Operator is the comparison operator: "<=", ">=", "==", "in", "not_in".
	Operator string `yaml:"operator" json:"operator"`

	// Value is the constraint limit value.
	Value any `yaml:"value" json:"value"`

	// Source identifies which context or tier imposed this constraint.
	Source string `yaml:"source" json:"source"`
}

type ConstraintConfig struct {
	// Field is the property being constrained (e.g., "memory", "replicas").
	Field string `yaml:"field" json:"field"`

	// Operator is the comparison operator: "<=", ">=", "==", "in", "not_in".
	Operator string `yaml:"operator" json:"operator"`

	// Value is the constraint limit value.
	Value any `yaml:"value" json:"value"`
}

type ConstraintValidator struct{}

type ConstraintViolation struct {
	// Constraint is the constraint that was violated.
	Constraint Constraint `json:"constraint"`

	// Actual is the value that violated the constraint.
	Actual any `json:"actual"`

	// Message is a human-readable description of the violation.
	Message string `json:"message"`
}

type ConstraintViolationError struct {
	// Resource is the name of the resource that violated the constraint.
	Resource string

	// Constraint is the constraint field that was violated.
	Constraint string

	// Value is the actual value that caused the violation.
	Value any

	// Limit is the constraint limit that was exceeded.
	Limit any
}

type ContextResolver interface {
	// ResolveContext builds a PlatformContext for the given tier and identifiers.
	// It reads parent tier state stores to populate ParentOutputs and Constraints.
	ResolveContext(ctx context.Context, org, env, app string, tier Tier) (*PlatformContext, error)

	// PropagateOutputs writes resource outputs into the context store so that
	// downstream tiers can resolve them via ResolveContext.
	PropagateOutputs(ctx context.Context, pctx *PlatformContext, outputs []*ResourceOutput) error

	// ValidateTierBoundary ensures a workflow operating at the given tier
	// does not attempt to modify resources outside its scope. Returns any
	// constraint violations found.
	ValidateTierBoundary(pctx *PlatformContext, declarations []CapabilityDeclaration) []ConstraintViolation
}

type CredentialBroker interface {
	// IssueCredential creates a scoped credential for the given platform context.
	// The credential value is stored in the secrets backend and a reference is returned.
	IssueCredential(ctx context.Context, pctx *PlatformContext, request CredentialRequest) (*CredentialRef, error)

	// RevokeCredential invalidates a previously issued credential and removes it
	// from the secrets backend.
	RevokeCredential(ctx context.Context, ref *CredentialRef) error

	// ResolveCredential retrieves the actual credential value from a reference.
	// This is the only way to access the credential value at runtime.
	ResolveCredential(ctx context.Context, ref *CredentialRef) (string, error)

	// RotateCredential replaces an existing credential with a new one, revoking
	// the old credential. Returns the new credential reference.
	RotateCredential(ctx context.Context, ref *CredentialRef) (*CredentialRef, error)

	// ListCredentials returns all credential references for a given platform context.
	ListCredentials(ctx context.Context, pctx *PlatformContext) ([]*CredentialRef, error)
}

type CredentialRef struct {
	// ID is the unique credential identifier.
	ID string `json:"id"`

	// Name is the human-readable credential name.
	Name string `json:"name"`

	// SecretPath is the path in the secrets backend where the value is stored.
	SecretPath string `json:"secretPath"`

	// Provider is the name of the secrets provider that holds the value.
	Provider string `json:"provider"`

	// ExpiresAt is when the credential expires.
	ExpiresAt time.Time `json:"expiresAt"`

	// Tier is the infrastructure tier the credential is scoped to.
	Tier Tier `json:"tier"`

	// ContextPath is the hierarchical context path (org/env/app).
	ContextPath string `json:"contextPath"`
}

type CredentialRequest struct {
	// Name is a human-readable name for the credential.
	Name string `json:"name"`

	// Type is the credential type: "api_key", "database", "tls_cert", "token".
	Type string `json:"type"`

	// Scope lists the resource names this credential can access.
	Scope []string `json:"scope"`

	// TTL is the credential lifetime. A zero value means no expiry.
	TTL time.Duration `json:"ttl"`

	// Renewable indicates whether the credential can be renewed before expiry.
	Renewable bool `json:"renewable"`
}

type CrossTierImpact struct {
	// SourceDrift is the drift that triggered the impact analysis.
	SourceDrift DriftResult `json:"sourceDrift"`

	// AffectedResources are the downstream resources potentially impacted.
	AffectedResources []DependencyRef `json:"affectedResources"`
}

type DependencyRef struct {
	// SourceContext is the context path of the depended-upon resource.
	SourceContext string `json:"sourceContext"`

	// SourceResource is the name of the depended-upon resource.
	SourceResource string `json:"sourceResource"`

	// TargetContext is the context path of the dependent resource.
	TargetContext string `json:"targetContext"`

	// TargetResource is the name of the dependent resource.
	TargetResource string `json:"targetResource"`

	// Type is the dependency type: "hard" (must exist) or "soft" (optional).
	Type string `json:"type"`
}

type DiffEntry struct {
	// Path is the dot-separated field path (e.g., "properties.replicas").
	Path string `json:"path"`

	// OldValue is the current value of the field.
	OldValue any `json:"oldValue"`

	// NewValue is the desired value of the field.
	NewValue any `json:"newValue"`
}

type DriftResult struct {
	// ContextPath is the hierarchical context path of the resource.
	ContextPath string `json:"contextPath"`

	// ResourceName is the name of the resource.
	ResourceName string `json:"resourceName"`

	// ResourceType is the provider-specific resource type.
	ResourceType string `json:"resourceType"`

	// Tier is the tier the resource belongs to.
	Tier Tier `json:"tier"`

	// DriftType classifies the drift: "changed", "added", "removed".
	DriftType string `json:"driftType"`

	// Diffs contains the individual field differences (for "changed" type).
	Diffs []DiffEntry `json:"diffs,omitempty"`

	// Expected is the stored state.
	Expected map[string]any `json:"expected,omitempty"`

	// Actual is the live state from the provider.
	Actual map[string]any `json:"actual,omitempty"`
}

type ExecutionConfig struct {
	// Tier1Mode controls Tier 1 execution: "plan_and_approve" or "auto_apply".
	Tier1Mode string `yaml:"tier1_mode" json:"tier1_mode"`

	// Tier2Mode controls Tier 2 execution: "plan_and_approve" or "auto_apply".
	Tier2Mode string `yaml:"tier2_mode" json:"tier2_mode"`

	// Tier3Mode controls Tier 3 execution: "plan_and_approve" or "auto_apply".
	Tier3Mode string `yaml:"tier3_mode" json:"tier3_mode"`

	// ReconciliationInterval is how often drift detection runs (e.g., "5m").
	ReconciliationInterval string `yaml:"reconciliation_interval" json:"reconciliation_interval"`

	// LockTimeout is the advisory lock TTL (e.g., "10m").
	LockTimeout string `yaml:"lock_timeout" json:"lock_timeout"`
}

type FidelityGap struct {
	// Property is the capability property that has a fidelity gap.
	Property string `json:"property"`

	// Description explains what is missing or different.
	Description string `json:"description"`

	// Workaround describes what the provider does instead, if anything.
	Workaround string `json:"workaround,omitempty"`
}

type FidelityGapError struct {
	// Provider is the provider that has the fidelity gap.
	Provider string

	// Capability is the capability type that is not fully supported.
	Capability string

	// Level is the actual fidelity level the provider offers.
	Level FidelityLevel

	// Details describes what is missing.
	Details string
}

type FidelityLevel string

type FidelityReport struct {
	// Capability is the abstract capability type being reported on.
	Capability string `json:"capability"`

	// Provider is the provider name.
	Provider string `json:"provider"`

	// Fidelity is the overall fidelity level for this capability.
	Fidelity FidelityLevel `json:"fidelity"`

	// Gaps lists the specific properties that are not fully implemented.
	Gaps []FidelityGap `json:"gaps"`
}

type HealthStatus struct {
	// Status is the health state: "healthy", "unhealthy", "degraded", or "unknown".
	Status string `json:"status"`

	// Message is a human-readable description of the health state.
	Message string `json:"message"`

	// Details contains provider-specific health check details.
	Details map[string]any `json:"details,omitempty"`

	// CheckedAt is when the health check was performed.
	CheckedAt time.Time `json:"checkedAt"`
}

type LockConflictError struct {
	// ContextPath is the context path that is locked.
	ContextPath string

	// HeldBy is an identifier for the holder, if known.
	HeldBy string
}

type LockHandle interface {
	// Unlock releases the advisory lock.
	Unlock(ctx context.Context) error

	// Refresh extends the lock TTL to prevent expiration during long operations.
	Refresh(ctx context.Context, ttl time.Duration) error
}

type NotScalableError struct {
	// ResourceType is the resource type that does not support scaling.
	ResourceType string
}

type Plan struct {
	// ID is a unique identifier for this plan.
	ID string `json:"id"`

	// Tier indicates which infrastructure tier this plan operates on.
	Tier Tier `json:"tier"`

	// Context is the hierarchical context path (e.g., "acme/production/api-service").
	Context string `json:"context"`

	// Actions is the ordered list of changes to execute.
	Actions []PlanAction `json:"actions"`

	// CreatedAt is when the plan was generated.
	CreatedAt time.Time `json:"createdAt"`

	// ApprovedAt is when the plan was approved (nil if pending).
	ApprovedAt *time.Time `json:"approvedAt,omitempty"`

	// ApprovedBy is the principal who approved the plan.
	ApprovedBy string `json:"approvedBy,omitempty"`

	// Status is the plan lifecycle state: "pending", "approved", "applying", "applied", "failed".
	Status string `json:"status"`

	// Provider is the name of the provider that generated this plan.
	Provider string `json:"provider"`

	// DryRun indicates whether this plan was generated as a dry-run.
	DryRun bool `json:"dryRun,omitempty"`

	// FidelityReports contains any fidelity gap warnings from the provider.
	FidelityReports []FidelityReport `json:"fidelityReports,omitempty"`
}

type PlanAction struct {
	// Action is the operation type: "create", "update", "delete", or "no-op".
	Action string `json:"action"`

	// ResourceName is the name of the resource being changed.
	ResourceName string `json:"resourceName"`

	// ResourceType is the provider-specific resource type.
	ResourceType string `json:"resourceType"`

	// Provider is the name of the provider executing the action.
	Provider string `json:"provider"`

	// Before is the current state properties (nil for create actions).
	Before map[string]any `json:"before,omitempty"`

	// After is the desired state properties (nil for delete actions).
	After map[string]any `json:"after,omitempty"`

	// Diff contains the individual field differences for update actions.
	Diff []DiffEntry `json:"diff,omitempty"`
}

type PlanConflictError struct {
	// PlanID is the conflicting plan's identifier.
	PlanID string

	// ConflictingResource is the resource that has a conflicting change.
	ConflictingResource string
}

type PlatformConfig struct {
	// Org is the organization identifier (e.g., "acme-corp").
	Org string `yaml:"org" json:"org"`

	// Environment is the target environment name (e.g., "production", "staging").
	Environment string `yaml:"environment" json:"environment"`

	// Provider configures the infrastructure provider to use.
	Provider ProviderConfig `yaml:"provider" json:"provider"`

	// Tiers defines the three-tier capability layout.
	Tiers TiersConfig `yaml:"tiers" json:"tiers"`

	// Execution controls per-tier execution modes and reconciliation settings.
	Execution ExecutionConfig `yaml:"execution" json:"execution"`
}

type PlatformContext struct {
	// Org is the organization identifier.
	Org string `json:"org"`

	// Environment is the deployment environment name (e.g., "production", "staging", "dev").
	Environment string `json:"environment"`

	// Application is the application name. Empty for Tier 1 and Tier 2 contexts.
	Application string `json:"application"`

	// Tier is the infrastructure tier this context operates at.
	Tier Tier `json:"tier"`

	// ParentOutputs are resource outputs inherited from parent tiers, keyed by resource name.
	ParentOutputs map[string]*ResourceOutput `json:"parentOutputs"`

	// Constraints are the accumulated constraints from all parent tiers.
	Constraints []Constraint `json:"constraints"`

	// Credentials holds resolved credential values for this scope.
	// This field is never serialized to prevent credential leakage.
	Credentials map[string]string `json:"-"`

	// Labels are metadata key-value pairs for resource tagging.
	Labels map[string]string `json:"labels"`

	// Annotations are metadata key-value pairs for operational metadata.
	Annotations map[string]string `json:"annotations"`
}

type PlatformRBAC interface {
	// CanAuthor checks if a principal can define workflows at the given tier
	// and context path.
	CanAuthor(ctx context.Context, principal string, tier Tier, contextPath string) (bool, error)

	// CanApprove checks if a principal can approve plans at the given tier
	// and context path.
	CanApprove(ctx context.Context, principal string, tier Tier, contextPath string) (bool, error)

	// CanView checks if a principal can read state at the given tier
	// and context path.
	CanView(ctx context.Context, principal string, tier Tier, contextPath string) (bool, error)

	// EnforceConstraints validates that a set of capability declarations
	// does not exceed the constraints imposed by parent tiers.
	// This is called at plan time before any resources are provisioned.
	EnforceConstraints(pctx *PlatformContext, declarations []CapabilityDeclaration) ([]ConstraintViolation, error)
}

type PropertySchema struct {
	// Name is the property identifier.
	Name string `json:"name"`

	// Type is the property data type: "string", "int", "bool", "duration", "map", "list".
	Type string `json:"type"`

	// Required indicates whether the property must be provided.
	Required bool `json:"required"`

	// Description is a human-readable description of the property.
	Description string `json:"description"`

	// DefaultValue is the value used when the property is not specified.
	DefaultValue any `json:"defaultValue,omitempty"`
}

type Provider interface {
	// Name returns the provider identifier (e.g., "aws", "docker-compose", "gcp").
	Name() string

	// Version returns the provider version string.
	Version() string

	// Initialize prepares the provider by authenticating and validating configuration.
	Initialize(ctx context.Context, config map[string]any) error

	// Capabilities returns the set of capability types this provider supports.
	// Used during plan-time to determine if a provider can satisfy a declaration.
	Capabilities() []CapabilityType

	// MapCapability resolves an abstract capability declaration to a provider-specific
	// resource plan. Returns an error if the capability cannot be satisfied.
	MapCapability(ctx context.Context, decl CapabilityDeclaration, pctx *PlatformContext) ([]ResourcePlan, error)

	// ResourceDriver returns the driver for a specific provider resource type.
	// Returns ErrResourceDriverNotFound if the resource type is not supported.
	ResourceDriver(resourceType string) (ResourceDriver, error)

	// CredentialBroker returns the provider's credential management interface.
	// Returns nil if the provider does not support credential brokering.
	CredentialBroker() CredentialBroker

	// StateStore returns the provider's state persistence interface.
	StateStore() StateStore

	// Healthy returns nil if the provider is reachable and authenticated.
	Healthy(ctx context.Context) error

	// Close releases any resources held by the provider.
	Close() error
}

type ProviderConfig struct {
	// Name is the provider identifier (e.g., "aws", "docker-compose", "gcp").
	Name string `yaml:"name" json:"name"`

	// Config holds provider-specific configuration key-value pairs.
	Config map[string]any `yaml:"config,omitempty" json:"config,omitempty"`
}

type ProviderFactory func() Provider

type ReconcileResult struct {
	// ContextPath is the context that was reconciled.
	ContextPath string `json:"contextPath"`

	// DriftResults contains all detected drifts.
	DriftResults []DriftResult `json:"driftResults"`

	// CrossTierImpacts describes downstream impacts of detected drifts.
	CrossTierImpacts []CrossTierImpact `json:"crossTierImpacts,omitempty"`

	// CheckedAt is when the reconciliation was performed.
	CheckedAt time.Time `json:"checkedAt"`

	// Duration is how long the reconciliation took.
	Duration time.Duration `json:"duration"`

	// ResourcesChecked is the number of resources that were checked.
	ResourcesChecked int `json:"resourcesChecked"`
}

type Reconciler struct {
	// contains filtered or unexported fields
}

type ReconcilerDriftReport struct {
	ID           int64          `json:"id"`
	ContextPath  string         `json:"contextPath"`
	ResourceName string         `json:"resourceName"`
	ResourceType string         `json:"resourceType"`
	Tier         Tier           `json:"tier"`
	DriftType    string         `json:"driftType"`
	Expected     map[string]any `json:"expected"`
	Actual       map[string]any `json:"actual"`
	Diffs        []DiffEntry    `json:"diffs"`
	DetectedAt   time.Time      `json:"detectedAt"`
	ResolvedAt   *time.Time     `json:"resolvedAt,omitempty"`
	ResolvedBy   string         `json:"resolvedBy,omitempty"`
}

type ReconcilerStateStore interface {
	StateStore
	SaveDriftReport(ctx context.Context, report *ReconcilerDriftReport) error
}

type ResourceDriver interface {
	// ResourceType returns the fully qualified resource type (e.g., "aws.eks_cluster").
	ResourceType() string

	// Create provisions a new resource with the given properties.
	// Returns the resource output when provisioning is complete.
	Create(ctx context.Context, name string, properties map[string]any) (*ResourceOutput, error)

	// Read fetches the current state of an existing resource from the provider.
	Read(ctx context.Context, name string) (*ResourceOutput, error)

	// Update modifies an existing resource to match the desired properties.
	// Both current and desired property maps are provided for diffing.
	Update(ctx context.Context, name string, current, desired map[string]any) (*ResourceOutput, error)

	// Delete removes a resource from the provider.
	Delete(ctx context.Context, name string) error

	// HealthCheck returns the health status of a managed resource.
	HealthCheck(ctx context.Context, name string) (*HealthStatus, error)

	// Scale adjusts resource scaling parameters if the resource type supports it.
	// Returns ErrNotScalable if the resource type does not support scaling.
	Scale(ctx context.Context, name string, scaleParams map[string]any) (*ResourceOutput, error)

	// Diff compares the desired properties with the actual provider state and
	// returns the list of field differences.
	Diff(ctx context.Context, name string, desired map[string]any) ([]DiffEntry, error)
}

type ResourceDriverNotFoundError struct {
	// ResourceType is the resource type that has no driver.
	ResourceType string

	// Provider is the provider that was queried.
	Provider string
}

type ResourceNotFoundError struct {
	// Name is the resource name that was not found.
	Name string

	// Provider is the provider where the resource was expected.
	Provider string
}

type ResourceOutput struct {
	// Name is the resource identifier matching the CapabilityDeclaration name.
	Name string `json:"name"`

	// Type is the abstract capability type.
	Type string `json:"type"`

	// ProviderType is the provider-specific resource type (e.g., "aws.eks_cluster").
	ProviderType string `json:"providerType"`

	// Endpoint is the primary access endpoint for the resource, if applicable.
	Endpoint string `json:"endpoint,omitempty"`

	// ConnectionStr is a connection string for database or messaging resources.
	ConnectionStr string `json:"connectionString,omitempty"`

	// CredentialRef is a reference to a credential in the credential broker.
	CredentialRef string `json:"credentialRef,omitempty"`

	// Properties are provider-specific output properties.
	Properties map[string]any `json:"properties"`

	// Status is the current lifecycle state of the resource.
	Status ResourceStatus `json:"status"`

	// LastSynced is the last time the resource state was read from the provider.
	LastSynced time.Time `json:"lastSynced"`
}

type ResourcePlan struct {
	// ResourceType is the provider-specific resource type (e.g., "aws.eks_nodegroup").
	ResourceType string `json:"resourceType"`

	// Name is the resource instance name.
	Name string `json:"name"`

	// Properties are the provider-specific properties for the resource.
	Properties map[string]any `json:"properties"`

	// DependsOn lists other resource names that must be created first.
	DependsOn []string `json:"dependsOn"`
}

type ResourceStatus string

type StateStore interface {
	// SaveResource persists the state of a resource within a context path.
	SaveResource(ctx context.Context, contextPath string, output *ResourceOutput) error

	// GetResource retrieves a resource's state by context path and resource name.
	GetResource(ctx context.Context, contextPath, resourceName string) (*ResourceOutput, error)

	// ListResources returns all resources in a context path.
	ListResources(ctx context.Context, contextPath string) ([]*ResourceOutput, error)

	// DeleteResource removes a resource from state.
	DeleteResource(ctx context.Context, contextPath, resourceName string) error

	// SavePlan persists an execution plan.
	SavePlan(ctx context.Context, plan *Plan) error

	// GetPlan retrieves an execution plan by its ID.
	GetPlan(ctx context.Context, planID string) (*Plan, error)

	// ListPlans lists plans for a context path, ordered by creation time descending.
	// The limit parameter controls the maximum number of plans returned.
	ListPlans(ctx context.Context, contextPath string, limit int) ([]*Plan, error)

	// Lock acquires an advisory lock for a context path to prevent concurrent
	// modifications to the same infrastructure. The TTL controls the maximum
	// lock duration.
	Lock(ctx context.Context, contextPath string, ttl time.Duration) (LockHandle, error)

	// Dependencies returns dependency references for resources that depend on
	// the given resource.
	Dependencies(ctx context.Context, contextPath, resourceName string) ([]DependencyRef, error)

	// AddDependency records a cross-resource or cross-tier dependency.
	AddDependency(ctx context.Context, dep DependencyRef) error
}

type StdContextResolver struct {
	// contains filtered or unexported fields
}

type StdTemplateRegistry struct {
	// contains filtered or unexported fields
}

type StdTierAuthorizer struct {
	// contains filtered or unexported fields
}

type TemplateOutput struct {
	// Name is the output identifier.
	Name string `yaml:"name" json:"name"`

	// Value is an expression referencing a resource output (e.g., "service-name.endpoint").
	Value string `yaml:"value" json:"value"`
}

type TemplateParameter struct {
	// Name is the parameter identifier used in placeholder expressions.
	Name string `yaml:"name" json:"name"`

	// Type is the parameter data type: "string", "int", "bool", "list", "map".
	Type string `yaml:"type" json:"type"`

	// Required indicates whether the parameter must be provided during resolution.
	Required bool `yaml:"required" json:"required"`

	// Default is the value used when the parameter is not provided.
	Default any `yaml:"default,omitempty" json:"default,omitempty"`

	// Description is a human-readable description of the parameter.
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	// Validation is a regex pattern or constraint expression for validating the value.
	Validation string `yaml:"validation,omitempty" json:"validation,omitempty"`
}

type TemplateRegistry interface {
	// Register adds or updates a template in the registry.
	Register(ctx context.Context, template *WorkflowTemplate) error

	// Get retrieves a specific template by name and version.
	Get(ctx context.Context, name, version string) (*WorkflowTemplate, error)

	// GetLatest retrieves the latest version of a template by name.
	GetLatest(ctx context.Context, name string) (*WorkflowTemplate, error)

	// List returns summaries of all available templates.
	List(ctx context.Context) ([]*WorkflowTemplateSummary, error)

	// Resolve instantiates a template with the given parameters, producing
	// a set of concrete capability declarations.
	Resolve(ctx context.Context, name, version string, params map[string]any) ([]CapabilityDeclaration, error)
}

type TemplateResolver struct{}

type Tier int

type TierAuthorizer interface {
	// Authorize checks whether the given role may perform operation on tier.
	// Returns nil if authorized, or a TierBoundaryError if not.
	Authorize(ctx context.Context, role TierRole, tier Tier, operation string) error

	// RegisterPolicy adds or replaces a policy for the given role.
	RegisterPolicy(policy AuthzPolicy)
}

type TierBoundaryError struct {
	// SourceTier is the tier the operation originated from.
	SourceTier Tier

	// TargetTier is the tier the operation attempted to reach.
	TargetTier Tier

	// Operation is the operation that was attempted.
	Operation string

	// Reason explains why the operation is not allowed.
	Reason string
}

type TierConfig struct {
	// Capabilities lists the abstract resources declared in this tier.
	Capabilities []CapabilityConfig `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`

	// ConstraintsForDownstream are hard limits imposed on lower tiers.
	ConstraintsForDownstream []ConstraintConfig `yaml:"constraints_for_downstream,omitempty" json:"constraints_for_downstream,omitempty"`
}

type TierRole string

type TiersConfig struct {
	// Infrastructure is Tier 1: compute, networking, IAM.
	Infrastructure TierConfig `yaml:"infrastructure" json:"infrastructure"`

	// SharedPrimitives is Tier 2: namespaces, queues, shared databases.
	SharedPrimitives TierConfig `yaml:"shared_primitives" json:"shared_primitives"`

	// Application is Tier 3: app deployments, scaling policies.
	Application TierConfig `yaml:"application" json:"application"`
}

type WorkflowTemplate struct {
	// Name is the template identifier.
	Name string `yaml:"name" json:"name"`

	// Version is the template version following semantic versioning.
	Version string `yaml:"version" json:"version"`

	// Description is a human-readable description of what the template provides.
	Description string `yaml:"description" json:"description"`

	// Parameters are the configurable inputs for this template.
	Parameters []TemplateParameter `yaml:"parameters" json:"parameters"`

	// Capabilities are the capability declarations with parameter placeholders.
	Capabilities []CapabilityDeclaration `yaml:"capabilities" json:"capabilities"`

	// Outputs are the declared outputs of this template, referencing resource outputs.
	Outputs []TemplateOutput `yaml:"outputs" json:"outputs"`

	// Tier is the infrastructure tier this template targets.
	Tier Tier `yaml:"tier" json:"tier"`
}

type WorkflowTemplateSummary struct {
	// Name is the template identifier.
	Name string `json:"name"`

	// Version is the template version.
	Version string `json:"version"`

	// Description is a human-readable description.
	Description string `json:"description"`

	// Parameters lists the parameter names accepted by this template.
	Parameters []string `json:"parameters"`
}