call

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package call implements the graph-native call@v1 step kind.

Definition discovery remains host-owned through compile.DefinitionResolver. Durable call resolution, inline graph driving, and child-run creation are explicit ports so this extraction-safe adapter imports no Hadron host, registry, filesystem, transport, or concrete persistence package.

Prepare evaluates child declaration defaults, then resolver/import partial bindings, and finally overlays the caller's already-typed node-local inputs. It records the resolved digest, provenance, effective-input digest, and full active lineage before child work begins. Resolution and operation identities use the logical call site rather than an execution-attempt number, so a keyed retry cannot fork an inline operation or child run.

Inline mode returns exactly the child's declared typed outputs. Run mode returns typed run-id, status, events-ref, cancellation, and outputs-ref handles. Hosts implement parent closure through the persisted runtime.ChildRunLink policy carried by ChildRunRequest.

Index

Constants

View Source 
const (
	CodeInputBinding diagnostic.Code = "HADR-CALL-010"
	CodeInputShape   diagnostic.Code = "HADR-CALL-011"
	CodeInputSchema  diagnostic.Code = "HADR-CALL-012"
)
View Source 
const (
	// KindName is the graph-native call executor name.
	KindName = "call"
	// KindVersion is the first immutable call executor contract.
	KindVersion = "v1"

	OutputRunID        = "run-id"
	OutputStatus       = "status"
	OutputEventsRef    = "events-ref"
	OutputCancellation = "cancellation"
	OutputOutputsRef   = "outputs-ref"

	CodeInvalidInvocation = "call_invalid_invocation"
	CodeResolutionFailed  = "call_resolution_failed"
	CodeResolutionInvalid = "call_resolution_invalid"
	CodeDepthExceeded     = "call_depth_exceeded"
	CodeCycle             = "call_cycle"
	CodeRecordFailed      = "call_resolution_record_failed"
	CodeInlineFailed      = "call_inline_failed"
	CodeChildRunFailed    = "call_child_run_failed"
	CodeResultInvalid     = "call_result_invalid"
)
View Source 
const DefaultMaxDepth = workflowcompile.DefaultMaxCallDepth

Variables

View Source 
var (
	ErrInvalidOptions     = errors.New("invalid call executor options")
	ErrInvalidCall        = errors.New("invalid workflow call")
	ErrResolutionConflict = errors.New("call resolution replay conflict")
)

Functions

This section is empty.

Types

type BindInputsRequest 

type BindInputsRequest struct {
	Invocation  stepkind.InvocationIdentity
	Resolved    workflowcompile.ResolvedDefinition
	LocalInputs values.ValueSet
	Context     values.ExpressionContext
	Options     values.ExpressionOptions
}

BindInputsRequest contains the parent-scoped expression data required to bind one call. Resolved.InputBindings are import-level partial defaults; LocalInputs are the call node's already-evaluated with: bindings.

type BindInputsResult 

type BindInputsResult struct {
	Inputs      values.ValueSet
	Diagnostics []diagnostic.Diagnostic
}

BindInputsResult contains either a complete typed child input set or stable diagnostics. Inputs is nil whenever Diagnostics is non-empty.

func BindInputs 

func BindInputs(request BindInputsRequest) BindInputsResult

BindInputs evaluates child declaration defaults first and resolver/import partial bindings second, then overlays the already-evaluated node-local with: inputs last. All default expression evaluation uses the caller-supplied parent context; partial outputs never become an implicit expression root.

type CallSiteIdentity 

type CallSiteIdentity struct {
	RunID     string `json:"run_id"`
	NodeID    string `json:"node_id"`
	Iteration string `json:"iteration,omitempty"`
}

CallSiteIdentity excludes attempt number so retries of the same expanded parent node stay pinned to one resolution and one child-run identity.

func (CallSiteIdentity) Validate 

func (i CallSiteIdentity) Validate() error

Validate reports malformed logical parent invocation identity.

type CancellationHandle 

type CancellationHandle struct {
	RunID  workflowruntime.RunID   `json:"run_id"`
	Policy graph.ParentClosePolicy `json:"policy"`
	Ref    string                  `json:"ref"`
}

CancellationHandle is a stable, non-secret reference for child-run control. It does not grant permission by itself; host policy authorizes its use.

type ChildRunExecutor 

type ChildRunExecutor interface {
	StartChildRun(context.Context, ChildRunRequest) (ChildRunResult, error)
}

ChildRunExecutor creates/replays separately identified child runs. A successful return guarantees the Run, ChildRunLink, creation event, and input reference are durable as one semantic operation.

type ChildRunRequest 

type ChildRunRequest struct {
	Parent         CallSiteIdentity                   `json:"parent"`
	ChildRunID     workflowruntime.RunID              `json:"child_run_id"`
	Definition     workflowcompile.ResolvedDefinition `json:"definition"`
	Plan           workflowruntime.PlanRef            `json:"plan"`
	Inputs         values.ValueSet                    `json:"inputs"`
	Lineage        []graph.DefinitionRef              `json:"lineage"`
	ParentClose    graph.ParentClosePolicy            `json:"parent_close"`
	IdempotencyKey string                             `json:"idempotency_key"`
}

ChildRunRequest asks the host to atomically create/replay a child Run and its existing runtime.ChildRunLink. ChildRunID and IdempotencyKey are derived from immutable parent call-site and persisted resolution identity.

type ChildRunResult 

type ChildRunResult struct {
	Run          workflowruntime.RunSnapshot  `json:"run"`
	Link         workflowruntime.ChildRunLink `json:"link"`
	EventsRef    string                       `json:"events_ref"`
	Cancellation CancellationHandle           `json:"cancellation"`
}

ChildRunResult is the durable child handle returned after atomic creation or exact replay. Run.Outputs may be nil while the child is active.

type ContextProvider 

type ContextProvider interface {
	ExpressionContext(context.Context, stepkind.Invocation) (values.ExpressionContext, values.ExpressionOptions, error)
}

ContextProvider reconstructs the parent-scoped expression context used to evaluate child declaration and resolver/import defaults. Invocation.Inputs already contains evaluated node-local with: values; those values are overlaid after defaults and remain authoritative on name collisions.

type ContextProviderFunc 

type ContextProviderFunc func(context.Context, stepkind.Invocation) (values.ExpressionContext, values.ExpressionOptions, error)

ContextProviderFunc adapts a function to ContextProvider.

func (ContextProviderFunc) ExpressionContext 

func (f ContextProviderFunc) ExpressionContext(ctx context.Context, invocation stepkind.Invocation) (values.ExpressionContext, values.ExpressionOptions, error)

ExpressionContext implements ContextProvider.

type Executor 

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

Executor implements the registered graph-native call step kind.

func New 

func New(options Options) (*Executor, error)

New constructs call@v1. Every collaborator is required because the single immutable registered kind truthfully supports both inline and child-run modes. MaxDepth defaults to compile.DefaultMaxCallDepth.

func Register 

func Register(registry stepkind.Registry, options Options) (*Executor, error)

Register registers call@v1 in registry.

func (*Executor) DescribeReversibility 

func (e *Executor) DescribeReversibility(_ context.Context, request stepkind.ReversibilityRequest) (stepkind.ReversibilityEvidence, error)

DescribeReversibility accepts only child-run calls: the durable child identity is truthful parent-side evidence, while the child retains and completes its own compensation ledger first.

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)

Execute drives inline child graphs or atomically creates/replays a child run.

func (*Executor) Prepare 

func (e *Executor) Prepare(ctx context.Context, invocation stepkind.Invocation) (stepkind.PreparedInvocation, error)

Prepare resolves, policy-checks, and durably records the immutable child definition before any child execution. Exact retries return the same record.

func (*Executor) Spec 

func (e *Executor) Spec() stepkind.StepKindSpec

Spec returns conservative metadata. A child definition may contain any portable effect, so policy must inspect the resolved graph before granting narrower permissions. Durable call replay requires an invocation key.

func (*Executor) ValidateConfig 

func (e *Executor) ValidateConfig(_ context.Context, config graph.Config) []diagnostic.Diagnostic

ValidateConfig rejects adapter config fields. Call semantics are represented only by graph.Node.Call, preventing a second divergent call envelope.

type InlineExecutor 

type InlineExecutor interface {
	ExecuteInline(context.Context, InlineRequest) (InlineResult, error)
}

InlineExecutor runs a resolved child graph using the parent RunID and a nested, collision-free invocation namespace chosen by the host runtime.

type InlineRequest 

type InlineRequest struct {
	Parent         CallSiteIdentity                   `json:"parent"`
	Definition     workflowcompile.ResolvedDefinition `json:"definition"`
	Inputs         values.ValueSet                    `json:"inputs"`
	Lineage        []graph.DefinitionRef              `json:"lineage"`
	IdempotencyKey string                             `json:"idempotency_key"`
}

InlineRequest executes a resolved definition beneath the parent run identity. Lineage and IdempotencyKey must be propagated to nested calls. Inputs and Definition are defensive copies.

type InlineResult 

type InlineResult struct {
	Outputs values.ValueSet `json:"outputs"`
}

InlineResult contains the finalized declared child outputs. Operational events remain attached to the parent run and are not data-plane fields.

type Options 

type Options struct {
	Resolver workflowcompile.DefinitionResolver
	State    ResolutionStore
	Context  ContextProvider
	Inline   InlineExecutor
	Runs     ChildRunExecutor
	MaxDepth int
}

Options supplies every host boundary required by call@v1.

type RecordResolutionRequest 

type RecordResolutionRequest struct {
	Record ResolutionRecord
}

RecordResolutionRequest asks the host store to persist an exact resolution before any child graph work begins. The store owns idempotency and event ordering; a process-local success without durable state is invalid.

type ResolutionOutcome 

type ResolutionOutcome string

ResolutionOutcome distinguishes a newly persisted resolution from an exact durable replay. Stores must reject a changed record for an existing Key. 

const (
	ResolutionApplied  ResolutionOutcome = "applied"
	ResolutionReplayed ResolutionOutcome = "replayed"
)

type ResolutionRecord 

type ResolutionRecord struct {
	Key         string                `json:"key"`
	Invocation  CallSiteIdentity      `json:"invocation"`
	Requested   graph.DefinitionRef   `json:"requested"`
	Resolved    graph.DefinitionRef   `json:"resolved"`
	InputDigest string                `json:"input_digest"`
	Lineage     []graph.DefinitionRef `json:"lineage"`
}

ResolutionRecord is the immutable durable explanation of one logical call site across execution attempts. Lineage includes the resolved child as its final element. InputDigest binds the record to the already typed effective child inputs. Stores must persist this record and its parent-invocation event atomically.

func (ResolutionRecord) Validate 

func (r ResolutionRecord) Validate() error

Validate reports malformed durable resolution metadata. It does not resolve definitions or read workflow values.

type ResolutionStore 

type ResolutionStore interface {
	RecordCallResolution(context.Context, RecordResolutionRequest) (ResolutionRecord, ResolutionOutcome, error)
}

ResolutionStore is the narrow durability boundary for parent call invocations. Implementations must be concurrency-safe, exact-replay safe, and must return ErrResolutionConflict (or an error wrapping it) when Key was used for a different record.

Source Files

View all Source files

Directories

Path Synopsis
Package calltest supplies extraction-safe call adapter conformance fixtures.
 Package calltest supplies extraction-safe call adapter conformance fixtures.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.