@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/credit-reservation-lock/reservation-create-api.md

@@ -0,0 +1,191 @@
+# Credit Reservation Lock, Reservation Create API
+
+**Status:** v1.1.0
+**Date:** 2026-05-16
+**Owner:** Revenue
+**Consumers:** Sales close orchestration; Delivery hold-create reads the resulting `credit_reservation_id`
+**Parent contract:** Credit Reservation Lock Contract v1.2.0
+
+## 1. Purpose and scope
+
+This sub-spec defines the Sales-callable API for creating a Revenue credit reservation before Delivery creates a lesson hold. It is an operational API surface owned by Revenue and governed by the Credit Reservation Lock Contract.
+
+The endpoint creates or returns a Revenue `crr_` credit reservation in lifecycle state `reserved`. It does not create a Delivery lesson hold, assign a coach, confirm funding, or post a lock debit. Delivery hold-create consumes the returned `credit_reservation_id` and advances the Delivery lesson-hold state separately.
+
+For Sales-originated close orchestration, `lesson_id` is absent until Delivery hold-create mints the Delivery-owned `les_` identifier. Revenue MUST NOT require Sales to fabricate or preallocate a `les_` value.
+
+Out of scope: payment collection, refund initiation, Delivery hold-create, Coaching eligibility reads, lesson rescheduling, and cancellation or release submission.
+
+## 2. Endpoint
+
+`POST /api/v1/reservations`
+
+Headers:
+
+- `Authorization`: bearer service token or authenticated cross-domain caller credential accepted by Revenue.
+- `Idempotency-Key`: required, string up to 128 characters. Scoped by `organization_id`.
+
+Body:
+
+```json
+{
+  "organization_id": "org_...",
+  "person_id": "per_...",
+  "participant_id": "par_...",
+  "lesson_type_id": "lty_...",
+  "service_area_id": "sva_...",
+  "window": {
+    "start": "2026-05-09T17:00:00-10:00",
+    "end": "2026-05-09T17:30:00-10:00"
+  },
+  "offering_id": "off_...",
+  "notes": "optional free text up to 500 chars"
+}
+```
+
+Required fields:
+
+- `organization_id`
+- `person_id`
+- `participant_id`
+- `lesson_type_id`
+- `service_area_id`
+- `window.start`
+- `window.end`
+
+Optional fields:
+
+- `offering_id`, when Sales already knows the sold offering that determines trial or regular credit price.
+- `lesson_id`, only when Delivery has already minted a canonical `les_` in a non-standard or replay path. Sales close orchestration normally omits it.
+- `notes`, operator context. Producers SHOULD redact this field from logs.
+
+Revenue MAY derive `reserved_credits` from the lesson duration, lesson type, and offering. Consumers SHALL NOT send `reserved_credits` as an authority field unless a later minor version adds it as an explicit override with Revenue validation.
+
+## 3. Success response
+
+HTTP 201 on a new reservation:
+
+```json
+{
+  "reservation_id": "crr_...",
+  "credit_reservation_id": "crr_...",
+  "organization_id": "org_...",
+  "person_id": "per_...",
+  "participant_id": "par_...",
+  "lesson_id": null,
+  "lesson_type_id": "lty_...",
+  "service_area_id": "sva_...",
+  "window": {
+    "start": "2026-05-09T17:00:00-10:00",
+    "end": "2026-05-09T17:30:00-10:00"
+  },
+  "lifecycle_state": "reserved",
+  "funding_state": "pending",
+  "reserved_credits": 6,
+  "result": "created",
+  "as_of": "2026-05-16T06:30:00.000Z"
+}
+```
+
+HTTP 200 on an idempotent replay or equivalent existing active reservation:
+
+```json
+{
+  "reservation_id": "crr_...",
+  "credit_reservation_id": "crr_...",
+  "organization_id": "org_...",
+  "person_id": "per_...",
+  "participant_id": "par_...",
+  "lesson_id": null,
+  "lesson_type_id": "lty_...",
+  "service_area_id": "sva_...",
+  "window": {
+    "start": "2026-05-09T17:00:00-10:00",
+    "end": "2026-05-09T17:30:00-10:00"
+  },
+  "lifecycle_state": "reserved",
+  "funding_state": "pending",
+  "reserved_credits": 6,
+  "result": "existing",
+  "as_of": "2026-05-16T06:30:00.000Z"
+}
+```
+
+`reservation_id` and `credit_reservation_id` are aliases in v1.0.0. Producers SHALL include both. Consumers SHOULD store `credit_reservation_id` as the explicit Revenue field and MAY pass `reservation_id` to older surfaces that use the shorter name.
+
+## 4. Error response
+
+Every error response uses this envelope:
+
+```json
+{
+  "error": {
+    "code": "validation_failed",
+    "message": "Human-readable summary.",
+    "conflict_reason": "existing_active_reservation",
+    "current_state": {
+      "reservation_id": "crr_...",
+      "lifecycle_state": "reserved",
+      "funding_state": "pending"
+    }
+  },
+  "as_of": "2026-05-16T06:30:00.000Z"
+}
+```
+
+`conflict_reason` and `current_state` are present only when useful for HTTP 409.
+
+Status codes:
+
+- `400 Bad Request`: malformed JSON, missing required field, invalid identifier prefix, invalid window shape.
+- `401 Unauthorized`: missing or invalid caller credential.
+- `403 Forbidden`: caller is authenticated but not allowed to act for the named `organization_id`.
+- `404 Not Found`: `person_id`, `participant_id`, supplied `lesson_id`, `lesson_type_id`, `service_area_id`, or `offering_id` does not resolve through the appropriate authoritative surface.
+- `409 Conflict`: the request is well-formed but cannot create the requested reservation because live state changed or conflicts with an existing reservation.
+- `422 Unprocessable Entity`: business rule failure on a well-formed request.
+- `429 Too Many Requests`: per-organization or caller rate limit exceeded.
+- `500` or `503`: Revenue cannot verify or persist the reservation. Consumers SHALL treat this branch as unverifiable and SHOULD avoid creating a Delivery hold until a retry or operator review succeeds.
+
+HTTP 409 `conflict_reason` values:
+
+- `existing_active_reservation`: the lesson already has an active Revenue reservation.
+- `reservation_already_terminal`: the matching reservation is terminal and cannot be reused.
+- `person_mismatch`: the participant or lesson context does not map to the request's `person_id`.
+- `organization_mismatch`: the request names state across more than one Organization.
+- `credit_account_missing`: Revenue cannot find an active Credit Account for `person_id`.
+- `credit_account_ambiguous`: Revenue finds multiple active Credit Accounts for `person_id`.
+- `lesson_not_reservable`: the lesson is not in a state that can receive a reservation.
+- `window_conflict`: the requested lesson window conflicts with known reservation state.
+- `idempotency_payload_mismatch`: the `Idempotency-Key` was already used with a different payload in the same `organization_id`.
+
+Consumers SHALL treat unknown `conflict_reason` values as safe to surface to an operator and unsafe for automated retry branching.
+
+## 5. Producer responsibilities
+
+Revenue SHALL create the reservation and emit `credit.reserved` in the same transaction per ADR-0009. A failure to publish the event rolls back the reservation create. A failure to create the reservation emits no event.
+
+Revenue SHALL scope idempotency to `(organization_id, idempotency_key)` and retain keys for at least 24 hours. Replays with the same key and same normalized payload return the original result. Replays with the same key and a different normalized payload return HTTP 409 with `conflict_reason: idempotency_payload_mismatch`.
+
+Revenue SHALL return only a `reserved` lifecycle state from this endpoint. Funding may already be sufficient, in which case `funding_state` MAY be `funded`, but the lifecycle state remains `reserved` until a separate lock transition occurs.
+
+Revenue SHALL accept absent `lesson_id` on the Sales close path. If Revenue stores a lesson reference on the `crr_`, the attachment point is Delivery's successful hold-create result or `delivery.lesson-hold.created`, not the initial reservation-create request.
+
+## 6. Consumer responsibilities
+
+Sales SHALL call Coaching eligibility before calling this endpoint when the reservation is part of close orchestration. Sales SHALL pass the returned `credit_reservation_id` to Delivery hold-create and SHALL NOT infer Delivery's lesson-hold state from Revenue's lifecycle state.
+
+Sales SHALL NOT call Delivery hold-create when this endpoint returns an error or an unverifiable 5xx branch. The safe path is retry with the same idempotency key if the request may not have reached Revenue, or operator review if Revenue may have persisted state but the client did not receive the response.
+
+## 7. Versioning
+
+Patch versions may clarify prose and add non-normative examples. Minor versions may add optional request fields, optional response fields, relax required fields, or add new `conflict_reason` values. Major versions are required to remove or rename fields, add new required fields, change idempotency semantics, or change the path.
+
+## 8. Change log
+
+### v1.1.0 (2026-05-16)
+
+Makes `lesson_id` optional and nullable on the Sales close-orchestration create path. Revenue reservation-create remains before Delivery hold-create; Delivery mints `les_` during hold-create and can attach it back to Revenue through `delivery.lesson-hold.created` or an explicit reconciliation write. No path, idempotency, lifecycle-state, or Delivery hold-create ordering change.
+
+### v1.0.0 (2026-05-16)
+
+Initial Sales-callable reservation-create sub-spec.

package/contracts/credit-reservation-lock/reservation-release-api.md

@@ -0,0 +1,171 @@
+# Credit Reservation Lock, Reservation Release API
+
+**Status:** v1.0.0
+**Date:** 2026-05-16
+**Owner:** Revenue
+**Consumers:** Sales close orchestration; Delivery cancellation and reconciliation flows
+**Parent contract:** Credit Reservation Lock Contract v1.2.0
+
+## 1. Purpose and scope
+
+This sub-spec defines the Sales-callable API for submitting a cancellation or release request to Revenue for an existing credit reservation. Revenue owns the policy decision and the resulting lifecycle transition.
+
+The endpoint can result in `released` or `forfeited` depending on the reservation state, initiator, reason code, timing, funding state, and Revenue policy. Consumers submit intent and context; they do not directly choose the terminal state.
+
+Out of scope: refund initiation for confirmed payment flows, Delivery lesson-hold cancellation storage, no-show recording, and creating replacement reservations.
+
+## 2. Endpoint
+
+`POST /api/v1/reservations/{reservation_id}/release`
+
+Path parameter:
+
+- `reservation_id`: required, a Revenue `crr_` credit reservation id.
+
+Headers:
+
+- `Authorization`: bearer service token or authenticated cross-domain caller credential accepted by Revenue.
+- `Idempotency-Key`: required, string up to 128 characters. Scoped by `organization_id`.
+
+Body:
+
+```json
+{
+  "organization_id": "org_...",
+  "initiator": "admin",
+  "reason_code": "customer_requested_in_window",
+  "reason_notes": "optional free text up to 500 chars",
+  "lesson_id": "les_..."
+}
+```
+
+Required fields:
+
+- `organization_id`
+- `initiator`
+- `reason_code`
+
+Optional fields:
+
+- `reason_notes`, operator context. Producers SHOULD redact this field from logs.
+- `lesson_id`, accepted as a defensive match check when the caller is releasing a reservation as part of a Delivery hold conflict or retry path.
+
+`initiator` values:
+
+- `customer`
+- `admin`
+- `coach`
+- `system_weather`
+- `system_logistics`
+- `system_unpaid`
+- `system_other`
+
+`reason_code` values are the `credit.released` v2 values in the parent contract §6.1:
+
+- `site_closure`
+- `coach_unavailable_reschedule_failed`
+- `force_majeure`
+- `weather`
+- `administrative_void`
+- `customer_requested_in_window`
+- `customer_requested_exception`
+- `policy_exception`
+- `bad_debt_writeoff`
+
+## 3. Success response
+
+HTTP 200:
+
+```json
+{
+  "reservation_id": "crr_...",
+  "credit_reservation_id": "crr_...",
+  "organization_id": "org_...",
+  "lesson_id": "les_...",
+  "prior_lifecycle_state": "reserved",
+  "lifecycle_state": "released",
+  "funding_state": null,
+  "initiator": "admin",
+  "reason_code": "customer_requested_in_window",
+  "reversal_reason": "Credits Released",
+  "released_at": "2026-05-16T06:30:00.000Z",
+  "ledger_reversal_created": false,
+  "result": "released",
+  "as_of": "2026-05-16T06:30:00.000Z"
+}
+```
+
+`result` values:
+
+- `released`: the request produced or idempotently returned a `released` terminal state.
+- `forfeited`: the request produced or idempotently returned a `forfeited` terminal state.
+- `already_terminal`: the reservation was already in the same terminal state produced by the same idempotency key.
+
+When `result` is `forfeited`, `lifecycle_state` is `forfeited`, `released_at` is omitted, and `forfeited_at` is present. Consumers SHALL surface this branch to an operator and SHALL NOT treat it as a release.
+
+`reservation_id` and `credit_reservation_id` are aliases in v1.0.0. Producers SHALL include both.
+
+## 4. Error response
+
+Every error response uses this envelope:
+
+```json
+{
+  "error": {
+    "code": "conflict",
+    "message": "Human-readable summary.",
+    "conflict_reason": "confirmed_state_requires_refund_flow",
+    "current_state": {
+      "reservation_id": "crr_...",
+      "lifecycle_state": "locked",
+      "funding_state": "funded"
+    }
+  },
+  "as_of": "2026-05-16T06:30:00.000Z"
+}
+```
+
+Status codes:
+
+- `400 Bad Request`: malformed JSON, missing required field, invalid identifier prefix, invalid `initiator`, invalid `reason_code`.
+- `401 Unauthorized`: missing or invalid caller credential.
+- `403 Forbidden`: caller is authenticated but not allowed to act for the named `organization_id`.
+- `404 Not Found`: `reservation_id` does not resolve in Revenue.
+- `409 Conflict`: live reservation state prevents the requested operation.
+- `422 Unprocessable Entity`: business rule failure on a well-formed request.
+- `429 Too Many Requests`: per-organization or caller rate limit exceeded.
+- `500` or `503`: Revenue cannot verify or persist the release. Consumers SHALL treat this branch as unverifiable and SHOULD avoid assuming the reservation was released until a retry or operator review succeeds.
+
+HTTP 409 `conflict_reason` values:
+
+- `reservation_already_consumed`: the reservation is already consumed.
+- `reservation_already_released`: the reservation is already released by a different idempotency key or different reason.
+- `reservation_already_forfeited`: the reservation is already forfeited by a different idempotency key or different reason.
+- `confirmed_state_requires_refund_flow`: money has moved and the request must go through the refund-flow handoff before release can complete.
+- `locked_state_requires_policy_decision`: the request could produce forfeiture and needs operator or policy confirmation not present in the request.
+- `organization_mismatch`: the reservation belongs to a different Organization.
+- `lesson_mismatch`: the optional `lesson_id` does not match the reservation.
+- `idempotency_payload_mismatch`: the `Idempotency-Key` was already used with a different payload in the same `organization_id`.
+- `concurrent_state_change`: the reservation changed while Revenue was evaluating the request.
+
+Consumers SHALL treat unknown `conflict_reason` values as safe to surface to an operator and unsafe for automated retry branching.
+
+## 5. Producer responsibilities
+
+Revenue SHALL run the cancellation policy from the parent contract §6 and perform the resulting lifecycle transition. Revenue SHALL emit `credit.released` or `credit.forfeited` in the same transaction as the state change and any required ledger write per ADR-0009.
+
+Revenue SHALL NOT emit `credit.released` for a request that policy resolves to forfeiture. Revenue SHALL NOT silently release a confirmed or locked reservation when refund-flow or forfeiture policy is required.
+
+Revenue SHALL scope idempotency to `(organization_id, idempotency_key)` and retain keys for at least 24 hours. Replays with the same key and same normalized payload return the original result. Replays with the same key and a different normalized payload return HTTP 409 with `conflict_reason: idempotency_payload_mismatch`.
+
+## 6. Consumer responsibilities
+
+Sales SHALL call this endpoint before retrying close orchestration with a fresh reservation when a Delivery hold-create conflict leaves an unused Revenue reservation. Sales SHALL wait for a success response before treating the prior reservation as released.
+
+Sales SHALL NOT call this endpoint to cancel a confirmed lesson for refund unless the refund-flow contract has provided the required initiation path. Until that path exists, confirmed-to-released cancellations remain out of scope for Sales-originated v1 close orchestration.
+
+Delivery MAY call this endpoint for cancellation submissions that must flow through Revenue policy, but Delivery remains responsible for its own lesson-hold storage transition and `delivery.lesson-hold.cancelled` event per the sales-scheduling-surface contract.
+
+## 7. Versioning
+
+Patch versions may clarify prose and add non-normative examples. Minor versions may add optional request fields, optional response fields, or new `conflict_reason` values. Major versions are required to remove or rename fields, change required fields, change idempotency semantics, change the path, or make `released` the only possible successful terminal outcome.

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

@@ -2,7 +2,7 @@
   "$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.",
+  "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-24h. 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": [

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

@@ -2,14 +2,13 @@
   "$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.",
+  "description": "Payload for the credit.reserved event_type per contracts/credit-reservation-lock/README.md §9.2. Emitted by Revenue when a reservation claim is recorded. Sales-originated reservations can omit lesson_id until Delivery hold-create mints the Delivery-owned les_ identifier. Subscribers: Delivery, Coaching, Platform warehouse.",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "credit_reservation_id",
     "credit_account_id",
     "person_id",
-    "lesson_id",
     "organization_id",
     "reserved_credits",
     "reserved_at",
@@ -33,7 +32,7 @@
     },
     "lesson_id": {
       "type": "string",
-      "description": "The Delivery-owned lesson. les_<UUID v7> per ADR-0002.",
+      "description": "The Delivery-owned lesson. les_<UUID v7> per ADR-0002. Optional on Sales-originated reservations until Delivery hold-create succeeds.",
       "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": {