@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/lead-lifecycle/schema/payloads/lead.handoff.context.recorded-v1.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.handoff.context.recorded-v1.json",
+  "title": "lead.handoff.context.recorded payload v1",
+  "description": "Payload for the lead.handoff.context.recorded event_type per contracts/lead-lifecycle/README.md §4.7. Emitted by Sales when close orchestration has a durable Sales-owned handoff-context snapshot for Delivery. The payload is curated relationship-start context only. It MUST NOT carry raw Sales note dumps, raw SMS bodies, call transcripts, phone numbers, email addresses, Guardian relationship facts, DOB, payment details, opt-out truth, or internal audit noise. Revenue's customer.handoff remains the first-lock handoff authority; this event carries Sales-owned context beside it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "person_id",
+    "organization_id",
+    "communication_preferences",
+    "recorded_by",
+    "recorded_at"
+  ],
+  "anyOf": [
+    {
+      "required": ["first_lesson_id", "credit_reservation_id"],
+      "properties": {
+        "first_lesson_id": { "type": "string" },
+        "credit_reservation_id": { "type": "string" }
+      }
+    },
+    {
+      "required": ["originating_offer_id"],
+      "properties": {
+        "originating_offer_id": { "type": "string", "minLength": 1 }
+      }
+    }
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Sales Lead whose close-orchestration context is being handed to Delivery. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The canonical Person the Lead is attached to. Delivery keys customer tracking by Person after customer.handoff arrives.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "organization_id": {
+      "type": "string",
+      "description": "The Organization for the close orchestration. Sales populates this from the close-orchestration request or qualification context; it is payload-required so Delivery can org-scope pending context before customer.handoff attaches."
+    },
+    "first_lesson_id": {
+      "type": ["string", "null"],
+      "description": "The first Delivery lesson correlated to the handoff context for single-lesson closes. les_<UUID v7 canonical>. Null or omitted for composite-offer contexts where the offer-level correlation is the stable v1 key.",
+      "pattern": "^les_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "credit_reservation_id": {
+      "type": ["string", "null"],
+      "description": "The Revenue credit reservation correlated to the handoff context for single-lesson closes. crr_<UUID v7 canonical>. Null or omitted for composite-offer contexts where the offer-level correlation is the stable v1 key.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "originating_offer_id": {
+      "type": ["string", "null"],
+      "description": "Optional Sales composite-offer correlation id. Present when the handoff context is tied to a package or composite close rather than one single lesson/reservation pair."
+    },
+    "lead_summary": {
+      "type": ["string", "null"],
+      "description": "Curated relationship-start summary from operator-authored Sales context and stable Lead or intake facts. This is not an automatic concatenation of all Sales notes and MUST NOT include raw comms bodies, contact details, Guardian facts, DOB, payment details, opt-out truth, or internal audit noise.",
+      "maxLength": 1000
+    },
+    "scheduling_notes": {
+      "type": ["string", "null"],
+      "description": "Reusable relationship-start scheduling constraints or context that should follow the customer across Delivery surfaces. Per-lesson operational notes stay on the sales-scheduling-surface hold-create or atomic-multi-create item notes fields.",
+      "maxLength": 1000
+    },
+    "communication_preferences": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["preferred_channel"],
+      "description": "Preference hints only. This object does not carry contact addresses, consent/opt-out truth, Guardian routing truth, or authorization to message a minor directly.",
+      "properties": {
+        "preferred_channel": {
+          "type": "string",
+          "enum": ["sms", "voice_call", "email", "unknown"],
+          "description": "Operator-captured channel preference. 'unknown' means no preference was captured. This is a preference hint, not consent or routing authority."
+        },
+        "best_time_window": {
+          "type": ["string", "null"],
+          "description": "Optional human-readable preferred contact or lesson-planning time window. Example: 'weekday evenings after 5pm'.",
+          "maxLength": 120
+        },
+        "language_preference": {
+          "type": ["string", "null"],
+          "description": "Optional language preference when Sales has one durably captured. BCP 47 tag preferred when available; otherwise a known internal value.",
+          "maxLength": 64
+        },
+        "operator_notes": {
+          "type": ["string", "null"],
+          "description": "Optional short preference-context annotation. Must follow the same PII exclusions as lead_summary.",
+          "maxLength": 500
+        }
+      }
+    },
+    "recorded_by": {
+      "type": "string",
+      "description": "The Sales operator actor id that recorded the handoff-context snapshot, or 'system' for future automated snapshots."
+    },
+    "recorded_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Sales commit time for the handoff-context snapshot. UTC."
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/lead.qualified-v1.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/lead.qualified-v1.json",
+  "title": "lead.qualified payload v1",
+  "description": "Payload for the lead.qualified event_type per contracts/lead-lifecycle/README.md §4.6. Emitted by Sales when a sales rep marks a Lead as qualified — meaning the Person has been reached, expressed intent, and is ready for scheduling handoff to Delivery. Producer SHALL emit inside the same Prisma transaction that transitions the Lead's qualification state. The confirmed organization_id and market_id carried on this event are the authoritative org/market pair for Growth attribution — they close the provisional → confirmed loop and supersede any provisional market inference Growth made from campaign metadata.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "organization_id",
+    "market_id",
+    "org_market_id",
+    "qualification_signal",
+    "qualified_at"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Lead being qualified. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "organization_id": {
+      "type": "string",
+      "description": "The Organization the Person is being qualified into. Authoritative — confirmed by the sales rep at qualification time, not inferred from campaign metadata. Platform canonical Organization.id."
+    },
+    "market_id": {
+      "type": "string",
+      "description": "The CanonicalMarket the Person is being qualified for. Authoritative — confirmed by the sales rep at qualification time, not inferred from zip or campaign. Platform canonical CanonicalMarket.id. Together with organization_id, resolves to an OrgMarket row."
+    },
+    "org_market_id": {
+      "type": "string",
+      "description": "The OrgMarket slug — '{org.slug}-{market.slug}', e.g. 'sguild-swim-dallas'. Denormalized for consumers that need the mart grain key without a join. Must match the OrgMarket row identified by (organization_id, market_id). Platform canonical OrgMarket.slug per ADR-0019."
+    },
+    "qualification_signal": {
+      "type": "string",
+      "enum": ["connected", "replied", "inbound_request"],
+      "description": "What signal drove qualification. 'connected' = sales rep had a live call and the Person expressed intent. 'replied' = Person replied to an outbound message and expressed intent. 'inbound_request' = Person self-initiated contact (e.g., booked a callback, filled a follow-up form)."
+    },
+    "qualified_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the qualification was recorded. Sales' wall-clock at the moment the rep marked the Lead qualified. UTC."
+    },
+    "operator_id": {
+      "type": ["string", "null"],
+      "description": "The sales rep who qualified the Lead. Sales-internal id format at v1. Null only for system-driven qualification paths (rare)."
+    },
+    "requalification_count": {
+      "type": ["integer", "null"],
+      "description": "How many times this Lead has been qualified (including this event). 1 for first qualification; >1 for re-qualification after a prior disqualification or re-engagement. Null if Sales has not yet implemented requalification tracking. Growth uses this to bump growth.qualified_intake.reQualifyCount.",
+      "minimum": 1
+    }
+  }
+}

package/contracts/lead-lifecycle/schema/payloads/sales.lead.onboarded-v1.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lead-lifecycle/schema/payloads/sales.lead.onboarded-v1.json",
+  "title": "sales.lead.onboarded payload v1",
+  "description": "Payload for the sales.lead.onboarded event_type. Emitted by Sales on Stage 4 entry after close-orchestration succeeds and Sales persists Lead.lessonDate from the lesson hold window. This is the dispatcher notification described in the cadence stage-map coordination memo, produced inside the same logical close path as the Lead onboarded transition.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lead_id",
+    "person_id",
+    "stage",
+    "substage",
+    "lesson_id",
+    "lesson_date",
+    "lesson_window",
+    "onboarded_at"
+  ],
+  "properties": {
+    "lead_id": {
+      "type": "string",
+      "description": "The Lead entering Stage 4. lead_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lead_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "person_id": {
+      "type": "string",
+      "description": "The canonical Person attached to the Lead. Stage 4 entry requires an identity-matched Lead. per_<UUID v7 canonical> per ADR-0003.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "stage": {
+      "type": "string",
+      "const": "onboarded",
+      "description": "The Sales Lead stage after Stage 4 entry."
+    },
+    "substage": {
+      "type": "string",
+      "description": "The Sales Lead substage after Stage 4 entry. Expected initial value is 'reserved' for the close-orchestration success path; kept flexible so Sales can extend Stage 4 operator vocabulary without a breaking payload change."
+    },
+    "lesson_id": {
+      "type": "string",
+      "description": "The Delivery Lesson id returned by close-orchestration hold-create.",
+      "pattern": "^les_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "lesson_date": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The lesson start timestamp Sales persists to Lead.lessonDate. Derived from lesson_window.start. UTC."
+    },
+    "lesson_window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["start", "end"],
+      "description": "The scheduled lesson window returned by close-orchestration.",
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Lesson window start. Must match lesson_date. UTC."
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Lesson window end. UTC."
+        }
+      }
+    },
+    "reservation_id": {
+      "type": ["string", "null"],
+      "description": "Sales-visible reservation id returned by the Revenue reservation call, when available."
+    },
+    "credit_reservation_id": {
+      "type": ["string", "null"],
+      "description": "Revenue credit reservation id associated with the Stage 4 entry, when available."
+    },
+    "reservation_lock_id": {
+      "type": ["string", "null"],
+      "description": "Reservation lock id returned by Delivery hold-create, when available."
+    },
+    "order_id": {
+      "type": ["string", "null"],
+      "description": "Revenue Order id associated with the Stage 4 entry, when known. Null when the close-orchestration response has not yet exposed an order correlation."
+    },
+    "organization_id": {
+      "type": ["string", "null"],
+      "description": "Organization id returned by Delivery hold-create, when available."
+    },
+    "service_area_id": {
+      "type": ["string", "null"],
+      "description": "Service Area id used for the reserved lesson, when available."
+    },
+    "lesson_type_id": {
+      "type": ["string", "null"],
+      "description": "Lesson Type id used for the reserved lesson, when available."
+    },
+    "coach_id": {
+      "type": ["string", "null"],
+      "description": "Coach id assigned to the reserved lesson, when available."
+    },
+    "lesson_site_id": {
+      "type": ["string", "null"],
+      "description": "Lesson site id returned by Delivery hold-create, when available."
+    },
+    "participant_id": {
+      "type": ["string", "null"],
+      "description": "Delivery participant id attached to the reserved lesson, when available."
+    },
+    "dispatcher_correlation_id": {
+      "type": ["string", "null"],
+      "description": "Sales-generated correlation id for downstream dispatcher-complete handling, when that producer edge is active."
+    },
+    "operator_id": {
+      "type": ["string", "null"],
+      "description": "Sales operator who completed close-orchestration and moved the Lead into Stage 4. Sales-internal id format at v1."
+    },
+    "onboarded_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Sales recorded Stage 4 entry. Sales wall-clock at commit. UTC."
+    }
+  }
+}

package/contracts/lesson-lifecycle/README.md

@@ -0,0 +1,118 @@
+# Lesson Lifecycle
+
+**Status:** v1.1.0
+**Date:** 2026-05-18
+**Owner:** delivery (lessons)
+**Consumers:** revenue (Lesson Completion Job, consumes `lesson.delivered`), sales (cadence, consumes `lesson.rescheduled`)
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template; `les_` prefix), ADR-0005 (event envelope), ADR-0006 (credit reservation lock state machine), ADR-0009 (dispatcher transport)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`), Credit Reservation Lock Contract (`../credit-reservation-lock/README.md`)
+**Sub-specs (authoritative):** `schema/payloads/lesson.delivered-v1.json`, `schema/payloads/lesson.cancelled-v1.json`, `schema/payloads/lesson.rescheduled-v1.json`
+**Validations:** none yet
+
+## 1. Purpose and scope
+
+This contract specifies the Lesson lifecycle event family produced by Delivery as a lesson moves through scheduling, rescheduling, attendance, and a terminal outcome. Five `lesson.*` event types are registered in `coordination/contracts/event-types-registry.json`, all produced by Delivery: `lesson.scheduled`, `lesson.rescheduled`, `lesson.attended`, `lesson.delivered`, and `lesson.cancelled`. Each is named in `coordination/domains/delivery.md` §"Primary interfaces" as a Delivery-produced event.
+
+At v1.1.0 this contract pins the payload shapes for `lesson.delivered`, `lesson.cancelled`, and `lesson.rescheduled`. `lesson.delivered` and `lesson.cancelled` are emitted by the Delivery lesson outcome write path (see `delivery/docs/outcome-write-side-postgres-design.md`). `lesson.rescheduled` is emitted by the Delivery reschedule write path when a scheduled lesson's window changes. `lesson.scheduled` and `lesson.attended` are documented here as part of the family in §4 but do not yet have payload schemas; they acquire schemas when a binding consumer registers, per §9.
+
+Out of scope: the Lesson record itself (Delivery-internal, lives in the Delivery repo's Prisma model), the credit reservation lock state machine (that is the Credit Reservation Lock Contract, Revenue-owned; `lesson.delivered` triggers Revenue's Lesson Completion Job but this contract does not specify that job), attendance reconciliation internals (Delivery-internal), the dispatcher transport (ADR-0009 and the dispatcher SDK), and the cancellation submission to Revenue's lock state machine (a separate call, see §4.4 and §3).
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted per RFC 2119.
+
+## 3. Terminology
+
+- **Lesson.** A Delivery-owned scheduling fact per `coordination/domains/delivery.md`. Identified by `les_<UUID v7 canonical>` per ADR-0002.
+- **Outcome.** A lesson's terminal status. Delivery's lesson outcome write path moves a lesson to one of three terminal statuses: `Completed`, `Canceled`, or `No-Show`. `lesson.delivered` fires on `Completed`; `lesson.cancelled` fires on `Canceled`. No-Show does not have a registered lifecycle event at v1.0.0 (the credit consequence of a no-show is carried by Revenue's `credit.forfeited`, not by a `lesson.*` event).
+- **The credit path is separate.** A lesson outcome and the credit consequence of that outcome are distinct. `lesson.delivered` is the lifecycle signal that *triggers* Revenue's Lesson Completion Job; the Job's own state transition (`locked` to `consumed`) and ledger postings are Revenue-owned and surface as `credit.consumed`, not as a `lesson.*` event. `lesson.cancelled` is purely a lifecycle notification: the cancellation submission to Revenue's lock state machine is a separate call that produces `credit.released` or `credit.forfeited` per Credit Reservation Lock Contract §6 and §12.4. A consumer wanting the credit truth subscribes to the `credit.*` events, not to these.
+
+## 4. Event types
+
+### 4.1 lesson.scheduled
+
+Fires when a lesson is scheduled. Producer: Delivery. No payload schema at v1.0.0; no cross-domain consumer is registered. Coaching MAY subscribe in a future version for assigned-versus-eligible projection enrichment per the coach-availability contract §4.2.1 producer-internal note. The payload schema lands when a binding consumer registers, per §9.
+
+### 4.2 lesson.attended
+
+Fires on attendance reconciliation. Producer: Delivery. No payload schema at v1.0.0; no cross-domain consumer is registered. The payload schema lands when a binding consumer registers, per §9.
+
+### 4.3 lesson.delivered
+
+Fires when a lesson reaches the `Completed` terminal state. The lifecycle signal that triggers Revenue's Lesson Completion Job.
+
+Producer SHALL: emit exactly once per lesson delivery, inside the same Prisma transaction that writes the lesson's terminal status, per the producer-transactional-guarantee shape in ADR-0009.
+
+Consumer: Revenue's Lesson Completion Job subscribes. On `lesson.delivered` it transitions the lesson's credit reservation from `locked` to `consumed` and posts the Adjustment (reason Credits Consumed) and Lesson Debit ledger entries, per Credit Reservation Lock Contract §10. The Job SHALL be idempotent per that contract; `credit_reservation_id`, when present on the payload, is the idempotency-key input.
+
+Payload schema: `schema/payloads/lesson.delivered-v1.json`. Fields: `lesson_id` (required), `credit_reservation_id` (optional; present for reserved lessons, omitted for lessons delivered without an active reservation), `delivered_at` (required).
+
+### 4.4 lesson.cancelled
+
+Fires when a lesson reaches the `Canceled` terminal state. A lifecycle notification only.
+
+Producer SHALL: emit exactly once per lesson cancellation, inside the same Prisma transaction that writes the lesson's terminal status, per ADR-0009.
+
+This event is deliberately decoupled from the credit path per §3. The cancellation submission to Revenue's lock state machine is a separate call that produces `credit.released` or `credit.forfeited` per Credit Reservation Lock Contract §6 and §12.4. `lesson.cancelled` does not carry a `credit_reservation_id` at v1.0.0 so that consumers are not invited to couple the lifecycle signal to the credit truth; adding it as an optional correlation field is a v2 candidate per §9 if a consumer need surfaces.
+
+No cross-domain consumer is registered at v1.0.0. Subscribers MAY warehouse-load for lifecycle reporting.
+
+Payload schema: `schema/payloads/lesson.cancelled-v1.json`. Fields: `lesson_id` (required), `cancellation_reason` (required, flexible string), `cancelled_at` (required).
+
+### 4.5 lesson.rescheduled
+
+Fires when a scheduled lesson's date or time window changes in place. The lifecycle signal lets Sales keep lesson-date-keyed cadence state aligned without polling Delivery's current Lesson snapshot and guessing that a reschedule happened.
+
+Producer SHALL: emit exactly once per successful window-changing reschedule, inside the same Prisma transaction that writes the new Lesson `startAt` and `endAt`, per ADR-0009.
+
+Consumer: Sales cadence consumes day one. On `lesson.rescheduled`, Sales updates its Lead lesson-date projection from `new_window.start` for the Lead it already correlates to the Lesson. The event does not carry `lead_id`, Sales substage, or Sales cadence state; Sales owns that correlation.
+
+Payload schema: `schema/payloads/lesson.rescheduled-v1.json`. Fields: `organization_id` (required), `lesson_id` (required), `reservation_lock_id` (required nullable), `reservation_id` (required nullable), `participant_id` (required nullable), `previous_window` (required), `new_window` (required), `previous_coach_id` (required nullable), `new_coach_id` (required nullable), `previous_lesson_site_id` (required nullable), `new_lesson_site_id` (required nullable), `service_area_id` (required nullable), `lesson_type_id` (required nullable), `reschedule_reason` (required nullable), `rescheduled_at` (required), and `rescheduled_by` (required nullable). Sales reads `new_window.start` as the updated lesson date.
+
+## 5. Versioning policy
+
+### 5.1 Semantic versioning
+
+Per-event-type payload schemas version independently of this contract document and of the event envelope, per the event envelope contract §8.2. The contract version below tracks the document and the set of pinned schemas.
+
+- **Patch** (1.0.0 to 1.0.1): editorial clarifications, typo fixes. No behavioral change.
+- **Minor** (1.x.y to 1.x+1.0): additive changes. A new optional payload field (a new payload `schema_version`), a new event type entering the family, a payload schema pinned for a previously-unpinned event type. Consumers on older minors continue to work.
+- **Major** (1.x.y to 2.0.0): breaking changes. Field removal, type change, narrowing a flexible string to an enum that drops in-use values, breaking payload changes.
+
+### 5.2 Deprecation policy
+
+On major-version publication, the previous major enters a two-week deprecation window per the org contract-currency standard. Consumers running against deprecated versions after the window contribute to drift.
+
+### 5.3 Additive discipline within a major
+
+New payload fields MUST default to null or a backwards-compatible value and land as a new payload `schema_version`. New `cancellation_reason` values are additive by construction (the field is a flexible string). Consumers MUST treat unknown enum-like values as safe-to-ignore.
+
+## 6. Consumer responsibilities
+
+Consumers SHALL dedup on the envelope `event_id`; the dispatcher SDK provides the dedup primitive but the at-most-once promise is the consumer's to honor. Consumers SHALL reference Delivery entities by canonical ID and SHALL NOT cache lesson state derived from these events beyond what the event asserts (these are lifecycle signals, not a lesson read API). Consumers SHALL treat unknown `cancellation_reason` values as safe-to-ignore per §5.3.
+
+For `lesson.delivered` specifically: Revenue's Lesson Completion Job SHALL be idempotent per Credit Reservation Lock Contract §10, since the dispatcher's at-least-once delivery plus retry may deliver the same `lesson.delivered` more than once.
+
+## 7. Producer responsibilities (Delivery)
+
+Delivery SHALL emit exactly one `lesson.delivered` per lesson reaching `Completed`, exactly one `lesson.cancelled` per lesson reaching `Canceled`, and exactly one `lesson.rescheduled` per successful window-changing reschedule, each inside the same Prisma transaction that writes the domain fact, per ADR-0009's producer-transactional-guarantee.
+
+Delivery SHALL emit canonical entity IDs on the payloads: `les_` for `lesson_id` and `crr_` for `credit_reservation_id`. Delivery resolves the `crr_` reservation id from its `reservation_lock` mirror at emit time; when the delivered lesson had no active reservation, Delivery SHALL omit `credit_reservation_id` rather than emit a placeholder.
+
+Delivery SHALL set `occurred_at` on the envelope to its wall-clock at the transaction commit and SHALL NOT backdate or postdate, per the event envelope contract §4.3. The payload's `delivered_at`, `cancelled_at`, or `rescheduled_at` carry the same instant.
+
+## 8. Security and privacy
+
+The pinned payloads do not carry PII. `lesson.delivered` carries canonical IDs (`les_`, `crr_`) and a timestamp. `lesson.cancelled` carries a canonical ID, a timestamp, and a `cancellation_reason` string drawn from an operational taxonomy that names no person. `lesson.rescheduled` carries Delivery and Revenue correlation IDs, before and after scheduling fields, an opaque reason, and an actor id. The envelope's `subject` and `actor` fields MAY carry a `per_` id per the event envelope contract; that is envelope-level PII handling and is out of scope for this contract.
+
+## 9. Future work
+
+- **`lesson.scheduled` and `lesson.attended` payload schemas.** Pinned when each acquires a binding cross-domain consumer, per the registry's per-event-type schema-on-demand discipline. Pinning either is a minor version bump per §5.1.
+- **`lesson.cancelled` v2 with `credit_reservation_id`.** If a consumer surfaces a need to correlate a cancellation to its reservation without a separate lookup, an optional `credit_reservation_id` lands as `lesson.cancelled` payload `schema_version` 2. Deliberately omitted at v1 per §4.4.
+- **`cancellation_reason` enum tightening.** If the cancellation reason taxonomy stabilizes, tightening the flexible string to a closed enum is a candidate; narrowing that drops in-use values is a major bump per §5.1.
+- **A `lesson.no_show` event.** No-Show is a lesson terminal outcome with no lifecycle event at v1.0.0. If a consumer needs the lifecycle signal distinct from Revenue's `credit.forfeited`, a `lesson.no_show` event type joins the family as a minor bump.
+
+## 10. Change log
+
+- **v1.1.0** (2026-05-18). Adds `lesson.rescheduled` to the Lesson lifecycle family, pins `schema/payloads/lesson.rescheduled-v1.json`, and registers Sales cadence as the day-one consumer. The event is emitted transactionally from Delivery's reschedule write path and carries previous/new scheduling windows so Sales does not infer reschedules from current-state polling. Authored by Delivery per `2026-05-17-delivery-cadence-reschedule-event-position`.
+- **v1.0.0** (2026-05-14). Initial contract. Documents the four-event Lesson lifecycle family; pins payload schemas for `lesson.delivered` and `lesson.cancelled` at payload `schema_version` 1. Authored by Delivery per the ownership confirmed on `2026-05-14-platform-dispatcher-producer-sdk-consumption`. Platform wires the registry `payload_schema` and `owning_contract` entries on notification per that memo.

package/contracts/lesson-lifecycle/schema/payloads/lesson.cancelled-v1.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lesson-lifecycle/schema/payloads/lesson.cancelled-v1.json",
+  "title": "lesson.cancelled payload v1",
+  "description": "Payload for the lesson.cancelled event_type per contracts/lesson-lifecycle/README.md §4.4. Emitted by Delivery when a lesson reaches the Canceled terminal state, inside the same Prisma transaction that writes the lesson's terminal status (ADR-0009 producer-transactional-guarantee). This is the lesson-lifecycle notification only. It is deliberately decoupled from the credit path: the cancellation submission to Revenue's lock state machine is a separate call that produces credit.released or credit.forfeited per credit-reservation-lock §6 and §12.4, not this event. No cross-domain consumer is registered at v1.0.0.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lesson_id",
+    "cancellation_reason",
+    "cancelled_at"
+  ],
+  "properties": {
+    "lesson_id": {
+      "type": "string",
+      "description": "The cancelled lesson. les_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^les_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "cancellation_reason": {
+      "type": "string",
+      "description": "Why the lesson was cancelled. Flexible string at v1.0.0; the Delivery-internal values in use are 'Client Canceled', 'Coach Canceled', 'Bad Weather', 'Access Issue', 'Scheduling Error', and 'Duplicate Lesson'. Carried as a string rather than a closed enum so Delivery can extend the reason taxonomy without a contract version bump; tightening to an enum is a v2 candidate per §9.",
+      "minLength": 1
+    },
+    "cancelled_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Delivery recorded the lesson as cancelled (the lesson's terminal-status write). UTC. Per the event envelope contract §4.3, producers MUST NOT backdate or postdate."
+    }
+  }
+}

package/contracts/lesson-lifecycle/schema/payloads/lesson.delivered-v1.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lesson-lifecycle/schema/payloads/lesson.delivered-v1.json",
+  "title": "lesson.delivered payload v1",
+  "description": "Payload for the lesson.delivered event_type per contracts/lesson-lifecycle/README.md §4.3. Emitted by Delivery when a lesson reaches the Completed terminal state, inside the same Prisma transaction that writes the lesson's terminal status (ADR-0009 producer-transactional-guarantee). Consumer: Revenue's Lesson Completion Job, which transitions the lesson's credit reservation from locked to consumed per credit-reservation-lock §10 and posts the Adjustment and Lesson Debit ledger entries.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lesson_id",
+    "delivered_at"
+  ],
+  "properties": {
+    "lesson_id": {
+      "type": "string",
+      "description": "The delivered lesson. les_<UUID v7 canonical> per ADR-0002. Revenue's Lesson Completion Job resolves the locked credit reservation from this when credit_reservation_id is absent.",
+      "pattern": "^les_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "credit_reservation_id": {
+      "type": "string",
+      "description": "The credit reservation tied to the delivered lesson, when one exists. crr_<UUID v7 canonical> per ADR-0002. Present for reserved lessons; omitted for lessons delivered without an active reservation (free trials, unreserved sessions). Revenue's Lesson Completion Job SHALL use it as the idempotency-key input per credit-reservation-lock §10 when present, and fall back to a lesson_id lookup when absent.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "delivered_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Delivery recorded the lesson as delivered (the lesson's terminal-status write). UTC. Per the event envelope contract §4.3, producers MUST NOT backdate or postdate."
+    }
+  }
+}

package/contracts/lesson-lifecycle/schema/payloads/lesson.rescheduled-v1.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/lesson-lifecycle/schema/payloads/lesson.rescheduled-v1.json",
+  "title": "lesson.rescheduled payload v1",
+  "description": "Payload for the lesson.rescheduled event_type per contracts/lesson-lifecycle/README.md section 4.5. Emitted by Delivery when a scheduled lesson's window changes, inside the same Prisma transaction that writes the new lesson window. Consumer: Sales cadence, which updates its lesson-date keyed follow-up state from new_window.start.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "organization_id",
+    "lesson_id",
+    "reservation_lock_id",
+    "reservation_id",
+    "participant_id",
+    "previous_window",
+    "new_window",
+    "previous_coach_id",
+    "new_coach_id",
+    "previous_lesson_site_id",
+    "new_lesson_site_id",
+    "service_area_id",
+    "lesson_type_id",
+    "reschedule_reason",
+    "rescheduled_at",
+    "rescheduled_by"
+  ],
+  "properties": {
+    "organization_id": {
+      "type": "string",
+      "description": "Delivery tenancy scope for the lesson.",
+      "minLength": 1
+    },
+    "lesson_id": {
+      "type": "string",
+      "description": "The rescheduled lesson. les_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^les_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "reservation_lock_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Delivery reservation-lock correlation when the lesson is lock-backed. lck_ is the canonical contract prefix; rlk_ is accepted for existing Delivery rows during prefix alignment.",
+      "pattern": "^(lck|rlk)_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "reservation_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Revenue credit reservation correlation when present. crr_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "participant_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Delivery Participant taking the lesson when known. par_<UUID v7 canonical> per ADR-0002; null only for legacy rows whose participant was not source-backed at migration time.",
+      "pattern": "^par_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "previous_window": {
+      "$ref": "#/$defs/window"
+    },
+    "new_window": {
+      "$ref": "#/$defs/window"
+    },
+    "previous_coach_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Coach assigned before the reschedule, when present. coa_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^coa_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "new_coach_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Coach assigned after the reschedule, when present. May equal previous_coach_id for time-only reschedules.",
+      "pattern": "^coa_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "previous_lesson_site_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Lesson site before the reschedule, when present. lsi_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lsi_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "new_lesson_site_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Lesson site after the reschedule, when present. May equal previous_lesson_site_id for time-only reschedules.",
+      "pattern": "^lsi_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "service_area_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Service area associated with the lesson when known. sva_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^sva_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "lesson_type_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Lesson type associated with the lesson when known. lty_<UUID v7 canonical> per ADR-0002.",
+      "pattern": "^lty_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "reschedule_reason": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Optional operational reason. Opaque to consumers.",
+      "minLength": 1
+    },
+    "rescheduled_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When Delivery recorded the reschedule. UTC. Per the event envelope contract, producers MUST NOT backdate or postdate."
+    },
+    "rescheduled_by": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Operator or system actor id responsible for the reschedule; null only when unavailable.",
+      "minLength": 1
+    }
+  },
+  "$defs": {
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "start",
+        "end"
+      ],
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}