httpapi

type Page[T any] struct {
	// Items are the rows this response could carry. Never nil: an empty page
	// serializes as `[]` rather than `null`, because every client iterates it.
	Items []T `json:"items"`
	// Total is how many there are. Read TotalExact before believing it.
	Total int `json:"total"`
	// TotalExact says whether Total is the population or merely what this request saw.
	// It is not a hedge. Some totals are a maintained counter — the instance listing's,
	// which is a point read (ADR-0080/0083) — or a walk the request was making anyway,
	// as the grant audit already holds every event it filters. Others would cost a walk
	// of seventy times what serving the page costs: measured at 108 ms against 1.6 ms
	// for the open-task listing at 6 000 instances. Paying that on every inbox load, for
	// a number most callers do not read, is the wrong trade; claiming the number anyway
	// would be the original defect wearing a new field name.
	//
	// False therefore means: Total is a floor, this endpoint cannot cheaply do better,
	// and the endpoint that *can* is named in this listing's API description.
	TotalExact bool `json:"totalExact"`
	// Truncated says the cap bit: there are rows this response left out. It is about
	// the rows and says nothing about Total, which may be exact on a truncated page —
	// that is the normal case for instances, where the counter knows the population
	// and the page holds a thousand of it.
	Truncated bool `json:"truncated"`
	// NextCursor continues the listing where this page stopped, for the listings that
	// page. Empty when there is no more, and on the listings that do not page at all.
	NextCursor string `json:"nextCursor,omitempty"`
}

type Principal struct {
	UserID   string
	Username string
	Roles    []string
	// GroupIDs are the ids of the groups the user belongs to, snapshotted at login
	// like Roles, so a scope's group grant resolves as a pure check against this
	// slice without a store read (ADR-0180).
	//
	// The snapshot is kept current rather than left to expire: adding or removing a
	// member pushes the change into that account's live sessions (ADR-0185), so it
	// applies from their next request. This comment said "takes effect on the user's
	// next login" long after that stopped being true, which is the worse kind of
	// stale documentation — it describes a delay an administrator would then wait
	// for, and tell a colleague to sign out and in again for no reason.
	GroupIDs []string
	// Scope confines a principal authenticated by a machine credential to a named
	// set of operations, whatever its roles would otherwise permit. Empty for a
	// person: a session is not scoped, it is who you are. The boundary enforces it
	// in one place; handlers never read it.
	Scope string
	// Reach confines a principal authenticated by a machine credential to named
	// subjects — today the projects it may see (ADR-0410). Scope says *which
	// routes*; this says *which subjects*, which no scope could express: a machine
	// principal has no account to own or be a member of anything, so it would
	// otherwise hold whatever role the sharing scopes give a caller with none.
	//
	// It only ever takes away. Empty means the credential states no reach and
	// nothing is narrowed, which is what keeps every credential already in the field
	// working; a credential that must state one is refused at minting instead.
	Reach []string
	// Session is true when the principal is a person signed in with their own
	// session, not a bearer credential: an API token, the internal token, or an
	// application the person granted access to (an OAuth grant resolves to their id,
	// and to their roles). A few acts are the person's alone — answering an approval,
	// consenting to a Worker acting as them — and are refused to anything that is not
	// their session (ADR-0475 §10).
	Session bool
}