source

source

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

Package source owns the upstream source contract of a connected catalog runtime. It holds the source interface, the optional source capabilities, and the single upstream observation that a read returns.

The package is a leaf. It implements no source and opens no connection. A package that implements a source therefore depends on this contract alone. It never depends on the attested source machinery that the runtime package carries.

Index

• type AuthorityObservable
• type IdentityAdopter
• type ManualReader
• type PermissionReader
• type Publication
  • func (p Publication) Copy() Publication
• type Read
• type Source
• type Watcher

type AuthorityObservable

AuthorityObservable reports verified requirements before source payload processing. Binding starts no acquisition. A source must refuse binding after manifest requests start.

type AuthorityObservable interface {
    Source
    BindAuthorityObserver(func(context.Context, catalogs.CatalogAuthorityHead) error) error
}

type IdentityAdopter

IdentityAdopter is an optional Source that takes the fleet instance identity of its runtime. The source and the runtime then spread their work on one identity, so a replica keeps one stable phase for every controller it owns. Open hands the identity over before the first read.

type IdentityAdopter interface {
    Source

    // AdoptInstanceIdentity takes the derived instance identity of the runtime.
    AdoptInstanceIdentity(instance string)
}

type ManualReader

ManualReader reads one upstream generation without starting a background lifecycle. The context bounds every request. Return ends all work that the call starts. Reactive sources must provide this capability for manual source mode.

type ManualReader interface {
    Source
    ReadOnce(context.Context) (Read, error)
}

type PermissionReader

PermissionReader reads authenticated authority receipts independently of catalog compatibility. A receipt read must not depend on a catalog fetch or an active event stream. The configured transport proves publisher trust. The runtime checks authority identity, replay, retention, and permission validity.

type PermissionReader interface {
    Source
    ReadPermission(context.Context) (catalogs.CatalogPermissionEnvelope, error)
}

type Publication

Publication binds a verified run receipt to its attested channel metadata. Source implementations verify publisher provenance before returning this record.

type Publication struct {
    Receipt      artifact.PublicationReceipt `json:"receipt"`
    Checksum     string                      `json:"checksum"`
    SourceCommit string                      `json:"source_commit"`
}

func (Publication) Copy

func (p Publication) Copy() Publication

Copy returns an independent publication record.

type Read

Read is one upstream observation.

type Read struct {
    // Changed reports whether the upstream generation moved.
    Changed bool

    // Generation is the verified immutable catalog generation. It is empty
    // when Changed is false.
    Generation catalogs.Generation

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

    // ChannelUpdatedAt is when the upstream channel last moved.
    ChannelUpdatedAt time.Time

    // Publication holds verified run evidence independently of the artifact manifest.
    Publication *Publication

    // Chain is the sanitized upstream source chain, nearest hop first.
    Chain []status.SourceHop

    // Health is the upstream-reported health of the source itself.
    Health status.Health
}

type Source

Source reads one upstream immutable catalog generation. Every built-in source verifies its evidence before it returns a generation.

type Source interface {
    // Identity returns the safe identity of the source. It names no URL, no
    // host, and no credential.
    Identity() string

    // Read returns the current upstream generation. A source that finds no
    // change reports Changed false and carries no generation.
    Read(ctx context.Context) (Read, error)
}

type Watcher

Watcher is an optional Source that reports an upstream change as it arrives. A reactive source, such as one Starmap cascaded onto another, learns of a publication on its own stream. The runtime then refreshes on that wake and waits for no poll boundary. A delta crosses a cascade in seconds instead of in one poll interval.

The channel carries an empty value for each change and holds at most one pending wake. A closed channel means the source reports no further change, and the runtime falls back to its poll interval.

type Watcher interface {
    Source

    // Changes reports each upstream change as one wake.
    Changes() <-chan struct{}
}

Generated by gomarkdoc