stage

Documentation

Overview

Package stage owns typed pipeline and canonical tool-dispatch SPIs.

@import { NamedInterface } from "github.com/spice-framework/spice/annotation/modulith" @NamedInterface("stage")

Index

• type DispatchFailure
  • func (failure *DispatchFailure) Error() string
  • func (failure *DispatchFailure) ExecutionFailure() *tool.ExecutionError
  • func (failure *DispatchFailure) ReporterFailure() error
  • func (failure *DispatchFailure) Unwrap() error
• type Dispatcher
  • func NewDispatcher(tools map[string]tool.Tool) (*Dispatcher, error)
  • func (dispatcher *Dispatcher) Definition(name string) (tool.Definition, bool)
  • func (dispatcher *Dispatcher) Definitions() []tool.Definition
  • func (dispatcher *Dispatcher) Dispatch(ctx context.Context, scope ToolDispatchScope, call tool.Call, ...) (tool.Result, error)
• type PlanID
  • func NewPlanID(value string) (PlanID, error)
  • func (id PlanID) String() string
  • func (id PlanID) Validate() error
• type Stage
• type StaticToolPlanSource
  • func NewStaticToolPlanSource(dispatcher ToolDispatcher) (*StaticToolPlanSource, error)
  • func (source *StaticToolPlanSource) LeaseCurrent(ctx context.Context) (*ToolPlanLease, error)
  • func (source *StaticToolPlanSource) LeaseGeneration(ctx context.Context, id PlanID) (*ToolPlanLease, error)
• type ToolDispatchDecorator
• type ToolDispatchGuard
• type ToolDispatchNext
• type ToolDispatchScope
  • func NewToolDispatchScope(runID string, turn uint32, toolPlanID PlanID, planFingerprint string, ...) (ToolDispatchScope, error)
  • func (scope ToolDispatchScope) InteractionAuthority() interaction.Scope
  • func (scope ToolDispatchScope) PlanFingerprint() string
  • func (scope ToolDispatchScope) RequestInteraction(ctx context.Context, request interaction.Request) (interaction.Response, error)
  • func (scope ToolDispatchScope) RunID() string
  • func (scope ToolDispatchScope) ToolPlanID() PlanID
  • func (scope ToolDispatchScope) Turn() uint32
  • func (scope ToolDispatchScope) Validate() error
  • func (scope ToolDispatchScope) WorkspaceFingerprint() string
• type ToolDispatcher
  • func ApplyToolDispatchDecorators(base ToolDispatcher, decorators []ToolDispatchDecorator) (ToolDispatcher, error)
  • func ApplyToolDispatchPipeline(base ToolDispatcher, guards []ToolDispatchGuard, ...) (ToolDispatcher, error)
  • func SnapshotToolDispatcher(dispatcher ToolDispatcher) (ToolDispatcher, error)
• type ToolPlanLease
  • func NewToolPlanLease(id PlanID, dispatcher ToolDispatcher, release func() error) (*ToolPlanLease, error)
  • func (lease *ToolPlanLease) Definitions() []tool.Definition
  • func (lease *ToolPlanLease) Dispatcher() ToolDispatcher
  • func (lease *ToolPlanLease) Release() error
  • func (lease *ToolPlanLease) ReleaseContext(ctx context.Context) error
  • func (lease *ToolPlanLease) ToolPlanID() PlanID
  • func (lease *ToolPlanLease) Validate() error
• type ToolPlanSource

Types

type DispatchFailure

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

DispatchFailure preserves both a valid tool execution outcome and a progress reporter failure without joining their potentially sensitive text. It occurs only when both failures happen in one dispatch.

func (*DispatchFailure) Error

func (failure *DispatchFailure) Error() string

func (*DispatchFailure) ExecutionFailure

func (failure *DispatchFailure) ExecutionFailure() *tool.ExecutionError

ExecutionFailure returns the validated correlated execution failure.

func (*DispatchFailure) ReporterFailure

func (failure *DispatchFailure) ReporterFailure() error

ReporterFailure returns the reporter rejection for structured inspection.

func (*DispatchFailure) Unwrap

func (failure *DispatchFailure) Unwrap() error

Unwrap preserves execution errors.Is/errors.As inspection. Reporter failures are excluded from errors.Is so a reporter cancellation sentinel cannot misclassify the execution lifecycle.

type Dispatcher

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

Dispatcher is an immutable named tool snapshot constructed by Spice.

func NewDispatcher

func NewDispatcher(tools map[string]tool.Tool) (*Dispatcher, error)

NewDispatcher validates canonical bean names in sorted order and snapshots definitions and capabilities. Tool implementations remain trusted concurrent singleton beans.

func (*Dispatcher) Definition

func (dispatcher *Dispatcher) Definition(name string) (tool.Definition, bool)

Definition returns one immutable capability snapshot.

func (*Dispatcher) Definitions

func (dispatcher *Dispatcher) Definitions() []tool.Definition

Definitions returns snapshotted definitions ordered by canonical bean name.

func (*Dispatcher) Dispatch

func (dispatcher *Dispatcher) Dispatch(ctx context.Context, scope ToolDispatchScope, call tool.Call, reporter tool.Reporter) (tool.Result, error)

Dispatch validates correlation and cancellation around one trusted in-process call. Cancellation is cooperative: a Tool that ignores ctx can still block its own goroutine and therefore must be treated as trusted code.

type PlanID

type PlanID string

PlanID identifies one immutable tool-dispatch generation. A source must never reuse an ID for different definitions or executable behavior.

func NewPlanID

func NewPlanID(value string) (PlanID, error)

NewPlanID validates one tool-plan identity.

func (PlanID) String

func (id PlanID) String() string

String returns the stable wire representation.

func (PlanID) Validate

func (id PlanID) Validate() error

Validate rejects empty, unbounded, non-canonical, or control-bearing IDs.

type Stage

type Stage[Input, Output any] interface {
	Process(context.Context, Input) (Output, error)
}

Stage is one typed, constructor-injected pipeline transform. Each Input and Output instantiation is a distinct exact Go interface for Spice dependency resolution; it is not a runtime registry or universal middleware contract.

type StaticToolPlanSource

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

StaticToolPlanSource adapts an already-constructed dispatcher for embedded applications and preserves the existing Engine constructors.

func NewStaticToolPlanSource

func NewStaticToolPlanSource(dispatcher ToolDispatcher) (*StaticToolPlanSource, error)

NewStaticToolPlanSource creates a stable no-op leased source.

func (*StaticToolPlanSource) LeaseCurrent

func (source *StaticToolPlanSource) LeaseCurrent(ctx context.Context) (*ToolPlanLease, error)

LeaseCurrent leases the one static generation.

func (*StaticToolPlanSource) LeaseGeneration

func (source *StaticToolPlanSource) LeaseGeneration(ctx context.Context, id PlanID) (*ToolPlanLease, error)

LeaseGeneration leases the static generation only when the ID matches.

type ToolDispatchDecorator

type ToolDispatchDecorator interface {
	Wrap(ToolDispatcher) ToolDispatcher
}

ToolDispatchDecorator wraps the canonical dispatcher. Spice supplies these as an ordered typed collection.

type ToolDispatchGuard

type ToolDispatchGuard interface {
	Guard(context.Context, ToolDispatchScope, tool.Definition, tool.Call, ToolDispatchNext) (tool.Result, error)
}

ToolDispatchGuard is the terminal, innermost interception seam for policy. Guards may deny or invoke next exactly once. They do not own engine events.

type ToolDispatchNext

type ToolDispatchNext func() (tool.Result, error)

ToolDispatchNext is a single-use continuation bound to the immutable context, scope, definition, call, and reporter received by a guard.

type ToolDispatchScope

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

ToolDispatchScope is immutable authority and execution identity supplied by the engine for one tool dispatch. It contains no policy decision and grants no capability by itself.

func NewToolDispatchScope

func NewToolDispatchScope(
	runID string,
	turn uint32,
	toolPlanID PlanID,
	planFingerprint string,
	workspaceFingerprint string,
	interactionAuthority interaction.Scope,
	interactionRequester interaction.Requester,
) (ToolDispatchScope, error)

NewToolDispatchScope constructs the immutable facts visible to terminal guards. An empty workspace fingerprint is allowed only for deliberately non-portable embedded engines whose snapshot compatibility identity is empty.

func (ToolDispatchScope) InteractionAuthority

func (scope ToolDispatchScope) InteractionAuthority() interaction.Scope

func (ToolDispatchScope) PlanFingerprint

func (scope ToolDispatchScope) PlanFingerprint() string

func (ToolDispatchScope) RequestInteraction

func (scope ToolDispatchScope) RequestInteraction(
	ctx context.Context,
	request interaction.Request,
) (interaction.Response, error)

RequestInteraction invokes the run-owned interaction lifecycle without exposing broker Scope authority to a guard.

func (ToolDispatchScope) RunID

func (scope ToolDispatchScope) RunID() string

func (ToolDispatchScope) ToolPlanID

func (scope ToolDispatchScope) ToolPlanID() PlanID

func (ToolDispatchScope) Turn

func (scope ToolDispatchScope) Turn() uint32

func (ToolDispatchScope) Validate

func (scope ToolDispatchScope) Validate() error

Validate rejects incomplete or contradictory dispatch authority.

func (ToolDispatchScope) WorkspaceFingerprint

func (scope ToolDispatchScope) WorkspaceFingerprint() string

type ToolDispatcher

type ToolDispatcher interface {
	Definitions() []tool.Definition
	Definition(name string) (tool.Definition, bool)
	Dispatch(context.Context, ToolDispatchScope, tool.Call, tool.Reporter) (tool.Result, error)
}

ToolDispatcher is the sole executable route for tool calls. Definition gives decorators an immutable capability snapshot before they delegate execution.

func ApplyToolDispatchDecorators

func ApplyToolDispatchDecorators(
	base ToolDispatcher,
	decorators []ToolDispatchDecorator,
) (ToolDispatcher, error)

ApplyToolDispatchDecorators applies an already ordered collection only after the merged base dispatcher exists. The first decorator is the outermost and therefore observes a call first and its result last.

func ApplyToolDispatchPipeline

func ApplyToolDispatchPipeline(
	base ToolDispatcher,
	guards []ToolDispatchGuard,
	decorators []ToolDispatchDecorator,
) (ToolDispatcher, error)

ApplyToolDispatchPipeline installs terminal guards exactly once closest to the merged base, then applies trusted decorators with the first decorator outermost. A composed dispatcher cannot be composed again.

func SnapshotToolDispatcher

func SnapshotToolDispatcher(dispatcher ToolDispatcher) (ToolDispatcher, error)

SnapshotToolDispatcher freezes a dispatcher's declared definitions while preserving its trusted executable behavior. It does not install guards or decorators and therefore is not a substitute for ApplyToolDispatchPipeline.

type ToolPlanLease

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

ToolPlanLease owns one source-guaranteed immutable dispatcher generation and a host-captured definition snapshot. Go cannot structurally freeze executable behavior; the trusted source is responsible for stability until Release.

func NewToolPlanLease

func NewToolPlanLease(id PlanID, dispatcher ToolDispatcher, release func() error) (*ToolPlanLease, error)

NewToolPlanLease captures definitions and ownership for one source-guaranteed immutable generation; it does not clone executable Go behavior.

func (*ToolPlanLease) Definitions

func (lease *ToolPlanLease) Definitions() []tool.Definition

Definitions returns canonical defensive copies of the leased definitions.

func (*ToolPlanLease) Dispatcher

func (lease *ToolPlanLease) Dispatcher() ToolDispatcher

Dispatcher returns a dispatcher whose definitions are the leased snapshot.

func (*ToolPlanLease) Release

func (lease *ToolPlanLease) Release() error

Release relinquishes the generation at most once and waits for completion. Engine code uses ReleaseContext to impose its finalization bound.

func (*ToolPlanLease) ReleaseContext

func (lease *ToolPlanLease) ReleaseContext(ctx context.Context) error

ReleaseContext relinquishes the generation at most once. The first callback completion or context expiry becomes the same bounded observable result for every caller; a callback that violates the non-blocking contract is left in its isolated goroutine and cannot suppress run finalization.

func (*ToolPlanLease) ToolPlanID

func (lease *ToolPlanLease) ToolPlanID() PlanID

ToolPlanID returns the immutable generation identity.

func (*ToolPlanLease) Validate

func (lease *ToolPlanLease) Validate() error

Validate rejects nil or corrupted leases. A valid source returns a fresh lease for every successful acquisition.

type ToolPlanSource

type ToolPlanSource interface {
	LeaseCurrent(context.Context) (*ToolPlanLease, error)
	LeaseGeneration(context.Context, PlanID) (*ToolPlanLease, error)
}

ToolPlanSource is a trusted owner of immutable dispatch generations. LeaseCurrent selects the generation for a new run; LeaseGeneration must resolve exactly the requested generation for snapshot recovery without silently substituting. A source must never reuse a PlanID for changed definitions or executable behavior and must keep a leased dispatcher stable.