@topy-ai/maggie 0.7.46 → 0.7.48

package/bundled-tools/clis/maggie_booking.py

@@ -7,6 +7,8 @@ import argparse
 import json
 import os
 import re
+import struct
+import zlib
 import secrets
 import shlex
 import shutil
@@ -17,6 +19,7 @@ from pathlib import Path
 
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
+STRIPE_SECRET_ENV_KEYS = ("STRIPE_SECRET_KEY", "ST_SECRECT_KEY")
 # Source checkouts keep contracts and the delivery board at repository root;
 # npm packages keep the same artifacts under bundled-contracts. Resolve both
 # layouts so the published CLI uses the exact same Booking gates as the repo.
@@ -26,7 +29,9 @@ DEFAULT_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-host-adapter-v1.json
 DEFAULT_ACCESS_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-access-v1.json"
 DEFAULT_EMAIL_TEMPLATES_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-email-templates-v1.json"
 DEFAULT_OPS_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-ops-evidence-v1.json"
+DEFAULT_BROWSER_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-browser-evidence-v2.json"
 DEFAULT_STRIPE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "stripe-booking-capabilities-v1.json"
+DEFAULT_VOUCHER_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-voucher-lifecycle-v1.json"
 EXECUTION_BOARD = (
     CONTRACTS_ROOT / "maggiedash" / "execution-board.json"
     if PACKAGED_CONTRACTS_ROOT.is_dir()
@@ -149,7 +154,7 @@ def stripe_contract_checks(contract: dict, max_age_days: int = 120) -> list[str]
     errors.extend(f"missing API matrix entry: {item}" for item in sorted(required_apis - api_ids))
     events = contract.get("x-webhook-events") or contract.get("webhookEvents") or []
     event_ids = {item.get("eventType") for item in events if isinstance(item, dict)}
-    required_events = {"checkout.session.completed", "checkout.session.async_payment_succeeded", "checkout.session.async_payment_failed", "payment_intent.processing", "payment_intent.payment_failed", "payment_intent.succeeded", "payment_intent.requires_action", "payment_intent.canceled", "refund.created", "refund.updated", "refund.failed"}
+    required_events = {"checkout.session.completed", "checkout.session.expired", "checkout.session.async_payment_succeeded", "checkout.session.async_payment_failed", "payment_intent.processing", "payment_intent.payment_failed", "payment_intent.succeeded", "payment_intent.requires_action", "payment_intent.canceled", "refund.created", "refund.updated", "refund.failed"}
     errors.extend(f"missing webhook event: {item}" for item in sorted(required_events - event_ids))
     native = contract.get("x-native-capabilities") or contract.get("nativeCapabilities") or {}
     if native.get("giftCards") != "not-native": errors.append("giftCards must remain not-native")
@@ -284,12 +289,16 @@ def email_templates_contract_checks(contract: dict) -> list[str]:
     if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
     if roles != ["owner", "admin", "manager"]: errors.append("roles must be owner, admin, manager")
     events = contract.get("events")
-    if not isinstance(events, list) or len(events) != 9: errors.append("exactly nine Booking email events are required")
+    if not isinstance(events, list) or len(events) != 10: errors.append("exactly ten Booking email events are required")
     event_ids = [item.get("id") for item in events if isinstance(item, dict)] if isinstance(events, list) else []
-    expected_events = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "package.purchase.confirmed", "package.purchase.refunded", "booking.waitlist.available"]
+    expected_events = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "payment.no_show_fee", "package.purchase.confirmed", "package.purchase.refunded", "booking.waitlist.available"]
     if event_ids != expected_events: errors.append("email event IDs are incomplete or out of order")
     if len(event_ids) != len(set(event_ids)): errors.append("email event IDs must be unique")
-    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName"}
+    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName", "arrivalNote"}
+    declared_variables = contract.get("variables")
+    event_variables = {variable for event in events if isinstance(event, dict) for variable in event.get("variables", []) if isinstance(variable, str)} if isinstance(events, list) else set()
+    if declared_variables is not None and (not isinstance(declared_variables, list) or set(declared_variables) != event_variables or len(declared_variables) != len(set(declared_variables))):
+        errors.append("email template global variables must exactly match the event allowlists")
     for event in events if isinstance(events, list) else []:
         variables = event.get("variables") if isinstance(event, dict) else None
         if not isinstance(variables, list) or not variables: errors.append(f"{event.get('id', 'unknown')}: variables must be a non-empty list")
@@ -384,6 +393,23 @@ def command_email_templates_contract(args: argparse.Namespace) -> int:
     return 0 if not errors else 1
 
 
+def command_voucher_contract(args: argparse.Namespace) -> int:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from maggie_booking_vouchers import voucher_contract_checks, voucher_ledger_checks
+    path = Path(args.contract).expanduser().resolve()
+    contract = load_json(path)
+    errors = voucher_contract_checks(contract)
+    result = {"status": "passed", "contract": str(path), "schemaVersion": contract.get("schemaVersion"), "runtimeOwner": (contract.get("runtime") or {}).get("owner"), "errors": errors}
+    if args.ledger:
+        ledger_path = Path(args.ledger).expanduser().resolve()
+        vouchers, ledger_errors = voucher_ledger_checks(load_json(ledger_path))
+        result.update({"ledger": str(ledger_path), "vouchers": vouchers})
+        errors.extend(ledger_errors)
+    result["status"] = "passed" if not errors else "failed"
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
 def project_path(args: argparse.Namespace) -> Path:
     return Path(args.project).expanduser().resolve()
 
@@ -625,10 +651,21 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
     has_sender = has("EMAIL_FROM") or has("RESEND_FROM_EMAIL")
     token_present = has("BOOKING_TOKEN_SECRET")
     token_valid = token_present and len(values.get("BOOKING_TOKEN_SECRET", "")) >= 32
-    stripe_secret = has("STRIPE_SECRET_KEY")
+    stripe_secret = any(has(key) for key in STRIPE_SECRET_ENV_KEYS)
+    stripe_legacy_alias = has("ST_SECRECT_KEY") and not has("STRIPE_SECRET_KEY")
     stripe_webhook = has("STRIPE_WEBHOOK_SECRET")
     stripe_complete = stripe_secret and stripe_webhook
     stripe_partial = stripe_secret != stripe_webhook
+    stripe_key_help = "STRIPE_SECRET_KEY (or existing ORA alias ST_SECRECT_KEY)"
+    stripe_detail = (
+        "Recognizes ORA's existing ST_SECRECT_KEY alias; prefer STRIPE_SECRET_KEY for new deployments. Verify the connection in Booking Overview."
+        if stripe_legacy_alias and stripe_complete
+        else f"Both {stripe_key_help} and STRIPE_WEBHOOK_SECRET are required for online payments."
+        if stripe_partial
+        else "Required only for deposit/full online payment flows; webhook URL is /api/maggie/booking/webhooks/stripe."
+        if stripe_secret or stripe_webhook
+        else "Optional at install: an owner or manager can connect Stripe from Booking Overview, or use the deployment secret store."
+    )
     workspace = (root / "_maggie" / "booking" / "booking.tsx").is_file()
     middleware = root / "src" / "middleware.ts"
     middleware_text = middleware.read_text(encoding="utf-8") if middleware.is_file() else ""
@@ -641,7 +678,7 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
         setup_check("site", "Public site URL", ["PUBLIC_SITE_URL"], has("PUBLIC_SITE_URL"), detail="Used for login links, booking links, and email URLs."),
         setup_check("booking-token", "Public booking token secret", ["BOOKING_TOKEN_SECRET"], token_valid, detail="Must be at least 32 characters; used to sign public manage-booking links." if token_valid or not token_present else "The configured secret is too short; use at least 32 characters.", status_override="passed" if token_valid else "invalid" if token_present else None),
         setup_check("resend", "Resend email delivery", ["RESEND_API_KEY", "EMAIL_FROM|RESEND_FROM_EMAIL"], has("RESEND_API_KEY") and has_sender, detail="Required for password setup/reset, booking notifications, and reminders."),
-        setup_check("stripe", "Stripe online payments", ["STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"], stripe_complete, required=False, detail="Required only for deposit/full online payment flows; webhook URL is /api/maggie/booking/webhooks/stripe." if not stripe_partial and (stripe_secret or stripe_webhook) else "Both Stripe secret and webhook secret are required for online payments." if stripe_partial else "Optional at install: an owner or manager can connect Stripe from Booking Overview, or use the deployment secret store.", status_override="passed" if stripe_complete else "degraded" if stripe_partial else "optional"),
+        setup_check("stripe", "Stripe online payments", ["STRIPE_SECRET_KEY|ST_SECRECT_KEY", "STRIPE_WEBHOOK_SECRET"], stripe_complete, required=False, detail=stripe_detail, status_override="passed" if stripe_complete else "degraded" if stripe_partial else "optional"),
         {"id": "schema", "label": "Booking database schema", "status": "not-verified", "required": True, "detail": "The CLI does not connect to PostgreSQL. Apply the schema after backup, then verify with the host runtime checks."},
         {"id": "owner", "label": "First owner account", "status": "not-verified", "required": True, "detail": "Open /_maggie/register once the schema is applied. Registration closes after the first owner."},
         {"id": "worker", "label": "Resend worker schedule", "status": "not-verified", "required": True, "detail": "Run the installed worker from a single-flight scheduler; setup does not create a cron or systemd job."},
@@ -656,7 +693,7 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
     if "booking-token" in missing_config:
         next_steps.append("Regenerate BOOKING_TOKEN_SECRET with at least 32 characters before enabling public customer manage links.")
     if "stripe" in degraded_config:
-        next_steps.append("Configure both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET before accepting online payments.")
+        next_steps.append(f"Configure both {stripe_key_help} and STRIPE_WEBHOOK_SECRET before accepting online payments.")
     if missing_dependencies:
         next_steps.append("For a new host, install missing packages and apply the schema together: maggie booking install --project . --confirm --ready")
     if not missing_dependencies and any(item["id"] == "schema" and item["status"] == "not-verified" for item in checks):
@@ -676,7 +713,7 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
         "status": status,
         "project": str(root),
         "checks": checks,
-        "configuredKeys": sorted(key for key in sources if key in {"DATABASE_URL", "PUBLIC_SITE_URL", "BOOKING_TOKEN_SECRET", "RESEND_API_KEY", "EMAIL_FROM", "RESEND_FROM_EMAIL", "STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"}),
+        "configuredKeys": sorted(key for key in sources if key in {"DATABASE_URL", "PUBLIC_SITE_URL", "BOOKING_TOKEN_SECRET", "RESEND_API_KEY", "EMAIL_FROM", "RESEND_FROM_EMAIL", "STRIPE_SECRET_KEY", "ST_SECRECT_KEY", "STRIPE_WEBHOOK_SECRET"}),
         "verificationPending": verification_pending,
         "paymentConfiguration": "online-payments-pending-verification" if stripe_complete else "incomplete-deployment-stripe" if stripe_partial else "dashboard-or-host-secret-pending",
         "next": next_steps,
@@ -946,7 +983,7 @@ def command_inspect(args: argparse.Namespace) -> int:
         "stripeContract": stripe_contract.is_file(),
         "schema": (root / "maggiedash" / "schema" / "maggie-booking-install.sql").is_file(),
         "runtimeContract": (root / "maggiedash" / "contracts" / "booking-runtime-v1.json").is_file(),
-        "browserEvidenceContract": (root / "maggiedash" / "contracts" / "booking-browser-evidence-v1.json").is_file(),
+        "browserEvidenceContract": (root / "maggiedash" / "contracts" / "booking-browser-evidence-v2.json").is_file(),
         "runtimePlanValidator": (root / "maggiedash" / "scripts" / "validate-booking-runtime-plan.mjs").is_file(),
         "customerFlowValidator": (root / "maggiedash" / "scripts" / "validate-booking-customer-flow.mjs").is_file(),
         "customerUIValidator": (root / "maggiedash" / "scripts" / "validate-booking-customer-ui.mjs").is_file(),
@@ -1014,36 +1051,147 @@ def runtime_result(evidence: dict, contract: dict) -> dict:
     return {"status": "passed" if not errors and bool(observations) else "failed", "checked": len(observations), "required": len(required), "missing": missing, "errors": errors}
 
 
-def browser_result(evidence: dict, artifact_root: Path) -> dict:
+def browser_result(evidence: dict, artifact_root: Path, contract: dict | None = None) -> dict:
     """Validate sanitized browser evidence without importing a browser runtime."""
     errors: list[str] = []
-    if evidence.get("schemaVersion") != "maggiedash-booking-browser-evidence.v1": errors.append("browser schemaVersion is unsupported")
+    contract = contract or load_json(DEFAULT_BROWSER_EVIDENCE_CONTRACT)
+    if contract.get("properties", {}).get("schemaVersion", {}).get("const") != "maggiedash-booking-browser-evidence.v2": errors.append("browser evidence contract is unsupported")
+    if evidence.get("schemaVersion") != "maggiedash-booking-browser-evidence.v2": errors.append("browser schemaVersion is unsupported")
     if not str(evidence.get("baseUrl", "")).startswith("https://"): errors.append("browser baseUrl must use HTTPS")
     generated_at = evidence.get("generatedAt")
     try:
         datetime.fromisoformat(str(generated_at).replace("Z", "+00:00"))
     except (TypeError, ValueError):
         errors.append("browser generatedAt must be an ISO timestamp")
-    viewport_map = {("mobile", 390, 844), ("tablet", 768, 1024), ("desktop", 1440, 1000)}
+    required_viewports = contract.get("x-required-viewports") if isinstance(contract.get("x-required-viewports"), list) else []
+    viewport_map = {(item.get("name"), item.get("width"), item.get("height")) for item in required_viewports if isinstance(item, dict)}
     actual_viewports = evidence.get("viewports") if isinstance(evidence.get("viewports"), list) else []
     observed_viewports = {(item.get("name"), item.get("width"), item.get("height")) for item in actual_viewports if isinstance(item, dict)}
     for viewport in sorted(viewport_map - observed_viewports):
         errors.append(f"missing viewport {viewport[0]} {viewport[1]}x{viewport[2]}")
-    routes = ["/_maggie/booking/", "/_maggie/booking/calendar", "/_maggie/booking/bookings", "/_maggie/booking/customers", "/_maggie/booking/waitlist", "/_maggie/booking/locations", "/_maggie/booking/catalog", "/_maggie/booking/staff", "/_maggie/booking/resources", "/_maggie/booking/schedule", "/_maggie/booking/payments", "/_maggie/booking/notifications", "/_maggie/booking/reports", "/_maggie/booking/settings", "/_maggie/booking/audit"]
+    routes = contract.get("x-required-routes") if isinstance(contract.get("x-required-routes"), list) else []
+    expected_headings = contract.get("x-required-headings") if isinstance(contract.get("x-required-headings"), dict) else {}
+    if not routes or len(set(routes)) != len(routes): errors.append("browser evidence contract must define unique required routes")
+    if len(expected_headings) != len(routes) or any(not isinstance(expected_headings.get(route), str) or not expected_headings[route].strip() for route in routes): errors.append("browser evidence contract must define one heading for every required route")
     screens = evidence.get("screens") if isinstance(evidence.get("screens"), list) else []
+    expected_count = len(routes) * len(viewport_map)
+    if len(screens) != expected_count: errors.append(f"browser screen count must be exactly {expected_count}")
+    expected_pairs = {(route, viewport[0]) for route in routes for viewport in viewport_map}
+    seen_pairs: set[tuple[str, str]] = set()
+    for item in screens:
+        if not isinstance(item, dict):
+            errors.append("browser screen must be an object")
+            continue
+        pair = (item.get("route"), item.get("viewport"))
+        if pair not in expected_pairs: errors.append(f"unexpected browser screen {pair[1]}:{pair[0]}")
+        if pair in seen_pairs: errors.append(f"duplicate browser screen {pair[1]}:{pair[0]}")
+        seen_pairs.add(pair)
     for route in routes:
-        for viewport in ("mobile", "tablet", "desktop"):
+        for viewport in sorted({item[0] for item in viewport_map}):
             item = next((row for row in screens if isinstance(row, dict) and row.get("route") == route and row.get("viewport") == viewport), None)
             if not item: errors.append(f"missing browser screen {viewport}:{route}"); continue
             if not isinstance(item.get("httpStatus"), int) or not 200 <= item["httpStatus"] < 400: errors.append(f"browser screen is not successful {viewport}:{route}")
+            final_path = item.get("finalPath")
+            normalized_final_path = final_path.rstrip("/") if isinstance(final_path, str) and final_path != "/" else final_path
+            normalized_route = route.rstrip("/") if route != "/" else route
+            if not isinstance(final_path, str) or not final_path.startswith("/") or final_path.startswith("//") or "?" in final_path or "#" in final_path or normalized_final_path != normalized_route: errors.append(f"browser screen final path does not match route {viewport}:{route}")
+            if not isinstance(item.get("heading"), str) or item["heading"].strip() != expected_headings.get(route): errors.append(f"browser screen heading does not match route {viewport}:{route}")
             if item.get("ready") is not True: errors.append(f"browser screen is not ready {viewport}:{route}")
             screenshot = item.get("screenshot")
             if not isinstance(screenshot, str) or Path(screenshot).is_absolute() or ".." in Path(screenshot).parts: errors.append(f"unsafe browser screenshot path {viewport}:{route}")
-            elif not (artifact_root / screenshot).is_file(): errors.append(f"missing browser screenshot {screenshot}")
+            else:
+                path = artifact_root / screenshot
+                if not path.is_file():
+                    errors.append(f"missing browser screenshot {screenshot}")
+                else:
+                    expected = next((width, height) for name, width, height in viewport_map if name == viewport)
+                    try:
+                        image_format, width, height = browser_image_dimensions(path)
+                        suffix = path.suffix.lower()
+                        extensions = {"png": {".png"}, "jpeg": {".jpg", ".jpeg"}}
+                        if suffix not in extensions.get(image_format, set()):
+                            errors.append(f"browser screenshot format does not match extension {viewport}:{route}")
+                        if width != expected[0] or height < expected[1]:
+                            errors.append(f"browser screenshot dimensions do not match viewport {viewport}:{route}")
+                    except (OSError, ValueError, struct.error):
+                        errors.append(f"browser screenshot is not a supported image {viewport}:{route}")
     if evidence.get("consoleErrors") != []: errors.append("browser consoleErrors is not empty")
     if evidence.get("failedRequests") != []: errors.append("browser failedRequests is not empty")
     if evidence.get("layoutErrors") != []: errors.append("browser layoutErrors is not empty")
-    return {"status": "passed" if not errors else "failed", "screens": len(screens), "required": len(routes) * 3, "errors": errors}
+    return {"status": "passed" if not errors else "failed", "screens": len(screens), "required": expected_count, "errors": errors}
+
+
+def browser_image_dimensions(path: Path) -> tuple[str, int, int]:
+    """Read PNG/JPEG dimensions while bounding the evidence artifact size."""
+    if path.stat().st_size > 25 * 1024 * 1024:
+        raise ValueError("screenshot exceeds 25 MiB")
+    data = path.read_bytes()
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        offset = 8
+        width = height = 0
+        found_header = found_data = found_end = False
+        while offset + 12 <= len(data):
+            chunk_length = struct.unpack(">I", data[offset:offset + 4])[0]
+            chunk_end = offset + 12 + chunk_length
+            if chunk_end > len(data):
+                break
+            kind = data[offset + 4:offset + 8]
+            payload = data[offset + 8:offset + 8 + chunk_length]
+            expected_crc = struct.unpack(">I", data[offset + 8 + chunk_length:chunk_end])[0]
+            if zlib.crc32(kind + payload) & 0xFFFFFFFF != expected_crc:
+                raise ValueError("invalid PNG chunk checksum")
+            if not found_header:
+                if kind != b"IHDR" or chunk_length != 13:
+                    raise ValueError("invalid PNG header")
+                width, height = struct.unpack(">II", payload[:8])
+                found_header = True
+            elif kind == b"IHDR":
+                raise ValueError("duplicate PNG header")
+            if kind == b"IDAT" and chunk_length:
+                found_data = True
+            if kind == b"IEND":
+                if chunk_length != 0 or chunk_end != len(data):
+                    raise ValueError("invalid PNG end chunk")
+                found_end = True
+                break
+            offset = chunk_end
+        if not found_header or not found_data or not found_end or not width or not height:
+            raise ValueError("incomplete PNG image")
+        return "png", width, height
+    if not data.startswith(b"\xff\xd8"):
+        raise ValueError("unsupported image format")
+    offset = 2
+    frame_markers = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
+    dimensions = None
+    while offset < len(data):
+        while offset < len(data) and data[offset] != 0xFF:
+            offset += 1
+        while offset < len(data) and data[offset] == 0xFF:
+            offset += 1
+        if offset >= len(data):
+            break
+        marker = data[offset]
+        offset += 1
+        if marker in {0xD8, 0xD9} or 0xD0 <= marker <= 0xD7:
+            continue
+        if offset + 2 > len(data):
+            break
+        segment_length = int.from_bytes(data[offset:offset + 2], "big")
+        if segment_length < 2 or offset + segment_length > len(data):
+            break
+        if marker in frame_markers:
+            if segment_length < 7:
+                break
+            height, width = struct.unpack(">HH", data[offset + 3:offset + 7])
+            if not width or not height:
+                break
+            dimensions = (width, height)
+        if marker == 0xDA:
+            if dimensions and data.endswith(b"\xff\xd9"):
+                return "jpeg", *dimensions
+            break
+        offset += segment_length
+    raise ValueError("JPEG dimensions were not found")
 
 
 def command_runtime_validate(args: argparse.Namespace) -> int:
@@ -1055,14 +1203,29 @@ def command_runtime_validate(args: argparse.Namespace) -> int:
 
 
 def ops_evidence_result(evidence: dict, contract: dict, require_host: bool = False) -> dict:
+    if not isinstance(evidence, dict):
+        return {"status": "failed", "checks": [], "requiredAlertCodes": 0, "errors": ["ops evidence must be a JSON object"]}
+    if not isinstance(contract, dict):
+        return {"status": "failed", "checks": [], "requiredAlertCodes": 0, "errors": ["ops evidence contract must be a JSON object"]}
     errors: list[str] = []
+    def parse_iso_utc_timestamp(value: object) -> datetime | None:
+        if not isinstance(value, str) or not re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z", value):
+            return None
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+
+    def is_iso_utc_timestamp(value: object) -> bool:
+        return parse_iso_utc_timestamp(value) is not None
+
     if evidence.get("schemaVersion") != contract.get("schemaVersion"): errors.append("ops evidence schemaVersion is unsupported")
-    if not evidence.get("generatedAt") or not isinstance(evidence.get("environment"), str) or not isinstance(evidence.get("tenant"), str): errors.append("generatedAt, environment, and tenant are required")
-    try:
-        datetime.fromisoformat(str(evidence.get("generatedAt")).replace("Z", "+00:00"))
-    except (TypeError, ValueError):
+    environment = evidence.get("environment")
+    tenant = evidence.get("tenant")
+    if not evidence.get("generatedAt") or not isinstance(environment, str) or not environment.strip() or not isinstance(tenant, str) or not tenant.strip(): errors.append("generatedAt, environment, and tenant are required")
+    if not is_iso_utc_timestamp(evidence.get("generatedAt")):
         errors.append("ops generatedAt must be an ISO timestamp")
-    if require_host and evidence.get("environment") in {"fixture", "test", "local"}: errors.append("host evidence cannot use a fixture/local environment")
+    if require_host and isinstance(environment, str) and environment.strip().lower() in {"fixture", "test", "local"}: errors.append("host evidence cannot use a fixture/local environment")
     checks = evidence.get("checks") if isinstance(evidence.get("checks"), dict) else {}
     def check_object(name: str) -> dict:
         value = checks.get(name)
@@ -1080,10 +1243,14 @@ def ops_evidence_result(evidence: dict, contract: dict, require_host: bool = Fal
     routed = check_object("alert_routing").get("alertCodes")
     if not isinstance(routed, list) or not set(contract.get("requiredAlertCodes", [])).issubset(set(routed)): errors.append("alert routing does not cover every stable alert code")
     for field in ("backupVerifiedAt", "restoreVerifiedAt"):
-        try:
-            datetime.fromisoformat(str(check_object("backup_restore").get(field)).replace("Z", "+00:00"))
-        except (TypeError, ValueError):
+        if not is_iso_utc_timestamp(check_object("backup_restore").get(field)):
             errors.append(f"backup_restore.{field} must be an ISO timestamp")
+    generated_at = parse_iso_utc_timestamp(evidence.get("generatedAt"))
+    backup_verified_at = parse_iso_utc_timestamp(check_object("backup_restore").get("backupVerifiedAt"))
+    restore_verified_at = parse_iso_utc_timestamp(check_object("backup_restore").get("restoreVerifiedAt"))
+    if generated_at is not None and backup_verified_at is not None and restore_verified_at is not None:
+        if restore_verified_at < backup_verified_at: errors.append("backup_restore.restoreVerifiedAt must not precede backupVerifiedAt")
+        if generated_at < restore_verified_at: errors.append("generatedAt must not precede restoreVerifiedAt")
     if check_object("backup_restore").get("rowCountVerified") is not True: errors.append("backup_restore.rowCountVerified must be true")
     if check_object("alert_routing").get("criticalDeliveryVerified") is not True: errors.append("alert_routing.criticalDeliveryVerified must be true")
     for field in ("rollbackWriteGuardVerified", "workerRestartVerified", "outboxReplayVerified"):
@@ -1116,9 +1283,11 @@ def command_release_gate(args: argparse.Namespace) -> int:
     access_result = access_contract_checks(load_json(access_path)) if access_path.is_file() else ["installed Booking access contract is missing"]
     email_templates_path = root / "maggiedash" / "contracts" / "booking-email-templates-v1.json"
     email_templates_result = email_templates_contract_checks(load_json(email_templates_path)) if email_templates_path.is_file() else ["installed Booking email templates contract is missing"]
+    browser_contract_path = root / "maggiedash" / "contracts" / "booking-browser-evidence-v2.json"
+    browser_contract = load_json(browser_contract_path) if browser_contract_path.is_file() else load_json(DEFAULT_BROWSER_EVIDENCE_CONTRACT)
     stripe_path = root / "maggiedash" / "contracts" / "stripe-booking-capabilities-v1.json"
     stripe_errors = stripe_contract_checks(load_json(stripe_path)) if stripe_path.is_file() else ["installed Stripe capability contract is missing"]
-    checks = {"contract": not contract_result, "emailTemplatesContract": not email_templates_result, "stripeContract": not stripe_errors, "serviceAdapterTypes": (root / "maggiedash" / "backend" / "booking-adapter-contract.d.ts").is_file(), "serviceContractValidator": (root / "maggiedash" / "scripts" / "validate-booking-service-contract.mjs").is_file(), "postgresManagerMethodsValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-manager-methods.mjs").is_file(), "postgresPaymentAdapter": (root / "maggiedash" / "backend" / "booking" / "postgres-payment-adapter.mjs").is_file(), "postgresPaymentValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-payment-adapter.mjs").is_file(), "postgresCustomerAdapter": (root / "maggiedash" / "backend" / "booking" / "postgres-customer-adapter.mjs").is_file(), "postgresCustomerValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-customer-adapter.mjs").is_file(), "postgresBackupRestoreValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-backup-restore.integration.mjs").is_file(), "postgresCoreRepository": (root / "maggiedash" / "backend" / "booking" / "postgres-core-repository.mjs").is_file(), "workspace": (root / "_maggie" / "booking" / "booking.tsx").is_file(), "schema": (root / "maggiedash" / "schema" / "maggie-booking-install.sql").is_file()}
+    checks = {"contract": not contract_result, "emailTemplatesContract": not email_templates_result, "browserEvidenceContract": browser_contract_path.is_file(), "stripeContract": not stripe_errors, "serviceAdapterTypes": (root / "maggiedash" / "backend" / "booking-adapter-contract.d.ts").is_file(), "serviceContractValidator": (root / "maggiedash" / "scripts" / "validate-booking-service-contract.mjs").is_file(), "postgresManagerMethodsValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-manager-methods.mjs").is_file(), "postgresPaymentAdapter": (root / "maggiedash" / "backend" / "booking" / "postgres-payment-adapter.mjs").is_file(), "postgresPaymentValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-payment-adapter.mjs").is_file(), "postgresCustomerAdapter": (root / "maggiedash" / "backend" / "booking" / "postgres-customer-adapter.mjs").is_file(), "postgresCustomerValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-customer-adapter.mjs").is_file(), "postgresBackupRestoreValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-backup-restore.integration.mjs").is_file(), "postgresCoreRepository": (root / "maggiedash" / "backend" / "booking" / "postgres-core-repository.mjs").is_file(), "workspace": (root / "_maggie" / "booking" / "booking.tsx").is_file(), "schema": (root / "maggiedash" / "schema" / "maggie-booking-install.sql").is_file()}
     errors = list(contract_result)
     errors.extend(f"access:{item}" for item in access_result)
     errors.extend(f"emailTemplates:{item}" for item in email_templates_result)
@@ -1143,7 +1312,7 @@ def command_release_gate(args: argparse.Namespace) -> int:
             browser_status = "failed"
             errors.append(browser_error)
         else:
-            browser_status = browser_result(browser_evidence, browser_path.parent).get("status", "failed")
+            browser_status = browser_result(browser_evidence, browser_path.parent, browser_contract).get("status", "failed")
             if browser_status != "passed": errors.append("browser evidence failed")
     elif args.require_browser:
         errors.append("browser evidence is required")
@@ -1219,6 +1388,10 @@ def parser() -> argparse.ArgumentParser:
     email_templates_contract = sub.add_parser("email-templates-contract", help="validate the tenant-scoped Booking email template contract")
     email_templates_contract.add_argument("--contract", default=str(DEFAULT_EMAIL_TEMPLATES_CONTRACT))
     email_templates_contract.set_defaults(func=command_email_templates_contract)
+    voucher_contract = sub.add_parser("voucher-contract", help="validate the gift voucher lifecycle contract and an optional sanitized host ledger fixture")
+    voucher_contract.add_argument("--contract", default=str(DEFAULT_VOUCHER_CONTRACT))
+    voucher_contract.add_argument("--ledger", help="sanitized maggiedash-booking-voucher-ledger.v1 fixture to replay")
+    voucher_contract.set_defaults(func=command_voucher_contract)
     inspect = sub.add_parser("inspect", help="inspect Booking install artifacts and contracts")
     inspect.add_argument("--project", default=".")
     inspect.add_argument("--contract", default=str(DEFAULT_CONTRACT))

package/bundled-tools/clis/maggie_booking_vouchers.py

@@ -0,0 +1,185 @@
+"""Validate the Booking gift voucher lifecycle contract and host ledger fixtures."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+
+CONTRACT_SCHEMA = "maggiedash-booking-voucher-lifecycle.v1"
+LEDGER_SCHEMA = "maggiedash-booking-voucher-ledger.v1"
+STATES = ["pending_payment", "active", "exhausted", "expired", "voided", "refunded"]
+ENTRY_TYPES = ["issue", "redeem", "undo_redeem", "void", "expire", "refund"]
+PERMISSIONS = ["vouchers.read", "vouchers.sell", "vouchers.redeem", "vouchers.void", "vouchers.refund"]
+NOTIFICATIONS = ["voucher.purchase.confirmed", "voucher.delivered", "voucher.redeemed", "voucher.refunded", "voucher.expiry_reminder"]
+ENDPOINTS = ["booking.vouchers.read", "booking.vouchers.sell", "booking.vouchers.redeem", "booking.vouchers.undo", "booking.vouchers.void", "booking.vouchers.refund"]
+# A ledger fixture is evidence, not a code store: the full code must never appear.
+FORBIDDEN_KEYS = {"code", "voucherCode", "rawCode", "secret", "hmacSecret"}
+
+
+def voucher_contract_checks(contract: dict) -> list[str]:
+    errors: list[str] = []
+    if contract.get("schemaVersion") != CONTRACT_SCHEMA: errors.append(f"schemaVersion must be {CONTRACT_SCHEMA}")
+    if contract.get("status") != "contract": errors.append("status must be contract")
+    runtime = contract.get("runtime") or {}
+    if runtime.get("owner") != "host" or runtime.get("maggieDashRuntime") is not False: errors.append("voucher runtime must be host-owned; MaggieDash ships no voucher runtime")
+    if contract.get("apiPrefix") != "/api/maggie/booking/vouchers.json": errors.append("apiPrefix must be /api/maggie/booking/vouchers.json")
+    auth = contract.get("auth") or {}
+    if auth.get("managerSession") != "host-session-cookie" or auth.get("emailPassword") is not True or auth.get("passkeys") is not False: errors.append("auth must use the host email/password session")
+    if contract.get("permissions") != PERMISSIONS: errors.append("voucher permissions are incomplete or out of order")
+    money = contract.get("money") or {}
+    if money.get("unit") != "minor" or money.get("integerOnly") is not True: errors.append("voucher money must be integer minor units")
+    channels = contract.get("channels") or {}
+    online, till = channels.get("online") or {}, channels.get("till") or {}
+    if online.get("provider") != "stripe" or online.get("nativeGiftCards") is not False: errors.append("online vouchers must be funded by Stripe payments with a local ledger, not a native gift card")
+    if not till.get("paymentMethods"): errors.append("till vouchers must declare recorded payment methods")
+    code_format = contract.get("codeFormat") or {}
+    if (code_format.get("online") or {}).get("check") != "hmac-sha256": errors.append("online codes must carry an HMAC check segment")
+    if not (code_format.get("till") or {}).get("check"): errors.append("till codes must carry a check digit")
+    if "codeHash" not in str(code_format.get("storage", "")): errors.append("code storage must keep only a hash and last four characters")
+    if contract.get("states") != STATES: errors.append("voucher states are incomplete or out of order")
+    ledger = contract.get("ledger") or {}
+    if ledger.get("appendOnly") is not True: errors.append("voucher ledger must be append-only")
+    if ledger.get("entryTypes") != ENTRY_TYPES: errors.append("voucher ledger entry types are incomplete or out of order")
+    rules = contract.get("rules") or {}
+    for rule in ("issue", "partialRedemption", "undo", "void", "expiry", "refund", "fullRefund"):
+        if not str(rules.get(rule, "")).strip(): errors.append(f"voucher rule is missing: {rule}")
+    notifications = [item.get("id") for item in contract.get("notifications", []) if isinstance(item, dict)]
+    if notifications != NOTIFICATIONS: errors.append("voucher notification events are incomplete or out of order")
+    if contract.get("endpointIds") != ENDPOINTS: errors.append("voucher endpoint IDs are incomplete or out of order")
+    routes = contract.get("canonicalRoutes") or {}
+    if set(routes) != set(ENDPOINTS): errors.append("voucher canonical routes are incomplete")
+    policy = contract.get("policy") or {}
+    for field in ("tenantScoped", "auditRequired", "idempotencyRequiredForMutations", "fullCodeOnlyInDeliveryEmail", "providerCredentialsRemainServerOnly"):
+        if policy.get(field) is not True: errors.append(f"voucher policy {field} must be true")
+    return errors
+
+
+def _time(value: object) -> datetime | None:
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else None
+
+
+def _forbidden_paths(value: object, path: str = "") -> list[str]:
+    found: list[str] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            child = f"{path}.{key}" if path else key
+            if key in FORBIDDEN_KEYS: found.append(child)
+            found.extend(_forbidden_paths(item, child))
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            found.extend(_forbidden_paths(item, f"{path}[{index}]"))
+    return found
+
+
+def replay_voucher(voucher: dict, now: datetime | None = None) -> tuple[dict, list[str]]:
+    """Replay one voucher ledger and return its derived state plus rule violations."""
+    vid = str(voucher.get("id") or "unknown")
+    errors: list[str] = []
+    face = voucher.get("faceValue")
+    channel = voucher.get("channel")
+    if channel not in ("online", "till"): errors.append(f"{vid}: channel must be online or till")
+    if not isinstance(face, int) or isinstance(face, bool) or face <= 0: errors.append(f"{vid}: faceValue must be a positive integer in minor units")
+    expires_at = _time(voucher.get("expiresAt")) if voucher.get("expiresAt") else None
+    if voucher.get("expiresAt") and expires_at is None: errors.append(f"{vid}: expiresAt must be an ISO timestamp with a timezone")
+    entries = voucher.get("entries")
+    if not isinstance(entries, list) or not entries:
+        return {"id": vid, "balance": 0, "status": None}, errors + [f"{vid}: ledger entries are required"]
+    balance = funded = refunded = 0
+    paid = channel == "till"
+    voided = expired = False
+    redeems: dict[str, int] = {}
+    undone: set[str] = set()
+    redeemed_any = False
+    previous: datetime | None = None
+    seen_ids: set[str] = set()
+    for index, entry in enumerate(entries):
+        label = f"{vid}: entry {entry.get('id') or index}"
+        kind, amount, at = entry.get("type"), entry.get("amount"), _time(entry.get("at"))
+        entry_id = str(entry.get("id") or "")
+        if not entry_id or entry_id in seen_ids: errors.append(f"{label}: entry id must be present and unique")
+        seen_ids.add(entry_id)
+        if kind not in ENTRY_TYPES: errors.append(f"{label}: unsupported entry type"); continue
+        if at is None: errors.append(f"{label}: at must be an ISO timestamp with a timezone"); continue
+        if previous and at < previous: errors.append(f"{label}: ledger entries must be in chronological order")
+        previous = at
+        if kind != "issue" and kind not in ("void", "expire") and (not isinstance(amount, int) or isinstance(amount, bool) or amount <= 0):
+            errors.append(f"{label}: amount must be a positive integer"); continue
+        if kind != "issue" and not str(entry.get("idempotencyKey", "")).strip(): errors.append(f"{label}: mutations require an idempotencyKey")
+        if index == 0 and kind != "issue": errors.append(f"{label}: the first entry must be issue"); continue
+        if kind == "issue":
+            if index != 0: errors.append(f"{label}: only one issue entry is allowed"); continue
+            if amount != face: errors.append(f"{label}: issue amount must equal faceValue")
+            balance = funded = face if isinstance(face, int) else 0
+            if channel == "online":
+                paid = bool(entry.get("paymentRef"))
+                if not paid: errors.append(f"{label}: online issue requires the verified provider paymentRef")
+            continue
+        if voided: errors.append(f"{label}: no {kind} is allowed after void"); continue
+        if kind == "void":
+            if not str(entry.get("reason", "")).strip(): errors.append(f"{label}: void requires a reason")
+            voided = True
+            continue
+        if kind == "expire":
+            if expires_at is None or at < expires_at: errors.append(f"{label}: expire before expiresAt")
+            expired = True
+            continue
+        if kind == "redeem":
+            if expires_at is not None and at >= expires_at: errors.append(f"{label}: redemption at or after expiry is blocked"); continue
+            if not paid: errors.append(f"{label}: redemption before payment is blocked"); continue
+            if amount > balance: errors.append(f"{label}: redemption exceeds the remaining balance"); continue
+            balance -= amount
+            redeems[entry_id] = amount
+            redeemed_any = True
+            continue
+        if kind == "undo_redeem":
+            target = str(entry.get("reverses") or "")
+            if target not in redeems: errors.append(f"{label}: undo must reverse an earlier redeem entry"); continue
+            if target in undone: errors.append(f"{label}: a redemption can be undone only once"); continue
+            if amount != redeems[target]: errors.append(f"{label}: undo amount must equal the reversed redemption"); continue
+            undone.add(target)
+            balance += amount
+            continue
+        if kind == "refund":
+            if amount > balance: errors.append(f"{label}: refund exceeds the remaining balance"); continue
+            if refunded + amount > funded: errors.append(f"{label}: refund exceeds the funded amount"); continue
+            if channel == "online" and not entry.get("paymentRef"): errors.append(f"{label}: online refunds must reference the original provider payment")
+            if channel == "till" and not entry.get("refundMethod"): errors.append(f"{label}: till refunds must record refundMethod")
+            balance -= amount
+            refunded += amount
+    if balance < 0: errors.append(f"{vid}: balance became negative")
+    # Status is evaluated at the later of the fixture clock and the ledger's own last entry.
+    now = now or datetime.now().astimezone()
+    if previous and previous > now: now = previous
+    if voided: status = "voided"
+    elif not paid: status = "pending_payment"
+    elif refunded and balance == 0 and not redeemed_any: status = "refunded"
+    elif balance == 0: status = "exhausted"
+    elif expired or (expires_at is not None and now >= expires_at): status = "expired"
+    else: status = "active"
+    declared = voucher.get("status")
+    if declared is not None and declared != status: errors.append(f"{vid}: declared status {declared} does not match the ledger ({status})")
+    declared_balance = voucher.get("balance")
+    if declared_balance is not None and declared_balance != balance: errors.append(f"{vid}: declared balance {declared_balance} does not match the ledger ({balance})")
+    return {"id": vid, "balance": balance, "status": status, "refunded": refunded}, errors
+
+
+def voucher_ledger_checks(fixture: dict) -> tuple[list[dict], list[str]]:
+    errors: list[str] = []
+    if fixture.get("schemaVersion") != LEDGER_SCHEMA: errors.append(f"ledger schemaVersion must be {LEDGER_SCHEMA}")
+    errors.extend(f"ledger must not contain full codes or secrets: {path}" for path in _forbidden_paths(fixture))
+    now = _time(fixture.get("now")) if fixture.get("now") else None
+    if fixture.get("now") and now is None: errors.append("ledger now must be an ISO timestamp with a timezone")
+    vouchers = fixture.get("vouchers")
+    if not isinstance(vouchers, list) or not vouchers:
+        return [], errors + ["ledger must contain at least one voucher"]
+    results = []
+    for voucher in vouchers:
+        if not isinstance(voucher, dict): errors.append("voucher entries must be objects"); continue
+        result, voucher_errors = replay_voucher(voucher, now)
+        results.append(result)
+        errors.extend(voucher_errors)
+    return results, errors