runtime

type CommitStore interface {
	// Commit applies one run's outputs and advances the offset, atomically.
	Commit(ctx context.Context, batch models.CommitBatch) error
	// ActivateReplay installs a prepared replay: claims, removed structure,
	// node-KV reconciliation, and the consumer checkpoint, in one transaction.
	ActivateReplay(ctx context.Context, profileID string, tail int64, claims []models.FeedClaim, feedIDs, sourceIDs, kvNodeIDs []string) error
}

type ConsoleLine struct {
	Level string `json:"level"`
	Text  string `json:"text"`
}

type ConsoleSink func(level, text string)

type DryRunResult struct {
	// Nodes is one entry per node a message reached, in execution order.
	Nodes []NodeTrace `json:"nodes"`
	// Outputs is what the terminals would have committed — feed memberships,
	// notifications and enqueued actions — had this been a live run.
	Outputs []models.Output `json:"outputs"`
	// FeedSnapshots is the reconciliation scope each snapshot input declared.
	// An empty snapshot still produces one: it is how a clean poll clears a
	// feed, so a dry run has to show it.
	FeedSnapshots []models.FeedSnapshot `json:"feedSnapshots"`
	// KVMutations is what the run would have written to durable node KV. The
	// values are the sandbox's, so this reads as "given the kv you seeded, here
	// is what the flow would store".
	KVMutations []models.KVMutation `json:"kvMutations"`
	// ConsoleTruncated reports that the run produced more console output than
	// it kept.
	ConsoleTruncated bool `json:"consoleTruncated,omitempty"`
}

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

type EngineOptions struct {
	Log     LogStore
	Items   InboxReader
	Commits CommitStore
	KV      KVReader
	Flows   Flows
	Scripts *ScriptRegistry
	Logger  zerolog.Logger
	// PageSize bounds one read. Zero means DefaultPageSize.
	PageSize int
	// Events receives InboxUpdated after a pass commits at least one flow.
	// Appending an unrouted log message does not emit this event.
	Events *events.Bus
	// Recorder reports install failures while the engine keeps the last known-good
	// flow active.
	Recorder activity.Recorder
}

type Flows interface {
	List() []flow.Flow
}

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

type InboxReader interface {
	ListUnarchived(ctx context.Context, profileID string) ([]stores.InboxItem, error)
}

type KVReader interface {
	Get(ctx context.Context, flowID, nodeID, key string, now int64) (value string, found bool, err error)
	Keys(ctx context.Context, flowID, nodeID, prefix string, now int64) ([]string, error)
}

type LogStore interface {
	// ReadForConsumer returns the next page after a consumer's committed
	// offset, with payloads only for the routed topics.
	ReadForConsumer(ctx context.Context, consumer string, limit int, routed models.RoutedTopics) ([]models.Msg, error)
	// TailOffset is the log's high-water mark, the point a replay
	// fast-forwards its consumer to.
	TailOffset(ctx context.Context) (int64, error)
	// ListLatestSnapshots returns each source's newest authoritative snapshot
	// at or before an offset.
	ListLatestSnapshots(ctx context.Context, profileID string, throughOffset int64) ([]models.Msg, error)
}

type MemoryKV map[string]map[string]string

type NodeError struct {
	Message string          `json:"message"`
	Kind    ScriptErrorKind `json:"kind,omitempty"`
	Line    int             `json:"line,omitempty"`
	Column  int             `json:"column,omitempty"`
	Stack   string          `json:"stack,omitempty"`
}

type NodeKV interface {
	Get(ctx context.Context, key string) (value string, found bool, err error)
	Set(ctx context.Context, key, value string, ttlSeconds int64) error
	Has(ctx context.Context, key string) (bool, error)
	Delete(ctx context.Context, key string) error
	Keys(ctx context.Context, prefix string) ([]string, error)
}

type NodeTrace struct {
	NodeID string `json:"nodeId"`
	Type   string `json:"type"`
	// Disabled marks a node that dropped everything without running, which is
	// otherwise indistinguishable from a node that chose to drop everything.
	Disabled bool `json:"disabled,omitempty"`
	// In, Out and Dropped are the same counters a live run records: messages
	// received, messages emitted or committed, and messages this node ended.
	In      int `json:"in"`
	Out     int `json:"out"`
	Dropped int `json:"dropped"`
	// OK is false when at least one message failed here.
	OK bool `json:"ok"`
	// Error is the last failure, structured when the node is a script.
	Error *NodeError `json:"error,omitempty"`
	// DurationMs is the total time spent in this node's processor.
	DurationMs int64 `json:"durationMs"`
	// Received is every message that arrived at this node's input, snapshots
	// already expanded into their items.
	Received []models.Msg `json:"received"`
	// Emitted is what the node put on each of its output ports, in port order.
	// A port with no wire behind it is still reported — what the node produced
	// does not depend on what is listening. Terminals emit nothing; read
	// Received and the run's Outputs for those.
	Emitted []PortEmission `json:"emitted"`
	// Console is the node's console output, oldest first.
	Console []ConsoleLine `json:"console,omitempty"`
}

type Options struct {
	// Scripts is the registry function nodes resolve their language through.
	Scripts *ScriptRegistry
	// KV is the durable node-KV read port; nil means every read misses
	// (preview, dry-run, tests).
	KV KVReader
}

type PortEmission struct {
	Port     int          `json:"port"`
	Messages []models.Msg `json:"messages"`
}

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

type ScriptError struct {
	Kind    ScriptErrorKind `json:"kind"`
	Message string          `json:"message"`
	Line    int             `json:"line,omitempty"`
	Column  int             `json:"column,omitempty"`
	// Stack is the language's own trace, kept whole for the editor. It is
	// never parsed.
	Stack string `json:"stack,omitempty"`
}

type ScriptErrorKind string

type ScriptInstance interface {
	// OnMessage evaluates the script for msg and returns its outputs indexed
	// by output port. config is the node's own config, passed as the script's
	// `node` argument; kv is the node's per-message durable-KV handle and
	// console its per-message console sink. A returned error is always a
	// *ScriptError.
	OnMessage(ctx context.Context, msg models.Msg, config any, kv NodeKV, console ConsoleSink) ([][]models.Msg, error)
	// Close releases the instance. An instance whose evaluation timed out may
	// still be running, in which case Close interrupts it and returns without
	// waiting.
	Close()
}

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

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

type ScriptRuntime interface {
	// Name is the language this runtime registers under.
	Name() string
	// Check reports whether src compiles, without running it. The editor's
	// live syntax check is a core concern, so it goes through the same
	// compiler the engine uses rather than a second parser.
	Check(src string) error
	// New compiles src into an instance with its own isolated state. outputs
	// is the node's declared output-port count: it is what disambiguates a
	// language's overloaded return shapes, so the engine only ever receives
	// port-indexed values.
	New(src string, outputs int) (ScriptInstance, error)
}