@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/event-types-registry.json

@@ -80,9 +80,18 @@
         {
           "version": 1,
           "payload_schema": null,
-          "status": "active",
+          "status": "deprecated",
           "registered_at": "2026-05-02",
-          "notes": "Emitted after Person mint or match on intake.captured. Carries person_id and the originating event_id (correlation)."
+          "deprecated_at": "2026-05-12",
+          "notes": "Initial version with top-level person_id + originating_event_id + match_type + matched_at. Deprecated 2026-05-12 in favor of v2 which adds the submission_summary block so Sales can open a Lead from the matched event alone (no back-lookup against Growth's dispatcher_event). Producer cutover to v2 at 2026-05-26 (deprecated_at + 14 days per envelope-contract §16). v1 stays consumable by old consumers through that window; producer Platform flips from emitting v1 to v2 at cutover."
+        },
+        {
+          "version": 2,
+          "payload_schema": "contracts/identity/schema/payloads/intake.matched-v2.json",
+          "status": "active",
+          "registered_at": "2026-05-12",
+          "active_from": "2026-05-26",
+          "notes": "Adds the submission_summary block (first_name, last_name, phone_normalized, zip, student_age_group, timeline, lesson_setting, new_qualified) plus source / campaign_code / landing_url carry-through from the originating intake.captured. Eliminates Sales' need to JOIN back to Growth's dispatcher_event when opening a Lead. Authored per the 2026-05-12 decision to forward operator-relevant fields on intake.matched rather than have downstream consumers chase secondary lookups; consistent with the topology B principle of self-contained envelopes."
         }
       ]
     },
@@ -104,6 +113,159 @@
         }
       ]
     },
+    "platform.comms.inbound": {
+      "producer": "platform",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/platform-comms/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/platform-comms/schema/payloads/platform.comms.inbound-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-17",
+          "notes": "Platform-owned inbound SMS and voice-call cadence-reset signal per 2026-05-17-platform-cadence-inbound-comms-position. Subject is person_id, actor is system:platform. Payload carries safe routing metadata only; raw provider payloads, full body text, contact details, and transcripts stay in Platform-owned comms storage. Sales consumes to reset cadence; platform-warehouse ingests for analytics."
+        }
+      ]
+    },
+    "coaching.lesson.confirmation_decided": {
+      "producer": "coaching",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/coaching-confirmation/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/coaching-confirmation/schema/payloads/coaching.lesson.confirmation_decided-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-17",
+          "notes": "Coaching-produced answer to Sales' lead.coach.confirmation.requested confirmation handshake per 2026-05-17-coaching-cadence-confirmation-event-position. Subject is confirmation_request_id. Sales consumes for cadence Stage 3b resolution; platform-warehouse ingests for confirmation latency, denial-rate, and re-engagement analytics."
+        }
+      ]
+    },
+    "lead.coach.confirmation.requested": {
+      "producer": "sales",
+      "consumers": [
+        "coaching",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/coaching-confirmation/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/coaching-confirmation/schema/payloads/lead.coach.confirmation.requested-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Sales-produced request that starts the Stage 3b coach-confirmation handshake per 2026-05-17-sales-cadence-stage-map-sales-side-commitments and 2026-05-17-coaching-cadence-confirmation-event-position. Subject is confirmation_request_id. Coaching consumes to decide confirm-or-deny without reading Sales state; platform-warehouse ingests for confirmation latency, denial-rate, and re-engagement analytics."
+        }
+      ]
+    },
+    "geography.market.upserted": {
+      "producer": "platform",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/platform-geography-snapshot/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/platform-geography-snapshot/schema/payloads/geography.market.upserted-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Platform-produced canonical Market snapshot event per platform-geography-snapshot v0.1.0 and 2026-05-16-platform-geography-snapshot-contract-position. Emitted on Market mint or canonical-field change when the row is not transitioning to archived. Sales consumes for a local geography fallback snapshot; platform-warehouse ingests for reference-data history."
+        }
+      ]
+    },
+    "geography.market.archived": {
+      "producer": "platform",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/platform-geography-snapshot/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/platform-geography-snapshot/schema/payloads/geography.market.archived-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Platform-produced canonical Market archive event per platform-geography-snapshot v0.1.0. Emitted when a Market transitions to archived so consumers can retire local snapshot rows without relying solely on daily reconciliation."
+        }
+      ]
+    },
+    "geography.service-area.upserted": {
+      "producer": "platform",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/platform-geography-snapshot/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/platform-geography-snapshot/schema/payloads/geography.service-area.upserted-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Platform-produced canonical Service Area snapshot event per platform-geography-snapshot v0.1.0 and ADR-0013. Emitted on Service Area mint or canonical-field change when the row is not transitioning to archived. Delivery is a reference-holder, not producer."
+        }
+      ]
+    },
+    "geography.service-area.archived": {
+      "producer": "platform",
+      "consumers": [
+        "sales",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/platform-geography-snapshot/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/platform-geography-snapshot/schema/payloads/geography.service-area.archived-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Platform-produced canonical Service Area archive event per platform-geography-snapshot v0.1.0. Emitted when a Service Area transitions to archived so consumers can retire local snapshot rows without relying solely on daily reconciliation."
+        }
+      ]
+    },
+    "role.assigned": {
+      "producer": "sales",
+      "consumers": [
+        "platform",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/identity/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/identity/schema/payloads/role.assigned-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-12",
+          "notes": "Emitted by a role-owning producer-domain when a Person gains a role-bearing relationship with one of that domain's entities. Closed enum of role values per contracts/identity/person-role-taxonomy.md: lead (sales), customer (revenue), student (delivery), coach (coaching), guardian (platform), operator (platform). Multiple domains produce; producer field on each envelope identifies which one. Platform consumes to maintain the person_role projection backing GET /api/identity/v1/person/<id>/roles. Sales is the v1 production producer (Lead → lead role); Revenue/Delivery/Coaching join additively as each domain wires its emit hooks. Guardian and operator roles are written in-process by Platform without going through the dispatcher (same Prisma transaction as the underlying guardian/member row write)."
+        }
+      ]
+    },
+    "role.retired": {
+      "producer": "sales",
+      "consumers": [
+        "platform",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/identity/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/identity/schema/payloads/role.retired-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-12",
+          "notes": "Emitted by a role-owning producer-domain when a Person's role-bearing relationship terminates (Lead reaches terminal stage, Coach moves to inactive, Participant deactivates, Guardian relationship terminated, Member row deleted). Idempotent at the projection: re-delivery for an already-retired row is a no-op. customer role is sticky — Revenue emits role.retired only for compliance scenarios with reason='compliance_purge'. Sales is the v1 production producer; other domains join additively per the same rollout schedule as role.assigned."
+        }
+      ]
+    },
     "customer.handoff": {
       "producer": "revenue",
       "consumers": [
@@ -155,7 +317,7 @@
           "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.reserved-v1.json",
           "status": "active",
           "registered_at": "2026-05-02",
-          "notes": "Emitted at scheduling per §9.2. Coaching subscribes per coach-availability §4.3 and ADR-0008."
+          "notes": "Emitted when Revenue records a reservation claim per §9.2. lesson_id is optional on Sales-originated reservations until Delivery hold-create mints les_; Coaching uses Delivery hold-created for coach-specific booking facts when lesson_id is absent."
         }
       ]
     },
@@ -191,7 +353,7 @@
           "payload_schema": "contracts/credit-reservation-lock/schema/payloads/credit.locked-v1.json",
           "status": "active",
           "registered_at": "2026-05-02",
-          "notes": "Emitted on T-48h lock per §9.4. customer.handoff sidecar fires on first per Person."
+          "notes": "Emitted on T-24h lock per §9.4. customer.handoff sidecar fires on first per Person."
         }
       ]
     },
@@ -262,21 +424,41 @@
     },
     "lesson.scheduled": {
       "producer": "delivery",
-      "consumers": [],
-      "owning_contract": null,
+      "consumers": [
+        "coaching"
+      ],
+      "owning_contract": "contracts/lesson-lifecycle/README.md",
       "schema_versions": [
         {
           "version": 1,
-          "payload_schema": null,
+          "payload_schema": "contracts/lesson-lifecycle/schema/payloads/lesson.scheduled-v1.json",
           "status": "active",
           "registered_at": "2026-05-02",
-          "notes": "Emitted by Delivery when a lesson is scheduled. No cross-domain consumer registered yet; Coaching MAY subscribe in future for assigned-vs-eligible projection enrichment per coach-availability §4.2.1 producer-internal note."
+          "notes": "Emitted by Delivery when a lesson is scheduled. Coaching consumes scheduling identity for assigned-vs-eligible projection enrichment per coach-availability §4.2.1 producer-internal note. Payload is PII-free and carries lesson, participant, reservation, coach, site, service-area, lesson-type, ZIP, and window correlations."
+        }
+      ]
+    },
+    "lesson.rescheduled": {
+      "producer": "delivery",
+      "consumers": [
+        "sales"
+      ],
+      "owning_contract": "contracts/lesson-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lesson-lifecycle/schema/payloads/lesson.rescheduled-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Emitted by Delivery when a scheduled Lesson's window changes in place. Sales consumes to keep Lead.lessonDate and lesson-date-keyed cadence state aligned from new_window.start, per 2026-05-17-delivery-cadence-reschedule-event-position. Payload is PII-free and carries previous/new scheduling windows plus nullable lock, reservation, coach, site, service-area, and lesson-type correlations."
         }
       ]
     },
     "lesson.attended": {
       "producer": "delivery",
-      "consumers": [],
+      "consumers": [
+        "coaching"
+      ],
       "owning_contract": null,
       "schema_versions": [
         {
@@ -290,31 +472,34 @@
     },
     "lesson.cancelled": {
       "producer": "delivery",
-      "consumers": [],
-      "owning_contract": null,
+      "consumers": [
+        "coaching"
+      ],
+      "owning_contract": "contracts/lesson-lifecycle/README.md",
       "schema_versions": [
         {
           "version": 1,
-          "payload_schema": null,
+          "payload_schema": "contracts/lesson-lifecycle/schema/payloads/lesson.cancelled-v1.json",
           "status": "active",
-          "registered_at": "2026-05-02",
-          "notes": "Emitted on lesson cancellation by Delivery. The cancellation request to Revenue (which runs the lock state machine) is separate; that submission produces credit.released or credit.forfeited per §6 and §12.4 of the credit-reservation-lock contract, not this event."
+          "registered_at": "2026-05-14",
+          "notes": "Emitted on lesson cancellation by Delivery. Carries lesson_id, cancellation_reason (flexible string), and cancelled_at. Deliberately no credit_reservation_id field: the credit cancellation path (credit.released or credit.forfeited) is a separate Revenue-produced event. No cross-domain consumers at v1; Revenue's Lesson Completion Job uses lesson.delivered, not this event. v2 additive candidate if a real consumer need surfaces."
         }
       ]
     },
     "lesson.delivered": {
       "producer": "delivery",
       "consumers": [
-        "revenue"
+        "revenue",
+        "coaching"
       ],
-      "owning_contract": null,
+      "owning_contract": "contracts/lesson-lifecycle/README.md",
       "schema_versions": [
         {
           "version": 1,
-          "payload_schema": null,
+          "payload_schema": "contracts/lesson-lifecycle/schema/payloads/lesson.delivered-v1.json",
           "status": "active",
-          "registered_at": "2026-05-02",
-          "notes": "Emitted post-delivery, triggers Revenue's Lesson Completion Job per §10 of credit-reservation-lock."
+          "registered_at": "2026-05-14",
+          "notes": "Emitted post-delivery by Delivery; triggers Revenue's Lesson Completion Job per credit-reservation-lock §10. Payload: lesson_id (required), credit_reservation_id (optional, present for reserved lessons), delivered_at (required). Revenue keys on credit_reservation_id when present, falls back to lesson_id lookup otherwise."
         }
       ]
     },
@@ -327,16 +512,53 @@
       "schema_versions": [
         {
           "version": 1,
-          "payload_schema": null,
+          "payload_schema": "contracts/coach-availability/schema/payloads/coach.assigned-v1.json",
           "status": "active",
           "registered_at": "2026-05-02",
-          "notes": "Single-writer per ADR-0008. Coaching consumes for the assigned-vs-eligible projection enrichment per coach-availability §4.3 prose."
+          "notes": "Single-writer per ADR-0008. Coaching consumes for the assigned-vs-eligible projection enrichment per coach-availability §4.3 prose. Payload is PII-free and carries lesson, previous coach, new coach, participant, site, service-area, lesson-type, window, and assigned_at."
+        }
+      ]
+    },
+    "delivery.lesson-hold.created": {
+      "producer": "delivery",
+      "consumers": [
+        "sales",
+        "coaching",
+        "revenue"
+      ],
+      "owning_contract": "contracts/sales-scheduling-surface/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/sales-scheduling-surface/schema/payloads/delivery.lesson-hold.created-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-19",
+          "notes": "Emitted by Delivery when the sales-scheduling-surface hold-create transaction inserts the Lesson row and advances the Delivery reservation lock to held. Payload carries scheduling-side facts only, including optional atomic-multi-create offer correlations."
+        }
+      ]
+    },
+    "delivery.lesson-hold.cancelled": {
+      "producer": "delivery",
+      "consumers": [
+        "sales",
+        "coaching",
+        "revenue"
+      ],
+      "owning_contract": "contracts/sales-scheduling-surface/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/sales-scheduling-surface/schema/payloads/delivery.lesson-hold.cancelled-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-19",
+          "notes": "Emitted by Delivery when the sales-scheduling-surface hold-cancel transaction cancels the Lesson row and advances the Delivery reservation lock to released. Revenue-owned refund and credit events remain on Revenue surfaces."
         }
       ]
     },
     "lead.created": {
       "producer": "sales",
       "consumers": [
+        "growth",
         "platform-warehouse"
       ],
       "owning_contract": "contracts/lead-lifecycle/README.md",
@@ -346,13 +568,14 @@
           "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.created-v1.json",
           "status": "active",
           "registered_at": "2026-05-14",
-          "notes": "Emitted by Sales when a new Lead opens per lead-lifecycle §4.1. Two opening cases (from intake.captured with null person_id, or from intake.matched with person_id populated) plus reactivations carrying reactivated_from. Producer-transactional emit per ADR-0009; same Prisma transaction as the Lead row creation."
+          "notes": "Emitted by Sales when a new Lead opens per lead-lifecycle §4.1. Two opening cases (from intake.captured with null person_id, or from intake.matched with person_id populated) plus reactivations carrying reactivated_from. Producer-transactional emit per ADR-0009; same Prisma transaction as the Lead row creation. Growth consumer (added 2026-05-12) populates growth.lead_intake_correlation by resolving originating_intake_event_id to a form_submission_id via Growth's local dispatcher_event table."
         }
       ]
     },
     "lead.stage.changed": {
       "producer": "sales",
       "consumers": [
+        "growth",
         "platform-warehouse"
       ],
       "owning_contract": "contracts/lead-lifecycle/README.md",
@@ -362,13 +585,14 @@
           "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.stage.changed-v1.json",
           "status": "active",
           "registered_at": "2026-05-14",
-          "notes": "Broad state-transition event per lead-lifecycle §4.2. transition_reason enum (operator_action | cadence_runtime | inbound_event) identifies what drove the move. May co-fire with lead.reached, lead.callback.scheduled, or lead.attempt.exhausted when both apply. Stage values flexible string at v1.0.0; v1.1 candidate to tighten to a closed enum."
+          "notes": "Broad state-transition event per lead-lifecycle §4.2. transition_reason enum (operator_action | cadence_runtime | inbound_event) identifies what drove the move. May co-fire with lead.reached, lead.callback.scheduled, or lead.attempt.exhausted when both apply. Stage values flexible string at v1.0.0; v1.1 candidate to tighten to a closed enum. Growth consumer (added 2026-05-12) upserts growth.qualified_intake on transitions to a qualifying to_stage (initially 'qualified'), sourcing the form_submission_id via lead_intake_correlation."
         }
       ]
     },
     "lead.reached": {
       "producer": "sales",
       "consumers": [
+        "growth",
         "platform-warehouse"
       ],
       "owning_contract": "contracts/lead-lifecycle/README.md",
@@ -378,7 +602,7 @@
           "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.reached-v1.json",
           "status": "active",
           "registered_at": "2026-05-14",
-          "notes": "Successful reach event per lead-lifecycle §4.3. Voicemail, busy, no-answer, disconnected do NOT fire this event; only real conversations. attempt_number 1-4 per the cadence cap. outcome flexible string at v1.0.0; v1.1 candidate to tighten."
+          "notes": "Successful reach event per lead-lifecycle §4.3. Voicemail, busy, no-answer, disconnected do NOT fire this event; only real conversations. attempt_number 1-4 per the cadence cap. outcome flexible string at v1.0.0; v1.1 candidate to tighten. Growth consumer (added 2026-05-12) upserts growth.qualified_intake when outcome='qualified', sourcing the form_submission_id via lead_intake_correlation."
         }
       ]
     },
@@ -414,6 +638,95 @@
         }
       ]
     },
+    "lead.qualified": {
+      "producer": "sales",
+      "consumers": [
+        "growth",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.qualified-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-17",
+          "notes": "Qualification event per lead-lifecycle §4.6 (v1.1.0 amendment). Carries confirmed organization_id, market_id, and org_market_id — the authoritative (org, market) pair that closes Growth's provisional → confirmed attribution loop per ADR-0019. Growth MUST consume to update growth.qualified_intake. Sales MUST confirm org/market with the rep at qualification time; must not infer from campaign metadata. qualification_signal is a closed enum at v1: connected | replied | inbound_request."
+        }
+      ]
+    },
+    "lead.handoff.context.recorded": {
+      "producer": "sales",
+      "consumers": [
+        "delivery",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/lead.handoff.context.recorded-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-19",
+          "notes": "Sales-produced curated handoff-context event per lead-lifecycle §4.7 and the 2026-05-19 platform/sales/delivery handoff-context thread. Delivery consumes to attach Sales-owned relationship-start context to customer tracking without expanding Revenue's customer.handoff payload. Platform-warehouse ingests for handoff-timeliness, context-coverage, and repeat-question analytics. Payload is curated and excludes raw comms content, contact details, Guardian facts, DOB, payment details, opt-out truth, and internal audit noise."
+        }
+      ]
+    },
+    "sales.lead.onboarded": {
+      "producer": "sales",
+      "consumers": [
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/lead-lifecycle/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/lead-lifecycle/schema/payloads/sales.lead.onboarded-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-18",
+          "notes": "Sales-produced Stage 4 entry signal per 2026-05-17-sales-cadence-stage-map-sales-side-commitments. v1.1 candidate under lead-lifecycle. Emitted from the close-orchestration success path alongside Lead.lessonDate persistence in recordCloseLessonBooked. Platform-warehouse consumes for Stage 4 payment-to-lesson funnel analytics."
+        }
+      ]
+    },
+    "order.created": {
+      "producer": "revenue",
+      "consumers": [
+        "revenue",
+        "sales",
+        "growth",
+        "delivery",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/order-flow/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/order-flow/schema/payloads/order.created-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Emitted by Revenue at the writeback transaction commit when an Order row first lands in the canonical Postgres store. Producer-transactional guarantee per ADR-0009."
+        }
+      ]
+    },
+    "order.updated": {
+      "producer": "revenue",
+      "consumers": [
+        "revenue",
+        "sales",
+        "delivery",
+        "platform-warehouse"
+      ],
+      "owning_contract": "contracts/order-flow/README.md",
+      "schema_versions": [
+        {
+          "version": 1,
+          "payload_schema": "contracts/order-flow/schema/payloads/order.updated-v1.json",
+          "status": "active",
+          "registered_at": "2026-05-14",
+          "notes": "Emitted by Revenue when an Order's load-bearing canonical fields change: status, amount_paid_cents, amount_total_cents, or cancelled_at. Free-text and operator-internal metadata edits do not emit."
+        }
+      ]
+    },
     "payment.received": {
       "producer": "revenue",
       "consumers": [