@topy-ai/maggie 0.7.52 → 0.7.53

package/bundled-tools/clis/maggie_booking_rules.py

@@ -0,0 +1,476 @@
+#!/usr/bin/env python3
+"""Booking rule contracts with shared test vectors (``maggie booking rules-vectors``).
+
+Hosts built on the MaggieDash booking model kept rediscovering the same rules
+by hand: client manage links that cancelled bookings already in progress, a
+paid client left without a booking when payment arrived after the hold
+expired, time off converted with the browser's time zone, add-ons counted
+twice at the till, reminders that only had one offset, a PIN switch that
+changed the API role but not the pages. Each rule here is a pure function
+with test vectors in ``contracts/maggiedash/booking-rules-v1.json``.
+
+``rules-vectors`` runs every vector against this reference implementation and,
+with ``--host-command``, against the host's own implementation: the command
+receives ``{"rule": NAME, "input": {...}}`` as one JSON line on stdin per
+vector and must print the result JSON. Results are compared field by field
+(only the fields the vector expects).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shlex
+import subprocess
+import sys
+from datetime import date, datetime, time, timedelta, timezone
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+CONTRACT = Path(__file__).resolve().parents[2] / "contracts" / "maggiedash" / "booking-rules-v1.json"
+SCHEMA = "maggiedash-booking-rules.v1"
+
+
+def _instant(value: str) -> datetime:
+    return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+
+
+def _iso(value: datetime) -> str:
+    return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# --- lifecycle --------------------------------------------------------------------
+
+OPEN = {"confirmed"}
+NOT_CONFIRMED = {"held", "pending_payment"}
+IN_PROGRESS = {"arrived", "checked_in", "in_service", "in_progress"}
+CLOSED = {"completed", "cancelled", "no_show", "expired"}
+
+
+def manage_action(i: dict) -> dict:
+    """May this actor cancel or reschedule this booking now? Clients only before start, only confirmed bookings."""
+    status, action, actor = i["status"], i["action"], i.get("actor", "client")
+    if action not in {"cancel", "reschedule"}:
+        raise ValueError("action must be cancel or reschedule")
+    if status in CLOSED:
+        return {"allowed": False, "reason": "closed"}
+    if actor == "client":
+        if status in NOT_CONFIRMED:
+            return {"allowed": False, "reason": "not_confirmed"}
+        if status in IN_PROGRESS:
+            return {"allowed": False, "reason": "in_progress"}
+        minutes = (_instant(i["startAt"]) - _instant(i["now"])).total_seconds() / 60
+        if minutes <= 0:
+            return {"allowed": False, "reason": "started"}
+        policy = i.get("policy") or {}
+        if policy.get("mode") == "window" and minutes < float(policy.get("windowHours", 0)) * 60:
+            return {"allowed": False, "reason": "inside_window"}
+        return {"allowed": True, "reason": "ok"}
+    if status in IN_PROGRESS and action == "reschedule":
+        return {"allowed": False, "reason": "in_progress"}
+    return {"allowed": True, "reason": "ok"}
+
+
+def late_payment(i: dict) -> dict:
+    """Checkout completed: confirm a pending booking; after the hold expired reinstate if free, else refund in full."""
+    status = i["bookingStatus"]
+    paid = int(i["paidMinor"])
+    if status in {"held", "pending_payment"}:
+        return {"outcome": "confirm", "newStatus": "confirmed", "refundMinor": 0, "notify": ["client.booking_confirmed", "business.booking_received"]}
+    if status == "confirmed":
+        return {"outcome": "duplicate_event", "newStatus": "confirmed", "refundMinor": 0, "notify": []}
+    if status in {"expired", "cancelled"} and i.get("cancelledBy", "system") == "system":
+        if i.get("slotFree"):
+            return {"outcome": "reinstate", "newStatus": "confirmed", "refundMinor": 0, "notify": ["client.booking_confirmed", "business.booking_received"]}
+        return {"outcome": "refund", "newStatus": status, "refundMinor": paid, "notify": ["client.payment_refunded_slot_taken", "business.late_payment_refunded"]}
+    return {"outcome": "refund", "newStatus": status, "refundMinor": paid, "notify": ["client.payment_refunded", "business.late_payment_refunded"]}
+
+
+# --- time and money ----------------------------------------------------------------------
+
+def schedule_to_utc(i: dict) -> dict:
+    """Interpret a schedule input (time off, closure, shift) in the venue's zone; the browser's zone never matters."""
+    zone = ZoneInfo(i["venueTz"])
+    local = datetime.fromisoformat(i["local"])
+    first = local.replace(tzinfo=zone, fold=0)
+    round_trip = first.astimezone(timezone.utc).astimezone(zone).replace(tzinfo=None)
+    if round_trip != local:
+        return {"error": "nonexistent_local_time"}
+    second = local.replace(tzinfo=zone, fold=1)
+    ambiguous = first.utcoffset() != second.utcoffset()
+    return {"utc": _iso(first), "ambiguous": ambiguous}
+
+
+def money_minor(i: dict) -> dict:
+    """Money is integer minor units; node-postgres returns bigint as a string, so parse before any arithmetic."""
+    value = i["value"]
+    if isinstance(value, bool):
+        return {"error": "not_minor_units"}
+    if isinstance(value, int):
+        return {"minor": value}
+    if isinstance(value, str) and re.fullmatch(r"-?\d{1,15}", value.strip()):
+        return {"minor": int(value.strip())}
+    return {"error": "not_minor_units"}
+
+
+def _round_half_up(numerator: int, denominator: int) -> int:
+    return (2 * numerator + denominator) // (2 * denominator)
+
+
+def sale_total(i: dict) -> dict:
+    """Till maths: items + add-ons not already in the item price, discount, service charge, then payments and tips."""
+    subtotal = 0
+    for item in i["items"]:
+        qty = int(item.get("qty", 1))
+        subtotal += int(item["priceMinor"]) * qty
+        for addon in item.get("addOns", []):
+            if not addon.get("includedInItemPrice"):
+                subtotal += int(addon["priceMinor"]) * qty
+    discount = min(int(i.get("discountMinor", 0)), subtotal)
+    after_discount = subtotal - discount
+    percent = i.get("serviceChargePercent", 0)
+    service_charge = _round_half_up(after_discount * int(round(float(percent) * 100)), 10000) if percent else 0
+    total = after_discount + service_charge
+    voucher = min(int(i.get("voucherMinor", 0)), total)
+    package = min(int(i.get("packageCoveredMinor", 0)), total - voucher)
+    tip = int(i.get("tipMinor", 0))
+    split = i.get("tipSplit") or []
+    tips: dict[str, int] = {}
+    if tip and split:
+        weights = [(entry["staffId"], float(entry.get("share", 1))) for entry in split]
+        total_weight = sum(weight for _, weight in weights)
+        raw = [(staff, tip * weight / total_weight) for staff, weight in weights]
+        tips = {staff: int(amount) for staff, amount in raw}
+        remainder = tip - sum(tips.values())
+        for staff, _ in sorted(raw, key=lambda pair: (-(pair[1] - int(pair[1])), pair[0]))[:remainder]:
+            tips[staff] += 1
+    elif tip:
+        tips = {"unassigned": tip}
+    return {"subtotalMinor": subtotal, "discountMinor": discount, "serviceChargeMinor": service_charge, "totalMinor": total,
+            "voucherMinor": voucher, "packageMinor": package, "tipMinor": tip, "amountDueMinor": total - voucher - package + tip, "tipsByStaff": tips}
+
+
+def payment_policy_setup(i: dict) -> dict:
+    """Deposit or full prepayment needs a connected payments account that can take charges."""
+    policy = i["policy"]
+    if policy == "venue":
+        return {"allowed": True, "reason": "ok"}
+    if policy not in {"deposit", "full"}:
+        raise ValueError("policy must be venue, deposit or full")
+    if not i.get("paymentsConnected"):
+        return {"allowed": False, "reason": "payments_not_connected"}
+    if not i.get("chargesEnabled"):
+        return {"allowed": False, "reason": "charges_not_enabled"}
+    return {"allowed": True, "reason": "ok"}
+
+
+# --- notifications and calendar -------------------------------------------------------------
+
+def reminders_due(i: dict) -> dict:
+    """Which reminder stages to send now: each offset once per booking, never for one created inside its window."""
+    if i.get("status", "confirmed") != "confirmed":
+        return {"due": [], "skipped": []}
+    start, now, created = _instant(i["startAt"]), _instant(i["now"]), _instant(i["createdAt"])
+    sent = set(i.get("sent", []))
+    due, skipped = [], []
+    for hours in sorted(i.get("offsetsHours", [24, 2]), reverse=True):
+        stage = f"{hours:g}h"
+        send_at = start - timedelta(hours=hours)
+        if stage in sent:
+            continue
+        if created > send_at:
+            skipped.append(stage)
+        elif send_at <= now < start:
+            due.append(stage)
+    # Only the latest due stage goes out; earlier ones a worker missed are skipped, not sent late.
+    if len(due) > 1:
+        skipped += due[:-1]
+        due = due[-1:]
+    return {"due": due, "skipped": skipped}
+
+
+def notification_plan(i: dict) -> dict:
+    """Templates per recipient for a cancel or reschedule; the wording names who acted."""
+    event, actor = i["event"], i["actor"]
+    if actor not in {"client", "business", "system"} or event not in {"cancelled", "rescheduled"}:
+        raise ValueError("event must be cancelled|rescheduled and actor client|business|system")
+    plan = {"client": f"booking.{event}.by_{actor}"}
+    if actor != "business":
+        plan["business"] = f"business.booking_{event}.by_{actor}"
+    return {"templates": plan}
+
+
+def ics_text(i: dict) -> dict:
+    """RFC 5545 TEXT escaping and 75-octet line folding."""
+    text = str(i["text"]).replace("\\", "\\\\").replace(";", "\\;").replace(",", "\\,").replace("\r\n", "\\n").replace("\n", "\\n")
+    line = f"{i.get('property', 'SUMMARY')}:{text}"
+    folded, current = [], b""
+    for char in line:
+        encoded = char.encode("utf-8")
+        limit = 75 if not folded else 74
+        if len(current) + len(encoded) > limit:
+            folded.append(current.decode("utf-8"))
+            current = b""
+        current += encoded
+    folded.append(current.decode("utf-8"))
+    return {"escaped": text, "lines": [folded[0]] + [" " + part for part in folded[1:]]}
+
+
+# --- availability ------------------------------------------------------------------------------
+
+def _ranges(day: date, zone: ZoneInfo, ranges: list[list[str]]) -> list[tuple[datetime, datetime]]:
+    out = []
+    for start, end in ranges:
+        a = datetime.combine(day, time.fromisoformat(start)).replace(tzinfo=zone)
+        b = datetime.combine(day, time.fromisoformat(end)).replace(tzinfo=zone)
+        out.append((a.astimezone(timezone.utc), b.astimezone(timezone.utc)))
+    return out
+
+
+def rota_week(i: dict) -> dict:
+    """Which pattern of an N-week rota applies on a date (weeks counted from the anchor's Monday)."""
+    anchor, day = date.fromisoformat(i["anchor"]), date.fromisoformat(i["date"])
+    monday = anchor - timedelta(days=anchor.weekday())
+    weeks = (day - monday).days // 7
+    return {"week": weeks % int(i.get("weeks", 2))}
+
+
+def _staff_ranges(staff: dict, day: date, zone: ZoneInfo, default: list[list[str]]) -> list[tuple[datetime, datetime]]:
+    rota = staff.get("rota")
+    if rota:
+        pattern = rota["patterns"][rota_week({"anchor": rota["anchor"], "date": day.isoformat(), "weeks": len(rota["patterns"])})["week"]]
+        ranges = pattern.get(str(day.weekday()), [])
+    else:
+        ranges = staff.get("hours", default)
+    return _ranges(day, zone, ranges)
+
+
+def plan_slots(i: dict) -> dict:
+    """Reference slot planner: split hours, rotas, per-staff durations, buffers, gap rule, any-staff choice, groups, DST."""
+    zone = ZoneInfo(i["timezone"])
+    day = date.fromisoformat(i["date"])
+    step = timedelta(minutes=int(i.get("slotMinutes", 15)))
+    service = i["service"]
+    before = timedelta(minutes=int(service.get("bufferBefore", 0)))
+    after = timedelta(minutes=int(service.get("bufferAfter", 0)))
+    min_gap = timedelta(minutes=int(i.get("minGapMinutes", 0)))
+    group = int(i.get("groupSize", 1))
+    if not 1 <= group <= 6:
+        raise ValueError("groupSize must be 1-6")
+    now = _instant(i["now"]) if i.get("now") else None
+    lead = timedelta(minutes=int(i.get("leadMinutes", 0)))
+    business = _ranges(day, zone, i["hours"])
+    closures = [(_instant(a), _instant(b)) for a, b in i.get("closures", [])]
+    staff = sorted(i["staff"], key=lambda s: (int(s.get("bookingsToday", 0)), int(s.get("sortOrder", 0)), s["id"]))
+    slots = []
+    for open_start, open_end in business:
+        cursor = open_start
+        while cursor < open_end:
+            free = []
+            for person in staff:
+                if service["id"] not in person.get("services", [service["id"]]):
+                    continue
+                minutes = int(person.get("durations", {}).get(service["id"], service["durationMinutes"]))
+                service_end = cursor + timedelta(minutes=minutes)
+                # As in MaggieDash planSlots: the service time sits inside opening hours and outside closures;
+                # buffers only keep other bookings away.
+                window_start, window_end = cursor - before, service_end + after
+                if service_end > open_end or (now and cursor < now + lead):
+                    continue
+                if any(a < service_end and cursor < b for a, b in closures):
+                    continue
+                if not any(a <= cursor and service_end <= b for a, b in _staff_ranges(person, day, zone, i["hours"])):
+                    continue
+                busy = [(_instant(a), _instant(b)) for a, b in person.get("busy", [])]
+                if any(a < window_end and window_start < b for a, b in busy):
+                    continue
+                if min_gap:
+                    gaps = [window_start - b for a, b in busy if b <= window_start] + [a - window_end for a, b in busy if a >= window_end]
+                    if any(timedelta(0) < gap < min_gap for gap in gaps):
+                        continue
+                free.append(person["id"])
+            if len(free) >= group:
+                local = cursor.astimezone(zone)
+                slots.append({"start": local.strftime("%H:%M"), "utc": _iso(cursor), "staff": free[:group]})
+            cursor += step
+    return {"slots": slots, "starts": [slot["start"] for slot in slots]}
+
+
+def price_for(i: dict) -> dict:
+    """Peak/off-peak price rules: the first matching rule (weekday + local time window) adjusts the base price."""
+    zone = ZoneInfo(i["timezone"])
+    local = _instant(i["startUtc"]).astimezone(zone)
+    price = int(i["basePriceMinor"])
+    for rule in i.get("rules", []):
+        if local.weekday() in rule.get("weekdays", range(7)) and time.fromisoformat(rule["from"]) <= local.time() < time.fromisoformat(rule["to"]):
+            if "percent" in rule:
+                return {"priceMinor": price + _round_half_up(price * int(rule["percent"] * 100), 10000), "rule": rule["name"]}
+            return {"priceMinor": int(rule["priceMinor"]), "rule": rule["name"]}
+    return {"priceMinor": price, "rule": None}
+
+
+# --- team, clients, money owed ----------------------------------------------------------------------
+
+ROLES = {"owner": 4, "manager": 3, "reception": 2, "therapist": 1}
+DEFAULT_PERMISSIONS = {
+    "owner": {"*"},
+    "manager": {"bookings.view_all", "bookings.edit", "clients.view", "clients.edit", "checkout.take_payment", "checkout.refund", "reports.view", "schedule.edit", "timeclock.self", "timeclock.manage"},
+    "reception": {"bookings.view_all", "bookings.edit", "clients.view", "clients.edit", "checkout.take_payment", "timeclock.self"},
+    "therapist": {"bookings.edit", "clients.view", "timeclock.self"},
+}
+OWNER_ONLY = {"team.manage", "billing.manage"}
+
+
+def permission_check(i: dict) -> dict:
+    """Named permissions per role, owner overrides, owner-only permissions, own-bookings scope, PIN switch that only lowers."""
+    session = i["role"]
+    pin = i.get("pinRole")
+    if pin and ROLES[pin] > ROLES[session]:
+        return {"allowed": False, "effectiveRole": session, "reason": "pin_cannot_raise_role"}
+    role = pin or session
+    permission = i["permission"]
+    if permission in OWNER_ONLY:
+        return {"allowed": role == "owner", "effectiveRole": role, "reason": "ok" if role == "owner" else "owner_only"}
+    granted = set(DEFAULT_PERMISSIONS[role])
+    override = (i.get("overrides") or {}).get(role, {})
+    granted |= set(override.get("grant", [])) - OWNER_ONLY
+    granted -= set(override.get("revoke", []))
+    allowed = "*" in granted or permission in granted
+    if allowed and permission.startswith("bookings.") and i.get("bookingStaffId") and "*" not in granted and "bookings.view_all" not in granted:
+        if i.get("bookingStaffId") != i.get("actorStaffId"):
+            return {"allowed": False, "effectiveRole": role, "reason": "own_bookings_only"}
+    return {"allowed": allowed, "effectiveRole": role, "reason": "ok" if allowed else "missing_permission"}
+
+
+def online_booking_gate(i: dict) -> dict:
+    """Client safety before online booking: blocked clients, patch tests per treatment category."""
+    client, service = i.get("client") or {}, i["service"]
+    if client.get("blocked"):
+        return {"allowed": False, "reason": "contact_business"}
+    category = service.get("patchTestCategory")
+    if not category:
+        return {"allowed": True, "reason": "ok"}
+    taken = (client.get("patchTests") or {}).get(category)
+    start = _instant(i["startAt"])
+    if not taken:
+        return {"allowed": False, "reason": "patch_test_required"}
+    taken_at = _instant(taken)
+    if start - taken_at > timedelta(days=int(service.get("patchTestValidDays", 180))):
+        return {"allowed": False, "reason": "patch_test_expired"}
+    if start - taken_at < timedelta(hours=int(service.get("patchTestMinHoursBefore", 48))):
+        return {"allowed": False, "reason": "patch_test_too_recent"}
+    return {"allowed": True, "reason": "ok"}
+
+
+def merge_clients(i: dict) -> dict:
+    """Merging duplicate clients keeps both point balances and histories and recomputes the tier."""
+    primary, duplicate = i["primary"], i["duplicate"]
+    points = int(primary.get("points", 0)) + int(duplicate.get("points", 0))
+    lifetime = int(primary.get("lifetimePoints", primary.get("points", 0))) + int(duplicate.get("lifetimePoints", duplicate.get("points", 0)))
+    tier = None
+    for entry in sorted(i.get("tiers", []), key=lambda t: t["minLifetimePoints"]):
+        if lifetime >= entry["minLifetimePoints"]:
+            tier = entry["name"]
+    return {"points": points, "lifetimePoints": lifetime, "tier": tier, "historyEntries": len(primary.get("history", [])) + len(duplicate.get("history", [])),
+            "memberships": sorted(set(primary.get("memberships", [])) | set(duplicate.get("memberships", [])))}
+
+
+def membership_credits(i: dict) -> dict:
+    """Monthly credits accrue only in billed months; a paused month neither bills nor adds credits."""
+    billed = [month for month in i["months"] if month["state"] == "active"]
+    return {"billedMonths": len(billed), "creditsAdded": len(billed) * int(i["creditsPerMonth"]), "amountBilledMinor": len(billed) * int(i["priceMinor"])}
+
+
+def commission(i: dict) -> dict:
+    """Commission on net sales after discounts (never on tips or service charge), per staff member and kind."""
+    totals: dict[str, int] = {}
+    for line in i["lines"]:
+        rate = (i["rates"].get(line["staffId"]) or {}).get(line["kind"], 0)
+        totals[line["staffId"]] = totals.get(line["staffId"], 0) + _round_half_up(int(line["netMinor"]) * int(round(rate * 10000)), 10000)  # rate is a fraction (0.4 = 40%)
+    return {"commissionMinor": totals}
+
+
+def hourly_pay(i: dict) -> dict:
+    """Clock-in/out shifts minus unpaid breaks, paid per minute at the hourly rate."""
+    minutes = 0
+    for shift in i["shifts"]:
+        worked = int((_instant(shift["out"]) - _instant(shift["in"])).total_seconds() // 60) - int(shift.get("breakMinutes", 0))
+        if worked < 0:
+            raise ValueError("break longer than the shift")
+        minutes += worked
+    return {"minutes": minutes, "payMinor": _round_half_up(minutes * int(i["rateMinor"]), 60)}
+
+
+def link_booking_to_account(i: dict) -> dict:
+    """A guest (token) booking joins a signed-in account only when the account e-mail is verified and equal."""
+    same = str(i["bookingEmail"]).strip().lower() == str(i["accountEmail"]).strip().lower()
+    return {"link": bool(same and i.get("accountEmailVerified")), "reason": "ok" if same and i.get("accountEmailVerified") else ("email_not_verified" if same else "different_email")}
+
+
+RULES = {
+    "manage_action": manage_action, "late_payment": late_payment, "schedule_to_utc": schedule_to_utc, "money_minor": money_minor,
+    "sale_total": sale_total, "payment_policy_setup": payment_policy_setup, "reminders_due": reminders_due, "notification_plan": notification_plan,
+    "ics_text": ics_text, "rota_week": rota_week, "plan_slots": plan_slots, "price_for": price_for, "permission_check": permission_check,
+    "online_booking_gate": online_booking_gate, "merge_clients": merge_clients, "membership_credits": membership_credits, "commission": commission,
+    "hourly_pay": hourly_pay, "link_booking_to_account": link_booking_to_account,
+}
+
+
+def _subset(expected: object, actual: object) -> bool:
+    if isinstance(expected, dict):
+        return isinstance(actual, dict) and all(key in actual and _subset(value, actual[key]) for key, value in expected.items())
+    return expected == actual
+
+
+def run_vectors(contract: dict, only: str | None = None, host_command: str | None = None) -> dict:
+    if contract.get("schemaVersion") != SCHEMA:
+        raise ValueError(f"contract schemaVersion must be {SCHEMA}")
+    results = []
+    for rule in contract.get("rules", []):
+        name = rule["id"]
+        if only and name != only:
+            continue
+        if name not in RULES:
+            results.append({"rule": name, "vector": "-", "passed": False, "error": "no reference implementation"})
+            continue
+        for vector in rule.get("vectors", []):
+            if host_command:
+                completed = subprocess.run(shlex.split(host_command), input=json.dumps({"rule": name, "input": vector["input"]}) + "\n", capture_output=True, text=True, timeout=60, check=False)
+                try:
+                    actual = json.loads(completed.stdout.strip().splitlines()[-1]) if completed.stdout.strip() else {"error": completed.stderr.strip()[-200:]}
+                except json.JSONDecodeError:
+                    actual = {"error": "host printed non-JSON output"}
+            else:
+                try:
+                    actual = RULES[name](vector["input"])
+                except (ValueError, KeyError) as error:
+                    actual = {"error": str(error)}
+            ok = _subset(vector["expect"], actual)
+            results.append({"rule": name, "vector": vector["name"], "passed": ok, **({} if ok else {"expected": vector["expect"], "actual": actual})})
+    failed = [r for r in results if not r["passed"]]
+    return {"schemaVersion": "maggiedash-booking-rules-run.v1", "implementation": "host" if host_command else "reference", "vectors": len(results), "failed": len(failed), "failures": failed, "passed": not failed and bool(results)}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie booking rules-vectors", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--contract", type=Path, default=CONTRACT)
+    parser.add_argument("--rule", help="run one rule's vectors")
+    parser.add_argument("--host-command", help="command that answers one {rule, input} JSON line with the result JSON (e.g. 'node scripts/booking-rules.mjs')")
+    parser.add_argument("--list", action="store_true", help="list rules and vector counts")
+    args = parser.parse_args(argv)
+    contract = json.loads(args.contract.read_text(encoding="utf-8"))
+    if args.list:
+        print(json.dumps([{"rule": r["id"], "feedback": r.get("why", ""), "vectors": len(r.get("vectors", []))} for r in contract.get("rules", [])], indent=2, ensure_ascii=False))
+        return 0
+    try:
+        report = run_vectors(contract, args.rule, args.host_command)
+    except (ValueError, OSError, subprocess.SubprocessError) as error:
+        print(f"BLOCKED: maggie booking rules-vectors: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_bridge_host.py

@@ -41,6 +41,32 @@ def _mode(value: object) -> int | None:
     return int(text, 8) if re.fullmatch(r"0?[0-7]{3}", text) else None
 
 
+MB = 1024 * 1024
+
+
+def parse_size(value: object) -> int:
+    """nginx size ("512k", "25m", "1g", "1048576") in bytes; 0 when unknown."""
+    match = re.fullmatch(r"\s*(\d+)\s*([kKmMgG]?)\s*", str(value or ""))
+    if not match:
+        return 0
+    return int(match.group(1)) * {"": 1, "k": 1024, "m": MB, "g": 1024 * MB}[match.group(2).lower()]
+
+
+def parse_seconds(value: object) -> int:
+    """nginx time ("300s", "5m", "300") in seconds; 0 when unknown."""
+    match = re.fullmatch(r"\s*(\d+)\s*(ms|s|m|h)?\s*", str(value or ""))
+    if not match:
+        return 0
+    return {"ms": 0, None: 1, "s": 1, "m": 60, "h": 3600}[match.group(2)] * int(match.group(1)) if match.group(2) != "ms" else int(match.group(1)) // 1000
+
+
+def proxy_needs(workloads: set[str]) -> tuple[int, int]:
+    """(min body bytes, min read timeout s): photos need several MB, image generation up to ~5 minutes."""
+    body = 25 * MB if workloads & {"images", "image-generation", "photos"} else 2 * MB
+    read = 360 if workloads & {"image-generation", "images"} else 120
+    return body, read
+
+
 def validate_plan(plan: dict, today: date | None = None) -> dict:
     today = today or datetime.now(timezone.utc).date()
     errors: list[str] = []
@@ -78,6 +104,17 @@ def validate_plan(plan: dict, today: date | None = None) -> dict:
         errors.append("network.publicBind must be loopback when a reverse proxy fronts the host")
     if net.get("adminBind") and net.get("adminBind") == net.get("publicBind"):
         errors.append("admin and public APIs must listen on different ports")
+    limits = net.get("proxyLimits") if isinstance(net.get("proxyLimits"), dict) else None
+    workloads = set(plan.get("workloads", []) or [])
+    need_body, need_read = proxy_needs(workloads)
+    if net.get("proxy") and limits is None:
+        (errors if workloads & {"images", "image-generation"} else warnings).append(
+            f"network.proxyLimits is missing: declare clientMaxBodySize (at least {need_body // MB} MB) and readTimeoutSeconds (at least {need_read}) for the bridge routes")
+    elif limits is not None:
+        if parse_size(limits.get("clientMaxBodySize")) < need_body:
+            errors.append(f"network.proxyLimits.clientMaxBodySize must be at least {need_body // MB}m for {', '.join(sorted(workloads)) or 'chat'}")
+        if not isinstance(limits.get("readTimeoutSeconds"), int) or limits["readTimeoutSeconds"] < need_read:
+            errors.append(f"network.proxyLimits.readTimeoutSeconds must be at least {need_read}: image generation can take 5 minutes")
     cap = plan.get("capacity", {}) if isinstance(plan.get("capacity"), dict) else {}
     if not isinstance(cap.get("maxSessions"), int) or cap["maxSessions"] < 1:
         errors.append("capacity.maxSessions must be a positive integer")
@@ -123,11 +160,34 @@ def validate_plan(plan: dict, today: date | None = None) -> dict:
     return {"schemaVersion": "maggie-bridge-host-plan-check.v1", "passed": not errors, "errors": errors, "warnings": warnings}
 
 
+# Effective nginx limits of the server block that proxies to the public port:
+# server/location values override the http level; nginx defaults are 1m / 60s.
+PROXY_AWK = r'''
+  function val(line) { sub(/^[^ \t]*[ \t]+/, "", line); sub(/;.*/, "", line); return line }
+  /^[ \t]*#/ { next }
+  { line = $0; sub(/^[ \t]+/, "", line) }
+  line ~ /^server[ \t]*\{/ && !ins { ins = 1; sd = depth; sb = ""; sr = ""; hit = 0 }
+  line ~ /^client_max_body_size/ { if (ins) sb = val(line); else hb = val(line) }
+  line ~ /^proxy_read_timeout/ { if (ins) sr = val(line); else hr = val(line) }
+  ins && line ~ /^proxy_pass/ && index(line, ":" port) { hit = 1 }
+  {
+    copy = line; opened = gsub(/\{/, "", copy); copy = line; closed = gsub(/\}/, "", copy); depth += opened - closed
+    if (ins && depth <= sd) { if (hit) { fb = (sb != "" ? sb : hb); fr = (sr != "" ? sr : hr); found = 1 } ins = 0 }
+  }
+  END {
+    if (found) printf "\"proxy\":{\"clientMaxBodySize\":\"%s\",\"readTimeout\":\"%s\"}}\n", (fb != "" ? fb : "1m"), (fr != "" ? fr : "60s")
+    else printf "\"proxy\":null}\n"
+  }
+'''
+
+
 def collect_script(plan: dict) -> str:
     """A POSIX sh collector; values are quoted once here and the script is sent over ssh stdin."""
     root = shlex.quote(str(plan.get("tenantsRoot", "/var/lib/bridge/tenants")))
     label = shlex.quote(str(plan.get("image", {}).get("label", "")))
     ports = " ".join(shlex.quote(str(plan.get("network", {}).get(key, "")).rsplit(":", 1)[-1]) for key in ("publicBind", "adminBind"))
+    public_port = shlex.quote(str(plan.get("network", {}).get("publicBind", "")).rsplit(":", 1)[-1])
+    awk = shlex.quote(PROXY_AWK)
     return f"""#!/bin/sh
 # maggie bridge-host collector: prints JSON facts only (modes, uids, listeners, image count).
 # Run: ssh <host> 'sh -s' < collect.sh > observed.json
@@ -150,7 +210,9 @@ printf '],"listeners":['
 listeners=$(for port in {ports}; do ss -ltnH "sport = :$port" 2>/dev/null | awk '{{print $4}}'; done)
 sep=''
 for local in $listeners; do printf '%s"%s"' "$sep" "$local"; sep=','; done
-printf '],"images":%s}}\\n' "$(docker images --filter label={label} --format '{{{{.ID}}}}' 2>/dev/null | sort -u | wc -l)"
+printf '],"images":%s,' "$(docker images --filter label={label} --format '{{{{.ID}}}}' 2>/dev/null | sort -u | wc -l)"
+conf=$( (sudo -n nginx -T 2>/dev/null || nginx -T 2>/dev/null) || true)
+printf '%s\\n' "$conf" | awk -v port={public_port} {awk}
 """
 
 
@@ -181,6 +243,20 @@ def check_observed(plan: dict, observed: dict) -> dict:
         host, _, port = str(listener).rpartition(":")
         if port == admin_port and host not in {"127.0.0.1", "[::1]", "::1"}:
             errors.append(f"admin port {port} listens on {host or '*'}, not loopback")
+    proxy = observed.get("proxy")
+    if plan.get("network", {}).get("proxy") == "nginx":
+        need_body, need_read = proxy_needs(set(plan.get("workloads", []) or []))
+        limits = plan.get("network", {}).get("proxyLimits") or {}
+        need_body = max(need_body, parse_size(limits.get("clientMaxBodySize")))
+        need_read = max(need_read, int(limits.get("readTimeoutSeconds") or 0))
+        if not isinstance(proxy, dict):
+            errors.append("no nginx server block proxies to the public port (or nginx -T was not readable); check the bridge routes by hand")
+        else:
+            body, read = parse_size(proxy.get("clientMaxBodySize")), parse_seconds(proxy.get("readTimeout"))
+            if body and body < need_body:
+                errors.append(f"nginx client_max_body_size is {proxy.get('clientMaxBodySize')} on the bridge routes; photos need at least {need_body // MB}m")
+            if read < need_read:
+                errors.append(f"nginx proxy_read_timeout is {proxy.get('readTimeout')} on the bridge routes; image jobs need at least {need_read}s")
     retain = plan.get("image", {}).get("retain", 2)
     if isinstance(observed.get("images"), int) and observed["images"] > retain:
         errors.append(f"{observed['images']} labelled images on the host; keep {retain} (current + previous)")