@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/event-envelope/validation/event-vocabulary.md

@@ -0,0 +1,270 @@
+# Validation: Event envelope against the existing event-name vocabulary
+
+**Status:** Passed with one design clarification recommended (intake.captured subject)
+**Date:** 2026-04-25
+**Owner:** Platform
+**Validates:** `platform/contracts/event-envelope/README.md` v1.0.0
+
+## Purpose
+
+Confirm that every event_type already named in the Sguild architecture fits the v1.0.0 event envelope shape cleanly. Walk each event, identify producer, subject, actor, payload, and surface any case where the envelope is awkward or insufficient.
+
+## Vocabulary walked
+
+Twenty event types across four producers (Platform, Growth, Sales, Delivery, Revenue). Grouped by producer.
+
+## Platform identity service events (producer = `platform`)
+
+### `person.created`
+
+- Subject: `person_id` (the new Person)
+- Actor: `system:platform` for automated mint via `intake.captured`; `<person_id>` of an admin for manual entry
+- Payload: full nine-field canonical Person shape
+- Schema version: 1
+
+Fits envelope cleanly. The producer is unambiguously Platform's identity service, the subject is the canonical entity, and the payload matches the Identity Contract v1.0.0 person shape.
+
+### `person.updated`
+
+- Subject: `person_id`
+- Actor: `system:platform` for automated invariants (the daily `is_minor` job); `<person_id>` for admin or customer-driven updates
+- Payload: full nine-field current Person shape
+- Schema version: 1
+
+Fits cleanly. Same shape as `person.created`. Bumps `updated_at` on the Person record as part of producing the event.
+
+### `person.merged`
+
+- Subject: `canonical_person_id` (the surviving Person)
+- Actor: `system:platform` for auto-merges; `<person_id>` of the operator for manual merges
+- Payload: `old_person_id`, `canonical_person_id`, `reason_code` (enum), `promoted_fields[]`, `role_record_changes[]`
+- Schema version: 1
+
+Fits cleanly. Subject correctly points at the canonical Person rather than the merged-away one; consumers resolving stale references via `alias_of` use the subject as the new reference.
+
+## Growth events (producer = `growth`)
+
+### `intake.captured`
+
+- Subject: **see clarification below**
+- Actor: `system:growth` for automated form submissions; `<person_id>` of an operator for manual entry
+- Payload: `form_submission_id`, `source`, `campaign`, `utm_*`, `raw_email`, `raw_phone`, `raw_name`, `submitted_at`, `browser_metadata` (optional)
+- Schema version: 1
+
+**Design clarification recommended.** At the moment Growth captures an intake, the canonical `person_id` does not yet exist; Platform's identity service mints or matches the Person in response to this event. So when Growth emits `intake.captured`, the `subject` field has no canonical Person to point at yet. Three options:
+
+1. **Subject = `form_submission_id` (recommended).** Reserve a `fsm_<UUID v7 canonical>` prefix (extends ADR-0002's reserved prefix table) for form submissions. Growth emits `intake.captured` with `subject=fsm_*`. Platform receives, mints or matches the Person, and emits a separate `intake.matched` event whose subject is the new `person_id` and whose payload links back to the original `fsm_*` ID. Consumers that want to track an intake from capture to match join on `fsm_*` until the match event provides the `person_id`.
+
+2. **Subject = empty (omit).** Allowed by the envelope (subject is optional). Consumers that need to track the intake parse the payload's `form_submission_id`. Less self-describing but works.
+
+3. **Subject populated by Platform after match.** Violates envelope immutability (events should not mutate after emission). Reject.
+
+Recommendation is option 1 because it keeps the envelope subject self-describing throughout the intake lifecycle and avoids the subjectless event pattern. This requires a small additive change to the Identity Contract (new reserved prefix `fsm_`) and a new Platform-emitted event (`intake.matched`). Both are v1.x additive and do not require event-envelope-v1.0.0 contract changes.
+
+## Sales events (producer = `sales`)
+
+### `lead.qualified`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the sales rep who closed qualification
+- Payload: `lead_id`, `qualification_signal` (enum: `connected`, `replied`, `inbound_request`), `connected_at`
+- Schema version: 1
+
+Fits cleanly. Subject points at the human being qualified.
+
+### `lead.unreachable`
+
+- Subject: `person_id`
+- Actor: `system:sales` (automated determination after four attempts)
+- Payload: `lead_id`, `attempt_count` (always 4 at this point), `last_attempt_at`
+- Schema version: 1
+
+Fits cleanly.
+
+### `lead.disqualified`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the sales rep who decided
+- Payload: `lead_id`, `disqualification_reason` (free text or enum), `disqualified_at`
+- Schema version: 1
+
+Fits cleanly.
+
+## Delivery events (producer = `delivery`)
+
+### `lesson.scheduled`
+
+- Subject: `lesson_id`
+- Actor: `<person_id>` of the scheduler (sales or ops staff), or `<person_id>` of the customer for self-service scheduling
+- Payload: `lesson_id`, `participant_person_ids[]`, `coach_person_id`, `organization_id`, `lesson_starts_at`, `lesson_duration_minutes`, `offering_id`, `credit_account_id` (the buyer's account, used for the reservation), `credits_required` (N)
+- Schema version: 1
+
+Fits cleanly. **Worth noting:** the subject is `lesson_id` (the lesson is the entity the event is about), not a participant `person_id`. For group lessons with multiple participants, all participant IDs ride in the payload. Subscribers who care about a specific person's lessons filter on `participant_person_ids[]` rather than on `subject`. This is correct: events are about entities, and a multi-participant lesson is one entity.
+
+### `lesson.delivered`
+
+- Subject: `lesson_id`
+- Actor: `<person_id>` of the coach who marked delivery
+- Payload: `lesson_id`, `attendance[]` (one entry per participant with status `present`/`absent`), `delivered_at`
+- Schema version: 1
+
+Fits cleanly. Triggers Revenue's Lesson Completion Job for any reservation tied to this lesson.
+
+### `lesson.cancelled`
+
+- Subject: `lesson_id`
+- Actor: depends on initiator (`<person_id>` for human; `system:delivery` for automated)
+- Payload: `lesson_id`, `initiator` (enum: `customer`, `admin`, `coach`, `system_weather`, `system_logistics`, `system_unpaid`, `system_other`), `reason_code`, `reason_note` (optional), `cancelled_at`
+- Schema version: 1
+
+Fits cleanly. Triggers Revenue's cancellation policy lookup; result drives the credit reservation lock state machine to `released` or `forfeited`.
+
+## Revenue events (producer = `revenue`)
+
+### `credit.purchased`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the customer (who initiated the purchase)
+- Payload: `credit_account_id`, `person_id`, `purchased_credits` (N), `order_id`, `purchased_at`
+- Schema version: 1
+
+Fits cleanly. Subscribers (Sales, Growth, Delivery) reference `person_id` for their own role-record updates.
+
+### `credit.reserved`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the scheduler or `system:revenue` for auto-rebooks after Sguild-side cancel
+- Payload: `credit_reservation_id`, `credit_account_id`, `person_id`, `lesson_id`, `organization_id`, `reserved_credits` (N), `reserved_at`, `lesson_starts_at`
+- Schema version: 1
+
+Fits cleanly. Multiple useful IDs in payload (`credit_reservation_id`, `credit_account_id`, `lesson_id`) for downstream joins; subject stays the canonical Person.
+
+### `credit.funded`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the customer for invoice-paid funding; `system:revenue` for credits-available auto-funding at scheduling
+- Payload: `credit_reservation_id`, `funding_source` (enum: `credits_available`, `invoice_paid`), `funded_at`
+- Schema version: 1
+
+Fits cleanly. Sales subscribes to mark Lead pipeline state to "funded" without needing to wait for lock.
+
+### `credit.locked`
+
+- Subject: `person_id`
+- Actor: `system:revenue` (Reservation Job at T-24h)
+- Payload: `credit_reservation_id`, `lesson_id`, `person_id`, `locked_credits` (N), `locked_at`
+- Schema version: 1
+
+Fits cleanly. The first emission per Person fires `customer.handoff` as a sidecar.
+
+### `credit.consumed`
+
+- Subject: `person_id`
+- Actor: `system:revenue` (Lesson Completion Job)
+- Payload: `credit_reservation_id`, `lesson_id`, `consumed_credits` (N), `consumed_at`
+- Schema version: 1
+
+Fits cleanly.
+
+### `credit.released`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the cancelling human or `system:revenue` for system_unpaid auto-cancel
+- Payload: `credit_reservation_id`, `credit_account_id`, `released_credits` (N), `initiator` (enum), `reversal_reason` (enum: `Credits Released`, `Administrative Void`), `reason_note` (optional), `cancelled_at`
+- Schema version: 1
+
+Fits cleanly. Initiator and reversal_reason enums give consumers enough categorical detail to drive their own logic without re-deriving from policy.
+
+### `credit.forfeited`
+
+- Subject: `person_id`
+- Actor: `system:revenue` (Forfeit Job)
+- Payload: `credit_reservation_id`, `lesson_id`, `forfeited_credits` (N), `forfeiture_reason` (enum: `late_cancel`, `no_show`), `forfeited_at`
+- Schema version: 1
+
+Fits cleanly.
+
+### `customer.handoff`
+
+- Subject: `person_id`
+- Actor: `system:revenue` (sidecar emission at first lock)
+- Payload: `person_id`, `first_lesson_id`, `credit_reservation_id`, `handoff_at`
+- Schema version: 1
+
+Fits cleanly. Subject points at the human being handed off; payload carries the lesson and reservation context.
+
+### `invoice.sent`
+
+- Subject: `person_id`
+- Actor: `system:revenue` (Revenue's invoicing layer, often triggered by a scheduled job at T-7 days)
+- Payload: `invoice_id`, `person_id`, `amount`, `currency`, `line_items[]`, `due_at`, `sent_at`
+- Schema version: 1
+
+Fits cleanly.
+
+### `payment.captured`
+
+- Subject: `person_id`
+- Actor: `<person_id>` of the customer for self-service; `system:revenue` for auto-capture (e.g., scheduled charge of saved card)
+- Payload: `payment_id`, `invoice_id` (optional, if tied to an invoice), `amount`, `currency`, `captured_at`, `payment_method_id`
+- Schema version: 1
+
+Fits cleanly.
+
+## Cross-cutting validation
+
+### Producer enum coverage
+
+The five `producer` enum values (`platform`, `growth`, `sales`, `operations`, `revenue`) cover every event type in the vocabulary. No event needs a sub-producer field at the envelope level; sub-job attribution (which Revenue job emitted which event, etc.) lives in payloads or in the ledger's `Created Via` field where applicable. Producer enum is sufficient at v1.0.0.
+
+### Schema version coverage
+
+Every event_type starts at `schema_version=1` and registers its initial payload schema in the event-type registry. No event needs a higher version at v1.0.0. Future additive payload changes (new optional fields) can land at v2 of an event_type without envelope contract changes.
+
+### Subject pattern coverage
+
+- Person-centric events (`person.*`, `lead.*`, `credit.*`, `customer.handoff`, `invoice.*`, `payment.*`, `intake.captured` post-match) carry `person_id` as subject.
+- Lesson-centric events (`lesson.*`) carry `lesson_id` as subject.
+- Pre-match `intake.captured` is the only event whose subject is not yet a canonical Person ID at emission time; the recommended `fsm_` prefix solves this without breaking the envelope contract.
+
+### Actor pattern coverage
+
+Every event's actor falls into one of two patterns: `<person_id>` for human-initiated actions (sales rep, coach, ops staff, customer self-service, admin) or `system:<domain>` for automated actions. The dispatcher SDK auto-populates `system:<producer>` when no human actor is specified and the producer is identifiable. Actor is universally meaningful for audit.
+
+### Correlation chains
+
+The most important cross-domain chain in the architecture is intake-to-handoff:
+
+```
+intake.captured (Growth)
+  → person.created (Platform)
+  → intake.matched (Platform) [proposed, see intake.captured clarification]
+  → lead.qualified (Sales)
+  → credit.purchased (Revenue)
+  → credit.reserved (Revenue, at Sales' scheduling action)
+  → credit.funded (Revenue)
+  → credit.locked (Revenue)
+  → customer.handoff (Revenue, sidecar)
+```
+
+The dispatcher SDK SHOULD auto-propagate `correlation_id` through this chain by stamping each downstream event with the originating event's `event_id` (or with the upstream event's `correlation_id` if that upstream event was itself part of a chain). Without auto-propagation, consumers lose the cross-domain trace. This is an implementation note for the dispatcher SDK, not a contract change.
+
+## Findings
+
+1. Twenty event types validated. Every one fits the envelope cleanly with the seven required fields plus optional subject, actor, and correlation_id.
+2. The producer enum (`platform`, `growth`, `sales`, `operations`, `revenue`) is sufficient. No envelope changes needed.
+3. The actor pattern (`<person_id>` for humans, `system:<domain>` for automation) is universally applicable.
+4. The subject pattern is consistent: person-centric events carry `person_id`, lesson-centric events carry `lesson_id`. Multi-participant events keep `lesson_id` as subject and list participants in payload, which is the correct treatment.
+5. **One design clarification.** `intake.captured` at emission time precedes the canonical Person mint, so its subject cannot be `person_id`. Recommended fix: reserve a `fsm_` prefix for form submissions and use that as the subject of `intake.captured`. Platform emits a separate `intake.matched` event with the canonical `person_id` once Platform's identity service resolves the Person. This is additive (a new prefix in ADR-0002 and a new Platform event) and does not require changes to ADR-0005 or the event envelope contract.
+6. The `correlation_id` field exists in the envelope but its propagation behavior (the dispatcher SDK should auto-stamp from upstream event_id) is an implementation note for the dispatcher SDK, not a contract field semantics change.
+
+## Recommendation
+
+No changes to Event Envelope Contract v1.0.0 required from this validation. Two follow-up additive items for v1.x:
+
+1. Reserve `fsm_<UUID v7 canonical>` prefix for form submissions in ADR-0002's reserved-prefix table. Update the Identity Contract README's §4.3 prefix table.
+2. Define a new `intake.matched` event_type emitted by Platform's identity service when a `fsm_*` is matched or minted to a `person_id`. Payload: `form_submission_id`, `person_id`, `match_type` (enum: `auto_matched`, `auto_minted`, `manual_resolved`), `matched_at`. This is an additive event, registered in the event-type registry at `schema_version=1`.
+
+Both items are minor and can be addressed when the intake-capture flow is implemented in code. Neither blocks tagging `event-envelope-v1.0.0`.
+
+Ready to feed into T3 (tag event-envelope-v1.0.0) and T4 (register in Notion Contracts Registry).