workspace

type AgentdDeliveryConfig struct {
	Image             string
	BinarySHA256AMD64 string
	BinarySHA256ARM64 string
}

type BinaryPins struct {
	SHA256AMD64 string
	SHA256ARM64 string
}

type CachedLLMProviderSource struct {
	// contains filtered or unexported fields
}

type CachedOrgStatusClient struct {
	// contains filtered or unexported fields
}

type FailureClass string

type HTTPRelayRouterClient struct {
	// contains filtered or unexported fields
}

type HostResolver interface {
	LookupHost(ctx context.Context, host string) ([]string, error)
}

type LLMProviderSource interface {
	LLMProviders(ctx context.Context, ownerUserID, workspaceID string) ([]secrets.LLMProviderData, error)
}

type OpencodeDeliveryConfig struct {
	Image             string
	BinarySHA256AMD64 string
	BinarySHA256ARM64 string
}

type OrgStatusClient interface {
	GetOrgStatus(ctx context.Context, orgID string) (status string, ok bool)
}

type OrgStatusLogger interface {
	Info(msg string, keysAndValues ...any)
	Error(err error, msg string, keysAndValues ...any)
}

type PodObservation struct {
	Exists             bool
	Phase              corev1.PodPhase
	Reason             string
	Message            string
	ContainerReason    string
	ContainerExitCode  int32
	ContainerOOMKilled bool
	CrashLoop          bool
	Unschedulable      bool
	Scheduled          bool
}

type RecoveryPolicy struct {
	MaxAttempts    int
	BackoffBase    time.Duration
	BackoffMax     time.Duration
	BackoffFactor  int
	StabilityReset time.Duration
	// ExhaustionAfter is the ConsecutiveFailures count at which the
	// recovery episode is flagged exhausted (#760): a RecoveryExhausted
	// condition, a warning Event, and a
	// WorkspaceRecoveryExhaustedTotal increment fire once, on the
	// crossing. Retries are NOT halted — backoff continues, and
	// spec.suspend=true (#699) is the operator's halt.
	ExhaustionAfter int32
}

type RelayMintRequest struct {
	WorkspaceID    string   `json:"workspaceID"`
	ProviderSlug   string   `json:"providerSlug"`
	BaseURL        string   `json:"baseURL"`
	ModelAllowlist []string `json:"modelAllowlist"`
	TTLSec         int64    `json:"ttlSeconds"`
	KeyID          string   `json:"keyID"`
}

type RelayRotateReceipt struct {
	KeyID      string `json:"keyID"`
	Generation int64  `json:"generation"`
	PublicKey  []byte `json:"publicKey"`
}

type RelayRouterClient interface {
	MintToken(ctx context.Context, req RelayMintRequest) (string, error)
	RotateKeys(ctx context.Context) (RelayRotateReceipt, error)
}

type RelayStagingConfig struct {
	RouterURL      string
	Namespace      string
	TokenTTL       time.Duration
	ProviderSource LLMProviderSource
	RouterClient   RelayRouterClient

	Now func() time.Time

	// APIReader is the DIRECT (non-cached) reader every llm-relay Secret
	// read goes through (pub, mint-key). The reconciler's cached client
	// cannot serve these: a namespace outside the cache scope fails
	// without an API call, and an informer inside it needs LIST+WATCH —
	// verbs the llm-relay Role deliberately withholds (§4.3 deviation
	// note). Writes stay on the reconciler client (controller-runtime
	// writes bypass the cache). REQUIRED at construction
	// (mgr.GetAPIReader() in production) — there is deliberately no
	// cached-client fallback.
	APIReader client.Reader
	// contains filtered or unexported fields
}

type UploadStagingConfig struct {
	BudgetBytes         int64
	CredentialFloorByte int64
	MaxConcurrent       int
	TTLMilliseconds     int64
	ApplyTimeoutMilli   int64
	// contains filtered or unexported fields
}

type WorkspaceReconciler struct {
	client.Client
	Scheme *runtime.Scheme

	// APIReader is the manager's DIRECT (non-cached) reader for
	// cluster-scoped lookups on the reconcile path (#1587): RuntimeEnvironment
	// resolution (pod_builder.go) and StorageClass WFFC detection (pvc.go).
	// A cached Get of these unwatched cluster-scoped types lazily starts an
	// informer that blocks forever when RBAC withholds the list/watch (#1551)
	// — wedging workers silently; direct reads fail fast and requeue.
	// Wired to mgr.GetAPIReader() in SetupControllers; SetupWithManager
	// refuses nil. DirectReader() serves lookups; never use r.Client for them.
	APIReader client.Reader

	// HostResolver is used by the per-workspace NetworkPolicy generator
	// (network_policy.go) to resolve declared FQDNs to /32 ipBlocks at
	// reconcile time. Tests inject a stub; production uses
	// defaultHostResolver (net.DefaultResolver) when nil.
	HostResolver HostResolver

	// InferenceRelayURL is the self-hosted relay URL for free-tier inference
	// (Epic 42 InferenceRelay fleet). When set, workspace pods route opencode
	// free-tier provider requests through this URL for IP distribution. When
	// empty (the chart default), opencode uses its default gateway
	// (opencode.ai/zen/v1) directly with the built-in `public` key.
	InferenceRelayURL string

	// OrgStatusClient, when non-nil AND the workspace belongs to an org
	// (Spec.Owner.OrgID != ""), is consulted on every Active reconcile to drive
	// D20 org-level suspension: if the org is suspended, the workspace
	// transitions Active → Suspending (pod killed, PVC retained). The client is
	// nil when --api-service-url is unset, disabling the feature. Lookups are
	// cached (30s TTL); a lookup failure fails open (workspace keeps running).
	OrgStatusClient OrgStatusClient

	// WorkspaceTerminationGraceSeconds (#1507) bounds every workspace
	// pod's graceful termination: on pod deletion kubelet SIGTERMs
	// agentd, whose serial shutdown budget (HTTP drain 25s → bg wait 5s
	// → opencode child SIGTERM→SIGKILL 5s) fits inside the default 40s.
	// The SUSPEND path deliberately does NOT wait for busy sessions
	// (#1507): this grace IS the bounded graceful opencode termination;
	// the hard cut at expiry is the deadline. 0 = controller default
	// (40s, the serial budget + margin). Sourced from
	// --workspace-termination-grace-seconds / Helm
	// controller.workspaceTerminationGraceSeconds.
	WorkspaceTerminationGraceSeconds int64

	// DefaultRuntimeClass is the container runtime class applied to all
	// workspace pods (Epic 51 S51.1). Typically "gvisor" for production
	// multi-tenant deployments to provide kernel-level isolation against
	// container escape. Empty means use the default (runc). Set via
	// --default-runtime-class controller flag, sourced from Helm
	// .Values.gvisor.defaultRuntimeClass (only set when .Values.gvisor.enabled
	// is true). Individual workspaces can override via spec.runtimeClass for
	// compatibility opt-out (admin-gated).
	DefaultRuntimeClass string

	// APIServiceURL is the in-cluster URL of the API service, used by the
	// workspace init container's bootstrap subcommand (Epic 35 US-35.4) to
	// fetch decrypted credentials via POST /internal/v1/pod-bootstrap. Same
	// value as --api-service-url (also used for OrgStatusClient). When empty,
	// the bootstrap subcommand degrades gracefully (empty secrets, pod boots
	// without credentials; the notify-pull path handles delivery).
	APIServiceURL string

	// PreviewOriginBaseDomain (Epic 66 Phase 1): when non-empty, workspace
	// pods receive PREVIEW_ORIGIN_BASE_DOMAIN so agentd's dev_preview_url
	// MCP tool emits the per-workspace-origin bootstrap URL instead of the
	// path-based URL. Sourced from the same previewOrigin.baseDomain chart
	// value the API consumes — one flag enables the deployment-wide mode.
	// Empty = path-based dev preview (unchanged behavior).
	PreviewOriginBaseDomain string

	// APIPublicURL (#1332) is the externally reachable API origin wired
	// into every container that runs agentd tooling as
	// LLMSAFESPACE_API_PUBLIC_URL — the origin the dev_preview_url MCP
	// tool bakes into user-facing URLs. Distinct from APIServiceURL
	// (in-cluster, load-bearing for bootstrap): in sidecar mode the tool
	// runs in the sidecar, whose LLMSAFESPACE_API_URL is deliberately the
	// svc coordinate. When unset and PreviewOriginBaseDomain is set, the
	// controller derives https://api.<baseDomain>; when both are unset
	// the env is omitted and the tool validates LLMSAFESPACE_API_URL,
	// refusing cluster-internal values. Same value as --api-public-url
	// (Helm value controller.apiPublicURL).
	APIPublicURL string
	// #863 agentd overlay delivery. When AgentdImage is set, buildPod pins a
	// digest-addressed image volume into every workspace pod and the
	// supervisor self-verifies the binary's sha256 against the per-arch
	// pins before exec (design 0053 — the deleted entrypoint's check
	// moved into the binary). All three fields must be set together (validated at
	// startup by validateAgentdDeliveryConfig). Empty AgentdImage = legacy
	// mode (binary baked into runtimes/base; no volume, mount, or env).
	AgentdImage             string
	AgentdBinarySHA256AMD64 string
	AgentdBinarySHA256ARM64 string

	// Design 0053 §4.2 opencode overlay delivery. When OpencodeImage is
	// set, buildPod pins a digest-addressed image volume into every
	// workspace pod (RO mount at /opencode on the workspace container
	// only) and the supervisor verifies the binary's sha256 against the
	// per-arch pins before spawn. All three fields must be set together
	// (validated at startup by validateOpencodeDeliveryConfig). Empty
	// OpencodeImage = baked-in mode (opencode stays in runtimes/base; S1
	// default — the feature is opt-in and inert until the base strip).
	OpencodeImage             string
	OpencodeBinarySHA256AMD64 string
	OpencodeBinarySHA256ARM64 string

	// AgentdSidecarEnabled (design 0051 US-2, chart-gated, default
	// false): when true, buildPod appends the native agentd sidecar and
	// switches the main container to supervise-opencode mode. Requires
	// AgentdImage (validated at startup) — the sidecar runs the same
	// digest-pinned delivery artifact.
	AgentdSidecarEnabled bool
	// UploadStaging (design 0060 PR 2.5): the env knobs landed on BOTH
	// agentd-bearing containers. Zero value = no env = agentd defaults.
	UploadStaging UploadStagingConfig

	// Recorder emits Kubernetes events on the Workspace (agentd verify
	// failures). Injected from mgr.GetEventRecorderFor() in production;
	// a FakeRecorder in tests.
	Recorder record.EventRecorder

	// MaxConcurrentReconciles: how many DIFFERENT workspaces reconcile in
	// parallel (controller-runtime never runs the same object concurrently,
	// so per-workspace state stays single-writer). 0/negative = framework
	// default (1 = fully serial). The default serial behavior made fleet
	// resume linear (~8s per workspace — 40 workspaces ≈ 5+ minutes, run
	// 33811397260); main.go clamps this to 1..64 to bound apiserver load.
	MaxConcurrentReconciles int

	// RelayStaging (Epic 72 / design 0058, US-72.3): when non-nil, every
	// Creating/Active reconcile runs the staging pass — seal bound BYO
	// llm-provider credentials into llm-relay envelope Secrets, mint scoped
	// tokens, write the workspace-namespace handoff Secret, maintain the
	// CredentialsStaged/CredentialStale/CredentialRejected conditions, and
	// run the §4.2 DR/residual-window terminator. NIL (the default —
	// --relay-only-key-delivery=false) means zero behavior change: the
	// legacy raw-key path and byte-identical batches.
	RelayStaging *RelayStagingConfig
	// contains filtered or unexported fields
}