feat: initialize k-tv-frontend with Next.js and Tailwind CSS

- Added package.json with dependencies and scripts for development, build, and linting.
- Created postcss.config.mjs for Tailwind CSS integration.
- Added SVG assets for UI components including file, globe, next, vercel, and window icons.
- Configured TypeScript with tsconfig.json for strict type checking and module resolution.

k-tv-backend/domain/src/entities.rs

@@ -0,0 +1,296 @@
+//! Domain entities
+//!
+//! This module contains pure domain types with no I/O dependencies.
+//! These represent the core business concepts of the application.
+
+pub use crate::value_objects::{Email, UserId};
+use chrono::{DateTime, NaiveTime, Timelike, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::value_objects::{
+    BlockId, ChannelId, ContentType, FillStrategy, MediaFilter, MediaItemId, RecyclePolicy, SlotId,
+};
+
+/// A user in the system.
+///
+/// Designed to be OIDC-ready: the `subject` field stores the OIDC subject claim
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct User {
+    pub id: UserId,
+    pub subject: String,
+    pub email: Email,
+    pub password_hash: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
+
+impl User {
+    pub fn new(subject: impl Into<String>, email: Email) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            subject: subject.into(),
+            email,
+            password_hash: None,
+            created_at: Utc::now(),
+        }
+    }
+
+    pub fn with_id(
+        id: Uuid,
+        subject: impl Into<String>,
+        email: Email,
+        password_hash: Option<String>,
+        created_at: DateTime<Utc>,
+    ) -> Self {
+        Self {
+            id,
+            subject: subject.into(),
+            email,
+            password_hash,
+            created_at,
+        }
+    }
+
+    pub fn new_local(email: Email, password_hash: impl Into<String>) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            subject: format!("local|{}", Uuid::new_v4()),
+            email,
+            password_hash: Some(password_hash.into()),
+            created_at: Utc::now(),
+        }
+    }
+}
+
+// ============================================================================
+// Channel
+// ============================================================================
+
+/// A broadcast channel owned by a user.
+///
+/// Holds the user-designed `ScheduleConfig` (the template) and `RecyclePolicy`.
+/// The engine consumes these to produce a concrete `GeneratedSchedule`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Channel {
+    pub id: ChannelId,
+    pub owner_id: UserId,
+    pub name: String,
+    pub description: Option<String>,
+    /// IANA timezone string, e.g. `"America/New_York"`. All `start_time` fields
+    /// inside `ScheduleConfig` are interpreted in this timezone.
+    pub timezone: String,
+    pub schedule_config: ScheduleConfig,
+    pub recycle_policy: RecyclePolicy,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl Channel {
+    pub fn new(
+        owner_id: UserId,
+        name: impl Into<String>,
+        timezone: impl Into<String>,
+    ) -> Self {
+        let now = Utc::now();
+        Self {
+            id: Uuid::new_v4(),
+            owner_id,
+            name: name.into(),
+            description: None,
+            timezone: timezone.into(),
+            schedule_config: ScheduleConfig::default(),
+            recycle_policy: RecyclePolicy::default(),
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+/// The user-designed programming template.
+///
+/// This is the shareable/exportable part of a channel. It contains an ordered
+/// list of `ProgrammingBlock`s but makes no assumptions about the media source.
+/// A channel does not need to cover all 24 hours — gaps are valid and render
+/// as a no-signal state on the client.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct ScheduleConfig {
+    pub blocks: Vec<ProgrammingBlock>,
+}
+
+impl ScheduleConfig {
+    /// Return the block whose time window contains `time`, if any.
+    ///
+    /// Handles blocks that span midnight (e.g. start 23:00, duration 180 min).
+    pub fn find_block_at(&self, time: NaiveTime) -> Option<&ProgrammingBlock> {
+        let secs = time.num_seconds_from_midnight();
+        self.blocks.iter().find(|block| {
+            let start = block.start_time.num_seconds_from_midnight();
+            let end = start + block.duration_mins * 60;
+            if end <= 86_400 {
+                secs >= start && secs < end
+            } else {
+                // Block crosses midnight: active from `start` to `end % 86400` next day
+                secs >= start || secs < (end % 86_400)
+            }
+        })
+    }
+
+    /// Return the start time of the next block that begins strictly after `time`,
+    /// within the same calendar day.
+    pub fn next_block_start_after(&self, time: NaiveTime) -> Option<NaiveTime> {
+        let secs = time.num_seconds_from_midnight();
+        self.blocks
+            .iter()
+            .map(|b| b.start_time.num_seconds_from_midnight())
+            .filter(|&s| s > secs)
+            .min()
+            .and_then(|s| NaiveTime::from_num_seconds_from_midnight_opt(s, 0))
+    }
+
+    /// The earliest block start time across all blocks (used for next-day rollover).
+    pub fn earliest_block_start(&self) -> Option<NaiveTime> {
+        self.blocks.iter().map(|b| b.start_time).min()
+    }
+}
+
+/// A single programming rule within a `ScheduleConfig`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProgrammingBlock {
+    pub id: BlockId,
+    pub name: String,
+    /// Local time of day (in the channel's timezone) when this block starts.
+    pub start_time: NaiveTime,
+    /// Target duration in minutes. The engine fills this window as closely as
+    /// possible; remaining time at the end becomes dead air (no-signal).
+    pub duration_mins: u32,
+    pub content: BlockContent,
+}
+
+impl ProgrammingBlock {
+    pub fn new_algorithmic(
+        name: impl Into<String>,
+        start_time: NaiveTime,
+        duration_mins: u32,
+        filter: MediaFilter,
+        strategy: FillStrategy,
+    ) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            name: name.into(),
+            start_time,
+            duration_mins,
+            content: BlockContent::Algorithmic { filter, strategy },
+        }
+    }
+
+    pub fn new_manual(
+        name: impl Into<String>,
+        start_time: NaiveTime,
+        duration_mins: u32,
+        items: Vec<MediaItemId>,
+    ) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            name: name.into(),
+            start_time,
+            duration_mins,
+            content: BlockContent::Manual { items },
+        }
+    }
+}
+
+/// How the content of a `ProgrammingBlock` is determined.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum BlockContent {
+    /// The user hand-picked specific items in a specific order.
+    Manual { items: Vec<MediaItemId> },
+    /// The engine selects items from the provider using the given filter and strategy.
+    Algorithmic {
+        filter: MediaFilter,
+        strategy: FillStrategy,
+    },
+}
+
+// ============================================================================
+// Media / Schedule resolution types
+// ============================================================================
+
+/// A snapshot of a media item's metadata at schedule-generation time.
+///
+/// Stream URLs are intentionally absent — they are fetched on-demand from the
+/// provider at tune-in time so they stay fresh and provider-agnostic.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MediaItem {
+    pub id: MediaItemId,
+    pub title: String,
+    pub content_type: ContentType,
+    pub duration_secs: u32,
+    pub genres: Vec<String>,
+    pub year: Option<u16>,
+    pub tags: Vec<String>,
+}
+
+/// A fully resolved 48-hour broadcast program for one channel.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GeneratedSchedule {
+    pub id: Uuid,
+    pub channel_id: ChannelId,
+    pub valid_from: DateTime<Utc>,
+    pub valid_until: DateTime<Utc>,
+    /// Monotonically increasing counter per channel, used by `RecyclePolicy`.
+    pub generation: u32,
+    /// Resolved slots, sorted ascending by `start_at`.
+    pub slots: Vec<ScheduledSlot>,
+}
+
+impl GeneratedSchedule {
+    pub fn is_active_at(&self, time: DateTime<Utc>) -> bool {
+        time >= self.valid_from && time < self.valid_until
+    }
+}
+
+/// A single resolved broadcast moment within a `GeneratedSchedule`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ScheduledSlot {
+    pub id: SlotId,
+    pub start_at: DateTime<Utc>,
+    pub end_at: DateTime<Utc>,
+    /// Metadata snapshot captured at schedule-generation time.
+    pub item: MediaItem,
+    /// Which `ProgrammingBlock` rule produced this slot.
+    pub source_block_id: BlockId,
+}
+
+/// What is currently broadcasting on a channel — derived from `GeneratedSchedule`
+/// and the wall clock. Never stored. `None` means no block is scheduled right now
+/// (dead air / no-signal).
+#[derive(Debug, Clone)]
+pub struct CurrentBroadcast {
+    pub slot: ScheduledSlot,
+    /// Seconds elapsed since the start of the current item.
+    pub offset_secs: u32,
+}
+
+/// Records that an item was aired on a channel. Persisted to drive `RecyclePolicy`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PlaybackRecord {
+    pub id: Uuid,
+    pub channel_id: ChannelId,
+    pub item_id: MediaItemId,
+    pub played_at: DateTime<Utc>,
+    /// The generation of the schedule that scheduled this play.
+    pub generation: u32,
+}
+
+impl PlaybackRecord {
+    pub fn new(channel_id: ChannelId, item_id: MediaItemId, generation: u32) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            channel_id,
+            item_id,
+            played_at: Utc::now(),
+            generation,
+        }
+    }
+}

k-tv-backend/domain/src/errors.rs

@@ -0,0 +1,92 @@
+//! Domain errors for K-Notes
+//!
+//! Uses `thiserror` for ergonomic error definitions.
+//! These errors represent domain-level failures and will be mapped
+//! to HTTP status codes in the API layer.
+
+use thiserror::Error;
+use uuid::Uuid;
+
+/// Domain-level errors for K-TV operations
+#[derive(Debug, Error)]
+#[non_exhaustive]
+pub enum DomainError {
+    /// The requested user was not found
+    #[error("User not found: {0}")]
+    UserNotFound(Uuid),
+
+    /// User with this email/subject already exists
+    #[error("User already exists: {0}")]
+    UserAlreadyExists(String),
+
+    /// The requested channel was not found
+    #[error("Channel not found: {0}")]
+    ChannelNotFound(Uuid),
+
+    /// No generated schedule exists and is active for the given channel and time
+    #[error("No active schedule for channel: {0}")]
+    NoActiveSchedule(Uuid),
+
+    /// A validation error occurred
+    #[error("Validation error: {0}")]
+    ValidationError(String),
+
+    /// A timezone string could not be parsed
+    #[error("Invalid timezone: {0}")]
+    TimezoneError(String),
+
+    /// User is not authenticated (maps to HTTP 401)
+    #[error("Unauthenticated: {0}")]
+    Unauthenticated(String),
+
+    /// User is not allowed to perform this action (maps to HTTP 403)
+    #[error("Forbidden: {0}")]
+    Forbidden(String),
+
+    /// A repository/infrastructure error occurred
+    #[error("Repository error: {0}")]
+    RepositoryError(String),
+
+    /// An infrastructure adapter error occurred
+    #[error("Infrastructure error: {0}")]
+    InfrastructureError(String),
+}
+
+impl DomainError {
+    /// Create a validation error
+    pub fn validation(message: impl Into<String>) -> Self {
+        Self::ValidationError(message.into())
+    }
+
+    /// Create an unauthenticated error (not logged in → 401)
+    pub fn unauthenticated(message: impl Into<String>) -> Self {
+        Self::Unauthenticated(message.into())
+    }
+
+    /// Create a forbidden error (not allowed → 403)
+    pub fn forbidden(message: impl Into<String>) -> Self {
+        Self::Forbidden(message.into())
+    }
+
+    /// Check if this error indicates a "not found" condition
+    pub fn is_not_found(&self) -> bool {
+        matches!(
+            self,
+            DomainError::UserNotFound(_) | DomainError::ChannelNotFound(_)
+        )
+    }
+
+    /// Check if this error indicates a conflict (already exists)
+    pub fn is_conflict(&self) -> bool {
+        matches!(self, DomainError::UserAlreadyExists(_))
+    }
+}
+
+impl From<crate::value_objects::ValidationError> for DomainError {
+    fn from(error: crate::value_objects::ValidationError) -> Self {
+        DomainError::ValidationError(error.to_string())
+    }
+}
+
+/// Result type alias for domain operations
+pub type DomainResult<T> = Result<T, DomainError>;

k-tv-backend/domain/src/lib.rs

@@ -0,0 +1,19 @@
+//! Domain Logic
+//!
+//! This crate contains the core business logic, entities, and repository interfaces.
+//! It is completely independent of the infrastructure layer (databases, HTTP, etc.).
+
+pub mod entities;
+pub mod errors;
+pub mod ports;
+pub mod repositories;
+pub mod services;
+pub mod value_objects;
+
+// Re-export commonly used types
+pub use entities::*;
+pub use errors::{DomainError, DomainResult};
+pub use ports::IMediaProvider;
+pub use repositories::*;
+pub use services::{ChannelService, ScheduleEngineService, UserService};
+pub use value_objects::*;

k-tv-backend/domain/src/ports.rs

@@ -0,0 +1,39 @@
+//! Provider ports
+//!
+//! Abstract interfaces for fetching media from any source.
+//! The domain never knows whether the backing provider is Jellyfin, Plex,
+//! a local filesystem, or anything else — adapters in the infra crate implement
+//! these traits for each concrete source.
+
+use async_trait::async_trait;
+
+use crate::entities::{MediaItem};
+use crate::errors::DomainResult;
+use crate::value_objects::{MediaFilter, MediaItemId};
+
+/// Port for reading media content from an external provider.
+///
+/// Implementations live in the infra layer. One adapter per provider type
+/// (e.g. `JellyfinMediaProvider`, `PlexMediaProvider`, `LocalFileProvider`).
+#[async_trait]
+pub trait IMediaProvider: Send + Sync {
+    /// Fetch metadata for all items matching `filter` from this provider.
+    ///
+    /// The provider interprets each field of `MediaFilter` in terms of its own
+    /// API (e.g. Jellyfin libraries, Plex sections, filesystem paths).
+    /// Returns an empty vec — not an error — when nothing matches.
+    async fn fetch_items(&self, filter: &MediaFilter) -> DomainResult<Vec<MediaItem>>;
+
+    /// Fetch metadata for a single item by its opaque ID.
+    ///
+    /// Used by the scheduler when resolving `BlockContent::Manual` blocks, where
+    /// the user has hand-picked specific items. Returns `None` if the item no
+    /// longer exists in the provider (deleted, unavailable, etc.).
+    async fn fetch_by_id(&self, item_id: &MediaItemId) -> DomainResult<Option<MediaItem>>;
+
+    /// Get a playback URL for an item, called on-demand at tune-in time.
+    ///
+    /// URLs are intentionally *not* stored in the schedule because they may be
+    /// short-lived (signed URLs, session tokens) or depend on client context.
+    async fn get_stream_url(&self, item_id: &MediaItemId) -> DomainResult<String>;
+}

k-tv-backend/domain/src/repositories.rs

@@ -0,0 +1,71 @@
+//! Repository ports (traits)
+//!
+//! These traits define the interface for data persistence.
+//! Implementations live in the infra layer.
+
+use async_trait::async_trait;
+use chrono::DateTime;
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::entities::{Channel, GeneratedSchedule, PlaybackRecord, User};
+use crate::errors::DomainResult;
+use crate::value_objects::{ChannelId, UserId};
+
+/// Repository port for User persistence
+#[async_trait]
+pub trait UserRepository: Send + Sync {
+    /// Find a user by their internal ID
+    async fn find_by_id(&self, id: Uuid) -> DomainResult<Option<User>>;
+
+    /// Find a user by their OIDC subject (used for authentication)
+    async fn find_by_subject(&self, subject: &str) -> DomainResult<Option<User>>;
+
+    /// Find a user by their email
+    async fn find_by_email(&self, email: &str) -> DomainResult<Option<User>>;
+
+    /// Save a new user or update an existing one
+    async fn save(&self, user: &User) -> DomainResult<()>;
+
+    /// Delete a user by their ID
+    async fn delete(&self, id: Uuid) -> DomainResult<()>;
+}
+
+/// Repository port for `Channel` persistence.
+#[async_trait]
+pub trait ChannelRepository: Send + Sync {
+    async fn find_by_id(&self, id: ChannelId) -> DomainResult<Option<Channel>>;
+    async fn find_by_owner(&self, owner_id: UserId) -> DomainResult<Vec<Channel>>;
+    /// Insert or update a channel.
+    async fn save(&self, channel: &Channel) -> DomainResult<()>;
+    async fn delete(&self, id: ChannelId) -> DomainResult<()>;
+}
+
+/// Repository port for `GeneratedSchedule` and `PlaybackRecord` persistence.
+#[async_trait]
+pub trait ScheduleRepository: Send + Sync {
+    /// Find the schedule whose `[valid_from, valid_until)` window contains `at`.
+    async fn find_active(
+        &self,
+        channel_id: ChannelId,
+        at: DateTime<Utc>,
+    ) -> DomainResult<Option<GeneratedSchedule>>;
+
+    /// Find the most recently generated schedule for a channel.
+    /// Used to derive the next generation number.
+    async fn find_latest(
+        &self,
+        channel_id: ChannelId,
+    ) -> DomainResult<Option<GeneratedSchedule>>;
+
+    /// Insert or replace a generated schedule.
+    async fn save(&self, schedule: &GeneratedSchedule) -> DomainResult<()>;
+
+    /// All playback records for a channel, used by the recycle policy engine.
+    async fn find_playback_history(
+        &self,
+        channel_id: ChannelId,
+    ) -> DomainResult<Vec<PlaybackRecord>>;
+
+    async fn save_playback_record(&self, record: &PlaybackRecord) -> DomainResult<()>;
+}

k-tv-backend/domain/src/services.rs

@@ -0,0 +1,565 @@
+//! Domain Services
+//!
+//! Services contain the business logic of the application.
+
+use std::collections::HashSet;
+use std::sync::Arc;
+
+use chrono::{DateTime, Duration, TimeZone, Utc};
+use chrono_tz::Tz;
+use rand::seq::SliceRandom;
+use uuid::Uuid;
+
+use crate::entities::{
+    BlockContent, CurrentBroadcast, GeneratedSchedule, MediaItem, PlaybackRecord,
+    ProgrammingBlock, ScheduledSlot,
+};
+use crate::errors::{DomainError, DomainResult};
+use crate::ports::IMediaProvider;
+use crate::repositories::{ChannelRepository, ScheduleRepository, UserRepository};
+use crate::value_objects::{
+    BlockId, ChannelId, Email, FillStrategy, MediaFilter, MediaItemId, RecyclePolicy,
+};
+
+// ============================================================================
+// UserService
+// ============================================================================
+
+/// Service for managing users.
+pub struct UserService {
+    user_repository: Arc<dyn UserRepository>,
+}
+
+impl UserService {
+    pub fn new(user_repository: Arc<dyn UserRepository>) -> Self {
+        Self { user_repository }
+    }
+
+    pub async fn find_or_create(&self, subject: &str, email: &str) -> DomainResult<crate::entities::User> {
+        if let Some(user) = self.user_repository.find_by_subject(subject).await? {
+            return Ok(user);
+        }
+
+        if let Some(mut user) = self.user_repository.find_by_email(email).await? {
+            if user.subject != subject {
+                user.subject = subject.to_string();
+                self.user_repository.save(&user).await?;
+            }
+            return Ok(user);
+        }
+
+        let email = Email::try_from(email)?;
+        let user = crate::entities::User::new(subject, email);
+        self.user_repository.save(&user).await?;
+        Ok(user)
+    }
+
+    pub async fn find_by_id(&self, id: Uuid) -> DomainResult<crate::entities::User> {
+        self.user_repository
+            .find_by_id(id)
+            .await?
+            .ok_or(DomainError::UserNotFound(id))
+    }
+
+    pub async fn find_by_email(&self, email: &str) -> DomainResult<Option<crate::entities::User>> {
+        self.user_repository.find_by_email(email).await
+    }
+
+    pub async fn create_local(
+        &self,
+        email: &str,
+        password_hash: &str,
+    ) -> DomainResult<crate::entities::User> {
+        let email = Email::try_from(email)?;
+        let user = crate::entities::User::new_local(email, password_hash);
+        self.user_repository.save(&user).await?;
+        Ok(user)
+    }
+}
+
+// ============================================================================
+// ChannelService
+// ============================================================================
+
+/// Service for managing channels (CRUD + ownership enforcement).
+pub struct ChannelService {
+    channel_repo: Arc<dyn ChannelRepository>,
+}
+
+impl ChannelService {
+    pub fn new(channel_repo: Arc<dyn ChannelRepository>) -> Self {
+        Self { channel_repo }
+    }
+
+    pub async fn create(
+        &self,
+        owner_id: crate::value_objects::UserId,
+        name: &str,
+        timezone: &str,
+    ) -> DomainResult<crate::entities::Channel> {
+        let channel = crate::entities::Channel::new(owner_id, name, timezone);
+        self.channel_repo.save(&channel).await?;
+        Ok(channel)
+    }
+
+    pub async fn find_by_id(
+        &self,
+        id: ChannelId,
+    ) -> DomainResult<crate::entities::Channel> {
+        self.channel_repo
+            .find_by_id(id)
+            .await?
+            .ok_or(DomainError::ChannelNotFound(id))
+    }
+
+    pub async fn find_by_owner(
+        &self,
+        owner_id: crate::value_objects::UserId,
+    ) -> DomainResult<Vec<crate::entities::Channel>> {
+        self.channel_repo.find_by_owner(owner_id).await
+    }
+
+    pub async fn update(
+        &self,
+        channel: crate::entities::Channel,
+    ) -> DomainResult<crate::entities::Channel> {
+        self.channel_repo.save(&channel).await?;
+        Ok(channel)
+    }
+
+    /// Delete a channel, enforcing that `requester_id` is the owner.
+    pub async fn delete(
+        &self,
+        id: ChannelId,
+        requester_id: crate::value_objects::UserId,
+    ) -> DomainResult<()> {
+        let channel = self.find_by_id(id).await?;
+        if channel.owner_id != requester_id {
+            return Err(DomainError::forbidden("You don't own this channel"));
+        }
+        self.channel_repo.delete(id).await
+    }
+}
+
+// ============================================================================
+// ScheduleEngineService
+// ============================================================================
+
+/// Core scheduling engine.
+///
+/// Generates 48-hour broadcast schedules by walking through a channel's
+/// `ScheduleConfig` day by day, resolving each `ProgrammingBlock` into concrete
+/// `ScheduledSlot`s via the `IMediaProvider`, and applying the `RecyclePolicy`
+/// to avoid replaying recently aired items.
+pub struct ScheduleEngineService {
+    media_provider: Arc<dyn IMediaProvider>,
+    channel_repo: Arc<dyn ChannelRepository>,
+    schedule_repo: Arc<dyn ScheduleRepository>,
+}
+
+impl ScheduleEngineService {
+    pub fn new(
+        media_provider: Arc<dyn IMediaProvider>,
+        channel_repo: Arc<dyn ChannelRepository>,
+        schedule_repo: Arc<dyn ScheduleRepository>,
+    ) -> Self {
+        Self {
+            media_provider,
+            channel_repo,
+            schedule_repo,
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+
+    /// Generate and persist a 48-hour schedule for `channel_id` starting at `from`.
+    ///
+    /// The algorithm:
+    /// 1. Walk each calendar day in the 48-hour window.
+    /// 2. For each `ProgrammingBlock`, compute its UTC wall-clock interval for that day.
+    /// 3. Clip the interval to `[from, from + 48h)`.
+    /// 4. Resolve the block content via the media provider, applying the recycle policy.
+    /// 5. Record every played item in the playback history.
+    ///
+    /// Gaps between blocks are left empty — clients render them as a no-signal state.
+    pub async fn generate_schedule(
+        &self,
+        channel_id: ChannelId,
+        from: DateTime<Utc>,
+    ) -> DomainResult<GeneratedSchedule> {
+        let channel = self
+            .channel_repo
+            .find_by_id(channel_id)
+            .await?
+            .ok_or(DomainError::ChannelNotFound(channel_id))?;
+
+        let tz: Tz = channel
+            .timezone
+            .parse()
+            .map_err(|_| DomainError::TimezoneError(channel.timezone.clone()))?;
+
+        let history = self
+            .schedule_repo
+            .find_playback_history(channel_id)
+            .await?;
+
+        let generation = self
+            .schedule_repo
+            .find_latest(channel_id)
+            .await?
+            .map(|s| s.generation + 1)
+            .unwrap_or(1);
+
+        let valid_from = from;
+        let valid_until = from + Duration::hours(48);
+
+        let start_date = from.with_timezone(&tz).date_naive();
+        let end_date = valid_until.with_timezone(&tz).date_naive();
+
+        let mut slots: Vec<ScheduledSlot> = Vec::new();
+        let mut current_date = start_date;
+
+        while current_date <= end_date {
+            for block in &channel.schedule_config.blocks {
+                let naive_start = current_date.and_time(block.start_time);
+
+                // `earliest()` handles DST gaps — if the local time doesn't exist
+                // (e.g. clocks spring forward) we skip this block occurrence.
+                let block_start_utc = match tz.from_local_datetime(&naive_start).earliest() {
+                    Some(dt) => dt.with_timezone(&Utc),
+                    None => continue,
+                };
+
+                let block_end_utc =
+                    block_start_utc + Duration::minutes(block.duration_mins as i64);
+
+                // Clip to the 48-hour window.
+                let slot_start = block_start_utc.max(valid_from);
+                let slot_end = block_end_utc.min(valid_until);
+
+                if slot_end <= slot_start {
+                    continue;
+                }
+
+                let mut block_slots = self
+                    .resolve_block(
+                        block,
+                        slot_start,
+                        slot_end,
+                        &history,
+                        &channel.recycle_policy,
+                        generation,
+                    )
+                    .await?;
+
+                slots.append(&mut block_slots);
+            }
+
+            current_date = current_date.succ_opt().ok_or_else(|| {
+                DomainError::validation("Date overflow during schedule generation")
+            })?;
+        }
+
+        // Blocks in ScheduleConfig are not required to be sorted; sort resolved slots.
+        slots.sort_by_key(|s| s.start_at);
+
+        let schedule = GeneratedSchedule {
+            id: Uuid::new_v4(),
+            channel_id,
+            valid_from,
+            valid_until,
+            generation,
+            slots,
+        };
+
+        self.schedule_repo.save(&schedule).await?;
+
+        // Persist playback history so the recycle policy has data for next generation.
+        for slot in &schedule.slots {
+            let record =
+                PlaybackRecord::new(channel_id, slot.item.id.clone(), generation);
+            self.schedule_repo.save_playback_record(&record).await?;
+        }
+
+        Ok(schedule)
+    }
+
+    /// Determine what is currently broadcasting on a schedule.
+    ///
+    /// Returns `None` when `now` falls in a gap between blocks — the client
+    /// should display a no-signal / static screen in that case.
+    pub fn get_current_broadcast(
+        schedule: &GeneratedSchedule,
+        now: DateTime<Utc>,
+    ) -> Option<CurrentBroadcast> {
+        schedule
+            .slots
+            .iter()
+            .find(|s| s.start_at <= now && now < s.end_at)
+            .map(|slot| CurrentBroadcast {
+                slot: slot.clone(),
+                offset_secs: (now - slot.start_at).num_seconds() as u32,
+            })
+    }
+
+    /// Look up the schedule currently active at `at` without generating a new one.
+    pub async fn get_active_schedule(
+        &self,
+        channel_id: ChannelId,
+        at: DateTime<Utc>,
+    ) -> DomainResult<Option<GeneratedSchedule>> {
+        self.schedule_repo.find_active(channel_id, at).await
+    }
+
+    /// Delegate stream URL resolution to the configured media provider.
+    pub async fn get_stream_url(&self, item_id: &MediaItemId) -> DomainResult<String> {
+        self.media_provider.get_stream_url(item_id).await
+    }
+
+    /// Return all slots that overlap the given time window — the EPG data.
+    pub fn get_epg<'a>(
+        schedule: &'a GeneratedSchedule,
+        from: DateTime<Utc>,
+        until: DateTime<Utc>,
+    ) -> Vec<&'a ScheduledSlot> {
+        schedule
+            .slots
+            .iter()
+            .filter(|s| s.start_at < until && s.end_at > from)
+            .collect()
+    }
+
+    // -------------------------------------------------------------------------
+    // Block resolution
+    // -------------------------------------------------------------------------
+
+    async fn resolve_block(
+        &self,
+        block: &ProgrammingBlock,
+        start: DateTime<Utc>,
+        end: DateTime<Utc>,
+        history: &[PlaybackRecord],
+        policy: &RecyclePolicy,
+        generation: u32,
+    ) -> DomainResult<Vec<ScheduledSlot>> {
+        match &block.content {
+            BlockContent::Manual { items } => {
+                self.resolve_manual(items, start, end, block.id).await
+            }
+            BlockContent::Algorithmic { filter, strategy } => {
+                self.resolve_algorithmic(
+                    filter, strategy, start, end, history, policy, generation, block.id,
+                )
+                .await
+            }
+        }
+    }
+
+    /// Resolve a manual block by fetching each hand-picked item in order.
+    /// Stops when the block's time budget (`end`) is exhausted.
+    async fn resolve_manual(
+        &self,
+        item_ids: &[MediaItemId],
+        start: DateTime<Utc>,
+        end: DateTime<Utc>,
+        block_id: BlockId,
+    ) -> DomainResult<Vec<ScheduledSlot>> {
+        let mut slots = Vec::new();
+        let mut cursor = start;
+
+        for item_id in item_ids {
+            if cursor >= end {
+                break;
+            }
+            if let Some(item) = self.media_provider.fetch_by_id(item_id).await? {
+                let item_end =
+                    (cursor + Duration::seconds(item.duration_secs as i64)).min(end);
+                slots.push(ScheduledSlot {
+                    id: Uuid::new_v4(),
+                    start_at: cursor,
+                    end_at: item_end,
+                    item,
+                    source_block_id: block_id,
+                });
+                cursor = item_end;
+            }
+            // If item is not found (deleted/unavailable), silently skip it.
+        }
+
+        Ok(slots)
+    }
+
+    /// Resolve an algorithmic block: fetch candidates, apply recycle policy,
+    /// run the fill strategy, and build slots.
+    async fn resolve_algorithmic(
+        &self,
+        filter: &MediaFilter,
+        strategy: &FillStrategy,
+        start: DateTime<Utc>,
+        end: DateTime<Utc>,
+        history: &[PlaybackRecord],
+        policy: &RecyclePolicy,
+        generation: u32,
+        block_id: BlockId,
+    ) -> DomainResult<Vec<ScheduledSlot>> {
+        let candidates = self.media_provider.fetch_items(filter).await?;
+
+        if candidates.is_empty() {
+            return Ok(vec![]);
+        }
+
+        let pool = Self::apply_recycle_policy(candidates, history, policy, generation);
+        let target_secs = (end - start).num_seconds() as u32;
+        let selected = Self::fill_block(&pool, target_secs, strategy);
+
+        let mut slots = Vec::new();
+        let mut cursor = start;
+
+        for item in selected {
+            if cursor >= end {
+                break;
+            }
+            let item_end =
+                (cursor + Duration::seconds(item.duration_secs as i64)).min(end);
+            slots.push(ScheduledSlot {
+                id: Uuid::new_v4(),
+                start_at: cursor,
+                end_at: item_end,
+                item: item.clone(),
+                source_block_id: block_id,
+            });
+            cursor = item_end;
+        }
+
+        Ok(slots)
+    }
+
+    // -------------------------------------------------------------------------
+    // Recycle policy
+    // -------------------------------------------------------------------------
+
+    /// Filter `candidates` according to `policy`, returning the eligible pool.
+    ///
+    /// An item is on cooldown if *either* the day-based or generation-based
+    /// threshold is exceeded. If honouring all cooldowns would leave fewer items
+    /// than `policy.min_available_ratio` of the total, all cooldowns are waived
+    /// and the full pool is returned (prevents small libraries from stalling).
+    fn apply_recycle_policy(
+        candidates: Vec<MediaItem>,
+        history: &[PlaybackRecord],
+        policy: &RecyclePolicy,
+        current_generation: u32,
+    ) -> Vec<MediaItem> {
+        let now = Utc::now();
+
+        let excluded: HashSet<MediaItemId> = history
+            .iter()
+            .filter(|record| {
+                let by_days = policy
+                    .cooldown_days
+                    .map(|days| (now - record.played_at).num_days() < days as i64)
+                    .unwrap_or(false);
+
+                let by_gen = policy
+                    .cooldown_generations
+                    .map(|gens| {
+                        current_generation.saturating_sub(record.generation) < gens
+                    })
+                    .unwrap_or(false);
+
+                by_days || by_gen
+            })
+            .map(|r| r.item_id.clone())
+            .collect();
+
+        let available: Vec<MediaItem> = candidates
+            .iter()
+            .filter(|i| !excluded.contains(&i.id))
+            .cloned()
+            .collect();
+
+        let min_count =
+            (candidates.len() as f32 * policy.min_available_ratio).ceil() as usize;
+
+        if available.len() < min_count {
+            // Pool too small after applying cooldowns — recycle everything.
+            candidates
+        } else {
+            available
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Fill strategies
+    // -------------------------------------------------------------------------
+
+    fn fill_block<'a>(
+        pool: &'a [MediaItem],
+        target_secs: u32,
+        strategy: &FillStrategy,
+    ) -> Vec<&'a MediaItem> {
+        match strategy {
+            FillStrategy::BestFit => Self::fill_best_fit(pool, target_secs),
+            FillStrategy::Sequential => Self::fill_sequential(pool, target_secs),
+            FillStrategy::Random => {
+                let mut indices: Vec<usize> = (0..pool.len()).collect();
+                indices.shuffle(&mut rand::thread_rng());
+                let mut remaining = target_secs;
+                let mut result = Vec::new();
+                for i in indices {
+                    let item = &pool[i];
+                    if item.duration_secs <= remaining {
+                        remaining -= item.duration_secs;
+                        result.push(item);
+                    }
+                }
+                result
+            }
+        }
+    }
+
+    /// Greedy bin-packing: at each step pick the longest item that still fits
+    /// in the remaining budget, without repeating items within the same block.
+    fn fill_best_fit(pool: &[MediaItem], target_secs: u32) -> Vec<&MediaItem> {
+        let mut remaining = target_secs;
+        let mut selected: Vec<&MediaItem> = Vec::new();
+        let mut used: HashSet<usize> = HashSet::new();
+
+        loop {
+            let best = pool
+                .iter()
+                .enumerate()
+                .filter(|(idx, item)| {
+                    !used.contains(idx) && item.duration_secs <= remaining
+                })
+                .max_by_key(|(_, item)| item.duration_secs);
+
+            match best {
+                Some((idx, item)) => {
+                    remaining -= item.duration_secs;
+                    used.insert(idx);
+                    selected.push(item);
+                }
+                None => break,
+            }
+        }
+
+        selected
+    }
+
+    /// Sequential: iterate the pool in order, picking items that fit within
+    /// the remaining budget. Good for series where episode order matters.
+    fn fill_sequential(pool: &[MediaItem], target_secs: u32) -> Vec<&MediaItem> {
+        let mut remaining = target_secs;
+        let mut result = Vec::new();
+        for item in pool {
+            if item.duration_secs <= remaining {
+                remaining -= item.duration_secs;
+                result.push(item);
+            }
+        }
+        result
+    }
+}

k-tv-backend/domain/src/value_objects.rs

@@ -0,0 +1,768 @@
+//! Value Objects for K-Notes Domain
+//!
+//! Newtypes that encapsulate validation logic, following the "parse, don't validate" pattern.
+//! These types can only be constructed if the input is valid, providing compile-time guarantees.
+
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use std::fmt;
+use thiserror::Error;
+use url::Url;
+use uuid::Uuid;
+
+pub type UserId = Uuid;
+
+// ============================================================================
+// Validation Error
+// ============================================================================
+
+/// Errors that occur when parsing/validating value objects
+#[derive(Debug, Error, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum ValidationError {
+    #[error("Invalid email format: {0}")]
+    InvalidEmail(String),
+
+    #[error("Password must be at least {min} characters, got {actual}")]
+    PasswordTooShort { min: usize, actual: usize },
+
+    #[error("Invalid URL: {0}")]
+    InvalidUrl(String),
+
+    #[error("Value cannot be empty: {0}")]
+    Empty(String),
+
+    #[error("Secret too short: minimum {min} bytes required, got {actual}")]
+    SecretTooShort { min: usize, actual: usize },
+}
+
+// ============================================================================
+// Email (using email_address crate for RFC-compliant validation)
+// ============================================================================
+
+/// A validated email address using RFC-compliant validation.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Email(email_address::EmailAddress);
+
+impl Email {
+    /// Create a new validated email address
+    pub fn new(value: impl AsRef<str>) -> Result<Self, ValidationError> {
+        let value = value.as_ref().trim().to_lowercase();
+        let addr: email_address::EmailAddress = value
+            .parse()
+            .map_err(|_| ValidationError::InvalidEmail(value.clone()))?;
+        Ok(Self(addr))
+    }
+
+    /// Get the inner value
+    pub fn into_inner(self) -> String {
+        self.0.to_string()
+    }
+}
+
+impl AsRef<str> for Email {
+    fn as_ref(&self) -> &str {
+        self.0.as_ref()
+    }
+}
+
+impl fmt::Display for Email {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl TryFrom<String> for Email {
+    type Error = ValidationError;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl TryFrom<&str> for Email {
+    type Error = ValidationError;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl Serialize for Email {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str(self.0.as_ref())
+    }
+}
+
+impl<'de> Deserialize<'de> for Email {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let s = String::deserialize(deserializer)?;
+        Self::new(s).map_err(serde::de::Error::custom)
+    }
+}
+
+// ============================================================================
+// Password
+// ============================================================================
+
+/// A validated password input (NOT the hash).
+///
+/// Enforces minimum length of 6 characters.
+#[derive(Clone, PartialEq, Eq)]
+pub struct Password(String);
+
+/// Minimum password length (NIST recommendation)
+pub const MIN_PASSWORD_LENGTH: usize = 8;
+
+impl Password {
+    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
+        let value = value.into();
+
+        if value.len() < MIN_PASSWORD_LENGTH {
+            return Err(ValidationError::PasswordTooShort {
+                min: MIN_PASSWORD_LENGTH,
+                actual: value.len(),
+            });
+        }
+
+        Ok(Self(value))
+    }
+
+    pub fn into_inner(self) -> String {
+        self.0
+    }
+}
+
+impl AsRef<str> for Password {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+// Intentionally hide password content in Debug
+impl fmt::Debug for Password {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Password(***)")
+    }
+}
+
+impl TryFrom<String> for Password {
+    type Error = ValidationError;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl TryFrom<&str> for Password {
+    type Error = ValidationError;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl<'de> Deserialize<'de> for Password {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let s = String::deserialize(deserializer)?;
+        Self::new(s).map_err(serde::de::Error::custom)
+    }
+}
+
+// Note: Password should NOT implement Serialize to prevent accidental exposure
+
+// ============================================================================
+// OIDC Configuration Newtypes
+// ============================================================================
+
+/// OIDC Issuer URL - validated URL for the identity provider
+///
+/// Stores the original string to preserve exact formatting (e.g., trailing slashes)
+/// since OIDC providers expect issuer URLs to match exactly.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct IssuerUrl(String);
+
+impl IssuerUrl {
+    pub fn new(value: impl AsRef<str>) -> Result<Self, ValidationError> {
+        let value = value.as_ref().trim().to_string();
+        // Validate URL format but store original string to preserve exact formatting
+        Url::parse(&value).map_err(|e| ValidationError::InvalidUrl(e.to_string()))?;
+        Ok(Self(value))
+    }
+}
+
+impl AsRef<str> for IssuerUrl {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for IssuerUrl {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl TryFrom<String> for IssuerUrl {
+    type Error = ValidationError;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl From<IssuerUrl> for String {
+    fn from(val: IssuerUrl) -> Self {
+        val.0
+    }
+}
+
+/// OIDC Client Identifier
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct ClientId(String);
+
+impl ClientId {
+    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
+        let value = value.into().trim().to_string();
+        if value.is_empty() {
+            return Err(ValidationError::Empty("client_id".to_string()));
+        }
+        Ok(Self(value))
+    }
+}
+
+impl AsRef<str> for ClientId {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for ClientId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl TryFrom<String> for ClientId {
+    type Error = ValidationError;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl From<ClientId> for String {
+    fn from(val: ClientId) -> Self {
+        val.0
+    }
+}
+
+/// OIDC Client Secret - hidden in Debug output
+#[derive(Clone, PartialEq, Eq)]
+pub struct ClientSecret(String);
+
+impl ClientSecret {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+
+    /// Check if the secret is empty (for public clients)
+    pub fn is_empty(&self) -> bool {
+        self.0.trim().is_empty()
+    }
+}
+
+impl AsRef<str> for ClientSecret {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for ClientSecret {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "ClientSecret(***)")
+    }
+}
+
+impl fmt::Display for ClientSecret {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "***")
+    }
+}
+
+impl<'de> Deserialize<'de> for ClientSecret {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let s = String::deserialize(deserializer)?;
+        Ok(Self::new(s))
+    }
+}
+
+// Note: ClientSecret should NOT implement Serialize
+
+/// OAuth Redirect URL - validated URL
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct RedirectUrl(Url);
+
+impl RedirectUrl {
+    pub fn new(value: impl AsRef<str>) -> Result<Self, ValidationError> {
+        let value = value.as_ref().trim();
+        let url = Url::parse(value).map_err(|e| ValidationError::InvalidUrl(e.to_string()))?;
+        Ok(Self(url))
+    }
+
+    pub fn as_url(&self) -> &Url {
+        &self.0
+    }
+}
+
+impl AsRef<str> for RedirectUrl {
+    fn as_ref(&self) -> &str {
+        self.0.as_str()
+    }
+}
+
+impl fmt::Display for RedirectUrl {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl TryFrom<String> for RedirectUrl {
+    type Error = ValidationError;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl From<RedirectUrl> for String {
+    fn from(val: RedirectUrl) -> Self {
+        val.0.to_string()
+    }
+}
+
+/// OIDC Resource Identifier (optional audience)
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(try_from = "String", into = "String")]
+pub struct ResourceId(String);
+
+impl ResourceId {
+    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
+        let value = value.into().trim().to_string();
+        if value.is_empty() {
+            return Err(ValidationError::Empty("resource_id".to_string()));
+        }
+        Ok(Self(value))
+    }
+}
+
+impl AsRef<str> for ResourceId {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for ResourceId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl TryFrom<String> for ResourceId {
+    type Error = ValidationError;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::new(value)
+    }
+}
+
+impl From<ResourceId> for String {
+    fn from(val: ResourceId) -> Self {
+        val.0
+    }
+}
+
+// ============================================================================
+// OIDC Flow Newtypes (for type-safe session storage)
+// ============================================================================
+
+/// CSRF Token for OIDC state parameter
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CsrfToken(String);
+
+impl CsrfToken {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+}
+
+impl AsRef<str> for CsrfToken {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for CsrfToken {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+/// Nonce for OIDC ID token verification
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OidcNonce(String);
+
+impl OidcNonce {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+}
+
+impl AsRef<str> for OidcNonce {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for OidcNonce {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+/// PKCE Code Verifier
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PkceVerifier(String);
+
+impl PkceVerifier {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+}
+
+impl AsRef<str> for PkceVerifier {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+// Hide PKCE verifier in Debug (security)
+impl fmt::Debug for PkceVerifier {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "PkceVerifier(***)")
+    }
+}
+
+/// OAuth2 Authorization Code
+#[derive(Clone, PartialEq, Eq)]
+pub struct AuthorizationCode(String);
+
+impl AuthorizationCode {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+}
+
+impl AsRef<str> for AuthorizationCode {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+// Hide authorization code in Debug (security)
+impl fmt::Debug for AuthorizationCode {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "AuthorizationCode(***)")
+    }
+}
+
+impl<'de> Deserialize<'de> for AuthorizationCode {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let s = String::deserialize(deserializer)?;
+        Ok(Self::new(s))
+    }
+}
+
+/// Complete authorization URL data returned when starting OIDC flow
+#[derive(Debug, Clone)]
+pub struct AuthorizationUrlData {
+    /// The URL to redirect the user to
+    pub url: Url,
+    /// CSRF token to store in session
+    pub csrf_token: CsrfToken,
+    /// Nonce to store in session
+    pub nonce: OidcNonce,
+    /// PKCE verifier to store in session
+    pub pkce_verifier: PkceVerifier,
+}
+
+// ============================================================================
+// Configuration Newtypes
+// ============================================================================
+
+/// JWT signing secret with minimum length requirement
+pub const MIN_JWT_SECRET_LENGTH: usize = 32;
+
+#[derive(Clone, PartialEq, Eq)]
+pub struct JwtSecret(String);
+
+impl JwtSecret {
+    pub fn new(value: impl Into<String>, is_production: bool) -> Result<Self, ValidationError> {
+        let value = value.into();
+        if is_production && value.len() < MIN_JWT_SECRET_LENGTH {
+            return Err(ValidationError::SecretTooShort {
+                min: MIN_JWT_SECRET_LENGTH,
+                actual: value.len(),
+            });
+        }
+        Ok(Self(value))
+    }
+
+    /// Create without validation (for development/testing)
+    pub fn new_unchecked(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+}
+
+impl AsRef<str> for JwtSecret {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for JwtSecret {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "JwtSecret(***)")
+    }
+}
+
+// ============================================================================
+// Channel / Schedule types
+// ============================================================================
+
+pub type ChannelId = Uuid;
+pub type SlotId = Uuid;
+pub type BlockId = Uuid;
+
+/// Opaque media item identifier — format is provider-specific internally.
+/// The domain never inspects the string; it just passes it back to the provider.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct MediaItemId(String);
+
+impl MediaItemId {
+    pub fn new(value: impl Into<String>) -> Self {
+        Self(value.into())
+    }
+
+    pub fn into_inner(self) -> String {
+        self.0
+    }
+}
+
+impl AsRef<str> for MediaItemId {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for MediaItemId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl From<String> for MediaItemId {
+    fn from(s: String) -> Self {
+        Self(s)
+    }
+}
+
+impl From<&str> for MediaItemId {
+    fn from(s: &str) -> Self {
+        Self(s.to_string())
+    }
+}
+
+/// The broad category of a media item.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ContentType {
+    Movie,
+    Episode,
+    Short,
+}
+
+/// Provider-agnostic filter for querying media items.
+///
+/// Each field is optional — omitting it means "no constraint on this dimension".
+/// The `IMediaProvider` adapter interprets these fields in terms of its own API.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct MediaFilter {
+    pub content_type: Option<ContentType>,
+    pub genres: Vec<String>,
+    /// Starting year of a decade: 1990 means 1990–1999.
+    pub decade: Option<u16>,
+    pub tags: Vec<String>,
+    pub min_duration_secs: Option<u32>,
+    pub max_duration_secs: Option<u32>,
+    /// Abstract groupings interpreted by each provider (Jellyfin library, Plex section,
+    /// filesystem path, etc.). An empty list means "all available content".
+    pub collections: Vec<String>,
+}
+
+/// How the scheduling engine fills a time block with selected media items.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FillStrategy {
+    /// Greedy bin-packing: at each step pick the longest item that still fits,
+    /// minimising dead air. Good for variety blocks.
+    BestFit,
+    /// Pick items in the order returned by the provider — ideal for series
+    /// where episode sequence matters.
+    Sequential,
+    /// Shuffle the pool randomly then fill sequentially. Good for "shuffle play" channels.
+    Random,
+}
+
+/// Controls when previously aired items become eligible to play again.
+///
+/// An item is *on cooldown* if *either* threshold is met.
+/// `min_available_ratio` is a safety valve: if honouring the cooldown would
+/// leave fewer items than this fraction of the total pool, the cooldown is
+/// ignored and all items become eligible. This prevents small libraries from
+/// running completely dry.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RecyclePolicy {
+    /// Do not replay an item within this many calendar days.
+    pub cooldown_days: Option<u32>,
+    /// Do not replay an item within this many schedule generations.
+    pub cooldown_generations: Option<u32>,
+    /// Always keep at least this fraction (0.0–1.0) of the matching pool
+    /// available for selection, even if their cooldown has not yet expired.
+    pub min_available_ratio: f32,
+}
+
+impl Default for RecyclePolicy {
+    fn default() -> Self {
+        Self {
+            cooldown_days: Some(30),
+            cooldown_generations: None,
+            min_available_ratio: 0.2,
+        }
+    }
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    mod email_tests {
+        use super::*;
+
+        #[test]
+        fn test_valid_email() {
+            assert!(Email::new("user@example.com").is_ok());
+            assert!(Email::new("USER@EXAMPLE.COM").is_ok()); // Should lowercase
+            assert!(Email::new("  user@example.com  ").is_ok()); // Should trim
+        }
+
+        #[test]
+        fn test_email_normalizes() {
+            let email = Email::new("  USER@EXAMPLE.COM  ").unwrap();
+            assert_eq!(email.as_ref(), "user@example.com");
+        }
+
+        #[test]
+        fn test_invalid_email_no_at() {
+            assert!(Email::new("userexample.com").is_err());
+        }
+
+        #[test]
+        fn test_invalid_email_no_domain() {
+            assert!(Email::new("user@").is_err());
+        }
+
+        #[test]
+        fn test_invalid_email_no_local() {
+            assert!(Email::new("@example.com").is_err());
+        }
+    }
+
+    mod password_tests {
+        use super::*;
+
+        #[test]
+        fn test_valid_password() {
+            assert!(Password::new("secret123").is_ok());
+            assert!(Password::new("12345678").is_ok()); // Exactly 8 chars
+        }
+
+        #[test]
+        fn test_password_too_short() {
+            assert!(Password::new("1234567").is_err()); // 7 chars
+            assert!(Password::new("").is_err());
+        }
+
+        #[test]
+        fn test_password_debug_hides_content() {
+            let password = Password::new("supersecret").unwrap();
+            let debug = format!("{:?}", password);
+            assert!(!debug.contains("supersecret"));
+            assert!(debug.contains("***"));
+        }
+    }
+
+    mod oidc_tests {
+        use super::*;
+
+        #[test]
+        fn test_issuer_url_valid() {
+            assert!(IssuerUrl::new("https://auth.example.com").is_ok());
+        }
+
+        #[test]
+        fn test_issuer_url_invalid() {
+            assert!(IssuerUrl::new("not-a-url").is_err());
+        }
+
+        #[test]
+        fn test_client_id_non_empty() {
+            assert!(ClientId::new("my-client").is_ok());
+            assert!(ClientId::new("").is_err());
+            assert!(ClientId::new("   ").is_err());
+        }
+
+        #[test]
+        fn test_client_secret_hides_in_debug() {
+            let secret = ClientSecret::new("super-secret");
+            let debug = format!("{:?}", secret);
+            assert!(!debug.contains("super-secret"));
+            assert!(debug.contains("***"));
+        }
+    }
+
+    mod secret_tests {
+        use super::*;
+
+        #[test]
+        fn test_jwt_secret_production_check() {
+            let short = "short";
+            let long = "a".repeat(32);
+
+            // Production mode enforces length
+            assert!(JwtSecret::new(short, true).is_err());
+            assert!(JwtSecret::new(&long, true).is_ok());
+
+            // Development mode allows short secrets
+            assert!(JwtSecret::new(short, false).is_ok());
+        }
+
+        #[test]
+        fn test_secrets_hide_in_debug() {
+            let jwt = JwtSecret::new_unchecked("secret");
+            assert!(!format!("{:?}", jwt).contains("secret"));
+        }
+    }
+}