Command center batch: production release runbook

This runbook covers the return-case, granular authority, subject-export, staff-invitation email, vendor-identity, WhatsApp reply, and vendor-sanction changes. It is a release checklist, not evidence that production has received this batch. Record the deployed Git SHA, migration history, operator, time, and smoke-test results before marking the release complete. No hosted DDL, email, or deployment was performed while writing this runbook. The verified database receipt is the 7 October migration receipt. It records all ten migrations 022, 023, and 025–032 as applied through MCP, including 030 after its blocker fixes passed review and regression tests. The receipt maps local filenames to hosted history versions; 030 maps to 20261007082935 with hosted name governed_whatsapp_replies. Backend, admin and storefront deployment at application revision 1a89a969 passed, together with CI and the production release workflow. No live WhatsApp message has been sent. Consult the receipt for that completed rollout; the checklist below remains guidance for future releases and provider configuration.

1. Preflight and migration order

1. Confirm the target is Debelu's production Supabase project and inspect its migration history. The prior release reported 20261011002400_align_manually_installed_command_functions.sql as applied; confirm that record before continuing. Do not replay or edit 024 if it is present. If absent or different from the checked-in file, stop and reconcile the actual schema and history before applying this batch.

2. Pass the repository's CI quality checks and the clean-database migration replay (scripts/db-flow-tests.sh) for the exact release SHA. Capture a recoverable database backup and identify the previous working backend, admin, storefront, and Edge Function deployments.

3. Reconcile these checked-in files against production history. Apply only outstanding files through Supabase MCP, exactly once, after their checks pass; verify each result in migration history before moving on. The status column reflects the readback on 7 October 2026:

   Order	Migration	Purpose	Hosted status
   1	20261011002200_atomic_return_case_governance.sql	Atomic return-case commands and receipts.	Applied
   2	20261011002300_granular_command_capabilities.sql	Separate sensitive staff grants, including default-false canReviewVendorKYC.	Applied
   checkpoint	20261011002400_align_manually_installed_command_functions.sql	Earlier alignment checkpoint; do not replay.	Applied earlier
   3	20261011002500_subject_privacy_export_delivery.sql	Protected subject export download and acknowledgment.	Applied
   4	20261011002600_guard_internal_wallet_refund_snapshot.sql	Wallet-refund snapshot tightening after 024.	Applied
   5	20261011002700_staff_invitation_delivery_outbox.sql	Durable invitation email queue and receipt RPCs.	Applied
   6	20261011002800_vendor_kyc_governance.sql	Evidence-bound vendor review and independent approval.	Applied
   7	20261011002900_vendor_kyc_onboarding_control_guard.sql	Atomic onboarding-pause guard at seller enrollment.	Applied
   8	20261011003000_governed_whatsapp_replies.sql	Durable support reply intents and provider receipts.	Applied; reviewed fixes and regression tests passed
   9	20261011003100_governed_vendor_sanctions.sql	Atomic disciplinary records, exact command replay, and expiry provenance.	Applied; independent of 030
   10	20261011003200_close_vendor_strike_truncate_boundary.sql	Close direct vendor-strike truncate privileges.	Applied; hosted 20261007085423

The files are under supabase/migrations/. A fresh database replay sorts all files chronologically, including 024; a production project with a verified 024 record only receives the outstanding files above. Never mark a failed migration as applied merely to advance the list.

2. Release application surfaces

1. Keep STAFF_INVITATION_DELIVERY_ENABLED unset or false. Set the backend and Edge Function secrets below, deploy supabase/functions/deliver-staff-invitation, and check that a worker call with no valid shared secret is refused. Do not enable a sending worker yet.
2. Deploy the matching debelu-backend revision and verify health, admin authorization, KYC routes, and invitation queue/receipt routes. The backend starts its 30-second worker only when the flag is exactly true.
3. Deploy the matching debelu-admin revision and storefront revision (the protected subject-export flow is in the storefront). The existing Cloudflare Pages workflow publishes both frontends from main; coordinate this with the backend rollout so clients do not reach missing RPCs or APIs. The repository's release documentation describes Railway as the backend host, but confirm the live deployment target and successful revision before directing traffic. The checked-in debelu-backend/railway.json currently probes /health/live; independently check /health/ready to verify database readiness. A successful liveness probe alone does not verify database access.
4. After the non-sending smoke checks pass, enable STAFF_INVITATION_DELIVERY_ENABLED=true on the backend. Confirm the worker is healthy and only then queue one controlled invitation to an approved test mailbox. A queued receipt means stored work, and provider_accepted means SES accepted the message; neither proves inbox delivery.

Required invitation settings: STAFF_INVITATION_DELIVERY_KEY must be the same canonical base64 encoding of 32 random bytes on backend and Edge Function; STAFF_INVITATION_WORKER_SECRET must be the same strong random value on both. Backend needs SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY. Edge Function needs those two values, ADMIN_URL as the HTTPS admin origin, and SES_REGION, SES_ACCESS_KEY_ID, SES_SECRET_ACCESS_KEY, and EMAIL_FROM. EMAIL_REPLY_TO and SES_CONFIGURATION_SET are optional. Keep these values out of browser builds and logs. Preserve the encryption key while any queued or ambiguous invitation ciphertext may need reconciliation; see staff-invitation-email-delivery.md.

WhatsApp reply dispatch requires backend WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_ID, and an explicit WHATSAPP_GRAPH_API_VERSION such as the version approved for the connected Meta application. Do not guess a provider version. Signed callback verification uses META_APP_SECRET; webhook setup uses WHATSAPP_WEBHOOK_VERIFY_TOKEN. Verify the worker's current enablement behavior and configuration before rollout: the checked-in server schedules reply processing every 30 seconds, and the service currently returns without dispatch when its provider configuration is missing. Migration application does not configure these secrets or certify a provider send.

3. Permission and behavior checks

• Assign canReviewVendorKYC explicitly to a global staff role in Team management. Migration 023 does not upgrade role templates or copy existing user-management grants. Verify an ungranted staff member cannot open /admin/vendor-kyc, call /api/vendors/kyc/*, or read identity evidence; verify an authorized reviewer can load the queue and document reference.
• Use separate authorized staff accounts for a controlled KYC review/proposal and the independent approval. Confirm the proposer cannot approve their own proposal, stale evidence or revoked authority fails closed, and a normal user-management path cannot bypass the governed decision.
• Verify enabling the vendor-onboarding pause prevents seller approval without changing the pending proposal or applicant privileges. Proposal rejection remains available during that pause.
• Migration 030's reviewed fixes passed 17 SQL checks, 17 backend tests, 7 admin tests, and both application typechecks. Verify the same behavior on the exact release revision: messaging pause blocks queue/claim/provider attempts while preserving queued work; definitive reply rejection unlocks the inbox; inherited service-role INSERT/UPDATE/DELETE/TRUNCATE grants cannot forge receipts or reset attempts. Test replay, opt-out, the 24-hour inbound window, early callbacks, and unknown outcomes without sending to real users. A fenced provider attempt that has started cannot be returned to the queue automatically.
• Migration 032 hosted readback confirmed no anon/authenticated/service_role truncate privilege on vendor strikes, and all 12 SQL sanction checks passed.
• Vendor sanctions record disciplinary decisions and effective expiry. They do not confirm a wallet hold or search restriction. Verify exact-command replay, stale-record rejection, stronger-sanction preservation, expired-strike provenance, and denied direct strike/projection writes in a disposable test database before any controlled production sanction.
• Check return-case revision conflicts and idempotent command receipts without triggering a financial refund. Check privacy export with the subject's authenticated AAL2 session: valid download and acknowledgment work; another subject, expired artifact, stale case revision, or active hold is refused.
• In Team management, confirm Create private link remains non-email, Email invitation initially returns queued, and delivery status can be read only by the authorized owner. Confirm expired/revoked invitations cannot be accepted. Inspect outbox and SES events when status is unknown; do not blindly reset or resend it.
• Check admin navigation, including actual expandable sidebar sections, keyboard operation, active-route visibility, and campus-scoped staff access limited to their order case queue.

4. Observe and recover

Watch backend health and errors, Edge Function failures, SES message events, the invitation outbox (queued, sending, provider_accepted, failed, unknown, cancelled), KYC command/audit receipts, and privileged 42501 or stale-command 40001 spikes. Reconcile any invitation unknown state against SES before issuing a new invitation; an ambiguous provider call must not be retried automatically.

For invitation delivery trouble, set STAFF_INVITATION_DELIVERY_ENABLED=false first; retain the outbox, audit records, and encryption key. Roll back backend, admin, storefront, or Edge Function to the last verified revision if needed. Keep applied database migrations in place; use a reviewed, tested forward compensating migration for schema or behavior repair. Record the incident, affected command IDs, evidence, and final reconciliation before re-enabling the worker or KYC decisions.