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

runtime

package
v0.17.2 Latest Latest
Warning

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

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

README

Connected catalog runtime

WithPermissionClockMonitor gives one unstarted clock monitor to the runtime. Open starts observations before source startup. A failed Open cancels any monitor it started. Close joins the monitor worker within the runtime shutdown bound. Cached permission checks query no source.

Choose a managed monitor or an external clock callback. An origin can share the managed monitor's Read method for receipt issuance. PermissionClockStatus exposes local diagnostics. Public endpoints must redact the last observation error. Canonical host settings and native profile qualification remain separate from this library lifecycle contract.

An authoritative stored catalog requires origin configuration or require_authority at startup. Removing those settings cannot convert the catalog to ordinary mode, even with a new runtime directory. The startup error preserves the stored generation. Restore the intended authority configuration before restarting.

An explicit authority change requires a runtime restart with the new source, authority ID, and policy ID. WithSourceAuthority supplies the explicit identity selection. A changed authority or policy starts a new permission context. The previous catalog remains available for diagnostics. Its approval cannot authorize the new context, including after restart.

The replacement authority must supply its own verified catalog and current permission receipt before inference can resume. Its complete catalog supplies its alias inventory. Alias history remains mandatory for updates within the same authority and policy. A failed catalog commit preserves the previous catalog and blocks inference. Restart recovers the pending input publication before another refresh.

An origin cannot rename its established authority or policy in place. Select a separate catalog store for a new origin identity. Subscribers must then explicitly select that identity. Clearing origin settings does not authorize ordinary startup against the old store.

WithFleetStore selects shared catalog storage and refresh ownership as one contract. WithFleetAuthorityOrigin also selects that store for authority publication and independent permission-head reads. The host supplies the adapter and qualifies its atomic commit, native lease expiry, and recovery identity. The runtime does not select a backend from these options.

Each fleet publication retains its acquisition inputs with the catalog, outside the leader's private directory. A follower reconstructs those inputs before it can take refresh ownership. The baseline, acquisition policy, declared source capabilities, and retained source identity must match. An incompatible follower can read an accepted catalog, but cannot take refresh ownership. FleetStatus reports the accepted head and replay readiness from memory.

Fleet followers check the accepted head every 30 seconds, including while public source polling is off or a generation pin is active. An unchanged head causes no full catalog or input read. RefreshFleet checks the head after a notification or reconnect. A known head cannot regress or change its recovery identity during the runtime's lifetime.

Before acquisition, the runtime captures the holder, process session, lease epoch, and approved recovery identity. The backend compares that original grant and predecessor in the same transaction that selects the catalog and recovery reference. A retry cannot substitute a newer grant. The publication revision also advances when inputs change without a catalog change.

A pin acceptance travels with the shared publication. A replacement process can recover that receipt and the inputs needed for an explicit unpin after local directory loss. Catalog recovery does not supply inference permission. An authoritative subscriber must separately validate its permission receipt, and a known withdrawal remains effective after catalog reload.

The separate WithLeaseStore option preserves the earlier lease interface for existing adapters. It does not provide the atomic fleet publication and recovery contract. An origin with that option polls accepted authority state every 30 seconds and requires matching local inputs before takeover.

runtime

import "github.com/agentstation/starmap/runtime"

Package runtime holds the connected catalog runtime. It opens a Starmap client, reads verified upstream generations from one source, publishes each accepted generation, and reports the operator-facing status of that work.

The default source is the attested public GitHub channel. A caller that opens the runtime accepts the signature verification and the network reads that this channel needs. The root starmap package stays the offline library.

Index

Constants

These bounds apply independently to raw capsule bytes, decoded recovery bytes, and input count.

const (
    MaxCatalogRetentionBatchBytes  = storage.DefaultRetentionInputMaxBytes
    MaxCatalogRetentionBatchInputs = storage.DefaultRetentionScanEntries
)

Lease timing. One holder renews well inside the expiry, so a short pause never drops the lease and a stopped holder expires quickly.

const (
    // LeaseTTL bounds how long one lease stays valid without a renewal.
    LeaseTTL = 90 * time.Second

    // LeaseRenewInterval is the period between renewals.
    LeaseRenewInterval = 30 * time.Second
)

Transfer and refresh defaults. They match the canonical CATALOG_TRANSFER_* and CATALOG_REFRESH_TIMEOUT settings.

const (
    // DefaultTransferIdleTimeout bounds a stalled transfer.
    DefaultTransferIdleTimeout = 2 * time.Minute

    // DefaultTransferMaxDuration bounds one whole transfer.
    DefaultTransferMaxDuration = 60 * time.Minute

    // DefaultRefreshTimeout is zero, so a refresh carries no deadline of its
    // own. Transfer bounds and caller cancellation stop a stalled run.
    DefaultRefreshTimeout time.Duration = 0

    // DefaultCoalesceWindow bounds how long completed provider observations
    // wait for a slower sibling before they publish.
    DefaultCoalesceWindow = 30 * time.Second
)

Source policy defaults. They match the canonical CATALOG_SOURCE_* settings.

const (
    // DefaultSourceRepository is the public catalog repository.
    DefaultSourceRepository = "agentstation/starmap"

    // DefaultSourceChannel is the mutable branch that names the current
    // immutable catalog release.
    DefaultSourceChannel = artifact.PublicationChannelName

    // DefaultSourcePollInterval is how often the runtime checks the channel.
    DefaultSourcePollInterval = time.Hour

    // DefaultSourceMaxAge is the age at which a served catalog is stale.
    DefaultSourceMaxAge = 6 * time.Hour

    // DefaultSourceMaxHops bounds a cascade of Starmap runtimes.
    DefaultSourceMaxHops = 8

    // MaxSourceAliases bounds the declared alias list. A deployment names a
    // few addresses of one node, so a longer list is a configuration error.
    MaxSourceAliases = 16

    // MaxSourceAliasBytes bounds one declared alias.
    MaxSourceAliasBytes = 128
)

Freshness thresholds. They follow the four-hour publication cadence, the one-hour channel poll, and the six-hour end-to-end objective.

const (
    // FreshnessChannelWarnAge is the served-catalog age that warns. A source
    // maximum age above zero replaces it, unless the caller supplies an
    // explicit freshness policy.
    FreshnessChannelWarnAge = 6 * time.Hour

    // FreshnessChannelCriticalAge is the served-catalog age that is critical.
    // A source maximum age above zero replaces it with the scaled age, unless
    // the caller supplies an explicit freshness policy.
    FreshnessChannelCriticalAge = 10 * time.Hour

    // FreshnessSourceCheckWarnAge is the source-check age that warns.
    FreshnessSourceCheckWarnAge = 90 * time.Minute

    // FreshnessSourceCheckCriticalAge is the source-check age that is critical.
    FreshnessSourceCheckCriticalAge = 2 * time.Hour

    // FreshnessAcquisitionWarnAge is the acquisition-success age that warns.
    FreshnessAcquisitionWarnAge = 5 * time.Hour

    // FreshnessAcquisitionCriticalAge is the acquisition-success age that is
    // critical.
    FreshnessAcquisitionCriticalAge = 8 * time.Hour
)

Fallback reasons. They say why the runtime still serves the verified embedded catalog instead of an upstream generation.

const (
    // FallbackNone means an upstream generation is active.
    FallbackNone = ""

    // FallbackAwaitingSource means no upstream reply arrived yet.
    FallbackAwaitingSource = "awaiting_source"

    // FallbackSourceUnavailable means every source read failed so far.
    FallbackSourceUnavailable = "source_unavailable"
)

Source kinds. Selection is terminal, so a deployment that names a custom source never falls back to the public GitHub channel.

const (
    // SourcePublic reads the attested public GitHub catalog channel.
    SourcePublic = status.SourcePublic

    // SourceGitHub reads an attested channel from a named repository.
    SourceGitHub = status.SourceGitHub

    // SourceStarmap reads from another Starmap runtime.
    SourceStarmap = status.SourceStarmap

    // SourceFile reads one immutable generation from a local path.
    SourceFile = status.SourceFile

    // SourceEmbedded pins the runtime to the verified embedded bootstrap.
    SourceEmbedded = status.SourceEmbedded
)

Freshness grades of one observed timestamp.

const (
    // FreshnessUnknown means no observation supports an evaluation yet.
    FreshnessUnknown = status.FreshnessUnknown

    // FreshnessCurrent means the age is inside every threshold.
    FreshnessCurrent = status.FreshnessCurrent

    // FreshnessWarn means the age passed the warning threshold.
    FreshnessWarn = status.FreshnessWarn

    // FreshnessCritical means the age passed the critical threshold.
    FreshnessCritical = status.FreshnessCritical
)

Health states of one runtime component.

const (
    // HealthUnknown means the component has not reported yet.
    HealthUnknown = status.HealthUnknown

    // HealthOK means the component reached its last objective.
    HealthOK = status.HealthOK

    // HealthDegraded means the component works with reduced evidence.
    HealthDegraded = status.HealthDegraded

    // HealthUnavailable means the component cannot reach its dependency.
    HealthUnavailable = status.HealthUnavailable
)

Acquisition policy defaults. Acquisition has exactly two settings: whether it runs, and how often. No start-time or mode setting exists.

const (
    // DefaultAcquisitionInterval is the acquisition period.
    DefaultAcquisitionInterval = 4 * time.Hour
)

FleetRecoveryOriginVersion identifies the explicit closed-import evidence schema.

const FleetRecoveryOriginVersion = 1

MaxCatalogRetentionRecordBytes bounds encoded and decoded original retention envelopes. JSON encoding can expand raw capsule bytes to twice the raw input bound.

const MaxCatalogRetentionRecordBytes = maxRetainedCatalogRecordBytes

MaxFleetRecoveryBytes bounds both encoded and decoded private inputs for one fleet publication.

const MaxFleetRecoveryBytes = storage.DefaultRetentionInputMaxBytes

func CatalogRecoveryChecksums

func CatalogRecoveryChecksums(ctx context.Context, path string, owner DirectoryOwner, identity string, generation catalogs.Generation) ([]string, error)

CatalogRecoveryChecksums lists immutable input-record identities for an exact generation. These checksums name compressed local descriptors, not exported FleetRecovery bytes. The caller must fence writers. Multiple results require an explicit selection. Listing never proves which publication committed or whether independent history is complete.

func CheckRetainedCatalogRecovery

func CheckRetainedCatalogRecovery(ctx context.Context, request CatalogRetainedReadRequest, comparison *CatalogRetentionComparison) (resultErr error)

CheckRetainedCatalogRecovery compares current retained bytes with checked original input. It checks the native owner, completed batch, manifest, exact entry, and bounded envelope hash. It does not decode unchanged input, repair files, select a catalog, or establish current permission.

func InspectCapturedCatalogRetention

func InspectCapturedCatalogRetention(ctx context.Context, name string, raw []byte) (CatalogRetentionEntry, CatalogRetentionInput, error)

InspectCapturedCatalogRetention checks original immutable envelope bytes without opening a runtime. It checks structure and generation identity. It proves no completed batch, selection, ownership, or permission. The host must verify the complete original archive census and publication records separately.

func InspectRetainedCatalogMaterialization

func InspectRetainedCatalogMaterialization(ctx context.Context, request CatalogRetainedMaterializationRequest, expected CatalogMaterializationReceipt, opts ...Option) (resultErr error)

InspectRetainedCatalogMaterialization verifies the current pre-activation input selection. It requires existing complete journals, exact batch coverage, and compatible target settings. A later input update refuses this check. Historical completed retries still return their original receipt. Inspection never repairs records, changes selection, or renews permission.

func InspectRetainedDirectory

func InspectRetainedDirectory(ctx context.Context, path string, owner DirectoryOwner, identity string) error

InspectRetainedDirectory validates private runtime records without opening a runtime. The caller must fence writers and verify the complete inventory around inspection. This check preserves identity and replay evidence. It does not approve replica reuse, deployment settings, accepted-catalog consistency, permission freshness, or admission. Path-bound migration records require their separate recovery procedure.

func InspectRetainedMigration

func InspectRetainedMigration(ctx context.Context, originalDirectory string, owner DirectoryOwner, identity string, read RetainedRecordReader) ([]string, error)

InspectRetainedMigration identifies completed migration records to keep inactive during restore. The caller supplies the captured directory name, configured owner and explicit scheduler identity. Paths in historical records are opaque identities. This check never opens those paths. The caller must verify the complete backup and the remaining runtime tree separately. This result does not approve current permission, external fencing, or replica reuse.

func InspectRetainedPublications

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

InspectRetainedPublications selects native journals and matching staging files to keep inactive. The caller must supply the complete verified runtime inventory and preserve all selected bytes. Destination records remain active and require separate owner validation. This check never promotes staging files. Native file identities are historical. This result does not authorize cleanup or admission.

func PrepareAcquisitionReplay

func PrepareAcquisitionReplay(ctx context.Context, baseline catalogs.Generation, publisherID string, bindings []sources.ProviderAcquisitionBinding, observations []sources.Observation, runID string, completedAt time.Time) (catalogs.Generation, []sources.Observation, error)

PrepareAcquisitionReplay returns a catalog generation and the original inputs needed for later replay. It retains compacted inputs only when catalog facts, provenance, membership, and current reviews remain exact. Current metadata reviews retain their latest original observation. Omission preserves the last review.

The retained inputs must fit the retained payload bound. The supplied history can exceed it. The caller authenticates the baseline and inputs. This function reads no sources or storage.

func PrepareCatalogRecoveryDirectory

func PrepareCatalogRecoveryDirectory(ctx context.Context, path string, owner DirectoryOwner, identity string) (resultErr error)

PrepareCatalogRecoveryDirectory establishes private owner, seed, and empty layer directories. It opens no runtime, reads no catalog source, and creates no selection or permission. Existing owner and seed records must match. Missing records in retained state require recovery. An already selected materialization requires passive inspection instead of preparation.

The host must fence writers and call this only before sealing its native activation decision. Restart paths must inspect the retained directory instead of invoking preparation.

func ReplayAcquisition

func ReplayAcquisition(ctx context.Context, baseline catalogs.Generation, publisherID string, bindings []sources.ProviderAcquisitionBinding, observations []sources.Observation) (*starmap.Candidate, error)

ReplayAcquisition rebuilds an ordered observation history above an explicit baseline. The caller authenticates the baseline and observations, and selects the active bindings. The baseline can contain this publisher's prior scopes but cannot carry enterprise authority. This function reads no sources or storage and starts no runtime workers.

func ValidateCatalogReplay

func ValidateCatalogReplay(ctx context.Context, generation catalogs.Generation, recovery CatalogRecovery, opts ...Option) error

ValidateCatalogReplay checks exact retained inputs against the supplied deployment settings. It starts no acquisition, writes, clock observation, or lease operation. Success grants no serving permission and does not prove independent recovery history.

func ValidateDirectoryPermissions

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

ValidateDirectoryPermissions checks existing runtime identity paths without writes. Linux and macOS require the effective UID and no group or other mode bits. macOS also restricts ACL grants to the owner. Deny entries remain valid. Windows requires the process account owner and limits grants to that account, SYSTEM, and Administrators.

Linux and macOS also check ancestor ownership, directory-entry protection, and selected symlink routes. Windows also checks ancestor DACLs and selected symlink routes. Effective access and native Windows execution require separate qualification. Other platforms check file types only. Windows native qualification remains required.

An empty directory selects in-memory state. Missing paths remain absent.

func ValidateFleetRecovery

func ValidateFleetRecovery(ctx context.Context, snapshot FleetSnapshot) error

ValidateFleetRecovery checks retained input structure without opening a runtime. It grants no permission and does not check compatibility with deployment settings.

func ValidateFleetReplay

func ValidateFleetReplay(ctx context.Context, snapshot FleetSnapshot, opts ...Option) error

ValidateFleetReplay reproduces a retained catalog under the supplied runtime settings. It starts no runtime, acquisition, clock observation, filesystem access, or lease. Successful validation does not renew a receipt or authorize an inference attempt.

func VerifyDirectoryMigrationPublication

func VerifyDirectoryMigrationPublication(ctx context.Context, request DirectoryMigrationRequest) error

VerifyDirectoryMigrationPublication verifies publication before a host opens the target. It verifies the source inventory, journal, receipts, owner, and seed without starting a runtime. Journal recovery can preserve and truncate an interrupted final event.

type Acquirer

Acquirer collects provider observations for the runtime. The root package selects no concrete provider client, so the deployment injects this role. Package acquisition supplies the built-in composition.

type Acquirer interface {
    AcquireProviders(ctx context.Context, request AcquisitionRequest) (AcquisitionResult, error)
}

type AcquisitionPolicy

AcquisitionPolicy configures all scheduled acquisition. The policy is exactly one switch and one period.

type AcquisitionPolicy struct {
    // Enabled reports whether scheduled acquisition runs.
    Enabled bool

    // Interval is the acquisition period. The scheduler places each instance
    // at a stable phase inside the interval. Zero means one startup pass and
    // no periodic work.
    Interval time.Duration
}

func DefaultAcquisitionPolicy
func DefaultAcquisitionPolicy() AcquisitionPolicy

DefaultAcquisitionPolicy returns the canonical acquisition policy.

func (AcquisitionPolicy) Validate
func (p AcquisitionPolicy) Validate() error

Validate checks the acquisition period. Zero is valid and selects one startup pass, so an operator schedules a single run without a cadence.

type AcquisitionReport

AcquisitionReport says what one acquisition run produced. A partial failure still publishes: the report names the providers that kept their own last-known-good observation.

type AcquisitionReport struct {
    // RunID is the identity of the run that produced this report.
    RunID string

    // StartedAt and CompletedAt bound the run.
    StartedAt   time.Time
    CompletedAt time.Time

    // Eligible counts provider targets, or bindings when the active set is explicit.
    Eligible int

    // Succeeded, Skipped, and Failed count the terminal attempts.
    Succeeded int
    Skipped   int
    Failed    int

    // Attempts holds one terminal attempt per eligible provider or binding.
    Attempts []sources.ProviderAttempt

    // SourceObservations binds each non-provider result to its original receipt.
    SourceObservations []catalogs.SourceObservationLink

    // SourceActivities holds the reported selection and attempts for this run.
    SourceActivities []sources.SourceActivity

    // Published reports whether the runtime published a new effective catalog.
    Published bool

    // GenerationID identifies the published effective catalog.
    GenerationID string

    // Retained names the providers that kept their previous last-known-good
    // observation in at least one scope that this run did not replace.
    Retained []catalogs.ProviderID

    // Health grades the run. A failed provider degrades the run.
    Health Health
}

type AcquisitionRequest

AcquisitionRequest describes one provider acquisition run.

type AcquisitionRequest struct {
    // RunID is the run identity that logs and status report.
    RunID string

    // Current is the immutable catalog the run starts from.
    Current *catalogs.Catalog

    // Providers restricts the run. An empty list observes every eligible
    // provider.
    Providers []catalogs.ProviderID

    // CoalesceWindow bounds how long completed observations wait for a slower
    // sibling before they publish.
    CoalesceWindow time.Duration

    // Publish emits the layers that completed inside one coalescing window.
    // The runtime retains them, rebuilds the effective catalog, and publishes
    // one generation under the lease epoch of the run. An acquirer that emits
    // nothing early leaves the field unused, and the runtime then publishes
    // every layer once the run returns.
    Publish func(context.Context, []ProviderLayer) error
}

type AcquisitionResult

AcquisitionResult is what one acquisition run observed.

type AcquisitionResult struct {
    // Eligible counts provider targets, or bindings when the active set is explicit.
    Eligible int

    // Attempts holds one terminal attempt per eligible provider or binding.
    Attempts []sources.ProviderAttempt

    // Layers holds one successful observation per provider or binding.
    Layers []ProviderLayer
}

type BaselinePromotion

BaselinePromotion selects the packaged baseline at one observed fleet head.

type BaselinePromotion struct {
    // ExpectedHead is the accepted publication that the operator reviewed.
    ExpectedHead FleetHead
    // PackagedGenerationID must name the embedded baseline of this binary.
    PackagedGenerationID string
}

type BaselinePromotionResult

BaselinePromotionResult describes one accepted baseline promotion.

type BaselinePromotionResult struct {
    // Head is the fleet publication that retains the promoted baseline.
    Head FleetHead
    // Previous identifies the retained baseline before promotion.
    Previous catalogs.GenerationIdentity
    // Promoted identifies the packaged baseline that the fleet now retains.
    Promoted catalogs.GenerationIdentity
    // InertRemovals lists retained removal targets that match nothing in the promoted catalog.
    // They stay recorded until an explicit removal edit replaces them.
    InertRemovals []catalogs.CatalogRemovalTarget
}

type BaselineStatus

BaselineStatus compares this binary's packaged baseline with the fleet's retained baseline.

type BaselineStatus struct {
    // Packaged identifies the embedded baseline compiled into this binary.
    Packaged catalogs.GenerationIdentity
    // Retained identifies the baseline that the accepted fleet publication replays.
    Retained catalogs.GenerationIdentity
    // Head is the accepted fleet publication that this replica observed.
    Head FleetHead
    // Promotable reports whether PromoteEmbeddedBaseline can adopt Packaged at Head.
    // It does not establish lease ownership.
    Promotable bool
    // Refusal explains why promotion is unavailable. It is empty when Promotable is true.
    Refusal string
}

type BindingAcquirer

BindingAcquirer observes only the supplied active declarations. It must preserve each declaration from credential selection through its receipt. Implementations also implement Acquirer for runtime injection.

type BindingAcquirer interface {
    AcquireProviderBindings(context.Context, AcquisitionRequest, []sources.ProviderAcquisitionBinding) (AcquisitionResult, error)
}

type CapturedCatalogBinding

CapturedCatalogBinding identifies the retained generation that the host must independently verify.

type CapturedCatalogBinding struct {
    ManifestChecksum string
    GenerationID     string
    PayloadChecksum  string
}

type CapturedCatalogRecovery

CapturedCatalogRecovery holds structurally checked original descriptor and baseline inputs. It proves no archive completeness, publication, target ownership, semantics, or permission.

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

func InspectCapturedCatalogRecovery
func InspectCapturedCatalogRecovery(ctx context.Context, name string, descriptor []byte, readBaseline func(context.Context, string, int64) ([]byte, error)) (*CapturedCatalogRecovery, error)

InspectCapturedCatalogRecovery checks original archive bytes without opening a runtime directory. The host supplies a bounded reader for the original baseline and verifies the complete archive census. Historical inputs receive structural validation. Target replay and permission checks remain separate.

func (*CapturedCatalogRecovery) Binding
func (p *CapturedCatalogRecovery) Binding() CapturedCatalogBinding

Binding returns checked identity fields without exposing private source inputs.

func (*CapturedCatalogRecovery) Format
func (*CapturedCatalogRecovery) Format(state fmt.State, _ rune)

Format excludes private source configuration and baseline data from diagnostics.

func (*CapturedCatalogRecovery) RecoveryFor
func (p *CapturedCatalogRecovery) RecoveryFor(ctx context.Context, generation catalogs.Generation) (CatalogRecovery, error)

RecoveryFor binds the original inputs to an independently retained complete generation. It creates a separate encoded copy. It neither replays target state nor renews permission.

type CatalogMaterializationInput

CatalogMaterializationInput binds one retained generation to its exact reconstruction inputs. The caller retains catalog-store selection and authority evidence separately.

type CatalogMaterializationInput struct {
    Generation catalogs.Generation `json:"generation"`
    Recovery   CatalogRecovery     `json:"recovery"`
}

type CatalogMaterializationReceipt

CatalogMaterializationReceipt records completed private-file replacement without catalog-store activation. DirectoryIdentity binds native ownership. InventorySHA256 binds the supplied ordered historical inputs.

type CatalogMaterializationReceipt struct {
    Version                int                       `json:"version"`
    OperationID            string                    `json:"operation_id"`
    RequestSHA256          string                    `json:"request_sha256"`
    PlanSHA256             string                    `json:"plan_sha256"`
    InventorySHA256        string                    `json:"inventory_sha256"`
    DirectoryIdentity      privatefiles.EntryReceipt `json:"directory_identity"`
    SelectedManifestSHA256 string                    `json:"selected_manifest_sha256"`
    SelectedInputsSHA256   string                    `json:"selected_inputs_sha256"`
    CatalogPublisherID     string                    `json:"catalog_publisher_id"`
    BaselineManifestSHA256 string                    `json:"baseline_manifest_sha256"`
}

func MaterializeCatalogRecovery
func MaterializeCatalogRecovery(ctx context.Context, request CatalogMaterializationRequest, opts ...Option) (receipt CatalogMaterializationReceipt, resultErr error)

MaterializeCatalogRecovery replaces catalog inputs through a private operation journal. It preserves owner, instance seed, permission checkpoints, and origin discovery records. Pending work blocks runtime startup. An exact completed retry returns its original receipt without replacing later state.

func MaterializeRetainedCatalogRecovery
func MaterializeRetainedCatalogRecovery(ctx context.Context, request CatalogRetainedMaterializationRequest, opts ...Option) (CatalogMaterializationReceipt, error)

MaterializeRetainedCatalogRecovery checks complete retained coverage and selects one capsule. Only the selected capsule must reproduce its generation under the supplied target settings. Completed retries return the original receipt without loading or recreating old envelopes.

type CatalogMaterializationRequest

CatalogMaterializationRequest selects private catalog inputs for an existing stopped runtime. Selected is an index into Inputs. Each input must reproduce its generation under the supplied options. Writers must remain fenced throughout recovery. This API grants no publication or serving permission.

type CatalogMaterializationRequest struct {
    Directory         string                        `json:"directory"`
    Owner             DirectoryOwner                `json:"owner"`
    SchedulerIdentity string                        `json:"scheduler_identity"`
    OperationID       string                        `json:"operation_id"`
    Selected          int                           `json:"selected"`
    Inputs            []CatalogMaterializationInput `json:"inputs"`
}

type CatalogRecovery

CatalogRecovery binds retained private inputs to one complete catalog manifest. It records reconstruction evidence, not publication success or serving permission. Inputs use the same private encoding as fleet publications.

type CatalogRecovery struct {
    ManifestChecksum string        `json:"manifest_checksum"`
    Inputs           FleetRecovery `json:"inputs"`
}

func CaptureFleetCatalogRecovery
func CaptureFleetCatalogRecovery(ctx context.Context, snapshot FleetSnapshot) (CatalogRecovery, error)

CaptureFleetCatalogRecovery copies a validated fleet publication's private inputs. The result preserves the complete generation binding without inventing local ownership. The host must retain the original fleet selection and verify deployment settings separately.

func ReadCatalogRecovery
func ReadCatalogRecovery(ctx context.Context, path string, owner DirectoryOwner, identity string, generation catalogs.Generation, recordChecksum string) (CatalogRecovery, error)

ReadCatalogRecovery reads exact private inputs without opening a runtime. The caller must fence writers and supply an independently retained generation and record checksum. Missing history refuses recovery. Current directory inputs never replace missing historical inputs.

func (CatalogRecovery) Validate
func (r CatalogRecovery) Validate(generation catalogs.Generation) error

Validate checks the complete generation binding and bounded input bytes.

type CatalogRetainedMaterializationRequest

CatalogRetainedMaterializationRequest selects one entry from complete retained batch coverage. Batches must cover the full manifest once, in order, without gaps or overlaps.

type CatalogRetainedMaterializationRequest struct {
    Directory         string                  `json:"directory"`
    Owner             DirectoryOwner          `json:"owner"`
    SchedulerIdentity string                  `json:"scheduler_identity"`
    OperationID       string                  `json:"operation_id"`
    TransferID        string                  `json:"transfer_id"`
    Batches           []CatalogRetentionBatch `json:"batches"`
    Selected          int                     `json:"selected"`
}

type CatalogRetainedReadRequest

CatalogRetainedReadRequest selects one entry within an exact completed batch. Index is an absolute index in the complete transfer manifest.

type CatalogRetainedReadRequest struct {
    Directory         string                `json:"directory"`
    Owner             DirectoryOwner        `json:"owner"`
    SchedulerIdentity string                `json:"scheduler_identity"`
    TransferID        string                `json:"transfer_id"`
    Batch             CatalogRetentionBatch `json:"batch"`
    Index             int                   `json:"index"`
}

type CatalogRetainedRecord

CatalogRetainedRecord binds an immutable envelope to its manifest entry. Structural validation does not establish compatibility with current settings.

type CatalogRetainedRecord struct {
    Entry        CatalogRetentionEntry `json:"entry"`
    RecordSHA256 string                `json:"record_sha256"`
}

type CatalogRetentionBatch

CatalogRetentionBatch selects an exact retained batch completion receipt.

type CatalogRetentionBatch struct {
    OperationID   string `json:"operation_id"`
    ReceiptSHA256 string `json:"receipt_sha256"`
}

type CatalogRetentionComparison

CatalogRetentionComparison binds structurally checked original input to its canonical envelope. It retains private hashes and byte counts. It grants no ownership, selection, replay, or permission. Only InspectCatalogRetentionComparison can create a usable value.

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

func InspectCatalogRetentionComparison
func InspectCatalogRetentionComparison(ctx context.Context, entry CatalogRetentionEntry, input CatalogRetentionInput) (*CatalogRetentionComparison, error)

InspectCatalogRetentionComparison checks original input and binds its canonical compressed envelope. The result contains no original data and has no serialized constructor. This inspection writes no files and contacts no sources.

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

Format excludes private entry identities and envelope hashes from diagnostics.

func (*CatalogRetentionComparison) Usage
func (p *CatalogRetentionComparison) Usage() CatalogRetentionUsage

Usage returns the immutable byte counts from the original complete structural check. A nil or empty comparison returns zero counts.

type CatalogRetentionEntry

CatalogRetentionEntry binds original descriptor bytes and exported reconstruction inputs. InputsSHA256 is CatalogRecovery.Inputs.Checksum, not the local descriptor checksum.

type CatalogRetentionEntry struct {
    ManifestSHA256         string                 `json:"manifest_sha256"`
    InputsSHA256           string                 `json:"inputs_sha256"`
    SourceOrigin           CatalogRetentionOrigin `json:"source_origin"`
    SourceDescriptorSHA256 string                 `json:"source_descriptor_sha256"`
}

type CatalogRetentionInput

CatalogRetentionInput supplies exact historical bytes without current deployment settings. Local descriptors use the original compressed localCatalogRecovery representation. The host validates fleet descriptors against their original publication inventory.

type CatalogRetentionInput struct {
    CatalogMaterializationInput
    SourceDescriptor []byte `json:"source_descriptor"`
}

func ReadRetainedCatalogRecovery
func ReadRetainedCatalogRecovery(ctx context.Context, request CatalogRetainedReadRequest) (input CatalogRetentionInput, resultErr error)

ReadRetainedCatalogRecovery exports original historical bytes without selection or repair. It verifies the native owner, completed batch, manifest, and immutable envelope. Returned data belongs to the caller. Success confers no current permission.

type CatalogRetentionOrigin

CatalogRetentionOrigin identifies the supplied historical descriptor format. Descriptors remain evidence and confer no current permission.

type CatalogRetentionOrigin string

Descriptor origin values distinguish original bytes from explicitly absent evidence.

const (
    CatalogRetentionLocalDescriptor CatalogRetentionOrigin = "local-descriptor"
    CatalogRetentionFleetDescriptor CatalogRetentionOrigin = "fleet-publication"
    CatalogRetentionNoDescriptor    CatalogRetentionOrigin = "no-descriptor"
)

type CatalogRetentionReceipt

CatalogRetentionReceipt records structural retention without selection or serving permission. It binds one native directory, the full manifest, and an exact batch range.

type CatalogRetentionReceipt struct {
    Version           int                       `json:"version"`
    Validation        string                    `json:"validation"`
    OperationID       string                    `json:"operation_id"`
    TransferID        string                    `json:"transfer_id"`
    RequestSHA256     string                    `json:"request_sha256"`
    PlanSHA256        string                    `json:"plan_sha256"`
    ManifestSHA256    string                    `json:"manifest_sha256"`
    BatchStart        int                       `json:"batch_start"`
    DirectoryIdentity privatefiles.EntryReceipt `json:"directory_identity"`
    Records           []CatalogRetainedRecord   `json:"records"`
}

func RetainCatalogRecovery
func RetainCatalogRecovery(ctx context.Context, request CatalogRetentionRequest) (receipt CatalogRetentionReceipt, resultErr error)

RetainCatalogRecovery preserves original historical capsules through a private operation journal. Validation is structural only. Pending retention blocks startup and selection. An exact completed retry returns its receipt without recreating missing records or changing later state.

type CatalogRetentionRequest

CatalogRetentionRequest retains one contiguous batch from a complete transfer manifest. All batches share TransferID and Manifest, and use distinct OperationID values. Writers must remain fenced. This operation never changes the active catalog inputs.

type CatalogRetentionRequest struct {
    Directory         string                  `json:"directory"`
    Owner             DirectoryOwner          `json:"owner"`
    SchedulerIdentity string                  `json:"scheduler_identity"`
    OperationID       string                  `json:"operation_id"`
    TransferID        string                  `json:"transfer_id"`
    Manifest          []CatalogRetentionEntry `json:"manifest"`
    BatchStart        int                     `json:"batch_start"`
    Inputs            []CatalogRetentionInput `json:"inputs"`
}

type CatalogRetentionUsage

CatalogRetentionUsage contains immutable byte counts without catalog data or private identities. It grants no retention, selection, current permission, or target ownership.

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

func InspectCatalogRetentionUsage
func InspectCatalogRetentionUsage(ctx context.Context, entry CatalogRetentionEntry, input CatalogRetentionInput) (CatalogRetentionUsage, error)

InspectCatalogRetentionUsage checks one capsule through the producer's original codecs. Hosts can pack against both byte dimensions and the count bound without another decoder. RetainCatalogRecovery independently checks each final batch. This inspection writes no files and contacts no sources.

func (CatalogRetentionUsage) DecodedBytes
func (u CatalogRetentionUsage) DecodedBytes() int64

DecodedBytes counts the decompressed original recovery record before JSON parsing.

func (CatalogRetentionUsage) Inputs
func (u CatalogRetentionUsage) Inputs() int

Inputs reports the one structurally checked input. An empty result reports zero.

func (CatalogRetentionUsage) RawBytes
func (u CatalogRetentionUsage) RawBytes() int64

RawBytes counts the serialized manifest, payload, compressed recovery, and original descriptor bytes.

type DirectoryMigrationCompletion

DirectoryMigrationCompletion binds a completed move to its retained source and target.

type DirectoryMigrationCompletion struct {
    OperationID       string         `json:"operation_id"`
    SourceDirectory   string         `json:"source_directory"`
    TargetDirectory   string         `json:"target_directory"`
    SchedulerIdentity string         `json:"scheduler_identity"`
    Owner             DirectoryOwner `json:"owner"`
    ManifestSHA256    string         `json:"manifest_sha256"`
}

func ReadDirectoryMigrationCompletion
func ReadDirectoryMigrationCompletion(ctx context.Context, directory string) (DirectoryMigrationCompletion, error)

ReadDirectoryMigrationCompletion verifies completion and the preserved source without writing files. It requires the source inventory, retirement record, target receipts, owner, and seed to match. It does not read the operation journal or compare mutable target catalog layers.

type DirectoryMigrationPreparation

DirectoryMigrationPreparation identifies the retained inventory and its journal. IdentityVerified is false for legacy state without an ownership record.

type DirectoryMigrationPreparation struct {
    JournalDirectory string `json:"journal_directory"`
    Phase            string `json:"phase"`
    FileCount        int    `json:"file_count"`
    IdentityVerified bool   `json:"identity_verified"`
}

func PrepareDirectoryMigration
func PrepareDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationPreparation, error)

PrepareDirectoryMigration records source checksums under an exclusive directory lock. It preserves source files, creates no target, and leaves configured roots unchanged. SourceIdentity must come from the old deployment. Legacy seeds alone cannot prove it.

type DirectoryMigrationPublication

DirectoryMigrationPublication identifies the replacement and its migration phase. SchedulerIdentity must accompany the target directory in the replacement runtime's options.

type DirectoryMigrationPublication struct {
    JournalDirectory  string `json:"journal_directory"`
    TargetDirectory   string `json:"target_directory"`
    SchedulerIdentity string `json:"scheduler_identity"`
    Phase             string `json:"phase"`
}

func PublishDirectoryMigration
func PublishDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationPublication, error)

PublishDirectoryMigration stages and publishes a verified copy, then retires the source. It preserves source data files and does not edit host configuration or complete root selection. Older source binaries must stay stopped because they do not honor retirement records.

type DirectoryMigrationRequest

DirectoryMigrationRequest selects an explicit runtime-directory migration. Stop the source process before preparation, including older binaries without directory locks.

type DirectoryMigrationRequest struct {
    OperationID     string
    SourceDirectory string
    TargetDirectory string
    JournalRoot     string
    SourceIdentity  string
    Owner           DirectoryOwner
}

type DirectoryMigrationStage

DirectoryMigrationStage identifies a verified copy that cannot yet serve a runtime.

type DirectoryMigrationStage struct {
    JournalDirectory string `json:"journal_directory"`
    StageDirectory   string `json:"stage_directory"`
    Phase            string `json:"phase"`
    FileCount        int    `json:"file_count"`
    IdentityVerified bool   `json:"identity_verified"`
}

func StageDirectoryMigration
func StageDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationStage, error)

StageDirectoryMigration copies a stopped source into private staging and verifies its bytes. It preserves the source and leaves the selected target and configuration roots unchanged.

type DirectoryOwner

DirectoryOwner binds persistent runtime state to one product, deployment, and instance. This record does not replace the live directory lock or a shared identity fence.

type DirectoryOwner struct {
    Product    string `json:"product"`
    Deployment string `json:"deployment"`
    Instance   string `json:"instance"`
}

func (DirectoryOwner) Validate
func (o DirectoryOwner) Validate() error

Validate checks the ownership identity without creating files.

type FleetAcquisitionChecker

FleetAcquisitionChecker verifies access before grant acquisition or renewal. It must use acquisition credentials and must not fetch provider inventories.

type FleetAcquisitionChecker interface {
    CheckFleetAcquisition(context.Context, FleetAcquisitionRequirements) error
}

type FleetAcquisitionRequirements

FleetAcquisitionRequirements identifies the acquisition access a refresh owner must retain. Bindings declare scopes. Unbound providers retain the deployment's implicit acquisition policy. No credential value or credential digest belongs in this record.

type FleetAcquisitionRequirements struct {
    // Catalog contains reconciled provider metadata and need not match the serving catalog.
    Catalog *catalogs.Catalog
    // Providers contains retained scopes whose acquisition credentials remain required.
    Providers []catalogs.ProviderID
    // Candidates contains unobserved providers that can lack configured credentials.
    Candidates []catalogs.ProviderID
    Bindings   []sources.ProviderAcquisitionBinding
}

type FleetAdoption

FleetAdoption identifies explicit host recovery without changing the original publication ownership evidence. The host must verify the receipt and independent approval before exposing this snapshot. This record grants no refresh lease or inference permission.

type FleetAdoption struct {
    Previous FleetHead `json:"previous"`
    Receipt  string    `json:"receipt"`
}

type FleetHead

FleetHead identifies one accepted publication, including its private recovery inputs. Revision increases for every publication, even when the catalog generation stays unchanged. The zero value selects an empty store. A populated head cannot use revision zero.

type FleetHead struct {
    Identity         FleetIdentity `json:"identity"`
    Revision         uint64        `json:"revision"`
    GenerationID     string        `json:"generation_id"`
    RecoveryChecksum string        `json:"recovery_checksum"`
}

func (FleetHead) Validate
func (h FleetHead) Validate() error

Validate accepts an empty head or a complete publication identity.

type FleetIdentity

FleetIdentity binds operations to an independently approved backend incarnation. The host gets this identity from its recovery authority, outside the catalog store. An address or a record restored inside that backend cannot establish this identity.

type FleetIdentity struct {
    DeploymentID  string `json:"deployment_id"`
    RecoveryEpoch uint64 `json:"recovery_epoch"`
    BackendID     string `json:"backend_id"`
}

func (FleetIdentity) Validate
func (i FleetIdentity) Validate() error

Validate requires a complete identity. It does not establish external approval.

type FleetPublication

FleetPublication retains one refresh grant or explicit recovery origin and its predecessor. A retry preserves all fields. It must not substitute newer ownership evidence or a predecessor.

type FleetPublication struct {
    Generation     catalogs.Generation  `json:"generation"`
    Recovery       FleetRecovery        `json:"recovery"`
    Grant          Lease                `json:"grant"`
    Expected       FleetHead            `json:"expected"`
    RecoveryOrigin *FleetRecoveryOrigin `json:"recovery_origin,omitempty"`
}

func (FleetPublication) Validate
func (p FleetPublication) Validate() error

Validate checks retained publication content and structural ownership evidence. It does not establish independent recovery approval, live lease ownership, or serving permission. Ordinary commit adapters must use ValidateRefreshPublication before their native transaction.

func (FleetPublication) ValidateRefreshPublication
func (p FleetPublication) ValidateRefreshPublication() error

ValidateRefreshPublication refuses recovery imports through the ordinary refresh commit path. The backend must still compare the original live grant, expiry, approved identity, and head atomically.

type FleetRecovery

FleetRecovery binds private acquisition inputs to one immutable generation. Stores retain these bytes with the generation and never expose them as public catalog data. The runtime owns the encoding. Hosts preserve the bytes without modification.

type FleetRecovery struct {
    GenerationID    string `json:"generation_id"`
    PayloadChecksum string `json:"payload_checksum"`
    Checksum        string `json:"checksum"`
    Data            []byte `json:"data"`
}

func (FleetRecovery) Validate
func (r FleetRecovery) Validate(generation catalogs.Generation) error

Validate checks the generation binding and the complete input checksum. Runtime recovery separately validates the input schema and acquisition policy.

type FleetRecoveryOrigin

FleetRecoveryOrigin binds catalog facts to a host-owned closed recovery import. The host must independently verify the accepted decision and closed import before exposing the publication. These digests describe retained evidence. They grant no refresh lease, authority receipt, or inference permission.

type FleetRecoveryOrigin struct {
    Version                  int           `json:"version"`
    Identity                 FleetIdentity `json:"identity"`
    OperationID              string        `json:"operation_id"`
    AcceptedDecisionSHA256   string        `json:"accepted_decision_sha256"`
    ClosedImportSHA256       string        `json:"closed_import_sha256"`
    GenerationManifestSHA256 string        `json:"generation_manifest_sha256"`
    RecoverySHA256           string        `json:"recovery_sha256"`
}

type FleetSnapshot

FleetSnapshot retains the accepted publication and its original ownership evidence. Reading a snapshot proves neither a live grant nor independent recovery approval.

type FleetSnapshot struct {
    Head        FleetHead        `json:"head"`
    Publication FleetPublication `json:"publication"`
    Adoption    *FleetAdoption   `json:"adoption,omitempty"`
}

func (FleetSnapshot) Validate
func (s FleetSnapshot) Validate() error

Validate checks that the head selects exactly this publication and its recovery inputs.

type FleetStatus

FleetStatus describes the accepted publication and this replica's ability to replay its inputs. Replay readiness does not establish current lease ownership or inference permission.

type FleetStatus struct {
    Head             FleetHead
    ReplayReady      bool
    AcquisitionReady bool
}

type FleetStore

FleetStore owns shared publication, retained inputs, and refresh ownership. Hosts supply the adapter. Standalone stores keep the separate storage.Store contract. Each method uses one deployment namespace and the approved backend incarnation. New or recovered connections must validate that incarnation before application operations.

type FleetStore interface {
    LeaseStore

    // CurrentHead reads publication metadata without transferring catalog or recovery payloads.
    CurrentHead(context.Context) (FleetHead, error)

    // CurrentPublication reads the complete durable head and the exact selected bytes.
    // Missing immutable bytes or recovery inputs are errors, never an empty-store result.
    CurrentPublication(context.Context) (FleetSnapshot, error)

    // Publication retrieves one retained publication by its complete head identity.
    Publication(context.Context, FleetHead) (FleetSnapshot, error)

    // Get retrieves a retained immutable catalog without exposing recovery inputs.
    Get(context.Context, string) (catalogs.Generation, error)

    // CommitPublication selects a refresh publication and recovery reference in one backend transaction.
    // It refuses RecoveryOrigin through ValidateRefreshPublication. Hosts import recovery separately.
    // It compares Expected, the exact holder, process session, epoch, live expiry, and recovery identity.
    // A refusal changes neither the head nor the recovery reference. Staged bytes confer no permission.
    //
    // An identical successful retry returns its original head while its receipt remains retained.
    // A retry after receipt collection refuses without another publication.
    // The store must prove that retry from the retained request, including its original grant.
    //
    // Lease expiry must not erase the durable epoch. Reuse of an active holder by another session fails.
    CommitPublication(context.Context, FleetPublication) (FleetHead, error)
}

type Freshness

Freshness is the evaluated age of one observed timestamp.

type Freshness = status.Freshness

type FreshnessPolicy

FreshnessPolicy holds the age thresholds that turn observed timestamps into a freshness level.

type FreshnessPolicy struct {
    ChannelWarnAge     time.Duration
    ChannelCriticalAge time.Duration

    SourceCheckWarnAge     time.Duration
    SourceCheckCriticalAge time.Duration

    AcquisitionWarnAge     time.Duration
    AcquisitionCriticalAge time.Duration
}

func DefaultFreshnessPolicy
func DefaultFreshnessPolicy() FreshnessPolicy

DefaultFreshnessPolicy returns the canonical freshness thresholds.

func (FreshnessPolicy) Validate
func (p FreshnessPolicy) Validate() error

Validate checks that every warning threshold precedes its critical partner.

type GenerationPinAcceptance

GenerationPinAcceptance identifies one verified selection and its publication. An origin rollback publishes the selected payload under a new authority generation. RequestedAt and AcceptedAt record local acceptance, not provider observation time.

type GenerationPinAcceptance struct {
    OperationID          string                        `json:"operation_id"`
    SelectedGenerationID string                        `json:"selected_generation_id"`
    AcceptedGenerationID string                        `json:"accepted_generation_id"`
    PreviousGenerationID string                        `json:"previous_generation_id"`
    PayloadChecksum      string                        `json:"payload_checksum"`
    AuthorityHead        catalogs.CatalogAuthorityHead `json:"authority_head,omitzero"`
    RequestedAt          time.Time                     `json:"requested_at"`
    AcceptedAt           time.Time                     `json:"accepted_at,omitzero"`
}

type Health

Health is the operator-facing state of one runtime component.

type Health = status.Health

type InputCollectionReport

InputCollectionReport separates protected references from unrecognized files and removable inputs. Scanned includes one possible entry beyond MaxEntries to detect overflow. SnapshotBytes counts captured raw records, excluding decoder and filesystem verification work. Removed includes visible deletions when later directory synchronization fails.

type InputCollectionReport struct {
    Scanned       int
    SnapshotBytes int64
    Protected     []string
    Preserved     []string
    Candidates    []string
    Removed       []string
}

type InputCollectionRequest

InputCollectionRequest bounds one explicit scan of retained input files. MaxEntries includes unknown directory entries. MaxBytes bounds raw snapshot bytes. DryRun validates references and reports candidates without deleting files.

type InputCollectionRequest struct {
    MaxEntries int
    MaxBytes   int64
    DryRun     bool
}

type Lease

Lease is the exclusive right to commit a durable catalog generation. The epoch increases on every fresh acquisition, so a commit that carries an older epoch is stale.

type Lease struct {
    // Holder names the instance that owns the lease.
    Holder string

    // Epoch increases on every fresh acquisition.
    Epoch uint64

    // SessionID identifies the process that acquired a fleet grant.
    // A restart uses a new session even when the configured holder name stays unchanged.
    SessionID string

    // Identity binds a fleet grant to the independently approved backend incarnation.
    // Legacy standalone lease adapters leave this identity empty.
    Identity FleetIdentity

    // ExpiresAt is when the lease lapses without a renewal.
    ExpiresAt time.Time
}

type LeaseStore

LeaseStore is the shared-storage lease that fences durable commits. A deployment whose instances share no storage needs no lease store, and the runtime then commits without a fence.

type LeaseStore interface {
    // AcquireLease takes the lease for the named holder. A store that another
    // holder owns returns an *errors.ConflictError. That refusal names a
    // non-owner state, not a failure. The runtime keeps serving its retained
    // catalog and tries again at the next run. Every other error fails Open.
    AcquireLease(ctx context.Context, holder string, ttl time.Duration) (Lease, error)

    // Renew extends a held lease without changing its holder, epoch, session, or recovery identity.
    // It fails when that grant expired or another holder took the lease.
    Renew(ctx context.Context, lease Lease, ttl time.Duration) (Lease, error)

    // Release returns the lease early.
    Release(ctx context.Context, lease Lease) error
}

type NetworkMode

NetworkMode controls outbound catalog acquisition, not inference or storage.

type NetworkMode string


const (
    // NetworkConfigured permits the selected catalog sources to use the network.
    NetworkConfigured NetworkMode = "configured"
    // NetworkOffline refuses network source reads and acquisition.
    NetworkOffline NetworkMode = "offline"
)

func ParseNetworkMode
func ParseNetworkMode(value string) (NetworkMode, error)

ParseNetworkMode accepts an explicit configured or offline selection.

type ObservationInputs

ObservationInputs separates accepted local facts from the selected baseline. Both catalogs are immutable snapshots. Baseline excludes this runtime's local observations.

type ObservationInputs struct {
    // Current is the complete accepted effective generation.
    Current starmap.CatalogState
    // Baseline is the retained upstream generation, or the compiled catalog when no upstream layer exists.
    Baseline starmap.CatalogState
}

type ObservationReset

ObservationReset names local acquisition evidence to replace. Empty SourceID selects provider APIs for compatibility.

type ObservationReset struct {
    // SourceID selects provider APIs or one models.dev source.
    SourceID sources.ID `json:"source,omitempty"`
    // ProviderID selects an original source provider identity. Empty selects an entire metadata source.
    ProviderID catalogs.ProviderID `json:"provider_id"`
    // BindingID selects one declared acquisition binding, or legacy unscoped input when empty.
    BindingID string `json:"binding_id,omitempty"`
    // BindingRevision selects that binding's declared revision.
    BindingRevision string `json:"binding_revision,omitempty"`
}

type ObservationUpdate

ObservationUpdate contains original acquisition results and explicit reset scopes. Acquisition derives scopes from the sources and bindings that actually completed.

type ObservationUpdate struct {
    Observations []sources.Observation
    Resets       []ObservationReset
}

type Option

Option configures the connected runtime. The offline constructors in the root package take their own option type, so no offline constructor accepts a connected-runtime setting.

type Option func(*options) error

func WithAcquirer
func WithAcquirer(acquirer Acquirer) Option

WithAcquirer injects the provider acquisition composition. The root package selects no concrete provider client. Non-provider acquisition uses WithSourceAcquirer.

func WithAcquisitionEnabled
func WithAcquisitionEnabled(enabled bool) Option

WithAcquisitionEnabled turns all scheduled acquisition on or off.

func WithAcquisitionInterval
func WithAcquisitionInterval(interval time.Duration) Option

WithAcquisitionInterval sets the acquisition period. Zero selects one startup pass and no periodic work.

func WithAcquisitionSources
func WithAcquisitionSources(ids ...sources.ID) Option

WithAcquisitionSources selects permitted local acquisition and retained evidence. An explicit empty set disables every acquisition source. It preserves the selected baseline. Omission preserves the acquisition roles and retained inputs that the caller supplies.

func WithAuthorityOrigin
func WithAuthorityOrigin(store storage.Store, config OriginConfig) Option

WithAuthorityOrigin selects the sole publication store and authorizes a catalog origin. Its store takes precedence over stores passed through WithClientOptions, independent of option order. Source, workspace, and acquisition options still apply. An authoritative subscriber cannot also be an origin. All writers to the underlying store must enforce the same authority publication contract.

func WithCatalogNetworkMode
func WithCatalogNetworkMode(value string) Option

WithCatalogNetworkMode selects configured or offline catalog acquisition.

func WithCatalogSource
func WithCatalogSource(name string) Option

WithCatalogSource selects the upstream catalog source by name. It accepts public, github, starmap, file, and embedded. A named custom source is terminal: the runtime never falls back to the public channel.

func WithClientOptions
func WithClientOptions(opts ...starmap.Option) Option

WithClientOptions forwards offline client options to the Starmap client that the runtime publishes into. The root package owns the catalog store, the workspace path, and the embedded bootstrap budgets. One composition therefore supplies both kinds of setting in one list.

func WithClock
func WithClock(now func() time.Time) Option

WithClock injects the runtime clock. Tests use it to keep timing exact.

func WithCoalesceWindow
func WithCoalesceWindow(window time.Duration) Option

WithCoalesceWindow bounds how long completed provider observations wait for a slower sibling before they publish.

func WithCompletedDirectoryMigration
func WithCompletedDirectoryMigration(completion DirectoryMigrationCompletion) Option

WithCompletedDirectoryMigration requires the observed completion record during startup. The host must select its target directory, owner, and retained scheduler identity. Open rechecks the preserved source and target under its directory lock.

func WithDirectoryOwner
func WithDirectoryOwner(owner DirectoryOwner) Option

WithDirectoryOwner selects the identity recorded for persistent runtime state. A different recorded identity requires an explicit migration before startup.

func WithFleetAuthorityOrigin
func WithFleetAuthorityOrigin(store FleetStore, origin OriginConfig) Option

WithFleetAuthorityOrigin selects one fleet store for origin publication and permission issuance. The adapter must support independent authority-head observations.

func WithFleetStore
func WithFleetStore(store FleetStore) Option

WithFleetStore selects shared catalog publication and refresh ownership together. The runtime stores acquisition inputs with each shared publication, outside its private directory. The fleet store takes precedence over stores passed through WithClientOptions.

func WithFreshnessPolicy
func WithFreshnessPolicy(policy FreshnessPolicy) Option

WithFreshnessPolicy replaces the freshness thresholds. An explicit policy wins, so WithSourceMaxAge then derives no channel threshold.

func WithGenerationPin
func WithGenerationPin(id string) Option

WithGenerationPin selects one retained generation for this runtime's lifetime. The host persists this setting in its configuration authority. An empty value clears it. Replacing the runtime applies a changed pin. Permission observation remains active.

func WithLeaseStore
func WithLeaseStore(store LeaseStore) Option

WithLeaseStore injects the shared-storage lease that fences durable commits. A deployment without shared storage needs no lease.

func WithListenAddress
func WithListenAddress(address string) Option

WithListenAddress records the server listen address. It does not change instance identity.

func WithModelsDevGitCommit
func WithModelsDevGitCommit(commit string) Option

WithModelsDevGitCommit sets the exact commit for models.dev Git acquisition. Empty clears an inherited pin. This option does not select the Git source.

func WithOwnedSource
func WithOwnedSource(source OwnedSource) Option

WithOwnedSource transfers the selected source to the runtime during Open. Open failure and runtime shutdown close it. Only the final selected source transfers. WithSource keeps ownership with the caller and replaces this selection.

func WithPermissionClock
func WithPermissionClock(sample func() permission.ClockReading) Option

WithPermissionClock supplies one qualified time and uncertainty sample for each permission check. The callback reads cached evidence and supports concurrent calls. It starts no I/O. It governs admission, permission relay, and permission status independently of the scheduler clock. Use WithPermissionClockUncertainty only when this option is absent. The caller owns native clock qualification.

func WithPermissionClockMonitor
func WithPermissionClockMonitor(monitor *permission.ClockMonitor) Option

WithPermissionClockMonitor assigns one unstarted monitor to this runtime. Open starts it before source startup and owns its shutdown after a successful start. A failed Open cancels any monitor it started. It leaves a monitor owned elsewhere alone. Select this option without either external permission-clock callback. An origin can also use this monitor's Read method in OriginConfig.Clock.

func WithPermissionClockUncertainty
func WithPermissionClockUncertainty(sample func() (time.Duration, bool)) Option

WithPermissionClockUncertainty supplies the host's cached clock assurance. The callback reads cached memory only. It reports uncertainty for WithClock's time and false when its evidence is absent or expired. No callback means unknown.

func WithProviderBindings
func WithProviderBindings(bindings ...sources.ProviderAcquisitionBinding) Option

WithProviderBindings selects the complete active set for local provider evidence. An empty set permits no local provider evidence. The set excludes unscoped evidence. The runtime copies the declarations. A changed set requires a new runtime.

func WithPublishedDirectoryMigration
func WithPublishedDirectoryMigration(request DirectoryMigrationRequest) Option

WithPublishedDirectoryMigration requires the exact published target during startup. The host must also select the request's directory, owner, and scheduler identity. Open verifies migration records under its directory lock before persistent initialization.

func WithRandom
func WithRandom(random Random) Option

WithRandom injects the jitter source that spreads scheduled work.

func WithRefreshTimeout
func WithRefreshTimeout(timeout time.Duration) Option

WithRefreshTimeout bounds one whole refresh run. Zero, the default, adds no deadline, so a long transfer inside its own bounds is not cut short.

func WithRetentionEnabled
func WithRetentionEnabled(enabled bool) Option

WithRetentionEnabled selects automatic collection. Explicit collection remains available.

func WithRetentionInputMaxBytes
func WithRetentionInputMaxBytes(bytes int64) Option

WithRetentionInputMaxBytes bounds raw retained input bytes captured during one scan.

func WithRetentionInterval
func WithRetentionInterval(interval time.Duration) Option

WithRetentionInterval sets the positive delay between scheduled collection passes.

func WithRetentionMaxBytes
func WithRetentionMaxBytes(bytes int64) Option

WithRetentionMaxBytes sets the retained generation byte target.

func WithRetentionMaxGenerations
func WithRetentionMaxGenerations(count int) Option

WithRetentionMaxGenerations sets the retained generation count target.

func WithRetentionPolicy
func WithRetentionPolicy(policy RetentionPolicy) Option

WithRetentionPolicy replaces the complete runtime collection policy.

func WithRetentionScanEntries
func WithRetentionScanEntries(entries int) Option

WithRetentionScanEntries bounds the entries inspected during one collection pass.

func WithSchedulerIdentity
func WithSchedulerIdentity(identity string) Option

WithSchedulerIdentity overrides the derived instance identity. Use it when the deployment already owns a stable instance name.

func WithSource
func WithSource(source Source) Option

WithSource injects a deployment-owned upstream source. It replaces every built-in source implementation.

func WithSourceAPIKey
func WithSourceAPIKey(key string) Option

WithSourceAPIKey supplies the source API key. The runtime keeps the key out of status, logs, and errors.

func WithSourceAcquirer
func WithSourceAcquirer(acquirer SourceAcquirer) Option

WithSourceAcquirer adds non-provider acquisition beside the provider role. This option starts no source reads. Scheduled and explicit Sync runs use this role.

func WithSourceAliases
func WithSourceAliases(aliases ...string) Option

WithSourceAliases declares the other stable identities that name this same runtime. A served source chain that names one of them is a self reference. The runtime then refuses the read instead of serving its own catalog back to itself.

func WithSourceAuthority
func WithSourceAuthority(authorityID, policyID string) Option

WithSourceAuthority pins the authority and policy used by require_authority. It changes neither the source address nor the startup policy.

func WithSourceAuthorityID
func WithSourceAuthorityID(identity string) Option

WithSourceAuthorityID selects the authority identity required by the source policy.

func WithSourceChannel
func WithSourceChannel(channel string) Option

WithSourceChannel names the mutable branch that selects the current catalog.

func WithSourceMaxAge
func WithSourceMaxAge(maxAge time.Duration) Option

WithSourceMaxAge sets the age at which the served catalog counts as stale. It also derives the channel freshness thresholds. The warning age becomes the maximum age, and the critical age keeps the six-to-ten ratio of the defaults. WithFreshnessPolicy wins over this derivation.

func WithSourceMaxHops
func WithSourceMaxHops(hops int) Option

WithSourceMaxHops bounds a cascade of Starmap runtimes.

func WithSourcePolicy
func WithSourcePolicy(policy SourcePolicy) Option

WithSourcePolicy replaces the whole upstream source policy.

func WithSourcePolicyID
func WithSourcePolicyID(identity string) Option

WithSourcePolicyID selects the permission policy within the configured authority.

func WithSourcePollInterval
func WithSourcePollInterval(interval time.Duration) Option

WithSourcePollInterval sets the channel check period.

func WithSourceRefreshMode
func WithSourceRefreshMode(value string) Option

WithSourceRefreshMode selects automatic or explicit-only source refresh.

func WithSourceRepository
func WithSourceRepository(repository string) Option

WithSourceRepository names the catalog repository of a GitHub channel.

func WithSourceSignerWorkflow
func WithSourceSignerWorkflow(workflow string) Option

WithSourceSignerWorkflow pins the build provenance the source accepts.

func WithSourceStartupPolicy
func WithSourceStartupPolicy(name string) Option

WithSourceStartupPolicy decides what the runtime serves before the first upstream reply.

func WithSourceToken
func WithSourceToken(token string) Option

WithSourceToken supplies the source access token. The runtime keeps the token out of status, logs, and errors.

func WithSourceURL
func WithSourceURL(url string) Option

WithSourceURL sets the deployment-owned source address used by the starmap and file sources.

func WithStartupSpread
func WithStartupSpread(spread time.Duration) Option

WithStartupSpread bounds the random delay before the first scheduled run.

func WithStateDirectory
func WithStateDirectory(directory string) Option

WithStateDirectory selects the durable directory that retains layers, the scheduler identity seed, and source discovery state. Open requires an absolute path and holds an exclusive directory lock until shutdown finishes.

func WithTransferIdleTimeout
func WithTransferIdleTimeout(timeout time.Duration) Option

WithTransferIdleTimeout bounds a stalled transfer.

func WithTransferMaxDuration
func WithTransferMaxDuration(duration time.Duration) Option

WithTransferMaxDuration bounds one whole transfer.

func WithUpdatePolicy
func WithUpdatePolicy(policy UpdatePolicy) Option

WithUpdatePolicy replaces both catalog update controls.

func WithoutAuthorityOrigin
func WithoutAuthorityOrigin() Option

WithoutAuthorityOrigin clears earlier origin issuance and publication options. The selected store remains in use. Its authority still requires an explicit transition before ordinary startup, or a matching require_authority subscriber configuration.

func WithoutPermissionClock
func WithoutPermissionClock() Option

WithoutPermissionClock clears earlier monitor and callback selections. No clock evidence remains until a later option supplies a clock explicitly.

type OriginConfig

OriginConfig explicitly authorizes this runtime to publish and issue permissions for one catalog authority. The complete catalog selected by the runtime defines this policy's permitted catalog. Clock must supply qualified, cached time evidence. An unknown reading prevents receipt issuance. The deployment owns clock qualification and access control for all catalog mutations.

type OriginConfig struct {
    AuthorityID string
    PolicyID    string
    // Bootstrap permits the runtime to adopt an existing ordinary catalog store.
    // It cannot change an established authority or reset its sequence.
    Bootstrap          bool
    PermissionLifetime time.Duration
    Clock              func() permission.ClockReading
}

type OwnedSource

OwnedSource supplies a source and its shutdown operation. Shutdown cancels and joins source-owned work unless its context ends first. With a live context, it must finish joining before returning any cleanup error. Repeated calls must be safe.

type OwnedSource interface {
    Source
    Shutdown(context.Context) error
}

type OwnerRecordStatus

OwnerRecordStatus describes a stored binding, not an active lock or seed verification.

type OwnerRecordStatus string


const (
    // OwnerRecordMatches means the canonical record matches the configured owner and identity override.
    OwnerRecordMatches OwnerRecordStatus = "matches"
    // OwnerRecordAbsent means the selected directory or record does not exist.
    OwnerRecordAbsent OwnerRecordStatus = "absent"
    // OwnerRecordConflict means the record or directory is invalid or has another binding.
    OwnerRecordConflict OwnerRecordStatus = "conflict"
    // OwnerRecordUnavailable means the metadata or bounded record read failed.
    OwnerRecordUnavailable OwnerRecordStatus = "unavailable"
    // OwnerRecordUnverified means the native inspection adapter is unavailable.
    OwnerRecordUnverified OwnerRecordStatus = "unverified"
)

func InspectDirectoryOwnerRecord
func InspectDirectoryOwnerRecord(ctx context.Context, directory string, owner DirectoryOwner, identity string) (OwnerRecordStatus, error)

InspectDirectoryOwnerRecord compares one bounded canonical record without writes or locks. It does not read the seed or verify active ownership, migration completion, or fleet fencing.

type ProviderLayer

ProviderLayer is one retained per-provider observation. The runtime keeps the last-known-good layer of every provider, so one failing provider never removes its records from the effective catalog.

type ProviderLayer struct {
    // ProviderID names the observed provider.
    ProviderID catalogs.ProviderID

    // Payload is the canonical encoding of the provider observation.
    Payload []byte

    // Digest is the content digest of Payload.
    Digest string

    // ObservedAt is when acquisition accepted the observation.
    ObservedAt time.Time

    // Receipt binds source identity, completeness, and classified issues to Payload.
    Receipt sources.ObservationReceipt
}

func NewProviderLayer
func NewProviderLayer(id catalogs.ProviderID, observation sources.Observation) (ProviderLayer, error)

NewProviderLayer encodes one validated provider observation with its durable receipt. It does not connect to a network or write files.

type ProviderObservationReset

ProviderObservationReset retains the provider-oriented spelling of ObservationReset.

type ProviderObservationReset = ObservationReset

type PublicationStatus

PublicationStatus summarizes one retained upstream publication.

type PublicationStatus = status.Publication

type Random

Random returns a uniform value in the half-open interval [0, 1). The runtime uses it to spread scheduled work across a fleet.

type Random func() float64

type RefreshReport

RefreshReport says what one whole refresh produced. A source-only run leaves the acquisition report empty, and an acquisition-only run leaves the source report empty.

type RefreshReport struct {
    // RunID is the identity of the run.
    RunID string

    // Kind names the work the run did.
    Kind string

    // StartedAt and CompletedAt bound the run.
    StartedAt   time.Time
    CompletedAt time.Time

    // Source reports the upstream read.
    Source SourceRefreshReport

    // Acquisition reports provider attempts and non-provider observations.
    Acquisition AcquisitionReport

    // Published reports whether the runtime published a new effective catalog.
    Published bool

    // GenerationID identifies the published effective catalog.
    GenerationID string
}

type RetainedCatalogPermission

RetainedCatalogPermission holds original passive permission evidence for a stopped consumer. It grants no permission renewal, source acquisition, catalog activation, or replica ownership.

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

func InspectRetainedCatalogPermission
func InspectRetainedCatalogPermission(ctx context.Context, request RetainedCatalogPermissionRequest, clock permission.ClockReading) (*RetainedCatalogPermission, error)

InspectRetainedCatalogPermission checks original retained permission without opening a connected runtime. Writers must remain fenced throughout inspection and rechecks. Internal authority receipts require a qualified current clock sample. An uncertain checkpoint requires separate source-owner verification. This operation does not clear uncertainty or extend expiry.

func (*RetainedCatalogPermission) Check
func (p *RetainedCatalogPermission) Check(ctx context.Context, request RetainedCatalogPermissionRequest, clock permission.ClockReading) error

Check verifies the original evidence and current expiry without changing files or receipt deadlines. After restart, compare fresh inspection with the record sealed in the original recovery decision.

func (*RetainedCatalogPermission) Digest
func (p *RetainedCatalogPermission) Digest() string

Digest returns the SHA-256 digest of the original record, or an empty string for an absent capability.

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

Format hides private native evidence from diagnostic output.

func (*RetainedCatalogPermission) Record
func (p *RetainedCatalogPermission) Record() []byte

Record returns a private, caller-owned copy of the original native evidence. Seal this record with the complete recovery decision before releasing any component.

type RetainedCatalogPermissionRequest

RetainedCatalogPermissionRequest binds a selected catalog to its configured consumer and private runtime state. The host must verify the catalog payload, source policy, and deployment fence independently.

type RetainedCatalogPermissionRequest struct {
    Directory         string
    Owner             DirectoryOwner
    SchedulerIdentity string
    SourcePolicy      SourcePolicy
    AcceptedHead      catalogs.CatalogAuthorityHead
}

type RetainedFile

RetainedFile identifies bytes in a verified backup. Names are slash-separated relative paths.

type RetainedFile = privatefiles.RetainedFile

type RetainedRecordReader

RetainedRecordReader reads a record from a verified backup with the supplied byte limit. An absent record must return an error that matches os.ErrNotExist.

type RetainedRecordReader = privatefiles.RetainedRecordReader

type RetentionPolicy

RetentionPolicy bounds automatic collection independently of catalog update permissions. Required generations can exceed the limits. Collection never removes them to satisfy a limit.

type RetentionPolicy struct {
    Enabled        bool
    Interval       time.Duration
    MaxGenerations int
    MaxBytes       int64
    ScanEntries    int
    InputMaxBytes  int64
}

func DefaultRetentionPolicy
func DefaultRetentionPolicy() RetentionPolicy

DefaultRetentionPolicy selects hourly collection with bounded scans and retained bytes.

func (RetentionPolicy) Validate
func (p RetentionPolicy) Validate() error

Validate rejects unbounded or invalid retention settings, including when operators disable scheduling.

type RetentionStatus

RetentionStatus is the last observed catalog collection outcome.

type RetentionStatus = status.RetentionStatus

type Runtime

Runtime is a connected Starmap. It serves the embedded catalog immediately, refreshes from one selected upstream source, retains per-provider observations, and rebuilds one immutable effective catalog from those layers. Reads reach no external system.

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

func Open
func Open(ctx context.Context, opts ...Option) (connected *Runtime, err error)

Open returns a connected runtime. It serves the verified embedded catalog before the first upstream reply, so Catalog and State never wait for the network. Open starts the source and acquisition schedules and returns. An authoritative stored catalog requires origin configuration or require_authority.

func (*Runtime) AcquisitionSources
func (r *Runtime) AcquisitionSources() ([]sources.ID, bool)

AcquisitionSources returns an owned explicit source set and its presence. Without a selection, the supplied acquisition roles keep their defaults.

func (*Runtime) AllowsCatalogAttempt
func (r *Runtime) AllowsCatalogAttempt(head catalogs.CatalogAuthorityHead) bool

AllowsCatalogAttempt checks permission for a consumer's separately accepted catalog. The consumer must bind this validated authority head to its exact catalog before publication. A retained catalog can serve new attempts only while its permission revision remains current. Equal permission revisions allow route preparation without interrupting the previous catalog. Ordinary sources use the same admission policy as AllowsNewAttempt. Call this memory-only check for every attempt, retry, and cached response delivery.

func (*Runtime) AllowsNewAttempt
func (r *Runtime) AllowsNewAttempt() bool

AllowsNewAttempt checks current catalog permission using memory only. Call it for every new attempt, including retries and cached response delivery. It does not replace model, destination, account, or budget authorization.

func (*Runtime) BaselineStatus
func (r *Runtime) BaselineStatus() (BaselineStatus, bool)

BaselineStatus returns the packaged and retained baselines without a storage operation. It returns false when the runtime has no fleet store.

func (*Runtime) Catalog
func (r *Runtime) Catalog() *catalogs.Catalog

Catalog returns the current immutable effective catalog. It reaches no external system and never blocks on the source.

func (*Runtime) Client
func (r *Runtime) Client() *starmap.Client

Client returns the immutable publication client underneath the runtime. Use it for explicit publication, hooks, and generation retrieval.

func (*Runtime) Close
func (r *Runtime) Close() error

Close stops runtime-owned work and releases the lease. It is idempotent and joins within thirty seconds. A run that does not stop in time leaves a typed timeout error. Directory ownership remains held until work and lease release finish.

func (*Runtime) CollectRetainedInputs
func (r *Runtime) CollectRetainedInputs(ctx context.Context, request InputCollectionRequest) (report InputCollectionReport, resultErr error)

CollectRetainedInputs removes validated immutable inputs outside retained history and pending publications. It cleans unused local inputs even when acquisition is offline or a generation pin prevents updates. Limits must be positive. MaxEntries cannot exceed storage.MaxRetentionScanEntries. A failed preflight removes nothing. Later failures return the partial removal report.

func (*Runtime) CompleteDirectoryMigration
func (r *Runtime) CompleteDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationPublication, error)

CompleteDirectoryMigration confirms this runtime's selected directory, owner, and retained identity. Call it after the host selects the replacement configuration and opens this runtime. This method records completion without editing configuration files or deleting the source.

func (*Runtime) FleetStatus
func (r *Runtime) FleetStatus() (FleetStatus, bool)

FleetStatus returns local fleet state without a storage operation.

func (*Runtime) ModelsDevGitCommit
func (r *Runtime) ModelsDevGitCommit() (string, bool)

ModelsDevGitCommit returns the configured Git pin and its explicit presence.

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

ObservationInputs returns the current catalog and its selected baseline. It reads retained memory, starts no acquisition, and writes no files. A later update reads new snapshots under runtime operation ownership.

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

PermissionClock returns the current permission time and its uncertainty from cached evidence. It starts no observation or I/O. An absent runtime or clock returns unknown time. Hosts must reject unknown time and uncertainty outside their admission bounds.

func (*Runtime) PermissionClockStatus
func (r *Runtime) PermissionClockStatus() permission.ClockMonitorStatus

PermissionClockStatus reports diagnostics for the runtime-owned clock monitor. It starts no observation. A runtime with an external callback returns an empty status. LastError is a local diagnostic. Hosts must redact it in public responses.

func (*Runtime) PinAcceptance
func (r *Runtime) PinAcceptance() (GenerationPinAcceptance, bool)

PinAcceptance returns the current acceptance and whether durable storage retains it. A missing acceptance returns a zero record and false. This method reads memory only.

func (*Runtime) PreviewAcquisition
func (r *Runtime) PreviewAcquisition(ctx context.Context, prepare func(context.Context, ObservationInputs) (ObservationUpdate, error), requestedSources ...sources.ID) (starmap.CatalogState, error)

PreviewAcquisition computes an acquisition against one captured runtime snapshot. It writes no catalog, workspace, or runtime state. The callback owns source reads. requestedSources has the same access contract as UpdateAcquisition.

func (*Runtime) PromoteEmbeddedBaseline
func (r *Runtime) PromoteEmbeddedBaseline(ctx context.Context, request BaselinePromotion) (BaselinePromotionResult, error)

PromoteEmbeddedBaseline makes this binary's packaged baseline the fleet's retained baseline. It runs under the publication lease and publishes one revision after ExpectedHead. Retained source, provider, manual, and removal inputs stay unchanged. It refuses a stale head, a different packaged generation, an equal baseline, a generation pin, and a configured source authority. The caller authorizes the operator action.

func (*Runtime) PublishObservations
func (r *Runtime) PublishObservations(ctx context.Context, observations ...sources.Observation) (starmap.CatalogState, error)

PublishObservations retains caller-supplied observations with their accepted catalog. The runtime validates receipts and active bindings before it publishes any input. This operation reads no source and joins runtime cancellation and shutdown.

func (*Runtime) ReadPermission
func (r *Runtime) ReadPermission(ctx context.Context) (catalogs.CatalogPermissionEnvelope, error)

ReadPermission issues an origin receipt or returns a confirmed upstream receipt without renewing it. Origins read current authoritative storage with a qualified clock. Relays read retained receipts from memory. It forwards a required revision even when this runtime cannot activate its catalog or permission schema. A newer manifest without a matching receipt, uncertain retention, or unknown clock validity prevents delivery. Callers must authenticate the downstream connection and enforce the receipt's original expiry.

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

Refresh reads the upstream and then observes configured acquisition sources. It changes the upstream layer and acquisition inputs in one run.

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

RefreshFleet activates the durable shared head after a missed notification or reconnect. It queries no source and requires no refresh lease.

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

RefreshPermission reads and retains the configured authority's requirement. It runs independently of catalog refresh and the shared acquisition lease.

func (*Runtime) RefreshSource
func (r *Runtime) RefreshSource(ctx context.Context) (SourceRefreshReport, error)

RefreshSource reads the upstream source only. It changes the source layer.

func (*Runtime) ReplaceRemovalTargets
func (r *Runtime) ReplaceRemovalTargets(ctx context.Context, expected starmap.CatalogState, targets ...catalogs.CatalogRemovalTarget) (starmap.CatalogState, error)

ReplaceRemovalTargets replaces this runtime's operator removal snapshot. Expected generation identity and checksum prevent stale edits. An empty target list restores local removals. The caller authorizes the operator action. Other publishers retain their own policies.

func (*Runtime) RetentionSnapshot
func (r *Runtime) RetentionSnapshot() RetentionStatus

RetentionSnapshot returns the configured policy and last collection result without storage reads.

func (*Runtime) State
func (r *Runtime) State() starmap.CatalogState

State returns one atomic snapshot of the effective catalog, generation identity, and authority head. It allocates no memory and reaches no external system. The authority head does not grant permission.

func (*Runtime) Status
func (r *Runtime) Status() Status

Status returns the current runtime status. It reads retained state only, so it reaches no external system and never blocks on the source.

func (*Runtime) Sync
func (r *Runtime) Sync(ctx context.Context, providers ...catalogs.ProviderID) (AcquisitionReport, error)

Sync observes configured provider and non-provider sources. An empty provider list observes every eligible provider scope.

func (*Runtime) UpdateAcquisition
func (r *Runtime) UpdateAcquisition(ctx context.Context, prepare func(context.Context, ObservationInputs) (ObservationUpdate, error), requestedSources ...sources.ID) (starmap.CatalogState, error)

UpdateAcquisition prepares and commits one acquisition under runtime ownership. Failed preparation preserves accepted state. The callback must not mutate this runtime. requestedSources declares every source the callback can read. Omission permits network acquisition only in configured mode.

func (*Runtime) UpdateObservations
func (r *Runtime) UpdateObservations(ctx context.Context, prepare func(context.Context, ObservationInputs) ([]sources.Observation, error), resets ...ObservationReset) (starmap.CatalogState, error)

UpdateObservations prepares and publishes original observations under runtime ownership. The callback may read sources. Runtime shutdown and caller cancellation stop its context. An error or empty observation list preserves accepted state. The callback must not call another mutation on this runtime. Use ObservationInputs for a read-only preview.

Optional resets replace prior local acquisition observations within the named scopes. Each scope requires complete successful replacement evidence. The baseline and unrelated scopes remain. Resets and replacements share the catalog publication journal.

func (*Runtime) Updates
func (r *Runtime) Updates() <-chan starmap.CatalogState

Updates returns the channel that carries every published effective catalog state. The runtime buffers the channel. A reader that falls behind loses intermediate states and always observes the newest one.

func (*Runtime) UpstreamPublication
func (r *Runtime) UpstreamPublication() *SourcePublication

UpstreamPublication returns a caller-owned copy of the accepted source run record. It returns nil when the source supplies no run receipt. The artifact manifest stays unchanged.

type Source

Source reads one upstream immutable catalog generation.

type Source = source.Source

type SourceAcquirer

SourceAcquirer collects configured non-provider observations without publication. It must preserve source receipts and report failed or partial observations. Runtime owns cancellation, lease fencing, retained evidence, and publication.

type SourceAcquirer interface {
    AcquireSources(context.Context, SourceAcquisitionRequest) ([]sources.Observation, error)
}

type SourceAcquisitionRequest

SourceAcquisitionRequest selects non-provider observations for one owned run. Current is immutable. Providers restricts model scope when the caller supplies IDs.

type SourceAcquisitionRequest struct {
    Current   *catalogs.Catalog
    Providers []catalogs.ProviderID
    // Sources replaces the collector source defaults when non-nil.
    Sources []sources.ID
    // ModelsDevGitCommit replaces the collector pin when non-nil.
    // An explicit empty value clears that pin. Git acquisition then requires a pin.
    ModelsDevGitCommit *string
}

type SourceDescriber

SourceDescriber declares metadata capabilities and default selection without acquisition. The runtime calls it once when it opens. It must not read external data. The runtime treats omitted metadata sources as unsupported. Eligibility remains unknown until acquisition.

type SourceDescriber interface {
    SourceConfiguration() []sources.SourceActivity
}

type SourceHop

SourceHop is one sanitized entry in an upstream source chain.

type SourceHop = status.SourceHop

type SourceIdentityAdopter

SourceIdentityAdopter is an optional Source that takes the fleet instance identity of its runtime.

type SourceIdentityAdopter = source.IdentityAdopter

type SourceKind

SourceKind names one supported upstream catalog source.

type SourceKind = status.SourceKind

func ParseSourceKind
func ParseSourceKind(name string) (SourceKind, error)

ParseSourceKind converts one configured name into a source kind. It rejects every unknown name with a typed validation error, so a typo never selects a silent default.

func SourceKinds
func SourceKinds() []SourceKind

SourceKinds returns a caller-owned copy of every accepted source name.

type SourceManualReader

SourceManualReader reads one generation without a background lifecycle.

type SourceManualReader = source.ManualReader

type SourcePolicy

SourcePolicy selects and bounds the upstream catalog source. It holds no token and no API key, so a policy value is safe to log and to serve.

type SourcePolicy struct {
    // Kind selects the source implementation.
    Kind SourceKind

    // URL is the deployment-owned source address. It applies to the starmap
    // and file kinds.
    URL string

    // Repository names the catalog repository for the public and github kinds.
    Repository string

    // Channel names the mutable branch that selects the current catalog.
    Channel string

    // SignerWorkflow pins the build provenance the source accepts.
    SignerWorkflow string

    // PollInterval is the channel check period.
    PollInterval time.Duration

    // StartupPolicy decides what the runtime serves before the first reply.
    StartupPolicy StartupPolicy

    // AuthorityID and PolicyID pin the authority required by require_authority.
    AuthorityID string
    PolicyID    string

    // MaxAge is the age at which the active catalog counts as stale.
    MaxAge time.Duration

    // MaxHops bounds a cascade of Starmap runtimes.
    MaxHops int

    // Aliases are the other stable identities that name this same runtime,
    // such as a load-balancer name or a second deployment name. A served
    // source chain that names one of them is a self reference, and address
    // comparison alone cannot detect it.
    Aliases []string
}

func DefaultSourcePolicy
func DefaultSourcePolicy() SourcePolicy

DefaultSourcePolicy returns the canonical public-channel source policy.

func ResolveSourcePolicy
func ResolveSourcePolicy(opts ...Option) (SourcePolicy, error)

ResolveSourcePolicy returns the source policy from canonical runtime options. It starts no runtime, source, clock, file access, or background work. The caller receives detached aliases. Other configuration domains retain their own validation.

func (SourcePolicy) SafeIdentity
func (p SourcePolicy) SafeIdentity() string

SafeIdentity returns the source identity that status and logs may show. It names the kind and, for a GitHub channel, the repository and the channel. It never names a custom URL, a host, or a credential.

func (SourcePolicy) Validate
func (p SourcePolicy) Validate() error

Validate checks the policy fields that the runtime depends on.

type SourcePublication

SourcePublication is the verified upstream run receipt and promotion identity.

type SourcePublication = source.Publication

type SourceRead

SourceRead is one upstream observation.

type SourceRead = source.Read

type SourceRefreshMode

SourceRefreshMode controls automatic source reads independently of acquisition.

type SourceRefreshMode string


const (
    // SourceRefreshAutomatic permits startup, periodic, and reactive source reads.
    SourceRefreshAutomatic SourceRefreshMode = "automatic"
    // SourceRefreshManual permits only explicit source reads.
    SourceRefreshManual SourceRefreshMode = "manual"
)

func ParseSourceRefreshMode
func ParseSourceRefreshMode(value string) (SourceRefreshMode, error)

ParseSourceRefreshMode accepts an explicit automatic or manual selection.

type SourceRefreshReport

SourceRefreshReport says what one upstream source read produced.

type SourceRefreshReport struct {
    // RunID is the identity of the run that produced this report.
    RunID string

    // StartedAt and CompletedAt bound the run.
    StartedAt   time.Time
    CompletedAt time.Time

    // SourceIdentity is the safe identity of the source that answered.
    SourceIdentity string

    // Changed reports whether the upstream generation moved.
    Changed bool

    // Published reports whether the runtime published a new effective catalog.
    Published bool

    // GenerationID identifies the upstream generation the runtime retained.
    GenerationID string

    // PublishedAt is the upstream publication time.
    PublishedAt time.Time

    // Health is what this runtime observed while it read the source. It grades
    // the transfer only.
    Health Health

    // UpstreamHealth is the health the upstream reported about itself. It stays
    // independent of Health, so a healthy transfer still carries a degraded
    // upstream report.
    UpstreamHealth Health

    // Reason is the safe reason code of a failed read.
    Reason string

    // Chain is the sanitized upstream source chain.
    Chain []SourceHop
}

type SourceWatcher

SourceWatcher is an optional Source that reports each upstream change.

type SourceWatcher = source.Watcher

type StartupPolicy

StartupPolicy decides what the runtime serves while the first source read is still outstanding.

type StartupPolicy string


const (
    // StartupPreferSource keeps the embedded baseline active and replaces it
    // with the first verified upstream generation. It is the default.
    StartupPreferSource StartupPolicy = "prefer_source"

    // StartupRequireSource keeps the runtime unusable until one verified
    // upstream generation is active. Open reads the source one time and fails
    // when that read fails. The policy names the evidence the runtime needs,
    // not the lease. A replica that another instance owns therefore opens
    // without a read and consumes the state that the owner publishes.
    StartupRequireSource StartupPolicy = "require_source"

    // StartupRequireAuthority retains catalog metadata while authority approval controls use.
    // Open returns diagnostics even when no approved catalog is available.
    StartupRequireAuthority StartupPolicy = "require_authority"

    // StartupPreferLocal keeps the retained local generation active and
    // applies an upstream generation only on an explicit refresh.
    StartupPreferLocal StartupPolicy = "prefer_local"
)

func ParseStartupPolicy
func ParseStartupPolicy(name string) (StartupPolicy, error)

ParseStartupPolicy converts one configured name into a startup policy.

func (StartupPolicy) String
func (p StartupPolicy) String() string

String returns the wire value of the startup policy.

func (StartupPolicy) Valid
func (p StartupPolicy) Valid() bool

Valid reports whether the policy is one of the accepted names.

type Status

Status is the operator-facing state of one connected runtime.

type Status = status.Status

type UpdatePolicy

UpdatePolicy separates automatic source refresh from catalog network access.

type UpdatePolicy struct {
    SourceRefreshMode SourceRefreshMode
    NetworkMode       NetworkMode
}

func DefaultUpdatePolicy
func DefaultUpdatePolicy() UpdatePolicy

DefaultUpdatePolicy permits automatic reads through configured sources.

func (UpdatePolicy) Validate
func (p UpdatePolicy) Validate() error

Validate rejects unknown policy values before runtime construction.

Generated by gomarkdoc

Documentation

Overview

Package runtime holds the connected catalog runtime. It opens a Starmap client, reads verified upstream generations from one source, publishes each accepted generation, and reports the operator-facing status of that work.

The default source is the attested public GitHub channel. A caller that opens the runtime accepts the signature verification and the network reads that this channel needs. The root starmap package stays the offline library.

Index

Constants

View Source 
const (
	MaxCatalogRetentionBatchBytes  = storage.DefaultRetentionInputMaxBytes
	MaxCatalogRetentionBatchInputs = storage.DefaultRetentionScanEntries
)

These bounds apply independently to raw capsule bytes, decoded recovery bytes, and input count.

View Source 
const (
	// LeaseTTL bounds how long one lease stays valid without a renewal.
	LeaseTTL = 90 * time.Second

	// LeaseRenewInterval is the period between renewals.
	LeaseRenewInterval = 30 * time.Second
)

Lease timing. One holder renews well inside the expiry, so a short pause never drops the lease and a stopped holder expires quickly.

View Source 
const (
	// DefaultTransferIdleTimeout bounds a stalled transfer.
	DefaultTransferIdleTimeout = 2 * time.Minute

	// DefaultTransferMaxDuration bounds one whole transfer.
	DefaultTransferMaxDuration = 60 * time.Minute

	// DefaultRefreshTimeout is zero, so a refresh carries no deadline of its
	// own. Transfer bounds and caller cancellation stop a stalled run.
	DefaultRefreshTimeout time.Duration = 0

	// DefaultCoalesceWindow bounds how long completed provider observations
	// wait for a slower sibling before they publish.
	DefaultCoalesceWindow = 30 * time.Second
)

Transfer and refresh defaults. They match the canonical CATALOG_TRANSFER_* and CATALOG_REFRESH_TIMEOUT settings.

View Source 
const (
	// DefaultSourceRepository is the public catalog repository.
	DefaultSourceRepository = "agentstation/starmap"

	// DefaultSourceChannel is the mutable branch that names the current
	// immutable catalog release.
	DefaultSourceChannel = artifact.PublicationChannelName

	// DefaultSourcePollInterval is how often the runtime checks the channel.
	DefaultSourcePollInterval = time.Hour

	// DefaultSourceMaxAge is the age at which a served catalog is stale.
	DefaultSourceMaxAge = 6 * time.Hour

	// DefaultSourceMaxHops bounds a cascade of Starmap runtimes.
	DefaultSourceMaxHops = 8

	// MaxSourceAliases bounds the declared alias list. A deployment names a
	// few addresses of one node, so a longer list is a configuration error.
	MaxSourceAliases = 16

	// MaxSourceAliasBytes bounds one declared alias.
	MaxSourceAliasBytes = 128
)

Source policy defaults. They match the canonical CATALOG_SOURCE_* settings.

View Source 
const (
	// FreshnessChannelWarnAge is the served-catalog age that warns. A source
	// maximum age above zero replaces it, unless the caller supplies an
	// explicit freshness policy.
	FreshnessChannelWarnAge = 6 * time.Hour

	// FreshnessChannelCriticalAge is the served-catalog age that is critical.
	// A source maximum age above zero replaces it with the scaled age, unless
	// the caller supplies an explicit freshness policy.
	FreshnessChannelCriticalAge = 10 * time.Hour

	// FreshnessSourceCheckWarnAge is the source-check age that warns.
	FreshnessSourceCheckWarnAge = 90 * time.Minute

	// FreshnessSourceCheckCriticalAge is the source-check age that is critical.
	FreshnessSourceCheckCriticalAge = 2 * time.Hour

	// FreshnessAcquisitionWarnAge is the acquisition-success age that warns.
	FreshnessAcquisitionWarnAge = 5 * time.Hour

	// FreshnessAcquisitionCriticalAge is the acquisition-success age that is
	// critical.
	FreshnessAcquisitionCriticalAge = 8 * time.Hour
)

Freshness thresholds. They follow the four-hour publication cadence, the one-hour channel poll, and the six-hour end-to-end objective.

View Source 
const (
	// FallbackNone means an upstream generation is active.
	FallbackNone = ""

	// FallbackAwaitingSource means no upstream reply arrived yet.
	FallbackAwaitingSource = "awaiting_source"

	// FallbackSourceUnavailable means every source read failed so far.
	FallbackSourceUnavailable = "source_unavailable"
)

Fallback reasons. They say why the runtime still serves the verified embedded catalog instead of an upstream generation.

View Source 
const (
	// SourcePublic reads the attested public GitHub catalog channel.
	SourcePublic = status.SourcePublic

	// SourceGitHub reads an attested channel from a named repository.
	SourceGitHub = status.SourceGitHub

	// SourceStarmap reads from another Starmap runtime.
	SourceStarmap = status.SourceStarmap

	// SourceFile reads one immutable generation from a local path.
	SourceFile = status.SourceFile

	// SourceEmbedded pins the runtime to the verified embedded bootstrap.
	SourceEmbedded = status.SourceEmbedded
)

Source kinds. Selection is terminal, so a deployment that names a custom source never falls back to the public GitHub channel.

View Source 
const (
	// FreshnessUnknown means no observation supports an evaluation yet.
	FreshnessUnknown = status.FreshnessUnknown

	// FreshnessCurrent means the age is inside every threshold.
	FreshnessCurrent = status.FreshnessCurrent

	// FreshnessWarn means the age passed the warning threshold.
	FreshnessWarn = status.FreshnessWarn

	// FreshnessCritical means the age passed the critical threshold.
	FreshnessCritical = status.FreshnessCritical
)

Freshness grades of one observed timestamp.

View Source 
const (
	// HealthUnknown means the component has not reported yet.
	HealthUnknown = status.HealthUnknown

	// HealthOK means the component reached its last objective.
	HealthOK = status.HealthOK

	// HealthDegraded means the component works with reduced evidence.
	HealthDegraded = status.HealthDegraded

	// HealthUnavailable means the component cannot reach its dependency.
	HealthUnavailable = status.HealthUnavailable
)

Health states of one runtime component.

View Source 
const (
	// DefaultAcquisitionInterval is the acquisition period.
	DefaultAcquisitionInterval = 4 * time.Hour
)

Acquisition policy defaults. Acquisition has exactly two settings: whether it runs, and how often. No start-time or mode setting exists.

View Source 
const FleetRecoveryOriginVersion = 1

FleetRecoveryOriginVersion identifies the explicit closed-import evidence schema.

View Source 
const MaxCatalogRetentionRecordBytes = maxRetainedCatalogRecordBytes

MaxCatalogRetentionRecordBytes bounds encoded and decoded original retention envelopes. JSON encoding can expand raw capsule bytes to twice the raw input bound.

View Source 
const MaxFleetRecoveryBytes = storage.DefaultRetentionInputMaxBytes

MaxFleetRecoveryBytes bounds both encoded and decoded private inputs for one fleet publication.

Variables

This section is empty.

Functions

func CatalogRecoveryChecksums added in v0.17.0 

func CatalogRecoveryChecksums(ctx context.Context, path string, owner DirectoryOwner, identity string, generation catalogs.Generation) ([]string, error)

CatalogRecoveryChecksums lists immutable input-record identities for an exact generation. These checksums name compressed local descriptors, not exported FleetRecovery bytes. The caller must fence writers. Multiple results require an explicit selection. Listing never proves which publication committed or whether independent history is complete.

func CheckRetainedCatalogRecovery added in v0.17.0 

func CheckRetainedCatalogRecovery(ctx context.Context, request CatalogRetainedReadRequest, comparison *CatalogRetentionComparison) (resultErr error)

CheckRetainedCatalogRecovery compares current retained bytes with checked original input. It checks the native owner, completed batch, manifest, exact entry, and bounded envelope hash. It does not decode unchanged input, repair files, select a catalog, or establish current permission.

func InspectCapturedCatalogRetention added in v0.17.0 

func InspectCapturedCatalogRetention(ctx context.Context, name string, raw []byte) (CatalogRetentionEntry, CatalogRetentionInput, error)

InspectCapturedCatalogRetention checks original immutable envelope bytes without opening a runtime. It checks structure and generation identity. It proves no completed batch, selection, ownership, or permission. The host must verify the complete original archive census and publication records separately.

func InspectRetainedCatalogMaterialization added in v0.17.0 

func InspectRetainedCatalogMaterialization(ctx context.Context, request CatalogRetainedMaterializationRequest, expected CatalogMaterializationReceipt, opts ...Option) (resultErr error)

InspectRetainedCatalogMaterialization verifies the current pre-activation input selection. It requires existing complete journals, exact batch coverage, and compatible target settings. A later input update refuses this check. Historical completed retries still return their original receipt. Inspection never repairs records, changes selection, or renews permission.

func InspectRetainedDirectory added in v0.17.0 

func InspectRetainedDirectory(ctx context.Context, path string, owner DirectoryOwner, identity string) error

InspectRetainedDirectory validates private runtime records without opening a runtime. The caller must fence writers and verify the complete inventory around inspection. This check preserves identity and replay evidence. It does not approve replica reuse, deployment settings, accepted-catalog consistency, permission freshness, or admission. Path-bound migration records require their separate recovery procedure.

func InspectRetainedMigration added in v0.17.0 

func InspectRetainedMigration(ctx context.Context, originalDirectory string, owner DirectoryOwner, identity string, read RetainedRecordReader) ([]string, error)

InspectRetainedMigration identifies completed migration records to keep inactive during restore. The caller supplies the captured directory name, configured owner and explicit scheduler identity. Paths in historical records are opaque identities. This check never opens those paths. The caller must verify the complete backup and the remaining runtime tree separately. This result does not approve current permission, external fencing, or replica reuse.

func InspectRetainedPublications added in v0.17.0 

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

InspectRetainedPublications selects native journals and matching staging files to keep inactive. The caller must supply the complete verified runtime inventory and preserve all selected bytes. Destination records remain active and require separate owner validation. This check never promotes staging files. Native file identities are historical. This result does not authorize cleanup or admission.

func PrepareAcquisitionReplay added in v0.17.0 

func PrepareAcquisitionReplay(ctx context.Context, baseline catalogs.Generation, publisherID string, bindings []sources.ProviderAcquisitionBinding, observations []sources.Observation, runID string, completedAt time.Time) (catalogs.Generation, []sources.Observation, error)

PrepareAcquisitionReplay returns a catalog generation and the original inputs needed for later replay. It retains compacted inputs only when catalog facts, provenance, membership, and current reviews remain exact. Current metadata reviews retain their latest original observation. Omission preserves the last review.

The retained inputs must fit the retained payload bound. The supplied history can exceed it. The caller authenticates the baseline and inputs. This function reads no sources or storage.

func PrepareCatalogRecoveryDirectory added in v0.17.0 

func PrepareCatalogRecoveryDirectory(ctx context.Context, path string, owner DirectoryOwner, identity string) (resultErr error)

PrepareCatalogRecoveryDirectory establishes private owner, seed, and empty layer directories. It opens no runtime, reads no catalog source, and creates no selection or permission. Existing owner and seed records must match. Missing records in retained state require recovery. An already selected materialization requires passive inspection instead of preparation.

The host must fence writers and call this only before sealing its native activation decision. Restart paths must inspect the retained directory instead of invoking preparation.

func ReplayAcquisition added in v0.17.0 

func ReplayAcquisition(ctx context.Context, baseline catalogs.Generation, publisherID string, bindings []sources.ProviderAcquisitionBinding, observations []sources.Observation) (*starmap.Candidate, error)

ReplayAcquisition rebuilds an ordered observation history above an explicit baseline. The caller authenticates the baseline and observations, and selects the active bindings. The baseline can contain this publisher's prior scopes but cannot carry enterprise authority. This function reads no sources or storage and starts no runtime workers.

func ValidateCatalogReplay added in v0.17.0 

func ValidateCatalogReplay(ctx context.Context, generation catalogs.Generation, recovery CatalogRecovery, opts ...Option) error

ValidateCatalogReplay checks exact retained inputs against the supplied deployment settings. It starts no acquisition, writes, clock observation, or lease operation. Success grants no serving permission and does not prove independent recovery history.

func ValidateDirectoryPermissions added in v0.17.0 

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

ValidateDirectoryPermissions checks existing runtime identity paths without writes. Linux and macOS require the effective UID and no group or other mode bits. macOS also restricts ACL grants to the owner. Deny entries remain valid. Windows requires the process account owner and limits grants to that account, SYSTEM, and Administrators.

Linux and macOS also check ancestor ownership, directory-entry protection, and selected symlink routes. Windows also checks ancestor DACLs and selected symlink routes. Effective access and native Windows execution require separate qualification. Other platforms check file types only. Windows native qualification remains required.

An empty directory selects in-memory state. Missing paths remain absent.

func ValidateFleetRecovery added in v0.17.0 

func ValidateFleetRecovery(ctx context.Context, snapshot FleetSnapshot) error

ValidateFleetRecovery checks retained input structure without opening a runtime. It grants no permission and does not check compatibility with deployment settings.

func ValidateFleetReplay added in v0.17.0 

func ValidateFleetReplay(ctx context.Context, snapshot FleetSnapshot, opts ...Option) error

ValidateFleetReplay reproduces a retained catalog under the supplied runtime settings. It starts no runtime, acquisition, clock observation, filesystem access, or lease. Successful validation does not renew a receipt or authorize an inference attempt.

func VerifyDirectoryMigrationPublication added in v0.17.0 

func VerifyDirectoryMigrationPublication(ctx context.Context, request DirectoryMigrationRequest) error

VerifyDirectoryMigrationPublication verifies publication before a host opens the target. It verifies the source inventory, journal, receipts, owner, and seed without starting a runtime. Journal recovery can preserve and truncate an interrupted final event.

Types

type Acquirer 

type Acquirer interface {
	AcquireProviders(ctx context.Context, request AcquisitionRequest) (AcquisitionResult, error)
}

Acquirer collects provider observations for the runtime. The root package selects no concrete provider client, so the deployment injects this role. Package acquisition supplies the built-in composition.

type AcquisitionPolicy 

type AcquisitionPolicy struct {
	// Enabled reports whether scheduled acquisition runs.
	Enabled bool

	// Interval is the acquisition period. The scheduler places each instance
	// at a stable phase inside the interval. Zero means one startup pass and
	// no periodic work.
	Interval time.Duration
}

AcquisitionPolicy configures all scheduled acquisition. The policy is exactly one switch and one period.

func DefaultAcquisitionPolicy 

func DefaultAcquisitionPolicy() AcquisitionPolicy

DefaultAcquisitionPolicy returns the canonical acquisition policy.

func (AcquisitionPolicy) Validate 

func (p AcquisitionPolicy) Validate() error

Validate checks the acquisition period. Zero is valid and selects one startup pass, so an operator schedules a single run without a cadence.

type AcquisitionReport 

type AcquisitionReport struct {
	// RunID is the identity of the run that produced this report.
	RunID string

	// StartedAt and CompletedAt bound the run.
	StartedAt   time.Time
	CompletedAt time.Time

	// Eligible counts provider targets, or bindings when the active set is explicit.
	Eligible int

	// Succeeded, Skipped, and Failed count the terminal attempts.
	Succeeded int
	Skipped   int
	Failed    int

	// Attempts holds one terminal attempt per eligible provider or binding.
	Attempts []sources.ProviderAttempt

	// SourceObservations binds each non-provider result to its original receipt.
	SourceObservations []catalogs.SourceObservationLink

	// SourceActivities holds the reported selection and attempts for this run.
	SourceActivities []sources.SourceActivity

	// Published reports whether the runtime published a new effective catalog.
	Published bool

	// GenerationID identifies the published effective catalog.
	GenerationID string

	// Retained names the providers that kept their previous last-known-good
	// observation in at least one scope that this run did not replace.
	Retained []catalogs.ProviderID

	// Health grades the run. A failed provider degrades the run.
	Health Health
}

AcquisitionReport says what one acquisition run produced. A partial failure still publishes: the report names the providers that kept their own last-known-good observation.

type AcquisitionRequest 

type AcquisitionRequest struct {
	// RunID is the run identity that logs and status report.
	RunID string

	// Current is the immutable catalog the run starts from.
	Current *catalogs.Catalog

	// Providers restricts the run. An empty list observes every eligible
	// provider.
	Providers []catalogs.ProviderID

	// CoalesceWindow bounds how long completed observations wait for a slower
	// sibling before they publish.
	CoalesceWindow time.Duration

	// Publish emits the layers that completed inside one coalescing window.
	// The runtime retains them, rebuilds the effective catalog, and publishes
	// one generation under the lease epoch of the run. An acquirer that emits
	// nothing early leaves the field unused, and the runtime then publishes
	// every layer once the run returns.
	Publish func(context.Context, []ProviderLayer) error
}

AcquisitionRequest describes one provider acquisition run.

type AcquisitionResult 

type AcquisitionResult struct {
	// Eligible counts provider targets, or bindings when the active set is explicit.
	Eligible int

	// Attempts holds one terminal attempt per eligible provider or binding.
	Attempts []sources.ProviderAttempt

	// Layers holds one successful observation per provider or binding.
	Layers []ProviderLayer
}

AcquisitionResult is what one acquisition run observed.

type BaselinePromotion added in v0.17.0 

type BaselinePromotion struct {
	// ExpectedHead is the accepted publication that the operator reviewed.
	ExpectedHead FleetHead
	// PackagedGenerationID must name the embedded baseline of this binary.
	PackagedGenerationID string
}

BaselinePromotion selects the packaged baseline at one observed fleet head.

type BaselinePromotionResult added in v0.17.0 

type BaselinePromotionResult struct {
	// Head is the fleet publication that retains the promoted baseline.
	Head FleetHead
	// Previous identifies the retained baseline before promotion.
	Previous catalogs.GenerationIdentity
	// Promoted identifies the packaged baseline that the fleet now retains.
	Promoted catalogs.GenerationIdentity
	// InertRemovals lists retained removal targets that match nothing in the promoted catalog.
	// They stay recorded until an explicit removal edit replaces them.
	InertRemovals []catalogs.CatalogRemovalTarget
}

BaselinePromotionResult describes one accepted baseline promotion.

type BaselineStatus added in v0.17.0 

type BaselineStatus struct {
	// Packaged identifies the embedded baseline compiled into this binary.
	Packaged catalogs.GenerationIdentity
	// Retained identifies the baseline that the accepted fleet publication replays.
	Retained catalogs.GenerationIdentity
	// Head is the accepted fleet publication that this replica observed.
	Head FleetHead
	// Promotable reports whether PromoteEmbeddedBaseline can adopt Packaged at Head.
	// It does not establish lease ownership.
	Promotable bool
	// Refusal explains why promotion is unavailable. It is empty when Promotable is true.
	Refusal string
}

BaselineStatus compares this binary's packaged baseline with the fleet's retained baseline.

type BindingAcquirer added in v0.17.0 

type BindingAcquirer interface {
	AcquireProviderBindings(context.Context, AcquisitionRequest, []sources.ProviderAcquisitionBinding) (AcquisitionResult, error)
}

BindingAcquirer observes only the supplied active declarations. It must preserve each declaration from credential selection through its receipt. Implementations also implement Acquirer for runtime injection.

type CapturedCatalogBinding added in v0.17.0 

type CapturedCatalogBinding struct {
	ManifestChecksum string
	GenerationID     string
	PayloadChecksum  string
}

CapturedCatalogBinding identifies the retained generation that the host must independently verify.

type CapturedCatalogRecovery added in v0.17.0 

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

CapturedCatalogRecovery holds structurally checked original descriptor and baseline inputs. It proves no archive completeness, publication, target ownership, semantics, or permission.

func InspectCapturedCatalogRecovery added in v0.17.0 

func InspectCapturedCatalogRecovery(ctx context.Context, name string, descriptor []byte, readBaseline func(context.Context, string, int64) ([]byte, error)) (*CapturedCatalogRecovery, error)

InspectCapturedCatalogRecovery checks original archive bytes without opening a runtime directory. The host supplies a bounded reader for the original baseline and verifies the complete archive census. Historical inputs receive structural validation. Target replay and permission checks remain separate.

func (*CapturedCatalogRecovery) Binding added in v0.17.0 

func (p *CapturedCatalogRecovery) Binding() CapturedCatalogBinding

Binding returns checked identity fields without exposing private source inputs.

func (*CapturedCatalogRecovery) Format added in v0.17.0 

func (*CapturedCatalogRecovery) Format(state fmt.State, _ rune)

Format excludes private source configuration and baseline data from diagnostics.

func (*CapturedCatalogRecovery) RecoveryFor added in v0.17.0 

func (p *CapturedCatalogRecovery) RecoveryFor(ctx context.Context, generation catalogs.Generation) (CatalogRecovery, error)

RecoveryFor binds the original inputs to an independently retained complete generation. It creates a separate encoded copy. It neither replays target state nor renews permission.

type CatalogMaterializationInput added in v0.17.0 

type CatalogMaterializationInput struct {
	Generation catalogs.Generation `json:"generation"`
	Recovery   CatalogRecovery     `json:"recovery"`
}

CatalogMaterializationInput binds one retained generation to its exact reconstruction inputs. The caller retains catalog-store selection and authority evidence separately.

type CatalogMaterializationReceipt added in v0.17.0 

type CatalogMaterializationReceipt struct {
	Version                int                       `json:"version"`
	OperationID            string                    `json:"operation_id"`
	RequestSHA256          string                    `json:"request_sha256"`
	PlanSHA256             string                    `json:"plan_sha256"`
	InventorySHA256        string                    `json:"inventory_sha256"`
	DirectoryIdentity      privatefiles.EntryReceipt `json:"directory_identity"`
	SelectedManifestSHA256 string                    `json:"selected_manifest_sha256"`
	SelectedInputsSHA256   string                    `json:"selected_inputs_sha256"`
	CatalogPublisherID     string                    `json:"catalog_publisher_id"`
	BaselineManifestSHA256 string                    `json:"baseline_manifest_sha256"`
}

CatalogMaterializationReceipt records completed private-file replacement without catalog-store activation. DirectoryIdentity binds native ownership. InventorySHA256 binds the supplied ordered historical inputs.

func MaterializeCatalogRecovery added in v0.17.0 

func MaterializeCatalogRecovery(ctx context.Context, request CatalogMaterializationRequest, opts ...Option) (receipt CatalogMaterializationReceipt, resultErr error)

MaterializeCatalogRecovery replaces catalog inputs through a private operation journal. It preserves owner, instance seed, permission checkpoints, and origin discovery records. Pending work blocks runtime startup. An exact completed retry returns its original receipt without replacing later state.

func MaterializeRetainedCatalogRecovery added in v0.17.0 

func MaterializeRetainedCatalogRecovery(ctx context.Context, request CatalogRetainedMaterializationRequest, opts ...Option) (CatalogMaterializationReceipt, error)

MaterializeRetainedCatalogRecovery checks complete retained coverage and selects one capsule. Only the selected capsule must reproduce its generation under the supplied target settings. Completed retries return the original receipt without loading or recreating old envelopes.

type CatalogMaterializationRequest added in v0.17.0 

type CatalogMaterializationRequest struct {
	Directory         string                        `json:"directory"`
	Owner             DirectoryOwner                `json:"owner"`
	SchedulerIdentity string                        `json:"scheduler_identity"`
	OperationID       string                        `json:"operation_id"`
	Selected          int                           `json:"selected"`
	Inputs            []CatalogMaterializationInput `json:"inputs"`
}

CatalogMaterializationRequest selects private catalog inputs for an existing stopped runtime. Selected is an index into Inputs. Each input must reproduce its generation under the supplied options. Writers must remain fenced throughout recovery. This API grants no publication or serving permission.

type CatalogRecovery added in v0.17.0 

type CatalogRecovery struct {
	ManifestChecksum string        `json:"manifest_checksum"`
	Inputs           FleetRecovery `json:"inputs"`
}

CatalogRecovery binds retained private inputs to one complete catalog manifest. It records reconstruction evidence, not publication success or serving permission. Inputs use the same private encoding as fleet publications.

func CaptureFleetCatalogRecovery added in v0.17.0 

func CaptureFleetCatalogRecovery(ctx context.Context, snapshot FleetSnapshot) (CatalogRecovery, error)

CaptureFleetCatalogRecovery copies a validated fleet publication's private inputs. The result preserves the complete generation binding without inventing local ownership. The host must retain the original fleet selection and verify deployment settings separately.

func ReadCatalogRecovery added in v0.17.0 

func ReadCatalogRecovery(ctx context.Context, path string, owner DirectoryOwner, identity string, generation catalogs.Generation, recordChecksum string) (CatalogRecovery, error)

ReadCatalogRecovery reads exact private inputs without opening a runtime. The caller must fence writers and supply an independently retained generation and record checksum. Missing history refuses recovery. Current directory inputs never replace missing historical inputs.

func (CatalogRecovery) Validate added in v0.17.0 

func (r CatalogRecovery) Validate(generation catalogs.Generation) error

Validate checks the complete generation binding and bounded input bytes.

type CatalogRetainedMaterializationRequest added in v0.17.0 

type CatalogRetainedMaterializationRequest struct {
	Directory         string                  `json:"directory"`
	Owner             DirectoryOwner          `json:"owner"`
	SchedulerIdentity string                  `json:"scheduler_identity"`
	OperationID       string                  `json:"operation_id"`
	TransferID        string                  `json:"transfer_id"`
	Batches           []CatalogRetentionBatch `json:"batches"`
	Selected          int                     `json:"selected"`
}

CatalogRetainedMaterializationRequest selects one entry from complete retained batch coverage. Batches must cover the full manifest once, in order, without gaps or overlaps.

type CatalogRetainedReadRequest added in v0.17.0 

type CatalogRetainedReadRequest struct {
	Directory         string                `json:"directory"`
	Owner             DirectoryOwner        `json:"owner"`
	SchedulerIdentity string                `json:"scheduler_identity"`
	TransferID        string                `json:"transfer_id"`
	Batch             CatalogRetentionBatch `json:"batch"`
	Index             int                   `json:"index"`
}

CatalogRetainedReadRequest selects one entry within an exact completed batch. Index is an absolute index in the complete transfer manifest.

type CatalogRetainedRecord added in v0.17.0 

type CatalogRetainedRecord struct {
	Entry        CatalogRetentionEntry `json:"entry"`
	RecordSHA256 string                `json:"record_sha256"`
}

CatalogRetainedRecord binds an immutable envelope to its manifest entry. Structural validation does not establish compatibility with current settings.

type CatalogRetentionBatch added in v0.17.0 

type CatalogRetentionBatch struct {
	OperationID   string `json:"operation_id"`
	ReceiptSHA256 string `json:"receipt_sha256"`
}

CatalogRetentionBatch selects an exact retained batch completion receipt.

type CatalogRetentionComparison added in v0.17.0 

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

CatalogRetentionComparison binds structurally checked original input to its canonical envelope. It retains private hashes and byte counts. It grants no ownership, selection, replay, or permission. Only InspectCatalogRetentionComparison can create a usable value.

func InspectCatalogRetentionComparison added in v0.17.0 

func InspectCatalogRetentionComparison(ctx context.Context, entry CatalogRetentionEntry, input CatalogRetentionInput) (*CatalogRetentionComparison, error)

InspectCatalogRetentionComparison checks original input and binds its canonical compressed envelope. The result contains no original data and has no serialized constructor. This inspection writes no files and contacts no sources.

func (CatalogRetentionComparison) Format added in v0.17.0 

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

Format excludes private entry identities and envelope hashes from diagnostics.

func (*CatalogRetentionComparison) Usage added in v0.17.0 

func (p *CatalogRetentionComparison) Usage() CatalogRetentionUsage

Usage returns the immutable byte counts from the original complete structural check. A nil or empty comparison returns zero counts.

type CatalogRetentionEntry added in v0.17.0 

type CatalogRetentionEntry struct {
	ManifestSHA256         string                 `json:"manifest_sha256"`
	InputsSHA256           string                 `json:"inputs_sha256"`
	SourceOrigin           CatalogRetentionOrigin `json:"source_origin"`
	SourceDescriptorSHA256 string                 `json:"source_descriptor_sha256"`
}

CatalogRetentionEntry binds original descriptor bytes and exported reconstruction inputs. InputsSHA256 is CatalogRecovery.Inputs.Checksum, not the local descriptor checksum.

type CatalogRetentionInput added in v0.17.0 

type CatalogRetentionInput struct {
	CatalogMaterializationInput
	SourceDescriptor []byte `json:"source_descriptor"`
}

CatalogRetentionInput supplies exact historical bytes without current deployment settings. Local descriptors use the original compressed localCatalogRecovery representation. The host validates fleet descriptors against their original publication inventory.

func ReadRetainedCatalogRecovery added in v0.17.0 

func ReadRetainedCatalogRecovery(ctx context.Context, request CatalogRetainedReadRequest) (input CatalogRetentionInput, resultErr error)

ReadRetainedCatalogRecovery exports original historical bytes without selection or repair. It verifies the native owner, completed batch, manifest, and immutable envelope. Returned data belongs to the caller. Success confers no current permission.

type CatalogRetentionOrigin added in v0.17.0 

type CatalogRetentionOrigin string

CatalogRetentionOrigin identifies the supplied historical descriptor format. Descriptors remain evidence and confer no current permission. 

const (
	CatalogRetentionLocalDescriptor CatalogRetentionOrigin = "local-descriptor"
	CatalogRetentionFleetDescriptor CatalogRetentionOrigin = "fleet-publication"
	CatalogRetentionNoDescriptor    CatalogRetentionOrigin = "no-descriptor"
)

Descriptor origin values distinguish original bytes from explicitly absent evidence.

type CatalogRetentionReceipt added in v0.17.0 

type CatalogRetentionReceipt struct {
	Version           int                       `json:"version"`
	Validation        string                    `json:"validation"`
	OperationID       string                    `json:"operation_id"`
	TransferID        string                    `json:"transfer_id"`
	RequestSHA256     string                    `json:"request_sha256"`
	PlanSHA256        string                    `json:"plan_sha256"`
	ManifestSHA256    string                    `json:"manifest_sha256"`
	BatchStart        int                       `json:"batch_start"`
	DirectoryIdentity privatefiles.EntryReceipt `json:"directory_identity"`
	Records           []CatalogRetainedRecord   `json:"records"`
}

CatalogRetentionReceipt records structural retention without selection or serving permission. It binds one native directory, the full manifest, and an exact batch range.

func RetainCatalogRecovery added in v0.17.0 

func RetainCatalogRecovery(ctx context.Context, request CatalogRetentionRequest) (receipt CatalogRetentionReceipt, resultErr error)

RetainCatalogRecovery preserves original historical capsules through a private operation journal. Validation is structural only. Pending retention blocks startup and selection. An exact completed retry returns its receipt without recreating missing records or changing later state.

type CatalogRetentionRequest added in v0.17.0 

type CatalogRetentionRequest struct {
	Directory         string                  `json:"directory"`
	Owner             DirectoryOwner          `json:"owner"`
	SchedulerIdentity string                  `json:"scheduler_identity"`
	OperationID       string                  `json:"operation_id"`
	TransferID        string                  `json:"transfer_id"`
	Manifest          []CatalogRetentionEntry `json:"manifest"`
	BatchStart        int                     `json:"batch_start"`
	Inputs            []CatalogRetentionInput `json:"inputs"`
}

CatalogRetentionRequest retains one contiguous batch from a complete transfer manifest. All batches share TransferID and Manifest, and use distinct OperationID values. Writers must remain fenced. This operation never changes the active catalog inputs.

type CatalogRetentionUsage added in v0.17.0 

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

CatalogRetentionUsage contains immutable byte counts without catalog data or private identities. It grants no retention, selection, current permission, or target ownership.

func InspectCatalogRetentionUsage added in v0.17.0 

func InspectCatalogRetentionUsage(ctx context.Context, entry CatalogRetentionEntry, input CatalogRetentionInput) (CatalogRetentionUsage, error)

InspectCatalogRetentionUsage checks one capsule through the producer's original codecs. Hosts can pack against both byte dimensions and the count bound without another decoder. RetainCatalogRecovery independently checks each final batch. This inspection writes no files and contacts no sources.

func (CatalogRetentionUsage) DecodedBytes added in v0.17.0 

func (u CatalogRetentionUsage) DecodedBytes() int64

DecodedBytes counts the decompressed original recovery record before JSON parsing.

func (CatalogRetentionUsage) Inputs added in v0.17.0 

func (u CatalogRetentionUsage) Inputs() int

Inputs reports the one structurally checked input. An empty result reports zero.

func (CatalogRetentionUsage) RawBytes added in v0.17.0 

func (u CatalogRetentionUsage) RawBytes() int64

RawBytes counts the serialized manifest, payload, compressed recovery, and original descriptor bytes.

type DirectoryMigrationCompletion added in v0.17.0 

type DirectoryMigrationCompletion struct {
	OperationID       string         `json:"operation_id"`
	SourceDirectory   string         `json:"source_directory"`
	TargetDirectory   string         `json:"target_directory"`
	SchedulerIdentity string         `json:"scheduler_identity"`
	Owner             DirectoryOwner `json:"owner"`
	ManifestSHA256    string         `json:"manifest_sha256"`
}

DirectoryMigrationCompletion binds a completed move to its retained source and target.

func ReadDirectoryMigrationCompletion added in v0.17.0 

func ReadDirectoryMigrationCompletion(ctx context.Context, directory string) (DirectoryMigrationCompletion, error)

ReadDirectoryMigrationCompletion verifies completion and the preserved source without writing files. It requires the source inventory, retirement record, target receipts, owner, and seed to match. It does not read the operation journal or compare mutable target catalog layers.

type DirectoryMigrationPreparation added in v0.17.0 

type DirectoryMigrationPreparation struct {
	JournalDirectory string `json:"journal_directory"`
	Phase            string `json:"phase"`
	FileCount        int    `json:"file_count"`
	IdentityVerified bool   `json:"identity_verified"`
}

DirectoryMigrationPreparation identifies the retained inventory and its journal. IdentityVerified is false for legacy state without an ownership record.

func PrepareDirectoryMigration added in v0.17.0 

func PrepareDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationPreparation, error)

PrepareDirectoryMigration records source checksums under an exclusive directory lock. It preserves source files, creates no target, and leaves configured roots unchanged. SourceIdentity must come from the old deployment. Legacy seeds alone cannot prove it.

type DirectoryMigrationPublication added in v0.17.0 

type DirectoryMigrationPublication struct {
	JournalDirectory  string `json:"journal_directory"`
	TargetDirectory   string `json:"target_directory"`
	SchedulerIdentity string `json:"scheduler_identity"`
	Phase             string `json:"phase"`
}

DirectoryMigrationPublication identifies the replacement and its migration phase. SchedulerIdentity must accompany the target directory in the replacement runtime's options.

func PublishDirectoryMigration added in v0.17.0 

func PublishDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationPublication, error)

PublishDirectoryMigration stages and publishes a verified copy, then retires the source. It preserves source data files and does not edit host configuration or complete root selection. Older source binaries must stay stopped because they do not honor retirement records.

type DirectoryMigrationRequest added in v0.17.0 

type DirectoryMigrationRequest struct {
	OperationID     string
	SourceDirectory string
	TargetDirectory string
	JournalRoot     string
	SourceIdentity  string
	Owner           DirectoryOwner
}

DirectoryMigrationRequest selects an explicit runtime-directory migration. Stop the source process before preparation, including older binaries without directory locks.

type DirectoryMigrationStage added in v0.17.0 

type DirectoryMigrationStage struct {
	JournalDirectory string `json:"journal_directory"`
	StageDirectory   string `json:"stage_directory"`
	Phase            string `json:"phase"`
	FileCount        int    `json:"file_count"`
	IdentityVerified bool   `json:"identity_verified"`
}

DirectoryMigrationStage identifies a verified copy that cannot yet serve a runtime.

func StageDirectoryMigration added in v0.17.0 

func StageDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationStage, error)

StageDirectoryMigration copies a stopped source into private staging and verifies its bytes. It preserves the source and leaves the selected target and configuration roots unchanged.

type DirectoryOwner added in v0.17.0 

type DirectoryOwner struct {
	Product    string `json:"product"`
	Deployment string `json:"deployment"`
	Instance   string `json:"instance"`
}

DirectoryOwner binds persistent runtime state to one product, deployment, and instance. This record does not replace the live directory lock or a shared identity fence.

func (DirectoryOwner) Validate added in v0.17.0 

func (o DirectoryOwner) Validate() error

Validate checks the ownership identity without creating files.

type FleetAcquisitionChecker added in v0.17.0 

type FleetAcquisitionChecker interface {
	CheckFleetAcquisition(context.Context, FleetAcquisitionRequirements) error
}

FleetAcquisitionChecker verifies access before grant acquisition or renewal. It must use acquisition credentials and must not fetch provider inventories.

type FleetAcquisitionRequirements added in v0.17.0 

type FleetAcquisitionRequirements struct {
	// Catalog contains reconciled provider metadata and need not match the serving catalog.
	Catalog *catalogs.Catalog
	// Providers contains retained scopes whose acquisition credentials remain required.
	Providers []catalogs.ProviderID
	// Candidates contains unobserved providers that can lack configured credentials.
	Candidates []catalogs.ProviderID
	Bindings   []sources.ProviderAcquisitionBinding
}

FleetAcquisitionRequirements identifies the acquisition access a refresh owner must retain. Bindings declare scopes. Unbound providers retain the deployment's implicit acquisition policy. No credential value or credential digest belongs in this record.

type FleetAdoption added in v0.17.0 

type FleetAdoption struct {
	Previous FleetHead `json:"previous"`
	Receipt  string    `json:"receipt"`
}

FleetAdoption identifies explicit host recovery without changing the original publication ownership evidence. The host must verify the receipt and independent approval before exposing this snapshot. This record grants no refresh lease or inference permission.

type FleetHead added in v0.17.0 

type FleetHead struct {
	Identity         FleetIdentity `json:"identity"`
	Revision         uint64        `json:"revision"`
	GenerationID     string        `json:"generation_id"`
	RecoveryChecksum string        `json:"recovery_checksum"`
}

FleetHead identifies one accepted publication, including its private recovery inputs. Revision increases for every publication, even when the catalog generation stays unchanged. The zero value selects an empty store. A populated head cannot use revision zero.

func (FleetHead) Validate added in v0.17.0 

func (h FleetHead) Validate() error

Validate accepts an empty head or a complete publication identity.

type FleetIdentity added in v0.17.0 

type FleetIdentity struct {
	DeploymentID  string `json:"deployment_id"`
	RecoveryEpoch uint64 `json:"recovery_epoch"`
	BackendID     string `json:"backend_id"`
}

FleetIdentity binds operations to an independently approved backend incarnation. The host gets this identity from its recovery authority, outside the catalog store. An address or a record restored inside that backend cannot establish this identity.

func (FleetIdentity) Validate added in v0.17.0 

func (i FleetIdentity) Validate() error

Validate requires a complete identity. It does not establish external approval.

type FleetPublication added in v0.17.0 

type FleetPublication struct {
	Generation     catalogs.Generation  `json:"generation"`
	Recovery       FleetRecovery        `json:"recovery"`
	Grant          Lease                `json:"grant"`
	Expected       FleetHead            `json:"expected"`
	RecoveryOrigin *FleetRecoveryOrigin `json:"recovery_origin,omitempty"`
}

FleetPublication retains one refresh grant or explicit recovery origin and its predecessor. A retry preserves all fields. It must not substitute newer ownership evidence or a predecessor.

func (FleetPublication) Validate added in v0.17.0 

func (p FleetPublication) Validate() error

Validate checks retained publication content and structural ownership evidence. It does not establish independent recovery approval, live lease ownership, or serving permission. Ordinary commit adapters must use ValidateRefreshPublication before their native transaction.

func (FleetPublication) ValidateRefreshPublication added in v0.17.0 

func (p FleetPublication) ValidateRefreshPublication() error

ValidateRefreshPublication refuses recovery imports through the ordinary refresh commit path. The backend must still compare the original live grant, expiry, approved identity, and head atomically.

type FleetRecovery added in v0.17.0 

type FleetRecovery struct {
	GenerationID    string `json:"generation_id"`
	PayloadChecksum string `json:"payload_checksum"`
	Checksum        string `json:"checksum"`
	Data            []byte `json:"data"`
}

FleetRecovery binds private acquisition inputs to one immutable generation. Stores retain these bytes with the generation and never expose them as public catalog data. The runtime owns the encoding. Hosts preserve the bytes without modification.

func (FleetRecovery) Validate added in v0.17.0 

func (r FleetRecovery) Validate(generation catalogs.Generation) error

Validate checks the generation binding and the complete input checksum. Runtime recovery separately validates the input schema and acquisition policy.

type FleetRecoveryOrigin added in v0.17.0 

type FleetRecoveryOrigin struct {
	Version                  int           `json:"version"`
	Identity                 FleetIdentity `json:"identity"`
	OperationID              string        `json:"operation_id"`
	AcceptedDecisionSHA256   string        `json:"accepted_decision_sha256"`
	ClosedImportSHA256       string        `json:"closed_import_sha256"`
	GenerationManifestSHA256 string        `json:"generation_manifest_sha256"`
	RecoverySHA256           string        `json:"recovery_sha256"`
}

FleetRecoveryOrigin binds catalog facts to a host-owned closed recovery import. The host must independently verify the accepted decision and closed import before exposing the publication. These digests describe retained evidence. They grant no refresh lease, authority receipt, or inference permission.

type FleetSnapshot added in v0.17.0 

type FleetSnapshot struct {
	Head        FleetHead        `json:"head"`
	Publication FleetPublication `json:"publication"`
	Adoption    *FleetAdoption   `json:"adoption,omitempty"`
}

FleetSnapshot retains the accepted publication and its original ownership evidence. Reading a snapshot proves neither a live grant nor independent recovery approval.

func (FleetSnapshot) Validate added in v0.17.0 

func (s FleetSnapshot) Validate() error

Validate checks that the head selects exactly this publication and its recovery inputs.

type FleetStatus added in v0.17.0 

type FleetStatus struct {
	Head             FleetHead
	ReplayReady      bool
	AcquisitionReady bool
}

FleetStatus describes the accepted publication and this replica's ability to replay its inputs. Replay readiness does not establish current lease ownership or inference permission.

type FleetStore added in v0.17.0 

type FleetStore interface {
	LeaseStore

	// CurrentHead reads publication metadata without transferring catalog or recovery payloads.
	CurrentHead(context.Context) (FleetHead, error)

	// CurrentPublication reads the complete durable head and the exact selected bytes.
	// Missing immutable bytes or recovery inputs are errors, never an empty-store result.
	CurrentPublication(context.Context) (FleetSnapshot, error)

	// Publication retrieves one retained publication by its complete head identity.
	Publication(context.Context, FleetHead) (FleetSnapshot, error)

	// Get retrieves a retained immutable catalog without exposing recovery inputs.
	Get(context.Context, string) (catalogs.Generation, error)

	// CommitPublication selects a refresh publication and recovery reference in one backend transaction.
	// It refuses RecoveryOrigin through ValidateRefreshPublication. Hosts import recovery separately.
	// It compares Expected, the exact holder, process session, epoch, live expiry, and recovery identity.
	// A refusal changes neither the head nor the recovery reference. Staged bytes confer no permission.
	//
	// An identical successful retry returns its original head while its receipt remains retained.
	// A retry after receipt collection refuses without another publication.
	// The store must prove that retry from the retained request, including its original grant.
	//
	// Lease expiry must not erase the durable epoch. Reuse of an active holder by another session fails.
	CommitPublication(context.Context, FleetPublication) (FleetHead, error)
}

FleetStore owns shared publication, retained inputs, and refresh ownership. Hosts supply the adapter. Standalone stores keep the separate storage.Store contract. Each method uses one deployment namespace and the approved backend incarnation. New or recovered connections must validate that incarnation before application operations.

type Freshness 

type Freshness = status.Freshness

Freshness is the evaluated age of one observed timestamp.

type FreshnessPolicy 

type FreshnessPolicy struct {
	ChannelWarnAge     time.Duration
	ChannelCriticalAge time.Duration

	SourceCheckWarnAge     time.Duration
	SourceCheckCriticalAge time.Duration

	AcquisitionWarnAge     time.Duration
	AcquisitionCriticalAge time.Duration
}

FreshnessPolicy holds the age thresholds that turn observed timestamps into a freshness level.

func DefaultFreshnessPolicy 

func DefaultFreshnessPolicy() FreshnessPolicy

DefaultFreshnessPolicy returns the canonical freshness thresholds.

func (FreshnessPolicy) Validate 

func (p FreshnessPolicy) Validate() error

Validate checks that every warning threshold precedes its critical partner.

type GenerationPinAcceptance added in v0.17.0 

type GenerationPinAcceptance struct {
	OperationID          string                        `json:"operation_id"`
	SelectedGenerationID string                        `json:"selected_generation_id"`
	AcceptedGenerationID string                        `json:"accepted_generation_id"`
	PreviousGenerationID string                        `json:"previous_generation_id"`
	PayloadChecksum      string                        `json:"payload_checksum"`
	AuthorityHead        catalogs.CatalogAuthorityHead `json:"authority_head,omitzero"`
	RequestedAt          time.Time                     `json:"requested_at"`
	AcceptedAt           time.Time                     `json:"accepted_at,omitzero"`
}

GenerationPinAcceptance identifies one verified selection and its publication. An origin rollback publishes the selected payload under a new authority generation. RequestedAt and AcceptedAt record local acceptance, not provider observation time.

type Health 

type Health = status.Health

Health is the operator-facing state of one runtime component.

type InputCollectionReport added in v0.17.0 

type InputCollectionReport struct {
	Scanned       int
	SnapshotBytes int64
	Protected     []string
	Preserved     []string
	Candidates    []string
	Removed       []string
}

InputCollectionReport separates protected references from unrecognized files and removable inputs. Scanned includes one possible entry beyond MaxEntries to detect overflow. SnapshotBytes counts captured raw records, excluding decoder and filesystem verification work. Removed includes visible deletions when later directory synchronization fails.

type InputCollectionRequest added in v0.17.0 

type InputCollectionRequest struct {
	MaxEntries int
	MaxBytes   int64
	DryRun     bool
}

InputCollectionRequest bounds one explicit scan of retained input files. MaxEntries includes unknown directory entries. MaxBytes bounds raw snapshot bytes. DryRun validates references and reports candidates without deleting files.

type Lease 

type Lease struct {
	// Holder names the instance that owns the lease.
	Holder string

	// Epoch increases on every fresh acquisition.
	Epoch uint64

	// SessionID identifies the process that acquired a fleet grant.
	// A restart uses a new session even when the configured holder name stays unchanged.
	SessionID string

	// Identity binds a fleet grant to the independently approved backend incarnation.
	// Legacy standalone lease adapters leave this identity empty.
	Identity FleetIdentity

	// ExpiresAt is when the lease lapses without a renewal.
	ExpiresAt time.Time
}

Lease is the exclusive right to commit a durable catalog generation. The epoch increases on every fresh acquisition, so a commit that carries an older epoch is stale.

type LeaseStore 

type LeaseStore interface {
	// AcquireLease takes the lease for the named holder. A store that another
	// holder owns returns an *errors.ConflictError. That refusal names a
	// non-owner state, not a failure. The runtime keeps serving its retained
	// catalog and tries again at the next run. Every other error fails Open.
	AcquireLease(ctx context.Context, holder string, ttl time.Duration) (Lease, error)

	// Renew extends a held lease without changing its holder, epoch, session, or recovery identity.
	// It fails when that grant expired or another holder took the lease.
	Renew(ctx context.Context, lease Lease, ttl time.Duration) (Lease, error)

	// Release returns the lease early.
	Release(ctx context.Context, lease Lease) error
}

LeaseStore is the shared-storage lease that fences durable commits. A deployment whose instances share no storage needs no lease store, and the runtime then commits without a fence.

type NetworkMode added in v0.17.0 

type NetworkMode string

NetworkMode controls outbound catalog acquisition, not inference or storage. 

const (
	// NetworkConfigured permits the selected catalog sources to use the network.
	NetworkConfigured NetworkMode = "configured"
	// NetworkOffline refuses network source reads and acquisition.
	NetworkOffline NetworkMode = "offline"
)

func ParseNetworkMode added in v0.17.0 

func ParseNetworkMode(value string) (NetworkMode, error)

ParseNetworkMode accepts an explicit configured or offline selection.

type ObservationInputs added in v0.17.0 

type ObservationInputs struct {
	// Current is the complete accepted effective generation.
	Current starmap.CatalogState
	// Baseline is the retained upstream generation, or the compiled catalog when no upstream layer exists.
	Baseline starmap.CatalogState
}

ObservationInputs separates accepted local facts from the selected baseline. Both catalogs are immutable snapshots. Baseline excludes this runtime's local observations.

type ObservationReset added in v0.17.0 

type ObservationReset struct {
	// SourceID selects provider APIs or one models.dev source.
	SourceID sources.ID `json:"source,omitempty"`
	// ProviderID selects an original source provider identity. Empty selects an entire metadata source.
	ProviderID catalogs.ProviderID `json:"provider_id"`
	// BindingID selects one declared acquisition binding, or legacy unscoped input when empty.
	BindingID string `json:"binding_id,omitempty"`
	// BindingRevision selects that binding's declared revision.
	BindingRevision string `json:"binding_revision,omitempty"`
}

ObservationReset names local acquisition evidence to replace. Empty SourceID selects provider APIs for compatibility.

type ObservationUpdate added in v0.17.0 

type ObservationUpdate struct {
	Observations []sources.Observation
	Resets       []ObservationReset
}

ObservationUpdate contains original acquisition results and explicit reset scopes. Acquisition derives scopes from the sources and bindings that actually completed.

type Option 

type Option func(*options) error

Option configures the connected runtime. The offline constructors in the root package take their own option type, so no offline constructor accepts a connected-runtime setting.

func WithAcquirer 

func WithAcquirer(acquirer Acquirer) Option

WithAcquirer injects the provider acquisition composition. The root package selects no concrete provider client. Non-provider acquisition uses WithSourceAcquirer.

func WithAcquisitionEnabled 

func WithAcquisitionEnabled(enabled bool) Option

WithAcquisitionEnabled turns all scheduled acquisition on or off.

func WithAcquisitionInterval 

func WithAcquisitionInterval(interval time.Duration) Option

WithAcquisitionInterval sets the acquisition period. Zero selects one startup pass and no periodic work.

func WithAcquisitionSources added in v0.17.0 

func WithAcquisitionSources(ids ...sources.ID) Option

WithAcquisitionSources selects permitted local acquisition and retained evidence. An explicit empty set disables every acquisition source. It preserves the selected baseline. Omission preserves the acquisition roles and retained inputs that the caller supplies.

func WithAuthorityOrigin added in v0.17.0 

func WithAuthorityOrigin(store storage.Store, config OriginConfig) Option

WithAuthorityOrigin selects the sole publication store and authorizes a catalog origin. Its store takes precedence over stores passed through WithClientOptions, independent of option order. Source, workspace, and acquisition options still apply. An authoritative subscriber cannot also be an origin. All writers to the underlying store must enforce the same authority publication contract.

func WithCatalogNetworkMode added in v0.17.0 

func WithCatalogNetworkMode(value string) Option

WithCatalogNetworkMode selects configured or offline catalog acquisition.

func WithCatalogSource 

func WithCatalogSource(name string) Option

WithCatalogSource selects the upstream catalog source by name. It accepts public, github, starmap, file, and embedded. A named custom source is terminal: the runtime never falls back to the public channel.

func WithClientOptions 

func WithClientOptions(opts ...starmap.Option) Option

WithClientOptions forwards offline client options to the Starmap client that the runtime publishes into. The root package owns the catalog store, the workspace path, and the embedded bootstrap budgets. One composition therefore supplies both kinds of setting in one list.

func WithClock 

func WithClock(now func() time.Time) Option

WithClock injects the runtime clock. Tests use it to keep timing exact.

func WithCoalesceWindow 

func WithCoalesceWindow(window time.Duration) Option

WithCoalesceWindow bounds how long completed provider observations wait for a slower sibling before they publish.

func WithCompletedDirectoryMigration added in v0.17.0 

func WithCompletedDirectoryMigration(completion DirectoryMigrationCompletion) Option

WithCompletedDirectoryMigration requires the observed completion record during startup. The host must select its target directory, owner, and retained scheduler identity. Open rechecks the preserved source and target under its directory lock.

func WithDirectoryOwner added in v0.17.0 

func WithDirectoryOwner(owner DirectoryOwner) Option

WithDirectoryOwner selects the identity recorded for persistent runtime state. A different recorded identity requires an explicit migration before startup.

func WithFleetAuthorityOrigin added in v0.17.0 

func WithFleetAuthorityOrigin(store FleetStore, origin OriginConfig) Option

WithFleetAuthorityOrigin selects one fleet store for origin publication and permission issuance. The adapter must support independent authority-head observations.

func WithFleetStore added in v0.17.0 

func WithFleetStore(store FleetStore) Option

WithFleetStore selects shared catalog publication and refresh ownership together. The runtime stores acquisition inputs with each shared publication, outside its private directory. The fleet store takes precedence over stores passed through WithClientOptions.

func WithFreshnessPolicy 

func WithFreshnessPolicy(policy FreshnessPolicy) Option

WithFreshnessPolicy replaces the freshness thresholds. An explicit policy wins, so WithSourceMaxAge then derives no channel threshold.

func WithGenerationPin added in v0.17.0 

func WithGenerationPin(id string) Option

WithGenerationPin selects one retained generation for this runtime's lifetime. The host persists this setting in its configuration authority. An empty value clears it. Replacing the runtime applies a changed pin. Permission observation remains active.

func WithLeaseStore 

func WithLeaseStore(store LeaseStore) Option

WithLeaseStore injects the shared-storage lease that fences durable commits. A deployment without shared storage needs no lease.

func WithListenAddress 

func WithListenAddress(address string) Option

WithListenAddress records the server listen address. It does not change instance identity.

func WithModelsDevGitCommit added in v0.17.0 

func WithModelsDevGitCommit(commit string) Option

WithModelsDevGitCommit sets the exact commit for models.dev Git acquisition. Empty clears an inherited pin. This option does not select the Git source.

func WithOwnedSource added in v0.17.0 

func WithOwnedSource(source OwnedSource) Option

WithOwnedSource transfers the selected source to the runtime during Open. Open failure and runtime shutdown close it. Only the final selected source transfers. WithSource keeps ownership with the caller and replaces this selection.

func WithPermissionClock added in v0.17.0 

func WithPermissionClock(sample func() permission.ClockReading) Option

WithPermissionClock supplies one qualified time and uncertainty sample for each permission check. The callback reads cached evidence and supports concurrent calls. It starts no I/O. It governs admission, permission relay, and permission status independently of the scheduler clock. Use WithPermissionClockUncertainty only when this option is absent. The caller owns native clock qualification.

func WithPermissionClockMonitor added in v0.17.0 

func WithPermissionClockMonitor(monitor *permission.ClockMonitor) Option

WithPermissionClockMonitor assigns one unstarted monitor to this runtime. Open starts it before source startup and owns its shutdown after a successful start. A failed Open cancels any monitor it started. It leaves a monitor owned elsewhere alone. Select this option without either external permission-clock callback. An origin can also use this monitor's Read method in OriginConfig.Clock.

func WithPermissionClockUncertainty added in v0.17.0 

func WithPermissionClockUncertainty(sample func() (time.Duration, bool)) Option

WithPermissionClockUncertainty supplies the host's cached clock assurance. The callback reads cached memory only. It reports uncertainty for WithClock's time and false when its evidence is absent or expired. No callback means unknown.

func WithProviderBindings added in v0.17.0 

func WithProviderBindings(bindings ...sources.ProviderAcquisitionBinding) Option

WithProviderBindings selects the complete active set for local provider evidence. An empty set permits no local provider evidence. The set excludes unscoped evidence. The runtime copies the declarations. A changed set requires a new runtime.

func WithPublishedDirectoryMigration added in v0.17.0 

func WithPublishedDirectoryMigration(request DirectoryMigrationRequest) Option

WithPublishedDirectoryMigration requires the exact published target during startup. The host must also select the request's directory, owner, and scheduler identity. Open verifies migration records under its directory lock before persistent initialization.

func WithRandom 

func WithRandom(random Random) Option

WithRandom injects the jitter source that spreads scheduled work.

func WithRefreshTimeout 

func WithRefreshTimeout(timeout time.Duration) Option

WithRefreshTimeout bounds one whole refresh run. Zero, the default, adds no deadline, so a long transfer inside its own bounds is not cut short.

func WithRetentionEnabled added in v0.17.0 

func WithRetentionEnabled(enabled bool) Option

WithRetentionEnabled selects automatic collection. Explicit collection remains available.

func WithRetentionInputMaxBytes added in v0.17.0 

func WithRetentionInputMaxBytes(bytes int64) Option

WithRetentionInputMaxBytes bounds raw retained input bytes captured during one scan.

func WithRetentionInterval added in v0.17.0 

func WithRetentionInterval(interval time.Duration) Option

WithRetentionInterval sets the positive delay between scheduled collection passes.

func WithRetentionMaxBytes added in v0.17.0 

func WithRetentionMaxBytes(bytes int64) Option

WithRetentionMaxBytes sets the retained generation byte target.

func WithRetentionMaxGenerations added in v0.17.0 

func WithRetentionMaxGenerations(count int) Option

WithRetentionMaxGenerations sets the retained generation count target.

func WithRetentionPolicy added in v0.17.0 

func WithRetentionPolicy(policy RetentionPolicy) Option

WithRetentionPolicy replaces the complete runtime collection policy.

func WithRetentionScanEntries added in v0.17.0 

func WithRetentionScanEntries(entries int) Option

WithRetentionScanEntries bounds the entries inspected during one collection pass.

func WithSchedulerIdentity 

func WithSchedulerIdentity(identity string) Option

WithSchedulerIdentity overrides the derived instance identity. Use it when the deployment already owns a stable instance name.

func WithSource 

func WithSource(source Source) Option

WithSource injects a deployment-owned upstream source. It replaces every built-in source implementation.

func WithSourceAPIKey 

func WithSourceAPIKey(key string) Option

WithSourceAPIKey supplies the source API key. The runtime keeps the key out of status, logs, and errors.

func WithSourceAcquirer added in v0.17.0 

func WithSourceAcquirer(acquirer SourceAcquirer) Option

WithSourceAcquirer adds non-provider acquisition beside the provider role. This option starts no source reads. Scheduled and explicit Sync runs use this role.

func WithSourceAliases 

func WithSourceAliases(aliases ...string) Option

WithSourceAliases declares the other stable identities that name this same runtime. A served source chain that names one of them is a self reference. The runtime then refuses the read instead of serving its own catalog back to itself.

func WithSourceAuthority added in v0.17.0 

func WithSourceAuthority(authorityID, policyID string) Option

WithSourceAuthority pins the authority and policy used by require_authority. It changes neither the source address nor the startup policy.

func WithSourceAuthorityID added in v0.17.0 

func WithSourceAuthorityID(identity string) Option

WithSourceAuthorityID selects the authority identity required by the source policy.

func WithSourceChannel 

func WithSourceChannel(channel string) Option

WithSourceChannel names the mutable branch that selects the current catalog.

func WithSourceMaxAge 

func WithSourceMaxAge(maxAge time.Duration) Option

WithSourceMaxAge sets the age at which the served catalog counts as stale. It also derives the channel freshness thresholds. The warning age becomes the maximum age, and the critical age keeps the six-to-ten ratio of the defaults. WithFreshnessPolicy wins over this derivation.

func WithSourceMaxHops 

func WithSourceMaxHops(hops int) Option

WithSourceMaxHops bounds a cascade of Starmap runtimes.

func WithSourcePolicy 

func WithSourcePolicy(policy SourcePolicy) Option

WithSourcePolicy replaces the whole upstream source policy.

func WithSourcePolicyID added in v0.17.0 

func WithSourcePolicyID(identity string) Option

WithSourcePolicyID selects the permission policy within the configured authority.

func WithSourcePollInterval 

func WithSourcePollInterval(interval time.Duration) Option

WithSourcePollInterval sets the channel check period.

func WithSourceRefreshMode added in v0.17.0 

func WithSourceRefreshMode(value string) Option

WithSourceRefreshMode selects automatic or explicit-only source refresh.

func WithSourceRepository 

func WithSourceRepository(repository string) Option

WithSourceRepository names the catalog repository of a GitHub channel.

func WithSourceSignerWorkflow 

func WithSourceSignerWorkflow(workflow string) Option

WithSourceSignerWorkflow pins the build provenance the source accepts.

func WithSourceStartupPolicy 

func WithSourceStartupPolicy(name string) Option

WithSourceStartupPolicy decides what the runtime serves before the first upstream reply.

func WithSourceToken 

func WithSourceToken(token string) Option

WithSourceToken supplies the source access token. The runtime keeps the token out of status, logs, and errors.

func WithSourceURL 

func WithSourceURL(url string) Option

WithSourceURL sets the deployment-owned source address used by the starmap and file sources.

func WithStartupSpread 

func WithStartupSpread(spread time.Duration) Option

WithStartupSpread bounds the random delay before the first scheduled run.

func WithStateDirectory 

func WithStateDirectory(directory string) Option

WithStateDirectory selects the durable directory that retains layers, the scheduler identity seed, and source discovery state. Open requires an absolute path and holds an exclusive directory lock until shutdown finishes.

func WithTransferIdleTimeout 

func WithTransferIdleTimeout(timeout time.Duration) Option

WithTransferIdleTimeout bounds a stalled transfer.

func WithTransferMaxDuration 

func WithTransferMaxDuration(duration time.Duration) Option

WithTransferMaxDuration bounds one whole transfer.

func WithUpdatePolicy added in v0.17.0 

func WithUpdatePolicy(policy UpdatePolicy) Option

WithUpdatePolicy replaces both catalog update controls.

func WithoutAuthorityOrigin added in v0.17.0 

func WithoutAuthorityOrigin() Option

WithoutAuthorityOrigin clears earlier origin issuance and publication options. The selected store remains in use. Its authority still requires an explicit transition before ordinary startup, or a matching require_authority subscriber configuration.

func WithoutPermissionClock added in v0.17.0 

func WithoutPermissionClock() Option

WithoutPermissionClock clears earlier monitor and callback selections. No clock evidence remains until a later option supplies a clock explicitly.

type OriginConfig added in v0.17.0 

type OriginConfig struct {
	AuthorityID string
	PolicyID    string
	// Bootstrap permits the runtime to adopt an existing ordinary catalog store.
	// It cannot change an established authority or reset its sequence.
	Bootstrap          bool
	PermissionLifetime time.Duration
	Clock              func() permission.ClockReading
}

OriginConfig explicitly authorizes this runtime to publish and issue permissions for one catalog authority. The complete catalog selected by the runtime defines this policy's permitted catalog. Clock must supply qualified, cached time evidence. An unknown reading prevents receipt issuance. The deployment owns clock qualification and access control for all catalog mutations.

type OwnedSource added in v0.17.0 

type OwnedSource interface {
	Source
	Shutdown(context.Context) error
}

OwnedSource supplies a source and its shutdown operation. Shutdown cancels and joins source-owned work unless its context ends first. With a live context, it must finish joining before returning any cleanup error. Repeated calls must be safe.

type OwnerRecordStatus added in v0.17.0 

type OwnerRecordStatus string

OwnerRecordStatus describes a stored binding, not an active lock or seed verification. 

const (
	// OwnerRecordMatches means the canonical record matches the configured owner and identity override.
	OwnerRecordMatches OwnerRecordStatus = "matches"
	// OwnerRecordAbsent means the selected directory or record does not exist.
	OwnerRecordAbsent OwnerRecordStatus = "absent"
	// OwnerRecordConflict means the record or directory is invalid or has another binding.
	OwnerRecordConflict OwnerRecordStatus = "conflict"
	// OwnerRecordUnavailable means the metadata or bounded record read failed.
	OwnerRecordUnavailable OwnerRecordStatus = "unavailable"
	// OwnerRecordUnverified means the native inspection adapter is unavailable.
	OwnerRecordUnverified OwnerRecordStatus = "unverified"
)

func InspectDirectoryOwnerRecord added in v0.17.0 

func InspectDirectoryOwnerRecord(ctx context.Context, directory string, owner DirectoryOwner, identity string) (OwnerRecordStatus, error)

InspectDirectoryOwnerRecord compares one bounded canonical record without writes or locks. It does not read the seed or verify active ownership, migration completion, or fleet fencing.

type ProviderLayer 

type ProviderLayer struct {
	// ProviderID names the observed provider.
	ProviderID catalogs.ProviderID

	// Payload is the canonical encoding of the provider observation.
	Payload []byte

	// Digest is the content digest of Payload.
	Digest string

	// ObservedAt is when acquisition accepted the observation.
	ObservedAt time.Time

	// Receipt binds source identity, completeness, and classified issues to Payload.
	Receipt sources.ObservationReceipt
}

ProviderLayer is one retained per-provider observation. The runtime keeps the last-known-good layer of every provider, so one failing provider never removes its records from the effective catalog.

func NewProviderLayer added in v0.17.0 

func NewProviderLayer(id catalogs.ProviderID, observation sources.Observation) (ProviderLayer, error)

NewProviderLayer encodes one validated provider observation with its durable receipt. It does not connect to a network or write files.

type ProviderObservationReset added in v0.17.0 

type ProviderObservationReset = ObservationReset

ProviderObservationReset retains the provider-oriented spelling of ObservationReset.

type PublicationStatus added in v0.17.0 

type PublicationStatus = status.Publication

PublicationStatus summarizes one retained upstream publication.

type Random 

type Random func() float64

Random returns a uniform value in the half-open interval [0, 1). The runtime uses it to spread scheduled work across a fleet.

type RefreshReport 

type RefreshReport struct {
	// RunID is the identity of the run.
	RunID string

	// Kind names the work the run did.
	Kind string

	// StartedAt and CompletedAt bound the run.
	StartedAt   time.Time
	CompletedAt time.Time

	// Source reports the upstream read.
	Source SourceRefreshReport

	// Acquisition reports provider attempts and non-provider observations.
	Acquisition AcquisitionReport

	// Published reports whether the runtime published a new effective catalog.
	Published bool

	// GenerationID identifies the published effective catalog.
	GenerationID string
}

RefreshReport says what one whole refresh produced. A source-only run leaves the acquisition report empty, and an acquisition-only run leaves the source report empty.

type RetainedCatalogPermission added in v0.17.0 

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

RetainedCatalogPermission holds original passive permission evidence for a stopped consumer. It grants no permission renewal, source acquisition, catalog activation, or replica ownership.

func InspectRetainedCatalogPermission added in v0.17.0 

func InspectRetainedCatalogPermission(ctx context.Context, request RetainedCatalogPermissionRequest, clock permission.ClockReading) (*RetainedCatalogPermission, error)

InspectRetainedCatalogPermission checks original retained permission without opening a connected runtime. Writers must remain fenced throughout inspection and rechecks. Internal authority receipts require a qualified current clock sample. An uncertain checkpoint requires separate source-owner verification. This operation does not clear uncertainty or extend expiry.

func (*RetainedCatalogPermission) Check added in v0.17.0 

func (p *RetainedCatalogPermission) Check(ctx context.Context, request RetainedCatalogPermissionRequest, clock permission.ClockReading) error

Check verifies the original evidence and current expiry without changing files or receipt deadlines. After restart, compare fresh inspection with the record sealed in the original recovery decision.

func (*RetainedCatalogPermission) Digest added in v0.17.0 

func (p *RetainedCatalogPermission) Digest() string

Digest returns the SHA-256 digest of the original record, or an empty string for an absent capability.

func (*RetainedCatalogPermission) Format added in v0.17.0 

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

Format hides private native evidence from diagnostic output.

func (*RetainedCatalogPermission) Record added in v0.17.0 

func (p *RetainedCatalogPermission) Record() []byte

Record returns a private, caller-owned copy of the original native evidence. Seal this record with the complete recovery decision before releasing any component.

type RetainedCatalogPermissionRequest added in v0.17.0 

type RetainedCatalogPermissionRequest struct {
	Directory         string
	Owner             DirectoryOwner
	SchedulerIdentity string
	SourcePolicy      SourcePolicy
	AcceptedHead      catalogs.CatalogAuthorityHead
}

RetainedCatalogPermissionRequest binds a selected catalog to its configured consumer and private runtime state. The host must verify the catalog payload, source policy, and deployment fence independently.

type RetainedFile added in v0.17.0 

type RetainedFile = privatefiles.RetainedFile

RetainedFile identifies bytes in a verified backup. Names are slash-separated relative paths.

type RetainedRecordReader added in v0.17.0 

type RetainedRecordReader = privatefiles.RetainedRecordReader

RetainedRecordReader reads a record from a verified backup with the supplied byte limit. An absent record must return an error that matches os.ErrNotExist.

type RetentionPolicy added in v0.17.0 

type RetentionPolicy struct {
	Enabled        bool
	Interval       time.Duration
	MaxGenerations int
	MaxBytes       int64
	ScanEntries    int
	InputMaxBytes  int64
}

RetentionPolicy bounds automatic collection independently of catalog update permissions. Required generations can exceed the limits. Collection never removes them to satisfy a limit.

func DefaultRetentionPolicy added in v0.17.0 

func DefaultRetentionPolicy() RetentionPolicy

DefaultRetentionPolicy selects hourly collection with bounded scans and retained bytes.

func (RetentionPolicy) Validate added in v0.17.0 

func (p RetentionPolicy) Validate() error

Validate rejects unbounded or invalid retention settings, including when operators disable scheduling.

type RetentionStatus added in v0.17.0 

type RetentionStatus = status.RetentionStatus

RetentionStatus is the last observed catalog collection outcome.

type Runtime 

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

Runtime is a connected Starmap. It serves the embedded catalog immediately, refreshes from one selected upstream source, retains per-provider observations, and rebuilds one immutable effective catalog from those layers. Reads reach no external system.

func Open 

func Open(ctx context.Context, opts ...Option) (connected *Runtime, err error)

Open returns a connected runtime. It serves the verified embedded catalog before the first upstream reply, so Catalog and State never wait for the network. Open starts the source and acquisition schedules and returns. An authoritative stored catalog requires origin configuration or require_authority.

func (*Runtime) AcquisitionSources added in v0.17.0 

func (r *Runtime) AcquisitionSources() ([]sources.ID, bool)

AcquisitionSources returns an owned explicit source set and its presence. Without a selection, the supplied acquisition roles keep their defaults.

func (*Runtime) AllowsCatalogAttempt added in v0.17.0 

func (r *Runtime) AllowsCatalogAttempt(head catalogs.CatalogAuthorityHead) bool

AllowsCatalogAttempt checks permission for a consumer's separately accepted catalog. The consumer must bind this validated authority head to its exact catalog before publication. A retained catalog can serve new attempts only while its permission revision remains current. Equal permission revisions allow route preparation without interrupting the previous catalog. Ordinary sources use the same admission policy as AllowsNewAttempt. Call this memory-only check for every attempt, retry, and cached response delivery.

func (*Runtime) AllowsNewAttempt added in v0.17.0 

func (r *Runtime) AllowsNewAttempt() bool

AllowsNewAttempt checks current catalog permission using memory only. Call it for every new attempt, including retries and cached response delivery. It does not replace model, destination, account, or budget authorization.

func (*Runtime) BaselineStatus added in v0.17.0 

func (r *Runtime) BaselineStatus() (BaselineStatus, bool)

BaselineStatus returns the packaged and retained baselines without a storage operation. It returns false when the runtime has no fleet store.

func (*Runtime) Catalog 

func (r *Runtime) Catalog() *catalogs.Catalog

Catalog returns the current immutable effective catalog. It reaches no external system and never blocks on the source.

func (*Runtime) Client 

func (r *Runtime) Client() *starmap.Client

Client returns the immutable publication client underneath the runtime. Use it for explicit publication, hooks, and generation retrieval.

func (*Runtime) Close 

func (r *Runtime) Close() error

Close stops runtime-owned work and releases the lease. It is idempotent and joins within thirty seconds. A run that does not stop in time leaves a typed timeout error. Directory ownership remains held until work and lease release finish.

func (*Runtime) CollectRetainedInputs added in v0.17.0 

func (r *Runtime) CollectRetainedInputs(ctx context.Context, request InputCollectionRequest) (report InputCollectionReport, resultErr error)

CollectRetainedInputs removes validated immutable inputs outside retained history and pending publications. It cleans unused local inputs even when acquisition is offline or a generation pin prevents updates. Limits must be positive. MaxEntries cannot exceed storage.MaxRetentionScanEntries. A failed preflight removes nothing. Later failures return the partial removal report.

func (*Runtime) CompleteDirectoryMigration added in v0.17.0 

func (r *Runtime) CompleteDirectoryMigration(ctx context.Context, request DirectoryMigrationRequest) (DirectoryMigrationPublication, error)

CompleteDirectoryMigration confirms this runtime's selected directory, owner, and retained identity. Call it after the host selects the replacement configuration and opens this runtime. This method records completion without editing configuration files or deleting the source.

func (*Runtime) FleetStatus added in v0.17.0 

func (r *Runtime) FleetStatus() (FleetStatus, bool)

FleetStatus returns local fleet state without a storage operation.

func (*Runtime) ModelsDevGitCommit added in v0.17.0 

func (r *Runtime) ModelsDevGitCommit() (string, bool)

ModelsDevGitCommit returns the configured Git pin and its explicit presence.

func (*Runtime) ObservationInputs added in v0.17.0 

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

ObservationInputs returns the current catalog and its selected baseline. It reads retained memory, starts no acquisition, and writes no files. A later update reads new snapshots under runtime operation ownership.

func (*Runtime) PermissionClock added in v0.17.0 

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

PermissionClock returns the current permission time and its uncertainty from cached evidence. It starts no observation or I/O. An absent runtime or clock returns unknown time. Hosts must reject unknown time and uncertainty outside their admission bounds.

func (*Runtime) PermissionClockStatus added in v0.17.0 

func (r *Runtime) PermissionClockStatus() permission.ClockMonitorStatus

PermissionClockStatus reports diagnostics for the runtime-owned clock monitor. It starts no observation. A runtime with an external callback returns an empty status. LastError is a local diagnostic. Hosts must redact it in public responses.

func (*Runtime) PinAcceptance added in v0.17.0 

func (r *Runtime) PinAcceptance() (GenerationPinAcceptance, bool)

PinAcceptance returns the current acceptance and whether durable storage retains it. A missing acceptance returns a zero record and false. This method reads memory only.

func (*Runtime) PreviewAcquisition added in v0.17.0 

func (r *Runtime) PreviewAcquisition(ctx context.Context, prepare func(context.Context, ObservationInputs) (ObservationUpdate, error), requestedSources ...sources.ID) (starmap.CatalogState, error)

PreviewAcquisition computes an acquisition against one captured runtime snapshot. It writes no catalog, workspace, or runtime state. The callback owns source reads. requestedSources has the same access contract as UpdateAcquisition.

func (*Runtime) PromoteEmbeddedBaseline added in v0.17.0 

func (r *Runtime) PromoteEmbeddedBaseline(ctx context.Context, request BaselinePromotion) (BaselinePromotionResult, error)

PromoteEmbeddedBaseline makes this binary's packaged baseline the fleet's retained baseline. It runs under the publication lease and publishes one revision after ExpectedHead. Retained source, provider, manual, and removal inputs stay unchanged. It refuses a stale head, a different packaged generation, an equal baseline, a generation pin, and a configured source authority. The caller authorizes the operator action.

func (*Runtime) PublishObservations added in v0.17.0 

func (r *Runtime) PublishObservations(ctx context.Context, observations ...sources.Observation) (starmap.CatalogState, error)

PublishObservations retains caller-supplied observations with their accepted catalog. The runtime validates receipts and active bindings before it publishes any input. This operation reads no source and joins runtime cancellation and shutdown.

func (*Runtime) ReadPermission added in v0.17.0 

func (r *Runtime) ReadPermission(ctx context.Context) (catalogs.CatalogPermissionEnvelope, error)

ReadPermission issues an origin receipt or returns a confirmed upstream receipt without renewing it. Origins read current authoritative storage with a qualified clock. Relays read retained receipts from memory. It forwards a required revision even when this runtime cannot activate its catalog or permission schema. A newer manifest without a matching receipt, uncertain retention, or unknown clock validity prevents delivery. Callers must authenticate the downstream connection and enforce the receipt's original expiry.

func (*Runtime) Refresh 

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

Refresh reads the upstream and then observes configured acquisition sources. It changes the upstream layer and acquisition inputs in one run.

func (*Runtime) RefreshFleet added in v0.17.0 

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

RefreshFleet activates the durable shared head after a missed notification or reconnect. It queries no source and requires no refresh lease.

func (*Runtime) RefreshPermission added in v0.17.0 

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

RefreshPermission reads and retains the configured authority's requirement. It runs independently of catalog refresh and the shared acquisition lease.

func (*Runtime) RefreshSource 

func (r *Runtime) RefreshSource(ctx context.Context) (SourceRefreshReport, error)

RefreshSource reads the upstream source only. It changes the source layer.

func (*Runtime) ReplaceRemovalTargets added in v0.17.0 

func (r *Runtime) ReplaceRemovalTargets(ctx context.Context, expected starmap.CatalogState, targets ...catalogs.CatalogRemovalTarget) (starmap.CatalogState, error)

ReplaceRemovalTargets replaces this runtime's operator removal snapshot. Expected generation identity and checksum prevent stale edits. An empty target list restores local removals. The caller authorizes the operator action. Other publishers retain their own policies.

func (*Runtime) RetentionSnapshot added in v0.17.0 

func (r *Runtime) RetentionSnapshot() RetentionStatus

RetentionSnapshot returns the configured policy and last collection result without storage reads.

func (*Runtime) State 

func (r *Runtime) State() starmap.CatalogState

State returns one atomic snapshot of the effective catalog, generation identity, and authority head. It allocates no memory and reaches no external system. The authority head does not grant permission.

func (*Runtime) Status 

func (r *Runtime) Status() Status

Status returns the current runtime status. It reads retained state only, so it reaches no external system and never blocks on the source.

func (*Runtime) Sync 

func (r *Runtime) Sync(ctx context.Context, providers ...catalogs.ProviderID) (AcquisitionReport, error)

Sync observes configured provider and non-provider sources. An empty provider list observes every eligible provider scope.

func (*Runtime) UpdateAcquisition added in v0.17.0 

func (r *Runtime) UpdateAcquisition(ctx context.Context, prepare func(context.Context, ObservationInputs) (ObservationUpdate, error), requestedSources ...sources.ID) (starmap.CatalogState, error)

UpdateAcquisition prepares and commits one acquisition under runtime ownership. Failed preparation preserves accepted state. The callback must not mutate this runtime. requestedSources declares every source the callback can read. Omission permits network acquisition only in configured mode.

func (*Runtime) UpdateObservations added in v0.17.0 

func (r *Runtime) UpdateObservations(ctx context.Context, prepare func(context.Context, ObservationInputs) ([]sources.Observation, error), resets ...ObservationReset) (starmap.CatalogState, error)

UpdateObservations prepares and publishes original observations under runtime ownership. The callback may read sources. Runtime shutdown and caller cancellation stop its context. An error or empty observation list preserves accepted state. The callback must not call another mutation on this runtime. Use ObservationInputs for a read-only preview.

Optional resets replace prior local acquisition observations within the named scopes. Each scope requires complete successful replacement evidence. The baseline and unrelated scopes remain. Resets and replacements share the catalog publication journal.

func (*Runtime) Updates 

func (r *Runtime) Updates() <-chan starmap.CatalogState

Updates returns the channel that carries every published effective catalog state. The runtime buffers the channel. A reader that falls behind loses intermediate states and always observes the newest one.

func (*Runtime) UpstreamPublication added in v0.17.0 

func (r *Runtime) UpstreamPublication() *SourcePublication

UpstreamPublication returns a caller-owned copy of the accepted source run record. It returns nil when the source supplies no run receipt. The artifact manifest stays unchanged.

type Source 

type Source = source.Source

Source reads one upstream immutable catalog generation.

type SourceAcquirer added in v0.17.0 

type SourceAcquirer interface {
	AcquireSources(context.Context, SourceAcquisitionRequest) ([]sources.Observation, error)
}

SourceAcquirer collects configured non-provider observations without publication. It must preserve source receipts and report failed or partial observations. Runtime owns cancellation, lease fencing, retained evidence, and publication.

type SourceAcquisitionRequest added in v0.17.0 

type SourceAcquisitionRequest struct {
	Current   *catalogs.Catalog
	Providers []catalogs.ProviderID
	// Sources replaces the collector source defaults when non-nil.
	Sources []sources.ID
	// ModelsDevGitCommit replaces the collector pin when non-nil.
	// An explicit empty value clears that pin. Git acquisition then requires a pin.
	ModelsDevGitCommit *string
}

SourceAcquisitionRequest selects non-provider observations for one owned run. Current is immutable. Providers restricts model scope when the caller supplies IDs.

type SourceDescriber added in v0.17.0 

type SourceDescriber interface {
	SourceConfiguration() []sources.SourceActivity
}

SourceDescriber declares metadata capabilities and default selection without acquisition. The runtime calls it once when it opens. It must not read external data. The runtime treats omitted metadata sources as unsupported. Eligibility remains unknown until acquisition.

type SourceHop 

type SourceHop = status.SourceHop

SourceHop is one sanitized entry in an upstream source chain.

type SourceIdentityAdopter 

type SourceIdentityAdopter = source.IdentityAdopter

SourceIdentityAdopter is an optional Source that takes the fleet instance identity of its runtime.

type SourceKind 

type SourceKind = status.SourceKind

SourceKind names one supported upstream catalog source.

func ParseSourceKind 

func ParseSourceKind(name string) (SourceKind, error)

ParseSourceKind converts one configured name into a source kind. It rejects every unknown name with a typed validation error, so a typo never selects a silent default.

func SourceKinds 

func SourceKinds() []SourceKind

SourceKinds returns a caller-owned copy of every accepted source name.

type SourceManualReader added in v0.17.0 

type SourceManualReader = source.ManualReader

SourceManualReader reads one generation without a background lifecycle.

type SourcePolicy 

type SourcePolicy struct {
	// Kind selects the source implementation.
	Kind SourceKind

	// URL is the deployment-owned source address. It applies to the starmap
	// and file kinds.
	URL string

	// Repository names the catalog repository for the public and github kinds.
	Repository string

	// Channel names the mutable branch that selects the current catalog.
	Channel string

	// SignerWorkflow pins the build provenance the source accepts.
	SignerWorkflow string

	// PollInterval is the channel check period.
	PollInterval time.Duration

	// StartupPolicy decides what the runtime serves before the first reply.
	StartupPolicy StartupPolicy

	// AuthorityID and PolicyID pin the authority required by require_authority.
	AuthorityID string
	PolicyID    string

	// MaxAge is the age at which the active catalog counts as stale.
	MaxAge time.Duration

	// MaxHops bounds a cascade of Starmap runtimes.
	MaxHops int

	// Aliases are the other stable identities that name this same runtime,
	// such as a load-balancer name or a second deployment name. A served
	// source chain that names one of them is a self reference, and address
	// comparison alone cannot detect it.
	Aliases []string
}

SourcePolicy selects and bounds the upstream catalog source. It holds no token and no API key, so a policy value is safe to log and to serve.

func DefaultSourcePolicy 

func DefaultSourcePolicy() SourcePolicy

DefaultSourcePolicy returns the canonical public-channel source policy.

func ResolveSourcePolicy added in v0.17.0 

func ResolveSourcePolicy(opts ...Option) (SourcePolicy, error)

ResolveSourcePolicy returns the source policy from canonical runtime options. It starts no runtime, source, clock, file access, or background work. The caller receives detached aliases. Other configuration domains retain their own validation.

func (SourcePolicy) SafeIdentity 

func (p SourcePolicy) SafeIdentity() string

SafeIdentity returns the source identity that status and logs may show. It names the kind and, for a GitHub channel, the repository and the channel. It never names a custom URL, a host, or a credential.

func (SourcePolicy) Validate 

func (p SourcePolicy) Validate() error

Validate checks the policy fields that the runtime depends on.

type SourcePublication added in v0.17.0 

type SourcePublication = source.Publication

SourcePublication is the verified upstream run receipt and promotion identity.

type SourceRead 

type SourceRead = source.Read

SourceRead is one upstream observation.

type SourceRefreshMode added in v0.17.0 

type SourceRefreshMode string

SourceRefreshMode controls automatic source reads independently of acquisition. 

const (
	// SourceRefreshAutomatic permits startup, periodic, and reactive source reads.
	SourceRefreshAutomatic SourceRefreshMode = "automatic"
	// SourceRefreshManual permits only explicit source reads.
	SourceRefreshManual SourceRefreshMode = "manual"
)

func ParseSourceRefreshMode added in v0.17.0 

func ParseSourceRefreshMode(value string) (SourceRefreshMode, error)

ParseSourceRefreshMode accepts an explicit automatic or manual selection.

type SourceRefreshReport 

type SourceRefreshReport struct {
	// RunID is the identity of the run that produced this report.
	RunID string

	// StartedAt and CompletedAt bound the run.
	StartedAt   time.Time
	CompletedAt time.Time

	// SourceIdentity is the safe identity of the source that answered.
	SourceIdentity string

	// Changed reports whether the upstream generation moved.
	Changed bool

	// Published reports whether the runtime published a new effective catalog.
	Published bool

	// GenerationID identifies the upstream generation the runtime retained.
	GenerationID string

	// PublishedAt is the upstream publication time.
	PublishedAt time.Time

	// Health is what this runtime observed while it read the source. It grades
	// the transfer only.
	Health Health

	// UpstreamHealth is the health the upstream reported about itself. It stays
	// independent of Health, so a healthy transfer still carries a degraded
	// upstream report.
	UpstreamHealth Health

	// Reason is the safe reason code of a failed read.
	Reason string

	// Chain is the sanitized upstream source chain.
	Chain []SourceHop
}

SourceRefreshReport says what one upstream source read produced.

type SourceWatcher 

type SourceWatcher = source.Watcher

SourceWatcher is an optional Source that reports each upstream change.

type StartupPolicy 

type StartupPolicy string

StartupPolicy decides what the runtime serves while the first source read is still outstanding. 

const (
	// StartupPreferSource keeps the embedded baseline active and replaces it
	// with the first verified upstream generation. It is the default.
	StartupPreferSource StartupPolicy = "prefer_source"

	// StartupRequireSource keeps the runtime unusable until one verified
	// upstream generation is active. Open reads the source one time and fails
	// when that read fails. The policy names the evidence the runtime needs,
	// not the lease. A replica that another instance owns therefore opens
	// without a read and consumes the state that the owner publishes.
	StartupRequireSource StartupPolicy = "require_source"

	// StartupRequireAuthority retains catalog metadata while authority approval controls use.
	// Open returns diagnostics even when no approved catalog is available.
	StartupRequireAuthority StartupPolicy = "require_authority"

	// StartupPreferLocal keeps the retained local generation active and
	// applies an upstream generation only on an explicit refresh.
	StartupPreferLocal StartupPolicy = "prefer_local"
)

func ParseStartupPolicy 

func ParseStartupPolicy(name string) (StartupPolicy, error)

ParseStartupPolicy converts one configured name into a startup policy.

func (StartupPolicy) String 

func (p StartupPolicy) String() string

String returns the wire value of the startup policy.

func (StartupPolicy) Valid 

func (p StartupPolicy) Valid() bool

Valid reports whether the policy is one of the accepted names.

type Status 

type Status = status.Status

Status is the operator-facing state of one connected runtime.

type UpdatePolicy added in v0.17.0 

type UpdatePolicy struct {
	SourceRefreshMode SourceRefreshMode
	NetworkMode       NetworkMode
}

UpdatePolicy separates automatic source refresh from catalog network access.

func DefaultUpdatePolicy added in v0.17.0 

func DefaultUpdatePolicy() UpdatePolicy

DefaultUpdatePolicy permits automatic reads through configured sources.

func (UpdatePolicy) Validate added in v0.17.0 

func (p UpdatePolicy) Validate() error

Validate rejects unknown policy values before runtime construction.

Source Files

View all Source files

Directories

Path Synopsis
Package source owns the upstream source contract of a connected catalog runtime.
 Package source owns the upstream source contract of a connected catalog runtime.
Package status owns the observable vocabulary of a connected catalog runtime.
 Package status owns the observable vocabulary of a connected catalog runtime.

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.