catalog

type AcquisitionReport struct {
	// Enabled reports whether this instance observes providers itself.
	Enabled bool `json:"enabled"`
	// Health is the state of the last acquisition run.
	Health string `json:"health"`
	// AgeSeconds is the age of the last acquisition success.
	AgeSeconds int64 `json:"age_seconds"`
	// Freshness grades that age.
	Freshness string `json:"freshness"`
}

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

type AdapterAvailability struct {
	ProviderID    catalogs.ProviderID
	Registered    bool
	Operations    []catalogs.ProviderOperation
	EndpointTypes []catalogs.EndpointType
}

type AdminStatus struct {
	// Runtime is the state of the connected Starmap runtime.
	Runtime RuntimeReport `json:"runtime"`
	// RouteValidation reports candidate, accepted, rejected, and pending as
	// distinct values.
	RouteValidation RouteValidation `json:"route_validation"`
	// SourceHealth is what this instance observed while it read its source.
	SourceHealth string `json:"source_health"`
	// UpstreamHealth is the health the upstream reported about itself.
	UpstreamHealth string `json:"upstream_health"`
	// Acquisition is the state of provider acquisition on this instance.
	Acquisition AcquisitionReport `json:"acquisition"`
	// Freshness grades the three independent ages.
	Freshness FreshnessReport `json:"freshness"`
	// Provenance carries the effective and the upstream provenance.
	Provenance Provenance `json:"provenance"`
	// Catalog is how much the accepted head holds.
	Catalog Counts `json:"catalog"`
	// Snapshot is the manifest detail of the accepted head: its validation
	// result, its degradation reasons, and the sources that fed it.
	Snapshot SnapshotMetadata `json:"snapshot,omitzero"`
	// NextUpdateAt is when this instance next reads its source.
	NextUpdateAt time.Time `json:"next_update_at,omitzero"`
	// Operations is the recent catalog work, newest first.
	Operations []Operation `json:"operations"`
}

type Candidate struct {
	// State is the effective generation the connected runtime published.
	State starmap.CatalogState

	// Epoch is the lease epoch the candidate was produced under. Zero means
	// the deployment shares no lease, and every candidate then passes the
	// fence.
	Epoch uint64
}

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

type Counts struct {
	// Providers is the number of providers the accepted head carries.
	Providers int `json:"providers"`
	// Models is the number of routable models the accepted head carries.
	Models int `json:"models"`
}

type DeploymentLookup func(name string) (string, bool)

type Diff struct {
	Available         bool      `json:"available"`
	Reason            string    `json:"reason,omitempty"`
	FromGenerationID  string    `json:"from_generation_id,omitempty"`
	ToGenerationID    string    `json:"to_generation_id,omitempty"`
	FromGeneratedAt   time.Time `json:"from_generated_at,omitzero"`
	ToGeneratedAt     time.Time `json:"to_generated_at,omitzero"`
	SemanticallyEqual bool      `json:"semantically_equal"`

	ModelsAdded      []string         `json:"models_added,omitempty"`
	ModelsRemoved    []string         `json:"models_removed,omitempty"`
	OfferingsAdded   []OfferingChange `json:"offerings_added,omitempty"`
	OfferingsRemoved []OfferingChange `json:"offerings_removed,omitempty"`
	PriceChanges     []PriceChange    `json:"price_changes,omitempty"`
}

type FreshnessReport struct {
	// Catalog grades the age of the served generation.
	Catalog string `json:"catalog"`
	// CatalogAgeSeconds is that age.
	CatalogAgeSeconds int64 `json:"catalog_age_seconds"`
	// Channel grades the age of the propagated origin publication.
	Channel string `json:"channel"`
	// ChannelAgeSeconds is that age.
	ChannelAgeSeconds int64 `json:"channel_age_seconds"`
	// SourceCheck grades the age of the last upstream check.
	SourceCheck string `json:"source_check"`
	// SourceCheckAgeSeconds is that age.
	SourceCheckAgeSeconds int64 `json:"source_check_age_seconds"`
}

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

type GenerationIndexEntry struct {
	GenerationID     string    `json:"generation_id"`
	GeneratedAt      time.Time `json:"generated_at"`
	PayloadChecksum  string    `json:"payload_checksum"`
	SemanticChecksum string    `json:"semantic_checksum,omitempty"`
}

type GenerationRef struct {
	// GenerationID identifies the generation.
	GenerationID string `json:"generation_id,omitempty"`
	// PayloadChecksum is the digest of the generation payload.
	PayloadChecksum string `json:"payload_checksum,omitempty"`
	// GeneratedAt is when the generation was built.
	GeneratedAt time.Time `json:"generated_at,omitzero"`
	// LeaseEpoch is the runtime lease epoch the generation was produced
	// under. Zero means the deployment shares no lease.
	LeaseEpoch uint64 `json:"lease_epoch,omitempty"`
}

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

type Hop struct {
	// Identity is the safe identity of the hop.
	Identity string `json:"identity,omitempty"`
	// Health is the health that hop reported about itself.
	Health string `json:"health"`
	// PublishedAt is when that hop published.
	PublishedAt time.Time `json:"published_at,omitzero"`
	// ObservedAt is when this instance observed the hop.
	ObservedAt time.Time `json:"observed_at,omitzero"`
}

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

type OfferingChange struct {
	Provider        string `json:"provider"`
	ProviderModelID string `json:"provider_model_id"`
	DefinitionID    string `json:"definition_id"`
}

type OfferingRoutability struct {
	ProviderID      catalogs.ProviderID
	ProviderModelID catalogs.ProviderModelID
	Routable        bool
	Exclusion       RouteExclusion
}

type Operation struct {
	// ID identifies the operation on the admin surface.
	ID string `json:"id"`
	// Kind names the work.
	Kind OperationKind `json:"kind"`
	// State is where the operation stands.
	State OperationState `json:"state"`
	// Reason is the safe cause of a closed operation.
	Reason OperationReason `json:"reason,omitempty"`
	// AcceptedAt is when the registry took the request.
	AcceptedAt time.Time `json:"accepted_at"`
	// StartedAt is when the work began.
	StartedAt time.Time `json:"started_at,omitzero"`
	// CompletedAt is when the work closed.
	CompletedAt time.Time `json:"completed_at,omitzero"`
	// GenerationID is the generation the work produced, when it produced one.
	GenerationID string `json:"generation_id,omitempty"`
	// Changed reports whether the work moved the accepted head.
	Changed bool `json:"changed"`
}

type OperationKind string

type OperationOption func(*Operations)

type OperationReason string

type OperationResult struct {
	// GenerationID is the generation the work produced.
	GenerationID string
	// Changed reports whether the work moved the accepted head.
	Changed bool
}

type OperationState string

type OperationWork func(context.Context) (OperationResult, error)

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

type PriceChange struct {
	Provider        string  `json:"provider"`
	ProviderModelID string  `json:"provider_model_id"`
	DefinitionID    string  `json:"definition_id"`
	Field           string  `json:"field"`
	PreviousPer1M   float64 `json:"previous_per_1m"`
	CurrentPer1M    float64 `json:"current_per_1m"`
}

type Provenance struct {
	// Effective is the accepted head this gateway routes on. It stays where
	// it stands when a newer candidate fails route validation.
	Effective GenerationRef `json:"effective,omitzero"`
	// Upstream is the publication the source reported.
	Upstream UpstreamProvenance `json:"upstream"`
}

type RefreshReport struct {
	PreviousGenerationID string    `json:"previous_generation_id"`
	GenerationID         string    `json:"generation_id"`
	GeneratedAt          time.Time `json:"generated_at"`
	Changed              bool      `json:"changed"`
}

type Rejection struct {
	// Generation names the refused candidate.
	Generation GenerationRef `json:"generation,omitzero"`
	// Reason is the safe cause. It never carries a failure text.
	Reason OperationReason `json:"reason,omitempty"`
	// At is when the refusal happened.
	At time.Time `json:"at,omitzero"`
}

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

type Route struct {
	CatalogGenerationID string
	DefinitionID        catalogs.ModelDefinitionID
	ProviderID          catalogs.ProviderID
	ProviderModelID     catalogs.ProviderModelID
	Operations          []catalogs.ProviderOperation
	Endpoints           []catalogs.ProviderOfferingEndpoint
	PromptCache         *bool
}

type RouteExclusion string

type RouteValidation struct {
	// State is where the newest candidate stands.
	State RouteValidationState `json:"state"`
	// Candidate is the newest generation the connected runtime published.
	Candidate GenerationRef `json:"candidate,omitzero"`
	// Accepted is the generation that routes every request now.
	Accepted GenerationRef `json:"accepted,omitzero"`
	// Rejected is the newest candidate this instance refused.
	Rejected Rejection `json:"rejected,omitzero"`
}

type RouteValidationState string

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

type RuntimeReport struct {
	// Usable reports whether the runtime serves a catalog now.
	Usable bool `json:"usable"`
	// SourceKind names the selected source. It reads from the closed source
	// vocabulary.
	SourceKind string `json:"source_kind"`
	// Fallback reports whether the runtime serves the embedded catalog
	// because no upstream generation is active.
	Fallback bool `json:"fallback"`
	// FallbackReason names why the runtime fell back. It reads from the
	// closed fallback vocabulary.
	FallbackReason string `json:"fallback_reason,omitempty"`
	// Lease reports the runtime lease state.
	Lease string `json:"lease,omitempty"`
	// LastRunID identifies the last refresh run.
	LastRunID string `json:"last_run_id,omitempty"`
	// StartedAt is when the runtime opened.
	StartedAt time.Time `json:"started_at,omitzero"`
	// ObservedAt is when the runtime built this report.
	ObservedAt time.Time `json:"observed_at,omitzero"`
}

type Settings struct {
	// Source selects the catalog source kind.
	Source string

	// SourceURL is the safe source endpoint or the file identity.
	SourceURL string

	// SourceAPIKey authenticates this instance to an upstream deployment.
	SourceAPIKey string

	// SourceRepository names the signed publication repository.
	SourceRepository string

	// SourceChannel names the publication channel.
	SourceChannel string

	// SourceSignerWorkflow names the workflow that signed a publication.
	SourceSignerWorkflow string

	// SourceToken reads a GitHub release.
	SourceToken string

	// SourcePollInterval bounds how often the source is asked.
	SourcePollInterval time.Duration

	// SourceStartupPolicy decides what startup does without a source answer.
	SourceStartupPolicy string

	// SourceMaxAge is the oldest publication this instance accepts.
	SourceMaxAge time.Duration

	// SourceMaxHops bounds the publication chain.
	SourceMaxHops int

	// AcquisitionEnabled decides whether this instance observes providers.
	AcquisitionEnabled bool

	// AcquisitionInterval is the period between provider observations.
	AcquisitionInterval time.Duration

	// WorkspacePath is the local catalog workspace directory. It holds the
	// catalog files an operator supplies and nothing this process owns.
	WorkspacePath string

	// StateDirectory is where this process keeps the state the connected
	// runtime retains: the layer store, the instance identity seed, and the
	// source discovery record. It belongs to one process on one machine.
	StateDirectory string

	// ListenAddress is the host and port this gateway serves. It joins the
	// identity seed and the host name in the instance identity, so two
	// processes on one host hold two identities and the runtime lease fences
	// one holder.
	ListenAddress string

	// StartupSpread spreads the first source read across a fleet.
	StartupSpread time.Duration

	// TransferIdleTimeout ends a transfer that stops making progress.
	TransferIdleTimeout time.Duration

	// TransferMaxDuration bounds one complete transfer.
	TransferMaxDuration time.Duration

	// RefreshTimeout is an added cap on one refresh run.
	RefreshTimeout time.Duration
}

type SnapshotMetadata struct {
	GenerationID         string    `json:"generation_id"`
	GeneratedAt          time.Time `json:"generated_at"`
	AgeSeconds           int64     `json:"age_seconds"`
	CatalogSequence      uint64    `json:"catalog_sequence"`
	AvailabilityRevision uint64    `json:"availability_revision"`
	PayloadChecksum      string    `json:"payload_checksum"`

	ManifestAvailable         bool   `json:"manifest_available"`
	ManifestUnavailableReason string `json:"manifest_unavailable_reason,omitempty"`

	SchemaVersion      uint64              `json:"schema_version,omitempty"`
	PayloadSizeBytes   int64               `json:"payload_size_bytes,omitempty"`
	Completeness       string              `json:"completeness,omitempty"`
	Degraded           bool                `json:"degraded"`
	DegradationReasons []string            `json:"degradation_reasons,omitempty"`
	Validation         ValidationSummary   `json:"validation,omitzero"`
	SourceObservations []SourceObservation `json:"source_observations,omitempty"`
	SyncRunID          string              `json:"sync_run_id,omitempty"`
}

type SnapshotSource interface {
	Current() *RoutableSnapshot
}

type Source interface {
	CurrentCatalogState() starmap.CatalogState
}

type SourceObservation struct {
	Source       string    `json:"source"`
	ObservedAt   time.Time `json:"observed_at"`
	Completeness string    `json:"completeness"`
	Status       string    `json:"status"`
}

type Summary struct {
	// GenerationID identifies the served catalog generation.
	GenerationID string `json:"generation_id"`
	// GeneratedAt is when the served generation was built.
	GeneratedAt time.Time `json:"generated_at,omitzero"`
	// AgeSeconds is the age of the served generation.
	AgeSeconds int64 `json:"age_seconds"`
	// Usable reports whether the gateway routes on a catalog now.
	Usable bool `json:"usable"`
	// Freshness grades the age of the served generation.
	Freshness string `json:"freshness"`
	// SourceKind names the selected source from the closed vocabulary.
	SourceKind string `json:"source_kind"`
	// Fallback reports whether the gateway serves the embedded baseline.
	Fallback bool `json:"fallback"`
	// Providers is how many providers the served catalog carries.
	Providers int `json:"providers"`
	// Models is how many routable models the served catalog carries.
	Models int `json:"models"`
	// NextUpdateAt is when this instance next reads its source.
	NextUpdateAt time.Time `json:"next_update_at,omitzero"`
}

type UpstreamProvenance struct {
	// SourceIdentity is the safe identity of the selected source.
	SourceIdentity string `json:"source_identity,omitempty"`
	// SourceKind names the selected source.
	SourceKind string `json:"source_kind"`
	// ChannelUpdatedAt is the origin publication time the chain propagated.
	ChannelUpdatedAt time.Time `json:"channel_updated_at,omitzero"`
	// Chain is the sanitized publication chain, nearest hop first.
	Chain []Hop `json:"chain,omitempty"`
}

type ValidationSummary struct {
	Status       string    `json:"status"`
	ErrorCount   int       `json:"error_count"`
	WarningCount int       `json:"warning_count"`
	ValidatedAt  time.Time `json:"validated_at"`
}