source

type Record[T any] struct {
	// EventID is a stable identifier used for at-least-once dedup. Sources should derive
	// this from the underlying message (Kinesis sequence number, Kafka topic+partition+
	// offset) so duplicates are detectable.
	EventID string

	// EventTime is the time the upstream system attaches to this record. Used by windowed
	// aggregations for bucket assignment. Falls back to processing-time when missing.
	EventTime time.Time

	// PartitionKey, when nonempty, is the upstream partitioning key (Kinesis partition
	// key, Kafka message key). Useful for diagnostics and for sources that want to
	// surface partition affinity to the runtime.
	PartitionKey string

	// Value is the decoded payload.
	Value T

	// Ack must be called once the record has been fully processed (state-update committed,
	// dedup entry written). Sources use Ack to advance their checkpoint position.
	Ack func() error
}

type Source[T any] interface {
	// Read yields records to the consumer. The consumer must call Ack on each record after
	// committing its effects. Errors are returned to the caller; a Source may also surface
	// retriable errors as a sentinel and continue.
	Read(ctx context.Context, out chan<- Record[T]) error

	// Name returns a stable identifier for logging and metrics (e.g. "kinesis:events-stream").
	Name() string

	// Close releases any underlying resources.
	Close() error
}