userstate

type Key struct {
	User     string
	Source   string
	EntityID string
	Variant  string
}

type Snooze struct {
	Key   Key
	Until time.Time
}

type Store interface {
	// SnoozedUntil reports the deadline for key, and whether a live snooze
	// exists at all. An expired snooze reports ok=false: expiry is a read-time
	// judgement against `now`, so no backend depends on a sweeper having run.
	SnoozedUntil(ctx context.Context, key Key, now time.Time) (until time.Time, ok bool, err error)

	// SetSnooze records a snooze until `until`. A second call for the same key
	// REPLACES the first rather than stacking: "not now, try tomorrow" after
	// "not for an hour" should mean tomorrow, not an hour plus a day.
	SetSnooze(ctx context.Context, key Key, until time.Time) error

	// Muted reports whether the user has muted this source entirely.
	Muted(ctx context.Context, user, source string) (bool, error)

	// SetMuted mutes or unmutes a source for a user. Muting is per-SOURCE,
	// never per-entity: a per-entity mute is invisible state that nobody can
	// find later, whereas the handful of configured sources make "what have I
	// turned off?" a short, reversible list.
	SetMuted(ctx context.Context, user, source string, muted bool) error

	// MutedSources lists a user's muted source ids, sorted. Backs the
	// settings screen that makes muting discoverable — the property that
	// justifies choosing per-source mute over per-entity in the first place.
	MutedSources(ctx context.Context, user string) ([]string, error)

	// LastShown reports when this suggestion was last surfaced, and whether
	// it ever was. Drives cooldown.
	LastShown(ctx context.Context, key Key) (at time.Time, ok bool, err error)

	// MarkShown records that the suggestion was surfaced at `at`.
	MarkShown(ctx context.Context, key Key, at time.Time) error

	// Prune drops state that can no longer affect a decision: snoozes whose
	// deadline has passed, and last-shown records older than `keepShown`.
	// Returns how many records were removed.
	//
	// Purely a housekeeping optimisation — reads already ignore expired
	// snoozes, so a backend that never prunes stays CORRECT while growing
	// unboundedly. That split is deliberate: correctness must not depend on
	// a sweeper the operator might disable.
	Prune(ctx context.Context, now time.Time, keepShown time.Duration) (removed int, err error)

	// Close releases resources. Subsequent calls return ErrClosed.
	Close() error
}