catalogmeta

catalogmeta

import "github.com/agentstation/starmap/pkg/catalogmeta"

Package catalogmeta provides shared catalog metadata definitions used across Starmap packages.

This package contains fundamental types like SourceID and ResourceType that are referenced by multiple packages (sources, provenance, reconciler, etc.) to avoid import cycles while maintaining type safety.

The package has zero dependencies and serves as a foundation for the type system.

Index

• func CompareReviewCandidates(left, right ReviewCandidate) int
• type ObservationCompleteness
• type ObservationIssue
• type ObservationIssueCode
• type ObservationIssueScope
• type ObservationRecordCounts
• type ObservationRevision
• type ObservationRevisionKind
• type ObservationStatus
• type ProjectionResult
• type ProjectionStatus
• type ResourceType
  • func (rt ResourceType) String() string
• type ReviewCandidate
• type ReviewCandidateCode
• type SourceID
  • func SourceIDs() []SourceID
  • func (id SourceID) IsValid() bool
  • func (id SourceID) String() string

func CompareReviewCandidates

func CompareReviewCandidates(left, right ReviewCandidate) int

CompareReviewCandidates returns a stable lexical order for review candidates.

type ObservationCompleteness

ObservationCompleteness states whether every expected record was observed.

type ObservationCompleteness string

const (
    // ObservationCompletenessComplete means every expected record was observed.
    ObservationCompletenessComplete ObservationCompleteness = "complete"
    // ObservationCompletenessPartial means at least one expected record is absent.
    ObservationCompletenessPartial ObservationCompleteness = "partial"
)

type ObservationIssue

ObservationIssue records one classified, non-fatal degradation.

type ObservationIssue struct {
    Scope   ObservationIssueScope `json:"scope" yaml:"scope"`
    Code    ObservationIssueCode  `json:"code" yaml:"code"`
    Subject string                `json:"subject,omitempty" yaml:"subject,omitempty"`
    Message string                `json:"message" yaml:"message"`
}

type ObservationIssueCode

ObservationIssueCode is a stable machine-readable degradation reason.

type ObservationIssueCode string

const (
    // ObservationIssueCodeInvalidRecord means one record failed validation or conversion.
    ObservationIssueCodeInvalidRecord ObservationIssueCode = "invalid_record"
    // ObservationIssueCodeSchemaDrift means an upstream identity/container changed shape or type.
    ObservationIssueCodeSchemaDrift ObservationIssueCode = "schema_drift"
    // ObservationIssueCodePayloadLimit means an upstream exceeded a bounded resource budget.
    ObservationIssueCodePayloadLimit ObservationIssueCode = "payload_limit"
    // ObservationIssueCodeMissingCredentials means a provider could not be queried.
    ObservationIssueCodeMissingCredentials ObservationIssueCode = "missing_credentials"
    // ObservationIssueCodeConfiguration means source/provider configuration was invalid.
    ObservationIssueCodeConfiguration ObservationIssueCode = "configuration"
    // ObservationIssueCodeFetchFailed means upstream acquisition failed.
    ObservationIssueCodeFetchFailed ObservationIssueCode = "fetch_failed"
    // ObservationIssueCodeStaleFallback means last-known-good stale evidence was used.
    ObservationIssueCodeStaleFallback ObservationIssueCode = "stale_fallback"
    // ObservationIssueCodeBootstrapFallback means embedded bootstrap evidence was used.
    ObservationIssueCodeBootstrapFallback ObservationIssueCode = "bootstrap_fallback"
    // ObservationIssueCodeVolumeCollapse means a source omitted records that
    // its prior accepted evidence supplied, without explicit lifecycle proof.
    ObservationIssueCodeVolumeCollapse ObservationIssueCode = "volume_collapse"
)

type ObservationIssueScope

ObservationIssueScope identifies the level at which degradation occurred.

type ObservationIssueScope string

const (
    // ObservationIssueScopeRecord applies to one upstream record.
    ObservationIssueScopeRecord ObservationIssueScope = "record"
    // ObservationIssueScopeProvider applies to one provider within a source.
    ObservationIssueScopeProvider ObservationIssueScope = "provider"
    // ObservationIssueScopeSource applies to the complete source call.
    ObservationIssueScopeSource ObservationIssueScope = "source"
    // ObservationIssueScopeStaleFallback identifies usable stale fallback data.
    ObservationIssueScopeStaleFallback ObservationIssueScope = "stale_fallback"
)

type ObservationRecordCounts

ObservationRecordCounts reports source records accepted into or rejected from one observation.

type ObservationRecordCounts struct {
    Accepted int `json:"accepted" yaml:"accepted"`
    Rejected int `json:"rejected" yaml:"rejected"`
}

type ObservationRevision

ObservationRevision identifies an upstream or normalized content revision.

type ObservationRevision struct {
    Kind          ObservationRevisionKind `json:"kind" yaml:"kind"`
    Value         string                  `json:"value,omitempty" yaml:"value,omitempty"`
    InputName     string                  `json:"input_name,omitempty" yaml:"input_name,omitempty"`
    InputChecksum string                  `json:"input_checksum,omitempty" yaml:"input_checksum,omitempty"`
}

type ObservationRevisionKind

ObservationRevisionKind identifies how an upstream revision was obtained.

type ObservationRevisionKind string

const (
    // ObservationRevisionKindUnknown means the upstream exposes no stable revision.
    ObservationRevisionKindUnknown ObservationRevisionKind = "unknown"
    // ObservationRevisionKindETag identifies an HTTP entity tag.
    ObservationRevisionKindETag ObservationRevisionKind = "etag"
    // ObservationRevisionKindLastModified identifies an HTTP Last-Modified validator.
    ObservationRevisionKindLastModified ObservationRevisionKind = "last_modified"
    // ObservationRevisionKindGitCommit identifies an exact Git commit.
    ObservationRevisionKindGitCommit ObservationRevisionKind = "git_commit"
    // ObservationRevisionKindSourceVersion identifies an upstream-declared version.
    ObservationRevisionKindSourceVersion ObservationRevisionKind = "source_version"
    // ObservationRevisionKindContentDigest identifies normalized observation content.
    ObservationRevisionKindContentDigest ObservationRevisionKind = "content_digest"
)

type ObservationStatus

ObservationStatus is the typed outcome of a source observation.

type ObservationStatus string

const (
    // ObservationStatusSucceeded means no known degradation occurred.
    ObservationStatusSucceeded ObservationStatus = "succeeded"
    // ObservationStatusDegraded means usable data has a known limitation.
    ObservationStatusDegraded ObservationStatus = "degraded"
)

type ProjectionResult

ProjectionResult reports the post-commit state of an optional human YAML workspace.

type ProjectionResult struct {
    // Path is the requested human workspace root.
    Path string
    // Status reports whether projection completed or requires repair.
    Status ProjectionStatus
    // IssueCode is empty after a successful projection.
    IssueCode string
    // GenerationID is the durable generation the workspace represents.
    GenerationID string
    // WorkspaceChecksum is present when the projected YAML became visible,
    // including when only the repair marker remains pending.
    WorkspaceChecksum string
}

type ProjectionStatus

ProjectionStatus is the post-commit state of an optional human YAML workspace projection.

type ProjectionStatus string

const (
    // ProjectionStatusApplied means the committed generation was materialized
    // successfully to the requested human workspace.
    ProjectionStatusApplied ProjectionStatus = "applied"
    // ProjectionStatusPendingRepair means the generation remains durably active,
    // but its optional human workspace projection must be repaired.
    ProjectionStatusPendingRepair ProjectionStatus = "pending_repair"

    // ProjectionIssueWorkspaceFailed identifies a committed generation whose
    // optional workspace projection did not complete.
    ProjectionIssueWorkspaceFailed = "workspace_projection_failed"
)

type ResourceType

ResourceType identifies the type of resource being tracked or merged in the catalog system. This allows provenance tracking and reconciliation to handle different resource types (models, providers, authors) with appropriate logic.

type ResourceType string

const (
    // ResourceTypeModel represents a model resource (e.g., gpt-4, claude-3).
    ResourceTypeModel ResourceType = "model"

    // ResourceTypeProvider represents a provider resource (e.g., openai, anthropic).
    ResourceTypeProvider ResourceType = "provider"

    // ResourceTypeAuthor represents an author resource (e.g., openai, meta).
    ResourceTypeAuthor ResourceType = "author"

    // ResourceTypeModelDefinition represents provider-independent canonical model facts.
    ResourceTypeModelDefinition ResourceType = "model_definition"

    // ResourceTypeProviderOffering represents one provider-specific model service contract.
    ResourceTypeProviderOffering ResourceType = "provider_offering"
)

func (ResourceType) String

func (rt ResourceType) String() string

String returns the string representation of a resource type.

type ReviewCandidate

ReviewCandidate records one provider offering excluded from a canonical catalog generation. ProviderModelID remains the provider's exact opaque ID.

type ReviewCandidate struct {
    Code                   ReviewCandidateCode `json:"code" yaml:"code"`
    ProviderID             string              `json:"provider_id" yaml:"provider_id"`
    ProviderModelID        string              `json:"provider_model_id" yaml:"provider_model_id"`
    SourceID               SourceID            `json:"source" yaml:"source"`
    SourceObservationID    string              `json:"source_observation_id" yaml:"source_observation_id"`
    SourceRevision         ObservationRevision `json:"source_revision" yaml:"source_revision"`
    EvidenceChecksum       string              `json:"evidence_checksum" yaml:"evidence_checksum"`
    Reason                 string              `json:"reason" yaml:"reason"`
    PriorReviewedModelLink string              `json:"prior_reviewed_model_link" yaml:"prior_reviewed_model_link"`
}

type ReviewCandidateCode

ReviewCandidateCode identifies a stable model-review reason.

type ReviewCandidateCode string

const (
    // ReviewCandidateUnresolvedModelReference means a provider offering has no
    // reviewed provider-independent model identity.
    ReviewCandidateUnresolvedModelReference ReviewCandidateCode = "unresolved_model_reference"
)

type SourceID

SourceID identifies a data source in the synchronization pipeline. It uniquely identifies where catalog data originates from (providers, models.dev, local files, etc.).

type SourceID string

Common source identifiers used throughout the system.

const (
    // ProvidersID identifies the provider API source (OpenAI, Anthropic, etc.).
    ProvidersID SourceID = "providers"

    // ModelsDevGitID identifies the models.dev Git repository source.
    ModelsDevGitID SourceID = "models_dev_git"

    // ModelsDevHTTPID identifies the models.dev HTTP API source.
    ModelsDevHTTPID SourceID = "models_dev_http"

    // LocalCatalogID identifies the local filesystem catalog source.
    LocalCatalogID SourceID = "local_catalog"

    // EmbeddedCatalogID identifies the verified catalog compiled into Starmap.
    EmbeddedCatalogID SourceID = "embedded_catalog"

    // ReleaseArtifactID identifies an explicitly imported and publisher-verified
    // immutable catalog release.
    ReleaseArtifactID SourceID = "release_artifact"
)

func SourceIDs

func SourceIDs() []SourceID

SourceIDs returns all available source identifiers. This provides a convenient way to iterate over all defined source IDs.

func (SourceID) IsValid

func (id SourceID) IsValid() bool

IsValid returns true if the SourceID is one of the defined constants. Uses SourceIDs() to ensure consistency with the authoritative list.

func (SourceID) String

func (id SourceID) String() string

String returns the string representation of a source ID.

Generated by gomarkdoc