"""Coordinate constructors; no feature aggregation happens here."""
from __future__ import annotations

import numpy as np


def physical_targets(duration_s: float, steps: int) -> np.ndarray:
    """K fixed bins spanning verified real media duration, in seconds."""
    duration = float(duration_s)
    if not np.isfinite(duration) or duration <= 0 or steps < 1:
        raise ValueError("physical targets require positive finite duration and steps")
    edges = np.linspace(0.0, duration, steps + 1, dtype=np.float64)
    return np.column_stack((edges[:-1], edges[1:]))


def relative_cells(length: int) -> np.ndarray:
    """Ordered source cells on a unit progress axis, with no time claim."""
    if length < 1:
        raise ValueError("relative source length must be positive")
    left = np.arange(length, dtype=np.float64) / length
    return np.column_stack((left, left + 1.0 / length))


def relative_targets(steps: int) -> np.ndarray:
    """K fixed cells on the same unit progress axis."""
    return relative_cells(steps)