step

type ContainerHandle string

type ContainerMount struct {
	Source   string
	Target   string
	ReadOnly bool
}

type ContainerResourceUsage struct {
	CPUConsumedNs     int64
	DiskConsumedBytes int64
	MemConsumedBytes  int64
}

type ContainerResult struct {
	ExitCode    int
	StartedAt   time.Time
	CompletedAt time.Time
	ContainerID string
	InspectJSON []byte
}

type ContainerRuntime interface {
	Create(ctx context.Context, spec ContainerSpec) (ContainerHandle, error)
	Start(ctx context.Context, handle ContainerHandle) error
	Wait(ctx context.Context, handle ContainerHandle) (ContainerResult, error)
	Logs(ctx context.Context, handle ContainerHandle) ([]byte, error)
	Remove(ctx context.Context, handle ContainerHandle) error
}

type ContainerRuntimeOptions struct {
	// PullImage controls whether the runtime refreshes the image before container
	// creation.
	PullImage bool
	// Network is optional Docker network name (empty => default bridge).
	Network string
	// RegistryAuthConfigFile is a Docker auth config JSON file path
	// (DOCKER_AUTH_CONFIG format). When set, each image pull reads current
	// credentials from this file.
	RegistryAuthConfigFile string
	// RegistryAuthRefreshSocket is an optional Unix socket owned by the host.
	// When set, an auth failure on image pull asks the host to refresh registry
	// auth before retrying the same pull once.
	RegistryAuthRefreshSocket string
	// RegistryAuthConfigJSON is a Docker auth config JSON payload (DOCKER_AUTH_CONFIG
	// format). When set, image pulls use matching registry credentials.
	RegistryAuthConfigJSON string
}

type ContainerSpec struct {
	Image      string
	Command    []string
	WorkingDir string
	Env        map[string]string
	Mounts     []ContainerMount
	Labels     map[string]string
	// Optional resource limits (0 => unlimited)
	LimitNanoCPUs    int64
	LimitMemoryBytes int64
	// Optional disk limit for writable layer (bytes; 0 => unlimited).
	// When set, Docker runtime may pass a storage option (driver dependent).
	LimitDiskBytes int64
	// Optional raw storage size option string passed to Docker (e.g., "10G").
	// Set only when the operator provided PLOY_BUILDGATE_LIMIT_DISK_SPACE.
	StorageSizeOpt string
}

type DiffGenerator interface {
	Generate(ctx context.Context, workspace string) ([]byte, error)
}

type GateExecutor interface {
	Execute(ctx context.Context, spec *contracts.StepGateSpec, workspace string) (*contracts.BuildGateStageMetadata, error)
}

type GateRuntimeImageObserver func(ctx context.Context, image string)

type PatchStats struct {
	FilesChanged int
	LinesAdded   int
	LinesRemoved int
}

type Request struct {
	// RunID threads the workflow run identifier for correlation/labels.
	// Container labels and telemetry use this value via LabelRunID.
	RunID types.RunID
	// JobID threads the workflow job identifier for correlation/labels.
	// Container labels and telemetry use this value via LabelJobID.
	JobID     types.JobID
	Manifest  contracts.StepManifest
	Workspace string
	OutDir    string
	// InDir is an optional directory mounted at /in for cross-phase inputs.
	InDir string
	// ShareDir is an optional directory mounted at /share for run-scoped
	// shared inputs/outputs across job stages.
	ShareDir string
	// TmpDir is an optional per-job directory seeded from Manifest.Tmp and
	// mounted at /tmp for writable, non-artifact temporary files.
	TmpDir string
	// StagingDir is an optional path to a directory containing pre-materialized
	// Hydra resources. Each In/Out/Home/Tmp entry is mounted from StagingDir/<shortHash>.
	StagingDir string
}

type Result struct {
	ExitCode int
	// Docker container identity and inspect output when a container was run.
	ContainerID          string
	ContainerInspectJSON []byte
	// Per-stage timings captured during execution.
	Timings            StageTiming
	Gate               *contracts.BuildGateStageMetadata
	ContainerResources *ContainerResourceUsage
}

type Runner struct {
	Workspace  WorkspaceHydrator
	Containers ContainerRuntime
	Gate       GateExecutor
	LogWriter  io.Writer // Optional: streams logs to server as gzipped chunks.
}

type StageTiming struct {
	HydrationDuration types.Duration
	ExecutionDuration types.Duration
	GateDuration      types.Duration
	DiffDuration      types.Duration
	PublishDuration   types.Duration
	TotalDuration     types.Duration
}

type WorkspaceHydrator interface {
	Hydrate(ctx context.Context, manifest contracts.StepManifest, workspace string) error
}