agent

package module
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package agent provides the Scope Agent Framework execution kernel.

Definition owns immutable behavior and creates serializable Execution values; Engine owns Process lifecycle, Signal delivery, Effect dispatch, child composition, resource bounds, observation, and portable snapshots. Strategy payloads stay opaque to the kernel, and persistence stays a caller responsibility.

The kernel exists for one purpose: a multi-step agent with children and external side effects must resume after a process restart with a stated meaning for every operation that was in flight. Everything below follows from that.

The execution waist

Every strategy intersects on exactly two interfaces: 

type Definition interface {
	Descriptor() Descriptor
	Start(Input) (Execution, error)
	Restore(ExecutionState) (Execution, error)
}

type Execution interface {
	Step(context.Context, []Signal) (Transition, error)
	Snapshot() (ExecutionState, error)
}

The waist is not generic, because the Engine holds heterogeneous definitions homogeneously. Input, Output, Signal, Effect, and ExecutionState cross it as bounded, defensively copied JSON. Generics belong to edge adapters that convert a Go input to raw input and raw output back to a Go output; they never enter the contract the Engine has to hold.

Step

A Step is one cancellable, discardable, purely candidate reduction. It may not call a model, run a tool, perform any other external I/O, hide an unbounded loop, or start an unowned goroutine. An external operation can only be declared as an Effect and executed outside the Step.

Three scales explain the kernel: the root tree is the consistency, commit, and recovery unit; a Process is the lifecycle and strategy-state isolation unit; a Step is the concurrency unit. Adding Processes to a tree adds isolated computation and external I/O concurrency, not authoritative commit parallelism. Independent commit throughput means separate root trees.

Each root tree has one private commit owner. Pure computation does not occupy the owner line: a Process has at most one Step job in flight and siblings run in parallel. Only the owner revalidates and adopts a result. When a kill, pause, cancel, or a new incarnation expires an attempt, the result and its error are discarded whole and the Execution is rebuilt from last-stable state.

Effects and settlement

An Effect is the only way an Execution requests work outside a Step. The Engine derives a stable effect identity from the Process identity, step sequence, and effect index, then freezes the payload. It interprets only its own closed set of framework effects — child, wait, timer — and hands a strategy effect whole to the dispatcher its Deployment bound. A dispatcher never mutates an Execution; it produces deltas and one settlement Signal.

Each effect advances through planned, pending, and settled in declaration order, one at a time:

  1. the owner validates candidate state, signal consumption, budget, capability, and batch identity;
  2. the effect enters pending, and in durable mode the pending boundary commits the whole tree first;
  3. only then does the dispatcher job start, outside the owner;
  4. the result is normalized to a definite or an unknown settlement;
  5. only after the settled boundary succeeds does the owner install the settlement, candidate state, mailbox, and Process transition.

A planned effect that was never dispatched can never become unknown. Automatic redelivery is allowed only where replaying one effect identity is proven to be the same logical operation; where it is not, an unknown settlement stays observable and awaits explicit adjudication. It is never silently replayed and never assumed successful. Ephemeral mode runs the same state machine without calling the durability port.

Signals and waiting

A Signal is the only runtime input into an Execution. Repeated submission of one signal identity produces exactly one logical consumption. The consumption cursor advances only when candidate state and transition commit, so a failed Step never permanently swallows input.

A wait identity is minted by the Engine; an Execution cannot generate an external one. The Execution declares a logical wait through a Transition; the Engine saves the mapping and enqueues an internal Signal carrying the identity; on the next Step the Execution records it and enters Waiting explicitly. That round trip keeps the Execution the single writer of its own state. The Engine wall clock never enters strategy input — business time is submitted as an explicit payload.

Each strategy declares its own safe consumption boundary and proves it with contract tests.

Process lifecycle

A Process moves through StatusNotStarted, StatusRunning, and then one of StatusWaiting, StatusPaused, StatusCompleted, StatusFailed, StatusCanceled, StatusTimedOut, or StatusKilled.

A terminal state is decided jointly by the recorded control intent and the Step result, never inferred from error text or from context.Canceled alone. The matrix is matched in priority order: an explicit kill wins; then a reached deadline; then parent or host cancellation; then a contract violation, external failure, or panic; then legal completion. A committed terminal state is first-terminal-wins, so a late cancellation cannot overwrite it. An effect's own cancellation first reaches the strategy as a settlement Signal — a local failure is never promoted to a Process terminal state on its own.

Recovery

ExecutionState is a discriminated envelope of a kind and an opaque payload. The kernel constrains the envelope and never interprets the payload recursively; each strategy owns and guards its own wire shape. A host may persist the envelope but must not parse it by kind and join strategy control flow. Recovery finds the Definition through an exact DeploymentRef; a global kind-to-factory switch is forbidden.

TreeSnapshot is the canonical recovery state of a complete root tree. ProcessSnapshot is a single-Process diagnostic value and is not a recovery unit. Events and Delta values record attempts and observations only; they never substitute for an acknowledged TreeSnapshot.

Strategies

Three strategies run on this one kernel. The interaction package implements ReAct-style model and tool loops with working context, delegates, and artifacts. The planning package, with planning/goap, implements goal-driven search over immutable actions. The workflow package implements ordered deterministic stages over a closed vocabulary, composing through real child Processes rather than by nesting a second Execution.

The Engine never imports or type-switches a concrete strategy. A new strategy is admitted by implementing the waist plus its own dispatcher, codec, and safe consumption boundary.

Boundaries

The framework owns definition validation, deployment freezing, the Process state machine, signal ordering and deduplication, effect identity and settlement, budgets, the lifecycle, framework events, and the snapshot and recovery protocol.

The host owns product identity, transports, stores and transactions, permissions and billing, provider and model selection, when a checkpoint commits, and the retention of its own facts. A host depends only on this neutral lifecycle contract and never parses a strategy's snapshot payload.

Chat, tools, embeddings, history, and telemetry stay in their own modules. Agent reuses them and duplicates none of them.

Index

Examples

Constants

View Source 
const (
	// EventProcessStarted reports initial Process execution.
	EventProcessStarted = "agent.process.started"
	// EventProcessRestored reports execution resumed from a TreeSnapshot.
	EventProcessRestored = "agent.process.restored"
	// EventProcessPaused reports a committed scheduling pause.
	EventProcessPaused = "agent.process.paused"
	// EventProcessResumed reports committed scheduling resumption.
	EventProcessResumed = "agent.process.resumed"
	// EventProcessFinished reports one immutable terminal outcome.
	EventProcessFinished = "agent.process.finished"
	// EventSignalAccepted reports one newly accepted Signal.
	EventSignalAccepted = "agent.signal.accepted"
	// EventStepStarted reports an Execution.Step call about to begin.
	EventStepStarted = "agent.step.started"
	// EventStepFinished reports an Execution.Step return or failure.
	EventStepFinished = "agent.step.finished"
	// EventStepPrepared reports validated candidate Step state and fixed Effects.
	EventStepPrepared = "agent.step.prepared"
	// EventStepCommitted reports authoritative Step state publication.
	EventStepCommitted = "agent.step.committed"
	// EventEffectStarted reports a Framework or Dispatcher Effect attempt.
	EventEffectStarted = "agent.effect.started"
	// EventEffectFinished reports a definite or unknown attempt settlement.
	EventEffectFinished = "agent.effect.finished"
	// EventDeltaDropped reports best-effort increments lost to backpressure.
	EventDeltaDropped = "agent.delta.dropped"
)

Variables

View Source 
var (
	ErrInvalidEngineConfig         = errors.New("agent: invalid engine configuration")
	ErrEngineClosed                = errors.New("agent: engine is closed")
	ErrEngineQuiescenceUnavailable = errors.New("agent: engine cannot become quiescent")
	ErrEngineHasActiveProcesses    = errors.New("agent: engine has active processes")
	ErrProcessAlreadyExists        = errors.New("agent: process identity already exists")
)
View Source 
var (
	ErrProcessFinished       = errors.New("agent: process has finished")
	ErrProcessNotRunning     = errors.New("agent: process is not running")
	ErrEffectNotPending      = errors.New("agent: effect does not require resolution")
	ErrInvalidProcessControl = errors.New("agent: invalid process control request")
)
View Source 
var (
	// ErrDurabilityConflict reports that an idempotency key was previously
	// committed with different content.
	ErrDurabilityConflict = errors.New("agent: durability boundary conflicts with committed content")
	// ErrTreeIncarnationConflict reports that a writer no longer owns the
	// authoritative tree head it attempted to advance.
	ErrTreeIncarnationConflict = errors.New("agent: tree incarnation conflict")
	// ErrTreeDurabilityMismatch reports an attempt to restore a durable tree in
	// an ephemeral Engine, or an ephemeral tree in a durable Engine.
	ErrTreeDurabilityMismatch = errors.New("agent: tree durability mode mismatch")
	// ErrTreeCaptureUnavailable reports that a durable tree cannot be captured
	// through the ephemeral, caller-driven checkpoint API.
	ErrTreeCaptureUnavailable = errors.New("agent: tree capture is unavailable in durable mode")
)
View Source 
var (
	ErrInvalidTreeSnapshot            = errors.New("agent: invalid process tree snapshot")
	ErrUnsupportedTreeSnapshotVersion = errors.New("agent: unsupported process tree snapshot version")
)
View Source 
var (
	ErrInvalidPreparedWaitingSubtreeCancellation = errors.New("agent: invalid prepared waiting subtree cancellation")

	ErrPreparedWaitingSubtreeCancellationResolved = errors.New("agent: prepared waiting subtree cancellation is resolved")

	ErrWaitingSubtreeCancellationUnavailable = errors.New("agent: waiting subtree cancellation is unavailable")
)
View Source 
var (
	ErrInvalidInput  = errors.New("agent: invalid input")
	ErrInvalidOutput = errors.New("agent: invalid output")
)
View Source 
var ErrInvalidCapability = errors.New("agent: invalid capability")
View Source 
var ErrInvalidChildStart = errors.New("agent: invalid child process start")
View Source 
var ErrInvalidChildWait = errors.New("agent: invalid child wait")
View Source 
var ErrInvalidDelta = errors.New("agent: invalid delta")
View Source 
var ErrInvalidDeployment = errors.New("agent: invalid deployment")
View Source 
var ErrInvalidDeploymentRef = errors.New("agent: invalid deployment reference")
View Source 
var ErrInvalidDescriptor = errors.New("agent: invalid descriptor")
View Source 
var ErrInvalidDigest = errors.New("agent: invalid digest")
View Source 
var ErrInvalidEffect = errors.New("agent: invalid effect")
View Source 
var ErrInvalidEvent = errors.New("agent: invalid event")
View Source 
var ErrInvalidExecutionState = errors.New("agent: invalid execution state")
View Source 
var ErrInvalidFailure = errors.New("agent: invalid failure")
View Source 
var ErrInvalidIdentity = errors.New("agent: invalid identity")
View Source 
var ErrInvalidProcessRelation = errors.New("agent: invalid process relation")
View Source 
var ErrInvalidSchema = errors.New("agent: invalid schema")
View Source 
var ErrInvalidSettlement = errors.New("agent: invalid effect settlement")
View Source 
var ErrInvalidSignal = errors.New("agent: invalid signal")
View Source 
var ErrInvalidSignalRequest = errors.New("agent: invalid signal request")
View Source 
var ErrInvalidSnapshot = errors.New("agent: invalid process snapshot")
View Source 
var ErrInvalidStatus = errors.New("agent: invalid status")
View Source 
var ErrInvalidTransition = errors.New("agent: invalid transition")
View Source 
var ErrInvalidTreeIncarnationID = errors.New("agent: invalid tree incarnation identity")
View Source 
var ErrProcessAdmissionRejected = errors.New("agent: process admission rejected")

ErrProcessAdmissionRejected marks failure at the policy boundary before execution starts.

View Source 
var ErrResourceLimitExceeded = errors.New("agent: resource limit exceeded")

ErrResourceLimitExceeded reports a designed execution bound, not an Engine defect.

View Source 
var (
	ErrSignalRejected = errors.New("agent: signal rejected")
)

Functions

This section is empty.

Types

type Budget 

type Budget struct {
	// Steps is the maximum committed Step count allocated to the child.
	Steps uint64 `json:"steps"`
	// Effects is the maximum prepared Effect count allocated to the child.
	Effects uint64 `json:"effects"`
	// Signals is the maximum accepted Signal count allocated to the child.
	Signals uint64 `json:"signals"`
}

Budget is a non-renewable allocation of Framework-owned work units. A child allocation is permanently transferred from its parent's remaining budget; unused units are not silently reclaimed or duplicated.

func NewBudget 

func NewBudget(config BudgetConfig) (Budget, error)

NewBudget validates the bounds together, because a budget is attenuated when it passes to a child and an unvalidated zero would read as unlimited at exactly the point authority is meant to narrow.

func (Budget) Valid 

func (b Budget) Valid() bool

type BudgetConfig added in v0.13.0 

type BudgetConfig struct {
	Steps   uint64
	Effects uint64
	Signals uint64
}

BudgetConfig names each bound so a call site cannot transpose them. Three positional counts of the same type are indistinguishable to the compiler, and a swapped pair produces a Process that runs far longer or dies far sooner than intended.

type Capability 

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

Capability is one stable qualified authority name understood by a Deployment's dispatcher or another external boundary. The Framework only enforces possession and attenuation; it does not assign product meaning.

func ParseCapability 

func ParseCapability(name string) (Capability, error)

ParseCapability validates a lowercase qualified capability name.

func (Capability) MarshalText 

func (c Capability) MarshalText() ([]byte, error)

func (Capability) String 

func (c Capability) String() string

func (*Capability) UnmarshalText 

func (c *Capability) UnmarshalText(text []byte) error

func (Capability) Valid 

func (c Capability) Valid() bool

type CapabilitySet 

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

CapabilitySet is an immutable, sorted set of authority names. Its zero value is the valid empty set.

func NewCapabilitySet 

func NewCapabilitySet(capabilities ...Capability) (CapabilitySet, error)

NewCapabilitySet builds the frozen grant a Process runs under. It is a set rather than a slice because a duplicated or reordered grant must not change authority, and because every child grant must be a subset of its parent's.

func (CapabilitySet) Allows 

func (c CapabilitySet) Allows(requested CapabilitySet) bool

Allows reports whether requested is a subset of c.

func (CapabilitySet) Contains 

func (c CapabilitySet) Contains(capability Capability) bool

Contains reports whether capability belongs to the set.

func (CapabilitySet) MarshalJSON 

func (c CapabilitySet) MarshalJSON() ([]byte, error)

func (*CapabilitySet) UnmarshalJSON 

func (c *CapabilitySet) UnmarshalJSON(data []byte) error

func (CapabilitySet) Valid 

func (c CapabilitySet) Valid() bool

func (CapabilitySet) Values 

func (c CapabilitySet) Values() []Capability

Values returns an independently owned, sorted capability slice.

type ChildKey 

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

ChildKey is an Execution-owned stable identity for one logical child start. The Engine combines it with the parent Process identity and prepared Effect identity to make retries and restoration idempotent.

func ParseChildKey 

func ParseChildKey(value string) (ChildKey, error)

ParseChildKey validates an Execution-owned logical child identity.

func (ChildKey) MarshalText 

func (c ChildKey) MarshalText() ([]byte, error)

func (ChildKey) String 

func (c ChildKey) String() string

func (*ChildKey) UnmarshalText 

func (c *ChildKey) UnmarshalText(text []byte) error

func (ChildKey) Valid 

func (c ChildKey) Valid() bool

type ChildOutcome 

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

ChildOutcome pairs a parent's logical ChildKey with one immutable terminal Process Result.

func (ChildOutcome) Key 

func (c ChildOutcome) Key() ChildKey

Key returns the parent-scoped logical child identity.

func (ChildOutcome) Result 

func (c ChildOutcome) Result() Result

Result returns the child's immutable terminal result.

func (ChildOutcome) Valid 

func (c ChildOutcome) Valid() bool

type ChildSpec 

type ChildSpec struct {
	// Key is the parent-scoped logical identity of this child start.
	Key ChildKey `json:"key"`
	// DeploymentRef identifies the exact child behavior binding.
	DeploymentRef DeploymentRef `json:"deployment_ref"`
	// Input is the portable input validated by the target Descriptor.
	Input Input `json:"input"`
	// Budget is permanently allocated from the parent to this child.
	Budget Budget `json:"budget"`
	// Capabilities is the attenuated authority granted to this child.
	Capabilities CapabilitySet `json:"capabilities"`
}

ChildSpec is the complete Strategy-declared intent for one child Process. Input is validated by the target Deployment before any Process is created.

func (ChildSpec) Valid 

func (c ChildSpec) Valid() bool

type ChildStartResult 

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

ChildStartResult is the definite result of one StartChild Effect. Success contains the Engine-created child ProcessID; failure contains a stable Framework Failure and never masquerades as an unknown external outcome.

func ParseChildStartResult 

func ParseChildStartResult(signal Signal) (ChildStartResult, error)

ParseChildStartResult decodes a Framework-owned child-start settlement Signal. The Signal must not address a wait.

func (ChildStartResult) DeploymentRef 

func (c ChildStartResult) DeploymentRef() DeploymentRef

DeploymentRef returns the exact child execution binding.

func (ChildStartResult) Failure 

func (c ChildStartResult) Failure() (Failure, bool)

Failure returns the definite start failure and true when no child was created.

func (ChildStartResult) Key 

func (c ChildStartResult) Key() ChildKey

Key returns the logical child identity declared by the Execution.

func (ChildStartResult) ProcessID 

func (c ChildStartResult) ProcessID() (ProcessID, bool)

ProcessID returns the created child identity and true on success.

func (ChildStartResult) Valid 

func (c ChildStartResult) Valid() bool

type ChildWaitCondition 

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

ChildWaitCondition identifies when a set of child Processes releases its parent. It describes completion count only; it does not imply cancellation of unfinished children or reinterpret child terminal statuses.

func AllChildren 

func AllChildren() ChildWaitCondition

AllChildren waits until every named child is terminal.

func AnyChild 

func AnyChild() ChildWaitCondition

AnyChild waits until at least one named child is terminal.

func ChildQuorum 

func ChildQuorum(count uint32) (ChildWaitCondition, error)

ChildQuorum waits until count named children are terminal.

func (ChildWaitCondition) Valid 

func (c ChildWaitCondition) Valid() bool

type ChildWaitOpened 

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

ChildWaitOpened is the definite acknowledgement that the Engine registered a child wait and minted its WaitID.

func ParseChildWaitOpened 

func ParseChildWaitOpened(signal Signal) (ChildWaitOpened, error)

ParseChildWaitOpened decodes the settlement Signal produced by WaitForChildren and verifies its Engine-attached WaitID.

func (ChildWaitOpened) Spec 

func (c ChildWaitOpened) Spec() ChildWaitSpec

Spec returns the immutable child-wait request acknowledged by Engine.

func (ChildWaitOpened) Valid 

func (c ChildWaitOpened) Valid() bool

func (ChildWaitOpened) WaitID 

func (c ChildWaitOpened) WaitID() WaitID

WaitID returns the Engine-minted wait identity to store in Execution state.

type ChildWaitSpec 

type ChildWaitSpec struct {
	// Key is the Execution-owned logical identity of this wait request.
	Key WaitKey
	// Children lists direct child identities in result order.
	Children []ProcessID
	// Condition declares how many listed children must become terminal.
	Condition ChildWaitCondition
}

ChildWaitSpec names one stable logical wait, its direct children in result order, and the completion predicate.

func (ChildWaitSpec) Valid 

func (c ChildWaitSpec) Valid() bool

type ChildrenCompleted 

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

ChildrenCompleted is one condition-satisfying, request-ordered child result set. For any or quorum it includes every child already terminal at the atomic satisfaction check, without canceling or omitting based on status.

func ParseChildrenCompleted 

func ParseChildrenCompleted(signal Signal) (ChildrenCompleted, error)

ParseChildrenCompleted decodes an Engine-generated, WaitID-addressed child completion Signal.

func (ChildrenCompleted) Key 

func (c ChildrenCompleted) Key() WaitKey

Key returns the logical wait key declared by the Execution.

func (ChildrenCompleted) Outcomes 

func (c ChildrenCompleted) Outcomes() []ChildOutcome

Outcomes returns terminal children in the original ChildWaitSpec order.

func (ChildrenCompleted) Valid 

func (c ChildrenCompleted) Valid() bool

func (ChildrenCompleted) WaitID 

func (c ChildrenCompleted) WaitID() WaitID

WaitID returns the addressed wait identity.

type Definition 

type Definition interface {
	// Descriptor returns the immutable, portable contract shared by every
	// Execution created from this definition. Repeated and concurrent calls must
	// return an equivalent value; runtime configuration and mutable state do not
	// belong in the descriptor.
	Descriptor() Descriptor
	// Start validates input against Descriptor and creates a fresh, isolated
	// Execution without performing external I/O. The returned Execution has not
	// executed a Step and must not share mutable state with another Process.
	Start(input Input) (Execution, error)
	// Restore reconstructs one Execution from a state previously produced by
	// Snapshot for this exact definition. It must reject malformed state and
	// state belonging to another contract; restoration must
	// not replay external work.
	Restore(state ExecutionState) (Execution, error)
}

Definition is an immutable Agent behavior definition. Its methods may be called concurrently for different Processes. Implementations create a fresh Execution from validated Input or restore one from their own opaque ExecutionState. Definition methods must not depend on Host product identities, storage protocols, or mutable global registration.

type Delta 

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

Delta is a bounded, best-effort stream increment from one Effect attempt. EffectSequence preserves producer order. Delta is never replayed from a snapshot and never contributes to the authoritative final Output.

func (Delta) EffectID 

func (d Delta) EffectID() EffectID

EffectID returns the Effect attempt that emitted the increment.

func (Delta) EffectSequence 

func (d Delta) EffectSequence() uint64

EffectSequence returns the one-based producer order within the Effect attempt.

func (Delta) EmittedAt 

func (d Delta) EmittedAt() time.Time

EmittedAt returns when the producer emitted the increment.

func (Delta) MarshalJSON 

func (d Delta) MarshalJSON() ([]byte, error)

func (Delta) Payload 

func (d Delta) Payload() json.RawMessage

Payload returns an independently owned Strategy-defined increment.

func (Delta) ProcessID 

func (d Delta) ProcessID() ProcessID

ProcessID returns the Process that owns the Effect attempt.

func (Delta) TreeIncarnationID 

func (d Delta) TreeIncarnationID() (TreeIncarnationID, bool)

TreeIncarnationID returns the active durable writer that emitted this delta. Deltas from ephemeral trees return false.

func (*Delta) UnmarshalJSON 

func (d *Delta) UnmarshalJSON(data []byte) error

func (Delta) Valid 

func (d Delta) Valid() bool

type DeltaDroppedFact 

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

DeltaDroppedFact reports the number of increments rejected during one Effect attempt because validation failed or the bounded observation queue was full.

func (DeltaDroppedFact) Count 

func (d DeltaDroppedFact) Count() uint64

func (DeltaDroppedFact) Valid 

func (d DeltaDroppedFact) Valid() bool

type DeltaEmitter 

type DeltaEmitter func(payload json.RawMessage)

DeltaEmitter accepts Strategy-owned streaming payloads while Dispatch is active. The Engine validates, orders, bounds, and publishes each payload as a best-effort Delta. It intentionally returns no observer error. A Dispatcher must not retain or call it after Dispatch returns.

type DeltaListener 

type DeltaListener interface {
	// OnDelta receives an accepted best-effort increment in queue order. Delivery
	// is sequential per listener but may lag Process execution; slow callbacks can
	// cause later increments to be dropped. The callback cannot affect execution.
	OnDelta(ctx context.Context, delta Delta)
}

DeltaListener observes best-effort Strategy streaming increments. Panics are isolated; slow listeners may cause bounded queue drops.

type DeltaListenerFunc 

type DeltaListenerFunc func(ctx context.Context, delta Delta)

DeltaListenerFunc adapts a plain function to the delta listener interface. It returns nothing for the same reason as EventListenerFunc, and because a dropped delta must never change execution.

func (DeltaListenerFunc) OnDelta 

func (d DeltaListenerFunc) OnDelta(ctx context.Context, delta Delta)

type Deployment 

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

Deployment is an immutable binding of one Definition, its Strategy-owned Dispatcher, and an exact value reference used by Process snapshots.

func NewDeployment 

func NewDeployment(config DeploymentConfig) (Deployment, error)

NewDeployment freezes a Definition and Dispatcher under explicit implementation and configuration digests. That binding lets recovery resolve the exact behavior a snapshot names instead of whatever now answers to the same Definition name.

func (Deployment) Definition 

func (d Deployment) Definition() Definition

Definition returns the erased behavior definition bound to this Deployment.

func (Deployment) DeploymentRef 

func (d Deployment) DeploymentRef() DeploymentRef

DeploymentRef returns the exact value identity stored in Process snapshots.

func (Deployment) Descriptor 

func (d Deployment) Descriptor() Descriptor

Descriptor returns the frozen static Definition contract.

func (Deployment) Valid 

func (d Deployment) Valid() bool

type DeploymentConfig 

type DeploymentConfig struct {
	// Definition owns the Strategy contract and creates per-Process execution.
	Definition Definition

	// Dispatcher interprets only Effects emitted by this Definition.
	Dispatcher Dispatcher

	// ImplementationDigest identifies the exact executable Definition artifact.
	ImplementationDigest Digest

	// ConfigurationDigest identifies all frozen behavior-affecting Definition
	// and Dispatcher configuration.
	ConfigurationDigest Digest
}

DeploymentConfig contains the complete behavior binding of one Deployment. The digests must cover the exact code artifact and all frozen dispatcher or Strategy configuration that can affect execution or restoration.

type DeploymentRef 

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

DeploymentRef is the immutable value identity of one exact Definition implementation and frozen execution configuration. It contains no registry pointer and is sufficient to reject restore against a different Deployment.

func (DeploymentRef) ConfigurationDigest 

func (d DeploymentRef) ConfigurationDigest() Digest

ConfigurationDigest returns the frozen behavior-affecting configuration identity, including dispatcher configuration.

func (DeploymentRef) ContractDigest 

func (d DeploymentRef) ContractDigest() Digest

ContractDigest returns the exact Descriptor contract identity.

func (DeploymentRef) Digest 

func (d DeploymentRef) Digest() Digest

Digest returns the complete Deployment value identity.

func (DeploymentRef) ImplementationDigest 

func (d DeploymentRef) ImplementationDigest() Digest

ImplementationDigest returns the exact executable implementation identity.

func (DeploymentRef) MarshalJSON 

func (d DeploymentRef) MarshalJSON() ([]byte, error)

func (DeploymentRef) Name 

func (d DeploymentRef) Name() string

Name returns the stable Definition name.

func (DeploymentRef) String 

func (d DeploymentRef) String() string

func (*DeploymentRef) UnmarshalJSON 

func (d *DeploymentRef) UnmarshalJSON(data []byte) error

func (DeploymentRef) Valid 

func (d DeploymentRef) Valid() bool

type DeploymentResolver 

type DeploymentResolver interface {
	// Resolve returns the immutable binding for exactly reference. It must not
	// fall back by name, perform routing or remote discovery, or retain
	// caller state. Missing and mismatched bindings are errors; concurrent calls
	// must be safe.
	Resolve(reference DeploymentRef) (Deployment, error)
}

DeploymentResolver performs one bounded, deterministic, context-free lookup of an exact immutable Deployment. The Engine accepts only a result whose reference exactly matches the requested reference. Implementations must be safe for concurrent use, must not perform remote I/O, and must not re-enter any Process. Routing and caller-specific selection happen before an exact DeploymentRef reaches this contract.

type Descriptor 

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

Descriptor is an immutable Definition contract. It contains no executable behavior or Deployment configuration.

func NewDescriptor 

func NewDescriptor(config DescriptorConfig) (Descriptor, error)

NewDescriptor validates the schemas at construction because they enter the Deployment digest. A schema accepted here and rejected later would change a Deployment's identity after Processes had already been started against it.

Example 
package main

import (
	"fmt"

	"github.com/Tangerg/scope/agent"
)

func main() {
	schema, err := agent.SchemaFor[string]()
	if err != nil {
		panic(err)
	}
	descriptor, err := agent.NewDescriptor(agent.DescriptorConfig{
		Name:         "example.echo",
		Description:  "Returns the supplied text.",
		InputSchema:  schema,
		OutputSchema: schema,
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(descriptor.Name(), descriptor.Valid())
}

Output:
example.echo true

func (Descriptor) DecodeOutput 

func (d Descriptor) DecodeOutput[T any](output Output) (T, error)

DecodeOutput validates output against this Descriptor's authoritative output schema and strictly decodes it into T.

func (Descriptor) Description 

func (d Descriptor) Description() string

Description returns the human-readable purpose of the Definition.

func (Descriptor) Digest 

func (d Descriptor) Digest() Digest

Digest returns the SHA-256 identity of the complete descriptor contract.

func (Descriptor) EncodeInput 

func (d Descriptor) EncodeInput[T any](value T) (Input, error)

EncodeInput converts value into an Input and validates it against this Descriptor's authoritative input schema.

func (Descriptor) InputSchema 

func (d Descriptor) InputSchema() Schema

InputSchema returns an independently owned schema value.

func (Descriptor) MarshalJSON 

func (d Descriptor) MarshalJSON() ([]byte, error)

func (Descriptor) Name 

func (d Descriptor) Name() string

Name returns the stable Definition name.

func (Descriptor) OutputSchema 

func (d Descriptor) OutputSchema() Schema

OutputSchema returns an independently owned schema value.

func (*Descriptor) UnmarshalJSON 

func (d *Descriptor) UnmarshalJSON(data []byte) error

func (Descriptor) Valid 

func (d Descriptor) Valid() bool

func (Descriptor) ValidateInput 

func (d Descriptor) ValidateInput(input Input) error

func (Descriptor) ValidateOutput 

func (d Descriptor) ValidateOutput(output Output) error

type DescriptorConfig 

type DescriptorConfig struct {
	// Name is a stable lowercase qualified Definition name.
	Name string

	// Description states the Definition's behavior for human and model-facing
	// discovery without execution-specific state.
	Description string

	// InputSchema is the authoritative structural contract for Process input.
	InputSchema Schema

	// OutputSchema is the authoritative structural contract for completed output.
	OutputSchema Schema
}

DescriptorConfig contains the complete static contract of a Definition. Executable implementation and frozen configuration identity belong to a Deployment, not this contract.

type Digest 

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

Digest is a canonical SHA-256 content identity. Its zero value is invalid.

func ComputeDigest 

func ComputeDigest(data []byte) Digest

ComputeDigest returns the canonical SHA-256 identity of data. Callers that assemble a Deployment use it for reproducible implementation artifacts and canonical frozen configuration bytes.

func ParseDigest 

func ParseDigest(value string) (Digest, error)

ParseDigest validates a canonical sha256:<lowercase-hex> identity.

func (Digest) MarshalText 

func (d Digest) MarshalText() ([]byte, error)

func (Digest) String 

func (d Digest) String() string

func (*Digest) UnmarshalText 

func (d *Digest) UnmarshalText(text []byte) error

func (Digest) Valid 

func (d Digest) Valid() bool

type Dispatcher 

type Dispatcher interface {
	// Dispatch performs one frozen Strategy Effect outside Execution.Step.
	// Settlement must address request.ID; a non-nil error means the external
	// outcome is unknown, not definitely failed. emit is valid only during this
	// call. Implementations honor ctx and may be called concurrently.
	Dispatch(ctx context.Context, request EffectRequest, emit DeltaEmitter) (Settlement, error)
	// ReplayPolicy declares, without I/O or mutable side effects, whether this
	// exact Effect can be repeated under its original EffectID after an unknown
	// settlement. The answer must be deterministic for equivalent Effects.
	ReplayPolicy(effect Effect) ReplayPolicy
}

Dispatcher executes Strategy-owned Effects outside Execution.Step. It must return a Settlement addressed to request.ID. A returned error means the Engine cannot prove the external result and records an unknown settlement. The same Dispatcher may serve Processes concurrently; implementations must be concurrency-safe, return in bounded time, not mutate an Execution, and not start unowned goroutines. ReplayPolicy must be a pure, deterministic declaration for the supplied immutable Effect.

type Effect 

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

Effect is an immutable request for an operation outside Execution.Step. Payload is frozen before dispatch and interpreted only by Target's owner. EffectID is deliberately absent because the Engine assigns it during prepare.

func NewDispatcherEffect 

func NewDispatcherEffect(payload json.RawMessage, required ...Capability) (Effect, error)

NewDispatcherEffect carries an opaque payload plus the capabilities it requires, so the Engine can refuse an effect the Process was never granted without understanding what the effect does. Keeping the payload opaque is what stops model and tool vocabulary from entering the kernel.

func RequestWait 

func RequestWait(key WaitKey, signalPayload json.RawMessage) (Effect, error)

RequestWait creates the Framework Effect that asks the Engine to mint one WaitID for key. signalPayload remains Strategy-owned and is returned unchanged in the internal Signal that carries the minted WaitID back to the Execution.

func StartChild 

func StartChild(spec ChildSpec) (Effect, error)

StartChild creates a Framework-owned Effect requesting one independently managed child Process. The Engine derives the child ProcessID; Execution code cannot construct or start the Process directly.

func WaitForChildren 

func WaitForChildren(spec ChildWaitSpec) (Effect, error)

WaitForChildren creates a Framework Effect that opens an Engine-owned wait over direct children. Dispatch returns immediately with a WaitID; child work never blocks Execution.Step or holds a prepared Step open.

func (Effect) MarshalJSON 

func (e Effect) MarshalJSON() ([]byte, error)

func (Effect) Payload 

func (e Effect) Payload() json.RawMessage

Payload returns an independently owned copy of the operation intent.

func (Effect) RequiredCapabilities 

func (e Effect) RequiredCapabilities() CapabilitySet

RequiredCapabilities returns the immutable authority set the Process must possess before this Dispatcher Effect may be prepared.

func (Effect) Target 

func (e Effect) Target() EffectTarget

Target returns the owner responsible for interpreting Payload.

func (*Effect) UnmarshalJSON 

func (e *Effect) UnmarshalJSON(data []byte) error

func (Effect) Valid 

func (e Effect) Valid() bool

type EffectBoundary 

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

EffectBoundary is an immutable proposal to atomically advance one tree head together with one external Effect fact. Values are minted by Engine only.

func (EffectBoundary) Kind 

func (e EffectBoundary) Kind() EffectBoundaryKind

func (EffectBoundary) PreviousTreeDigest 

func (e EffectBoundary) PreviousTreeDigest() Digest

func (EffectBoundary) Request 

func (e EffectBoundary) Request() EffectRequest

Request returns the exact immutable dispatch request represented by this boundary.

func (EffectBoundary) Settlement 

func (e EffectBoundary) Settlement() (Settlement, bool)

Settlement returns the settlement introduced by a settled or resolved boundary. Pending boundaries return false.

func (EffectBoundary) TreeSnapshot 

func (e EffectBoundary) TreeSnapshot() TreeSnapshot

func (EffectBoundary) Valid 

func (e EffectBoundary) Valid() bool

type EffectBoundaryKind 

type EffectBoundaryKind string

EffectBoundaryKind identifies one monotonic durable transition of an external Effect. The zero value is invalid. 

const (
	EffectBoundaryInvalid  EffectBoundaryKind = ""
	EffectBoundaryPending  EffectBoundaryKind = "pending"
	EffectBoundarySettled  EffectBoundaryKind = "settled"
	EffectBoundaryResolved EffectBoundaryKind = "resolved"
)

These boundaries name the exact points at which durable state is committed. They are a closed vocabulary because recovery reasons about them directly: a boundary the kernel cannot name is one it cannot resume from.

func (EffectBoundaryKind) String 

func (e EffectBoundaryKind) String() string

func (EffectBoundaryKind) Valid 

func (e EffectBoundaryKind) Valid() bool

type EffectFinishedFact 

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

EffectFinishedFact is the immutable settlement observation for one Effect attempt. It does not replace the durable Effect boundary.

func (EffectFinishedFact) Duration 

func (e EffectFinishedFact) Duration() time.Duration

func (EffectFinishedFact) SettlementStatus 

func (e EffectFinishedFact) SettlementStatus() SettlementStatus

func (EffectFinishedFact) Target 

func (e EffectFinishedFact) Target() EffectTarget

func (EffectFinishedFact) Valid 

func (e EffectFinishedFact) Valid() bool

type EffectID 

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

EffectID identifies one Effect at a stable Process, Step, and batch index.

func ParseEffectID 

func ParseEffectID(value string) (EffectID, error)

ParseEffectID validates an externally encoded Effect identity.

func (EffectID) MarshalText 

func (e EffectID) MarshalText() ([]byte, error)

func (EffectID) String 

func (e EffectID) String() string

func (*EffectID) UnmarshalText 

func (e *EffectID) UnmarshalText(text []byte) error

func (EffectID) Valid 

func (e EffectID) Valid() bool

type EffectRequest 

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

EffectRequest is the immutable dispatch context prepared by the Engine.

func (EffectRequest) BatchIndex 

func (e EffectRequest) BatchIndex() uint32

BatchIndex returns the zero-based declaration order within the Step Effect batch.

func (EffectRequest) DeploymentRef 

func (e EffectRequest) DeploymentRef() DeploymentRef

DeploymentRef returns the exact behavior binding executing the Effect.

func (EffectRequest) Effect 

func (e EffectRequest) Effect() Effect

Effect returns an independently owned copy of the frozen intent.

func (EffectRequest) ID 

func (e EffectRequest) ID() EffectID

ID returns the stable identity assigned during Step preparation.

func (EffectRequest) ProcessID 

func (e EffectRequest) ProcessID() ProcessID

ProcessID returns the Process that owns the Effect.

func (EffectRequest) Relation 

func (e EffectRequest) Relation() ProcessRelation

Relation returns the immutable Process tree location executing the Effect.

func (EffectRequest) StepSequence 

func (e EffectRequest) StepSequence() uint64

StepSequence returns the one-based Step sequence that declared the Effect.

func (EffectRequest) Valid 

func (e EffectRequest) Valid() bool

Valid reports whether the request contains one complete Engine-minted dispatch identity and immutable Effect.

type EffectStartedFact 

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

EffectStartedFact identifies the target of one Effect attempt.

func (EffectStartedFact) Target 

func (e EffectStartedFact) Target() EffectTarget

func (EffectStartedFact) Valid 

func (e EffectStartedFact) Valid() bool

type EffectTarget 

type EffectTarget string

EffectTarget identifies which of the two execution boundaries owns an Effect. Framework Effects are interpreted by the Engine; Dispatcher Effects remain opaque to the Engine and are interpreted by the Deployment-bound dispatcher. 

const (
	// EffectTargetInvalid is the invalid zero value.
	EffectTargetInvalid EffectTarget = ""
	// EffectTargetFramework identifies an Engine-interpreted Effect.
	EffectTargetFramework EffectTarget = "framework"
	// EffectTargetDispatcher identifies a Strategy dispatcher Effect.
	EffectTargetDispatcher EffectTarget = "dispatcher"
)

func (EffectTarget) String 

func (e EffectTarget) String() string

func (EffectTarget) Valid 

func (e EffectTarget) Valid() bool

type Engine 

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

Engine is the sole owner of Process construction, scheduling, lifecycle, Signal delivery, Effect dispatch, and snapshot boundaries. It contains no Deployment catalog or Host persistence abstraction. Engine values must be constructed with NewEngine and must not be copied after first use.

func NewEngine 

func NewEngine(config EngineConfig) (*Engine, error)

NewEngine validates the whole configuration up front because an Engine owns Process lifecycle: a defect discovered after Processes exist has no safe remedy, since stopping the Engine would abandon in-flight effects whose settlement is still unknown.

func (*Engine) CaptureTree 

func (e *Engine) CaptureTree(ctx context.Context, rootID ProcessID) (TreeSnapshot, error)

CaptureTree quiesces one complete Engine-owned tree at Strategy-safe boundaries and captures a consistent portable cut. In-flight Effects settle according to their existing contract before a Process joins the barrier.

func (*Engine) Close 

func (e *Engine) Close() error

Close releases observation workers after all Processes have reached a terminal state. Process results remain readable from existing handles.

func (*Engine) FlushDeltas 

func (e *Engine) FlushDeltas(ctx context.Context) error

FlushDeltas waits until every best-effort Delta accepted before this call has finished delivery to the configured listeners. Deltas rejected by the bounded queue remain dropped; the method is an ordering barrier, not a reliability upgrade. Callers use it before publishing a final value that must not overtake its already-accepted streaming observations.

func (*Engine) ObservationFailures 

func (e *Engine) ObservationFailures() ObservationFailureCounts

ObservationFailures returns a concurrency-safe snapshot of listener panics isolated by this Engine. The counts do not alter Process state or Usage.

func (*Engine) PrepareWaitingSubtreeCancellation 

func (e *Engine) PrepareWaitingSubtreeCancellation(
	ctx context.Context,
	rootID ProcessID,
	targetID ProcessID,
	reason string,
) (*PreparedWaitingSubtreeCancellation, error)

PrepareWaitingSubtreeCancellation freezes one complete source tree and computes its exact cancellation result. targetID must identify a non-root Waiting Process in the tree rooted at rootID. The returned capability must be resolved exactly once with Apply or Discard.

func (*Engine) Process 

func (e *Engine) Process(id ProcessID) (*Process, bool)

Process returns an Engine-issued handle for an identity known to this Engine.

func (*Engine) RestoreTree 

func (e *Engine) RestoreTree(
	ctx context.Context,
	rootDeployment Deployment,
	snapshot TreeSnapshot,
) (*Process, error)

RestoreTree recreates a complete Process tree from one strict TreeSnapshot. rootDeployment must exactly bind the captured root; same-reference children reuse it, while other exact references are resolved through EngineConfig's DeploymentResolver. Registration is all-or-nothing within this Engine.

func (*Engine) Run 

func (e *Engine) Run(ctx context.Context, deployment Deployment, input Input) (Result, error)

Run starts one Process and waits for its terminal result. Once Start succeeds, Run waits for safe finalization even if ctx is canceled; the same ctx has already recorded the Process termination intent.

func (*Engine) Start 

func (e *Engine) Start(ctx context.Context, deployment Deployment, input Input) (*Process, error)

Start validates Input, creates exactly one Execution, registers its Process, and starts the Engine-owned loop. Canceling ctx records a Host cancellation or deadline; use a longer-lived context for execution beyond a request.

type EngineConfig 

type EngineConfig struct {
	// TreeDurability enables active recovery for complete root Process trees. It
	// owns the atomic Host transaction behind lifecycle, Effect, checkpoint, and
	// activation boundaries. Nil selects zero-configuration ephemeral execution.
	TreeDurability TreeDurability

	// ProcessStartOutcomeAcknowledger enables the optional conclusive handshake
	// after an accepted admission. A started outcome is acknowledged before
	// Process publication; an aborted outcome guarantees no publication.
	ProcessStartOutcomeAcknowledger ProcessStartOutcomeAcknowledger

	// DeploymentResolver supplies exact Deployments requested by child Effects
	// and tree restoration. It is unnecessary for same-Deployment recursion.
	// Resolution is a bounded, context-free local binding lookup only; the
	// resolver does not perform routing or own Process construction or lifecycle.
	DeploymentResolver DeploymentResolver

	// ProcessAdmitter is the optional admission boundary immediately before any
	// root or child Process initializes. It observes immutable Framework facts and
	// may reject, but cannot modify resource or capability allocation.
	ProcessAdmitter ProcessAdmitter

	// EventListeners receive ordered facts for each Process. Different
	// Processes may call a listener concurrently.
	EventListeners []EventListener

	// DeltaListeners receive best-effort streaming increments from the shared
	// bounded queue. Delivery to each listener is sequential.
	DeltaListeners []DeltaListener

	// DeltaBufferCapacity bounds the Engine-wide pending Delta queue. Zero uses
	// the documented internal default; negative values are invalid.
	DeltaBufferCapacity int

	// Limits supplies per-Process execution bounds. Each zero field inherits
	// the corresponding value from DefaultLimits.
	Limits Limits

	// TreeLimits bounds child depth, lifetime fan-out, active children, and the
	// total Process count in each independent tree.
	TreeLimits TreeLimits

	// Capabilities is the maximum authority of each root Process. Child Effects
	// may only allocate subsets and Dispatcher Effects declare what they require.
	Capabilities CapabilitySet
}

EngineConfig contains only cross-Strategy execution mechanics. Definition, Dispatcher, schema, and behavior configuration belong to each Deployment.

type Event 

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

Event is an immutable, ordered fact published by the Framework. Observers may project or instrument it, but observer failure never changes Process state. Payload is descriptive data, never a Signal or state mutation command.

func (Event) DeltaDropped 

func (e Event) DeltaDropped() (DeltaDroppedFact, bool)

DeltaDropped returns the typed loss fact for EventDeltaDropped.

func (Event) DeploymentRef 

func (e Event) DeploymentRef() DeploymentRef

DeploymentRef returns the exact execution binding that emitted the fact.

func (Event) EffectFinished 

func (e Event) EffectFinished() (EffectFinishedFact, bool)

EffectFinished returns the typed settlement fact for EventEffectFinished.

func (Event) EffectID 

func (e Event) EffectID() (EffectID, bool)

EffectID returns the related Effect identity and true when this is an Effect fact.

func (Event) EffectStarted 

func (e Event) EffectStarted() (EffectStartedFact, bool)

EffectStarted returns the typed target fact for EventEffectStarted.

func (Event) MarshalJSON 

func (e Event) MarshalJSON() ([]byte, error)

func (Event) Name 

func (e Event) Name() string

Name returns the stable Framework fact name.

func (Event) OccurredAt 

func (e Event) OccurredAt() time.Time

OccurredAt returns when the fact occurred.

func (Event) Payload 

func (e Event) Payload() json.RawMessage

Payload returns an independently owned descriptive payload.

func (Event) Phase 

func (e Event) Phase() EventPhase

Phase returns whether the fact describes an attempt or committed state.

func (Event) ProcessFinished 

func (e Event) ProcessFinished() (ProcessFinishedFact, bool)

ProcessFinished returns the typed terminal fact for EventProcessFinished.

func (Event) ProcessID 

func (e Event) ProcessID() ProcessID

ProcessID returns the Process whose fact is described.

func (Event) ProcessSequence 

func (e Event) ProcessSequence() uint64

ProcessSequence returns the Process-local publication order.

func (Event) Relation 

func (e Event) Relation() ProcessRelation

Relation returns the Process tree location that emitted the fact.

func (Event) SignalAccepted 

func (e Event) SignalAccepted() (SignalAcceptedFact, bool)

SignalAccepted returns the typed delivery fact for EventSignalAccepted.

func (Event) StepCommitted 

func (e Event) StepCommitted() (StepCommittedFact, bool)

StepCommitted returns the typed state fact for EventStepCommitted.

func (Event) StepFinished 

func (e Event) StepFinished() (StepFinishedFact, bool)

StepFinished returns the typed attempt fact for EventStepFinished.

func (Event) StepSequence 

func (e Event) StepSequence() (uint64, bool)

StepSequence returns the one-based Step sequence and true, or zero and false for a Process fact outside a Step.

func (Event) TreeIncarnationID 

func (e Event) TreeIncarnationID() (TreeIncarnationID, bool)

TreeIncarnationID returns the active durable writer that emitted this event. Events from ephemeral trees return false.

func (*Event) UnmarshalJSON 

func (e *Event) UnmarshalJSON(data []byte) error

func (Event) Valid 

func (e Event) Valid() bool

type EventListener 

type EventListener interface {
	// OnEvent receives one committed or attempted Framework fact in increasing
	// ProcessSequence for its Process. Different Processes may call the listener
	// concurrently. The callback must be bounded, must not re-enter the observed
	// Process, and has no veto or acknowledgment authority.
	OnEvent(ctx context.Context, event Event)
}

EventListener observes ordered Framework facts. Panics are isolated from Process execution and never alter committed state. Implementations must return in bounded time and must not re-enter the observed Process.

type EventListenerFunc 

type EventListenerFunc func(ctx context.Context, event Event)

EventListenerFunc adapts a plain function to the event listener interface. A listener observes and must not steer execution, so the signature returns nothing to make that boundary hard to violate by accident.

func (EventListenerFunc) OnEvent 

func (e EventListenerFunc) OnEvent(ctx context.Context, event Event)

type EventPhase 

type EventPhase string

EventPhase distinguishes an attempted external operation from a fact that the Engine has committed into authoritative Process state. 

const (
	// EventPhaseInvalid is the invalid zero value.
	EventPhaseInvalid EventPhase = ""
	// EventPhaseAttempt identifies work observed before authoritative commit.
	EventPhaseAttempt EventPhase = "attempt"
	// EventPhaseCommitted identifies a fact published after authoritative commit.
	EventPhaseCommitted EventPhase = "committed"
)

func (EventPhase) String 

func (e EventPhase) String() string

func (EventPhase) Valid 

func (e EventPhase) Valid() bool

type Execution 

type Execution interface {
	// Step reduces the current private state and the supplied ordered Signal
	// prefix into one candidate Transition. It must honor ctx for bounded CPU
	// work, perform no I/O, consume no hidden input, and never retain signals.
	// The Engine serializes calls for one Execution.
	Step(ctx context.Context, signals []Signal) (Transition, error)
	// Snapshot returns a complete, independently owned state from
	// which Definition.Restore can reproduce the current Execution exactly. It
	// must fail rather than omit state required for deterministic continuation.
	Snapshot() (ExecutionState, error)
}

Execution is the single Strategy-owned state machine inside one Process. Step must be a bounded, deterministic state reduction over the current state and the supplied Signal prefix. It must not perform external I/O, read clock, random or global state, or start ownerless goroutines. External operations are returned as Effects. Snapshot must fail rather than return partial state.

The Engine is the sole caller and never invokes Step concurrently for the same Execution. If Step or Snapshot fails, the instance is discarded and may only be rebuilt from the last stable ExecutionState.

type ExecutionState 

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

ExecutionState is an immutable envelope owned by one Execution Strategy. The Engine persists and returns Payload without interpreting it. Its zero value is invalid.

func NewExecutionState 

func NewExecutionState(kind string, payload json.RawMessage) (ExecutionState, error)

NewExecutionState pairs a strategy kind with an opaque payload. The kind exists so a snapshot can be rejected when restored into the wrong strategy; the payload stays opaque so adding a strategy never widens the kernel.

func (ExecutionState) Kind 

func (e ExecutionState) Kind() string

Kind returns the Strategy that exclusively interprets Payload.

func (ExecutionState) MarshalJSON 

func (e ExecutionState) MarshalJSON() ([]byte, error)

func (ExecutionState) Payload 

func (e ExecutionState) Payload() json.RawMessage

Payload returns an independently owned copy of the opaque Strategy state.

func (*ExecutionState) UnmarshalJSON 

func (e *ExecutionState) UnmarshalJSON(data []byte) error

func (ExecutionState) Valid 

func (e ExecutionState) Valid() bool

type Failure 

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

Failure is an immutable, snapshot-safe classification and explanation. Code is stable for machine decisions; Message is diagnostic and must not contain secrets or unbounded external payloads.

func NewFailure 

func NewFailure(kind FailureKind, code, message string) (Failure, error)

NewFailure requires a kind and code alongside the message so callers classify failures programmatically. Matching on message text is what makes error handling break on wording changes, and it does not survive the snapshot round trip.

func (Failure) Code 

func (f Failure) Code() string

Code returns the stable machine-readable reason.

func (Failure) Kind 

func (f Failure) Kind() FailureKind

Kind returns the framework-level failure classification.

func (Failure) MarshalJSON 

func (f Failure) MarshalJSON() ([]byte, error)

func (Failure) Message 

func (f Failure) Message() string

Message returns the bounded diagnostic explanation.

func (*Failure) UnmarshalJSON 

func (f *Failure) UnmarshalJSON(data []byte) error

func (Failure) Valid 

func (f Failure) Valid() bool

type FailureKind 

type FailureKind string

FailureKind is the stable framework-level classification of a failed Process. It deliberately does not imply retryability or business semantics. 

const (
	// FailureKindInvalid is the invalid zero value.
	FailureKindInvalid FailureKind = ""
	// FailureKindExecution identifies an ordinary Strategy execution failure.
	FailureKindExecution FailureKind = "execution"
	// FailureKindContract identifies a violated Framework or Strategy contract.
	FailureKindContract FailureKind = "contract"
	// FailureKindExternal identifies failed external infrastructure.
	FailureKindExternal FailureKind = "external"
	// FailureKindPanic identifies a recovered panic at an execution boundary.
	FailureKindPanic FailureKind = "panic"
)

func (FailureKind) String 

func (f FailureKind) String() string

func (FailureKind) Valid 

func (f FailureKind) Valid() bool

type Input 

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

Input is the immutable JSON value used to start a Process. Its zero value is invalid. ParseInput and EncodeInput take ownership by copying and normalizing their input.

func EncodeInput 

func EncodeInput[T any](value T) (Input, error)

EncodeInput converts a typed value into an independently owned Input.

Example 
package main

import (
	"fmt"

	"github.com/Tangerg/scope/agent"
)

func main() {
	type request struct {
		Topic string `json:"topic"`
	}

	input, err := agent.EncodeInput(request{Topic: "agent runtimes"})
	if err != nil {
		panic(err)
	}
	decoded, err := input.Decode[request]()
	if err != nil {
		panic(err)
	}

	fmt.Println(decoded.Topic, input.Valid())
}

Output:
agent runtimes true

func ParseInput 

func ParseInput(data json.RawMessage) (Input, error)

ParseInput validates one JSON value and returns an independently owned Input.

func (Input) Decode 

func (i Input) Decode[T any]() (T, error)

Decode strictly decodes i into a typed value. Unknown object fields are rejected when T is a struct.

func (Input) JSON 

func (i Input) JSON() json.RawMessage

JSON returns an independently owned JSON representation.

func (Input) MarshalJSON 

func (i Input) MarshalJSON() ([]byte, error)

func (*Input) UnmarshalJSON 

func (i *Input) UnmarshalJSON(data []byte) error

func (Input) Valid 

func (i Input) Valid() bool

type Limits 

type Limits struct {
	// MaxSteps bounds committed Steps.
	MaxSteps uint64 `json:"max_steps"`

	// MaxEffects bounds Effects prepared across all Steps.
	MaxEffects uint64 `json:"max_effects"`

	// MaxSignals bounds all accepted external and Engine-generated Signals.
	MaxSignals uint64 `json:"max_signals"`

	// MaxPendingSignals bounds the unconsumed mailbox suffix, including space
	// reserved for the current prepared Effect batch.
	MaxPendingSignals uint64 `json:"max_pending_signals"`
}

Limits bounds Framework-owned execution growth. Zero-valued fields in EngineConfig inherit DefaultLimits; ProcessSnapshot stores effective non-zero values so restoration preserves the same execution contract.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns conservative hard bounds for one Process.

func (Limits) Valid 

func (l Limits) Valid() bool

type ObservationFailureCounts 

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

ObservationFailureCounts is an immutable snapshot of listener panics isolated by one Engine. Counts are monotonic and saturate at math.MaxUint64.

func (ObservationFailureCounts) DeltaListenerPanics 

func (o ObservationFailureCounts) DeltaListenerPanics() uint64

func (ObservationFailureCounts) EventListenerPanics 

func (o ObservationFailureCounts) EventListenerPanics() uint64

type Output 

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

Output is the immutable final semantic result of a completed Process. Its zero value is invalid and it never represents streamed Delta content.

func EncodeOutput 

func EncodeOutput[T any](value T) (Output, error)

EncodeOutput converts a typed value into an independently owned Output.

func ParseOutput 

func ParseOutput(data json.RawMessage) (Output, error)

ParseOutput validates one JSON value and returns an independently owned Output.

func (Output) Decode 

func (o Output) Decode[T any]() (T, error)

Decode strictly decodes o into a typed value. Unknown object fields are rejected when T is a struct.

func (Output) JSON 

func (o Output) JSON() json.RawMessage

JSON returns an independently owned JSON representation.

func (Output) MarshalJSON 

func (o Output) MarshalJSON() ([]byte, error)

func (*Output) UnmarshalJSON 

func (o *Output) UnmarshalJSON(data []byte) error

func (Output) Valid 

func (o Output) Valid() bool

type PreparedWaitingSubtreeCancellation 

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

PreparedWaitingSubtreeCancellation owns one frozen, Strategy-safe source tree and its exact prospective cancellation result. Callers must retain the returned pointer rather than copy the value. The underlying authority is shared and must be resolved exactly once with Apply or Discard; an accidental value copy does not duplicate that authority. Until resolution, the source tree remains frozen. Other root trees in the Engine remain independent.

func (*PreparedWaitingSubtreeCancellation) Apply 

func (p *PreparedWaitingSubtreeCancellation) Apply() error

Apply commits the exact prepared Framework state and releases the frozen source tree. Prepare completed every fallible or cancelable operation, so Apply deliberately has no context: once the caller's durable decision exists, request cancellation cannot revoke this in-memory commit boundary.

func (*PreparedWaitingSubtreeCancellation) CanceledProcessIDs 

func (p *PreparedWaitingSubtreeCancellation) CanceledProcessIDs() []ProcessID

CanceledProcessIDs returns Processes projected as Canceled, ordered from parent to child and then by ProcessID within one depth.

func (*PreparedWaitingSubtreeCancellation) Discard 

func (p *PreparedWaitingSubtreeCancellation) Discard() error

Discard releases the frozen source tree without applying the prospective cancellation. It returns an error when Apply or Discard already resolved it.

func (*PreparedWaitingSubtreeCancellation) PausedProcessIDs 

func (p *PreparedWaitingSubtreeCancellation) PausedProcessIDs() []ProcessID

PausedProcessIDs returns parents projected as Paused before they can consume a child-completion Signal. A caller that later continues uses Process.Resume.

func (*PreparedWaitingSubtreeCancellation) ResultingSnapshot 

func (p *PreparedWaitingSubtreeCancellation) ResultingSnapshot() TreeSnapshot

ResultingSnapshot returns the exact complete tree state that Apply will install. The snapshot remains readable after Apply or Discard.

func (*PreparedWaitingSubtreeCancellation) SourceTreeDigest 

func (p *PreparedWaitingSubtreeCancellation) SourceTreeDigest() Digest

SourceTreeDigest returns the authoritative head that the Host transaction must compare before installing ResultingSnapshot.

type Process 

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

Process is an Engine-issued handle to one managed execution. Its fields and construction remain private so a caller cannot create a second lifecycle owner. Methods only submit control-plane requests to the owning Engine loop. Except for RequestCancellation, ctx bounds both command submission and response waiting. Once the Engine loop receives a command, canceling ctx does not revoke it.

func (*Process) Await 

func (p *Process) Await(ctx context.Context) (Result, error)

Await waits for the immutable terminal result and the Engine's immediate parent/child bookkeeping for that termination. Canceling ctx stops only the wait; Process cancellation is explicit or follows the context passed to Start.

func (*Process) Budget 

func (p *Process) Budget() Budget

Budget returns the fixed non-renewable allocation assigned to this Process.

func (*Process) Capabilities 

func (p *Process) Capabilities() CapabilitySet

Capabilities returns the immutable authority set assigned to this Process.

func (*Process) DeliverSignal 

func (p *Process) DeliverSignal(ctx context.Context, request SignalRequest) (accepted bool, err error)

DeliverSignal submits immutable Strategy input. Running input is consumed only at the next Strategy-safe Step boundary; Waiting input must address WaitID. accepted is false, with nil error, when SignalID was already accepted.

func (*Process) DeliverSignals 

func (p *Process) DeliverSignals(ctx context.Context, requests ...SignalRequest) (accepted bool, err error)

DeliverSignals atomically appends an ordered Signal batch. This is useful when one WaitID-addressed response and ordinary follow-up input must become visible at the same safe Strategy boundary. Either the complete batch is accepted in order or the mailbox remains unchanged.

func (*Process) DeploymentRef 

func (p *Process) DeploymentRef() DeploymentRef

DeploymentRef returns the exact Definition and dispatcher binding identity.

func (*Process) ID 

func (p *Process) ID() ProcessID

ID returns the stable Process identity.

func (*Process) Kill 

func (p *Process) Kill(ctx context.Context, reason string) error

Kill records the Engine control plane's highest-priority terminal intent. It does not silently abandon an in-flight Effect; settlement finishes first.

func (*Process) Pause 

func (p *Process) Pause(ctx context.Context, reason string) error

Pause requests a scheduling pause at the next safe Step boundary. An in-flight Effect is allowed to settle before the pause becomes visible.

func (*Process) Relation 

func (p *Process) Relation() ProcessRelation

Relation returns the immutable parent/root/depth location assigned by the Engine. It is a root relation for Processes created through Engine.Start.

func (*Process) RequestCancellation 

func (p *Process) RequestCancellation(ctx context.Context, reason string) error

RequestCancellation submits a caller-owned cancellation intent. A nil error means the request entered the owning Engine loop's queue; it does not mean the Process has reached a safe boundary or become terminal. Once submitted, ctx cancellation cannot revoke the request. The first committed cancellation intent maps to StatusCanceled with a host-cancellation cause.

func (*Process) ResolveUnknownEffect 

func (p *Process) ResolveUnknownEffect(ctx context.Context, settlement Settlement) error

ResolveUnknownEffect supplies a definite result after an Effect attempt became unknown. The Engine never converts unknown into retry or success implicitly.

func (*Process) Resume 

func (p *Process) Resume(ctx context.Context) error

Resume makes an explicitly Paused Process schedulable again. Waiting is resumed only by a Signal addressed to its current WaitID.

func (*Process) Snapshot 

func (p *Process) Snapshot(ctx context.Context) (ProcessSnapshot, error)

Snapshot returns a consistent last-stable or prepared-step snapshot. Snapshot does not imply that the caller persisted it durably.

func (*Process) StartedAt 

func (p *Process) StartedAt() time.Time

StartedAt returns the lifecycle time committed by its started outcome.

func (*Process) Status 

func (p *Process) Status() Status

Status returns the latest committed common lifecycle status.

func (*Process) UnknownEffectIDs 

func (p *Process) UnknownEffectIDs(ctx context.Context) ([]EffectID, error)

UnknownEffectIDs returns stable identities whose external outcome requires an explicit ResolveUnknownEffect decision. Payloads remain owned by the Dispatcher.

func (*Process) Usage 

func (p *Process) Usage() Usage

Usage returns the latest Framework-owned counters.

func (*Process) WaitID 

func (p *Process) WaitID() (WaitID, bool)

WaitID returns the current externally addressable wait while Status is Waiting. The payload schema and meaning remain owned by the Strategy.

type ProcessAdmission 

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

ProcessAdmission is the immutable Framework-owned information supplied to a ProcessAdmitter immediately before one root or child Process starts. It does not expose Input, Execution, Dispatcher, product identity, or Host state.

func (ProcessAdmission) Budget 

func (p ProcessAdmission) Budget() Budget

Budget returns the prospective Process's fixed non-renewable allocation.

func (ProcessAdmission) Capabilities 

func (p ProcessAdmission) Capabilities() CapabilitySet

Capabilities returns the prospective Process's immutable authority set.

func (ProcessAdmission) DeploymentRef 

func (p ProcessAdmission) DeploymentRef() DeploymentRef

DeploymentRef returns the exact prospective Deployment identity.

func (ProcessAdmission) Descriptor 

func (p ProcessAdmission) Descriptor() Descriptor

Descriptor returns the prospective Definition's static contract.

func (ProcessAdmission) Relation 

func (p ProcessAdmission) Relation() ProcessRelation

Relation returns the prospective Process identity and tree location.

func (ProcessAdmission) Valid 

func (p ProcessAdmission) Valid() bool

type ProcessAdmitter 

type ProcessAdmitter interface {
	// Admit decides whether the immutable prospective Process may initialize.
	// Returning nil accepts only the supplied identity and resources; it cannot
	// enlarge Budget or Capabilities. Returning an error prevents initialization
	// and publication. Implementations honor ctx, are bounded and concurrency-
	// safe, and must tolerate the same prospective identity after recovery.
	Admit(ctx context.Context, admission ProcessAdmission) error
}

ProcessAdmitter decides whether one prospective root or child Process may initialize. Implementations may coordinate caller-owned external admission work, but must not create a Process, mutate the admission, or allocate Framework resources. A prepared Step may replay the same child admission with the same prospective Process identity after recovery.

Implementations must respect ctx, return in bounded time, be safe for concurrent calls when shared, and must not re-enter the Engine or a Process. Framework identity is stable, but persistence, transactionality, charging, and business idempotency remain implementation responsibilities. Returning an error rejects only this prospective Process. Budget allocation, capability attenuation, and tree limits remain Engine invariants and cannot be changed by an admitter. Every accepted admission concludes with exactly one ProcessStartOutcome when an acknowledger is configured. Restore repeats neither admission nor its outcome for a captured Process.

type ProcessAdmitterFunc 

type ProcessAdmitterFunc func(ctx context.Context, admission ProcessAdmission) error

ProcessAdmitterFunc adapts a plain function to the admitter interface, so a host quota or policy check does not require a named type.

func (ProcessAdmitterFunc) Admit 

func (p ProcessAdmitterFunc) Admit(ctx context.Context, admission ProcessAdmission) error

type ProcessFinishedFact 

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

ProcessFinishedFact is the immutable terminal fact carried by a finished Process Event. Usage is the authoritative Framework-owned terminal usage.

func (ProcessFinishedFact) Cause 

func (p ProcessFinishedFact) Cause() TerminationCause

func (ProcessFinishedFact) Failure 

func (p ProcessFinishedFact) Failure() (FailureKind, string, bool)

func (ProcessFinishedFact) Status 

func (p ProcessFinishedFact) Status() Status

func (ProcessFinishedFact) Usage 

func (p ProcessFinishedFact) Usage() Usage

func (ProcessFinishedFact) Valid 

func (p ProcessFinishedFact) Valid() bool

type ProcessID 

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

ProcessID is the stable identity of one Engine-owned Process.

func ParseProcessID 

func ParseProcessID(value string) (ProcessID, error)

ParseProcessID validates an externally encoded Process identity.

func (ProcessID) MarshalText 

func (p ProcessID) MarshalText() ([]byte, error)

func (ProcessID) String 

func (p ProcessID) String() string

func (*ProcessID) UnmarshalText 

func (p *ProcessID) UnmarshalText(text []byte) error

func (ProcessID) Valid 

func (p ProcessID) Valid() bool

type ProcessRelation 

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

ProcessRelation is the immutable location of one Process in an Engine-owned tree. Roots identify themselves as RootID at depth zero. Children have one parent and one stable ChildKey; a Process never has multiple parents.

func (ProcessRelation) ChildKey 

func (p ProcessRelation) ChildKey() (ChildKey, bool)

ChildKey returns the parent-scoped logical child identity and true for a child, or zero and false for a root.

func (ProcessRelation) Depth 

func (p ProcessRelation) Depth() uint32

Depth returns zero for a root and parent depth plus one for every child.

func (ProcessRelation) IsRoot 

func (p ProcessRelation) IsRoot() bool

IsRoot reports whether p identifies the root of its tree.

func (ProcessRelation) ParentID 

func (p ProcessRelation) ParentID() (ProcessID, bool)

ParentID returns the direct parent and true for a child, or zero and false for a root.

func (ProcessRelation) ProcessID 

func (p ProcessRelation) ProcessID() ProcessID

ProcessID returns the Process located by this relation.

func (ProcessRelation) RootID 

func (p ProcessRelation) RootID() ProcessID

RootID returns the stable root identity shared by the complete Process tree.

func (ProcessRelation) Valid 

func (p ProcessRelation) Valid() bool

type ProcessSnapshot 

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

ProcessSnapshot is an immutable diagnostic capture of one Engine-owned Process. Strategy state and Effect payloads remain opaque. A ProcessSnapshot is not a recovery unit; only a complete TreeSnapshot can be restored.

func ParseProcessSnapshot 

func ParseProcessSnapshot(data json.RawMessage) (ProcessSnapshot, error)

ParseProcessSnapshot strictly validates one Process snapshot wire value.

func (ProcessSnapshot) Budget 

func (p ProcessSnapshot) Budget() Budget

Budget returns the Process work allocation captured by this snapshot.

func (ProcessSnapshot) Capabilities 

func (p ProcessSnapshot) Capabilities() CapabilitySet

Capabilities returns the Process authority set captured by this snapshot.

func (ProcessSnapshot) CommittedExecutionState 

func (p ProcessSnapshot) CommittedExecutionState() ExecutionState

CommittedExecutionState returns the latest committed opaque Strategy state. A prepared candidate, when present, remains an uncommitted Engine detail. Only the owning Definition or its typed inspection helpers may interpret the returned state's payload.

func (ProcessSnapshot) DeploymentRef 

func (p ProcessSnapshot) DeploymentRef() DeploymentRef

DeploymentRef returns the exact execution binding required for restoration.

func (ProcessSnapshot) JSON 

func (p ProcessSnapshot) JSON() json.RawMessage

JSON returns an independently owned snapshot representation.

func (ProcessSnapshot) MarshalJSON 

func (p ProcessSnapshot) MarshalJSON() ([]byte, error)

func (ProcessSnapshot) ProcessID 

func (p ProcessSnapshot) ProcessID() ProcessID

ProcessID returns the captured Process identity.

func (ProcessSnapshot) Relation 

func (p ProcessSnapshot) Relation() ProcessRelation

Relation returns the immutable parent/root/depth location captured with the Process.

func (ProcessSnapshot) Status 

func (p ProcessSnapshot) Status() Status

Status returns the captured common lifecycle state.

func (*ProcessSnapshot) UnmarshalJSON 

func (p *ProcessSnapshot) UnmarshalJSON(data []byte) error

func (ProcessSnapshot) Valid 

func (p ProcessSnapshot) Valid() bool

func (ProcessSnapshot) WaitID 

func (p ProcessSnapshot) WaitID() (WaitID, bool)

WaitID returns the current Engine-minted wait identity and true when the captured Process is Waiting.

type ProcessStartOutcome 

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

ProcessStartOutcome is the immutable conclusive Framework result for one accepted ProcessAdmission. A started outcome is acknowledged immediately before Engine publication; an aborted outcome guarantees no publication.

func (ProcessStartOutcome) Admission 

func (p ProcessStartOutcome) Admission() ProcessAdmission

Admission returns the exact accepted admission concluded by this outcome.

func (ProcessStartOutcome) Failure 

func (p ProcessStartOutcome) Failure() (Failure, bool)

Failure returns the stable initialization failure for an aborted outcome.

func (ProcessStartOutcome) PreviousTreeDigest 

func (p ProcessStartOutcome) PreviousTreeDigest() (Digest, bool)

PreviousTreeDigest returns the authoritative head compared by a durable child outcome. Root and ephemeral outcomes return false.

func (ProcessStartOutcome) StartedAt 

func (p ProcessStartOutcome) StartedAt() (time.Time, bool)

StartedAt returns the authoritative UTC lifecycle time for a started Process. Aborted outcomes return false because no Process lifecycle began.

func (ProcessStartOutcome) Status 

func (p ProcessStartOutcome) Status() ProcessStartOutcomeStatus

Status returns the conclusive started or aborted initialization result.

func (ProcessStartOutcome) TreeSnapshot 

func (p ProcessStartOutcome) TreeSnapshot() (TreeSnapshot, bool)

TreeSnapshot returns the prospective complete tree installed atomically by a durable started or child-aborted outcome. Ephemeral and root-aborted outcomes return false.

func (ProcessStartOutcome) Valid 

func (p ProcessStartOutcome) Valid() bool

type ProcessStartOutcomeAcknowledger 

type ProcessStartOutcomeAcknowledger interface {
	// AcknowledgeProcessStartOutcome synchronously closes one previously accepted
	// admission as started or aborted. Returning an error for started prevents
	// Process publication; an aborted Process is never published regardless of
	// acknowledgment outcome. Implementations must be bounded, concurrency-safe,
	// idempotent by admission identity, and must not re-enter Engine or Process.
	AcknowledgeProcessStartOutcome(ctx context.Context, outcome ProcessStartOutcome) error
}

ProcessStartOutcomeAcknowledger is the optional synchronous boundary that accepts exactly one conclusive result for every accepted admission. Implementations may be called concurrently for different Processes, must be idempotent for the same admission identity, must return in bounded time, and must not re-enter the Engine or any Process. Restore does not produce outcomes.

Returning nil accepts the outcome. Rejecting a started outcome prevents publication; rejecting an aborted outcome cannot create a Process. The Framework owns no persistence, transaction, charging, or product semantics behind this neutral lifecycle handshake.

type ProcessStartOutcomeAcknowledgerFunc 

type ProcessStartOutcomeAcknowledgerFunc func(
	ctx context.Context,
	outcome ProcessStartOutcome,
) error

ProcessStartOutcomeAcknowledgerFunc adapts a plain function to the acknowledger interface. The function still owes the interface's guarantees — bounded, concurrency-safe, idempotent, and no re-entry into the Engine.

func (ProcessStartOutcomeAcknowledgerFunc) AcknowledgeProcessStartOutcome 

func (p ProcessStartOutcomeAcknowledgerFunc) AcknowledgeProcessStartOutcome(
	ctx context.Context,
	outcome ProcessStartOutcome,
) error

type ProcessStartOutcomeStatus 

type ProcessStartOutcomeStatus string

ProcessStartOutcomeStatus identifies the conclusive result of one accepted Process admission. The zero value is invalid. 

const (
	// ProcessStartOutcomeStatusInvalid is the invalid zero value.
	ProcessStartOutcomeStatusInvalid ProcessStartOutcomeStatus = ""
	// ProcessStartOutcomeStatusStarted means the prospective Process completed
	// initialization and is ready for Engine publication.
	ProcessStartOutcomeStatusStarted ProcessStartOutcomeStatus = "started"
	// ProcessStartOutcomeStatusAborted means initialization failed and no
	// Process will be published for the accepted admission.
	ProcessStartOutcomeStatusAborted ProcessStartOutcomeStatus = "aborted"
)

func (ProcessStartOutcomeStatus) String 

func (p ProcessStartOutcomeStatus) String() string

func (ProcessStartOutcomeStatus) Valid 

func (p ProcessStartOutcomeStatus) Valid() bool

type ReplayPolicy 

type ReplayPolicy string

ReplayPolicy states whether a Dispatcher can prove that repeating an Effect with the same EffectID is the same logical external operation. It does not claim transactionality or allow replay under a different identity. 

const (
	// ReplayPolicyInvalid is the invalid zero value.
	ReplayPolicyInvalid ReplayPolicy = ""
	// ReplayPolicyNever forbids automatic replay after an unknown settlement.
	ReplayPolicyNever ReplayPolicy = "never"
	// ReplayPolicySameIdentity permits replay only with the original EffectID.
	ReplayPolicySameIdentity ReplayPolicy = "same_identity"
)

func (ReplayPolicy) String 

func (r ReplayPolicy) String() string

func (ReplayPolicy) Valid 

func (r ReplayPolicy) Valid() bool

type Result 

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

Result is the immutable terminal outcome of one Process. A failed or canceled execution is represented by Termination, not by Await's error.

func (Result) FinishedAt 

func (r Result) FinishedAt() time.Time

FinishedAt returns the committed terminal time.

func (Result) Output 

func (r Result) Output() (Output, bool)

Output returns the final semantic result only for StatusCompleted.

func (Result) ProcessID 

func (r Result) ProcessID() ProcessID

ProcessID returns the completed Process identity.

func (Result) StartedAt 

func (r Result) StartedAt() time.Time

StartedAt returns the lifecycle start time.

func (Result) Status 

func (r Result) Status() Status

Status returns the terminal lifecycle state.

func (Result) Termination 

func (r Result) Termination() Termination

Termination returns the stable terminal cause and optional Failure.

func (Result) Usage 

func (r Result) Usage() Usage

Usage returns the final Framework-owned resource counters.

func (Result) Valid 

func (r Result) Valid() bool

type Schema 

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

Schema is an immutable, resolved JSON Schema used by Framework input and output contracts. Its zero value is invalid.

func ParseSchema 

func ParseSchema(data json.RawMessage) (Schema, error)

ParseSchema validates and resolves one JSON Schema.

func SchemaFor 

func SchemaFor[T any]() (Schema, error)

SchemaFor derives and resolves a JSON Schema for T.

func (Schema) JSON 

func (s Schema) JSON() json.RawMessage

JSON returns an independently owned JSON representation.

func (Schema) MarshalJSON 

func (s Schema) MarshalJSON() ([]byte, error)

func (*Schema) UnmarshalJSON 

func (s *Schema) UnmarshalJSON(data []byte) error

func (Schema) Valid 

func (s Schema) Valid() bool

func (Schema) ValidateInput 

func (s Schema) ValidateInput(input Input) error

func (Schema) ValidateOutput 

func (s Schema) ValidateOutput(output Output) error

type Settlement 

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

Settlement is the immutable final fact for one EffectID. Payload is owned by the Effect target and becomes opaque Signal data for the next Step. The Engine uses Status only to preserve definite versus unknown execution facts.

func NewSettlement 

func NewSettlement(effectID EffectID, status SettlementStatus, payload json.RawMessage) (Settlement, error)

NewSettlement binds a result to the exact effect identity it settles, so a dispatcher cannot close an effect other than the one it was given. Ordering by completion time instead would let a slow settlement overwrite a newer one.

func (Settlement) EffectID 

func (s Settlement) EffectID() EffectID

EffectID returns the Effect this result settles.

func (Settlement) MarshalJSON 

func (s Settlement) MarshalJSON() ([]byte, error)

func (Settlement) Payload 

func (s Settlement) Payload() json.RawMessage

Payload returns an independently owned owner-defined result.

func (Settlement) Status 

func (s Settlement) Status() SettlementStatus

Status returns whether the external result is definite or unknown.

func (*Settlement) UnmarshalJSON 

func (s *Settlement) UnmarshalJSON(data []byte) error

func (Settlement) Valid 

func (s Settlement) Valid() bool

type SettlementStatus 

type SettlementStatus string

SettlementStatus records whether an Effect definitely succeeded, definitely failed, or has an unknown external result. Unknown never implies safe retry. 

const (
	// SettlementStatusInvalid is the invalid zero value.
	SettlementStatusInvalid SettlementStatus = ""
	// SettlementStatusSucceeded records a definite successful outcome.
	SettlementStatusSucceeded SettlementStatus = "succeeded"
	// SettlementStatusFailed records a definite failed outcome.
	SettlementStatusFailed SettlementStatus = "failed"
	// SettlementStatusUnknown records an externally indeterminate outcome.
	SettlementStatusUnknown SettlementStatus = "unknown"
)

func (SettlementStatus) String 

func (s SettlementStatus) String() string

func (SettlementStatus) Valid 

func (s SettlementStatus) Valid() bool

type Signal 

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

Signal is the immutable input envelope delivered by the Engine to an Execution. Dispatcher and ordinary wait payloads belong exclusively to the Strategy; Framework composition payloads are decoded only through their public typed helpers. SignalID identifies delivery, while an optional WaitID identifies the Engine-created wait target.

func (Signal) ID 

func (s Signal) ID() SignalID

ID returns the stable delivery and deduplication identity.

func (Signal) MarshalJSON 

func (s Signal) MarshalJSON() ([]byte, error)

func (Signal) Payload 

func (s Signal) Payload() json.RawMessage

Payload returns an independently owned copy. Strategy-owned payloads are interpreted only by their Strategy; Framework-owned payloads should be read through the corresponding typed parser rather than decoded ad hoc.

func (*Signal) UnmarshalJSON 

func (s *Signal) UnmarshalJSON(data []byte) error

func (Signal) Valid 

func (s Signal) Valid() bool

func (Signal) WaitID 

func (s Signal) WaitID() (WaitID, bool)

WaitID returns the addressed wait and true, or a zero WaitID and false for a Signal queued at the next Strategy-safe boundary.

type SignalAcceptedFact 

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

SignalAcceptedFact is the immutable delivery identity carried by an accepted Signal Event. WaitID is present only for a wait-addressed Signal.

func (SignalAcceptedFact) SignalID 

func (s SignalAcceptedFact) SignalID() SignalID

func (SignalAcceptedFact) Valid 

func (s SignalAcceptedFact) Valid() bool

func (SignalAcceptedFact) WaitID 

func (s SignalAcceptedFact) WaitID() (WaitID, bool)

type SignalID 

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

SignalID is the stable identity used to deduplicate one Signal delivery.

func ParseSignalID 

func ParseSignalID(value string) (SignalID, error)

ParseSignalID validates an externally supplied Signal delivery identity. Parsing does not accept or deliver the Signal.

func (SignalID) MarshalText 

func (s SignalID) MarshalText() ([]byte, error)

func (SignalID) String 

func (s SignalID) String() string

func (*SignalID) UnmarshalText 

func (s *SignalID) UnmarshalText(text []byte) error

func (SignalID) Valid 

func (s SignalID) Valid() bool

type SignalRequest 

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

SignalRequest is an immutable request to deliver Strategy-owned input to a Process. ID supplies caller-stable deduplication. WaitID is zero for ordinary next-boundary input and Engine-minted for an external wait answer.

func NewSignalRequest 

func NewSignalRequest(id SignalID, waitID WaitID, payload json.RawMessage) (SignalRequest, error)

NewSignalRequest requires a caller-chosen signal identity so that resubmitting the same delivery is exactly one logical consumption. Without it, a host retry after an ambiguous network failure would be indistinguishable from a second answer.

func (SignalRequest) ID 

func (s SignalRequest) ID() SignalID

ID returns the stable delivery and deduplication identity.

func (SignalRequest) Payload 

func (s SignalRequest) Payload() json.RawMessage

Payload returns an independently owned Strategy-defined value.

func (SignalRequest) Valid 

func (s SignalRequest) Valid() bool

func (SignalRequest) WaitID 

func (s SignalRequest) WaitID() (WaitID, bool)

WaitID returns the addressed wait and true, or a zero WaitID and false.

type Status 

type Status string

Status is the complete common lifecycle state of a Process. Strategy-specific conditions such as a Planning no-plan result do not add common statuses. 

const (
	// StatusInvalid is the invalid zero value.
	StatusInvalid Status = ""
	// StatusNotStarted identifies a Process before execution begins.
	StatusNotStarted Status = "not_started"
	// StatusRunning identifies a Process eligible to advance.
	StatusRunning Status = "running"
	// StatusWaiting identifies a Process awaiting a WaitID-addressed Signal.
	StatusWaiting Status = "waiting"
	// StatusPaused identifies an explicitly suspended Process.
	StatusPaused Status = "paused"
	// StatusCompleted identifies successful semantic completion.
	StatusCompleted Status = "completed"
	// StatusFailed identifies terminal execution failure.
	StatusFailed Status = "failed"
	// StatusCanceled identifies cooperative cancellation.
	StatusCanceled Status = "canceled"
	// StatusTimedOut identifies deadline termination.
	StatusTimedOut Status = "timed_out"
	// StatusKilled identifies an explicit Engine kill.
	StatusKilled Status = "killed"
)

func (Status) MarshalText 

func (s Status) MarshalText() ([]byte, error)

func (Status) String 

func (s Status) String() string

func (Status) Terminal 

func (s Status) Terminal() bool

Terminal reports whether the Process may never transition again.

func (*Status) UnmarshalText 

func (s *Status) UnmarshalText(text []byte) error

func (Status) Valid 

func (s Status) Valid() bool

type StepCommittedFact 

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

StepCommittedFact is the Process status installed by one committed Step.

func (StepCommittedFact) Status 

func (s StepCommittedFact) Status() Status

func (StepCommittedFact) Valid 

func (s StepCommittedFact) Valid() bool

type StepFinishedFact 

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

StepFinishedFact is the immutable outcome of one Execution.Step attempt.

func (StepFinishedFact) Duration 

func (s StepFinishedFact) Duration() time.Duration

func (StepFinishedFact) Status 

func (s StepFinishedFact) Status() StepStatus

func (StepFinishedFact) Valid 

func (s StepFinishedFact) Valid() bool

type StepStatus 

type StepStatus string

StepStatus reports whether one Step reduction succeeded, and is deliberately narrower than Status: a failed Step does not by itself terminate a Process, because the terminal decision also depends on recorded control intent. 

const (
	StepStatusSucceeded StepStatus = "succeeded"
	StepStatusFailed    StepStatus = "failed"
)

Step status is separate from Process status because a failed Step does not by itself terminate a Process; the terminal decision also weighs recorded control intent.

func (StepStatus) String 

func (s StepStatus) String() string

func (StepStatus) Valid 

func (s StepStatus) Valid() bool

type Termination 

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

Termination is the immutable result of applying the terminal priority matrix.

func (Termination) Cause 

func (t Termination) Cause() TerminationCause

Cause returns the stable machine-readable terminal category.

func (Termination) Failure 

func (t Termination) Failure() (Failure, bool)

Failure returns the classified failure for StatusFailed.

func (Termination) MarshalJSON 

func (t Termination) MarshalJSON() ([]byte, error)

func (Termination) Reason 

func (t Termination) Reason() string

Reason returns a bounded diagnostic reason. Completion has an empty reason.

func (Termination) Status 

func (t Termination) Status() Status

Status returns the resolved terminal Process status.

func (*Termination) UnmarshalJSON 

func (t *Termination) UnmarshalJSON(data []byte) error

func (Termination) UnresolvedEffectIDs 

func (t Termination) UnresolvedEffectIDs() []EffectID

UnresolvedEffectIDs returns the canonical identities of external operations that may have occurred but were not durably resolved when the tree stopped.

func (Termination) Valid 

func (t Termination) Valid() bool

type TerminationCause 

type TerminationCause string

TerminationCause is the stable reason category of a terminal Process. 

const (
	// TerminationCauseInvalid is the invalid zero value.
	TerminationCauseInvalid TerminationCause = ""
	// TerminationCauseCompletion identifies successful semantic completion.
	TerminationCauseCompletion TerminationCause = "completion"
	// TerminationCauseEngineKill identifies an explicit Engine kill.
	TerminationCauseEngineKill TerminationCause = "engine_kill"
	// TerminationCauseProcessDeadline identifies the Process's own deadline.
	TerminationCauseProcessDeadline TerminationCause = "process_deadline"
	// TerminationCauseParentDeadline identifies deadline propagation from a parent.
	TerminationCauseParentDeadline TerminationCause = "parent_deadline"
	// TerminationCauseHostDeadline identifies expiry of the Host context.
	TerminationCauseHostDeadline TerminationCause = "host_deadline"
	// TerminationCauseParentCancellation identifies cancellation by a parent Process.
	TerminationCauseParentCancellation TerminationCause = "parent_cancellation"
	// TerminationCauseHostCancellation identifies cancellation by the Host context.
	TerminationCauseHostCancellation TerminationCause = "host_cancellation"
	// TerminationCauseExecutionFailure identifies an ordinary Strategy failure.
	TerminationCauseExecutionFailure TerminationCause = "execution_failure"
	// TerminationCauseContractFailure identifies a contract violation.
	TerminationCauseContractFailure TerminationCause = "contract_failure"
	// TerminationCauseExternalFailure identifies failed external infrastructure.
	TerminationCauseExternalFailure TerminationCause = "external_failure"
	// TerminationCausePanic identifies a recovered execution-boundary panic.
	TerminationCausePanic TerminationCause = "panic"
)

func (TerminationCause) String 

func (t TerminationCause) String() string

func (TerminationCause) Valid 

func (t TerminationCause) Valid() bool

type Transition 

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

Transition is an immutable candidate lifecycle intent. The Engine validates ConsumedSignals against the delivered Signal window, captures the candidate ExecutionState, and assigns EffectID values before committing anything.

func Complete 

func Complete(consumedSignals uint32, output Output) (Transition, error)

Complete supplies the final semantic Output. The Engine must validate it against the Definition Descriptor before committing Completed.

func Continue 

func Continue(consumedSignals uint32, effects ...Effect) (Transition, error)

Continue keeps the Process schedulable after consuming the stated Signal prefix. Effects are dispatched only after the Engine prepares the Step.

func Fail 

func Fail(consumedSignals uint32, failure Failure) (Transition, error)

Fail supplies a stable Strategy-declared failure without making the Execution instance untrusted. A Step error follows the separate discard path.

func Pause 

func Pause(consumedSignals uint32, reason string) (Transition, error)

Pause requests an explicit scheduling pause with a bounded diagnostic reason.

func Wait 

func Wait(consumedSignals uint32, waitID WaitID) (Transition, error)

Wait moves the Process to Waiting for an Engine-minted WaitID already stored in the candidate ExecutionState.

func (Transition) ConsumedSignals 

func (t Transition) ConsumedSignals() uint32

ConsumedSignals returns the length of the delivered Signal prefix to commit.

func (Transition) Effects 

func (t Transition) Effects() []Effect

Effects returns independently owned operation intents in declaration order.

func (Transition) Failure 

func (t Transition) Failure() (Failure, bool)

Failure returns the terminal failure for a Fail transition.

func (Transition) Kind 

func (t Transition) Kind() TransitionKind

Kind returns the requested lifecycle intent.

func (Transition) MarshalJSON 

func (t Transition) MarshalJSON() ([]byte, error)

func (Transition) Output 

func (t Transition) Output() (Output, bool)

Output returns the final result for a Complete transition.

func (Transition) Reason 

func (t Transition) Reason() (string, bool)

Reason returns the pause reason for a Pause transition.

func (*Transition) UnmarshalJSON 

func (t *Transition) UnmarshalJSON(data []byte) error

func (Transition) Valid 

func (t Transition) Valid() bool

func (Transition) WaitID 

func (t Transition) WaitID() (WaitID, bool)

WaitID returns the wait target for a Wait transition.

type TransitionKind 

type TransitionKind string

TransitionKind is the lifecycle intent produced by one bounded Step. 

const (
	// TransitionKindInvalid is the invalid zero value.
	TransitionKindInvalid TransitionKind = ""
	// TransitionKindContinue advances to another runnable Step.
	TransitionKindContinue TransitionKind = "continue"
	// TransitionKindWait enters an Engine-minted wait.
	TransitionKindWait TransitionKind = "wait"
	// TransitionKindPause enters an explicit scheduling pause.
	TransitionKindPause TransitionKind = "pause"
	// TransitionKindComplete commits a validated semantic Output.
	TransitionKindComplete TransitionKind = "complete"
	// TransitionKindFail commits a classified failure.
	TransitionKindFail TransitionKind = "fail"
)

func (TransitionKind) String 

func (t TransitionKind) String() string

func (TransitionKind) Valid 

func (t TransitionKind) Valid() bool

type TreeActivation 

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

TreeActivation transfers active-writer authority from one durable snapshot to a prospective snapshot with a freshly minted incarnation. Values are minted by Engine only.

func (TreeActivation) IncarnationID 

func (t TreeActivation) IncarnationID() TreeIncarnationID

func (TreeActivation) PreviousIncarnationID 

func (t TreeActivation) PreviousIncarnationID() TreeIncarnationID

func (TreeActivation) PreviousTreeDigest 

func (t TreeActivation) PreviousTreeDigest() Digest

func (TreeActivation) TreeSnapshot 

func (t TreeActivation) TreeSnapshot() TreeSnapshot

func (TreeActivation) Valid 

func (t TreeActivation) Valid() bool

type TreeCheckpoint 

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

TreeCheckpoint is an immutable Runtime-owned proposal to persist a safe whole-tree cut. Values are minted by Engine only.

func (TreeCheckpoint) Kind 

func (t TreeCheckpoint) Kind() TreeCheckpointKind

func (TreeCheckpoint) PreviousTreeDigest 

func (t TreeCheckpoint) PreviousTreeDigest() Digest

func (TreeCheckpoint) TreeSnapshot 

func (t TreeCheckpoint) TreeSnapshot() TreeSnapshot

func (TreeCheckpoint) Valid 

func (t TreeCheckpoint) Valid() bool

type TreeCheckpointKind 

type TreeCheckpointKind string

TreeCheckpointKind identifies a Runtime-owned durable program-counter cut. The zero value is invalid. 

const (
	TreeCheckpointInvalid  TreeCheckpointKind = ""
	TreeCheckpointParked   TreeCheckpointKind = "parked"
	TreeCheckpointTerminal TreeCheckpointKind = "terminal"
)

These boundaries name the exact points at which durable state is committed. They are a closed vocabulary because recovery reasons about them directly: a boundary the kernel cannot name is one it cannot resume from.

func (TreeCheckpointKind) String 

func (t TreeCheckpointKind) String() string

func (TreeCheckpointKind) Valid 

func (t TreeCheckpointKind) Valid() bool

type TreeDurability 

type TreeDurability interface {
	ProcessStartOutcomeAcknowledger
	// ActivateTree atomically fences the previous incarnation and installs the
	// prospective snapshot before a restored tree is published.
	ActivateTree(ctx context.Context, activation TreeActivation) error
	// CommitEffect atomically records one Effect fact and advances the tree head.
	CommitEffect(ctx context.Context, boundary EffectBoundary) error
	// CommitCheckpoint atomically advances the tree head to a Runtime-owned safe cut.
	CommitCheckpoint(ctx context.Context, checkpoint TreeCheckpoint) error
}

TreeDurability is the complete Host port for active recovery. Every boundary that carries a prospective tree must atomically compare and advance the same authoritative head; root-aborted outcomes only close their admission fact. The implementation owns storage, transactions, product facts, deadlines, and ambiguous-commit reconciliation; Engine owns ordering and fencing.

type TreeIncarnationID 

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

TreeIncarnationID identifies the one active writer generation of a durable Process tree. Its zero value is invalid.

func ParseTreeIncarnationID 

func ParseTreeIncarnationID(value string) (TreeIncarnationID, error)

ParseTreeIncarnationID validates the canonical wire representation of a tree incarnation identity.

func (TreeIncarnationID) MarshalText 

func (t TreeIncarnationID) MarshalText() ([]byte, error)

func (TreeIncarnationID) String 

func (t TreeIncarnationID) String() string

func (*TreeIncarnationID) UnmarshalText 

func (t *TreeIncarnationID) UnmarshalText(text []byte) error

func (TreeIncarnationID) Valid 

func (t TreeIncarnationID) Valid() bool

type TreeLimits 

type TreeLimits struct {
	// MaxDepth bounds the root-relative depth of any Process.
	MaxDepth uint32 `json:"max_depth"`
	// MaxChildren bounds the lifetime child count of one Process.
	MaxChildren uint32 `json:"max_children"`
	// MaxActiveChildren bounds concurrent non-terminal children of one Process.
	MaxActiveChildren uint32 `json:"max_active_children"`
	// MaxTreeProcesses bounds the lifetime Process count of one tree.
	MaxTreeProcesses uint32 `json:"max_tree_processes"`
}

TreeLimits bounds structural expansion independently of per-Process work limits. Every zero field in EngineConfig inherits DefaultTreeLimits.

func DefaultTreeLimits 

func DefaultTreeLimits() TreeLimits

DefaultTreeLimits returns conservative structured-concurrency bounds.

func (TreeLimits) Valid 

func (t TreeLimits) Valid() bool

type TreeSnapshot 

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

TreeSnapshot is an immutable, portable capture of one complete Process tree. It owns Framework execution facts, a canonical content digest, and the optional active-writer identity of durable state. Persistence, transactions, revisions, and cleanup policy remain Host responsibilities.

func ParseTreeSnapshot 

func ParseTreeSnapshot(data json.RawMessage) (TreeSnapshot, error)

ParseTreeSnapshot validates one complete Process tree snapshot. A syntactically valid foreign version is classified before the current wire shape is enforced.

func (TreeSnapshot) Digest 

func (t TreeSnapshot) Digest() Digest

Digest returns the canonical content identity of this complete tree state.

func (TreeSnapshot) IncarnationID 

func (t TreeSnapshot) IncarnationID() (TreeIncarnationID, bool)

IncarnationID returns the active writer identity carried by a durable tree. Ephemeral snapshots return false.

func (TreeSnapshot) JSON 

func (t TreeSnapshot) JSON() json.RawMessage

JSON returns an independently owned tree snapshot representation.

func (TreeSnapshot) MarshalJSON 

func (t TreeSnapshot) MarshalJSON() ([]byte, error)

func (TreeSnapshot) ProcessSnapshots 

func (t TreeSnapshot) ProcessSnapshots() []ProcessSnapshot

ProcessSnapshots returns immutable captures ordered by depth and ProcessID.

func (TreeSnapshot) RootID 

func (t TreeSnapshot) RootID() ProcessID

RootID returns the identity of the tree's root Process.

func (*TreeSnapshot) UnmarshalJSON 

func (t *TreeSnapshot) UnmarshalJSON(data []byte) error

func (TreeSnapshot) Valid 

func (t TreeSnapshot) Valid() bool

func (TreeSnapshot) Version 

func (t TreeSnapshot) Version() TreeSnapshotVersion

Version lets a Host route explicit migration before asking Engine to restore.

type TreeSnapshotVersion 

type TreeSnapshotVersion uint16

TreeSnapshotVersion identifies one exact durable wire contract. 

const (
	CurrentTreeSnapshotVersion TreeSnapshotVersion = 1
)

Exported defaults keep constructor behavior visible and overridable.

type Usage 

type Usage struct {
	// CommittedSteps counts finalized Steps.
	CommittedSteps uint64 `json:"committed_steps"`

	// PreparedEffects counts stable logical Effect identities, not replay attempts.
	PreparedEffects uint64 `json:"prepared_effects"`

	// AcceptedSignals counts external and Engine-generated mailbox entries.
	AcceptedSignals uint64 `json:"accepted_signals"`

	// DroppedDeltas counts increments rejected by validation or the bounded queue.
	DroppedDeltas uint64 `json:"dropped_deltas"`
}

Usage contains monotonic Framework-owned counters. It deliberately excludes provider pricing and Strategy-specific concepts such as tokens or tool calls.

type WaitID 

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

WaitID identifies one Engine-created external wait target. Parsing a WaitID does not create a wait; the Engine rejects identities it did not mint.

func ParseWaitID 

func ParseWaitID(value string) (WaitID, error)

ParseWaitID validates the wire representation of a Wait identity.

func (WaitID) MarshalText 

func (w WaitID) MarshalText() ([]byte, error)

func (WaitID) String 

func (w WaitID) String() string

func (*WaitID) UnmarshalText 

func (w *WaitID) UnmarshalText(text []byte) error

func (WaitID) Valid 

func (w WaitID) Valid() bool

type WaitKey 

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

WaitKey is an Execution-owned logical key used to associate a requested wait with the WaitID later minted by the Engine.

func ParseWaitKey 

func ParseWaitKey(value string) (WaitKey, error)

ParseWaitKey validates an Execution-owned logical wait key.

func (WaitKey) MarshalText 

func (w WaitKey) MarshalText() ([]byte, error)

func (WaitKey) String 

func (w WaitKey) String() string

func (*WaitKey) UnmarshalText 

func (w *WaitKey) UnmarshalText(text []byte) error

func (WaitKey) Valid 

func (w WaitKey) Valid() bool

Source Files

View all Source files

Directories

Path Synopsis
Package agenttest provides deterministic consumer-side fixtures and reusable conformance suites for the Agent Framework's public execution boundaries.
 Package agenttest provides deterministic consumer-side fixtures and reusable conformance suites for the Agent Framework's public execution boundaries.
examples
autonomous command
Command autonomous demonstrates an Interaction in which the model chooses a Tool from environment feedback and decides when to stop.
 Command autonomous demonstrates an Interaction in which the model chooses a Tool from environment feedback and decides when to stop.
composition command
Command composition demonstrates that direct Engine embedding and a cross-Strategy composed Agent use the same Definition/Execution/Process contracts.
 Command composition demonstrates that direct Engine embedding and a cross-Strategy composed Agent use the same Definition/Execution/Process contracts.
direct_vs_managed command
Command direct_vs_managed contrasts a direct model call with the same model capability managed as a recoverable agent Process.
 Command direct_vs_managed contrasts a direct model call with the same model capability managed as a recoverable agent Process.
embedded_vs_platform command
Command embedded_vs_platform proves that direct Engine embedding and the optional Platform deployment layer use one execution kernel and one set of Process semantics.
 Command embedded_vs_platform proves that direct Engine embedding and the optional Platform deployment layer use one execution kernel and one set of Process semantics.
evaluator_optimizer command
Command evaluator_optimizer demonstrates bounded evaluator-optimizer composition with exact managed child Processes.
 Command evaluator_optimizer demonstrates bounded evaluator-optimizer composition with exact managed child Processes.
orchestrator_workers command
Command orchestrator_workers demonstrates model-directed task decomposition, deterministic managed worker fan-out, and model synthesis without a Supervisor Strategy or runtime.
 Command orchestrator_workers demonstrates model-directed task decomposition, deterministic managed worker fan-out, and model synthesis without a Supervisor Strategy or runtime.
workflow command
Command workflow demonstrates an ordered managed Workflow whose Call and Fork Stages create independently recoverable child Processes.
 Command workflow demonstrates an ordered managed Workflow whose Call and Fork Stages create independently recoverable child Processes.
workflow_patterns command
Command workflow_patterns demonstrates prompt chaining, routing, parallel sectioning, and parallel voting through one managed Workflow.
 Command workflow_patterns demonstrates prompt chaining, routing, parallel sectioning, and parallel voting through one managed Workflow.
Package interaction provides the model-directed execution Strategy for the Agent Framework.
 Package interaction provides the model-directed execution Strategy for the Agent Framework.
Package planning provides goal-directed state planning as an Agent execution strategy.
 Package planning provides goal-directed state planning as an Agent execution strategy.
goap
Package goap provides deterministic goal-oriented action planning over immutable planning.WorldState values.
 Package goap provides deterministic goal-oriented action planning over immutable planning.WorldState values.
Package platform provides optional multi-Deployment catalog, routing, and governance capabilities above the Agent Engine.
 Package platform provides optional multi-Deployment catalog, routing, and governance capabilities above the Agent Engine.
Package workflow provides deterministic orchestration of Framework-managed child Processes.
 Package workflow provides deterministic orchestration of Framework-managed child Processes.

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.