runtime

type ActionRegistration interface {
	NewReceiver() any
	Run(ctx context.Context, receiver, cfg any) (any, error)
	OutputType() reflect.Type
}

type ApplyError struct {
	Address        string
	Kind           NodeKind
	Decision       Decision
	Library        string
	Elapsed        time.Duration
	Err            error
	SkippedCount   int
	SucceededCount int
}

type ApplyEvent struct {
	Address string
	Kind    NodeKind

	// Composite marks an event for a composite call site (a boundary).
	// A boundary's Kind is its own resource/data/action kind, so this
	// is what tells a boundary apart from a leaf of that kind.
	Composite bool

	Decision Decision
	Stage    ApplyStage
	Time     time.Time
	Elapsed  time.Duration
	Err      error
}

type ApplyStage string

type CompositeType struct {
	Name      string
	Kind      NodeKind
	Body      *lang.File
	Libraries map[string]*Library
}

type ConfigRef struct {
	Alias         string
	Configuration string
}

type DAG struct {
	Nodes map[string]*Node
	Edges map[string][]string
}

type DataSourceRegistration interface {
	NewReceiver() any
	Read(ctx context.Context, receiver, cfg any) (any, error)
	OutputType() reflect.Type
}

type Decision string

type EvalContext struct {
	Vars      map[string]any
	Resources map[string]any
	Data      map[string]any
	Actions   map[string]any
	Libraries map[string]*Library
	Bindings  map[string]any

	// Each holds named iteration bindings, @each for a @for-each body
	// and declared names like @rule for a chained constraint form,
	// each a key/value record read as @name.key and @name.value.
	Each map[string]lang.EachValue

	// MissingAsNull makes path navigation yield null instead of
	// ErrEvalNotFound, or a hard error, when a key is absent or a parent
	// is itself null. The constraint checkers set it so a predicate over
	// an unset optional input, including a nested one, reduces to a
	// boolean rather than collapsing the whole expression to null or
	// failing on a null parent. Navigating into a non-null scalar is
	// still an error. It stays false everywhere else, because the planner
	// relies on ErrEvalNotFound to detect forward references to upstreams
	// that have not run yet.
	MissingAsNull bool
	// contains filtered or unexported fields
}

type ExecResult struct {
	Outputs    map[string]any
	Actions    map[string]any
	Data       map[string]any
	WrittenRev string
}

type Executor struct {
	DAG       *DAG
	Libraries map[string]*Library
	Inputs    map[string]any

	// Source is the parsed stack file. Static analysis passes (e.g.
	// sensitivity propagation at plan time) consult its top-level
	// blocks for declarations the DAG alone does not carry. May be
	// nil in test setups; analyses that need it degrade to no-op.
	Source *lang.File

	// Configurations is keyed first by the library's import alias and
	// then by the configuration alias declared in config.ub. Entries
	// are the value returned by cfg.ConfigurationType.New populated
	// by cfg.Decode. A nil map disables config routing and every CRUD
	// call sees a nil cfg argument.
	Configurations map[string]map[string]any

	Store   state.Backend
	Factory state.FactoryInfo

	// Parallelism caps the number of in-flight resource, data, and
	// action steps during ApplyPlan. Zero or negative falls back to
	// DefaultParallelism.
	Parallelism int

	// Destroy makes Plan compute a teardown: every resource in prior
	// state is planned for destroy and no outputs are evaluated. The
	// source is still parsed and its configurations still resolve, so
	// the deletes use the right credentials.
	Destroy bool

	// Drain, when non-nil, lets the caller ask the scheduler to stop
	// dispatching new steps without canceling the apply context. The
	// runner closes this channel on SIGINT so in-flight CRUD calls
	// finish and their state writes commit; SIGTERM cancels the
	// context directly. A nil channel disables the drain signal.
	Drain <-chan struct{}

	// Events, when non-nil, receives one ApplyEvent per step stage
	// during ApplyPlan: start when the scheduler hands the step to a
	// worker, done or fail when the worker returns. The caller owns
	// the channel and is responsible for sizing the buffer and
	// closing it after ApplyPlan returns. A nil channel disables
	// event emission.
	Events chan<- ApplyEvent
	// contains filtered or unexported fields
}

type FactoryRef struct {
	Name            string `json:"name"`
	Version         string `json:"version"`
	ContentRevision string `json:"content-revision"`
}

type FunctionType struct {
	Name        string
	Description string
	ArgCount    int
	Variadic    bool
	Func        func(args []any) (any, error)
}

type Library struct {
	Name          string
	Description   string
	Configuration *cfg.ConfigurationType
	Actions       map[string]ActionRegistration
	Resources     map[string]ResourceRegistration
	DataSources   map[string]DataSourceRegistration
	// Composites are kept in one map per kind, mirroring the
	// Resources / DataSources / Actions Go-type maps. resource, data,
	// and action are distinct namespaces, so a library may declare
	// resource.foo and data.foo as separate composites.
	ResourceComposites map[string]*CompositeType
	DataComposites     map[string]*CompositeType
	ActionComposites   map[string]*CompositeType
	Functions          map[string]FunctionType
	// Schema carries the library's resource, data source, and action
	// output field sets. Populated by the dev CLI from a fetched Go
	// library's source for compile-time reference checking; nil at
	// runtime since the stack binary does not need it.
	Schema *LibrarySchema

	// Constraints holds each Go type's cross-field constraints in the
	// embeddable spec form, keyed by "<kind>.<type>" (e.g. "resource.vpc")
	// since resource, data, and action are distinct namespaces. codegen
	// sets it in the generated main.go from the constraints goschema
	// derived from the library's source; the plan checks a node against
	// Constraints[node.Kind + "." + node.Type]. UB composites carry their
	// own constraints in their bodies, so this stays empty for UB libraries.
	Constraints map[string][]lang.ConstraintSpec

	// Defaults holds each Go type's declared input defaults, keyed by
	// "<kind>.<type>" like Constraints and set the same way by codegen.
	// The runtime fills a Value default into a body's inputs wherever a
	// field is left out or null, before constraints, triggers, and
	// decode read them; an Optional marker fills nothing.
	Defaults map[string][]lang.DefaultSpec
}

type LibrarySchema struct {
	Resources   map[string]*TypeSchema
	DataSources map[string]*TypeSchema
	Actions     map[string]*TypeSchema
	// Functions maps each function name the library exports to its
	// declared signature. The implementations live in the compiled Go
	// and cannot run at compile time, but the signature lets the
	// reference checker reject a call to an unknown function or one
	// given the wrong number of arguments, and the inferrer check each
	// argument's type and use the result type. A function registered
	// without declared types reads as all-Unknown, which counts
	// arguments but checks no types.
	Functions map[string]typecheck.FuncSig

	// Configuration describes the fields of the library's Configuration
	// struct, keyed by kebab-case field name. Nil when the library
	// declares no configuration or when the struct behind the
	// ConfigurationType's New function cannot be read from source.
	// HasConfiguration distinguishes the two: it is true whenever the
	// library declares a configuration, readable or not, so checks can
	// tell "no configuration" from "fields unknowable".
	Configuration    map[string]typecheck.Type
	HasConfiguration bool
}

type MigrationState struct {
	Inputs  map[string]any
	Outputs map[string]any
}

type Migrator interface {
	Migrate(oldVersion int, prior MigrationState) (MigrationState, error)
}

type Node struct {
	Address       string
	Kind          NodeKind
	Alias         string
	Type          string
	Name          string
	Body          lang.Expr
	Composite     string
	CompositeBody *lang.File
	Libraries     map[string]*Library

	ForEach lang.Expr

	// Configuration names the configuration selected under the node's
	// import (Alias) that the runtime hands to CRUD calls. Empty falls
	// back to "default" at lookup time.
	Configuration string

	// LockName is the value of a node body's `@lock:` field. Two nodes
	// sharing a non-empty LockName cannot run in parallel under apply's
	// scheduler, even on unrelated DAG branches. Empty means the node is
	// not under a named lock. It applies to any kind; since the
	// scheduler only runs nodes in parallel at apply, a lock has no
	// effect on a data source whose inputs are known and read at plan.
	LockName string

	// Timeout is the parsed value of a node body's `@timeout:` field: a
	// limit on how long the node's apply step may run. Zero means no
	// limit. On expiry the step's context is cancelled and the step
	// fails like any other apply error. Like @lock it only bites at
	// apply, so it does not bound a data source read at plan.
	Timeout time.Duration

	// ConfigurationsRemap is set only on a composite boundary. It maps an
	// inner import alias to the (alias, configuration) of the
	// configuration that backs that import inside the call. The
	// runtime walks the composite chain at lookup time and the
	// validator enforces that the right-hand-side alias matches
	// the key.
	ConfigurationsRemap map[string]ConfigRef
}

type NodeKind string

type PanicError struct {
	Op      string
	Library string
	Value   any
	Stack   []byte
	Core    bool
}

type PendingValue struct {
	Refs []string
}

type Plan struct {
	Factory           state.FactoryInfo
	Stack             string
	StateRev          string
	Inputs            map[string]any
	RawConfigurations map[string]map[string]any
	Steps             []*PlanStep

	// Backend names the state backend the plan was computed against,
	// so apply can reconstruct the same backend without re-reading
	// config.ub. A nil value means the resolver's default (the local
	// backend under .unobin/state) was used.
	Backend *StateRef

	// Parallelism is the in-flight cap apply should honor. Zero means
	// the runtime's DefaultParallelism applies.
	Parallelism int

	// Destroy marks a teardown plan: every step is a destroy and apply
	// evaluates no outputs.
	Destroy bool
}

type PlanFile struct {
	FormatVersion     int                       `json:"format-version"`
	Factory           FactoryRef                `json:"factory"`
	Stack             string                    `json:"stack"`
	StateRev          string                    `json:"state-rev"`
	GeneratedAt       time.Time                 `json:"generated-at"`
	Inputs            map[string]any            `json:"inputs,omitempty"`
	RawConfigurations map[string]map[string]any `json:"configurations,omitempty"`
	Backend           *StateRef                 `json:"backend,omitempty"`
	Parallelism       int                       `json:"parallelism,omitempty"`
	Destroy           bool                      `json:"destroy,omitempty"`
	Steps             []PlanStep                `json:"steps"`
}

type PlanStep struct {
	Address string   `json:"address"`
	Kind    NodeKind `json:"kind"`

	// Composite marks a step whose apply finalizes a composite call
	// site (a boundary) rather than a primitive leaf. A boundary's Kind
	// is its own resource/data/action kind, so the runtime cannot
	// tell it from a leaf by Kind alone; on a Node that distinction is
	// the expanded CompositeBody (Node.IsComposite), but a step has no
	// body, so the bit is stored explicitly in the plan file.
	Composite bool `json:"composite,omitempty"`

	Decision         Decision            `json:"decision"`
	Inputs           map[string]any      `json:"inputs,omitempty"`
	UnresolvedInputs map[string][]string `json:"unresolved-inputs,omitempty"`

	// DeferredRead names the configuration selection (alias.name form)
	// whose pending evaluation kept this node's read from running at
	// plan. The stored state is taken as current for the decision;
	// apply and the next plan see real values.
	DeferredRead string `json:"deferred-read,omitempty"`

	// PriorInputs is the body the last apply evaluated, recorded so the plan
	// can show a changed field as `old -> new` rather than the new value
	// alone. Nil for a create, where there is no prior to compare against.
	PriorInputs map[string]any `json:"prior-inputs,omitempty"`

	PriorOutputs    map[string]any `json:"prior-outputs,omitempty"`
	ObservedOutputs map[string]any `json:"observed-outputs,omitempty"`
	TriggerHash     string         `json:"trigger-hash,omitempty"`

	// ReplaceTriggers names the replace-forcing fields whose value changed,
	// the reason a step replaces rather than updates. The renderer tags each
	// with `(forces replacement)`. Empty unless Decision is replace.
	ReplaceTriggers []string `json:"replace-triggers,omitempty"`

	// Configuration is the step's library configuration ref
	// ("<alias>.<configuration>"). A destroy step records it from prior
	// state, so apply deletes against the same credentials the resource
	// was created with. A live step records it only when the selection
	// names an internal configuration still pending this plan, which is
	// how the renderer knows to show the selection on the step.
	Configuration string `json:"configuration,omitempty"`

	// DependsOn carries a destroy step's recorded dependencies from
	// prior state. Apply reverses these edges so a resource is deleted
	// before the resources it depended on.
	DependsOn []string `json:"depends-on,omitempty"`

	// AlreadyGone marks a destroy step whose resource was already
	// absent when the plan read it. Apply drops the entry from state
	// without calling Delete.
	AlreadyGone bool `json:"already-gone,omitempty"`

	// SensitiveInputs names the input fields whose value expression
	// reads from any sensitive source. Renderers replace the value
	// with a placeholder rather than printing the secret.
	SensitiveInputs []string `json:"sensitive-inputs,omitempty"`

	// SensitiveOutputs names the output fields of this step that are
	// sensitive. For a primitive resource/action it comes from the
	// library schema's tagged fields; for a composite call site it
	// comes from the composite type's `@sensitive` markers and from
	// propagation through its body.
	SensitiveOutputs []string `json:"sensitive-outputs,omitempty"`
	// contains filtered or unexported fields
}

type Prior[In, Out any] struct {
	Inputs   In
	Outputs  Out
	Observed Out
}

type RefreshResult struct {
	WrittenRev string
	Refreshed  int
	Dropped    int
}

type ResourceRegistration interface {
	SchemaVersion() int
	Migrate(oldVersion int, prior MigrationState) (MigrationState, error)
	NewReceiver() any
	Create(ctx context.Context, receiver, cfg any) (any, error)
	Read(ctx context.Context, receiver, cfg, prior any) (any, error)
	Update(ctx context.Context, receiver, cfg, priorInputs, priorOutputs, observed any) (any, error)
	Delete(ctx context.Context, receiver, cfg, prior any) error
	ReplaceFields(receiver any) []string
	OutputType() reflect.Type
}

type StateRef = state.Ref

type StepNode struct {
	Address   string   `json:"address"`
	Kind      NodeKind `json:"kind"`
	Composite bool     `json:"composite,omitempty"`
	Decision  Decision `json:"decision"`
	DependsOn []string `json:"depends-on,omitempty"`
}

type TriggerDecision struct {
	Hash        string
	AlwaysRerun bool
	HasExplicit bool
}

type TypeSchema struct {
	Inputs           map[string]typecheck.Type
	Outputs          map[string]typecheck.Type
	SensitiveInputs  []string
	SensitiveOutputs []string

	// Constraints holds the type's cross-field constraints, derived from
	// its Constraints method at compile time, in the embeddable string
	// form. A check parses them with lang.ParseSpecs and runs them through
	// lang.CheckConstraintEntries, the same path UB constraints take.
	Constraints []lang.ConstraintSpec

	// Defaults holds the type's declared input defaults, derived from
	// its Defaults method at compile time. A field with a Value default
	// is filled in when a body leaves it out; an Optional marker only
	// declares that absence is fine. Any other input is required.
	Defaults []lang.DefaultSpec
}

type TypedAction[Out any] interface {
	Run(ctx context.Context, cfg any) (Out, error)
}

type TypedDataSource[Out any] interface {
	Read(ctx context.Context, cfg any) (Out, error)
}

type TypedResource[In, Out any] interface {
	SchemaVersion() int
	Create(ctx context.Context, cfg any) (Out, error)
	Read(ctx context.Context, cfg any, prior Out) (Out, error)
	Update(ctx context.Context, cfg any, prior Prior[In, Out]) (Out, error)
	Delete(ctx context.Context, cfg any, prior Out) error
	ReplaceFields() []string
}