contracts

type BuildGateConfig struct {
	// Disabled skips Build Gate jobs when true.
	Disabled bool `json:"disabled,omitempty" yaml:"disabled,omitempty"`

	// Pre configures stack detection policy for the pre-gate phase.
	Pre *BuildGatePhaseConfig `json:"pre,omitempty" yaml:"pre,omitempty"`

	// Post configures stack detection policy for the post-gate phase.
	Post *BuildGatePhaseConfig `json:"post,omitempty" yaml:"post,omitempty"`

	// Images provides mig-level image mapping overrides for Build Gate image resolution.
	// These rules override the default mapping file.
	Images []BuildGateImageRule `json:"images,omitempty" yaml:"images,omitempty"`
}

type BuildGateImageMapping struct {
	// Images holds the image rules from this source.
	Images []BuildGateImageRule
}

type BuildGateImageRule struct {
	// Stack holds the stack expectation to match against.
	// Language is required. Release and Tool are optional wildcards.
	Stack StackExpectation `json:"stack,omitempty" yaml:"stack,omitempty"`

	// Image is the container image URL to use when this rule matches.
	// Required field.
	Image string `json:"image,omitempty" yaml:"image,omitempty"`
}

type BuildGateLogFinding struct {
	Code     string `json:"code,omitempty"`
	Severity string `json:"severity"`
	Message  string `json:"message"`
	Evidence string `json:"evidence,omitempty"`
}

type BuildGatePhaseConfig struct {
	// Stack configures stack detection behavior for this gate phase.
	Stack *BuildGateStackConfig `json:"stack,omitempty" yaml:"stack,omitempty"`
}

type BuildGateResourceUsage struct {
	// Limits configured for the container (0 means unlimited/not set).
	LimitNanoCPUs    int64 `json:"limit_nano_cpus"`
	LimitMemoryBytes int64 `json:"limit_memory_bytes"`

	// Observed usage during the container lifetime.
	CPUTotalNs      uint64 `json:"cpu_total_ns"`
	MemUsageBytes   uint64 `json:"mem_usage_bytes"`
	MemMaxBytes     uint64 `json:"mem_max_bytes"`
	BlkioReadBytes  uint64 `json:"blkio_read_bytes"`
	BlkioWriteBytes uint64 `json:"blkio_write_bytes"`
	SizeRwBytes     *int64 `json:"size_rw_bytes,omitempty"`
}

type BuildGateStackConfig struct {
	Mode     BuildGateStackMode `json:"mode,omitempty" yaml:"mode,omitempty"`
	Language string             `json:"language,omitempty" yaml:"language,omitempty"`
	Tool     string             `json:"tool,omitempty" yaml:"tool,omitempty"`
	Release  string             `json:"release,omitempty" yaml:"release,omitempty"`
}

type BuildGateStackMode string

type BuildGateStageMetadata struct {
	LogDigest    types.Sha256Digest           `json:"log_digest,omitempty"`
	StaticChecks []BuildGateStaticCheckReport `json:"static_checks,omitempty"`
	// ExecutedCommand is the exact gate command shell payload executed by the
	// gate container.
	ExecutedCommand string `json:"executed_command,omitempty"`
	// Detected captures the resolved gate stack identity used for this gate
	// execution, including optional release matching.
	Detected    *StackExpectation     `json:"detected_stack,omitempty"`
	LogFindings []BuildGateLogFinding `json:"log_findings,omitempty"`
	// RuntimeImage is the container image name used to run the gate container.
	// Not serialized in JSON APIs.
	RuntimeImage string `json:"-"`
	// StackGate captures the outcome of Stack Gate pre-check validation.
	// Present only when Stack Gate mode is enabled.
	StackGate *StackGateResult `json:"stack_gate,omitempty"`
	// LogsText carries the raw build logs text for node-local processing.
	// Not serialized in JSON APIs.
	LogsText string `json:"-"`
	// Resources summarizes container limits and observed usage for the gate run.
	// Not serialized in JSON APIs.
	Resources *BuildGateResourceUsage `json:"-"`
	// BugSummary is a short one-line description of the gate failure.
	// Max 200 chars, no newlines.
	BugSummary string `json:"bug_summary,omitempty"`
}

type BuildGateStaticCheckFailure struct {
	RuleID   string `json:"rule_id,omitempty"`
	File     string `json:"file,omitempty"`
	Line     int    `json:"line,omitempty"`
	Column   int    `json:"column,omitempty"`
	Severity string `json:"severity"`
	Message  string `json:"message"`
}

type BuildGateStaticCheckReport struct {
	Language string                        `json:"language,omitempty"`
	Tool     string                        `json:"tool"`
	Passed   bool                          `json:"passed"`
	Failures []BuildGateStaticCheckFailure `json:"failures,omitempty"`
}

type BuildMeta struct {
	// Tool identifies the build tool (e.g., "maven", "gradle", "npm", "bazel").
	Tool string `json:"tool,omitempty"`
	// Command is the full command line executed (for diagnostics).
	Command string `json:"command,omitempty"`
	// StatusDetails provides additional context on build outcome.
	StatusDetails string `json:"status_details,omitempty"`
	// Metrics contains arbitrary build metrics (e.g., compilation time, test count).
	Metrics map[string]interface{} `json:"metrics,omitempty"`
}

type CommandSpec struct {
	// Shell holds the command when specified as a single shell string.
	// When non-empty, the command is executed via ["/bin/sh", "-c", Shell].
	Shell string

	// Exec holds the command when specified as an exec array.
	// When non-nil, the command is executed directly without a shell wrapper.
	Exec []string
}

type GateClaimContext struct {
	CycleName string `json:"cycle_name"`
}

type JobImage struct {
	// Universal holds the image when specified as a single string.
	// When non-empty, this image is used regardless of detected stack.
	Universal string

	// ByStack holds stack-specific images when image is specified as a map.
	// Keys are stack names (e.g., "java-maven", "java-gradle", "default").
	// When non-nil and non-empty, stack resolution rules apply.
	ByStack map[MigStack]string
}

type JobKind string

type JobMeta struct {
	// Kind identifies the job type: "mig", "gate", or "build".
	Kind JobKind `json:"kind"`

	// GateMetadata contains build gate validation metadata when Kind is JobKindGate.
	// This includes static check results, log findings, and digest information.
	GateMetadata *BuildGateStageMetadata `json:"gate,omitempty"`

	// Build contains build tool metadata when Kind is JobKindBuild.
	// This includes tool name, command, status details, and metrics.
	Build *BuildMeta `json:"build,omitempty"`

	// MigStepName stores the user-defined step name from MigSpec.Steps[i].Name
	// for mig jobs. Used by the CLI to display a friendly name in --follow mode.
	// Only populated for mig jobs (kind="mig") when a step name is provided.
	MigStepName string `json:"mig_step_name,omitempty"`

	// MigStepIndex stores the concrete mig step index selected for this job.
	// Populated for mig jobs so execution does not depend on job name parsing.
	MigStepIndex *int `json:"mig_step_index,omitempty"`

	// GateCycleName stores the concrete gate cycle name used by gate jobs.
	// Examples: pre-gate, post-gate.
	GateCycleName string `json:"gate_cycle_name,omitempty"`
}

type ManifestReference struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type MigClaimContext struct {
	StepIndex int `json:"step_index"`
}

type MigSpec struct {

	// JobID is the claimed job ID injected into the spec at claim time.
	JobID types.JobID `json:"job_id,omitempty" yaml:"job_id,omitempty"`

	// APIVersion is an optional schema version identifier (e.g., "ploy.mig/v1alpha1").
	// Informational only; the control plane forwards specs as opaque JSON.
	APIVersion string `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"`

	// Name is an optional stable name for publishing and selecting this spec.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

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

	// Steps holds the ordered list of mig steps.
	// A spec must contain at least one step.
	Steps []MigStep `json:"steps,omitempty" yaml:"steps,omitempty"`

	// Envs holds environment variables applied to every step (step envs overrides on conflicts).
	Envs map[string]string `json:"envs,omitempty" yaml:"envs,omitempty"`

	// BuildGate configures Build Gate validation policy.
	// Applies globally to all steps.
	BuildGate *BuildGateConfig `json:"build_gate,omitempty" yaml:"build_gate,omitempty"`

	// BundleMap maps content hashes used in In/Out/Home/Tmp entries to their
	// spec bundle download identifiers (bundle IDs). Populated by the CLI
	// compiler during spec submission. The nodeagent uses this to resolve
	// shortHash → bundleID for resource download during materialization.
	BundleMap map[string]string `json:"bundle_map,omitempty" yaml:"bundle_map,omitempty"`
}

type MigStack string

type MigStep struct {
	// Name is an optional human-readable name for this step.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Image is the container image for this step (required).
	// Supports both universal images (string) and stack-specific images (map).
	Image JobImage `json:"image,omitempty" yaml:"image,omitempty"`

	// Command is the container command override for this step (optional).
	// Can be a shell string or an exec array.
	Command CommandSpec `json:"command,omitempty,omitzero" yaml:"command,omitempty"`

	// Envs holds environment variables specific to this step.
	Envs map[string]string `json:"envs,omitempty" yaml:"envs,omitempty"`

	// Options holds strict, step-scoped runtime options.
	Options MigStepOptions `json:"options,omitempty,omitzero" yaml:"options,omitempty"`

	// In lists canonical read-only input entries ("shortHash:/in/dst").
	In []string `json:"in,omitempty" yaml:"in,omitempty"`

	// Out lists canonical read-write output entries ("shortHash:/out/dst").
	Out []string `json:"out,omitempty" yaml:"out,omitempty"`

	// Home lists canonical home-relative entries ("shortHash:dst{:ro}").
	Home []string `json:"home,omitempty" yaml:"home,omitempty"`

	// Tmp lists canonical writable temporary entries ("shortHash:/tmp/dst").
	Tmp []string `json:"tmp,omitempty" yaml:"tmp,omitempty"`

	// Stack configures Stack Gate validation for this step.
	// Inbound validates pre-mig expectations; Outbound validates post-mig expectations.
	Stack *StackGateSpec `json:"stack,omitempty" yaml:"stack,omitempty"`
}

type MigStepOptions struct {
	MountDockerSocket bool `json:"mount_docker_socket,omitempty" yaml:"mount_docker_socket,omitempty"`
}

type ParsedStoredEntry struct {
	Hash     string
	Dst      string
	ReadOnly bool
}

type RepoMaterialization struct {
	URL           types.RepoURL   `json:"url,omitempty"`
	BaseRef       types.GitRef    `json:"base_ref,omitempty"`
	Commit        types.CommitSHA `json:"commit,omitempty"`
	WorkspaceHint string          `json:"workspace_hint,omitempty"`
}

type StackExpectation struct {
	// Language is the expected programming language (e.g., "java", "go", "python").
	Language string `json:"language,omitempty" yaml:"language,omitempty"`

	// Tool is the expected build tool (e.g., "maven", "gradle", "npm").
	Tool string `json:"tool,omitempty" yaml:"tool,omitempty"`

	// Release is the expected version/release (e.g., "11", "17", "3.9").
	// Stored as string to handle both integer and string release values in YAML.
	Release string `json:"release,omitempty" yaml:"release,omitempty"`
}

type StackGatePhaseSpec struct {
	// Enabled controls whether this phase is active.
	// When false, the phase is skipped entirely.
	Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// Expect defines the stack expectations for this phase.
	// Only validated when Enabled is true.
	Expect *StackExpectation `json:"expect,omitempty" yaml:"expect,omitempty"`
}

type StackGateResult struct {
	Enabled      bool              `json:"enabled"`
	Expected     *StackExpectation `json:"expected,omitempty"`
	Detected     *StackExpectation `json:"detected,omitempty"`
	RuntimeImage string            `json:"runtime_image,omitempty"`
	Result       string            `json:"result,omitempty"` // "pass", "mismatch", "unknown"
	Reason       string            `json:"reason,omitempty"`
}

type StackGateSpec struct {
	// Inbound configures pre-mig stack validation.
	// Validates that the repository matches expectations before the mig runs.
	Inbound *StackGatePhaseSpec `json:"inbound,omitempty" yaml:"inbound,omitempty"`

	// Outbound configures post-mig stack validation.
	// Validates that the mig produced the expected stack transformation.
	Outbound *StackGatePhaseSpec `json:"outbound,omitempty" yaml:"outbound,omitempty"`
}

type StageName string

type StepArtifact struct {
	Name string
	Type string
}

type StepGateSpec struct {
	Enabled bool
	Env     map[string]string

	// ImageOverrides holds mig-level image mapping overrides for gate execution.
	// These rules override the default mapping file.
	ImageOverrides []BuildGateImageRule

	// StackDetect configures stack detection behavior for this gate.
	// mode=forced skips detection and uses the configured stack.
	// mode=strict requires detection to match the configured stack.
	// mode=fallback uses detection when complete, otherwise the configured stack.
	StackDetect *BuildGateStackConfig

	// RepoURL is the Git repository URL for remote gate execution.
	// Populated from StartRunRequest.RepoURL when building manifests.
	RepoURL types.RepoURL

	// RepoID is the repo identifier for this execution.
	// Used for gate job/runtime correlation.
	RepoID types.MigRepoID

	// Ref is the Git reference (commit SHA, branch, or tag) for remote gate execution.
	// Derived from CommitSHA > BaseRef precedence when building manifests.
	Ref types.GitRef

	// DiffPatch is an optional gzipped unified diff (base64-encoded) to apply
	// on top of the cloned repo_url+ref baseline, avoiding full archive uploads.
	// The diff captures all changes relative to the initial repo_url+ref clone.
	DiffPatch []byte

	// StackGate holds the Stack Gate configuration for this step.
	// Used for pre/post gate validation of stack expectations.
	StackGate *StepGateStackSpec
}

type StepGateStackSpec struct {
	// Enabled controls whether Stack Gate validation is active for this phase.
	Enabled bool

	// Expect holds the stack expectations to validate.
	// Only validated when Enabled is true.
	Expect *StackExpectation
}

type StepInput struct {
	Name        string
	MountPath   string
	Mode        StepInputMode
	SnapshotCID types.CID
	DiffCID     types.CID
	Hydration   *StepInputHydration
}

type StepInputArtifactRef struct {
	CID    types.CID          `json:"cid"`
	Digest types.Sha256Digest `json:"digest,omitempty"`
	Size   int64              `json:"size,omitempty"`
}

type StepInputHydration struct {
	BaseSnapshot StepInputArtifactRef   `json:"base_snapshot,omitempty"`
	Diffs        []StepInputArtifactRef `json:"diffs,omitempty"`
	Repo         *RepoMaterialization   `json:"repo,omitempty"`
}

type StepInputMode string

type StepManifest struct {
	ID         types.StepID
	Name       string
	Image      string
	Command    []string
	Args       []string
	WorkingDir string
	Envs       map[string]string
	Inputs     []StepInput
	Outputs    []StepOutput
	Artifacts  []StepArtifact
	Gate       *StepGateSpec
	Resources  StepResourceSpec
	// Options holds arbitrary run-specific options.
	// Read options via OptionString/OptionBool helpers to avoid scattered type
	// assertions in callers. This field is not validated and values are never
	// logged.
	Options map[string]any

	// In lists canonical read-only input entries ("shortHash:/in/dst").
	In []string

	// Out lists canonical read-write output entries ("shortHash:/out/dst").
	Out []string

	// Home lists canonical home-relative entries ("shortHash:dst{:ro}").
	Home []string

	// Tmp lists canonical writable temporary entries ("shortHash:/tmp/dst").
	Tmp []string

	// BundleMap maps content hashes to spec bundle download identifiers.
	// The nodeagent uses this to resolve Hydra entry hashes → bundleIDs
	// for resource download during staged materialization.
	BundleMap map[string]string
}

type StepOutput struct {
	Name string
	Path string
	Type string
}

type StepResourceSpec struct {
	CPU    types.CPUmilli
	Memory types.Bytes
	Disk   types.Bytes
	GPU    string
}

type SubjectSet struct {
	CheckpointStream string
	ArtifactStream   string
	StatusStream     string
}

type WorkflowRun struct {
	SchemaVersion string              `json:"schema_version"`
	RunID         types.RunID         `json:"run_id"`
	Manifest      ManifestReference   `json:"manifest"`
	Repo          RepoMaterialization `json:"repo,omitempty"`
}