header

Documentation

Overview

Package header provides common header types for AICR data structures.

This package defines the Header type used across recipes, snapshots, and other AICR data structures to provide consistent metadata and versioning information.

Header Structure

The Header contains standard fields for API versioning and metadata:

type Header struct {
    Kind       Kind              `json:"kind,omitempty" yaml:"kind,omitempty"`             // Resource type (Snapshot, Recipe, RecipeResult)
    APIVersion string            `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"` // API version (e.g., "aicr.run/v1alpha2")
    Metadata   map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`     // Free-form string metadata (timestamp, version, etc.)
}

Metadata is a flat map[string]string populated by Init / InitWithTime with the unprefixed keys "timestamp" (RFC3339 UTC) and "version" (when supplied).

Usage

Initialize a header for a recipe via Init:

var h header.Header
h.Init(header.KindRecipe, header.GroupVersion, "v1.0.0")
// h.Metadata == map[string]string{"timestamp": "...", "version": "v1.0.0"}

For reproducible-build callers (SLSA, signed artifacts) inject a fixed timestamp via InitWithTime instead of Init:

var h header.Header
h.InitWithTime(header.KindSnapshot, header.GroupVersion, "v1.0.0", buildTime)

Serialization

Headers serialize consistently to JSON and YAML:

{
  "apiVersion": "aicr.run/v1alpha2",
  "kind": "Recipe",
  "metadata": {
    "timestamp": "2025-12-30T10:30:00Z",
    "version": "v1.0.0"
  }
}

API Versioning

The APIVersion field enables evolution of data formats. The current group and version is GroupVersion ("aicr.run/v1alpha2"); APIGroup derives from Domain. Per ADR-013 the move from the legacy aicr.nvidia.com/v1alpha1 group was a hard break — the old value is rejected, not migrated.

Callers should gate on IsSupportedAPIVersion rather than comparing literals, so the single source of truth in this package stays authoritative:

if h.APIVersion != "" && !header.IsSupportedAPIVersion(h.APIVersion) {
    return fmt.Errorf("unsupported apiVersion %q; expected %s", h.APIVersion, header.GroupVersion)
}

Kind Field

The Kind field is a typed constant identifying the resource:

• KindSnapshot ("Snapshot"): System configuration capture
• KindRecipe ("Recipe"): Configuration recommendations
• KindRecipeResult ("RecipeResult"): Resolved recipe with hydrated values

Custom Metadata

Because Metadata is a flat map[string]string, callers may add their own keys alongside the Init-populated "timestamp" and "version":

h.Metadata["node"] = "gpu-node-1"
h.Metadata["cluster"] = "production"
h.Metadata["environment"] = "staging"

Timestamps

Init writes the timestamp using RFC3339 format in UTC:

h.Init(header.KindRecipe, header.GroupVersion, "v1.0.0")
// h.Metadata["timestamp"] == "2025-12-30T10:30:00Z"

Validation

While Header doesn't enforce validation, consumers should verify:

• APIVersion is supported
• Kind is recognized
• Metadata["timestamp"] is reasonable
• Version is a valid semantic version (if present)

Index

• Constants
• func IsSupportedAPIVersion(v string) bool
• type Header
  • func (h *Header) Init(kind Kind, apiVersion string, version string)
  • func (h *Header) InitWithTime(kind Kind, apiVersion string, version string, ts time.Time)
• type Kind
  • func (k Kind) String() string

Constants

const (
	// Domain is the single source of truth for the AICR API domain. Every
	// role (apiVersion group, K8s label/annotation keys, attestation and
	// provenance URI hosts, UUIDv5 namespace seed) derives from this value.
	Domain = "aicr.run"

	// APIGroup is the API group for AICR artifacts.
	APIGroup = Domain

	// APIVersionV1Alpha2 is the current artifact API version segment.
	APIVersionV1Alpha2 = "v1alpha2"

	// GroupVersion is the canonical "group/version" string for AICR artifacts.
	GroupVersion = APIGroup + "/" + APIVersionV1Alpha2
)

AICR artifact API versioning. These constants are the single source of truth for the group/version stamped into every AICR artifact header (snapshot, recipe, config). Package-local aliases (e.g. snapshotter.FullAPIVersion, recipe.RecipeAPIVersion, config.APIVersion) must reference GroupVersion rather than redeclaring the literal.

Evolution policy (see docs/design/011-artifact-apiversion-policy.md): schema changes within a version must be additive-only; a breaking change requires a new version segment. This is a hard break: the old value is NOT accepted alongside the new one — there is no transition window. Artifacts stamped with a prior group/version must be regenerated.

Functions

func IsSupportedAPIVersion

func IsSupportedAPIVersion(v string) bool

IsSupportedAPIVersion reports whether v is an artifact apiVersion this binary understands. The empty string is intentionally NOT supported here: callers that tolerate a missing apiVersion for backward compatibility with older artifacts must special-case "" before calling this.

Bumping the artifact schema is a hard break: replace GroupVersion with the new value rather than accepting both. The prior value is rejected — artifacts stamped with an older group/version must be regenerated, not migrated.

Types

type Header

type Header struct {
	// Kind is the type of the snapshot object.
	Kind Kind `json:"kind,omitempty" yaml:"kind,omitempty"`

	// APIVersion is the API version of the snapshot object.
	APIVersion string `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"`

	// Metadata contains key-value pairs with metadata about the snapshot.
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Header contains metadata and versioning information for AICR resources. It follows Kubernetes-style resource conventions with Kind, APIVersion, and Metadata fields.

func (*Header) Init

func (h *Header) Init(kind Kind, apiVersion string, version string)

Init initializes the Header with the specified kind, apiVersion, and version. It sets the Kind, APIVersion, and populates Metadata with timestamp and version. Uses unprefixed keys (timestamp, version) for all kinds.

The timestamp is wall-clock time. Reproducible-build callers (SLSA, signed artifacts) must inject a fixed timestamp via InitWithTime to keep the serialized header byte-stable across runs.

func (*Header) InitWithTime

func (h *Header) InitWithTime(kind Kind, apiVersion string, version string, ts time.Time)

InitWithTime is like Init but uses the caller-supplied timestamp. Use this when the header feeds into a digest, signature, or otherwise reproducible artifact — derive ts from a content-addressable source (commit SHA, the SOURCE_DATE_EPOCH environment variable, etc.).

type Kind

type Kind string

Kind represents the type of AICR resource. All AICR resources should use these constants for consistency.

const (
	KindSnapshot     Kind = "Snapshot"
	KindRecipe       Kind = "Recipe"
	KindRecipeResult Kind = "RecipeResult"
)

Valid Kind constants for all AICR resource types.

func (Kind) String

func (k Kind) String() string

String returns the string representation of the Kind.