flight-alloc 0.0.1__py3-none-any.whl

flight_alloc-0.0.1.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: flight-alloc
+Version: 0.0.1
+Summary: IndiGo CLC flight-allocation system — engine + local web console
+Requires-Python: <3.15,>=3.11
+Requires-Dist: openpyxl~=3.1
+Requires-Dist: pydantic~=2.7
+Requires-Dist: ortools~=9.15
+Requires-Dist: pyyaml~=6.0
+Provides-Extra: dev
+Requires-Dist: pytest~=8.0; extra == "dev"

flight_alloc-0.0.1.dist-info/RECORD

@@ -0,0 +1,71 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/cli.py,sha256=fXb4PbZQB3pbk2BglF85J1BLEtMYZE0-nzEUwYYsWHY,1419
+src/config.py,sha256=fAXTRvMiVGKwsFY_YkhRMcLD86I3o5pumEAqXDn3gkM,6273
+src/greedy_fallback.py,sha256=UthzsxJX50qfTpGYtCFq1B20JHJf7SwkwP0gayXLRYM,4249
+src/plan.py,sha256=Io8kDmDibmPlMO3xtOfoFS9_plMY8e9QR0h2ZtDqNks,7324
+src/recommender_staffing.py,sha256=iW55PsrOFNdNhgCGPqGlTueR9cO0-jJdbDKeWtGC_g0,13494
+src/roster_store.py,sha256=x0AKKbDBXqsAzaxPBEPZMHTy_XQmhFKF72YoYwlZiGc,4961
+src/schemas.py,sha256=C21mdp8tqysFedaKYWi6KjScb10Se67pQ0W77YdBi48,46019
+src/staged_overrides.py,sha256=5kB58a9Rgt6JsltoVFSIgUEAstHQsekouk3FHzkvL3E,17409
+src/state.py,sha256=p84yRK0sYZG7EeqJjcZDP8GnWSHSrKr09ZvMbwfcviI,19078
+src/step1_clean_flights.py,sha256=YbANruEps8HCWXJxr4ZFIwGek8Pb1m4cSRFF8hn-d2U,11353
+src/step2_extract_roster.py,sha256=ZFjCUkUGiSl4DuWEzUlMZZTrx1jMCxXSnyzTjx1J3QI,13318
+src/step3_allocate_flights.py,sha256=h5BMrkDfb_xOP0Fq2RFHrsKz1HnSXlSq--SjFQhqrIA,74715
+src/zc_store.py,sha256=3Oo3sgl7gTIuUVOw3n_dK74-PqGORdwb1ce0P-J-v_k,7819
+src/allocator/__init__.py,sha256=YyS6mA75iNuxn3_5L5Kt6aF_jCYjBdKUqM-GKSOpI7c,229
+src/allocator/caps.py,sha256=yQtvYMvVCzQWpEUHn9-nSCTBDS9XAZVJFE9NAehep0M,21132
+src/allocator/eligibility.py,sha256=DpgQyNHnlUkA5QjYQnCd9ogw7a3cjI7ID7xlEPhikpY,12944
+src/allocator/greedy_fallback.py,sha256=3Y6Baxzl7tyr9cW3WHJvbIXx7RUONUwKgzyZNfQpnLM,4518
+src/allocator/invariants.py,sha256=TaTqrq5rhl4niEzt1iCWC6INQGlj91-c2xW5DZvnQI0,4665
+src/allocator/p2f_priority.py,sha256=odudR4okb69IywNbbuIsvOJtgH-I9O9pnkWYXUndjtA,5882
+src/allocator/pair_validation.py,sha256=x8ZiTUYsMOQqvOSv6boj7E3Rhul1fEj05K5PC_9SL-E,4315
+src/allocator/pairings.py,sha256=9ODg7p-cZw32S-gkufSsFDmNMMyN-jxplf8yWmKKvik,23478
+src/allocator/postpass_break.py,sha256=WtrHKM-deRU4q5kbOGF3DusVNO-9Y8UopGK-0F0ADPs,14901
+src/allocator/postpass_intl.py,sha256=N9IFZlmWYtG4hQoXBQhTgZCVbHRTn1kn59EQ-TWai4w,19221
+src/allocator/postpass_p2f.py,sha256=Lj9MaLSWkHqOM_IVaOK3VLxLS2kZqQhD5dS8SHw0Xpw,30139
+src/allocator/postpass_rebalance.py,sha256=iVGltvwmSbF6X-v4EOyk1BS7irPTdnOEXpc_k0ZOyFo,10147
+src/allocator/postsolve.py,sha256=YkCBV3RJwp0GQ6cUAWBSV08p8Oh17FkmF23l6uvpF5A,22740
+src/allocator/recommender.py,sha256=ReC8RQOw4-D1WRXJWtdRMZUJMyNJBhacO-MMpnBuTpo,13562
+src/allocator/windows.py,sha256=UwWGHalQdcZAWAIKYSIzlKFGWjfkUWAvSOgPnYJ41gQ,16331
+src/io/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/io/export.py,sha256=hJH08M5hPPqnl5_ZFKqQvWvH_mHkRBaEIQZzg39WT2A,10200
+src/io/export_xml.py,sha256=KCI7WGgo8kyyCO0sjVFYEiul6Lfy5tjA2zEz5SMB-Uo,2526
+src/io/readers.py,sha256=r8_UayUpnYtL6zK-eLYoBmCMmP3bKsXbgjbR2LRh_RE,38674
+src/io/roster_library.py,sha256=hqgZaRUm8EA9E3V-3KMPaUgTuoUOlMX0_KrPb3T6K5E,3458
+src/solver/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/solver/allocator_cpsat.py,sha256=MqOxrZnym7PK92ANW8iOtYocF1iQkEw-fVhGa9Tp4RM,63609
+src/web/__init__.py,sha256=-wJjMJfaf9IlPxVLjxXgLdMkiCS58qrWio8RvdvVdjc,2051
+src/web/__main__.py,sha256=cfMS5N9oZaxTfflkDqPte44KcU_8Lx6PqKcx12KVR-w,163
+src/web/runner.py,sha256=G3rl2CvbYM4Wf514IY4Pch50NBsSTmhg5FAH8WCcNlA,5504
+src/web/server.py,sha256=W5L9t-Teo9BplVSjhBRCNY3_r_3rWH6xfvSNvpFB_p8,6464
+src/web/api/__init__.py,sha256=vL3YK7szKP0sIjXJyFoXAaNKuqfvoJ9jfoqL4YJxmDI,1527
+src/web/api/export.py,sha256=m81TktlSPLPYQ4tSYaiTNrobGT-dOEeyXgFqLGWghMM,1179
+src/web/api/inputs.py,sha256=Hyntl4jYs2IuQuxvsXjalwQz7VAEvKYxg7eQYbWrVdg,4845
+src/web/api/override_rows.py,sha256=HBFboapcq6y4IY0M4mJScvZ7Kuqlp2FmD_n1YAY0pxU,5452
+src/web/api/pages.py,sha256=973ocA6AWnG9I6F50HGIOSQsiS9fQRiswIjptb9N3k4,841
+src/web/api/readbacks.py,sha256=zPGjAVb9WkjmcRFs53HKHXHj9ZeAyVZLMcMTwaPZCYI,2697
+src/web/api/recommender.py,sha256=aQkXpZxrcxW19vUlmY-lJohOcCXgZIvzKLsoaScJk7g,2769
+src/web/api/runs.py,sha256=cZjMmz10hwvC5-u0USAu9J8rHU7gLT3vCWGq3zBBFuw,3763
+src/web/api/settings.py,sha256=VS_pGykBK3VJ6bxk5ezN_WQVBYUwPs0bQEJsXq2QbnA,8021
+src/web/api/zc.py,sha256=SS4-f2CCKmiwykhBS1_h1b-MNGf-e7VexO2HPCQRPok,4212
+src/web/core/__init__.py,sha256=eBMYTOLKhrj0eZIUqj39fa-_ZBixlZ88LSgfFHFUbRE,185
+src/web/core/responses.py,sha256=1IoLRU0K96xcyvcpgUKS3coom2M9qPv1_rqTcJEkAqU,2520
+src/web/core/router.py,sha256=VJIYHX0CBCoVd5in-vOhk7TftURNDzD0SUTuCtzGhGg,5853
+src/web/core/static_files.py,sha256=HHSIa2_UAaB6J89Ywa1_r1sMyASdFBeqcuGWTkhmyto,2943
+src/web/overrides/__init__.py,sha256=ogdjA_cWm7VUptZkHI0w09cp4S1ZnG5UATp6TLmMDK0,1949
+src/web/overrides/airports.py,sha256=hyAXjuJcCMPZ0HAzVi4E_9eHf0omIfkhnkbSv_nW71s,10457
+src/web/overrides/break_time.py,sha256=Nn9g0xDwfN3GOqABcgS_9yMlnn9K1KtVpw7culOOrrk,3010
+src/web/overrides/config_yaml.py,sha256=feZyafDsyms2qwaETYzrkj-BFhJhEkYZdi9N4tse39M,703
+src/web/overrides/filters.py,sha256=jAkP68EHh9xeIQ121LlY2XBm5AIsa6mCSqE1bYWggn8,6964
+src/web/overrides/rows.py,sha256=EyjJG72LyRG1QtrYbCTi41Cp9SHpwkXsuThAio2m4UY,4124
+src/web/readback/__init__.py,sha256=DAwQgJh5VU0id7Me1-FVM3AKpyLdGG4_jIrO3o3PCNU,1748
+src/web/readback/common.py,sha256=INi-ZtfDd4-hRo6dauJY6mvSd52zLvzZXM5jXofcehk,1990
+src/web/readback/dashboard.py,sha256=0xfKqfFCQFqGJlv-usfg7bzkEGRRukrew9NomTOkEYc,3166
+src/web/readback/planning.py,sha256=6BOuISarumaP_g7YfVRRtxrwRJUd6k2Hb_Lj6cbvTbg,13157
+src/web/readback/session.py,sha256=Pyzkre3MXhemHYp9a2wEez2wXTo2_nZUODZjUh7USqs,5796
+src/web/readback/tables.py,sha256=475gq5pSgo2swQrAQbXxqyVMEJEd9k9f_13qYMnxdqI,6088
+flight_alloc-0.0.1.dist-info/METADATA,sha256=9IsooWjPnne6Ws__MNemXpkMgTTfieNhmbW2Q2Gtpbw,350
+flight_alloc-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+flight_alloc-0.0.1.dist-info/entry_points.txt,sha256=2As932cS3ifWNunOGp0MFegD0HIMW-XRjAYbRA-gPpc,46
+flight_alloc-0.0.1.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+flight_alloc-0.0.1.dist-info/RECORD,,

flight_alloc-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flight_alloc-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flight-alloc = src.cli:main

flight_alloc-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/allocator/__init__.py

@@ -0,0 +1,6 @@
+"""Step 4 allocator — pre-solve matrix construction, pair generation, and
+post-solve assembly.
+
+The CP-SAT model itself lives in ``src.solver.allocator_cpsat``;
+this package holds the deterministic plumbing on either side.
+"""

src/allocator/caps.py

@@ -0,0 +1,513 @@
+"""Per-(shift, role) workload bands — defaults from JSON, plus
+iteration-scoped overrides.
+
+Task 2 (2026-05-12) replaces the previous hardcoded ``(Role, "day"|"night")``
+tables with a per-shift-role JSON config at ``configs/shift_limits.json``.
+Each (shift, role) entry has three values:
+
+  min     — S1 preferred floor; counts below this incur shortfall penalty
+  target  — S1 acceptable max; counts above this start to penalize
+  max     — H16 hard cap; counts above this are infeasible
+
+Validation: ``min <= target <= max`` and all positive integers.
+
+The same JSON powers the override drawer's "Edit shift limits" form
+(see web/overrides.py). Per-iteration overrides are pushed into
+``_iteration_overrides`` by the drawer or by override rows; they
+shadow the JSON defaults without persisting to disk. ``reset_overrides()``
+clears them and is invoked on the engine's reset path.
+
+Per-staff overrides:
+  * a ``max_flights`` override row LOWERS a single staff's H16 cap.
+  * a ``preferred_target`` override row REPLACES a single staff's
+    preferred (default = (shift, role)'s ``min``).
+  Both reset when the overrides are cleared.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import threading
+from collections.abc import Iterable
+from pathlib import Path
+
+from ..schemas import Role, StaffMember
+
+_CONFIG_PATH = Path(__file__).resolve().parents[2] / "configs" / "shift_limits.json"
+# Per-iteration overrides persist here so they survive the process
+# boundary between the web server (where the drawer writes them) and
+# the CLI subprocess that actually runs the engine. Wiped by
+# ``reset_overrides()`` and by the engine's reset path.
+_STATE_PATH = Path(__file__).resolve().parents[2] / "data" / "state" / "iteration_overrides.json"
+
+# All known shift codes — kept in sync with config.status.shifts.
+_KNOWN_SHIFTS = ("M", "A", "N", "M1", "A1")
+_ROLE_KEYS = {Role.STAFF: "STAFF", Role.ZC: "ZC"}
+
+# Cached default table loaded from JSON. Refreshed on import and on any
+# explicit ``reload_defaults()`` call (e.g., after the drawer edits the
+# defaults rather than the iteration scratch).
+_defaults: dict[tuple[str, Role], dict[str, int]] = {}
+# Per-iteration shadow values: empty until the drawer writes here.
+_iteration_overrides: dict[tuple[str, Role], dict[str, int]] = {}
+# Per-staff iteration overrides — keyed by employee_id.
+_iteration_per_staff_preferred: dict[str, int] = {}
+_iteration_per_staff_cap: dict[str, int] = {}
+_lock = threading.RLock()
+
+
+def _coerce_int(v: object, key: str) -> int:
+    if not isinstance(v, (int, float)) or isinstance(v, bool):
+        raise ValueError(f"{key} must be a number, got {v!r}")
+    iv = int(v)
+    if iv <= 0:
+        raise ValueError(f"{key} must be a positive integer, got {iv}")
+    return iv
+
+
+def _validate_band(min_v: int, target_v: int, max_v: int, where: str) -> None:
+    """Reject any (min, target, max) triple that breaks the ordering
+    invariant. Single source of truth used by both the JSON loader and
+    the drawer write path so a bad form submission can't slip through."""
+    if not (min_v <= target_v <= max_v):
+        raise ValueError(
+            f"{where}: require min <= target <= max, got "
+            f"min={min_v} target={target_v} max={max_v}"
+        )
+
+
+def _load_defaults_from_disk() -> dict[tuple[str, Role], dict[str, int]]:
+    raw = json.loads(_CONFIG_PATH.read_text(encoding="utf-8"))
+    shifts_block = raw.get("shifts", {})
+    out: dict[tuple[str, Role], dict[str, int]] = {}
+    for shift, role_map in shifts_block.items():
+        if shift not in _KNOWN_SHIFTS:
+            continue
+        for role_name, vals in role_map.items():
+            role = Role.STAFF if role_name == "STAFF" else (
+                Role.ZC if role_name == "ZC" else None
+            )
+            if role is None:
+                continue
+            min_v = _coerce_int(vals.get("min"), f"{shift}/{role_name}.min")
+            target_v = _coerce_int(vals.get("target"), f"{shift}/{role_name}.target")
+            max_v = _coerce_int(vals.get("max"), f"{shift}/{role_name}.max")
+            _validate_band(min_v, target_v, max_v, f"{shift}/{role_name}")
+            out[(shift, role)] = {"min": min_v, "target": target_v, "max": max_v}
+    return out
+
+
+def reload_defaults() -> None:
+    """Re-read ``configs/shift_limits.json`` into the module cache.
+
+    Use this after editing the file out-of-band; the drawer's per-iteration
+    overrides write through ``set_iteration_band`` instead — those land
+    in ``data/state/iteration_overrides.json`` rather than the defaults
+    file."""
+    global _defaults
+    with _lock:
+        _defaults = _load_defaults_from_disk()
+
+
+def _dump_defaults(raw: dict) -> str:
+    """Serialise shift_limits.json in its hand-written layout — the
+    comment block one string per line, then one line per (shift, role)
+    band — so a Setup sidebar save leaves a readable diff."""
+    def dumps(v: object) -> str:
+        return json.dumps(v, ensure_ascii=False)
+
+    # Continuation lines line up under the first role: 4 indent + the
+    # 6-wide shift key + "{ ".
+    role_pad = " " * 12
+    parts: list[str] = []
+    for key, value in raw.items():
+        if key == "shifts":
+            shift_lines = []
+            for shift, roles in value.items():
+                role_lines = [
+                    f"{dumps(role) + ':':<9}{{ "
+                    + ", ".join(f"{dumps(k)}: {dumps(v)}" for k, v in band.items())
+                    + " }"
+                    for role, band in roles.items()
+                ]
+                body = (",\n" + role_pad).join(role_lines)
+                shift_lines.append(f"    {dumps(shift) + ':':<6}{{ {body} }}")
+            parts.append('  "shifts": {\n' + ",\n".join(shift_lines) + "\n  }")
+        elif isinstance(value, list):
+            items = ",\n".join(f"    {dumps(v)}" for v in value)
+            parts.append(f"  {dumps(key)}: [\n{items}\n  ]")
+        else:
+            parts.append(f"  {dumps(key)}: {dumps(value)}")
+    return "{\n" + ",\n".join(parts) + "\n}\n"
+
+
+def _state_path_or_none() -> Path | None:
+    """Return the runtime-state file path, or None if its parent
+    directory cannot be created. Callers treat None as "no persistence
+    available" and skip the disk hop."""
+    try:
+        _STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return None
+    return _STATE_PATH
+
+
+def _write_iteration_state_to_disk() -> None:
+    """Serialize the in-memory iteration overrides to JSON so the engine
+    subprocess sees the same shadow when the user clicks Allocate."""
+    p = _state_path_or_none()
+    if p is None:
+        return
+    payload = {
+        "shift_role": [
+            {"shift": shift, "role": (role.value if hasattr(role, "value") else role),
+             "min": v["min"], "target": v["target"], "max": v["max"]}
+            for (shift, role), v in _iteration_overrides.items()
+        ],
+        "per_staff_preferred": dict(_iteration_per_staff_preferred),
+        "per_staff_cap": dict(_iteration_per_staff_cap),
+    }
+    p.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def _load_iteration_state_from_disk() -> None:
+    """Populate the in-memory iteration overrides from the state file
+    on module import. Silently skips when the file is absent (= no
+    overrides for this iteration)."""
+    if not _STATE_PATH.exists():
+        return
+    try:
+        payload = json.loads(_STATE_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return
+    for entry in payload.get("shift_role", []):
+        shift = entry.get("shift")
+        role_name = entry.get("role")
+        role = Role.STAFF if role_name == "STAFF" else (
+            Role.ZC if role_name == "ZC" else None
+        )
+        if shift not in _KNOWN_SHIFTS or role is None:
+            continue
+        try:
+            min_v = _coerce_int(entry.get("min"), "min")
+            target_v = _coerce_int(entry.get("target"), "target")
+            max_v = _coerce_int(entry.get("max"), "max")
+            _validate_band(min_v, target_v, max_v, f"{shift}/{role_name}")
+        except ValueError:
+            continue
+        _iteration_overrides[(shift, role)] = {
+            "min": min_v, "target": target_v, "max": max_v,
+        }
+    for emp_id, v in payload.get("per_staff_preferred", {}).items():
+        with contextlib.suppress(ValueError, TypeError):
+            _iteration_per_staff_preferred[str(emp_id)] = int(v)
+    for emp_id, v in payload.get("per_staff_cap", {}).items():
+        with contextlib.suppress(ValueError, TypeError):
+            _iteration_per_staff_cap[str(emp_id)] = int(v)
+
+
+# Load once at import. Module remains usable even if the file's missing
+# at import time — we'll fall back to a minimal hardcoded table so unit
+# tests that don't ship the JSON don't crash the import.
+try:
+    _defaults = _load_defaults_from_disk()
+except (FileNotFoundError, json.JSONDecodeError, ValueError):
+    _defaults = {
+        ("M",  Role.STAFF): {"min": 22, "target": 23, "max": 24},
+        ("M",  Role.ZC):    {"min": 14, "target": 15, "max": 16},
+        ("A",  Role.STAFF): {"min": 22, "target": 23, "max": 24},
+        ("A",  Role.ZC):    {"min": 14, "target": 15, "max": 16},
+        ("M1", Role.STAFF): {"min": 22, "target": 23, "max": 24},
+        ("M1", Role.ZC):    {"min": 14, "target": 15, "max": 16},
+        ("A1", Role.STAFF): {"min": 22, "target": 23, "max": 24},
+        ("A1", Role.ZC):    {"min": 14, "target": 15, "max": 16},
+        ("N",  Role.STAFF): {"min": 20, "target": 21, "max": 22},
+        ("N",  Role.ZC):    {"min": 10, "target": 11, "max": 12},
+    }
+
+# Pick up any iteration overrides left over from a prior session
+# (e.g., user closed the browser without clicking Reset).
+_load_iteration_state_from_disk()
+
+
+# ---------- public API ----------
+
+def get_band(shift: str, role: Role) -> dict[str, int] | None:
+    """Return ``{"min", "target", "max"}`` for (shift, role), preferring
+    any active iteration override over the JSON default. ``None`` when
+    no band exists (unknown shift or role)."""
+    with _lock:
+        if (shift, role) in _iteration_overrides:
+            return dict(_iteration_overrides[(shift, role)])
+        if (shift, role) in _defaults:
+            return dict(_defaults[(shift, role)])
+    return None
+
+
+def default_caps() -> dict[str, dict[str, int]]:
+    """The saved hard cap (``max``) per shift and role, as
+    ``{shift: {"STAFF": n, "ZC": n}}`` in file order — what the Setup
+    sidebar's cap table shows. Iteration overrides are not applied."""
+    with _lock:
+        out: dict[str, dict[str, int]] = {}
+        for (shift, role), band in _defaults.items():
+            out.setdefault(shift, {})[_ROLE_KEYS[role]] = band["max"]
+        return out
+
+
+def set_default_caps(caps: dict[str, dict[str, object]]) -> list[str]:
+    """Save new hard caps (``max``) to ``configs/shift_limits.json`` and
+    reload them, so the next run uses them. The Setup sidebar's cap
+    table is the caller; an iteration override still shadows its band.
+
+    A cap below a band's min or target pulls those down to it, keeping
+    ``min <= target <= max``; returns one note per band that moved.
+    Raises ``ValueError``, before anything is written, on an unknown
+    shift or role, a cap that isn't a positive whole number, or a ZC
+    cap above that shift's STAFF cap.
+    """
+    global _defaults
+    with _lock:
+        raw = json.loads(_CONFIG_PATH.read_text(encoding="utf-8"))
+        shifts_block = raw.get("shifts", {})
+        notes: list[str] = []
+        for shift, role_caps in caps.items():
+            if not isinstance(role_caps, dict):
+                raise ValueError(f"{shift}: expected {{role: cap}}, got {role_caps!r}")
+            for role_name, cap in role_caps.items():
+                where = f"{shift}/{role_name}"
+                band = shifts_block.get(shift, {}).get(role_name)
+                if shift not in _KNOWN_SHIFTS or band is None:
+                    raise ValueError(f"unknown shift/role {where}")
+                if isinstance(cap, bool) or not isinstance(cap, int) or cap <= 0:
+                    raise ValueError(
+                        f"{where} cap must be a positive whole number, got {cap!r}"
+                    )
+                band["max"] = cap
+                lowered = [
+                    f"{label} {band[key]}"
+                    for key, label in (("min", "preferred"), ("target", "target"))
+                    if band[key] > cap
+                ]
+                if lowered:
+                    band["min"] = min(band["min"], cap)
+                    band["target"] = min(band["target"], cap)
+                    notes.append(f"{where}: {' and '.join(lowered)} lowered to {cap}")
+        for shift, roles in shifts_block.items():
+            staff, zc = roles.get("STAFF"), roles.get("ZC")
+            if staff and zc and zc["max"] > staff["max"]:
+                raise ValueError(
+                    f"{shift}: the ZC cap ({zc['max']}) can't be above the "
+                    f"STAFF cap ({staff['max']})"
+                )
+        _CONFIG_PATH.write_text(_dump_defaults(raw), encoding="utf-8")
+        _defaults = _load_defaults_from_disk()
+    return notes
+
+
+def set_iteration_band(
+    shift: str, role: Role, *, min_v: int, target_v: int, max_v: int,
+) -> dict[str, int]:
+    """Install a per-iteration override for the (shift, role) band. The
+    drawer "Edit shift limits" form is the only intended caller. Returns
+    the persisted dict for confirmation.
+
+    Validates via ``_coerce_int`` (positive integer) AND ``_validate_band``
+    (ordering); raises ``ValueError`` on either failure.
+    Also written to ``data/state/iteration_overrides.json`` so a band
+    tweak survives a server restart. Reset clears it.
+    """
+    role_name = role.value if hasattr(role, "value") else role
+    where = f"{shift}/{role_name}"
+    min_i = _coerce_int(min_v, f"{where}.min")
+    target_i = _coerce_int(target_v, f"{where}.target")
+    max_i = _coerce_int(max_v, f"{where}.max")
+    _validate_band(min_i, target_i, max_i, where)
+    with _lock:
+        _iteration_overrides[(shift, role)] = {
+            "min": min_i, "target": target_i, "max": max_i,
+        }
+        _write_iteration_state_to_disk()
+        return dict(_iteration_overrides[(shift, role)])
+
+
+def set_iteration_per_staff_preferred(employee_id: str, value: int) -> None:
+    """Per-staff iteration override for the preferred-target. Used by
+    the engine when an an override row of type=preferred_flights is
+    present. ``reset_overrides()`` clears this too."""
+    with _lock:
+        _iteration_per_staff_preferred[str(employee_id)] = int(value)
+        _write_iteration_state_to_disk()
+
+
+def set_iteration_per_staff_cap(employee_id: str, value: int) -> None:
+    """Per-staff iteration override that LOWERS the hard cap (matches
+    the legacy ``max_flights`` override semantics)."""
+    with _lock:
+        _iteration_per_staff_cap[str(employee_id)] = int(value)
+        _write_iteration_state_to_disk()
+
+
+def reset_overrides() -> None:
+    """Wipe every iteration-scoped override (both per-(shift, role) and
+    per-staff). Engine's reset path and the drawer "Reset" button both
+    call this so a clean run uses the JSON defaults. Also removes the
+    on-disk state file so a later run can't pick up stale overrides."""
+    with _lock:
+        _iteration_overrides.clear()
+        _iteration_per_staff_preferred.clear()
+        _iteration_per_staff_cap.clear()
+        with contextlib.suppress(FileNotFoundError):
+            _STATE_PATH.unlink()
+
+
+def snapshot_iteration_overrides() -> dict[str, dict[str, dict[str, int]]]:
+    """Diagnostic snapshot for the drawer's "show current iteration
+    overrides" hint and for the audit harness. Read-only copy.
+
+    Shape:
+      {
+        "shift_role": {"M/STAFF": {"min": ..., "target": ..., "max": ...}, ...},
+        "per_staff_preferred": {"<emp_id>": 20, ...},
+        "per_staff_cap":       {"<emp_id>": 18, ...}
+      }
+    """
+    with _lock:
+        return {
+            "shift_role": {
+                f"{shift}/{(role.value if hasattr(role, 'value') else role)}": dict(v)
+                for (shift, role), v in _iteration_overrides.items()
+            },
+            "per_staff_preferred": dict(_iteration_per_staff_preferred),
+            "per_staff_cap": dict(_iteration_per_staff_cap),
+        }
+
+
+# ---------- engine-facing helpers (used by solver, postsolve, post-passes) ----------
+
+def hard_cap_for(staff: StaffMember) -> int:
+    """Return the binding upper bound on flights for ``staff`` today.
+
+    Order of precedence:
+      1. Per-staff iteration override (LOWER only)
+      2. StaffMember.max_flights_cap from an override (LOWER only)
+      3. JSON default for (shift, role)
+
+    AMs and off-shift staff get 0 (they don't fly).
+    """
+    if staff.role == Role.AM or staff.shift_today is None:
+        return 0
+    band = get_band(staff.shift_today, staff.role)
+    if band is None:
+        return 0
+    base = band["max"]
+    # Per-staff iteration override (only lowers).
+    iter_cap = _iteration_per_staff_cap.get(staff.employee_id)
+    if iter_cap is not None:
+        base = min(base, iter_cap)
+    # Legacy max_flights override cap (only lowers).
+    if staff.max_flights_cap is not None:
+        base = min(base, staff.max_flights_cap)
+    return base
+
+
+def aggregate_capacity(staff: Iterable[StaffMember]) -> int:
+    """Sum of ``hard_cap_for()`` across all input staff. Compared against
+    flight count before invoking the solver — if capacity < demand the
+    day is structurally infeasible regardless of solver strategy."""
+    return sum(hard_cap_for(s) for s in staff)
+
+
+def preferred_target_for(staff: StaffMember) -> int:
+    """S1 preferred count for ``staff`` today.
+
+    Order of precedence:
+      1. Per-staff iteration override
+      2. JSON default for (shift, role)
+    """
+    if staff.role == Role.AM or staff.shift_today is None:
+        return 0
+    iter_pref = _iteration_per_staff_preferred.get(staff.employee_id)
+    if iter_pref is not None:
+        return int(iter_pref)
+    band = get_band(staff.shift_today, staff.role)
+    return band["min"] if band else 0
+
+
+def acceptable_max_for(staff: StaffMember) -> int:
+    """Upper end of the acceptable range."""
+    if staff.role == Role.AM or staff.shift_today is None:
+        return 0
+    band = get_band(staff.shift_today, staff.role)
+    return band["target"] if band else 0
+
+
+def preferred_target_for_shift_role(shift: str, role: Role) -> int:
+    """Aggregate preferred lookup keyed purely on (shift, role).
+
+    Used by the planner / readback layer for the "people needed" display
+    on the dashboard (Task 2a) — the per-staff override path doesn't
+    apply because we're calculating a shift-wide capacity estimate, not
+    a per-staff bound.
+    """
+    band = get_band(shift, role)
+    return band["min"] if band else 0
+
+
+# ---------- legacy compatibility re-exports ----------
+#
+# Other modules (solver, postsolve, tests) reach into these dicts directly.
+# We expose them as live views over the active values so callers don't
+# need to update — but new code should prefer the helper functions above.
+
+def _build_legacy_view(group: str) -> dict[tuple[Role, str], int]:
+    """``group`` is one of ``"min"`` / ``"target"`` / ``"max"``. Returns
+    a ``(Role, "day"|"night")`` dict where "day" merges M/A/M1/A1 (we
+    use M's values as the representative — they're the same in defaults)
+    and "night" maps from N."""
+    def day_for(role: Role, key: str) -> int:
+        band = get_band("M", role)
+        return band[key] if band else 0
+    def night_for(role: Role, key: str) -> int:
+        band = get_band("N", role)
+        return band[key] if band else 0
+    return {
+        (Role.STAFF, "day"):   day_for(Role.STAFF, group),
+        (Role.STAFF, "night"): night_for(Role.STAFF, group),
+        (Role.ZC,    "day"):   day_for(Role.ZC, group),
+        (Role.ZC,    "night"): night_for(Role.ZC, group),
+    }
+
+
+def __getattr__(name: str):  # pragma: no cover — module-level dynamic attr
+    """Module-level ``__getattr__`` so the legacy names
+    ``H16_HARD_CAPS`` / ``S1_PREFERRED_TARGETS`` / ``S1_ACCEPTABLE_MAX``
+    still resolve to live dicts. Existing code that did ``from .caps
+    import H16_HARD_CAPS`` keeps working without each call site having
+    to migrate to the new helper functions in one pass."""
+    if name == "H16_HARD_CAPS":
+        return _build_legacy_view("max")
+    if name == "S1_PREFERRED_TARGETS":
+        return _build_legacy_view("min")
+    if name == "S1_ACCEPTABLE_MAX":
+        return _build_legacy_view("target")
+    raise AttributeError(name)
+
+
+__all__ = [
+    "acceptable_max_for",
+    "aggregate_capacity",
+    "default_caps",
+    "get_band",
+    "hard_cap_for",
+    "preferred_target_for",
+    "preferred_target_for_shift_role",
+    "reload_defaults",
+    "reset_overrides",
+    "set_default_caps",
+    "set_iteration_band",
+    "set_iteration_per_staff_cap",
+    "set_iteration_per_staff_preferred",
+    "snapshot_iteration_overrides",
+]