spec

type Batch interface {
	Messages() iter.Seq2[int, Message]
	Append(msg Message)
}

type Collector interface {
	Collect(msg Message) error
	Flush() (Batch, error)
	// Legacy methods for backward compatibility
	Write(msg Message) error
	Disconnect() error
}

type Component interface {
	// Init initializes the component with the given context.
	// This is called once before the component starts processing.
	Init(ctx ComponentContext) error

	// Close releases any resources held by the component.
	// This is called when the component is being shut down.
	Close(ctx ComponentContext) error
}

type ComponentConstructor[T Component] func(sys System, cfg Config) (T, error)

type ComponentContext interface {
	Logger
	ExpressionFactory
	MessageFactory
	MetadataFilterFactory

	Context() context.Context

	// Resource management
	Resources() ResourceManager

	// Component access (for cross-component communication)
	Input(name string) (Input, error)
	Output(name string) (Output, error)

	// System access (for shared client usage)
	System(name string) (System, error)
}

type ComponentFactory interface {
	// NewInput creates a new Input component using the provided system and configuration
	NewInput(sys System, cfg Config) (Input, error)

	// NewOutput creates a new Output component using the provided system and configuration
	NewOutput(sys System, cfg Config) (Output, error)
}

type ComponentSpec interface {
	// Name returns the component name used for registration
	Name() string

	// Summary returns a brief description of the component
	Summary() string

	// Description returns detailed documentation for the component
	Description() string

	// InputConfigSchema returns the JSON schema for input component configuration
	InputConfigSchema() string

	// OutputConfigSchema returns the JSON schema for output component configuration
	OutputConfigSchema() string

	// SystemConfigSchema returns the JSON schema for system configuration
	SystemConfigSchema() string
}

type Config interface {
	Decode(target any) error
}

type ConfigSchema interface {
	// AddField adds a configuration field to the schema
	AddField(field SchemaField) ConfigSchema

	// ToJSON returns the JSON schema representation
	ToJSON() (string, error)
}

type Counter interface {
	Inc(delta int64)
}

type DynamicField interface {
	String() string
	Int() int
	Bool() bool
	// Legacy methods for backward compatibility
	AsString(msg Message) (string, error)
	AsBool(msg Message) (bool, error)
}

type DynamicFieldFactory interface {
	NewDynamicField(expr string) DynamicField
}

type Environment interface {
	Logger
	DynamicFieldFactory
	GetString(key string) string
	GetInt(key string) int
	GetBool(key string) bool
}

type ExprLangExpressionFactory struct{}

type Expression interface {
	EvalString(ctx ExpressionContext) (string, error)
	EvalInt(ctx ExpressionContext) (int, error)
	EvalBool(ctx ExpressionContext) (bool, error)
}

type ExpressionContext map[string]any

type ExpressionFactory interface {
	ParseExpression(expr string) (Expression, error)
}

type Gauge interface {
	Set(value float64)
}

type Input interface {
	Component

	// Read retrieves a batch of data from the external source.
	// Returns the data batch and a callback to acknowledge processing.
	Read(ctx ComponentContext) (Batch, ProcessedCallback, error)
}

type Logger interface {
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

type Message interface {
	SetMetadata(key string, value any)
	SetRaw(b []byte)

	Raw() ([]byte, error)
	Metadata() iter.Seq2[string, any]
}

type MessageFactory interface {
	NewBatch() Batch
	NewMessage() Message
}

type Metadata interface {
	Keys() iter.Seq[string]
	Get(key string) any
}

type MetadataFilter interface {
	Include(key string) bool
}

type MetadataFilterFactory interface {
	BuildMetadataFilter(patterns []string, invert bool) (MetadataFilter, error)
}

type Metrics interface {
	Counter(name string) Counter
	Gauge(name string) Gauge
	Timer(name string) Timer
}

type Output interface {
	Component

	// Write sends a batch of data to the external destination.
	// The batch should be written atomically where possible.
	Write(ctx ComponentContext, batch Batch) error
}

type ProcessedCallback func(ctx context.Context, err error) error

type Processor interface {
	Component

	// Process transforms the input batch and returns the processed result.
	// Returns the transformed batch and a callback to acknowledge processing.
	Process(ctx ComponentContext, batch Batch) (Batch, ProcessedCallback, error)
}

type ResourceManager interface {
	Logger() Logger

	// System returns a shared system instance by name
	System(name string) (System, error)

	// RegisterSystem registers a system instance for sharing
	RegisterSystem(name string, sys System) error

	// Context returns the base context for operations
	Context() context.Context

	// Metrics returns a metrics interface (placeholder for future implementation)
	Metrics() Metrics
}

type RetrievalProcessor interface {
	Component

	// Retrieve fetches actual data based on the provided trigger events.
	// Can filter triggers before retrieval to optimize performance.
	Retrieve(ctx ComponentContext, triggers TriggerBatch) (Batch, ProcessedCallback, error)
}

type SchemaField struct {
	Name        string
	Type        string
	Description string
	Required    bool
	Default     any
	Examples    []any
}

type SelfContainedInput interface {
	Input // Inherits standard Input behavior
}

type System interface {
	Connect(ctx context.Context) error
	Close(ctx context.Context) error
	Client() any
}

type SystemConstructor func(cfg Config) (System, error)

type SystemFactory interface {
	// NewSystem creates a new System instance from raw configuration
	NewSystem(cfg Config) (System, error)
}

type Timer interface {
	Record(duration float64)
}

type TriggerBatch interface {
	// Triggers returns all trigger events in this batch.
	Triggers() []TriggerEvent

	// Append adds a new trigger event to this batch.
	Append(trigger TriggerEvent)
}

type TriggerEvent interface {
	// Source identifies the trigger mechanism that generated this event.
	// Examples: "eventbridge", "s3-polling", "webhook", "generate"
	Source() string

	// Reference provides the data location or identifier for retrieval.
	// Examples: S3 object key, database record ID, API endpoint URL
	Reference() string

	// Metadata contains trigger-specific context and additional parameters.
	// This can include filtering criteria, authentication tokens, or processing hints.
	Metadata() map[string]any

	// Timestamp returns when the trigger was generated (Unix timestamp).
	// Used for ordering, deduplication, and expiration logic.
	Timestamp() int64
}

type TriggerInput interface {
	Component

	// ReadTriggers returns a batch of trigger events referencing available data.
	// These are lightweight references, not the actual data.
	ReadTriggers(ctx ComponentContext) (TriggerBatch, ProcessedCallback, error)
}