substrate

type ClassSupport struct {
	// Classes the substrate can enforce, strongest last. A class is listed ONLY
	// when its enforcing runtime is actually available (never overclaim).
	Classes []types.ConfinementClass
	// Resolved maps each available class to its substrate label ("oci/<runtime>").
	Resolved map[types.ConfinementClass]string
	// StructuralEgress reports L0 (no default route; sole egress = wardyn-proxy).
	StructuralEgress bool
	// NetworkPolicy reports L1 (a packet-filter default-deny, e.g. Kubernetes
	// NetworkPolicy, default-denying the agent's egress except the proxy
	// sidecar) — PROVEN on this host/cluster, not merely configured. A
	// substrate sets this true only after a boot-time canary has positively
	// confirmed the deny is actually enforced (see the package doc); a
	// NetworkPolicy object that exists but is silently ignored by a
	// non-enforcing CNI is exactly the false claim this field must never make.
	// StructuralEgress and NetworkPolicy are not mutually exclusive in
	// principle, but today's substrates each prove exactly one.
	NetworkPolicy bool
	// SessionRecording reports wardyn-rec PTY recording support.
	SessionRecording bool
}

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 — L0).
	ProxyImage string
	// ConfinementRuntimes are the operator's fail-closed per-class runtime pins
	// (WARDYN_CONFINEMENT_MAP); nil = the substrate's built-in defaults.
	ConfinementRuntimes map[types.ConfinementClass]string
}

type Substrate interface {
	// Name reports the substrate kind ("docker"/OCI today), surfaced on /healthz.
	Name() string
	// Classes reports the enforceable Confinement Classes + their substrate labels.
	Classes(ctx context.Context) (ClassSupport, error)
	// CreateSandbox provisions the run's isolated network + proxy + agent unit,
	// fail-closed with full rollback on any error.
	CreateSandbox(ctx context.Context, spec runner.SandboxSpec) (runner.Sandbox, error)
	// Exec launches the agent process inside the sandbox ref, returning the
	// substrate-specific agent exec id ("" for exec-less/main-process substrates)
	// so the control plane can persist it for restart-safe liveness.
	//
	// A substrate MAY support only ONE Exec per ref over the sandbox's
	// lifetime: Kubernetes ephemeral containers are ADD-ONLY (a pod's
	// ephemeral-container list can only grow, never be replaced), so a k8s
	// substrate cannot honour a second Exec on the same ref the way the
	// docker substrate's "latest Exec wins" re-exec does today. Callers MUST
	// NOT re-Exec a ref expecting replace semantics — treat Exec as
	// one-shot per sandbox. A substrate that cannot honour a second Exec on
	// ref MUST return an error: never silently no-op, and never return the
	// PRIOR exec's id — a stale agentExecID would point AgentStatus at the
	// wrong process (fail closed; don't misreport liveness).
	//
	// This one-shot constraint is EXEC-SPECIFIC. ExecStream (below) is the
	// opposite: a substrate MUST support repeated ExecStream calls against
	// the same ref.
	Exec(ctx context.Context, ref string, argv []string) (agentExecID string, err error)
	// Wait blocks until the agent process for ref exits and returns its code.
	Wait(ctx context.Context, ref string) (int, error)
	// Attach opens an interactive PTY session inside ref.
	Attach(ctx context.Context, ref string, opts runner.AttachOptions) (runner.Session, error)
	// ExecStream launches spec.Argv inside ref as a fresh, streamable exec.
	// See runner.ExecStream's doc for the streaming, TTY-merge, and
	// invariant-3/4 security contract.
	//
	// UNLIKE Exec, ExecStream MUST be repeatable against the SAME ref: a
	// substrate MUST support many ExecStream calls against one long-lived
	// sandbox (e.g. one per SSH/SFTP channel). A k8s substrate implements
	// ExecStream on the streaming exec subresource (pods/<name>/exec —
	// repeatable, leaves no pod-spec residue), NOT an ephemeral container
	// (add-only — that limit is what makes Exec one-shot, not ExecStream).
	ExecStream(ctx context.Context, ref string, spec runner.ExecSpec) (*runner.ExecSession, error)
	// Status reports the sandbox lifecycle state.
	Status(ctx context.Context, ref string) (runner.Status, error)
	// AgentStatus reports the AGENT's state restart-safely given the persisted
	// agentExecID (inspects the exec for exec-based substrates; falls 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
}