flight-alloc 0.0.1__py3-none-any.whl

src/allocator/windows.py

@@ -0,0 +1,377 @@
+"""Shift-window tables and time helpers for Step 4.
+
+The numbers below are the single source of truth for H7 (tail extensions),
+H9 (ZC report buffers), H10 (15-min spacing, 30 min domestic→INTL and
+P2F↔P2F),
+H12 (international ±60min),
+and H15 (awkward-window routing). They mirror REF_Constraints in the
+unified workbook — keep them in lockstep when either side changes.
+
+Time arithmetic uses "ops-day minutes": minutes from 00:00 of the ops day
+(D). A flight at STD 02:00 on calendar D+1 (the N-shift continuation) has
+ops_day_minutes = 120 + 1440 = 1560, which is inside N's window
+[1230, 1740] = [20:30 D, 05:00 D+1]. This convention sidesteps midnight-
+crossing edge cases everywhere downstream.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import date as date_t
+from datetime import time as time_t
+
+from ..schemas import OpsClass, ShiftCode
+
+# ---------- shift hours (nominal) ----------
+# (start_offset, end_offset) in minutes from 00:00 of the ops day.
+# N's end is 24*60 + 5*60 = 1740 because it crosses midnight into D+1.
+
+SHIFT_NOMINAL_MIN: dict[ShiftCode, tuple[int, int]] = {
+    "M": (4 * 60, 12 * 60 + 30),                 # 04:00 - 12:30
+    "M1": (6 * 60, 14 * 60 + 30),                # 06:00 - 14:30
+    "A": (12 * 60 + 30, 21 * 60),                # 12:30 - 21:00
+    "A1": (14 * 60 + 30, 23 * 60),               # 14:30 - 23:00
+    "N": (20 * 60 + 30, 24 * 60 + 5 * 60),       # 20:30 - 05:00 D+1
+}
+
+# Handover overlap (round-3 update): for STDs in (nominal_end, nominal_end +
+# HANDOVER_WINDOW_MIN], BOTH the prev shift AND the next shift are eligible
+# (soft, not hard). The solver picks via S1 count balance + S5 handover
+# preference. Postsolve uses is_in_tail_ext (same range) to decide whether
+# RELIEVED_BY annotation applies.
+HANDOVER_WINDOW_MIN = 30
+
+# ---------- STD distribution windows (user direction 2026-05-12) ----------
+# These windows constrain which shifts a flight's STD can be ALLOCATED to.
+# Distinct from SHIFT_NOMINAL_MIN (which is staff working hours): a shift
+# only takes flights whose STD lies inside this distribution band.
+#
+# M / M1 / N — hard bounds [inner_lo, inner_hi].
+# A / A1    — hard inner band; soft outer extension (extra ~5 min beyond
+#             inner_hi). Outer-band assignments are allowed but the solver
+#             pays a penalty to minimize their use (S_outer term).
+#
+# All values are ops-day minutes. N wraps midnight: end=29:00 = 05:00 D+1.
+SHIFT_STD_WINDOW_INNER: dict[ShiftCode, tuple[int, int]] = {
+    "M":  (5 * 60 + 5,  12 * 60 + 55),                 # 05:05 - 12:55
+    "M1": (7 * 60 + 5,  14 * 60 + 55),                 # 07:05 - 14:55
+    # Patch 2026-05-14 (post-Phase-4 unallocated fix): A inner_lo was
+    # 13:10, leaving a 15-min coverage gap [12:56, 13:09] where only M1
+    # (12 staff) could absorb the rush. 9 unallocated 13:00 flights on
+    # the 05-03 dataset traced to M1 saturation. Pulling A's left edge
+    # to 13:00 lets the much larger A pool (32 STAFF) absorb the rush.
+    "A":  (13 * 60,      21 * 60 + 5),                 # 13:00 - 21:05
+    "A1": (15 * 60 + 10, 22 * 60 + 55),                # 15:10 - 22:55
+    # Same patch on the A->N side: N inner_lo was 21:20, leaving a gap
+    # [21:06, 21:19] where only A1 (12 staff) could absorb. Pulling N's
+    # left edge to 21:05 lets N share the load.
+    "N":  (21 * 60 + 5,  24 * 60 + 5 * 60),            # 21:05 - 05:00 D+1
+}
+# Soft outer end-extension for A and A1 only. The window grows from
+# inner_hi to outer_hi; entries here override that growth for the listed
+# shifts. Other shifts have outer = inner (no extension).
+SHIFT_STD_WINDOW_OUTER_END: dict[ShiftCode, int] = {
+    "A":  21 * 60 + 10,                                # +5 min to 21:10
+    "A1": 23 * 60,                                     # +5 min to 23:00
+}
+
+# ---------- shift hours with handover window (H7, round-3 update) ----------
+# Computed from SHIFT_NOMINAL_MIN + HANDOVER_WINDOW_MIN. Uniform 30 min
+# across all shifts — replaces the per-shift D6/r1/r2-1 values.
+
+SHIFT_TAIL_END_MIN: dict[ShiftCode, int] = {
+    shift: nominal_end + HANDOVER_WINDOW_MIN
+    for shift, (_, nominal_end) in SHIFT_NOMINAL_MIN.items()
+}
+
+# ---------- ZC report buffers (H9) ----------
+# Half-open intervals [start, end) in ops-day minutes. STDs in either buffer
+# are excluded for ZCs of that shift.
+
+ZC_BUFFER_START_MIN: dict[ShiftCode, tuple[int, int]] = {
+    "M": (4 * 60, 5 * 60 + 30),                  # 04:00 - 05:30
+    "A": (12 * 60 + 30, 14 * 60),                # 12:30 - 14:00
+    "M1": (6 * 60, 7 * 60 + 30),                 # 06:00 - 07:30
+    "A1": (14 * 60 + 30, 16 * 60),               # 14:30 - 16:00
+    "N": (20 * 60 + 30, 22 * 60),                # 20:30 - 22:00
+}
+
+ZC_BUFFER_END_MIN: dict[ShiftCode, tuple[int, int]] = {
+    "M": (11 * 60, 12 * 60 + 30),                # 11:00 - 12:30
+    "A": (19 * 60 + 30, 21 * 60),                # 19:30 - 21:00
+    "M1": (13 * 60, 14 * 60 + 30),               # 13:00 - 14:30
+    "A1": (21 * 60 + 30, 23 * 60),               # 21:30 - 23:00
+    "N": (24 * 60 + 3 * 60 + 30, 24 * 60 + 5 * 60),  # 03:30 - 05:00 D+1
+}
+
+# ---------- H15 awkward-window routing ----------
+# Keyed by ops-day minutes; value = tuple of shifts eligible at that STD.
+# Only applies to flights on the ops day itself (not D+1 N-tail flights —
+# those belong to tomorrow's M shift).
+
+AWKWARD_ROUTING_MIN: dict[int, tuple[ShiftCode, ...]] = {
+    # M -> A boundary
+    12 * 60 + 55: ("M",),
+    13 * 60:      ("M", "M1"),
+    13 * 60 + 5:  ("M1",),
+    13 * 60 + 10: ("M1", "A"),
+    13 * 60 + 15: ("A",),
+    # M1 -> A1 boundary (per D7 sample evidence: A absorbs entirely)
+    14 * 60 + 55: ("A",),
+    15 * 60:      ("A",),
+    15 * 60 + 5:  ("A",),
+    15 * 60 + 10: ("A",),
+    15 * 60 + 15: ("A",),
+}
+
+# ---------- buffer constants ----------
+# H10 (post-round-3 update per user direction 2026-05-10): hard floor
+# raised from 10 → 15 min (no two flights for one handler within 15 min);
+# soft warning band raised from 15 → 20 min so the assigner sees a flag
+# whenever spacing is between 15 and 20 min.
+SPACING_HARD_MIN = 15
+SPACING_SOFT_WARN_MIN = 20
+
+# H10 (user direction 2026-09-26): the 15-min floor is strict — the
+# 10-min rush-band relaxation of 2026-05-15 is gone — and a domestic
+# flight followed by an international one needs 30 min, so the handler
+# has time to prepare for the INTL departure. INTL→domestic and
+# INTL→INTL keep the plain 15-min floor.
+SPACING_DOM_TO_INTL_MIN = 30
+# H10 (user direction 2026-09-26): one handler can run two P2F flights
+# only when they are at least 30 min apart.
+SPACING_P2F_PAIR_MIN = 30
+#: Widest gap any pair of flights can need — callers scanning a sorted
+#: schedule can stop once two flights are this far apart.
+SPACING_MAX_MIN = max(SPACING_HARD_MIN, SPACING_DOM_TO_INTL_MIN, SPACING_P2F_PAIR_MIN)
+
+#: A flight as the H10 rules see it:
+#: ``(STD in ops-day minutes, is_international, is_p2f)``.
+SpacingKey = tuple[int, bool, bool]
+
+# Operationally-dense rush windows (user direction 2026-05-15). They
+# used to relax H10 to 10 min; now they only drive the solver's
+# "prefer a handler whose shift isn't starting or ending" tiebreaker.
+# Each entry is (start_min, end_min) in ops-day minutes, inclusive.
+# Derived from the manual 06-May-2026 allocation's 89 H10 violations
+# (88 of them fall in these six windows).
+RUSH_BANDS_MIN: tuple[tuple[int, int], ...] = (
+    (5 * 60,         5 * 60 + 30),     # 05:00 - 05:30
+    (6 * 60 + 55,    7 * 60 + 30),     # 06:55 - 07:30
+    (12 * 60 + 55,   13 * 60 + 15),    # 12:55 - 13:15
+    (17 * 60,        17 * 60 + 15),    # 17:00 - 17:15
+    (20 * 60,        22 * 60),         # 20:00 - 22:00
+    (23 * 60 + 15,   23 * 60 + 35),    # 23:15 - 23:35
+)
+
+
+def is_in_rush_band(
+    std: time_t, flight_date: date_t, ops_day: date_t,
+) -> bool:
+    """True if a flight's STD lies in one of the rush bands (inclusive
+    on both ends)."""
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    return any(lo <= minutes <= hi for lo, hi in RUSH_BANDS_MIN)
+
+
+def spacing_key(flight, ops_day: date_t) -> SpacingKey:
+    """``flight``'s :data:`SpacingKey` — anything with ``std``,
+    ``date``, ``is_international`` and ``ops_class`` will do."""
+    return (
+        std_to_ops_day_minutes(flight.std, flight.date, ops_day),
+        bool(flight.is_international),
+        flight.ops_class == OpsClass.P2F,
+    )
+
+
+def required_spacing_min(a: SpacingKey, b: SpacingKey) -> int:
+    """Required min gap between two same-staff flights, in either
+    order: 30 when the earlier one is domestic and the later one
+    international, 30 when both are P2F, else 15."""
+    earlier, later = (a, b) if a[0] <= b[0] else (b, a)
+    gap = SPACING_HARD_MIN
+    if later[1] and not earlier[1]:
+        gap = max(gap, SPACING_DOM_TO_INTL_MIN)
+    if earlier[2] and later[2]:
+        gap = max(gap, SPACING_P2F_PAIR_MIN)
+    return gap
+
+
+def spacing_clear(key: SpacingKey, others: Iterable[SpacingKey]) -> bool:
+    """True when a flight keeps the H10 gap to every one of ``others``
+    — the same staff member's other flights."""
+    return all(
+        abs(key[0] - other[0]) >= required_spacing_min(key, other)
+        for other in others
+    )
+
+
+def shift_boundary_within_30min(
+    shift: ShiftCode, std: time_t, flight_date: date_t, ops_day: date_t,
+) -> bool:
+    """True iff ``shift``'s nominal START or END lies within ±30 min of
+    the flight's STD.
+
+    Used by the band-targeted "prefer stable shift" soft preference
+    (user direction 2026-05-15): within the rush bands, the
+    solver should prefer to assign a flight to a staff whose shift is
+    NOT in transition. A shift is "in transition" at STD T when its
+    nominal start or end is within 30 minutes of T.
+
+    Handles N's midnight wrap: N's nominal end is at ops-day-min 1740
+    (= 05:00 D+1). A D-day flight at 04:50 (ops-min 290) is far from
+    that 1740 in the linear sense, but std_to_ops_day_minutes adds
+    1440 when ``flight_date == ops_day + 1``, so the comparison stays
+    correct on either side of midnight.
+    """
+    nominal = SHIFT_NOMINAL_MIN.get(shift)
+    if nominal is None:
+        return False
+    start_min, end_min = nominal
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    return abs(minutes - start_min) <= 30 or abs(minutes - end_min) <= 30
+
+# H4 P2F buffer (user direction 2026-09-26): a P2F handler takes no
+# normal flights from 2 hrs before to 1 hr after each of their P2F
+# flights' STD, both ends inclusive. Replaces the round-3 D-3hrs ±15
+# hard block and the D-1hr / D+20min ±15 max-1 windows. Enforced as an
+# eligibility filter (eligibility.py F6), so the solver and every
+# post-pass that checks eligibility respect it.
+P2F_BLOCK_BEFORE_MIN = 120
+P2F_BLOCK_AFTER_MIN = 60
+
+
+def in_p2f_block(std_min: int, p2f_std_mins: Iterable[int]) -> bool:
+    """True when a normal flight at ``std_min`` falls inside the
+    no-normal-flight window of any of a handler's P2F flights
+    (``p2f_std_mins``; all in ops-day minutes)."""
+    return any(
+        p - P2F_BLOCK_BEFORE_MIN <= std_min <= p + P2F_BLOCK_AFTER_MIN
+        for p in p2f_std_mins
+    )
+
+# International ±60 min from shift start/end (H12, correction r2-3).
+INTL_SHIFT_EDGE_MIN = 60
+
+
+# ---------- time-arithmetic helpers ----------
+
+def std_to_ops_day_minutes(std: time_t, flight_date: date_t, ops_day: date_t) -> int:
+    """Convert (calendar date, STD) to minutes-from-00:00-of-ops-day.
+
+    A 02:00 STD on calendar (ops_day + 1) returns 1560, which N's window
+    [1230, 1740] correctly contains.
+    """
+    base = std.hour * 60 + std.minute
+    delta_days = (flight_date - ops_day).days
+    return base + delta_days * 1440
+
+
+def is_in_shift(
+    std: time_t, flight_date: date_t, ops_day: date_t, shift: ShiftCode,
+) -> bool:
+    """True if (flight_date, std) falls within ``shift``'s window+tail-ext on
+    ``ops_day``. Inclusive of both endpoints — a 13:00 STD is still M's
+    (M's tail ends at 13:00 sharp, so STD=13:00 is the last allowed)."""
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    start = SHIFT_NOMINAL_MIN[shift][0]
+    end = SHIFT_TAIL_END_MIN[shift]
+    return start <= minutes <= end
+
+
+def is_in_zc_buffer(
+    std: time_t, flight_date: date_t, ops_day: date_t, shift: ShiftCode,
+) -> bool:
+    """True if STD is in the ZC's start-of-shift OR end-of-shift report
+    buffer for ``shift``. Half-open [start, end), so the buffer's upper
+    edge is the first eligible STD."""
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    s1, e1 = ZC_BUFFER_START_MIN[shift]
+    s2, e2 = ZC_BUFFER_END_MIN[shift]
+    return (s1 <= minutes < e1) or (s2 <= minutes < e2)
+
+
+def awkward_eligible_shifts(
+    std: time_t, flight_date: date_t, ops_day: date_t,
+) -> tuple[ShiftCode, ...] | None:
+    """Return the tuple of shifts allowed at this STD per H15, OR None if
+    the STD is not in any awkward window. D+1 flights never trigger H15
+    (next-day's M owns them, not today's solver)."""
+    if flight_date != ops_day:
+        return None
+    minutes = std.hour * 60 + std.minute
+    return AWKWARD_ROUTING_MIN.get(minutes)
+
+
+def is_in_tail_ext(
+    std: time_t, flight_date: date_t, ops_day: date_t, shift: ShiftCode,
+) -> bool:
+    """True if STD is in the tail-extension portion of ``shift`` —
+    i.e., past the nominal end but within the configured tail end.
+
+    Tail-ext flights are still owned by ``shift`` (STAFF column points
+    to the prev-shift handler), but the next shift's paired person does
+    the post-airborne (D+20) work and is recorded as RELIEVED_BY.
+    Flights at or before nominal end are NOT relieved (the prev staff
+    handles their own D+20 within shift).
+
+    Note: the uniform 30-min handover window is applied to N as well, so
+    05:01-05:30 on D+1 return True for N. Earlier comments claimed N has
+    no tail extension; postsolve is unaffected because it has no relief
+    shift for N. Behaviour is pinned in tests/test_windows.py.
+    """
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    nominal_end = SHIFT_NOMINAL_MIN[shift][1]
+    tail_end = SHIFT_TAIL_END_MIN[shift]
+    return nominal_end < minutes <= tail_end
+
+
+def is_within_intl_shift_edge(
+    std: time_t, flight_date: date_t, ops_day: date_t, shift: ShiftCode,
+) -> bool:
+    """H12 (correction r2-3): for international flights, exclude staff
+    whose STD is within 60 min of their shift's nominal start or end.
+
+    Strict-less-than / strict-greater-than per the correction's literal
+    wording: STD < shift_start + 60min OR STD > shift_end - 60min.
+
+    Retired 2026-05-12 (F9 dropped in eligibility.py). Kept here for
+    history / tests; not called by the live pipeline.
+    """
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    start, end = SHIFT_NOMINAL_MIN[shift]
+    return minutes < start + INTL_SHIFT_EDGE_MIN or minutes > end - INTL_SHIFT_EDGE_MIN
+
+
+def is_in_std_window(
+    std: time_t, flight_date: date_t, ops_day: date_t, shift: ShiftCode,
+) -> bool:
+    """True if the flight's STD lies in ``shift``'s STD distribution
+    window (inner OR outer band; outer applies to A and A1 only).
+
+    Per user direction 2026-05-12 §1: a flight is eligible for a shift
+    only when its STD falls in that shift's STD window. This is a
+    NARROWER check than ``is_in_shift`` (which spans the full shift
+    hours + handover overlap). Replaces F5 in eligibility.py.
+    """
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    lo, hi = SHIFT_STD_WINDOW_INNER[shift]
+    outer_hi = SHIFT_STD_WINDOW_OUTER_END.get(shift, hi)
+    return lo <= minutes <= outer_hi
+
+
+def is_in_std_outer_band(
+    std: time_t, flight_date: date_t, ops_day: date_t, shift: ShiftCode,
+) -> bool:
+    """True if STD lies in the soft outer band (inner_hi, outer_hi].
+
+    Used by the solver to penalize outer-band assignments via a soft
+    objective term — A and A1 only have non-empty bands. Other shifts
+    return False (no outer band defined).
+    """
+    if shift not in SHIFT_STD_WINDOW_OUTER_END:
+        return False
+    minutes = std_to_ops_day_minutes(std, flight_date, ops_day)
+    _, inner_hi = SHIFT_STD_WINDOW_INNER[shift]
+    outer_hi = SHIFT_STD_WINDOW_OUTER_END[shift]
+    return inner_hi < minutes <= outer_hi

src/cli.py

@@ -0,0 +1,41 @@
+"""Launcher for the Flight Allocation console.
+
+State lives in the server process for the length of a session, so there
+is nothing for a per-stage CLI command to read or write — the stages are
+driven from the dashboard. This module exists to start the UI.
+
+    python -m src.cli            # launch the console
+    python -m src.cli --port 9000 --no-browser
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .web.server import DEFAULT_HOST, DEFAULT_PORT, serve
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="flight-alloc",
+        description="Launch the Flight Allocation console (local web UI).",
+    )
+    p.add_argument("--host", default=DEFAULT_HOST,
+                   help=f"bind address (default {DEFAULT_HOST})")
+    p.add_argument("--port", type=int, default=DEFAULT_PORT,
+                   help=f"bind port (default {DEFAULT_PORT})")
+    p.add_argument("--no-browser", action="store_true",
+                   help="do not auto-open the browser")
+    # Accepted and ignored so an old shortcut like `flight-alloc web`
+    # still launches instead of erroring out.
+    p.add_argument("command", nargs="?", default="web",
+                   help=argparse.SUPPRESS)
+    args = p.parse_args(argv)
+
+    serve(host=args.host, port=args.port, open_browser=not args.no_browser)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/config.py

@@ -0,0 +1,168 @@
+"""Load and validate ``configs/config.yml`` (plan §1.5.1)."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Floating mid-shift break length, in minutes. The bounds are shared by
+#: the config model below and the Setup sidebar's edit form: under 15 is
+#: shorter than the H10 flight spacing, and every shift is 8.5 h with the
+#: first and last hour kept break-free.
+BREAK_MINUTES_DEFAULT = 30
+BREAK_MINUTES_LOWEST = 15
+BREAK_MINUTES_HIGHEST = 120
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class AllocationConfig(_Frozen):
+    cycle_year: int
+    default_date: date
+
+
+class SolverConfig(_Frozen):
+    max_seconds: int
+    deficit_penalty_lambda: int
+    # CPU cores handed to CP-SAT for parallel portfolio search. 0 (default)
+    # means "auto": use every available core, capped at 8 (see
+    # solver/allocator_cpsat.py — OR-Tools' own guidance is that portfolio
+    # search gets most of its benefit by ~8 diverse workers). Set explicitly
+    # only if you know this machine should use more/fewer.
+    num_workers: int = 0
+
+
+class StateConfig(_Frozen):
+    staleness_max_days: int
+
+
+class SVPortalConfig(_Frozen):
+    sheet: str
+    columns: dict[str, str]
+    date_format: str
+    pax_regex: str
+    # Phase 3 / Change 1 (2026-05-14, INTL overhaul): flights with
+    # ``DEP ∈ routing_drop_dep_codes`` are dropped at Step 1 extraction.
+    # ARR-side highlighting was removed in the same amendment — Gulf-3
+    # ARR flights are plain domestic now.
+    routing_drop_dep_codes: list[str] = []
+    # Step 1 tags a flight is_international=True if **DEP** is in this
+    # list (Change 9, 2026-05-14: DEP-side only — was DEP OR ARR).
+    international_airport_codes: list[str] = []
+
+
+class StaffRosterConfig(_Frozen):
+    sheet: str
+    name_column: str
+    date_header_format: str
+    skip_blank_columns: bool
+
+
+class AMRosterConfig(_Frozen):
+    sheet_glob: str
+    name_column: str
+    date_header_format: str
+    subheader_rows_to_skip: int
+
+
+class IOConfig(_Frozen):
+    sv_portal: SVPortalConfig
+    staff_roster: StaffRosterConfig
+    am_roster: AMRosterConfig
+
+
+class StatusConfig(_Frozen):
+    aliases: dict[str, str]
+    shifts: list[str]
+    non_shift_recognized: list[str]
+    am_shifts: list[str]
+    zc_shifts: list[str]
+    unrecognized_treatment: str
+
+
+class P2FAdjustmentConfig(_Frozen):
+    """User direction 2026-05-12 §3 — P2F post-pass tolerance window.
+
+    For each P2F flight assigned to a handler, the post-pass removes:
+      * 2 flights with STD within ±tolerance_minutes of (P2F_STD - 3h)
+      * 1 flight with STD within ±tolerance_minutes of (P2F_STD - 1h)
+      * 1 flight with STD within ±tolerance_minutes of (P2F_STD + 20min)
+    Removed flights go to the §4 redistribution pool. Partial removal
+    allowed (e.g., only 1 of 2 candidates found within tolerance).
+
+    2026-05-28 (user direction): ``logic_v2`` switches the P2F post-pass
+    from the anchored 3-point model (D-3h / D-1h / D+20m, host-vs-owner
+    split) to a single union window per P2F flight. For each P2F at
+    STD=T, the entire P2F handler chain (owner shift's handler +
+    pre-planner shift's handler) loses ALL their flights in [T-2h, T+1h]
+    — the P2F flight itself stays with the owner. Removed flights enter
+    the redistribution pool. When ``logic_v2: true`` the P2F post-pass
+    also runs BEFORE the INTL post-pass (default order is INTL first)
+    so INTL D-75 removal doesn't waste a slot the P2F window would
+    already free.
+    """
+
+    tolerance_minutes: int = 15
+    logic_v2: bool = False
+
+
+class BreakPassConfig(_Frozen):
+    """Floating mid-shift break (``allocator/postpass_break.py``). Every
+    on-shift staff member gets one flight-free window of
+    ``length_minutes``. Editable from the Setup sidebar."""
+
+    length_minutes: int = Field(
+        default=BREAK_MINUTES_DEFAULT,
+        ge=BREAK_MINUTES_LOWEST,
+        le=BREAK_MINUTES_HIGHEST,
+    )
+
+
+class Config(_Frozen):
+    allocation: AllocationConfig
+    # Task 2a (2026-05-12): required_staffing removed. The per-shift
+    # "people needed" baseline is now derived at display time from the
+    # current preferred targets and the day's flight count
+    # (ceil(flights / preferred_per_staff)). Editable values for
+    # per-(shift, role) preferred / acceptable / cap live in
+    # configs/shift_limits.json — see allocator/caps.py.
+    solver: SolverConfig
+    state: StateConfig
+    io: IOConfig
+    status: StatusConfig
+    ops_class_by_aircraft_type: dict[str, str] = {}
+    # GULF classification (user direction 2026-05-19): a flight is GULF
+    # when EITHER its DEP airport (3-letter) is in
+    # ``ops_class_gulf_dep_codes`` (default AUH / DOH / DXB), OR its
+    # Aircraft Owner / TYPE letter equals one of
+    # ``ops_class_gulf_owner_codes`` (default QR). GULF lands on the
+    # dedicated GULF class for reference but is NOT read
+    # by Step 3 — extract-only, never allocated. Replaces the legacy
+    # ``routing_drop_dep_codes`` outright drop.
+    ops_class_gulf_dep_codes: list[str] = []
+    ops_class_gulf_owner_codes: list[str] = []
+    # User-defined extraction filters (per user direction 2026-05-25).
+    # Each filter is a dict with any subset of keys: ``ac_type``,
+    # ``ac_owner``, ``ac``, ``dep``, ``arr``, plus an optional
+    # ``custom_header`` + ``custom_value`` for matching arbitrary
+    # SV-portal columns. Empty / missing field means "don't match on
+    # that field". A flight matches the filter iff ALL specified fields
+    # match (AND semantics, case-insensitive exact match). When a
+    # flight matches any filter it routes to the GULF class — the
+    # existing extract-only sheet — same as the static Gulf codes
+    # above. Edits via the Override drawer's Extraction Filters form
+    # or directly in config.yml.
+    extraction_filters: list[dict[str, str]] = []
+    p2f_adjustment: P2FAdjustmentConfig = P2FAdjustmentConfig()
+    break_pass: BreakPassConfig = BreakPassConfig()
+
+
+def load_config(path: Path | str) -> Config:
+    raw: Any = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    return Config.model_validate(raw)

src/greedy_fallback.py

@@ -0,0 +1,102 @@
+"""Greedy fallback allocator — Step 4 safety net.
+
+CP-SAT (``solver/allocator_cpsat.py``) is the primary allocator: it
+enforces every hard rule (H1/H10/H16/H4/H17/H18...) simultaneously and,
+when it reaches OPTIMAL, provably gives the best weighted result. But
+it is an EXACT solver — if any combination of hard constraints turns
+out to be mutually unsatisfiable (a mis-tuned config value, a day with
+an unusual shape, a bug not yet caught), it reports INFEASIBLE and
+hands back ZERO assignments for the WHOLE day, even for the 99% of
+flights that had nothing to do with the conflict. That is what
+happened in production on 2026-09-22 (a static N/ZC workload floor of
+14 with zero actual night-ops flights).
+
+This module is the fallback for exactly that situation. It is invoked
+ONLY when CP-SAT returns a non-feasible status. It ignores every soft
+objective (workload balance, handover preference, INTL spacing
+fairness, day-level targeting...) — it exists purely so the operator
+gets a usable, physically-valid allocation instead of a wall of
+unallocated flights, with a loud warning that manual review is needed.
+
+Hard rules this DOES still enforce (the ones that are non-negotiable
+even in a degraded mode):
+  H1   one staff per flight             — never double-books a flight
+  H10  same-staff spacing               — never overlaps/underspaces
+       one person's flights
+  H16  per-staff hard cap               — never exceeds a staff's max
+
+Hard rules this does NOT enforce (left to the operator to review via
+the Warnings / Unallocated tabs when a greedy-fallback run happens):
+  H4 P2F partial-block windows, H17 P2F-per-handler cap of 8, H18
+  workload-spread bucketing, INTL D-75 coverage nuances.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date as date_t
+
+from ..schemas import FlightInput, StaffMember
+from .caps import hard_cap_for
+from .windows import required_spacing_min, std_to_ops_day_minutes
+
+
+def greedy_allocate(
+    flights: list[FlightInput],
+    staff: list[StaffMember],
+    eligibility: dict[str, set[str]],
+    *,
+    ops_day: date_t,
+) -> dict[str, str]:
+    """Best-effort assignment respecting H1, H10, H16 only.
+
+    Walks flights in chronological (STD) order; for each, picks the
+    least-loaded eligible staff who doesn't violate that staff's
+    spacing or hard cap. No optimality guarantee and no workload
+    balancing beyond "prefer whoever has fewer flights so far" — this
+    is a safety net, not a replacement for the CP-SAT model.
+
+    Returns ``{flight.unique_id: employee_id}`` for whatever it
+    managed to place. A flight with no eligible-and-available staff is
+    simply absent from the result, exactly like a partial CP-SAT
+    solve — the caller's existing UNALLOCATED bookkeeping picks it up
+    the same way either way.
+    """
+    staff_by_id = {s.employee_id: s for s in staff}
+    caps = {s.employee_id: hard_cap_for(s) for s in staff}
+    counts: dict[str, int] = defaultdict(int)
+    # Per-staff list of assigned STD minutes for H10 spacing checks.
+    assigned_by_staff: dict[str, list[int]] = defaultdict(list)
+
+    ordered = sorted(
+        flights,
+        key=lambda f: std_to_ops_day_minutes(f.std, f.date, ops_day),
+    )
+
+    assignments: dict[str, str] = {}
+    for f in ordered:
+        std_min = std_to_ops_day_minutes(f.std, f.date, ops_day)
+        candidates: list[str] = []
+        for eid in eligibility.get(f.unique_id, ()):
+            if staff_by_id.get(eid) is None:
+                continue
+            cap = caps.get(eid, 0)
+            if cap <= 0 or counts[eid] >= cap:
+                continue
+            ok = True
+            for other_std in assigned_by_staff[eid]:
+                lo, hi = min(std_min, other_std), max(std_min, other_std)
+                if hi - lo < required_spacing_min(lo, hi):
+                    ok = False
+                    break
+            if ok:
+                candidates.append(eid)
+        if not candidates:
+            continue
+        candidates.sort(key=lambda eid: (counts[eid], eid))
+        pick = candidates[0]
+        assignments[f.unique_id] = pick
+        counts[pick] += 1
+        assigned_by_staff[pick].append(std_min)
+
+    return assignments