participation

package
v0.3.0-beta.13 Latest Latest
Warning

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

Go to latest
Published: Aug 11, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package participation owns the shared Network participation contract.

Index

Constants

View Source
const SpecVersion = "network-participation/v1"

Variables

View Source
var (
	ErrUnavailable             = errors.New("network_participation_unavailable")
	ErrChannelUnknown          = errors.New("network_channel_unknown")
	ErrStrategyInvalid         = errors.New("network_strategy_invalid")
	ErrStrategyChannelConflict = errors.New("network_strategy_channel_conflict")
	ErrAuthorityDenied         = errors.New("network_participation_permission_denied")
	ErrBoundsExceedCeiling     = errors.New("network_bounds_exceed_ceiling")
	ErrLoopRequiresLive        = errors.New("loop_requires_live")
	ErrLiveUnsupported         = errors.New("network_live_unsupported")
	ErrNotParticipating        = errors.New("not_participating")
)

Functions

func ObserveResolved

func ObserveResolved(
	ctx context.Context,
	resolver Resolver,
	observation ResolvedObservation,
) error

ObserveResolved publishes a committed snapshot when the resolver supports observations.

func OwnerKey

func OwnerKey(owner OwnerRef) string

OwnerKey returns the canonical budget-owner identity for one execution.

func ValidateOwner

func ValidateOwner(owner OwnerRef) error

ValidateOwner verifies that an execution owner has a supported kind and stable identity.

func ValidateOwnerKey

func ValidateOwnerKey(value string) error

ValidateOwnerKey verifies a canonical kind-prefixed budget-owner identity.

func ValidateSpec

func ValidateSpec(spec Spec) error

ValidateSpec verifies that an immutable participation snapshot is complete and internally consistent.

Types

type AuthorityFunc

type AuthorityFunc func(ctx context.Context, in ResolveInput, spec Spec) (bool, error)

type AuthorityScope

type AuthorityScope struct {
	Enforced   bool
	ChannelIDs []string
}

AuthorityScope carries the concrete channel grant delegated to one child execution.

type AvailabilityFunc

type AvailabilityFunc func(ctx context.Context) (bool, error)

type Bounds

type Bounds struct {
	MaxWakes         int    `json:"max_wakes"           yaml:"max_wakes"           toml:"max_wakes"`
	MaxWakeWallTime  string `json:"max_wake_wall_time"  yaml:"max_wake_wall_time"  toml:"max_wake_wall_time"`
	MaxTotalWallTime string `json:"max_total_wall_time" yaml:"max_total_wall_time" toml:"max_total_wall_time"`
	MaxInputTokens   int64  `json:"max_input_tokens"    yaml:"max_input_tokens"    toml:"max_input_tokens"`
	MaxOutputTokens  int64  `json:"max_output_tokens"   yaml:"max_output_tokens"   toml:"max_output_tokens"`
	MaxWakeDepth     int    `json:"max_wake_depth"      yaml:"max_wake_depth"      toml:"max_wake_depth"`
	CoalesceWindow   string `json:"coalesce_window"     yaml:"coalesce_window"     toml:"coalesce_window"`
}

func ResolveBounds

func ResolveBounds(request *BoundsRequest, defaults Bounds, limits Limits) (Bounds, error)

func (Bounds) IsZero

func (b Bounds) IsZero() bool

type BoundsRequest

type BoundsRequest struct {
	MaxWakes         *int    `json:"max_wakes,omitempty"           yaml:"max_wakes,omitempty"           toml:"max_wakes,omitempty"`
	MaxWakeWallTime  *string `json:"max_wake_wall_time,omitempty"  yaml:"max_wake_wall_time,omitempty"  toml:"max_wake_wall_time,omitempty"`
	MaxTotalWallTime *string `json:"max_total_wall_time,omitempty" yaml:"max_total_wall_time,omitempty" toml:"max_total_wall_time,omitempty"`
	MaxInputTokens   *int64  `json:"max_input_tokens,omitempty"    yaml:"max_input_tokens,omitempty"    toml:"max_input_tokens,omitempty"`
	MaxOutputTokens  *int64  `json:"max_output_tokens,omitempty"   yaml:"max_output_tokens,omitempty"   toml:"max_output_tokens,omitempty"`
	MaxWakeDepth     *int    `json:"max_wake_depth,omitempty"      yaml:"max_wake_depth,omitempty"      toml:"max_wake_depth,omitempty"`
	CoalesceWindow   *string `json:"coalesce_window,omitempty"     yaml:"coalesce_window,omitempty"     toml:"coalesce_window,omitempty"`
}

type ChannelExistsFunc

type ChannelExistsFunc func(ctx context.Context, workspaceID, channelID string) (bool, error)

type ChannelStrategy

type ChannelStrategy string
const (
	StrategyNamed   ChannelStrategy = "named"
	StrategyRun     ChannelStrategy = "run"
	StrategyLoopRun ChannelStrategy = "loop_run"
)

type Intent

type Intent struct {
	Request *Request
	Source  Source
}

Intent is the participation request and source selected before resolution.

type IntentResolver

type IntentResolver interface {
	Resolver
	SelectIntent(ctx context.Context, in ResolveInput) (Intent, error)
	ResolveIntent(ctx context.Context, in ResolveInput, intent Intent) (Spec, error)
}

IntentResolver exposes the selected intent so pre-resolve policy observes the same input as resolution.

type Limits

type Limits struct {
	MaxWakes          int
	MaxWakeWallTime   string
	MaxTotalWallTime  string
	MaxInputTokens    int64
	MaxOutputTokens   int64
	MaxWakeDepth      int
	MinCoalesceWindow string
	MaxCoalesceWindow string
}

func (Limits) Validate

func (l Limits) Validate() error

type LiveSupportFunc

type LiveSupportFunc func(ctx context.Context, in ResolveInput) (bool, error)

type Mode

type Mode string
const (
	ModeLocal Mode = "local"
	ModeLive  Mode = "live"
)

type OwnerKind

type OwnerKind string
const (
	OwnerKindSession       OwnerKind = "session"
	OwnerKindTaskRun       OwnerKind = "task_run"
	OwnerKindLoopRun       OwnerKind = "loop_run"
	OwnerKindAutomationRun OwnerKind = "automation_run"
)

type OwnerRef

type OwnerRef struct {
	WorkspaceID string    `json:"workspace_id"`
	Kind        OwnerKind `json:"kind"`
	ID          string    `json:"id"`
}

func OwnerRefFromKey

func OwnerRefFromKey(workspaceID, value string) (OwnerRef, error)

OwnerRefFromKey reconstructs a public owner reference at an internal owner-key boundary.

type Request

type Request struct {
	Mode            *Mode            `json:"mode,omitempty"             yaml:"mode,omitempty"             toml:"mode,omitempty"`
	ChannelStrategy *ChannelStrategy `json:"channel_strategy,omitempty" yaml:"channel_strategy,omitempty" toml:"channel_strategy,omitempty"`
	ChannelID       *string          `json:"channel_id,omitempty"       yaml:"channel_id,omitempty"       toml:"channel_id,omitempty"`
	Bounds          *BoundsRequest   `json:"bounds,omitempty"           yaml:"bounds,omitempty"           toml:"bounds,omitempty"`
}

func CloneRequest

func CloneRequest(request *Request) *Request

CloneRequest returns a deep copy of one unresolved participation intent.

func NormalizeIntent

func NormalizeIntent(request Request) (Request, error)

NormalizeIntent validates and canonicalizes persisted execution intent without resolving omitted live bounds against runtime defaults. Resolution remains the single place that fills defaults and enforces ceilings.

func Validate

func Validate(request Request) (Request, error)

func ValidateWithBounds

func ValidateWithBounds(request Request, defaults Bounds, limits Limits) (Request, error)

type ResolveInput

type ResolveInput struct {
	WorkspaceID   string
	Owner         OwnerRef
	Request       *Request
	RequestSource Source
	Definition    *Request
	RunID         string
	LoopRunID     string
	Coordinated   bool
	Authority     *AuthorityScope
}

type ResolvedObservation

type ResolvedObservation struct {
	WorkspaceID string
	Owner       OwnerRef
	Spec        Spec
}

ResolvedObservation binds one committed snapshot to its durable owner.

type ResolvedObserver

type ResolvedObserver interface {
	ObserveParticipationResolved(ctx context.Context, observation ResolvedObservation) error
}

ResolvedObserver receives one immutable snapshot only after its owner commits.

type Resolver

type Resolver interface {
	Resolve(ctx context.Context, in ResolveInput) (Spec, error)
}

func NewResolver

func NewResolver(options ResolverOptions) (Resolver, error)

type ResolverOptions

type ResolverOptions struct {
	Defaults              Bounds
	Limits                Limits
	Availability          AvailabilityFunc
	ChannelExists         ChannelExistsFunc
	WorkspaceCoordination WorkspaceCoordinationFunc
	LiveSupport           LiveSupportFunc
	Authority             AuthorityFunc
}

type Source

type Source string
const (
	SourceExplicitRequest       Source = "explicit_request"
	SourceTaskProfile           Source = "task_profile"
	SourceWorkspaceCoordination Source = "workspace_coordination"
	SourceLoopDefinition        Source = "loop_definition"
	SourceAutomationJob         Source = "automation_job"
	SourceBuiltInLocal          Source = "built_in_local"
)

type Spec

type Spec struct {
	Version         string          `json:"version"`
	Mode            Mode            `json:"mode"`
	WorkspaceID     string          `json:"workspace_id,omitempty"`
	ChannelStrategy ChannelStrategy `json:"channel_strategy,omitempty"`
	ChannelID       string          `json:"channel_id,omitempty"`
	Source          Source          `json:"source"`
	Bounds          Bounds          `json:"bounds,omitzero"`
}

func CloneSpec

func CloneSpec(spec Spec) *Spec

CloneSpec returns an independently addressable immutable participation snapshot.

func LocalSpec

func LocalSpec() Spec

LocalSpec returns the canonical zero-Network participation snapshot.

type Status

type Status struct {
	Owner         OwnerRef `json:"owner"`
	Available     bool     `json:"available"`
	Participating bool     `json:"participating"`
	Reason        string   `json:"reason,omitempty"`
}

Status is the public, read-only participation evidence for one execution owner.

type WorkspaceCoordinationFunc

type WorkspaceCoordinationFunc func(ctx context.Context, workspaceID string) (bool, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL