v1alpha1

type CachePolicy struct {
	// Enabled toggles output caching when true.
	// Defaults to true when CachePolicy is set.
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// Key selects the cache key. When empty, the resolved step inputs are hashed.
	// Supports template expressions (e.g. "{{ inputs.userId }}").
	// +optional
	Key *string `json:"key,omitempty"`

	// Salt is appended to cache keys to support explicit cache invalidation.
	// Change this value to logically purge previous cache entries.
	// +optional
	Salt *string `json:"salt,omitempty"`

	// Mode controls cache read/write behavior.
	// - read: read-only (do not populate cache)
	// - write: write-only (skip lookups)
	// - readWrite: lookup and populate
	// +kubebuilder:validation:Enum=read;write;readWrite
	// +optional
	Mode *string `json:"mode,omitempty"`

	// TTLSeconds controls how long cache entries remain valid.
	// Zero or negative means no expiry.
	// +optional
	TTLSeconds *int32 `json:"ttlSeconds,omitempty"`
}

type ConcurrencyMode string

type ConcurrencyScope string

type Engram struct {
	metav1.TypeMeta `json:",inline"`
	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of Engram
	// +required
	Spec EngramSpec `json:"spec"`

	// status defines the observed state of Engram
	// +optional
	Status EngramStatus `json:"status,omitzero"`
}

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

type EngramSpec struct {
	// Version identifies this Engram instance for pinning by Story steps.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string `json:"version,omitempty"`

	// TemplateRef selects the EngramTemplate that provides defaults, validation,
	// and base artifacts for this instance.
	// +kubebuilder:validation:Required
	TemplateRef refs.EngramTemplateReference `json:"templateRef"`

	// Mode optionally overrides the workload controller selected by the template.
	// Supported values are job, deployment, and statefulset.
	// +kubebuilder:validation:Enum=job;deployment;statefulset
	Mode enums.WorkloadMode `json:"mode,omitempty"`

	// With carries template-specific configuration. The template schema determines
	// the structure and validation rules applied to this payload.
	// +kubebuilder:pruning:PreserveUnknownFields
	With *runtime.RawExtension `json:"with,omitempty"`

	// Secrets maps named secret inputs defined by the template to concrete Secret
	// resources in the tenant namespace.
	Secrets map[string]string `json:"secrets,omitempty"`

	// ExecutionPolicy captures the fully-resolved execution policy after hierarchical
	// merge. Template defaults feed into this value.
	// +optional
	ExecutionPolicy *ExecutionPolicy `json:"executionPolicy,omitempty"`

	// Overrides allows callers to apply instance-specific execution adjustments.
	Overrides *ExecutionOverrides `json:"overrides,omitempty"`

	// Transport carries transport-level overrides such as TLS configuration.
	// +optional
	Transport *EngramTransportSpec `json:"transport,omitempty"`
}

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

	// Conditions conveys per-condition status such as Ready.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Replicas and ReadyReplicas surface pod readiness information for controllers
	// that expose it (Deployments/StatefulSets). Jobs leave these fields at zero.
	Replicas      int32       `json:"replicas,omitempty"`
	ReadyReplicas int32       `json:"readyReplicas,omitempty"`
	Phase         enums.Phase `json:"phase,omitempty"`

	// ValidationStatus reflects whether the engram spec passed validation.
	ValidationStatus enums.ValidationStatus `json:"validationStatus,omitempty"`
	// ValidationErrors contains messages describing validation failures.
	ValidationErrors []string `json:"validationErrors,omitempty"`

	// UsageCount reports how many Stories reference this Engram.
	// +optional
	UsageCount int32 `json:"usageCount"`

	// Triggers reports how many StepRuns currently reference this Engram.
	// Useful for understanding runtime fan-out and utilisation.
	// +optional
	Triggers int64 `json:"triggers"`

	// LastExecutionTime captures the completion timestamp for the most recent run.
	LastExecutionTime *metav1.Time `json:"lastExecutionTime,omitempty"`
	// TotalExecutions counts the number of completed runs for job workloads.
	TotalExecutions int32 `json:"totalExecutions,omitempty"`
	// FailedExecutions counts runs that ended in a failure state.
	FailedExecutions int32 `json:"failedExecutions,omitempty"`
}

type EngramTLSSpec struct {
	// SecretRef references a Secret containing tls.key/tls.crt data.
	// +optional
	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty"`

	// UseDefaultTLS requests the operator's default TLS secret when true.
	// Defaults to true when SecretRef is unset.
	// +optional
	UseDefaultTLS *bool `json:"useDefaultTLS,omitempty"`
}

type EngramTransportSpec struct {
	// TLS configures TLS secrets for hybrid transports.
	// +optional
	TLS *EngramTLSSpec `json:"tls,omitempty"`
}

type ExecutionOverrides struct {
	// Timeout overrides the resolved execution timeout (Go duration string).
	Timeout *string `json:"timeout,omitempty"`

	// Retry overrides the resolved retry policy.
	Retry *RetryPolicy `json:"retry,omitempty"`

	// Debug enables verbose, component-level logging when true.
	// +optional
	Debug *bool `json:"debug,omitempty"`

	// Security overrides pod-level security settings.
	Security *WorkloadSecurity `json:"security,omitempty"`

	// Placement overrides pod scheduling constraints (node selectors, tolerations, affinity).
	// +optional
	Placement *PlacementPolicy `json:"placement,omitempty"`

	// ImagePullPolicy overrides the container pull policy.
	ImagePullPolicy *string `json:"imagePullPolicy,omitempty"`

	// MaxInlineSize overrides the inline payload threshold in bytes. Set to 0 to always offload.
	// +optional
	MaxInlineSize *int `json:"maxInlineSize,omitempty"`

	// ServiceAccountName overrides the ServiceAccount used by workload pods.
	// Must be a valid DNS subdomain name (RFC 1123).
	// +optional
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
	ServiceAccountName *string `json:"serviceAccountName,omitempty"`

	// AutomountServiceAccountToken toggles automountServiceAccountToken on the pod spec.
	// When omitted, the controller-resolved default is preserved.
	// +optional
	AutomountServiceAccountToken *bool `json:"automountServiceAccountToken,omitempty"`

	// Probes allows disabling template-defined probes; probe definitions themselves
	// remain owned by the template.
	// +optional
	Probes *ProbeOverrides `json:"probes,omitempty"`

	// Storage overrides the resolved storage policy (e.g., enable S3 or file providers).
	// +optional
	Storage *StoragePolicy `json:"storage,omitempty"`

	// Cache overrides output caching behavior.
	// +optional
	Cache *CachePolicy `json:"cache,omitempty"`

	// RBAC adds extra Role/ClusterRole bindings to the generated ServiceAccount.
	// +optional
	RBAC *RBACRuleOverrides `json:"rbac,omitempty"`
}

type ExecutionPolicy struct {
	// Resources enumerates the concrete pod resource assignments.
	Resources *ResourcePolicy `json:"resources,omitempty"`

	// Security enumerates the concrete pod security settings.
	Security *SecurityPolicy `json:"security,omitempty"`

	// Placement enumerates the pod scheduling constraints.
	// +optional
	Placement *PlacementPolicy `json:"placement,omitempty"`

	// Job enumerates the job controller settings.
	Job *JobPolicy `json:"job,omitempty"`

	// Retry enumerates the retry configuration.
	Retry *RetryPolicy `json:"retry,omitempty"`

	// Timeout is the execution deadline expressed as a Go duration string.
	Timeout *string `json:"timeout,omitempty"`

	// MaxRecursionDepth overrides the maximum nesting depth used when hydrating
	// or dehydrating structured inputs and outputs for this Story. Increase this
	// when the Story intentionally passes deeply nested documents, such as full
	// Kubernetes objects, through shared storage.
	// +kubebuilder:validation:Minimum=1
	// +optional
	MaxRecursionDepth *int `json:"maxRecursionDepth,omitempty"`

	// ServiceAccountName identifies the ServiceAccount used by derived workloads.
	// +optional
	ServiceAccountName *string `json:"serviceAccountName,omitempty"`

	// Storage enumerates the resolved storage policy applied to the workload.
	// +optional
	Storage *StoragePolicy `json:"storage,omitempty"`

	// Cache enumerates the resolved output caching policy applied to the workload.
	// +optional
	Cache *CachePolicy `json:"cache,omitempty"`

	// Realtime enumerates realtime-specific execution settings (e.g., TTL for lingering pods).
	// +optional
	Realtime *RealtimePolicy `json:"realtime,omitempty"`
}

type FileStorageProvider struct {
	// Path is the directory inside the container where the storage backend should write files.
	// Defaults to "/var/run/bubu/storage" when omitted.
	Path string `json:"path,omitempty"`

	// VolumeClaimName references an existing PersistentVolumeClaim mounted to the workload.
	// Mutually exclusive with EmptyDir.
	// +optional
	VolumeClaimName string `json:"volumeClaimName,omitempty"`

	// EmptyDir defines an ephemeral volume to provision for file storage. When both
	// EmptyDir and VolumeClaimName are omitted, an EmptyDir{} volume is used by default.
	// +optional
	EmptyDir *corev1.EmptyDirVolumeSource `json:"emptyDir,omitempty"`
}

type Impulse struct {
	metav1.TypeMeta `json:",inline"`
	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of Impulse
	// +required
	Spec ImpulseSpec `json:"spec"`

	// status defines the observed state of Impulse
	// +optional
	Status ImpulseStatus `json:"status,omitzero"`
}

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

type ImpulseSpec struct {
	// Version identifies this Impulse instance for pinning by references.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string `json:"version,omitempty"`

	// TemplateRef selects the ImpulseTemplate that implements the trigger mechanics.
	// +kubebuilder:validation:Required
	TemplateRef refs.ImpulseTemplateReference `json:"templateRef"`

	// StoryRef identifies the Story executed when the trigger fires.
	// +kubebuilder:validation:Required
	StoryRef refs.StoryReference `json:"storyRef"`

	// With carries template-specific configuration and is validated by the template.
	// +kubebuilder:pruning:PreserveUnknownFields
	With *runtime.RawExtension `json:"with,omitempty"`

	// Secrets maps template-defined secret inputs to concrete namespace Secrets.
	Secrets map[string]string `json:"secrets,omitempty"`

	// Mapping describes how an incoming event is converted into Story inputs.
	// +kubebuilder:pruning:PreserveUnknownFields
	Mapping *runtime.RawExtension `json:"mapping,omitempty"`

	// DeliveryPolicy controls trigger deduplication and retry behavior.
	// Overrides delivery defaults from the referenced ImpulseTemplate.
	// +optional
	DeliveryPolicy *TriggerDeliveryPolicy `json:"deliveryPolicy,omitempty"`

	// Throttle limits trigger submission rate and concurrency for this Impulse.
	// +optional
	Throttle *TriggerThrottlePolicy `json:"throttle,omitempty"`

	// Workload controls the backing workload for the impulse (deployment or statefulset).
	Workload *WorkloadSpec `json:"workload,omitempty"`

	// Service controls instance-level exposure of the impulse via a Service.
	// Ports and health come from the template; this sets type/labels/annotations.
	// If omitted, defaults to ClusterIP with template-defined ports.
	Service *ServiceExposure `json:"service,omitempty"`

	// Execution provides instance-level execution overrides.
	Execution *ExecutionOverrides `json:"execution,omitempty"`
}

type ImpulseStatus struct {
	// observedGeneration is the most recent generation observed for this Impulse. It corresponds to the
	// Impulse's generation, which is updated on mutation by the API Server.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions is the standard Kubernetes condition set (Ready, etc.).
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Replicas and ReadyReplicas surface readiness information reported by the backing workload.
	// +optional
	Replicas int32 `json:"replicas,omitempty"`
	// +optional
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
	// +optional
	Phase enums.Phase `json:"phase,omitempty"`

	// TriggersReceived counts all events seen by the impulse.
	// +optional
	TriggersReceived int64 `json:"triggersReceived"`
	// StoriesLaunched counts StoryRuns successfully started from events.
	// +optional
	StoriesLaunched int64 `json:"storiesLaunched"`
	// FailedTriggers counts events that failed validation or launch.
	// +optional
	FailedTriggers int64 `json:"failedTriggers"`
	// ThrottledTriggers counts events delayed by trigger throttling.
	// +optional
	ThrottledTriggers int64 `json:"throttledTriggers"`
	// LastTrigger records the timestamp of the most recent event.
	// +optional
	LastTrigger *metav1.Time `json:"lastTrigger,omitempty"`
	// LastThrottled records the timestamp of the most recent throttled trigger.
	// +optional
	LastThrottled *metav1.Time `json:"lastThrottled,omitempty"`
	// LastSuccess records the timestamp of the most recent successful Story launch.
	// +optional
	LastSuccess *metav1.Time `json:"lastSuccess,omitempty"`
}

type JobPolicy struct {
	// Backoff limit for jobs
	BackoffLimit *int32 `json:"backoffLimit,omitempty"`

	// TTL for cleaning up child resources (StepRuns, Pods) after StoryRun finishes.
	// After this period expires, child resources are deleted to free up cluster resources.
	// The parent StoryRun record is preserved for observability.
	// Default: 3600 (1 hour)
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`

	// Retention period for the StoryRun record itself after it finishes.
	// After this period expires, the StoryRun is deleted to prevent etcd overload.
	// Set to 0 to keep StoryRuns forever (requires manual cleanup).
	// Set to -1 to delete StoryRun immediately after child cleanup (not recommended).
	// Recommended: 86400 (24 hours) to 604800 (7 days) for production systems.
	// Default: 86400 (24 hours)
	// +optional
	StoryRunRetentionSeconds *int32 `json:"storyRunRetentionSeconds,omitempty"`

	// Restart policy
	RestartPolicy *string `json:"restartPolicy,omitempty"`
}

type JobWorkloadConfig struct {
	// Parallelism mirrors spec.parallelism.
	Parallelism *int32 `json:"parallelism,omitempty"`

	// Completions mirrors spec.completions.
	Completions *int32 `json:"completions,omitempty"`

	// BackoffLimit mirrors spec.backoffLimit.
	BackoffLimit *int32 `json:"backoffLimit,omitempty"`

	// ActiveDeadlineSeconds mirrors spec.activeDeadlineSeconds.
	ActiveDeadlineSeconds *int64 `json:"activeDeadlineSeconds,omitempty"`

	// TTLSecondsAfterFinished mirrors spec.ttlSecondsAfterFinished.
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`
}

type PlacementPolicy struct {
	// NodeSelector constrains scheduling to nodes with matching labels.
	// +optional
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`

	// Tolerations allow scheduling onto tainted nodes.
	// +optional
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`

	// Affinity expresses node and pod affinity rules.
	// +optional
	Affinity *corev1.Affinity `json:"affinity,omitempty"`
}

type PostExecutionCheck struct {
	// Condition is a Go template expression that must evaluate to "true" for the step
	// to be considered truly successful. Has access to steps.<name>.output.* context.
	// Example: '{{ ne (index .steps "send-notification").output.deliveryStatus "failed" }}'
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Condition string `json:"condition"`

	// FailureMessage is a human-readable message used when the condition evaluates to false.
	// +optional
	FailureMessage string `json:"failureMessage,omitempty"`
}

type ProbeOverrides struct {
	// DisableLiveness disables the liveness probe when true.
	// +optional
	DisableLiveness bool `json:"disableLiveness,omitempty"`

	// DisableReadiness disables the readiness probe when true.
	// +optional
	DisableReadiness bool `json:"disableReadiness,omitempty"`

	// DisableStartup disables the startup probe when true.
	// +optional
	DisableStartup bool `json:"disableStartup,omitempty"`
}

type RBACRuleOverrides struct {
	// Rules lists additional Role rules appended to the default policy.
	// +optional
	Rules []rbacv1.PolicyRule `json:"rules,omitempty"`
}

type RealtimeConcurrency struct {
	// Mode controls cycle behavior: serial queues, cancelPrevious cancels old
	// cycles, parallel allows all (default).
	// +kubebuilder:default=parallel
	Mode ConcurrencyMode `json:"mode,omitempty"`

	// Scope determines the cycle tracking granularity.
	// +kubebuilder:default=storyrun
	Scope ConcurrencyScope `json:"scope,omitempty"`
}

type RealtimePolicy struct {
	// TTLSecondsAfterFinished controls how long realtime resources (Deployments, Services) remain after finish.
	// Set to 0 to delete immediately, negative to keep indefinitely, or positive seconds to keep temporarily.
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`
}

type ResourceLimits struct {
	CPU              *string `json:"cpu,omitempty"`              // e.g., "1000m", "2"
	Memory           *string `json:"memory,omitempty"`           // e.g., "1Gi", "4Gi"
	EphemeralStorage *string `json:"ephemeralStorage,omitempty"` // e.g., "5Gi"
}

type ResourcePolicy struct {
	// CPU request
	CPURequest *string `json:"cpuRequest,omitempty"`

	// Memory request
	MemoryRequest *string `json:"memoryRequest,omitempty"`

	// CPU limit
	CPULimit *string `json:"cpuLimit,omitempty"`

	// Memory limit
	MemoryLimit *string `json:"memoryLimit,omitempty"`
}

type ResourceRequests struct {
	CPU              *string `json:"cpu,omitempty"`              // e.g., "100m", "0.5"
	Memory           *string `json:"memory,omitempty"`           // e.g., "128Mi", "1Gi"
	EphemeralStorage *string `json:"ephemeralStorage,omitempty"` // e.g., "1Gi"
}

type RetryPolicy struct {
	// Maximum number of retry attempts
	// +kubebuilder:default=3
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=10
	MaxRetries *int32 `json:"maxRetries,omitempty"`

	// Base delay between retries
	// Examples: "1s", "5s", "30s"
	// +kubebuilder:default="1s"
	Delay *string `json:"delay,omitempty"`

	// MaxDelay caps the computed retry delay after backoff is applied.
	// Examples: "30s", "5m"
	// +optional
	MaxDelay *string `json:"maxDelay,omitempty"`

	// Jitter applies a fractional jitter to the computed delay.
	// 0 disables jitter; 50 allows up to +50% delay.
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	// +optional
	Jitter *int32 `json:"jitter,omitempty"`

	// Backoff strategy for retry delays
	// - exponential: 1s, 2s, 4s, 8s... (doubles each time)
	// - linear: 1s, 2s, 3s, 4s... (increases by delay each time)
	// - constant: 1s, 1s, 1s, 1s... (same delay each time)
	Backoff *enums.BackoffStrategy `json:"backoff,omitempty"`
}

type RollingUpdateConfig struct {
	// Maximum number of pods that can be unavailable during update
	// Can be absolute number (ex: 5) or percentage (ex: 25%)
	MaxUnavailable *string `json:"maxUnavailable,omitempty"`

	// Maximum number of pods that can be created above desired replicas during update
	// Only for Deployment (not StatefulSet)
	MaxSurge *string `json:"maxSurge,omitempty"`
}

type S3Authentication struct {
	// ServiceAccountAnnotations allows specifying annotations to be added to the
	// auto-generated ServiceAccount. This is the recommended approach for
	// IAM-based authentication on cloud providers (e.g., IRSA on EKS).
	// The key-value pairs will be added to the ServiceAccount's metadata.annotations.
	// +optional
	ServiceAccountAnnotations map[string]string `json:"serviceAccountAnnotations,omitempty"`

	// SecretRef references a Kubernetes Secret that contains the credentials.
	// The secret must contain keys 'accessKeyID' and 'secretAccessKey'.
	// +optional
	SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty"`
}

type S3StorageProvider struct {
	// Bucket is the name of the S3 bucket.
	// +kubebuilder:validation:Required
	Bucket string `json:"bucket"`

	// Region is the AWS region of the bucket.
	// +optional
	Region string `json:"region,omitempty"`

	// Endpoint is the S3 endpoint URL. Useful for S3-compatible stores like MinIO.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// Authentication configures how the workload authenticates with S3.
	// +kubebuilder:validation:Required
	Authentication S3Authentication `json:"authentication"`

	// UsePathStyle forces path-style addressing for S3-compatible providers that require it.
	// +optional
	UsePathStyle bool `json:"usePathStyle,omitempty"`
}

type SecurityPolicy struct {
	// Whether to run as non-root user
	RunAsNonRoot *bool `json:"runAsNonRoot,omitempty"`

	// Whether to allow privilege escalation
	AllowPrivilegeEscalation *bool `json:"allowPrivilegeEscalation,omitempty"`

	// Read-only root filesystem
	ReadOnlyRootFilesystem *bool `json:"readOnlyRootFilesystem,omitempty"`

	// User ID to run as
	RunAsUser *int64 `json:"runAsUser,omitempty"`
}

type ServiceExposure struct {
	// Type is the Service type (ClusterIP, NodePort, LoadBalancer).
	Type string `json:"type,omitempty"`
	// Labels are merged into the Service metadata.
	Labels map[string]string `json:"labels,omitempty"`
	// Annotations are merged into the Service metadata.
	Annotations map[string]string `json:"annotations,omitempty"`
}

type StatefulSetWorkloadConfig struct {
	// ServiceName is the headless Service used for stable network identities.
	ServiceName string `json:"serviceName"`

	// PodManagementPolicy mirrors spec.podManagementPolicy.
	PodManagementPolicy *string `json:"podManagementPolicy,omitempty"`
}

type Step struct {
	// Name uniquely identifies the step within the Story. Outputs and dependencies
	// are referenced by this name.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	Name string `json:"name"`

	// ID optionally provides a stable identifier distinct from Name. It is useful
	// for programmatic processing of the workflow graph.
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	// +optional
	ID string `json:"id,omitempty"`

	// Needs lists predecessor step names that must complete before this step starts.
	// +optional
	Needs []string `json:"needs,omitempty"`

	// Type selects a built-in primitive.
	//
	// Supported step types:
	//   - condition, parallel, sleep, stop, executeStory
	//   - wait, gate (batch-only)
	//
	// When Type is omitted and Ref is set, the step executes an Engram.
	// +optional
	Type enums.StepType `json:"type,omitempty"`

	// If gates execution on a template expression that evaluates to true.
	// +optional
	If *string `json:"if,omitempty"`

	// AllowFailure permits the step to fail without failing the StoryRun.
	// When true, dependent steps may continue and the StoryRun can still succeed.
	// +optional
	AllowFailure *bool `json:"allowFailure,omitempty"`

	// SideEffects indicates this step performs external mutations (e.g., API calls,
	// notifications). When true and no explicit retry policy is set, retries default to 0
	// to prevent duplicate side effects.
	// +optional
	SideEffects *bool `json:"sideEffects,omitempty"`

	// Requires lists dot-paths that must resolve to non-nil values before this step
	// is scheduled. Paths follow the format "steps.<name>.output.<key>".
	// If any required path is nil, the step fails immediately with a descriptive error.
	// +optional
	Requires []string `json:"requires,omitempty"`

	// IdempotencyKeyTemplate is a Go template that produces a business-scoped idempotency key.
	// When set, the evaluated result replaces the auto-generated execution-scoped key.
	// Template has access to inputs.* and steps.* contexts.
	// Example: "send-notification-{{ .inputs.customerId }}-{{ .inputs.orderId }}"
	// +kubebuilder:validation:MaxLength=512
	// +optional
	IdempotencyKeyTemplate *string `json:"idempotencyKeyTemplate,omitempty"`

	// Ref points to the Engram executed by this step.
	// +optional
	Ref *refs.EngramReference `json:"ref,omitempty"`

	// With carries step configuration and parameters for the Engram.
	// Evaluation timing depends on execution mode:
	//
	// Batch/Job Mode:
	//   - Evaluated once when the job starts (runtime evaluation)
	//   - Can access story inputs (inputs.*) and outputs from completed predecessor steps (steps.*)
	//   - May use now at runtime
	//   - Passed as BUBU_STEP_CONFIG environment variable
	//
	// Realtime/Streaming Mode:
	//   - Evaluated once at deployment creation (static configuration)
	//   - Can access story inputs (inputs.*) only
	//   - Step outputs are NOT available (they're per-packet, use 'runtime' field instead)
	//   - now is not allowed for deterministic static config
	//   - Passed as BUBU_STEP_CONFIG environment variable
	//
	// Examples:
	//   Batch: with: {inputFile: "{{ steps.fetch.outputs.filename }}", config: "{{ inputs.settings }}"}
	//   Realtime: with: {model: "gpt-4o-mini", systemPrompt: "{{ inputs.prompt }}"}
	//
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	With *runtime.RawExtension `json:"with,omitempty"`

	// Runtime carries dynamic per-packet configuration for realtime/streaming steps.
	// This field is ONLY used in realtime mode and is evaluated by the hub for each packet.
	//
	// Template expressions can reference:
	//   - inputs.*: Story inputs (static)
	//   - steps.*: Outputs from predecessor steps (per-packet data)
	//   - packet.*: Current packet metadata
	//   - now: runtime clock (allowed only for runtime evaluation)
	//
	// The hub evaluates this configuration for each packet and passes the result
	// in StreamMessage.Inputs to the engram.
	//
	// Batch Mode: This field is ignored (use 'with' field instead)
	//
	// Examples:
	//   runtime: {userPrompt: "{{ steps.transcribe.text }}", speakerId: "{{ packet.identity }}"}
	//
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	Runtime *runtime.RawExtension `json:"runtime,omitempty"`

	// Transport selects a named transport declared in Story.spec.transports. Streaming
	// steps use this to bind to the correct connector.
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	// +optional
	Transport string `json:"transport,omitempty"`

	// Secrets overrides template secret bindings for Engram steps.
	// +optional
	Secrets map[string]string `json:"secrets,omitempty"`

	// Execution carries per-step execution overrides. Prefer story- or template-level
	// configuration when possible.
	Execution *ExecutionOverrides `json:"execution,omitempty"`

	// PostExecution defines optional verification to run after the step completes.
	// The controller evaluates the condition template against the step's output.
	// If the condition evaluates to false, the step is marked as failed with a
	// verification error, even though the engram itself succeeded.
	// +optional
	PostExecution *PostExecutionCheck `json:"postExecution,omitempty"`
}

type StoragePolicy struct {
	// S3 specifies the configuration for an S3-compatible object store.
	// +optional
	S3 *S3StorageProvider `json:"s3,omitempty"`

	// File specifies configuration for a filesystem-backed object store.
	// +optional
	File *FileStorageProvider `json:"file,omitempty"`
	// NOTE: GCS, AzureBlob, etc., can be added here in the future.
	TimeoutSeconds int `json:"timeoutSeconds,omitempty"`
}

type Story struct {
	metav1.TypeMeta `json:",inline"`
	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of Story
	// +required
	Spec StorySpec `json:"spec"`

	// status defines the observed state of Story
	// +optional
	Status StoryStatus `json:"status,omitzero"`
}

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

type StoryPolicy struct {
	// Timeouts
	Timeouts *StoryTimeouts `json:"timeouts,omitempty"`

	// With provides the inputs for the sub-story, mirroring the 'with' field in an Engram step.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	With *runtime.RawExtension `json:"with,omitempty"`
	// Retry behavior
	Retries *StoryRetries `json:"retries,omitempty"`

	// Concurrency limits
	Concurrency *int32 `json:"concurrency,omitempty"`

	// Queue assigns StoryRuns to a scheduling queue for global/queue concurrency control.
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern="^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
	// +optional
	Queue *string `json:"queue,omitempty"`

	// Priority controls ordering within the selected queue (higher runs first).
	// +kubebuilder:validation:Minimum=0
	// +optional
	Priority *int32 `json:"priority,omitempty"`

	// Storage configuration
	Storage *StoragePolicy `json:"storage,omitempty"`

	// Default execution settings (can be overridden at step level)
	Execution *ExecutionPolicy `json:"execution,omitempty"`
}

type StoryRetries struct {
	// Default retry policy for steps
	StepRetryPolicy *RetryPolicy `json:"stepRetryPolicy,omitempty"`

	// Whether to continue story on step failure
	// +kubebuilder:default=false
	ContinueOnStepFailure *bool `json:"continueOnStepFailure,omitempty"`
}

type StorySpec struct {
	// Version identifies this Story for pinning by references.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	Version string `json:"version,omitempty"`

	// Pattern selects the execution model. Batch stories produce short-lived StoryRuns;
	// realtime stories maintain long-lived topologies.
	// +kubebuilder:validation:Enum=batch;realtime
	// +kubebuilder:default=batch
	Pattern enums.StoryPattern `json:"pattern,omitempty"`

	// Concurrency configures how the hub handles overlapping pipeline cycles
	// in realtime stories. Only applies when spec.pattern is "realtime".
	// +optional
	Concurrency *RealtimeConcurrency `json:"concurrency,omitempty"`

	// InputsSchema defines the schema for the data required to start a StoryRun.
	// JSON Schema defaults ("default") are applied at runtime when inputs are missing.
	// +optional
	InputsSchema *runtime.RawExtension `json:"inputsSchema,omitempty"`

	// OutputsSchema defines the schema for the data this Story is expected to produce.
	// +optional
	OutputsSchema *runtime.RawExtension `json:"outputsSchema,omitempty"`

	// Output defines a template for the Story's final output.
	// This template is evaluated upon successful completion of the story,
	// and the result is stored in the StoryRun's status.output field.
	// It has access to 'inputs' and 'steps' contexts.
	// e.g., {"final_message": "{{ printf \"processed %v records\" steps.load_data.outputs.count }}"}
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	Output *runtime.RawExtension `json:"output,omitempty"`

	// Steps enumerates the workflow graph. Control-flow primitives and Engram
	// references are represented here.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=100
	Steps []Step `json:"steps"`

	// Compensations lists steps to run when the story fails.
	// These steps run after main steps finish and before finally steps.
	// +kubebuilder:validation:MaxItems=50
	// +optional
	Compensations []Step `json:"compensations,omitempty"`

	// Finally lists steps that always run after the story completes
	// (success or failure). These steps run after compensations.
	// +kubebuilder:validation:MaxItems=50
	// +optional
	Finally []Step `json:"finally,omitempty"`

	// Policy provides optional story-wide defaults such as timeouts and storage.
	Policy *StoryPolicy `json:"policy,omitempty"`

	// Transports declares named media/stream transports that steps can publish to
	// or subscribe from. Controllers surface these to StoryRuns so engrams know
	// whether to keep payloads on the transport ("hot") or fall back to storage.
	// +optional
	Transports []StoryTransport `json:"transports,omitempty"`
}

type StoryStatus struct {
	// ObservedGeneration is the most recent generation observed for this Story.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Standard Kubernetes conditions for detailed status tracking (e.g., "Ready", "Validated")
	// This will indicate if the Story's syntax is valid and all referenced Engrams exist.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// StepsTotal reflects the total number of steps defined in the story's specification.
	// This provides a quick way to understand the complexity of the story.
	// +optional
	StepsTotal int32 `json:"stepsTotal,omitempty"`

	// Transports mirrors the declared transports with lightweight readiness info.
	// +optional
	Transports []StoryTransportStatus `json:"transports,omitempty"`

	// ValidationStatus indicates whether this Story's specification passed validation.
	ValidationStatus enums.ValidationStatus `json:"validationStatus,omitempty"`
	// ValidationErrors captures human-readable validation problems, when present.
	ValidationErrors []string `json:"validationErrors,omitempty"`

	// ValidationWarnings captures non-fatal validation issues (e.g., unreachable step references in templates).
	// +optional
	ValidationWarnings []string `json:"validationWarnings,omitempty"`

	// UsageCount reports how many Impulses reference this Story.
	// +optional
	UsageCount int32 `json:"usageCount"`

	// Triggers reports how many StoryRuns currently reference this Story.
	// This approximates how frequently the story has been executed.
	// +optional
	Triggers int64 `json:"triggers"`
}

type StoryTimeouts struct {
	// Total time for the entire story
	Story *string `json:"story,omitempty"`

	// Default timeout for individual steps
	Step *string `json:"step,omitempty"`

	// GracefulShutdownTimeout is the maximum time to wait for steps to complete
	// after cancel is requested. Defaults to 30s.
	// +optional
	GracefulShutdownTimeout *metav1.Duration `json:"gracefulShutdownTimeout,omitempty"`
}

type StoryTransport struct {
	// Name references the transport from steps (e.g. "realtime-audio").
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	Name string `json:"name"`
	// TransportRef references the Transport CR providing this functionality.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	TransportRef string `json:"transportRef"`
	// Description provides optional human-readable context.
	// +optional
	Description string `json:"description,omitempty"`
	// Streaming configures streaming policies such as backpressure, flow control, and delivery.
	// +optional
	Streaming *transportv1alpha1.TransportStreamingSettings `json:"streaming,omitempty"`
	// Settings contain provider-specific overrides evaluated per StoryRun.
	// +optional
	Settings *runtime.RawExtension `json:"settings,omitempty"`
}

type StoryTransportStatus struct {
	Name         string              `json:"name"`
	TransportRef string              `json:"transportRef"`
	Mode         enums.TransportMode `json:"mode,omitempty"`
	// ModeReason explains why the controller selected the effective mode (e.g., "declarative-default", "requires-primitives").
	// +optional
	ModeReason string `json:"modeReason,omitempty"`
}

type TriggerDedupeMode string

type TriggerDedupePolicy struct {
	// Mode selects the dedupe strategy.
	// - none: no deduplication
	// - token: use caller-provided trigger token
	// - key: derive a token from keyTemplate
	// +optional
	Mode *TriggerDedupeMode `json:"mode,omitempty"`

	// KeyTemplate is a template string used to derive a dedupe key when mode=key.
	// +optional
	KeyTemplate *string `json:"keyTemplate,omitempty"`
}

type TriggerDeliveryPolicy struct {
	// Dedupe configures trigger deduplication behavior.
	// +optional
	Dedupe *TriggerDedupePolicy `json:"dedupe,omitempty"`

	// Retry configures trigger retry behavior for transient failures.
	// +optional
	Retry *TriggerRetryPolicy `json:"retry,omitempty"`
}

type TriggerRetryPolicy struct {
	// MaxAttempts caps total trigger attempts (including the first).
	// +kubebuilder:validation:Minimum=0
	// +optional
	MaxAttempts *int32 `json:"maxAttempts,omitempty"`

	// BaseDelay is the initial retry delay (Go duration string).
	// +optional
	BaseDelay *string `json:"baseDelay,omitempty"`

	// MaxDelay caps the computed retry delay (Go duration string).
	// +optional
	MaxDelay *string `json:"maxDelay,omitempty"`

	// Backoff controls how retry delays are computed.
	// +optional
	Backoff *enums.BackoffStrategy `json:"backoff,omitempty"`
}

type TriggerThrottlePolicy struct {
	// MaxInFlight caps the number of concurrent trigger submissions.
	// Zero or negative disables the limit.
	// +optional
	MaxInFlight *int32 `json:"maxInFlight,omitempty"`

	// RatePerSecond sets the steady-state token bucket rate.
	// Zero or negative disables rate limiting.
	// +optional
	RatePerSecond *int32 `json:"ratePerSecond,omitempty"`

	// Burst sets the token bucket burst capacity.
	// When omitted, the SDK defaults to RatePerSecond.
	// +optional
	Burst *int32 `json:"burst,omitempty"`
}

type UpdateStrategy struct {
	// Type of update strategy
	// - RollingUpdate: Gradually replace old pods with new ones
	// - Recreate: Delete all old pods before creating new ones
	Type *enums.UpdateStrategyType `json:"type,omitempty"`

	// Rolling update configuration (only applies when type=RollingUpdate)
	RollingUpdate *RollingUpdateConfig `json:"rollingUpdate,omitempty"`
}

type WorkloadResources struct {
	// Resource requests and limits
	Requests *ResourceRequests `json:"requests,omitempty"`
	Limits   *ResourceLimits   `json:"limits,omitempty"`

	// Placement defines pod scheduling constraints.
	// +optional
	Placement *PlacementPolicy `json:"placement,omitempty"`
}

type WorkloadSecurity struct {
	// Whether to run as non-root user
	RunAsNonRoot *bool `json:"runAsNonRoot,omitempty"`

	// Whether to allow privilege escalation
	AllowPrivilegeEscalation *bool `json:"allowPrivilegeEscalation,omitempty"`

	// Read-only root filesystem
	ReadOnlyRootFilesystem *bool `json:"readOnlyRootFilesystem,omitempty"`

	// User ID to run as
	RunAsUser *int64 `json:"runAsUser,omitempty"`

	// Required secrets for this workload
	RequiredSecrets []string `json:"requiredSecrets,omitempty"`
}

type WorkloadSpec struct {
	// Mode selects the workload controller backing the component.
	//   * job        – short-lived, run-to-completion executions
	//   * deployment – continuously running, stateless processes
	//   * statefulset – continuously running processes with sticky identity
	// +kubebuilder:default="job"
	Mode enums.WorkloadMode `json:"mode,omitempty"`

	// Job config applies when Mode is job.
	Job *JobWorkloadConfig `json:"job,omitempty"`

	// StatefulSet config applies when Mode is statefulset.
	StatefulSet *StatefulSetWorkloadConfig `json:"statefulSet,omitempty"`

	// Resources specifies pod-level resource guarantees and limits.
	Resources *WorkloadResources `json:"resources,omitempty"`

	// UpdateStrategy determines how the workload should roll out changes.
	UpdateStrategy *UpdateStrategy `json:"updateStrategy,omitempty"`
}