v1alpha1

type Engram struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   EngramSpec   `json:"spec,omitempty"`
	Status EngramStatus `json:"status,omitempty"`
}

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

type EngramSpec struct {
	// Which template to use for this engram instance
	// This connects the specific configuration below to a reusable component
	// +kubebuilder:validation:Required
	TemplateRef refs.EngramTemplateReference `json:"templateRef"`

	// Mode specifies how the Engram should be run.
	// Supported values are "job", "deployment", "statefulset".
	// If not specified, it defaults to the template's supported mode or "job".
	// +kubebuilder:validation:Enum=job;deployment;statefulset
	Mode enums.WorkloadMode `json:"mode,omitempty"`

	// How to configure this specific engram instance
	// This data gets validated against the EngramTemplate's configSchema
	// +kubebuilder:pruning:PreserveUnknownFields
	With *runtime.RawExtension `json:"with,omitempty"`

	// Secrets maps template secret definitions to actual Kubernetes secrets.
	Secrets map[string]string `json:"secrets,omitempty"`

	// ExecutionPolicy defines the execution configuration for this Engram.
	// These settings override any defaults from the EngramTemplate.
	// +optional
	ExecutionPolicy *ExecutionPolicy `json:"executionPolicy,omitempty"`

	// Overrides allows for fine-tuning of execution behavior.
	Overrides *ExecutionOverrides `json:"overrides,omitempty"`
}

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

	// This will indicate if the Engram's syntax is valid and its template is resolved.
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Current workload status - what's actually running.
	// These fields are ONLY populated for Engrams running as a Deployment or StatefulSet.
	// For job-based engrams, these will be empty.
	Replicas      int32       `json:"replicas,omitempty"`      // How many pods are currently running
	ReadyReplicas int32       `json:"readyReplicas,omitempty"` // How many pods are actually ready to serve traffic
	Phase         enums.Phase `json:"phase,omitempty"`         // Overall state: Pending, Running, Succeeded, Failed

	// Additional useful information for debugging and monitoring
	LastExecutionTime *metav1.Time `json:"lastExecutionTime,omitempty"` // When did this last run (for jobs)
	TotalExecutions   int32        `json:"totalExecutions,omitempty"`   // How many times has this run
	FailedExecutions  int32        `json:"failedExecutions,omitempty"`  // How many executions failed
}

type ExecutionOverrides struct {
	// Timeout for execution
	Timeout *string `json:"timeout,omitempty"`

	// Retry policy override
	Retry *RetryPolicy `json:"retry,omitempty"`

	// Security context override
	Security *WorkloadSecurity `json:"security,omitempty"`

	// Image pull policy override
	ImagePullPolicy *string `json:"imagePullPolicy,omitempty"`

	// ServiceAccount to use for the workload.
	// +optional
	ServiceAccountName *string `json:"serviceAccountName,omitempty"`

	// AutomountServiceAccountToken controls whether a service account token should be automatically mounted.
	// Defaults to false.
	// +optional
	AutomountServiceAccountToken *bool `json:"automountServiceAccountToken,omitempty"`

	// Probe overrides allow disabling template-defined probes at instance level
	// Note: You can only disable probes, not redefine them
	// +optional
	Probes *ProbeOverrides `json:"probes,omitempty"`
}

type ExecutionPolicy struct {
	// Resource configuration (actual values, not defaults)
	Resources *ResourcePolicy `json:"resources,omitempty"`

	// Security configuration
	Security *SecurityPolicy `json:"security,omitempty"`

	// Job configuration
	Job *JobPolicy `json:"job,omitempty"`

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

	// Timeout configuration
	Timeout *string `json:"timeout,omitempty"`

	// ServiceAccount to use for workloads created from this policy.
	// +optional
	ServiceAccountName *string `json:"serviceAccountName,omitempty"`
}

type Impulse struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   ImpulseSpec   `json:"spec,omitempty"`
	Status ImpulseStatus `json:"status,omitempty"`
}

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

type ImpulseSpec struct {
	// Which template to use for handling events
	// Examples: "github-webhook", "slack-handler", "file-watcher", "cron-scheduler"
	// +kubebuilder:validation:Required
	TemplateRef refs.ImpulseTemplateReference `json:"templateRef"`

	// Which Story to launch when an event is received
	// This is the story that will run in response to the trigger
	// +kubebuilder:validation:Required
	StoryRef refs.StoryReference `json:"storyRef"`

	// How to configure this specific trigger instance
	// Examples:
	// - Webhook: {"port": 8080, "path": "/webhook"}
	// - File watcher: {"bucket": "my-bucket", "prefix": "uploads/"}
	// - Scheduler: {"schedule": "0 2 * * *", "timezone": "UTC"}
	// +kubebuilder:pruning:PreserveUnknownFields
	With *runtime.RawExtension `json:"with,omitempty"`

	// Secrets configuration for this impulse instance
	// Maps template secret definitions to actual Kubernetes secrets
	// Example: {"authToken": "webhook-secret", "apiKey": "external-service-key"}
	Secrets map[string]string `json:"secrets,omitempty"`

	// How to transform the trigger event into Story inputs
	// You have complete freedom here - map any event data to any Story input
	// Examples:
	// - GitHub: {"repo": "{{ event.repository.name }}", "branch": "{{ event.ref }}"}
	// - File: {"filename": "{{ event.object.key }}", "size": "{{ event.object.size }}"}
	// +kubebuilder:pruning:PreserveUnknownFields
	Mapping *runtime.RawExtension `json:"mapping,omitempty"`

	// How to run this impulse (deployment or statefulset only - must be always-on)
	// Impulses can't be jobs because they need to continuously listen for events
	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"`

	// Fine-tune execution behavior for special cases
	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"`

	// Standard Kubernetes conditions (Ready, Available, etc.)
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Current workload status - how many trigger instances are running (managed by KEDA/HPA)
	Replicas      int32       `json:"replicas,omitempty"`      // How many trigger pods are currently running
	ReadyReplicas int32       `json:"readyReplicas,omitempty"` // How many trigger pods are ready to receive events
	Phase         enums.Phase `json:"phase,omitempty"`         // Overall state: Pending, Running, Failed

	// Event processing statistics - useful for monitoring and debugging
	TriggersReceived int64        `json:"triggersReceived,omitempty"` // Total events received since creation
	StoriesLaunched  int64        `json:"storiesLaunched,omitempty"`  // Total Stories successfully triggered
	FailedTriggers   int64        `json:"failedTriggers,omitempty"`   // Events that failed to trigger Stories
	LastTrigger      *metav1.Time `json:"lastTrigger,omitempty"`      // When did we last receive an event
	LastSuccess      *metav1.Time `json:"lastSuccess,omitempty"`      // When did we last successfully trigger a Story
}

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

	// TTL for job cleanup
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`

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

type JobWorkloadConfig struct {
	// Number of pods to run in parallel
	Parallelism *int32 `json:"parallelism,omitempty"`

	// Number of successful completions needed
	Completions *int32 `json:"completions,omitempty"`

	// Number of retries before marking as failed
	BackoffLimit *int32 `json:"backoffLimit,omitempty"`

	// Time after which job is considered failed
	ActiveDeadlineSeconds *int64 `json:"activeDeadlineSeconds,omitempty"`

	// TTL for cleanup after completion
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`
}

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

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

	// DisableStartup disables the startup probe
	// +optional
	DisableStartup bool `json:"disableStartup,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"`

	// 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"`
}

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 of Service to create (ClusterIP default, NodePort, LoadBalancer)
	Type string `json:"type,omitempty"`
	// Additional labels to attach to the Service
	Labels map[string]string `json:"labels,omitempty"`
	// Additional annotations to attach to the Service
	Annotations map[string]string `json:"annotations,omitempty"`
}

type StatefulSetWorkloadConfig struct {
	// Service name for StatefulSet
	ServiceName string `json:"serviceName"`

	// Pod management policy
	PodManagementPolicy *string `json:"podManagementPolicy,omitempty"`
}

type Step struct {
	// Name is a human-readable identifier for the step.
	// It's used to reference this step's outputs in other steps.
	// e.g., '{{ steps.my-step-name.outputs.some_field }}'
	// +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 is an optional, unique identifier for a step instance.
	// While 'name' identifies the step in logs and outputs, 'id' can be used
	// programmatically to reference a specific node in 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 explicitly defines a list of step names that must be completed before this step can run.
	// This is used to create an execution order for steps that don't have an implicit data dependency.
	// +optional
	Needs []string `json:"needs,omitempty"`

	// Type determines the kind of operation this step performs.
	// Use built-in types for common patterns. If omitted and 'ref' is present, the step is an 'engram' step.
	//
	// Built-in primitive types:
	// - condition: if/then/else logic
	// - loop: iterate over arrays or repeat N times
	// - parallel: run multiple steps simultaneously
	// - sleep: wait for a specified duration
	// - stop: halt story execution (success or failure)
	// - switch: multi-way branching like switch/case
	// - filter: filter arrays or objects based on conditions
	// - transform: modify data structure or format
	// - executeStory: run another story as a sub-story
	// - setData: set variables or update context
	// - mergeData: combine data from multiple sources
	// - wait: wait for external conditions
	// - throttle: rate limiting
	// - batch: group operations
	// - gate: wait for a manual approval
	// +optional
	Type enums.StepType `json:"type,omitempty"`

	// If provides a condition for executing this step.
	// The step is only executed if the CEL expression evaluates to true.
	// +optional
	If *string `json:"if,omitempty"`

	// Ref points to an Engram to execute.
	// This is a shortcut for a step of type 'engram'.
	// If 'ref' is used, 'type' should be omitted.
	// +optional
	Ref *refs.EngramReference `json:"ref,omitempty"`

	// With provides the configuration for the step. The expected structure of this block
	// is determined by the step 'type'. For example:
	// - for 'engram': the inputs to the engram.
	// - for 'executeStory': contains 'storyRef', 'waitForCompletion', and 'with'.
	// - for 'loop': contains 'items' and 'template'.
	// The structure is validated at runtime by the controller.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	With *runtime.RawExtension `json:"with,omitempty"`

	// Secrets maps template secret definitions to actual Kubernetes secrets for this step.
	// This is only applicable to 'engram' steps and overrides any secret mappings on the Engram itself.
	// Example: {"apiKey": "openai-credentials", "database": "postgres-creds"}
	// +optional
	Secrets map[string]string `json:"secrets,omitempty"`

	// Override execution settings for this specific step
	// Use sparingly - most configuration should be at the story or engram level
	Execution *ExecutionOverrides `json:"execution,omitempty"`
}

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

type Story struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   StorySpec   `json:"spec,omitempty"`
	Status StoryStatus `json:"status,omitempty"`
}

type StoryList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	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"`

	// 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
	ContinueOnStepFailure *bool `json:"continueOnStepFailure,omitempty"`
}

type StorySpec struct {
	// Pattern specifies the execution model for the Story.
	// "batch" stories are run to completion via a StoryRun.
	// "streaming" stories create long-running workloads that process data continuously.
	// +kubebuilder:validation:Enum=batch;streaming
	// +kubebuilder:default=batch
	Pattern enums.StoryPattern `json:"pattern,omitempty"`

	// StreamingStrategy defines the deployment strategy for long-running engrams in a streaming story.
	// "PerStory" creates a single, shared set of long-running engrams for the Story.
	// "PerStoryRun" creates a dedicated set of long-running engrams for each StoryRun.
	// This field is only applicable when `pattern` is "streaming".
	// +kubebuilder:validation:Enum=PerStory;PerStoryRun
	// +kubebuilder:default=PerStory
	// +optional
	StreamingStrategy enums.StreamingStrategy `json:"streamingStrategy,omitempty"`

	// InputsSchema defines the schema for the data required to start a StoryRun.
	// +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 CEL expression 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": "processed " + steps.load_data.outputs.count + " records"}
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	Output *runtime.RawExtension `json:"output,omitempty"`

	// The actual workflow steps - this is where the magic happens!
	// Steps run in sequence unless you use parallel/condition logic
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=100
	Steps []Step `json:"steps"`

	// How should this Story behave? (timeouts, retries, storage, etc.)
	Policy *StoryPolicy `json:"policy,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
	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"`
}

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

	// Default timeout for individual steps
	Step *string `json:"step,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"`

	// Scheduling constraints
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
	Tolerations  []string          `json:"tolerations,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 {
	// How to run this workload - the fundamental execution pattern
	// - job: Run once and complete (like a batch script or CI job)
	// - deployment: Always-on stateless service (like a web API or webhook listener)
	// - statefulset: Always-on stateful service (like a database or file processor with persistent storage)
	// +kubebuilder:default="job"
	Mode enums.WorkloadMode `json:"mode,omitempty"`

	// Job-specific settings (only applies when mode=job)
	Job *JobWorkloadConfig `json:"job,omitempty"`

	// StatefulSet-specific settings (only applies when mode=statefulset)
	StatefulSet *StatefulSetWorkloadConfig `json:"statefulSet,omitempty"`

	// Resource requirements (CPU, memory, etc.)
	Resources *WorkloadResources `json:"resources,omitempty"`

	// How to handle updates/upgrades
	UpdateStrategy *UpdateStrategy `json:"updateStrategy,omitempty"`
}