snapshot

type HandoffToken []byte

type Source[T any] interface {
	// CaptureHandoff captures the live-source resume position before scanning begins.
	// Called once at bootstrap start.
	CaptureHandoff(ctx context.Context) (HandoffToken, error)

	// Scan emits records via out until the snapshot is exhausted. Implementations should
	// honor ctx cancellation and yield records in stable, resumable chunks. Each record
	// must carry an EventID derived from the document's primary key so re-runs are
	// idempotent under at-least-once dedup.
	Scan(ctx context.Context, out chan<- source.Record[T]) error

	// Resume continues a previously-interrupted scan from the persisted progress marker.
	// Implementations that don't support resumption should restart from the beginning;
	// at-least-once dedup handles the duplicate emissions.
	Resume(ctx context.Context, marker []byte, out chan<- source.Record[T]) error

	// Name returns a stable identifier for logging and metrics.
	Name() string

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