interfaces

type ActionError struct {
	Resource string `json:"resource"`
	Action   string `json:"action"`
	Error    string `json:"error"`
}

type ActionOutcome struct {
	ActionIndex uint32       `json:"action_index"`
	Status      ActionStatus `json:"status"`
	Error       string       `json:"error,omitempty"`
}

type ActionStatus uint8

type AlertSpec struct {
	Rule     string  `json:"rule" yaml:"rule"`
	Operator string  `json:"operator" yaml:"operator"` // GREATER_THAN | LESS_THAN
	Value    float64 `json:"value" yaml:"value"`
	Window   string  `json:"window" yaml:"window"` // e.g. "10m"
	Disabled bool    `json:"disabled" yaml:"disabled"`
}

type ApplyResult struct {
	PlanID    string           `json:"plan_id"`
	Resources []ResourceOutput `json:"resources"`
	Errors    []ActionError    `json:"errors,omitempty"`

	// InitialInputSnapshot captures env-var fingerprints at the start of apply.
	// Populated by wfctlhelpers.ApplyPlan (T3.1) at apply entry by snapshotting
	// every name listed in plan.InputSnapshot through inputsnapshot.OSEnvProvider.
	// Used by the deferred postcondition (T3.1.5) to compute the drift report
	// against the apply-time snapshot.
	InitialInputSnapshot map[string]string `json:"initial_input_snapshot,omitempty"`

	// InputDriftReport names env-vars whose fingerprint changed between plan
	// and apply. Populated by the deferred postcondition in
	// wfctlhelpers.ApplyPlan (T3.1.5) regardless of whether the apply
	// itself succeeded or errored. Empty (or nil) means no drift detected.
	// Entries are sorted by Name for deterministic comparison and stable
	// diagnostic output; the sort guarantee is enforced by
	// inputsnapshot.ComputeDrift (covered by
	// TestComputeDrift_ResultIsSortedByName in
	// iac/inputsnapshot/compute_drift_test.go).
	InputDriftReport []DriftEntry `json:"input_drift_report,omitempty"`

	// ReplaceIDMap propagates new ProviderIDs from Replace actions to
	// dependent resources whose Apply runs later in the same plan.
	// Populated by doReplace (T3.4); consumed by JIT substitution in W-5
	// (T5.2/T5.3).
	//
	// Keyed by the *replaced* resource's Name (i.e., action.Resource.Name
	// from the Replace PlanAction — the resource whose Delete-then-Create
	// just produced a fresh ProviderID). The value is the new ProviderID
	// returned from the post-Delete Create. Dependent resources reference
	// the replaced resource by name in their config, so JIT substitution
	// in W-5 translates "name → new ProviderID" via this map.
	ReplaceIDMap map[string]string `json:"replace_id_map,omitempty"`

	// Actions surfaces per-PlanAction outcomes for v2 hook dispatch in
	// wfctl. Always populated (one entry per IaCPlan.Actions index) when
	// an IaC plugin declares ComputePlanVersion="v2" in
	// CapabilitiesResponse. Per ADR 0024 + ADR 0040, plugins NOT
	// declaring v2 are permanently incompatible with workflow v0.54.0+;
	// there is no compat shim. Per workflow#640 Phase 2 + ADR 0040
	// invariants 1-2.
	Actions []ActionOutcome `json:"actions,omitempty"`
}

type ArtifactEntry struct {
	Path string `json:"path"`
	URL  string `json:"url"`
}

type AutoscalingSpec struct {
	Min           int `json:"min" yaml:"min"`
	Max           int `json:"max" yaml:"max"`
	CPUPercent    int `json:"cpu_percent" yaml:"cpu_percent"`
	MemoryPercent int `json:"memory_percent" yaml:"memory_percent"`
}

type BootstrapResult struct {
	// Bucket is the name of the created or confirmed state bucket/container.
	Bucket string `json:"bucket,omitempty"`
	// Region is the region where the bucket resides.
	Region string `json:"region,omitempty"`
	// Endpoint is the S3-compatible API endpoint URL (if applicable).
	Endpoint string `json:"endpoint,omitempty"`
	// EnvVars is a map of environment variable names to values that should be
	// exported for CI capture (e.g. WFCTL_STATE_BUCKET, SPACES_BUCKET).
	EnvVars map[string]string `json:"env_vars,omitempty"`
}

type CORSSpec struct {
	AllowOrigins     []string `json:"allow_origins,omitempty" yaml:"allow_origins,omitempty"`
	AllowMethods     []string `json:"allow_methods,omitempty" yaml:"allow_methods,omitempty"`
	AllowHeaders     []string `json:"allow_headers,omitempty" yaml:"allow_headers,omitempty"`
	ExposeHeaders    []string `json:"expose_headers,omitempty" yaml:"expose_headers,omitempty"`
	AllowCredentials bool     `json:"allow_credentials" yaml:"allow_credentials"`
	MaxAge           string   `json:"max_age,omitempty" yaml:"max_age,omitempty"`
}

type DestroyResult struct {
	Destroyed []string      `json:"destroyed"`
	Errors    []ActionError `json:"errors,omitempty"`
}

type Diagnostic struct {
	ID     string    `json:"id"`               // provider-side identifier (e.g. deployment ID)
	Phase  string    `json:"phase"`            // terminal or current phase
	Cause  string    `json:"cause"`            // human-readable root cause or error summary
	At     time.Time `json:"at"`               // when the event was created or last updated
	Detail string    `json:"detail,omitempty"` // optional verbose tail (log excerpt, stack)
}

type DiffResult struct {
	NeedsUpdate  bool          `json:"needs_update"`
	NeedsReplace bool          `json:"needs_replace"`
	Changes      []FieldChange `json:"changes"`
}

type DomainSpec struct {
	Name     string `json:"name" yaml:"name"`
	Zone     string `json:"zone,omitempty" yaml:"zone,omitempty"`
	Type     string `json:"type" yaml:"type"` // PRIMARY | ALIAS
	Wildcard bool   `json:"wildcard" yaml:"wildcard"`
}

type DriftClass string

type DriftConfigDetector interface {
	DetectDriftWithSpecs(ctx context.Context, resources []ResourceRef, specs map[string]ResourceSpec) ([]DriftResult, error)
}

type DriftEntry struct {
	Name             string `json:"name"`
	PlanFingerprint  string `json:"plan_fingerprint"`
	ApplyFingerprint string `json:"apply_fingerprint"`
}

type DriftResult struct {
	Name     string         `json:"name"`
	Type     string         `json:"type"`
	Drifted  bool           `json:"drifted"`
	Class    DriftClass     `json:"class,omitempty"` // additive; omitted when Unknown
	Expected map[string]any `json:"expected,omitempty"`
	Actual   map[string]any `json:"actual,omitempty"`
	Fields   []string       `json:"fields,omitempty"` // which fields drifted
}

type EgressRule struct {
	Destination string `json:"destination" yaml:"destination"`
	Protocol    string `json:"protocol" yaml:"protocol"`
	Allow       bool   `json:"allow" yaml:"allow"`
}

type EgressSpec struct {
	Bandwidth string       `json:"bandwidth,omitempty" yaml:"bandwidth,omitempty"` // informational budget, e.g. "1Gbps"
	Rules     []EgressRule `json:"rules,omitempty" yaml:"rules,omitempty"`
}

type Enumerator interface {
	EnumerateByTag(ctx context.Context, tag string) ([]ResourceRef, error)
}

type EnumeratorAll interface {
	EnumerateAll(ctx context.Context, resourceType string) ([]*ResourceOutput, error)
}

type EventEmitter interface {
	EmitWorkflowStarted(ctx context.Context, workflowType, action string, data map[string]any)
	EmitWorkflowCompleted(ctx context.Context, workflowType, action string, duration time.Duration, results map[string]any)
	EmitWorkflowFailed(ctx context.Context, workflowType, action string, duration time.Duration, err error)
}

type EventRecorder interface {
	RecordEvent(ctx context.Context, executionID string, eventType string, data map[string]any) error
}

type FieldChange struct {
	Path     string `json:"path"`
	Old      any    `json:"old"`
	New      any    `json:"new"`
	ForceNew bool   `json:"force_new"` // change requires resource replacement
}

type GeneratorMetadata struct {
	WfctlVersion string              `json:"wfctl_version"`
	Plugins      []PluginVersionInfo `json:"plugins,omitempty"`
}

type HealthCheckSpec struct {
	HTTPPath            string `json:"http_path,omitempty" yaml:"http_path,omitempty"`
	TCPPort             int    `json:"tcp_port,omitempty" yaml:"tcp_port,omitempty"`
	Port                int    `json:"port,omitempty" yaml:"port,omitempty"`
	InitialDelaySeconds int    `json:"initial_delay_seconds" yaml:"initial_delay_seconds"`
	PeriodSeconds       int    `json:"period_seconds" yaml:"period_seconds"`
	TimeoutSeconds      int    `json:"timeout_seconds" yaml:"timeout_seconds"`
	SuccessThreshold    int    `json:"success_threshold" yaml:"success_threshold"`
	FailureThreshold    int    `json:"failure_threshold" yaml:"failure_threshold"`
}

type HealthResult struct {
	Healthy bool   `json:"healthy"`
	Message string `json:"message,omitempty"`
}

type HookEvent string

type HookPayload struct {
	Event     HookEvent      `json:"event"`
	Plugin    string         `json:"plugin"`
	BuildID   string         `json:"build_id"`
	Timestamp int64          `json:"timestamp"`
	Data      map[string]any `json:"data,omitempty"`
}

type IaCCapabilityDeclaration struct {
	ResourceType string   `json:"resource_type"` // infra.database, infra.vpc, etc.
	Tier         int      `json:"tier"`          // 1=infra, 2=shared, 3=app
	Operations   []string `json:"operations"`    // create, read, update, delete, scale
}

type IaCLockHandle interface {
	Unlock(ctx context.Context) error
}

type IaCPlan struct {
	ID        string       `json:"id"`
	Actions   []PlanAction `json:"actions"`
	CreatedAt time.Time    `json:"created_at"`
	// DesiredHash is a SHA-256 hex digest of the canonical desired-state inputs
	// (sorted ResourceSpecs) at the time the plan was generated. wfctl infra apply
	// --plan compares this against the current config to detect stale plans.
	DesiredHash string `json:"plan_hash,omitempty"`

	// Include records the sorted resource names passed through
	// `wfctl infra plan --include`. Empty means the plan covered the full
	// desired set. wfctl infra apply --plan uses this to recompute DesiredHash
	// against the same scope without requiring --include at apply time.
	Include []string `json:"include,omitempty"`

	// SchemaVersion is bumped when on-disk plan format changes (W-5 sets to 2 when JIT is required).
	SchemaVersion int `json:"schema_version,omitempty"`

	// InputSnapshot records env var names read during ${VAR} substitution at
	// plan time, fingerprinting only those that were SET (16-hex-char sha256
	// prefix of the value). Unset vars are omitted from the map; their absence
	// at apply time is therefore not flagged as drift. Apply re-computes inputs
	// and prints diagnostic on mismatch.
	//
	// Completeness caveat: the cmd/wfctl scanner that populates this map
	// (cmd/wfctl/infra_inputsnapshot.go::collectInfraEnvVarRefs) currently
	// walks each module's own Config but does not apply top-level
	// environments[env].envVars defaults. Vars that originate solely from a
	// top-level envVars default may therefore be absent from the snapshot;
	// closing this gap is tracked as a follow-up to W-1.
	InputSnapshot map[string]string `json:"input_snapshot,omitempty"`

	// GeneratorMetadata records the wfctl version and installed IaC plugin
	// versions present when this plan was produced. Populated when the plan
	// is serialised to disk (wfctl infra plan -o). Consumers can inspect
	// this to assess whether upgrades are needed before re-applying a stored
	// plan.
	GeneratorMetadata *GeneratorMetadata `json:"generator_metadata,omitempty"`
}

type IaCProvider interface {
	Name() string
	Version() string
	Initialize(ctx context.Context, config map[string]any) error

	// Capabilities returns what resource types this provider supports.
	Capabilities() []IaCCapabilityDeclaration

	// Lifecycle
	Plan(ctx context.Context, desired []ResourceSpec, current []ResourceState) (*IaCPlan, error)
	// Apply was removed per workflow#699 (2026-05-17). v2 dispatch
	// routes through wfctlhelpers.ApplyPlanWithHooks (ResourceDriver
	// per-action + IaCProviderFinalizer.FinalizeApply post-loop). The
	// load-time Capabilities-RPC gate in cmd/wfctl/deploy_providers.go
	// rejects plugins whose CapabilitiesResponse.compute_plan_version
	// is not "v2".
	Destroy(ctx context.Context, resources []ResourceRef) (*DestroyResult, error)

	// Observability
	Status(ctx context.Context, resources []ResourceRef) ([]ResourceStatus, error)
	DetectDrift(ctx context.Context, resources []ResourceRef) ([]DriftResult, error)

	// Migration
	Import(ctx context.Context, cloudID string, resourceType string) (*ResourceState, error)

	// Sizing
	ResolveSizing(resourceType string, size Size, hints *ResourceHints) (*ProviderSizing, error)

	// Resource drivers for fine-grained CRUD
	ResourceDriver(resourceType string) (ResourceDriver, error)

	// SupportedCanonicalKeys returns the subset of canonical IaC config keys
	// that this provider understands. Providers may return a subset; callers
	// use this to warn on unrecognised fields before applying a plan.
	// Built-in and stub providers return the full canonical key set.
	SupportedCanonicalKeys() []string

	// BootstrapStateBackend ensures the state backend resource (bucket/container)
	// exists on this provider. It is idempotent: if the resource already exists,
	// it returns the current metadata without error. cfg is the expanded
	// iac.state module config (backend, bucket, region, credentials, etc.).
	//
	// Providers that do not manage a state backend should return (nil, nil).
	// The caller prints each entry in result.EnvVars as `export KEY=VALUE` for
	// CI capture and writes result.Bucket back to the on-disk config.
	BootstrapStateBackend(ctx context.Context, cfg map[string]any) (*BootstrapResult, error)

	Close() error
}

type IaCStateStore interface {
	SaveResource(ctx context.Context, state ResourceState) error
	GetResource(ctx context.Context, name string) (*ResourceState, error)
	ListResources(ctx context.Context) ([]ResourceState, error)
	DeleteResource(ctx context.Context, name string) error

	SavePlan(ctx context.Context, plan IaCPlan) error
	GetPlan(ctx context.Context, id string) (*IaCPlan, error)

	Lock(ctx context.Context, resource string, ttl time.Duration) (IaCLockHandle, error)

	Close() error
}

type IngressRule struct {
	Match     string `json:"match" yaml:"match"`         // path prefix or header expression
	Component string `json:"component" yaml:"component"` // target service/worker name
}

type IngressSpec struct {
	LoadBalancer string        `json:"load_balancer,omitempty" yaml:"load_balancer,omitempty"` // e.g. round_robin | least_connections
	Rules        []IngressRule `json:"rules,omitempty" yaml:"rules,omitempty"`
}

type InstallVerifyPayload struct {
	TarballPath               string `json:"tarball_path"`
	ExpectedSignatureIdentity string `json:"expected_signature_identity,omitempty"`
	ExpectedSBOMHash          string `json:"expected_sbom_hash,omitempty"`
	VulnPolicy                string `json:"vuln_policy,omitempty"` // block-critical | warn | off
}

type JobSpec struct {
	Name            string               `json:"name" yaml:"name"`
	Kind            string               `json:"kind" yaml:"kind"`
	Image           string               `json:"image,omitempty" yaml:"image,omitempty"`
	RunCommand      string               `json:"run_command" yaml:"run_command"`
	EnvVars         map[string]string    `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
	EnvVarsSecret   map[string]string    `json:"env_vars_secret,omitempty" yaml:"env_vars_secret,omitempty"`
	Cron            string               `json:"cron,omitempty" yaml:"cron,omitempty"` // non-empty for SCHEDULED kind
	Termination     *TerminationSpec     `json:"termination,omitempty" yaml:"termination,omitempty"`
	Alerts          []AlertSpec          `json:"alerts,omitempty" yaml:"alerts,omitempty"`
	LogDestinations []LogDestinationSpec `json:"log_destinations,omitempty" yaml:"log_destinations,omitempty"`
}

type LogDestinationSpec struct {
	Name     string            `json:"name" yaml:"name"`
	Endpoint string            `json:"endpoint" yaml:"endpoint"`
	Headers  map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
	TLS      bool              `json:"tls" yaml:"tls"`
}

type MaintenanceSpec struct {
	Window  string `json:"window" yaml:"window"` // e.g. "Sun 03:00-05:00 UTC"
	Enabled bool   `json:"enabled" yaml:"enabled"`
}

type MetricsRecorder interface {
	RecordWorkflowExecution(workflowType, action, status string)
	RecordWorkflowDuration(workflowType, action string, duration time.Duration)
}

type MigrationDriver interface {
	Name() string
	Up(ctx context.Context, req MigrationRequest) (MigrationResult, error)
	Down(ctx context.Context, req MigrationRequest) (MigrationResult, error)
	Status(ctx context.Context, req MigrationRequest) (MigrationStatus, error)
	Goto(ctx context.Context, req MigrationRequest, target string) (MigrationResult, error)
}

type MigrationOptions struct {
	Steps   int
	DryRun  bool
	Timeout time.Duration
	Version string
}

type MigrationProvider interface {
	// ProvidesMigrations returns an fs.FS rooted at the migrations directory.
	// The FS must contain SQL files named in the golang-migrate convention:
	// <version>_<description>.up.sql and <version>_<description>.down.sql.
	ProvidesMigrations() (fs.FS, error)

	// MigrationsDependencies returns the names of other MigrationProvider
	// modules whose migrations must be applied before this module's.
	// For example, the authz module might return ["workflow.tenants"].
	// Returning nil or an empty slice means no dependencies.
	MigrationsDependencies() []string
}

type MigrationRepairRequest struct {
	AppResourceName      string            `json:"app_resource_name"`
	DatabaseResourceName string            `json:"database_resource_name"`
	JobImage             string            `json:"job_image"`
	SourceDir            string            `json:"source_dir"`
	ExpectedDirtyVersion string            `json:"expected_dirty_version"`
	ForceVersion         string            `json:"force_version"`
	ThenUp               bool              `json:"then_up"`
	UpIfClean            bool              `json:"up_if_clean"`
	ConfirmForce         string            `json:"confirm_force"`
	Env                  map[string]string `json:"env,omitempty"`
	TimeoutSeconds       int               `json:"timeout_seconds,omitempty"`
}

type MigrationRepairResult struct {
	ProviderJobID string       `json:"provider_job_id,omitempty"`
	Status        string       `json:"status"`
	Applied       []string     `json:"applied,omitempty"`
	Logs          string       `json:"logs,omitempty"`
	Diagnostics   []Diagnostic `json:"diagnostics,omitempty"`
}

type MigrationRequest struct {
	DSN     string
	Source  MigrationSource
	Options MigrationOptions
}

type MigrationResult struct {
	Applied    []string
	Skipped    []string
	DurationMs int64
}

type MigrationSource struct {
	Dir        string
	Files      []string
	SchemaName string
}

type MigrationStatus struct {
	Current string
	Pending []string
	Dirty   bool
}

type PipelineContext struct {
	// TriggerData is the original data from the trigger (immutable after creation).
	TriggerData map[string]any

	// StepOutputs maps step-name -> output from each completed step.
	StepOutputs map[string]map[string]any

	// Current is the merged state: trigger data + all step outputs.
	// Steps read from Current and their output is merged back into it.
	Current map[string]any

	// Metadata holds execution metadata (pipeline name, trace ID, etc.)
	Metadata map[string]any

	// StrictTemplates causes template execution to return an error instead of
	// the zero value when a template expression references a missing map key.
	// When false (the default), missing keys resolve to the zero value with a
	// warning logged via Logger. Enable via pipeline config: strict_templates: true.
	StrictTemplates bool

	// Logger is used to emit warnings when a template expression resolves a
	// missing key to the zero value (non-strict mode). When nil, slog.Default()
	// is used.
	Logger *slog.Logger
}

type PipelineExecutor interface {
	// ExecutePipeline runs a named pipeline synchronously and returns its
	// structured output. Returns _pipeline_output if set by
	// step.pipeline_output, otherwise the pipeline's merged Current state.
	ExecutePipeline(ctx context.Context, name string, data map[string]any) (map[string]any, error)
}

type PipelineRunner interface {
	// Run executes the pipeline with the given trigger data and returns the
	// merged result map (equivalent to PipelineContext.Current).
	Run(ctx context.Context, data map[string]any) (map[string]any, error)

	// SetLogger sets the logger used for pipeline execution.
	// Implementations should be idempotent: if a logger is already set,
	// a subsequent call should be a no-op.
	SetLogger(logger *slog.Logger)

	// SetEventRecorder sets the recorder used for pipeline execution events.
	// Implementations should be idempotent: if a recorder is already set,
	// a subsequent call should be a no-op.
	SetEventRecorder(recorder EventRecorder)
}

type PipelineStep interface {
	// Name returns the step's unique name within the pipeline.
	Name() string

	// Execute runs the step with the pipeline context.
	Execute(ctx context.Context, pc *PipelineContext) (*StepResult, error)
}

type PlanAction struct {
	Action   string         `json:"action"` // create, update, replace, delete
	Resource ResourceSpec   `json:"resource"`
	Current  *ResourceState `json:"current,omitempty"`
	Changes  []FieldChange  `json:"changes,omitempty"`

	// ResolvedConfigHash is the SHA-256 of POST-substitution Resource.Config,
	// computed via platform.ConfigHash. Encoded as lower-case hex (no
	// "sha256:" prefix); empty string when the config map is empty
	// (platform.ConfigHash short-circuit). The field uses `omitempty`, so the
	// empty-string case is ABSENT from plan.json — consumers should treat
	// "key missing" and "value == empty string" as the same condition.
	//
	// Currently populated by ComputePlan and persisted in plan.json so apply
	// has the per-action hash available; the apply-time consumer that surfaces
	// a per-resource diagnostic on mismatch is wired in a follow-up PR (W-3a/
	// T3.1.5). Until then the field is observable via plan.json inspection but
	// not yet enforced at apply.
	ResolvedConfigHash string `json:"resolved_config_hash,omitempty"`
}

type PlanDiagnostic struct {
	// Severity is Error|Warning|Info; see PlanDiagnosticSeverity.
	Severity PlanDiagnosticSeverity `json:"severity"`
	// Resource is the offending resource name; empty for plan-level findings.
	Resource string `json:"resource,omitempty"`
	// Field is a dotted/bracketed field path within Resource (e.g. "vpc_ref"
	// or "tags[0].key"); empty for resource-level findings.
	Field string `json:"field,omitempty"`
	// Message is a human-readable description of the finding.
	Message string `json:"message"`
}

type PlanDiagnosticSeverity int

type PluginVersionInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

type PortSpec struct {
	Name     string `json:"name" yaml:"name"`
	Port     int    `json:"port" yaml:"port"`
	Protocol string `json:"protocol" yaml:"protocol"` // http | tcp | udp
	Public   bool   `json:"public" yaml:"public"`
}

type PostArtifactsPublishPayload struct {
	Assets     []ArtifactEntry `json:"assets"`
	DurationMs int64           `json:"duration_ms"`
}

type PostBuildPayload struct {
	Targets    []string `json:"targets"`
	Success    bool     `json:"success"`
	DurationMs int64    `json:"duration_ms"`
}

type PostContainerBuildPayload struct {
	Target     string `json:"target"`
	ImageRef   string `json:"image_ref"`
	Digest     string `json:"digest"`
	DurationMs int64  `json:"duration_ms"`
}

type PostContainerPushPayload struct {
	ImageRef   string   `json:"image_ref"`
	Digest     string   `json:"digest"`
	Registries []string `json:"registries"`
	DurationMs int64    `json:"duration_ms"`
}

type PostTargetBuildPayload struct {
	Target     string   `json:"target"`
	Type       string   `json:"type"`
	Outputs    []string `json:"outputs,omitempty"`
	DurationMs int64    `json:"duration_ms"`
}

type PreArtifactsPublishPayload struct {
	Assets []string `json:"assets"`
}

type PreBuildFailPayload struct {
	Error  string `json:"error"`
	Target string `json:"target,omitempty"`
}

type PreBuildPayload struct {
	ConfigPath string   `json:"config_path"`
	Targets    []string `json:"targets"`
}

type PreContainerBuildPayload struct {
	Target         string   `json:"target"`
	DockerfilePath string   `json:"dockerfile_path"`
	ContextPath    string   `json:"context_path"`
	Tags           []string `json:"tags"`
}

type PreContainerPushPayload struct {
	ImageRef   string   `json:"image_ref"`
	Registries []string `json:"registries"`
}

type PreTargetBuildPayload struct {
	Target string `json:"target"`
	Type   string `json:"type"`
}

type ProviderCredentialRevoker interface {
	RevokeProviderCredential(ctx context.Context, source string, credentialID string) error
}

type ProviderIDFormat int

type ProviderIDValidator interface {
	ProviderIDFormat() ProviderIDFormat
}

type ProviderMigrationRepairer interface {
	RepairDirtyMigration(ctx context.Context, req MigrationRepairRequest) (*MigrationRepairResult, error)
}

type ProviderPlanner interface {
	PlanV2(ctx context.Context, desired []ResourceSpec, current []ResourceState) (IaCPlan, error)
}

type ProviderSizing struct {
	InstanceType string         `json:"instance_type"`
	Specs        map[string]any `json:"specs"`
}

type ProviderValidator interface {
	ValidatePlan(plan *IaCPlan) []PlanDiagnostic
}

type Reconfigurable interface {
	// Reconfigure applies new configuration to a running module.
	// The module should:
	//   1. Validate the new config
	//   2. Gracefully drain in-flight work
	//   3. Apply the new configuration
	//   4. Resume accepting new work
	// Returns an error if the new config is invalid or cannot be applied.
	Reconfigure(ctx context.Context, newConfig map[string]any) error
}

type ResourceAdoptionLocator interface {
	AdoptionRef(spec ResourceSpec) (ResourceRef, bool, error)
}

type ResourceDriver interface {
	Create(ctx context.Context, spec ResourceSpec) (*ResourceOutput, error)
	Read(ctx context.Context, ref ResourceRef) (*ResourceOutput, error)
	Update(ctx context.Context, ref ResourceRef, spec ResourceSpec) (*ResourceOutput, error)
	Delete(ctx context.Context, ref ResourceRef) error
	Diff(ctx context.Context, desired ResourceSpec, current *ResourceOutput) (*DiffResult, error)
	HealthCheck(ctx context.Context, ref ResourceRef) (*HealthResult, error)
	Scale(ctx context.Context, ref ResourceRef, replicas int) (*ResourceOutput, error)
	// SensitiveKeys returns output keys whose values should be masked in logs and plan output.
	SensitiveKeys() []string
}

type ResourceHints struct {
	CPU     string `json:"cpu,omitempty" yaml:"cpu,omitempty"`
	Memory  string `json:"memory,omitempty" yaml:"memory,omitempty"`
	Storage string `json:"storage,omitempty" yaml:"storage,omitempty"`
}

type ResourceOutput struct {
	Name       string          `json:"name"`
	Type       string          `json:"type"`
	ProviderID string          `json:"provider_id"`
	Outputs    map[string]any  `json:"outputs"`             // IPs, endpoints, connection strings
	Sensitive  map[string]bool `json:"sensitive,omitempty"` // keys whose values are sensitive
	Status     string          `json:"status"`
}

type ResourceRef struct {
	Name       string `json:"name"`
	Type       string `json:"type"`
	ProviderID string `json:"provider_id,omitempty"`
}

type ResourceReplacer interface {
	Replace(ctx context.Context, oldRef ResourceRef, spec ResourceSpec) (*ResourceOutput, error)
}

type ResourceSpec struct {
	Name      string         `json:"name"`
	Type      string         `json:"type"`
	Config    map[string]any `json:"config"`
	Size      Size           `json:"size,omitempty"`
	Hints     *ResourceHints `json:"hints,omitempty"`
	DependsOn []string       `json:"depends_on,omitempty"`
}

type ResourceState struct {
	ID            string         `json:"id"`
	Name          string         `json:"name"`
	Type          string         `json:"type"`
	Provider      string         `json:"provider"`
	ProviderRef   string         `json:"provider_ref,omitempty"`
	ProviderID    string         `json:"provider_id"`
	ConfigHash    string         `json:"config_hash"`
	AppliedConfig map[string]any `json:"applied_config"`
	// AppliedConfigSource records the provenance of AppliedConfig:
	//   - "apply": AppliedConfig came from a user-supplied ResourceSpec.Config
	//     (set by applyWithProviderAndStore / applyPrecomputedPlanWithStore).
	//   - "adoption": AppliedConfig was reflowed from live cloud Outputs
	//     (set by adoptExistingResources). Comparing such entries against
	//     a fresh Read produces false-positive config-drift; consumers MUST
	//     refuse to compute config-drift on adoption-shaped entries.
	//   - "" (empty): legacy state written before this field existed.
	//     Consumers MUST treat as "adoption" (conservative default).
	AppliedConfigSource string         `json:"applied_config_source,omitempty"`
	Outputs             map[string]any `json:"outputs"`
	Dependencies        []string       `json:"dependencies"`
	CreatedAt           time.Time      `json:"created_at"`
	UpdatedAt           time.Time      `json:"updated_at"`
	LastDriftCheck      time.Time      `json:"last_drift_check,omitempty"`
}

type ResourceStatus struct {
	Name       string         `json:"name"`
	Type       string         `json:"type"`
	ProviderID string         `json:"provider_id"`
	Status     string         `json:"status"` // running, stopped, degraded, unknown
	Outputs    map[string]any `json:"outputs"`
}

type RouteSpec struct {
	Path               string `json:"path" yaml:"path"`
	PreservePathPrefix bool   `json:"preserve_path_prefix" yaml:"preserve_path_prefix"`
}

type SchemaRegistrar interface {
	// Name returns the module name (used for logging).
	Name() string

	// RegisterAdminSchemas registers all admin API request/response schemas
	// onto this generator. Equivalent to calling module.RegisterAdminSchemas(gen).
	RegisterAdminSchemas()

	// ApplySchemas applies all previously registered component schemas and
	// operation schema overrides to the current OpenAPI spec.
	ApplySchemas()
}

type Selector interface {
	Match(r *http.Request) (key string, matched bool, err error)
}

type SidecarSpec struct {
	Name              string                `json:"name" yaml:"name"`
	Image             string                `json:"image,omitempty" yaml:"image,omitempty"`
	RunCommand        string                `json:"run_command" yaml:"run_command"`
	EnvVars           map[string]string     `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
	EnvVarsSecret     map[string]string     `json:"env_vars_secret,omitempty" yaml:"env_vars_secret,omitempty"`
	Ports             []PortSpec            `json:"ports,omitempty" yaml:"ports,omitempty"`
	Resources         *WorkloadResourceSpec `json:"resources,omitempty" yaml:"resources,omitempty"`
	HealthCheck       *HealthCheckSpec      `json:"health_check,omitempty" yaml:"health_check,omitempty"`
	SharesNetworkWith string                `json:"shares_network_with,omitempty" yaml:"shares_network_with,omitempty"` // name of the service this sidecar attaches to
}

type Size string

type SizingDefaults struct {
	CPU         string `json:"cpu"`
	Memory      string `json:"memory"`
	DBStorage   string `json:"db_storage"`
	CacheMemory string `json:"cache_memory"`
}

type StaticSiteSpec struct {
	Name         string            `json:"name" yaml:"name"`
	BuildCommand string            `json:"build_command" yaml:"build_command"`
	OutputDir    string            `json:"output_dir" yaml:"output_dir"`
	EnvVars      map[string]string `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
	Routes       []RouteSpec       `json:"routes,omitempty" yaml:"routes,omitempty"`
	CORS         *CORSSpec         `json:"cors,omitempty" yaml:"cors,omitempty"`
	Domains      []DomainSpec      `json:"domains,omitempty" yaml:"domains,omitempty"`
	Alerts       []AlertSpec       `json:"alerts,omitempty" yaml:"alerts,omitempty"`
}

type StepRegistrar interface {
	StepRegistryProvider
	// Create instantiates a PipelineStep of the given type.
	// app must be a modular.Application; it is typed as any to avoid
	// coupling this interfaces package to the modular dependency.
	Create(stepType, name string, config map[string]any, app any) (PipelineStep, error)
}

type StepRegistryProvider interface {
	// Types returns all registered step type names.
	Types() []string
}

type StepResult struct {
	// Output is the data produced by this step.
	Output map[string]any

	// NextStep overrides the default next step (for conditional routing).
	// Empty string means continue to the next step in sequence.
	NextStep string

	// Stop indicates the pipeline should stop after this step (success).
	Stop bool

	// Skipped indicates the step was bypassed by a guard (skip_if or if).
	// When true, the pipeline executor will not record this step in StepOutputs.
	Skipped bool
}

type Tenant struct {
	ID       string         `json:"id"`
	Name     string         `json:"name"`
	Slug     string         `json:"slug"`
	Domains  []string       `json:"domains,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
	IsActive bool           `json:"is_active"`
}

type TenantFilter struct {
	ActiveOnly bool   `json:"active_only,omitempty"`
	Domain     string `json:"domain,omitempty"`
	Slug       string `json:"slug,omitempty"`
	Limit      int    `json:"limit,omitempty"`
	Offset     int    `json:"offset,omitempty"`
}

type TenantPatch struct {
	Name     *string        `json:"name,omitempty"`
	Domains  []string       `json:"domains,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
	IsActive *bool          `json:"is_active,omitempty"`
}

type TenantRegistry interface {
	// Ensure creates the tenant if it does not exist, or returns the existing one.
	Ensure(spec TenantSpec) (Tenant, error)

	// GetByID looks up a tenant by its opaque ID.
	GetByID(id string) (Tenant, error)

	// GetByDomain looks up a tenant by one of its associated domains.
	GetByDomain(domain string) (Tenant, error)

	// GetBySlug looks up a tenant by its unique URL slug.
	GetBySlug(slug string) (Tenant, error)

	// List returns tenants matching the filter (all tenants if filter is zero).
	List(filter TenantFilter) ([]Tenant, error)

	// Update applies a partial patch to an existing tenant.
	Update(id string, patch TenantPatch) (Tenant, error)

	// Disable soft-deletes a tenant (sets IsActive=false).
	Disable(id string) error
}

type TenantResolver interface {
	// Resolve returns the Tenant associated with the request.
	// Returns the zero Tenant and no error when no tenant is found.
	Resolve(ctx context.Context, r *http.Request) (Tenant, error)
}

type TenantSpec struct {
	Name     string         `json:"name"`
	Slug     string         `json:"slug"`
	Domains  []string       `json:"domains,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TerminationSpec struct {
	DrainSeconds       int `json:"drain_seconds" yaml:"drain_seconds"`
	GracePeriodSeconds int `json:"grace_period_seconds" yaml:"grace_period_seconds"`
}

type Trigger interface {
	modular.Module
	modular.Startable
	modular.Stoppable

	// Configure sets up the trigger from configuration.
	Configure(app modular.Application, triggerConfig any) error
}

type TriggerRegistrar interface {
	// RegisterTrigger adds a trigger to the registry.
	RegisterTrigger(trigger Trigger)
}

type Troubleshooter interface {
	Troubleshoot(ctx context.Context, ref ResourceRef, failureMsg string) ([]Diagnostic, error)
}

type UpsertSupporter interface {
	SupportsUpsert() bool
}

type ValidationError struct {
	Message string
	Status  int    // HTTP status code to use (e.g., 400, 422)
	Field   string // optional: which field was invalid
	Code    string // optional: machine-readable error code for clients
}

type WorkerSpec struct {
	Name            string                `json:"name" yaml:"name"`
	Image           string                `json:"image,omitempty" yaml:"image,omitempty"`
	RunCommand      string                `json:"run_command" yaml:"run_command"`
	EnvVars         map[string]string     `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
	EnvVarsSecret   map[string]string     `json:"env_vars_secret,omitempty" yaml:"env_vars_secret,omitempty"`
	InstanceCount   int                   `json:"instance_count" yaml:"instance_count"`
	Size            string                `json:"size,omitempty" yaml:"size,omitempty"`
	Autoscaling     *AutoscalingSpec      `json:"autoscaling,omitempty" yaml:"autoscaling,omitempty"`
	HealthCheck     *HealthCheckSpec      `json:"health_check,omitempty" yaml:"health_check,omitempty"`
	Resources       *WorkloadResourceSpec `json:"resources,omitempty" yaml:"resources,omitempty"`
	Termination     *TerminationSpec      `json:"termination,omitempty" yaml:"termination,omitempty"`
	Alerts          []AlertSpec           `json:"alerts,omitempty" yaml:"alerts,omitempty"`
	LogDestinations []LogDestinationSpec  `json:"log_destinations,omitempty" yaml:"log_destinations,omitempty"`
}

type WorkflowStoreProvider interface {
	// Name returns the module name (used for logging).
	Name() string

	// WorkflowStore returns the underlying workflow data store as an opaque
	// value. The caller is responsible for asserting the concrete type
	// (typically *module.V1Store) when further operations are required.
	WorkflowStore() any
}

type WorkloadResourceSpec struct {
	CPUMillis   int `json:"cpu_millis" yaml:"cpu_millis"` // 1000 = 1 vCPU
	MemoryMiB   int `json:"memory_mib" yaml:"memory_mib"`
	CPULimit    int `json:"cpu_limit" yaml:"cpu_limit"`
	MemoryLimit int `json:"memory_limit" yaml:"memory_limit"`
}