@topy-ai/maggie 0.7.47 → 0.7.48

package/bundled-skills/maggie-social-share/references/queue-and-connections.md

@@ -0,0 +1,101 @@
+# Social Share queue, campaigns, and connections
+
+All commands read one redacted JSON document, make no provider or model calls,
+and print a JSON report. Validation commands exit `1` when the contract fails.
+
+## Adapter scope contract — `adapters`
+
+```json
+{
+  "adapters": [{
+    "provider": "linkedin",
+    "canonical_scopes": ["openid", "profile", "email", "w_member_social"],
+    "client_id_ref": "linkedin-app-main",
+    "connect_paths": [
+      {"id": "dashboard", "scopes": ["openid", "profile", "email", "w_member_social"]},
+      {"id": "mobile", "scopes": ["openid", "profile", "email", "w_member_social"]}
+    ],
+    "redirect_uris": ["https://app.example.com/oauth/linkedin/callback"],
+    "client_shared_with": []
+  }]
+}
+```
+
+- Fails when any connect path requests a scope set different from
+  `canonical_scopes` (order is ignored). LinkedIn revokes a member's earlier
+  tokens when a sign-in requests a different scope set.
+- Fails when secret fields (`client_secret`, tokens) appear in the manifest.
+  `client_id_ref` is a label, not the credential.
+- Warns when the OAuth client is shared with other products, or redirect URIs
+  span several hosts without a `client_shared_with` record.
+
+## Connection health — `connections`
+
+```json
+{"connections": [{
+  "id": "conn-1", "provider": "linkedin", "status": "active",
+  "token_decryptable": true,
+  "provider_check": {"status": "valid", "checked_at": "2026-10-10T08:00:00Z"},
+  "avatar_url": "https://media.licdn.com/dms/image/...?...&e=1790000000",
+  "avatar_cached": false, "avatar_refresh_on_read": false,
+  "scheduled_items": 4
+}]}
+```
+
+- `status` is derived: `needs_reconnect` when the token cannot be decrypted on
+  the serving host or the provider reports it `revoked`/`invalid`/`expired`.
+  A stored `active` that should be `needs_reconnect` fails, and the report
+  counts scheduled items that would otherwise fail at publish time.
+- Run the decrypt check on every host that serves social routes; a missing
+  encryption key on a failover host looks exactly like an undecryptable token.
+- A signed, expiring avatar URL (LinkedIn `e=`, Meta `oe=`, S3/GCS signed
+  URLs) fails unless `avatar_cached` (bytes in owned storage) or
+  `avatar_refresh_on_read` is true. Use `--now` for deterministic checks.
+
+## Campaign idea stage — `campaigns`
+
+```text
+idea (planned, no copy) --write (1 credit)--> written (draft_id) --all written + start_day + posts_per_day--> Start
+```
+
+- Ideas are visible and manageable on every client (dashboard and mobile), not
+  only where they were planned. Written drafts keep their `campaign_id`.
+- A campaign can start only when every idea is `written` with a `draft_id`,
+  orders are unique integers, `start_day` is a date, and `posts_per_day >= 1`.
+  The report lists blockers; a `started` campaign with blockers fails.
+
+## Slot-based posting queue — `queue`
+
+Posts do not carry a fixed publish time. The person's posting hours are slots:
+
+```json
+{
+  "timezone": "Europe/London",
+  "posting_hours": {"mon": ["09:00", "17:00"], "wed": ["12:30"]},
+  "queue": [{"id": "post-7", "queued_at": "2026-10-09T10:00:00Z", "not_before": null}],
+  "campaigns": [{"id": "autumn", "status": "started", "start_day": "2026-10-12", "posts_per_day": 1,
+                 "ideas": [{"id": "i1", "order": 1, "status": "written", "draft_id": "post-31"}],
+                 "posted_idea_ids": []}]
+}
+```
+
+```bash
+maggie tool maggie_social_share.py queue queue.json --from 2026-10-12T00:00:00Z --slots 14
+```
+
+Rules the planner applies, in order:
+
+1. Each slot (local wall time in `timezone`) posts at most one item.
+2. The standalone queue is newest-first: a new post goes to the front.
+3. A stored time is `not_before` only. An overdue item is simply eligible; it
+   is never stranded behind a past `scheduled_at`.
+4. A started campaign publishes written ideas in idea order from `start_day`,
+   at most `posts_per_day` per local day.
+5. The standalone queue and each started campaign take turns (round-robin);
+   a source with nothing eligible is skipped for that slot.
+6. Wall times keep their local meaning across DST. A time that does not exist
+   (spring-forward gap) is skipped and reported; an ambiguous time uses its
+   first occurrence.
+
+The plan is advisory output for the host scheduler, which re-plans after every
+publish, approval, or queue edit instead of persisting stale per-post times.

package/bundled-skills/maggie-template/SKILL.md

@@ -28,9 +28,10 @@ maggie tool maggie_marketplace.py apply \
   --id medical-spa-landing-001 --project /path/to/astro-project
 ```
 
-`list` shows ID, lifecycle status, industries, and style tags. `suggest`
-matches the user's brief against those fields and ranks published entries
-first. `inspect` returns metadata and available artifacts. `apply` validates
+`list` shows ID, the neutral `displayName`, lifecycle status, industries, and
+style tags. Show customers the `displayName` and `displayDescription`, never the
+source title in `sourceMetadata`. `suggest` matches the user's brief against
+those fields and ranks published entries first. `inspect` returns metadata and available artifacts. `apply` validates
 the template, writes a namespaced reference to `.maggie/marketplace/<id>/`,
 copies the homepage, assets, screenshots, and `DESIGN.md`, and records
 `.maggie/template-selection.json`. It does not silently overwrite application
@@ -39,6 +40,59 @@ routes.
 Draft entries are for review only. Use `--allow-draft` only when the user
 explicitly wants to preview an unpublished template.
 
+## Preview studio
+
+Compare a template across viewports and palettes before applying it:
+
+```bash
+maggie tool maggie_marketplace.py measure-design <id> --palette-roles /tmp/<id>-palettes.json
+maggie tool maggie_design.py palette generate --roles /tmp/<id>-palettes.json \
+  --template <id> --output /tmp/<id>-palettes.json   # optional: contrast-safe variants
+maggie tool maggie_marketplace.py studio <id> --palettes /tmp/<id>-palettes.json
+maggie tool maggie_marketplace.py studio <id> --palettes /tmp/<id>-palettes.json --check-overflow [--palette <variant-id>]
+```
+
+`studio` writes `.maggie/template-studio/<id>/index.html` under the
+marketplace root: the homepage in scaled frames at 390, 768, 1024, and
+1440 px, a palette dropdown fed by a `maggie-palette-roles-v1` file (the
+measured signature when none is given), and labels on sample copy. Each label
+links to `content-fields.html`, which names the `maggie-template-content-v1`
+field and where the owner replaces it. Elements marked
+`data-maggie-sample="hero.headline"` are labelled exactly; otherwise headings,
+contact links, and section headings are matched heuristically. A palette is
+applied by swapping the signature role colours for the variant's and by
+setting `--maggie-<role>` CSS variables. Open `#<palette-id>` to link a variant.
+
+Serve the marketplace root over HTTP (`python3 -m http.server`) to view it.
+`--check-overflow` serves it locally, renders it with headless Chrome, writes
+`overflow-report.json`, and exits non-zero when any viewport has horizontal
+overflow, naming up to five offending elements. Templates that load Tailwind or
+fonts from a CDN need network access for a faithful render.
+
+## Data-driven component export
+
+A template reused across many businesses must render data, not hand-edited
+copy. The neutral content contract is
+[`contracts/maggie-marketplace/template-content-v1.schema.json`](../../bundled-contracts/maggie-marketplace/template-content-v1.schema.json)
+(`brand`, `contact`, `hero`, `categories` with `services`, `about`, `gallery`,
+`reviews`, `hours`, `faqs`, plus `samples` and an optional palette). An example
+is in [`references/template-content-v1.example.json`](references/template-content-v1.example.json).
+
+```bash
+maggie tool maggie_marketplace.py content-validate --input content.json
+maggie tool maggie_marketplace.py content-css --input content.json   # :root { --maggie-<role>: … }
+```
+
+`content-validate` enforces the business rules the schema cannot: service
+prices and durations, `HH:MM` opening hours, reviews that carry a `source` or
+are explicitly `sample: true` (never invent reviews), and `samples` paths that
+resolve. Export path: build one Astro component per template that takes the
+content object as props, maps each `[data-maggie-sample]` region to its
+content field, and reads colours from the `--maggie-<role>` variables emitted
+by `content-css`. Converting the existing marketplace templates into such
+components is not automated yet; do it per template and keep the static
+`homepage.html` as the visual reference.
+
 ## Selection workflow
 
 Use the deterministic marketplace CLI for listing, recommendation, inspection,

package/bundled-skills/maggie-template/references/template-content-v1.example.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "maggie-template-content-v1",
+  "brand": { "name": "Maggie Studio", "tagline": "Considered care in London", "logo": { "src": "assets/maggie-mark.png", "alt": "Maggie Studio" } },
+  "contact": { "phone": "020 0000 0000", "email": "hello@example.co.uk", "address": "1 Example Street, London", "bookingUrl": "/book" },
+  "hero": {
+    "headline": "Calm, personalised treatments",
+    "subheadline": "Book facials, massage and body treatments online.",
+    "image": { "src": "assets/maggie-hero.png", "alt": "Treatment room" },
+    "cta": { "label": "Book now", "href": "/book" }
+  },
+  "categories": [
+    {
+      "name": "Facials",
+      "services": [
+        { "name": "Signature facial", "price": 85, "currency": "GBP", "durationMinutes": 60, "bookingRef": null },
+        { "name": "Express facial", "price": 50, "currency": "GBP", "durationMinutes": 30, "bookingRef": null }
+      ]
+    }
+  ],
+  "about": { "heading": "About us", "body": "A small team offering unhurried appointments.", "image": null },
+  "gallery": [{ "src": "assets/maggie-care-team.png", "alt": "Care team" }],
+  "reviews": [{ "quote": "Thoughtful and relaxing.", "author": "A. Client", "rating": 5, "sample": true }],
+  "hours": [
+    { "day": "mon", "opens": "09:00", "closes": "18:00" },
+    { "day": "sun", "closed": true }
+  ],
+  "faqs": [{ "question": "Do you take walk-ins?", "answer": "Please book online so we can prepare your room." }],
+  "samples": ["brand.name", "contact.phone", "contact.email", "contact.address", "hero.headline", "reviews.0"],
+  "palette": {
+    "id": "signature",
+    "name": "Signature",
+    "roles": { "canvas": "#FDFBF7", "panel": "#FFFFFF", "soft": "#F2EFE9", "text": "#2A241E", "accent": "#2D5A27", "accentText": "#2D5A27", "onAccent": "#FFFFFF", "dark": "#2D5A27", "deep": "#000000" }
+  }
+}

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))