runtime

type ArtifactStore interface {
	// Put stores an artifact and returns its key.
	Put(ctx context.Context, loopID event.LoopID, seq uint64, data []byte) (string, error)
	// Get retrieves an artifact by key.
	Get(ctx context.Context, key string) ([]byte, error)
}

type ChildResult struct {
	LoopID      event.LoopID
	OutcomeKind string
	RespJSON    []byte
	ErrDetail   string
	Spend       budget.Spend
}

type ChildSpawner interface {
	// SpawnChild executes a new child loop and returns its result.
	// opts is the current parent runner options (shared store/provider/tools).
	// parentID and depth come from the parent's LoopStarted event.
	SpawnChild(
		ctx context.Context,
		opts RunnerOptions,
		parentID event.LoopID,
		depth int,
		childBudget budget.Budget,
		childGrant policy.Grant,
		definitionName string,
		request []byte,
	) ChildResult

	// ResumeChild resumes an existing unfinished child loop by ID.
	// definitionName is used to look up the correct typed runner.
	ResumeChild(
		ctx context.Context,
		opts RunnerOptions,
		childID event.LoopID,
		definitionName string,
	) ChildResult
}

type Clock interface {
	// Now returns the current time.
	Now() time.Time
}

type CompactionPlan struct {
	// Strategy is the name of the strategy that produced this plan.
	Strategy string `json:"strategy"`
	// DropRanges is a list of [from, to] message index ranges to remove.
	DropRanges [][2]int `json:"drop_ranges,omitempty"`
	// Summaries is a list of summary insertions to inject.
	Summaries []SummarySpec `json:"summaries,omitempty"`
	// Offloads is a list of message indices to offload to the ArtifactStore.
	Offloads []OffloadSpec `json:"offloads,omitempty"`
}

type ContextManager interface {
	// Plan decides whether and how to compact the message history.
	// ledger tracks per-source token totals for the current loop run.
	// msgs is the current message slice.
	// Returns (planJSON, true) if compaction is needed, (nil, false) otherwise.
	// planJSON is the serialised plan stored verbatim in CompactionApplied.PlanJSON.
	Plan(ledger *ctxmgr.Ledger, msgs []model.Message) (planJSON []byte, needed bool)
	// ApplyPlanJSON transforms the message slice according to a previously
	// recorded plan (from CompactionApplied.PlanJSON). Called during replay.
	ApplyPlanJSON(planJSON []byte, msgs []model.Message) []model.Message
	// StrategyName returns the strategy identifier for CompactionApplied.Strategy.
	StrategyName() string
}

type ErrForkBeyondLog struct {
	At      uint64
	LastSeq uint64
}

type EventStore interface {
	// Append atomically appends evs to the loop's event log.
	// expectedLastSeq must equal the current last sequence number of the loop
	// (0 if no events have been written yet). Returns ErrConflict if the
	// actual last seq differs — the caller must reload and retry.
	// All events in evs must be pre-populated (LoopID, Seq, Time, Kind, Payload, Hash).
	Append(ctx context.Context, id event.LoopID, expectedLastSeq uint64, evs []event.Envelope) error

	// Load returns events for the given loop starting at fromSeq (inclusive).
	// fromSeq=1 returns all events. The iterator yields events in seq order.
	// An error in the iterator terminates iteration.
	Load(ctx context.Context, id event.LoopID, fromSeq uint64) iter.Seq2[event.Envelope, error]

	// SaveSnapshot persists a snapshot for later use by Resume.
	SaveSnapshot(ctx context.Context, snap event.Snapshot) error

	// LatestSnapshot returns the most recent snapshot for the given loop.
	// Returns (snap, true, nil) if found, or (Snapshot{}, false, nil) if not.
	LatestSnapshot(ctx context.Context, id event.LoopID) (event.Snapshot, bool, error)

	// List returns summary metadata for loops matching the filter.
	List(ctx context.Context, f ListFilter) ([]LoopMeta, error)
}

type ForkSpec struct {
	// At is the sequence number at which to diverge. Events 1..At are replayed
	// from the source log; everything after is executed live with Overrides applied.
	At uint64
	// Overrides replaces components for the live portion.
	Overrides Overrides
}

type ListFilter struct {
	// Status filters by loop status. Empty string means all statuses.
	Status string
	// Limit caps the number of results (0 = no limit).
	Limit int
	// Offset skips this many results (for pagination).
	Offset int
	// ParentID filters by parent loop ID (SP5: recursive resume).
	// Empty string means no parent filter.
	ParentID string
}

type LoopMeta struct {
	// ID is the loop's unique identifier.
	ID event.LoopID
	// Name is the human-readable loop name (from LoopStarted).
	Name string
	// CreatedAt is when the loop was started.
	CreatedAt time.Time
	// LastSeq is the sequence number of the most recent event.
	LastSeq uint64
	// Status is the current loop status: "running", "completed", "interrupted", "failed".
	Status string
	// ParentID is the parent loop's ID (empty for root loops). SP5.
	ParentID string
}

type ModelProvider interface {
	// Complete sends a request to the model and returns its complete response.
	// The response includes content, stop reason, and usage information.
	Complete(ctx context.Context, req model.Request) (model.Response, error)
	// Stream sends a request to the model and returns a StreamReader for reading chunks.
	// Each chunk represents an incremental update to the response.
	// The caller must call Close() on the reader to free resources.
	Stream(ctx context.Context, req model.Request) (StreamReader, error)
}

type NoopTelemetry struct{}

type OffloadSpec struct {
	// MessageIndex is the index in the message slice to offload.
	MessageIndex int `json:"message_index"`
	// ArtifactKey is the key under which the content is stored.
	ArtifactKey string `json:"artifact_key,omitempty"` // set after Put
}

type Overrides struct {
	// Provider replaces the ModelProvider for the live portion of the fork.
	Provider ModelProvider
	// Model overrides the model name for all ModelCall actions.
	Model string
	// SystemPatch is prepended to all system prompts in ModelCall requests.
	SystemPatch string
	// Tools replaces the ToolExecutor for the live portion of the fork.
	Tools ToolExecutor
}

type PolicyMode int

type RealClock struct{}

type ReplayDivergenceError struct {
	// Seq is the sequence number of the first divergent event.
	Seq uint64
	// Want is the expected (stored) hash.
	Want [32]byte
	// Got is the recomputed hash.
	Got [32]byte
}

type Runner[S, R any] struct {
	// contains filtered or unexported fields
}

type RunnerOptions struct {
	Store          EventStore
	Provider       ModelProvider
	Tools          ToolExecutor
	Clock          Clock
	SnapshotEvery  int // take snapshot every N events (0 = disabled)
	Seed           int64
	MaxIterations  int            // 0 = unlimited
	PricingTable   model.Table    // pricing for model cost calculation; nil uses model.DefaultTable
	StreamObserver StreamObserver // optional callback for streaming chunks; nil disables

	// SP3: governance
	Budget         budget.Budget    // zero = no budget enforcement
	TokenEstimator TokenEstimator   // nil = default heuristic (chars/4 + MaxTokens)
	Policy         *policy.Grant    // nil = allow-all (back-compat)
	PolicyMode     PolicyMode       // default: PolicyModeTerminate
	Convergence    *converge.Config // nil = no convergence monitoring

	// SP5: multi-agent
	Spawner       ChildSpawner  // nil = Spawn actions return ErrUnsupported
	ArtifactStore ArtifactStore // nil = ArtifactOffload not available
	// CtxMgr is the context manager strategy. nil = no compaction.
	CtxMgr ContextManager

	// SP6: telemetry — nil uses NoopTelemetry (zero hot-path alloc).
	Telemetry Telemetry
}

type Sandbox interface {
	// Run executes the given sandbox spec and returns the result.
	// If ctx is cancelled or exceeds its deadline, the sandbox must stop
	// execution and return an error.
	Run(ctx context.Context, spec SandboxSpec) (SandboxResult, error)
}

type SandboxResult struct {
	// Output is the tool's stdout as JSON.
	Output []byte
	// Stderr is the tool's stderr output.
	Stderr []byte
}

type SandboxSpec struct {
	// Module is the WASM binary (required for TierWASM).
	Module []byte
	// Fn is the in-process function (required for TierInProc).
	Fn func(ctx context.Context, input []byte) ([]byte, error)
	// Input is the JSON stdin for the tool.
	Input []byte
	// Caps are the capabilities granted to the sandbox.
	// fs:read:<dir> grants read-only access to that directory.
	Caps []policy.Capability
	// MemoryLimitPages sets the WASM memory limit in 64KiB pages.
	// 0 means use the default (typically 256 pages = 16 MiB).
	MemoryLimitPages uint32
}

type SpanAttrs struct {
	// ActionType is the action kind ("ModelCall", "ToolCall", "Finish", etc.).
	ActionType string
	// Tool is the tool name (only for ToolCall spans).
	Tool string
	// Model is the model identifier (only for ModelCall spans).
	Model string
	// InputTokens is the number of input tokens charged (GenAI semconv gen_ai.usage.input_tokens).
	InputTokens int64
	// OutputTokens is the number of output tokens charged.
	OutputTokens int64
	// CostUSD is the cost charged in US dollars.
	CostUSD float64
	// Outcome is the final outcome kind (for run-level spans).
	Outcome string
	// Iteration is the iteration number (for iteration spans).
	Iteration int
}

type SpanID [16]byte

type SpanKind string

type StreamObserver func(loopID event.LoopID, chunk event.StreamChunk)

type StreamReader interface {
	// Recv returns the next chunk from the stream.
	// Returns io.EOF when the stream is complete.
	Recv() (event.StreamChunk, error)
	// Close closes the stream and frees resources.
	Close() error
}

type SummarySpec struct {
	// InsertAfter is the index after which to insert the summary message.
	InsertAfter int `json:"insert_after"`
	// Content is the summary text.
	Content string `json:"content"`
}

type Telemetry interface {
	// OnEvent is called after each event is appended to the store.
	// Must return quickly (no blocking I/O on the hot path).
	OnEvent(ev event.Envelope)

	// SpanStart records the beginning of a span. Returns an opaque SpanID.
	// kind indicates the semantic level; attrs provides initial attributes.
	SpanStart(kind SpanKind, loopID event.LoopID, attrs SpanAttrs) SpanID

	// SpanEnd closes a previously started span.
	// attrs may carry final attributes not known at SpanStart (e.g. token counts).
	// elapsed is the wall-clock duration of the span.
	SpanEnd(id SpanID, attrs SpanAttrs, elapsed time.Duration, err error)

	// RecordSpend records a resource charge (counters and histograms).
	RecordSpend(loopID event.LoopID, spend budget.Spend, actionType string)
}

type Tier string

type TokenEstimator func(req model.Request) int64

type ToolDescriptor struct {
	// Name is the tool's unique identifier.
	Name string
	// Description explains what the tool does (shown to the model).
	Description string
	// Schema is the JSON schema for the tool's arguments.
	Schema []byte
	// Semantics controls crash-resume behavior for this tool.
	Semantics action.ReplaySemantics
	// RequiredCapabilities is the list of capability tokens needed (SP3).
	RequiredCapabilities []string
	// Tier specifies the sandbox execution tier for this tool (zero value = TierInProc).
	Tier Tier
}

type ToolExecutor interface {
	// Execute runs the named tool with the given request.
	Execute(ctx context.Context, call ToolRequest) (ToolResult, error)
	// Describe returns metadata about all available tools.
	Describe() []ToolDescriptor
}

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

type ToolRequest struct {
	// Tool is the tool name.
	Tool string
	// Args is the tool arguments as canonical JSON.
	Args []byte
	// IdempotencyKey is a stable key for this specific call, used to deduplicate.
	IdempotencyKey string
}

type ToolResult struct {
	// Result is the tool's output as JSON.
	Result []byte
	// IsError indicates whether the tool returned an error.
	IsError bool
}

type Trajectory[S any] struct {
	// Events is the full ordered event log.
	Events []event.Envelope
	// FinalState is the state after all events have been folded.
	FinalState S
	// Outcome is the terminal outcome (nil if loop has not finished).
	Outcome outcome.Outcome[S]
}