Documentation
¶
Overview ¶
Package runner implements execution substrate introspection.
Three-layer model (mandatory):
- Layer 1 — SubstrateFacts: unconditional raw measurements (no mode params, no policy)
- Layer 2 — []Finding: policy evaluation (same facts, different severity per mode)
- Layer 3 — HealthGrade: deterministic reducer from findings
This package has no knowledge of CI runners, pipeline phases, or output rendering. It returns structured data; callers own rendering and policy wiring.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EvaluateHealth ¶
func EvaluateHealth(facts SubstrateFacts, opts Options) ([]Finding, HealthGrade)
EvaluateHealth applies policy to SubstrateFacts and returns findings + grade. Options controls Layer 2 only — CollectFacts is unconditional and unaffected.
func ResolveInvocationID ¶
func ResolveInvocationID(engine ExecutionEngine, identity RunnerIdentity) string
ResolveInvocationID returns a universal correlation ID for this run. For CI engines, this is the pipeline/run ID. For local runs, a generated 12-char hex ID.
Types ¶
type ExecutionEngine ¶
type ExecutionEngine string
ExecutionEngine identifies the CI orchestrator or execution context.
const ( EngineGitLab ExecutionEngine = "gitlab" EngineGitHub ExecutionEngine = "github" EngineForgejo ExecutionEngine = "forgejo" EngineGitea ExecutionEngine = "gitea" EngineLocal ExecutionEngine = "local" EngineStageFreight ExecutionEngine = "stagefreight" EngineUnknown ExecutionEngine = "unknown" )
func DetectEngine ¶
func DetectEngine() ExecutionEngine
DetectEngine identifies the CI orchestrator from environment variables.
type ExecutionReport ¶
type ExecutionReport struct {
Engine ExecutionEngine `json:"engine"`
InvocationID string `json:"invocation_id"` // universal correlation key
Identity RunnerIdentity `json:"identity"`
Facts SubstrateFacts `json:"facts"`
Findings []Finding `json:"findings"`
Health HealthGrade `json:"health"`
}
ExecutionReport is the complete execution introspection result. JSON field names use "runner" prefix in cistate for compatibility.
func Run ¶
func Run(rootDir string, opts Options) ExecutionReport
Run collects substrate facts, evaluates health policy, and assembles an ExecutionReport. This is the primary entry point.
type Finding ¶
type Finding struct {
ID string `json:"id"`
Status string `json:"status"` // "ok" | "warn" | "fail"
Detail string `json:"detail,omitempty"`
Severity string `json:"severity"` // "hard_fail" | "warn" | "info"
}
Finding is Layer 2: policy applied to facts.
type HealthGrade ¶
type HealthGrade string
HealthGrade is Layer 3: derived from findings.
const ( Healthy HealthGrade = "healthy" Degraded HealthGrade = "degraded" Unhealthy HealthGrade = "unhealthy" )
type Options ¶
type Options struct {
DockerRequired bool // true = docker absence is hard_fail; false = info
IsCrucible bool // doubles disk/memory warn thresholds
DiskWarnMB int64 // 0 = default (2048)
DiskFailMB int64 // 0 = default (512)
MemWarnMB int64 // 0 = default (512); IsCrucible doubles to 1024
}
Options controls Layer 2 policy only — never Layer 1 fact collection.
type RunnerIdentity ¶
type RunnerIdentity struct {
Name string `json:"name,omitempty"` // CI_RUNNER_DESCRIPTION / RUNNER_NAME
PipelineID string `json:"pipeline_id,omitempty"` // CI_PIPELINE_ID / GITHUB_RUN_ID
JobID string `json:"job_id,omitempty"` // CI_JOB_ID / GITHUB_JOB
Workflow string `json:"workflow,omitempty"` // GITHUB_WORKFLOW (GitHub only)
Controller string `json:"controller,omitempty"` // future: SF daemon controller
Satellite string `json:"satellite,omitempty"` // future: SF satellite node
}
RunnerIdentity holds engine-specific session fields. TODO: rename to ExecutionIdentity in a follow-on PR for domain consistency.
func ExtractIdentity ¶
func ExtractIdentity(engine ExecutionEngine) RunnerIdentity
ExtractIdentity reads engine-specific session fields from environment variables.
type SubstrateFacts ¶
type SubstrateFacts struct {
DockerSocket string `json:"docker_socket"` // path if found, "" if absent
DockerAvailable bool `json:"docker_available"`
DindDetected bool `json:"dind_detected"`
BuildKitAvailable bool `json:"buildkit_available"` // = DockerAvailable (modern Docker ships BuildKit)
BuildxAvailable bool `json:"buildx_available"`
DiskFreeMB int64 `json:"disk_free_mb"` // .stagefreight filesystem
TmpFreeMB int64 `json:"tmp_free_mb"`
MemAvailableMB int64 `json:"mem_available_mb"` // -1 if unsupported (non-Linux)
CPULoadAvg1 float64 `json:"cpu_load_avg1"` // -1 if unsupported
StagefreightWritable bool `json:"stagefreight_writable"`
WorkdirReadable bool `json:"workdir_readable"`
InodePctFree int `json:"inode_pct_free"` // -1 if unsupported
}
SubstrateFacts is Layer 1: raw substrate measurements, always collected unconditionally. Named "Substrate" not "Runner" because these facts describe the execution substrate regardless of whether it is a CI runner, local machine, or SF daemon node. No mode parameters. No policy. No severity. Just facts.
func CollectFacts ¶
func CollectFacts(rootDir string) SubstrateFacts
CollectFacts gathers raw substrate measurements unconditionally. No mode parameters. No policy. No severity. Just facts.
Source Files