v1alpha1

type AuditCredentialRef struct {
	// Name is the credential's logical name (matches the template's
	// requires.credentials[*].name).
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Provider is the provider kind that handled (or would have handled)
	// the request. See ADR-0015.
	// +optional
	Provider string `json:"provider,omitempty"`

	// Purpose is the requested purpose ("llm", "gitforge", "generic").
	// +optional
	Purpose string `json:"purpose,omitempty"`
}

type AuditDecision string

type AuditDestination struct {
	// Host is the destination hostname.
	// +kubebuilder:validation:Required
	Host string `json:"host"`

	// Port is the destination TCP port.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	Port int32 `json:"port,omitempty"`
}

type AuditEvent struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec AuditEventSpec `json:"spec"`
}

type AuditEventList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []AuditEvent `json:"items"`
}

type AuditEventSpec struct {
	// RunRef identifies the HarnessRun this decision pertains to. May be
	// empty for events emitted outside a run context (e.g. broker
	// startup diagnostics — not currently emitted).
	//
	// Names prefixed "seed-" denote a workspace-seed-time decision; the
	// suffix is the Workspace name (F-52).
	// +optional
	RunRef *LocalObjectReference `json:"runRef,omitempty"`

	// Decision is the outcome: granted, denied, or warned.
	// +kubebuilder:validation:Required
	Decision AuditDecision `json:"decision"`

	// Kind categorises the event. Shape of Destination, Credential, and
	// Policy fields depends on Kind.
	// +kubebuilder:validation:Required
	Kind AuditKind `json:"kind"`

	// Timestamp is when the decision was taken. Set by the emitter —
	// not metadata.creationTimestamp, which records when the object
	// landed in etcd (can lag materially under load).
	// +kubebuilder:validation:Required
	Timestamp metav1.Time `json:"timestamp"`

	// Destination is set for egress-* and credential-* kinds that target
	// an upstream service.
	// +optional
	Destination *AuditDestination `json:"destination,omitempty"`

	// Credential is set for credential-* kinds; names the logical
	// credential and the backing provider.
	// +optional
	Credential *AuditCredentialRef `json:"credential,omitempty"`

	// MatchedPolicy is the BrokerPolicy whose grant covered this
	// decision, or nil on a deny.
	// +optional
	MatchedPolicy *LocalObjectReference `json:"matchedPolicy,omitempty"`

	// Reason is a human-readable explanation. For denials, includes the
	// specific rule that failed.
	// +optional
	// +kubebuilder:validation:MaxLength=1024
	Reason string `json:"reason,omitempty"`

	// Count is the number of events collapsed into this record. Set
	// only for egress-block-summary and similar summary kinds; otherwise
	// implicitly 1.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Count int32 `json:"count,omitempty"`

	// SampleDestinations carries up to three example destinations when
	// Kind is a summary. Purely diagnostic.
	// +optional
	// +kubebuilder:validation:MaxItems=3
	SampleDestinations []AuditDestination `json:"sampleDestinations,omitempty"`

	// WindowStart and WindowEnd delimit the time range a summary event
	// covers. Set only for summary kinds.
	// +optional
	WindowStart *metav1.Time `json:"windowStart,omitempty"`

	// +optional
	WindowEnd *metav1.Time `json:"windowEnd,omitempty"`

	// Detail carries kind-specific key-value pairs that do not fit the
	// structured fields above. Used by interactive lifecycle kinds
	// (prompt-submitted, shell-session-*, credential-renewal-failed,
	// interactive-run-terminated) and any future kinds that need
	// extensible metadata without CRD schema churn.
	// +optional
	Detail map[string]string `json:"detail,omitempty"`
}

type AuditKind string

type BasicAuthSubstitution struct {
	// +kubebuilder:validation:Required
	Username string `json:"username"`
}

type BrokerCredentialReference struct {
	// Name of the broker-creds Secret (convention: <run>-broker-creds).
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key inside Secret.Data. Matches the credential name declared on
	// the template's spec.requires.credentials.
	// +kubebuilder:validation:Required
	Key string `json:"key"`
}

type BrokerPolicy struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec BrokerPolicySpec `json:"spec"`
	// +optional
	Status BrokerPolicyStatus `json:"status,omitzero"`
}

type BrokerPolicyGrants struct {
	// +optional
	Credentials []CredentialGrant `json:"credentials,omitempty"`
	// +optional
	Egress []EgressGrant `json:"egress,omitempty"`
	// +optional
	GitRepos []GitRepoGrant `json:"gitRepos,omitempty"`
	// Runs declares run-time interaction capabilities (interactive prompt
	// submission, shell open). Independent of Credentials, Egress,
	// GitRepos.
	// +optional
	Runs *GrantRunsCapabilities `json:"runs,omitempty"`
}

type BrokerPolicyList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []BrokerPolicy `json:"items"`
}

type BrokerPolicySpec struct {
	// AppliesToTemplates is a list of template name globs this policy
	// will back. "*" matches any template name; explicit names tighten
	// the operator-consent story. At least one entry is required.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:Required
	AppliesToTemplates []string `json:"appliesToTemplates"`

	// Grants enumerates the capabilities this policy is willing to back.
	// +kubebuilder:validation:Required
	Grants BrokerPolicyGrants `json:"grants"`

	// Interception selects the egress-proxy interception mode for runs
	// governed by this policy. Absent the field admission defaults to
	// requiring transparent mode; a run whose namespace PSA forbids
	// NET_ADMIN (baseline/restricted) then fails closed rather than
	// silently falling back to cooperative. Set
	// spec.interception.cooperativeAccepted to opt into the weaker mode
	// with a written reason.
	// +optional
	Interception *InterceptionSpec `json:"interception,omitempty"`

	// EgressDiscovery, when present, opens a time-bounded window during
	// which denied egress is allowed-but-logged. Admission rejects
	// expiresAt values in the past or more than 7 days in the future.
	// After the window closes, the BrokerPolicy reconciler sets
	// DiscoveryExpired=True and the HarnessRun admission webhook
	// rejects new runs governed by this policy until the operator
	// updates expiresAt or removes the field. See spec 0003 §3.6.
	// +optional
	EgressDiscovery *EgressDiscoverySpec `json:"egressDiscovery,omitempty"`
}

type BrokerPolicyStatus struct {
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ClusterHarnessTemplate struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec HarnessTemplateSpec `json:"spec"`
	// +optional
	Status ClusterHarnessTemplateStatus `json:"status,omitzero"`
}

type ClusterHarnessTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []ClusterHarnessTemplate `json:"items"`
}

type ClusterHarnessTemplateStatus struct {
	// ObservedGeneration is the last spec generation reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest observations of the template's state.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type CooperativeAcceptedInterception struct {
	// Accepted must be true.
	// +kubebuilder:validation:Required
	Accepted bool `json:"accepted"`

	// Reason explains why cooperative interception is necessary instead
	// of transparent. Typical reasons include cluster PSA=restricted
	// without a node-level DaemonSet proxy.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=20
	// +kubebuilder:validation:MaxLength=500
	Reason string `json:"reason"`
}

type CredentialGrant struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
	// +kubebuilder:validation:Required
	Provider ProviderConfig `json:"provider"`
}

type CredentialRequirement struct {
	// Name is the env-var key the agent reads. The broker-issued value
	// is exposed under this name inside the agent container.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
}

type CredentialStatus struct {
	// Name matches the template's requires.credentials[*].name.
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Provider is the backing provider kind (e.g. "UserSuppliedSecret",
	// "AnthropicAPI"). Copied from the matched grant.
	Provider string `json:"provider"`

	// DeliveryMode is "ProxyInjected" or "InContainer".
	// +kubebuilder:validation:Enum=ProxyInjected;InContainer
	DeliveryMode DeliveryModeName `json:"deliveryMode"`

	// Hosts lists the destination hostnames this credential substitutes
	// on, for ProxyInjected delivery. Empty for InContainer.
	// +optional
	Hosts []string `json:"hosts,omitempty"`

	// InContainerReason mirrors the policy grant's
	// deliveryMode.inContainer.reason when DeliveryMode is InContainer.
	// +optional
	InContainerReason string `json:"inContainerReason,omitempty"`
}

type DeliveryMode struct {
	// +optional
	ProxyInjected *ProxyInjectedDelivery `json:"proxyInjected,omitempty"`
	// +optional
	InContainer *InContainerDelivery `json:"inContainer,omitempty"`
}

type DeliveryModeName string

type EgressDiscoverySpec struct {
	// Accepted must be true; setting it documents that the operator
	// acknowledges egress will be allowed-but-logged rather than blocked
	// for the duration of ExpiresAt.
	// +kubebuilder:validation:Required
	Accepted bool `json:"accepted"`

	// Reason explains why a discovery window is necessary instead of
	// iterating per-denial via paddock policy suggest.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=20
	// +kubebuilder:validation:MaxLength=500
	Reason string `json:"reason"`

	// ExpiresAt closes the discovery window. Admission rejects values
	// in the past or more than 7 days in the future.
	// +kubebuilder:validation:Required
	ExpiresAt metav1.Time `json:"expiresAt"`
}

type EgressGrant struct {
	// +kubebuilder:validation:Required
	Host string `json:"host"`
	// +optional
	Ports []int32 `json:"ports,omitempty"`
}

type EgressRequirement struct {
	// Host is a destination hostname. A leading "*." permits any
	// subdomain (e.g. "*.anthropic.com"). Case-insensitive.
	// +kubebuilder:validation:Required
	Host string `json:"host"`

	// Ports lists the TCP ports this destination uses. Empty or [0]
	// means any port; otherwise the run's proxy will only permit
	// connections on these ports.
	// +optional
	Ports []int32 `json:"ports,omitempty"`
}

type EventAdapterSpec struct {
	// Image is the adapter sidecar image reference.
	// +kubebuilder:validation:Required
	Image string `json:"image"`

	// ImagePullPolicy overrides the default pull policy for the adapter.
	// +optional
	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`
}

type GitRepoAccess string

type GitRepoGrant struct {
	// +kubebuilder:validation:Required
	Owner string `json:"owner"`
	// +kubebuilder:validation:Required
	Repo string `json:"repo"`
	// +kubebuilder:default=read
	// +kubebuilder:validation:Enum=read;write
	// +optional
	Access GitRepoAccess `json:"access,omitempty"`
}

type GrantRunsCapabilities struct {
	// Interact enables prompt submission and event streaming for runs
	// matching this policy. Default false. Required for spec.mode:
	// Interactive admission.
	// +optional
	Interact bool `json:"interact,omitempty"`

	// Shell, when non-nil, enables shell-session open against runs
	// matching this policy. Nil means denied.
	// +optional
	Shell *ShellCapability `json:"shell,omitempty"`
}

type HarnessRun struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec HarnessRunSpec `json:"spec"`
	// +optional
	Status HarnessRunStatus `json:"status,omitzero"`
}

type HarnessRunList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []HarnessRun `json:"items"`
}

type HarnessRunMode string

type HarnessRunOutputs struct {
	// PullRequests opened by the run.
	// +optional
	PullRequests []string `json:"pullRequests,omitempty"`

	// FilesChanged is the count of files modified by the run.
	// +optional
	FilesChanged int32 `json:"filesChanged,omitempty"`

	// Summary is a human-readable summary of what the run accomplished.
	// +optional
	Summary string `json:"summary,omitempty"`

	// Artifacts are additional named outputs (URIs or file paths).
	// +optional
	Artifacts []string `json:"artifacts,omitempty"`
}

type HarnessRunPhase string

type HarnessRunSpec struct {
	// TemplateRef identifies which HarnessTemplate or ClusterHarnessTemplate
	// the run uses. Resolution tries namespaced first, then cluster.
	// +kubebuilder:validation:Required
	TemplateRef TemplateRef `json:"templateRef"`

	// WorkspaceRef names the Workspace this run mounts. Required when the
	// resolved template declares workspace.required=true and auto-provision
	// is disabled; otherwise the controller creates an ephemeral Workspace
	// (see ADR-0004).
	// +optional
	WorkspaceRef string `json:"workspaceRef,omitempty"`

	// Prompt is the inline prompt supplied to the agent. Exactly one of
	// Prompt or PromptFrom must be set (enforced by admission webhook).
	// Capped at 256 KiB — use PromptFrom for anything larger.
	//
	// Regardless of source, the controller materialises the prompt into
	// an owned Secret (<run>-prompt, SecretTypeOpaque, key "prompt.txt")
	// and mounts it at /paddock/prompt/prompt.txt. See ADR-0011.
	// +optional
	Prompt string `json:"prompt,omitempty"`

	// PromptFrom sources the prompt from a ConfigMap or Secret. The
	// resolved content is copied into an owned Secret (see Prompt).
	// +optional
	PromptFrom *PromptSource `json:"promptFrom,omitempty"`

	// Timeout overrides the template's default timeout.
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// Retries is the Job backoffLimit. Defaults to 0 — agent failures do
	// not re-run unless explicitly requested.
	// +kubebuilder:default=0
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=10
	// +optional
	Retries int32 `json:"retries,omitempty"`

	// Resources override the template's default resource requests/limits.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// ExtraEnv adds env vars to the agent container, merged after the
	// template's defaults and the PADDOCK_* standard variables.
	// +optional
	ExtraEnv []corev1.EnvVar `json:"extraEnv,omitempty"`

	// Model overrides the template's default model (exported as
	// PADDOCK_MODEL).
	// +optional
	Model string `json:"model,omitempty"`

	// TTLSecondsAfterFinished, when set, deletes the HarnessRun that many
	// seconds after its terminal phase is reached. No default — matches
	// the batch/v1 Job convention.
	// +optional
	// +kubebuilder:validation:Minimum=0
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`

	// Mode selects Batch (default — one-shot) or Interactive (long-lived
	// pod, multi-prompt). When Interactive, the resolved template's
	// spec.interactive.mode must be non-empty (admission webhook
	// enforces). Immutable after creation, like the rest of the spec.
	// +optional
	Mode HarnessRunMode `json:"mode,omitempty"`

	// InteractiveOverrides allows per-run overrides of the template's
	// interactive timing values. Each override is bounded by the
	// template's value (override may not exceed the template's bound).
	// Ignored unless Mode == Interactive.
	// +optional
	InteractiveOverrides *InteractiveOverrides `json:"interactiveOverrides,omitempty"`
}

type HarnessRunStatus struct {
	// ObservedGeneration is the spec generation last reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase summarises the run's lifecycle in a single token.
	// +optional
	Phase HarnessRunPhase `json:"phase,omitempty"`

	// Conditions report typed lifecycle signals. Known types:
	// TemplateResolved, WorkspaceBound, JobCreated, PodReady, Completed.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// JobName is the name of the backing batch/v1 Job, once created.
	// +optional
	JobName string `json:"jobName,omitempty"`

	// WorkspaceRef records which Workspace this run ended up bound to
	// (either user-supplied or ephemerally provisioned).
	// +optional
	WorkspaceRef string `json:"workspaceRef,omitempty"`

	// StartTime is when the run's Job entered Running.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is when the run reached a terminal phase.
	// +optional
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// RecentEvents is a ring buffer of the most recent PaddockEvents
	// emitted during the run (capped by controller flag, default 50).
	// Full event history lives on the Workspace PVC at
	// /workspace/.paddock/runs/<name>/events.jsonl.
	// +optional
	RecentEvents []PaddockEvent `json:"recentEvents,omitempty"`

	// Outputs are structured outputs reported by the harness on exit.
	// +optional
	Outputs *HarnessRunOutputs `json:"outputs,omitempty"`

	// Credentials reports, per requires.credentials[*].name, which
	// provider backed it and how the value was delivered. Populated by
	// the controller after a successful Issue call to the broker. Lets
	// the user verify at runtime that the actual delivery matches the
	// policy's declaration.
	// +listType=map
	// +listMapKey=name
	// +optional
	Credentials []CredentialStatus `json:"credentials,omitempty"`

	// NetworkPolicyEnforced records whether per-run NetworkPolicy
	// enforcement was active when this run was admitted. Immutable after
	// admission. The reconciler honours this for the run's lifetime, so a
	// flag flip on the controller-manager
	// (--networkpolicy-enforce=on → off) does not weaken running pods.
	// F-43 / Phase 2d.
	// +optional
	NetworkPolicyEnforced *bool `json:"networkPolicyEnforced,omitempty"`

	// IssuedLeases records every credential lease the broker has minted
	// for this run. Populated by the controller after each successful
	// Issue call; consumed by the controller's broker-leases finalizer
	// to revoke leases at run-delete time, and by the broker on startup
	// to reconstruct PATPool slot reservations across restarts. F-11, F-14.
	// +listType=map
	// +listMapKey=leaseID
	// +optional
	IssuedLeases []IssuedLease `json:"issuedLeases,omitempty"`

	// Interactive carries live-session counters and timestamps for
	// Interactive runs. Nil for Batch runs.
	// +optional
	Interactive *InteractiveStatus `json:"interactive,omitempty"`
}

type HarnessTemplate struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec HarnessTemplateSpec `json:"spec"`
	// +optional
	Status HarnessTemplateStatus `json:"status,omitzero"`
}

type HarnessTemplateDefaults struct {
	// Model is the default model identifier exported to the agent as
	// PADDOCK_MODEL. Overridable per-run.
	// +optional
	Model string `json:"model,omitempty"`

	// Timeout is the default active deadline for a run. Overridable per-run.
	// +kubebuilder:default="30m"
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// Resources are the default resource requests/limits for the agent
	// container. Overridable per-run.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// TerminationGracePeriodSeconds is the grace period for SIGTERM →
	// SIGKILL when a run is cancelled or times out.
	// +kubebuilder:default=60
	// +optional
	TerminationGracePeriodSeconds *int64 `json:"terminationGracePeriodSeconds,omitempty"`
}

type HarnessTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []HarnessTemplate `json:"items"`
}

type HarnessTemplateSpec struct {
	// BaseTemplateRef, when set on a namespaced HarnessTemplate, inherits
	// the referenced ClusterHarnessTemplate's pod shape. Locked fields
	// (Image, Command, Args, EventAdapter, Workspace) must be empty on
	// the inheriting template. Not valid on ClusterHarnessTemplate.
	// +optional
	BaseTemplateRef *LocalObjectReference `json:"baseTemplateRef,omitempty"`

	// Harness is a free-form label identifying the agent (codex, claude-code,
	// opencode, etc.). Used for observability and filtering only — the
	// controller has no per-harness logic.
	// +kubebuilder:validation:MaxLength=63
	// +optional
	Harness string `json:"harness,omitempty"`

	// Image is the agent container image. Required when BaseTemplateRef is
	// not set. Locked (must be empty) when inheriting.
	// +optional
	Image string `json:"image,omitempty"`

	// Command overrides the image's entrypoint. Env-var expansion via
	// $(VAR) is supported; the controller injects PADDOCK_PROMPT_PATH,
	// PADDOCK_RAW_PATH, PADDOCK_EVENTS_PATH, PADDOCK_RESULT_PATH,
	// PADDOCK_WORKSPACE, PADDOCK_RUN_NAME, and PADDOCK_MODEL. Required
	// when BaseTemplateRef is not set. Locked when inheriting.
	// +optional
	Command []string `json:"command,omitempty"`

	// Args are merged after Command. Locked when inheriting.
	// +optional
	Args []string `json:"args,omitempty"`

	// Defaults are per-template values that a HarnessRun may override.
	// Always overridable on namespaced templates.
	// +optional
	Defaults HarnessTemplateDefaults `json:"defaults,omitempty"`

	// EventAdapter is the per-harness sidecar image that converts raw
	// harness output to PaddockEvents. When unset, events.jsonl is not
	// produced and status.recentEvents carries only lifecycle events.
	// Locked when inheriting.
	// +optional
	EventAdapter *EventAdapterSpec `json:"eventAdapter,omitempty"`

	// Requires declares the capabilities the agent will exercise at
	// runtime: credentials it expects to be injected, and upstream
	// destinations it will connect to. A HarnessRun against this template
	// is admitted only if one or more BrokerPolicies in the run's
	// namespace grant a superset of Requires. See ADR-0014 and spec 0002
	// §8. Always overridable on namespaced templates.
	// +optional
	Requires RequireSpec `json:"requires,omitempty"`

	// Workspace declares the template's workspace requirement. Locked when
	// inheriting.
	// +optional
	Workspace WorkspaceRequirement `json:"workspace,omitempty"`

	// PodTemplateOverlay is strategically merged into the generated
	// PodSpec. Escape hatch for scheduling hints, tolerations, or extra
	// volumes. Always overridable on namespaced templates.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	PodTemplateOverlay *corev1.PodTemplateSpec `json:"podTemplateOverlay,omitempty"`

	// Interactive declares the template's interactive-mode support and
	// lifecycle defaults. When nil, runs against this template may not
	// set spec.mode: Interactive (admission rejects). Always overridable
	// on namespaced templates that inherit a ClusterHarnessTemplate.
	// +optional
	Interactive *InteractiveSpec `json:"interactive,omitempty"`
}

type HarnessTemplateStatus struct {
	// ObservedGeneration is the last generation of the spec that the
	// controller has reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest observations of the template's state.
	// Known types: Ready.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type HeaderSubstitution struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
	// ValuePrefix is prepended to the secret value (e.g. "Bearer ").
	// +optional
	ValuePrefix string `json:"valuePrefix,omitempty"`
}

type InContainerDelivery struct {
	// Accepted must be true.
	// +kubebuilder:validation:Required
	Accepted bool `json:"accepted"`

	// Reason explains why in-container delivery is necessary.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=20
	// +kubebuilder:validation:MaxLength=500
	Reason string `json:"reason"`
}

type InteractiveOverrides struct {
	// +optional
	IdleTimeout *metav1.Duration `json:"idleTimeout,omitempty"`
	// +optional
	DetachIdleTimeout *metav1.Duration `json:"detachIdleTimeout,omitempty"`
	// +optional
	DetachTimeout *metav1.Duration `json:"detachTimeout,omitempty"`
	// +optional
	MaxLifetime *metav1.Duration `json:"maxLifetime,omitempty"`
}

type InteractiveSpec struct {
	// Mode declares which interactive implementation strategy the
	// template's adapter image supports. The adapter image must declare
	// a matching value via paddock.dev/interactive-modes annotation
	// (validated at pod-spec generation, not at template admission).
	// +kubebuilder:validation:Enum="";per-prompt-process;persistent-process
	// +optional
	Mode string `json:"mode,omitempty"`

	// IdleTimeout is the maximum time since the last completed prompt
	// before the run terminates, while at least one client is attached.
	// Default 30m.
	// +optional
	// +kubebuilder:default="30m"
	IdleTimeout *metav1.Duration `json:"idleTimeout,omitempty"`

	// DetachIdleTimeout is the maximum idle time when no client is
	// attached. Default 15m.
	// +optional
	// +kubebuilder:default="15m"
	DetachIdleTimeout *metav1.Duration `json:"detachIdleTimeout,omitempty"`

	// DetachTimeout is the maximum time with zero attached clients
	// before termination. Default 5m.
	// +optional
	// +kubebuilder:default="5m"
	DetachTimeout *metav1.Duration `json:"detachTimeout,omitempty"`

	// MaxLifetime is the absolute hard cap on run lifetime regardless
	// of activity. Default 24h. Non-negotiable upper bound.
	// +optional
	// +kubebuilder:default="24h"
	MaxLifetime *metav1.Duration `json:"maxLifetime,omitempty"`

	// MaxRecentEvents overrides HarnessRun.status.recentEvents ring size
	// for runs against this template. Default 50; bounded [10, 500].
	// +optional
	// +kubebuilder:validation:Minimum=10
	// +kubebuilder:validation:Maximum=500
	MaxRecentEvents *int32 `json:"maxRecentEvents,omitempty"`
}

type InteractiveStatus struct {
	// PromptCount is the total number of prompt turns submitted since the
	// run started. Always serialized (no omitempty) — zero is a real
	// observable value for status consumers.
	PromptCount int32 `json:"promptCount"`

	// LastPromptAt is the time the most recent prompt was received.
	// +optional
	LastPromptAt *metav1.Time `json:"lastPromptAt,omitempty"`

	// AttachedSessions is the current number of client sessions attached
	// to the run's prompt stream or shell endpoint. Always serialized.
	AttachedSessions int32 `json:"attachedSessions"`

	// LastAttachedAt is the time the most recent session attached.
	// +optional
	LastAttachedAt *metav1.Time `json:"lastAttachedAt,omitempty"`

	// IdleSince is the time the run entered the Idle phase most recently.
	// Nil if the run has never been idle.
	// +optional
	IdleSince *metav1.Time `json:"idleSince,omitempty"`

	// CurrentTurnSeq is the monotonically increasing sequence number of
	// the prompt turn currently in progress. Nil when no turn is active.
	// +optional
	CurrentTurnSeq *int32 `json:"currentTurnSeq,omitempty"`

	// RenewalCount is the total number of credential renewals completed
	// for this run. Always serialized.
	RenewalCount int32 `json:"renewalCount"`

	// LastRenewalAt is the time of the most recent credential renewal.
	// +optional
	LastRenewalAt *metav1.Time `json:"lastRenewalAt,omitempty"`
}

type InterceptionMode string

type InterceptionSpec struct {
	// +optional
	Transparent *TransparentInterception `json:"transparent,omitempty"`
	// +optional
	CooperativeAccepted *CooperativeAcceptedInterception `json:"cooperativeAccepted,omitempty"`
}

type IssuedLease struct {
	// Provider is the provider kind (matches BrokerPolicy
	// grant.provider.kind). The broker dispatches /v1/revoke to the
	// named provider's Revoke method.
	// +kubebuilder:validation:Required
	Provider string `json:"provider"`

	// LeaseID is the provider-supplied identifier returned from
	// IssueResult.LeaseID. Opaque to the controller; passed back unchanged.
	// +kubebuilder:validation:Required
	LeaseID string `json:"leaseID"`

	// CredentialName is the requirement name from the template's
	// spec.requires.credentials list. Used for audit correlation only —
	// never load-bearing for revocation.
	// +kubebuilder:validation:Required
	CredentialName string `json:"credentialName"`

	// ExpiresAt mirrors IssueResult.ExpiresAt. Reconstruction skips
	// entries with ExpiresAt < now (no point rebuilding state for an
	// already-dead lease). Optional: nil means "no expiry".
	// +optional
	ExpiresAt *metav1.Time `json:"expiresAt,omitempty"`

	// PoolRef carries PATPool-specific reconstruction metadata.
	// Populated only when Provider == "PATPool"; nil otherwise.
	// Anonymous tagged-union pattern; future providers add their own
	// optional ref alongside without breaking pre-1.0 in-place evolution.
	// +optional
	PoolRef *PoolLeaseRef `json:"poolRef,omitempty"`
}

type LocalObjectReference struct {
	// Name of the referenced object.
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

type PaddockEvent struct {
	// SchemaVersion governs the semantics of this event. Bump when the
	// semantics of existing fields change; add optional fields without
	// bumping. See ADR-0001.
	// +kubebuilder:default="1"
	SchemaVersion string `json:"schemaVersion"`

	// Timestamp is when the event was produced.
	Timestamp metav1.Time `json:"ts"`

	// Type identifies the event category. Known types: ToolUse, Message,
	// FileEdit, Commit, Elicitation, Error, Result. Adapters may emit
	// custom types for harness-specific events; consumers should tolerate
	// unknown types.
	// +kubebuilder:validation:Required
	Type string `json:"type"`

	// Summary is a one-line human-readable description of the event.
	// Suitable for display in kubectl output without interpreting the
	// type-specific fields.
	// +optional
	Summary string `json:"summary,omitempty"`

	// Fields carries event-specific details as string-valued key/value
	// pairs. Its schema is determined by Type and SchemaVersion; consumers
	// should tolerate unknown keys.
	// +optional
	Fields map[string]string `json:"fields,omitempty"`
}

type PoolLeaseRef struct {
	// +kubebuilder:validation:Required
	SecretRef SecretKeyReference `json:"secretRef"`
	// +kubebuilder:validation:Required
	SlotIndex int `json:"slotIndex"`
}

type PromptSource struct {
	// +optional
	ConfigMapKeyRef *corev1.ConfigMapKeySelector `json:"configMapKeyRef,omitempty"`
	// +optional
	SecretKeyRef *corev1.SecretKeySelector `json:"secretKeyRef,omitempty"`
}

type ProviderConfig struct {
	// Kind names the provider implementation.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=UserSuppliedSecret;AnthropicAPI;GitHubApp;PATPool
	Kind string `json:"kind"`

	// SecretRef identifies the Secret backing this provider.
	// +optional
	SecretRef *SecretKeyReference `json:"secretRef,omitempty"`

	// AppID is the GitHub App numeric ID (GitHubApp only). Must be a
	// positive integer of at most 20 digits when set; required for
	// GitHubApp providers (admission rejects empty for that kind).
	// +optional
	// +kubebuilder:validation:Pattern=`^[1-9][0-9]{0,19}$`
	AppID string `json:"appId,omitempty"`

	// InstallationID is the GitHub App installation ID (GitHubApp only).
	// Must be a positive integer of at most 20 digits when set;
	// required for GitHubApp providers.
	// +optional
	// +kubebuilder:validation:Pattern=`^[1-9][0-9]{0,19}$`
	InstallationID string `json:"installationId,omitempty"`

	// RotationSeconds optionally overrides the provider's default TTL.
	// +optional
	// +kubebuilder:validation:Minimum=60
	RotationSeconds *int32 `json:"rotationSeconds,omitempty"`

	// Hosts optionally overrides the destination host list used for
	// proxy substitution, for built-in providers (AnthropicAPI,
	// GitHubApp, PATPool). For UserSuppliedSecret with proxyInjected
	// delivery, hosts live under deliveryMode.proxyInjected instead and
	// this field must not be set.
	// +optional
	Hosts []string `json:"hosts,omitempty"`

	// DeliveryMode is required for UserSuppliedSecret and forbidden for
	// all other kinds.
	// +optional
	DeliveryMode *DeliveryMode `json:"deliveryMode,omitempty"`
}

type ProxyInjectedDelivery struct {
	// Hosts are the destination hostnames the proxy will substitute on.
	// A leading "*." permits any subdomain. At least one entry required.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:Required
	Hosts []string `json:"hosts"`

	// Exactly one of Header / QueryParam / BasicAuth must be set.
	// +optional
	Header *HeaderSubstitution `json:"header,omitempty"`
	// +optional
	QueryParam *QueryParamSubstitution `json:"queryParam,omitempty"`
	// +optional
	BasicAuth *BasicAuthSubstitution `json:"basicAuth,omitempty"`
}

type QueryParamSubstitution struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

type RequireSpec struct {
	// Credentials are the credentials the agent expects to be injected
	// as env vars. Name is the env-var key inside the agent container.
	// Templates never name a provider directly — that is the
	// operator's choice via BrokerPolicy.
	// +optional
	Credentials []CredentialRequirement `json:"credentials,omitempty"`

	// Egress lists the upstream destinations the agent will open
	// connections to. A leading "*." on Host permits any subdomain.
	// +optional
	Egress []EgressRequirement `json:"egress,omitempty"`
}

type SecretKeyReference struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
	// +kubebuilder:validation:Required
	Key string `json:"key"`
}

type ShellCapability struct {
	// Target is which container the broker exec's into.
	// +kubebuilder:validation:Enum=agent;adapter
	// +kubebuilder:default=agent
	// +optional
	Target string `json:"target,omitempty"`

	// Command overrides the default shell-discovery (try /bin/bash, fall
	// back to /bin/sh). When set, the broker forwards Command verbatim
	// to the container's exec; missing binaries surface as a failed
	// shell session (the session opens, exec returns immediately with
	// the kubelet's error) rather than as an admission rejection.
	// +optional
	Command []string `json:"command,omitempty"`

	// AllowedPhases restricts which run phases can host a shell session.
	// Default (when empty): all phases that have a pod (Running, Idle,
	// Succeeded, Failed, Cancelled).
	// +optional
	AllowedPhases []HarnessRunPhase `json:"allowedPhases,omitempty"`

	// RecordTranscript captures the WebSocket bytestream to
	// <workspace>/.paddock/shell/<session-id>.log when true. Default
	// false — recording doubles disk I/O and stores potentially-sensitive
	// output.
	// +optional
	RecordTranscript bool `json:"recordTranscript,omitempty"`
}

type TemplateRef struct {
	// Name of the template.
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Kind restricts resolution. When empty, a namespaced HarnessTemplate
	// with this name is preferred over a cluster one.
	// +kubebuilder:validation:Enum=HarnessTemplate;ClusterHarnessTemplate
	// +optional
	Kind string `json:"kind,omitempty"`
}

type TransparentInterception struct{}

type Workspace struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec WorkspaceSpec `json:"spec"`
	// +optional
	Status WorkspaceStatus `json:"status,omitzero"`
}

type WorkspaceGitSource struct {
	// URL is the clone URL (https or ssh).
	// +kubebuilder:validation:Required
	URL string `json:"url"`

	// Path is the relative directory under the workspace mount where the
	// repo is cloned. Empty means the workspace mount root (only allowed
	// when this is the only repo). When multiple repos are declared,
	// every Path must be set and unique.
	// +optional
	Path string `json:"path,omitempty"`

	// Branch to clone. Defaults to the remote's HEAD.
	// +optional
	Branch string `json:"branch,omitempty"`

	// Depth is the shallow-clone depth. Zero or unset means a full clone.
	// +kubebuilder:validation:Minimum=0
	// +optional
	Depth int32 `json:"depth,omitempty"`

	// BrokerCredentialRef, when set, routes git credentials through
	// the broker (ADR-0015) instead of a static Secret. The referenced
	// Secret must exist before the seed Job runs — typically the
	// <run>-broker-creds Secret the HarnessRun reconciler materialises
	// from broker.Issue responses. Data[Key] must be a Paddock-issued
	// bearer (pdk-github-… or pdk-patpool-…). The seed Pod gains a
	// proxy sidecar so MITM substitution swaps the bearer for the real
	// upstream token at git-HTTPS time — upstream git forges never
	// see the Paddock-issued value.
	//
	// Mutually exclusive with CredentialsSecretRef. Only valid on
	// https URLs (ssh URLs use key-based auth via CredentialsSecretRef).
	// +optional
	BrokerCredentialRef *BrokerCredentialReference `json:"brokerCredentialRef,omitempty"`

	// CredentialsSecretRef, when set, supplies git credentials to the
	// seed Job for this repo. For https URLs the Secret must carry
	// `username` and `password` keys (a personal access token goes in
	// `password`). For ssh URLs it must carry `ssh-privatekey`. Mounted
	// read-only into the seed Job only. See ADR-0006.
	// +optional
	CredentialsSecretRef *LocalObjectReference `json:"credentialsSecretRef,omitempty"`
}

type WorkspaceList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []Workspace `json:"items"`
}

type WorkspacePhase string

type WorkspaceRequirement struct {
	// Required indicates the template must run against a Workspace. When
	// true and a HarnessRun omits workspaceRef, the controller provisions
	// an ephemeral Workspace (see ADR-0004).
	// +kubebuilder:default=true
	// +optional
	Required bool `json:"required,omitempty"`

	// MountPath is where the workspace PVC is mounted in the agent
	// container. Defaults to /workspace.
	// +kubebuilder:default="/workspace"
	// +optional
	MountPath string `json:"mountPath,omitempty"`
}

type WorkspaceSeed struct {
	// Repos clones one or more git repositories into the workspace. With
	// a single entry an empty Path clones directly to the workspace
	// mount root; with multiple entries every Path must be set to a
	// distinct relative directory. See ADR-0006 for credential handling.
	// +optional
	Repos []WorkspaceGitSource `json:"repos,omitempty"`
}

type WorkspaceSpec struct {
	// Storage configures the backing PVC.
	// +kubebuilder:validation:Required
	Storage WorkspaceStorage `json:"storage"`

	// Seed describes how the workspace is initialised. When set, the
	// Workspace controller spawns a seed Job that populates the PVC
	// before any run may start.
	// +optional
	Seed *WorkspaceSeed `json:"seed,omitempty"`

	// Ephemeral marks a workspace auto-provisioned by a HarnessRun when
	// no workspaceRef was supplied. Ephemeral workspaces carry an
	// ownerReference to their HarnessRun and cascade-delete with it.
	// See ADR-0004.
	// +optional
	Ephemeral bool `json:"ephemeral,omitempty"`
}

type WorkspaceStatus struct {
	// ObservedGeneration is the spec generation last reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase summarises the workspace's lifecycle.
	// +optional
	Phase WorkspacePhase `json:"phase,omitempty"`

	// PVCName is the backing PersistentVolumeClaim, once created.
	// +optional
	PVCName string `json:"pvcName,omitempty"`

	// SeedJobName is the backing seed Job, while it exists.
	// +optional
	SeedJobName string `json:"seedJobName,omitempty"`

	// ActiveRunRef names the HarnessRun currently using the workspace.
	// Empty when the workspace is idle. Used to serialise concurrent
	// runs against a ReadWriteOnce PVC without reliance on PVC attach
	// errors.
	// +optional
	ActiveRunRef string `json:"activeRunRef,omitempty"`

	// TotalRuns is a monotonic count of HarnessRuns that have bound to
	// this workspace. Informational only.
	// +optional
	TotalRuns int32 `json:"totalRuns,omitempty"`

	// LastCountedRun is the name of the most recently counted
	// HarnessRun for TotalRuns. Used by the binding logic to keep the
	// TotalRuns increment idempotent across cache-staleness re-
	// reconciles: a re-bind of the same run name is recognised here
	// and skips the increment that the (ActiveRunRef==run.Name) guard
	// can't catch when the controller-runtime informer cache hasn't
	// yet propagated the previous binding update. See bindWorkspace.
	// +optional
	LastCountedRun string `json:"lastCountedRun,omitempty"`

	// LastActivity is the time of the most recent run's last event. Used
	// by future archive-on-idle logic.
	// +optional
	LastActivity *metav1.Time `json:"lastActivity,omitempty"`

	// Conditions report typed lifecycle signals. Known types: PVCBound,
	// Seeded, Ready.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type WorkspaceStorage struct {
	// Size is the requested storage capacity (e.g. "20Gi").
	// +kubebuilder:validation:Required
	Size resource.Quantity `json:"size"`

	// StorageClass names the StorageClass for the PVC. When empty, the
	// cluster's default StorageClass is used.
	// +optional
	StorageClass string `json:"storageClass,omitempty"`

	// AccessMode is the PVC access mode. Defaults to ReadWriteOnce.
	// ReadWriteMany is supported but requires a networked filesystem
	// StorageClass and is not exercised on Kind.
	// +kubebuilder:default=ReadWriteOnce
	// +kubebuilder:validation:Enum=ReadWriteOnce;ReadWriteMany
	// +optional
	AccessMode corev1.PersistentVolumeAccessMode `json:"accessMode,omitempty"`
}