compile

type CompileOptions ¶

type CompileOptions struct {
	NodeExpanders []NodeExpander
}

CompileOptions supplies extraction-safe, deterministic source-sugar expanders. Expanders are selected by Name rather than caller order.

type CompileResult ¶

type CompileResult struct {
	Plan        *ExecutionPlan
	Diagnostics []diagnostic.Diagnostic
}

CompileResult is the outcome of lowering a loaded source. Plan is present only when Diagnostics is empty.

func Compile(source *Source) CompileResult

func CompileGraph(input graph.Graph, options GraphCompileOptions) CompileResult

func CompileWithOptions(source *Source, options CompileOptions) CompileResult

type DeferredDependency ¶

type DeferredDependency struct {
	Consumer   ValueConsumer            `json:"consumer"`
	Expression *graph.Expression        `json:"expression,omitempty"`
	Reference  *values.Reference        `json:"reference,omitempty"`
	ProducerID string                   `json:"producer_id,omitempty"`
	Reason     DeferredDependencyReason `json:"reason"`
}

DeferredDependency retains a dependency whose producer or invocation-local value cannot be fully selected at compile time. Reference is nil only for opaque verification config that had no registered extractor.

type DeferredDependencyReason ¶

type DeferredDependencyReason string

DeferredDependencyReason explains why a dependency must be resolved or checked at runtime instead of becoming a statically complete data edge.

const (
	// DeferredDynamicStep is a computed steps[...] lookup or root-only steps map
	// access. It may observe only producers already visible through explicit or
	// separately inferred edges.
	DeferredDynamicStep DeferredDependencyReason = "dynamic_step"
	// DeferredFanOutItem is the invocation-local item root.
	DeferredFanOutItem DeferredDependencyReason = "fan_out_item"
	// DeferredFanOutIndex is the invocation-local index root.
	DeferredFanOutIndex DeferredDependencyReason = "fan_out_index"
	// DeferredOptionalProducer is a producer that may not materialize because it
	// is conditional, branch-selected, or fan-out shaped.
	DeferredOptionalProducer DeferredDependencyReason = "optional_producer"
	// DeferredOpaqueVerification records verifier config that core cannot inspect
	// without an extractor registered for that verifier kind.
	DeferredOpaqueVerification DeferredDependencyReason = "opaque_verification"
)

type DefinitionResolver ¶

type DefinitionResolver interface {
	ResolveDefinition(ctx context.Context, ref graph.DefinitionRef) (ResolvedDefinition, error)
}

DefinitionResolver resolves a child definition for call-cycle and depth validation. Ordinary structural validation never invokes it.

func NewBundledDefinitionResolver(plan *ExecutionPlan) (DefinitionResolver, error)

type DefinitionResolverFunc ¶

type DefinitionResolverFunc func(context.Context, graph.DefinitionRef) (ResolvedDefinition, error)

DefinitionResolverFunc adapts a function to DefinitionResolver.

func (f DefinitionResolverFunc) ResolveDefinition(ctx context.Context, ref graph.DefinitionRef) (ResolvedDefinition, error)

type DependencyOptions ¶

type DependencyOptions struct {
	VerificationExtractors map[string]VerificationExpressionExtractor
}

DependencyOptions supplies expression ownership for opaque verifier config. Map keys are exact VerificationCheck.Kind values. Unknown kinds remain deferred and are never inspected lexically by core.

type DependencyResult ¶

type DependencyResult struct {
	Plan        *ExecutionPlan          `json:"plan,omitempty"`
	Visibility  ValueVisibilityPlan     `json:"visibility"`
	Deferred    []DeferredDependency    `json:"deferred,omitempty"`
	Diagnostics []diagnostic.Diagnostic `json:"diagnostics,omitempty"`
}

DependencyResult is the outcome of dependency inference. Plan is nil when any error diagnostic exists. Visibility and Deferred remain available for deterministic diagnostics, tooling, and conformance inspection.

func InferValueDependencies(plan *ExecutionPlan, options DependencyOptions) DependencyResult

type ExecutionPlan ¶

type ExecutionPlan struct {
	SchemaVersion string              `json:"schema_version"`
	ID            string              `json:"id"`
	Digest        string              `json:"digest"`
	Definition    graph.DefinitionRef `json:"definition"`
	Provenance    graph.Provenance    `json:"provenance"`
	SourceDigests []SourceDigest      `json:"source_digests"`
	Graph         graph.Graph         `json:"graph"`
	SourceMap     graph.SourceMap     `json:"source_map"`
	// BundledDefinitions are immutable generated or vendored child workflows
	// required by this plan. They make call resolution restart-safe without a
	// process-local compiler registry.
	BundledDefinitions []ResolvedDefinition `json:"bundled_definitions,omitempty"`
}

ExecutionPlan is the immutable, extraction-ready build artifact consumed by later binding and runtime packages. Definition and Graph contain executable identity and semantics. The original locator appears only in provenance and source-location fields: the plan-level SourceMap and Graph's root, nested, and full-map SourceRef carriers.

SourceMap.Nodes is keyed by normalized node ID, which is the compact source reference a later node invocation persists. Inputs and Outputs use their normalized names. Edges use EdgeSourceKey.

type GraphCompileOptions ¶

type GraphCompileOptions struct {
	SourceFormat graph.SourceFormat
	SourceDigest string
	Definition   graph.DefinitionRef
	Compile      CompileOptions
}

GraphCompileOptions supplies exact source identity for graph IR emitted by an SDK, UI, or agent. CompileGraph performs the same expansion and immutable plan finalization as source lowering; dependency inference and host-selected validation remain the caller's explicit subsequent phases.

type NodeExpander ¶

type NodeExpander interface {
	Name() string
	ExpandNode(NodeExpansionRequest) (expansion NodeExpansion, handled bool, diagnostics []diagnostic.Diagnostic)
}

NodeExpander is a pure compiler extension. ExpandNode returns handled=false when the node is outside its vocabulary. A handled expansion with any diagnostic is rejected; implementations must not perform I/O or consult mutable registries.

type NodeExpansion ¶

type NodeExpansion struct {
	EntryNodeID string               `json:"entry_node_id"`
	ExitNodeID  string               `json:"exit_node_id"`
	Nodes       []graph.Node         `json:"nodes"`
	Edges       []graph.Edge         `json:"edges,omitempty"`
	Definitions []ResolvedDefinition `json:"definitions,omitempty"`
}

NodeExpansion replaces one authored node with ordinary graph nodes and optional immutable child definitions. EntryNodeID receives inbound edges; ExitNodeID retains downstream dependency and expression identity.

type NodeExpansionRequest ¶

type NodeExpansionRequest struct {
	Graph graph.Graph `json:"graph"`
	Node  graph.Node  `json:"node"`
}

NodeExpansionRequest gives an expander a defensive copy of the complete lowered graph and the candidate node. The graph is read-only input; returned replacements must carry every semantic field the expander accepts.

type NodeValidation ¶

type NodeValidation struct {
	GraphID string
	Node    graph.Node
	Kind    *stepkind.StepKindSpec
}

NodeValidation is the application-neutral input supplied to a PolicyHook. Kind is nil when the node's step kind is unavailable; hooks may still report policy findings based on graph declarations alone.

type PolicyHook ¶

type PolicyHook interface {
	ValidateNode(ctx context.Context, input NodeValidation) []diagnostic.Diagnostic
}

PolicyHook validates effect, retry, idempotency, or other host-selected policy combinations without importing a concrete policy implementation.

type PolicyHookFunc ¶

type PolicyHookFunc func(context.Context, NodeValidation) []diagnostic.Diagnostic

PolicyHookFunc adapts a function to PolicyHook.

func (f PolicyHookFunc) ValidateNode(ctx context.Context, input NodeValidation) []diagnostic.Diagnostic

type ResolvedDefinition ¶

type ResolvedDefinition struct {
	Definition    graph.DefinitionRef      `json:"definition"`
	Graph         graph.Graph              `json:"graph"`
	InputBindings map[string]graph.Binding `json:"input_bindings,omitempty"`
}

ResolvedDefinition is the immutable definition identity and graph returned by a DefinitionResolver for opt-in call traversal and execution. InputBindings are resolver-owned partial-application defaults (for example, an imported definition's with: bindings). Call sites overlay their node-local bindings after these defaults are evaluated.

type Result ¶

type Result struct {
	Source      *Source
	Diagnostics []diagnostic.Diagnostic
}

Result is the outcome of loading workflow source. Source is present only when Diagnostics is empty.

func LoadBytes(locator string, data []byte) Result

func LoadFile(locator string) (Result, error)

type SemanticPlanDigest ¶

type SemanticPlanDigest string

SemanticPlanDigest is not assignment-compatible with source-bound digest strings accepted by DefinitionRef, PlanRef, or ExecutionPlan.

type SemanticPlanDocument ¶

type SemanticPlanDocument struct {
	SchemaVersion string          `json:"schema_version"`
	CanonicalJSON json.RawMessage `json:"canonical_json"`
}

SemanticPlanDocument is canonical comparison material for authoring-tool conformance tests. It is deliberately not an ExecutionPlan and cannot be passed to a runtime, registry, or definition API.

func CanonicalPlanSemantics(value ExecutionPlan) (SemanticPlanDocument, error)

type SemanticPlanFingerprint ¶

type SemanticPlanFingerprint struct {
	SchemaVersion  string             `json:"schema_version"`
	SemanticDigest SemanticPlanDigest `json:"semantic_digest"`
}

SemanticPlanFingerprint is a tooling-only equivalence identity. Its struct shape deliberately prevents accidental use as a runtime PlanRef or definition digest, both of which must retain exact source identity.

func FingerprintPlanSemantics(value ExecutionPlan) (SemanticPlanFingerprint, error)

type Source ¶

type Source struct {
	Locator  string
	Document *yaml.Node
	// contains filtered or unexported fields
}

Source preserves a single YAML document and its graph-native source locations. Document is the unlowered yaml.v3 AST, including node tags, styles, anchors, aliases, and comments retained by the YAML parser.

Semantic paths append a mapping key or a zero-based sequence index at each level. The empty path identifies the document root. YAML mappings must use unique string keys so every semantic path has exactly one meaning.

func (s *Source) Bytes() []byte

func (s *Source) Location(path ...string) (graph.SourceRef, bool)

func (s *Source) Locations() []graph.SourceRef

func (s *Source) Node(path ...string) (*yaml.Node, bool)

type SourceDigest ¶

type SourceDigest struct {
	Format graph.SourceFormat `json:"format"`
	Digest string             `json:"digest"`
}

SourceDigest identifies immutable source content without embedding its relocation-sensitive locator. Digest uses SHA-256 over the exact loaded bytes, including comments and authoring layout.

type StepKindLookup ¶

type StepKindLookup interface {
	Lookup(name, version string) (stepkind.StepKind, bool)
	List() []stepkind.StepKindSpec
}

StepKindLookup is the read-only registry surface required by validation. A stepkind.Registry satisfies this interface.

type ValidationOptions ¶

type ValidationOptions struct {
	StepKinds StepKindLookup
	// Verifiers defaults to the deterministic core verification registry when
	// nil. Host-owned reviewer adapters supply an exact immutable registry.
	Verifiers    verification.Registry
	PolicyHooks  []PolicyHook
	Definitions  DefinitionResolver
	MaxCallDepth int
}

ValidationOptions supplies extraction-safe collaborators for validation. Definitions is optional; when nil, validation does not resolve calls. MaxCallDepth defaults to DefaultMaxCallDepth when it is not positive.

type ValueConsumer ¶

type ValueConsumer struct {
	Kind    ValueConsumerKind `json:"kind"`
	ID      string            `json:"id"`
	Surface string            `json:"surface"`
	Source  *graph.SourceRef  `json:"source,omitempty"`
}

ValueConsumer identifies one graph location that consumes expressions. Surface is a stable semantic path such as "with.payload" or "verify.checks[0].expression[0]".

type ValueConsumerKind ¶

type ValueConsumerKind string

ValueConsumerKind identifies the evaluation scope that consumes a reference.

const (
	// ValueConsumerNode is an executable node invocation.
	ValueConsumerNode ValueConsumerKind = "node"
	// ValueConsumerWorkflowOutput is a workflow output evaluated after graph work.
	ValueConsumerWorkflowOutput ValueConsumerKind = "workflow_output"
	// ValueConsumerActivation is a pre-run activation declaration.
	ValueConsumerActivation ValueConsumerKind = "activation"
)

type ValueScope ¶

type ValueScope struct {
	Producers []string `json:"producers"`
	FanOut    bool     `json:"fan_out,omitempty"`
}

ValueScope is the direct value visibility of one evaluation scope. Producers never includes transitive or merely completed graph nodes.

type ValueVisibilityPlan ¶

type ValueVisibilityPlan struct {
	Nodes           map[string]ValueScope `json:"nodes"`
	WorkflowOutputs ValueScope            `json:"workflow_outputs"`
	Activations     map[string]ValueScope `json:"activations,omitempty"`
}

ValueVisibilityPlan is the binder artifact produced beside an inferred execution plan. Nodes contains every normalized node ID, including nodes with an empty producer set.

func (p ValueVisibilityPlan) ScopeNodeContext(
	nodeID string,
	available values.ExpressionContext,
	base values.ExpressionOptions,
) (values.ExpressionContext, values.ExpressionOptions, error)

type VerificationExpressionExtractor ¶

type VerificationExpressionExtractor interface {
	ExtractVerificationExpressions(check graph.VerificationCheck) ([]graph.Expression, []diagnostic.Diagnostic)
}

VerificationExpressionExtractor gives one registered verifier kind sole authority to expose expression-bearing fields from its opaque config. Diagnostics should be structured; omitted sources are assigned to the verification check carrier by InferValueDependencies.

type VerificationExpressionExtractorFunc ¶

type VerificationExpressionExtractorFunc func(graph.VerificationCheck) ([]graph.Expression, []diagnostic.Diagnostic)

VerificationExpressionExtractorFunc adapts a function to an extractor.

func (f VerificationExpressionExtractorFunc) ExtractVerificationExpressions(check graph.VerificationCheck) ([]graph.Expression, []diagnostic.Diagnostic)