package ports

import (
	"context"
	"time"
)

// StreamLagProbe reports how far the persisted consumer offset trails the
// stream tail. It feeds the three `lobby.*.oldest_unprocessed_age_ms`
// observable gauges defined in `lobby/README.md` §Observability.
type StreamLagProbe interface {
	// OldestUnprocessedAge returns the age of the first stream entry that
	// follows savedOffset on stream. The boolean return reports whether
	// the implementation could compute an age at all: it is false when
	// the stream is empty, when no entries follow savedOffset, or when
	// the stream key is absent. An empty savedOffset is interpreted as
	// "no progress yet"; the implementation falls back to the stream
	// head in that case.
	OldestUnprocessedAge(ctx context.Context, stream, savedOffset string) (time.Duration, bool, error)
}