v1alpha1

type AudioBinding struct {
	// direction indicates whether the owning engram publishes, subscribes, or both.
	// +kubebuilder:validation:Required
	Direction MediaDirection `json:"direction"`

	// codecs enumerates the preferred codecs ordered by priority.
	// If empty, defaults to PCM16.
	// +optional
	Codecs []AudioCodec `json:"codecs,omitempty"`
}

type AudioCodec struct {
	// name of the codec (e.g., pcm16, opus, g711-mu)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=pcm16;pcm24;opus;g711-mu;g711-a;g722;aac;mp3;flac;raw
	Name string `json:"name"`

	// sampleRateHz indicates the sampling rate for this codec.
	// +optional
	SampleRateHz int32 `json:"sampleRateHz,omitempty"`

	// channels indicates the number of channels carried by this codec.
	// +optional
	Channels int32 `json:"channels,omitempty"`
}

type BinaryBinding struct {
	// direction indicates whether the owning engram publishes, subscribes, or both.
	// +kubebuilder:validation:Required
	Direction MediaDirection `json:"direction"`

	// mimeTypes enumerates supported MIME types (e.g., application/json, application/octet-stream).
	// +optional
	MimeTypes []string `json:"mimeTypes,omitempty"`
}

type BufferDropPolicy string

type DeliverySemantics string

type FlowControlMode string

type MediaDirection string

type OrderingMode string

type ReplayMode string

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

	// spec defines the desired state of Transport
	// +required
	Spec TransportSpec `json:"spec"`

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

type TransportBackpressureSettings struct {
	// Buffer configures queue limits and drop policy.
	// +optional
	Buffer *TransportBufferSettings `json:"buffer,omitempty"`
}

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

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

	// spec defines the desired state of TransportBinding
	// +required
	Spec TransportBindingSpec `json:"spec"`

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

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

type TransportBindingSpec struct {
	// transportRef references the Transport CR driving this binding.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	TransportRef string `json:"transportRef"`

	// storyRunRef identifies the StoryRun this binding belongs to when scoped to an individual run.
	// +optional
	StoryRunRef *refs.StoryRunReference `json:"storyRunRef,omitempty"`

	// stepName is the Story step that owns this binding.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	StepName string `json:"stepName"`

	// engramName is the run-specific engram backing the step.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	EngramName string `json:"engramName"`

	// driver indicates which connector driver should be used.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Driver string `json:"driver"`

	// audio describes the desired audio flow for this binding.
	// +optional
	Audio *AudioBinding `json:"audio,omitempty"`

	// video describes the desired video flow for this binding.
	// +optional
	Video *VideoBinding `json:"video,omitempty"`

	// binary describes the desired binary flow for this binding.
	// +optional
	Binary *BinaryBinding `json:"binary,omitempty"`

	// connectorEndpoint is the in-pod endpoint engrams should dial to reach the connector sidecar (e.g., 127.0.0.1:50051).
	// +optional
	ConnectorEndpoint string `json:"connectorEndpoint,omitempty"`

	// settings carries provider-specific configuration serialized as JSON.
	// +optional
	RawSettings *runtime.RawExtension `json:"rawSettings,omitempty"`
}

type TransportBindingStatus struct {
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// negotiatedAudio captures the codec the connector selected for audio.
	// +optional
	NegotiatedAudio *AudioCodec `json:"negotiatedAudio,omitempty"`

	// negotiatedVideo captures the codec the connector selected for video.
	// +optional
	NegotiatedVideo *VideoCodec `json:"negotiatedVideo,omitempty"`

	// negotiatedBinary captures the MIME type the connector selected for binary payloads.
	// +optional
	NegotiatedBinary string `json:"negotiatedBinary,omitempty"`

	// endpoint is the connector endpoint (host:port or unix socket) for this binding.
	// +optional
	Endpoint string `json:"endpoint,omitempty"`

	// downstreamHost is the resolved downstream endpoint (host:port) for the engram owning this binding.
	// This is populated when the engram can accept direct P2P connections from upstream engrams.
	// +optional
	DownstreamHost string `json:"downstreamHost,omitempty"`

	// upstreamHost is the resolved upstream endpoint (host:port) that this engram should connect to.
	// This is populated when the connection can bypass the hub and use direct P2P routing.
	// +optional
	UpstreamHost string `json:"upstreamHost,omitempty"`

	// conditions represent the current state of the TransportBinding resource.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type TransportBufferSettings struct {
	// MaxMessages caps the number of buffered messages.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxMessages *int32 `json:"maxMessages,omitempty"`

	// MaxBytes caps the total bytes buffered.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxBytes *int32 `json:"maxBytes,omitempty"`

	// MaxAgeSeconds caps the time a message can remain buffered.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxAgeSeconds *int32 `json:"maxAgeSeconds,omitempty"`

	// DropPolicy selects which messages to drop when the buffer is full.
	// +optional
	DropPolicy BufferDropPolicy `json:"dropPolicy,omitempty"`
}

type TransportDeliverySettings struct {
	// Ordering controls ordering guarantees.
	// +optional
	Ordering OrderingMode `json:"ordering,omitempty"`

	// Semantics controls delivery semantics.
	// +optional
	Semantics DeliverySemantics `json:"semantics,omitempty"`

	// Replay configures replay/retention.
	// +optional
	Replay *TransportReplaySettings `json:"replay,omitempty"`
}

type TransportFanInMode string

type TransportFanInSettings struct {
	// Mode controls whether all, any, or a quorum of upstreams are required.
	// +optional
	Mode TransportFanInMode `json:"mode,omitempty"`

	// Quorum sets the minimum number of upstreams required when Mode=quorum.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Quorum *int32 `json:"quorum,omitempty"`

	// TimeoutSeconds caps how long fan-in will wait before giving up.
	// +optional
	// +kubebuilder:validation:Minimum=0
	TimeoutSeconds *int32 `json:"timeoutSeconds,omitempty"`

	// MaxEntries caps the number of concurrent fan-in joins retained in memory.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MaxEntries *int32 `json:"maxEntries,omitempty"`
}

type TransportFanOutMode string

type TransportFlowAckSettings struct {
	// Messages is the ack interval in messages.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Messages *int32 `json:"messages,omitempty"`

	// Bytes is the ack interval in bytes.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Bytes *int32 `json:"bytes,omitempty"`

	// MaxDelay caps the time between ack/credit emissions (duration string, e.g., "250ms").
	// +optional
	MaxDelay *string `json:"maxDelay,omitempty"`
}

type TransportFlowControlSettings struct {
	// Mode selects the flow-control strategy.
	// +optional
	Mode FlowControlMode `json:"mode,omitempty"`

	// InitialCredits sets the initial credit window for credits/window mode.
	// +optional
	InitialCredits *TransportFlowCredits `json:"initialCredits,omitempty"`

	// AckEvery controls how frequently acks/credits are emitted.
	// +optional
	AckEvery *TransportFlowAckSettings `json:"ackEvery,omitempty"`

	// PauseThreshold sets the buffer utilization (0-1) that pauses upstream.
	// +optional
	PauseThreshold *TransportFlowThreshold `json:"pauseThreshold,omitempty"`

	// ResumeThreshold sets the buffer utilization (0-1) that resumes upstream.
	// +optional
	ResumeThreshold *TransportFlowThreshold `json:"resumeThreshold,omitempty"`
}

type TransportFlowCredits struct {
	// Messages is the credit window in messages.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Messages *int32 `json:"messages,omitempty"`

	// Bytes is the credit window in bytes.
	// +optional
	// +kubebuilder:validation:Minimum=0
	Bytes *int32 `json:"bytes,omitempty"`
}

type TransportFlowThreshold struct {
	// BufferPct defines the buffer utilization threshold as a percent (0-100).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	BufferPct *int32 `json:"bufferPct,omitempty"`
}

type TransportLane struct {
	// Name identifies the lane (e.g., "audio", "telemetry").
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:Pattern=^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
	Name string `json:"name"`

	// Kind declares the lane media/payload type.
	// +kubebuilder:validation:Required
	Kind TransportLaneKind `json:"kind"`

	// Direction declares whether the lane is publish/subscribe/bidirectional.
	// +optional
	Direction TransportLaneDirection `json:"direction,omitempty"`

	// Description provides optional human-readable context.
	// +optional
	Description string `json:"description,omitempty"`

	// MaxMessages caps buffered messages for this lane (applies per downstream).
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxMessages *int32 `json:"maxMessages,omitempty"`

	// MaxBytes caps buffered bytes for this lane (applies per downstream).
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxBytes *int32 `json:"maxBytes,omitempty"`
}

type TransportLaneDirection string

type TransportLaneKind string

type TransportLifecycleSettings struct {
	// Strategy controls upgrade behavior for streaming workloads.
	// +optional
	Strategy TransportUpgradeStrategy `json:"strategy,omitempty"`

	// DrainTimeoutSeconds caps how long to drain in-flight messages before cutover.
	// +optional
	// +kubebuilder:validation:Minimum=0
	DrainTimeoutSeconds *int32 `json:"drainTimeoutSeconds,omitempty"`

	// MaxInFlight caps the number of in-flight messages allowed during upgrades.
	// +optional
	// +kubebuilder:validation:Minimum=0
	MaxInFlight *int32 `json:"maxInFlight,omitempty"`
}

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

type TransportMetricsSettings struct {
	// Enabled toggles metrics emission (default true).
	// +optional
	Enabled *bool `json:"enabled,omitempty"`
}

type TransportObservabilitySettings struct {
	// Metrics controls per-lane and hub-level metrics emission.
	// +optional
	Metrics *TransportMetricsSettings `json:"metrics,omitempty"`

	// Tracing controls distributed tracing hooks.
	// +optional
	Tracing *TransportTracingSettings `json:"tracing,omitempty"`

	// Watermark controls event-time watermark/lag tracking.
	// +optional
	Watermark *TransportWatermarkSettings `json:"watermark,omitempty"`
}

type TransportPartitionMode string

type TransportPartitioningSettings struct {
	// Mode selects how to assign partition IDs.
	// +optional
	Mode TransportPartitionMode `json:"mode,omitempty"`

	// Key selects the value used for hash partitioning (e.g., "metadata.user_id" or "payload.session").
	// +optional
	Key *string `json:"key,omitempty"`

	// Partitions sets the total number of partitions used for hash mode.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Partitions *int32 `json:"partitions,omitempty"`

	// Sticky keeps an existing partition assignment if present.
	// +optional
	Sticky *bool `json:"sticky,omitempty"`
}

type TransportRecordingMode string

type TransportRecordingSettings struct {
	// Mode controls whether metadata-only or full payloads are recorded.
	// +optional
	Mode TransportRecordingMode `json:"mode,omitempty"`

	// SampleRate controls recording sampling percentage (0..100).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	SampleRate *int32 `json:"sampleRate,omitempty"`

	// RetentionSeconds sets how long recordings should be retained.
	// +optional
	// +kubebuilder:validation:Minimum=0
	RetentionSeconds *int32 `json:"retentionSeconds,omitempty"`

	// RedactFields lists JSON field paths to redact (e.g., "payload.api_key").
	// +optional
	RedactFields []string `json:"redactFields,omitempty"`
}

type TransportReplaySettings struct {
	// Mode selects replay storage mode.
	// +optional
	Mode ReplayMode `json:"mode,omitempty"`

	// RetentionSeconds sets how long replay data is retained.
	// +optional
	// +kubebuilder:validation:Minimum=0
	RetentionSeconds *int32 `json:"retentionSeconds,omitempty"`

	// CheckpointInterval sets how frequently checkpoints are persisted (duration string, e.g., "1s").
	// +optional
	CheckpointInterval *string `json:"checkpointInterval,omitempty"`
}

type TransportRoutingMode string

type TransportRoutingRule struct {
	// Name is an optional identifier for observability/debugging.
	// +optional
	Name string `json:"name,omitempty"`

	// When is a Go template expression evaluated against the streaming runtime scope.
	// +optional
	When *string `json:"when,omitempty"`

	// Action controls whether matching targets are allowed or denied.
	// +optional
	Action TransportRoutingRuleAction `json:"action,omitempty"`

	// Target selects which downstream steps this rule applies to.
	// +optional
	Target *TransportRoutingRuleTarget `json:"target,omitempty"`
}

type TransportRoutingRuleAction string

type TransportRoutingRuleTarget struct {
	// Steps lists downstream step names that the rule applies to. Empty means all downstream steps.
	// +optional
	Steps []string `json:"steps,omitempty"`
}

type TransportRoutingSettings struct {
	// Mode selects the routing topology (auto chooses based on DAG analysis).
	// +optional
	Mode TransportRoutingMode `json:"mode,omitempty"`

	// FanOut controls dispatch when multiple downstream steps consume a stream.
	// +optional
	FanOut TransportFanOutMode `json:"fanOut,omitempty"`

	// MaxDownstreams caps the number of downstream targets per step (guardrail).
	// +optional
	// +kubebuilder:validation:Minimum=1
	MaxDownstreams *int32 `json:"maxDownstreams,omitempty"`

	// Rules define conditional routing filters evaluated per packet.
	// +optional
	Rules []TransportRoutingRule `json:"rules,omitempty"`
}

type TransportSpec struct {
	// provider is the human-readable provider name (e.g., livekit, twilio, custom).
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Provider string `json:"provider"`

	// driver is the connector driver identifier that should be used for bindings.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Driver string `json:"driver"`

	// connectorImage optionally declares the recommended connector image implementing this driver.
	// +optional
	ConnectorImage string `json:"connectorImage,omitempty"`

	// supportedAudio lists the audio codecs supported by this transport.
	// +optional
	SupportedAudio []AudioCodec `json:"supportedAudio,omitempty"`

	// supportedVideo lists the video codecs supported by this transport.
	// +optional
	SupportedVideo []VideoCodec `json:"supportedVideo,omitempty"`

	// supportedBinary lists MIME types supported for generic binary payloads.
	// +optional
	SupportedBinary []string `json:"supportedBinary,omitempty"`

	// streaming configures default streaming policies such as backpressure, flow control, and delivery.
	// +optional
	Streaming *TransportStreamingSettings `json:"streaming,omitempty"`

	// configSchema optionally captures a JSONSchema for provider-specific settings.
	// +optional
	ConfigSchema *runtime.RawExtension `json:"configSchema,omitempty"`

	// defaultSettings contains default provider-specific settings serialized as JSON.
	// +optional
	DefaultSettings *runtime.RawExtension `json:"defaultSettings,omitempty"`
}

type TransportStatus struct {
	ObservedGeneration int64                  `json:"observedGeneration,omitempty"`
	ValidationStatus   enums.ValidationStatus `json:"validationStatus,omitempty"`
	ValidationErrors   []string               `json:"validationErrors,omitempty"`
	UsageCount         int32                  `json:"usageCount,omitempty"`
	// negotiatedAudio lists the codecs the connector actually exposes/negotiates.
	// +optional
	AvailableAudio []AudioCodec `json:"availableAudio,omitempty"`
	// negotiatedVideo lists the video codecs the connector supports.
	// +optional
	AvailableVideo []VideoCodec `json:"availableVideo,omitempty"`
	// negotiatedBinary lists MIME types the connector supports for binary payloads.
	// +optional
	AvailableBinary []string `json:"availableBinary,omitempty"`
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
	// pendingBindings tracks how many bindings still await negotiation.
	// +optional
	PendingBindings int32 `json:"pendingBindings,omitempty"`
	// lastHeartbeat records when a binding last reported capabilities.
	// +optional
	LastHeartbeatTime *metav1.Time `json:"lastHeartbeatTime,omitempty"`
}

type TransportStreamingSettings struct {
	// Backpressure configures buffer limits and overflow behavior.
	// +optional
	Backpressure *TransportBackpressureSettings `json:"backpressure,omitempty"`

	// FlowControl configures credit/window-based flow control.
	// +optional
	FlowControl *TransportFlowControlSettings `json:"flowControl,omitempty"`

	// Delivery configures ordering, delivery semantics, and replay.
	// +optional
	Delivery *TransportDeliverySettings `json:"delivery,omitempty"`

	// Routing configures topology selection and fan-out policy.
	// +optional
	Routing *TransportRoutingSettings `json:"routing,omitempty"`

	// Lanes declares named streaming lanes (audio/video/binary/payload) and per-lane caps.
	// +optional
	Lanes []TransportLane `json:"lanes,omitempty"`

	// FanIn configures how multiple upstream steps are joined at fan-in points.
	// +optional
	FanIn *TransportFanInSettings `json:"fanIn,omitempty"`

	// Partitioning configures partition assignment for streaming envelopes.
	// +optional
	Partitioning *TransportPartitioningSettings `json:"partitioning,omitempty"`

	// Lifecycle configures drain/cutover and in-flight guardrails.
	// +optional
	Lifecycle *TransportLifecycleSettings `json:"lifecycle,omitempty"`

	// Observability configures metrics, tracing, and watermark tracking.
	// +optional
	Observability *TransportObservabilitySettings `json:"observability,omitempty"`

	// Recording configures optional stream recording/sampling behavior.
	// +optional
	Recording *TransportRecordingSettings `json:"recording,omitempty"`
}

type TransportTracingSettings struct {
	// Enabled toggles tracing emission (default true).
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// SampleRate controls sampling percentage (0..100).
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	SampleRate *int32 `json:"sampleRate,omitempty"`

	// SamplePolicy selects the sampling policy (e.g., "rate", "rules").
	// +optional
	SamplePolicy *string `json:"samplePolicy,omitempty"`
}

type TransportUpgradeStrategy string

type TransportWatermarkSettings struct {
	// Enabled toggles watermark and lag tracking.
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// TimestampSource selects the source for event-time timestamps (e.g., "metadata.event_time_ms").
	// +optional
	TimestampSource *string `json:"timestampSource,omitempty"`
}

type VideoBinding struct {
	// direction indicates whether the owning engram publishes, subscribes, or both.
	// +kubebuilder:validation:Required
	Direction MediaDirection `json:"direction"`

	// codecs enumerates supported codecs. Encoded pass-through drivers should
	// declare the codecs they can forward.
	// +optional
	Codecs []VideoCodec `json:"codecs,omitempty"`

	// raw indicates whether raw frames are required for processing (e.g., CV tasks).
	// Drivers may use this hint to determine if decoding is necessary.
	// +optional
	Raw bool `json:"raw,omitempty"`
}

type VideoCodec struct {
	// name of the codec (e.g., h264, vp8, raw-yuv420)
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=h264;vp8;vp9;av1;raw-yuv420;raw-rgb;raw-bgr
	Name string `json:"name"`

	// profile or format hint (e.g., baseline, high, rgb)
	// +optional
	Profile string `json:"profile,omitempty"`
}