@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/credit-reservation-lock/README.md

@@ -0,0 +1,433 @@
+# Credit Reservation Lock Contract
+
+**Status:** v1.4.1
+**Date:** 2026-05-19
+**Owner:** Platform (contract); Revenue (implementation)
+**Consumers:** Delivery (primary subscriber for day-of and handoff signals), Sales (subscribes to `customer.handoff` to close out Leads), Platform (warehouse ingestion), Growth (funnel close), Coaching (lock-aware availability projection on `credit.reserved`, `credit.locked`, `credit.released`, `credit.forfeited` per ADR-0008)
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template), ADR-0003 (Person canonical, customer.handoff trigger), ADR-0005 (event envelope), ADR-0006 (state machine decision)
+**Related contracts:** Identity Contract v1.0.0 (`../identity/README.md`), Event Envelope Contract v1.0.0 (`../event-envelope/README.md`), Sales Scheduling Surface Contract v1.2.0 (`../sales-scheduling-surface/README.md`)
+**Sub-specs (authoritative):** `reservation-create-api.md`, `reservation-release-api.md`, `delivery-state-vocabulary.md`
+
+## 1. Purpose and scope
+
+This contract specifies the credit reservation lock state machine: the lifecycle of a credit reservation from the moment a lesson is scheduled through to its terminal outcome (consumed, released, or forfeited). It defines the states, the transitions, the events emitted, the credit ledger entries posted at each step, and the special `customer.handoff` behavior on first lock for a Person.
+
+Out of scope: how credits are priced, how packs are sold, how invoices are generated, how scheduling is implemented, how cancellation deadlines are configured per-Org or per-tier (Revenue policy), how Refund Debit and other ledger entry types not directly involved in the lock lifecycle are produced.
+
+## 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
+
+- **Credit.** A unit of coach time. Default 10 minutes per credit. A 30-minute lesson costs 3 credits; a 60-minute lesson costs 6. The credit count for any reservation is denoted **N** in this contract; N is a positive integer determined by the lesson's duration (or by the offering's reduced credit price for trial lessons).
+- **Credit Account.** The Revenue record holding a Person's available credits, identified by `crd_acct_<UUID v7 canonical>` (reserved). One Credit Account per Person within a tenant.
+- **Reservation.** A claim that a credit account makes against a specific scheduled lesson. Identified by `crr_<UUID v7 canonical>` in Revenue. Reduces available balance but does not post a ledger entry until lock.
+- **Lock.** The state where a Reservation Lock Debit ledger entry has posted (at T-24h on a funded reservation). Customer can no longer cancel without forfeit; Sguild-side cancellation can still release.
+- **Available balance.** `credit_account.balance − sum_of_open_reservations.N`. The credit count available for new reservations after accounting for already-claimed reservations.
+- **Lesson.** A scheduled service-delivery event in Delivery. Identified by `les_<UUID v7 canonical>` (reserved per ADR-0002).
+- **Cancellation deadline.** The configurable cutoff for customer-initiated cancellations. Default 24 hours pre-lesson; per-Org and per-tier overrides allowed in Revenue policy.
+
+## 4. State machine
+
+### 4.1 Lifecycle states
+
+The state machine has two active states and three terminal states:
+
+| State | Type | Description |
+|---|---|---|
+| `reserved` | active | Claim recorded against credit account. No ledger entry posted yet. Anyone can cancel without forfeit. |
+| `locked` | active | T-24h passed on a funded reservation. Reservation Lock Debit entry posted. Customer can no longer cancel without forfeit; Sguild-side cancellation can still release. |
+| `consumed` | terminal | Lesson delivered. Lock dissolved (Adjustment with reason "Credits Consumed") and Lesson Debit posted. Net account impact: −N credits. |
+| `released` | terminal | Cancellation reversed the reservation. Net account impact: 0 credits (lock dissolved if any, no debit). Several initiator/reason flavors. |
+| `forfeited` | terminal | Customer cancelled after lock or no-show. Lock dissolved (Adjustment with reason "Credits Forfeited") and Credit Forfeit posted. Net account impact: −N credits. |
+
+### 4.2 Funding sub-state on reservation
+
+A reservation in the `reserved` state has a funding sub-state, separate from the lifecycle state:
+
+- `pending`: insufficient credits in the account, invoice not yet paid.
+- `funded`: sufficient credits in the account OR invoice paid.
+
+The funding sub-state is what the T-24h lock check reads to decide `reserved → locked` vs `reserved → released (system_unpaid)`. The funding sub-state has no meaning after the reservation enters a terminal state.
+
+### 4.3 Transitions
+
+| From | To | Trigger | Producer | Event emitted |
+|---|---|---|---|---|
+| (start) | `reserved` | Lesson scheduled, claim recorded | Revenue | `credit.reserved` |
+| `reserved` | `reserved` (funded) | Funding settles (credits become sufficient OR invoice paid) | Revenue | `credit.funded` |
+| `reserved` | `locked` | T-24h auto-job, reservation is `funded` | Revenue | `credit.locked` (and `customer.handoff` if first lock for Person) |
+| `reserved` | `released` (system_unpaid) | T-24h auto-job, reservation is `pending` | Revenue | `credit.released` |
+| `reserved` | `released` (any other initiator) | Cancellation arrives before T-24h | Revenue | `credit.released` |
+| `locked` | `consumed` | Lesson delivery event from Delivery | Revenue | `credit.consumed` |
+| `locked` | `released` | Sguild-side cancellation (admin, coach, weather, logistics) OR administrative void after lock | Revenue | `credit.released` |
+| `locked` | `forfeited` | Customer-initiated cancellation after lock OR no-show | Revenue | `credit.forfeited` |
+
+All terminal states are absorbing.
+
+### 4.4 Reschedule policy
+
+Customer-initiated rescheduling of a `locked` lesson is NOT a transition path. The state machine has no `locked → reserved` transition. To reschedule a locked lesson, the customer must forfeit the existing lock and create a new reservation for the new lesson, which will independently progress through the state machine.
+
+Sguild-initiated rescheduling (admin moves the lesson) is a `locked → released` (Sguild-side) followed by a new `(start) → reserved` for the rescheduled lesson. The customer keeps their credits and gets a fresh reservation.
+
+Rescheduling before T-24h (while still `reserved`) follows the same pattern: cancel the current reservation (released, no ledger entries), create a new reservation for the new lesson.
+
+## 5. Customer handoff coupling
+
+When `credit.locked` fires AND it is the FIRST lock for a Person across all credits and lessons, Revenue SHALL emit `customer.handoff` immediately after `credit.locked`. This is the Sales-to-Delivery handoff per the amended ADR-0003.
+
+`customer.handoff` payload v1:
+- `person_id`
+- `first_lesson_id`
+- `credit_reservation_id`
+- `handoff_at`
+
+Idempotency: Revenue tracks per-Person "first lock fired" state. If the dispatcher redelivers `credit.locked` because a consumer crashed, the side-effect `customer.handoff` SHALL NOT be re-emitted.
+
+### 5.1 Handoff is irrevocable
+
+Once the FIRST lock fires for a Person, `customer.handoff` is emitted and Delivery owns that human's daily-touch responsibility. The handoff is not retracted by the lock's terminal state:
+
+- If the first lock transitions to `released` (Sguild-side cancellation or administrative void), the lock state machine completes for that lesson but the Person remains Delivery-managed.
+- If the first lock transitions to `forfeited`, the same applies; the handoff stands.
+- A customer whose first lesson was forfeited or cancelled and never rescheduled is an Delivery-managed customer in a stalled state. Delivery retains responsibility for re-engagement, not Sales.
+
+The handoff signal is the lock-fired event, not the lock outcome. This matches the late-handoff business intent: Sales' incentive aligns with leads who became real enough to have a lock fire on them.
+
+### 5.2 Free vs paid trials
+
+Trial lessons are not free; they are sold at a reduced credit price specified in the offering tied to the order. The reservation for a trial uses the trial's N value (smaller than a regular lesson) but otherwise progresses through the state machine identically. `customer.handoff` fires on the first lock regardless of whether that first lesson is a trial or a regular lesson.
+
+### 5.3 Group lessons
+
+A lesson with multiple participants charges exactly one credit account: the buyer's. There is no per-participant credit cost. The reservation, the lock, and the lifecycle are all single-account. Multiple participants share the same `lesson_id` but only the buyer's `credit_account` has a reservation against it.
+
+## 6. Cancellation policy interface
+
+Revenue queries its own cancellation policy at the moment of cancellation to decide the resulting transition. The policy is not purely time-based; it considers initiator, timing, and reason jointly.
+
+```
+cancellationPolicy(
+  person_id,
+  lesson_id,
+  cancelled_at,
+  lesson_starts_at,
+  initiator,    // "customer" | "admin" | "coach" | "system_weather" | "system_logistics" | "system_unpaid" | "system_other"
+  reason_code   // see credit.released / credit.forfeited payload enums
+) → { state: "released" | "forfeited", reversal_reason: "Credits Released" | "Administrative Void" | "Credits Forfeited" }
+```
+
+Default behavior:
+
+- **Sguild-initiated cancellations** (initiator ∈ {`admin`, `coach`, `system_weather`, `system_logistics`, `system_unpaid`, `system_other`}): always `released`. The reversal_reason is `Credits Released` for normal operational cancellations, `Administrative Void` for admin overrides or data corrections.
+- **Customer-initiated cancellation arriving 24+ hours before lesson start**: `released` with reversal_reason `Credits Released`.
+- **Customer-initiated cancellation arriving inside the 24-hour window**: `forfeited` with reversal_reason `Credits Forfeited`.
+
+The 24-hour customer cancellation deadline is the Revenue policy default; per-Organization, per-program-type, or per-customer-tier overrides may shorten or lengthen the window. The state machine treats the policy as a black-box query.
+
+### 6.1 Auto-release versus explicit-operator subsets (v1.1.0)
+
+The `reason_code` parameter on `cancellationPolicy` is structured into two subsets that determine whether the resulting `→ released` transition fires automatically or requires explicit operator approval at the lock-state-machine boundary. The distinction is encoded in the §9.6 `credit.released` payload's `reason_code` field at schema_version 2 so the refund flow can route on it without re-deriving from `initiator` or operator notes.
+
+**Auto-release subset** (Delivery system-initiated transitions; no operator approval at the lock-state-machine boundary, though Phase-2 narrowing may surface declaration-layer operator actions for some values):
+
+- `site_closure`. The lesson site closed for a program-wide event Delivery declares.
+- `coach_unavailable_reschedule_failed`. Delivery's reschedule attempts have failed within the program's reschedule policy window. The window is configured per-program but the per-reservation transition is automatic once the window expires.
+- `force_majeure`. A non-weather event-class cancellation Delivery declares (regional emergencies, declared health events, regulatory holds). The per-reservation transition is automatic; the declaration step itself is operator-driven and lives at the Delivery scheduling layer rather than on the credit-reservation-lock event surface.
+- `weather`. Weather-induced cancellation per the program's weather policy.
+- `administrative_void`. System-error or duplicate-reservation void. The Sguild-side equivalent of a typo correction.
+
+**Explicit-operator subset** (operator confirms refund eligibility against program rules before the transition fires):
+
+- `customer_requested_in_window`. Customer requested cancellation, operator confirmed the request is within the program's cancellation window and refund eligibility holds.
+- `customer_requested_exception`. Customer requested cancellation outside the program's cancellation window, operator approved a refund as a policy exception. The split between `_in_window` and `_exception` makes the policy decision visible in the event payload for downstream reconciliation.
+- `policy_exception`. Operator-applied refund exception not driven by a customer cancellation request.
+- `bad_debt_writeoff`. Revenue-initiated bad-debt write-off processed through Delivery's lock-state cancellation interface. The originator is Revenue's reconciliation flow; the Delivery operator confirms the lock-state transition does not collide with in-flight changes on the lesson record rather than independently deciding bad-debt status.
+
+Consumers SHALL treat unknown `reason_code` values as safe-to-ignore per the additive-discipline rule in §11. New values may be added in Phase-2 narrowing as policy work surfaces specifics; the additive-discipline accommodates the additions without consumer breakage.
+
+`reason_code` is a separate field from `initiator` and `reversal_reason`. `initiator` records who initiated the cancellation. `reversal_reason` records the credit-accounting category. `reason_code` records the cancellation cause in a refund-flow-actionable way. Typical combinations on `credit.released` v2: `initiator=system_weather, reason_code=weather, reversal_reason=Credits Released`; `initiator=admin, reason_code=customer_requested_in_window, reversal_reason=Credits Released`; `initiator=admin, reason_code=administrative_void, reversal_reason=Administrative Void`.
+
+## 7. Credit ledger entry types
+
+The credit account ledger uses the following Entry Type enum:
+
+| Entry Type | Sign | Description |
+|---|---|---|
+| `Purchase Credit` | +N | Customer purchase of credits, posted by Payment Job |
+| `Lesson Debit` | −N | Lesson delivered, posted by Lesson Completion Job |
+| `Refund Debit` | −N | Customer refund of credits, posted by Refund Job (out of scope for this contract) |
+| `Adjustment` | ±N | Programmatic or manual correction; carries a `reason_code` |
+| `Reservation Lock Debit` | −N | Lock posted at T-24h, posted by Reservation Job |
+| `Credit Forfeit` | −N | Customer-side forfeiture, posted by Forfeit Job |
+
+Every ledger entry SHALL also carry a `Created Via` field with one of: `Payment Job`, `Lesson Completion Job`, `Forfeit Job`, `Reservation Job`, `Refund Job`, `Manual`, `Backfill`.
+
+### 7.1 Adjustment reason codes
+
+The `Adjustment` entry type carries a `reason_code`. The four codes used at lock dissolution are:
+
+| Reason | Used at | Paired entry |
+|---|---|---|
+| `Credits Consumed` | `locked → consumed` | Lesson Debit (−N), same Created Via (Lesson Completion Job) |
+| `Credits Forfeited` | `locked → forfeited` | Credit Forfeit (−N), same Created Via (Forfeit Job) |
+| `Credits Released` | `locked → released` (Sguild operational) | none |
+| `Administrative Void` | `locked → released` (admin override or data correction) | none |
+
+Additional `reason_code` values may be added for non-lock adjustments (goodwill credits, extenuating-circumstance credits, data corrections, expiration writeoffs, etc.) in v1.x without contract bumps. The four lock-resolution reasons listed are the only `reason_code` values that this contract specifies normatively; others are Revenue-internal.
+
+### 7.2 Lock dissolution invariant
+
+For every transition out of `locked`, exactly one Adjustment entry of type "Lock Debit Reversal" SHALL be posted, with one of the four `reason_code` values above and a link back to the Reservation Lock Debit entry it reverses. The Adjustment posts +N to balance. Lock dissolution is universal; the paired debit entry (Lesson Debit or Credit Forfeit) is conditional on the terminal state.
+
+## 8. Per-outcome ledger pattern
+
+| Terminal | Entry sequence | Net balance impact |
+|---|---|---|
+| `reserved → released` (any pre-lock cancel) | none (no lock to reverse, no debit) | 0 |
+| `reserved → released` (system_unpaid at T-24h) | none (lock never posted) | 0 |
+| `locked → consumed` | Adjustment +N (reason: Credits Consumed); Lesson Debit −N | −N |
+| `locked → released` (Sguild operational) | Adjustment +N (reason: Credits Released) | 0 |
+| `locked → released` (admin override) | Adjustment +N (reason: Administrative Void) | 0 |
+| `locked → forfeited` (customer late or no-show) | Adjustment +N (reason: Credits Forfeited); Credit Forfeit −N | −N |
+
+A reservation's full ledger footprint is reconstructible by following the Reservation Lock Debit entry forward to its paired Adjustment and any subsequent Lesson Debit or Credit Forfeit entry.
+
+## 9. Events
+
+Each event SHALL ride on the Event Envelope (per `../event-envelope/README.md`) with `producer = "revenue"`, `subject = <person_id>`, `actor = "system:revenue"` for automated transitions or `actor = <person_id>` for human-triggered transitions.
+
+### 9.1 `credit.purchased`
+
+Emitted 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).
+
+Payload v1:
+- `credit_account_id`
+- `person_id`
+- `purchased_credits` (N, the count added)
+- `order_id` (the originating order from Revenue)
+- `purchased_at`
+
+### 9.2 `credit.reserved`
+
+Emitted when Revenue records a reservation claim. Subscribers: Delivery (awareness of the upcoming hold claim), Coaching (reservation awareness; coach-specific booking facts arrive on Delivery's hold-created event when `lesson_id` is absent), Platform warehouse.
+
+Payload v1:
+- `credit_reservation_id`
+- `credit_account_id`
+- `person_id`
+- `lesson_id` (optional on Sales-originated reservations until Delivery hold-create mints `les_`)
+- `organization_id`
+- `reserved_credits` (N)
+- `reserved_at`
+- `lesson_starts_at`
+
+### 9.3 `credit.funded`
+
+Emitted when funding sub-state flips from `pending` to `funded`. Subscribers: Sales (signal that customer is committing financially), Delivery.
+
+Payload v1:
+- `credit_reservation_id`
+- `funding_source` (enum: `credits_available`, `invoice_paid`)
+- `funded_at`
+
+### 9.4 `credit.locked`
+
+Emitted 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).
+
+Payload v1:
+- `credit_reservation_id`
+- `lesson_id`
+- `person_id`
+- `locked_credits` (N, posted as Reservation Lock Debit)
+- `locked_at`
+
+### 9.5 `credit.consumed`
+
+Emitted at delivery. Subscribers: Delivery (post-delivery follow-up), Revenue (revenue recognition), Platform warehouse.
+
+Payload v1:
+- `credit_reservation_id`
+- `lesson_id`
+- `consumed_credits` (N)
+- `consumed_at`
+
+### 9.6 `credit.released`
+
+Emitted 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), Platform warehouse.
+
+Payload v1:
+- `credit_reservation_id`
+- `credit_account_id`
+- `released_credits` (N)
+- `initiator` (enum: `customer`, `admin`, `coach`, `system_weather`, `system_logistics`, `system_unpaid`, `system_other`)
+- `reversal_reason` (enum: `Credits Released`, `Administrative Void`)
+- `reason_note` (optional free-form for context)
+- `cancelled_at`
+
+Payload v2 (additive over v1; v1 consumers continue to work):
+- All v1 fields above.
+- `reason_code` (optional, enum). Captures the cancellation cause separate from who initiated and from the credit-accounting category. Values are partitioned into the auto-release and explicit-operator subsets per §6.1. Auto-release values: `site_closure`, `coach_unavailable_reschedule_failed`, `force_majeure`, `weather`, `administrative_void`. Explicit-operator values: `customer_requested_in_window`, `customer_requested_exception`, `policy_exception`, `bad_debt_writeoff`. Consumers SHALL treat unknown values as safe-to-ignore per §11.
+
+Producers SHALL emit `reason_code` from the v1.1.0 cutover date (per §16's change log entry); before the cutover date, the field is omitted and consumers see v1 semantics. Consumers MAY rely on `reason_code` from the cutover date. Consumers gating on payload schema use `schema_version >= 2` per the event envelope contract's per-event-type versioning.
+
+### 9.7 `credit.forfeited`
+
+Emitted on `locked → forfeited`. Subscribers: Delivery (re-engagement workflow), Revenue (recognition of forfeited credits as recognized revenue per policy), Coaching (unsubtracts the slot in the availability projection), Platform warehouse.
+
+Payload v1:
+- `credit_reservation_id`
+- `lesson_id`
+- `forfeited_credits` (N)
+- `forfeiture_reason` (enum: `late_cancel`, `no_show`)
+- `forfeited_at`
+
+Forfeiture is always customer-side. Sguild-initiated cancellations emit `credit.released`, never `credit.forfeited`, regardless of timing.
+
+## 10. Auto-transitions and scheduled jobs
+
+Three Revenue-owned scheduled jobs implement the state machine's time-based transitions:
+
+**Reservation Job (T-24h lock check).** Runs at T-24h before each scheduled lesson. For each `reserved` reservation: if `funded`, transition to `locked` and post the Reservation Lock Debit entry; if `pending`, transition to `released` with `initiator=system_unpaid` and post no ledger entry.
+
+**Lesson Completion Job.** Runs after lesson delivery (triggered by Delivery' `lesson.delivered` event). Transitions `locked → consumed`. Posts the Adjustment entry (reason Credits Consumed) and the Lesson Debit entry.
+
+**Forfeit Job.** Runs after a no-show is recorded by Delivery or after a customer late-cancellation is processed. Transitions `locked → forfeited`. Posts the Adjustment entry (reason Credits Forfeited) and the Credit Forfeit entry.
+
+Each job SHALL be idempotent: if it runs twice for the same reservation, it produces the same ledger footprint. Idempotency keys SHALL include the `credit_reservation_id` and the target terminal state.
+
+If any job fails, retries SHALL re-run the job atomically; partial state is not allowed (e.g., Adjustment posted but Lesson Debit missing must be reconciled before the lock is considered dissolved).
+
+### 10.1 Auto-release subset cascades (v1.1.0)
+
+The five auto-release `reason_code` values in §6.1 (`site_closure`, `coach_unavailable_reschedule_failed`, `force_majeure`, `weather`, `administrative_void`) name cancellation causes whose per-reservation transitions fire automatically without operator approval at the lock-state-machine boundary. The auto-release subset cascades through the existing `reserved → released` and `locked → released` transitions in §4.3; this section does not add new transitions.
+
+Two notes on the operator's role with auto-release values:
+
+For `force_majeure` and `site_closure`, the declaration step (the operator declaring an event force-majeure for a program, site, region, or date range; the operator declaring a site closure) is operator-driven and lives at the Delivery scheduling layer. Once declared, per-reservation cancellations cascade automatically and emit on the credit-reservation-lock event surface with the corresponding `reason_code`. The declaration itself does not emit on the credit-reservation-lock surface in v1.1.0; if Phase-2 narrowing surfaces a need to expose the declaration event downstream, the additive-discipline accommodates a future `force_majeure_declared` or `site_closure_declared` value.
+
+For `coach_unavailable_reschedule_failed`, the determinism is configuration-bounded by the program's reschedule policy window. The window is operator-configured per-program; the per-reservation transition is automatic once the window expires.
+
+The four explicit-operator `reason_code` values (`customer_requested_in_window`, `customer_requested_exception`, `policy_exception`, `bad_debt_writeoff`) require operator confirmation of refund eligibility before the transition fires. The operator workflow for confirmation is Delivery-internal and out of scope for this contract.
+
+## 11. Versioning policy
+
+This contract follows the same semver discipline as the Identity Contract and the Event Envelope Contract:
+
+- **Patch:** editorial clarifications.
+- **Minor:** additive changes. New optional payload fields, new transition triggers that map to existing transitions, new enum values for `initiator`, `reversal_reason`, `forfeiture_reason`, `Adjustment.reason_code`, or `Created Via`.
+- **Major:** breaking changes. Removing or renaming states, removing transitions, removing entry types, breaking payload changes.
+
+State additions or removals are major version bumps. Adding a new entry type to the Entry Type enum is minor (additive). Adding a new Adjustment reason code is minor.
+
+Cancellation deadline policy is NOT versioned by this contract; it is a Revenue policy parameter that can change without contract bumps.
+
+## 12. Consumer responsibilities
+
+### 12.1 Idempotency
+Consumers MUST be idempotent over `event_id` per the Event Envelope contract.
+
+### 12.2 First-lock detection trust
+Delivery and Sales SHALL trust Revenue's `customer.handoff` emission as the authoritative first-lock signal. Consumers SHALL NOT independently compute "is this Person's first lock"; that determination belongs to Revenue.
+
+### 12.3 State machine state is Revenue's
+Consumers MAY observe state via events but the authoritative state of any reservation is Revenue's. To query current state, consumers call Revenue's API; consumers SHALL NOT maintain their own copy of reservation state for authoritative use.
+
+### 12.4 Cancellation submission
+Cancellation events from Delivery or Sales (a customer cancels through their portal, an ops staff cancels on behalf of a customer) SHALL be submitted to Revenue as cancellation requests with `initiator` and `reason_code`. Revenue runs the state machine and emits the resulting transition event. Consumers SHALL NOT directly emit `credit.released` or `credit.forfeited`. The Sales-callable reservation-release API is specified in `reservation-release-api.md`.
+
+### 12.6 Reservation creation
+
+Sales-originated close orchestration SHALL create the Revenue credit reservation through the Sales-callable reservation-create API specified in `reservation-create-api.md` before calling Delivery hold-create. The endpoint returns a Revenue `crr_` in lifecycle state `reserved`; it does not create a Delivery lesson hold or advance Delivery's lesson-hold state.
+
+### 12.7 Delivery state vocabulary
+
+Revenue lifecycle states and Delivery lesson-hold states are distinct vocabularies. The authoritative mapping is specified in `delivery-state-vocabulary.md`. Consumers SHALL NOT describe a Revenue `crr_` as being in Delivery `requested`, `held`, or `confirmed` state.
+
+### 12.5 Reschedule pattern
+Consumers wanting to reschedule a `locked` lesson SHALL submit a forfeit request followed by a new reservation, not a reschedule operation against the state machine.
+
+### 12.8 Atomic multi-create
+
+Sales-originated composite offers MAY use `POST /api/v1/reservations/atomic-multi-create` to create N reservations in a single Revenue transaction. Each item in the batch results in an independent `crr_` with its own lifecycle state, funding sub-state, lock job, release path, refund path, and ledger footprint. No composite reservation state or bundle-level ledger entry is introduced.
+
+Consumers:
+
+- SHALL submit one `Idempotency-Key` header scoped by `organization_id` for the whole batch.
+- SHALL include `originating_offer_id` once on the request envelope. Each item SHALL include a unique `offer_item_id` for per-item correlation. Consumers SHALL NOT repeat or disagree on `organization_id` or `person_id` across items; those fields live only on the envelope.
+- SHALL treat the endpoint as all-or-none on Revenue's side. If the endpoint returns a non-2xx response, none of the Revenue reservations were created and no `credit.reserved` events were emitted.
+- SHALL NOT assume that a successful Revenue multi-create atomically includes Delivery hold-creates. The Revenue-to-Delivery boundary remains a cross-service orchestration boundary; Sales owns the orchestration cleanup if Revenue multi-create succeeds but a subsequent Delivery hold-create fails (using the existing single-reservation release API per `reservation-release-api.md` for each returned `crr_`).
+- SHALL NOT use per-item idempotency keys. The single batch-level key guarantees all-or-none replay semantics; per-item keys would imply partial replay, which this endpoint does not support.
+
+HTTP 200 `result: "existing"` means all N lessons already had active Revenue reservations (idempotent replay). HTTP 201 `result: "created"` means all N were newly created. HTTP 409 `conflict_reason: "partial_existing_state"` means some lessons already had active reservations and some did not; Sales must investigate and not retry automatically.
+
+## 13. Producer responsibilities (Revenue)
+
+### 13.1 State machine implementation
+Revenue SHALL implement the state machine exactly as specified.
+
+### 13.2 Event emission
+Revenue SHALL emit exactly one event per state transition, on the Event Envelope, with the payload defined in §9.
+
+### 13.3 Ledger entry posting
+Revenue SHALL post the ledger entries specified in §8 for each state transition, with correct Entry Type, Created Via, signed amount, and references. Lock dissolution (Adjustment with reason) is universal at every `locked → terminal` transition.
+
+### 13.4 First-lock detection
+Revenue SHALL track per-Person "first lock fired" state and emit `customer.handoff` exactly once per Person, on the first `credit.locked`.
+
+### 13.5 Scheduled jobs
+Revenue SHALL run the Reservation Job, Lesson Completion Job, and Forfeit Job per §10. Each job SHALL be idempotent.
+
+### 13.6 Cancellation policy
+Revenue SHALL maintain the cancellation policy as a black-box query. Per-Org and per-tier overrides are policy-internal.
+
+### 13.7 Idempotent emission
+Revenue SHALL NOT emit duplicate events for the same state transition. Retries reuse the same `event_id`.
+
+### 13.9 Atomic multi-create (v1.4.0)
+
+Revenue SHALL implement `POST /api/v1/reservations/atomic-multi-create` per §12.8. The implementation constraints are:
+
+- Revenue SHALL wrap all N `creditReservation.create` writes and all N `credit.reserved` event publishes in a single Prisma transaction. A validation failure on any item before the transaction opens rolls back all writes and no events emit.
+- Revenue SHALL accept `originating_offer_id` and per-item `offer_item_id` / `client_item_id` on the request and MAY persist them as audit correlation fields on the reservation record. Revenue SHALL NOT surface `originating_offer_id` on the `credit.reserved` event payload unless a later minor version adds it with a demonstrated consumer need.
+- Revenue SHALL enforce all-or-none idempotency at the batch level: same `Idempotency-Key` + same normalized batch payload returns the same full array. Same key + different normalized payload returns HTTP 409 with `conflict_reason: idempotency_payload_mismatch`.
+- Revenue SHALL NOT permit batch sizes larger than 20 items.
+- `customer.handoff` first-lock behavior is unchanged: if multiple reservations for the same Person lock in the same Reservation Job run, Revenue's first-lock implementation SHALL choose the earliest `lesson_starts_at` as the deterministic first lock, with `credit_reservation_id` as the tiebreaker. The `customer.handoff` payload remains singular and unchanged from v1.0.0.
+
+### 13.8 reason_code emission on credit.released v2 (v1.1.0)
+
+From the cutover date specified in §16's v1.1.0 change log entry, Revenue SHALL include the `reason_code` field on every `credit.released` envelope at payload schema_version 2, populated from one of the values in §6.1. The value SHALL be drawn from the cancellation policy's input alongside `initiator` and `reversal_reason`. Before the cutover date, Revenue continues to emit at schema_version 1 with `reason_code` omitted; consumer behavior follows the additive-discipline pattern in §11.
+
+Revenue's `cancellationPolicy` (§6) accepts `reason_code` as an input and routes the resulting transition state alongside `initiator` and `reversal_reason`. The policy backend's mapping from `reason_code` to the resulting transition state is Revenue-internal; the contract surface is the input-and-output shape of the policy plus the emission obligation.
+
+## 14. Security and privacy
+
+### 14.1 PII in payloads
+Payloads carry `person_id`, `credit_reservation_id`, and, once Delivery has minted it, `lesson_id`, all pseudonymous. No contact information; comms routing for related notifications goes through Platform's identity service Guardian-aware comms-routing endpoint.
+
+### 14.2 Tenant isolation
+All state machine operations are tenant-scoped. Locks, credits, lessons, and Persons all carry `tenant_id`.
+
+### 14.3 Audit trail
+The state machine's events plus the ledger entries together form the audit trail. Replaying the events for a Person reconstructs the credit lifecycle.
+
+## 15. Future work
+
+- **Partial forfeiture or partial release.** If policy evolves to support partial outcomes (e.g., 50% forfeit), payloads gain amount fields additively.
+- **Pack expiration.** Currently no expiration. If introduced later, requires lot-level accounting (a non-trivial v1.x or v2 change).
+- **Multi-credit-account billing for group lessons.** Currently single-account per lesson. If group billing models change, the contract needs extension.
+- **Subscription credits.** If credit replenishment becomes recurring (subscription model rather than packs), the Purchase Credit entry type and `credit.purchased` event may need additional fields.
+- **Reschedule-as-first-class operation.** If forfeit-and-rebook becomes too punitive operationally, a `locked → reserved` transition might be introduced for limited reschedule scenarios. Defer until policy demands.
+
+## 16. Change log
+
+- **v1.4.1** (2026-05-19): Patch. Corrects the default credit unit from 5 minutes per credit to 10 minutes per credit. A 30-minute lesson costs 3 credits and a 60-minute lesson costs 6. No lifecycle state, transition, event payload, ledger entry type, funding sub-state, cancellation policy, lock timing, or `customer.handoff` behavior changes.
+- **v1.4.0** (2026-05-19): Additive minor. Adds `POST /api/v1/reservations/atomic-multi-create` for Sales-originated composite offers (§12.8, §13.9). The endpoint wraps N Revenue reservation creates in a single Prisma transaction, guaranteeing all-or-none semantics on Revenue's side. Each item results in an independent `crr_` with the full existing lifecycle. Adds `originating_offer_id` on request envelope and per-item `offer_item_id` / `client_item_id` for composite-offer correlation. No new `credit.*` event types, no new lifecycle states, no ledger entry type changes, no `customer.handoff` behavior change (first-lock determinism tiebreaker named in §13.9 for the multi-lock-in-same-job-run case: earliest `lesson_starts_at`, then `credit_reservation_id`). Revenue ack memo: `coordination/memos/2026/2026-05-18-revenue-composite-offer-reservation-position.md`. Implementation: `src/app/api/v1/reservations/atomic-multi-create/route.ts`.
+- **v1.3.0** (2026-05-16): Additive minor. Resolves the Sales, Delivery, and Revenue lesson-id sequencing contradiction on the Sales close path. Revenue reservation-create remains before Delivery hold-create, but `lesson_id` is optional on the reservation-create API and optional on `credit.reserved` v1 until Delivery mints the Delivery-owned `les_` during hold-create. Delivery's `delivery.lesson-hold.created` event, or an explicit reconciliation write, is the attachment point for adding `lesson_id` back to Revenue state. Memos: `2026-05-16-sales-revenue-reservation-create-lesson-id-sequencing-ask`, `2026-05-16-delivery-reservation-create-lesson-id-sequencing-answer`, `2026-05-16-revenue-reservation-create-lesson-id-sequencing-ack`.
+- **v1.2.1** (2026-05-16): Patch. Changes the default reservation lock and customer cancellation deadline from T-48h to T-24h. The lifecycle states, transition set, payload fields, event names, ledger entry types, lock-dissolution invariant, and first-lock `customer.handoff` coupling do not change. Revenue remains responsible for per-Org and per-tier policy overrides through the cancellation policy black box.
+- **v1.2.0** (2026-05-16): Additive minor. Adds three authoritative sub-specs: `reservation-create-api.md` for the Sales-callable reservation-create endpoint, `reservation-release-api.md` for the Sales-callable cancellation or release submission endpoint, and `delivery-state-vocabulary.md` for the mapping between Revenue lifecycle states and Delivery lesson-hold states. Updates §3 to use Revenue's live `crr_` reservation prefix, adds §12.6 and §12.7, and amends §12.4 to point cancellation submissions at the release API sub-spec. No event payload, ledger-entry, or lifecycle transition changes.
+- **v1.1.0** (2026-05-08): Additive minor. Adds the `reason_code` field to `credit.released` payload at schema_version 2, partitioned into auto-release and explicit-operator subsets per §6.1. Adds §6.1 (auto-release versus explicit-operator subsets), §10.1 (auto-release subset cascades), and §13.8 (reason_code emission on credit.released v2). Producers SHALL emit `reason_code` from the cutover date 2026-05-22 (v1.1.0 publish date plus 14 days); before the cutover, producers continue to emit at schema_version 1 with `reason_code` omitted. Consumers MAY rely on `reason_code` from the cutover date. v1 consumers continue to work indefinitely; the new field is safe-to-ignore per §11. ADR-0006 is amended in parallel with a dated note under Decision; original body preserved. Phase-2 narrowing of the enum (tightening permissive values, retiring unused ones, adding values operators surface during the policy work) lands as later v1.x patches under the additive-discipline. Memos: `2026-04-28-revenue-refund-against-canceled-lessons` (the original gap), `2026-05-02-delivery-refund-cancellation-reason-codes` (Delivery's proposal), `2026-05-08-revenue-refund-reason-codes-signoff` (Revenue's signoff with reframings), `2026-05-08-delivery-reason-codes-signoff-accepted` (Delivery's confirmation closing the Phase-1 contract-shape conversation).
+- **v1.0.1** (2026-04-27): Editorial. Replaced "Operations" with "Delivery" throughout to match the renamed domain (Operations was briefly canonical earlier in 2026 and was renamed back to Delivery on 2026-04-27 to avoid collision with the company-level Operations function). No state, transition, event, payload, ledger entry type, reason code, or job behavior changed. Consumers running against v1.0.0 are interface-compatible with v1.0.1.
+- **v1.0.0** (2026-04-25): Initial release. Five-state machine (reserved, locked, consumed, released, forfeited) with funding sub-state on reserved. Six entry types in the credit ledger. Seven Created Via values. Four Adjustment reason codes for lock dissolution; additional reason codes reserved for goodwill and extenuating-circumstance adjustments without contract bumps. Seven domain events plus the customer.handoff coupling on first lock. N-parameterized credit amounts (credit-unit default corrected to 10 minutes per credit in v1.4.1; trials use reduced N per offering). Group lessons charge one credit account regardless of participant count. Rescheduling locked lessons requires forfeit + rebook.

package/contracts/credit-reservation-lock/delivery-state-vocabulary.md

@@ -0,0 +1,73 @@
+# Credit Reservation Lock, Delivery State Vocabulary Mapping
+
+**Status:** v1.0.0
+**Date:** 2026-05-16
+**Owner:** Revenue and Delivery
+**Consumers:** Sales close orchestration, Delivery scheduling, Revenue ledger reconciliation, Coaching lock-aware projection
+**Parent contract:** Credit Reservation Lock Contract v1.2.0
+
+## 1. Purpose and scope
+
+This sub-spec reconciles two related vocabularies:
+
+- Revenue's credit reservation lifecycle, expressed on the Revenue `crr_` record and emitted through `credit.*` events.
+- Delivery's lesson-hold state, expressed on the Delivery reservation-lock or lesson-hold record and emitted through `delivery.lesson-hold.*` events.
+
+The two vocabularies are intentionally not the same enum. They describe linked records at different ownership boundaries. Consumers SHALL use the vocabulary of the surface they are reading or writing and SHALL NOT infer one enum value as a stored value on the other domain's record.
+
+## 2. Revenue lifecycle states
+
+Revenue lifecycle states are authoritative for commercial state and ledger effects:
+
+| Revenue lifecycle state | Meaning |
+|---|---|
+| `reserved` | Revenue has created the credit reservation claim. No lock debit has posted. |
+| `locked` | Revenue has posted the Reservation Lock Debit at the lock boundary. |
+| `consumed` | Lesson delivery completed and Revenue posted the consumption ledger pattern. |
+| `released` | Reservation released without final customer debit. |
+| `forfeited` | Customer-side forfeiture posted. |
+
+Revenue owns these states and the `credit.*` events that report transitions among them.
+
+## 3. Delivery lesson-hold states
+
+Delivery lesson-hold states are authoritative for scheduling hold state:
+
+| Delivery state | Meaning |
+|---|---|
+| `requested` | Sales has a Revenue `crr_` reservation available for Delivery hold-create, but Delivery has not yet created the lesson hold. |
+| `held` | Delivery created the lesson hold against the Revenue reservation. |
+| `confirmed` | Delivery sees the lesson hold as confirmed for scheduling execution. Funding has cleared from the Delivery-facing point of view. |
+| `consumed` | Delivery has recorded lesson completion for the hold. |
+| `released` | Delivery has released or cancelled the hold. |
+
+Delivery owns these states and the `delivery.lesson-hold.*` events that report scheduling-side facts.
+
+## 4. Mapping
+
+The common close-orchestration mapping is:
+
+| Flow point | Revenue lifecycle | Delivery lesson-hold state | Notes |
+|---|---|---|---|
+| After Sales reservation-create succeeds | `reserved` | `requested` context exists for Delivery hold-create | `requested` is not stored on the Revenue `crr_`. It is the Delivery-side pre-hold condition that a live `reserved` Revenue reservation can satisfy. |
+| After Delivery hold-create succeeds | `reserved` | `held` | Revenue remains `reserved`; Delivery has accepted the hold. |
+| After funding clears before lock debit | `reserved` with funding state `funded` | `confirmed` or `held` depending on Delivery execution policy | Funding state is Revenue-owned. Delivery may expose `confirmed` as its scheduling state, but Revenue lifecycle is still `reserved` until lock. |
+| After T-24h lock job succeeds | `locked` | `confirmed` | Revenue has posted the lock debit. Delivery state usually remains `confirmed`. |
+| After lesson completion | `consumed` | `consumed` | Terminal states align by name but are still stored on different records. |
+| After release before lock | `released` | `released` | No lock debit reversal is needed on the Revenue side. |
+| After release after lock | `released` | `released` | Revenue posts the lock reversal pattern. |
+| After customer late cancellation or no-show | `forfeited` | `released` or terminal cancellation state | Delivery does not expose `forfeited` in v1.0.0. Consumers needing forfeiture truth read Revenue. |
+
+## 5. Contract wording rule
+
+Contract text SHALL NOT say that a Revenue `crr_` is in Delivery `requested`, `held`, or `confirmed` state. It SHALL say one of:
+
+- A Revenue `crr_` is in Revenue lifecycle state `reserved`, `locked`, `consumed`, `released`, or `forfeited`.
+- A Delivery lesson hold or reservation-lock record is in Delivery state `requested`, `held`, `confirmed`, `consumed`, or `released`.
+- Delivery hold-create requires a live Revenue `crr_` in lifecycle state `reserved`, plus Delivery-side preconditions that allow creating a `requested → held` scheduling transition.
+
+This wording rule prevents consumers from branching on the wrong enum and keeps ledger authority in Revenue while scheduling authority stays in Delivery.
+
+## 6. Versioning
+
+Patch versions may clarify examples. Minor versions may add mapping rows for new Delivery states or Revenue lifecycle states that are additive on their parent contracts. Removing or renaming states in either parent contract is governed by that parent contract's major-version rules.