Help us shape the future of Go! Take the 2026 Go Developer Survey

catalog

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: AGPL-3.0 Imports: 52 Imported by: 0

Documentation

Overview

Package catalog owns Starport's immutable view of Starmap facts and the separately versioned runtime availability used to derive routable models.

Index

Constants

View Source 
const (
	PolicyMatch    = "match"
	PolicyMismatch = "policy_mismatch"
)

Policy states that the catalog status reports. An empty state means that this replica has no shared policy to compare.

View Source 
const BaselineRecoveryDirectoryName = starmap.BaselineRecoveryDirectoryName

BaselineRecoveryDirectoryName identifies the journal directory owned by Starmap.

View Source 
const DefaultRetained = 64

DefaultRetained is how many closed operations the registry keeps. An operator reads the recent history of catalog work, and an unbounded history would grow with every refresh a scheduler starts.

View Source 
const (
	// PromotionRequestLifetime bounds a pending request. A request that no
	// leader settles expires, and the same operation ID can write it again.
	PromotionRequestLifetime = 10 * time.Minute
)
View Source 
const SpeechCharacterUnit = "characters"

SpeechCharacterUnit identifies the input count in a character-priced speech valuation.

View Source 
const VideoOutputSecondUnit = "video_output_seconds"

VideoOutputSecondUnit identifies provider-reported output seconds.

Variables

View Source 
var (
	// ErrAmbiguousModelName reports a retired canonical ID that also names an exact provider route.
	ErrAmbiguousModelName = errors.New("canonical alias conflicts with a provider route")
	// ErrCatalogSourceRequired reports a missing Starmap catalog source.
	ErrCatalogSourceRequired = errors.New("catalog source is required")
	// ErrCatalogRequired means that a Starmap state has no immutable catalog.
	ErrCatalogRequired = errors.New("catalog state must contain a catalog")
	// ErrModelNotCatalogued reports a model name the retained generation does
	// not hold. It is separate from an unreachable model because the two have
	// different answers: a name the catalog never held is the caller's to
	// correct, and a catalogued model with no reachable provider is the
	// gateway's to report.
	ErrModelNotCatalogued = errors.New("model is not in the catalog")
	// ErrCatalogGenerationRequired means that a Starmap state has no generation identity.
	ErrCatalogGenerationRequired = errors.New("catalog state must contain a generation ID")
	// ErrCatalogAuthorityMismatch reports authority metadata from a different publication.
	ErrCatalogAuthorityMismatch = errors.New("catalog authority head does not match the catalog generation")
	// ErrRecognitionUnpriced reports missing billing units or usable rates.
	ErrRecognitionUnpriced = errors.New("offering serves document recognition without known billing units and rates")
	// ErrRerankUnpriced reports an offering that serves reranking and states
	// no price in the unit it bills.
	//
	// Providers disagree on that unit. Cohere bills a search unit, which is one
	// query against a bounded document count, and Voyage bills the tokens it
	// reads. The offering names its own basis, so an offering that names one
	// and publishes no price for it is a catalog defect rather than a known
	// gap. Planning drops the operation, which keeps a silent zero out of the
	// account's spend total.
	ErrRerankUnpriced = errors.New("offering serves reranking with no price in the unit it bills")
)
View Source 
var ErrBaselinePromotionFleetOnly = errors.New("baseline promotion is fleet-only. A local deployment serves the baseline of its binary")

ErrBaselinePromotionFleetOnly refuses baseline promotion outside fleet mode. A local deployment retains no baseline apart from its binary.

View Source 
var ErrDisclosurePolicyRequired = errors.New("catalog disclosure policy is required")

ErrDisclosurePolicyRequired reports a missing viewer disclosure policy.

View Source 
var ErrNoFleetHead = errors.New("no fleet head. A gateway publishes the first fleet head when it starts")

ErrNoFleetHead means that no gateway published a fleet head yet, so a baseline report has nothing to compare.

View Source 
var ErrOperationNotFound = errors.New("catalog operation is not found")

ErrOperationNotFound reports an operation identifier the registry does not hold. A closed operation the registry pruned reads the same way.

View Source 
var ErrPolicyFenceUnavailable = errors.New("the configured storage has no shared catalog lease to fence")

ErrPolicyFenceUnavailable reports a deployment without shared catalog storage. Its single process has no lease to fence.

View Source 
var ErrRouteValidationFailed = errors.New("catalog candidate failed route validation")

ErrRouteValidationFailed marks a candidate that did not become routable. Composition wraps the validation failure with it, so the operation registry and the admin surface name the cause without reading the failure text.

View Source 
var ErrRuntimeGenerationCapacity = errors.New("runtime generation capacity is exhausted")

ErrRuntimeGenerationCapacity defers activation until retained requests finish.

View Source 
var ErrStaleLeaseEpoch = errors.New("catalog candidate carries a stale lease epoch")

ErrStaleLeaseEpoch matches a candidate the lease fence refused.

Functions

func AdoptFleet added in v1.3.0 

func AdoptFleet(ctx context.Context, backend storage.IncarnationProvider, witness *recovery.Witness, request FleetAdoptionRequest, settings Settings) (recovery.Record, error)

AdoptFleet validates copied catalog state before approving the replacement budget authority. The operator must first close recovery, fence all writers, and reconcile missing history. This operation does not infer those external actions from copied records.

func ApplyPolicy added in v1.3.0 

func ApplyPolicy(ctx context.Context, store storage.KVStore, db *sqlstore.DB, deployment string, applied AppliedPolicy) error

ApplyPolicy writes the applied policy record. It never takes the catalog refresh lease, so a sitting leader cannot block it. The next lease acquisition or renewal compares the record: a leader with another checksum loses the lease at its next renewal and keeps serving.

func Bundled added in v1.3.0 

func Bundled() (*catalogs.Catalog, error)

Bundled returns the immutable catalog shipped in the pinned Starmap module. Accepted upstream catalogs and runtime refresh cannot replace this value.

func EmbeddingValuation added in v1.3.0 

func EmbeddingValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

EmbeddingValuation projects the complete synchronous embedding charge. The caller must enforce the text or token-ID input scope before dispatch.

func ImageQuantities added in v1.3.0 

func ImageQuantities(billing *catalogs.ImageBilling, count int64, size string) (reservation.Quantities, error)

ImageQuantities counts submitted or completed images under one catalog contract. A zero count selects the declared request default. Settlement must supply a positive count.

func ImageValuation added in v1.3.0 

func ImageValuation(offering catalogs.ProviderOffering, operation catalogs.ProviderOperation, at time.Time) (reservation.Valuation, error)

ImageValuation projects complete catalog image charges for one operation.

func InspectBaselineExports added in v1.3.0 

func InspectBaselineExports(ctx context.Context, directory string) error

InspectBaselineExports validates completed exports without activation or acquisition. The caller must fence writers and verify the complete inventory around inspection.

func InspectCapturedCatalog added in v1.3.0 

func InspectCapturedCatalog(ctx context.Context, view *recovery.KVSnapshotView, boundary recovery.Record) error

InspectCapturedCatalog checks catalog references without opening a runtime or renewing permission. The closed backup boundary supplies deployment identity, not activation approval.

func InspectRetainedBaselinePublications added in v1.3.0 

func InspectRetainedBaselinePublications(ctx context.Context, files map[string]productfiles.RetainedFile, read productfiles.RetainedRecordReader) ([]string, error)

InspectRetainedBaselinePublications selects verified baseline stages to keep inactive. Include the separate recovery records and preserve them as historical evidence.

func ModerationValuation added in v1.3.0 

func ModerationValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

ModerationValuation projects the complete synchronous text moderation charge. A missing declaration or price is unknown. An explicit zero price is free.

func PrepareFleetAdoption added in v1.3.0 

func PrepareFleetAdoption(ctx context.Context, backend storage.IncarnationProvider, witness *recovery.Witness, request FleetAdoptionRequest, settings Settings) error

PrepareFleetAdoption validates and selects recovered catalog state while SQL approval remains closed. It never grants admission or releases import barriers. The recovery coordinator must reconcile history and activate every component before completing authority approval. All writers must remain fenced.

func ProbeSource added in v1.3.0 

func ProbeSource(ctx context.Context, settings Settings) error

ProbeSource checks that the catalog source of the settings answers within a bounded time. It reads no catalog payload and changes no state. An embedded source needs no connection. A file source must be a regular file. A starmap source must serve its current manifest. A public or github source must show its repository to the configured token.

func ProviderFromModelID 

func ProviderFromModelID(modelID string) string

ProviderFromModelID returns the adapter ID named by a provider-scoped model ID.

func RecognitionValuation added in v1.3.0 

func RecognitionValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

RecognitionValuation prices the complete synchronous PDF recognition contract. Display estimates and unresolved tiers cannot establish a reservation price.

func RerankValuation added in v1.3.0 

func RerankValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

RerankValuation projects every declared charge for synchronous text reranking.

func SafeFreshness added in v1.2.1 

func SafeFreshness(freshness runtime.Freshness) string

SafeFreshness maps one freshness grade onto the closed vocabulary.

func SafeHealth added in v1.2.1 

func SafeHealth(health runtime.Health) string

SafeHealth maps one health value onto the closed vocabulary.

func SafeSourceKind added in v1.2.1 

func SafeSourceKind(kind runtime.SourceKind) string

SafeSourceKind maps one source kind onto the closed vocabulary. A kind outside the set reads as "unknown", so a metric label and a reader response never carry a value the deployment invented.

func SpeechValuation added in v1.3.0 

func SpeechValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

SpeechValuation projects all charges declared for character-priced speech.

func SplitModelID 

func SplitModelID(modelID string) (provider, model string, ok bool)

SplitModelID splits one provider-scoped model ID.

func TextChatValuation added in v1.3.0 

func TextChatValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

TextChatValuation projects every declared charge from one selected offering. Missing prices, non-USD currencies, and unresolved pricing tiers remain unknown. The caller must enforce the text-chat request scope before dispatch.

func ValidatePromotionOperationID added in v1.3.0 

func ValidatePromotionOperationID(id string) error

ValidatePromotionOperationID accepts 1 to 128 letters, digits, and the characters ".", "_", ":", and "-".

func VideoMeasuredQuantities added in v1.3.0 

func VideoMeasuredQuantities(billing *catalogs.VideoBilling, seconds int64) (reservation.Quantities, error)

VideoMeasuredQuantities preserves measured duration, including an explicit zero. It never substitutes a requested duration or a catalog default. The caller must verify measured evidence for every declared charge.

func VideoRequestQuantities added in v1.3.0 

func VideoRequestQuantities(billing *catalogs.VideoBilling, seconds int64, size string) (reservation.Quantities, error)

VideoRequestQuantities resolves omitted inputs and bounds a declared video request. Its output is a reservation bound, never provider usage evidence.

func VideoValuation added in v1.3.0 

func VideoValuation(offering catalogs.ProviderOffering, at time.Time) (reservation.Valuation, error)

VideoValuation pins every declared charge for an output-duration video offering.

Types

type AcquisitionReport added in v1.2.1 

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"`
}

AcquisitionReport is the state of provider acquisition on this instance. It stays separate from source health, because an instance reads a source and observes providers as two independent pieces of work.

type AcquisitionResolver added in v1.2.1 

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

AcquisitionResolver uses Starmap's deployment credential sources and policy.

func NewAcquisitionResolver added in v1.2.1 

func NewAcquisitionResolver(lookup DeploymentLookup) *AcquisitionResolver

NewAcquisitionResolver creates an ephemeral acquisition resolver without reading secrets. A nil lookup refuses resolution and never falls back to the process environment.

func (*AcquisitionResolver) ResolveCatalog added in v1.2.1 

func (r *AcquisitionResolver) ResolveCatalog(ctx context.Context, provider *catalogs.Provider) (sources.ProviderCredentialMaterial, error)

ResolveCatalog resolves acquisition material without inference or account stores.

type AdapterAvailability 

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

AdapterAvailability is runtime state for one compiled provider adapter. It is not a catalog fact and does not contain operator credential state.

type AdminStatus added in v1.2.1 

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"`
}

AdminStatus is the operator view of the catalog runtime. Every concept is a separate value: a degraded upstream never hides a healthy transfer, and a rejected candidate never hides the accepted head that still routes.

func NewAdminStatus added in v1.2.1 

func NewAdminStatus(
	status runtime.Status,
	validation RouteValidation,
	acquisitionEnabled bool,
	counts Counts,
	snapshot SnapshotMetadata,
	nextUpdateAt time.Time,
	operations []Operation,
) AdminStatus

NewAdminStatus projects one connected runtime status onto the operator view. The caller supplies what the runtime does not know: the validation record, whether this instance acquires, how much the accepted head holds, when the next source read happens, and the recent operations.

func (AdminStatus) Summary added in v1.2.1 

func (s AdminStatus) Summary() Summary

Summary projects the allowlisted reader view of the admin status. Every vocabulary value passes through the closed-set maps, so a value the runtime did not produce reads as "unknown" rather than reaching a reader.

type AppliedPolicy added in v1.3.0 

type AppliedPolicy struct {
	Sequence    int64  `json:"sequence"`
	Checksum    string `json:"checksum"`
	OperationID string `json:"operation_id"`
}

AppliedPolicy is the shared configuration revision that the fleet applied. The checksum identifies the deployment-scope values without credentials.

type AttemptPermissionStatus added in v1.3.0 

type AttemptPermissionStatus struct {
	// NewAttemptsAllowed reports catalog permission, not credential or budget eligibility.
	NewAttemptsAllowed bool `json:"new_attempts_allowed"`
	// AdmittedStreamsMayFinish reports that catalog withdrawal does not cancel admitted streams.
	AdmittedStreamsMayFinish bool `json:"admitted_streams_may_finish"`
}

AttemptPermissionStatus separates new catalog admission from admitted stream completion.

type BaselineIdentity added in v1.3.0 

type BaselineIdentity struct {
	GenerationID string `json:"generation_id"`
	Checksum     string `json:"checksum"`
}

BaselineIdentity identifies one catalog baseline.

type BaselineReport added in v1.3.0 

type BaselineReport struct {
	DeploymentID string           `json:"deployment_id"`
	Packaged     BaselineIdentity `json:"packaged"`
	Retained     BaselineIdentity `json:"retained"`
	HeadRevision uint64           `json:"head_revision"`
	Promotable   bool             `json:"promotable"`
	Refusal      string           `json:"refusal,omitempty"`
}

BaselineReport compares the packaged baseline with the retained fleet baseline. It comes from memory and carries no credential.

type Candidate added in v1.2.1 

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

	// Epoch identifies the lease epoch active when the runtime produced the candidate. Zero means
	// the deployment shares no lease, and every candidate then passes the
	// fence.
	Epoch uint64

	// FleetHead binds route validation to the original durable publication and grant.
	FleetHead runtime.FleetHead
}

Candidate is one effective catalog generation offered for acceptance, together with the lease epoch the run that produced it started under.

The epoch travels with the candidate because acceptance happens after route validation, which takes time. An instance that loses the lease during that work must not advance the shared accepted head, and the epoch is what says so.

type CompiledTopology added in v1.3.0 

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

CompiledTopology privately retains deterministic catalog changes. It grants no admission authority.

func CompileRecoveryTopology added in v1.3.0 

func CompileRecoveryTopology(ctx context.Context, source *recovery.RestoreSource, request TopologyTransferRequest) (compiled *CompiledTopology, resultErr error)

CompileRecoveryTopology derives all inputs from one verified immutable backup. It opens no current target and grants no publication or admission permission.

func CompileTopologyTransfer added in v1.3.0 

func CompileTopologyTransfer(ctx context.Context, inventory *TopologyInventory, request TopologyTransferRequest, target *recovery.KVSnapshotView) (*CompiledTopology, error)

CompileTopologyTransfer binds checked source facts and exact imported target preimages. It calls no runtime acquisition, serving approval, refresh lease, or ordinary commit method.

func InspectRecoveryTopology added in v1.3.0 

func InspectRecoveryTopology(ctx context.Context, source *recovery.RestoreSource, request TopologyTransferRequest, record []byte, sealedSHA256 string) (*CompiledTopology, error)

InspectRecoveryTopology recompiles original verified backup bytes and checks the exact seal. It does not recapture current targets, renew time evidence, or write catalog state.

func (*CompiledTopology) ApplySelection added in v1.3.0 

func (c *CompiledTopology) ApplySelection(ctx context.Context, proof *TopologyMaterialization, target TopologyTarget) error

ApplySelection verifies all staged immutable bytes before the final bounded selection transaction. The native guard must refuse a changed replay cursor. The final graph census remains mandatory.

func (*CompiledTopology) ApplyStage added in v1.3.0 

func (c *CompiledTopology) ApplyStage(ctx context.Context, index int, target TopologyTarget) error

ApplyStage submits one predetermined transaction through the recovery-owned native guard.

func (*CompiledTopology) CheckMaterialization added in v1.3.0 

func (c *CompiledTopology) CheckMaterialization(ctx context.Context, target TopologyRuntimeTarget, proof *TopologyMaterialization, options ...runtime.Option) error

CheckMaterialization validates complete retained original bytes and the active producer selection. It does not mutate state, read sources, renew permission, or replace expired receipts.

func (*CompiledTopology) CheckPermission added in v1.3.0 

func (c *CompiledTopology) CheckPermission(ctx context.Context, settings Settings, clock permission.ClockReading, proof *TopologyPermission) error

CheckPermission rechecks original identities and expiry without extending receipt validity.

func (*CompiledTopology) CheckSelection added in v1.3.0 

func (c *CompiledTopology) CheckSelection(ctx context.Context, proof *TopologyMaterialization, target TopologyTarget) error

CheckSelection validates current catalog selection without treating a historical receipt as current permission. The target owner must preserve its selected native import identity and writer fence during reads.

func (*CompiledTopology) Digest added in v1.3.0 

func (c *CompiledTopology) Digest() string

Digest identifies the sealed backup record. TopologyDigest identifies the separate native lane.

func (CompiledTopology) Format added in v1.3.0 

func (c CompiledTopology) Format(state fmt.State, _ rune)

Format omits source records and target mutation preimages.

func (*CompiledTopology) InspectMaterialization added in v1.3.0 

func (c *CompiledTopology) InspectMaterialization(ctx context.Context, target TopologyRuntimeTarget, data []byte, options ...runtime.Option) (*TopologyMaterialization, error)

InspectMaterialization reopens journal evidence through actual producer-owned records. Missing completion, changed target inputs, or incomplete coverage refuse without repair.

func (*CompiledTopology) InspectPermission added in v1.3.0 

func (c *CompiledTopology) InspectPermission(ctx context.Context, settings Settings, clock permission.ClockReading) (*TopologyPermission, error)

InspectPermission checks the accepted catalog's original receipt under current target settings. The caller separately checks materialization, selection, and the native writer fence. This operation starts no runtime, source transport, acquisition, or clock monitor.

func (*CompiledTopology) InspectPreparedCapturedCatalog added in v1.3.0 

func (c *CompiledTopology) InspectPreparedCapturedCatalog(ctx context.Context, view *recovery.KVSnapshotView, boundary recovery.Record) error

InspectPreparedCapturedCatalog checks original or final records against one sealed backup transfer. The final catalog can use the verified future identity while SQL admission remains closed. This read neither changes the original boundary nor grants admission permission.

func (*CompiledTopology) InspectRetainedPermission added in v1.3.0 

func (c *CompiledTopology) InspectRetainedPermission(ctx context.Context, settings Settings, clock permission.ClockReading, record []byte, expectedSHA256 string) (*TopologyPermission, error)

InspectRetainedPermission reopens evidence sealed before any component release. The expected digest must come from the complete immutable activation decision.

func (*CompiledTopology) Record added in v1.3.0 

func (c *CompiledTopology) Record() ([]byte, error)

Record returns the small original backup binding without private capsules or target mutations. Low-level compiler output has no verified backup provenance and cannot produce this record.

func (*CompiledTopology) RetainAndMaterialize added in v1.3.0 

func (c *CompiledTopology) RetainAndMaterialize(ctx context.Context, target TopologyRuntimeTarget, options ...runtime.Option) (*TopologyMaterialization, error)

RetainAndMaterialize preserves every original capsule before selecting current producer inputs. The producer checks the structure of historical inputs. It replays both selections under target settings. This completes before catalog selection and authorization revision replacement.

func (*CompiledTopology) StageCount added in v1.3.0 

func (c *CompiledTopology) StageCount() int

StageCount reports the exact number of bounded native stage transactions.

func (*CompiledTopology) TopologyDigest added in v1.3.0 

func (c *CompiledTopology) TopologyDigest() string

TopologyDigest binds the exact checked transfer without exposing private source records.

type ControlPlane 

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

ControlPlane atomically publishes one routable view derived from an immutable Starmap generation and separately versioned runtime availability.

func Open 

func Open(source Source) (*ControlPlane, error)

Open creates the catalog control plane from the source's current atomic state.

func (*ControlPlane) Activate 

func (p *ControlPlane) Activate(state starmap.CatalogState) error

Activate validates and atomically publishes one complete catalog generation. Retained older snapshots remain valid and do not observe the new generation.

func (*ControlPlane) Current 

func (p *ControlPlane) Current() *RoutableSnapshot

Current returns the current immutable routable snapshot in O(1).

func (*ControlPlane) PublishAvailability 

func (p *ControlPlane) PublishAvailability(snapshot availability.Snapshot) error

PublishAvailability applies one availability-owner generation to the derived routable projection. It does not own availability state transitions.

func (*ControlPlane) Refresh 

func (p *ControlPlane) Refresh() error

Refresh atomically activates the source's current catalog generation.

func (*ControlPlane) RemoveAdapter 

func (p *ControlPlane) RemoveAdapter(providerID catalogs.ProviderID) error

RemoveAdapter removes one runtime adapter and atomically republishes the view.

func (*ControlPlane) ReplaceAdapters 

func (p *ControlPlane) ReplaceAdapters(adapters []AdapterAvailability) error

ReplaceAdapters replaces the complete runtime adapter set in one publication.

func (*ControlPlane) ReplaceRuntime added in v1.0.2 

func (p *ControlPlane) ReplaceRuntime(
	state starmap.CatalogState,
	adapters []AdapterAvailability,
) (*RoutableSnapshot, error)

ReplaceRuntime atomically publishes one catalog state and complete adapter set. Retained snapshots remain immutable.

func (*ControlPlane) SetAdapter 

func (p *ControlPlane) SetAdapter(adapter AdapterAvailability) error

SetAdapter updates one runtime adapter and atomically republishes the derived view.

func (*ControlPlane) ValidateRuntime added in v1.0.2 

func (p *ControlPlane) ValidateRuntime(
	state starmap.CatalogState,
	adapters []AdapterAvailability,
) error

ValidateRuntime proves that one catalog state and complete adapter set can produce a routable snapshot without changing published state.

type Counts added in v1.2.1 

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"`
}

Counts is how much the accepted head holds.

type DeploymentLookup added in v1.2.1 

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

DeploymentLookup reads deployment configuration without account or BYOK access.

type Diff added in v1.1.0 

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"`
}

Diff compares the previous accepted generation against the current one. When only one generation is recorded, Available is false and Reason says why — that is a normal state, not an error.

type DisclosurePolicy added in v1.3.0 

type DisclosurePolicy interface {
	AllowsDefinition(catalogs.ModelDefinitionID) bool
	AllowsOffering(catalogs.OfferingKey) bool
}

DisclosurePolicy selects accepted facts that a viewer can inspect. Implementations retain one immutable policy revision and read only memory. Disclosure permission does not authorize inference.

type DiscoveredModel added in v1.3.0 

type DiscoveredModel struct {
	Definition catalogs.ModelDefinition
	Offerings  []catalogs.ProviderOffering
}

DiscoveredModel contains one permitted definition and its permitted offerings. These facts do not assert structural support or caller readiness.

type Discovery added in v1.3.0 

type Discovery struct {
	GenerationID    string
	PayloadChecksum string
	Models          []DiscoveredModel
}

Discovery contains caller-owned facts from one accepted catalog generation. Adapter availability and credential state do not determine this membership.

type FleetAdoptionRequest added in v1.3.0 

type FleetAdoptionRequest struct {
	SourceApproval recovery.Record   `json:"source_approval"`
	Closed         recovery.Record   `json:"closed"`
	Head           runtime.FleetHead `json:"head"`
	BackendID      string            `json:"backend_id"`
	OperationID    string            `json:"operation_id"`
	Evidence       string            `json:"evidence"`
	ResolveReaders bool              `json:"resolve_readers"`
}

FleetAdoptionRequest names a fenced recovery operation and its selected source head. ResolveReaders explicitly abandons claims from the externally fenced processes. Evidence must identify the operator's fencing and cross-store reconciliation record.

type FleetHistoricalArchive added in v1.3.0 

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

FleetHistoricalArchive preserves source fleet evidence without granting destination authority. It is private, immutable, and created only from checked captured records.

func (FleetHistoricalArchive) Format added in v1.3.0 

func (a FleetHistoricalArchive) Format(state fmt.State, _ rune)

Format omits archived ownership tokens and private records.

type FleetStore added in v1.3.0 

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

FleetStore binds shared catalog publication to an independent recovery approval. It uses native backend expiry and retains complete acquisition inputs outside local directories.

func NewFleetStore added in v1.3.0 

func NewFleetStore(ctx context.Context, store storage.IncarnationProvider, witness *recovery.Witness, deployment string) (*FleetStore, error)

NewFleetStore requires an existing open recovery approval and a matching live backend. It never approves a missing record or a replacement backend during startup.

func (*FleetStore) AcceptPublication added in v1.3.0 

func (s *FleetStore) AcceptPublication(ctx context.Context, selected, expected runtime.FleetHead) error

AcceptPublication selects a validated candidate under its original live acquisition grant. It compares the complete candidate and accepted predecessors in the same native transaction.

func (*FleetStore) AcceptedHistory added in v1.3.0 

func (s *FleetStore) AcceptedHistory(ctx context.Context) ([]GenerationIndexEntry, error)

AcceptedHistory returns a bounded index from the same record as the accepted head.

func (*FleetStore) AcceptedPublication added in v1.3.0 

func (s *FleetStore) AcceptedPublication(ctx context.Context) (runtime.FleetSnapshot, error)

AcceptedPublication reads the publication that passed Starport route validation.

func (*FleetStore) AcquireGeneration added in v1.3.0 

func (s *FleetStore) AcquireGeneration(ctx context.Context, id string) (catalogs.Generation, func() error, error)

AcquireGeneration keeps a retained generation until an explicit successful release. Reader claims have no time-based expiry. Recovery must resolve abandoned claims explicitly.

func (*FleetStore) AcquireLease added in v1.3.0 

func (s *FleetStore) AcquireLease(ctx context.Context, holder string, ttl time.Duration) (runtime.Lease, error)

AcquireLease advances a durable epoch and creates a separate expiring native grant.

func (*FleetStore) Collect added in v1.3.0 

func (s *FleetStore) Collect(ctx context.Context, request catalogstorage.RetentionRequest) (catalogstorage.RetentionReport, error)

Collect applies the caller's retention policy under the native maintenance lease. Publication does not collect committed data. Dry runs do not recover pending deletions.

func (*FleetStore) CommitPublication added in v1.3.0 

func (s *FleetStore) CommitPublication(ctx context.Context, publication runtime.FleetPublication) (runtime.FleetHead, error)

CommitPublication checks the original live grant and predecessor in one native transaction.

func (*FleetStore) CurrentHead added in v1.3.0 

func (s *FleetStore) CurrentHead(ctx context.Context) (runtime.FleetHead, error)

CurrentHead reads small metadata without downloading acquisition inputs.

func (*FleetStore) CurrentPublication added in v1.3.0 

func (s *FleetStore) CurrentPublication(ctx context.Context) (runtime.FleetSnapshot, error)

CurrentPublication reads the immutable snapshot selected by the current head.

func (*FleetStore) Get added in v1.3.0 

func (s *FleetStore) Get(ctx context.Context, id string) (catalogs.Generation, error)

Get reads an immutable catalog from a retained publication.

func (*FleetStore) PolicyState added in v1.3.0 

func (s *FleetStore) PolicyState() string

PolicyState reports the last comparison with the applied fleet policy.

func (*FleetStore) Publication added in v1.3.0 

func (s *FleetStore) Publication(ctx context.Context, head runtime.FleetHead) (runtime.FleetSnapshot, error)

Publication reads a retained snapshot by its complete head identity.

func (*FleetStore) Release added in v1.3.0 

func (s *FleetStore) Release(ctx context.Context, lease runtime.Lease) error

Release removes only this process's original grant and preserves the durable epoch.

func (*FleetStore) Renew added in v1.3.0 

func (s *FleetStore) Renew(ctx context.Context, lease runtime.Lease, ttl time.Duration) (runtime.Lease, error)

Renew extends only the original live native grant. A leader whose applied configuration differs from the applied fleet policy loses the lease. After the renewal, a pending promotion request wakes the leader executor. Renewal never runs the promotion itself.

type FreshnessReport added in v1.2.1 

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"`
}

FreshnessReport grades three independent ages: the served generation, the propagated origin publication, and the last source check.

type FreshnessService added in v1.1.0 

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

FreshnessService reads catalog freshness from the active snapshot and the durable generation store. It never mutates either.

func NewFreshnessService added in v1.1.0 

func NewFreshnessService(snapshots SnapshotSource, generations *GenerationStore) *FreshnessService

NewFreshnessService creates the freshness read service.

func (*FreshnessService) Changes added in v1.1.0 

func (s *FreshnessService) Changes(ctx context.Context) (Diff, error)

Changes diffs the previous accepted generation against the current one.

func (*FreshnessService) Metadata added in v1.1.0 

func (s *FreshnessService) Metadata(ctx context.Context) (SnapshotMetadata, error)

Metadata reports the active snapshot's identity, age, and manifest facts.

type GenerationIndexEntry added in v1.1.0 

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"`
}

GenerationIndexEntry records one accepted generation in acceptance order. The semantic checksum excludes provenance, so the diff service can skip provenance-only churn without decoding payloads.

type GenerationRef added in v1.2.1 

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"`
}

GenerationRef names one catalog generation without disclosing its content.

type GenerationStore 

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

GenerationStore adapts Starport's configured KV store to Starmap's durable immutable-generation contract.

func NewGenerationStore 

func NewGenerationStore(store storage.KVStore) (*GenerationStore, error)

NewGenerationStore creates a durable Starmap generation store.

func OpenAcceptedStore added in v1.3.0 

func OpenAcceptedStore(ctx context.Context, store storage.KVStore, db *sqlstore.DB, deployment string) (*GenerationStore, error)

OpenAcceptedStore selects the accepted head without starting a catalog runtime. Shared storage requires independent recovery approval. This function never creates it.

func (*GenerationStore) Commit 

func (s *GenerationStore) Commit(
	ctx context.Context,
	generation catalogs.Generation,
	expectedGenerationID string,
) error

Commit stores one immutable generation, then selects it with compare-and-swap.

func (*GenerationStore) Current 

func (s *GenerationStore) Current(ctx context.Context) (catalogs.Generation, error)

Current returns the atomically selected generation.

func (*GenerationStore) Get 

func (s *GenerationStore) Get(ctx context.Context, generationID string) (catalogs.Generation, error)

Get returns one immutable generation by ID.

func (*GenerationStore) History added in v1.1.0 

func (s *GenerationStore) History(ctx context.Context) ([]GenerationIndexEntry, error)

History returns accepted generations in acceptance order, oldest first. A store without an index (the remote head store) reports no history.

type Hop added in v1.2.1 

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"`
}

Hop is one sanitized upstream publication step.

type LeaseStore added in v1.2.1 

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

LeaseStore is the catalog runtime lease over Starport's shared storage. It gives this deployment the epoch that fences an accepted head: an acceptance that started under an older epoch belongs to an instance that has since lost the lease, and shared storage must refuse it.

func NewLeaseStore added in v1.2.1 

func NewLeaseStore(store storage.KVStore) (*LeaseStore, error)

NewLeaseStore returns the catalog runtime lease over shared storage.

func (*LeaseStore) AcquireLease added in v1.2.1 

func (l *LeaseStore) AcquireLease(
	ctx context.Context,
	holder string,
	ttl time.Duration,
) (runtime.Lease, error)

AcquireLease takes the lease for one holder. A live lease another holder owns returns a conflict, which names a non-owner state and never a failure. Every fresh acquisition raises the epoch, so an older epoch is stale.

func (*LeaseStore) CurrentEpoch added in v1.2.1 

func (l *LeaseStore) CurrentEpoch(ctx context.Context) (uint64, error)

CurrentEpoch returns the epoch of the lease shared storage holds. A store that holds no lease reports epoch zero, and every candidate then passes the fence.

func (*LeaseStore) Release added in v1.2.1 

func (l *LeaseStore) Release(ctx context.Context, lease runtime.Lease) error

Release returns the lease early. A lease another holder took stays as it is.

func (*LeaseStore) Renew added in v1.2.1 

func (l *LeaseStore) Renew(
	ctx context.Context,
	lease runtime.Lease,
	ttl time.Duration,
) (runtime.Lease, error)

Renew extends a held lease and keeps its epoch. A lease another holder took returns a conflict.

type OfferingChange added in v1.1.0 

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

OfferingChange identifies one provider offering added or removed between two accepted generations.

type OfferingRoutability added in v1.1.0 

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

OfferingRoutability is the planning verdict for one exact catalog offering. The verdict set is total: every offering in the generation carries one, so a caller can tell an advertised offering apart from a reachable one.

type Operation added in v1.2.1 

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"`
	// PermissionAtCompletion records admission and stream policy when the operation ended.
	PermissionAtCompletion AttemptPermissionStatus `json:"permission_at_completion,omitzero"`
}

Operation is one unit of catalog work an operator asked for or a schedule started. It names what the work is, where it stands, and why it closed. It never carries the text of a failure.

func (Operation) Open added in v1.2.1 

func (o Operation) Open() bool

Open reports whether the operation can still change.

type OperationKind added in v1.2.1 

type OperationKind string

OperationKind names the work an operation performs. The set is closed, so an audit subject and a metric label read from a fixed vocabulary. 

const KindCatalogUpdate OperationKind = "catalog_update"

KindCatalogUpdate is the one kind this gateway runs: read the source, observe the providers, and offer the result for acceptance.

type OperationOption added in v1.2.1 

type OperationOption func(*Operations)

OperationOption configures the registry.

func WithOperationTimeout added in v1.2.1 

func WithOperationTimeout(timeout time.Duration) OperationOption

WithOperationTimeout bounds one operation. The deployment refresh timeout supplies it, and zero adds no cap: the transfer bounds end a transfer that stops making progress, and the cancel route and Close end a run an operator no longer wants.

func WithRetainedOperations added in v1.2.1 

func WithRetainedOperations(retained int) OperationOption

WithRetainedOperations sets how many closed operations the registry keeps.

type OperationReason added in v1.2.1 

type OperationReason string

OperationReason is the safe cause of a closed operation. The set is closed, because this value reaches a log line, a metric label, and an operator response, and a provider message must reach none of them. 

const (
	// ReasonNone is the reason of an operation that did not fail.
	ReasonNone OperationReason = ""
	// ReasonSourceUnavailable means the catalog source answered nothing
	// usable.
	ReasonSourceUnavailable OperationReason = "source_unavailable"
	// ReasonTimedOut means the operation reached its bound.
	ReasonTimedOut OperationReason = "timed_out"
	// ReasonCanceled means an operator or a shutdown ended the operation.
	ReasonCanceled OperationReason = "canceled"
	// ReasonStaleLeaseEpoch means the instance lost the runtime lease while
	// it validated the candidate.
	ReasonStaleLeaseEpoch OperationReason = "stale_lease_epoch"
	// ReasonRouteValidationFailed means the candidate did not become
	// routable.
	ReasonRouteValidationFailed OperationReason = "route_validation_failed"
	// ReasonAcceptedHeadConflict means another instance moved the accepted
	// head first.
	ReasonAcceptedHeadConflict OperationReason = "accepted_head_conflict"
	// ReasonCatalogUnavailable means no catalog generation is present.
	ReasonCatalogUnavailable OperationReason = "catalog_unavailable"
	// ReasonRuntimeGenerationCapacity means retained requests delay activation.
	ReasonRuntimeGenerationCapacity OperationReason = "runtime_generation_capacity"
	// ReasonInternalError is the reason of a failure with no safe cause of
	// its own. It never carries the failure text.
	ReasonInternalError OperationReason = "internal_error"
)

func ClassifyOperationFailure added in v1.2.1 

func ClassifyOperationFailure(err error) OperationReason

ClassifyOperationFailure maps one failure onto the closed reason set. A cause the set does not name reads as an internal error, so no provider or source text reaches a log line, a metric label, or an operator response.

type OperationResult added in v1.2.1 

type OperationResult struct {
	// GenerationID is the generation the work produced.
	GenerationID string
	// Changed reports whether the work moved the accepted head.
	Changed bool
	// PermissionAtCompletion records admission and stream policy when the work ended.
	PermissionAtCompletion AttemptPermissionStatus
}

OperationResult is what one unit of catalog work produced.

type OperationState added in v1.2.1 

type OperationState string

OperationState names where one operation stands. The set is closed. 

const (
	// OperationAccepted means the registry took the request and no run
	// started yet.
	OperationAccepted OperationState = "accepted"
	// OperationRunning means the work is in flight.
	OperationRunning OperationState = "running"
	// OperationSucceeded means the work finished with no failure.
	OperationSucceeded OperationState = "succeeded"
	// OperationFailed means the work ended with a failure.
	OperationFailed OperationState = "failed"
	// OperationCanceled means an operator or a shutdown ended the work.
	OperationCanceled OperationState = "canceled"
)

type OperationWork added in v1.2.1 

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

OperationWork is one unit of catalog work. The context it receives ends when the operation is canceled or reaches its bound.

type Operations added in v1.2.1 

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

Operations is the registry of catalog operations. It keeps one open operation per kind, so overlapping refresh requests join the run in flight rather than starting a second one.

func NewOperations added in v1.2.1 

func NewOperations(options ...OperationOption) *Operations

NewOperations creates the catalog operation registry.

func (*Operations) Cancel added in v1.2.1 

func (o *Operations) Cancel(id string) (Operation, error)

Cancel ends one open operation. Canceling a closed operation returns it unchanged, so a repeated cancel is a success that changes nothing.

func (*Operations) Close added in v1.2.1 

func (o *Operations) Close()

Close ends every open operation and waits for the work to stop.

func (*Operations) Get added in v1.2.1 

func (o *Operations) Get(id string) (Operation, error)

Get returns one operation by identifier.

func (*Operations) List added in v1.2.1 

func (o *Operations) List() []Operation

List returns every held operation, newest first.

func (*Operations) Submit added in v1.2.1 

func (o *Operations) Submit(kind OperationKind, work OperationWork) (Operation, bool)

Submit accepts one unit of work and returns the operation that carries it.

A kind that already has an open operation joins that operation: the caller reads the identifier of the run in flight and no second run starts. The second return value reports the join, so a caller can say which answer it gave.

The work runs on a background context. A request that ends does not end the operation it started, because the operator asked for the work and not for the response.

type PolicyMismatchError added in v1.3.0 

type PolicyMismatchError struct {
	Applied AppliedPolicy
	Local   string
}

PolicyMismatchError refuses leadership to a replica whose applied configuration differs from the applied fleet policy. It is a lease conflict, so the replica keeps serving its accepted catalog.

func (*PolicyMismatchError) Error added in v1.3.0 

func (e *PolicyMismatchError) Error() string

func (*PolicyMismatchError) Unwrap added in v1.3.0 

func (e *PolicyMismatchError) Unwrap() error

Unwrap reports the lease conflict that the Starmap runtime treats as a refusal.

type PriceChange added in v1.1.0 

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"`
}

PriceChange reports one token-price movement on an offering present in both generations. Values are USD per one million tokens.

type ProbeError added in v1.3.0 

type ProbeError struct {
	Message string
}

ProbeError is a source reachability failure. Its message never holds a credential or a source URL.

func (*ProbeError) Error added in v1.3.0 

func (e *ProbeError) Error() string

type PromotionIdentity added in v1.3.0 

type PromotionIdentity struct {
	GenerationID string `json:"generation_id"`
	Checksum     string `json:"checksum"`
	Revision     uint64 `json:"revision"`
}

PromotionIdentity identifies one baseline at one fleet head revision.

type PromotionReceipt added in v1.3.0 

type PromotionReceipt struct {
	OperationID   string                          `json:"operation_id"`
	DeploymentID  string                          `json:"deployment_id"`
	Status        PromotionStatus                 `json:"status"`
	Previous      PromotionIdentity               `json:"previous"`
	Promoted      PromotionIdentity               `json:"promoted"`
	InertRemovals []catalogs.CatalogRemovalTarget `json:"inert_removals"`
	Refusal       string                          `json:"refusal"`
	Actor         string                          `json:"actor"`
	CreatedAt     time.Time                       `json:"created_at"`
}

PromotionReceipt records one baseline promotion. It carries no credential. The fleet stores an applied receipt under its operation ID.

type PromotionRecord added in v1.3.0 

type PromotionRecord struct {
	OperationID          string            `json:"operation_id"`
	ExpectedRevision     uint64            `json:"expected_revision"`
	PackagedGenerationID string            `json:"packaged_generation_id"`
	Actor                string            `json:"actor"`
	RequestedAt          time.Time         `json:"requested_at"`
	Status               PromotionStatus   `json:"status"`
	Receipt              *PromotionReceipt `json:"receipt,omitempty"`
	// Expires is the end of the record lifetime that the read observed.
	Expires time.Time `json:"-"`
}

PromotionRecord is the one shared promotion request of a deployment. The command writes it pending. The leader replaces it with the outcome.

type PromotionRequest added in v1.3.0 

type PromotionRequest struct {
	// OperationID is the stable operator ID that makes a retry exact.
	OperationID string
	// ExpectedRevision is the fleet head revision that the operator reviewed.
	// Zero accepts the head that this replica observes. The head before this
	// process republished the same generation as it took the lease also matches.
	ExpectedRevision uint64
	// PackagedGenerationID names the packaged baseline of the binary that wrote the request.
	// The leader promotes only its own packaged generation. Empty selects the packaged
	// generation of this replica.
	PackagedGenerationID string
	// Actor names the operator for the receipt.
	Actor string
}

PromotionRequest selects the packaged baseline of this binary for the fleet.

type PromotionRequests added in v1.3.0 

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

PromotionRequests writes and reads the shared promotion request of one deployment. It never takes the publication lease and never opens a gateway state directory.

func OpenPromotionRequests added in v1.3.0 

func OpenPromotionRequests(ctx context.Context, store storage.KVStore, db *sqlstore.DB, deployment string) (*PromotionRequests, error)

OpenPromotionRequests opens the request record of a fleet deployment. A deployment without shared catalog storage refuses.

func (*PromotionRequests) Leader added in v1.3.0 

func (p *PromotionRequests) Leader(ctx context.Context) (string, error)

Leader names the current publication lease holder. It is empty when no gateway leads.

func (*PromotionRequests) Read added in v1.3.0 

func (p *PromotionRequests) Read(ctx context.Context, operationID string) (PromotionRecord, bool, error)

Read returns the record when it belongs to the operation ID. It reports false when the record expired or another operation replaced it.

func (*PromotionRequests) Submit added in v1.3.0 

func (p *PromotionRequests) Submit(ctx context.Context, request PromotionRequest) (PromotionRecord, error)

Submit writes one pending request, or returns the record of the same operation ID.

type PromotionStatus added in v1.3.0 

type PromotionStatus string

PromotionStatus names the outcome of one baseline promotion. 

const (
	// PromotionApplied means the fleet accepted the promoted baseline.
	PromotionApplied PromotionStatus = "applied"
	// PromotionRefused means the fleet head and its baseline did not change.
	PromotionRefused PromotionStatus = "refused"
)
const PromotionPending PromotionStatus = "pending"

PromotionPending means that no leader settled the request yet.

type Provenance added in v1.2.1 

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"`
}

Provenance carries both provenances of the served catalog: the generation this runtime composed and the upstream publication it came from.

type RefreshReport added in v1.1.0 

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

RefreshReport summarizes one forced catalog acquisition.

type Rejection added in v1.2.1 

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"`
}

Rejection is the newest candidate this instance refused, with the safe cause of the refusal.

type RetainedFile added in v1.3.0 

type RetainedFile = runtime.RetainedFile

RetainedFile identifies bytes in a verified runtime backup.

type RoutableSnapshot 

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

RoutableSnapshot projects one Starmap generation and one runtime availability revision into an immutable route set.

func (*RoutableSnapshot) AllowsNewAttempt added in v1.3.0 

func (s *RoutableSnapshot) AllowsNewAttempt() bool

AllowsNewAttempt checks current permission for this snapshot without storage access. Call it before route selection, each provider attempt, and cached response delivery. Retained metadata alone cannot authorize an authoritative catalog.

func (*RoutableSnapshot) AttemptPermissionStatus added in v1.3.0 

func (s *RoutableSnapshot) AttemptPermissionStatus() AttemptPermissionStatus

AttemptPermissionStatus records the current catalog permission and stream policy.

func (*RoutableSnapshot) AuthorityHead added in v1.3.0 

func (s *RoutableSnapshot) AuthorityHead() catalogs.CatalogAuthorityHead

AuthorityHead returns the authority head bound to this catalog. This read does not grant permission.

func (*RoutableSnapshot) AvailabilityRevision 

func (s *RoutableSnapshot) AvailabilityRevision() uint64

AvailabilityRevision returns the runtime availability revision.

func (*RoutableSnapshot) Catalog 

func (s *RoutableSnapshot) Catalog() *catalogs.Catalog

Catalog returns the retained immutable Starmap catalog. Starmap guarantees that published catalogs are safe to share and retain across goroutines.

func (*RoutableSnapshot) CatalogSequence 

func (s *RoutableSnapshot) CatalogSequence() uint64

CatalogSequence returns the source's monotonic generation sequence.

func (*RoutableSnapshot) CheckNewAttempt added in v1.3.0 

func (s *RoutableSnapshot) CheckNewAttempt() *failure.Failure

CheckNewAttempt returns a retryable gateway refusal when current permission is unavailable. A refusal carries no provider-health evidence. Successful checks allocate no memory.

func (*RoutableSnapshot) Definition 

func (s *RoutableSnapshot) Definition(
	id catalogs.ModelDefinitionID,
) (catalogs.ModelDefinition, error)

Definition returns one caller-owned definition from this exact generation.

func (*RoutableSnapshot) Definitions 

func (s *RoutableSnapshot) Definitions() []catalogs.ModelDefinition

Definitions returns caller-owned Starmap definitions that have a routable offering.

func (*RoutableSnapshot) Discover added in v1.3.0 

func (s *RoutableSnapshot) Discover(policy DisclosurePolicy) (Discovery, error)

Discover applies explicit disclosure policy to this accepted generation. It checks authority before and after projection without external reads. The caller must recheck current disclosure policy before response delivery.

func (*RoutableSnapshot) DiscoveryCacheIdentity added in v1.3.0 

func (s *RoutableSnapshot) DiscoveryCacheIdentity() string

DiscoveryCacheIdentity names this immutable runtime view across process lifetimes. Adapter changes create a new view even when the catalog generation is unchanged.

func (*RoutableSnapshot) GeneratedAt 

func (s *RoutableSnapshot) GeneratedAt() time.Time

GeneratedAt returns the Starmap generation timestamp.

func (*RoutableSnapshot) GenerationID 

func (s *RoutableSnapshot) GenerationID() string

GenerationID returns the Starmap generation used to derive this snapshot.

func (*RoutableSnapshot) LowestPagePrice added in v1.1.0 

func (s *RoutableSnapshot) LowestPagePrice(operation catalogs.ProviderOperation) (float64, bool)

LowestPagePrice returns the cheapest page price this generation publishes for one operation.

It answers the question a caller has before a route exists: what is the least this document can cost to read? The planner picks the offering afterwards, so no exact price is knowable yet, and the cheapest one is the only bound that refuses no work the account could have paid for.

func (*RoutableSnapshot) LowestSearchUnitPrice added in v1.1.0 

func (s *RoutableSnapshot) LowestSearchUnitPrice(modelID string) (float64, bool)

LowestSearchUnitPrice returns the cheapest search unit price this generation publishes for one model's rerank offerings.

It answers the question a spend budget has before a route exists: what is the least this rerank call can cost? The planner picks the offering afterwards, so no exact price is knowable yet, and the cheapest one is the only bound that refuses no work the account could have paid for. An offering that bills tokens rather than search units states no floor at all before the provider has read the documents, so it answers nothing and the budget refuses nothing.

func (*RoutableSnapshot) Names added in v1.1.0 

func (s *RoutableSnapshot) Names(modelID string) bool

Names reports whether accepted membership contains a model name. It includes offerings without a ready adapter and canonical definitions. A credential or adapter gap does not remove accepted membership.

func (*RoutableSnapshot) Offering 

func (s *RoutableSnapshot) Offering(route Route) (catalogs.ProviderOffering, error)

Offering returns one caller-owned offering from this exact generation.

func (*RoutableSnapshot) OfferingRoutability added in v1.1.0 

func (s *RoutableSnapshot) OfferingRoutability() []OfferingRoutability

OfferingRoutability returns the planning verdict for every offering in the generation, routable or not, sorted by provider and provider model ID.

func (*RoutableSnapshot) PagePriceFor added in v1.1.0 

func (s *RoutableSnapshot) PagePriceFor(
	modelID string,
	operation catalogs.ProviderOperation,
) (float64, bool)

PagePriceFor returns what one model charges to read one page of a document, in USD, only when the offering declares page billing.

func (*RoutableSnapshot) PayloadChecksum added in v1.0.2 

func (s *RoutableSnapshot) PayloadChecksum() string

PayloadChecksum returns the checksum bound to the Starmap generation.

func (*RoutableSnapshot) PlanningCandidates added in v1.3.0 

func (s *RoutableSnapshot) PlanningCandidates(names []string, unrestricted bool) []routing.Candidate

PlanningCandidates returns caller-owned static candidates for the selected names. An unrestricted selection returns every candidate in snapshot order.

func (*RoutableSnapshot) RecognitionOfferingFor added in v1.3.0 

func (s *RoutableSnapshot) RecognitionOfferingFor(modelID string) (catalogs.ProviderOffering, bool)

RecognitionOfferingFor returns the exact recognition offering used by a route. Its billing units and rates come from the request's retained catalog generation.

func (*RoutableSnapshot) ResolveAlias added in v1.3.0 

func (s *RoutableSnapshot) ResolveAlias(name string) (string, bool)

ResolveAlias resolves a retained canonical alias without reading external state. Ordinary names pass through. Removed aliases and missing snapshots return false.

func (*RoutableSnapshot) ResolveOperation 

func (s *RoutableSnapshot) ResolveOperation(
	modelID string,
	operation catalogs.ProviderOperation,
) (Route, bool)

ResolveOperation resolves only routes that support one exact operation.

func (*RoutableSnapshot) ResolveRoute 

func (s *RoutableSnapshot) ResolveRoute(modelID string) (Route, bool)

ResolveRoute resolves a provider-scoped route ID or a canonical definition ID to the first stable routable offering.

func (*RoutableSnapshot) Routes 

func (s *RoutableSnapshot) Routes() []Route

Routes returns a caller-owned copy of the routable offering identities.

func (*RoutableSnapshot) RoutesForDefinition 

func (s *RoutableSnapshot) RoutesForDefinition(definitionID catalogs.ModelDefinitionID) []Route

RoutesForDefinition returns routable offerings for one canonical model.

func (*RoutableSnapshot) RoutesForModel added in v1.3.0 

func (s *RoutableSnapshot) RoutesForModel(name string) []Route

RoutesForModel returns caller-owned routes matching a canonical or exact offering name.

func (*RoutableSnapshot) RoutesForProvider 

func (s *RoutableSnapshot) RoutesForProvider(providerID catalogs.ProviderID) []Route

RoutesForProvider returns routable offerings for one provider in stable order.

type Route 

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

Route is one immutable, generation-bound provider offering identity.

func (Route) Endpoint 

func (r Route) Endpoint(operation catalogs.ProviderOperation) (catalogs.ProviderOfferingEndpoint, bool)

Endpoint returns the exact Starmap endpoint for a supported operation.

func (Route) ID 

func (r Route) ID() string

ID returns Starport's provider-scoped route ID.

func (Route) Key 

func (r Route) Key() catalogs.OfferingKey

Key returns the exact Starmap provider offering identity.

func (Route) Supports 

func (r Route) Supports(operation catalogs.ProviderOperation) bool

Supports reports whether the catalog offering and compiled adapter both support the operation.

func (Route) SupportsPromptCache 

func (r Route) SupportsPromptCache() bool

SupportsPromptCache reports exact offering support. Unknown is not support.

type RouteExclusion added in v1.1.0 

type RouteExclusion string

RouteExclusion names the derivation filter that kept one catalog offering out of the routable set. It is the route planner's own vocabulary. A caller that reports operator state maps it into its own reason words. 

const (
	// RouteExclusionNone marks an offering that planning kept.
	RouteExclusionNone RouteExclusion = ""
	// RouteExclusionAdapterNotReady reports that the provider has no adapter
	// able to carry a request, so none of its offerings can be reached.
	RouteExclusionAdapterNotReady RouteExclusion = "adapter_not_ready"
	// RouteExclusionCatalogRetired reports a retired offering lifecycle.
	RouteExclusionCatalogRetired RouteExclusion = "catalog_retired"
	// RouteExclusionCatalogUnavailable reports catalog-declared unavailability.
	RouteExclusionCatalogUnavailable RouteExclusion = "catalog_unavailable"
	// RouteExclusionOfferingUnavailable reports that the availability owner
	// currently withholds this offering.
	RouteExclusionOfferingUnavailable RouteExclusion = "offering_unavailable"
	// RouteExclusionOperationUnsupported reports that the offering and the
	// adapter share no operation with a usable endpoint. The offering exists in
	// the catalog and is healthy, and no request can reach it.
	RouteExclusionOperationUnsupported RouteExclusion = "operation_unsupported"
	// RouteExclusionOperationUnpriced reports that every operation the offering
	// and the adapter share is one the gateway cannot bill. It is a separate
	// verdict from operation_unsupported because the fix is a catalog price,
	// not a compiled adapter.
	RouteExclusionOperationUnpriced RouteExclusion = "operation_unpriced"
)

Route exclusions are a closed set, ordered the way the derivation applies them. An offering carries the first exclusion that rejected it.

type RouteValidation added in v1.2.1 

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"`
}

RouteValidation reports the four states of the candidate-to-accepted transaction as separate values: what the source offered, what routes now, what this instance refused, and where the newest candidate stands.

type RouteValidationState added in v1.2.1 

type RouteValidationState string

RouteValidationState says where the newest candidate stands between the source and the routable head. The set is closed. 

const (
	// RouteValidationUnknown means this instance observed no candidate yet.
	RouteValidationUnknown RouteValidationState = "unknown"
	// RouteValidationPending means a candidate is ahead of the accepted head
	// and validation has not finished.
	RouteValidationPending RouteValidationState = "pending"
	// RouteValidationAccepted means the newest candidate became the accepted
	// head.
	RouteValidationAccepted RouteValidationState = "accepted"
	// RouteValidationRejected means the newest candidate did not become
	// routable, and the accepted head still serves every request.
	RouteValidationRejected RouteValidationState = "rejected"
)

type Runtime 

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

Runtime owns one Starmap connected runtime, Starport's accepted catalog head, and the routable control plane derived from that head.

One runtime reads one source. The local-or-remote choice is gone: a deployment names a source kind, and the same composition serves every kind. Starmap publishes an effective generation into the candidate store. Starport validates the candidate before it advances the accepted head. A candidate that fails route validation never routes a request.

func OpenBaselineObserver added in v1.3.0 

func OpenBaselineObserver(ctx context.Context, store storage.KVStore, db *sqlstore.DB, settings Settings, lookup DeploymentLookup) (*Runtime, error)

OpenBaselineObserver opens the fleet catalog runtime for one baseline report. It replays the shared fleet head into a new temporary directory and never takes the publication lease, so it runs beside a gateway on the same host. It never opens the state directory of the gateway. Close removes the temporary directory. A fleet without a head returns ErrNoFleetHead.

func OpenRuntime 

func OpenRuntime(
	ctx context.Context,
	store storage.KVStore,
	settings Settings,
	lookup DeploymentLookup,
) (*Runtime, error)

OpenRuntime composes one connected Starmap runtime over Starport's durable storage. It starts the source and acquisition schedules and returns.

The deployment lookup is the only credential plane catalog acquisition reads, so an inference credential can reach no provider observation.

func OpenRuntimeWithRecovery added in v1.3.0 

func OpenRuntimeWithRecovery(ctx context.Context, store storage.KVStore, db *sqlstore.DB, settings Settings, lookup DeploymentLookup) (*Runtime, error)

OpenRuntimeWithRecovery uses an independent SQL witness for a shared KV deployment. An unknown or closed witness cannot approve a backend during startup.

func (*Runtime) Accept added in v1.2.1 

func (r *Runtime) Accept(ctx context.Context, candidate Candidate) error

Accept advances the accepted head to one validated candidate.

The transaction has three parts, in this order. The lease epoch fences the write, so a run that lost the lease writes nothing. The candidate must move the head forward. Acceptance refuses stale or contradictory generations. The write itself is a compare-and-swap against the head the caller read, so two instances that reach this point together produce exactly one advance.

Repeating a candidate that the head already carries is a success that writes nothing. Shared storage stays idempotent for a retry after a partial failure.

func (*Runtime) AcceptedGeneration added in v1.2.1 

func (r *Runtime) AcceptedGeneration(ctx context.Context) (catalogs.Generation, error)

AcceptedGeneration returns the head Starport accepted. A deployment that accepted nothing yet reports the not-found error.

func (*Runtime) AcceptedStore added in v1.3.0 

func (r *Runtime) AcceptedStore() *GenerationStore

AcceptedStore exposes the runtime's exact storage selection to diagnostics and history.

func (*Runtime) BaselineReport added in v1.3.0 

func (r *Runtime) BaselineReport() (BaselineReport, error)

BaselineReport reads the packaged and retained baselines from memory.

func (*Runtime) Close added in v1.2.1 

func (r *Runtime) Close(ctx context.Context) error

Close stops the forwarding work and closes the connected runtime.

func (*Runtime) ControlPlane 

func (r *Runtime) ControlPlane() *ControlPlane

ControlPlane returns Starport's generation-consistent catalog projection. It reads the accepted head alone.

func (*Runtime) CurrentCandidate added in v1.2.1 

func (r *Runtime) CurrentCandidate(ctx context.Context) (Candidate, error)

CurrentCandidate returns the effective state the connected runtime serves now, with the lease epoch that fences its acceptance.

func (*Runtime) PermissionClock added in v1.3.0 

func (r *Runtime) PermissionClock() permission.ClockReading

PermissionClock shares the connected runtime's qualified cached time with its host. It reads no storage and calls no native clock API.

func (*Runtime) PolicyState added in v1.3.0 

func (r *Runtime) PolicyState() string

PolicyState reports the last comparison of this replica's applied configuration with the applied fleet policy.

func (*Runtime) PromoteBaseline added in v1.3.0 

func (r *Runtime) PromoteBaseline(ctx context.Context, request PromotionRequest) (PromotionReceipt, error)

PromoteBaseline makes the packaged baseline of this binary the retained fleet baseline. Only the publication lease holder promotes. The promoted head passes fleet acceptance before the receipt reports it applied. An exact retry returns the stored receipt without a promotion. A refusal returns a receipt that the fleet does not store. The leader calls it for a recorded request. See executePromotionRequest.

func (*Runtime) Refresh 

func (r *Runtime) Refresh(ctx context.Context) (runtime.RefreshReport, error)

Refresh reads the source and observes every eligible provider. Overlapping callers join one run, because the connected runtime keeps refresh single-flight and returns the report of the run in flight.

func (*Runtime) RefreshCandidate added in v1.1.0 

func (r *Runtime) RefreshCandidate(
	ctx context.Context,
	timeout time.Duration,
) (Candidate, error)

RefreshCandidate refreshes the connected runtime and returns the effective state the refresh produced, with the lease epoch that fences its acceptance.

A timeout of zero adds no cap. The transfer bounds already end a transfer that stops making progress, so an added cap would cut a transfer the transfer policy still allows.

func (*Runtime) RefreshFleet added in v1.3.0 

func (r *Runtime) RefreshFleet(ctx context.Context) error

RefreshFleet recovers a missed shared head without source or provider acquisition.

func (*Runtime) Reject added in v1.2.1 

func (r *Runtime) Reject(candidate Candidate, failure error)

Reject records one candidate this instance refused, with the safe cause of the refusal. The accepted head does not move.

func (*Runtime) RouteValidation added in v1.2.1 

func (r *Runtime) RouteValidation() RouteValidation

RouteValidation reports where the newest candidate stands between the source and the routable head.

func (*Runtime) Start added in v1.2.1 

func (r *Runtime) Start(ctx context.Context) error

Start forwards every new candidate the connected runtime publishes.

func (*Runtime) Status added in v1.2.1 

func (r *Runtime) Status() runtime.Status

Status returns the connected runtime status. It carries both provenances: the upstream generation the source published and the effective generation this runtime built from it.

func (*Runtime) Updates added in v1.2.1 

func (r *Runtime) Updates() <-chan Candidate

Updates emits distinct candidates and retries shared candidates after a failed validation.

type RuntimeMigration added in v1.3.0 

type RuntimeMigration struct {
	OperationID     string
	SourceDirectory string
	TargetDirectory string
	JournalRoot     string
	SourceIdentity  string
	StoreSelection  string
	// contains filtered or unexported fields
}

RuntimeMigration selects a stopped runtime directory and its replacement. It does not move the gateway databases, catalog store, or authoring workspace.

func (RuntimeMigration) Complete added in v1.3.0 

func (m RuntimeMigration) Complete(ctx context.Context, connected *Runtime, settings Settings) (RuntimeMigrationResult, error)

Complete records completion for an active replacement after saved selection checks.

func (RuntimeMigration) OpenReplacement added in v1.3.0 

func (m RuntimeMigration) OpenReplacement(ctx context.Context, store storage.KVStore, settings Settings) (*Runtime, error)

OpenReplacement verifies migration evidence before opening the selected runtime. The caller must retain the original catalog KV store and persist the target settings. Completion remains explicit after the host verifies that saved configuration.

func (RuntimeMigration) Prepare added in v1.3.0 

func (m RuntimeMigration) Prepare(ctx context.Context, store storage.KVStore, settings Settings) (RuntimeMigrationResult, error)

Prepare inventories source files without creating the target directory.

func (RuntimeMigration) Publish added in v1.3.0 

func (m RuntimeMigration) Publish(ctx context.Context, store storage.KVStore, settings Settings) (RuntimeMigrationResult, error)

Publish installs the verified target and retires the source runtime.

func (RuntimeMigration) Stage added in v1.3.0 

func (m RuntimeMigration) Stage(ctx context.Context, store storage.KVStore, settings Settings) (RuntimeMigrationResult, error)

Stage copies and verifies private staging files without publishing the target.

func (RuntimeMigration) WithRecoveryWitness added in v1.3.0 

func (m RuntimeMigration) WithRecoveryWitness(db *sqlstore.DB) RuntimeMigration

WithRecoveryWitness selects the independent witness for a shared catalog directory move.

type RuntimeMigrationResult added in v1.3.0 

type RuntimeMigrationResult struct {
	Phase                string `json:"phase"`
	HostJournalDirectory string `json:"host_journal_directory"`
	JournalDirectory     string `json:"journal_directory"`
	TargetDirectory      string `json:"target_directory"`
	SchedulerIdentity    string `json:"scheduler_identity"`
	FileCount            int    `json:"file_count,omitempty"`
	IdentityVerified     *bool  `json:"identity_verified,omitempty"`
}

RuntimeMigrationResult reports the durable phase of a runtime directory move.

type RuntimeReport added in v1.2.1 

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"`
	// Policy reports the last comparison of the applied configuration with
	// the applied fleet policy: match or policy_mismatch. A mismatch blocks
	// leadership, and the runtime keeps serving.
	Policy string `json:"policy,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"`
}

RuntimeReport is the state of the connected Starmap runtime.

type Settings added in v1.2.1 

type Settings struct {
	// CredentialPolicyDirectory retains private acquisition policy decisions. Empty selects an ephemeral resolver.
	CredentialPolicyDirectory string
	// BaselineDirectory selects the host-owned immutable embedded export.
	BaselineDirectory string
	// SourceCacheDirectory selects the host-owned parent for source caches and checkouts.
	SourceCacheDirectory string
	// InstanceID and DeploymentID bind the runtime directory to this Starport process.
	InstanceID   string
	DeploymentID string

	// Values retains the canonical settings that have no gateway-specific projection.
	Values map[string]string

	// AppliedPolicyChecksum identifies the shared configuration revision that
	// this process applied. A shared fleet refuses the refresh lease when it
	// differs from the applied fleet policy. Empty leaves the lease unfenced.
	AppliedPolicyChecksum string

	// PermissionClock contains the canonical host bounds. The runtime owns its monitor.
	PermissionClock profile.Config

	// 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 sets the polling interval for the source.
	SourcePollInterval time.Duration

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

	// SourceAuthorityID pins the authority used by require_authority.
	SourceAuthorityID string

	// SourcePolicyID pins the permission policy within the selected authority.
	SourcePolicyID string

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

	// SourceMaxHops bounds the publication chain.
	SourceMaxHops int

	// AcquisitionEnabled controls automatic observations. Explicit refresh still checks network and authority policy.
	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.
	// Changing this address does not change the durable runtime identity.
	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
}

Settings contains the catalog values one connected runtime reads. It mirrors the canonical Starmap settings with plain Go types. The configuration package names no Starmap options. This package owns the translation.

func (Settings) HasRetainedInstallation added in v1.3.0 

func (s Settings) HasRetainedInstallation(ctx context.Context, store storage.KVStore) (bool, error)

HasRetainedInstallation checks catalog markers before startup creates new state.

func (Settings) InspectCredentialPolicy added in v1.3.0 

func (s Settings) InspectCredentialPolicy(ctx context.Context, directory string) error

InspectCredentialPolicy validates retained acquisition policy without writes or credential access. The caller must fence writers and verify the complete inventory around inspection.

func (Settings) InspectCredentialPolicyPublications added in v1.3.0 

func (s Settings) InspectCredentialPolicyPublications(ctx context.Context, files map[string]productfiles.RetainedFile, read productfiles.RetainedRecordReader) ([]string, error)

InspectCredentialPolicyPublications selects publication evidence for inactive retention. The caller preserves selected bytes and validates the remaining policy before publication.

func (Settings) InspectRetainedDirectory added in v1.3.0 

func (s Settings) InspectRetainedDirectory(ctx context.Context, directory string) error

InspectRetainedDirectory validates runtime identity and retained inputs without activation. The caller must fence writers and verify the complete inventory around inspection. This check does not approve replica reuse, current permission, or admission.

func (Settings) InspectRetainedMigration added in v1.3.0 

func (s Settings) InspectRetainedMigration(ctx context.Context, originalDirectory string, read func(context.Context, string, int64) ([]byte, error)) ([]string, error)

InspectRetainedMigration selects completed path-bound records to retain as inactive history. Paths identify the captured host only. The caller must verify the remaining runtime tree.

func (Settings) InspectRetainedPublications added in v1.3.0 

func (s Settings) InspectRetainedPublications(ctx context.Context, files map[string]RetainedFile, read func(context.Context, string, int64) ([]byte, error)) ([]string, error)

InspectRetainedPublications selects native staging evidence that must remain inactive. The caller preserves the selected bytes and validates all remaining runtime records.

func (Settings) PrepareRecoveryTopologyDirectory added in v1.3.0 

func (s Settings) PrepareRecoveryTopologyDirectory(ctx context.Context) error

PrepareRecoveryTopologyDirectory establishes stopped native owner state before the host seals activation. It reads no external catalog and issues no permission. Sealed restart paths must use passive inspection.

func (Settings) RecoveryTopologyTarget added in v1.3.0 

func (s Settings) RecoveryTopologyTarget() (TopologyRuntimeTarget, []runtime.Option, error)

RecoveryTopologyTarget parses current target policy without constructing a connected runtime. It starts no source transport, acquisition, or clock monitor. Passive collectors preserve the same canonical acquisition capabilities for semantic replay.

func (Settings) ValidateStorageSelection added in v1.3.0 

func (s Settings) ValidateStorageSelection(ctx context.Context) error

ValidateStorageSelection refuses a conflicting catalog owner before gateway stores open. The runtime repeats ownership validation under its directory lock during startup.

type SnapshotMetadata added in v1.1.0 

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"`
}

SnapshotMetadata is the freshness surface of the active catalog snapshot. The scalar identity always comes from the snapshot itself. Manifest detail comes from the stored generation record; when that record is missing the metadata says so instead of silently omitting fields.

type SnapshotSource added in v1.1.0 

type SnapshotSource interface {
	Current() *RoutableSnapshot
}

SnapshotSource supplies the active routable snapshot.

type Source 

type Source interface {
	CurrentCatalogState() starmap.CatalogState
}

Source supplies one atomic Starmap catalog and generation pair.

type SourceObservation added in v1.1.0 

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

SourceObservation reports one acquisition source that fed the generation.

type Summary added in v1.2.1 

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"`
}

Summary is the allowlisted catalog view of a reader that holds no admin scope. It is an allowlist and not a redaction: a field reaches it only because this projection names it, so a new operational value on the admin status never appears here by accident.

It carries no source address, no source identity, no publication chain, no lease, no run identifier, no failure reason, and no operation.

type TopologyCapsule added in v1.3.0 

type TopologyCapsule struct {
	Generation       catalogs.Generation     `json:"generation"`
	Recovery         runtime.CatalogRecovery `json:"recovery"`
	SourceOrigin     string                  `json:"source_origin"`
	SourceDescriptor []byte                  `json:"source_descriptor,omitempty"`
}

TopologyCapsule preserves original reconstruction settings inside Recovery. SourceDescriptor contains the exact source descriptor, never a target configuration substitute.

func (TopologyCapsule) Format added in v1.3.0 

func (c TopologyCapsule) Format(state fmt.State, _ rune)

Format omits the private descriptor and reconstruction bytes.

type TopologyDirection added in v1.3.0 

type TopologyDirection string

TopologyDirection names the supported catalog ownership changes. 

const (
	TopologyLocalToFleet TopologyDirection = "local-to-fleet"
	TopologyFleetToLocal TopologyDirection = "fleet-to-local"
	TopologyLocalRestore TopologyDirection = "local-restore"
	TopologyFleetRestore TopologyDirection = "fleet-restore"
)

Supported topology changes preserve separate source and destination ownership.

func DeriveRecoveryTopologyDirection added in v1.3.0 

func DeriveRecoveryTopologyDirection(ctx context.Context, source *recovery.RestoreSource, destinationFleet bool) (direction TopologyDirection, resultErr error)

DeriveRecoveryTopologyDirection reads the original catalog ownership from the verified backup. The destination storage owner supplies its fleet selection. This read grants no target permission.

type TopologyExpiringTarget added in v1.3.0 

type TopologyExpiringTarget interface {
	ApplyExpiringCatalogTopology(context.Context, string, int, []storage.TransferRecord) error
}

TopologyExpiringTarget retires exact original expiring controls through their native import owner. It never renews or creates a record. The owner checks native expiry, claim, cursor, and incarnation. The catalog compiler and target keep this operation separate from persistent CAS.

type TopologyInventory added in v1.3.0 

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

TopologyInventory retains checked source facts privately. It grants no serving permission.

func CaptureTopologyInventory added in v1.3.0 

func CaptureTopologyInventory(ctx context.Context, source *recovery.KVSnapshotView, boundary recovery.Record, selection TopologySelection, capsules []TopologyCapsule) (*TopologyInventory, error)

CaptureTopologyInventory checks source selection and every retained generation against exact capsules. It opens no runtime. Callers must supply the exact original producer-owned descriptor census. A KV snapshot proves generation coverage. It cannot prove that a local descriptor census is complete.

func (TopologyInventory) Format added in v1.3.0 

func (i TopologyInventory) Format(state fmt.State, _ rune)

Format omits private catalog inputs from diagnostics.

type TopologyMaterialization added in v1.3.0 

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

TopologyMaterialization binds actual producer retention and target semantic replay. Callers cannot replace its private state with digest-only success reports.

func (TopologyMaterialization) Format added in v1.3.0 

func (p TopologyMaterialization) Format(state fmt.State, _ rune)

Format omits native identities and private receipt evidence.

func (*TopologyMaterialization) Record added in v1.3.0 

func (p *TopologyMaterialization) Record() ([]byte, error)

Record exports bounded private evidence for the recovery owner's immutable journal. It contains no catalog bytes, raw credentials, or storage mutation authority.

type TopologyPermission added in v1.3.0 

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

TopologyPermission retains original native permission evidence for a checked transfer. It grants no catalog selection, permission renewal, or admission authority.

func (*TopologyPermission) Digest added in v1.3.0 

func (p *TopologyPermission) Digest() string

Digest identifies original evidence. It does not replace native owner checks.

func (TopologyPermission) Format added in v1.3.0 

func (TopologyPermission) Format(state fmt.State, _ rune)

Format excludes native identities and private runtime paths from diagnostics.

func (*TopologyPermission) Record added in v1.3.0 

func (p *TopologyPermission) Record() ([]byte, error)

Record returns a private copy for the coordinator's immutable activation decision.

type TopologyReference added in v1.3.0 

type TopologyReference struct {
	ManifestSHA256         string `json:"manifest_sha256"`
	InputsSHA256           string `json:"inputs_sha256"`
	SourceDescriptorSHA256 string `json:"source_descriptor_sha256"`
}

TopologyReference names exact catalog and reconstruction evidence, including its original descriptor.

func (TopologyReference) Format added in v1.3.0 

func (r TopologyReference) Format(state fmt.State, _ rune)

Format omits private reconstruction identities.

type TopologyRuntimeTarget added in v1.3.0 

type TopologyRuntimeTarget struct {
	Directory         string
	Owner             runtime.DirectoryOwner
	SchedulerIdentity string
}

TopologyRuntimeTarget selects the existing stopped producer-owned input directory. It does not copy captured target settings or establish new serving authority.

func (TopologyRuntimeTarget) Format added in v1.3.0 

func (t TopologyRuntimeTarget) Format(state fmt.State, _ rune)

Format omits the selected private runtime directory.

type TopologySelection added in v1.3.0 

type TopologySelection struct {
	Accepted         TopologyReference   `json:"accepted"`
	Candidate        TopologyReference   `json:"candidate"`
	CapsuleInventory []TopologyReference `json:"capsule_inventory"`
}

TopologySelection distinguishes accepted serving facts from the latest candidate. CapsuleInventory must come from the complete original producer-owned retained-input census. Callers cannot substitute an arbitrary operator-supplied census.

func (TopologySelection) Format added in v1.3.0 

func (s TopologySelection) Format(state fmt.State, _ rune)

Format omits private selection and inventory evidence.

type TopologyTarget added in v1.3.0 

type TopologyTarget interface {
	ReadCatalogTopology(context.Context, string, int) ([]byte, error)
	CompletedCatalogTopology(context.Context, string, int) (bool, error)
	ApplyCatalogTopology(context.Context, string, int, []storage.CompareAndSwapMutation) error
}

TopologyTarget applies catalog-owned changes under the exact closed native import. Reads and mutations must bind the same native cursor. External writer fencing remains required. A committed native receipt must survive a later cross-store guard failure for exact retry.

type TopologyTransferRequest added in v1.3.0 

type TopologyTransferRequest struct {
	Direction              TopologyDirection         `json:"direction"`
	Operation              recovery.RestoreOperation `json:"operation"`
	DestinationBoundary    recovery.Record           `json:"destination_boundary"`
	DestinationIdentity    runtime.FleetIdentity     `json:"destination_identity"`
	AcceptedDecisionSHA256 string                    `json:"accepted_decision_sha256"`
	ClosedImportSHA256     string                    `json:"closed_import_sha256"`
}

TopologyTransferRequest supplies domain decisions, not catalog storage mutations. DestinationBoundary remains closed. Its identity differs from archived source identity. A prepared SQL boundary can omit BackendID until final activation. The host must verify DestinationIdentity against the destination native incarnation before release.

func (TopologyTransferRequest) Format added in v1.3.0 

func (r TopologyTransferRequest) Format(state fmt.State, _ rune)

Format omits private accepted decisions and fencing evidence.

type UpstreamProvenance added in v1.2.1 

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"`
}

UpstreamProvenance is what the source said about the generation it published. It stays separate from the effective provenance, because this runtime composes its own generation over the one it received.

type ValidationSummary added in v1.1.0 

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

ValidationSummary condenses the generation validation report for operators.

Source Files

View all Source files

Directories

Path Synopsis
Package disclosure intersects account and key catalog visibility.
 Package disclosure intersects account and key catalog visibility.
Package logos serves the bundled catalog identity marks.
 Package logos serves the bundled catalog identity marks.
Package view owns the console- and API-facing projections of one routable catalog snapshot.
 Package view owns the console- and API-facing projections of one routable catalog snapshot.

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.