graph

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package graph owns the application-neutral workflow graph representation, source references, source maps, and schema-bearing contracts shared by compilers, runtimes, transports, user interfaces, and conformance tests.

It is extraction-ready engine core. Imports are limited to the standard library and explicitly adopted extraction-safe dependencies; Hadron internal packages are forbidden. Adapter-specific configuration remains opaque to this package and is validated by step-kind implementations.

Index

Constants

View Source 
const CatchAllErrors = "*"

CatchAllErrors is the canonical catch selector for every structured failure.

View Source 
const MaxIDLength = 128

MaxIDLength is the maximum normalized workflow, node, input, output, or activation identifier length in bytes.

Variables

This section is empty.

Functions

func NormalizeID 

func NormalizeID(value string) string

NormalizeID converts an identifier into lower-case ASCII kebab form. Runs of punctuation, underscores, whitespace, or unsupported characters become one hyphen; leading and trailing separators are removed.

func ValidateID 

func ValidateID(value string) error

ValidateID rejects empty, overlong, or non-normalized identifiers.

Types

type ActivationDeclaration 

type ActivationDeclaration struct {
	ID         string             `json:"id" yaml:"id"`
	Kind       string             `json:"kind" yaml:"kind"`
	Config     Config             `json:"config,omitempty" yaml:"config,omitempty"`
	Inputs     map[string]Binding `json:"inputs,omitempty" yaml:"inputs,omitempty"`
	Policy     ActivationPolicy   `json:"policy,omitempty" yaml:"policy,omitempty"`
	Provenance Provenance         `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	Source     *SourceRef         `json:"source,omitempty" yaml:"source,omitempty"`
	Metadata   Metadata           `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

ActivationDeclaration is an immutable, source-declared request for a host to materialize an operational activation registration. Provenance records the source authority; Config remains host-adapter opaque.

type ActivationPolicy 

type ActivationPolicy struct {
	Overlap          OverlapPolicy    `json:"overlap,omitempty" yaml:"overlap,omitempty"`
	StartingDeadline Duration         `json:"starting_deadline,omitempty" yaml:"starting_deadline,omitempty"`
	Catchup          bool             `json:"catchup,omitempty" yaml:"catchup,omitempty"`
	DeduplicationKey *Expression      `json:"deduplication_key,omitempty" yaml:"deduplication_key,omitempty"`
	RunIDReuse       RunIDReusePolicy `json:"run_id_reuse,omitempty" yaml:"run_id_reuse,omitempty"`
}

ActivationPolicy carries portable overlap, deduplication, and missed-fire declarations. A host resolves them before creating a bound run.

type BackoffPolicy 

type BackoffPolicy struct {
	Strategy     BackoffStrategy `json:"strategy" yaml:"strategy"`
	InitialDelay Duration        `json:"initial_delay,omitempty" yaml:"initial_delay,omitempty"`
	MaxDelay     Duration        `json:"max_delay,omitempty" yaml:"max_delay,omitempty"`
	Multiplier   float64         `json:"multiplier,omitempty" yaml:"multiplier,omitempty"`
}

BackoffPolicy describes how delays grow between attempts.

type BackoffStrategy 

type BackoffStrategy string

BackoffStrategy selects retry delay growth. 

const (
	// BackoffNone retries without an engine-introduced delay.
	BackoffNone BackoffStrategy = "none"
	// BackoffFixed uses the initial delay for every retry.
	BackoffFixed BackoffStrategy = "fixed"
	// BackoffLinear increases delay by a constant multiple.
	BackoffLinear BackoffStrategy = "linear"
	// BackoffExponential multiplies delay after each attempt.
	BackoffExponential BackoffStrategy = "exponential"
)

func (BackoffStrategy) Valid 

func (s BackoffStrategy) Valid() bool

Valid reports whether s is a supported backoff strategy.

type Binding 

type Binding struct {
	Kind          BindingKind `json:"kind" yaml:"kind"`
	Literal       any         `json:"literal,omitempty" yaml:"literal,omitempty"`
	Expression    *Expression `json:"expression,omitempty" yaml:"expression,omitempty"`
	Interpolation string      `json:"interpolation,omitempty" yaml:"interpolation,omitempty"`
	Source        *SourceRef  `json:"source,omitempty" yaml:"source,omitempty"`
}

Binding provides a typed place for a literal, raw expression, or string interpolation without evaluating it in the graph package.

type BindingKind 

type BindingKind string

BindingKind identifies how a binding obtains its value. 

const (
	// BindingLiteral carries a literal JSON-compatible value.
	BindingLiteral BindingKind = "literal"
	// BindingExpression carries a raw expression-language value.
	BindingExpression BindingKind = "expression"
	// BindingInterpolation carries a string containing interpolations.
	BindingInterpolation BindingKind = "interpolation"
)

func (BindingKind) Valid 

func (k BindingKind) Valid() bool

Valid reports whether k is a supported binding kind.

type CallMode 

type CallMode string

CallMode selects child workflow run identity. 

const (
	// CallInline executes a child definition inside the parent run identity.
	CallInline CallMode = "inline"
	// CallRun creates separately identifiable child-run state.
	CallRun CallMode = "run"
)

func (CallMode) Valid 

func (m CallMode) Valid() bool

Valid reports whether m is a supported call mode.

type CallSpec 

type CallSpec struct {
	Definition DefinitionRef `json:"definition,omitempty" yaml:"definition,omitempty"`
	// DefinitionInput names a typed invocation input containing an immutable,
	// exact-digest DefinitionRef. It is mutually exclusive with Definition and
	// is resolved by the runtime before the ordinary call adapter executes.
	DefinitionInput string            `json:"definition_input,omitempty" yaml:"definition_input,omitempty"`
	Mode            CallMode          `json:"mode" yaml:"mode"`
	OnParentClose   ParentClosePolicy `json:"on_parent_close,omitempty" yaml:"on_parent_close,omitempty"`
}

CallSpec invokes another workflow inline or as a separately identified run.

type CatchRule 

type CatchRule struct {
	Errors  []string    `json:"errors,omitempty" yaml:"errors,omitempty"`
	When    *Expression `json:"when,omitempty" yaml:"when,omitempty"`
	Targets []string    `json:"targets" yaml:"targets"`
	BindAs  string      `json:"bind_as,omitempty" yaml:"bind_as,omitempty"`
	Source  *SourceRef  `json:"source,omitempty" yaml:"source,omitempty"`
}

CatchRule routes a matching structured error to ordinary graph nodes. An empty Errors list deterministically matches every error; When may narrow it. BindAs is an expression-local lower-snake identifier, not a graph node ID.

func (CatchRule) ContinueOnError 

func (r CatchRule) ContinueOnError() bool

ContinueOnError reports whether this rule is the compiler's exact policy sugar for handling every failure without selecting a handler node. Keeping the lowering in CatchRule means the runtime has one error-routing model.

type CompensationMode 

type CompensationMode string

CompensationMode selects handler failure behavior. Best effort preserves remaining independent work after one handler exhausts its normal retry. 

const CompensationBestEffort CompensationMode = "best_effort"

func (CompensationMode) Valid 

func (m CompensationMode) Valid() bool

type CompensationPolicy 

type CompensationPolicy struct {
	Triggers []CompensationTrigger `json:"triggers" yaml:"triggers"`
	Mode     CompensationMode      `json:"mode,omitempty" yaml:"mode,omitempty"`
}

CompensationPolicy selects the explicit run outcomes that freeze and drive the run-owned saga ledger. Manual is opt-in and never inferred from effects.

type CompensationSpec 

type CompensationSpec struct {
	Handler string `json:"handler" yaml:"handler"`
}

CompensationSpec registers an ordinary graph node as the dormant handler for this forward node. The handler is materialized only from a frozen saga entry; it is never eligible during forward scheduling.

type CompensationTrigger 

type CompensationTrigger string

CompensationTrigger selects an explicit run outcome that starts rollback. 

const (
	CompensationOnFailure CompensationTrigger = "failure"
	CompensationOnCancel  CompensationTrigger = "cancel"
	CompensationOnTimeout CompensationTrigger = "timeout"
	CompensationManual    CompensationTrigger = "manual"
)

func (CompensationTrigger) Valid 

func (t CompensationTrigger) Valid() bool

type ConcurrencyClaim 

type ConcurrencyClaim struct {
	Resource string `json:"resource" yaml:"resource"`
	Amount   int    `json:"amount,omitempty" yaml:"amount,omitempty"`
}

ConcurrencyClaim requests units from a named concurrency resource.

type ConcurrencyResource 

type ConcurrencyResource struct {
	Name     string   `json:"name" yaml:"name"`
	Limit    int      `json:"limit" yaml:"limit"`
	Metadata Metadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

ConcurrencyResource defines a portable named semaphore.

type ConcurrencySpec 

type ConcurrencySpec struct {
	Resources []ConcurrencyResource `json:"resources,omitempty" yaml:"resources,omitempty"`
	MaxRun    int                   `json:"max_run,omitempty" yaml:"max_run,omitempty"`
	Extension Extension             `json:"extension,omitempty" yaml:"extension,omitempty"`
}

ConcurrencySpec declares named resources whose claims can be enforced across nodes and runs by a host scheduler.

type Config 

type Config map[string]any

Config is opaque step-kind or host-extension configuration. Its schema and semantics belong to the registered adapter or extension implementation.

type DefinitionRef 

type DefinitionRef struct {
	Authority  string      `json:"authority,omitempty" yaml:"authority,omitempty"`
	Kind       string      `json:"kind,omitempty" yaml:"kind,omitempty"`
	ID         string      `json:"id,omitempty" yaml:"id,omitempty"`
	Locator    string      `json:"locator,omitempty" yaml:"locator,omitempty"`
	Version    string      `json:"version,omitempty" yaml:"version,omitempty"`
	Digest     string      `json:"digest,omitempty" yaml:"digest,omitempty"`
	Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`
}

DefinitionRef is an application-neutral reference to workflow source. A compiler or host resolves Locator and Version to Digest before execution.

type DurabilityMode 

type DurabilityMode string

DurabilityMode selects the workflow persistence contract. 

const (
	// DurabilityNone selects the validated non-durable subset.
	DurabilityNone DurabilityMode = "none"
	// DurabilitySteps persists node-level progress.
	DurabilitySteps DurabilityMode = "steps"
)

func (DurabilityMode) Valid 

func (m DurabilityMode) Valid() bool

Valid reports whether m is a supported durability mode.

type DurabilitySpec 

type DurabilitySpec struct {
	Mode      DurabilityMode `json:"mode" yaml:"mode"`
	Extension Extension      `json:"extension,omitempty" yaml:"extension,omitempty"`
}

DurabilitySpec selects the portable persistence mode. Runtime storage and continue-as-new mechanics remain outside the graph package.

type Duration 

type Duration string

Duration is a source-preserving duration such as "30s" or "24h". Runtime packages are responsible for parsing it at the appropriate binding boundary.

type Edge 

type Edge struct {
	From     string     `json:"from" yaml:"from"`
	To       string     `json:"to" yaml:"to"`
	Kind     EdgeKind   `json:"kind" yaml:"kind"`
	Source   *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
	Metadata Metadata   `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Edge is a normalized graph edge. Compilers may derive edges from Needs and bindings while preserving the declaration source.

type EdgeKind 

type EdgeKind string

EdgeKind identifies whether an edge exists for ordering or value visibility. 

const (
	// EdgeControl is an ordering-only dependency.
	EdgeControl EdgeKind = "control"
	// EdgeData permits downstream value visibility in addition to ordering.
	EdgeData EdgeKind = "data"
)

func (EdgeKind) Valid 

func (k EdgeKind) Valid() bool

Valid reports whether k is a supported edge kind.

type Effect 

type Effect string

Effect classifies the externally observable effect of a node. 

const (
	// EffectRead observes state without changing it.
	EffectRead Effect = "read"
	// EffectCompute performs deterministic or isolated computation.
	EffectCompute Effect = "compute"
	// EffectMaterialize creates derived artifacts or resources.
	EffectMaterialize Effect = "materialize"
	// EffectMutate changes existing external state.
	EffectMutate Effect = "mutate"
	// EffectDestructive removes or irreversibly changes external state.
	EffectDestructive Effect = "destructive"
)

func (Effect) Valid 

func (e Effect) Valid() bool

Valid reports whether e is a supported effect class.

type EffectSet 

type EffectSet []Effect

EffectSet is the declared set of effects for a graph node.

type EnumValidationError 

type EnumValidationError struct {
	Path  string
	Value string
}

EnumValidationError identifies an unsupported enum value and its graph path.

func (*EnumValidationError) Error 

func (e *EnumValidationError) Error() string

Error implements error.

type ExecutionTargetRequirements 

type ExecutionTargetRequirements struct {
	Kinds        []string          `json:"kinds,omitempty" yaml:"kinds,omitempty"`
	Capabilities []string          `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`
	Labels       map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
	Constraints  Config            `json:"constraints,omitempty" yaml:"constraints,omitempty"`
}

ExecutionTargetRequirements describes compute capabilities and labels required by a graph or node. It never identifies a Hadron run scope or workspace record.

type Expression 

type Expression struct {
	Text   string     `json:"text" yaml:"text"`
	Source *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
}

Expression is unevaluated expression-language source.

type Extension 

type Extension struct {
	Version  string     `json:"version,omitempty" yaml:"version,omitempty"`
	Config   Config     `json:"config,omitempty" yaml:"config,omitempty"`
	Source   *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
	Metadata Metadata   `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Extension reserves a versioned, application-neutral location for semantics implemented by a later engine or host capability.

type FinallySpec 

type FinallySpec struct {
	Scope []string `json:"scope,omitempty" yaml:"scope,omitempty"`
}

FinallySpec marks an ordinary node as cleanup for a declared graph scope. Empty Scope means the whole workflow.

type ForEachSpec 

type ForEachSpec struct {
	Items          Expression `json:"items" yaml:"items"`
	ItemName       string     `json:"item_name,omitempty" yaml:"item_name,omitempty"`
	IndexName      string     `json:"index_name,omitempty" yaml:"index_name,omitempty"`
	MaxConcurrency int        `json:"max_concurrency,omitempty" yaml:"max_concurrency,omitempty"`
	// FailFast prevents fan-out items that have not started from being admitted
	// after the first non-tolerated terminal item failure. Already-running items
	// still converge through their ordinary attempt lifecycle.
	FailFast bool                    `json:"fail_fast,omitempty" yaml:"fail_fast,omitempty"`
	Tolerate *ToleratedFailurePolicy `json:"tolerate,omitempty" yaml:"tolerate,omitempty"`
}

ForEachSpec describes runtime fan-out while keeping the graph static.

type Graph 

type Graph struct {
	ID           string                      `json:"id" yaml:"id"`
	Namespace    string                      `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Version      string                      `json:"version" yaml:"version"`
	Digest       string                      `json:"digest" yaml:"digest"`
	Provenance   Provenance                  `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	Inputs       []InputSpec                 `json:"inputs,omitempty" yaml:"inputs,omitempty"`
	Outputs      []OutputSpec                `json:"outputs,omitempty" yaml:"outputs,omitempty"`
	Nodes        []Node                      `json:"nodes" yaml:"nodes"`
	Edges        []Edge                      `json:"edges,omitempty" yaml:"edges,omitempty"`
	Activations  []ActivationDeclaration     `json:"activations,omitempty" yaml:"activations,omitempty"`
	Source       *SourceRef                  `json:"source,omitempty" yaml:"source,omitempty"`
	SourceMap    SourceMap                   `json:"source_map,omitempty" yaml:"source_map,omitempty"`
	Concurrency  ConcurrencySpec             `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
	Completion   *RunCompletionPolicy        `json:"completion,omitempty" yaml:"completion,omitempty"`
	Compensation *CompensationPolicy         `json:"compensation,omitempty" yaml:"compensation,omitempty"`
	Durability   *DurabilitySpec             `json:"durability,omitempty" yaml:"durability,omitempty"`
	Policy       []PolicyRequirement         `json:"policy_requirements,omitempty" yaml:"policy_requirements,omitempty"`
	Target       ExecutionTargetRequirements `json:"execution_target,omitempty" yaml:"execution_target,omitempty"`
	Extensions   map[string]Extension        `json:"extensions,omitempty" yaml:"extensions,omitempty"`
	Metadata     Metadata                    `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Graph is the canonical in-memory workflow graph shared by all engine frontends and hosts.

func (Graph) ValidateEnums 

func (g Graph) ValidateEnums() error

ValidateEnums validates only closed enum fields. It intentionally does not perform graph topology, reference, schema, or policy validation, which belong to compiler validation passes.

type IDValidationError 

type IDValidationError struct {
	ID         string
	Reason     string
	Normalized string
}

IDValidationError explains why an identifier is not canonical.

func (*IDValidationError) Error 

func (e *IDValidationError) Error() string

Error implements error.

type IdempotencyMode 

type IdempotencyMode string

IdempotencyMode describes how a node supports safe duplicate attempts. 

const (
	// IdempotencyNone makes no idempotency claim.
	IdempotencyNone IdempotencyMode = "none"
	// IdempotencyIntrinsic means the operation is inherently idempotent.
	IdempotencyIntrinsic IdempotencyMode = "intrinsic"
	// IdempotencyKeyed means the resolved key identifies duplicate operations.
	IdempotencyKeyed IdempotencyMode = "keyed"
)

func (IdempotencyMode) Valid 

func (m IdempotencyMode) Valid() bool

Valid reports whether m is a supported idempotency mode.

type IdempotencySpec 

type IdempotencySpec struct {
	Mode       IdempotencyMode `json:"mode" yaml:"mode"`
	Key        *Expression     `json:"key,omitempty" yaml:"key,omitempty"`
	Scope      string          `json:"scope,omitempty" yaml:"scope,omitempty"`
	Extensions Config          `json:"extensions,omitempty" yaml:"extensions,omitempty"`
}

IdempotencySpec records the declaration needed to reason about safe retry and recovery. Hosts and executors decide whether the claim is sufficient.

type InputSpec 

type InputSpec struct {
	Name        string     `json:"name" yaml:"name"`
	Description string     `json:"description,omitempty" yaml:"description,omitempty"`
	Schema      Schema     `json:"schema" yaml:"schema"`
	Required    bool       `json:"required,omitempty" yaml:"required,omitempty"`
	Default     *Binding   `json:"default,omitempty" yaml:"default,omitempty"`
	Source      *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
	Metadata    Metadata   `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

InputSpec declares a named, schema-bearing workflow input.

type MemoizationSpec 

type MemoizationSpec struct {
	Key          Expression `json:"key" yaml:"key"`
	MaxAge       Duration   `json:"max_age,omitempty" yaml:"max_age,omitempty"`
	OutputDigest string     `json:"output_digest,omitempty" yaml:"output_digest,omitempty"`
	Extension    Extension  `json:"extension,omitempty" yaml:"extension,omitempty"`
}

MemoizationSpec selects the exact cache-key, freshness bound, and optional output digest enforced by the runtime. The step kind's declared output schema is hashed into the compatible cache identity.

type Metadata 

type Metadata map[string]any

Metadata contains application-neutral descriptive data that does not change graph execution semantics.

type Need 

type Need struct {
	Node   string     `json:"node" yaml:"node"`
	Kind   EdgeKind   `json:"kind,omitempty" yaml:"kind,omitempty"`
	Source *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
}

Need declares an explicit ordering or data dependency on another node.

type Node 

type Node struct {
	ID            string                      `json:"id" yaml:"id"`
	DisplayName   string                      `json:"display_name,omitempty" yaml:"display_name,omitempty"`
	Kind          string                      `json:"kind" yaml:"kind"`
	KindVersion   string                      `json:"kind_version,omitempty" yaml:"kind_version,omitempty"`
	Needs         []Need                      `json:"needs,omitempty" yaml:"needs,omitempty"`
	ReadyWhen     ReadyRule                   `json:"ready_when,omitempty" yaml:"ready_when,omitempty"`
	If            *Expression                 `json:"if,omitempty" yaml:"if,omitempty"`
	ForEach       *ForEachSpec                `json:"for_each,omitempty" yaml:"for_each,omitempty"`
	Config        Config                      `json:"config,omitempty" yaml:"config,omitempty"`
	InputBindings map[string]Binding          `json:"with,omitempty" yaml:"with,omitempty"`
	Outputs       []OutputSpec                `json:"outputs,omitempty" yaml:"outputs,omitempty"`
	Effects       EffectSet                   `json:"effects,omitempty" yaml:"effects,omitempty"`
	Retry         *RetryPolicy                `json:"retry,omitempty" yaml:"retry,omitempty"`
	Idempotency   *IdempotencySpec            `json:"idempotency,omitempty" yaml:"idempotency,omitempty"`
	Timeout       *TimeoutPolicy              `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	Catch         []CatchRule                 `json:"catch,omitempty" yaml:"catch,omitempty"`
	Finally       *FinallySpec                `json:"finally,omitempty" yaml:"finally,omitempty"`
	Switch        *SwitchSpec                 `json:"switch,omitempty" yaml:"switch,omitempty"`
	Call          *CallSpec                   `json:"call,omitempty" yaml:"call,omitempty"`
	Concurrency   []ConcurrencyClaim          `json:"concurrency,omitempty" yaml:"concurrency,omitempty"`
	Verification  *VerificationSpec           `json:"verify,omitempty" yaml:"verify,omitempty"`
	Memoization   *MemoizationSpec            `json:"memoize,omitempty" yaml:"memoize,omitempty"`
	Durability    *DurabilitySpec             `json:"durability,omitempty" yaml:"durability,omitempty"`
	Service       *ServiceNodeSpec            `json:"service,omitempty" yaml:"service,omitempty"`
	Compensation  *CompensationSpec           `json:"compensation,omitempty" yaml:"compensation,omitempty"`
	Policy        []PolicyRequirement         `json:"policy_requirements,omitempty" yaml:"policy_requirements,omitempty"`
	Target        ExecutionTargetRequirements `json:"execution_target,omitempty" yaml:"execution_target,omitempty"`
	Source        *SourceRef                  `json:"source,omitempty" yaml:"source,omitempty"`
	Provenance    Provenance                  `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	Extensions    map[string]Extension        `json:"extensions,omitempty" yaml:"extensions,omitempty"`
	Metadata      Metadata                    `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Node is one executable or control-flow unit in a workflow graph.

type OutputSpec 

type OutputSpec struct {
	Name        string     `json:"name" yaml:"name"`
	Description string     `json:"description,omitempty" yaml:"description,omitempty"`
	Schema      Schema     `json:"schema" yaml:"schema"`
	Value       *Binding   `json:"value,omitempty" yaml:"value,omitempty"`
	Source      *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
	Metadata    Metadata   `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

OutputSpec declares a named, schema-bearing node or workflow output. Workflow outputs require Value. Node outputs omit Value for exact same-name adapter passthrough or set it to project the registered kind's raw outputs root.

type OverlapPolicy 

type OverlapPolicy string

OverlapPolicy controls overlapping source activations. 

const (
	// OverlapAllow permits overlapping runs.
	OverlapAllow OverlapPolicy = "allow"
	// OverlapForbid rejects a new activation while an earlier run is active.
	OverlapForbid OverlapPolicy = "forbid"
	// OverlapReplace replaces an earlier active run according to host policy.
	OverlapReplace OverlapPolicy = "replace"
)

func (OverlapPolicy) Valid 

func (p OverlapPolicy) Valid() bool

Valid reports whether p is a supported overlap policy.

type ParentClosePolicy 

type ParentClosePolicy string

ParentClosePolicy controls a child run when its parent closes. 

const (
	// ParentCloseCancel cancels the child with the parent.
	ParentCloseCancel ParentClosePolicy = "cancel"
	// ParentCloseAbandon leaves the child running.
	ParentCloseAbandon ParentClosePolicy = "abandon"
	// ParentCloseRequestCancel requests cancellation through the child host.
	ParentCloseRequestCancel ParentClosePolicy = "request_cancel"
)

func (ParentClosePolicy) Valid 

func (p ParentClosePolicy) Valid() bool

Valid reports whether p is a supported parent-close policy.

type PolicyRequirement 

type PolicyRequirement struct {
	Name       string `json:"name" yaml:"name"`
	Version    string `json:"version,omitempty" yaml:"version,omitempty"`
	Parameters Config `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

PolicyRequirement names a host-resolved policy or grant requirement without importing a concrete policy authority.

type Provenance 

type Provenance struct {
	Authority string          `json:"authority,omitempty" yaml:"authority,omitempty"`
	Origin    string          `json:"origin,omitempty" yaml:"origin,omitempty"`
	Locator   string          `json:"locator,omitempty" yaml:"locator,omitempty"`
	Revision  string          `json:"revision,omitempty" yaml:"revision,omitempty"`
	Digest    string          `json:"digest,omitempty" yaml:"digest,omitempty"`
	Parents   []ProvenanceRef `json:"parents,omitempty" yaml:"parents,omitempty"`
	Metadata  Metadata        `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Provenance explains the authority and immutable origin of graph material without depending on a host principal or registry type.

type ProvenanceRef 

type ProvenanceRef struct {
	Authority string `json:"authority,omitempty" yaml:"authority,omitempty"`
	Locator   string `json:"locator,omitempty" yaml:"locator,omitempty"`
	Digest    string `json:"digest,omitempty" yaml:"digest,omitempty"`
}

ProvenanceRef is a compact link to parent provenance.

type ReadyRule 

type ReadyRule string

ReadyRule selects dependency readiness behavior. 

const (
	// ReadyAllSuccess requires every dependency to succeed.
	ReadyAllSuccess ReadyRule = "all_success"
	// ReadyAllDone requires every dependency to reach a terminal state.
	ReadyAllDone ReadyRule = "all_done"
	// ReadyOneFailed requires at least one dependency to fail.
	ReadyOneFailed ReadyRule = "one_failed"
	// ReadyAllFailed requires every dependency to fail.
	ReadyAllFailed ReadyRule = "all_failed"
	// ReadyNoneFailed requires no dependency to fail.
	ReadyNoneFailed ReadyRule = "none_failed"
	// ReadyAlways ignores dependency outcomes after they become observable.
	ReadyAlways ReadyRule = "always"
)

func (ReadyRule) Valid 

func (r ReadyRule) Valid() bool

Valid reports whether r is a supported readiness rule.

type RetryPolicy 

type RetryPolicy struct {
	Attempts int           `json:"attempts" yaml:"attempts"`
	Backoff  BackoffPolicy `json:"backoff,omitempty" yaml:"backoff,omitempty"`
	On       []string      `json:"on,omitempty" yaml:"on,omitempty"`
}

RetryPolicy describes retry eligibility and backoff, independent of any concrete executor.

type RunCompletionMode 

type RunCompletionMode string

RunCompletionMode selects behavior after an unhandled branch failure. 

const (
	// CompletionFailFast stops or skips remaining eligible work according to policy.
	CompletionFailFast RunCompletionMode = "fail_fast"
	// CompletionRunToCompletion continues independent branches.
	CompletionRunToCompletion RunCompletionMode = "run_to_completion"
)

func (RunCompletionMode) Valid 

func (m RunCompletionMode) Valid() bool

Valid reports whether m is a supported run completion mode.

type RunCompletionPolicy 

type RunCompletionPolicy struct {
	Mode      RunCompletionMode `json:"mode" yaml:"mode"`
	Extension Extension         `json:"extension,omitempty" yaml:"extension,omitempty"`
}

RunCompletionPolicy selects fail-fast or run-to-completion behavior while retaining a versioned extension location for later details.

type RunIDReusePolicy 

type RunIDReusePolicy string

RunIDReusePolicy controls activation behavior when a run ID already exists. 

const (
	// RunIDReuseReject rejects an existing run ID.
	RunIDReuseReject RunIDReusePolicy = "reject"
	// RunIDReuseAllowDuplicate allows a duplicate logical activation.
	RunIDReuseAllowDuplicate RunIDReusePolicy = "allow_duplicate"
	// RunIDReuseTerminateExisting terminates the prior run before replacement.
	RunIDReuseTerminateExisting RunIDReusePolicy = "terminate_existing"
)

func (RunIDReusePolicy) Valid 

func (p RunIDReusePolicy) Valid() bool

Valid reports whether p is a supported run ID reuse policy.

type Schema 

type Schema map[string]any

Schema carries an inline JSON Schema. A reference-only schema uses the standard "$ref" key. The graph package does not interpret schema keywords.

type ServiceNodeSpec 

type ServiceNodeSpec struct {
	ReadyCheck       *VerificationSpec `json:"ready_check,omitempty" yaml:"ready_check,omitempty"`
	HeartbeatTimeout Duration          `json:"heartbeat_timeout,omitempty" yaml:"heartbeat_timeout,omitempty"`
	TeardownNodes    []string          `json:"teardown_nodes,omitempty" yaml:"teardown_nodes,omitempty"`
	// TeardownOf identifies the service-start node owned by this finally node.
	// It is empty on a service start and required on generated teardown nodes.
	TeardownOf string    `json:"teardown_of,omitempty" yaml:"teardown_of,omitempty"`
	Extension  Extension `json:"extension,omitempty" yaml:"extension,omitempty"`
}

ServiceNodeSpec reserves service readiness, heartbeat observation, and teardown references without introducing a separate scheduler.

type SourceFormat 

type SourceFormat string

SourceFormat identifies the frontend that produced graph material. 

const (
	// SourceWorkflow is the graph-native workflow source format.
	SourceWorkflow SourceFormat = "workflow"
	// SourceArchivedBlueprint is legacy blueprint reference material.
	SourceArchivedBlueprint SourceFormat = "archived-blueprint"
	// SourceArchivedPipeline is legacy pipeline reference material.
	SourceArchivedPipeline SourceFormat = "archived-pipeline"
	// SourceSDK is graph material emitted through an SDK.
	SourceSDK SourceFormat = "sdk"
	// SourceUI is graph material emitted through a user interface.
	SourceUI SourceFormat = "ui"
	// SourceAgent is graph material emitted by an agent authoring surface.
	SourceAgent SourceFormat = "agent"
)

func (SourceFormat) Valid 

func (f SourceFormat) Valid() bool

Valid reports whether f is a supported source format.

type SourceMap 

type SourceMap struct {
	Graph       *SourceRef           `json:"graph,omitempty" yaml:"graph,omitempty"`
	Inputs      map[string]SourceRef `json:"inputs,omitempty" yaml:"inputs,omitempty"`
	Outputs     map[string]SourceRef `json:"outputs,omitempty" yaml:"outputs,omitempty"`
	Nodes       map[string]SourceRef `json:"nodes,omitempty" yaml:"nodes,omitempty"`
	Edges       map[string]SourceRef `json:"edges,omitempty" yaml:"edges,omitempty"`
	Activations map[string]SourceRef `json:"activations,omitempty" yaml:"activations,omitempty"`
}

SourceMap gathers source locations by semantic graph element. ExecutionPlan compaction and persistence are compiler concerns, not graph behavior.

type SourceRef 

type SourceRef struct {
	Format      SourceFormat `json:"format" yaml:"format"`
	Locator     string       `json:"locator" yaml:"locator"`
	StartLine   int          `json:"start_line,omitempty" yaml:"start_line,omitempty"`
	StartColumn int          `json:"start_column,omitempty" yaml:"start_column,omitempty"`
	EndLine     int          `json:"end_line,omitempty" yaml:"end_line,omitempty"`
	EndColumn   int          `json:"end_column,omitempty" yaml:"end_column,omitempty"`
	Section     string       `json:"section,omitempty" yaml:"section,omitempty"`
	StepName    string       `json:"step_name,omitempty" yaml:"step_name,omitempty"`
	StageName   string       `json:"stage_name,omitempty" yaml:"stage_name,omitempty"`
	Path        []string     `json:"path,omitempty" yaml:"path,omitempty"`
}

SourceRef locates graph material in source authored by any supported frontend. Legacy source formats are reference-only formats.

type SwitchArm 

type SwitchArm struct {
	When    Expression `json:"when" yaml:"when"`
	Targets []string   `json:"targets" yaml:"targets"`
	Source  *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
}

SwitchArm is one ordered branch in a SwitchSpec.

type SwitchSpec 

type SwitchSpec struct {
	Arms    []SwitchArm `json:"arms" yaml:"arms"`
	Default []string    `json:"default,omitempty" yaml:"default,omitempty"`
}

SwitchSpec evaluates arms in order and selects the first matching branch.

type TimeoutPolicy 

type TimeoutPolicy struct {
	Queue           Duration `json:"queue,omitempty" yaml:"queue,omitempty"`
	Execution       Duration `json:"execution,omitempty" yaml:"execution,omitempty"`
	Wait            Duration `json:"wait,omitempty" yaml:"wait,omitempty"`
	Heartbeat       Duration `json:"heartbeat,omitempty" yaml:"heartbeat,omitempty"`
	ScheduleToClose Duration `json:"schedule_to_close,omitempty" yaml:"schedule_to_close,omitempty"`
}

TimeoutPolicy distinguishes queue, execution, wait, heartbeat, and total schedule-to-close deadlines.

type ToleratedFailurePolicy 

type ToleratedFailurePolicy struct {
	Count      int     `json:"count,omitempty" yaml:"count,omitempty"`
	Percentage float64 `json:"percentage,omitempty" yaml:"percentage,omitempty"`
}

ToleratedFailurePolicy permits an explicit count or percentage of fan-out item failures. A nil policy means unhandled item failure fails the fan-out.

type VerificationCheck 

type VerificationCheck struct {
	Kind   string     `json:"kind" yaml:"kind"`
	Config Config     `json:"config,omitempty" yaml:"config,omitempty"`
	Source *SourceRef `json:"source,omitempty" yaml:"source,omitempty"`
}

VerificationCheck identifies a registered verifier and keeps its config opaque to the graph package.

type VerificationSpec 

type VerificationSpec struct {
	Checks    []VerificationCheck `json:"checks,omitempty" yaml:"checks,omitempty"`
	Extension Extension           `json:"extension,omitempty" yaml:"extension,omitempty"`
}

VerificationSpec describes post-execution checks without importing verifier or provider implementations.

Source Files

View all Source files

Directories

Path Synopsis
internal
schemagen
Package schemagen generates the committed workflow graph JSON Schema from the graph package's Go types and enum declarations.
 Package schemagen generates the committed workflow graph JSON Schema from the graph package's Go types and enum declarations.
schemagen/cmd command
Package schema exposes the committed graph IR JSON Schema as a strict, extraction-safe validation boundary for SDK, UI, and agent front ends.
 Package schema exposes the committed graph IR JSON Schema as a strict, extraction-safe validation boundary for SDK, UI, and agent front ends.

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.