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
	SyntaxBody *syntax.FactoryBody
	Libraries  map[string]*Library
}

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

	// SyntaxSource is the typed factory body for grammar-first callers.
	SyntaxSource *syntax.FactoryBody

	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.Registration
	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 generated 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, 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
	ConfigurationFields   []typecheck.ObjectField
	ConfigurationDefaults []lang.DefaultSpec
	ConfigurationDigest   string
	ConfigurationEmpty    bool
	HasConfiguration      bool
}

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

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

type NoConfig struct{}

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

	ForEach lang.Expr

	// 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
}

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
	Steps    []*PlanStep

	// Backend names the state backend the plan was computed against,
	// so apply can reconstruct the same backend without re-reading
	// the stack file. 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"`

	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:"node-kind"`
	Selector *state.Selector `json:"selector,omitempty"`

	// 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; Node.IsComposite has source
	// body metadata, 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"`

	// DeferredConfig names the library-config node 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.
	DeferredConfig string `json:"deferred-config,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"`

	PriorSelector   *state.Selector `json:"prior-selector,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"`

	// 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 RefMatch struct {
	Address  string
	Segments int
}

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:"node-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, Config any] interface {
	Run(ctx context.Context, config Config) (Out, error)
}

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

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