run

type AIGoalPartInput struct {
	// ActorID references the roster sdk.Actor that runs this Part's
	// loop — becomes sdk.AIGoalSection.ActorID verbatim.
	ActorID string
	// Goal is this Part's own goal.Goal, including its own goal.Budgets —
	// each ai-goal Part carries its own budgets, independent of any
	// Run.Ceiling (see RunCeiling).
	Goal goal.Goal
	// Provider proposes this Part's actions — any actor.Provider, including
	// actor.NewScriptedProvider for a zero-token, fully deterministic Part.
	Provider actor.Provider
	// Config configures the actor.Loop this Part runs. ChatID and User are
	// required (also used to construct this Part's own observe.Engine).
	// Config.Now is always overwritten with the owning Run's
	// Environment.Now before the loop starts — a caller-set value here is
	// never consulted, so it may be left nil.
	Config actor.Config
}

type AssembleBundleRunInput struct {
	// RunID, Platform and EndpointProfile become sdk.Run's own fields —
	// see sdk.Run.ID/Platform/EndpointProfile.
	RunID           string
	Platform        string
	EndpointProfile string
	// Actors is the run's roster — see sdk.Run.Actors.
	Actors []sdk.Actor
	// Chats is the run's full, final per-chat journal — the same shape
	// SingleAIGoalRunInput.Chats expects (every entry the whole Run
	// produced, in each chat, from the very start); build each entry with
	// WireJournal.
	Chats []sdk.ChatJournal
	// Result is a completed Run.Execute's own return value.
	Result Result
	// Bookmarks and Annotations become the Run's own fields verbatim — see
	// sdk.Run.Bookmarks/Annotations.
	Bookmarks   []sdk.Bookmark
	Annotations []sdk.Annotation
}

type CeilingTrip struct {
	Reason goal.StopReason
	PartID string
}

type DeterministicOutcome struct {
	Definition  cw.Definition
	Steps       []cw.StepEvidence
	Checkpoints []cw.CheckpointEvidence
	Branches    []cw.BranchEvidence
	Failures    []cw.FailureEvidence
}

type Environment struct {
	// Emulator is the shared platform.Emulator every Part acts against.
	Emulator platform.Emulator
	// ChatIDs is every chat this run's journal spans, in the order boundary
	// entries are reported. Must be non-empty — see ErrNoChatIDs.
	ChatIDs []int64
	// Now supplies this run's notion of the current time — see the package
	// doc comment for why this is never time.Now internally. Must not be
	// nil — see ErrNilClock.
	Now func() time.Time
}

type FailurePolicy string

type Part struct {
	// ID is caller-supplied and only needs to be unique within its Run —
	// mirrors sdk.Part.ID, since AssembleBundleRun copies it there
	// verbatim for every Part that actually executed.
	ID string
	// Title is an optional human-readable label — see sdk.Part.Title.
	Title string
	// Kind discriminates this Part's payload — sdk.PartKindDeterministic
	// or sdk.PartKindAIGoal, reusing the sdk's own wire vocabulary rather
	// than a parallel enum.
	Kind sdk.PartKind
	// FailurePolicy declares what happens to the rest of the Run if this
	// Part fails — see FailurePolicy.
	FailurePolicy FailurePolicy
	// contains filtered or unexported fields
}

type PartOutcome struct {
	PartID string
	Title  string
	Kind   sdk.PartKind
	Status PartStatus
	// Err is set when Status is PartFailed: the deterministic Fragment's
	// own error, or the ai-goal Loop.RunTask's own error.
	Err error
	// Boundary is this Part's slice of the run-level journal, computed by
	// diffBoundary from Environment snapshots taken immediately before and
	// after the Part ran.
	Boundary sdk.JournalBoundary
	// Deterministic is set for a deterministic Part: the retained
	// cw.FragmentInvocation provenance (definition, steps,
	// checkpoints, branches, failures) — see DeterministicOutcome.
	Deterministic *DeterministicOutcome
	// AIGoal is set for an ai-goal Part that at least started running (any
	// status except one the Run never reached): the same shape
	// sdk.AIGoalSection carries, ready to attach to a sdk.Part
	// verbatim.
	AIGoal *sdk.AIGoalSection
	// CeilingTrip is set exactly on the one PartOutcome where Run.Ceiling
	// tripped (Status will be PartCeilingStopped), nil otherwise.
	CeilingTrip *CeilingTrip
}

type PartStatus string

type Result struct {
	// RunID mirrors Run.ID.
	RunID string
	// Parts is every Part that actually executed (PartCompleted,
	// PartFailed or PartCeilingStopped — see PartStatus), in the order it
	// ran. AssembleBundleRun turns this directly into a sdk.Run's Parts.
	Parts []PartOutcome
	// Skipped is every Part the Run never reached (PartAborted or
	// PartCoverageGap), in declared order, once execution stopped short.
	Skipped []SkippedPart
	// CeilingTrip is set once Ceiling ever tripped during this Run, nil
	// otherwise — mirrors whichever PartOutcome.CeilingTrip actually
	// tripped it, kept at Result level too so a caller never has to scan
	// Parts to learn whether the run-level ceiling fired at all.
	CeilingTrip *CeilingTrip
}

type Run struct {
	// ID identifies this Run — required (cw.NewExecutionContext,
	// which threads deterministic-Part provenance across the whole Run,
	// needs a non-empty root path/definition name) and, conventionally, the
	// same value later given to sdk.Run.ID when assembling evidence.
	ID string
	// Environment is the one platform.Emulator (plus its declared chat IDs
	// and clock) every Part executes over — see Environment.
	Environment Environment
	// Parts is this Run's ordered passages — see Part, NewDeterministicPart,
	// NewAIGoalPart.
	Parts []Part
	// Ceiling optionally aggregates ai-goal step/cost/duration usage across
	// every Part in the Run, on top of each ai-goal Part's own
	// goal.Budgets — see RunCeiling. The zero value means "no run-level
	// ceiling", mirroring goal.Budgets' own "zero means unlimited"
	// convention.
	Ceiling RunCeiling
}

type RunCeiling struct {
	// MaxSteps caps the total number of actor.LoopEvents recorded across
	// every ai-goal Part in the Run.
	MaxSteps int
	// MaxCost caps the total accrued actor.Usage.Cost across every ai-goal
	// Part in the Run. Nil means cost is not budgeted at the run level,
	// mirroring goal.Budgets.MaxCost.
	MaxCost *float64
	// MaxDuration caps wall-clock time elapsed (per Environment.Now) since
	// Run.Execute started, checked between an ai-goal Part's tasks.
	MaxDuration time.Duration
}

type SingleAIGoalRunInput struct {
	// RunID is caller-supplied — see sdk.Run.ID.
	RunID string
	// Platform is the platform name the run drove — see sdk.Run.Platform.
	Platform string
	// EndpointProfile is the run's declared endpoint profile — see
	// sdk.Run.EndpointProfile, sdk.EndpointProfilePlatformEmulated.
	EndpointProfile string
	// Actors is the run's roster — see sdk.Run.Actors.
	Actors []sdk.Actor
	// Chats is the run's continuous per-chat journal — see sdk.Run.Chats;
	// build each entry with WireJournal from the emulator's own Journal.
	Chats []sdk.ChatJournal

	// PartID and PartTitle name the single ai-goal Part this run gets — see
	// sdk.Part.ID, sdk.Part.Title.
	PartID    string
	PartTitle string

	// ActorID references the Actors entry that ran the loop — see
	// sdk.AIGoalSection.ActorID.
	ActorID string

	// Goal is the goal.Goal the part's actor loop ran; it becomes the
	// part's sdk.AIGoalSection.Goal.
	Goal goal.Goal
	// Events is every actor.LoopEvent the loop recorded (actor.Loop.Events),
	// in the loop's own order; it becomes sdk.AIGoalSection.Events.
	Events []actor.LoopEvent
	// Observations is the raw retained-observation map exactly as
	// actor.Loop.Observations returns it. SingleAIGoalRun sorts it ascending
	// by Sequence and converts it internally — absorbing the pre-split
	// bundle package's SortObservations — so a caller never orders (or
	// wire-converts) observations by hand. See sdk.AIGoalSection.Observations
	// for why the stored form is an ordered slice, not this map.
	Observations map[int64]observe.Observation
	// Report is the part's assembled campaign.Report (campaign.Assemble); it
	// becomes sdk.AIGoalSection.Report.
	Report campaign.Report
	// Evidence is the datastate.Evidence any data-state assertions produced,
	// in the order they were run; it becomes sdk.AIGoalSection.Evidence.
	Evidence []datastate.Evidence

	// Bookmarks and Annotations become the Run's own fields verbatim — see
	// sdk.Run.Bookmarks, sdk.Run.Annotations. Both are optional: a caller
	// with nothing to attach leaves them nil, and the resulting Run carries
	// none (SingleAIGoalRun never invents one).
	Bookmarks   []sdk.Bookmark
	Annotations []sdk.Annotation
}

type SkippedPart struct {
	PartID string
	Status PartStatus // PartAborted or PartCoverageGap.
}