v1alpha1

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

	// spec defines the desired state of EngramTemplate
	// +required
	Spec EngramTemplateSpec `json:"spec"`

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

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

type EngramTemplateSpec struct {
	// Common template fields (version, description, image, etc.)
	TemplateSpec `json:",inline"`

	// What data does this engram expect as input?
	// This defines the contract for the data flowing INTO this component
	// Examples:
	// - HTTP client: {"url": "string", "method": "string", "headers": "object"}
	// - OpenAI: {"prompt": "string", "model": "string", "temperature": "number"}
	// - Database: {"query": "string", "parameters": "object"}
	// +kubebuilder:pruning:PreserveUnknownFields
	InputSchema *runtime.RawExtension `json:"inputSchema,omitempty"`

	// What data does this engram produce as output?
	// This defines the contract for the data flowing OUT of this component
	// Examples:
	// - HTTP client: {"status": "integer", "body": "string", "headers": "object"}
	// - OpenAI: {"response": "string", "usage": "object", "model": "string"}
	// - Database: {"rows": "array", "rowCount": "integer", "duration": "number"}
	// +kubebuilder:pruning:PreserveUnknownFields
	OutputSchema *runtime.RawExtension `json:"outputSchema,omitempty"`

	// DeclaredOutputKeys lists the top-level keys this engram is expected to produce in its output.
	// Used for documentation, static analysis, and downstream template validation.
	// Example: ["body", "status", "headers"]
	// +optional
	DeclaredOutputKeys []string `json:"declaredOutputKeys,omitempty"`
}

type EngramTemplateStatus struct {
	TemplateStatus `json:",inline"`
}

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

	// spec defines the desired state of ImpulseTemplate
	// +required
	Spec ImpulseTemplateSpec `json:"spec"`

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

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

type ImpulseTemplateSpec struct {
	// Common template fields (version, description, image, etc.)
	TemplateSpec `json:",inline"`

	// What data does this trigger provide when events occur?
	// This defines the structure of the event context that will be available for mapping to Story inputs
	// Examples:
	// - GitHub webhook: {"repository": "object", "ref": "string", "commits": "array", "sender": "object"}
	// - File watcher: {"bucket": "string", "objectKey": "string", "size": "integer", "timestamp": "string"}
	// - Slack event: {"channel": "string", "user": "object", "message": "string", "timestamp": "string"}
	// - Cron trigger: {"scheduledTime": "string", "timezone": "string", "schedule": "string"}
	// +kubebuilder:pruning:PreserveUnknownFields
	ContextSchema *runtime.RawExtension `json:"contextSchema,omitempty"`

	// DeliveryPolicy defines default trigger delivery behavior (dedupe/retry) for Impulses.
	// +optional
	DeliveryPolicy *TriggerDeliveryPolicy `json:"deliveryPolicy,omitempty"`
}

type ImpulseTemplateStatus struct {
	TemplateStatus `json:",inline"`
}

type SecretDefinition struct {
	// Whether this secret is required for the template to function
	Required bool `json:"required,omitempty"`

	// Human-readable description of what this secret is used for
	// Example: "API key for OpenAI authentication", "Database connection credentials"
	Description string `json:"description,omitempty"`

	// How this secret should be mounted and accessed
	// - env: As environment variables (default for simple secrets)
	// - file: As mounted files (better for certificates, config files)
	// - both: Available as both env vars and files
	MountType enums.SecretMountType `json:"mountType,omitempty"`

	// For env mounting: what environment variable prefix to use
	// If not specified, uses secret name in uppercase
	// Example: "DATABASE" -> DATABASE_HOST, DATABASE_USER, DATABASE_PASSWORD
	EnvPrefix string `json:"envPrefix,omitempty"`

	// For file mounting: where to mount the secret files
	// Example: "/etc/secrets/database", "/opt/certs"
	MountPath string `json:"mountPath,omitempty"`

	// Expected keys in this secret (for validation and documentation)
	// Example: ["host", "username", "password"] or ["api-key", "org-id"]
	ExpectedKeys []string `json:"expectedKeys,omitempty"`
}

type TemplateExecutionPolicy struct {
	// Image handling recommendations (pull policies, etc.)
	Images *TemplateImagePolicy `json:"images,omitempty"`

	// Resource recommendations (how much CPU/memory this typically needs)
	Resources *TemplateResourcePolicy `json:"resources,omitempty"`

	// Security requirements and recommendations
	Security *TemplateSecurityPolicy `json:"security,omitempty"`

	// Job-specific recommendations (for templates that run as jobs)
	Job *TemplateJobPolicy `json:"job,omitempty"`

	// Retry behavior recommendations
	Retry *TemplateRetryPolicy `json:"retry,omitempty"`

	// Default timeout recommendation
	Timeout *string `json:"timeout,omitempty"`

	// Service exposure defaults for realtime components (and impulses)
	Service *TemplateServicePolicy `json:"service,omitempty"`

	// Health check probes (liveness, readiness, startup)
	// These are defined using standard Kubernetes probe format
	Probes *TemplateProbePolicy `json:"probes,omitempty"`

	// Storage recommendations for workloads that offload large inputs/outputs.
	Storage *TemplateStoragePolicy `json:"storage,omitempty"`

	// RBAC policies to bind to the generated ServiceAccount when using this template.
	RBAC *TemplateRBACPolicy `json:"rbac,omitempty"`
}

type TemplateFileStorageProvider struct {
	Path            string                       `json:"path,omitempty"`
	VolumeClaimName string                       `json:"volumeClaimName,omitempty"`
	EmptyDir        *corev1.EmptyDirVolumeSource `json:"emptyDir,omitempty"`
}

type TemplateImagePolicy struct {
	// Default image pull policy for this template (Always, Never, IfNotPresent)
	PullPolicy *string `json:"pullPolicy,omitempty"`
}

type TemplateJobPolicy struct {
	// Recommended backoff limit for this template
	RecommendedBackoffLimit *int32 `json:"recommendedBackoffLimit,omitempty"`
	// Recommended TTL after finished for this template
	RecommendedTTLSecondsAfterFinished *int32 `json:"recommendedTtlSecondsAfterFinished,omitempty"`
	// Recommended restart policy for this template
	RecommendedRestartPolicy *string `json:"recommendedRestartPolicy,omitempty"`
}

type TemplateProbePolicy struct {
	// Liveness probe checks if the container is alive
	// If this probe fails, the container will be restarted
	// +optional
	Liveness *corev1.Probe `json:"liveness,omitempty"`

	// Readiness probe checks if the container is ready to serve traffic
	// If this probe fails, the pod will be removed from service endpoints
	// +optional
	Readiness *corev1.Probe `json:"readiness,omitempty"`

	// Startup probe checks if the application has started
	// All other probes are disabled until this succeeds
	// Useful for slow-starting containers
	// +optional
	Startup *corev1.Probe `json:"startup,omitempty"`
}

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

type TemplateResourcePolicy struct {
	// Recommended CPU request for this template
	RecommendedCPURequest *string `json:"recommendedCpuRequest,omitempty"`
	// Recommended CPU limit for this template
	RecommendedCPULimit *string `json:"recommendedCpuLimit,omitempty"`
	// Recommended memory request for this template
	RecommendedMemoryRequest *string `json:"recommendedMemoryRequest,omitempty"`
	// Recommended memory limit for this template
	RecommendedMemoryLimit *string `json:"recommendedMemoryLimit,omitempty"`
	// Minimum resource requirements for this template
	MinCPURequest    *string `json:"minCpuRequest,omitempty"`
	MinMemoryRequest *string `json:"minMemoryRequest,omitempty"`
}

type TemplateRetryPolicy struct {
	// Recommended max retries for this template
	RecommendedMaxRetries *int `json:"recommendedMaxRetries,omitempty"`
	// Recommended backoff strategy for this template
	RecommendedBackoff *string `json:"recommendedBackoff,omitempty"`
	// Recommended base delay for this template
	RecommendedBaseDelay *string `json:"recommendedBaseDelay,omitempty"`
	// Recommended max delay for this template
	RecommendedMaxDelay *string `json:"recommendedMaxDelay,omitempty"`
}

type TemplateS3Authentication struct {
	ServiceAccountAnnotations map[string]string            `json:"serviceAccountAnnotations,omitempty"`
	SecretRef                 *corev1.LocalObjectReference `json:"secretRef,omitempty"`
}

type TemplateS3StorageProvider struct {
	Bucket         string                   `json:"bucket"`
	Region         string                   `json:"region,omitempty"`
	Endpoint       string                   `json:"endpoint,omitempty"`
	Authentication TemplateS3Authentication `json:"authentication"`

	// UsePathStyle forces path-style addressing when this template targets S3-compatible stores.
	// +optional
	UsePathStyle bool `json:"usePathStyle,omitempty"`
}

type TemplateSecurityPolicy struct {
	// Whether this template requires running as non-root
	RequiresNonRoot *bool `json:"requiresNonRoot,omitempty"`
	// Whether this template requires read-only root filesystem
	RequiresReadOnlyRoot *bool `json:"requiresReadOnlyRoot,omitempty"`
	// Whether this template requires no privilege escalation
	RequiresNoPrivilegeEscalation *bool `json:"requiresNoPrivilegeEscalation,omitempty"`
	// Recommended user ID for this template
	RecommendedRunAsUser *int64 `json:"recommendedRunAsUser,omitempty"`
}

type TemplateServicePolicy struct {
	// Ports defines external service ports and their target container ports
	Ports []TemplateServicePort `json:"ports,omitempty"`
}

type TemplateServicePort struct {
	Name       string `json:"name,omitempty"`
	Protocol   string `json:"protocol,omitempty"`
	Port       int32  `json:"port"`
	TargetPort int32  `json:"targetPort"`
}

type TemplateSpec struct {
	// Version of this template package (use semantic versioning like "1.2.3")
	// This allows users to pin to specific versions or upgrade safely
	Version string `json:"version"`

	// Human-readable description of what this template does
	// Examples: "HTTP client with retry and timeout support", "OpenAI GPT integration"
	Description string `json:"description,omitempty"`

	// Which Kubernetes workload types this template supports
	// - job: One-shot tasks (like batch processing, CI builds)
	// - deployment: Always-on stateless services (like APIs, webhooks)
	// - statefulset: Always-on stateful services (like databases, file processors)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=3
	SupportedModes []enums.WorkloadMode `json:"supportedModes"`

	// JSON Schema defining how users can configure this template
	// This validates the "with" field when users create Engrams/Impulses
	// Example: {"timeout": {"type": "string"}, "retries": {"type": "integer"}}
	// +kubebuilder:pruning:PreserveUnknownFields
	ConfigSchema *runtime.RawExtension `json:"configSchema,omitempty"`

	// Secret definitions that this template can use
	// Defines what secrets this template expects and how they should be structured
	// Users must provide corresponding secrets when creating Engrams/Impulses
	SecretSchema map[string]SecretDefinition `json:"secretSchema,omitempty"`

	// Container image that implements this template's functionality
	// This is the actual code that runs when someone uses this template
	// +kubebuilder:validation:MaxLength=512
	Image string `json:"image,omitempty"`

	// Default execution settings that template authors recommend
	// These provide sensible defaults but can be overridden by users
	Execution *TemplateExecutionPolicy `json:"execution,omitempty"`
}

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

	// Standard Kubernetes conditions (Ready, Available, etc.)
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// How many Engrams/Impulses are currently using this template
	// Useful for understanding template popularity and impact of changes
	// +optional
	UsageCount int32 `json:"usageCount"`

	// Whether this template passed validation checks
	ValidationStatus enums.ValidationStatus `json:"validationStatus,omitempty"`

	// If validation failed, what were the specific errors?
	// Helps template authors fix issues with their schemas or configuration
	ValidationErrors []string `json:"validationErrors,omitempty"`
}

type TemplateStoragePolicy struct {
	S3             *TemplateS3StorageProvider   `json:"s3,omitempty"`
	File           *TemplateFileStorageProvider `json:"file,omitempty"`
	TimeoutSeconds int                          `json:"timeoutSeconds,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"`
}