catalogartifact

catalogartifact

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

Package catalogartifact defines the deterministic distribution format for immutable Starmap catalog generations.

Index

• Constants
• func Open(archive, attestation []byte) (catalogstore.Generation, error)
• type Artifact
  • func Build(generation catalogstore.Generation) (Artifact, error)
• type AttestationPredicate
• type AttestationStatement
• type Descriptor
  • func (d Descriptor) String() string
• type DigestSet
• type FileDescriptor
• type ReleaseAssets
  • func StageReleaseAssets(root string, artifact Artifact) (ReleaseAssets, error)
• type Subject

Constants

const (
    // FormatVersion is the current catalog distribution archive format.
    FormatVersion uint64 = 1
    // MediaType is the media type of the compressed catalog archive.
    MediaType = "application/vnd.agentstation.starmap.catalog-artifact.v1+tar+gzip"
    // DescriptorMediaType is the media type of artifact.json.
    DescriptorMediaType = "application/vnd.agentstation.starmap.catalog-artifact-descriptor.v1+json"
    // AttestationPredicateType identifies the detached in-toto predicate.
    AttestationPredicateType = "https://agentstation.ai/starmap/catalog-generation/v1"
    // AttestationStatementType is the in-toto statement schema identifier.
    AttestationStatementType = "https://in-toto.io/Statement/v1"
    // Filename is the stable archive filename; generation identity is carried by
    // the descriptor and distribution path rather than interpolated into a path.
    Filename = "starmap-catalog.tar.gz"
    // AttestationFilename is the detached in-toto statement filename.
    AttestationFilename = "starmap-catalog.intoto.json"
    // OCIMirrorArtifactType identifies an OCI manifest that mirrors the exact
    // immutable release assets. The catalog archive remains a layer with
    // MediaType, so its digest can be compared across distribution channels.
    OCIMirrorArtifactType = "application/vnd.agentstation.starmap.catalog-mirror.v1"
    // OCIGenerationAnnotation carries the logical catalog generation ID on an
    // OCI mirror manifest. Consumers must still pin and verify content digests.
    OCIGenerationAnnotation = "ai.agentstation.starmap.generation"
)

const (
    // ChecksumFilename is the detached SHA-256 checksum asset.
    ChecksumFilename = "starmap-catalog.tar.gz.sha256"
)

func Open

func Open(archive, attestation []byte) (catalogstore.Generation, error)

Open verifies an archive and detached statement before returning its exact immutable catalog generation.

type Artifact

Artifact is one reproducible archive and its detached attestation statement.

type Artifact struct {
    GenerationID        string
    Filename            string
    MediaType           string
    Data                []byte
    Checksum            string
    AttestationFilename string
    Attestation         []byte
}

func Build

func Build(generation catalogstore.Generation) (Artifact, error)

Build validates a generation and deterministically packages it for distribution. Rebuilding identical generation bytes produces identical archive and attestation bytes.

type AttestationPredicate

AttestationPredicate records the catalog compatibility identity asserted by the detached statement. Signature and builder provenance are added and verified by the publication boundary.

type AttestationPredicate struct {
    GenerationID          string                         `json:"generation_id"`
    ManifestVersion       uint64                         `json:"manifest_version"`
    SchemaVersion         uint64                         `json:"schema_version"`
    ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
}

type AttestationStatement

AttestationStatement is the deterministic in-toto statement emitted beside an artifact. It is deliberately detached to avoid a self-referential archive digest and to permit signing without changing reproducible artifact bytes.

type AttestationStatement struct {
    Type          string               `json:"_type"`
    Subject       []Subject            `json:"subject"`
    PredicateType string               `json:"predicateType"`
    Predicate     AttestationPredicate `json:"predicate"`
}

type Descriptor

Descriptor describes the complete logical generation carried by an archive.

type Descriptor struct {
    FormatVersion         uint64                         `json:"format_version"`
    MediaType             string                         `json:"media_type"`
    GenerationID          string                         `json:"generation_id"`
    ManifestVersion       uint64                         `json:"manifest_version"`
    SchemaVersion         uint64                         `json:"schema_version"`
    ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
    Manifest              FileDescriptor                 `json:"manifest"`
    Payload               FileDescriptor                 `json:"payload"`
}

func (Descriptor) String

func (d Descriptor) String() string

String returns a concise descriptor useful in logs.

type DigestSet

DigestSet is the SHA-256 digest map used by an in-toto subject.

type DigestSet struct {
    SHA256 string `json:"sha256"`
}

type FileDescriptor

FileDescriptor binds one named artifact member to exact bytes.

type FileDescriptor struct {
    Name      string `json:"name"`
    MediaType string `json:"media_type"`
    Checksum  string `json:"checksum"`
    SizeBytes int64  `json:"size_bytes"`
}

type ReleaseAssets

ReleaseAssets describes one atomically staged immutable publication set.

type ReleaseAssets struct {
    GenerationID    string
    ArchiveChecksum string
    Directory       string
    Files           []string
}

func StageReleaseAssets

func StageReleaseAssets(root string, artifact Artifact) (ReleaseAssets, error)

StageReleaseAssets validates and atomically stages archive, attestation, and checksum assets. An exact retry is idempotent; rebinding the same generation ID to different bytes returns a typed conflict.

type Subject

Subject is one byte object bound by the detached statement.

type Subject struct {
    Name   string    `json:"name"`
    Digest DigestSet `json:"digest"`
}

Generated by gomarkdoc