shared

type ActorContext struct {
	Kind ActorKind
	// TenantID is empty exactly when the actor is anonymous.
	TenantID shared.ID
	// TenantSlug is the workspace's public name, riding with the credential so the
	// middleware can compare §3's weaker resolution sources - the subdomain and the header -
	// against what the credential says without a second lookup.
	TenantSlug string
	// RateLimitPerMinute is the workspace's own request-rate ceiling, riding with the
	// credential for the limiter's sake. 0 means none is configured - the installation's
	// default applies, at the level that already enforces it.
	RateLimitPerMinute int64
	// AccountID is the acting account. Empty for the system itself.
	AccountID shared.ID
	// AccountName is the label the audit trail records next to the identifier. It travels with
	// the actor because the trail denormalises it: an entry that only points at a foreign key
	// becomes unreadable once the account is deleted (audit.md §2, test AT-7). It is personal
	// data and goes nowhere else - not into a log, a metric, a span, or an event.
	AccountName string
	// TokenID identifies the credential used, for the audit trail and for revocation. Empty on an
	// interactive session.
	TokenID shared.ID
	// Scopes are the token's bounds. They are a second, independent limit on top of the role: a
	// token can never do more than its scopes allow, whatever role its owner holds (ADR-0005).
	Scopes []string
	// Withheld are the scopes the credential names that the operator register took away
	// (ADR-0070 §1). They are not held - `HasScope` never sees them - and they exist so that a
	// refusal can say the register is the reason (UC-INS-03 check 5).
	Withheld WithheldScopes
	// RunsForRule is the automation rule this act runs for, set by the rule engine and nowhere else;
	// empty for every act a caller makes itself. The engine acts as the rule's service account, which
	// a caller holding that account's token would be too - only this tells an act whose answer
	// nobody reads from one whose caller reads it.
	RunsForRule shared.ID
	// Present is true for a request a person is waiting on now: a call through the REST API - the
	// web app's door and hubctl's - set by that adapter and nowhere else. It decides one thing:
	// whether the workspace owner's running emergency access to a private hub counts (ADR-0073 §4,
	// identity.md §22). The access is for the person looking, for one hour, and must leave nothing
	// behind it: so it never counts for a device's copy (the sync service takes the mark off,
	// ForACopy), a calendar subscription, a job or a rule run later (built without it), or an AI
	// agent acting with the person's credential. False is the safe value: an actor somebody forgot
	// to mark sees nothing of a private hub.
	Present bool
	// APIClient is the OAuth client the credential was issued to, empty for everything
	// that is not a grant session. It is what the audit trail records as the acting app.
	APIClient shared.ID
	// Locale is BCP 47, resolved request → account → tenant → installation (i18n-l10n.md §2).
	Locale string
	// TimeZone is an IANA name. Every relative date in a query and every reminder is computed in
	// it, so it travels with the actor rather than being looked up per use case.
	TimeZone string
	// WeekStart is `MONDAY`, `SUNDAY` or `SATURDAY`: the account's own preference where it set
	// one, otherwise the day the week starts where its locale is spoken (i18n-l10n.md §4).
	// The week anchors of a query - `@start_of_week`, `@end_of_week` - are computed from it, so
	// it travels here beside the zone rather than being looked up per use case. Empty is Monday.
	WeekStart string
}

type ActorKind = shared.ActorKind

type Push struct {
	ID         shared.ID
	OccurredAt time.Time
}

type WithheldScopes struct {
	Scopes []string
	// Unreadable is true when the register could not be read, so the scope was withheld closed
	// rather than because the holder is outside it.
	Unreadable bool
}