-- pg_orrery 0.18.0 -> 0.19.0: Sun almanac SRF, conjunction detection,
-- penumbral fraction, physical libration

-- ============================================================
-- Sun almanac events SRF (1)
-- ============================================================

CREATE FUNCTION sun_almanac_events(
    observer, start timestamptz, stop timestamptz,
    refracted bool DEFAULT false
) RETURNS TABLE(event_time timestamptz, event_type text)
    AS 'MODULE_PATHNAME', 'sun_almanac_events'
    LANGUAGE C STABLE STRICT PARALLEL SAFE
    ROWS 50;
COMMENT ON FUNCTION sun_almanac_events(observer, timestamptz, timestamptz, bool) IS
    'All Sun events (rise, set, civil/nautical/astronomical dawn and dusk) within a time window, sorted chronologically. Replaces chained individual twilight queries. Max 366-day window.';

-- ============================================================
-- Conjunction detection SRF (1)
-- ============================================================

CREATE FUNCTION planet_conjunctions(
    int4, int4, timestamptz, timestamptz,
    max_separation float8 DEFAULT 10.0
) RETURNS TABLE(conjunction_time timestamptz, separation_deg float8)
    AS 'MODULE_PATHNAME', 'planet_conjunctions'
    LANGUAGE C STABLE STRICT PARALLEL SAFE
    ROWS 10;
COMMENT ON FUNCTION planet_conjunctions(int4, int4, timestamptz, timestamptz, float8) IS
    'Finds conjunctions (angular separation minima) between two solar system bodies. Body IDs: 0=Sun, 1-8=planets, 10=Moon. max_separation filters results (degrees, default 10). Max 3660-day (10-year) window.';

-- ============================================================
-- Penumbral fraction (1)
-- ============================================================

CREATE FUNCTION satellite_penumbral_fraction(tle, timestamptz) RETURNS float8
    AS 'MODULE_PATHNAME', 'satellite_penumbral_fraction'
    LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION satellite_penumbral_fraction(tle, timestamptz) IS
    'Continuous shadow depth: 0.0 = full sunlight, 1.0 = full umbra. Linear interpolation in penumbral zone.';

-- ============================================================
-- Physical libration (1)
-- ============================================================

CREATE FUNCTION moon_physical_libration(
    timestamptz,
    OUT tau float8, OUT rho float8
) RETURNS record
    AS 'MODULE_PATHNAME', 'moon_physical_libration'
    LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION moon_physical_libration(timestamptz) IS
    'Physical libration corrections (Meeus p. 373): tau = longitude correction, rho = latitude correction (both in degrees, typically |value| < 0.1).';