substrate

type Advertiser interface {
	Advertised() (runner.TargetFacts, bool)
}

type ClassSupport struct {
	Classes                   []types.ConfinementClass          // strongest last; never overclaim
	Resolved                  map[types.ConfinementClass]string // substrate label ("oci/<runtime>") per class
	StructuralEgress          bool                              // L0: no default route; sole egress = wardyn-proxy
	NetworkPolicy             bool                              // L1, true only once a boot-time canary confirms enforcement
	NetworkPolicyAcknowledged bool                              // an OPERATOR accepted a canary failure; never a substitute for NetworkPolicy=true
	SessionRecording          bool                              // wardyn-rec PTY recording support
	// RecordPerRun says the substrate records each run as its SandboxSpec.Record says, within
	// SessionRecording. A runner that predates it records by its own setting whatever the org asks,
	// so the org treats it as one that does not record on its word (TargetFacts.Records).
	RecordPerRun bool
	// UserDrives and ManagedFiles are CONJUNCTION-aggregated (read BEFORE
	// routing, unlike every OR-merged flag above): can this substrate BIND a
	// member's user drive / deliver a root-owned file; false fail-closed.
	UserDrives   bool
	ManagedFiles bool
	// EphemeralDiskEnforcement names what binds runner.Resources.DiskMiB —
	// `filesystem`, `eviction`, or `none`/empty. Aggregated as the WEAKEST.
	EphemeralDiskEnforcement types.StorageEnforcement
	Freeze                   map[types.ConfinementClass]bool // per-class pause/resume support; absent/false = none
	ExecOutputUncaptured     bool                            // an exec's output cannot be captured (runner.Capabilities.ExecOutputUncaptured)
}

type Constructor func(Deps) (Substrate, error)

type Deps struct {
	// ProxyImage is the wardyn-proxy sidecar image the substrate launches beside each agent (the sole egress path).
	ProxyImage string
	// DriveProbeImage is the OCI image the docker substrate's host_path drive-readability
	// probe runs in; empty means the substrate's own pinned default (a non-OCI substrate ignores it).
	DriveProbeImage string
	// ConfinementRuntimes are the operator's fail-closed per-class runtime pins (WARDYN_CONFINEMENT_MAP); nil = built-in defaults.
	ConfinementRuntimes map[types.ConfinementClass]string
	// UserDriveHostRoots is WARDYN_USER_DRIVE_HOST_ROOTS, parsed once at boot and passed here
	// so every substrate agrees on one host_path ceiling instead of re-reading the env itself.
	// nil (default) refuses every host_path drive; Kubernetes (no host-path backend) ignores it.
	UserDriveHostRoots []string
	// Record is whether a substrate should wrap Exec's argv with wardyn-rec (PTY recording),
	// set by cmd/wardynd from the resolved recording-store selection (RecordEnabled) rather
	// than hardcoded; each substrate must carry it through to Config.Record verbatim, never defaulting it to true.
	Record bool
}

type Substrate interface {
	Name() string // reports the substrate kind, surfaced on /healthz
	// Classes reports the enforceable Confinement Classes + their substrate labels.
	Classes(ctx context.Context) (ClassSupport, error)
	// CreateSandbox provisions the run's sandbox, fail-closed with full rollback on any error.
	CreateSandbox(ctx context.Context, spec runner.SandboxSpec) (runner.Sandbox, error)
	// Exec launches the agent process inside ref, returning the exec id for
	// restart-safe liveness. A substrate MAY support only ONE Exec per ref
	// (k8s ephemeral containers are ADD-ONLY) and MUST error rather than
	// no-op or return the PRIOR id when it can't honour a second.
	Exec(ctx context.Context, ref string, argv []string) (agentExecID string, err error)
	Wait(ctx context.Context, ref string) (int, error)                                         // blocks until the agent process for ref exits and returns its code
	Attach(ctx context.Context, ref string, opts runner.AttachOptions) (runner.Session, error) // opens an interactive PTY session inside ref
	// ExecStream launches a fresh, streamable exec, repeatable against the SAME ref (see runner.ExecStream's doc).
	ExecStream(ctx context.Context, ref string, spec runner.ExecSpec) (*runner.ExecSession, error)
	Status(ctx context.Context, ref string) (runner.Status, error) // reports the sandbox lifecycle state
	// AgentStatus reports the AGENT's state restart-safely, falling back to Status when agentExecID is "".
	AgentStatus(ctx context.Context, ref, agentExecID string) (runner.Status, error)
	// StopSandbox is the graceful teardown (idempotent on a gone sandbox).
	StopSandbox(ctx context.Context, ref string) error
	// KillSandbox is the immediate kill-switch teardown (idempotent).
	KillSandbox(ctx context.Context, ref string) error
}