build

type ContentManifest struct {
	// LayerID is the layer this manifest describes.
	LayerID string `yaml:"layer_id"`

	// Files maps file path (relative to squashfs root) to SHA256.
	Files map[string]string `yaml:"files"`
}

type DryRunExecutor struct {
	Out io.Writer // defaults to os.Stderr
}

type EC2Config struct {
	// Region is the AWS region, e.g. "us-east-1".
	Region string

	// AMIID is the base AMI ID for the build instance (must match target OS/arch).
	AMIID string

	// InstanceType is the EC2 instance type, e.g. "c5.4xlarge" or "c6g.4xlarge".
	InstanceType string

	// SubnetID is the subnet to launch into; AWS picks a subnet if empty.
	SubnetID string

	// SecurityGroupID is the security group ID, e.g. "sg-0fca02f58fafcdad1".
	SecurityGroupID string

	// IAMProfile is the IAM instance profile name, e.g. "strata-builder".
	IAMProfile string

	// BucketURL is the S3 registry URL, e.g. "s3://strata-registry".
	BucketURL string

	// BinaryArch is the strata binary architecture suffix: "amd64" or "arm64".
	BinaryArch string

	// KeyRef is the cosign key reference. If it begins with "s3://", the
	// user-data script downloads it to /root/.strata-keys/cosign.key and
	// passes that local path to --key. Empty = keyless OIDC.
	KeyRef string

	// CosignVersion is the cosign release tag to install on the build instance,
	// e.g. "v3.0.5". Defaults to "v3.0.5".
	CosignVersion string

	// RootVolumeGB overrides the root EBS volume size in GiB.
	// Default 60. Some AMIs (e.g. DLAMIs) require a larger minimum.
	RootVolumeGB int32

	// PollInterval is how often to poll for build completion. Default 30s.
	PollInterval time.Duration

	// UseSpawn launches the build instance through the pinned spore.host spawn
	// CLI instead of the AWS SDK, so the instance gets spawn's TTL/auto-terminate
	// lifecycle and cannot linger after a failed or hung build (#236). It is
	// fire-and-forget: spawn owns the lifecycle, so it pairs with the no-wait
	// launch path, not the tag-polling one.
	UseSpawn bool

	// TTL is the spawn auto-terminate window (e.g. "4h") when UseSpawn is set:
	// the instance terminates after it regardless of build outcome — the hard
	// cost ceiling. Empty lets spawn apply its default idle timeout.
	TTL string
}

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

type EnvLayer struct {
	// Manifest is the full layer manifest from the registry.
	Manifest *spec.LayerManifest

	// SqfsPath is the local path to the downloaded squashfs file.
	SqfsPath string

	// MountOrder is the layer's position in the OverlayFS lower stack (1 = bottom).
	MountOrder int
}

type EnvResolver interface {
	// Resolve fetches manifests matching buildRequires (arch + abi) from the
	// registry, downloads their squashfs files to cacheDir, and returns the
	// resolved layers in mount order (lowest-tier layer first).
	Resolve(ctx context.Context, buildRequires []spec.Requirement, arch, abi, cacheDir string) ([]EnvLayer, error)
}

type ErrMksquashfsNotFound struct{}

type Executor interface {
	Execute(ctx context.Context, scriptPath string, env []string, outputDir string) error
}

type FakeBuildEnvResolver struct {
	// Layers maps requirement name (e.g. "gcc") to the EnvLayer to return.
	// The same layer is returned regardless of version constraint.
	Layers map[string]EnvLayer
}

type Job struct {
	// RecipeDir is the path to the recipe directory.
	RecipeDir string

	// Base is the target OS and architecture.
	Base spec.BaseRef

	// RegistryURL is the S3 URL to push the built layer to.
	RegistryURL string

	// DryRun skips the actual EC2 launch and squashfs creation.
	// Used for recipe validation in CI without cloud access.
	DryRun bool

	// EnvResolver resolves and downloads build_requires layers for Stage 3
	// (OverlayFS build environment). When nil, build_requires are not mounted
	// and the layer is marked bootstrap_build=true (Tier 0 only).
	EnvResolver EnvResolver

	// CacheDir is the local directory for caching downloaded .sqfs files.
	// Defaults to os.TempDir()/strata-build-cache when empty.
	CacheDir string

	// KeyRef is the signing key reference (file path or KMS URI) used to
	// sign the layer. Stored as manifest.SignedBy for provenance tracking.
	KeyRef string
}

type LocalExecutor struct {
	Stdout io.Writer // defaults to os.Stdout
	Stderr io.Writer // defaults to os.Stderr
}

type ModuleEnvVar struct {
	// Var is the environment variable name, e.g. "GCC_HOME", "CC".
	Var string `yaml:"var"`

	// Path is the file path relative to the layer's install prefix.
	// Empty string means the prefix itself (setenv VAR base).
	// A non-empty path is appended: setenv VAR (base .. "/" .. path).
	// Example: path "bin/gcc" → setenv("CC", base .. "/bin/gcc")
	Path string `yaml:"path"`
}

type Plan struct {
	// Stages is the ordered list of build stages. Each stage is a set of
	// recipe names that can build concurrently.
	Stages [][]string

	// Recipes maps recipe name to its parsed recipe.
	Recipes map[string]*Recipe
}

type PushRegistry interface {
	PushLayer(ctx context.Context, manifest *spec.LayerManifest,
		sqfsPath string, bundleJSON []byte) error
}

type Recipe struct {
	// Meta is the parsed meta.yaml content.
	Meta RecipeMeta

	// BuildScriptPath is the absolute path to build.sh.
	BuildScriptPath string

	// Dir is the recipe directory (parent of build.sh and meta.yaml).
	Dir string
}

type RecipeMeta struct {
	// Name is the layer name, e.g. "openmpi".
	Name string `yaml:"name"`

	// Version is the layer version, e.g. "4.1.6".
	Version string `yaml:"version"`

	// Description is optional human-readable context.
	Description string `yaml:"description,omitempty"`

	// Tier classifies where this layer sits in the dependency stack.
	// Valid values: "core", "library", "application".
	//   core:        built with OS system compiler; no build_requires (bootstrap).
	//   library:     built with Strata tools; may be dependency-only (user_selectable:false).
	//   application: end-user software built on top of core/library layers.
	// Required; validated by Validate().
	Tier string `yaml:"tier"`

	// Provides is the list of capabilities this layer makes available.
	// Written into LayerManifest.Provides at build time.
	Provides []spec.Capability `yaml:"provides"`

	// BuildRequires lists capabilities needed during the build but NOT
	// included in the output squashfs. The build environment supplies these.
	BuildRequires []spec.Requirement `yaml:"build_requires,omitempty"`

	// RuntimeRequires lists capabilities required at runtime on the target
	// instance. Written into LayerManifest.Requires. The resolver validates
	// these against BaseCapabilities before mounting.
	RuntimeRequires []spec.Requirement `yaml:"runtime_requires,omitempty"`

	// ABI is the C runtime ABI this layer targets: "linux-gnu-2.34" or "linux-gnu-2.35".
	// A single ABI covers multiple OS versions (AL2023, Rocky 9/10, RHEL 9).
	ABI string `yaml:"abi"`

	// UserSelectable is false for dependency-only layers (ucx, hwloc, pmix, libfabric).
	// Omit from YAML to default to true. ParseRecipe sets this to true when not
	// explicitly set false, because the Go zero value false would hide layers by default.
	UserSelectable *bool `yaml:"user_selectable,omitempty"`

	// InstallLayout is "versioned" (default) or "flat".
	// "flat" layers install directly to $STRATA_PREFIX, not $STRATA_PREFIX/<name>/<version>.
	InstallLayout string `yaml:"install_layout,omitempty"`

	// ModulefileEnv declares extra environment variables to emit in the
	// auto-generated Lmod modulefile beyond the standard auto-detected ones
	// (PATH, LD_LIBRARY_PATH, PKG_CONFIG_PATH, MANPATH, INFOPATH, CPATH).
	ModulefileEnv []ModuleEnvVar `yaml:"modulefile_env,omitempty"`

	// Sources lists the source artifacts the build fetches, each pinned by
	// SHA256. The build stages every declared source into $STRATA_SOURCES,
	// verifying its digest before build.sh runs, so a build is reproducible from
	// its recipe and a tampered source fails the build (#68). A recipe with no
	// Sources fetches nothing that is pinned — build.sh reading from the network
	// is the reproducibility gap this field closes; see StagedFile.
	Sources []RecipeSource `yaml:"sources,omitempty"`
}

type RecipeSource struct {
	// URL is where the artifact is fetched from.
	URL string `yaml:"url"`

	// SHA256 is the expected content digest (64 lowercase hex). A mismatch
	// between this and the fetched bytes fails the build.
	SHA256 string `yaml:"sha256"`

	// File is the staged filename under $STRATA_SOURCES. Optional; defaults to
	// the last path element of URL.
	File string `yaml:"file,omitempty"`

	// Arch restricts this source to one target architecture ("x86_64" or
	// "arm64"). Empty means it applies to every arch — correct for a source
	// tarball compiled per arch, where one digest is valid everywhere. An
	// arch-specific *binary* distribution declares one source per arch, each with
	// the same File, so build.sh reads a consistent $STRATA_SOURCES path while the
	// build stages only the source matching the arch it targets.
	Arch string `yaml:"arch,omitempty"`
}

type RegistryBuildEnvResolver struct {
	Registry RegistryClient
}

type RegistryClient interface {
	// ResolveLayer returns the highest-versioned layer manifest matching name,
	// versionPrefix, arch, and abi.
	ResolveLayer(ctx context.Context, name, versionPrefix, arch, abi string) (*spec.LayerManifest, error)

	// FetchLayerSqfs downloads the squashfs file for manifest to cacheDir and
	// returns the local file path. Cache hit returns the existing file immediately.
	FetchLayerSqfs(ctx context.Context, manifest *spec.LayerManifest, cacheDir string) (string, error)
}

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