flight-alloc 0.0.1__py3-none-any.whl

src/allocator/eligibility.py

@@ -0,0 +1,302 @@
+"""Eligibility matrix for Step 4 (round-3 update).
+
+For every (flight, staff) pair, answer one question: is this staff eligible
+to be assigned this flight, given the *hard* constraints H2, H3, H4, H11,
+H12, H13? The matrix is a sparse mapping ``flight_id -> set[employee_id]``
+that the CP-SAT solver consumes to define decision variables.
+
+Each filter is a tiny pure function. Filter ordering does not change
+correctness (all filters must pass — AND semantics) but it does change the
+``ExcludeReason`` returned for diagnostic logs.
+
+Hard constraints enforced HERE:
+  H2   shift coverage (incl. handover overlap window — both prev and next
+       shift are eligible in the (nominal_end, nominal_end+30] window;
+       solver picks via S1+S5)
+  H3   P2F license match
+  H4   P2F dedication + buffer (no normal flights for the handler
+       from STD-2hrs to STD+1hr of each of their P2F flights)
+  H11  per-day overrides (STD cutoff, max_flights via H16 cap)
+  H12  international newbie + shift-edge exclusions
+  H13  AM exclusion
+  H20  nominated P2F handlers never take international flights (frees
+       up their day for more P2F work)
+
+Hard constraints NOT enforced here (deferred to the solver):
+  H1   exactly one staff per flight       — solver objective
+  H10  15-min spacing (30 domestic→INTL)  — solver at-most-one pairs
+  H16  hard caps                          — solver constraint
+
+Hard constraints removed in round-3 (now SOFT, handled in the solver):
+  H7   handover window (was tail-ext hard)        — soft via S5
+  H9   ZC report buffers (was hard exclusion)     — soft via S7
+  H15  awkward routing (was hard pre-filter)      — soft via S6
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date as date_t
+from datetime import time as time_t
+from enum import StrEnum
+
+from ..schemas import (
+    AllocationSheet,
+    FlightInput,
+    OpsClass,
+    Role,
+    ShiftCode,
+    StaffMember,
+)
+from .windows import (
+    SHIFT_NOMINAL_MIN,
+    awkward_eligible_shifts,
+    in_p2f_block,
+    is_in_std_window,
+    std_to_ops_day_minutes,
+)
+
+# D-marker offset: planning happens 75 minutes before STD.
+_D75_OFFSET_MIN: int = 75
+
+
+def _intl_handler_covers_d75_through_std(
+    staff_shift: ShiftCode,
+    flight_std: time_t,
+    flight_date: date_t,
+    ops_day: date_t,
+) -> bool:
+    """For INTL same-handler rule (Change 4): does ``staff_shift``'s
+    nominal working window cover the full span from D-75 (the planning
+    marker) through STD?
+
+    Used by:
+      * Phase 2 (2026-05-14) — postsolve's INTL self-pair override
+        skips assigning PLANNED_BY / RELIEVED_BY when the handler can't
+        actually cover the planning window. Phase 3 makes this an
+        eligibility filter that rejects the assignment entirely.
+
+    Pure function — no side effects. Returns True iff:
+      * shift's nominal start ≤ (STD - 75 min), AND
+      * STD ≤ shift's nominal end.
+
+    Both bounds in ops-day minutes (handles N's midnight wrap via
+    ``std_to_ops_day_minutes``)."""
+    nominal = SHIFT_NOMINAL_MIN.get(staff_shift)
+    if nominal is None:
+        return False
+    start_min, end_min = nominal
+    std_min = std_to_ops_day_minutes(flight_std, flight_date, ops_day)
+    d75_min = std_min - _D75_OFFSET_MIN
+    return start_min <= d75_min and std_min <= end_min
+
+
+class ExcludeReason(StrEnum):
+    """Diagnostic tag returned when a filter rejects a (flight, staff)
+    pair. Used by W201 diagnostic messages when a flight has zero
+    eligible staff."""
+
+    AM_ROLE = "AM (no flights, H13)"
+    NOT_ASSIGNABLE_TODAY = "staff not on shift today"
+    P2F_NOT_LICENSED = "P2F flight requires P2F license (H3)"
+    P2F_NOT_HANDLER = "P2F flight only goes to shift's nominated handler (H4)"
+    P2F_HANDLER_HARD_BLOCK = (
+        "normal flight within 2 hrs before / 1 hr after one of the "
+        "handler's P2F flights (H4)"
+    )
+    OUT_OF_SHIFT = "STD outside shift's distribution window (user 2026-05-12)"
+    STD_OUTSIDE_ALL_WINDOWS = "STD outside all shift windows"
+    OVERRIDE_CUTOFF = "STD past staff's per-day STD cutoff (H11)"
+    NEWBIE_INTERNATIONAL = "newbies excluded from international flights (H12a)"
+    INTL_SHIFT_EDGE = "international: staff within ±60 min of shift start/end (H12b — retired)"
+    INTL_SHIFT_COVERAGE = (
+        "international DEP: handler's shift does not cover D-75 through "
+        "STD (Change 4 — same handler start-to-finish)"
+    )
+    P2F_HANDLER_NO_INTL = (
+        "nominated P2F handlers do not take international flights (H20)"
+    )
+
+
+@dataclass(frozen=True)
+class EligibilityContext:
+    """Runtime context used by the filters. Computed once by the
+    orchestrator at preprocessing time."""
+
+    ops_day: date_t
+    p2f_handler_by_shift: dict[ShiftCode, str] = field(default_factory=dict)
+    """shift -> employee_id of the P2F handler nominated for that shift.
+    Per user direction 2026-05-10: only M / A / N have P2F handlers;
+    M1 and A1 P2F flights drop the handler restriction (any P2F-licensed
+    staff on shift can take them)."""
+
+    p2f_flight_minutes_by_handler: dict[str, list[int]] = field(default_factory=dict)
+    """employee_id -> list of P2F flight STDs (in ops-day minutes) the
+    handler is dedicated to. Drives H4's no-normal-flight window."""
+
+    # Phase R per-flight overrides — populated by step3 from the override list
+    # rows of type ``skip_p2f_buffer``. Each entry is (flight_key,
+    # employee_id) where flight_key = ``f"{flt}|{std.isoformat()}"``.
+    # When present, F6 skips the P2F buffer check for that exact pair.
+    skip_p2f_buffer_pairs: frozenset[tuple[str, str]] = frozenset()
+
+
+def check(
+    flight: FlightInput, staff: StaffMember, ctx: EligibilityContext,
+) -> ExcludeReason | None:
+    """Return the first failing exclusion reason, or None if eligible."""
+    # F1: AM exclusion (H13). Cheapest; AMs never fly.
+    if staff.role == Role.AM:
+        return ExcludeReason.AM_ROLE
+    # F2: shift assignability. Off today => not eligible.
+    if staff.shift_today is None:
+        return ExcludeReason.NOT_ASSIGNABLE_TODAY
+    # F3: P2F license (H3). P2F flights require P2F-licensed staff.
+    if flight.ops_class == OpsClass.P2F and not staff.is_p2f_licensed:
+        return ExcludeReason.P2F_NOT_LICENSED
+    # F4: P2F dedication (H4). P2F is strictly M / A / N only — per
+    # user direction 2026-05-10, M1 and A1 staff are NEVER eligible for
+    # P2F flights regardless of license. Among M/A/N staff, only the
+    # shift's nominated handler is eligible.
+    if flight.ops_class == OpsClass.P2F:
+        if staff.shift_today not in ("M", "A", "N"):
+            return ExcludeReason.P2F_NOT_HANDLER  # M1/A1 excluded
+        nominated = ctx.p2f_handler_by_shift.get(staff.shift_today)
+        if nominated != staff.employee_id:
+            return ExcludeReason.P2F_NOT_HANDLER
+    # F5: STD distribution window (user direction 2026-05-12, §1).
+    # A flight is eligible for a shift only if its STD falls in that
+    # shift's distribution window (M / M1 / N hard-bounded; A and A1
+    # have a soft outer band that the solver penalizes via S_outer).
+    if not is_in_std_window(
+        flight.std, flight.date, ctx.ops_day, staff.shift_today,
+    ):
+        return ExcludeReason.OUT_OF_SHIFT
+    # F6: P2F handler buffer (H4, user direction 2026-09-26). For each
+    # P2F flight the handler runs, no normal flight from 2 hrs before
+    # to 1 hr after its STD (prep and turnaround time). Applies to
+    # every handler, ZC+P2F included.
+    #
+    # Phase R override: if the (flight_key, employee_id) pair is in
+    # ``ctx.skip_p2f_buffer_pairs``, skip the buffer check entirely.
+    if flight.ops_class != OpsClass.P2F:
+        anchors = ctx.p2f_flight_minutes_by_handler.get(staff.employee_id, [])
+        if anchors:
+            flight_key = f"{flight.flt}|{flight.std.isoformat(timespec='minutes')}"
+            override_active = (
+                (flight_key, staff.employee_id) in ctx.skip_p2f_buffer_pairs
+            )
+            if not override_active:
+                target = std_to_ops_day_minutes(
+                    flight.std, flight.date, ctx.ops_day,
+                )
+                if in_p2f_block(target, anchors):
+                    return ExcludeReason.P2F_HANDLER_HARD_BLOCK
+    # F7: per-staff STD window (H11).
+    # 2026-05-27: extended to a windowed constraint — flights must fall
+    # in [std_start, std_cutoff] when those are set. Either bound may be
+    # None, in which case the staff's normal shift bound applies for
+    # that side (i.e., no extra constraint).
+    if staff.std_cutoff is not None and flight.std > staff.std_cutoff:
+        return ExcludeReason.OVERRIDE_CUTOFF
+    if staff.std_start is not None and flight.std < staff.std_start:
+        return ExcludeReason.OVERRIDE_CUTOFF
+    # F8: international newbie exclusion (H12a).
+    if flight.is_international and staff.is_newbie:
+        return ExcludeReason.NEWBIE_INTERNATIONAL
+    # F9 (Phase 3, Change 4 — 2026-05-14): INTL DEP same-handler
+    # start-to-finish. For an INTL flight, the handler's shift must
+    # nominally cover D-75 through STD (strict). If not, exclude.
+    # No buffer, no fallback (per user direction). Replaces the retired
+    # F9 INTL_SHIFT_EDGE rule.
+    if flight.is_international and not _intl_handler_covers_d75_through_std(
+        staff.shift_today, flight.std, flight.date, ctx.ops_day,
+    ):
+        return ExcludeReason.INTL_SHIFT_COVERAGE
+    # F10 (H20): the staff member nominated as *their own shift's* P2F
+    # handler never takes a *normal* international flight. Keeping
+    # ordinary INTL work off their plate frees up the time/slots
+    # they'd otherwise spend on it for more P2F flights instead. This
+    # must NOT touch the handler's own P2F flights — a P2F flight can
+    # itself be international (e.g. HAN-CCU), and F4 above is already
+    # the sole authority on who may take it; excluding it here would
+    # leave that flight with zero eligible staff. Mirrors F4's lookup
+    # — only the handler nominated for the shift they're working
+    # today is affected.
+    if (
+        flight.is_international
+        and flight.ops_class != OpsClass.P2F
+        and ctx.p2f_handler_by_shift.get(staff.shift_today) == staff.employee_id
+    ):
+        return ExcludeReason.P2F_HANDLER_NO_INTL
+    return None
+
+
+def build_matrix(
+    flights: list[FlightInput],
+    staff_today: list[StaffMember],
+    ctx: EligibilityContext,
+) -> dict[str, set[str]]:
+    """Return ``{flight.unique_id: {employee_id, ...}}``. Sparse: only
+    includes eligible pairs.
+
+    Per user direction 2026-05-12: keyed by ``unique_id`` (flt + dep +
+    arr + STD) so multi-leg rotations with the same FLT number stay
+    independent. Earlier code keyed by ``flt`` alone, which caused
+    later legs to silently overwrite earlier ones in the dict.
+
+    Flight rows with empty sets are still emitted; the orchestrator
+    scans for these and aborts with W201 before invoking the solver.
+    """
+    matrix: dict[str, set[str]] = {}
+    for f in flights:
+        eligible: set[str] = set()
+        for s in staff_today:
+            if check(f, s, ctx) is None:
+                eligible.add(s.employee_id)
+        matrix[f.unique_id] = eligible
+    return matrix
+
+
+def diagnose_unassignable(
+    flight: FlightInput, staff_today: list[StaffMember], ctx: EligibilityContext,
+) -> list[tuple[str, ExcludeReason]]:
+    """For a flight with zero eligible staff, return the list of
+    (employee_id, reason) tuples explaining why each candidate was excluded.
+    Drives W201 diagnostic messages.
+    """
+    out: list[tuple[str, ExcludeReason]] = []
+    for s in staff_today:
+        reason = check(flight, s, ctx)
+        if reason is not None:
+            out.append((s.employee_id, reason))
+    return out
+
+
+# ---------- preprocessing helpers ----------
+
+def tag_awkward_window(flight: FlightInput, ops_day: date_t) -> FlightInput:
+    """Tag a flight with is_awkward_window + awkward_eligible_shifts for
+    the solver's soft S6 routing preference. No longer drives eligibility
+    (awkward routing is soft now), but the solver consults these tags to
+    add a small penalty for non-preferred shifts."""
+    awk = awkward_eligible_shifts(flight.std, flight.date, ops_day)
+    if awk is None:
+        return flight
+    return flight.model_copy(update={
+        "is_awkward_window": True,
+        "awkward_eligible_shifts": awk,
+    })
+
+
+def sheet_target_for(flight: FlightInput, staff: StaffMember) -> AllocationSheet:
+    """Resolve which allocation lane the row belongs to. Routing is
+    by ops_class (P2F) with the day/night split decided by the
+    assigned STAFF's shift (clarification 1)."""
+    if flight.ops_class == OpsClass.P2F:
+        return AllocationSheet.P2F
+    return (
+        AllocationSheet.NIGHT_OPS
+        if staff.shift_today == "N"
+        else AllocationSheet.DAY_OPS
+    )

src/allocator/greedy_fallback.py

@@ -0,0 +1,106 @@
+"""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):
+  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, OpsClass, StaffMember
+from .caps import hard_cap_for
+from .windows import SpacingKey, spacing_clear, spacing_key, 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.
+
+    Places every P2F flight first (so the nominated handler is never
+    crowded out by normal flights), then all other flights, each group
+    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 SpacingKey list for H10 spacing checks.
+    assigned_by_staff: dict[str, list[SpacingKey]] = defaultdict(list)
+
+    # P2F FIRST (2026-09-22, user direction): the nominated handler's P2F
+    # flights are placed before any normal flight is considered.
+    # Walking purely by time let a handler fill up on earlier normal
+    # flights and then hit his cap / spacing when his P2F flights came
+    # up. Within each group the order is still chronological.
+    ordered = sorted(
+        flights,
+        key=lambda f: (
+            f.ops_class != OpsClass.P2F,
+            std_to_ops_day_minutes(f.std, f.date, ops_day),
+        ),
+    )
+
+    assignments: dict[str, str] = {}
+    for f in ordered:
+        key = spacing_key(f, 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
+            if spacing_clear(key, assigned_by_staff[eid]):
+                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(key)
+
+    return assignments

src/allocator/invariants.py

@@ -0,0 +1,124 @@
+"""Independent re-check of the hard rules on a finished allocation.
+
+The CP-SAT model and the two post-passes (P2F, INTL) each enforce parts of
+H1 / H10 / H16, and the post-passes move flights *after* the solver has
+finished. This module re-derives the rules from the final rows alone, so a
+regression in any stage shows up as a concrete list of violations instead
+of a quietly worse roster.
+
+It is deliberately decoupled from the solver: it only needs rows that carry
+``date``, ``std``, ``flt``, ``dep``, ``arr`` and ``staff_employee_id``
+(``AllocationRow`` qualifies, so does a ``SimpleNamespace`` in a test),
+plus ``is_international`` and ``sheet_target`` when a row has them.
+
+Rules checked
+-------------
+H1   a flight appears against at most one staff member
+H10  same-staff spacing (15 min, or 30 min for a domestic flight followed
+     by an international one and for two P2F flights — see
+     ``windows.required_spacing_min``)
+H16  per-staff hard cap (only when ``caps`` is supplied)
+
+Rows with an empty ``staff_employee_id`` (pre-plan-only / unallocated) are
+ignored: they are reported elsewhere and have no owner to check.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from collections.abc import Collection, Iterable, Mapping
+from dataclasses import dataclass
+from datetime import date as date_t
+
+from .windows import (
+    SPACING_MAX_MIN,
+    SpacingKey,
+    required_spacing_min,
+    std_to_ops_day_minutes,
+)
+
+
+def _spacing_key(row, ops_day: date_t) -> SpacingKey:
+    """A row's H10 identity. Rows carry no ops class, so P2F is read
+    off the lane they were routed to; missing fields read as a plain
+    domestic flight."""
+    return (
+        std_to_ops_day_minutes(row.std, row.date, ops_day),
+        bool(getattr(row, "is_international", False)),
+        str(getattr(row, "sheet_target", "")) == "P2F",
+    )
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One broken rule. ``employee_id`` is empty for flight-level rules."""
+
+    rule: str
+    employee_id: str
+    detail: str
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        who = f" [{self.employee_id}]" if self.employee_id else ""
+        return f"{self.rule}{who}: {self.detail}"
+
+
+def flight_key(row) -> str:
+    """Stable identity for a flight row (mirrors ``FlightInput.unique_id``)."""
+    return f"{row.flt}|{row.dep}|{row.arr}|{row.std.isoformat()}|{row.date.isoformat()}"
+
+
+def check_allocation(
+    rows: Iterable,
+    *,
+    ops_day: date_t,
+    caps: Mapping[str, int] | None = None,
+    waived_pairs: Collection[frozenset[str]] = (),
+) -> list[Violation]:
+    """Return every H1 / H10 / H16 violation found in ``rows``.
+
+    ``caps`` maps employee_id -> hard cap (H16). Staff missing from the
+    mapping are not cap-checked.
+    ``waived_pairs`` holds ``frozenset({key_a, key_b})`` entries for pairs
+    an operator explicitly waived (the ``waive_h10_pair`` override); those
+    pairs are not reported for H10.
+    """
+    assigned = [r for r in rows if getattr(r, "staff_employee_id", "")]
+    violations: list[Violation] = []
+
+    # ---- H1: no flight owned twice ----
+    seen = Counter(flight_key(r) for r in assigned)
+    for key, n in sorted(seen.items()):
+        if n > 1:
+            violations.append(Violation("H1", "", f"{key} assigned {n} times"))
+
+    by_staff: dict[str, list] = defaultdict(list)
+    for r in assigned:
+        by_staff[r.staff_employee_id].append(r)
+
+    for emp_id, flights in sorted(by_staff.items()):
+        # ---- H16: hard cap ----
+        if caps is not None and emp_id in caps and len(flights) > caps[emp_id]:
+            violations.append(
+                Violation("H16", emp_id, f"{len(flights)} flights > cap {caps[emp_id]}")
+            )
+
+        # ---- H10: spacing (all pairs inside the max window, not just
+        # neighbours: a domestic flight 20 min before an INTL one breaks
+        # the 30-min rule even with a flight in between) ----
+        timed = sorted((_spacing_key(r, ops_day), flight_key(r)) for r in flights)
+        for i, (a, a_key) in enumerate(timed):
+            for b, b_key in timed[i + 1:]:
+                gap = b[0] - a[0]
+                if gap >= SPACING_MAX_MIN:
+                    break
+                if gap < required_spacing_min(a, b):
+                    if frozenset({a_key, b_key}) in waived_pairs:
+                        continue
+                    violations.append(
+                        Violation(
+                            "H10",
+                            emp_id,
+                            f"{a_key} and {b_key} only {gap} min apart",
+                        )
+                    )
+    return violations

src/allocator/p2f_priority.py

@@ -0,0 +1,142 @@
+"""P2F-first priority: reserve each handler's P2F flights before anything else.
+
+Why this exists
+---------------
+A P2F flight can only go to the shift's nominated handler (eligibility F4).
+That same handler is also eligible for ordinary flights, and every one of
+those competes with his P2F flights for the same cap (H16) and the same
+15-minute spacing (H10). With every flight costing the same when left
+unallocated, nothing told the allocator that the handler's P2F work comes
+first, so he could end up filled with normal flights and a P2F left over.
+
+``select_p2f_priority`` decides, per handler, which P2F flights are
+*reserved* for him. The CP-SAT model then fixes those assignments and the
+normal flights are solved around them; the greedy fallback places them
+before it looks at any normal flight.
+
+Only flights that can be reserved *safely* are returned, so fixing them
+can never make the model infeasible:
+
+* the flight must have exactly one nominated handler eligible for it
+  (if two handlers could take it, the choice is left to the solver);
+* at most ``per_handler_limit`` (H17: 8) per handler, and never more than
+  the handler's own hard cap (H16);
+* two reserved P2F flights for one handler must be at least 30 min
+  apart (H10), unless the operator waived that pair;
+* a flight is skipped when a normal flight already pinned to the handler
+  (re-solve mode) is too close to it, or when it is pinned elsewhere.
+
+Anything skipped is returned with a reason so the caller can log it. Those
+flights are still allocated by the solver, just without the reservation.
+
+The module only needs flights with ``unique_id``, ``date``, ``std``,
+``ops_class`` and ``is_international`` — no solver dependency — so it is
+cheap to unit test.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Collection, Iterable, Mapping
+from datetime import date as date_t
+
+from ..schemas import OpsClass
+from .windows import SpacingKey, spacing_clear, spacing_key
+
+# H17: no handler is asked to do more than this many P2F flights a day.
+P2F_PER_HANDLER_LIMIT = 8
+
+
+def select_p2f_priority(
+    flights: Iterable,
+    eligibility: Mapping[str, Collection[str]],
+    handler_ids: Collection[str],
+    *,
+    ops_day: date_t,
+    cap_by_staff: Mapping[str, int],
+    per_handler_limit: int = P2F_PER_HANDLER_LIMIT,
+    pinned_assignments: Mapping[str, str] | None = None,
+    waive_h10_triples: Collection[tuple[str, str, str]] = frozenset(),
+) -> tuple[dict[str, str], list[tuple[str, str]]]:
+    """Pick the P2F flights to reserve for their handlers.
+
+    Returns ``(reserved, skipped)``:
+
+    * ``reserved`` — ``{flight_unique_id: handler_employee_id}``
+    * ``skipped``  — ``[(flight_unique_id, reason), ...]`` for every P2F
+      flight that was *not* reserved.
+    """
+    pinned = dict(pinned_assignments or {})
+    handler_set = set(handler_ids)
+    flight_list = list(flights)
+    key_of = {f.unique_id: spacing_key(f, ops_day) for f in flight_list}
+
+    reserved: dict[str, str] = {}
+    skipped: list[tuple[str, str]] = []
+
+    # Group each P2F flight under the single handler eligible for it.
+    by_handler: dict[str, list] = defaultdict(list)
+    for f in flight_list:
+        if f.ops_class != OpsClass.P2F:
+            continue
+        candidates = set(eligibility.get(f.unique_id, ())) & handler_set
+        if not candidates:
+            skipped.append((f.unique_id, "no nominated handler is eligible"))
+        elif len(candidates) > 1:
+            skipped.append((f.unique_id, "more than one handler is eligible"))
+        else:
+            by_handler[next(iter(candidates))].append(f)
+
+    # Times of ordinary flights already pinned to each handler (re-solve
+    # mode). A reserved P2F flight must keep H10 spacing from these.
+    p2f_uids = {f.unique_id for fl in by_handler.values() for f in fl}
+    pinned_normal: dict[str, list[SpacingKey]] = defaultdict(list)
+    for uid, eid in pinned.items():
+        if eid in by_handler and uid in key_of and uid not in p2f_uids:
+            pinned_normal[eid].append(key_of[uid])
+
+    def _waived(uid_a: str, uid_b: str, emp: str) -> bool:
+        return (
+            (uid_a, uid_b, emp) in waive_h10_triples
+            or (uid_b, uid_a, emp) in waive_h10_triples
+        )
+
+    for handler, p2f_flights in by_handler.items():
+        limit = min(per_handler_limit, cap_by_staff.get(handler, 0))
+        # Flights already pinned to this handler go first (they are fixed
+        # anyway), then earliest STD.
+        ordered = sorted(
+            p2f_flights,
+            key=lambda f: (pinned.get(f.unique_id) != handler, key_of[f.unique_id][0]),
+        )
+        taken: list = []
+        for f in ordered:
+            uid = f.unique_id
+            pinned_to = pinned.get(uid)
+            if pinned_to is not None and pinned_to != handler:
+                skipped.append((uid, f"pinned to {pinned_to}, not the handler"))
+                continue
+            if len(taken) >= limit:
+                skipped.append((uid, f"handler already has {limit} reserved (H17/H16)"))
+                continue
+            here = key_of[uid]
+            clash = next(
+                (
+                    o for o in taken
+                    if not _waived(uid, o.unique_id, handler)
+                    and not spacing_clear(here, [key_of[o.unique_id]])
+                ),
+                None,
+            )
+            if clash is not None:
+                skipped.append(
+                    (uid, f"too close to reserved P2F {clash.unique_id} (H10)")
+                )
+                continue
+            if not spacing_clear(here, pinned_normal.get(handler, ())):
+                skipped.append((uid, "too close to a flight already pinned to the handler"))
+                continue
+            taken.append(f)
+            reserved[uid] = handler
+
+    return reserved, skipped