@topy-ai/maggie 0.7.38 → 0.7.40

package/bundled-references/maggiedash-booking/QA-TEST-PLAN.md

@@ -0,0 +1,235 @@
+# Booking QA and release test plan
+
+The booking system is a correctness-sensitive workflow. Visual polish matters,
+but a beautiful calendar that can double-book or misstate payment is a failed
+release.
+
+## 1. Test layers
+
+| Layer | What it proves | Required fixtures |
+|---|---|---|
+| Unit | Money, timezone, policies, transitions, capability mapping | deterministic dates and currencies |
+| Contract | DTO shape, required fields, errors, auth declarations | host adapter JSON fixtures |
+| Database | uniqueness, overlap, foreign keys, transaction behavior | PostgreSQL test database |
+| Integration | booking service plus payment adapter/outbox | fake provider with event replay |
+| Browser | manager journeys, forms, dialogs, responsive states | seeded tenant and fake gateway |
+| Security | tenant isolation, secret scans, webhook verification | hostile IDs and redacted payloads |
+| Runtime | real host routes and server session | sanitized conformance evidence |
+| Load | availability and concurrent hold behavior | fixed dataset and concurrency count |
+
+The repository now also has a deterministic runtime layer gate:
+
+```bash
+npm test
+npm run booking:worker -- --job all --now 2026-09-20T10:00:00Z
+```
+
+It covers state transitions, half-open interval conflicts, hold expiry,
+newest-first payment event reconciliation, webhook signature/tenant/amount/
+currency boundaries, notification leases/retries, dry-run isolation, and the
+worker cycle. It does not claim PostgreSQL concurrency or provider delivery
+until the host adapter is connected.
+
+The migration gate is:
+
+```bash
+npm run booking:schema:validate
+node scripts/validate-booking-schema.mjs \
+  --database-url "$DATABASE_URL" --confirm
+```
+
+The database check is intended for a disposable migration-test database. It
+applies the base schema once, applies the Booking migration twice, verifies the
+table/constraint/index inventory, and checks that an overlapping staff
+allocation is rejected inside a rolled-back transaction. It also verifies the
+normalized payment-event columns, availability snapshot table, and a
+PostgreSQL advisory-lock round trip.
+
+The worker repository boundary has a separate source gate:
+
+```bash
+npm run booking:postgres-repository:test
+```
+
+This uses an injected fake executor to prove parameterized, tenant-scoped SQL,
+transactional writes, payment-event acknowledgement, snapshot persistence, and
+the lock API. It does not replace host connection-pool, backup/restore,
+notification, or alerting evidence.
+
+Operational health is checked with:
+
+```bash
+npm run booking:health:test
+```
+
+The test covers correlation IDs, lock contention, stale worker/availability
+alerts, payment lag, retryable notifications, and dead-letter escalation. The
+host must still prove that critical codes reach its alerting/paging system.
+
+The fake-executor and schema checks are supplemented by the optional real
+repository cycle:
+
+```bash
+npm run booking:postgres-repository:integration -- \
+  --database-url "$DATABASE_URL" --confirm
+```
+
+It requires a host-installed `pg` dependency and an approved disposable/staging
+database; it cleans up its own uniquely-prefixed test tenant.
+
+## 2. Required scenario matrix
+
+### Availability
+
+- location opening hours;
+- staff working hours and service eligibility;
+- staff time off and blocked time;
+- resource conflict;
+- buffer before/after;
+- lead time and maximum advance window;
+- multiple locations with different timezones;
+- DST nonexistent and ambiguous wall-clock times;
+- multi-segment booking;
+- expired hold release;
+- manager override with permission.
+
+### Booking lifecycle
+
+- customer hold and successful payment;
+- customer hold and failed payment;
+- customer abandon and hold expiry;
+- manager no-payment booking;
+- check-in, in-progress, completed;
+- cancellation inside/outside policy window;
+- reschedule success;
+- reschedule conflict rollback;
+- no-show and no-show fee policy;
+- duplicate submit with same idempotency key;
+- same key with changed request body;
+- cross-tenant and cross-location access.
+
+### Payment
+
+- gateway configured and unavailable;
+- `action_required` authentication;
+- delayed provider event;
+- duplicate event;
+- out-of-order event;
+- unmatched event;
+- provider object belongs to another tenant/account;
+- full refund;
+- partial refund;
+- refund over captured amount;
+- refund retry after timeout;
+- saved method and off-session flows only when capability is true;
+- Terminal flow only when capability is true.
+
+## 3. Concurrency test
+
+The minimum regression test starts two requests for the same service, staff,
+resource, and interval at the same time. It expects one of:
+
+- one successful hold and one explicit conflict;
+- one successful booking and one explicit conflict;
+- one idempotent replay of the same request.
+
+It must never produce two active allocations, two confirmed bookings, or two
+provider payment attempts for one client action.
+
+## 4. Browser checklist
+
+For desktop and mobile:
+
+- login redirect and return path;
+- sidebar/workspace navigation;
+- overview empty/loading/error/provider-outage states;
+- calendar filters and timezone labels;
+- create booking dialog with one scroll owner;
+- booking detail timeline and separate payment status;
+- refund and cancellation confirmation;
+- catalog/staff/resource/schedule forms;
+- disabled unsupported capability action with reason;
+- keyboard focus and Escape behavior;
+- no native browser prompt;
+- no console errors or failed same-origin JSON requests;
+- no horizontal overflow at 320, 768, and desktop widths.
+
+## 5. Evidence artifacts
+
+Every release candidate should produce sanitized files under `.maggie/booking/`:
+
+```text
+host-conformance.json
+runtime-evidence.json
+config-evidence.json
+payment-contract.json
+webhook-evidence.json
+migration-preflight.json
+concurrency.json
+browser-report.json
+release-gate.json
+```
+
+The protected workflow
+`.github/workflows/booking-browser-evidence.yml` captures the 15 Booking
+routes at 390x844, 768x1024, and 1440x1000, with a host session supplied by an
+environment-scoped secret. `validate-booking-browser-evidence.mjs` fails on a
+missing route, non-2xx response, login redirect, missing screenshot, console
+error, failed network request, or horizontal overflow reported in
+`layoutErrors`. Browser evidence must come from a dedicated test tenant and
+must never include committed cookies or customer exports.
+
+The protected workflow
+`.github/workflows/booking-runtime-evidence.yml` captures all 47 host adapter
+endpoints from a host-owned test plan. The plan supplies a dedicated tenant,
+explicit disposable mutation bodies, and the same email/password session
+cookie used by the browser run. `capture-booking-runtime-evidence.mjs` writes
+only sanitized endpoint IDs, canonical routes, status codes, and required-field
+booleans. `validate-booking-runtime-evidence.mjs` fails on a missing endpoint,
+non-2xx response, contract mismatch, or sensitive evidence field. This is the
+real-host gate; `fixtures/booking-runtime-evidence.v1.json` is only a local
+validator fixture.
+
+The completed local UI gate also runs the compiled Booking React workspace in
+Chrome against the secret-free reference host. It caught and fixed two classes
+of regression before release: an unselected detail panel requesting a fake
+`none.json` booking, and grid/table intrinsic widths overflowing a 390px
+viewport. The regression check now waits for network idle, verifies
+`document.body.scrollWidth <= window.innerWidth`, and repeats the route sweep
+at all three target widths. This is local fixture evidence, not a substitute
+for the protected real-host run.
+
+Artifacts contain schema versions, hashes, counts, statuses, and safe errors.
+They do not contain credentials, cookies, payment payloads, raw provider
+responses, or unredacted customer details.
+
+## 6. Release gate
+
+`maggie booking release-gate` should fail when any required artifact is missing,
+stale, or failed. It should print:
+
+- project and tenant scope;
+- MaggieDash and ai-cmo-skills revisions;
+- schema/migration version;
+- selected payment provider and capabilities;
+- report IDs and generated-at timestamps;
+- failed phase and next action;
+- final `passed` boolean.
+
+No “best effort” pass is allowed for auth, tenancy, allocation, payment,
+webhook, migration, or secret-redaction checks.
+
+## 7. Regression policy
+
+Every production incident adds one of:
+
+- a unit test for a pure rule;
+- a database/concurrency test;
+- a provider fixture;
+- a host conformance fixture;
+- a browser journey;
+- a stable CLI validation;
+- a confirmed memory entry only when the rule is general.
+
+The feedback draft is evidence and discussion. It is not active memory until the
+maintainer confirms the diagnosis and generality.

package/bundled-references/maggiedash-booking/README.md

@@ -0,0 +1,271 @@
+# MaggieDash Booking workspace
+
+This folder is the product and engineering documentation for the Booking
+workspace at `/_maggie/booking`. The canonical current snapshot and gap list is
+[`CURRENT-STATE.md`](./CURRENT-STATE.md); this README explains the surface and
+links the deeper contracts.
+
+The target is a first-party booking management system for store managers. It
+must own the booking domain while keeping payment providers replaceable. Stripe
+is the first adapter, not the database, booking engine, or public API contract.
+
+## What is true today
+
+This repository currently provides:
+
+- the `maggie-service-booking` skill for provider-backed service catalogues,
+  variants, provider URLs, sync, factual validation, and service-page output;
+- a provider-neutral booking adapter reference with Fresha as the first
+  catalogue provider and Google Calendar as a limited fallback;
+- MaggieDash installation into `./_maggie/admin`;
+- MaggieDash distribution of a separate `./_maggie/booking` React workspace,
+  Booking UI v1 and the provider-neutral Booking host adapter v1;
+- a provider-neutral PostgreSQL Booking starter schema with idempotency, audit,
+  outbox, payment, hold, allocation, and database overlap constraints;
+- `maggie booking install` (including explicit `--install-dependencies`, `--bootstrap`, the combined `--ready` path, and reviewed `--schedule systemd|cron` generation), `worker-schedule`, `inspect`, the read-only first-run `setup` checklist,
+  `contract`, `runtime-validate`, `ops-validate`, task-board, and fail-closed
+  `release-gate` checks in ai-cmo-skills;
+- a non-destructive Astro host bootstrap that installs email/password auth,
+  first-owner registration, manager/public routes, PostgreSQL/Stripe wiring,
+  the schema command, Resend worker, and middleware rewrite starter;
+- Booking access management for email/password staff, manager, and finance
+  accounts is covered by the installable `booking-access-v1` contract, including
+  granular permissions, Resend invitations, password reset, revocation,
+  disabled-account protection, staff-profile linking, and server-enforced
+  granular permissions;
+- tenant-scoped Booking email template management for ten Resend events,
+  allowlisted variables, sandboxed preview, audited draft/publish/rollback, and
+  worker fallback resolution without exposing provider secrets or recipients;
+- server-side staff assignment scope for bookings, calendar, availability,
+  customer summaries, schedule, resources, and lifecycle mutations;
+- a source/install-side runtime plan regression gate for concrete route
+  parameters, query parameters, and mutation bodies;
+- a protected operational-evidence workflow that rejects fixture artifacts at
+  the host release boundary;
+- a separate public-noindex customer-flow contract and route handler for
+  catalogue, availability, holds, checkout start, payment-return recovery,
+  cancellation, token-bound customer rescheduling, customer-manage history,
+  waitlist joining, safe DTO
+  redaction, and notification intents;
+- a tenant-scoped waitlist queue with manager filtering, priority/status
+  actions, audit records, a linked booking conversion transaction, and a Resend
+  availability-notification intent;
+- a worker-side waitlist matcher that orders eligible entries by priority/FIFO,
+  persists the offered slot, and queues one idempotent Resend availability
+  notification without auto-reserving the appointment;
+- separate short-lived payment tokens and 30-day sealed customer-manage
+  tokens, with Resend worker links for customer self-service follow-up;
+- a public customer-manage history view that lists only redacted appointment
+  summaries for the tenant/customer bound to the 30-day token;
+- a manager customer directory with searchable tenant-scoped customer details,
+  consent summary, and appointment history;
+- editable schedule-rule management for working hours, staff shifts, time off,
+  and location closures without destructive snapshot writes;
+- editable service and treatment catalogue management with stable service and
+  variant IDs, payment policy controls, search, and active/inactive status;
+- editable location management with tenant-scoped timezone, locale, address,
+  active state, and online-booking controls;
+- editable staff and resource management with assignment, bookable, capacity,
+  and active-state controls;
+- editable Booking defaults for venue timezone/currency, accepting new
+  bookings, and automatic/manual payment capture policy;
+- editable tenant-scoped treatment package catalogue with included treatment
+  quantities, package pricing, currency, expiry, and active state;
+- manager-granted customer package entitlements with tenant/customer-scoped
+  balances, expiry checks, and atomic redemption when creating manager
+  bookings; public package checkout, provider reconciliation/webhook fulfillment,
+  manager purchase listing, and guarded package refund routes are included;
+- Overview bookability readiness that identifies missing active locations,
+  catalogue variants, assigned bookable staff, working hours, payment
+  capability, and the resulting overall `bookable` state;
+- manager booking creation driven by live catalogue, location, staff, and
+  resource selectors with required allocation;
+- install-time configuration forms that read tenant locations and live service
+  assignments instead of relying on fixture IDs;
+- an installable public customer booking page source and Astro route starter
+  for the same hold/checkout/pending-return journey;
+- public multi-treatment selection with combined-duration availability, summed
+  checkout pricing, safe segment DTOs, segment-safe customer rescheduling, and
+  tenant location selection with location-scoped availability;
+- a deterministic public customer reference-host journey validator covering
+  hold replay, checkout pending state, payment return, token-bound cancel, and
+  manager-session isolation;
+- provider-neutral runtime rules and worker runner for availability, hold
+  expiry, payment webhook/reconciliation, priority/FIFO waitlist matching, and
+  notification outbox delivery;
+- a dated Stripe API/resource/event audit and installable capability contract;
+  the host still supplies the concrete official SDK adapter;
+- a manager Reports screen and tenant-scoped `/reports.json` read model for
+  period totals plus day, service, staff, and location breakdowns;
+- an idempotent 24-hour reminder worker job that queues confirmed-booking
+  reminders into the existing Resend notification outbox;
+- service-level payment policies (`full`, `deposit`, `pay_later`, and
+  `no_payment`), purpose-labelled payment attempts, captured/refunded payment
+  projection, and manager controls for deposits and outstanding balances;
+- systemd/cron scheduling templates and a protected Playwright browser-evidence
+  capture/validation workflow;
+- provider-neutral MaggieDash host, auth, activity, navigation, content, media,
+  migration, and runtime-evidence contracts;
+- a PostgreSQL starter schema for MaggieDash content and audit records.
+- a tenant-scoped Notifications screen for delivery-state inspection and
+  reasoned dead-letter replay, with recipient redaction and audit evidence.
+- policy-safe cancellation settlement that allocates full/deposit refunds,
+  invokes the injected payment provider after the lifecycle write, returns
+  `manual_required` on provider failure, and queues accepted/pending refund
+  notices through the existing Resend outbox;
+
+The manager workspace, distribution contracts, starter schema, provider-neutral
+runtime rules, worker runner, scheduling templates, browser-evidence gate, and
+customer-flow boundary are implemented locally. A secret-free reference host
+and an Astro host scaffold are also available for contract/browser work. A host
+must still apply the schema, prove PostgreSQL transactions, verify a real
+payment account and webhook, enable notification delivery and tenant locking,
+and capture authenticated production browser/runtime/ops evidence before real
+bookings can be enabled.
+Resend is the server-side notification and account-email transport. Staff
+invitation, first-login setup, password reset, one-time token expiry, and
+session revocation are implemented in the Astro host scaffold; real delivery
+and browser evidence remain host deployment gates.
+Stripe setup is likewise server-side: configure the host secret store, then
+verify the account from Booking Overview. For a single-business host, an
+owner/manager can alternatively enter both Stripe values in the secure
+dashboard form; the host verifies them first and stores only encrypted
+ciphertext derived from `BOOKING_TOKEN_SECRET`. Secret presence alone is only
+`pending`; `connected` requires a successful API check, explicit Stripe
+charges/payouts enablement, and a webhook secret. Raw Stripe credentials are
+never returned by the API or stored as plaintext Booking data. Deployment
+secrets take precedence over dashboard-managed credentials.
+
+## Current verification snapshot — 2026-09-21
+
+| Item | Current evidence |
+|---|---|
+| MaggieDash source | Package `0.2.8`, `HEAD`/`origin/main` [`9d99de7`](https://github.com/TOPY-AI-LTD/MaggieDash/commit/9d99de7); the working tree contains newer uncommitted Booking changes |
+| Delivery board | 84 implementation tasks passed and 3 real-host evidence tasks pending (BK-030, BK-031, BK-032); Reports, reminders, payment-policy projection, cancellation policy snapshots/cutoff/refund settlement, consented Stripe no-show fee charging with explicit manager/finance approval, venue-local calendar day/week ranges, manager/customer history, editable schedule rules, catalogue, treatment package catalogue plus customer entitlement balances/redemption, public package checkout/payment return and public customer package redemption, transactional package-credit restoration on cancellation, Stripe package fulfillment/refunds, package confirmation/refund Resend notifications, locations, staff/resource management, live-config booking creation, manager and public multi-treatment appointments, segment-safe rescheduling, strict first-run setup checks, secure dashboard-managed Stripe connection, tenant-scoped Stripe Customer identity mapping, secret-safe Stripe readiness, installed-workspace validator coverage, explicit schema bootstrap, bootstrap secret provisioning, transactional schema dry-run, compatible Resend sender keys, token-bound rescheduling, customer-manage links/history, transactional waitlist conversion, priority/FIFO waitlist slot matching, synchronized install contracts, npm bundled-contract path resolution, tenant-scoped notification inspection/dead-letter replay, first-owner registration hardening, access defaults, complete server-enforced capability permissions, worker migration preflight, complete browser evidence route coverage, installable administrator-managed Booking access contracts, reference-host Team access CRUD/denial evidence, dependency-complete fresh Astro installation, tenant-scoped Resend email template management, and complete tenant booking defaults are covered by the manager/runtime and public-customer contracts |
+| Local code gates | MaggieDash `npm test`, contract/UI/security/customer/runtime validators, and Python task-board/link checks passed |
+| Installer projection | The default public GitHub source installed 139 source artifacts plus 23 Astro host files in a fresh disposable project; dependency completion added the missing SSR adapter, and the installed host bootstrap validator, `maggie booking inspect`, and `astro build` all passed. Existing host deployment configs are preserved |
+| Published npm parity | Local CLI source is `0.7.39`; npm still serves `@topy-ai/maggie@0.7.38`, which has the older Booking contract and needs a release/published-tarball verification |
+| Access boundary | Standard Booking schema owns `maggiedash_booking_user_roles`; host access API, explicit permissions, linked `staff_id`, and repository data-scope checks passed |
+| Reference host | 47 manager endpoint checks plus public customer-flow checks passed, including explicit no-show fee route coverage, location setup, package catalogue management, customer package grant/balance/redemption, public package redemption from hold to zero-price booking, package checkout/payment-return, Stripe connection verification, notification replay, and multi-treatment hold/checkout/reschedule |
+| Local browser smoke | The browser contract now covers all 15 manager routes (`45` route/viewport screens) across 390/768/1440. A fresh authenticated host capture is still required; the earlier 33/33 result covered only the former 11-route surface and is not reused as production evidence |
+| Production proof | Not yet complete; reference-host and fixture artifacts are explicitly not production evidence |
+
+## Current product limits
+
+The local Booking release supports both manager-led and public customer package
+redemption. After a confirmed package purchase, the customer can continue to
+the public booking page; the server binds the entitlement to the customer's
+email, locks the balance during checkout, and creates a zero-price confirmed
+booking when all selected treatments are covered. A successful cancellation
+restores each active redemption once and records the reversal; completed and
+no-show visits remain consumed by policy. Memberships, gift cards, and
+recurring appointments are not yet part of the v1 contract. No-show fees are
+supported only through the separate consented, explicitly confirmed
+off-session charge route; there is no automatic charge on status transition.
+
+## Evidence inspected
+
+| Evidence | What it establishes |
+|---|---|
+| `/home/balalior/Dev/MaggieDash/maggiedash.json` | Distribution targets `_maggie/admin` plus the separate `_maggie/booking` workspace |
+| `/home/balalior/Dev/MaggieDash/backend/booking-adapter-contract.d.ts` | Booking host owns the email/password session, API prefix, manager service surface, and injected provider boundary |
+| `/home/balalior/Dev/MaggieDash/contracts/booking-host-adapter-v1.json` | Current 47-endpoint Booking host contract and response policy, including treatment packages, customer package balances/redemption, package purchase/refund, Stripe verification, consented no-show fee charging, and notification inspection/replay |
+| `/home/balalior/Dev/MaggieDash/contracts/booking-customer-surface-v1.json` | Current eleven-endpoint public customer boundary and noindex/idempotency policy, including package checkout/payment return |
+| `/home/balalior/Dev/MaggieDash/package.json` | Current `0.2.8` package scripts and executable Booking validators |
+| `skills/maggie-service-booking/SKILL.md` | Current provider-backed catalogue and booking-link scope |
+| `references/provider-adapter-contract.md` | Existing provider-neutral booking/payment direction |
+| `tools/clis/maggie_dash.py` | Installer maps both admin and Booking workspaces, plus root contracts/schema |
+| `tools/clis/maggie_booking.py` | Booking installer plus inspect, contract, runtime, and release gates |
+| `/home/balalior/Dev/MaggieDash/adapters/astro/host/` | Generic non-destructive Astro host scaffold for auth, routes, PostgreSQL, Stripe, schema, Resend worker, and middleware |
+| `/home/balalior/Dev/MaggieDash/contracts/booking-email-templates-v1.json` | Ten-event tenant-scoped template contract and server-only Resend/recipient policy |
+| `/home/balalior/Dev/MaggieDash/backend/booking/email-templates.mjs` | Provider-neutral fallback, placeholder allowlist, HTML escaping, and renderer |
+
+## Documents
+
+| Document | Diataxis role | Use it for |
+|---|---|---|
+| [PRD](./PRD.md) | Reference | Product scope, requirements, personas, and acceptance criteria |
+| [Architecture](./ARCHITECTURE.md) | Explanation | System boundary, modules, state ownership, and runtime topology |
+| [User journeys](./USER-JOURNEYS.md) | Tutorial / explanation | Manager, customer, staff, finance, and failure journeys |
+| [Data flow](./DATA-FLOW.md) | Explanation / reference | DFD, events, consistency, and source-of-truth rules |
+| [Data model](./DATA-MODEL.md) | Reference | Entities, constraints, indexes, and migration order |
+| [Payment gateway](./PAYMENT-GATEWAY.md) | Reference / explanation | Provider port, Stripe adapter, webhooks, refunds, and future providers |
+| [Stripe integration audit](./STRIPE-INTEGRATION.md) | Reference / runbook | Verified API matrix, webhook set, Tax/Billing/Terminal/Connect choices, and gift-card/referral boundary |
+| [Host adapter](./HOST-ADAPTER.md) | Reference | Routes, payloads, auth, errors, and conformance evidence |
+| [Skills and CLI](./SKILLS-AND-CLI.md) | How-to / reference | How ai-cmo-skills supports implementation, checks, and release gates |
+| [Security and compliance](./SECURITY-COMPLIANCE.md) | Explanation / reference | Secrets, tenancy, audit, PCI scope, privacy, and operational controls |
+| [QA plan](./QA-TEST-PLAN.md) | How-to / reference | Contract, state, concurrency, payment, browser, and release tests |
+| [Runtime operations](./RUNTIME-OPERATIONS.md) | How-to / runbook | Worker jobs, webhook flow, notification outbox, cron/systemd, browser evidence, alerts and rollback |
+| [Current state](./CURRENT-STATE.md) | Reference / runbook | Verified surface, release blockers, host sequence, and gaps |
+| [Decision log](./DECISIONS.md) | Explanation | Durable architecture decisions and unresolved choices |
+| [Execution board](./EXECUTION-BOARD.json) | Reference | Leaf tasks with dependencies, implementation files, tests, docs, and acceptance evidence |
+| [Task runbook](./TASK-RUNBOOK.md) | How-to | Task → plan → implement → test → docs → progress operating loop |
+| [ORA integration audit](./ORAWELLNESS-INTEGRATION-AUDIT.md) | Reference | Host-specific Booking, Stripe, Resend, migration, and production-readiness status |
+
+## Diagrams
+
+The source files live in [`diagrams/`](./diagrams/). Rendered images are linked
+from the data-flow and architecture documents so the documentation does not
+depend on GitHub Mermaid rendering.
+
+- [System context](./diagrams/system-context.svg)
+- [Manager journey](./diagrams/manager-journey.svg)
+- [Booking data-flow diagram](./diagrams/booking-dfd.svg)
+- [Payment sequence](./diagrams/payment-sequence.svg)
+- [Booking state machine](./diagrams/booking-state-machine.svg)
+
+Each diagram also has an editable `.mmd` source. Flowcharts include an
+`.excalidraw` scene; the sequence and state diagrams intentionally include only
+SVG and PNG because the renderer's editable-scene converter supports flowcharts
+only.
+
+## Recommended host rollout
+
+1. Read [`CURRENT-STATE.md`](./CURRENT-STATE.md) and run the read-only install,
+   schema, contract, and build checks.
+2. Back up the host database and rehearse restore into an empty disposable
+   database.
+3. Apply Booking/access migrations only after owner approval, then register the
+   first owner and seed a staging location/catalogue/staff schedule.
+4. Configure and verify Stripe test credentials plus the signed webhook secret.
+5. Enable one worker scheduler with lock, alert, retry, and dead-letter proof;
+   verify Resend invitation, reset, reminder, waitlist, refund, package, and
+   no-show delivery.
+6. Capture the 47-endpoint runtime, 45-screen browser, and ops evidence bundle;
+   run the final release gate before a one-location canary.
+
+The detailed execution board is maintained by
+[`EXECUTION-BOARD.json`](./EXECUTION-BOARD.json). Use
+`maggie booking tasks validate` before starting a task and record the evidence
+in [`PROGRESS.md`](./PROGRESS.md). A final delivery decision must require
+runtime, browser, ops, and board evidence:
+
+```bash
+maggie booking release-gate --project . --require-runtime \
+  --evidence .maggie/booking/runtime-evidence.json \
+  --require-browser --browser-evidence .maggie/booking/browser/evidence.json \
+  --require-ops --ops-evidence .maggie/booking/ops-evidence.json \
+  --require-board
+```
+
+## Non-negotiable truths
+
+- PostgreSQL is business truth.
+- The availability engine and database constraints are booking truth.
+- The payment gateway is payment truth, but never booking truth.
+- A payment redirect is not proof of payment; a verified webhook or provider
+  read is required.
+- A hold is a first-class record with an expiry and an idempotency key.
+- All monetary values use integer minor units plus an ISO currency.
+- All stored instants are UTC; venue-local input carries an IANA timezone.
+- Manager actions are authenticated, authorized, idempotent, and auditable.
+- Provider credentials stay server-side and never enter dashboard props or
+  browser bundles.
+
+## Evidence boundary
+
+The existing MaggieDash source and ai-cmo-skills contracts were inspected on
+2026-09-21. Statements marked **current** describe repository evidence.
+Statements marked **proposed** describe the implementation target and must not
+be presented to a user as an already-supported feature until the relevant
+contract, adapter, tests, and runtime evidence land.

package/bundled-references/maggiedash-booking/RUNTIME-OPERATIONS.md

@@ -0,0 +1,152 @@
+# Booking runtime operations
+
+This document turns the host-owned runtime boundary into deployable pieces.
+MaggieDash supplies the rules and contracts; the host supplies PostgreSQL,
+provider adapters, email/SMS, secrets, tenant scope, and deployment.
+
+## Data model to service map
+
+| Runtime concern | Tables | Code/contract | Owner |
+|---|---|---|---|
+| Availability | `maggiedash_booking_working_hours`, `shifts`, `time_off`, `allocations`, `holds`, `bookings` | `backend/booking/domain.mjs` `computeAvailability` | host transaction + Booking worker |
+| Holds | `maggiedash_booking_holds`, `idempotency_keys`, `events`, `audit_events` | `expireHolds` and `booking.holds.*` endpoints | host worker |
+| Payment webhook | `payment_attempts`, `webhook_events`, `events`, `audit_events` | `payment-webhook.mjs`, `booking.provider.webhook` | host server route |
+| Payment reconciliation | `payment_attempts`, `refunds`, `webhook_events` | `reconcilePaymentEvents` and `booking.payment.*` endpoints | host worker/provider adapter |
+| Notifications | `outbox`, `notifications`, `events`, `audit_events` | `notifications.mjs`, `claimNotifications`, `scheduleNotification` | host email/SMS adapter |
+| Browser evidence | no business tables; artifact storage only | `booking-browser-evidence-v1.json` and capture/validate scripts | protected CI environment |
+
+## Worker sequence
+
+```text
+lock tenant
+  │
+  ├─ expire holds
+  │    └─ append hold.expired event + audit/outbox in one DB transaction
+  ├─ reconcile verified payment events
+  │    └─ dedupe provider event, reject mismatch, update payment projection
+  ├─ refresh availability
+  │    └─ read UTC schedule and exclusion state, publish labelled read model
+  └─ claim notification outbox rows
+       └─ dispatch with idempotency key, mark sent or retry/dead-letter
+unlock tenant
+```
+
+The database exclusion constraints remain the final double-booking guard. A
+distributed lock reduces duplicate work but is not a correctness substitute.
+
+Every installed PostgreSQL worker performs a read-only schema preflight before
+acquiring the tenant lock. It checks the core, Booking, and access tables. If a
+migration is missing, it exits with code 1 and emits bounded JSON with
+`status: "needs-migration"`; it does not load worker state, acquire the lock,
+or write business rows. Operators should run the schema command's `--dry-run`
+before an explicitly approved `--apply --confirm` migration.
+
+Notification delivery is intentionally after booking/payment truth is committed.
+`notifications.mjs` stores only a recipient hash and allowlisted template
+variables, leases rows before dispatch, retries with exponential backoff, moves
+exhausted rows to `dead_letter`, and requires an operator reason for replay.
+Delivery failure therefore cannot roll back a booking transaction.
+
+## Service and cron choices
+
+Use one of these, never both for the same tenant:
+
+1. `ops/systemd/maggie-booking-worker.service` plus `.timer` on a VPS. The
+   timer runs every minute and systemd provides restart/logging boundaries.
+2. `ops/cron/maggie-booking-cron.example` on a host without systemd. `flock`
+   makes the single-host job non-overlapping.
+3. A platform scheduler calling the same worker command with a distributed
+   lock for a multi-replica deployment.
+
+The worker is four logical jobs, not four independent processes. Run them in
+this order so expired holds cannot continue blocking or leaking into
+availability. Webhooks are event-driven and should call the server helper
+immediately; the reconciliation job is a recovery poll, not the primary
+payment signal.
+
+## Host adapter module
+
+The production command accepts a host module:
+
+```bash
+node maggiedash/backend/booking/run-booking-jobs.mjs \
+  --adapter /etc/maggie/booking-adapter.mjs \
+  --job all --write --output /var/lib/maggie/booking/last-run.json
+```
+
+The module must export:
+
+```js
+export async function loadState() { /* tenant-scoped PostgreSQL read */ }
+export async function saveState(nextState) { /* transaction + audit/outbox */ }
+export async function dispatchNotification(item) { /* idempotent email/SMS */ }
+export async function acquireLock() { /* PostgreSQL advisory/distributed lock */ }
+export async function releaseLock() { /* release the tenant lock */ }
+```
+
+The adapter binds tenant IDs and makes the state snapshot/write atomic. The
+runner acquires and releases the adapter lock around the full cycle. The JSON
+fixture mode is for local development and CI only, and is rejected when
+`NODE_ENV=production`.
+
+MaggieDash also ships `backend/booking/postgres-worker-repository.mjs`. A host
+can compose it with the adapter seam by injecting a parameterized query
+function, a checked-out-client transaction callback, a tenant scope, and the
+availability window configuration. It persists worker state, acknowledges
+verified payment events, writes availability snapshots, and uses a PostgreSQL
+advisory lock. The query function and transaction callback must use the same
+client; the module does not import `pg` or read secrets. The repository accepts
+the adapter context `{ tenantScope, nextState }` and rejects a mismatched
+tenant scope, so the adapter/repository boundary cannot silently discard a
+state write.
+
+## Payment webhook sequence
+
+1. Host route receives raw body and provider headers.
+2. `handlePaymentWebhook` calls the provider verifier before parsing trustable
+   fields.
+3. Provider adapter normalizes event ID, payment attempt ID, status, amount,
+   currency, occurrence time, and account/tenant reference.
+4. Existing `(provider, provider_event_id)` returns idempotent success.
+5. Unknown attempt is quarantined for operator reconciliation, not confirmed.
+6. Tenant, amount, and currency mismatches return a safe 422 error.
+7. Verified event is inserted, then the worker applies ordering and updates
+   booking/payment projections.
+
+## Browser evidence workflow
+
+The protected workflow in
+`.github/workflows/booking-browser-evidence.yml` requires an HTTPS base URL and
+an environment-scoped, short-lived storage state. It captures 15 manager
+screens at mobile/tablet/desktop widths, records console/request failures, uploads
+artifacts for 14 days, and fails validation when any route is missing, not
+ready, non-2xx, or has a browser/network error.
+
+Never commit storage state, cookies, screenshots with customer data, or raw
+provider payloads. Use a dedicated test tenant and redact artifacts before
+retention beyond the CI window.
+
+The companion `.github/workflows/booking-runtime-evidence.yml` uses the same
+session boundary plus a host-owned runtime plan to exercise every declared
+Booking endpoint. It requires `--confirm` because the plan includes disposable
+test mutations, and it writes only sanitized 2xx/required-field observations.
+Run `maggie booking runtime-validate` on the resulting artifact before the
+release gate. A fixture evidence file can validate the toolchain locally but
+must never be used as production evidence.
+
+## Alerts and rollback
+
+Alert on:
+
+- worker lock contention or two missed minute ticks;
+- availability read model older than five minutes;
+- holds expiring above baseline;
+- payment webhook verification/quarantine spikes or reconciliation lag;
+- notification retries/dead letters;
+- browser evidence console/network errors, route readiness failures, or
+  `layoutErrors` horizontal overflow.
+
+Rollback disables new booking writes and payment capture through host feature
+flags. It does not delete confirmed bookings, payments, webhooks, events,
+notifications, or audit history. Existing bookings remain readable and
+operable for cancellation/refund recovery.