authority

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package authority defines public request- and attempt-level authority provider contracts, decisions, safe evidence, and concurrency lease DTOs.

Import DAG: authority → economics → metering; authority also uses policydecision and controlplane for EvidenceSink (no cycles). Implementations and stores live outside this package (Phase 6+ / 8).

QuotaPolicy is an optional nonfinancial authority contract for persisted provider account-window gauges. It retains the provider account/pool/window reset binding, freshness and evidence status, but never represents money, provider request debits, payable postings or customer credit.

Boundary rules:

  • Must not import internal/*, database/sql, net/http, or provider SDKs.
  • Must not reference Executor or runtimebundle types.

Observers vs authorities (requirement 12.7): fail-open usage/traffic observers remain supported via ProviderKindObserver descriptors, but must not implement RequestProvider or AttemptProvider for strict admission. StrengthRequired is reserved for ProviderKindAuthority.

Compatibility (requirement 12.8): follows metering.CompatibilityPolicy — Validate rejects unknown enums for local enforcement; additive wire decode preserves unrecognized values via IsKnown/UnknownEnum.

Index

Constants

View Source 
const (
	LifecycleLogicalRequest   = metering.LifecycleLogicalRequest
	LifecycleBackendAttempt   = metering.LifecycleBackendAttempt
	LifecycleAuxiliaryRequest = metering.LifecycleAuxiliaryRequest
)
View Source 
const (
	// QuotaPolicyMaxFreshness bounds an operator policy so a configuration
	// cannot accidentally turn a stale telemetry snapshot into an evergreen
	// admission authority.
	QuotaPolicyMaxFreshness = 365 * 24 * time.Hour
	MaxQuotaFields          = 128
	MaxQuotaThresholds      = 128
	MaxQuotaObservations    = 1024
)
View Source 
const (
	QuotaDecisionAllow         QuotaDecisionKind = "allow"
	QuotaDecisionDeny          QuotaDecisionKind = "deny"
	QuotaDecisionIndeterminate QuotaDecisionKind = "indeterminate"
	QuotaAllow                                   = QuotaDecisionAllow
	QuotaDeny                                    = QuotaDecisionDeny
	QuotaIndeterminate                           = QuotaDecisionIndeterminate
)
View Source 
const (
	QuotaFailureDeny                QuotaFailureAction = "deny"
	QuotaFailureIndeterminate       QuotaFailureAction = "indeterminate"
	QuotaFailureActionDeny                             = QuotaFailureDeny
	QuotaFailureActionIndeterminate                    = QuotaFailureIndeterminate
)
View Source 
const (
	QuotaThresholdMaxUtilization     QuotaThresholdKind = "max_utilization"
	QuotaThresholdMinHeadroom        QuotaThresholdKind = "min_headroom"
	QuotaThresholdKindMaxUtilization                    = QuotaThresholdMaxUtilization
	QuotaThresholdKindMinHeadroom                       = QuotaThresholdMinHeadroom
)
View Source 
const (
	QuotaValuePercent      QuotaValueKind = "percent"
	QuotaValueAbsolute     QuotaValueKind = "absolute"
	QuotaValueKindPercent                 = QuotaValuePercent
	QuotaValueKindAbsolute                = QuotaValueAbsolute
)
View Source 
const QuotaPolicyMethodV1 = "provider_quota.v1"

QuotaPolicyMethodV1 identifies the canonical provider-quota policy method. The method is nonfinancial: it describes admission against an allowance gauge and cannot create a charge, payable posting or customer debit.

Variables

View Source 
var (
	ErrInvalidQuotaPolicy       = errors.New("authority: invalid quota policy")
	ErrInvalidQuotaEvaluation   = errors.New("authority: invalid quota evaluation")
	ErrInvalidQuotaEvidence     = errors.New("authority: invalid quota evidence")
	ErrQuotaEvidenceConflict    = errors.New("authority: quota evidence identity conflict")
	ErrQuotaEvidenceUnsupported = errors.New("authority: unsupported quota evidence")
)

Functions

This section is empty.

Types

type AttemptAdmission 

type AttemptAdmission struct {
	RequestID      string                        `json:"request_id"`
	AttemptID      string                        `json:"attempt_id"`
	BLegID         string                        `json:"b_leg_id"`
	ALegID         string                        `json:"a_leg_id,omitempty"`
	BackendID      string                        `json:"backend_id,omitempty"`
	Model          string                        `json:"model,omitempty"`
	Perspective    metering.EconomicPerspective  `json:"perspective"`
	Lifecycle      metering.LifecycleScope       `json:"lifecycle"`
	Scope          scope.PrincipalScopeView      `json:"scope"`
	Exposure       economics.ExposureBasis       `json:"exposure"`
	BoundVersions  []economics.PolicySnapshotRef `json:"bound_versions,omitempty"`
	RatingVersions []economics.RatingSnapshotRef `json:"rating_versions,omitempty"`
	IdempotencyKey string                        `json:"idempotency_key,omitempty"`
}

AttemptAdmission is backend-attempt admit input and requires attempt/B-leg identity (requirements 9.2, 9.3).

func (AttemptAdmission) Validate 

func (a AttemptAdmission) Validate() error

Validate requires request, attempt, and B-leg identity.

type AttemptClampPreviewer 

type AttemptClampPreviewer interface {
	PreviewAttempt(ctx context.Context, in AttemptAdmission) (Decision, error)
}

AttemptClampPreviewer optionally previews non-widening clamps without holds (design Clamp Preview; requirement 2.1). PreviewAttempt must not reserve or record durable admission evidence.

type AttemptPriority 

type AttemptPriority string

AttemptPriority is the deterministic evaluation class for attempt authorities (requirement 3.4; design Descriptor-Bound Registrations). 

const (
	AttemptPriorityHardSpend AttemptPriority = "hard_spend"
	AttemptPriorityQuotaRate AttemptPriority = "quota_rate"
	AttemptPriorityAdvisory  AttemptPriority = "advisory"
)

func (AttemptPriority) IsKnown 

func (p AttemptPriority) IsKnown() bool

IsKnown reports whether p is a documented attempt priority.

func (AttemptPriority) Validate 

func (p AttemptPriority) Validate() error

Validate returns an error when p is not a known attempt priority.

type AttemptProvider 

type AttemptProvider interface {
	AdmitAttempt(ctx context.Context, in AttemptAdmission) (Decision, error)
	SettleAttempt(ctx context.Context, in AttemptSettlement) (Settlement, error)
	ReleaseAttempt(ctx context.Context, in AttemptRelease) error
}

AttemptProvider evaluates backend-attempt operator authority.

type AttemptRegistration 

type AttemptRegistration struct {
	Descriptor ProviderDescriptor
	Priority   AttemptPriority
	Provider   AttemptProvider
}

AttemptRegistration binds a provider descriptor, priority, and attempt authority instance into one production registration (design D4).

func (AttemptRegistration) Validate 

func (r AttemptRegistration) Validate() error

Validate checks descriptor posture, priority, and provider instance binding.

type AttemptRelease 

type AttemptRelease struct {
	RequestID          string   `json:"request_id"`
	AttemptID          string   `json:"attempt_id"`
	BLegID             string   `json:"b_leg_id"`
	Handles            []string `json:"handles,omitempty"`
	CompensationHandle string   `json:"compensation_handle,omitempty"`
	Reason             string   `json:"reason,omitempty"`
}

AttemptRelease compensates or releases prior attempt reservations.

type AttemptSettlement 

type AttemptSettlement struct {
	RequestID        string                        `json:"request_id"`
	AttemptID        string                        `json:"attempt_id"`
	BLegID           string                        `json:"b_leg_id"`
	Handles          []string                      `json:"handles,omitempty"`
	Reservations     []Reservation                 `json:"reservations,omitempty"`
	Facts            []metering.Fact               `json:"facts,omitempty"`
	Outcome          metering.AttemptOutcome       `json:"outcome,omitempty"`
	Surfaced         metering.SurfacedState        `json:"surfaced,omitempty"`
	Kind             string                        `json:"kind,omitempty"`
	ALegID           string                        `json:"a_leg_id,omitempty"`
	BackendID        string                        `json:"backend_id,omitempty"`
	Model            string                        `json:"model,omitempty"`
	Scope            scope.PrincipalScopeView      `json:"scope,omitzero"`
	BackendAttempted bool                          `json:"backend_attempted,omitempty"`
	OutputCommitted  bool                          `json:"output_committed,omitempty"`
	ClientCanceled   bool                          `json:"client_canceled,omitempty"`
	BoundVersions    []economics.PolicySnapshotRef `json:"bound_versions,omitempty"`
	IdempotencyKey   string                        `json:"idempotency_key,omitempty"`
}

AttemptSettlement settles operator/attempt reservations for one B-leg.

type Clamp 

type Clamp struct {
	Kind   ClampKind       `json:"kind"`
	Value  int64           `json:"value,omitempty"`
	Money  economics.Money `json:"money,omitzero"`
	RuleID string          `json:"rule_id,omitempty"`
}

Clamp is a non-widening constraint imposed by a provider.

type ClampKind 

type ClampKind string

ClampKind classifies an enforcement clamp applied at admit. 

const (
	ClampMaxOutputTokens ClampKind = "max_output_tokens"
	ClampMaxSpend        ClampKind = "max_spend"
	ClampOther           ClampKind = "other"
)

func (ClampKind) IsKnown 

func (k ClampKind) IsKnown() bool

IsKnown reports whether k is a documented clamp kind.

type ConcurrencyProvider 

type ConcurrencyProvider interface {
	AdmitLease(ctx context.Context, in LeaseAdmission) (LeaseDecision, error)
	RenewLease(ctx context.Context, in LeaseRenew) (LeaseDecision, error)
	ReleaseLease(ctx context.Context, in LeaseRelease) error
	QueryLeases(ctx context.Context, q LeaseQuery) (LeasePage, error)
}

ConcurrencyProvider is the Phase 8 seam for logical-request leases. This package defines the contract only; no store implementation lives here.

type ConcurrencyRegistration 

type ConcurrencyRegistration struct {
	Descriptor ProviderDescriptor
	Provider   ConcurrencyProvider
}

ConcurrencyRegistration binds a provider descriptor and concurrency provider instance into one production registration (design D4).

func (ConcurrencyRegistration) Validate 

func (r ConcurrencyRegistration) Validate() error

Validate checks descriptor posture and provider instance binding.

type Decision 

type Decision struct {
	Kind               DecisionKind                  `json:"kind"`
	ProviderID         string                        `json:"provider_id,omitempty"`
	Stage              Stage                         `json:"stage,omitempty"`
	Reservations       []Reservation                 `json:"reservations,omitempty"`
	Clamps             []Clamp                       `json:"clamps,omitempty"`
	CompensationHandle string                        `json:"compensation_handle,omitempty"`
	Readiness          Readiness                     `json:"readiness,omitempty"`
	BoundVersions      []economics.PolicySnapshotRef `json:"bound_versions,omitempty"`
	RatingVersions     []economics.RatingSnapshotRef `json:"rating_versions,omitempty"`
	Exposure           economics.ExposureBasis       `json:"exposure,omitzero"`
	Evidence           SafeEvidence                  `json:"evidence,omitzero"`
}

Decision is the admit result from a RequestProvider or AttemptProvider.

func (Decision) Validate 

func (d Decision) Validate() error

Validate checks Decision kind, reservations, clamps, and hold contradictions (requirements 4.1–4.4, 4.6).

func (Decision) ValidateFor 

func (d Decision) ValidateFor(reg ProviderDescriptor, stage Stage) error

ValidateFor checks Decision against the registration descriptor and stage (design External Result Validation; requirements 3.2, 4.1).

type DecisionKind 

type DecisionKind string

DecisionKind is the outcome of an admit call. 

const (
	DecisionAllow    DecisionKind = "allow"
	DecisionDeny     DecisionKind = "deny"
	DecisionAdvisory DecisionKind = "advisory"
)

func (DecisionKind) IsKnown 

func (k DecisionKind) IsKnown() bool

IsKnown reports whether k is a documented decision kind.

type Describer 

type Describer interface {
	Describe() ProviderDescriptor
}

Describer exposes provider posture independently of Admit/Settle/Release so the design provider method sets stay focused while still satisfying 15.1.

type EvidenceSink 

type EvidenceSink interface {
	RecordPolicyDecision(ctx context.Context, record policydecision.Record) error
	RecordAccountingAuthority(ctx context.Context, event controlplane.Event) error
}

EvidenceSink projects authority outcomes into policy-decision and control-plane evidence without exposing storage or HTTP concerns (requirement 12.1). Closed enterprise modules inject implementations through lipruntime.Options.

type FailureBehavior 

type FailureBehavior string

FailureBehavior classifies fail-open vs fail-closed infrastructure posture for a provider at a lifecycle stage (requirement 15.1). Distinct from deterministic capacity denials (requirement 15.4). Fail-open observers use ProviderKindObserver and must not be represented as strict authorities (requirement 12.7). 

const (
	FailureFailClosed FailureBehavior = "fail_closed"
	FailureFailOpen   FailureBehavior = "fail_open"
)

func (FailureBehavior) IsKnown 

func (b FailureBehavior) IsKnown() bool

IsKnown reports whether b is a documented failure behavior.

func (FailureBehavior) Validate 

func (b FailureBehavior) Validate() error

Validate returns an error when b is not a known failure behavior.

type LeaseAdmission 

type LeaseAdmission struct {
	RequestID      string                      `json:"request_id"`
	Scope          scope.PrincipalScopeView    `json:"scope"`
	RuleID         string                      `json:"rule_id,omitempty"`
	Namespace      string                      `json:"namespace,omitempty"`
	TTL            time.Duration               `json:"ttl,omitempty"`
	BoundVersion   economics.PolicySnapshotRef `json:"bound_version"`
	IdempotencyKey string                      `json:"idempotency_key,omitempty"`
	// Lifecycle identifies auxiliary vs top-level logical request (requirement 10.10).
	Lifecycle LifecycleScope `json:"lifecycle,omitempty"`
	// ParentLeaseID is the parent occupancy when Lifecycle is auxiliary and policy inherits.
	ParentLeaseID string `json:"parent_lease_id,omitempty"`
	// AuxPolicy controls whether auxiliary calls inherit the parent lease ("", "inherit", "acquire_own").
	AuxPolicy string `json:"aux_policy,omitempty"`
}

LeaseAdmission requests a logical-request concurrency lease (Phase 8 implements).

type LeaseDecision 

type LeaseDecision struct {
	Kind           LeaseDecisionKind           `json:"kind"`
	LeaseID        string                      `json:"lease_id,omitempty"`
	Generation     int64                       `json:"generation,omitempty"`
	ExpiresAt      time.Time                   `json:"expires_at,omitzero"`
	RemainingSlots int                         `json:"remaining_slots,omitempty"`
	Readiness      Readiness                   `json:"readiness,omitempty"`
	BoundVersion   economics.PolicySnapshotRef `json:"bound_version,omitzero"`
	Evidence       SafeEvidence                `json:"evidence,omitzero"`
	// RenewBefore is the configured offset before ExpiresAt when heartbeat should renew.
	RenewBefore time.Duration `json:"renew_before,omitempty"`
	// TTL is the lease lifetime used for renew extensions.
	TTL time.Duration `json:"ttl,omitempty"`
	// FailureBehavior is the post-admission renew-failure posture (fail_closed|fail_open).
	FailureBehavior FailureBehavior `json:"failure_behavior,omitempty"`
	// Leases lists all rule occupancies from multi-rule Admit (omitempty for single-lease).
	Leases []LeaseOccupancy `json:"leases,omitempty"`
	// SetID is the atomic multi-rule lease-set identity when Admit used AcquireSet.
	SetID string `json:"set_id,omitempty"`
}

LeaseDecision is the admit result for a concurrency lease.

LeaseID/Generation/... remain the primary occupancy (last successfully acquired for multi-rule allow). Leases enumerates every occupancy when multiple rules matched; empty means callers should fall back to LeaseID.

func (LeaseDecision) Validate 

func (d LeaseDecision) Validate() error

Validate checks LeaseDecision kind and occupancy contradictions (requirements 4.1, 10.2).

func (LeaseDecision) ValidateFor 

func (d LeaseDecision) ValidateFor(in LeaseAdmission, reg ProviderDescriptor) error

ValidateFor checks LeaseDecision against admission input and registration (design External Result Validation; requirements 4.1, 10.2). Expiry relative to wall/evaluation clock is enforced by the coordinator Now seam, not here — public ValidateFor stays deterministic.

func (LeaseDecision) ValidateRenewalFor 

func (d LeaseDecision) ValidateRenewalFor(in LeaseRenew, reg ProviderDescriptor) error

ValidateRenewalFor checks LeaseDecision against a renew request and registration (design External Result Validation; requirements 4.1, 10.2). Single-lease renew requires occupancy IDs to match LeaseID. When SetID is set, the complete set shape is validated and member lease IDs may differ. Generation may equal ExpectedGeneration for TTL-only expiry extension. Expiry relative to wall clock is enforced by the coordinator Now seam, not here.

type LeaseDecisionKind 

type LeaseDecisionKind string

LeaseDecisionKind is the outcome of a concurrency lease admit. 

const (
	LeaseAllow    LeaseDecisionKind = "allow"
	LeaseDeny     LeaseDecisionKind = "deny"
	LeaseAdvisory LeaseDecisionKind = "advisory"
)

func (LeaseDecisionKind) IsKnown 

func (k LeaseDecisionKind) IsKnown() bool

IsKnown reports whether k is a documented lease decision kind.

type LeaseOccupancy 

type LeaseOccupancy struct {
	LeaseID         string          `json:"lease_id"`
	Generation      int64           `json:"generation,omitempty"`
	RuleID          string          `json:"rule_id,omitempty"`
	ExpiresAt       time.Time       `json:"expires_at,omitzero"`
	RenewBefore     time.Duration   `json:"renew_before,omitempty"`
	TTL             time.Duration   `json:"ttl,omitempty"`
	FailureBehavior FailureBehavior `json:"failure_behavior,omitempty"`
}

LeaseOccupancy is one rule-scoped lease held for a logical request after Admit.

type LeasePage 

type LeasePage struct {
	Leases     []LeaseRecord `json:"leases"`
	NextCursor string        `json:"next_cursor,omitempty"`
}

LeasePage is a bounded page of lease records.

type LeaseQuery 

type LeaseQuery struct {
	RequestID string                   `json:"request_id,omitempty"`
	LeaseID   string                   `json:"lease_id,omitempty"`
	RuleID    string                   `json:"rule_id,omitempty"`
	Scope     scope.PrincipalScopeView `json:"scope,omitzero"`
	State     LeaseState               `json:"state,omitempty"`
	Limit     int                      `json:"limit,omitempty"`
	Cursor    string                   `json:"cursor,omitempty"`
}

LeaseQuery is a bounded filter for active/history lease queries.

type LeaseRecord 

type LeaseRecord struct {
	LeaseID      string                      `json:"lease_id"`
	RequestID    string                      `json:"request_id,omitempty"`
	State        LeaseState                  `json:"state"`
	Generation   int64                       `json:"generation,omitempty"`
	ExpiresAt    time.Time                   `json:"expires_at,omitzero"`
	ReleasedAt   time.Time                   `json:"released_at,omitzero"`
	RuleID       string                      `json:"rule_id,omitempty"`
	Version      economics.PolicySnapshotRef `json:"version,omitzero"`
	DimensionKey string                      `json:"dimension_key,omitempty"` // safe scope correlation
}

LeaseRecord is one lease row returned by query (no store types).

type LeaseRelease 

type LeaseRelease struct {
	LeaseID   string `json:"lease_id"`
	RequestID string `json:"request_id,omitempty"`
	Reason    string `json:"reason,omitempty"`
	// SetID, when set, releases the complete lease set atomically (Phase 6).
	SetID string `json:"set_id,omitempty"`
}

LeaseRelease releases a previously acquired lease or lease set.

type LeaseRenew 

type LeaseRenew struct {
	LeaseID            string        `json:"lease_id"`
	RequestID          string        `json:"request_id,omitempty"`
	ExpectedGeneration int64         `json:"expected_generation"`
	TTL                time.Duration `json:"ttl,omitempty"`
	// RuleID, when set, constrains occupancy rule identity on the renewal result.
	RuleID string `json:"rule_id,omitempty"`
	// SetID, when set, renews the complete lease set atomically (Phase 6).
	SetID string `json:"set_id,omitempty"`
	// RenewBefore is required for set renew timing validation when SetID is set.
	RenewBefore time.Duration `json:"renew_before,omitempty"`
}

LeaseRenew extends an active lease before expiry using generation CAS. ExpectedGeneration is the caller's current generation; providers must not resurrect released/expired capacity on mismatch. A successful renew may return the same generation when only TTL/expiry is extended (TTL-only renew).

type LeaseState 

type LeaseState string

LeaseState is the queryable state of a concurrency lease. 

const (
	LeaseStateActive   LeaseState = "active"
	LeaseStateExpiring LeaseState = "expiring"
	LeaseStateExpired  LeaseState = "expired"
	LeaseStateReleased LeaseState = "released"
)

type LifecycleScope 

type LifecycleScope = metering.LifecycleScope

Lifecycle aliases metering scopes so authority callers can stay in one import when only documenting stage placement.

type ProviderDescriptor 

type ProviderDescriptor struct {
	ID       string         `json:"id"`
	Kind     ProviderKind   `json:"kind,omitempty"`
	Postures []StagePosture `json:"postures"`
}

ProviderDescriptor is the public registration/describe surface for request, attempt, concurrency, or observer providers (requirements 12.1, 12.7, 15.1). Coordinators consume descriptors; they are not store or executor types.

Kind is optional for additive compatibility (requirement 12.8): omitted Kind defaults to ProviderKindAuthority via EffectiveKind.

func (ProviderDescriptor) EffectiveKind 

func (d ProviderDescriptor) EffectiveKind() ProviderKind

EffectiveKind returns Kind, defaulting omitted values to authority.

func (ProviderDescriptor) Validate 

func (d ProviderDescriptor) Validate() error

Validate requires a non-empty trimmed ID and validates kind and each posture row. Duplicate stage postures are rejected (requirement 3.2). Observers cannot declare StrengthRequired (requirement 12.7).

type ProviderKind 

type ProviderKind string

ProviderKind distinguishes enforceable authority providers from fail-open usage/traffic observers (requirement 12.7). Observers must not be wired as RequestProvider or AttemptProvider for strict admission. 

const (
	// ProviderKindAuthority may participate in Admit/Settle/Release. Strength
	// and FailureBehavior on StagePosture further classify required vs advisory
	// and fail-open vs fail-closed infrastructure posture (requirement 15.1).
	ProviderKindAuthority ProviderKind = "authority"
	// ProviderKindObserver is diagnostic/observation only. It must never be
	// treated as a strict admission authority, even when FailureBehavior is
	// fail_open.
	ProviderKindObserver ProviderKind = "observer"
)

func (ProviderKind) IsKnown 

func (k ProviderKind) IsKnown() bool

IsKnown reports whether k is a documented provider kind.

func (ProviderKind) Validate 

func (k ProviderKind) Validate() error

Validate returns an error when k is not a known provider kind.

type QuotaBinding 

type QuotaBinding struct {
	StoreID            string    `json:"store_id,omitempty"`
	TenantID           string    `json:"tenant_id,omitempty"`
	ProviderAccountKey string    `json:"provider_account_key"`
	PoolID             string    `json:"pool_id"`
	WindowID           string    `json:"window_id"`
	ResetAt            time.Time `json:"reset_at"`
}

QuotaBinding is the complete reset-scoped provider allowance identity. An empty StoreID means the policy is portable across one store, but evaluation still rejects an ambiguous multi-store input rather than choosing one.

func (QuotaBinding) Normalize 

func (b QuotaBinding) Normalize() (QuotaBinding, error)

Normalize returns a UTC reset-scoped binding copy.

func (QuotaBinding) Validate 

func (b QuotaBinding) Validate() error

Validate checks the complete provider account/pool/window/reset identity.

type QuotaDecision 

type QuotaDecision struct {
	Kind              QuotaDecisionKind         `json:"kind"`
	Reason            QuotaReason               `json:"reason"`
	EvidenceStatus    QuotaEvidenceStatus       `json:"evidence_status"`
	Policy            QuotaPolicyRef            `json:"policy"`
	EvidenceRefs      []metering.ObservationRef `json:"evidence_refs,omitempty"`
	Measures          []metering.Measure        `json:"measures,omitempty"`
	HeadObservationID string                    `json:"head_observation_id,omitempty"`
	HeadObservedAt    time.Time                 `json:"head_observed_at,omitzero"`
	HeadReceivedAt    time.Time                 `json:"head_received_at,omitzero"`
	ResetAt           time.Time                 `json:"reset_at"`
	ReplayCount       int                       `json:"replay_count,omitempty"`
}

QuotaDecision is a nonfinancial quota result. Measures and evidence refs are retained so an adapter can explain the decision; neither is a payable amount, customer balance, provider debit or ledger command.

func (QuotaDecision) Validate 

func (d QuotaDecision) Validate() error

Validate checks the bounded, nonfinancial decision envelope. It is useful at the C2 adapter boundary before mapping the result to generic authority.

type QuotaDecisionKind 

type QuotaDecisionKind string

QuotaDecisionKind is deliberately separate from the generic authority DecisionKind. A quota evaluator can be indeterminate when telemetry is missing or stale; the C2 adapter decides how that status participates in a request-level authority decision.

func (QuotaDecisionKind) IsKnown 

func (k QuotaDecisionKind) IsKnown() bool

type QuotaEvaluationInput 

type QuotaEvaluationInput struct {
	At                   time.Time
	Observations         []metering.Observation
	TelemetryUnavailable bool
}

QuotaEvaluationInput is the deterministic input to Evaluate. At must be supplied by the caller; the evaluator never reads a wall clock. Observed gauges are the only evidence accepted, not provider debit or money records.

type QuotaEvidenceStatus 

type QuotaEvidenceStatus string

QuotaEvidenceStatus records why an optional telemetry authority could not make a complete decision. Status is retained even when the configured failure action is deny. 

const (
	QuotaEvidenceComplete    QuotaEvidenceStatus = "complete"
	QuotaEvidenceMissing     QuotaEvidenceStatus = "missing"
	QuotaEvidenceStale       QuotaEvidenceStatus = "stale"
	QuotaEvidencePartial     QuotaEvidenceStatus = "partial"
	QuotaEvidenceUnavailable QuotaEvidenceStatus = "unavailable"
	QuotaEvidenceMismatch    QuotaEvidenceStatus = "mismatch"
	QuotaEvidenceFuture      QuotaEvidenceStatus = "future"
	QuotaEvidenceInvalid     QuotaEvidenceStatus = "invalid"
)

func (QuotaEvidenceStatus) IsKnown 

func (s QuotaEvidenceStatus) IsKnown() bool

type QuotaFailureAction 

type QuotaFailureAction string

QuotaFailureAction controls the result for a declared evidence failure. It is not a retry instruction and has no financial meaning.

func (QuotaFailureAction) IsKnown 

func (a QuotaFailureAction) IsKnown() bool

type QuotaFailurePolicy 

type QuotaFailurePolicy struct {
	Missing     QuotaFailureAction `json:"missing"`
	Stale       QuotaFailureAction `json:"stale"`
	Partial     QuotaFailureAction `json:"partial"`
	Unavailable QuotaFailureAction `json:"unavailable"`
	Mismatch    QuotaFailureAction `json:"mismatch"`
	Future      QuotaFailureAction `json:"future"`
}

QuotaFailurePolicy makes all non-complete telemetry cases explicit. Zero values normalize to deny, so an omitted failure action never silently allows a request.

func (QuotaFailurePolicy) Normalize 

func (p QuotaFailurePolicy) Normalize() (QuotaFailurePolicy, error)

Normalize returns the explicit failure posture, defaulting every omitted action to deny.

func (QuotaFailurePolicy) Validate 

func (p QuotaFailurePolicy) Validate() error

Validate checks failure actions without changing the caller's value.

type QuotaField 

type QuotaField = metering.ComponentKey

QuotaField aliases the canonical metering component identity. Quota fields must be nondirectional because account-window gauges have no request-flow direction. The alias also keeps field identity and measure identity exact.

type QuotaPolicy 

type QuotaPolicy struct {
	// contains filtered or unexported fields
}

QuotaPolicy is immutable after CompileQuotaPolicy returns. Mutable caller slices are normalized and copied, and accessors return copies.

func CompileQuotaPolicy 

func CompileQuotaPolicy(config QuotaPolicyConfig) (*QuotaPolicy, error)

CompileQuotaPolicy validates, normalizes and content-addresses a quota policy. The resulting hash is stable across required/threshold input order.

func NewQuotaPolicy 

func NewQuotaPolicy(config QuotaPolicyConfig) (*QuotaPolicy, error)

NewQuotaPolicy is an explicit constructor alias for CompileQuotaPolicy.

func (*QuotaPolicy) Binding 

func (p *QuotaPolicy) Binding() QuotaBinding

Binding returns the reset-scoped provider account/pool/window binding.

func (*QuotaPolicy) CanonicalJSON 

func (p *QuotaPolicy) CanonicalJSON() []byte

CanonicalJSON returns a copy of the normalized policy bytes used as the policy hash preimage.

func (*QuotaPolicy) Evaluate 

func (p *QuotaPolicy) Evaluate(input QuotaEvaluationInput) (QuotaDecision, error)

Evaluate applies one frozen policy to persisted account-window gauge history. It merges present fields in observation order, never adds gauge values or derives request consumption, then compares exact decimals.

func (*QuotaPolicy) FailurePolicy 

func (p *QuotaPolicy) FailurePolicy() QuotaFailurePolicy

FailurePolicy returns the normalized explicit missing/stale behavior.

func (*QuotaPolicy) Freshness 

func (p *QuotaPolicy) Freshness() time.Duration

Freshness returns the immutable maximum age accepted by the evaluator.

func (*QuotaPolicy) Hash 

func (p *QuotaPolicy) Hash() string

Hash returns the canonical SHA-256 policy hash.

func (*QuotaPolicy) ID 

func (p *QuotaPolicy) ID() string

ID returns the immutable policy identifier.

func (*QuotaPolicy) MarshalJSON 

func (p *QuotaPolicy) MarshalJSON() ([]byte, error)

MarshalJSON emits the same normalized policy body used for hashing. A caller that needs the immutable content hash should retain PolicyRef alongside the body.

func (*QuotaPolicy) Method 

func (p *QuotaPolicy) Method() string

Method returns the immutable policy method.

func (*QuotaPolicy) PolicyRef 

func (p *QuotaPolicy) PolicyRef() QuotaPolicyRef

PolicyRef returns the immutable method/version/hash binding.

func (*QuotaPolicy) Ref 

func (p *QuotaPolicy) Ref() QuotaPolicyRef

Ref is a concise alias for PolicyRef.

func (*QuotaPolicy) RequiredFields 

func (p *QuotaPolicy) RequiredFields() []QuotaField

RequiredFields returns a deep copy of the fields required for admission.

func (*QuotaPolicy) Thresholds 

func (p *QuotaPolicy) Thresholds() []QuotaThreshold

Thresholds returns a deep copy of the exact typed threshold set.

func (*QuotaPolicy) Version 

func (p *QuotaPolicy) Version() string

Version returns the immutable policy version.

type QuotaPolicyConfig 

type QuotaPolicyConfig struct {
	ID         string             `json:"id"`
	Version    string             `json:"version"`
	Method     string             `json:"method,omitempty"`
	Binding    QuotaBinding       `json:"binding"`
	Freshness  time.Duration      `json:"freshness"`
	Required   []QuotaField       `json:"required"`
	Thresholds []QuotaThreshold   `json:"thresholds,omitempty"`
	Failures   QuotaFailurePolicy `json:"failures"`
}

QuotaPolicyConfig is the source form for one immutable nonfinancial quota authority. It contains no price, currency, ledger, debit or customer-credit field by design.

func (QuotaPolicyConfig) Validate 

func (c QuotaPolicyConfig) Validate() error

Validate checks that the source form can be compiled into an immutable policy. It does not retain or mutate caller-owned slices.

type QuotaPolicyRef 

type QuotaPolicyRef struct {
	Method  string `json:"method"`
	ID      string `json:"id"`
	Version string `json:"version"`
	Hash    string `json:"hash"`
}

QuotaPolicyRef identifies the frozen nonfinancial policy used for one decision. Hash is lower-case SHA-256 over the canonical normalized policy.

func (QuotaPolicyRef) Validate 

func (r QuotaPolicyRef) Validate() error

type QuotaReason 

type QuotaReason string

QuotaReason explains a quota result without implying money or request consumption. It is bounded so an adapter can safely expose it in metrics. 

const (
	QuotaReasonAllowed              QuotaReason = "allowed"
	QuotaReasonThresholdExceeded    QuotaReason = "threshold_exceeded"
	QuotaReasonHeadroomInsufficient QuotaReason = "headroom_insufficient"
	QuotaReasonMissingEvidence      QuotaReason = "missing_evidence"
	QuotaReasonStaleEvidence        QuotaReason = "stale_evidence"
	QuotaReasonPartialEvidence      QuotaReason = "partial_evidence"
	QuotaReasonTelemetryUnavailable QuotaReason = "telemetry_unavailable"
	QuotaReasonAccountMismatch      QuotaReason = "account_mismatch"
	QuotaReasonTenantMismatch       QuotaReason = "tenant_mismatch"
	QuotaReasonStoreMismatch        QuotaReason = "store_mismatch"
	QuotaReasonPoolMismatch         QuotaReason = "pool_mismatch"
	QuotaReasonWindowMismatch       QuotaReason = "window_mismatch"
	QuotaReasonResetMismatch        QuotaReason = "reset_mismatch"
	QuotaReasonNotYetEffective      QuotaReason = "not_yet_effective"
	QuotaReasonInvalidEvidence      QuotaReason = "invalid_evidence"
)

func (QuotaReason) IsKnown 

func (r QuotaReason) IsKnown() bool

type QuotaThreshold 

type QuotaThreshold struct {
	Kind      QuotaThresholdKind `json:"kind"`
	Field     QuotaField         `json:"field"`
	ValueKind QuotaValueKind     `json:"value_kind"`
	Value     metering.Decimal   `json:"value"`
}

QuotaThreshold is one exact typed comparison against one gauge field. Percent values are in [0,100]. Absolute values are nonnegative decimals in the field's native unit; no cross-field conversion is attempted.

func (QuotaThreshold) Normalize 

func (t QuotaThreshold) Normalize() (QuotaThreshold, error)

Normalize returns a deep-copied threshold with exact canonical decimal representation.

func (QuotaThreshold) Validate 

func (t QuotaThreshold) Validate() error

Validate checks threshold kind, field unit and exact typed value.

type QuotaThresholdKind 

type QuotaThresholdKind string

QuotaThresholdKind identifies whether a value is a utilization ceiling or a headroom floor. Comparisons are exact and never derive one gauge from another.

func (QuotaThresholdKind) IsKnown 

func (k QuotaThresholdKind) IsKnown() bool

type QuotaValueKind 

type QuotaValueKind string

QuotaValueKind keeps percentage and absolute thresholds distinct even when a provider uses numerically similar values.

func (QuotaValueKind) IsKnown 

func (k QuotaValueKind) IsKnown() bool

type Readiness 

type Readiness string

Readiness reports whether the authority plane can enforce required decisions. 

const (
	ReadinessReady       Readiness = "ready"
	ReadinessDegraded    Readiness = "degraded"
	ReadinessUnavailable Readiness = "unavailable"
	ReadinessDisabled    Readiness = "disabled"
)

func (Readiness) IsKnown 

func (r Readiness) IsKnown() bool

IsKnown reports whether r is a documented readiness value.

type RequestAdmission 

type RequestAdmission struct {
	RequestID      string                        `json:"request_id"`
	ALegID         string                        `json:"a_leg_id,omitempty"`
	TraceID        string                        `json:"trace_id,omitempty"`
	Perspective    metering.EconomicPerspective  `json:"perspective"`
	Lifecycle      metering.LifecycleScope       `json:"lifecycle"`
	Scope          scope.PrincipalScopeView      `json:"scope"`
	Exposure       economics.ExposureBasis       `json:"exposure"`
	BoundVersions  []economics.PolicySnapshotRef `json:"bound_versions,omitempty"`
	RatingVersions []economics.RatingSnapshotRef `json:"rating_versions,omitempty"`
	IdempotencyKey string                        `json:"idempotency_key,omitempty"`
	// ParentLeaseID is set for auxiliary requests that inherit occupancy (10.10).
	ParentLeaseID string `json:"parent_lease_id,omitempty"`
	// AuxPolicy overrides default parent-lease inheritance for auxiliary admits.
	AuxPolicy string `json:"aux_policy,omitempty"`
}

RequestAdmission is logical-request admit input. It intentionally has no AttemptID or BLegID fields (requirements 9.2, 9.3).

func (RequestAdmission) Validate 

func (a RequestAdmission) Validate() error

Validate checks required request identity and enums.

type RequestPriority 

type RequestPriority string

RequestPriority is the deterministic evaluation class for request authorities (requirement 3.3; design Descriptor-Bound Registrations). 

const (
	RequestPriorityConcurrency     RequestPriority = "concurrency"
	RequestPriorityCreditWallet    RequestPriority = "credit_wallet"
	RequestPriorityQuotaBudgetRate RequestPriority = "quota_budget_rate"
	RequestPriorityAdvisory        RequestPriority = "advisory"
)

func (RequestPriority) IsKnown 

func (p RequestPriority) IsKnown() bool

IsKnown reports whether p is a documented request priority.

func (RequestPriority) Validate 

func (p RequestPriority) Validate() error

Validate returns an error when p is not a known request priority.

type RequestProvider 

type RequestProvider interface {
	AdmitRequest(ctx context.Context, in RequestAdmission) (Decision, error)
	SettleRequest(ctx context.Context, in RequestSettlement) (Settlement, error)
	ReleaseRequest(ctx context.Context, in RequestRelease) error
}

RequestProvider evaluates logical-request customer authority.

type RequestRegistration 

type RequestRegistration struct {
	Descriptor ProviderDescriptor
	Priority   RequestPriority
	Provider   RequestProvider
}

RequestRegistration binds a provider descriptor, priority, and request authority instance into one production registration (design D4).

func (RequestRegistration) Validate 

func (r RequestRegistration) Validate() error

Validate checks descriptor posture, priority, and provider instance binding.

type RequestRelease 

type RequestRelease struct {
	RequestID          string   `json:"request_id"`
	Handles            []string `json:"handles,omitempty"`
	CompensationHandle string   `json:"compensation_handle,omitempty"`
	Reason             string   `json:"reason,omitempty"`
}

RequestRelease compensates or releases prior request reservations.

type RequestSettlement 

type RequestSettlement struct {
	RequestID      string                        `json:"request_id"`
	Handles        []string                      `json:"handles,omitempty"`
	Facts          []metering.Fact               `json:"facts,omitempty"`
	BoundVersions  []economics.PolicySnapshotRef `json:"bound_versions,omitempty"`
	IdempotencyKey string                        `json:"idempotency_key,omitempty"`
}

RequestSettlement settles customer/logical-request reservations once.

type Reservation 

type Reservation struct {
	Handle   string             `json:"handle"`
	Kind     ReservationKind    `json:"kind,omitempty"`
	RuleID   string             `json:"rule_id,omitempty"`
	Quantity *metering.Quantity `json:"quantity,omitempty"`
	Money    *economics.Money   `json:"money,omitempty"`
}

Reservation is a successful admit hold to settle or compensate later. Handle remains opaque; Quantity or Money carries safe provider-neutral reserved exposure when later settlement needs the admission-time amount.

type ReservationKind 

type ReservationKind string

ReservationKind classifies a held reservation handle. 

const (
	ReservationQuota  ReservationKind = "quota"
	ReservationBudget ReservationKind = "budget"
	ReservationSpend  ReservationKind = "spend"
	ReservationCredit ReservationKind = "credit"
	ReservationOther  ReservationKind = "other"
)

func (ReservationKind) IsKnown 

func (k ReservationKind) IsKnown() bool

IsKnown reports whether k is a documented reservation kind.

type SafeEvidence 

type SafeEvidence struct {
	Category       string                    `json:"category,omitempty"`
	Code           string                    `json:"code,omitempty"`
	Message        string                    `json:"message,omitempty"`
	RuleID         string                    `json:"rule_id,omitempty"`
	ProviderID     string                    `json:"provider_id,omitempty"`
	Attrs          map[string]string         `json:"attrs,omitempty"`
	QuotaPolicyRef *QuotaPolicyRef           `json:"quota_policy_ref,omitempty"`
	EvidenceRefs   []metering.ObservationRef `json:"evidence_refs,omitempty"`
}

SafeEvidence is denial/allow evidence without secrets, raw payloads, or credentials (requirements 12.8, 14.x). Prefer stable categories and identifiers.

type Settlement 

type Settlement struct {
	Kind          SettlementKind                `json:"kind"`
	Handle        string                        `json:"handle,omitempty"`
	Consumed      economics.Money               `json:"consumed,omitzero"`
	Released      economics.Money               `json:"released,omitzero"`
	Evidence      SafeEvidence                  `json:"evidence,omitzero"`
	BoundVersions []economics.PolicySnapshotRef `json:"bound_versions,omitempty"`
}

Settlement is the result of settling a prior reservation.

func OwnedFinalSettlement 

func OwnedFinalSettlement(handles []string) Settlement

OwnedFinalSettlement returns SettlementFinal echoing the first submitted owned handle when present (providers must identify an owned handle).

func (Settlement) ValidateFor 

func (s Settlement) ValidateFor(handles []string, p metering.EconomicPerspective) error

ValidateFor checks Settlement against submitted provider-owned handles and perspective (design External Result Validation; requirements 4.5, 4.6, 4.9).

type SettlementKind 

type SettlementKind string

SettlementKind classifies settlement completion. 

const (
	SettlementFinal       SettlementKind = "final"
	SettlementPartial     SettlementKind = "partial"
	SettlementEstimated   SettlementKind = "estimated"
	SettlementUnavailable SettlementKind = "unavailable"
)

func (SettlementKind) IsKnown 

func (k SettlementKind) IsKnown() bool

IsKnown reports whether k is a documented settlement kind.

type Stage 

type Stage string

Stage identifies where an authority decision runs in the dual-plane lifecycle. 

const (
	StageRequestAdmit   Stage = "request_admit"
	StageRequestSettle  Stage = "request_settle"
	StageRequestRelease Stage = "request_release"
	StageAttemptAdmit   Stage = "attempt_admit"
	StageAttemptSettle  Stage = "attempt_settle"
	StageAttemptRelease Stage = "attempt_release"
	StageLeaseAdmit     Stage = "lease_admit"
	StageLeaseRelease   Stage = "lease_release"
)

func (Stage) IsKnown 

func (s Stage) IsKnown() bool

IsKnown reports whether s is a documented authority stage.

type StagePosture 

type StagePosture struct {
	Stage           Stage           `json:"stage"`
	Strength        Strength        `json:"strength"`
	FailureBehavior FailureBehavior `json:"failure_behavior"`
}

StagePosture is one provider's declared posture for one lifecycle stage.

func AdmitPosture 

func AdmitPosture(d ProviderDescriptor, admit Stage) (StagePosture, bool)

AdmitPosture returns the admit-stage posture for the registration family. Missing admit posture returns zero values and false.

func RequireAdmitPosture 

func RequireAdmitPosture(d ProviderDescriptor, admit Stage) (StagePosture, error)

RequireAdmitPosture returns the admit-stage posture or an error when absent.

func (StagePosture) Validate 

func (p StagePosture) Validate() error

Validate checks stage, strength, and failure behavior are known.

type Strength 

type Strength string

Strength classifies whether an authority provider is required or advisory for a lifecycle stage (requirement 15.1). 

const (
	StrengthRequired Strength = "required"
	StrengthAdvisory Strength = "advisory"
)

func (Strength) IsKnown 

func (s Strength) IsKnown() bool

IsKnown reports whether s is a documented strength.

func (Strength) Validate 

func (s Strength) Validate() error

Validate returns an error when s is not a known strength.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.