@sguild/dispatcher 2.0.0

package/contracts/credit-reservation-lock/schema/payloads/credit.funded-v1.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/credit.funded-v1.json",
+  "title": "credit.funded payload v1",
+  "description": "Payload for the credit.funded event_type per contracts/credit-reservation-lock/README.md §9.3. Emitted by Revenue when the funding sub-state on a 'reserved' reservation flips from 'pending' to 'funded'. Subscribers: Sales (signal that customer is committing financially), Delivery. Coaching does NOT subscribe; the funding sub-state is Revenue-internal and does not change whether the slot is claimed in the lock-aware availability projection (per coach-availability §4.3.1).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credit_reservation_id",
+    "funding_source",
+    "funded_at"
+  ],
+  "properties": {
+    "credit_reservation_id": {
+      "type": "string",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "funding_source": {
+      "type": "string",
+      "description": "How the reservation became funded.",
+      "enum": [
+        "credits_available",
+        "invoice_paid"
+      ]
+    },
+    "funded_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/contracts/credit-reservation-lock/schema/payloads/credit.locked-v1.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/credit.locked-v1.json",
+  "title": "credit.locked payload v1",
+  "description": "Payload for the credit.locked event_type per contracts/credit-reservation-lock/README.md §9.4. Emitted by Revenue when the reservation enters 'locked' state at T-48h. Subscribers: Delivery (day-of preparation), Sales (close Lead via the customer.handoff sidecar), Coaching (state-transition only; the slot stays subtracted in the availability projection per coach-availability §4.3.2). The customer.handoff sidecar fires on the first credit.locked per Person.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credit_reservation_id",
+    "lesson_id",
+    "person_id",
+    "locked_credits",
+    "locked_at"
+  ],
+  "properties": {
+    "credit_reservation_id": {
+      "type": "string",
+      "description": "The reservation transitioning to locked. crr_<UUID v7 canonical>.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "lesson_id": {
+      "type": "string",
+      "description": "The Delivery-owned lesson. les_<UUID v7>.",
+      "pattern": "^les_[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 Person whose credit account is locked.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "locked_credits": {
+      "type": "integer",
+      "description": "N (positive integer): the credit count posted as the Reservation Lock Debit ledger entry per §7.",
+      "minimum": 1
+    },
+    "locked_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the lock posted. Producer's wall-clock in UTC."
+    }
+  }
+}

package/contracts/credit-reservation-lock/schema/payloads/credit.purchased-v1.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/credit.purchased-v1.json",
+  "title": "credit.purchased payload v1",
+  "description": "Payload for the credit.purchased event_type per contracts/credit-reservation-lock/README.md §9.1. Emitted by Revenue when a Purchase Credit ledger entry posts (customer pack purchase). Subscribers: Sales (close out related Leads), Growth (funnel attribution), Delivery (awareness of new credit availability), Platform warehouse.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credit_account_id",
+    "person_id",
+    "purchased_credits",
+    "order_id",
+    "purchased_at"
+  ],
+  "properties": {
+    "credit_account_id": {
+      "type": "string",
+      "pattern": "^crd_acct_[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",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "purchased_credits": {
+      "type": "integer",
+      "description": "N (positive integer): the credit count added to the account by this purchase.",
+      "minimum": 1
+    },
+    "order_id": {
+      "type": "string",
+      "description": "The originating order from Revenue. ord_<UUID v7>.",
+      "pattern": "^ord_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "purchased_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/contracts/credit-reservation-lock/schema/payloads/credit.released-v1.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/credit.released-v1.json",
+  "title": "credit.released payload v1",
+  "description": "Payload for the credit.released event_type per contracts/credit-reservation-lock/README.md §9.6. Emitted by Revenue on '→ released' transition from any source. Subscribers: Delivery, Sales (if pre-lock release of a Lead's first reservation), Coaching (unsubtracts the slot in the availability projection per coach-availability §4.3.2), Platform warehouse. v2 will add a cancellation_reason (or reason_code; naming TBD) per the pending ADR-0006 amendment in 2026-05-02-delivery-refund-cancellation-reason-codes; the v1 payload here is the consumer-stable shape during the SDK gap and the Phase-2 cutover.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credit_reservation_id",
+    "credit_account_id",
+    "released_credits",
+    "initiator",
+    "reversal_reason",
+    "cancelled_at"
+  ],
+  "properties": {
+    "credit_reservation_id": {
+      "type": "string",
+      "description": "The reservation being released.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "credit_account_id": {
+      "type": "string",
+      "pattern": "^crd_acct_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "released_credits": {
+      "type": "integer",
+      "description": "N (positive integer).",
+      "minimum": 1
+    },
+    "initiator": {
+      "type": "string",
+      "description": "Who initiated the cancellation per §6 cancellation policy interface and §9.6.",
+      "enum": [
+        "customer",
+        "admin",
+        "coach",
+        "system_weather",
+        "system_logistics",
+        "system_unpaid",
+        "system_other"
+      ]
+    },
+    "reversal_reason": {
+      "type": "string",
+      "description": "The credit-accounting category for the reversal Adjustment per §7.1. 'Credits Released' for normal operational cancellations; 'Administrative Void' for admin overrides or data corrections.",
+      "enum": [
+        "Credits Released",
+        "Administrative Void"
+      ]
+    },
+    "reason_note": {
+      "type": "string",
+      "description": "Optional free-form context. Operator notes, weather event description, etc."
+    },
+    "cancelled_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/contracts/credit-reservation-lock/schema/payloads/credit.released-v2.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/credit.released-v2.json",
+  "title": "credit.released payload v2",
+  "description": "Payload for the credit.released event_type per contracts/credit-reservation-lock/README.md §9.6 at schema_version 2 (v1.1.0 amendment landed 2026-05-08 per memos/2026-05-08-revenue-refund-reason-codes-signoff and 2026-05-08-delivery-reason-codes-signoff-accepted). Adds the required reason_code field; otherwise identical to v1. Producers SHALL emit at schema_version 2 from the cutover date 2026-05-22; v1 consumers continue to work indefinitely per §11 additive-discipline (the new field is safe-to-ignore on the v1 surface). reason_code is partitioned into the auto-release and explicit-operator subsets per §6.1. Consumers SHALL treat unknown reason_code values as safe-to-ignore per §11 (Phase-2 narrowing may add values as policy work surfaces specifics).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credit_reservation_id",
+    "credit_account_id",
+    "released_credits",
+    "initiator",
+    "reason_code",
+    "reversal_reason",
+    "cancelled_at"
+  ],
+  "properties": {
+    "credit_reservation_id": {
+      "type": "string",
+      "description": "The reservation being released.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "credit_account_id": {
+      "type": "string",
+      "pattern": "^crd_acct_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "released_credits": {
+      "type": "integer",
+      "description": "N (positive integer).",
+      "minimum": 1
+    },
+    "initiator": {
+      "type": "string",
+      "description": "Who initiated the cancellation per §6 cancellation policy interface and §9.6.",
+      "enum": [
+        "customer",
+        "admin",
+        "coach",
+        "system_weather",
+        "system_logistics",
+        "system_unpaid",
+        "system_other"
+      ]
+    },
+    "reason_code": {
+      "type": "string",
+      "description": "Cancellation cause in a refund-flow-actionable way per §6.1. Auto-release subset (no operator approval at the lock-state-machine boundary): site_closure, coach_unavailable_reschedule_failed, force_majeure, weather, administrative_void. Explicit-operator subset (operator confirms refund eligibility): customer_requested_in_window, customer_requested_exception, policy_exception, bad_debt_writeoff. Consumers SHALL treat unknown values as safe-to-ignore per §11.",
+      "enum": [
+        "site_closure",
+        "coach_unavailable_reschedule_failed",
+        "force_majeure",
+        "weather",
+        "administrative_void",
+        "customer_requested_in_window",
+        "customer_requested_exception",
+        "policy_exception",
+        "bad_debt_writeoff"
+      ]
+    },
+    "reversal_reason": {
+      "type": "string",
+      "description": "The credit-accounting category for the reversal Adjustment per §7.1. 'Credits Released' for normal operational cancellations; 'Administrative Void' for admin overrides or data corrections.",
+      "enum": [
+        "Credits Released",
+        "Administrative Void"
+      ]
+    },
+    "reason_note": {
+      "type": "string",
+      "description": "Optional free-form context. Operator notes, weather event description, etc."
+    },
+    "cancelled_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/contracts/credit-reservation-lock/schema/payloads/credit.reserved-v1.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/credit.reserved-v1.json",
+  "title": "credit.reserved payload v1",
+  "description": "Payload for the credit.reserved event_type per contracts/credit-reservation-lock/README.md §9.2. Emitted by Revenue at scheduling. Subscribers: Delivery (awareness of upcoming lesson), Coaching (subtracts the slot in the lock-aware availability projection per coach-availability §4.3.2), Platform warehouse.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "credit_reservation_id",
+    "credit_account_id",
+    "person_id",
+    "lesson_id",
+    "organization_id",
+    "reserved_credits",
+    "reserved_at",
+    "lesson_starts_at"
+  ],
+  "properties": {
+    "credit_reservation_id": {
+      "type": "string",
+      "description": "The reservation per ADR-0002. crr_<UUID v7 canonical>.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "credit_account_id": {
+      "type": "string",
+      "description": "The credit account being claimed against. crd_acct_<UUID v7 canonical> per the contract terminology section.",
+      "pattern": "^crd_acct_[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 Person whose credit account is claimed. per_<UUID v7> per ADR-0002.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "lesson_id": {
+      "type": "string",
+      "description": "The Delivery-owned lesson. les_<UUID v7> 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}$"
+    },
+    "organization_id": {
+      "type": "string",
+      "description": "Tenant scope on the reservation; see ADR-0001 for the tenant model. Today a fixed singleton.",
+      "minLength": 1
+    },
+    "reserved_credits": {
+      "type": "integer",
+      "description": "N (positive integer): the credit count claimed by this reservation. Determined by the lesson's duration or the offering's reduced credit price for trial lessons.",
+      "minimum": 1
+    },
+    "reserved_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the reservation was recorded. Producer's wall-clock in UTC."
+    },
+    "lesson_starts_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the lesson is scheduled to start. Used by consumers (notably Coaching) to scope window math."
+    }
+  }
+}

package/contracts/credit-reservation-lock/schema/payloads/customer.handoff-v1.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/credit-reservation-lock/schema/payloads/customer.handoff-v1.json",
+  "title": "customer.handoff payload v1",
+  "description": "Payload for the customer.handoff event_type per contracts/credit-reservation-lock/README.md §5 (Customer handoff coupling). Emitted by Revenue immediately after credit.locked when it is the FIRST lock for a Person across all credits and lessons. Subscribers: Delivery (starts customer-tracking record, owns daily-touch responsibility), Sales (closes the originating Lead), Platform warehouse. Idempotent: Revenue tracks per-Person 'first lock fired' state and SHALL NOT re-emit on credit.locked redelivery (§5 Idempotency note). Per §5.1 the handoff is irrevocable; subsequent terminal states on the lock do not retract it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "person_id",
+    "first_lesson_id",
+    "credit_reservation_id",
+    "handoff_at"
+  ],
+  "properties": {
+    "person_id": {
+      "type": "string",
+      "description": "The Person being handed off from Sales' daily-touch responsibility to Delivery's.",
+      "pattern": "^per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "first_lesson_id": {
+      "type": "string",
+      "description": "The lesson whose first-lock-for-this-Person triggered the handoff.",
+      "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 reservation whose locked transition fired this handoff.",
+      "pattern": "^crr_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "handoff_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/contracts/event-envelope/schema/envelope-v1.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/event-envelope/envelope-v1.json",
+  "title": "Sguild Event Envelope v1",
+  "description": "The shared envelope every cross-domain event rides on, per contracts/event-envelope/README.md (currently v1.0.2). Required and optional fields per §4.1 and §4.2; field rules per §4.3. Per-event-type payload schemas live alongside the producing contract at contracts/<contract>/schema/payloads/<event_type>-v<schema_version>.json and version independently per §8.2.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "event_id",
+    "event_type",
+    "occurred_at",
+    "tenant_id",
+    "producer",
+    "schema_version",
+    "payload"
+  ],
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "description": "Globally unique event identifier per ADR-0002. Format: 'evt_' followed by a UUID v7 in canonical form.",
+      "pattern": "^evt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "event_type": {
+      "type": "string",
+      "description": "Hierarchical event-type identifier; dotted lowercase noun.verb. Must be registered in the event-type registry before first use per §10.4.",
+      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$",
+      "minLength": 3,
+      "maxLength": 128
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Producer's wall-clock at the moment the event happened. ISO 8601 with timezone, in UTC. Producers MUST NOT backdate or postdate (§4.3)."
+    },
+    "tenant_id": {
+      "type": "string",
+      "description": "Tenant scoping per ADR-0001. Today a fixed singleton. Producers MUST NOT accept tenant_id from untrusted input (§4.3); it comes from request context.",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "producer": {
+      "type": "string",
+      "description": "Which domain emitted the event. Closed enum per the closed domain set; 'operations' is the legacy value during the 2026-04-27 to 2026-05-11 deprecation window per v1.0.1 changelog.",
+      "enum": [
+        "platform",
+        "growth",
+        "sales",
+        "delivery",
+        "revenue",
+        "coaching",
+        "operations"
+      ]
+    },
+    "schema_version": {
+      "type": "integer",
+      "description": "Versions the payload shape for this event_type. Independent of envelope version per §8.2. Starts at 1 per §10.4.",
+      "minimum": 1
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data; shape determined by (event_type, schema_version). Payload schemas live at contracts/<contract>/schema/payloads/<event_type>-v<schema_version>.json and are applied separately by the dispatcher SDK after envelope validation succeeds."
+    },
+    "subject": {
+      "type": "string",
+      "description": "The primary entity the event is about. Usually a person_id; may be any canonical entity ID per ADR-0002 (lead_*, par_*, coa_*, crd_*, etc.). Optional but SHOULD be set for events whose subject is a Person.",
+      "pattern": "^[a-z]{3,4}_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "actor": {
+      "type": "string",
+      "description": "The human or system that caused the event. Either a person_id (per_<UUID v7>) for human-triggered events or 'system:<domain>' for automated events.",
+      "pattern": "^(per_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|system:(platform|growth|sales|delivery|revenue|coaching))$"
+    },
+    "correlation_id": {
+      "type": "string",
+      "description": "The originating event in a chain. Lets consumers reconstruct cross-domain workflows. Same shape as event_id.",
+      "pattern": "^evt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    }
+  }
+}