controlplane

package
v0.1.0-rc.1 Latest Latest
Warning

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

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

Documentation

Overview

Package controlplane defines the stable, safe control-plane evidence and query contracts for the LLM Interactive Proxy runtime.

Go API note (v2-compatible): Event carries a single EventDetail interface field instead of parallel nullable detail pointers. JSON on the wire is unchanged — category-keyed detail objects are preserved via custom marshaling.

The package is additive public SDK surface for future feature plugins, internal adapters, and protected operator query routes. It is safe-by-construction: raw bearer tokens, API keys, OAuth/resume tokens, credential secrets, raw transport headers, and raw request/response payloads are never fields on these types. Only stable identifiers, correlation fields, safe scope attribution, bounded summaries, and explicit availability/redaction state are carried.

Boundary rules (enforced by architecture tests):

  • This package must not import internal/core, internal/infra, internal/stdhttp, internal/plugins, database/sql, Bun, net/http, or any provider SDK.
  • The only permitted non-stdlib dependency is pkg/lipsdk/scope, which provides the safe, presence-aware principal/scope attribution snapshot.

The contract intentionally does not expose storage, transport, or provider types. Storage adapters and HTTP query routes translate into and out of these DTOs at their own boundaries.

Index

Constants

This section is empty.

Variables

View Source 
var ErrQueryTooBroad = errors.New("controlplane: query too broad")

ErrQueryTooBroad is returned when a query lacks selective bounds (14.4, 14.8).

View Source 
var ErrQueryUnsupported = errors.New("controlplane: query unsupported")

ErrQueryUnsupported is returned when a query class or filter is unsupported (14.5, 14.8).

Functions

func EconomicControlReady 

func EconomicControlReady(report ReadinessReport) bool

EconomicControlReady reports whether the OSS technical economic-control posture is ready for protected traffic (design EconomicControlReady). This is not commercial billing, payments, invoicing, or tax readiness.

func EvaluateEconomicControlReady 

func EvaluateEconomicControlReady(report ReadinessReport) (bool, string)

EvaluateEconomicControlReady returns readiness and the first blocking reason.

func ValidateAccountingDecisionQuery 

func ValidateAccountingDecisionQuery(q AccountingDecisionQuery) error

ValidateAccountingDecisionQuery rejects too-broad decision history queries.

func ValidateAccountingLimitStatusQuery 

func ValidateAccountingLimitStatusQuery(q AccountingLimitStatusQuery) error

ValidateAccountingLimitStatusQuery rejects queries that do not target remaining live authority rows.

func ValidateCalculatedAmount 

func ValidateCalculatedAmount(a CalculatedAmount) error

ValidateCalculatedAmount rejects amounts that omit an explicit calculation type (14.7).

func ValidateUsageQuery 

func ValidateUsageQuery(q UsageQuery) error

ValidateUsageQuery rejects too-broad or unsupported usage evidence queries.

Types

type AccountingAuthorityDetail 

type AccountingAuthorityDetail struct {
	Correlation     Correlation               `json:"correlation"`
	Scope           ScopeSnapshot             `json:"scope"`
	RuleID          string                    `json:"rule_id,omitempty"`
	RuleType        string                    `json:"rule_type,omitempty"`
	Outcome         AccountingOutcome         `json:"outcome"`
	ReasonCode      string                    `json:"reason_code,omitempty"`
	Authority       AccountingAuthoritySource `json:"authority,omitempty"`
	ReservationID   string                    `json:"reservation_id,omitempty"`
	SettlementState AccountingSettlementState `json:"settlement_state,omitempty"`
	Unit            string                    `json:"unit,omitempty"`
	Currency        string                    `json:"currency,omitempty"`
	Limit           int64                     `json:"limit,omitempty"`
	Consumed        int64                     `json:"consumed,omitempty"`
	Reserved        int64                     `json:"reserved,omitempty"`
	Remaining       int64                     `json:"remaining,omitempty"`
	Adjustment      int64                     `json:"adjustment,omitempty"`
	WindowStart     time.Time                 `json:"window_start,omitzero"`
	WindowEnd       time.Time                 `json:"window_end,omitzero"`
	WindowResetAt   time.Time                 `json:"window_reset_at,omitzero"`
	EvidenceState   EvidenceState             `json:"evidence_state"`
	RedactionState  RedactionState            `json:"redaction_state"`
	// Dual-plane identity (requirements 1.6, 14.3, 17.4).
	AuthorityNamespace string              `json:"authority_namespace,omitempty"`
	Perspective        UsagePerspective    `json:"perspective,omitempty"`
	LifecycleScope     UsageLifecycleScope `json:"lifecycle_scope,omitempty"`
	Basis              string              `json:"basis,omitempty"`
	RuleVersion        string              `json:"rule_version,omitempty"`
	Surfaced           UsageSurfaced       `json:"surfaced,omitempty"`
	ReservationType    AuthorityHandleType `json:"reservation_type,omitempty"`
	ParentRequestID    string              `json:"parent_request_id,omitempty"`
	BoundPolicyVersion VersionRef          `json:"bound_policy_version,omitzero"`
	BoundRatingVersion VersionRef          `json:"bound_rating_version,omitzero"`
}

AccountingAuthorityDetail is the safe, queryable accounting authority evidence block for decisions, reservations, settlements, adjustments, and unavailable states.

"No window" semantic for WindowStart/End/ResetAt: a projector that emits this detail may not have access to the rule's window metadata (the rule snapshot is the authoritative source for window bounds). In that case the projector MUST leave all three fields as the time.Time zero value. SDK consumers MUST treat WindowStart.IsZero(), WindowEnd.IsZero(), and WindowResetAt.IsZero() as "not applicable" rather than as a zero-length or "reset now" window. To look up actual window bounds, query the accounting limit status (AccountingLimitStatusRow.WindowStart/End/ResetAt) which is always populated by the authority store. Event.Validate does not reject zero window fields precisely so this no-window projection is a valid contract.

type AccountingAuthoritySource 

type AccountingAuthoritySource string

AccountingAuthoritySource identifies the authority posture that produced the detail or row. 

const (
	AccountingAuthoritySourceEstimated     AccountingAuthoritySource = "estimated"
	AccountingAuthoritySourceAuthoritative AccountingAuthoritySource = "authoritative"
	AccountingAuthoritySourceReserved      AccountingAuthoritySource = "reserved"
	AccountingAuthoritySourceReconciled    AccountingAuthoritySource = "reconciled"
	AccountingAuthoritySourceAdvisory      AccountingAuthoritySource = "advisory"
	AccountingAuthoritySourceUnavailable   AccountingAuthoritySource = "unavailable"
)

func (AccountingAuthoritySource) IsKnown 

func (s AccountingAuthoritySource) IsKnown() bool

IsKnown reports whether s is one of the documented accounting authority sources.

type AccountingAuthorityState 

type AccountingAuthorityState string

AccountingAuthorityState reports the operator-visible readiness posture for accounting authority queries and live limit state. 

const (
	AccountingAuthorityDisabled     AccountingAuthorityState = "disabled"
	AccountingAuthorityReady        AccountingAuthorityState = "ready"
	AccountingAuthorityDegraded     AccountingAuthorityState = "degraded"
	AccountingAuthorityUnavailable  AccountingAuthorityState = "unavailable"
	AccountingAuthorityAdvisoryOnly AccountingAuthorityState = "advisory_only"
)

func (AccountingAuthorityState) IsKnown 

func (s AccountingAuthorityState) IsKnown() bool

IsKnown reports whether s is one of the documented accounting authority states.

type AccountingAuthorityStatus 

type AccountingAuthorityStatus struct {
	State          AccountingAuthorityState `json:"state"`
	Reason         ReasonCode               `json:"reason,omitempty"`
	LastUpdatedAt  time.Time                `json:"last_updated_at,omitzero"`
	EvidenceState  EvidenceState            `json:"evidence_state"`
	RedactionState RedactionState           `json:"redaction_state"`
}

AccountingAuthorityStatus is the operator-visible live posture snapshot for accounting authority. It remains distinct from historical usage aggregates.

type AccountingDecisionQuery 

type AccountingDecisionQuery struct {
	Common          CommonFilters             `json:"common,omitzero"`
	RuleID          string                    `json:"rule_id,omitempty"`
	Unit            string                    `json:"unit,omitempty"`
	Currency        string                    `json:"currency,omitempty"`
	Authority       AccountingAuthoritySource `json:"authority,omitempty"`
	SettlementState AccountingSettlementState `json:"settlement_state,omitempty"`
	EvidenceState   EvidenceState             `json:"evidence_state,omitempty"`
	RedactionState  RedactionState            `json:"redaction_state,omitempty"`
	Perspective     UsagePerspective          `json:"perspective,omitempty"`
	LifecycleScope  UsageLifecycleScope       `json:"lifecycle_scope,omitempty"`
	Basis           string                    `json:"basis,omitempty"`
	Class           QueryClass                `json:"class,omitempty"`
	Limit           int                       `json:"limit,omitempty"`
	Cursor          Cursor                    `json:"cursor,omitzero"`
	Visibility      Visibility                `json:"visibility,omitempty"`
}

AccountingDecisionQuery requests bounded accounting decision rows.

type AccountingDecisionRow 

type AccountingDecisionRow struct {
	Correlation     Correlation               `json:"correlation"`
	Scope           ScopeSnapshot             `json:"scope"`
	RuleID          string                    `json:"rule_id,omitempty"`
	Outcome         AccountingOutcome         `json:"outcome"`
	ReasonCode      string                    `json:"reason_code,omitempty"`
	Authority       AccountingAuthoritySource `json:"authority,omitempty"`
	ReservationID   string                    `json:"reservation_id,omitempty"`
	SettlementState AccountingSettlementState `json:"settlement_state,omitempty"`
	Unit            string                    `json:"unit,omitempty"`
	Currency        string                    `json:"currency,omitempty"`
	Limit           int64                     `json:"limit,omitempty"`
	Consumed        int64                     `json:"consumed,omitempty"`
	Reserved        int64                     `json:"reserved,omitempty"`
	Remaining       int64                     `json:"remaining,omitempty"`
	Released        int64                     `json:"released,omitzero"`
	Overage         int64                     `json:"overage,omitzero"`
	Adjustment      int64                     `json:"adjustment,omitzero"`
	WindowStart     time.Time                 `json:"window_start,omitzero"`
	WindowEnd       time.Time                 `json:"window_end,omitzero"`
	WindowResetAt   time.Time                 `json:"window_reset_at,omitzero"`
	EvidenceState   EvidenceState             `json:"evidence_state"`
	RedactionState  RedactionState            `json:"redaction_state"`
	// Dual-plane identity (requirements 1.6, 14.3, 17.4).
	AuthorityNamespace string              `json:"authority_namespace,omitempty"`
	Perspective        UsagePerspective    `json:"perspective,omitempty"`
	LifecycleScope     UsageLifecycleScope `json:"lifecycle_scope,omitempty"`
	Basis              string              `json:"basis,omitempty"`
	RuleVersion        string              `json:"rule_version,omitempty"`
	Surfaced           UsageSurfaced       `json:"surfaced,omitempty"`
	ReservationType    AuthorityHandleType `json:"reservation_type,omitempty"`
	ParentRequestID    string              `json:"parent_request_id,omitempty"`
	BoundPolicyVersion VersionRef          `json:"bound_policy_version,omitzero"`
	BoundRatingVersion VersionRef          `json:"bound_rating_version,omitzero"`
}

AccountingDecisionRow is the decision-history view for accounting authority evidence.

WindowStart/End/ResetAt are populated by the authority store's appendDecision path from the live limit row. They are set only when the underlying rule has a window definition; rules without a window definition leave these fields as the zero time.Time. SDK consumers SHOULD treat zero values on these fields as "no window" — same contract as AccountingLimitStatusRow.

Released/Overage/Adjustment carry the settlement/release delta for the mutation recorded by this row. Settle records released/overage/adjustment (adjustment = released - overage); release records released with adjustment mirroring released and no overage; reserve decisions (allow or deny) leave all three as zero. They use the ,omitzero JSON tag so reserve rows omit them entirely and consumers can distinguish "no settlement delta" from a real zero-valued adjustment.

type AccountingLimitStatusQuery 

type AccountingLimitStatusQuery struct {
	Common          CommonFilters             `json:"common,omitzero"`
	RuleID          string                    `json:"rule_id,omitempty"`
	Unit            string                    `json:"unit,omitempty"`
	Currency        string                    `json:"currency,omitempty"`
	Authority       AccountingAuthoritySource `json:"authority,omitempty"`
	SettlementState AccountingSettlementState `json:"settlement_state,omitempty"`
	EvidenceState   EvidenceState             `json:"evidence_state,omitempty"`
	RedactionState  RedactionState            `json:"redaction_state,omitempty"`
	Perspective     UsagePerspective          `json:"perspective,omitempty"`
	LifecycleScope  UsageLifecycleScope       `json:"lifecycle_scope,omitempty"`
	Basis           string                    `json:"basis,omitempty"`
	Class           QueryClass                `json:"class,omitempty"`
	Limit           int                       `json:"limit,omitempty"`
	Cursor          Cursor                    `json:"cursor,omitzero"`
	Visibility      Visibility                `json:"visibility,omitempty"`
}

AccountingLimitStatusQuery requests bounded live accounting limit rows.

type AccountingLimitStatusRow 

type AccountingLimitStatusRow struct {
	Correlation    Correlation               `json:"correlation"`
	Scope          ScopeSnapshot             `json:"scope"`
	RuleID         string                    `json:"rule_id,omitempty"`
	RuleType       string                    `json:"rule_type,omitempty"`
	Unit           string                    `json:"unit,omitempty"`
	Currency       string                    `json:"currency,omitempty"`
	Limit          int64                     `json:"limit,omitempty"`
	Consumed       int64                     `json:"consumed,omitempty"`
	Reserved       int64                     `json:"reserved,omitempty"`
	Remaining      int64                     `json:"remaining,omitempty"`
	Adjustment     int64                     `json:"adjustment,omitempty"`
	WindowStart    time.Time                 `json:"window_start,omitzero"`
	WindowEnd      time.Time                 `json:"window_end,omitzero"`
	WindowResetAt  time.Time                 `json:"window_reset_at,omitzero"`
	Authority      AccountingAuthoritySource `json:"authority,omitempty"`
	EvidenceState  EvidenceState             `json:"evidence_state"`
	RedactionState RedactionState            `json:"redaction_state"`
	// Dual-plane identity (Phase 7). Empty AuthorityNamespace means legacy.
	AuthorityNamespace string `json:"authority_namespace,omitempty"`
	Perspective        string `json:"perspective,omitempty"`
	LifecycleScope     string `json:"lifecycle_scope,omitempty"`
	Basis              string `json:"basis,omitempty"`
	RuleVersion        string `json:"rule_version,omitempty"`
}

AccountingLimitStatusRow is the live accounting limit view distinct from historical usage aggregates.

WindowStart/End/ResetAt are populated by the authority store from the rule's window bounds at append time. They are set only when the rule has a window definition (Window.Algorithm, Size, or Anchor); rules without a window definition leave these fields as the zero time.Time. SDK consumers SHOULD treat zero values on these fields as "no window" — same contract as AccountingAuthorityDetail. To check whether the authority is enabled and queryable, use AccountingAuthorityStatus before reading limit rows.

type AccountingOutcome 

type AccountingOutcome string

AccountingOutcome is the safe accounting decision vocabulary used by accounting authority detail and query rows. 

const (
	AccountingOutcomeAllow       AccountingOutcome = "allow"
	AccountingOutcomeDeny        AccountingOutcome = "deny"
	AccountingOutcomeAdvisory    AccountingOutcome = "advisory"
	AccountingOutcomeClamp       AccountingOutcome = "clamp"
	AccountingOutcomeReserve     AccountingOutcome = "reserve"
	AccountingOutcomeReconcile   AccountingOutcome = "reconcile"
	AccountingOutcomeUnavailable AccountingOutcome = "unavailable"
	AccountingOutcomeError       AccountingOutcome = "error"
)

func (AccountingOutcome) IsKnown 

func (o AccountingOutcome) IsKnown() bool

IsKnown reports whether o is one of the documented accounting outcomes.

type AccountingPageQueries 

type AccountingPageQueries interface {
	LimitStatus(ctx context.Context, q AccountingLimitStatusQuery) (Page[AccountingLimitStatusRow], error)
	Decisions(ctx context.Context, q AccountingDecisionQuery) (Page[AccountingDecisionRow], error)
}

AccountingPageQueries is the stable service contract for bounded accounting authority query views.

type AccountingQueries 

type AccountingQueries interface {
	AccountingStatusReader
	AccountingPageQueries
}

AccountingQueries composes live status and bounded page queries for the dedicated accounting authority control-plane surface.

type AccountingSettlementState 

type AccountingSettlementState string

AccountingSettlementState reports the settlement posture attached to a reservation or reconciliation record. 

const (
	AccountingSettlementPending     AccountingSettlementState = "pending"
	AccountingSettlementSettled     AccountingSettlementState = "settled"
	AccountingSettlementReleased    AccountingSettlementState = "released"
	AccountingSettlementAdjusted    AccountingSettlementState = "adjusted"
	AccountingSettlementOverage     AccountingSettlementState = "overage"
	AccountingSettlementUnavailable AccountingSettlementState = "unavailable"
)

func (AccountingSettlementState) IsKnown 

func (s AccountingSettlementState) IsKnown() bool

IsKnown reports whether s is one of the documented settlement states.

type AccountingStatusReader 

type AccountingStatusReader interface {
	Status(ctx context.Context) (AccountingAuthorityStatus, error)
}

AccountingStatusReader is the stable service contract for reading the live accounting authority posture.

type AttemptDetail 

type AttemptDetail struct {
	ALegID       string          `json:"a_leg_id,omitempty"`
	BLegID       string          `json:"b_leg_id,omitempty"`
	AttemptSeq   int             `json:"attempt_seq,omitempty"`
	BackendID    string          `json:"backend_id,omitempty"`
	Model        string          `json:"model,omitempty"`
	RouteOutcome string          `json:"route_outcome,omitempty"`
	Surfaced     AttemptSurfaced `json:"surfaced"`
	Outcome      AttemptOutcome  `json:"outcome"`
	ErrorClass   string          `json:"error_class,omitempty"`
	StartedAt    time.Time       `json:"started_at,omitzero"`
	FinishedAt   time.Time       `json:"finished_at,omitzero"`
}

AttemptDetail is the typed detail block for CategoryAttempt events (requirement 1.3, 3.2, 3.3). Surfaced distinguishes client-visible attempts from swallowed, cancelled, or losing attempts so query consumers do not read a replacement as a transparent continuation of surfaced output.

type AttemptOutcome 

type AttemptOutcome string

AttemptOutcome classifies the terminal outcome of a backend attempt (requirement 3.2). 

const (
	AttemptOutcomeUnknown   AttemptOutcome = "unknown"
	AttemptOutcomeSucceeded AttemptOutcome = "succeeded"
	AttemptOutcomeFailed    AttemptOutcome = "failed"
	AttemptOutcomeCancelled AttemptOutcome = "cancelled"
	AttemptOutcomeLostRace  AttemptOutcome = "lost_race"
)

func (AttemptOutcome) IsKnown 

func (o AttemptOutcome) IsKnown() bool

IsKnown reports whether o is one of the documented attempt outcomes.

type AttemptQuery 

type AttemptQuery struct {
	Common     CommonFilters `json:"common,omitzero"`
	Surfaced   string        `json:"surfaced,omitempty"`
	Limit      int           `json:"limit,omitempty"`
	Cursor     Cursor        `json:"cursor,omitzero"`
	Visibility Visibility    `json:"visibility,omitempty"`
}

AttemptQuery requests bounded backend attempt rows (requirement 2.2).

type AttemptRow 

type AttemptRow struct {
	Correlation   Correlation     `json:"correlation"`
	BackendID     string          `json:"backend_id,omitempty"`
	Model         string          `json:"model,omitempty"`
	RouteOutcome  string          `json:"route_outcome,omitempty"`
	Surfaced      AttemptSurfaced `json:"surfaced"`
	Outcome       AttemptOutcome  `json:"outcome"`
	ErrorClass    string          `json:"error_class,omitempty"`
	StartedAt     time.Time       `json:"started_at,omitzero"`
	FinishedAt    time.Time       `json:"finished_at,omitzero"`
	EvidenceState EvidenceState   `json:"evidence_state"`
}

AttemptRow is one row of an AttemptQuery result (requirement 2.2, 3.2).

type AttemptSurfaced 

type AttemptSurfaced string

AttemptSurfaced classifies whether a backend attempt produced client-visible output (requirement 3.2, 3.3). 

const (
	AttemptSurfacedUnknown   AttemptSurfaced = "unknown"
	AttemptSurfacedSurfaced  AttemptSurfaced = "surfaced"
	AttemptSurfacedSwallowed AttemptSurfaced = "swallowed"
)

func (AttemptSurfaced) IsKnown 

func (s AttemptSurfaced) IsKnown() bool

IsKnown reports whether s is one of the documented surfaced states.

type AuditDetail 

type AuditDetail struct {
	Action     string `json:"action"`
	Result     string `json:"result,omitempty"`
	ReasonCode string `json:"reason_code,omitempty"`
}

AuditDetail is the typed detail block for CategoryAudit events (requirement 1.6, 9.3). Action and Result are safe summaries; privileged audit evidence is marked via the Event RedactionState and Visibility, not raw fields here.

type AuthDetail 

type AuthDetail struct {
	Outcome    string `json:"outcome"`
	ReasonCode string `json:"reason_code,omitempty"`
	Frontend   string `json:"frontend,omitempty"`
	AuthMethod string `json:"auth_method,omitempty"`
	IsNew      bool   `json:"is_new,omitempty"`
}

AuthDetail is the typed detail block for CategoryAuth events (requirement 1.1). Outcome and ReasonCode are safe, non-secret classifications; raw challenge material and credentials are never carried here.

type AuthorityHandleType 

type AuthorityHandleType string

AuthorityHandleType classifies the authority handle referenced by evidence. 

const (
	AuthorityHandleReservation AuthorityHandleType = "reservation"
	AuthorityHandleLease       AuthorityHandleType = "lease"
)

type CalculatedAmount 

type CalculatedAmount struct {
	Calculation ReportCalculationType `json:"calculation"`
	Money       MoneyAmountInput      `json:"money,omitzero"`
	Quantity    TokenQuantityInput    `json:"quantity,omitzero"`
}

CalculatedAmount is the only DTO that may combine customer and operator economics. It always carries an explicit ReportCalculationType (14.7).

func CalculateCompressionTokenSavings 

func CalculateCompressionTokenSavings(in CompressionReportInput) (CalculatedAmount, error)

CalculateCompressionTokenSavings returns frontend minus backend input tokens via an explicit compression_token_savings calculation (4.7, 14.6).

func CalculateGrossMargin 

func CalculateGrossMargin(customer CustomerChargeInput, operator OperatorCostInput) (CalculatedAmount, error)

CalculateGrossMargin returns customer charge minus operator cost using an explicit gross_margin calculation (14.7).

func CalculateRoutingOverheadTotal 

func CalculateRoutingOverheadTotal(in RoutingOverheadInput) (CalculatedAmount, error)

CalculateRoutingOverheadTotal returns non-surfaced attempt overhead cost via an explicit routing_overhead_total calculation (5.7, 14.7).

type CapabilityState 

type CapabilityState string

CapabilityState is the operator-visible readiness state of the control-plane capability (requirement 7.1, 7.5). 

const (
	CapabilityDisabled    CapabilityState = "disabled"
	CapabilityReady       CapabilityState = "ready"
	CapabilityDegraded    CapabilityState = "degraded"
	CapabilityUnavailable CapabilityState = "unavailable"
)

func (CapabilityState) IsKnown 

func (s CapabilityState) IsKnown() bool

IsKnown reports whether s is one of the documented capability states.

type CapabilityStatus 

type CapabilityStatus struct {
	State           CapabilityState `json:"state"`
	Reason          ReasonCode      `json:"reason,omitempty"`
	LastFailureAt   time.Time       `json:"last_failure_at,omitzero"`
	RecordingPolicy RecordingPolicy `json:"recording_policy,omitempty"`
}

CapabilityStatus is the operator-visible status snapshot for the control-plane capability (requirement 7.1, 7.2, 7.3).

type Category 

type Category string

Category classifies one control-plane evidence record into a lifecycle domain. Exactly one Category is carried per Event, and it must match the single typed detail block (requirement 1.7, 1.8). 

const (
	CategoryAuth                Category = "auth"
	CategorySession             Category = "session"
	CategoryAttempt             Category = "attempt"
	CategoryUsage               Category = "usage"
	CategoryAccountingAuthority Category = "accounting_authority"
	CategoryPolicy              Category = "policy"
	CategoryAudit               Category = "audit"
	CategoryLifecycle           Category = "lifecycle"
)

func (Category) IsKnown 

func (c Category) IsKnown() bool

IsKnown reports whether c is one of the documented category values.

type CommonFilters 

type CommonFilters struct {
	Scope      ScopeFilters `json:"scope,omitzero"`
	TimeRange  TimeRange    `json:"time_range,omitzero"`
	BackendID  string       `json:"backend_id,omitempty"`
	Model      string       `json:"model,omitempty"`
	FrontendID string       `json:"frontend_id,omitempty"`
	TraceID    string       `json:"trace_id,omitempty"`
	SessionID  string       `json:"session_id,omitempty"`
	ALegID     string       `json:"a_leg_id,omitempty"`
	BLegID     string       `json:"b_leg_id,omitempty"`
	Outcome    string       `json:"outcome,omitempty"`
	ReasonCode string       `json:"reason_code,omitempty"`
}

CommonFilters are the correlation and scope filters shared across query shapes (requirement 2.5, 9.1).

type CompressionReportInput 

type CompressionReportInput struct {
	FrontendInput   TokenQuantityInput `json:"frontend_input,omitzero"`
	BackendInput    TokenQuantityInput `json:"backend_input,omitzero"`
	DeliveredOutput TokenQuantityInput `json:"delivered_output,omitzero"`
	ProviderOutput  TokenQuantityInput `json:"provider_output,omitzero"`
	ProviderCost    MoneyAmountInput   `json:"provider_cost,omitzero"`
}

CompressionReportInput exposes transformation lineage without raw content (requirements 4.7, 14.6).

type ConcurrencyAuthorityState 

type ConcurrencyAuthorityState string

ConcurrencyAuthorityState reports operator-visible lease-authority readiness. 

const (
	ConcurrencyAuthorityDisabled    ConcurrencyAuthorityState = "disabled"
	ConcurrencyAuthorityReady       ConcurrencyAuthorityState = "ready"
	ConcurrencyAuthorityDegraded    ConcurrencyAuthorityState = "degraded"
	ConcurrencyAuthorityUnavailable ConcurrencyAuthorityState = "unavailable"
)

func (ConcurrencyAuthorityState) IsKnown 

func (s ConcurrencyAuthorityState) IsKnown() bool

IsKnown reports whether s is a documented concurrency authority state.

type ConcurrencyAuthorityStatus 

type ConcurrencyAuthorityStatus struct {
	State          ConcurrencyAuthorityState `json:"state"`
	Reason         string                    `json:"reason,omitempty"`
	EvidenceState  EvidenceState             `json:"evidence_state,omitempty"`
	RedactionState RedactionState            `json:"redaction_state,omitempty"`
	LastUpdatedAt  time.Time                 `json:"last_updated_at,omitzero"`
	// LeaseSets exposes bounded active/uncertain/expiring/released/failed counts.
	LeaseSets LeaseSetOccupancyCounts `json:"lease_sets,omitzero"`
}

ConcurrencyAuthorityStatus is the safe readiness snapshot for lease authority.

type ConcurrencyCapacityRow 

type ConcurrencyCapacityRow struct {
	RuleID         string `json:"rule_id"`
	RuleVersion    string `json:"rule_version,omitempty"`
	DimensionKey   string `json:"dimension_key,omitempty"`
	Limit          int    `json:"limit"`
	Active         int    `json:"active"`
	Expiring       int    `json:"expiring,omitempty"`
	RemainingSlots int    `json:"remaining_slots"`
}

ConcurrencyCapacityRow reports remaining slots for one rule (requirement 10.12).

type ConcurrencyLeaseQuery 

type ConcurrencyLeaseQuery struct {
	RequestID string                `json:"request_id,omitempty"`
	LeaseID   string                `json:"lease_id,omitempty"`
	RuleID    string                `json:"rule_id,omitempty"`
	State     ConcurrencyLeaseState `json:"state,omitempty"`
	Limit     int                   `json:"limit,omitempty"`
	Cursor    Cursor                `json:"cursor,omitzero"`
}

ConcurrencyLeaseQuery requests a bounded page of lease rows. Unsupported filters must fail closed with an unsupported/too-broad outcome.

type ConcurrencyLeaseRow 

type ConcurrencyLeaseRow struct {
	LeaseID        string                `json:"lease_id"`
	RequestID      string                `json:"request_id,omitempty"`
	RuleID         string                `json:"rule_id,omitempty"`
	RuleVersion    string                `json:"rule_version,omitempty"`
	DimensionKey   string                `json:"dimension_key,omitempty"` // safe scope correlation
	State          ConcurrencyLeaseState `json:"state"`
	Generation     int64                 `json:"generation,omitempty"`
	ExpiresAt      time.Time             `json:"expires_at,omitzero"`
	ReleasedAt     time.Time             `json:"released_at,omitzero"`
	RemainingSlots int                   `json:"remaining_slots,omitempty"`
	EvidenceState  EvidenceState         `json:"evidence_state,omitempty"`
	RedactionState RedactionState        `json:"redaction_state,omitempty"`
}

ConcurrencyLeaseRow is one safe lease correlation row (no other principals).

type ConcurrencyLeaseState 

type ConcurrencyLeaseState string

ConcurrencyLeaseState is the queryable occupancy state for one lease row. 

const (
	ConcurrencyLeaseActive   ConcurrencyLeaseState = "active"
	ConcurrencyLeaseExpiring ConcurrencyLeaseState = "expiring"
	ConcurrencyLeaseExpired  ConcurrencyLeaseState = "expired"
	ConcurrencyLeaseReleased ConcurrencyLeaseState = "released"
)

func (ConcurrencyLeaseState) IsKnown 

func (s ConcurrencyLeaseState) IsKnown() bool

IsKnown reports whether s is a documented concurrency lease state.

type Correlation 

type Correlation struct {
	TraceID       string `json:"trace_id,omitempty"`
	RequestID     string `json:"request_id,omitempty"`
	SessionID     string `json:"session_id,omitempty"`
	ALegID        string `json:"a_leg_id,omitempty"`
	BLegID        string `json:"b_leg_id,omitempty"`
	AttemptSeq    int    `json:"attempt_seq,omitempty"`
	FrontendID    string `json:"frontend_id,omitempty"`
	BackendID     string `json:"backend_id,omitempty"`
	Model         string `json:"model,omitempty"`
	ParentTraceID string `json:"parent_trace_id,omitempty"`
}

Correlation carries the shared identifiers that let query consumers deduplicate and correlate evidence from auth, session, attempt, usage, policy, and audit paths (requirement 3.1, 3.7, 9.1). All fields are optional; unknown identifiers must be omitted rather than invented (requirement 3.6).

type Cursor 

type Cursor struct {
	Token string `json:"token,omitempty"`
}

Cursor is an opaque continuation token tied to a specific query shape and visibility level (requirement 2.7, 7.4). Consumers must treat the Token as opaque bytes; the core query service validates cursor shape before store access and rejects reuse across different query conditions.

func (Cursor) IsZero 

func (c Cursor) IsZero() bool

IsZero reports whether the cursor carries no continuation.

type CustomerChargeInput 

type CustomerChargeInput struct {
	Money                 MoneyAmountInput   `json:"money,omitzero"`
	FrontendIngressTokens TokenQuantityInput `json:"frontend_ingress_tokens,omitzero"`
	FrontendEgressTokens  TokenQuantityInput `json:"frontend_egress_tokens,omitzero"`
	RatingVersion         VersionRef         `json:"rating_version,omitzero"`
}

CustomerChargeInput holds independently queryable customer charge facts (5.7).

type DedupeOutcome 

type DedupeOutcome string

DedupeOutcome reports the idempotent projection outcome for a source event key (requirement 1.7, design "Idempotency"). 

const (
	DedupeInserted  DedupeOutcome = "inserted"
	DedupeDuplicate DedupeOutcome = "duplicate"
)

func (DedupeOutcome) IsKnown 

func (d DedupeOutcome) IsKnown() bool

IsKnown reports whether d is one of the documented dedupe outcomes.

type DualPlaneReportInputs 

type DualPlaneReportInputs struct {
	Customer         CustomerChargeInput    `json:"customer"`
	Operator         OperatorCostInput      `json:"operator"`
	Compression      CompressionReportInput `json:"compression,omitzero"`
	RoutingOverhead  RoutingOverheadInput   `json:"routing_overhead,omitzero"`
	Completeness     ReportCompleteness     `json:"completeness,omitempty"`
	LegacyProvenance ReportLegacyProvenance `json:"legacy_provenance,omitempty"`
}

DualPlaneReportInputs groups independent source inputs for query/report consumers. It intentionally omits any merged total field (14.7).

func DualPlaneReportInputsFromFacts 

func DualPlaneReportInputsFromFacts(facts []metering.Fact) (DualPlaneReportInputs, error)

DualPlaneReportInputsFromFacts reconstructs customer/operator/compression/ routing-overhead report inputs solely from metering facts. Missing ingress is classified incomplete; quantities are never invented.

type EnforcementScope 

type EnforcementScope string

EnforcementScope classifies whether a component provides distributed strict enforcement or advisory single-process posture (15.8). 

const (
	EnforcementScopeDistributedStrict     EnforcementScope = "distributed_strict"
	EnforcementScopeAdvisorySingleProcess EnforcementScope = "advisory_single_process"
	EnforcementScopeDisabled              EnforcementScope = "disabled"
)

func EnforcementScopeForStoreBacking 

func EnforcementScopeForStoreBacking(store string, strictCapable bool) EnforcementScope

EnforcementScopeForStoreBacking maps configured store backing to enforcement scope. Local memory (and sqlite single-node stores) are never distributed strict (15.8, 16.7).

func (EnforcementScope) IsKnown 

func (s EnforcementScope) IsKnown() bool

IsKnown reports whether s is a documented enforcement scope.

type ErrorCode 

type ErrorCode string

ErrorCode is the stable classification carried on query/recording errors so future feature consumers and HTTP adapters can map failures without raw infrastructure details (requirement 7.4, 9.4). 

const (
	ErrCodeDisabled          ErrorCode = "disabled"
	ErrCodeUnavailable       ErrorCode = "unavailable"
	ErrCodeDegraded          ErrorCode = "degraded"
	ErrCodeInvalidQuery      ErrorCode = "invalid_query"
	ErrCodeTooBroad          ErrorCode = "too_broad"
	ErrCodeUnsupportedFilter ErrorCode = "unsupported_filter"
	ErrCodeUnsafeEvidence    ErrorCode = "unsafe_evidence"
)
const (
	ErrCodeMethodNotAllowed        ErrorCode = "method_not_allowed"
	ErrCodeControlPlaneUnavailable ErrorCode = "control_plane_unavailable"
)

HTTP-layer error codes for the operator query adapter (not control-plane query classifications), kept as named constants so every response code is discoverable.

func (ErrorCode) IsKnown 

func (c ErrorCode) IsKnown() bool

IsKnown reports whether c is one of the documented error codes.

type Event 

type Event struct {
	ID             EventID        `json:"id"`
	SourceEventKey string         `json:"source_event_key,omitempty"`
	Category       Category       `json:"category"`
	OccurredAt     time.Time      `json:"occurred_at"`
	RecordedAt     time.Time      `json:"recorded_at"`
	Correlation    Correlation    `json:"correlation"`
	Scope          ScopeSnapshot  `json:"scope"`
	Source         SourceRef      `json:"source"`
	Visibility     Visibility     `json:"visibility"`
	EvidenceState  EvidenceState  `json:"evidence_state"`
	RedactionState RedactionState `json:"redaction_state"`
	Summary        string         `json:"summary,omitempty"`

	// Detail carries exactly one typed detail block matching Category. Use the
	// typed accessors (Auth, Session, …) or assign a concrete *XDetail pointer.
	// JSON wire shape remains the historical category-keyed object via custom
	// marshaling (Go API v2-compatible; see package doc).
	Detail EventDetail `json:"-"`
}

Event is one normalized lifecycle evidence record with stable identity, category, correlation, safe scope, availability state, redaction state, and exactly one typed detail block (requirement 1.7, 1.8, 3.5, 4.1).

func (Event) AccountingAuthority 

func (e Event) AccountingAuthority() *AccountingAuthorityDetail

AccountingAuthority returns the accounting-authority detail when Detail carries one.

func (Event) Attempt 

func (e Event) Attempt() *AttemptDetail

Attempt returns the attempt detail when Detail carries one.

func (Event) Audit 

func (e Event) Audit() *AuditDetail

Audit returns the audit detail when Detail carries one.

func (Event) Auth 

func (e Event) Auth() *AuthDetail

Auth returns the auth detail when Detail carries one.

func (Event) Lifecycle 

func (e Event) Lifecycle() *LifecycleDetail

Lifecycle returns the lifecycle detail when Detail carries one.

func (Event) MarshalJSON 

func (e Event) MarshalJSON() ([]byte, error)

MarshalJSON preserves the historical wire shape with category-keyed detail blocks.

func (Event) Policy 

func (e Event) Policy() *PolicyDetail

Policy returns the policy detail when Detail carries one.

func (Event) Session 

func (e Event) Session() *SessionDetail

Session returns the session detail when Detail carries one.

func (*Event) UnmarshalJSON 

func (e *Event) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the historical wire shape into Detail by construction.

func (Event) Usage 

func (e Event) Usage() *UsageDetail

Usage returns the usage detail when Detail carries one.

func (Event) Validate 

func (e Event) Validate() error

Validate performs structural invariant checks for an Event. It is the authoritative SDK-level guard used by core normalization and store adapters before persistence or query output (requirement 1.7, 3.5, 4.4, 4.5). It does not check source-specific detail semantics; those belong to the core normalizer.

Event-timestamp contract (see validateTimestamps): OccurredAt and RecordedAt are mandatory lifecycle anchors and zero values are rejected.

WindowStart/End/ResetAt on AccountingAuthorityDetail (and on the AccountingLimitStatusRow / AccountingDecisionRow query types) are intentionally NOT validated. A projector that emits an AccountingAuthorityDetail may not have access to the rule's window metadata (the rule snapshot is the authoritative source for window bounds). The zero time.Time value is the documented "no window" signal — see AccountingAuthorityDetail's godoc for the SDK consumer contract. Callers that need the actual window MUST query AccountingLimitStatus instead.

type EventDetail 

type EventDetail interface {
	// contains filtered or unexported methods
}

EventDetail is the sum-type marker carried by Event. Exactly one non-nil detail value must match Event.Category. The Go API uses this interface field instead of parallel nullable detail pointers (v2-compatible wire JSON is preserved via custom marshaling on Event).

type EventID 

type EventID struct {
	StoreID  string `json:"store_id"`
	Sequence int64  `json:"sequence"`
}

EventID is the stable identity assigned by a backing store. It is opaque to consumers and stable within one configured backing store (requirement 1.7, 2.7). The zero EventID is unassigned.

func (EventID) IsZero 

func (id EventID) IsZero() bool

IsZero reports whether the identity is unassigned.

type EventQuery 

type EventQuery struct {
	Common     CommonFilters `json:"common,omitzero"`
	Category   Category      `json:"category,omitempty"`
	Limit      int           `json:"limit,omitempty"`
	Cursor     Cursor        `json:"cursor,omitzero"`
	Visibility Visibility    `json:"visibility,omitempty"`
}

EventQuery requests bounded raw control-plane events (requirement 9.1).

type EvidenceQuery 

type EvidenceQuery struct {
	Common     CommonFilters `json:"common,omitzero"`
	Effect     string        `json:"effect,omitempty"`
	Category   Category      `json:"category,omitempty"`
	Limit      int           `json:"limit,omitempty"`
	Cursor     Cursor        `json:"cursor,omitzero"`
	Visibility Visibility    `json:"visibility,omitempty"`
}

EvidenceQuery requests bounded policy and audit evidence rows (requirement 2.4, 9.3).

type EvidenceState 

type EvidenceState string

EvidenceState reports the availability of an evidence record or field to a query consumer (requirement 1.8, 3.5, 3.6). Distinct from an empty string: unavailable, expired, redacted, and unsupported must be explicit rather than ambiguous empty values. 

const (
	EvidenceRecorded    EvidenceState = "recorded"
	EvidencePartial     EvidenceState = "partial"
	EvidenceUnavailable EvidenceState = "unavailable"
	EvidenceRedacted    EvidenceState = "redacted"
	EvidenceExpired     EvidenceState = "expired"
	EvidenceUnsupported EvidenceState = "unsupported"
)

func (EvidenceState) IsKnown 

func (s EvidenceState) IsKnown() bool

IsKnown reports whether s is one of the documented evidence states.

type ExecutableGenerationStatus 

type ExecutableGenerationStatus struct {
	ID               int64           `json:"id,omitempty"`
	Version          string          `json:"version,omitempty"`
	State            CapabilityState `json:"state"`
	Reason           ReasonCode      `json:"reason,omitempty"`
	EvidenceObjectID string          `json:"evidence_object_id,omitempty"`
	SourceID         string          `json:"source_id,omitempty"`
	LastUpdatedAt    time.Time       `json:"last_updated_at,omitzero"`
}

ExecutableGenerationStatus is the operator-visible executable generation readiness (requirements 9.6, 9.9, 12.1). It names evaluator object identity separately from source-fetch snapshot planes and terminal provider resolution.

type HostCapabilities 

type HostCapabilities struct {
	ProductionMetering, TrafficObservers, UsageObservers bool
	ProductionEvidenceSink                               bool
	ProductionMeteringQuerier                            bool
	SnapshotGenerationID, ExecutableGenerationID         int64
	SnapshotUsageVersion, ExecutableVersion              string
	ExecutableState                                      CapabilityState
	ExecutableEvidenceObjectID                           string
}

HostCapabilities reports production wiring and active-generation identity derived from a live host (not cached facade booleans).

type LeaseSetOccupancyCounts 

type LeaseSetOccupancyCounts struct {
	Active         int `json:"active"`
	Uncertain      int `json:"uncertain"`
	Expiring       int `json:"expiring"`
	Released       int `json:"released"`
	Failed         int `json:"failed"`
	PendingRelease int `json:"pending_release,omitempty"`
}

LeaseSetOccupancyCounts is a bounded projection of lease-set states (Phase 6).

type LifecycleDetail 

type LifecycleDetail struct {
	Stage  string `json:"stage"`
	Action string `json:"action,omitempty"`
}

LifecycleDetail is the typed detail block for CategoryLifecycle events that do not fit one of the domain-specific categories (for example operator-visible shutdown or degraded-state transitions).

type MoneyAmountInput 

type MoneyAmountInput struct {
	NanoUnits int64  `json:"nano_units,omitempty"`
	Currency  string `json:"currency,omitempty"`
	Present   bool   `json:"present"`
}

MoneyAmountInput is a currency-tagged amount with explicit presence (6.2).

type OperatorCostInput 

type OperatorCostInput struct {
	Money                MoneyAmountInput   `json:"money,omitzero"`
	BackendIngressTokens TokenQuantityInput `json:"backend_ingress_tokens,omitzero"`
	BackendEgressTokens  TokenQuantityInput `json:"backend_egress_tokens,omitzero"`
	ProviderReportedCost MoneyAmountInput   `json:"provider_reported_cost,omitzero"`
	RatingVersion        VersionRef         `json:"rating_version,omitzero"`
}

OperatorCostInput holds independently queryable operator cost facts (5.7).

type Page 

type Page[T any] struct {
	Items       []T                 `json:"items"`
	Next        Cursor              `json:"next,omitzero"`
	Unsupported []UnsupportedFilter `json:"unsupported,omitempty"`
	Visibility  Visibility          `json:"visibility"`
}

Page is a bounded result set with continuation, unsupported-filter reporting, and visibility metadata (requirement 2.6, 2.7, 2.8, 3.5).

type PageQueries 

type PageQueries interface {
	Sessions(ctx context.Context, q SessionQuery) (Page[SessionSummary], error)
	Attempts(ctx context.Context, q AttemptQuery) (Page[AttemptRow], error)
	Usage(ctx context.Context, q UsageQuery) (Page[UsageRow], error)
	UsageAggregate(ctx context.Context, q UsageAggregateQuery) (Page[UsageAggregate], error)
	PolicyAudit(ctx context.Context, q EvidenceQuery) (Page[PolicyAuditRow], error)
	Events(ctx context.Context, q EventQuery) (Page[Event], error)
}

PageQueries is the stable service contract for bounded cross-session read views (requirement 2.1-2.9, 9.1, 9.5). Query consumers do not need to know which diagnostic, observer, ledger, or store supplied a result.

Preconditions: ctx is non-nil; query bounds and cursor shape are validated by the implementation before store access. Postconditions: results contain only safe fields, report unsupported filters explicitly, and distinguish disabled capability, empty matches, unavailable evidence, and unsupported capability.

type PolicyAuditRow 

type PolicyAuditRow struct {
	Correlation    Correlation    `json:"correlation"`
	Category       Category       `json:"category"`
	Stage          string         `json:"stage,omitempty"`
	Outcome        string         `json:"outcome,omitempty"`
	Effect         string         `json:"effect,omitempty"`
	ReasonCode     string         `json:"reason_code,omitempty"`
	OccurredAt     time.Time      `json:"occurred_at,omitzero"`
	Visibility     Visibility     `json:"visibility,omitempty"`
	RedactionState RedactionState `json:"redaction_state"`
	EvidenceState  EvidenceState  `json:"evidence_state"`
}

PolicyAuditRow is one row of an EvidenceQuery result for policy or audit evidence (requirement 2.4, 9.3).

type PolicyDetail 

type PolicyDetail struct {
	Stage      string `json:"stage"`
	Outcome    string `json:"outcome"`
	Effect     string `json:"effect,omitempty"`
	ReasonCode string `json:"reason_code,omitempty"`
	ProviderID string `json:"provider_id,omitempty"`
}

PolicyDetail is the typed detail block for CategoryPolicy events (requirement 1.5, 9.3). It records safe decision stage, outcome, effect, and reason code without changing the original decision outcome and without exposing privileged content by default.

type ProtectedTrafficPosture 

type ProtectedTrafficPosture struct {
	State          CapabilityState `json:"state"`
	Reason         ReasonCode      `json:"reason,omitempty"`
	MayServeStrict bool            `json:"may_serve_strict"`
	LastUpdatedAt  time.Time       `json:"last_updated_at,omitzero"`
}

ProtectedTrafficPosture aggregates whether required protected traffic may be served (15.7).

func AggregateProtectedTrafficPosture 

func AggregateProtectedTrafficPosture(components []ReadinessComponentStatus, at time.Time) ProtectedTrafficPosture

AggregateProtectedTrafficPosture derives aggregate posture from independent component rows (15.7).

type Queries 

type Queries interface {
	StatusReader
	PageQueries
}

Queries composes status and bounded read views for consumers that expose the complete protected control-plane query surface.

type QueryClass 

type QueryClass string

QueryClass distinguishes historical metering, live authority, lease, and proprietary financial projections (requirement 14.5). 

const (
	QueryClassHistoricalMetering  QueryClass = "historical_metering"
	QueryClassLiveReservation     QueryClass = "live_reservation"
	QueryClassActiveLease         QueryClass = "active_lease"
	QueryClassRemainingAuthority  QueryClass = "remaining_authority"
	QueryClassFinancialProjection QueryClass = "financial_projection"
	QueryClassPendingTerminalWork QueryClass = "pending_terminal_work"
)

func (QueryClass) IsKnown 

func (c QueryClass) IsKnown() bool

IsKnown reports whether c is a documented query class.

type ReadinessComponentID 

type ReadinessComponentID string

ReadinessComponentID identifies an independently reported readiness/journal source (15.7). 

const (
	ReadinessComponentMeteringJournal       ReadinessComponentID = "metering_journal"
	ReadinessComponentBillingSpool          ReadinessComponentID = "billing_spool"
	ReadinessComponentControlPlane          ReadinessComponentID = "control_plane"
	ReadinessComponentUsageAuthority        ReadinessComponentID = "usage_authority"
	ReadinessComponentConcurrencyAuthority  ReadinessComponentID = "concurrency_authority"
	ReadinessComponentRequestCoordinator    ReadinessComponentID = "request_coordinator"
	ReadinessComponentAttemptCoordinator    ReadinessComponentID = "attempt_coordinator"
	ReadinessComponentUsageSnapshot         ReadinessComponentID = "usage_snapshot"
	ReadinessComponentConcurrencySnapshot   ReadinessComponentID = "concurrency_snapshot"
	ReadinessComponentRatingSnapshot        ReadinessComponentID = "rating_snapshot"
	ReadinessComponentExecutableGeneration  ReadinessComponentID = "executable_generation"
	ReadinessComponentSecretGuardQuarantine ReadinessComponentID = "secret_guard_quarantine"
	ReadinessComponentTerminalRecovery      ReadinessComponentID = "terminal_recovery"
)

type ReadinessComponentStatus 

type ReadinessComponentStatus struct {
	Component        ReadinessComponentID `json:"component"`
	State            CapabilityState      `json:"state"`
	Reason           ReasonCode           `json:"reason,omitempty"`
	EnforcementScope EnforcementScope     `json:"enforcement_scope,omitempty"`
	StoreBacking     string               `json:"store_backing,omitempty"`
	// ProviderIDs lists configured descriptor-bound provider or rater identities
	// for coordinator/rater components (requirement 3.7, 3.9).
	ProviderIDs []string `json:"provider_ids,omitempty"`
	// GenerationID/Version and EvidenceObjectID apply to executable_generation
	// rows (requirements 9.9, 12.1). They must not carry terminal unresolved
	// provider IDs or metadata-only catalog labels.
	GenerationID      int64     `json:"generation_id,omitempty"`
	GenerationVersion string    `json:"generation_version,omitempty"`
	EvidenceObjectID  string    `json:"evidence_object_id,omitempty"`
	LastUpdatedAt     time.Time `json:"last_updated_at,omitzero"`
}

ReadinessComponentStatus is one independent authority/journal readiness row (15.7).

type ReadinessReport 

type ReadinessReport struct {
	Components           []ReadinessComponentStatus `json:"components"`
	ExecutableGeneration ExecutableGenerationStatus `json:"executable_generation"`
	Posture              ProtectedTrafficPosture    `json:"posture"`
}

ReadinessReport is the full independent plus aggregate readiness snapshot (15.7).

type ReadinessReportReader 

type ReadinessReportReader interface {
	Report(ctx context.Context) (ReadinessReport, error)
}

ReadinessReportReader returns independent authority/journal readiness rows and aggregate protected-traffic posture (15.7).

type ReasonCode 

type ReasonCode string

ReasonCode is a bounded, safe operator-visible reason for a non-ready capability state (requirement 7.2, 7.3). It never carries raw infrastructure error text, DSNs, SQL, or driver details. 

const (
	ReasonNone                ReasonCode = ""
	ReasonDisabled            ReasonCode = "disabled"
	ReasonUnsupported         ReasonCode = "unsupported"
	ReasonStoreNotReady       ReasonCode = "store_not_ready"
	ReasonBackingUnavailable  ReasonCode = "backing_unavailable"
	ReasonRecordingFailure    ReasonCode = "recording_failure"
	ReasonQueryFailure        ReasonCode = "query_failure"
	ReasonRetentionFailure    ReasonCode = "retention_failure"
	ReasonRedactionFailure    ReasonCode = "redaction_failure"
	ReasonPendingTerminalWork ReasonCode = "pending_terminal_work"
)

func (ReasonCode) IsKnown 

func (r ReasonCode) IsKnown() bool

IsKnown reports whether r is one of the documented non-empty reason codes.

type RecordResult 

type RecordResult struct {
	ID         EventID       `json:"id"`
	Dedupe     DedupeOutcome `json:"dedupe"`
	RecordedAt time.Time     `json:"recorded_at"`
}

RecordResult is the stable outcome of appending an Event to a store (requirement 1.7). Dedupe reports whether the source event key was a duplicate of an already-recorded fact.

type Recorder 

type Recorder interface {
	Record(ctx context.Context, ev Event) (RecordResult, error)
}

Recorder is the stable service contract for appending control-plane evidence (requirement 1.7, 5.1, 5.4). Implementations apply recording policy and capability status without altering normal runtime outcomes.

Preconditions: ctx is non-nil; ev has passed Event.Validate or the implementation rejects it with ErrCodeUnsafeEvidence. Postconditions: the returned RecordResult carries the stable identity assigned by the backing store and the dedupe outcome for the source event key. Invariants: event IDs are stable within a configured backing store; post- output recording failures never request retry, failover, or replacement.

type RecordingPolicy 

type RecordingPolicy string

RecordingPolicy controls how the recorder treats failures per lifecycle category (requirement 5.4, 5.5, 7.6). 

const (
	RecordingDisabled        RecordingPolicy = "disabled"
	RecordingBestEffort      RecordingPolicy = "best_effort"
	RecordingRequiredPreWork RecordingPolicy = "required_pre_work"
)

func (RecordingPolicy) IsKnown 

func (p RecordingPolicy) IsKnown() bool

IsKnown reports whether p is one of the documented recording policies.

type RedactionState 

type RedactionState string

RedactionState reports how a record or field has been redacted for query visibility (requirement 4.6, 4.7, 6.2). 

const (
	RedactionNone       RedactionState = "none"
	RedactionSummarized RedactionState = "summarized"
	RedactionRedacted   RedactionState = "redacted"
	RedactionHashed     RedactionState = "hashed"
	RedactionPrivileged RedactionState = "privileged"
)

func (RedactionState) IsKnown 

func (r RedactionState) IsKnown() bool

IsKnown reports whether r is one of the documented redaction states.

type ReportCalculationType 

type ReportCalculationType string

ReportCalculationType names an explicit cross-plane calculation. Customer charge and operator cost must never merge without one of these types (14.7). 

const (
	ReportCalculationGrossMargin        ReportCalculationType = "gross_margin"
	ReportCalculationNetExposure        ReportCalculationType = "net_exposure"
	ReportCalculationCompressionSavings ReportCalculationType = "compression_token_savings"
	ReportCalculationRoutingOverhead    ReportCalculationType = "routing_overhead_total"
)

func (ReportCalculationType) IsKnown 

func (t ReportCalculationType) IsKnown() bool

IsKnown reports whether t is a documented report calculation type.

type ReportCompleteness 

type ReportCompleteness string

ReportCompleteness classifies whether reconstructed report inputs have the ingress facts required for a complete dual-plane view (task 3.5 / design migration note: historical rows without ingress are incomplete). 

const (
	ReportCompletenessComplete   ReportCompleteness = "complete"
	ReportCompletenessIncomplete ReportCompleteness = "incomplete"
)

type ReportLegacyProvenance 

type ReportLegacyProvenance string

ReportLegacyProvenance names how reconstructed inputs relate to legacy historical metering without silent reinterpretation. 

const (
	ReportLegacyProvenanceNone                     ReportLegacyProvenance = ""
	ReportLegacyProvenanceHistoricalWithoutIngress ReportLegacyProvenance = "historical_without_ingress"
)

type RoutingOverheadInput 

type RoutingOverheadInput struct {
	AttemptCount        TokenQuantityInput `json:"attempt_count,omitzero"`
	NonSurfacedAttempts TokenQuantityInput `json:"non_surfaced_attempts,omitzero"`
	OverheadCost        MoneyAmountInput   `json:"overhead_cost,omitzero"`
}

RoutingOverheadInput holds routing overhead separately from direct attempt costs (5.7).

type ScopeFilters 

type ScopeFilters struct {
	PrincipalID    scopeValue `json:"principal_id,omitzero"`
	CredentialID   scopeValue `json:"credential_id,omitzero"`
	TenantID       scopeValue `json:"tenant_id,omitzero"`
	OrganizationID scopeValue `json:"organization_id,omitzero"`
	WorkspaceID    scopeValue `json:"workspace_id,omitzero"`
	ProjectID      scopeValue `json:"project_id,omitzero"`
	DepartmentID   scopeValue `json:"department_id,omitzero"`
	CostCenterID   scopeValue `json:"cost_center_id,omitzero"`
}

ScopeFilters carries the safe, presence-aware principal/scope filter dimensions (requirement 2.5, 4.2, 4.3). Unknown values match records whose dimension is unknown; known-empty values match records whose dimension is known and intentionally empty.

type ScopeSnapshot 

type ScopeSnapshot struct {
	Principal      scope.PrincipalScopeView `json:"principal"`
	PrincipalID    scope.Value              `json:"principal_id"`
	CredentialID   scope.Value              `json:"credential_id"`
	TenantID       scope.Value              `json:"tenant_id"`
	OrganizationID scope.Value              `json:"organization_id"`
	WorkspaceID    scope.Value              `json:"workspace_id"`
	ProjectID      scope.Value              `json:"project_id"`
	DepartmentID   scope.Value              `json:"department_id"`
	CostCenterID   scope.Value              `json:"cost_center_id"`
}

ScopeSnapshot preserves safe principal/scope attribution with flattened, presence-aware filter dimensions (requirement 4.1, 4.2, 4.3, 9.1). The embedded Principal view is the authoritative safe snapshot; the flattened Value fields are the queryable dimensions and preserve unknown vs known-empty state.

type SessionAction 

type SessionAction string

SessionAction classifies the lifecycle action recorded for a session event. 

const (
	SessionActionCreated SessionAction = "created"
	SessionActionResumed SessionAction = "resumed"
	SessionActionUpdated SessionAction = "updated"
	SessionActionDenied  SessionAction = "denied"
)

func (SessionAction) IsKnown 

func (a SessionAction) IsKnown() bool

IsKnown reports whether a is one of the documented session actions.

type SessionDetail 

type SessionDetail struct {
	SessionID        string        `json:"session_id,omitempty"`
	ClientSessionRef string        `json:"client_session_ref,omitempty"`
	ALegID           string        `json:"a_leg_id,omitempty"`
	Action           SessionAction `json:"action"`
	Certainty        string        `json:"certainty,omitempty"`
}

SessionDetail is the typed detail block for CategorySession events (requirement 1.2). ClientSessionRef is an opaque, non-secret client correlation id, not a resume proof or token.

type SessionQuery 

type SessionQuery struct {
	Common     CommonFilters `json:"common,omitzero"`
	Limit      int           `json:"limit,omitempty"`
	Cursor     Cursor        `json:"cursor,omitzero"`
	Visibility Visibility    `json:"visibility,omitempty"`
}

SessionQuery requests bounded session summaries (requirement 2.1).

type SessionSummary 

type SessionSummary struct {
	SessionID     string        `json:"session_id"`
	LastActivity  time.Time     `json:"last_activity"`
	Scope         ScopeSnapshot `json:"scope"`
	UsageTotals   *UsageTotals  `json:"usage_totals,omitempty"`
	AttemptCount  int           `json:"attempt_count,omitempty"`
	EvidenceState EvidenceState `json:"evidence_state"`
}

SessionSummary is one row of a SessionQuery result (requirement 2.1).

type SourceRef 

type SourceRef struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

SourceRef identifies the originating diagnostic, observer, ledger, or store that supplied a record (requirement 3.5, 8.5). Consumers do not need to understand it to use the safe query contract (requirement 9.5).

type StatusReader 

type StatusReader interface {
	Status(ctx context.Context) (CapabilityStatus, error)
}

StatusReader is the stable service contract for reading the control-plane capability status (requirement 7.1, 7.4).

type TimeRange 

type TimeRange struct {
	From time.Time `json:"from,omitzero"`
	To   time.Time `json:"to,omitzero"`
}

TimeRange bounds a query by event time. Either bound may be omitted to express an open range; both bounds require a selective filter for broad event queries against durable stores (requirement 2.6, 7.4).

type TokenQuantityInput 

type TokenQuantityInput struct {
	Component string `json:"component,omitempty"`
	Unit      string `json:"unit,omitempty"`
	Value     int64  `json:"value,omitempty"`
	Present   bool   `json:"present"`
}

TokenQuantityInput is a safe quantity observation without raw content (requirements 4.7, 14.6, 17.5).

type UnsupportedFilter 

type UnsupportedFilter struct {
	Field  string `json:"field"`
	Reason string `json:"reason,omitempty"`
}

UnsupportedFilter names a requested filter that recorded evidence cannot apply, with a safe reason (requirement 2.5, 8.6, 9.4). Stores report unsupported filters explicitly rather than silently widening the query.

type UsageAggregate 

type UsageAggregate struct {
	Scope          ScopeSnapshot       `json:"scope,omitzero"`
	BackendID      string              `json:"backend_id,omitempty"`
	Model          string              `json:"model,omitempty"`
	Plane          UsagePlane          `json:"plane"`
	Perspective    UsagePerspective    `json:"perspective,omitempty"`
	Boundary       UsageBoundary       `json:"boundary,omitempty"`
	LifecycleScope UsageLifecycleScope `json:"lifecycle_scope,omitempty"`
	InputTokens    int64               `json:"input_tokens,omitempty"`
	OutputTokens   int64               `json:"output_tokens,omitempty"`
	TotalTokens    int64               `json:"total_tokens,omitempty"`
	CostNanoUnits  int64               `json:"cost_nano_units,omitempty"`
	WindowStart    time.Time           `json:"window_start,omitzero"`
	WindowEnd      time.Time           `json:"window_end,omitzero"`
	EvidenceState  EvidenceState       `json:"evidence_state"`
}

UsageAggregate is one row of a UsageAggregateQuery result (requirement 2.3, 6.4). Aggregate rows are logically distinct from detailed usage rows.

type UsageAggregateQuery 

type UsageAggregateQuery struct {
	Common     CommonFilters `json:"common,omitzero"`
	GroupBy    []string      `json:"group_by,omitempty"`
	Limit      int           `json:"limit,omitempty"`
	Cursor     Cursor        `json:"cursor,omitzero"`
	Visibility Visibility    `json:"visibility,omitempty"`
}

UsageAggregateQuery requests bounded usage aggregates grouped by requested dimensions (requirement 2.3, 6.4).

type UsageAvailability 

type UsageAvailability string

UsageAvailability distinguishes observed, accounting-authoritative, unavailable, and failed-accounting usage evidence (requirement 9.2). 

const (
	UsageAvailabilityObserved       UsageAvailability = "observed"
	UsageAvailabilityAccountingAuth UsageAvailability = "accounting_authoritative"
	UsageAvailabilityUnavailable    UsageAvailability = "unavailable"
	UsageAvailabilityFailed         UsageAvailability = "failed_accounting"
)

func (UsageAvailability) IsKnown 

func (a UsageAvailability) IsKnown() bool

IsKnown reports whether a is one of the documented usage availability values.

type UsageBoundary 

type UsageBoundary string

UsageBoundary is a legal metering checkpoint on the proxy data path. 

const (
	UsageBoundaryFrontendIngress UsageBoundary = "frontend_ingress"
	UsageBoundaryBackendIngress  UsageBoundary = "backend_ingress"
	UsageBoundaryBackendEgress   UsageBoundary = "backend_egress"
	UsageBoundaryFrontendEgress  UsageBoundary = "frontend_egress"
)

type UsageDetail 

type UsageDetail struct {
	// Legacy compatibility projections (requirement 14.2, 17.4). Plane and
	// Availability remain for existing consumers; dual-plane fields below are
	// authoritative when present.
	Plane        UsagePlane        `json:"plane"`
	Availability UsageAvailability `json:"availability"`
	// Dual-plane identity (requirements 1.6, 14.1). Perspective, provenance,
	// and boundary are independent dimensions.
	Perspective         UsagePerspective    `json:"perspective,omitempty"`
	Boundary            UsageBoundary       `json:"boundary,omitempty"`
	LifecycleScope      UsageLifecycleScope `json:"lifecycle_scope,omitempty"`
	Provenance          UsageProvenance     `json:"provenance,omitempty"`
	FactKind            UsageFactKind       `json:"fact_kind,omitempty"`
	Surfaced            UsageSurfaced       `json:"surfaced,omitempty"`
	PolicyVersion       VersionRef          `json:"policy_version,omitzero"`
	RatingVersion       VersionRef          `json:"rating_version,omitzero"`
	InputTokens         int                 `json:"input_tokens,omitempty"`
	OutputTokens        int                 `json:"output_tokens,omitempty"`
	CacheReadTokens     int                 `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens    int                 `json:"cache_write_tokens,omitempty"`
	ReasoningTokens     int                 `json:"reasoning_tokens,omitempty"`
	TotalTokens         int                 `json:"total_tokens,omitempty"`
	TokenPresence       UsageTokenPresence  `json:"token_presence,omitzero"`
	CostNanoUnits       int64               `json:"cost_nano_units,omitempty"`
	CostPresent         bool                `json:"cost_present"`
	Currency            string              `json:"currency,omitempty"`
	AccountingAuthority string              `json:"accounting_authority,omitempty"`
	CostSource          string              `json:"cost_source,omitempty"`
}

UsageDetail is the typed detail block for CategoryUsage events (requirement 1.4, 9.2). Raw usage JSON from upstream sources is never surfaced here; only typed safe token/cost/accounting fields and explicit availability state are carried.

type UsageFactKind 

type UsageFactKind string

UsageFactKind classifies how a usage fact participates in aggregation. 

const (
	UsageFactKindDelta                    UsageFactKind = "delta"
	UsageFactKindCumulative               UsageFactKind = "cumulative"
	UsageFactKindCorrection               UsageFactKind = "correction"
	UsageFactKindAuthoritativeReplacement UsageFactKind = "authoritative_replacement"
	UsageFactKindReservationEstimate      UsageFactKind = "reservation_estimate"
	UsageFactKindUnavailable              UsageFactKind = "unavailable"
)

type UsageLifecycleScope 

type UsageLifecycleScope string

UsageLifecycleScope identifies the lifecycle object usage evidence applies to. 

const (
	UsageLifecycleLogicalRequest   UsageLifecycleScope = "logical_request"
	UsageLifecycleBackendAttempt   UsageLifecycleScope = "backend_attempt"
	UsageLifecycleAuxiliaryRequest UsageLifecycleScope = "auxiliary_request"
)

type UsagePerspective 

type UsagePerspective string

UsagePerspective identifies whose economics usage evidence represents. 

const (
	UsagePerspectiveCustomer UsagePerspective = "customer"
	UsagePerspectiveOperator UsagePerspective = "operator"
	UsagePerspectiveNone     UsagePerspective = "none"
)

type UsagePlane 

type UsagePlane string

UsagePlane identifies whether usage evidence is observed from the provider stream or authoritative from the accounting ledger (requirement 9.2). 

const (
	UsagePlaneObserved   UsagePlane = "observed"
	UsagePlaneAccounting UsagePlane = "accounting"
)

func (UsagePlane) IsKnown 

func (p UsagePlane) IsKnown() bool

IsKnown reports whether p is one of the documented usage planes.

type UsageProvenance 

type UsageProvenance string

UsageProvenance is evidence provenance for usage facts, independent of economic perspective and metering boundary (requirement 14.1). 

const (
	UsageProvenanceAuthoritative UsageProvenance = "authoritative"
	UsageProvenanceDelegated     UsageProvenance = "delegated"
	UsageProvenanceEstimated     UsageProvenance = "estimated"
	UsageProvenanceAdvisory      UsageProvenance = "advisory"
	UsageProvenanceUnavailable   UsageProvenance = "unavailable"
)

type UsageQuery 

type UsageQuery struct {
	Common         CommonFilters       `json:"common,omitzero"`
	Plane          string              `json:"plane,omitempty"`
	Availability   string              `json:"availability,omitempty"`
	Perspective    UsagePerspective    `json:"perspective,omitempty"`
	Boundary       UsageBoundary       `json:"boundary,omitempty"`
	LifecycleScope UsageLifecycleScope `json:"lifecycle_scope,omitempty"`
	RuleID         string              `json:"rule_id,omitempty"`
	Class          QueryClass          `json:"class,omitempty"`
	Limit          int                 `json:"limit,omitempty"`
	Cursor         Cursor              `json:"cursor,omitzero"`
	Visibility     Visibility          `json:"visibility,omitempty"`
}

UsageQuery requests bounded usage rows (requirement 2.3, 9.2).

type UsageRow 

type UsageRow struct {
	Correlation      Correlation         `json:"correlation"`
	Plane            UsagePlane          `json:"plane"`
	Availability     UsageAvailability   `json:"availability"`
	Perspective      UsagePerspective    `json:"perspective,omitempty"`
	Boundary         UsageBoundary       `json:"boundary,omitempty"`
	LifecycleScope   UsageLifecycleScope `json:"lifecycle_scope,omitempty"`
	Provenance       UsageProvenance     `json:"provenance,omitempty"`
	FactKind         UsageFactKind       `json:"fact_kind,omitempty"`
	Surfaced         UsageSurfaced       `json:"surfaced,omitempty"`
	PolicyVersion    VersionRef          `json:"policy_version,omitzero"`
	RatingVersion    VersionRef          `json:"rating_version,omitzero"`
	InputTokens      int                 `json:"input_tokens,omitempty"`
	OutputTokens     int                 `json:"output_tokens,omitempty"`
	CacheReadTokens  int                 `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens int                 `json:"cache_write_tokens,omitempty"`
	ReasoningTokens  int                 `json:"reasoning_tokens,omitempty"`
	TotalTokens      int                 `json:"total_tokens,omitempty"`
	TokenPresence    UsageTokenPresence  `json:"token_presence,omitzero"`
	CostNanoUnits    int64               `json:"cost_nano_units,omitempty"`
	CostPresent      bool                `json:"cost_present"`
	Currency         string              `json:"currency,omitempty"`
	EvidenceState    EvidenceState       `json:"evidence_state"`
	RedactionState   RedactionState      `json:"redaction_state"`
}

UsageRow is one row of a UsageQuery result (requirement 2.3, 9.2).

type UsageSurfaced 

type UsageSurfaced string

UsageSurfaced records whether attempt output reached the client. 

const (
	UsageSurfacedYes     UsageSurfaced = "yes"
	UsageSurfacedNo      UsageSurfaced = "no"
	UsageSurfacedUnknown UsageSurfaced = "unknown"
)

type UsageTokenPresence 

type UsageTokenPresence struct {
	InputTokens      bool `json:"input_tokens"`
	OutputTokens     bool `json:"output_tokens"`
	CacheReadTokens  bool `json:"cache_read_tokens"`
	CacheWriteTokens bool `json:"cache_write_tokens"`
	ReasoningTokens  bool `json:"reasoning_tokens"`
	TotalTokens      bool `json:"total_tokens"`
}

UsageTokenPresence records which token counters were explicitly present on projected usage evidence (requirement 2.9). False means omitted, not zero.

func (UsageTokenPresence) Any 

func (p UsageTokenPresence) Any() bool

Any reports whether at least one token counter was explicitly present.

type UsageTotals 

type UsageTotals struct {
	InputTokens   int   `json:"input_tokens,omitempty"`
	OutputTokens  int   `json:"output_tokens,omitempty"`
	TotalTokens   int   `json:"total_tokens,omitempty"`
	CostNanoUnits int64 `json:"cost_nano_units,omitempty"`
}

UsageTotals carries safe aggregate usage totals for a session summary (requirement 2.1). Aggregate values are distinct from detailed usage rows (requirement 6.4).

type VersionRef 

type VersionRef struct {
	ID          string    `json:"id,omitempty"`
	Version     string    `json:"version,omitempty"`
	EffectiveAt time.Time `json:"effective_at,omitzero"`
	FetchedAt   time.Time `json:"fetched_at,omitzero"`
}

VersionRef is an immutable snapshot identity for policy or rating versions carried on control-plane evidence (requirements 1.6, 14.3, 17.4). It mirrors economics.VersionRef without importing economics so the SDK import surface stays minimal.

type Visibility 

type Visibility string

Visibility controls whether privileged detail may leave the control-plane boundary for a record or query result (requirement 4.6, 6.5). 

const (
	VisibilityDefault    Visibility = "default"
	VisibilityPrivileged Visibility = "privileged"
)

func (Visibility) IsKnown 

func (v Visibility) IsKnown() bool

IsKnown reports whether v is one of the documented visibility values.

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.