flight-alloc 0.0.1__py3-none-any.whl

src/io/roster_library.py

@@ -0,0 +1,89 @@
+"""Read the stored period rosters as one merged roster.
+
+The staff roster arrives about once a month and the periods don't line
+up with calendar months (31 Aug - 27 Sep, then 28 Sep - 25 Oct, ...).
+The app keeps every roster it has been given; this module turns "the
+rosters on file" into the rows for one allocation date:
+
+  * pick the stored files that have a column for the date (and the day
+    after it — Plan reads D and D+1);
+  * read each with the normal wide-roster reader;
+  * merge people across files by employee id, dated cells from a later
+    upload overriding the same date from an earlier one.
+
+So on the last day of a roster, D comes from the current file and D+1
+comes from the next one, without the operator doing anything.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from datetime import date as date_t
+from typing import TypeVar
+
+from ..config import Config
+from ..schemas import AMRosterRow, CrewRosterRow
+from ..state import AppState
+from .readers import read_am_roster, read_staff_roster, workbook_from_bytes
+
+Row = TypeVar("Row", CrewRosterRow, AMRosterRow)
+
+
+def read_roster_bytes(kind: str, data: bytes, config: Config) -> list:
+    """Parse one uploaded roster of ``kind`` into typed rows."""
+    reader = {"staff_roster": read_staff_roster, "am_roster": read_am_roster}[kind]
+    wb = workbook_from_bytes(data)
+    try:
+        return reader(wb, config)
+    finally:
+        wb.close()
+
+
+def roster_dates(kind: str, data: bytes, config: Config) -> set[date_t]:
+    """Every date the workbook has a column for. Also validates the file
+    (missing ID column, duplicate ids, unknown layout) — the upload
+    endpoint calls this so a bad roster is rejected at the door with the
+    reader's own message instead of failing later inside Plan."""
+    dates: set[date_t] = set()
+    for row in read_roster_bytes(kind, data, config):
+        dates.update(row.status_by_date.keys())
+    return dates
+
+
+def merge_rows(per_file_rows: Sequence[Sequence[Row]]) -> list[Row]:
+    """Merge rows from several rosters, oldest upload first.
+
+    Same employee id -> one row: identity fields (name, licence, role)
+    come from the newest file that lists the person, and per-date cells
+    are unioned with the newest file winning any date both cover.
+    """
+    merged: dict[str, Row] = {}
+    for rows in per_file_rows:
+        for row in rows:
+            prev = merged.get(row.employee_id)
+            if prev is None:
+                merged[row.employee_id] = row
+                continue
+            merged[row.employee_id] = row.model_copy(update={
+                "status_by_date": {**prev.status_by_date, **row.status_by_date},
+                "raw_status_by_date": {
+                    **getattr(prev, "raw_status_by_date", {}),
+                    **getattr(row, "raw_status_by_date", {}),
+                },
+            })
+    return list(merged.values())
+
+
+def read_library(
+    state: AppState, kind: str, config: Config,
+    window: Iterable[date_t] | None = None,
+) -> list:
+    """Rows for ``kind`` from the stored rosters relevant to ``window``.
+
+    Raises FileNotFoundError (with the UI's own wording) when nothing has
+    been uploaded for ``kind``.
+    """
+    files = state.roster_files_for(kind, window)
+    if not files:
+        state.input_bytes(kind)          # raises the standard message
+    return merge_rows([read_roster_bytes(kind, f.data, config) for f in files])

src/plan.py

@@ -0,0 +1,192 @@
+"""Plan stage — Step 1 + Step 2 only, plus the summary the assigner
+reviews before allocating.
+
+Flow:
+
+  1. Step 1: clean the uploaded flight schedule into ``state.cleaned``.
+  2. Step 2: extract the rosters into ``state.availability``.
+  3. Compute the summary (this module's contribution):
+        - flights to be planned, per ops_class and per shift window
+        - staff on shift today, per shift
+        - recommendations: day/night headcount, P2F handlers (1 per 8
+          P2F flights per shift)
+        - the gap, if any
+  4. Store it on ``state.plan_summary`` / ``state.plan_text`` and print
+     a readable version to the server console.
+
+The assigner reviews the dashboard, stages any overrides in the drawer,
+then clicks Allocate.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import date as date_t
+from pathlib import Path
+
+from .allocator.windows import SHIFT_NOMINAL_MIN, std_to_ops_day_minutes
+from .config import load_config
+from .schemas import OpsClass
+from .state import AppState
+from .step1_clean_flights import run as run_step1
+from .step2_extract_roster import run as run_step2
+
+# Operational ceilings used for recommendations.
+P2F_FLIGHTS_PER_HANDLER = 8
+TARGET_FLIGHTS_PER_STAFF_DAY = 22  # STAFF day-shift acceptable
+TARGET_FLIGHTS_PER_STAFF_NIGHT = 19  # STAFF night-shift acceptable
+
+
+def _cleaned_breakdown(state: AppState) -> dict[str, int]:
+    """Flight count per ops_class. Every class is present (0 when empty)
+    so the dashboard cards never have to guard for missing keys."""
+    out = {o.value: 0 for o in OpsClass}
+    for ops, rows in state.cleaned.items():
+        out[ops.value] = len(rows)
+    return out
+
+
+def _p2f_per_shift(state: AppState, d_day: date_t) -> dict[str, int]:
+    """Count P2F flights by which M/A/N shift's nominal window holds them."""
+    counts: Counter[str] = Counter()
+    for row in state.cleaned.get(OpsClass.P2F, []):
+        std_min = std_to_ops_day_minutes(row.std, row.date, d_day)
+        for shift, (start, end) in SHIFT_NOMINAL_MIN.items():
+            if shift in ("M", "A", "N") and start <= std_min <= end:
+                counts[shift] += 1
+                break
+    return dict(counts)
+
+
+def _staff_counts_today(state: AppState, d_day: date_t) -> dict[str, int]:
+    """Count assignable staff per shift on D."""
+    counts: Counter[str] = Counter()
+    d_iso = d_day.isoformat()
+    for av in state.availability:
+        if av.date.isoformat() != d_iso or not av.assignable:
+            continue
+        if not av.current_shift:
+            continue
+        counts[av.current_shift] += 1
+    return dict(counts)
+
+
+def _format_summary(
+    flights: dict[str, int],
+    p2f_per_shift: dict[str, int],
+    staff: dict[str, int],
+    d_day: date_t,
+) -> tuple[str, dict[str, object]]:
+    """Build the plain-text summary and a JSON-friendly dict for the UI."""
+    target_per_day_staff = TARGET_FLIGHTS_PER_STAFF_DAY
+    target_per_night_staff = TARGET_FLIGHTS_PER_STAFF_NIGHT
+    day_staff = sum(staff.get(s, 0) for s in ("M", "A", "M1", "A1"))
+    night_staff = staff.get("N", 0)
+
+    def _ceil_div(a: int, b: int) -> int:
+        return -(-a // b) if b else 0
+
+    needed_day_staff = _ceil_div(flights["day"], target_per_day_staff)
+    needed_night_staff = _ceil_div(flights["night"], target_per_night_staff)
+    day_gap = max(0, needed_day_staff - day_staff)
+    night_gap = max(0, needed_night_staff - night_staff)
+
+    p2f_handlers_needed = sum(
+        _ceil_div(n, P2F_FLIGHTS_PER_HANDLER) for n in p2f_per_shift.values()
+    )
+
+    lines: list[str] = []
+    lines.append(f"=== Plan summary for D={d_day.isoformat()} ===\n")
+    lines.append("FLIGHTS TO BE PLANNED")
+    lines.append(f"  Day ops:  {flights['day']:5d}")
+    lines.append(f"  Night ops:{flights['night']:5d}")
+    lines.append(f"  P2F:      {flights['p2f']:5d}     "
+                 f"per shift: M={p2f_per_shift.get('M', 0)} "
+                 f"A={p2f_per_shift.get('A', 0)} "
+                 f"N={p2f_per_shift.get('N', 0)}")
+    lines.append(f"  Ferry:    {flights['ferry']:5d}")
+    lines.append(f"  Charter:  {flights['charter']:5d}")
+    lines.append(f"  Test:     {flights['test']:5d}")
+    # GULF is extract-only — the solver never sees it, so it must not
+    # inflate the plannable total.
+    plannable_total = sum(v for k, v in flights.items() if k != "gulf")
+    lines.append(f"  Total:    {plannable_total:5d}")
+    lines.append(f"  Gulf (extracted, NOT allocated): {flights['gulf']}")
+    lines.append("")
+    lines.append("STAFF ON SHIFT TODAY")
+    for s in ("M", "A", "N", "M1", "A1"):
+        lines.append(f"  {s:3} : {staff.get(s, 0):3d}")
+    lines.append(f"  Day staff (M+A+M1+A1):  {day_staff}")
+    lines.append(f"  Night staff (N):         {night_staff}")
+    lines.append("")
+    lines.append("RECOMMENDATIONS")
+    lines.append(
+        f"  Day staff needed (target {target_per_day_staff}/staff): "
+        f"{needed_day_staff}  -> gap: {day_gap}"
+    )
+    lines.append(
+        f"  Night staff needed (target {target_per_night_staff}/staff): "
+        f"{needed_night_staff}  -> gap: {night_gap}"
+    )
+    lines.append(
+        f"  P2F handlers needed (1 per {P2F_FLIGHTS_PER_HANDLER} flights): "
+        f"{p2f_handlers_needed}"
+    )
+    lines.append("")
+    lines.append("NEXT STEP")
+    if day_gap or night_gap:
+        lines.append("  Add staff for the gap shifts via the Override drawer,")
+        lines.append("  OR proceed to allocate (gap flights will be UNALLOCATED).")
+    else:
+        lines.append("  Staff coverage looks OK. Click Allocate.")
+
+    text = "\n".join(lines)
+    payload = {
+        "date": d_day.isoformat(),
+        "flights": flights,
+        "p2f_per_shift": p2f_per_shift,
+        "staff": staff,
+        "day_staff_total": day_staff,
+        "night_staff_total": night_staff,
+        "needed_day_staff": needed_day_staff,
+        "needed_night_staff": needed_night_staff,
+        "day_gap": day_gap,
+        "night_gap": night_gap,
+        "p2f_handlers_needed": p2f_handlers_needed,
+    }
+    return text, payload
+
+
+def run(
+    state: AppState,
+    d_day: date_t,
+    config_path: Path | str = "configs/config.yml",
+) -> dict[str, object]:
+    """Run Step 1 + Step 2, then build the plan summary. Returns the
+    JSON-friendly payload (also stored on ``state.plan_summary``)."""
+    load_config(config_path)  # fail fast if the config is unreadable
+    run_step1(state, d_day, config_path)
+    run_step2(state, d_day, config_path)
+
+    flights = _cleaned_breakdown(state)
+    p2f_per_shift = _p2f_per_shift(state, d_day)
+    staff = _staff_counts_today(state, d_day)
+    text, payload = _format_summary(flights, p2f_per_shift, staff, d_day)
+    print(text)
+
+    with state.lock:
+        state.run_date = d_day
+        state.plan_summary = payload
+        state.plan_text = text
+
+    # Staffing recommender: required = max(peak_floor, volume_floor,
+    # p2f_floor) per shift. Advisory — a failure here must not break Plan.
+    from . import recommender_staffing as _rs
+    try:
+        _rs.run_for_state(state, d_day)
+    except Exception as exc:  # noqa: BLE001
+        print(f"  WARNING: staffing recommender failed: {exc}")
+
+    state.stamp_run(mode="Plan", solver_status="(Plan only — no solve)",
+                    duration_s=None)
+    return payload

src/recommender_staffing.py

@@ -0,0 +1,329 @@
+"""Staffing recommender — per-shift required-headcount calculator.
+
+Per user direction 2026-05-22:
+
+  required(S) = max(
+      peak_floor(S),            # peak-hour flights / 4 (H10 spacing)
+      volume_floor(S),          # total flights / hard_cap (capacity ceiling)
+      p2f_floor(S),             # 1 if any P2F flight in shift, else 0
+  )
+
+No sick/surge buffer (staff handle that operationally). No mentor /
+pre-planner floor (user direction: only P2F qualifies as a 'must-fill'
+position for the recommender's purpose).
+
+Output schema (see ``StaffingRecommendation`` below) is stored on
+``state.staffing`` and surfaced via /api/staffing for the dashboard.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections import Counter
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass
+from datetime import date as date_t
+from datetime import time as time_t
+from datetime import timedelta
+from pathlib import Path
+
+from .schemas import Role, ShiftCode
+from .state import AppState
+
+# H10 hard spacing floor (minutes between consecutive same-staff flights).
+_H10_SPACING_MIN = 15
+# Max flights one staff can handle per hour, derived from H10.
+_FLIGHTS_PER_STAFF_PER_HOUR = 60 // _H10_SPACING_MIN  # = 4
+
+# Pool-based primary STD bands. The recommender treats M/M1 and A/A1 as
+# shared-coverage pools (since both shifts work overlapping hours and the
+# engine allocates across both freely). Output rows = {MORNING, AFTERNOON,
+# NIGHT}. The per-shift split inside each pool is reported as a context
+# breakdown but the required-headcount math is computed pool-level.
+# 2026-05-24 (user direction): AFTERNOON shrunk back to 13:00-21:00 so
+# the 21:00-22:55 evening surge (~160 flights on a busy day) lands in
+# NIGHT — A1 is still active there but N is the destination shift
+# for those legs. Net: AFTERNOON required drops from ~51 to ~44 (in
+# line with the 35-36 the assigner expects operationally), NIGHT is
+# higher but A1 overlap helps cover the early hours.
+_POOL_BANDS_MIN: dict[str, tuple[int, int]] = {
+    "MORNING":   (5 * 60 + 5,  13 * 60),
+    "AFTERNOON": (13 * 60,     21 * 60),
+    "NIGHT":     (21 * 60,     24 * 60 + 5 * 60 + 5),
+}
+_POOL_SHIFTS: dict[str, tuple[ShiftCode, ...]] = {
+    "MORNING":   ("M", "M1"),
+    "AFTERNOON": ("A", "A1"),
+    "NIGHT":     ("N",),
+}
+# 2026-05-24 (user direction): A1 stays in AFTERNOON pool but shares
+# capacity with N during the 21:00-23:00 overlap. When computing
+# NIGHT pool's required headcount, attribute some of the 21:00-23:00
+# flight load to A1 (proportional to A1:N staff ratio), so we don't
+# over-count N's burden. A1's pool membership and breakdown action
+# remain on AFTERNOON only.
+_A1_NIGHT_OVERLAP_BAND = (21 * 60, 23 * 60)   # 21:00 - 22:59
+
+# Per-(shift, role) hard caps from configs/shift_limits.json. We pull the
+# STAFF cap since the volume floor is computed against the dominant role.
+_SHIFT_LIMITS_PATH = Path(__file__).resolve().parents[1] / "configs" / "shift_limits.json"
+
+_SHIFTS: tuple[ShiftCode, ...] = ("M", "M1", "A", "A1", "N")
+_POOLS: tuple[str, ...] = ("MORNING", "AFTERNOON", "NIGHT")
+
+
+@dataclass(frozen=True)
+class StaffingRecommendation:
+    """One row of the recommendation — per shift pool, with a per-shift
+    breakdown so the operator knows exactly which shift to add to or
+    remove from."""
+
+    pool: str
+    shifts_in_pool: str
+    assigned_today: int
+    assigned_breakdown: str
+    target_breakdown: str             # 2026-05-22: per-shift target headcount after applying recommendation, e.g. "M=28, M1=9"
+    breakdown_action: str             # 2026-05-22: actionable per-shift delta, e.g. "REMOVE 6 from M, REMOVE 2 from M1"
+    flights_in_window: int
+    peak_hour: str
+    peak_hour_flights: int
+    has_p2f_flight: bool
+    target_per_staff: int
+    hard_cap_per_staff: int
+    peak_floor: int
+    volume_floor: int
+    p2f_floor: int
+    required: int
+    bottleneck: str
+    gap: int
+    action: str
+    implied_avg_per_staff: float
+
+
+def _load_shift_limits() -> dict[str, dict[str, dict[str, int]]]:
+    """Read configs/shift_limits.json. Returns the ``shifts`` map."""
+    raw = json.loads(_SHIFT_LIMITS_PATH.read_text(encoding="utf-8"))
+    return raw["shifts"]
+
+
+def _std_minutes(std: time_t) -> int:
+    """Convert a time-of-day to minutes since midnight."""
+    return std.hour * 60 + std.minute
+
+
+def _flight_in_window(std: time_t, flight_date: date_t, d_day: date_t,
+                      window_inner: tuple[int, int]) -> bool:
+    """True iff the flight's STD falls within the shift's inner window.
+
+    Window minutes are relative to D-day 00:00; N-shift wraps past midnight
+    (end > 24*60), so D+1 flights with STD < 05:00 are treated as ops-day
+    minute = std + 24*60.
+    """
+    start_min, end_min = window_inner
+    flt_min = _std_minutes(std)
+    if flight_date == d_day + timedelta(days=1):
+        flt_min += 24 * 60
+    return start_min <= flt_min < end_min
+
+
+def _hour_label(std: time_t, flight_date: date_t, d_day: date_t) -> str:
+    """Bucket label for hourly histogram. D+1 flights display as 24+ to
+    keep N-shift contiguous when reading top-to-bottom."""
+    h = std.hour
+    if flight_date == d_day + timedelta(days=1):
+        h += 24
+    return f"{h % 24:02d}:00"
+
+
+def compute_staffing(
+    flights: Iterable[tuple[date_t, time_t, str]],
+    assigned_by_shift: dict[str, int],
+    d_day: date_t,
+) -> list[StaffingRecommendation]:
+    """Compute required headcount per shift.
+
+    Args:
+        flights: iterable of (flight_date, std, ops_class) tuples. ops_class
+                 is a lowercase string ('day', 'night', 'p2f',
+                 'ferry', 'test', 'charter', 'gulf'). Gulf flights are
+                 filtered out before the math — extract-only.
+        assigned_by_shift: {'M': n, 'M1': n, ...} headcount from the roster
+                           (STAFF + ZC, AM excluded).
+        d_day: the operating D-day.
+    """
+    limits = _load_shift_limits()
+    # Filter out Gulf (extract-only, never counted toward staffing).
+    flights = [(d, s, oc) for (d, s, oc) in flights if oc != "gulf"]
+
+    out: list[StaffingRecommendation] = []
+    for pool in _POOLS:
+        window = _POOL_BANDS_MIN[pool]
+        in_window: list[tuple[date_t, time_t, str]] = [
+            (d, s, oc) for (d, s, oc) in flights
+            if _flight_in_window(s, d, d_day, window)
+        ]
+        hourly: Counter[str] = Counter()
+        has_p2f = False
+        for d, s, oc in in_window:
+            hourly[_hour_label(s, d, d_day)] += 1
+            if oc == "p2f":
+                has_p2f = True
+        peak_hour = ""
+        peak_count = 0
+        if hourly:
+            peak_hour, peak_count = hourly.most_common(1)[0]
+
+        lead_shift = _POOL_SHIFTS[pool][0]
+        staff_cfg = limits[lead_shift]["STAFF"]
+        target = int(staff_cfg["min"])
+        hard_cap = int(staff_cfg["max"])
+
+        peak_floor = math.ceil(peak_count / _FLIGHTS_PER_STAFF_PER_HOUR) if peak_count else 0
+        # 2026-05-22: volume_floor uses TARGET load, not hard cap.
+        # Hard cap (24/22) is the absolute ceiling, but the solver
+        # cannot pack everyone to it — H10 spacing, INTL pin windows,
+        # P2F buffers, and shift-window edges create slack the math
+        # ignores. Using target ensures the recommendation stays
+        # operationally feasible. Earlier test (2026-05-22) confirmed
+        # cap-based volume_floor caused INFEASIBLE solves when applied.
+        effective_flight_count = len(in_window)
+        # 2026-05-24: for NIGHT pool, discount A1's helping capacity
+        # during the 21:00-23:00 overlap. A1 is still operationally
+        # active until 22:55 and shares the load with N before N has
+        # to fully cover. We attribute a proportional share of the
+        # overlap-window flights to A1 (using its target as effective
+        # per-staff capacity over the 2-hour window), so N's required
+        # headcount reflects the real night burden.
+        if pool == "NIGHT":
+            ovl_lo, ovl_hi = _A1_NIGHT_OVERLAP_BAND
+            overlap_count = 0
+            for d, s, oc in in_window:
+                lbl = _hour_label(s, d, d_day)
+                hh = int(lbl.split(":")[0])
+                # ops-day hour can wrap (00 = midnight)
+                std_min_hh = hh * 60
+                if ovl_lo <= std_min_hh < ovl_hi:
+                    overlap_count += 1
+            a1_help = min(
+                overlap_count,
+                # A1 max contribution during the 2-hour overlap = headcount * target/8hr * 2hr
+                int(assigned_by_shift.get("A1", 0) * target / 8 * 2),
+            )
+            effective_flight_count = max(0, effective_flight_count - a1_help)
+            # Peak floor also relaxes if the peak hour falls inside the
+            # overlap band — split between A1 and N by staff ratio.
+            try:
+                peak_hh = int(peak_hour.split(":")[0]) if peak_hour else -1
+            except (ValueError, AttributeError):
+                peak_hh = -1
+            if ovl_lo <= peak_hh * 60 < ovl_hi:
+                n_count = assigned_by_shift.get("N", 0)
+                a1_count = assigned_by_shift.get("A1", 0)
+                total = n_count + a1_count
+                if total > 0:
+                    n_share = peak_count * n_count / total
+                    peak_floor = math.ceil(n_share / _FLIGHTS_PER_STAFF_PER_HOUR)
+        volume_floor = math.ceil(effective_flight_count / target) if effective_flight_count and target else 0
+        p2f_floor = 1 if has_p2f else 0
+
+        floors = {"peak": peak_floor, "volume": volume_floor, "p2f": p2f_floor}
+        required = max(floors.values())
+        bottleneck = max(floors, key=lambda k: floors[k])
+
+        pool_shifts = _POOL_SHIFTS[pool]
+        assigned_per_shift = {s: assigned_by_shift.get(s, 0) for s in pool_shifts}
+        assigned = sum(assigned_per_shift.values())
+        breakdown = ", ".join(f"{s}={assigned_per_shift[s]}" for s in pool_shifts)
+
+        gap = required - assigned
+        if gap > 0:
+            action = f"ADD {gap}"
+        elif gap < -2:
+            action = f"REMOVE {-gap}"
+        else:
+            action = "OK"
+        implied_avg = (len(in_window) / required) if required else 0.0
+
+        # 2026-05-22: per-shift breakdown of how to apply the recommendation.
+        # Distribute the target proportionally to the CURRENT shift ratio
+        # so existing M:M1 / A:A1 balance is preserved. For NIGHT (single
+        # shift) it's trivial.
+        target_per_shift: dict[str, int] = {}
+        if len(pool_shifts) == 1:
+            target_per_shift[pool_shifts[0]] = required
+        elif assigned == 0:
+            # Edge case: no one assigned yet — split evenly.
+            even = required // len(pool_shifts)
+            for s in pool_shifts:
+                target_per_shift[s] = even
+            target_per_shift[pool_shifts[0]] += required - even * len(pool_shifts)
+        else:
+            # Proportional to current headcount.
+            running = 0
+            for s in pool_shifts[:-1]:
+                t = round(required * assigned_per_shift[s] / assigned)
+                target_per_shift[s] = t
+                running += t
+            target_per_shift[pool_shifts[-1]] = max(0, required - running)
+        target_brk = ", ".join(f"{s}={target_per_shift[s]}" for s in pool_shifts)
+        # Build the actionable delta string.
+        deltas: list[str] = []
+        for s in pool_shifts:
+            d = target_per_shift[s] - assigned_per_shift[s]
+            if d > 0:
+                deltas.append(f"ADD {d} to {s}")
+            elif d < 0:
+                deltas.append(f"REMOVE {-d} from {s}")
+        breakdown_action = " · ".join(deltas) if deltas else "no change"
+
+        out.append(StaffingRecommendation(
+            pool=pool,
+            shifts_in_pool=" + ".join(pool_shifts),
+            assigned_today=assigned,
+            assigned_breakdown=breakdown,
+            target_breakdown=target_brk,
+            breakdown_action=breakdown_action,
+            flights_in_window=len(in_window),
+            peak_hour=peak_hour,
+            peak_hour_flights=peak_count,
+            has_p2f_flight=has_p2f,
+            target_per_staff=target,
+            hard_cap_per_staff=hard_cap,
+            peak_floor=peak_floor,
+            volume_floor=volume_floor,
+            p2f_floor=p2f_floor,
+            required=required,
+            bottleneck=bottleneck,
+            gap=gap,
+            action=action,
+            implied_avg_per_staff=round(implied_avg, 1),
+        ))
+    return out
+
+
+# ---------- state glue ----------
+
+
+def run_for_state(state: AppState, d_day: date_t) -> list[dict]:
+    """Compute the recommendation from current state, store it on
+    ``state.staffing`` and return the JSON-friendly rows."""
+    flights = [
+        (r.date, r.std, r.ops_class.value) for r in state.allocatable_cleaned()
+    ]
+    # Assigned by shift: STAFF + ZC only (AM excluded — they don't fly).
+    assigned: dict[str, int] = {s: 0 for s in _SHIFTS}
+    d_iso = d_day.isoformat()
+    for av in state.availability:
+        if av.date.isoformat() != d_iso or not av.assignable:
+            continue
+        if av.role is Role.AM:
+            continue
+        if av.current_shift in assigned:
+            assigned[av.current_shift] += 1
+
+    rows = compute_staffing(flights, assigned, d_day)
+    out = [asdict(r) for r in rows]
+    with state.lock:
+        state.staffing = out
+    return out