contracts

const (
	// Controller timing configuration
	// Note: Per-controller max-concurrent-reconciles are under storyrun.*, steprun.*, etc.
	KeyRequeueBaseDelay                  = "controller.requeue-base-delay"
	KeyRequeueMaxDelay                   = "controller.requeue-max-delay"
	KeyCleanupInterval                   = "controller.cleanup-interval"
	KeyReconcileTimeout                  = "controller.reconcile-timeout"
	KeyMaxStoryWithBlockSizeBytes        = "controller.max-story-with-block-size-bytes"
	KeyControllerMaxConcurrentReconciles = "controller.max-concurrent-reconciles"

	// Image configuration
	KeyDefaultEngramImage  = "images.default-engram"
	KeyDefaultImpulseImage = "images.default-impulse"
	KeyImagePullPolicy     = "images.pull-policy"

	// Resource limit configuration
	KeyDefaultCPURequest    = "resources.default.cpu-request"
	KeyDefaultCPULimit      = "resources.default.cpu-limit"
	KeyDefaultMemoryRequest = "resources.default.memory-request"
	KeyDefaultMemoryLimit   = "resources.default.memory-limit"
	KeyEngramCPURequest     = "resources.engram.cpu-request"
	KeyEngramCPULimit       = "resources.engram.cpu-limit"
	KeyEngramMemoryRequest  = "resources.engram.memory-request"
	KeyEngramMemoryLimit    = "resources.engram.memory-limit"

	// Retry and timeout configuration
	KeyMaxRetries             = "retry.max-retries"
	KeyDefaultStepTimeout     = "timeout.default-step"
	KeyApprovalDefaultTimeout = "timeout.approval-default"
	KeyExternalDataTimeout    = "timeout.external-data-default"
	KeyConditionalTimeout     = "timeout.conditional-default"

	// Loop configuration
	KeyMaxLoopIterations    = "loop.max-iterations"
	KeyDefaultLoopBatchSize = "loop.default-batch-size"
	KeyMaxLoopBatchSize     = "loop.max-batch-size"
	KeyMaxLoopConcurrency   = "loop.max-concurrency"
	KeyMaxConcurrencyLimit  = "loop.max-concurrency-limit"

	// Security configuration
	KeyRunAsNonRoot                 = "security.run-as-non-root"
	KeyReadOnlyRootFilesystem       = "security.read-only-root-filesystem"
	KeyAllowPrivilegeEscalation     = "security.allow-privilege-escalation"
	KeyDropCapabilities             = "security.drop-capabilities"
	KeyRunAsUser                    = "security.run-as-user"
	KeyAutomountServiceAccountToken = "security.automount-service-account-token"
	KeyServiceAccountName           = "security.service-account-name"

	// Transport configuration
	KeyTransportEnabled              = "transport.enabled"
	KeyTransportHeartbeatInterval    = "controller.transport.heartbeat-interval"
	KeyTransportHeartbeatTimeout     = "controller.transport.heartbeat-timeout"
	KeyTransportSecurityMode         = "transport.security-mode"
	KeyTransportGRPCEnableDownstream = "controller.transport.grpc.enable-downstream-targets"
	KeyTransportGRPCDefaultTLSSecret = "controller.transport.grpc.default-tls-secret"

	// Job configuration
	KeyJobBackoffLimit                 = "job.backoff-limit"
	KeyJobTTLSecondsAfterFinished      = "job.ttl-seconds-after-finished"
	KeyRealtimeTTLSecondsAfterFinished = "realtime.ttl-seconds-after-finished"
	KeyJobRestartPolicy                = "job.restart-policy"
	KeyStoryRunRetentionSeconds        = "storyrun.retention-seconds"

	// Templating configuration
	KeyTemplatingEvaluationTimeout = "templating.evaluation-timeout"
	KeyTemplatingMaxOutputBytes    = "templating.max-output-bytes"
	KeyTemplatingDeterministic     = "templating.deterministic"
	KeyTemplatingOffloadedPolicy   = "templating.offloaded-data-policy"
	KeyTemplatingMaterializeEngram = "templating.materialize-engram"

	// Reference configuration
	KeyReferencesCrossNamespacePolicy = "references.cross-namespace-policy"

	// Telemetry configuration
	KeyTelemetryEnabled = "telemetry.enabled"
	KeyTracePropagation = "telemetry.trace-propagation"

	// Debug configuration
	KeyVerboseLogging    = "debug.enable-verbose-logging"
	KeyStepOutputLogging = "debug.enable-step-output-logging"
	KeyEnableMetrics     = "debug.enable-metrics"

	// Engram defaults
	KeyEngramDefaultInlineSize = "engram.default-max-inline-size"

	// StoryRun controller configuration
	KeyStoryRunMaxConcurrentReconciles     = "storyrun.max-concurrent-reconciles"
	KeyStoryRunRateLimiterBaseDelay        = "storyrun.rate-limiter.base-delay"
	KeyStoryRunRateLimiterMaxDelay         = "storyrun.rate-limiter.max-delay"
	KeyStoryRunMaxInlineInputsSize         = "storyrun.max-inline-inputs-size"
	KeyStoryRunBindingMaxMutations         = "storyrun.binding.max-mutations-per-reconcile"
	KeyStoryRunBindingThrottleRequeueDelay = "storyrun.binding.throttle-requeue-delay"
	KeyStoryRunGlobalConcurrency           = "storyrun.global-concurrency"
	KeyStoryRunQueuePrefix                 = "storyrun.queue."
	KeyStoryRunQueueConcurrencySuffix      = "concurrency"
	KeyStoryRunQueueDefaultPrioritySuffix  = "default-priority"
	KeyStoryRunQueuePriorityAgingSuffix    = "priority-aging-seconds"

	// StepRun controller configuration
	KeyStepRunMaxConcurrentReconciles = "steprun.max-concurrent-reconciles"
	KeyStepRunRateLimiterBaseDelay    = "steprun.rate-limiter.base-delay"
	KeyStepRunRateLimiterMaxDelay     = "steprun.rate-limiter.max-delay"

	// Story controller configuration
	KeyStoryMaxConcurrentReconciles     = "story.max-concurrent-reconciles"
	KeyStoryRateLimiterBaseDelay        = "story.rate-limiter.base-delay"
	KeyStoryRateLimiterMaxDelay         = "story.rate-limiter.max-delay"
	KeyStoryBindingMaxMutations         = "story.binding.max-mutations-per-reconcile"
	KeyStoryBindingThrottleRequeueDelay = "story.binding.throttle-requeue-delay"

	// Engram controller configuration
	KeyEngramMaxConcurrentReconciles           = "engram.max-concurrent-reconciles"
	KeyEngramRateLimiterBaseDelay              = "engram.rate-limiter.base-delay"
	KeyEngramRateLimiterMaxDelay               = "engram.rate-limiter.max-delay"
	KeyEngramDefaultGRPCPort                   = "engram.default-grpc-port"
	KeyEngramDefaultHeartbeatIntervalSeconds   = "engram.default-grpc-heartbeat-interval-seconds"
	KeyEngramDefaultStorageTimeoutSeconds      = "engram.default-storage-timeout-seconds"
	KeyEngramDefaultGracefulShutdownSeconds    = "engram.default-graceful-shutdown-timeout-seconds"
	KeyEngramDefaultTerminationGraceSeconds    = "engram.default-termination-grace-period-seconds"
	KeyEngramDefaultMaxRecvMsgBytes            = "engram.default-max-recv-msg-bytes"
	KeyEngramDefaultMaxSendMsgBytes            = "engram.default-max-send-msg-bytes"
	KeyEngramDefaultDialTimeoutSeconds         = "engram.default-dial-timeout-seconds"
	KeyEngramDefaultChannelBufferSize          = "engram.default-channel-buffer-size"
	KeyEngramDefaultReconnectMaxRetries        = "engram.default-reconnect-max-retries"
	KeyEngramDefaultReconnectBaseBackoffMillis = "engram.default-reconnect-base-backoff-millis"
	KeyEngramDefaultReconnectMaxBackoffSeconds = "engram.default-reconnect-max-backoff-seconds"
	KeyEngramDefaultHangTimeoutSeconds         = "engram.default-hang-timeout-seconds"
	KeyEngramDefaultMessageTimeoutSeconds      = "engram.default-message-timeout-seconds"

	// Impulse controller configuration
	KeyImpulseMaxConcurrentReconciles = "impulse.max-concurrent-reconciles"
	KeyImpulseRateLimiterBaseDelay    = "impulse.rate-limiter.base-delay"
	KeyImpulseRateLimiterMaxDelay     = "impulse.rate-limiter.max-delay"

	// Template controller configuration
	KeyTemplateMaxConcurrentReconciles = "template.max-concurrent-reconciles"
	KeyTemplateRateLimiterBaseDelay    = "template.rate-limiter.base-delay"
	KeyTemplateRateLimiterMaxDelay     = "template.rate-limiter.max-delay"

	// Storage defaults
	KeyStorageProvider        = "controller.storage.provider"
	KeyStorageS3Bucket        = "controller.storage.s3.bucket"
	KeyStorageS3Region        = "controller.storage.s3.region"
	KeyStorageS3Endpoint      = "controller.storage.s3.endpoint"
	KeyStorageS3PathStyle     = "controller.storage.s3.use-path-style"
	KeyStorageS3AuthSecret    = "controller.storage.s3.auth-secret-name"
	KeyStorageFilePath        = "controller.storage.file.path"
	KeyStorageFileVolumeClaim = "controller.storage.file.volume-claim-name"
)

const (
	PullPolicyAlways       = "Always"
	PullPolicyNever        = "Never"
	PullPolicyIfNotPresent = "IfNotPresent"
)

const (
	RestartPolicyAlways    = "Always"
	RestartPolicyNever     = "Never"
	RestartPolicyOnFailure = "OnFailure"
)

const (
	StorageProviderS3   = "s3"
	StorageProviderFile = "file"
)

const (
	// Controller concurrency defaults
	DefaultControllerMaxConcurrentReconciles = 10
	DefaultStoryRunMaxConcurrentReconciles   = 8
	DefaultStepRunMaxConcurrentReconciles    = 15
	DefaultStoryMaxConcurrentReconciles      = 5
	DefaultEngramMaxConcurrentReconciles     = 5
	DefaultImpulseMaxConcurrentReconciles    = 5
	DefaultTemplateMaxConcurrentReconciles   = 2
	DefaultTransportMaxConcurrentReconciles  = 2

	// Loop configuration defaults
	DefaultMaxLoopIterations   = 10000
	DefaultLoopBatchSize       = 100
	DefaultMaxLoopBatchSize    = 1000
	DefaultMaxLoopConcurrency  = 10
	DefaultMaxConcurrencyLimit = 50

	// Size limits
	DefaultMaxStoryWithBlockSizeBytes = 64 * 1024        // 64 KiB
	DefaultMaxInlineInputsSize        = 1 * 1024         // 1 KiB
	DefaultMaxInlineSize              = 1 * 1024         // 1 KiB
	DefaultMaxRecvMsgBytes            = 10 * 1024 * 1024 // 10 MiB
	DefaultMaxSendMsgBytes            = 10 * 1024 * 1024 // 10 MiB

	// gRPC defaults
	DefaultGRPCPort                       = 50051
	DefaultGRPCHeartbeatIntervalSeconds   = 10
	DefaultStorageTimeoutSeconds          = 300 // 5 minutes
	DefaultGracefulShutdownTimeoutSeconds = 20
	DefaultTerminationGracePeriodSeconds  = 30
	DefaultDialTimeoutSeconds             = 10
	DefaultChannelBufferSize              = 16
	DefaultReconnectMaxRetries            = 10
	DefaultReconnectBaseBackoffMillis     = 500
	DefaultReconnectMaxBackoffSeconds     = 30
	DefaultHangTimeoutSeconds             = 0
	DefaultMessageTimeoutSeconds          = 30

	// Binding controller defaults
	DefaultBindingMaxMutationsPerReconcile = 8
)

const (
	// StoryNameEnv stores the Story name for the active workload.
	StoryNameEnv = PrefixEnv + "STORY_NAME"
	// StoryVersionEnv stores the Story version for the active workload.
	StoryVersionEnv = PrefixEnv + "STORY_VERSION"
	// StoryRunIDEnv stores the StoryRun identifier for the active workload.
	StoryRunIDEnv = PrefixEnv + "STORYRUN_ID"
	// StepNameEnv stores the step name for the active workload.
	StepNameEnv = PrefixEnv + "STEP_NAME"
	// StepRunNameEnv stores the StepRun resource name for the active workload.
	StepRunNameEnv = PrefixEnv + "STEPRUN_NAME"
	// StepRunNamespaceEnv stores the StepRun namespace for the active workload.
	StepRunNamespaceEnv = PrefixEnv + "STEPRUN_NAMESPACE"
	// EngramNameEnv stores the Engram name bound to the active workload.
	EngramNameEnv = PrefixEnv + "ENGRAM_NAME"
	// EngramVersionEnv stores the Engram version bound to the active workload.
	EngramVersionEnv = PrefixEnv + "ENGRAM_VERSION"
	// ExecutionModeEnv stores the top-level execution mode selected for the workload.
	ExecutionModeEnv = PrefixEnv + "EXECUTION_MODE"
	// WorkloadModeEnv stores the specific runtime mode used by the current pod or process.
	WorkloadModeEnv = PrefixEnv + "WORKLOAD_MODE"
)

const (
	// StepConfigEnv stores static step configuration resolved from `step.config` or `step.with`.
	StepConfigEnv = PrefixEnv + "STEP_CONFIG"
	// TriggerDataEnv stores the resolved trigger payload for the active workload.
	TriggerDataEnv = PrefixEnv + "TRIGGER_DATA"
	// TemplateContextEnv stores the template evaluation context passed to the SDK.
	TemplateContextEnv = PrefixEnv + "TEMPLATE_CONTEXT"
	// SkipInputTemplatingEnv disables SDK-side template resolution when set.
	SkipInputTemplatingEnv = PrefixEnv + "SKIP_INPUT_TEMPLATING"
	// TransportsEnv stores serialized transport configuration for the active workload.
	TransportsEnv = PrefixEnv + "TRANSPORTS"
	// ConfigPrefixEnv prefixes per-key configuration environment variables.
	ConfigPrefixEnv = PrefixEnv + "CONFIG_"
	// StartedAtEnv stores the workload start timestamp.
	StartedAtEnv = PrefixEnv + "STARTED_AT"
	// ImpulseNameEnv stores the triggering Impulse name when execution originates from an Impulse.
	ImpulseNameEnv = PrefixEnv + "IMPULSE_NAME"
	// ImpulseNamespaceEnv stores the triggering Impulse namespace when execution originates from an Impulse.
	ImpulseNamespaceEnv = PrefixEnv + "IMPULSE_NAMESPACE"
	// TargetStoryNameEnv stores the Story name targeted by a trigger or bridge action.
	TargetStoryNameEnv = PrefixEnv + "TARGET_STORY_NAME"
	// TargetStoryNamespaceEnv stores the namespace of the targeted Story.
	TargetStoryNamespaceEnv = PrefixEnv + "TARGET_STORY_NAMESPACE"
	// TriggerTokenEnv stores the normalized trigger token for the current execution.
	TriggerTokenEnv = PrefixEnv + "TRIGGER_TOKEN"
	// PodNameEnv stores the pod name for downward-API consumers.
	PodNameEnv = PrefixEnv + "POD_NAME"
	// PodNamespaceEnv stores the pod namespace for downward-API consumers.
	PodNamespaceEnv = PrefixEnv + "POD_NAMESPACE"
	// ServiceAccountNameEnv stores the Kubernetes service account name used by the workload.
	ServiceAccountNameEnv = PrefixEnv + "SERVICE_ACCOUNT_NAME"
	// SecretPrefixEnv prefixes environment variables sourced from secrets.
	SecretPrefixEnv = PrefixEnv + "SECRET_"
	// TransportBindingEnv stores the serialized transport binding envelope for the workload.
	TransportBindingEnv = PrefixEnv + "TRANSPORT_BINDING"
	// TransportDriverEnv stores the selected transport driver identifier.
	TransportDriverEnv = PrefixEnv + "TRANSPORT_DRIVER"
	// TransportEndpointEnv stores the resolved transport endpoint for the workload.
	TransportEndpointEnv = PrefixEnv + "TRANSPORT_ENDPOINT"
	// TransportAudioCodecsEnv stores the allowed transport audio codec list.
	TransportAudioCodecsEnv = PrefixEnv + "TRANSPORT_AUDIO_CODECS"
	// TransportVideoCodecsEnv stores the allowed transport video codec list.
	TransportVideoCodecsEnv = PrefixEnv + "TRANSPORT_VIDEO_CODECS"
	// TransportBinaryTypesEnv stores the allowed binary payload type list.
	TransportBinaryTypesEnv = PrefixEnv + "TRANSPORT_BINARY_TYPES"
	// TransportHeartbeatIntervalEnv stores the transport heartbeat interval.
	TransportHeartbeatIntervalEnv = PrefixEnv + "TRANSPORT_HEARTBEAT_INTERVAL"
	// TransportSecurityModeEnv stores the transport security mode. The supported value is "tls".
	TransportSecurityModeEnv = PrefixEnv + "TRANSPORT_SECURITY_MODE"
	// DebugEnv enables shared debug behavior when set.
	DebugEnv = PrefixEnv + "DEBUG"
)

const (
	// TransportReadyAnnotation marks a transport-backed workload as ready.
	TransportReadyAnnotation = "transport.bobravoz.bubustack.io/ready"
	// TransportReadyMessageAnnotation stores human-readable readiness details for a transport workload.
	TransportReadyMessageAnnotation = "transport.bobravoz.bubustack.io/message"
	// TransportBindingAnnotation stores the transport binding reference attached to a resource.
	TransportBindingAnnotation = "transport.bubustack.io/binding"
	// StoryAnnotation stores the owning Story name on an annotated resource.
	StoryAnnotation = "bubustack.io/story"
	// StoryRunAnnotation stores the owning StoryRun name on an annotated resource.
	StoryRunAnnotation = "bubustack.io/storyrun"
	// StoryRunTriggerAnnotation marks that a StoryRun trigger has been recorded.
	StoryRunTriggerAnnotation = "storyrun.bubustack.io/trigger-recorded"
	// StoryRunTriggerTokenAnnotation stores the trigger token recorded on a StoryRun.
	StoryRunTriggerTokenAnnotation = "storyrun.bubustack.io/trigger-token"
	// StepAnnotation stores the owning step name on an annotated resource.
	StepAnnotation = "bubustack.io/step"
	// ResolvedInputsAnnotation stores resolved step inputs materialized by the controller.
	ResolvedInputsAnnotation = "bubustack.io/resolved-inputs"
	// EngramTLSSecretAnnotation stores the TLS secret associated with an Engram.
	EngramTLSSecretAnnotation = "engram.bubustack.io/tls-secret"
	// TLSSecretAnnotation stores a generic TLS secret reference on a workload resource.
	TLSSecretAnnotation = "bubustack.io/tls-secret"
	// StepRunTriggerAnnotation marks that a StepRun trigger has been recorded.
	StepRunTriggerAnnotation = "steprun.bubustack.io/trigger-recorded"
	// MaterializePurposeAnnotation stores why a materialization workload was created.
	MaterializePurposeAnnotation = "bubustack.io/materialize-purpose"
	// MaterializeTargetAnnotation stores the target step for a materialization workload.
	MaterializeTargetAnnotation = "bubustack.io/materialize-target-step"
	// MaterializeModeAnnotation stores the materialization mode requested by the controller.
	MaterializeModeAnnotation = "bubustack.io/materialize-mode"
	// MaterializeTransportAnnotation stores the transport selected for a materialization workload.
	MaterializeTransportAnnotation = "bubustack.io/materialize-transport"
	// CorrelationIDAnnotation stores the cross-component correlation identifier.
	CorrelationIDAnnotation = "bubustack.io/correlation-id"
)

const (
	// StoryRunTriggerTokenStory identifies Story-triggered StoryRuns.
	StoryRunTriggerTokenStory = "story"
	// StoryRunTriggerTokenImpulse identifies Impulse-triggered StoryRuns.
	StoryRunTriggerTokenImpulse = "impulse"
	// StoryRunTriggerTokenImpulseSuccess identifies success callbacks from Impulse execution.
	StoryRunTriggerTokenImpulseSuccess = "impulse-success"
	// StoryRunTriggerTokenImpulseFailed identifies failure callbacks from Impulse execution.
	StoryRunTriggerTokenImpulseFailed = "impulse-failed"
	// StepRunTriggerTokenEngram identifies Engram-triggered StepRuns.
	StepRunTriggerTokenEngram = "engram"
)

const (
	// MaxInlineSizeEnv stores the maximum size for inline payload materialization.
	MaxInlineSizeEnv = PrefixEnv + "MAX_INLINE_SIZE"
	// MediaInlineSizeEnv stores the maximum size for inline media payloads.
	MediaInlineSizeEnv = PrefixEnv + "MEDIA_INLINE_SIZE"
	// MaxRecursionDepthEnv stores the maximum shared recursion depth for evaluation helpers.
	MaxRecursionDepthEnv = PrefixEnv + "MAX_RECURSION_DEPTH"
	// StepTimeoutEnv stores the step execution timeout.
	StepTimeoutEnv = PrefixEnv + "STEP_TIMEOUT"
	// StorageTimeoutEnv stores the storage operation timeout.
	StorageTimeoutEnv = PrefixEnv + "STORAGE_TIMEOUT"
)

const (
	// HybridBridgeEnv stores the hybrid bridge mode or endpoint selection.
	HybridBridgeEnv = PrefixEnv + "HYBRID_BRIDGE"
	// HybridBridgeTimeoutEnv stores the timeout applied to hybrid bridge operations.
	HybridBridgeTimeoutEnv = PrefixEnv + "HYBRID_BRIDGE_TIMEOUT"
	// ConnectorGenerationEnv stores the connector generation expected by the workload.
	ConnectorGenerationEnv = PrefixEnv + "CONNECTOR_GENERATION"
	// GRPCLocalEndpointEnv stores the local gRPC listen endpoint for an Engram or connector.
	GRPCLocalEndpointEnv = PrefixEnv + "GRPC_LOCAL_ENDPOINT"
	// GRPCPortEnv stores the gRPC listen port.
	GRPCPortEnv = PrefixEnv + "GRPC_PORT"
)

const (
	// HubEndpointEnv stores the explicitly configured hub endpoint.
	HubEndpointEnv = PrefixEnv + "HUB_ENDPOINT"
	// HubServiceNameEnv stores the Kubernetes Service name used for hub discovery.
	HubServiceNameEnv = PrefixEnv + "HUB_SERVICE_NAME"
	// HubServiceNamespaceEnv stores the Kubernetes Service namespace used for hub discovery.
	HubServiceNamespaceEnv = PrefixEnv + "HUB_SERVICE_NAMESPACE"
	// HubClusterDomainEnv stores the cluster DNS suffix used for hub discovery.
	HubClusterDomainEnv = PrefixEnv + "HUB_CLUSTER_DOMAIN"
	// HubPortEnv stores the discovered or configured hub port.
	HubPortEnv = PrefixEnv + "HUB_PORT"
)

const (
	// HubBufferMaxMessagesEnv stores the maximum buffered message count per hub buffer.
	HubBufferMaxMessagesEnv = PrefixEnv + "HUB_BUFFER_MAX_MESSAGES"
	// HubBufferMaxBytesEnv stores the maximum buffered byte size per hub buffer.
	HubBufferMaxBytesEnv = PrefixEnv + "HUB_BUFFER_MAX_BYTES"
	// HubBufferEvictionTTLEnv stores the TTL for buffered hub messages before eviction.
	HubBufferEvictionTTLEnv = PrefixEnv + "HUB_BUFFER_EVICTION_TTL"
	// HubBufferEvictionIntervalEnv stores how often hub buffer eviction runs.
	HubBufferEvictionIntervalEnv = PrefixEnv + "HUB_BUFFER_EVICTION_INTERVAL"
	// HubBufferFlushIntervalEnv stores how often buffered hub messages are flushed.
	HubBufferFlushIntervalEnv = PrefixEnv + "HUB_BUFFER_FLUSH_INTERVAL"
	// HubPerMessageTimeoutEnv stores the timeout applied to individual hub message handling.
	HubPerMessageTimeoutEnv = PrefixEnv + "HUB_PER_MESSAGE_TIMEOUT"
	// HubJoinCacheTTLEnv stores the TTL for cached hub join state.
	HubJoinCacheTTLEnv = PrefixEnv + "HUB_JOIN_CACHE_TTL"
	// HubJoinCacheMaxEntriesEnv stores the maximum join-cache entry count.
	HubJoinCacheMaxEntriesEnv = PrefixEnv + "HUB_JOIN_CACHE_MAX_ENTRIES"
	// HubMaxActiveStreamsEnv stores the maximum number of concurrent active streams.
	HubMaxActiveStreamsEnv = PrefixEnv + "HUB_MAX_ACTIVE_STREAMS"
	// HubMaxBuffersEnv stores the maximum number of in-memory hub buffers.
	HubMaxBuffersEnv = PrefixEnv + "HUB_MAX_BUFFERS"
	// HubMaxDownstreamsEnv stores the maximum number of downstream consumers attached to a buffer.
	HubMaxDownstreamsEnv = PrefixEnv + "HUB_MAX_DOWNSTREAMS"
)

const (
	// GRPCMaxRecvBytesEnv stores the server-side maximum received gRPC message size.
	GRPCMaxRecvBytesEnv = PrefixEnv + "GRPC_MAX_RECV_BYTES"
	// GRPCMaxSendBytesEnv stores the server-side maximum sent gRPC message size.
	GRPCMaxSendBytesEnv = PrefixEnv + "GRPC_MAX_SEND_BYTES"
	// GRPCClientMaxRecvBytesEnv stores the client-side maximum received gRPC message size.
	GRPCClientMaxRecvBytesEnv = PrefixEnv + "GRPC_CLIENT_MAX_RECV_BYTES"
	// GRPCClientMaxSendBytesEnv stores the client-side maximum sent gRPC message size.
	GRPCClientMaxSendBytesEnv = PrefixEnv + "GRPC_CLIENT_MAX_SEND_BYTES"
	// GRPCDialTimeoutEnv stores the default connector dial timeout.
	GRPCDialTimeoutEnv = PrefixEnv + "GRPC_DIAL_TIMEOUT"
	// GRPCHubDialTimeoutEnv stores the timeout for dialing the transport hub.
	GRPCHubDialTimeoutEnv = PrefixEnv + "GRPC_HUB_DIAL_TIMEOUT"
	// GRPCStreamTimeoutEnv stores the timeout applied to long-lived gRPC streams.
	GRPCStreamTimeoutEnv = PrefixEnv + "GRPC_STREAM_TIMEOUT"
	// GRPCChannelBufferSizeEnv stores the connector channel buffer size.
	GRPCChannelBufferSizeEnv = PrefixEnv + "GRPC_CHANNEL_BUFFER_SIZE"
	// GRPCChannelSendTimeoutEnv stores the timeout applied to connector channel sends.
	GRPCChannelSendTimeoutEnv = PrefixEnv + "GRPC_CHANNEL_SEND_TIMEOUT"
	// GRPCMessageTimeoutEnv stores the timeout applied to single message operations.
	GRPCMessageTimeoutEnv = PrefixEnv + "GRPC_MESSAGE_TIMEOUT"
	// GRPCHangTimeoutEnv stores the timeout used when detecting hung gRPC operations.
	GRPCHangTimeoutEnv = PrefixEnv + "GRPC_HANG_TIMEOUT"
	// GRPCGracefulShutdownTimeout stores the timeout for graceful gRPC shutdown.
	GRPCGracefulShutdownTimeout = PrefixEnv + "GRPC_GRACEFUL_SHUTDOWN_TIMEOUT"
	// GRPCHeartbeatIntervalEnv stores the heartbeat interval for gRPC keepalive logic.
	GRPCHeartbeatIntervalEnv = PrefixEnv + "GRPC_HEARTBEAT_INTERVAL"
	// GRPCKeepaliveTimeEnv stores the gRPC keepalive probe interval.
	GRPCKeepaliveTimeEnv = PrefixEnv + "GRPC_KEEPALIVE_TIME"
	// GRPCKeepaliveTimeoutEnv stores the gRPC keepalive acknowledgment timeout.
	GRPCKeepaliveTimeoutEnv = PrefixEnv + "GRPC_KEEPALIVE_TIMEOUT"
)

const (
	// GRPCReconnectMaxRetriesEnv stores the maximum number of connector reconnect attempts.
	GRPCReconnectMaxRetriesEnv = PrefixEnv + "GRPC_RECONNECT_MAX_RETRIES"
	// GRPCReconnectBaseBackoffEnv stores the initial reconnect backoff duration.
	GRPCReconnectBaseBackoffEnv = PrefixEnv + "GRPC_RECONNECT_BASE_BACKOFF"
	// GRPCReconnectMaxBackoffEnv stores the maximum reconnect backoff duration.
	GRPCReconnectMaxBackoffEnv = PrefixEnv + "GRPC_RECONNECT_MAX_BACKOFF"
)

const (
	// GRPCClientTLSSecretNameEnv stores the secret name used for client TLS material.
	GRPCClientTLSSecretNameEnv = PrefixEnv + "GRPC_CLIENT_TLS_SECRET_NAME"
	// GRPCRequireTLSEnv enables or requires TLS for gRPC connections.
	GRPCRequireTLSEnv = PrefixEnv + "GRPC_REQUIRE_TLS"
	// GRPCTLSCertFileEnv stores the server TLS certificate path.
	GRPCTLSCertFileEnv = PrefixEnv + "GRPC_TLS_CERT_FILE"
	// GRPCTLSKeyFileEnv stores the server TLS private-key path.
	GRPCTLSKeyFileEnv = PrefixEnv + "GRPC_TLS_KEY_FILE"
	// GRPCCAFileEnv stores the CA bundle path used to validate peers.
	GRPCCAFileEnv = PrefixEnv + "GRPC_CA_FILE"
	// GRPCClientCertFileEnv stores the client certificate path for mTLS.
	GRPCClientCertFileEnv = PrefixEnv + "GRPC_CLIENT_CERT_FILE"
	// GRPCClientKeyFileEnv stores the client private-key path for mTLS.
	GRPCClientKeyFileEnv = PrefixEnv + "GRPC_CLIENT_KEY_FILE"
	// GRPCHubServerNameEnv stores the expected TLS server name for hub connections.
	GRPCHubServerNameEnv = PrefixEnv + "GRPC_HUB_SERVER_NAME"
	// HubTLSCertFileEnv stores the hub server TLS certificate path.
	HubTLSCertFileEnv = PrefixEnv + "HUB_TLS_CERT_FILE"
	// HubTLSKeyFileEnv stores the hub server TLS private-key path.
	HubTLSKeyFileEnv = PrefixEnv + "HUB_TLS_KEY_FILE"
	// HubCAFileEnv stores the CA bundle path used by hub TLS.
	HubCAFileEnv = PrefixEnv + "HUB_CA_FILE"
)

const (
	// StorageProviderEnv stores the selected shared storage backend.
	StorageProviderEnv = PrefixEnv + "STORAGE_PROVIDER"
	// StoragePathEnv stores the local or mounted storage path.
	StoragePathEnv = PrefixEnv + "STORAGE_PATH"
	// StorageS3BucketEnv stores the S3 bucket name used for offloaded data.
	StorageS3BucketEnv = PrefixEnv + "STORAGE_S3_BUCKET"
	// StorageS3RegionEnv stores the S3 region used for offloaded data.
	StorageS3RegionEnv = PrefixEnv + "STORAGE_S3_REGION"
	// StorageS3EndpointEnv stores the custom S3 endpoint used for offloaded data.
	StorageS3EndpointEnv = PrefixEnv + "STORAGE_S3_ENDPOINT"
)

const (
	// StorageS3MaxRetriesEnv stores the maximum retry count for S3 requests.
	StorageS3MaxRetriesEnv = PrefixEnv + "S3_MAX_RETRIES"
	// StorageS3MaxBackoffEnv stores the maximum retry backoff for S3 requests.
	StorageS3MaxBackoffEnv = PrefixEnv + "S3_MAX_BACKOFF"
	// StorageS3ForcePathStyleEnv enables path-style S3 addressing when set.
	StorageS3ForcePathStyleEnv = PrefixEnv + "S3_FORCE_PATH_STYLE"
	// StorageS3AccessKeyIDEnv stores the S3 access key identifier.
	StorageS3AccessKeyIDEnv = PrefixEnv + "S3_ACCESS_KEY_ID"
	// StorageS3SecretAccessKeyEnv stores the S3 secret access key.
	StorageS3SecretAccessKeyEnv = PrefixEnv + "S3_SECRET_ACCESS_KEY"
	// StorageS3SessionTokenEnv stores the optional S3 session token.
	StorageS3SessionTokenEnv = PrefixEnv + "S3_SESSION_TOKEN"
	// StorageS3TimeoutEnv stores the timeout applied to S3 requests.
	StorageS3TimeoutEnv = PrefixEnv + "S3_TIMEOUT"
	// StorageS3TLSEnv enables TLS for S3 endpoints when set.
	StorageS3TLSEnv = PrefixEnv + "S3_TLS"
	// StorageS3MaxPartSizeEnv stores the multipart-upload part size for S3.
	StorageS3MaxPartSizeEnv = PrefixEnv + "S3_MAX_PART_SIZE"
	// StorageS3ConcurrencyEnv stores the multipart-upload concurrency for S3.
	StorageS3ConcurrencyEnv = PrefixEnv + "S3_CONCURRENCY"
	// StorageS3SSEEnv stores the server-side encryption mode for S3 objects.
	StorageS3SSEEnv = PrefixEnv + "S3_SSE"
	// StorageS3SSEKMSKeyEnv stores the KMS key identifier used for S3 SSE-KMS.
	StorageS3SSEKMSKeyEnv = PrefixEnv + "S3_SSE_KMS_KEY"
	// StorageS3OutputPrefixEnv stores the output prefix for offloaded S3 objects.
	StorageS3OutputPrefixEnv = PrefixEnv + "STORAGE_OUTPUT_PREFIX"
	// StorageS3InputPrefixEnv stores the input prefix for offloaded S3 objects.
	StorageS3InputPrefixEnv = PrefixEnv + "STORAGE_INPUT_PREFIX"
)

const (
	// S3IntegrationEnv enables S3 integration tests or integration-only code paths when set.
	S3IntegrationEnv = PrefixEnv + "S3_INTEGRATION_ENABLED"
	// SDKMetricsEnabledEnv enables shared SDK metrics instrumentation when set.
	SDKMetricsEnabledEnv = PrefixEnv + "SDK_METRICS_ENABLED"
	// SDKTracingEnabledEnv enables shared SDK tracing instrumentation when set.
	SDKTracingEnabledEnv = PrefixEnv + "SDK_TRACING_ENABLED"
	// TracePropagationEnv enables cross-component trace propagation behavior when set.
	TracePropagationEnv = PrefixEnv + "TRACE_PROPAGATION"
	// K8sUserAgentEnv stores the Kubernetes client user-agent string.
	K8sUserAgentEnv = PrefixEnv + "K8S_USER_AGENT"
	// K8sTimeoutEnv stores the default Kubernetes client timeout.
	K8sTimeoutEnv = PrefixEnv + "K8S_TIMEOUT"
	// K8sOperationTimeoutEnv stores the timeout for individual Kubernetes operations.
	K8sOperationTimeoutEnv = PrefixEnv + "K8S_OPERATION_TIMEOUT"
	// K8sPatchMaxRetriesEnv stores the maximum retry count for Kubernetes patch operations.
	K8sPatchMaxRetriesEnv = PrefixEnv + "K8S_PATCH_MAX_RETRIES"
)

const (
	// StoryLabelKey labels resources with their owning Story.
	StoryLabelKey = "bubustack.io/story"
	// StoryNameLabelKey labels resources with a Story name field used for selectors.
	StoryNameLabelKey = "bubustack.io/story-name"
	// StepLabelKey labels resources with their owning step.
	StepLabelKey = "bubustack.io/step"
	// StepRunLabelKey labels resources with their owning StepRun.
	StepRunLabelKey = "bubustack.io/steprun"
	// StoryRunLabelKey labels resources with their owning StoryRun.
	StoryRunLabelKey = "bubustack.io/storyrun"
	// ParentStoryRunLabel labels resources with their parent StoryRun.
	ParentStoryRunLabel = "bubustack.io/parent-storyrun"
	// ParentStepLabel labels resources with their parent step.
	ParentStepLabel = "bubustack.io/parent-step"
	// LoopIndexLabelKey labels loop-generated resources with their iteration index.
	LoopIndexLabelKey = "bubustack.io/loop-index"
	// EngramLabelKey labels resources with their owning Engram.
	EngramLabelKey = "bubustack.io/engram"
	// MaterializeLabelKey labels resources created for template materialization.
	MaterializeLabelKey = "bubustack.io/materialize"
	// QueueLabelKey labels resources with the queue assigned for reconciliation.
	QueueLabelKey = "bubustack.io/queue"
	// QueuePriorityLabelKey labels resources with their queue priority.
	QueuePriorityLabelKey = "bubustack.io/queue-priority"
	// CorrelationIDLabelKey labels resources with a cross-component correlation identifier.
	CorrelationIDLabelKey = "bubustack.io/correlation-id"
)

const (
	// Engram indexes
	// IndexEngramTemplateRef indexes Engrams by their referenced EngramTemplate name.
	// Used by: EngramTemplate controller to find dependent Engrams.
	IndexEngramTemplateRef = "spec.templateRef.name"

	// StepRun indexes
	// IndexStepRunEngramRef indexes StepRuns by their Engram reference (namespaced key).
	// Format: "<namespace>/<name>"
	// Used by: StepRun controller for Engram change fan-out.
	IndexStepRunEngramRef = "spec.engramRef.key"

	// IndexStepRunStoryRunRef indexes StepRuns by their parent StoryRun name.
	// Format: "<namespace>/<name>"
	// Note: Currently used for CRD printer columns; no active controller lookups.
	// Retained for potential future use in StoryRun cleanup or status aggregation.
	IndexStepRunStoryRunRef = "spec.storyRunRef.key"

	// StoryRun indexes
	// IndexStoryRunImpulseRef indexes StoryRuns by their triggering Impulse (namespaced key).
	// Used by: Impulse controller to find runs triggered by an Impulse.
	// Format: "<namespace>/<name>"
	IndexStoryRunImpulseRef = "spec.impulseRef.key"

	// IndexStoryRunStoryRefName indexes StoryRuns by their parent Story name only.
	// Used by: Story controller for name-based lookups within a namespace.
	IndexStoryRunStoryRefName = "spec.storyRef.name"

	// IndexStoryRunStoryRefKey indexes StoryRuns by their parent Story (namespaced key).
	// Format: "<namespace>/<name>"
	// Used by: Story controller to count active runs and check deletion eligibility.
	IndexStoryRunStoryRefKey = "spec.storyRef.key"

	// Impulse indexes
	// IndexImpulseTemplateRef indexes Impulses by their referenced ImpulseTemplate name.
	// Used by: ImpulseTemplate controller to find dependent Impulses.
	IndexImpulseTemplateRef = "spec.templateRef.name"

	// IndexImpulseStoryRef indexes Impulses by their referenced Story (namespaced key).
	// Used by: Story controller to find Impulses that trigger a Story.
	// Format: "<namespace>/<name>"
	IndexImpulseStoryRef = "spec.storyRef.key"

	// Story indexes
	// IndexStoryStepEngramRefs indexes Stories by the Engrams referenced in their steps.
	// Format: "<namespace>/<name>" for each Engram reference.
	// Used by: Engram controller to find Stories that use an Engram.
	IndexStoryStepEngramRefs = "spec.steps.ref.key"

	// IndexStoryStepStoryRefs indexes Stories by the Stories referenced in execute-story steps.
	// Format: "<namespace>/<name>" for each Story reference.
	// Used by: Story controller to find Stories that execute another Story.
	IndexStoryStepStoryRefs = "spec.steps.storyRef.key"

	// IndexStoryTransportRefs indexes Stories by their transport references.
	// Used by: Transport controller to find Stories using a Transport.
	IndexStoryTransportRefs = "spec.transports.transportRef"

	// TransportBinding indexes
	// IndexTransportBindingTransportRef indexes TransportBindings by their Transport reference.
	// Used by: Transport controller to find bindings for a Transport.
	IndexTransportBindingTransportRef = "spec.transportRef"

	// EngramTemplate indexes
	// IndexEngramTemplateDescription indexes EngramTemplates by their description.
	// Note: Currently not actively used in controller lookups.
	// Retained for potential future catalog search/filter functionality.
	IndexEngramTemplateDescription = "spec.description"

	// IndexEngramTemplateVersion indexes EngramTemplates by their version.
	// Note: Currently not actively used in controller lookups.
	// Retained for potential future version-based catalog queries.
	IndexEngramTemplateVersion = "spec.version"
)

const ControllerResolveAnnotation = "bubustack.io/controller-resolve"

const PrefixEnv = "BUBU_"

const (
	// TransportSecurityModeTLS enforces TLS between engrams, connectors, and the hub.
	TransportSecurityModeTLS = "tls"
)