model

type ArtifactSpec struct {
	// Paths lists artifact paths to collect after the job completes.
	Paths []string

	// ExpireIn is a human-readable duration string (e.g. "1 week", "2 hours").
	// Empty means the forge default.
	ExpireIn string

	// WhenAlways uploads the artifacts even when the job FAILED (GitLab `artifacts: when:
	// always`; Actions `if: always()`). Set on audition so its contract — the ledger — reaches
	// perform whether or not audition's exit code was non-zero. The gate is the contract in the
	// ledger, NOT the forge's default drop-on-failure; without this, a failed audition drops its
	// ledger and the in-code gate is silently bypassed by forge behaviour.
	WhenAlways bool
}

type CapabilitySpec struct {
	// Docker indicates this job requires Docker daemon access (DinD).
	Docker bool

	// OIDC indicates this job requires an OIDC identity token.
	// GitLab emitter adds id_tokens.STAGEFREIGHT_OIDC.
	OIDC bool

	// ForgeAPI indicates this job needs a forge WRITE credential — for forge mutations
	// via the REST API (release creation, MR/PR, commit status) AND via git push (docs
	// and dependency auto-commits). On the Actions family both authenticate with the
	// same write-scoped token (GITHUB_TOKEN / GITEA_TOKEN / FORGEJO_TOKEN), so one
	// capability scopes the credential; the surface (API vs git transport) is a usage
	// detail. The emitter wires the token (operator PAT override → auto-token) ONLY onto
	// jobs that carry this capability, so the credential is never present in the build
	// phase (which runs untrusted Dockerfiles / build scripts). Credential visibility
	// follows mutation authority: planner-assigned to the phases that mutate the forge
	// (audition deps MR+commit, publish releases, narrate docs-commit) — never
	// perform/review.
	ForgeAPI bool

	// PackageRegistries lists the package/container registries this job pushes to,
	// by config provider + credential env prefix. Each forge's emitter auto-wires the
	// entry matching ITS native registry (github→ghcr, gitea→gitea, forgejo→forgejo)
	// with that forge's auto-token; entries it doesn't own (e.g. dockerhub, harbor)
	// are left to explicit secrets. Empty = no package-registry push.
	PackageRegistries []PackageRegistry
}

type Job struct {
	// Name is the canonical phase name (audition, perform, review, publish, narrate).
	Name string

	// Stage is the stage this job belongs to. For most forges, stages determine
	// execution order at the scheduler level.
	Stage string

	// Needs lists jobs that must complete before this job runs.
	// Empty means no dependencies (first stage).
	Needs []string

	// Commands are the shell commands to execute in order.
	Commands []string

	// Source controls git clone behavior for this job.
	Source SourceSpec

	// Artifacts describes what this job produces and how long to keep it.
	Artifacts ArtifactSpec

	// Routing declares runner placement requirements for this job.
	// The forge emitter lowers Labels to forge-native routing primitives.
	Routing RoutingSpec

	// Capabilities declares what execution substrate this job requires.
	// The forge emitter uses these to inject services, variables, etc.
	Capabilities CapabilitySpec

	// Policy controls job-level scheduling and failure behavior.
	Policy PolicySpec
}

type PackageRegistry struct {
	Provider   string
	CredPrefix string
}

type Pipeline struct {
	// Defaults are pipeline-level settings that apply to all jobs unless overridden.
	Defaults PipelineDefaults

	// Jobs is an ordered list of pipeline jobs. Ordering determines emit order.
	// The graph is structurally stable across all lifecycle modes.
	Jobs []Job
}

type PipelineDefaults struct {
	// Image is the default container image for all jobs.
	// GitLab: default.image. GitHub: container.image.
	Image string

	// Interruptible means jobs can be cancelled when a newer pipeline starts.
	// GitLab: default.interruptible. GitHub: concurrency.cancel-in-progress.
	Interruptible bool

	// CancelSuperseded means the forge should cancel in-flight pipelines
	// when a new commit arrives on the same ref.
	// GitLab: workflow.auto_cancel.on_new_commit.
	// GitHub: concurrency group with cancel-in-progress.
	CancelSuperseded bool

	// CIContext indicates this pipeline requires StageFreight CI context
	// hydration. Each emitter injects the appropriate mechanism:
	//   GitLab: before_script exporting SF_CI_* from CI_* variables
	//   GitHub: env block or setup step mapping GITHUB_* to SF_CI_*
	CIContext bool
}

type PolicySpec struct {
	// AllowFailure means the pipeline continues even if this job fails.
	AllowFailure bool

	// WhenAlways means this job runs regardless of prior job outcomes.
	// Used for narrate/docs jobs that must always emit truth.
	WhenAlways bool
}

type RoutingSpec struct {
	// Labels are runner selection labels. Empty means no routing constraint.
	//   GitLab emitter:             tags: [label...]
	//   GitHub/Gitea/Forgejo:       runs-on: [label...]
	Labels []string
}

type SourceSpec struct {
	// FullClone requests an unshallow clone (git depth 0).
	// False means the forge's default shallow clone behavior.
	FullClone bool
}