providerstate

package

v1.0.3 Latest Latest Go to latest Published: Aug 11, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/agentstation/starport

Links

Open Source Insights

Documentation ¶

Overview ¶

Package providerstate projects safe provider runtime state from its concept owners. It does not own adapter activation, credential resolution, or offering circuit transitions.

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	// ErrCatalogRequired reports an incomplete catalog-state projection.
	ErrCatalogRequired = errors.New("provider-state catalog is required")
	// ErrAdapterProjectionIncomplete reports missing or duplicate adapter state.
	ErrAdapterProjectionIncomplete = errors.New("provider adapter projection is incomplete")
)

Functions ¶

This section is empty.

Types ¶

type AdapterObservation ¶

type AdapterObservation struct {
	ProviderID catalogs.ProviderID
	State      AdapterState
	Reason     ReasonCode
}

AdapterObservation is the activation owner's safe projection.

type AdapterState ¶

type AdapterState string

AdapterState identifies compiled support for one catalog provider.

const (
	AdapterReady                     AdapterState = "ready"
	AdapterUnsupportedTransport      AdapterState = "unsupported_transport"
	AdapterUnsupportedAuthentication AdapterState = "unsupported_authentication"
	AdapterNoOfferings               AdapterState = "no_offerings"
)

Adapter support states are a closed projection of compiled primitives and catalog offerings.

type AdapterStatus ¶

type AdapterStatus struct {
	State  AdapterState `json:"state"`
	Reason ReasonCode   `json:"reason,omitempty"`
}

AdapterStatus is safe compiled support state.

type CredentialGeneration ¶

type CredentialGeneration struct {
	CatalogGenerationID string
	Observations        []CredentialObservation
}

CredentialGeneration replaces the complete operator credential projection for one exact catalog generation.

type CredentialObservation ¶

type CredentialObservation struct {
	ProviderID      catalogs.ProviderID
	State           CredentialState
	Reason          ReasonCode
	Usable          bool
	MaterialVersion string
}

CredentialObservation is the reconciler's safe lifecycle projection. MaterialVersion is opaque internal evidence and never enters Snapshot.

type CredentialPublisher ¶

type CredentialPublisher interface {
	PublishCredentials(CredentialGeneration)
}

CredentialPublisher accepts complete reconciler projections.

type CredentialState ¶

type CredentialState string

CredentialState identifies operator inference credential state.

const (
	CredentialReady         CredentialState = "ready"
	CredentialNotConfigured CredentialState = "not_configured"
	CredentialDenied        CredentialState = "denied"
	CredentialInvalid       CredentialState = "invalid"
	CredentialUnavailable   CredentialState = "unavailable"
	CredentialRefreshing    CredentialState = "refreshing"
)

Operator credential states are a closed lifecycle projection.

type CredentialStatus ¶

type CredentialStatus struct {
	State     CredentialState `json:"state"`
	Reason    ReasonCode      `json:"reason,omitempty"`
	Usable    bool            `json:"usable"`
	UpdatedAt time.Time       `json:"updated_at,omitempty"`
}

CredentialStatus is safe operator credential state.

type OfferingStatus ¶

type OfferingStatus struct {
	ProviderModelID catalogs.ProviderModelID `json:"provider_model_id"`
	State           availability.State       `json:"state"`
	Reason          ReasonCode               `json:"reason,omitempty"`
}

OfferingStatus is the projected state of one exact opaque provider model ID.

type ProviderStatus ¶

type ProviderStatus struct {
	ProviderID         catalogs.ProviderID `json:"provider_id"`
	Adapter            AdapterStatus       `json:"adapter"`
	OperatorCredential CredentialStatus    `json:"operator_credential"`
	Offerings          []OfferingStatus    `json:"offerings"`
}

ProviderStatus separates adapter, operator credential, and offering state.

type ReasonCode ¶

type ReasonCode string

ReasonCode is a stable, secret-free operator reason.

const (
	ReasonNone                      ReasonCode = ""
	ReasonTransportUnsupported      ReasonCode = "transport_unsupported"
	ReasonAuthenticationUnsupported ReasonCode = "authentication_unsupported"
	ReasonNoOfferings               ReasonCode = "no_offerings"
	ReasonOperatorNotRequired       ReasonCode = "credential_not_required"
	ReasonOperatorNotConfigured     ReasonCode = "credential_not_configured"
	ReasonOperatorSourceDenied      ReasonCode = "credential_source_denied"
	ReasonOperatorSourceInvalid     ReasonCode = "credential_source_invalid"
	ReasonOperatorSourceUnavailable ReasonCode = "credential_source_unavailable"
	ReasonOperatorRefreshRetained   ReasonCode = "credential_refresh_failed_retained"
	ReasonOperatorRefreshing        ReasonCode = "credential_refreshing"
	ReasonAuthenticationFailed      ReasonCode = "authentication_failed"
	ReasonPermissionDenied          ReasonCode = "permission_denied"
	ReasonQuotaExceeded             ReasonCode = "quota_exceeded"
	ReasonBillingUnavailable        ReasonCode = "billing_unavailable"
	ReasonCatalogUnavailable        ReasonCode = "catalog_unavailable"
	ReasonCatalogRetired            ReasonCode = "catalog_retired"
	ReasonOfferingNotFound          ReasonCode = "offering_not_found"
	ReasonRateLimited               ReasonCode = "rate_limited"
	ReasonProviderUnavailable       ReasonCode = "provider_unavailable"
	ReasonProviderTimeout           ReasonCode = "provider_timeout"
)

Provider-state reason codes are stable and contain no provider diagnostics or credential material.

type Snapshot ¶

type Snapshot struct {
	Revision            uint64           `json:"revision"`
	CatalogGenerationID string           `json:"catalog_generation_id"`
	Providers           []ProviderStatus `json:"providers"`
}

Snapshot is one caller-owned immutable provider-state generation.

type Store ¶

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

Store retains safe projections and exact opaque versions needed to reject stale inference outcomes.

func New ¶

func New() *Store

New creates an empty provider-state projection.

func (*Store) OperatorMaterialReady ¶

func (s *Store) OperatorMaterialReady(providerID string, materialVersion string) bool

OperatorMaterialReady reports whether an exact resolved material version is eligible for a new inference attempt. A version not yet observed by the projection is admitted so an atomic runtime publication cannot be blocked by a lagging status projection.

func (*Store) PublishAvailability ¶

func (s *Store) PublishAvailability(snapshot availability.Snapshot) error

PublishAvailability projects the availability owner's complete snapshot.

func (*Store) PublishCatalog ¶

func (s *Store) PublishCatalog(
	generationID string,
	catalog *catalogs.Catalog,
	observations []AdapterObservation,
) error

PublishCatalog replaces the complete catalog and adapter projection.

func (*Store) PublishCredentials ¶

func (s *Store) PublishCredentials(generation CredentialGeneration)

PublishCredentials replaces the reconciler projection. A successful read of the same material version does not erase an inference-proved failure.

func (*Store) PublishOutcome ¶

func (s *Store) PublishOutcome(outcome execution.AttemptOutcome)

PublishOutcome applies only explicitly scoped operator credential evidence.

func (*Store) Snapshot ¶

func (s *Store) Snapshot() Snapshot

Snapshot returns a caller-owned, deterministically ordered projection.

Source Files ¶

View all Source files

store.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL