app

type ActiveLimitQuery struct {
	RuleID     string
	Dimensions domain.Dimensions
	At         time.Time
}

type AdmissionInput struct {
	Correlation    controlplane.Correlation
	Scope          scope.PrincipalScopeView
	Dimensions     domain.Dimensions
	Request        domain.Amount
	RequestCount   domain.Amount
	PreflightUsage domain.PreflightUsage
	Authority      domain.AuthorityLevel
	ReservationKey domain.ReservationKey
	EstimateOnly   bool
	// SkipEvidence suppresses durable policy/accounting evidence projection.
	// Clamp preview uses this with EstimateOnly so repeated preview admits do
	// not write audit noise; estimate-only precheck denials still record.
	SkipEvidence bool
	// Phase 7.2: lifecycle stage for rule filtering; exposure/facts for amount selection.
	LifecycleScope metering.LifecycleScope
	Perspective    metering.EconomicPerspective
	Exposure       economics.ExposureBasis
	Facts          []metering.Fact
}

type AdmissionReservation struct {
	ReservationID  string
	RuleID         string
	ReservedAmount domain.Amount
}

type AdmissionResult struct {
	Allowed bool
	Outcome domain.DecisionOutcome
	RuleIDs []string
	// AdvisoryRuleIDs are the matched rules configured with RuleModeAdvisory.
	// They are tracked separately from RuleIDs so the runtime can apply final
	// advisory usage to advisory windows even when no strict reservation was
	// created (requirement 7.7). Advisory rules never reserve.
	AdvisoryRuleIDs []string
	// UnreservedRuleIDs are matched rules whose allowed execution created no
	// reservation (advisory and strict fail-open paths). Their final usage is
	// applied through ApplyUsage at lifecycle completion.
	UnreservedRuleIDs []string
	// SelectedRuleID identifies the rule whose outcome won admission severity.
	// RuleIDs remains the complete matched set for multi-rule evidence.
	SelectedRuleID  string
	RuleKind        domain.RuleKind
	ReservationID   string
	Reserved        bool
	ReservedAmount  domain.Amount
	Reservations    []AdmissionReservation
	PolicyRecord    policydecision.Record
	AccountingEvent controlplane.Event
	// BoundVersion is the policy snapshot identity captured at admission (11.2).
	BoundVersion economics.PolicySnapshotRef
	// BoundRatingVersion is the rating/catalog snapshot identity when known (14.3).
	BoundRatingVersion economics.RatingSnapshotRef
}

type ApplyUsageCommand struct {
	Correlation          controlplane.Correlation
	Scope                scope.PrincipalScopeView
	Dimensions           domain.Dimensions
	RuleIDs              []string
	Usage                domain.PreflightUsage
	RequestCount         domain.Amount
	Authority            domain.AuthorityLevel
	MeasurementAuthority MeasurementAuthority
	Kind                 SettlementKind
	UsagePresent         bool
	At                   time.Time
	SourceKey            string
}

type ApplyUsageResult struct {
	Applied bool
	RuleIDs []string
}

type Clock interface {
	Now() time.Time
}

type DecisionHistoryResult struct {
	State QueryState
	Page  controlplane.Page[controlplane.AccountingDecisionRow]
}

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

type Evidence struct {
	At              time.Time
	Correlation     controlplane.Correlation
	Scope           scope.PrincipalScopeView
	RuleID          string
	MatchedRuleIDs  []string
	RuleType        string
	Outcome         controlplane.AccountingOutcome
	ReasonCode      policydecision.AccountingReasonCode
	ReservationID   string
	SettlementState controlplane.AccountingSettlementState
	// SourceKind and SourceSequence are included in event identity for mutation
	// stages. Admission evidence leaves them empty and zero.
	SourceKind       string
	SourceSequence   int
	Unit             string
	Limit            int64
	Consumed         int64
	Reserved         int64
	Adjustment       int64
	Authority        domain.AuthorityLevel
	Stage            string
	BackendAttempted bool
	OutputCommitted  bool
	// Dual-plane identity and version refs (requirements 1.6, 14.3, 17.4).
	AuthorityNamespace string
	Perspective        string
	LifecycleScope     string
	Basis              string
	RuleVersion        string
	Surfaced           string
	ReservationType    string
	ParentRequestID    string
	BoundPolicyVersion economics.PolicySnapshotRef
	BoundRatingVersion economics.RatingSnapshotRef
}

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

type LimitStatusResult struct {
	State QueryState
	Page  controlplane.Page[controlplane.AccountingLimitStatusRow]
}

type MeasurementAuthority struct {
	Usage domain.AuthorityLevel
}

type QueryState string

type ReleaseCommand struct {
	Reservations     []ReleaseDescriptor
	Correlation      controlplane.Correlation
	Scope            scope.PrincipalScopeView
	ReleaseKey       domain.ReleaseKey
	ReservationKey   domain.ReservationKey
	ReservationID    string
	RuleID           string
	Kind             ReleaseKind
	Amount           domain.Amount
	Authority        domain.AuthorityLevel
	Stage            string
	BackendAttempted bool
	OutputCommitted  bool
	At               time.Time
	SourceKey        string
}

type ReleaseDescriptor struct {
	Reservation ReservationDescriptor
	SourceKey   string
	Sequence    int
}

type ReleaseInput struct {
	Reservations   []ReleaseDescriptor
	Correlation    controlplane.Correlation
	Scope          scope.PrincipalScopeView
	ReservationKey domain.ReservationKey
	ReservationID  string
	RuleID         string
	Kind           ReleaseKind
	// Sequence distinguishes release stages that share one reservation identity.
	Sequence         int
	Amount           domain.Amount
	Authority        domain.AuthorityLevel
	Stage            string
	BackendAttempted bool
	OutputCommitted  bool
}

type ReleaseKind string

type ReleaseMutation struct {
	RuleID        string
	ReservationID string
	ReleasedDelta domain.Amount
}

type ReleaseResult struct {
	Applied          bool
	ReservationID    string
	ReleasedDelta    domain.Amount
	Mutations        []ReleaseMutation
	PolicyRecords    []policydecision.Record
	AccountingEvents []controlplane.Event
	PolicyRecord     policydecision.Record
	AccountingEvent  controlplane.Event
}

type ReservationCapacityError struct {
	Requested domain.Amount
	Remaining domain.Amount
}

type ReservationDescriptor struct {
	RuleID         string
	Kind           domain.RuleKind
	Unit           domain.AmountUnit
	Dimensions     domain.Dimensions
	ReservationKey domain.ReservationKey
	ReservationID  string
	Amount         domain.Amount
	SourceKey      string
	Authority      domain.AuthorityLevel
}

type ReservationSet []ReservationDescriptor

type ReserveCommand struct {
	Reservations       ReservationSet
	Correlation        controlplane.Correlation
	Scope              scope.PrincipalScopeView
	ReservationKey     domain.ReservationKey
	RuleID             string
	RuleType           string
	Dimensions         domain.Dimensions
	Request            domain.Amount
	Authority          domain.AuthorityLevel
	EstimateOnly       bool
	At                 time.Time
	SourceKey          string
	Surfaced           controlplane.UsageSurfaced
	ParentRequestID    string
	BoundPolicyVersion controlplane.VersionRef
	BoundRatingVersion controlplane.VersionRef
}

type ReserveResult struct {
	Applied        bool
	ReservationID  string
	ReservedAmount domain.Amount
	RuleID         string
	RuleType       string
	Reservations   []AdmissionReservation
}

type RuleReservationError struct {
	RuleID string
	Err    error
}

type RuleSnapshot struct {
	ID                 string
	Version            string
	EffectiveAt        time.Time
	FetchedAt          time.Time
	State              economics.SnapshotState
	Status             domain.AuthorityStatus
	UnknownAttribution domain.UnknownAttribution
	Rules              []domain.Rule
}

type RuleSource interface {
	Snapshot(ctx context.Context) (RuleSnapshot, error)
}

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

type ServiceOptions struct {
	EvaluationTimeout      time.Duration
	CleanupTimeout         time.Duration
	DefaultFailureBehavior domain.FailureBehavior
	StageMetrics           StageMetrics
}

type SettleCommand struct {
	Reservations         []SettlementDescriptor
	Correlation          controlplane.Correlation
	Scope                scope.PrincipalScopeView
	SettlementKey        domain.SettlementKey
	ReservationKey       domain.ReservationKey
	ReservationID        string
	RuleID               string
	Kind                 SettlementKind
	FinalUsage           domain.Amount
	ReservedUsage        domain.Amount
	EstimatedUsage       domain.Amount
	Authority            domain.AuthorityLevel
	MeasurementAuthority MeasurementAuthority
	FinalUsagePresent    bool
	Stage                string
	BackendAttempted     bool
	OutputCommitted      bool
	ClientCanceled       bool
	At                   time.Time
	SourceKey            string
}

type SettleInput struct {
	Reservations   []SettlementDescriptor
	Correlation    controlplane.Correlation
	Scope          scope.PrincipalScopeView
	ReservationKey domain.ReservationKey
	ReservationID  string
	RuleID         string
	Kind           SettlementKind
	// Sequence distinguishes partial, cancellation, final, and authoritative
	// reconciliation mutations that share one reservation identity.
	Sequence             int
	FinalUsage           domain.Amount
	ReservedUsage        domain.Amount
	EstimatedUsage       domain.Amount
	Authority            domain.AuthorityLevel
	MeasurementAuthority MeasurementAuthority
	FinalUsagePresent    bool
	Stage                string
	BackendAttempted     bool
	OutputCommitted      bool
	ClientCanceled       bool
	// Facts/Exposure carry quantity evidence for dual-plane rules.
	Exposure economics.ExposureBasis
	Facts    []metering.Fact
	// BoundVersion pins settlement to the admission-time policy snapshot (11.4).
	BoundVersion economics.PolicySnapshotRef
	// BoundRatingVersion pins rating identity when known at settlement (14.3).
	BoundRatingVersion economics.RatingSnapshotRef
}

type SettleResult struct {
	Applied          bool
	ReservationID    string
	ReleasedDelta    domain.Amount
	OverageDelta     domain.Amount
	AdjustmentDelta  domain.Amount
	Mutations        []SettlementMutation
	PolicyRecords    []policydecision.Record
	AccountingEvents []controlplane.Event
	PolicyRecord     policydecision.Record
	AccountingEvent  controlplane.Event
}

type SettlementDescriptor struct {
	Reservation          ReservationDescriptor
	FinalUsage           domain.Amount
	EstimatedUsage       domain.Amount
	SourceKey            string
	Sequence             int
	Authority            domain.AuthorityLevel
	MeasurementAuthority MeasurementAuthority
}

type SettlementKind string

type SettlementMutation struct {
	RuleID          string
	ReservationID   string
	ReleasedDelta   domain.Amount
	OverageDelta    domain.Amount
	AdjustmentDelta domain.Amount
}

type StageMetrics interface {
	ObserveStage(stage, provider, outcome string, seconds float64)
}

type StateStore interface {
	Reserve(ctx context.Context, cmd ReserveCommand) (ReserveResult, error)
	Settle(ctx context.Context, cmd SettleCommand) (SettleResult, error)
	Release(ctx context.Context, cmd ReleaseCommand) (ReleaseResult, error)
	ApplyUsage(ctx context.Context, cmd ApplyUsageCommand) (ApplyUsageResult, error)
	ActiveLimit(ctx context.Context, q ActiveLimitQuery) (controlplane.AccountingLimitStatusRow, bool, error)
	LimitStatus(ctx context.Context, q controlplane.AccountingLimitStatusQuery) (controlplane.Page[controlplane.AccountingLimitStatusRow], error)
	DecisionHistory(ctx context.Context, q controlplane.AccountingDecisionQuery) (controlplane.Page[controlplane.AccountingDecisionRow], error)
	CheckReadiness(ctx context.Context) (domain.AuthorityStatus, error)
}

type Store = StateStore