@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/coach-availability/README.v2.md

@@ -0,0 +1,263 @@
+# Coach Availability Contract v2.1.2
+
+**Status:** v2.1.3
+**Date:** 2026-05-19
+**Owner:** Coaching
+**Consumers:** Sales (offer construction at the close), Delivery (coach assignment at scheduling and lesson time)
+**Related ADRs:** ADR-0001, ADR-0003 amended, ADR-0005, ADR-0006, ADR-0008 (partially superseded), ADR-0018 (this version's load-bearing decision)
+**Validations:** `validation/sales-offer-construction.md`, `validation/delivery-assignment.md` (both updated alongside this version)
+
+## 1. Purpose and scope
+
+Coach availability is the shared concern Coaching exists to own. Sales reads availability and eligibility at offer-construction time to know whether a lesson can be promised before a credit reservation is requested. Delivery reads the same surface at assignment time to attach a coach to a confirmed lesson.
+
+v2.0.0 supersedes v1.0.0's per-slot model with a continuous-band model. Availability is returned as `{coach_id, date, free_intervals[], bookings[]}` rather than `{coach_id, window, state}` per slot. Eligibility responses gain a structured `why` field for ineligible coaches so consumers can debug without an out-of-band query. The travel-time eligibility constraint (drive from prior booked lesson, drive from home) is first-class in the eligibility math.
+
+v2.1.0 adds a lightweight roster read for consumer selector hydration. The roster read exposes Coaching-owned role facts and `person_id`; it does not expose canonical Person labels or market display labels. v2.1.1 adds `service_area_id` to availability booking overlays so consumers can show where an existing reservation sits before estimating drive time. v2.1.2 adds candidate-zip travel buffers to the availability read, computed by Coaching's travel-time matrix.
+
+Out of scope: coach assignment to a specific lesson (Delivery owns it; `coach.assigned` is a Delivery event), Person identity (Platform), the credit reservation lock state machine (Delivery and Revenue jointly per ADR-0006; Coaching is a subscriber), pricing, payroll. Capacity adjustments and certification publication remain v1.0.0 scope items and stay out of v2.0.0.
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY follow RFC 2119.
+
+## 3. Terminology
+
+- **Coach.** A Person with a `coa_` role record at Coaching. One Coach per Person per Organization. A Coach belongs to exactly one Market.
+- **Free interval.** A half-open `[start, end)` time range during which the coach is available, derived from `AvailabilityTemplate` and `AvailabilityException`, with bookings subtracted. Always expressed in ISO 8601 with timezone.
+- **Booking.** A row in `coaching.coach_lesson_booking` representing a lesson that the coach is on the hook for. State is one of `reserved | locked | consumed | released`.
+- **Eligibility.** The boolean predicate "may this Coach take this lesson," composed of (coach in lesson's Market) AND (lesson interval fits a free interval that day) AND (drive from prior booked lesson on the same day fits `maxInterLessonTravelMinutes`, else drive from `coach.zip` fits `maxDriveMinutesFromHome`) AND (required certifications held).
+- **Drive-time computation.** Performed by `coaching/modules/travel-time` against `coaching.zip_distance_cache`, with Google Maps Distance Matrix as the fresh-source provider and a heuristic fallback when the API key is unset. Tagged in the cache by `source`.
+- **Authoritative state.** Revenue's lock-state-machine record per ADR-0006. Coaching's `CoachLessonBooking` is eventually-consistent against the `credit.*` event stream.
+
+## 4. Surface
+
+Four read endpoints. All return `application/json`. All accept `organization_id` as a required parameter (tenancy scope, per ADR-0001).
+
+### 4.1 Availability read
+
+`GET /coaching/v2/availability`
+
+Query parameters:
+
+- `organization_id` (required, string). Tenancy scope.
+- `coach_id` (optional, string). If present, scope to a single coach. If omitted, return all coaches in the organization.
+- `market_id` (reserved, string). The v2.1.0 route returns HTTP 400 with `error: market_filter_not_supported` when this parameter is supplied. Coaching will enable this filter in a later minor once service-area to market mapping is hydrated into the read model.
+- `service_area_id` (optional, string). If present, scope to coaches who cover this service area. This is the live geography filter in v2.1.0.
+- `lesson_zip` (optional, string). Candidate lesson ZIP. When present, Coaching computes travel-matrix buffers around active bookings whose lesson ZIP differs from the candidate ZIP. Same-ZIP bookings produce no travel buffer.
+- `window_start` (required, ISO 8601 with timezone). Start of the read window.
+- `window_end` (required, ISO 8601 with timezone). End. Maximum span 31 days; longer reads return HTTP 400.
+
+Response (HTTP 200):
+
+```
+{
+  "as_of": "2026-05-16T18:42:11.123Z",
+  "organization_id": "org_...",
+  "coaches": [
+    {
+      "coach_id": "coa_...",
+      "market_id": null,
+      "days": [
+        {
+          "date": "2026-05-17",
+          "free_intervals": [
+            { "start": "2026-05-17T09:00:00-10:00", "end": "2026-05-17T15:30:00-10:00" }
+          ],
+          "bookings": [
+            {
+              "lesson_id": "les_...",
+              "start": "2026-05-17T10:00:00-10:00",
+              "end": "2026-05-17T11:00:00-10:00",
+              "service_area_id": "sva_...",
+              "lesson_zip": "75201",
+              "state": "locked",
+              "reservation_id": "crr_...",
+              "lock_id": "lck_..."
+            }
+          ],
+          "travel_buffers": [
+            {
+              "lesson_id": "les_...",
+              "start": "2026-05-17T09:40:00-10:00",
+              "end": "2026-05-17T10:00:00-10:00",
+              "minutes": 20,
+              "source": "google_maps",
+              "from_zip": "75248",
+              "to_zip": "75201",
+              "position": "before"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+`free_intervals` already has bookings and returned travel buffers subtracted; a consumer that wants to overlay bookings visually can use the arrays directly. `bookings` lists every booking on the coach for that date regardless of state (so released or consumed bookings show too, for historical reconciliation); consumers filter by `state` if they only want active ones. `service_area_id` is nullable and identifies the booked lesson's service area when Coaching has received that fact from Delivery or a backfill. `lesson_zip` is nullable and is the booked lesson ZIP Coaching used for travel-matrix buffer computation. Consumers that need a service-area display label SHALL hydrate it from Platform canonical geography.
+
+`travel_buffers` is present and may be empty. It is computed only when the request includes `lesson_zip`. Each buffer is tied to a booked `lesson_id`, carries its matrix `minutes`, and sits either immediately `before` or immediately `after` that booking. Same-ZIP comparisons produce no buffer. Missing booked-lesson ZIPs produce no buffer because Coaching cannot ask the matrix for a pair. Buffers may overlap each other and may overlap booked lessons; consumers should render them as explanatory overlays, not as distinct assignments.
+
+`as_of` is the eligibility composer's read instant; consumers SHOULD log this when surfacing availability to operators so stale-read traceability is intact.
+
+`market_id` in the response is nullable in v2.1.0. Until Coaching hydrates the service-area to market mapping into the read model, consumers MUST treat null as "not populated by Coaching" and use Platform canonical geography for market labels, timezones, and market-level grouping.
+
+### 4.2 Eligibility by lesson ID
+
+`GET /coaching/v2/eligibility/by-lesson`
+
+Query parameters:
+
+- `organization_id` (required).
+- `lesson_id` (required, string). The Delivery lesson ID. Coaching resolves the lesson's `lesson_address` (or `lesson_zip`), `lesson_start`, `lesson_end`, and `required_certifications[]` via a synchronous read against Delivery's lesson surface keyed by `lesson_id`. The `lesson.scheduled` event payload does not carry these fields today; the read-against-Delivery path is the contract's source of truth so Delivery's event surface does not need to widen on Coaching's behalf. If Delivery's lesson read fails or times out, Coaching returns HTTP 502 with `error: lesson_fetch_failed`; consumers MAY retry.
+
+Response (HTTP 200):
+
+```
+{
+  "as_of": "...",
+  "lesson_id": "les_...",
+  "eligible_coaches": [
+    { "coach_id": "coa_...", "why": "fits" }
+  ],
+  "ineligible": [
+    {
+      "coach_id": "coa_...",
+      "why": "drive_from_prev_too_long",
+      "detail": {
+        "previous_lesson_id": "les_...",
+        "previous_end": "2026-05-17T10:30:00-10:00",
+        "needed_minutes": 45,
+        "allowed_minutes": 30
+      }
+    }
+  ]
+}
+```
+
+The `why` enum values are `fits | no_band | drive_from_prev_too_long | drive_from_home_too_long | wrong_market | missing_cert | already_booked`. Each ineligible entry carries a `detail` object with the relevant inputs. Consumers MUST treat unknown `why` values as opaque ineligibility (forward-compatible expansion).
+
+### 4.3 Eligibility by description
+
+`GET /coaching/v2/eligibility/by-description`
+
+Query parameters:
+
+- `organization_id` (required).
+- `lesson_address` OR `lesson_zip` (at least one required). `lesson_address` is the street address; `lesson_zip` is a normalized ZIP code. Both are first-class locators per Sales' offer-construction shape (close-orchestration often has a resolved ZIP before a full address). When both are present, Coaching prefers the address for travel-time routing and uses the ZIP as a service-area validation. When only `lesson_zip` is present, Coaching resolves to a service area via `coaching.zip_service_area_cache` and runs travel-time at ZIP granularity.
+- `lesson_start` (required, ISO 8601 with timezone).
+- `lesson_end` (required, ISO 8601 with timezone). MUST be later than `lesson_start`.
+- `required_certifications` (optional, comma-separated cert IDs).
+- `preferred_coach_id` (optional). When present, the response sorts the preferred coach first in `eligible_coaches`.
+
+Response shape mirrors §4.2 minus the `lesson_id` field at the top. The response includes a `resolved_service_area_id` field so consumers can confirm which service area Coaching mapped the locator to.
+
+Error responses:
+
+- HTTP 400 with `error: missing_locator` when neither `lesson_address` nor `lesson_zip` is present.
+- HTTP 422 with `error: address_outside_service_areas` when an address-only request cannot be parsed to a known ZIP.
+- HTTP 422 with `error: zip_outside_service_areas` when a ZIP doesn't map to any service area in `zip_service_area_cache`.
+- HTTP 422 with `error: zip_ambiguous` when a ZIP maps to multiple service areas and the cache flags ambiguity (operator-repair surface).
+
+### 4.4 Coach roster read
+
+`GET /coaching/v2/roster`
+
+Query parameters:
+
+- `organization_id` (required, string). Tenancy scope.
+- `coach_id` (optional, string). If present, scope to one Coach.
+- `service_area_id` (optional, string). If present, scope to coaches whose home service area or coverage list includes this service area.
+- `market_id` (reserved, string). The v2.1.0 route returns HTTP 400 with `error: market_filter_not_supported` when this parameter is supplied. Coaching will enable this filter in a later minor once service-area to market mapping is hydrated into the read model.
+- `include_archived` (optional, boolean). Defaults to false. When false, archived coaches do not appear.
+
+Response (HTTP 200):
+
+```
+{
+  "as_of": "2026-05-19T14:00:00.000Z",
+  "organization_id": "org_...",
+  "coaches": [
+    {
+      "coach_id": "coa_...",
+      "person_id": "per_...",
+      "status": "active",
+      "home_service_area_id": "sva_...",
+      "service_area_ids": ["sva_..."],
+      "market_id": null,
+      "can_cross_service_areas": true,
+      "max_drive_minutes_from_home": 30,
+      "max_inter_lesson_travel_minutes": 20
+    }
+  ]
+}
+```
+
+This endpoint is for consumer selector hydration and roster scoping. It is not an identity endpoint. `person_id` is the key consumers use to read canonical Person labels from Platform. Market display name and timezone come from Platform canonical geography, not from Coaching.
+
+### 4.5 Address and ZIP → service-area resolution
+
+Eligibility routes on the lesson's locator (address or ZIP). Coaching maintains a zip-to-service-area lookup table (`coaching.zip_service_area_cache`) populated from Platform's canonical geography catalog plus an internal manual-override mechanism for zips that span multiple areas. The lookup is one read per eligibility call; misses fall back to "ask Platform" until the cache is warmed.
+
+When the input is `lesson_address` only, Coaching extracts the ZIP via a simple parser (a five-digit run in the address string, validated against `zip_service_area_cache`) and routes through the same path as `lesson_zip`. v2.0.0 does not call a geocoder; a future minor version may add one if address-only requests without parsable ZIPs become common.
+
+Ambiguous zips (one ZIP serving multiple service areas) are tagged in the cache as `source: ambiguous` and escalated to Platform via memo rather than resolved locally per Platform's canonical-geography ownership.
+
+### 4.6 Compatibility shim for v1.0.0
+
+The original v2 draft expected a two-week v1.0.0 compatibility shim. The v2-live implementation removed v1 routes during the big-bang internal rewrite instead. Consumers must use v2 endpoints. If the missing shim causes operational pain, file on the `2026-05-16-coaching-availability-v2-incoming` thread and Coaching will decide whether to stand up a temporary successor route from the v2 service layer.
+
+## 5. Producer responsibilities
+
+- Coaching SHALL compute eligibility from live state, not from a stale projection. `as_of` reflects the eligibility composer's read instant.
+- Coaching SHALL respect the travel-time fallback chain per `coordination/adrs/coaching/001-travel-time-engine-and-fallback.md`. When the response is computed against heuristic travel time, the response MAY include a `travel_time_source: "heuristic"` field at the coach level so consumers can flag approximate eligibility.
+- Coaching SHALL maintain `CoachLessonBooking` rows with eventually-consistent state against Revenue's `credit.*` stream and Delivery's lesson lifecycle events.
+- The freshness SLO from v1.0.0 stays: Coaching does not invent a stricter bound. Operators reading stale availability that costs offers is a Coaching incident.
+- Coaching SHALL NOT expose canonical Person labels or market display labels on the roster or availability response. It exposes `person_id` and geography ids so consumers can hydrate those labels from Platform.
+
+## 6. Consumer responsibilities
+
+- Consumers MUST treat unknown `why` enum values as opaque ineligibility.
+- Consumers MUST NOT depend on the slot quantization in the v1.0.0 shim past the deprecation window.
+- Consumers SHOULD log `as_of` when surfacing availability to operators.
+- Consumers that need coach display labels SHALL read Platform's Person facts API using `person_id` from the roster response. Consumers that need market display name or timezone SHALL read Platform canonical geography.
+
+## 7. Versioning and deprecation
+
+- v2.1.3 is the load-bearing version.
+- v1.0.0 is retired in the live implementation per §4.6.
+- Future minor versions (v2.x.0) MAY add new endpoints or new `why` enum values. Removing endpoints or removing `why` values is a major version bump.
+
+## 8. Cross-domain dependencies (resolved during v2 review)
+
+- **Delivery lesson lifecycle and hold event surface.** Per Delivery's 2026-05-16 ack, the registered lesson lifecycle events Coaching subscribes to are: `lesson.scheduled` (seeds booking facts: time, participant, organization, coach assignment if any, duration), `coach.assigned` (authoritative coach assignment per ADR-0008), `lesson.cancelled` (booking removed), `lesson.delivered` (post-delivery signal, equivalent of the original `consumed` notion). For Sales-originated holds, Coaching also consumes `delivery.lesson-hold.created` from the sales-scheduling-surface contract as scheduling-side evidence, including optional `lesson_zip` when Delivery can source it from the lesson site. `lesson.attended` exists for attendance reconciliation; Coaching subscribes only if participant-level attendance becomes load-bearing for eligibility, which it does not in v2.0.0.
+- **Booking state transitions.** `reserved | locked | released | consumed` semantics come from Revenue's `credit.*` stream, not from Delivery lesson events. This preserves the no-duplicate-financial-truth boundary per the credit-reservation-lock contract.
+- **Sales close-orchestration call site.** Sales acked the v2 shape; no enum changes required. Sales will carry `as_of` as the v2 freshness anchor.
+- **Platform canonical geography.** `service_area.market_id` exposure via the geography catalog continues to be the authoritative source. Coaching additionally builds a zip-to-service-area cache populated from Platform's catalog; if a zip's service area attribution becomes ambiguous (e.g., a zip spans multiple service areas), Coaching escalates to Platform via a separate memo rather than resolving the ambiguity locally.
+
+## 9. Sub-specs
+
+None for v2.1.0. The surface is small enough to fit here. v2.x.0 sub-specs (e.g., a partial-band scheduling surface for multi-coach lessons) live as siblings to this README when they land.
+
+## 10. Change log
+
+### v2.1.3 (2026-05-19)
+
+Patch clarification. Documents Coaching's subscription to Delivery's `delivery.lesson-hold.created` scheduling-side event for Sales-originated holds, including optional `lesson_zip` when sourced by Delivery. No availability response shape changes.
+
+### v2.1.2 (2026-05-19)
+
+Add optional `lesson_zip` to `GET /coaching/v2/availability` and return per-day `travel_buffers[]` computed from Coaching's travel-time matrix. Same-ZIP comparisons produce no buffer. Returned free intervals subtract both active bookings and returned travel buffers so Sales offer construction sees the same travel spacing the lane overlay shows.
+
+### v2.1.1 (2026-05-19)
+
+Add `service_area_id` to each availability `bookings[]` row for Sales swim-lane reservation overlays. The field is additive and nullable; labels remain Platform canonical geography, not Coaching-owned text.
+
+### v2.1.0 (2026-05-19)
+
+Add `GET /coaching/v2/roster` as a lightweight roster read for Sales and Delivery selector hydration. Clarify that coach display labels come from Platform Person facts via `person_id`, and market display labels plus timezone come from Platform canonical geography. Reconcile the `market_id` filter with the deployed route behavior by reserving it until Coaching hydrates service-area to market mapping into the read model; `service_area_id` is the live filter in this version.
+
+### v2.0.0 (2026-05-16)
+
+Initial continuous-band v2 surface. Availability returns per-coach, per-day free intervals plus bookings. Eligibility routes return structured `why` values and use lesson address or ZIP for travel-time-aware service-area routing.

package/contracts/coach-availability/schema/payloads/coach.assigned-v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://contracts.sguild/coach-availability/schema/payloads/coach.assigned-v1.json",
+  "title": "coach.assigned payload v1",
+  "description": "Payload for the coach.assigned event_type per ADR-0008. Delivery is the single writer for coach assignment facts; Coaching consumes this event to update its assigned-vs-eligible projection. The payload is PII-free.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "lesson_id",
+    "previous_coach_id",
+    "coach_id",
+    "participant_id",
+    "lesson_site_id",
+    "service_area_id",
+    "lesson_type_id",
+    "window",
+    "assigned_at"
+  ],
+  "properties": {
+    "lesson_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "previous_coach_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "coach_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "participant_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "lesson_site_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "service_area_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "lesson_type_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "window": {
+      "$ref": "#/$defs/window"
+    },
+    "assigned_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "$defs": {
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "start",
+        "end"
+      ],
+      "properties": {
+        "start": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "end": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

package/contracts/coach-availability/validation/delivery-assignment.md

@@ -0,0 +1,89 @@
+# Validation: Delivery assignment
+
+**Contract:** `coach-availability` v1.1.0
+**Consumer:** Delivery (assignment-time eligibility, coach-day planner module)
+**Date:** 2026-05-16
+
+## Why this validation exists
+
+Delivery is the consumer that previously owned the surface this contract now exposes. Post-split, Delivery is a peer consumer of Coaching's read endpoints rather than the producer of an internal surface. This file documents what Delivery calls, when, with what inputs, and how Delivery's coach-assignment function and coach-day planner module compose the eligibility response with Delivery-side scheduling facts. The producer SHALL preserve this shape across patch and minor versions; any change that breaks Delivery's shape is a v2-class change.
+
+## Delivery's surface area
+
+Delivery calls the `coach-availability` contract at two points: at scheduling time (when a lesson is created and a coach is being assigned) and at lesson-day operations time (when the coach-day planner surfaces the operator's morning queue and re-validates assignments against current availability state).
+
+The contract is involved in eligibility reads only. The write that emits `coach.assigned` lives in Delivery's assignment module, not in Coaching, and is unchanged by the Coaching split.
+
+### Inputs Delivery has at assignment time
+
+- `organization_id`. Resolved from the lesson's organization context.
+- `lesson_id`. The `les_` identifier of the lesson being assigned. Always present at assignment time; the lesson record exists by the time Delivery calls Coaching for eligibility.
+
+Delivery does NOT pass `service_area_id`, `window`, `lesson_type_id`, or `required_certifications` directly. Those inputs are read by Coaching from Delivery's lesson surface, keyed off the `lesson_id`. The contract's design intent is that the producer (Coaching) reads inputs the producer cannot otherwise know (the lesson's program rule references), and the consumer (Delivery) passes only what the consumer owns (the lesson identity).
+
+### Endpoint Delivery calls
+
+`GET /coaching/v1/eligibility/by-lesson` per §4.2.1.
+
+Delivery does not call `POST /coaching/v1/eligibility/by-description` because Delivery always has a `les_` at assignment time. The by-description endpoint is for offer construction before a lesson record exists; that is Sales' shape.
+
+Delivery may call `GET /coaching/v1/availability` (§4.1) for operator-tooling display purposes (the coach-day planner's morning view, the "show me all coach availability across the next two weeks" overview). The availability endpoint is acceptable for read-only inspection; it is not the assignment-decision call.
+
+## Read frequency
+
+Delivery calls eligibility at three points in the assignment lifecycle:
+
+1. At scheduling time, when a lesson is first created and an automatic coach assignment is attempted. One call per lesson.
+2. At reassignment time, when an operator manually changes a coach assignment. One call per reassignment to validate the new coach is eligible.
+3. At lesson-day operations time, when the coach-day planner re-validates each upcoming assignment against current availability state to catch any drift since the original assignment. One call per active assignment per planner refresh; refresh cadence is operator-tooling-internal and not contract-defined.
+
+Read three is the most frequent. Coaching's producer SHOULD assume the by-lesson endpoint receives read traffic at a multiple of the active-assignment count per organization per refresh interval.
+
+## Stale-projection handling
+
+If the projection is stale at scheduling time (read one) and the slot has been taken between the response's `projection_as_of` and the moment Delivery commits the assignment, the assignment write into Delivery's storage layer succeeds locally (Delivery's storage does not gate on Coaching's projection), but the underlying credit-reservation-lock state on Revenue may already be `released` or `forfeited` for the original reservation, in which case the assignment is moot.
+
+Delivery SHALL handle this case by re-validating against the credit-reservation-lock contract before emitting `coach.assigned`. If the underlying reservation is not in `reserved` or `locked` state, Delivery SHALL NOT emit `coach.assigned`; the assignment is a Delivery-internal record that is not yet authoritative. Operator-tooling surfaces this state ("assignment pending lock confirmation").
+
+If the projection is stale at read three (planner refresh) and the projection says a coach is no longer available for an assignment that has already fired `coach.assigned`, the planner SHALL surface the discrepancy to the operator rather than auto-reassign. The discrepancy is informational; the authoritative assignment is Delivery's.
+
+## Coach-day planner integration
+
+`delivery/modules/coach-day/` is the planner that surfaces the operator's daily view. Pre-split, the planner imported directly from `delivery/modules/coach/` to compose Coach state with Lesson and Service Area facts into a Coach Day result type. Post-split, the planner consumes this contract for the coach-side facts and continues to own the Coach Day result type per the per-domain module pattern's rule "the module owns the result type."
+
+The rewrite per ADR-0008 action item 7 changes the planner's data flow but not its result type or its public surface. Specifically:
+
+The planner's `loadAllCoachProfiles` repo function (which today reads from Delivery's local Coach storage) becomes a contract call against Coaching's surface. The repo abstraction stays in `delivery/modules/coach-day/repo.ts`; only the implementation under it changes from a local read to a remote read.
+
+The planner's eligibility composition (which today computes capacity and certification matches in Delivery code) becomes consumption of Coaching's decomposed predicates from the eligibility response. The planner SHALL NOT re-implement the predicates locally; the contract's response is authoritative.
+
+The planner's `actions.ts` entry point (`getCoachDays`) remains as the user-vocabulary action; the operator-tooling surface is unchanged.
+
+The planner SHOULD batch contract reads where possible. The `by-lesson` endpoint is per-lesson; the `availability` endpoint covers a window across all coaches in a service area. For the planner's morning view (a service-area-wide read), the availability endpoint is the right call; for per-assignment validation, the by-lesson endpoint.
+
+## Boundary that does not move
+
+`coach.assigned` remains a Delivery emission per ADR-0008. The Coaching split does not relocate the assignment event; the contract does not produce assignment events; Delivery's assignment write authority is unchanged.
+
+Delivery continues to own:
+
+- The `delivery/modules/coach-day/` planner (composing module per the layout standard).
+- The `delivery/modules/coach-assignment/` module (or wherever the assignment write lives in Delivery's repo today; the module-layout standard's location rule does not change with the split).
+- Lesson, Lesson Site, Service Area, attendance, the lock state machine on the Delivery side per ADR-0006.
+- `coach.assigned` as the producer-of-record event for assignment.
+
+Delivery no longer owns:
+
+- `coa_` Coach role records (relocated to Coaching per the amended ADR-0003).
+- Coach availability and capacity (Coaching's per ADR-0008).
+- The eligibility predicate computation (Coaching's per §7.4 of the README).
+
+The boundary is "Coaching produces the eligibility answer; Delivery composes it with scheduling-side facts and emits the assignment."
+
+## Open questions Delivery reserves the right to raise
+
+None for v1.0.0. Delivery is the proposing domain for ADR-0008 and the drafting author of this contract; the surface reflects Delivery's actual consumption needs as best understood pre-stand-up. If a Delivery-side implementation surfaces a missing field or a mis-shaped response during action items 6 through 8, the change lands as a v1.x patch or minor (depending on whether the change is editorial or surface) per §5 of the README.
+
+## Sign-off
+
+Delivery is the proposing domain; sign-off on this contract is implicit in the parent thread's settlement and ADR-0008's acceptance. Delivery does not file a separate sign-off memo. Sales' sign-off on the parent thread is the gate before stand-up uses the contract per ADR-0008 action item 4.

package/contracts/coach-availability/validation/sales-offer-construction.md

@@ -0,0 +1,76 @@
+# Validation: Sales offer construction
+
+**Contract:** `coach-availability` v1.1.0
+**Consumer:** Sales (offer-construction surface, closing seam)
+**Date:** 2026-05-16
+
+## Why this validation exists
+
+Sales is the consumer that prompted the Coaching split. The ownership change matters only if Sales' offer-construction shape lands as a first-class consumer of the contract rather than a Delivery-helper that Sales happens to call. This file documents what Sales calls, when, with what inputs, and how Sales handles stale-projection cases. The producer SHALL preserve this shape across patch and minor versions; any change that breaks Sales' shape is a v2-class change.
+
+## Sales' surface area
+
+Sales calls the `coach-availability` contract at one logical point in the close orchestration: offer construction. The closing operator selects a Coach and a Window, then submits a reservation request to Revenue's credit-reservation-lock surface, then if the reservation lands Sales calls Delivery's assignment surface to attach the coach to the first lesson. The contract is involved in step one only; steps two and three are governed by the credit-reservation-lock contract and Delivery's assignment surface respectively.
+
+### Inputs Sales has at offer construction
+
+- `organization_id`. Resolved from the Lead's organization context.
+- `service_area_id`. Resolved from the Lead's location intake (address, region, or service-area selection during qualification).
+- `window`. The slot the operator and customer are negotiating, expressed as a half-open `[start, end)` interval in the customer's timezone.
+- `lesson_type_id`. The lesson type the offer is for (kid intro, adult lap, group lesson, etc.). Resolved from the Lead's program selection during qualification.
+- `required_certifications`. Derived from the lesson type's program-rule references. Sales reads program rules from a Sales-internal cache of lesson-type metadata; the source of truth lives in Delivery's lesson-type table, but Sales does not call Delivery for it on every offer.
+
+Sales does NOT have at offer construction: a `lesson_id` (no `les_` exists yet; the lesson record is created by Delivery on lock confirmation), a `coach_id` (the operator is choosing one from the eligibility response).
+
+### Endpoint Sales calls
+
+`POST /coaching/v1/eligibility/by-description` per §4.2.2.
+
+Sales does not call `GET /coaching/v1/availability` (§4.1) at offer construction. The availability endpoint is for inspection and operator-tooling overlays; the eligibility-by-description endpoint is the offer-construction call because it composes availability with capacity, service area, and certification predicates in a single response.
+
+## Read frequency
+
+Sales calls the eligibility endpoint multiple times per close. Typical shape:
+
+1. Operator opens an offer-construction view; Sales calls eligibility with the Lead's window of intent (a wide window around the customer's stated availability).
+2. Operator narrows the window during conversation; Sales re-calls eligibility with each material narrowing.
+3. Operator selects a coach and a slot; Sales calls eligibility one more time immediately before submitting the reservation request, to detect any in-flight changes since the operator's last view.
+
+Read three is the load-bearing one for stale-read handling. The interval between read three and the reservation submission to Revenue is the freshness window where a different operator's reservation could land in the projection's lag.
+
+## Stale-projection handling
+
+If the projection is stale at read three and the slot has been taken between the response's `projection_as_of` and Revenue's authoritative state at the moment Sales submits the reservation, the reservation request to Revenue returns a conflict. Sales SHALL:
+
+1. Treat the conflict as a normal-path race, not an error condition.
+2. Re-call eligibility with the same inputs (a fresh read).
+3. Surface to the operator that the slot was taken and offer the operator the next-best eligible slots from the fresh response.
+4. Not retry the original reservation request. The original window is no longer available; retrying would either fail again or claim a different slot than the one the operator selected.
+
+Sales SHALL NOT cache eligibility responses across operator commits. Caching at the operator-tooling layer for sub-second display purposes is acceptable; caching across commits is not.
+
+Sales SHALL log the `as_of` and `projection_as_of` values from each eligibility response so a stale-read root-cause is traceable. Operator-reported "the slot was free a second ago" is a normal-path event, not a Coaching incident, but the log line is needed to confirm the projection lag was within SLO.
+
+## Assignment-at-close orchestration
+
+Once the reservation lands at Revenue and the lock attaches, Sales orchestrates the first-lesson assignment by calling Delivery's assignment surface, not Coaching's. The relevant orchestration shape:
+
+1. Sales submits reservation request to Revenue, receives `crr_` and `lck_` (or the equivalent identifiers per the credit-reservation-lock contract).
+2. Sales calls Delivery's assignment surface (out of scope for this contract; lives in Delivery's repo) with the operator's chosen coach.
+3. Delivery's assignment surface validates eligibility one more time (Delivery calls Coaching's eligibility-by-lesson endpoint per §4.2.1; see `delivery-assignment.md`), assigns the coach if eligible, emits `coach.assigned` (per ADR-0008, `coach.assigned` is a Delivery event).
+
+Sales does NOT call `coach.assigned` directly. Sales does NOT write into Coaching's surface. Sales' role at the close ends with the reservation-and-assignment hand-off.
+
+## Identity and comms-routing
+
+Outbound communications to the Lead's Person (offer letter, lesson confirmation, scheduling instructions) route through Platform's Guardian-aware comms-routing endpoint per the identity contract. This is unchanged by the Coaching split; the routing rule applies uniformly across Sales' communications regardless of which domain the substantive content originates in.
+
+Outbound communications about the assigned Coach (mentioning the coach's name in an offer letter, for example) also route through Platform's Person facts API for the coach's identity fields. Sales does NOT read coach identity fields from this contract; the contract returns `coa_` references, not Person fields.
+
+## Open questions Sales reserves the right to raise
+
+None for v1.0.0. Sales' acknowledgment of the lock-aware position in `2026-05-01-sales-coaching-availability-ack` covered the substantive shape; this file is the documentation of that shape, not new ground. If Sales surfaces a future shape change (the softly-held v1.x extension is the most likely candidate per §9.1 of the README), it lands as a memo against the parent thread or as a fresh thread.
+
+## Sign-off
+
+Sales signs off by responding to the Delivery sibling memo announcing this contract's draft on the parent thread (`2026-05-01-delivery-coaching-split`). Sign-off is the trigger for promoting the contract from draft to merged in the coordination repo and for Coaching to begin the lock-event subscriber implementation per ADR-0008 action item 8.

package/contracts/coaching-confirmation/README.md

@@ -0,0 +1,96 @@
+# Coaching Confirmation
+
+**Status:** v1.1.0
+**Date:** 2026-05-18
+**Owner:** coaching (confirmation workflow)
+**Consumers:** sales (cadence Stage 3b), platform-warehouse (analytics ingestion)
+**Related ADRs:** ADR-0001 (tenant_id), ADR-0002 (canonical entity ID template), ADR-0005 (event envelope), ADR-0008 (Coaching domain boundary), ADR-0009 (dispatcher transport, producer transactional guarantee)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`), Lead Lifecycle Contract (`../lead-lifecycle/README.md`), Coach Availability Contract (`../coach-availability/README.md`)
+**Sub-specs (authoritative):** `schema/payloads/lead.coach.confirmation.requested-v1.json`, `schema/payloads/coaching.lesson.confirmation_decided-v1.json`
+**Validations:** none yet
+
+## 1. Purpose and scope
+
+This contract specifies the dispatcher handshake between Sales and Coaching for the Stage 3b coach-confirmation workflow. Sales requests a coach confirmation after a Lead enters the coach-confirmation stage. Coaching decides whether the proposed coach and lesson window are confirmed or denied, then emits a decision event back through dispatcher fanout.
+
+In scope: the inbound Sales request event name, the inbound Sales request payload schema, the outbound Coaching decision event name, the outbound Coaching decision payload schema, producer responsibilities, consumer responsibilities, and privacy rules for the confirmation handshake.
+
+Out of scope: Sales cadence-stage state transitions, Sales close-orchestration internals, coach eligibility reads, coach assignment writes, customer communications, and lesson outcomes. Availability remains in the coach-availability contract. Coach assignment remains Delivery-owned per ADR-0008.
+
+## 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
+
+**Confirmation request.** A Sales-produced request asking Coaching to confirm or deny a proposed coach for a proposed lesson window.
+
+**Confirmation decision.** Coaching's answer to a confirmation request. A decision is either `confirmed` or `denied`.
+
+**Confirmation request ID.** A Sales-minted idempotency and correlation key. Coaching echoes it on the decision event and uses it as the event subject.
+
+## 4. Event types
+
+### 4.1 `lead.coach.confirmation.requested`
+
+Produced by Sales. This event starts the handshake. Coaching consumes it to decide whether the proposed coach and lesson window are confirmed or denied. Platform warehouse may ingest it for confirmation latency, deny-rate, and re-engagement analytics.
+
+The event envelope subject SHALL be `confirmation_request_id`. The actor SHALL be the Sales operator or system actor that created the request. Payload v1 is authoritative at `schema/payloads/lead.coach.confirmation.requested-v1.json`.
+
+The request payload SHALL carry enough context for Coaching to decide without reading Sales state: `organization_id`, `lead_id`, `confirmation_request_id`, `coach_id`, `service_area_id`, `lesson_type_id`, `lesson_window`, optional `required_certifications`, `requested_at`, and an optional Sales source pointer for audit.
+
+### 4.2 `coaching.lesson.confirmation_decided`
+
+Produced by Coaching. Sales consumes this event to resolve Stage 3b. Platform warehouse may ingest it for confirmation latency, deny-rate, and re-engagement analytics.
+
+The event envelope subject SHALL be `confirmation_request_id`. The actor SHALL be the operator id that made the decision, or `system:coaching` only for future system-decided paths. Payload v1 is authoritative at `schema/payloads/coaching.lesson.confirmation_decided-v1.json`.
+
+Known `decision` values are `confirmed` and `denied`. Known `denial_reason` values at v1 are `coach_unavailable`, `capacity_changed`, `coverage_mismatch`, `certification_mismatch`, `operator_declined`, and `other`. Consumers MUST treat unknown future `denial_reason` values as opaque denial reasons.
+
+## 5. Producer responsibilities
+
+Coaching SHALL emit `coaching.lesson.confirmation_decided` exactly once per `confirmation_request_id` accepted into the decision workflow.
+
+Coaching SHALL publish the event in the same Prisma transaction as its local audit record, satisfying ADR-0009's producer-transactional guarantee.
+
+Coaching SHALL echo the request's `organization_id`, `lead_id`, `confirmation_request_id`, `coach_id`, `service_area_id`, `lesson_type_id`, and `lesson_window` on the decision payload so Sales can reconcile without a back-lookup.
+
+Coaching SHALL set `denial_reason` to null when `decision=confirmed` and to a non-null reason when `decision=denied`.
+
+Sales SHALL emit `lead.coach.confirmation.requested` in the same Prisma transaction as its local confirmation request or stage-transition record, satisfying ADR-0009's producer-transactional guarantee.
+
+Sales SHALL mint `confirmation_request_id` before publishing and persist it locally so the inbound Coaching decision can be correlated without reading dispatcher history.
+
+## 6. Consumer responsibilities
+
+Sales consumes `coaching.lesson.confirmation_decided` as the authoritative answer to its matching `lead.coach.confirmation.requested` event.
+
+Sales SHALL correlate by `confirmation_request_id`, not by coach or window alone.
+
+Sales SHALL deduplicate by dispatcher `event_id`. The event id is deterministic from `confirmation_request_id`, so replays of the same workflow decision do not create a second logical decision.
+
+Sales SHALL treat `notes` as operator context only. It MUST NOT depend on `notes` for state-machine transitions.
+
+## 7. Security and privacy
+
+This event intentionally avoids customer contact details, full lead notes, guardian details, and coach private contact details. It carries operational identifiers, the proposed lesson window, decision metadata, and optional short operator context.
+
+Producers and consumers MAY log ids, timestamps, decision, and denial reason. They SHOULD avoid long-lived logging of `notes` unless there is a clear operator need.
+
+## 8. Versioning
+
+This contract follows the additive discipline from the Event Envelope Contract. New optional fields and new denial reasons may land as v1.x changes when consumers can safely ignore them.
+
+Removing fields, renaming fields, changing `decision` semantics, changing correlation from `confirmation_request_id`, or adding content-bearing PII requires a major version bump and a deprecation window.
+
+Per-event `schema_version` is scoped to `coaching.lesson.confirmation_decided`.
+Per-event `schema_version` is scoped independently for `lead.coach.confirmation.requested` and `coaching.lesson.confirmation_decided`.
+
+## 9. Trigger to revisit
+
+Revisit this contract if Coaching needs to read Sales state to make the decision, if Delivery becomes a consumer, if the decision workflow becomes multi-step, or if Sales needs confirmation decisions to reserve capacity rather than merely drive cadence.
+
+## 10. Change log
+
+- **v1.1.0** (2026-05-18): Registers Sales-produced `lead.coach.confirmation.requested` under this contract and adds its v1 payload schema per `2026-05-17-sales-cadence-stage-map-sales-side-commitments`.
+- **v1.0.0** (2026-05-17): Initial release. Adds the dedicated confirmation handshake contract and the Coaching-produced `coaching.lesson.confirmation_decided` v1 event per `2026-05-17-coaching-cadence-confirmation-event-position`.