@ingenx-io/valets-schema-mcp-server 0.1.1 → 0.1.3

package/data/static/decisions.json

@@ -0,0 +1,966 @@
+{
+  "generated": "2026-02-28",
+  "source": "DATA_MODEL_DECISION_WORKBOOK.md",
+  "decisions": [
+    {
+      "id": "D00",
+      "title": "Shared schema package approach",
+      "decision": "Zod as source of truth → TS direct import (Dashboard/Firebase) + JSON Schema → Dart codegen (Mobile)",
+      "rationale": "Prerequisite for all type alignment work",
+      "refs": [
+        "CROSS_CUTTING §Insight 1",
+        "all alignment docs"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Zod → JSON Schema → Dart (quicktype). See §9 for full spec.",
+      "schema_refs": [],
+      "wave": 1
+    },
+    {
+      "id": "D01",
+      "title": "Canonical PaymentStatus enum set",
+      "decision": "Use billing.ts set + REFUND_PROCESSING: PENDING, PAID, PARTIALLY_PAID, FAILED, REFUND_PROCESSING, REFUNDED, PARTIALLY_REFUNDED (7 values)",
+      "rationale": "Blocks orders/bookings/billing parity and migrations",
+      "refs": [
+        "ORDER#2",
+        "BOOKING_MODEL_ALIGNMENT §10"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "7-value PaymentStatus: PENDING, PAID, PARTIALLY_PAID, FAILED, REFUND_PROCESSING, REFUNDED, PARTIALLY_REFUNDED. Added REFUND_PROCESSING for refund-in-progress transitional state.",
+      "schema_refs": [
+        "payment-status"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D02",
+      "title": "Canonical PaymentMethod enum set",
+      "decision": "Unified set with African + global methods (CASH, CREDIT_CARD, ORANGE_MONEY, WAVE, MTN_MONEY, MOOV_MONEY, BANK_TRANSFER, PAYPAL, STRIPE, OTHER)",
+      "rationale": "Blocks sales/payment interoperability",
+      "refs": [
+        "SALES#1",
+        "SALES#7"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Use unified payment method set (African + global)",
+      "schema_refs": [
+        "payment-method"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D03",
+      "title": "CONFIRMED vs PROCESSING for order lifecycle",
+      "decision": "Keep both with explicit semantics (CONFIRMED = accepted/committed; PROCESSING = in preparation/fulfillment)",
+      "rationale": "Active cross-platform status mismatch",
+      "refs": [
+        "ORDER#1"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Keep both: CONFIRMED = accepted/committed, PROCESSING = in preparation. See §8 State Machine. Skip-CONFIRMED allowed but not ideal. Stale-order alerts per business config.",
+      "schema_refs": [
+        "order-status"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D04",
+      "title": "Canonical timestamp/status field casing",
+      "decision": "Locked: Single convention — SCREAMING_SNAKE for all lifecycle timestamp fields. Migrate Mobile camelCase.",
+      "rationale": "Blocks migration and serializer consistency",
+      "refs": [
+        "ORDER#3",
+        "EVENTS#1"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Single convention: SCREAMING_SNAKE for all lifecycle timestamp fields. Migrate Mobile camelCase fields (processingOn → PROCESSING_ON, etc.)",
+      "schema_refs": [
+        "order"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D05",
+      "title": "Canonical purchase amount field",
+      "decision": "Locked: amount is only persisted field. total is a read-only getter in code (not written to Firestore).",
+      "rationale": "Blocks dual-write cleanup",
+      "refs": [
+        "SALES#3"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "amount is the only persisted field. total becomes a read-only getter in code (not written to Firestore). Mobile stops writing total.",
+      "schema_refs": [
+        "sale"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D06",
+      "title": "Canonical sales collection path",
+      "decision": "Locked (revised): Keep Firestore collection as purchases/. Use code-level alias (SalesService wrapping purchases collection). Single company-wide path; eliminate customer-scoped duplicate.",
+      "rationale": "Blocks data fragmentation and query strategy",
+      "refs": [
+        "SALES#4"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Keep Firestore collection as purchases/. Use code-level alias (SalesService wrapping purchases collection). Avoids high-cost collection rename.",
+      "schema_refs": [
+        "sale"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D07",
+      "title": "Canonical loyalty transaction type values",
+      "decision": "SCREAMING_SNAKE past tense: EARNED, REDEEMED, ADJUSTED, EXPIRED, BONUS, REFUND",
+      "rationale": "Blocks dashboard/mobile readability",
+      "refs": [
+        "CUSTOMER#1"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "SCREAMING_SNAKE: EARNED, REDEEMED, ADJUSTED, EXPIRED, BONUS, REFUND. Aligned with system-wide D04 convention. Migration required for existing lowercase values.",
+      "schema_refs": [
+        "loyalty-transaction-type"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D08",
+      "title": "Canonical location for customer points",
+      "decision": "customers/{id}/loyalty/status is source of truth; customer doc gets optional derived summary only",
+      "rationale": "Blocks drift and trigger design",
+      "refs": [
+        "CUSTOMER#2"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "loyalty/status as source of truth",
+      "schema_refs": [
+        "customer",
+        "loyalty-status"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D09",
+      "title": "Canonical startDate/endDate type for bookings",
+      "decision": "number (YYYYMMDD)",
+      "rationale": "Blocks query consistency and typings",
+      "refs": [
+        "BOOKING#2"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "number YYYYMMDD; requested pros/cons follow-up captured below",
+      "schema_refs": [
+        "booking"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D10",
+      "title": "Canonical booking add-on IDs",
+      "decision": "Descriptive IDs: recording, photo",
+      "rationale": "Blocks label mapping and migration",
+      "refs": [
+        "BOOKING#1"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Implement additively with legacy compatibility, avoid disruptive rewrite",
+      "schema_refs": [
+        "booking"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D11",
+      "title": "Canonical price field names in booking slots",
+      "decision": "price, notMainPurposePrice",
+      "rationale": "Blocks legacy alias cleanup",
+      "refs": [
+        "BOOKING#6"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Canonical names: price, notMainPurposePrice. Read fallbacks for 1-2 cycles, then remove.",
+      "schema_refs": [
+        "booking"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D12",
+      "title": "Payments canonical location model",
+      "decision": "payments[] on Sale; allow denormalized snapshot on Order when linked",
+      "rationale": "Blocks overlap between OrderPayment and PaymentTransaction",
+      "refs": [
+        "SALES#2",
+        "ORDER#5"
+      ],
+      "queue": "priority",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Canonical on sale, optional order snapshot when linked",
+      "schema_refs": [
+        "order",
+        "sale"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D13",
+      "title": "Mobile order status support breadth",
+      "decision": "Full 7-value OrderStatus typed enum (per D34 decomposition); fulfillmentStatus and returnStatus as optional typed enums",
+      "refs": [
+        "ORDER#6",
+        "D34"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "OrderStatus typed enum: PENDING, CONFIRMED, PROCESSING, READY, COMPLETED, CANCELLED, EXPIRED (7 values). Extended statuses removed — now separate fields per D34.",
+      "schema_refs": [
+        "order-status"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D14",
+      "title": "Keep Mobile order override fields (calculatedTotal, manualTotal, totalOverridden)",
+      "decision": "Keep temporarily as optional fields; review removal after 2 release cycles",
+      "refs": [
+        "ORDER#4"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Keep mobile override fields temporarily",
+      "schema_refs": [
+        "order"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D15",
+      "title": "Should SaleMargin be server-side",
+      "decision": "Yes, move computation to Firebase trigger/service",
+      "refs": [
+        "SALES#5"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Move SaleMargin server-side",
+      "schema_refs": [
+        "sale"
+      ],
+      "wave": 3
+    },
+    {
+      "id": "D16",
+      "title": "Mobile CRM scope",
+      "decision": "Read-only first; no full CRM authoring",
+      "refs": [
+        "SALES#6"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Mobile CRM stays read-only first",
+      "schema_refs": [
+        "customer"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D17",
+      "title": "Mobile CRDT write behavior for bookings",
+      "decision": "Read CRDT tombstones now; keep hard-delete writes short-term; schedule soft-delete parity later",
+      "refs": [
+        "BOOKING#3"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Prioritize parity",
+      "schema_refs": [
+        "booking"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D18",
+      "title": "Firebase BookingVersion ownership",
+      "decision": "Yes, server-side version generation on write",
+      "refs": [
+        "BOOKING#4"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Requested context on purpose/current handling",
+      "schema_refs": [
+        "booking",
+        "booking-version"
+      ],
+      "wave": 3
+    },
+    {
+      "id": "D19",
+      "title": "Mobile session status transitions",
+      "decision": "Read-only: Mobile displays session statuses but cannot transition them. Dashboard remains sole writer.",
+      "refs": [
+        "BOOKING#5"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Read-only first. Mobile displays per-session statuses but cannot transition them. Dashboard remains sole writer.",
+      "schema_refs": [
+        "session-status"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D20",
+      "title": "createdFromBackend behavior for dashboard-created bookings",
+      "decision": "Dashboard sets flag explicitly where notification suppression is desired",
+      "refs": [
+        "BOOKING#7"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Requested context on why a decision is needed",
+      "schema_refs": [
+        "booking"
+      ],
+      "wave": 3
+    },
+    {
+      "id": "D21",
+      "title": "Loyalty config canonical field names",
+      "decision": "Adopt Mobile naming: pointsPerCurrency, pointsExpirationDays, etc.",
+      "refs": [
+        "CUSTOMER#3"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Deeper loyalty-module dive requested later",
+      "schema_refs": [
+        "loyalty-config"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D22",
+      "title": "Mobile customer payment feature scope",
+      "decision": "Trusted-party capture: cashier/manager roles create payments with mandatory audit fields; advanced allocation/edit/refund stays Dashboard-only",
+      "refs": [
+        "CUSTOMER#4"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Trusted-party capture: cashier/manager roles can create payments from Mobile with mandatory audit fields (recordedBy, recordedByName, timestamp, reference). Advanced allocation/edit/refund stays Dashboard-only.",
+      "schema_refs": [
+        "customer-payment"
+      ],
+      "wave": 4
+    },
+    {
+      "id": "D23",
+      "title": "Firebase loyalty automation",
+      "decision": "Yes (award, expire, validate server-side)",
+      "refs": [
+        "CUSTOMER#5"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Server-side loyalty automation approved",
+      "schema_refs": [
+        "loyalty-transaction"
+      ],
+      "wave": 3
+    },
+    {
+      "id": "D24",
+      "title": "Customer reference naming standardization",
+      "decision": "Standardize for new writes only; document mapping for legacy data",
+      "refs": [
+        "CUSTOMER#6"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Standardize names for new writes",
+      "schema_refs": [
+        "customer",
+        "booking",
+        "order"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D25",
+      "title": "communicationEntries storage shape",
+      "decision": "Keep as array unless cardinality/perf issues arise",
+      "refs": [
+        "CUSTOMER#7"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Keep as embedded array on Customer document. Move to subcollection only if cardinality/perf becomes a problem.",
+      "schema_refs": [
+        "customer"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D26",
+      "title": "Event/Ticket support in dashboard",
+      "decision": "Yes, if cross-platform parity is a product goal this cycle",
+      "refs": [
+        "EVENTS#3"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Dashboard should be superset of functionality",
+      "schema_refs": [
+        "event"
+      ],
+      "wave": 4
+    },
+    {
+      "id": "D27",
+      "title": "Dashboard ticket scanning",
+      "decision": "Optional; keep mobile-first scanning initially",
+      "refs": [
+        "EVENTS#4"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Keep mobile-first scanning initially",
+      "schema_refs": [
+        "ticket"
+      ],
+      "wave": 4
+    },
+    {
+      "id": "D28",
+      "title": "Firebase Event/Ticket triggers",
+      "decision": "Yes (notifications, counters, metrics)",
+      "refs": [
+        "EVENTS#5"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Add Firebase Event/Ticket triggers when Dashboard Event support (D26) is built. Not before — Events are Mobile-only today.",
+      "schema_refs": [
+        "event",
+        "ticket"
+      ],
+      "wave": 4
+    },
+    {
+      "id": "D29",
+      "title": "Ticket-to-customer linkage model",
+      "decision": "Add optional customerId + keep denormalized fields for compatibility",
+      "refs": [
+        "EVENTS#6"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Link tickets to customer with compatibility",
+      "schema_refs": [
+        "ticket"
+      ],
+      "wave": 2
+    },
+    {
+      "id": "D30",
+      "title": "Ticket tiers/types support timing",
+      "decision": "Defer until business requirement is confirmed",
+      "refs": [
+        "EVENTS#7"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Defer ticket tiers",
+      "schema_refs": [
+        "ticket"
+      ],
+      "wave": null
+    },
+    {
+      "id": "D31",
+      "title": "LegacyTicketMapper deprecation gate",
+      "decision": "Remove only after migration confirms zero legacy docs",
+      "refs": [
+        "EVENTS#8"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Deprecate legacy mapper after data migration completion",
+      "schema_refs": [
+        "ticket"
+      ],
+      "wave": 5
+    },
+    {
+      "id": "D32",
+      "title": "Event/Ticket status casing",
+      "decision": "Move to SCREAMING_SNAKE with fallback reads during migration",
+      "refs": [
+        "EVENTS#1"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Migrate status casing with fallback",
+      "schema_refs": [
+        "event-status",
+        "ticket-status"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D33",
+      "title": "Deterministic IV in QR encryption",
+      "decision": "Deferred — not essential for current cycle",
+      "refs": [
+        "EVENTS#2"
+      ],
+      "queue": "second-wave",
+      "status": "deferred",
+      "date": "2026-02-27",
+      "owner": "User (chat)",
+      "notes": "Not essential for current cycle",
+      "schema_refs": [],
+      "wave": null
+    },
+    {
+      "id": "D34",
+      "title": "Order status decomposition into orthogonal fields",
+      "decision": "Decompose 20-value OrderStatus into 4 fields: orderStatus (7), paymentStatus (7, D01), fulfillmentStatus (6, new), returnStatus (6, new)",
+      "refs": [
+        "ORDER cross-cutting"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Decompose into 4 orthogonal status fields. See §10 for full spec. Supersedes old \"extended statuses\" in §8.",
+      "schema_refs": [
+        "order",
+        "order-status",
+        "payment-status",
+        "fulfillment-status",
+        "return-status"
+      ],
+      "wave": 1
+    },
+    {
+      "id": "D35",
+      "title": "Migration framework approach",
+      "decision": "CLI + callable hybrid: CLI for heavy (>100K docs), Firebase callable for incremental/per-company. Shared progress tracking in Firestore.",
+      "refs": [
+        "CROSS_CUTTING §Insight 3"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Both CLI + callable. CLI for heavy one-time migrations (>100K docs). Firebase callable for incremental/per-company runs. Shared progress tracking in Firestore. See §12.",
+      "schema_refs": [],
+      "wave": 1
+    },
+    {
+      "id": "D36",
+      "title": "Firebase architectural role: relay vs enforcer",
+      "decision": "Log-and-heal (Waves 1-3) → strict enforcement (post-Wave 3). Validate on write, auto-normalize known patterns.",
+      "refs": [
+        "CROSS_CUTTING §Insight 2"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Log-and-heal now → strict later. Validate on write, log issues, auto-normalize known patterns. Switch to strict enforcement after migration waves complete. See §13.",
+      "schema_refs": [],
+      "wave": 1
+    },
+    {
+      "id": "D37",
+      "title": "Execution wave plan approval",
+      "decision": "5-wave rollout: Foundation → Adoption → Server-Side Logic → Feature Parity → Cleanup",
+      "refs": [
+        "CROSS_CUTTING §Part 3"
+      ],
+      "queue": "second-wave",
+      "status": "locked",
+      "date": "2026-02-26",
+      "owner": "User (chat)",
+      "notes": "Approved as proposed: 5-wave phased rollout (Foundation → Adoption → Server-Side Logic → Feature Parity → Cleanup). See §14.",
+      "schema_refs": [],
+      "wave": 1
+    }
+  ],
+  "implementation_gaps": [
+    {
+      "id": "IG-1",
+      "summary": "Cross-Platform Contract Testing",
+      "wave": 1,
+      "acceptance_criteria": "Shared JSON fixtures exist for all models; read/write round-trip tests pass across all 3 platforms",
+      "refs": [
+        "ORDER §5.1-5.2",
+        "SALES §6.1-6.2"
+      ]
+    },
+    {
+      "id": "IG-2",
+      "summary": "Firestore Security Rules Generation",
+      "wave": 3,
+      "acceptance_criteria": "Security rules enforce basic type checks for critical collections; generated or manually aligned with @valets/schema",
+      "refs": [
+        "ORDER §5.1",
+        "SALES §6.2"
+      ]
+    },
+    {
+      "id": "IG-3",
+      "summary": "Booking Model Convergence (Mobile)",
+      "wave": 2,
+      "acceptance_criteria": "Single canonical Booking class on Mobile generated from @valets/schema; BookingData page class removed or reduced to UI-only state",
+      "refs": [
+        "BOOKING gap #4"
+      ]
+    },
+    {
+      "id": "IG-4",
+      "summary": "Order Payments Model Ownership",
+      "wave": 2,
+      "acceptance_criteria": "OrderPayment → PaymentTransaction field mapping documented; sync rules for Sale↔Order denormalized snapshot implemented",
+      "refs": [
+        "ORDER §4.3",
+        "SALES §Phase 3",
+        "D12"
+      ]
+    },
+    {
+      "id": "IG-5",
+      "summary": "Purchases Collection Path Consolidation",
+      "wave": 1,
+      "acceptance_criteria": "All purchase documents exist in single purchases/ path; customer-scoped duplicates removed; references rewritten",
+      "refs": [
+        "SALES gap",
+        "D06",
+        "MIG-04"
+      ]
+    },
+    {
+      "id": "IG-6",
+      "summary": "Booking CRDT Interoperability",
+      "wave": 2,
+      "acceptance_criteria": "Mobile fromMap filters _deleted items; conflict resolution documented; timeline for soft-delete parity set",
+      "refs": [
+        "BOOKING gap #2",
+        "D17"
+      ]
+    },
+    {
+      "id": "IG-7",
+      "summary": "Customer Payments Rollout Spec",
+      "wave": 4,
+      "acceptance_criteria": "Trusted roles defined; audit field requirements in @valets/schema; server-side validation rules deployed",
+      "refs": [
+        "CUSTOMER gap #3",
+        "D22"
+      ]
+    },
+    {
+      "id": "IG-8",
+      "summary": "Notification Behavior Policy",
+      "wave": 3,
+      "acceptance_criteria": "createdFromBackend behavior documented and consistently applied; notification regression tests in CI",
+      "refs": [
+        "BOOKING §D20",
+        "ORDER §8"
+      ]
+    },
+    {
+      "id": "IG-9",
+      "summary": "Event/Ticket Crypto + Legacy Cutover",
+      "wave": 5,
+      "acceptance_criteria": "LegacyTicketMapper removal gate query exists; key rotation policy documented; IV migration plan ready when triggered",
+      "refs": [
+        "EVENTS gaps #3/#5",
+        "D31",
+        "D33"
+      ]
+    },
+    {
+      "id": "IG-10",
+      "summary": "LoyaltyReward / LoyaltyConfig Parity",
+      "wave": 2,
+      "acceptance_criteria": "Mobile-only loyalty fields catalogued; canonical set defined in @valets/schema; Dashboard config UI spec created",
+      "refs": [
+        "CUSTOMER gaps #6/#8"
+      ]
+    },
+    {
+      "id": "IG-11",
+      "summary": "slotKitTypes Firebase Type Parity",
+      "wave": 2,
+      "acceptance_criteria": "slotKitTypes field added to Firebase Booking type definition; validated in contract tests",
+      "refs": [
+        "BOOKING gap #8"
+      ]
+    },
+    {
+      "id": "IG-12",
+      "summary": "bookingId Mobile Purchase Parity",
+      "wave": 2,
+      "acceptance_criteria": "bookingId field added to Mobile Purchase model; links sales to bookings across platforms",
+      "refs": [
+        "SALES gap #7"
+      ]
+    },
+    {
+      "id": "IG-13",
+      "summary": "companyId Firebase Quote/Opportunity Parity",
+      "wave": 2,
+      "acceptance_criteria": "companyId field added to Firebase Quote and Opportunity type definitions; multi-tenant queries work",
+      "refs": [
+        "SALES gap #8"
+      ]
+    }
+  ],
+  "migrations": [
+    {
+      "id": "MIG-01",
+      "name": "Timestamp field casing",
+      "type": "data",
+      "collection": "orders",
+      "decision": "D04",
+      "description": "Rename processingOn → PROCESSING_ON, completedOn → COMPLETED_ON, cancelledOn → CANCELLED_ON, etc.",
+      "wave": 1
+    },
+    {
+      "id": "MIG-02",
+      "name": "Payment method normalization",
+      "type": "data",
+      "collection": "purchases",
+      "decision": "D02",
+      "description": "In payments[] array: CARD → CREDIT_CARD, OM → ORANGE_MONEY, MTN → MTN_MONEY, MOOV → MOOV_MONEY",
+      "wave": 1
+    },
+    {
+      "id": "MIG-03",
+      "name": "PaymentStatus consolidation",
+      "type": "data",
+      "collection": "orders, purchases, bookings",
+      "decision": "D01",
+      "description": "UNPAID → PENDING, PARTIAL → PARTIALLY_PAID (Dashboard's conflicting enum). Bookings also carry payment status.",
+      "wave": 1
+    },
+    {
+      "id": "MIG-04",
+      "name": "Purchases path consolidation",
+      "type": "data",
+      "collection": "customers/*/purchases → purchases",
+      "decision": "D06",
+      "description": "Move customer-scoped purchase docs to company-wide path. Deduplicate. Rewrite references. See IG-5 (§15) for acceptance criteria.",
+      "wave": 1
+    },
+    {
+      "id": "MIG-05",
+      "name": "Loyalty transaction type normalization",
+      "type": "data",
+      "collection": "loyaltyTransactions",
+      "decision": "D07",
+      "description": "earn/earned → EARNED, redeem/redeemed → REDEEMED, adjust/adjusted → ADJUSTED, expire/expired → EXPIRED, bonus → BONUS, refund → REFUND",
+      "wave": 1
+    },
+    {
+      "id": "MIG-06",
+      "name": "Loyalty config field renaming",
+      "type": "data",
+      "collection": "loyaltySettings/config",
+      "decision": "D21",
+      "description": "pointsPerCurrencyUnit → pointsPerCurrency, pointsExpiryMonths → pointsExpirationDays (convert months×30)",
+      "wave": 1
+    },
+    {
+      "id": "MIG-07",
+      "name": "Booking add-on ID normalization",
+      "type": "data",
+      "collection": "bookings (nested slots)",
+      "decision": "D10",
+      "description": "Numeric IDs ('1', '2') → descriptive ('recording', 'photo'). Additive with legacy compat.",
+      "wave": 1
+    },
+    {
+      "id": "MIG-08",
+      "name": "Booking price field renaming",
+      "type": "data",
+      "collection": "bookings (nested slots)",
+      "decision": "D11",
+      "description": "standardPrice → price, fullPrice → notMainPurposePrice",
+      "wave": 1
+    },
+    {
+      "id": "MIG-09",
+      "name": "Event status casing",
+      "type": "data",
+      "collection": "events",
+      "decision": "D32",
+      "description": "draft → DRAFT, active → ACTIVE, cancelled → CANCELLED, completed → COMPLETED",
+      "wave": 1
+    },
+    {
+      "id": "MIG-10",
+      "name": "Ticket status casing",
+      "type": "data",
+      "collection": "events/*/tickets",
+      "decision": "D32",
+      "description": "valid → VALID, used → USED, cancelled → CANCELLED",
+      "wave": 1
+    },
+    {
+      "id": "MIG-11",
+      "name": "Order status decomposition",
+      "type": "data",
+      "collection": "orders",
+      "decision": "D34",
+      "description": "Split extended statuses into orderStatus + paymentStatus + fulfillmentStatus + returnStatus per §10 mapping table",
+      "wave": 1
+    },
+    {
+      "id": "MIG-12",
+      "name": "Customer points source of truth",
+      "type": "data",
+      "collection": "customers, loyalty/status",
+      "decision": "D08",
+      "description": "Verify loyalty/status populated for all customers; flag discrepancies with denormalized customer doc fields",
+      "wave": 1
+    },
+    {
+      "id": "COD-01",
+      "name": "Stop writing total",
+      "type": "code",
+      "platform": "Mobile",
+      "decision": "D05",
+      "description": "Mobile stops writing total field on purchases. total becomes read-only getter.",
+      "wave": 1
+    },
+    {
+      "id": "COD-02",
+      "name": "SalesService alias",
+      "type": "code",
+      "platform": "All",
+      "decision": "D06",
+      "description": "Code-level alias wrapping purchases collection. No Firestore rename.",
+      "wave": 1
+    },
+    {
+      "id": "COD-03",
+      "name": "Add missing BookingStatus values",
+      "type": "code",
+      "platform": "Mobile",
+      "decision": "—",
+      "description": "Add CANCELLATION_REQUESTED, COMPLETED_MIXED to Mobile enum",
+      "wave": 1
+    },
+    {
+      "id": "COD-04",
+      "name": "Add SessionStatus awareness",
+      "type": "code",
+      "platform": "Mobile, Firebase",
+      "decision": "D19",
+      "description": "Mobile reads and displays SessionStatus. Read-only first.",
+      "wave": 1
+    },
+    {
+      "id": "MIG-13",
+      "name": "Legacy ticket format migration",
+      "type": "data",
+      "collection": "events/*/tickets",
+      "decision": "D31",
+      "description": "Migrate userName/userEmail/userPhone/ticketStatus variants to canonical field names. Run only after audit confirms scope.",
+      "wave": 5
+    },
+    {
+      "id": "MIG-14",
+      "name": "Remove fallback read paths",
+      "type": "data",
+      "collection": "All platforms",
+      "decision": "Various",
+      "description": "Remove old field name readers after fallback removal gate is met (see §1 Transition Protocol).",
+      "wave": 5
+    }
+  ]
+}