flight-alloc 0.0.1__py3-none-any.whl

src/step1_clean_flights.py

@@ -0,0 +1,286 @@
+"""Step 1 — clean SV portal flights (plan §10 Phase 1).
+
+Reads the uploaded flight schedule and groups the surviving rows by
+OpsClass into ``state.cleaned``.
+
+Drop filter (Phase 3 INTL overhaul — 2026-05-14, amended 2026-05-19):
+  1. drop rows where date is None or dep_time is None
+  2. drop rows where date not in {D, D+1}
+  3. drop rows where date == D and std < 05:05  (asymmetric — see plan §1.5)
+  4. drop rows where date == D+1 and std > 05:30 (Change 7: widened from
+     05:05 to 05:30 — flights at 05:05-05:30 D+1 are KEPT with the
+     ``is_preplan_deferred=True`` flag, re-appended by Step 3 as
+     ``warning="PREPLAN_DEFERRED"``)
+  5. drop rows where dep is None or arr is None
+  6. drop rows where ops_class cannot be derived
+  7. drop rows where the cleaned-row schema rejects the values
+
+2026-05-19 amendment (Gulf routing):
+  * Gulf-3 DEP flights (AUH / DOH / DXB) and QR-owner flights are no
+    longer DROPPED. They route to OpsClass.GULF and land on the
+    dedicated GULF class for reference. Step 3 does not
+    read that sheet, so these flights are never allocated to staff —
+    same operational outcome as the legacy drop, but with audit-trail
+    visibility.
+  * ``routing_drop_dep_codes`` is now defunct; the new
+    ``ops_class_gulf_dep_codes`` + ``ops_class_gulf_owner_codes``
+    drive the routing.
+
+Phase 3 amendments (2026-05-14):
+  * Change 9: ``is_international = (dep ∈ intl_codes)`` — DEP-side only
+    (was DEP or ARR). Pink-highlight machinery removed.
+  * Change 7: D+1 STD 05:05-05:30 enters pool with ``is_preplan_deferred``.
+
+Pax (Booked Pax) is read for reference only as of 2026-05-10 — it does
+NOT drop rows or influence allocation. Unparseable pax strings (CV,
+empty, etc.) are kept with load=0.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable, Mapping
+from datetime import date as date_type
+from datetime import time, timedelta
+from pathlib import Path
+
+from .config import Config, load_config
+from .io.readers import read_sv_portal, workbook_from_bytes
+from .schemas import CleanFlightRow, OpsClass, RawFlightRow
+from .state import AppState
+
+CUTOFF: time = time(5, 5)
+# Phase 3 / Change 7: D+1 flights with STD in [CUTOFF, DEFERRED_UPPER]
+# are KEPT (flagged is_preplan_deferred); D+1 > DEFERRED_UPPER is dropped.
+DEFERRED_UPPER: time = time(5, 30)
+
+
+def _safe_load(pax_raw: str | None) -> int:
+    """Best-effort parse of a Booked Pax string to an int load. Pax is
+    reference-only since 2026-05-10 — unparseable values default to 0
+    rather than dropping the flight."""
+    if not pax_raw or not isinstance(pax_raw, str):
+        return 0
+    tail = pax_raw.rsplit("/", 1)[-1].strip()
+    try:
+        n = int(tail)
+    except (ValueError, TypeError):
+        return 0
+    return max(0, min(600, n))
+
+
+def _derive_ops_class(
+    aircraft_type: str | None,
+    owner: str | None,
+    dep: str,
+    arr: str,
+    row_date: date_type,
+    d_day: date_type,
+    ops_map: Mapping[str, str],
+    gulf_dep_codes: frozenset[str],
+    gulf_owner_codes: frozenset[str],
+) -> OpsClass | None:
+    """Routing precedence (highest to lowest):
+
+    1. GULF — DEP in ``gulf_dep_codes`` (AUH / DOH / DXB) OR owner /
+       TYPE letter in ``gulf_owner_codes`` (e.g. ``QR``). Extract-only:
+       the cleaned row lands in the GULF class but Step 3 ignores
+       that sheet, so these flights never enter the solver. Per user
+       direction 2026-05-19.
+    2. TYPE = X → TEST or FERRY based on routing (user direction
+       2026-05-11):
+         * dep == arr (same-airport loop) → TEST
+         * dep != arr (positioning leg)   → FERRY
+    3. Flat TYPE-letter mapping — H → P2F, B → CHARTER, K/P/T/G/W → FERRY.
+    4. Date-based fallback — D → DAY, D+1 → NIGHT (J / unknown types
+       routing to passenger ops).
+    """
+    owner_upper = (owner or "").strip().upper()
+    t_upper = (aircraft_type or "").strip().upper()
+    # 2026-05-19: GULF detection wins outright. DEP-side OR owner-side
+    # match routes the flight to the extract-only GULF class.
+    if dep in gulf_dep_codes:
+        return OpsClass.GULF
+    if owner_upper and owner_upper in gulf_owner_codes:
+        return OpsClass.GULF
+    if t_upper and t_upper in gulf_owner_codes:
+        return OpsClass.GULF
+    if t_upper == "X":
+        return OpsClass.TEST if dep == arr else OpsClass.FERRY
+    if t_upper:
+        mapped = ops_map.get(t_upper)
+        if mapped is not None:
+            try:
+                return OpsClass(mapped)
+            except ValueError:
+                return None
+    if row_date == d_day:
+        return OpsClass.DAY
+    if row_date == d_day + timedelta(days=1):
+        return OpsClass.NIGHT
+    return None
+
+
+def _matches_filter(
+    f: "dict[str, str]",
+    *, ac_type: str, ac_owner: str, ac: str, dep: str, arr: str,
+    extras: "dict[str, str]",
+) -> bool:
+    """Return True iff every non-empty field in ``f`` matches the
+    corresponding flight value (case-insensitive exact). Empty/missing
+    fields are skipped — they don't constrain the match. A filter
+    with every field blank never matches anything (returns False) so
+    a blank filter row in config can't accidentally drop the whole
+    pool."""
+    def _eq(target: str | None, actual: str) -> bool:
+        return bool(target and target.strip()
+                    and target.strip().upper() == actual.strip().upper())
+    constraints = [
+        ("ac_type", ac_type),
+        ("ac_owner", ac_owner),
+        ("ac", ac),
+        ("dep", dep),
+        ("arr", arr),
+    ]
+    active = False
+    for key, actual in constraints:
+        want = f.get(key) or ""
+        if want.strip():
+            active = True
+            if not _eq(want, actual):
+                return False
+    # Custom-header constraint.
+    ch = (f.get("custom_header") or "").strip()
+    cv = (f.get("custom_value") or "").strip()
+    if ch and cv:
+        active = True
+        cell = extras.get(ch) or ""
+        if cell.strip().upper() != cv.upper():
+            return False
+    return active
+
+
+def clean_flights(
+    raw_rows: Iterable[RawFlightRow],
+    d_day: date_type,
+    config: Config,
+) -> dict[OpsClass, list[CleanFlightRow]]:
+    d_plus_1 = d_day + timedelta(days=1)
+    # Phase 3 / Change 9: DEP-side only INTL definition.
+    intl_codes = {c.upper() for c in config.io.sv_portal.international_airport_codes}
+    ops_map = {k.upper(): v for k, v in config.ops_class_by_aircraft_type.items()}
+    # 2026-05-19: GULF routing — extract-only sheet, never allocated.
+    gulf_dep_codes = frozenset(
+        c.strip().upper() for c in config.ops_class_gulf_dep_codes if c.strip()
+    )
+    gulf_owner_codes = frozenset(
+        c.strip().upper() for c in config.ops_class_gulf_owner_codes if c.strip()
+    )
+    # 2026-05-25: user-defined extraction filters. Flights matching any
+    # filter route to OpsClass.GULF — same destination as Gulf-DEP
+    # flights (extract-only, never allocated).
+    extraction_filters = list(config.extraction_filters or [])
+
+    out: dict[OpsClass, list[CleanFlightRow]] = defaultdict(list)
+
+    for r in raw_rows:
+        if r.date is None or r.dep_time is None:
+            continue
+        if r.date not in (d_day, d_plus_1):
+            continue
+        if r.date == d_day and r.dep_time < CUTOFF:
+            continue
+        # Phase 3 / Change 7: D+1 keep-window widened to [CUTOFF, DEFERRED_UPPER]
+        # inclusive. STD in that band is flagged is_preplan_deferred. Anything
+        # past DEFERRED_UPPER on D+1 is dropped.
+        if r.date == d_plus_1 and r.dep_time > DEFERRED_UPPER:
+            continue
+        if r.departure is None or r.arrival is None:
+            continue
+        dep = r.departure[:3].upper()
+        arr = r.arrival[:3].upper()
+        # 2026-05-19: Gulf-3 + QR-owner flights are no longer dropped.
+        # They route to OpsClass.GULF (extract-only) — see
+        # _derive_ops_class precedence. Step 3 ignores the GULF class
+        # so they stay out of the solver naturally.
+        # Pax is reference-only (user direction 2026-05-10) — never
+        # dropped on this basis. Unparseable pax becomes load=0.
+        load = _safe_load(r.booked_pax_raw)
+        ops = _derive_ops_class(
+            r.aircraft_type, r.owner,
+            dep, arr, r.date, d_day, ops_map,
+            gulf_dep_codes, gulf_owner_codes,
+        )
+        if ops is None:
+            continue
+        # 2026-05-25: user-defined extraction filters override the
+        # derived ops_class. If any filter matches, route the flight
+        # to OpsClass.GULF (extract-only sheet) regardless of what
+        # _derive_ops_class returned. Filters run AFTER ops_class
+        # derivation so the original class is known (helpful for
+        # debugging / log output later if needed) but the destination
+        # is overridden to GULF when matched.
+        if extraction_filters:
+            ac_type_val = str(r.aircraft_type or "")
+            ac_owner_val = str(r.owner or "")
+            ac_val = str(r.aircraft_subtype or "")
+            extras = r.extra_columns or {}
+            for f in extraction_filters:
+                if _matches_filter(
+                    f,
+                    ac_type=ac_type_val, ac_owner=ac_owner_val,
+                    ac=ac_val, dep=dep, arr=arr, extras=extras,
+                ):
+                    ops = OpsClass.GULF
+                    break
+        # Change 7: deferred = D+1 row whose STD is at/after CUTOFF
+        # (D+1 < CUTOFF is the existing post-midnight NIGHT tail).
+        is_deferred = (r.date == d_plus_1 and r.dep_time >= CUTOFF)
+        try:
+            cleaned = CleanFlightRow(
+                date=r.date,
+                flt=str(r.flight_id) if r.flight_id is not None else "",
+                type=str(r.aircraft_type or ""),
+                ac=str(r.aircraft_subtype or ""),
+                dep=dep,
+                arr=arr,
+                std=r.dep_time,
+                load=load,
+                ops_class=ops,
+                # Change 9 (2026-05-14): DEP-side only.
+                # 2026-05-16: P2F flights are NEVER marked international
+                # even when their DEP airport (e.g. DAC, KMG) is in the
+                # INTL list. P2F has its own dedicated routing + color
+                # convention; the INTL flag is for regular DEP-side INTL
+                # passenger ops only.
+                is_international=(dep in intl_codes
+                                  and ops != OpsClass.P2F),
+                is_preplan_deferred=is_deferred,
+            )
+        except ValueError:
+            continue
+        out[ops].append(cleaned)
+
+    return dict(out)
+
+
+def run(
+    state: AppState,
+    d_day: date_type,
+    config_path: Path | str = "configs/config.yml",
+) -> dict[OpsClass, int]:
+    """Clean the uploaded flight schedule into ``state.cleaned``.
+
+    Returns the row count per OpsClass. Raises FileNotFoundError when
+    the schedule has not been uploaded yet.
+    """
+    config = load_config(config_path)
+    wb = workbook_from_bytes(state.input_bytes("sv_portal"))
+    try:
+        raw = read_sv_portal(wb, config)
+    finally:
+        wb.close()
+    by_class = clean_flights(raw, d_day, config)
+    with state.lock:
+        state.cleaned = by_class
+    return {k: len(v) for k, v in by_class.items()}

src/step2_extract_roster.py

@@ -0,0 +1,316 @@
+"""Step 2 — extract roster availability (plan §10 Phase 2).
+
+Reads the two uploaded rosters (regular staff + AM/ZC), normalises
+statuses, and stores the long-format availability matrix in
+``state.availability``. Coverage-shortfall warnings (W010, W011) land in
+``state.warnings``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import date as date_t
+from datetime import timedelta
+from pathlib import Path
+from typing import cast
+
+from .config import Config, load_config
+from .io.readers import DuplicateEmployeeIdError
+from .io.roster_library import read_library
+from .schemas import (
+    NON_ASSIGNABLE,
+    SHIFT_CODES,
+    AMRosterRow,
+    AvailabilityRow,
+    CrewRosterRow,
+    CrewStatus,
+    Role,
+    Severity,
+    ShiftCode,
+    WarningRow,
+)
+
+# 2026-05-27 (centralization): the per-status shift mapping now lives
+# in schemas.STATUS_TO_SHIFT (single source of truth). This local alias
+# is kept ONLY for readability at call sites that already say
+# `_STATUS_TO_SHIFT.get(...)` — its content is byte-identical to the
+# central map. When a new status is added to CrewStatus, update the
+# central STATUS_TO_SHIFT and every consumer picks it up — no more
+# scattered duplicates to keep in sync.
+from .schemas import STATUS_TO_SHIFT as _STATUS_TO_SHIFT
+
+# Status values that ALSO imply a P2F license, even if the License column
+# 2026-05-27 (centralization): the set of P2F-license-granting statuses
+# now lives in schemas.P2F_LICENSE_GRANTING_STATUSES. The alias is kept
+# so existing call sites read clearly. Add a new combined ZC+P2F or
+# plain P2F status to the central STATUS_TO_P2F_HANDLER_SHIFT map and
+# this set picks it up automatically.
+from .schemas import P2F_LICENSE_GRANTING_STATUSES as _P2F_HANDLER_STATUSES
+from .state import AppState
+
+
+def _emit_for_window(
+    rows: Iterable[CrewRosterRow | AMRosterRow],
+    window: list[date_t],
+) -> list[AvailabilityRow]:
+    out: list[AvailabilityRow] = []
+    for crew in rows:
+        for d in window:
+            if d not in crew.status_by_date:
+                continue
+            status = crew.status_by_date[d]
+            raw = crew.raw_status_by_date.get(d, "")
+            # Derive current_shift from any shift-bearing status: plain
+            # shifts (M/A/N/M1/A1), ZC variants (M/ZC etc.), and P2F-
+            # handler variants (P2F/M etc.). Older code only matched the
+            # plain shifts via SHIFT_CODES, which left ZC/P2F rows with
+            # current_shift=None — Step 3 then skipped them entirely.
+            current_shift: ShiftCode | None = _STATUS_TO_SHIFT.get(status)
+            if current_shift is None and status.value in SHIFT_CODES:
+                # Defensive fallback for any new shift literal added to
+                # CrewStatus without an entry in the map above.
+                current_shift = cast(ShiftCode, status.value)
+            # P2F-handler statuses auto-populate the license column so
+            # downstream eligibility (F3 + F4) treats them as P2F-
+            # licensed even when the assigner didn't set the License
+            # cell explicitly.
+            license_val = crew.license
+            if status in _P2F_HANDLER_STATUSES and not (
+                license_val and "P2F" in license_val.upper()
+            ):
+                license_val = "P2F (auto from roster cell)"
+            # 2026-05-23: per-day role override. Previously crew.role
+            # was inferred at READ time across the entire row's date
+            # window — so an AM who was M/ZC on one day got tagged
+            # Role.ZC for EVERY day, including days they were just
+            # plain M. The bug surfaced as "AMs showing up as ZC" in
+            # the dashboard. Fix: derive role per-day from THIS day's
+            # status only; fall back to the crew's sheet-origin role.
+            day_role = crew.role
+            if status in (
+                CrewStatus.ZC_M, CrewStatus.ZC_A, CrewStatus.ZC_N,
+                CrewStatus.ZC_M1, CrewStatus.ZC_A1,
+                # 2026-05-26: combined ZC+P2F cells also imply ZC role.
+                CrewStatus.ZC_P2F_M, CrewStatus.ZC_P2F_A, CrewStatus.ZC_P2F_N,
+                CrewStatus.ZC_P2F_M1, CrewStatus.ZC_P2F_A1,
+            ):
+                day_role = Role.ZC
+            elif crew.role == Role.ZC:
+                # Row-level inferred ZC but TODAY's cell isn't /ZC —
+                # treat as AM (sheet origin = IN_AM_Roster).
+                day_role = Role.AM
+            out.append(AvailabilityRow(
+                employee_id=crew.employee_id,
+                name=crew.name,
+                role=day_role,
+                date=d,
+                status=status,
+                raw_status=raw,
+                assignable=status not in NON_ASSIGNABLE,
+                current_shift=current_shift,
+                license=license_val,
+                origin_role=Role.STAFF if crew.role == Role.STAFF else Role.AM,
+            ))
+    return out
+
+
+def _coverage_warning(
+    code: str,
+    label: str,
+    rows_loaded: int,
+    covered_dates: set[date_t],
+    target_window: list[date_t],
+) -> WarningRow | None:
+    if rows_loaded == 0:
+        return None
+    missing = [d for d in target_window if d not in covered_dates]
+    if not missing:
+        return None
+    iso = ", ".join(d.isoformat() for d in missing)
+    return WarningRow(
+        severity=Severity.WARN,
+        code=code,
+        message=(
+            f"{label} roster does not cover {iso}; "
+            "emitting empty availability for those dates."
+        ),
+    )
+
+
+def extract_availability(
+    staff_rows: list[CrewRosterRow],
+    am_rows: list[AMRosterRow],
+    d_day: date_t,
+) -> tuple[list[AvailabilityRow], list[WarningRow]]:
+    window: list[date_t] = [d_day, d_day + timedelta(days=1)]
+
+    staff_dates: set[date_t] = set()
+    for s in staff_rows:
+        staff_dates.update(s.status_by_date.keys())
+    am_dates: set[date_t] = set()
+    for a in am_rows:
+        am_dates.update(a.status_by_date.keys())
+
+    warnings: list[WarningRow] = []
+    w_staff = _coverage_warning("W010", "staff", len(staff_rows), staff_dates, window)
+    if w_staff is not None:
+        warnings.append(w_staff)
+    w_am = _coverage_warning("W011", "AM", len(am_rows), am_dates, window)
+    if w_am is not None:
+        warnings.append(w_am)
+
+    avail = _emit_for_window(staff_rows, window) + _emit_for_window(am_rows, window)
+    return avail, warnings
+
+
+def run(
+    state: AppState,
+    d_day: date_t,
+    config_path: Path | str = "configs/config.yml",
+    *,
+    append_warnings: bool = False,
+) -> dict[str, int]:
+    """Read both uploaded rosters and store availability + warnings on
+    ``state``. Returns a per-role count dict plus WARNINGS."""
+    config: Config = load_config(config_path)
+    # The rosters on file cover whole periods and there can be several
+    # of them; read the ones that have a column for D / D+1 and merge.
+    window = [d_day, d_day + timedelta(days=1)]
+    avail: list[AvailabilityRow] = []
+    warnings: list[WarningRow] = []
+    try:
+        staff_rows = read_library(state, "staff_roster", config, window)
+        am_rows = read_library(state, "am_roster", config, window)
+    except DuplicateEmployeeIdError as e:
+        # W020: Surface as ERROR and abort.
+        warnings = [WarningRow(
+            severity=Severity.ERROR,
+            code="W020",
+            message=str(e),
+        )]
+        _store_warnings(state, warnings, append=append_warnings)
+        return {"WARNINGS": len(warnings), "ABORTED": 1}
+    # 2026-05-27 (user direction): also check for CROSS-roster ID
+    # collisions. _check_unique_employee_ids only validates within
+    # one sheet at a time — if the same employee_id appears in
+    # BOTH Staff_Roster and AM_Roster, downstream code collapses
+    # the two rows into one decision variable in the solver. The
+    # M1/ZC entry that "doesn't get extracted" is actually
+    # silently overwritten by the same-id row from the other
+    # sheet. Abort with a clear message.
+    cross_dup_ids: list[tuple[str, str, str]] = []   # (id, staff_name, am_name)
+    staff_id_to_name = {r.employee_id: r.name for r in staff_rows}
+    for r in am_rows:
+        if r.employee_id in staff_id_to_name:
+            cross_dup_ids.append(
+                (r.employee_id, staff_id_to_name[r.employee_id], r.name)
+            )
+    if cross_dup_ids:
+        previews = "; ".join(
+            f"id={eid!r}: Staff={sn!r}, AM={an!r}"
+            for eid, sn, an in cross_dup_ids[:5]
+        )
+        if len(cross_dup_ids) > 5:
+            previews += f", … (+{len(cross_dup_ids) - 5} more)"
+        warnings = [WarningRow(
+            severity=Severity.ERROR,
+            code="W022",
+            message=(
+                f"{len(cross_dup_ids)} employee_id(s) appear in BOTH "
+                f"the staff roster AND the AM roster: {previews}. Each "
+                "staff must have a UNIQUE id across both sheets — the "
+                "solver keys decision variables by id, so duplicates "
+                "silently drop one of the rows (the M1/ZC entry the "
+                "assigner expected to see often disappears this way). "
+                "Fix the IDs in the source files, re-upload, re-run."
+            ),
+        )]
+        _store_warnings(state, warnings, append=append_warnings)
+        return {"WARNINGS": len(warnings), "ABORTED": 1}
+    # 2026-05-27 (informational): same NAME with DIFFERENT IDs
+    # across rosters is allowed (it's a real scenario — different
+    # people with the same name), but emit a WARN so the assigner
+    # knows to be careful when matching override rows by name.
+    staff_names_lower = {r.name.strip().upper(): r.employee_id for r in staff_rows}
+    same_name_diff_id: list[tuple[str, str, str]] = []  # (name, staff_id, am_id)
+    for r in am_rows:
+        key = r.name.strip().upper()
+        if key in staff_names_lower and staff_names_lower[key] != r.employee_id:
+            same_name_diff_id.append((r.name, staff_names_lower[key], r.employee_id))
+    # Also same name within Staff sheet (different IDs already
+    # caught for the same sheet by _check_unique_employee_ids on
+    # ids — but two different ids with the SAME name slip past).
+    staff_name_counts: dict[str, list[str]] = {}
+    for r in staff_rows:
+        staff_name_counts.setdefault(r.name.strip().upper(), []).append(r.employee_id)
+    dup_names_in_staff = [
+        (name, ids) for name, ids in staff_name_counts.items() if len(ids) > 1
+    ]
+    cross_warns: list[WarningRow] = []
+    if same_name_diff_id:
+        previews = "; ".join(
+            f"{nm!r} (Staff id={sid}, AM id={aid})"
+            for nm, sid, aid in same_name_diff_id[:5]
+        )
+        cross_warns.append(WarningRow(
+            severity=Severity.WARN,
+            code="W023",
+            message=(
+                f"{len(same_name_diff_id)} name(s) appear in BOTH "
+                f"rosters with different IDs: {previews}. Override "
+                "rows that match by name will resolve to the AM-roster "
+                "ID (later wins). Use IDs explicitly in overrides to "
+                "be unambiguous."
+            ),
+        ))
+    if dup_names_in_staff:
+        previews = "; ".join(
+            f"{nm!r} (ids: {', '.join(ids)})"
+            for nm, ids in dup_names_in_staff[:5]
+        )
+        cross_warns.append(WarningRow(
+            severity=Severity.WARN,
+            code="W024",
+            message=(
+                f"{len(dup_names_in_staff)} name(s) appear MORE THAN "
+                f"ONCE in the staff roster with distinct IDs: {previews}. "
+                "Override rows that match by name will resolve to "
+                "the LAST-seen ID. Disambiguate via IDs in overrides."
+            ),
+        ))
+    avail, warnings = extract_availability(staff_rows, am_rows, d_day)
+    warnings = cross_warns + warnings
+    with state.lock:
+        state.availability = avail
+    _store_warnings(state, warnings, append=append_warnings)
+
+    # Re-apply the staged drawer mutations AFTER availability has been
+    # rebuilt from the raw rosters. Without this, every Plan wipes the
+    # assigner's staged intent (remove_staff flipping assignable=False,
+    # add_staff synthetic rows, add_flight / remove_flight) and the
+    # solver sees the original roster instead. The override list is the
+    # source of truth; cleaned flights + availability are working
+    # copies that get patched here on every step2 run.
+    from . import staged_overrides as _so
+    applied = _so.apply_staged_overrides(state, d_day)
+    total = sum(applied.values()) if applied else 0
+    if total:
+        print(
+            "  staged overrides re-applied after roster rebuild: "
+            + ", ".join(f"{k}={v}" for k, v in applied.items() if v)
+        )
+
+    counts: dict[str, int] = {}
+    for r in avail:
+        counts[r.role.value] = counts.get(r.role.value, 0) + 1
+    counts["WARNINGS"] = len(warnings)
+    return counts
+
+
+def _store_warnings(
+    state: AppState, warnings: list[WarningRow], *, append: bool,
+) -> None:
+    """Put this stage's warnings on the state, either appending to what
+    a previous stage left or replacing it."""
+    with state.lock:
+        state.warnings = (list(state.warnings) + warnings) if append else list(warnings)