querypage

type AnchorOutcome struct {
	// Found: the anchor row exists AND matches the query's filters/search;
	// Rank is then its 0-based position among matching rows in display order.
	Found bool
	// Filtered: the anchor row exists in the store but the query's
	// filters/search exclude it. Mutually exclusive with Found.
	Filtered bool
	// Rank is valid only when Found; -1 otherwise.
	Rank int
}

type Cursor struct {
	ClusterID string    `json:"c"`
	Signature string    `json:"q"` // hash of the query shape (filters, scope, …)
	Sort      string    `json:"s"`
	Direction Direction `json:"d"`
	Limit     int       `json:"l"`

	// Position holds the single comparable sort value of the boundary row this
	// cursor pins (the store's one-comparable-per-row invariant). UID is the final,
	// always-unique tiebreak. Together they are the keyset seek position. Empty
	// Position + empty UID = first page.
	Position string `json:"p,omitempty"`
	UID      string `json:"u,omitempty"`

	// Backward marks a prev-page cursor: the engine walks the sort order DOWNWARD from
	// Position (collecting the rows immediately before it) instead of upward. It is a
	// navigation property, not part of the query shape, so Validate ignores it.
	Backward bool `json:"b,omitempty"`
}

type Direction string

type Page[R any] struct {
	Rows       []R
	NextCursor string
	PrevCursor string
	Facets     map[string]map[string]int
	Total      int

	// CursorInvalid reports that the request's cursor was rejected — undecodable,
	// pinned to a different query shape, or an un-navigable backward dead end (a
	// valid prev-page cursor whose predecessors were all deleted). The served page
	// is a first-page restart for the first two, and the empty dead-end page for
	// the last; callers forward the flag so the client resets its pagination
	// state. Owning this in the engine keeps every executor's degrade behavior
	// identical — callers need no cursor pre-validation of their own.
	CursorInvalid bool

	// PageStartRank is the 0-based rank of the served page's first row among the
	// query's matching rows — exact position honesty for the footer. Counted
	// serves (QueryAround/QueryAt) fill it; the cursor-based Query path returns
	// -1 (not computed — the O(rank) walk it would cost is gated behind the P9
	// benchmark). The wire layer maps ≥0 to a pointer so rank 0 survives
	// omitempty.
	PageStartRank int

	// SelfCursor addresses THIS page: a later plain Query with it reproduces the
	// window (the page-stability primitive live refetches use after an anchored
	// or offset landing — cursor-addressed pages already hold their own request
	// token). Counted serves mint it from the entry preceding the window; "" for
	// a first-page window, whose address is the empty token.
	SelfCursor string
}

type Query struct {
	ClusterID string
	Signature string // identifies the query shape (filters+scope); pins the cursor
	Sort      string // a key in Schema.SortKeys
	Direction Direction
	Limit     int
	Search    string              // case-insensitive substring filter over SearchText
	Filters   map[string][]string // facet filters: facet name -> allowed values (set membership; OR within, AND across facets)
	MatchNone bool                // explicit empty multiselect: no row can match
	Cursor    string              // opaque continueToken from a previous Page
}

type Schema[R any] struct {
	UID              func(R) string
	SortKeys         map[string]func(R) string
	Facets           map[string]func(R) string
	MultiFacets      map[string]func(R) []string
	FacetNormalizers map[string]func(string) string
	SearchText       func(R) string
}

type Store[R any] struct {
	// contains filtered or unexported fields
}