v1alpha1

type DownstreamTarget struct {
	// GRPCTarget specifies the connection details for the next Engram in the chain.
	// +optional
	GRPCTarget *GRPCTarget `json:"grpc,omitempty"`

	// Terminate indicates that this is the last step in the flow.
	// +optional
	Terminate *TerminateTarget `json:"terminate,omitempty"`
}

type EffectClaim struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of EffectClaim
	// +required
	Spec EffectClaimSpec `json:"spec"`

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

type EffectClaimCompletionStatus string

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

type EffectClaimPhase string

type EffectClaimSpec struct {
	// StepRunRef identifies the StepRun that owns this effect claim.
	// +kubebuilder:validation:Required
	StepRunRef refs.StepRunReference `json:"stepRunRef"`

	// EffectKey identifies the stable external effect within the StepRun.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=256
	EffectKey string `json:"effectKey"`

	// IdempotencyKey optionally copies the step-scoped business idempotency key.
	// +kubebuilder:validation:MaxLength=256
	// +optional
	IdempotencyKey string `json:"idempotencyKey,omitempty"`

	// HolderIdentity identifies the current reservation owner.
	// +kubebuilder:validation:MaxLength=253
	// +optional
	HolderIdentity string `json:"holderIdentity,omitempty"`

	// LeaseDurationSeconds bounds how long a reservation may remain unrenewed
	// before another worker may recover it.
	// +kubebuilder:validation:Minimum=1
	// +optional
	LeaseDurationSeconds int32 `json:"leaseDurationSeconds,omitempty"`

	// AcquireTime records when the current holder first acquired the reservation.
	// +optional
	AcquireTime *metav1.MicroTime `json:"acquireTime,omitempty"`

	// RenewTime records the latest observed successful renewal by the holder.
	// +optional
	RenewTime *metav1.MicroTime `json:"renewTime,omitempty"`

	// LeaseTransitions counts successful stale-takeover transitions.
	// +kubebuilder:validation:Minimum=0
	// +optional
	LeaseTransitions int32 `json:"leaseTransitions,omitempty"`

	// CompletionStatus records the terminal effect outcome once known.
	// +optional
	CompletionStatus EffectClaimCompletionStatus `json:"completionStatus,omitempty"`

	// CompletedAt records when the effect entered a terminal completion state.
	// +optional
	CompletedAt *metav1.Time `json:"completedAt,omitempty"`

	// Details carries compact structured metadata about the terminal effect outcome.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	Details *runtime.RawExtension `json:"details,omitempty"`
}

type EffectClaimStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase provides a canonical high-level lifecycle summary for the claim.
	// +optional
	Phase EffectClaimPhase `json:"phase,omitempty"`

	// Conditions provide canonical Kubernetes lifecycle status for the claim.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type EffectRecord struct {
	// Seq is a monotonically increasing sequence number for this StepRun.
	Seq uint64 `json:"seq"`
	// Key identifies the external effect (idempotency key or effect ID).
	Key string `json:"key"`
	// Status captures the outcome (e.g., succeeded, failed).
	// +optional
	Status string `json:"status,omitempty"`
	// EmittedAt records when the effect was emitted.
	// +optional
	EmittedAt *metav1.Time `json:"emittedAt,omitempty"`
	// Details carries optional structured metadata about the effect.
	// +optional
	Details *runtime.RawExtension `json:"details,omitempty"`
}

type GRPCTarget struct {
	// Endpoint is the address of the downstream service (e.g., "engram-b.default.svc:9000").
	// +kubebuilder:validation:Required
	Endpoint string `json:"endpoint"`
}

type GateDecisionState string

type GateStatus struct {
	// State is the gate decision state (Pending/Approved/Rejected).
	// +optional
	State GateDecisionState `json:"state,omitempty"`
	// Message provides optional human context for the decision.
	// +optional
	Message string `json:"message,omitempty"`
	// UpdatedAt records when the decision was last updated.
	// +optional
	UpdatedAt *metav1.Time `json:"updatedAt,omitempty"`
	// UpdatedBy is an optional identifier for who/what updated the decision.
	// +optional
	UpdatedBy string `json:"updatedBy,omitempty"`
}

type HandoffPhase string

type HandoffStatus struct {
	// Strategy reflects the lifecycle strategy in effect for this streaming workload.
	// +optional
	Strategy *transportv1alpha1.TransportUpgradeStrategy `json:"strategy,omitempty"`

	// Phase indicates the current handoff stage.
	// +optional
	Phase HandoffPhase `json:"phase,omitempty"`

	// Message provides a human-readable explanation for the current phase.
	// +optional
	Message string `json:"message,omitempty"`

	// UpdatedAt records when the handoff status was last updated.
	// +optional
	UpdatedAt *metav1.Time `json:"updatedAt,omitempty"`
}

type SchemaReference struct {
	// Ref is the schema identifier (for example: bubu://story/<namespace>/<story>/inputs).
	// +optional
	Ref string `json:"ref,omitempty"`

	// Version is the schema version when known.
	// +optional
	Version string `json:"version,omitempty"`
}

type SignalEvent struct {
	// Seq is a monotonically increasing sequence number for this StepRun.
	Seq uint64 `json:"seq"`
	// Key identifies the signal name.
	Key string `json:"key"`
	// EmittedAt records when the signal was emitted.
	// +optional
	EmittedAt *metav1.Time `json:"emittedAt,omitempty"`
	// Payload carries the signal payload.
	// +optional
	Payload *runtime.RawExtension `json:"payload,omitempty"`
}

type StepExecutionOverrides struct {
	// Resource overrides - only the essentials
	CPURequest    *string `json:"cpuRequest,omitempty"`    // Override CPU request (e.g., "100m", "0.5")
	CPULimit      *string `json:"cpuLimit,omitempty"`      // Override CPU limit (e.g., "500m", "1")
	MemoryRequest *string `json:"memoryRequest,omitempty"` // Override memory request (e.g., "128Mi", "1Gi")
	MemoryLimit   *string `json:"memoryLimit,omitempty"`   // Override memory limit (e.g., "256Mi", "2Gi")

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

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

	// Debug toggles component-level debug logging.
	Debug *bool `json:"debug,omitempty"`

	// Job behavior overrides
	BackoffLimit            *int32  `json:"backoffLimit,omitempty"`            // Override job backoff limit
	TTLSecondsAfterFinished *int32  `json:"ttlSecondsAfterFinished,omitempty"` // Override job cleanup time
	RestartPolicy           *string `json:"restartPolicy,omitempty"`           // Override restart policy (Never, OnFailure)
}

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

	// spec defines the desired state of StepRun
	// +required
	Spec StepRunSpec `json:"spec"`

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

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

type StepRunSpec struct {
	// Which StoryRun does this step belong to?
	// Used to track the parent execution and coordinate step ordering
	// +kubebuilder:validation:Required
	StoryRunRef refs.StoryRunReference `json:"storyRunRef"`

	// Which step in the Story is this executing?
	// References the step name/ID from the original Story definition
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=63
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	StepID string `json:"stepId"`

	// IdempotencyKey provides a stable identifier for step side effects.
	// External systems should use this to dedupe effects across retries.
	// +kubebuilder:validation:MaxLength=256
	// +optional
	IdempotencyKey string `json:"idempotencyKey,omitempty"`

	// What should this step execute?
	// Always references an Engram (for custom logic) or uses built-in primitive type
	// Primitive types: condition, parallel, sleep, stop, wait, executeStory, gate.
	EngramRef *refs.EngramReference `json:"engramRef,omitempty"` // Reference to an Engram for custom logic

	// TemplateGeneration records the EngramTemplate metadata.generation at the time
	// this StepRun was created. Enables auditing and replay against the exact template version.
	// +optional
	TemplateGeneration int64 `json:"templateGeneration,omitempty"`

	// What data should be passed to this step?
	// This is the resolved input after template evaluation and data flow from previous steps
	// Examples:
	// - HTTP request: {"url": "https://api.example.com", "method": "GET", "headers": {...}}
	// - OpenAI call: {"prompt": "Summarize this text: ...", "model": "gpt-4", "temperature": 0.7}
	// - Condition: {"expression": "{{ eq steps.http_check.output.status 200 }}"}
	// +kubebuilder:pruning:PreserveUnknownFields
	Input *runtime.RawExtension `json:"input,omitempty"`

	// Execution timing constraints (inherited from Story → Engram → Template hierarchy)
	// How long to wait before considering this step failed?
	// Examples: "30s", "5m", "1h"
	// Priority: StepRun > Story.steps[].execution.timeout > Engram.execution.timeout > Template.execution.timeout
	Timeout string `json:"timeout,omitempty"`

	// What to do if this step fails?
	// Priority: StepRun > Story.steps[].execution.retry > Engram.execution.retry > Template.execution.retry
	Retry *bubuv1alpha1.RetryPolicy `json:"retry,omitempty"`

	// Last-minute overrides for special situations
	// This has the highest priority in the configuration hierarchy
	ExecutionOverrides *StepExecutionOverrides `json:"executionOverrides,omitempty"`

	// DownstreamTargets instructs the Engram's SDK what to do with the output.
	// This is populated by the storyrun-controller to enable direct Engram-to-Engram communication.
	// Can be a list to support fanning out to multiple parallel steps.
	// +optional
	DownstreamTargets []DownstreamTarget `json:"downstreamTargets,omitempty"`
}

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

	// Current execution phase
	// - Pending: StepRun created but not yet started (waiting for dependencies)
	// - Running: Step is actively executing
	// - Succeeded: Step completed successfully
	// - Failed: Step failed and will not be retried
	// - Canceled: Step was canceled by user or system
	// - Paused: Step is paused waiting for external input or approval
	Phase enums.Phase `json:"phase,omitempty"`

	// Execution timing and metadata
	StartedAt  *metav1.Time `json:"startedAt,omitempty"`  // When did this step start?
	FinishedAt *metav1.Time `json:"finishedAt,omitempty"` // When did this step finish?
	Duration   string       `json:"duration,omitempty"`   // How long did execution take? (calculated field)

	// LastOutputAt records when the step's output was last written.
	// Useful for staleness detection — downstream consumers can compare this
	// against their own scheduling time.
	// +optional
	LastOutputAt *metav1.Time `json:"lastOutputAt,omitempty"`

	// Trace captures the OpenTelemetry trace context for this StepRun.
	// +optional
	Trace *TraceInfo `json:"trace,omitempty"`

	// Process execution details
	ExitCode  int32           `json:"exitCode,omitempty"`  // What exit code did the container return? (0 = success)
	ExitClass enums.ExitClass `json:"exitClass,omitempty"` // How should we interpret this exit? (success|retry|terminal|rateLimited)
	PodName   string          `json:"podName,omitempty"`   // Which Kubernetes pod executed this step?

	// Retry tracking (aligned with our Story/Engram/Template retry design)
	Retries        int32        `json:"retries"`                  // How many times has this step been retried?
	NextRetryAt    *metav1.Time `json:"nextRetryAt,omitempty"`    // When will the next retry happen?
	LastFailureMsg string       `json:"lastFailureMsg,omitempty"` // Most recent failure message for debugging

	// InputSchemaRef identifies the schema used to validate resolved step inputs.
	// +optional
	InputSchemaRef *SchemaReference `json:"inputSchemaRef,omitempty"`

	// OutputSchemaRef identifies the schema expected for step outputs.
	// +optional
	OutputSchemaRef *SchemaReference `json:"outputSchemaRef,omitempty"`

	// What did this step produce?
	// For small outputs (< 1MB), stored inline here
	// For large outputs, automatically stored in shared storage (if enabled) and path referenced here
	// This gets validated against the Engram's outputSchema (if applicable)
	// Examples:
	// - HTTP client: {"status": 200, "body": "...", "headers": {...}, "responseTime": 150}
	// - OpenAI: {"response": "Summary text...", "usage": {"tokens": 250}, "model": "gpt-4"}
	// - Large file: {"result": "success", "outputPath": "/shared/storage/story-123/step-fetch/response.json"}
	// +kubebuilder:pruning:PreserveUnknownFields
	Output *runtime.RawExtension `json:"output,omitempty"`

	// Optional logs reference emitted by the SDK/Engram.
	// When storage is enabled, the SDK may upload logs and store a storage ref map here.
	// +kubebuilder:pruning:PreserveUnknownFields
	Logs *runtime.RawExtension `json:"logs,omitempty"`

	// If the step failed, what was the error?
	// Contains structured error information for debugging.
	// Must conform to the StructuredError v1 contract (https://bubustack.io/docs/api/errors).
	// Examples:
	// - HTTP error: {"type": "http_error", "status": 404, "message": "Not Found", "url": "..."}
	// - Timeout: {"type": "timeout", "duration": "30s", "stage": "execution"}
	// - Validation: {"type": "validation_error", "field": "url", "message": "Invalid URL format"}
	Error *StructuredError `json:"error,omitempty"`

	// Conditions provide the canonical lifecycle status. Phase/Message are summaries.
	// The Ready condition reason holds stable reason codes for state transitions.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Handoff captures streaming upgrade/cutover state for realtime workloads.
	// +optional
	Handoff *HandoffStatus `json:"handoff,omitempty"`

	// Step coordination - which steps must complete before this one can start
	// Uses the same "needs" terminology as our Story API for consistency
	Needs []string `json:"needs,omitempty"` // StepRun names that must complete first

	// Signals captures lightweight, controller-friendly metadata emitted by running Engrams.
	// These values are intended for template expressions and branching logic (e.g., last transcript text).
	// Payloads should remain small (<8 KiB) to avoid bloating status objects.
	// +optional
	Signals map[string]runtime.RawExtension `json:"signals,omitempty"`

	// SignalEvents captures an append-only sequence of emitted signals for replay.
	// Payloads should remain small (<8 KiB) to avoid bloating status objects.
	// +optional
	// +kubebuilder:validation:MaxItems=256
	// +kubebuilder:validation:ListType=map
	// +kubebuilder:validation:ListMapKey=seq
	SignalEvents []SignalEvent `json:"signalEvents,omitempty"`

	// Effects records external side effects emitted by the step.
	// This ledger is append-only and intended for idempotency checks.
	// Payloads should remain small to avoid bloating status objects.
	// +optional
	// +kubebuilder:validation:MaxItems=256
	// +kubebuilder:validation:ListType=map
	// +kubebuilder:validation:ListMapKey=seq
	Effects []EffectRecord `json:"effects,omitempty"`
}

type StepState struct {
	// Phase is the current execution phase of the step.
	Phase enums.Phase `json:"phase"`
	// Message provides a human-readable summary of the step's status.
	// +optional
	Message string `json:"message,omitempty"`
	// StartedAt records when the step first entered a non-empty phase.
	// +optional
	StartedAt *metav1.Time `json:"startedAt,omitempty"`
	// FinishedAt records when the step reached a terminal phase.
	// +optional
	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`
	// For 'executeStory' steps, this tracks the name of the created sub-StoryRun.
	// +optional
	SubStoryRunName string `json:"subStoryRunName,omitempty"`
}

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

	// spec defines the desired state of StoryRun
	// +required
	Spec StoryRunSpec `json:"spec"`

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

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

type StoryRunSpec struct {
	// Which Story to execute
	// References can be same-namespace (name only) or cross-namespace with explicit namespace
	// Examples: "ci-pipeline", cross-ns: {"name": "deploy-app", "namespace": "production"}
	// +kubebuilder:validation:Required
	StoryRef refs.StoryReference `json:"storyRef"`

	// Which Impulse triggered this StoryRun, if any
	// This provides a clear audit trail from an event trigger to its corresponding workflow execution
	// +optional
	ImpulseRef *refs.ImpulseReference `json:"impulseRef,omitempty"`

	// Input data for this specific story execution
	// This data gets validated against the Story's inputsSchema
	// Examples:
	// - CI pipeline: {"repository": "my-app", "branch": "main", "commit": "abc123"}
	// - Data processing: {"filename": "data.csv", "format": "csv", "destination": "warehouse"}
	// - Deployment: {"environment": "production", "version": "v1.2.3", "rollback": false}
	// +kubebuilder:pruning:PreserveUnknownFields
	Inputs *runtime.RawExtension `json:"inputs,omitempty"`

	// CancelRequested signals that this StoryRun should be gracefully canceled.
	// When set to true, the controller will:
	// 1. Stop scheduling new steps
	// 2. Set running steps' CancelRequested annotation
	// 3. Wait for GracefulShutdownTimeout (default 30s) before force-killing
	// 4. Set the StoryRun phase to Finished
	// +optional
	CancelRequested *bool `json:"cancelRequested,omitempty"`
}

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

	// Current execution phase
	// - Pending: StoryRun created but not yet started
	// - Running: Story is actively executing steps
	// - Succeeded: All steps completed successfully
	// - Failed: A step failed and the story cannot continue
	// - Finished: Execution was stopped/canceled by user or system (non-failure termination)
	Phase enums.Phase `json:"phase,omitempty"`

	// Human-readable message about the story's status
	Message string `json:"message,omitempty"`

	// List of steps that are currently executing
	Active []string `json:"active,omitempty"`

	// List of steps that have completed successfully
	Completed []string `json:"completed,omitempty"`

	// Tracks the child StepRuns created by primitive steps (e.g., parallel branches)
	// Key: Name of the parent primitive step (e.g., "my-parallel-step")
	// Value: List of child StepRun names created by that primitive
	// +optional
	PrimitiveChildren map[string][]string `json:"primitiveChildren,omitempty"`

	// Execution timing
	StartedAt  *metav1.Time `json:"startedAt,omitempty"`
	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`

	// Timestamp when child resources (StepRuns, Pods) were cleaned up
	// Used to track the two-phase cleanup process (children first, then parent)
	// +optional
	ChildrenCleanedAt *metav1.Time `json:"childrenCleanedAt,omitempty"`

	// How long did this execution take? (calculated field)
	Duration string `json:"duration,omitempty"`

	// Trace captures the OpenTelemetry trace context for this StoryRun.
	// +optional
	Trace *TraceInfo `json:"trace,omitempty"`

	// Attempts counts how many times the StoryRun has entered Running.
	// This increments on each transition into Running.
	Attempts int32 `json:"attempts,omitempty"`

	// InputSchemaRef identifies the schema used to validate StoryRun inputs.
	// +optional
	InputSchemaRef *SchemaReference `json:"inputSchemaRef,omitempty"`

	// OutputSchemaRef identifies the schema expected for StoryRun outputs.
	// +optional
	OutputSchemaRef *SchemaReference `json:"outputSchemaRef,omitempty"`

	// What data did this story produce upon completion?
	// For small outputs (< 1MB), stored inline here
	// For large outputs, automatically stored in shared storage (if enabled) and path referenced here
	// This gets validated against the Story's outputSchema
	// Examples:
	// - CI pipeline: {"buildArtifact": "app-v1.2.3.tar.gz", "testResults": {...}, "deploymentUrl": "https://..."}
	// - Data processing: {"processedRows": 1000, "outputFile": "processed-data.json", "errors": 5}
	// - Large output: {"result": "success", "outputPath": "/shared/storage/story-123/final-output.json"}
	// +kubebuilder:pruning:PreserveUnknownFields
	Output *runtime.RawExtension `json:"output,omitempty"`

	// StepStates provides a detailed, real-time status for each step in the Story.
	// The key is the step name.
	// +optional
	StepStates map[string]StepState `json:"stepStates,omitempty"`

	// Gates captures manual gate decisions keyed by step name.
	// +optional
	Gates map[string]GateStatus `json:"gates,omitempty"`

	// If the story failed, what was the error?
	// Contains structured error information for debugging
	// Examples:
	// - Step failure: {"failedStep": "deploy", "reason": "timeout", "details": "..."}
	// - Validation error: {"type": "input_validation", "field": "url", "message": "Invalid URL"}
	// +kubebuilder:pruning:PreserveUnknownFields
	Error *runtime.RawExtension `json:"error,omitempty"`

	// Conditions provide the canonical lifecycle status. Phase/Message are summaries.
	// The Ready condition reason holds stable reason codes for state transitions.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Step execution summary for quick overview
	StepsTotal    int32 `json:"stepsTotal,omitempty"`    // Total number of steps in the story
	StepsComplete int32 `json:"stepsComplete,omitempty"` // Number of steps that completed successfully
	StepsFailed   int32 `json:"stepsFailed,omitempty"`   // Number of steps that failed
	StepsSkipped  int32 `json:"stepsSkipped,omitempty"`  // Number of steps that were skipped

	// AllowedFailures lists steps that failed but were explicitly allowed to fail.
	// +optional
	AllowedFailures []string `json:"allowedFailures,omitempty"`

	// TriggerTokens tracks which parent resources have counted this StoryRun.
	// Used for idempotent trigger counting by Story/Impulse controllers.
	// Managed by the StoryRun controller to avoid annotation churn from multiple writers.
	// Possible tokens:
	//   - "story": counted by parent Story's trigger count
	//   - "impulse": counted by parent Impulse's trigger count
	//   - "impulse-success": counted by parent Impulse's success count
	//   - "impulse-failed": counted by parent Impulse's failure count
	// +optional
	TriggerTokens []string `json:"triggerTokens,omitempty"`
}

type StoryTrigger struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec defines the desired state of StoryTrigger
	// +required
	Spec StoryTriggerSpec `json:"spec"`

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

type StoryTriggerDecision string

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

type StoryTriggerSpec struct {
	// StoryRef identifies the Story executed when the trigger is accepted.
	// +kubebuilder:validation:Required
	StoryRef refs.StoryReference `json:"storyRef"`

	// ImpulseRef identifies the Impulse that observed the external event.
	// +optional
	ImpulseRef *refs.ImpulseReference `json:"impulseRef,omitempty"`

	// Inputs is the resolved Story input payload for the requested run.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +optional
	Inputs *runtime.RawExtension `json:"inputs,omitempty"`

	// DeliveryIdentity is the durable request identity used for dedupe and retry resolution.
	// +kubebuilder:validation:Required
	DeliveryIdentity TriggerDeliveryIdentity `json:"deliveryIdentity"`
}

type StoryTriggerStatus struct {
	// ObservedGeneration is the latest generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Decision is the controller-owned durable admission decision.
	// +optional
	Decision StoryTriggerDecision `json:"decision,omitempty"`

	// Reason is a stable machine-readable reason for the current decision.
	// +optional
	Reason string `json:"reason,omitempty"`

	// Message provides a human-readable description of the current decision.
	// +optional
	Message string `json:"message,omitempty"`

	// StoryRunRef points at the accepted or reused StoryRun once resolution completes.
	// +optional
	StoryRunRef *refs.StoryRunReference `json:"storyRunRef,omitempty"`

	// AcceptedAt records when the trigger was first accepted for controller processing.
	// +optional
	AcceptedAt *metav1.Time `json:"acceptedAt,omitempty"`

	// CompletedAt records when the controller finished resolving the trigger.
	// +optional
	CompletedAt *metav1.Time `json:"completedAt,omitempty"`

	// Conditions provide canonical Kubernetes lifecycle status for the trigger request.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type StructuredError struct {
	// Version identifies the schema version for this error payload.
	// +kubebuilder:default="v1"
	Version string `json:"version"`

	// Type is a machine-readable error category.
	Type StructuredErrorType `json:"type"`

	// Message is the human-readable error message.
	Message string `json:"message"`

	// Retryable indicates whether a retry may succeed for this error.
	// Omitted when unknown.
	Retryable *bool `json:"retryable,omitempty"`

	// ExitCode is the container exit code, when known.
	ExitCode *int32 `json:"exitCode,omitempty"`

	// ExitClass mirrors the platform retry classification (success|retry|terminal|rateLimited).
	ExitClass StructuredErrorExitClass `json:"exitClass,omitempty"`

	// Code is an optional, component-specific error code.
	Code string `json:"code,omitempty"`

	// Details carries optional structured data for debugging.
	// +kubebuilder:pruning:PreserveUnknownFields
	Details *runtime.RawExtension `json:"details,omitempty"`
}

type StructuredErrorExitClass string

type StructuredErrorType string

type TerminateTarget struct {
	// StopMode defines the final phase of the StoryRun (e.g., success, failure).
	// +kubebuilder:validation:Required
	StopMode enums.StopMode `json:"stopMode"`
}

type TraceInfo struct {
	// TraceID is the OpenTelemetry trace identifier.
	// +optional
	TraceID string `json:"traceId,omitempty"`
	// SpanID is the OpenTelemetry span identifier associated with the trace.
	// +optional
	SpanID string `json:"spanId,omitempty"`
	// Sampled reports whether the trace was sampled when recorded.
	// +optional
	Sampled *bool `json:"sampled,omitempty"`
}

type TriggerDeliveryIdentity struct {
	// Mode records how the trigger identity was derived.
	// +optional
	Mode *bubuv1alpha1.TriggerDedupeMode `json:"mode,omitempty"`

	// Key is the stable business key used for token/key dedupe modes.
	// +kubebuilder:validation:MaxLength=256
	// +optional
	Key string `json:"key,omitempty"`

	// InputHash is the canonical sha256 of the resolved trigger inputs.
	// Required when Key is set.
	// +kubebuilder:validation:MaxLength=64
	// +optional
	InputHash string `json:"inputHash,omitempty"`

	// SubmissionID identifies one logical trigger submission attempt chain.
	// Retries for the same submission must reuse this value.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	SubmissionID string `json:"submissionId"`
}