> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create N package sessions atomically (or best-effort) from one PACKAGE order item

> Books all sessions of a package against one PACKAGE order item. Provide exactly one source: slateId (book a whole slate — recommended; the server resolves times/supplier/location and fills the travel-zone location itself), slotIds (cherry-pick), or sessions (explicit). Booking does NOT require the order to be paid — credits exist from order creation — but a CANCELLED order books nothing (409 ORDER_CANCELLED), as package-slate refuses to plan from its credits. Note: this response is NOT wrapped in a { data } envelope, and created[].sessionIndex is 0-based. Returns 409 with freshSuggestions if a chosen slot went stale — regenerated from the stale slate's request but planned from THIS order item (its remaining sessions, offering and expiry), so they can be booked here; null when this item has nothing left to plan — or with code SLOT_HELD/SLOT_BOOKED naming the blocking claim if the requested time is taken. Every session must book the order item's own service and offering (400 ORDER_ITEM_SERVICE_MISMATCH); asking for more sessions than remain is 400 ORDER_ITEM_QUANTITY_UNAVAILABLE (409 with the same code only when a concurrent booking used them first). A session starting after the credit's `expiresAt` is 409 `PACKAGE_EXPIRED` (all_or_nothing refuses the whole call; best_effort reports it in `failed[]`); reusing an `idempotencyKey` with a different body is 409 `IDEMPOTENCY_KEY_CONFLICT`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/package-bookings
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/orders/{orderId}/package-bookings:
    post:
      tags:
        - Orders
      summary: >-
        Create N package sessions atomically (or best-effort) from one PACKAGE
        order item
      description: >-
        Books all sessions of a package against one PACKAGE order item. Provide
        exactly one source: slateId (book a whole slate — recommended; the
        server resolves times/supplier/location and fills the travel-zone
        location itself), slotIds (cherry-pick), or sessions (explicit). Booking
        does NOT require the order to be paid — credits exist from order
        creation — but a CANCELLED order books nothing (409 ORDER_CANCELLED), as
        package-slate refuses to plan from its credits. Note: this response is
        NOT wrapped in a { data } envelope, and created[].sessionIndex is
        0-based. Returns 409 with freshSuggestions if a chosen slot went stale —
        regenerated from the stale slate's request but planned from THIS order
        item (its remaining sessions, offering and expiry), so they can be
        booked here; null when this item has nothing left to plan — or with code
        SLOT_HELD/SLOT_BOOKED naming the blocking claim if the requested time is
        taken. Every session must book the order item's own service and offering
        (400 ORDER_ITEM_SERVICE_MISMATCH); asking for more sessions than remain
        is 400 ORDER_ITEM_QUANTITY_UNAVAILABLE (409 with the same code only when
        a concurrent booking used them first). A session starting after the
        credit's `expiresAt` is 409 `PACKAGE_EXPIRED` (all_or_nothing refuses
        the whole call; best_effort reports it in `failed[]`); reusing an
        `idempotencyKey` with a different body is 409
        `IDEMPOTENCY_KEY_CONFLICT`.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
        - schema:
            type: string
            minLength: 1
            description: >-
              The order — the commercial record. Order items are drawn down into
              bookings.
            example: ord_01kv8m92p4jcrywn14znp8cym0
          required: true
          description: >-
            The order — the commercial record. Order items are drawn down into
            bookings.
          name: orderId
          in: path
      requestBody:
        description: Order item + sessions + atomicity
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderItemId:
                  type: string
                  minLength: 1
                  description: >-
                    The PACKAGE order item to draw down. All N sessions
                    decrement its quantityRemaining.
                  example: oi_01kx16ek2kf2fsc9x7b2n1dfc9
                idempotencyKey:
                  type: string
                  minLength: 1
                  description: >-
                    Idempotency key that makes retry attempts safe; reusing it
                    returns the original result. A slateId/slotIds retry must
                    arrive within the slate's resolvable window; after that it
                    is refused like a stale slate.
                  example: a3f1c2e4-5b6d-4e7f-8a9b-0c1d2e3f4a5b
                atomicity:
                  type: string
                  enum:
                    - all_or_nothing
                    - best_effort
                  default: all_or_nothing
                  description: >-
                    all_or_nothing (default, one transaction, max 15 sessions)
                    or best_effort (per-session; requires project opt-in).
                  example: all_or_nothing
                sessions:
                  type: array
                  items:
                    type: object
                    properties:
                      supplierId:
                        type: string
                        minLength: 1
                        description: >-
                          The supplier who delivers the session. Must belong to
                          this project.
                        example: sup_01kx16ejb3fz2g5h8k1m4p7r9t
                      bookingStartUtc:
                        type: string
                        format: date-time
                        description: When the session starts, as an ISO 8601 UTC instant.
                        example: '2026-11-03T20:00:00.000Z'
                      bookingEndUtc:
                        type: string
                        format: date-time
                        description: When the session ends, as an ISO 8601 UTC instant.
                        example: '2026-11-03T20:30:00.000Z'
                      bookingTz:
                        type: string
                        minLength: 1
                        description: >-
                          The session's home zone (IANA). The booking's local
                          date and times are derived from the UTC instants in
                          this zone.
                        example: America/Toronto
                      locationType:
                        type: string
                        enum:
                          - PHYSICAL
                          - VIRTUAL
                          - TRAVEL_ZONE
                        description: >-
                          Where the session happens: PHYSICAL (at a venue;
                          locationId required), TRAVEL_ZONE (at the client's
                          address; locationId is the supplier's travel zone, and
                          latitude, longitude and address are required) or
                          VIRTUAL (online; locationId must be null).
                        example: VIRTUAL
                      locationId:
                        type: string
                        nullable: true
                        minLength: 1
                        description: >-
                          The venue (PHYSICAL) or supplier travel zone
                          (TRAVEL_ZONE). Null for VIRTUAL.
                        example: loc_01kx16ejc7fq4r6s9v2x5z8b1d
                      latitude:
                        type: number
                        nullable: true
                        description: >-
                          Latitude of the client's address. Required for
                          TRAVEL_ZONE.
                        example: 43.6532
                      longitude:
                        type: number
                        nullable: true
                        description: >-
                          Longitude of the client's address. Required for
                          TRAVEL_ZONE.
                        example: -79.3832
                      address:
                        $ref: '#/components/schemas/Address'
                      services:
                        type: array
                        items:
                          type: object
                          properties:
                            serviceId:
                              type: string
                              minLength: 1
                              description: >-
                                The service this session books. Must be the
                                order item's own service.
                              example: srv_01kx16ej8wfp0b4v3x1q7m2d5c
                            offeringId:
                              type: string
                              minLength: 1
                              description: >-
                                The offering this session books. Must be the
                                order item's own offering.
                              example: off_01kx16ej9af1c3s8t6y2w4n7hb
                          required:
                            - serviceId
                            - offeringId
                        minItems: 1
                        description: >-
                          The service lines of the session: the order item's
                          service and offering.
                        example:
                          - serviceId: srv_01kx16ej8wfp0b4v3x1q7m2d5c
                            offeringId: off_01kx16ej9af1c3s8t6y2w4n7hb
                    required:
                      - supplierId
                      - bookingStartUtc
                      - bookingEndUtc
                      - bookingTz
                      - locationType
                      - services
                  minItems: 1
                  description: >-
                    Explicit, client-supplied sessions (advanced). Prefer
                    slateId. Provide exactly one of sessions, slateId, or
                    slotIds.
                slateId:
                  type: string
                  minLength: 1
                  description: >-
                    Book an entire persisted slate by id (recommended). The
                    server resolves every session; send no session details.
                  example: slate_01kx16ejsqffc9rbgdcc591w2p
                slotIds:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  description: >-
                    Cherry-pick specific persisted slots by id. Provide exactly
                    one of sessions, slateId, or slotIds.
                  example:
                    - slot_01kx16ejsrfs7tf3edy19wdsf8
              required:
                - orderItemId
                - idempotencyKey
      responses:
        '201':
          description: Package bookings created
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string
                  orderItemId:
                    type: string
                  packageOrderItemId:
                    type: string
                  atomicity:
                    type: string
                    enum:
                      - all_or_nothing
                      - best_effort
                  created:
                    type: array
                    items:
                      type: object
                      properties:
                        sessionIndex:
                          type: integer
                          minimum: 0
                        bookingId:
                          type: string
                        allocationId:
                          type: string
                      required:
                        - sessionIndex
                        - bookingId
                        - allocationId
                    description: >-
                      Bookings created, each with a 0-based sessionIndex,
                      bookingId and allocationId.
                  failed:
                    type: array
                    items:
                      type: object
                      properties:
                        sessionIndex:
                          type: integer
                          minimum: 0
                        reason:
                          type: string
                      required:
                        - sessionIndex
                        - reason
                    description: Per-session failures (best_effort only).
                  quantityRemaining:
                    type: integer
                    minimum: 0
                    description: Credits left on the order item after this call.
                required:
                  - orderId
                  - orderItemId
                  - packageOrderItemId
                  - atomicity
                  - created
                  - failed
                  - quantityRemaining
        '400':
          description: >-
            Validation error, a session for another service/offering, more
            sessions than remain, or a location of the wrong type / another
            supplier’s / with invalid fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Order / item / offering / supplier / location not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: >-
            PACKAGE_EXPIRED, ORDER_CANCELLED (a cancelled order),
            ORDER_ITEM_QUANTITY_UNAVAILABLE (a concurrent booking used the
            credits first), IDEMPOTENCY_KEY_CONFLICT, SLOT_HELD/SLOT_BOOKED
            (supplier time held/booked), OCCUPANCY_CONTENTION (the calendar is
            under contention), or the slate/slot went stale (freshSuggestions
            returned)
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorMessage'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - SLOT_HELD
                          - SLOT_BOOKED
                        description: Which kind of claim is blocking the requested time.
                        example: SLOT_HELD
                      message:
                        type: string
                        description: Human-readable summary of the conflict.
                        example: >-
                          Supplier time is not available: HOLD
                          resv_01kv8p20m1gnqvxl92xln6awk8
                          (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)
                      statusCode:
                        type: number
                        enum:
                          - 409
                        description: >-
                          The HTTP status, repeated in the body — every
                          MarketBox error carries it, so you can branch on the
                          body alone.
                        example: 409
                      requestId:
                        type: string
                        description: >-
                          The id of this request (also returned as the
                          X-Request-Id header). Quote it in a support ticket.
                        example: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
                      conflicts:
                        type: array
                        items:
                          type: object
                          properties:
                            claimType:
                              type: string
                              enum:
                                - BOOKING
                                - HOLD
                              description: >-
                                Whether the blocking claim is a HOLD or a
                                confirmed BOOKING.
                            supplierId:
                              type: string
                              nullable: true
                              description: >-
                                The supplier whose calendar is blocked, when
                                known.
                            startUtc:
                              type: string
                              format: date-time
                              description: Start of the blocking claim, UTC ISO 8601.
                              example: '2026-08-01T10:00:00Z'
                            endUtc:
                              type: string
                              format: date-time
                              description: End of the blocking claim, UTC ISO 8601.
                              example: '2026-08-01T11:00:00Z'
                            reservationId:
                              type: string
                              nullable: true
                              description: >-
                                Present when claimType is HOLD — the
                                reservationId to convert or release. Null for a
                                BOOKING conflict.
                              example: resv_01kv8p20m1gnqvxl92xln6awk8
                            bookingId:
                              type: string
                              nullable: true
                              description: >-
                                Present when claimType is BOOKING — the id of
                                the confirmed booking occupying this time. Null
                                for a HOLD conflict.
                              example: null
                            heldUntil:
                              type: string
                              nullable: true
                              format: date-time
                              description: >-
                                HOLD only: when the blocking hold lazily
                                expires. Null for a BOOKING conflict.
                              example: '2026-08-01T10:05:00Z'
                          required:
                            - claimType
                            - startUtc
                            - endUtc
                        description: >-
                          Every live claim that overlaps the requested time —
                          usually one, but can be more.
                      hint:
                        type: string
                        description: >-
                          What to do next: for SLOT_HELD, convert or release the
                          named reservationId (POST
                          .../holds/{reservationId}/convert or /release); for
                          SLOT_BOOKED, search availability again.
                        example: >-
                          This time is held (reservation
                          resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via
                          POST
                          /v1/projects/{projectId}/holds/{reservationId}/convert,
                          or release it with POST
                          /v1/projects/{projectId}/holds/{reservationId}/release.
                          Direct booking routes will not consume a hold — if you
                          hold, you convert.
                    required:
                      - code
                      - message
                      - statusCode
                      - requestId
                      - conflicts
                      - hint
                  - type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      statusCode:
                        type: number
                        enum:
                          - 409
                        description: >-
                          The HTTP status, repeated in the body — every
                          MarketBox error carries it, so you can branch on the
                          body alone.
                        example: 409
                      requestId:
                        type: string
                        description: >-
                          The id of this request (also returned as the
                          X-Request-Id header). Quote it in a support ticket.
                        example: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
                      freshSuggestions:
                        type: object
                        nullable: true
                        properties:
                          searchId:
                            type: string
                            description: >-
                              The id of this search, also returned as the
                              `X-MB-Search-Id` header. Every page of a paginated
                              search carries the same id (the cursor keeps it).
                              Keep it for the session if you want attribution:
                              pass it back as `searchId` when the client books,
                              and in the `search.rendered` event when you report
                              what you showed.
                            example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
                          status:
                            type: string
                            enum:
                              - OK
                              - ALTERNATIVE_CADENCE
                              - NO_COMPLETE_SLATE
                              - NO_AVAILABILITY
                            description: >-
                              OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or
                              NO_AVAILABILITY. ALTERNATIVE_CADENCE is only
                              reachable when this request opted in via
                              cadenceFlexibility or guaranteeSlate — a request
                              sending today’s body (neither set) never observes
                              it.
                          reason:
                            type: string
                            nullable: true
                          suggestionRequestId:
                            type: string
                            nullable: true
                            description: >-
                              Audit id for this suggestion request (present when
                              persisted).
                          resolvableUntil:
                            type: string
                            nullable: true
                            format: date-time
                          primarySlate:
                            type: object
                            nullable: true
                            properties:
                              slateId:
                                type: string
                                description: >-
                                  Pass this to POST .../package-bookings to book
                                  the whole plan.
                                example: slate_01kx16ejsqffc9rbgdcc591w2p
                              supplierId:
                                type: string
                              completeness:
                                type: string
                                enum:
                                  - COMPLETE
                                  - PARTIAL
                              sessionsRequested:
                                type: integer
                                minimum: 0
                                exclusiveMinimum: true
                                description: >-
                                  How many sessions were requested (the
                                  package's creditCount).
                              sessionsFilled:
                                type: integer
                                minimum: 0
                                description: >-
                                  How many of the requested sessions the plan
                                  could fill.
                              startTimeConsistencyPercent:
                                type: number
                                minimum: 0
                                maximum: 100
                              totalTravelTimeMins:
                                type: number
                                minimum: 0
                              slots:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    slotId:
                                      type: string
                                      description: >-
                                        Id of one session; pass a subset of
                                        these as slotIds to cherry-pick.
                                    sessionIndex:
                                      type: integer
                                      minimum: 0
                                      exclusiveMinimum: true
                                      description: >-
                                        1-based index of this session within the
                                        slate.
                                    supplierId:
                                      type: string
                                    serviceId:
                                      type: string
                                    offeringId:
                                      type: string
                                    bookingStartUtc:
                                      type: string
                                      format: date-time
                                    bookingEndUtc:
                                      type: string
                                      format: date-time
                                    bookingTz:
                                      type: string
                                    locationType:
                                      type: string
                                      enum:
                                        - PHYSICAL
                                        - VIRTUAL
                                        - TRAVEL_ZONE
                                    locationId:
                                      type: string
                                      nullable: true
                                    latitude:
                                      type: number
                                      nullable: true
                                    longitude:
                                      type: number
                                      nullable: true
                                    address:
                                      $ref: '#/components/schemas/Address'
                                    travelTimeMins:
                                      type: number
                                      nullable: true
                                      minimum: 0
                                    capacity:
                                      type: integer
                                      minimum: 0
                                      exclusiveMinimum: true
                                    reservationStatus:
                                      type: string
                                      enum:
                                        - FREE
                                        - HELD
                                        - CONVERTED
                                        - RELEASED
                                  required:
                                    - slotId
                                    - sessionIndex
                                    - supplierId
                                    - serviceId
                                    - offeringId
                                    - bookingStartUtc
                                    - bookingEndUtc
                                    - bookingTz
                                    - locationType
                                    - locationId
                                    - latitude
                                    - longitude
                                    - address
                                    - travelTimeMins
                                    - capacity
                                    - reservationStatus
                              position:
                                type: integer
                                minimum: 0
                                description: >-
                                  0-based rank of this slate across the whole
                                  response: primarySlate is 0, then alternates,
                                  then partial, then cadenceAlternatives, in the
                                  order returned. Absent on slates built before
                                  this field existed.
                                example: 0
                              cadenceRrule:
                                type: string
                                nullable: true
                                description: >-
                                  The recurrence rule this slate’s sessions
                                  actually follow. Null for a direct fill (no
                                  recurrence rule at all). This is PROVENANCE —
                                  it records how the slate was generated and is
                                  NOT re-validated if a slot is later
                                  rescheduled.
                                example: FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8
                              matchesRequestedCadence:
                                type: boolean
                                description: >-
                                  True when cadenceRrule is the rrule you asked
                                  for.
                                example: false
                              cadenceRelaxation:
                                type: string
                                enum:
                                  - EXACT
                                  - INTERVAL_TIGHTENED
                                  - DAYS_ADDED
                                  - DAYS_SUBSTITUTED
                                  - ALL_WORKING_DAYS
                                  - DIRECT_FILL
                                description: >-
                                  How this slate’s cadence was derived from the
                                  one you requested. EXACT matches the request.
                                  INTERVAL_TIGHTENED keeps the requested
                                  weekdays but runs more often. DAYS_ADDED keeps
                                  every requested weekday and adds more.
                                  DAYS_SUBSTITUTED replaces them with weekdays
                                  the supplier actually works. ALL_WORKING_DAYS
                                  uses every weekday the supplier works.
                                  DIRECT_FILL follows no recurrence rule at all
                                  — it is the supplier’s real openings, one
                                  session per day.
                              cadenceDistance:
                                type: integer
                                minimum: 0
                                description: >-
                                  How far this slate’s cadence is from the one
                                  you requested — 0 is an exact match, lower is
                                  closer. When the request carries no
                                  sessionsPerWeek target, cadenceAlternatives is
                                  sorted by this value alone, closest first.
                                  When it does carry a target, alternatives are
                                  ranked by closeness to that target first, and
                                  this distance only breaks ties between
                                  cadences equally close to it.
                                example: 2
                              cadenceSummary:
                                type: object
                                properties:
                                  requested:
                                    type: integer
                                    nullable: true
                                    minimum: 0
                                    exclusiveMinimum: true
                                    description: >-
                                      The frequency you asked for, in sessions
                                      per week. Your sessionsPerWeek target when
                                      you sent one; otherwise counted from the
                                      weekdays your own rrule named
                                      (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null
                                      when you expressed no frequency at all,
                                      and also null when the rrule was not yours
                                      — a non-weekly FREQ, an INTERVAL other
                                      than 1, a weekly rule naming no weekdays
                                      at all, or a rule this API synthesised for
                                      you — because reporting a frequency you
                                      never asked for is worse than reporting
                                      none.
                                    example: 4
                                  peak:
                                    type: integer
                                    minimum: 0
                                    exclusiveMinimum: true
                                    description: >-
                                      The most sessions this slate holds in any
                                      single week — the number to render as
                                      "4×/week". This is the honest answer to
                                      "how often is this plan", and it is
                                      deliberately NOT an average: when a
                                      supplier has a break mid-plan, an average
                                      reports a rate that none of the weeks
                                      actually run at (nine sessions split
                                      1/0/4/4 averages 2.25, while the plan
                                      plainly runs at four a week wherever it
                                      runs).
                                    example: 4
                                  average:
                                    type: number
                                    minimum: 0
                                    description: >-
                                      Sessions divided by the number of weeks in
                                      byWeek, to 2 decimal places — so you can
                                      verify it against byWeek yourself. Weeks
                                      are counted across the PLAN’s span (first
                                      session’s week through last session’s
                                      week, gap weeks included), never across
                                      your whole lookAhead window, so a wide
                                      window does not dilute it. Prefer peak for
                                      client-facing copy; this number is for
                                      capacity and reporting.
                                    example: 2.25
                                  byWeek:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) that
                                            starts this week.
                                          example: '2026-09-14'
                                        sessions:
                                          type: integer
                                          minimum: 0
                                          description: >-
                                            Sessions this slate holds in this week.
                                            0 is a real value and the most
                                            informative entry in the array — it is a
                                            week inside the plan where the supplier
                                            had nothing.
                                          example: 0
                                      required:
                                        - weekStart
                                        - sessions
                                    minItems: 1
                                    description: >-
                                      Every Monday-anchored week from the first
                                      session’s week through the last session’s,
                                      ascending and contiguous, including weeks
                                      holding zero sessions. A zero week is how
                                      you show a client WHY the plan looks
                                      uneven — it is a week the supplier could
                                      not serve, not a gap in this data. Never
                                      empty: a slate with no sessions omits
                                      cadenceSummary entirely rather than
                                      publishing an empty array.
                                required:
                                  - requested
                                  - peak
                                  - average
                                  - byWeek
                                description: >-
                                  How often this slate actually runs, against
                                  the frequency you asked for. Present on every
                                  slate holding at least one session, on every
                                  request — absent only for a slate with no
                                  sessions, which has no cadence to describe.
                                  Render peak, not average: see peak’s
                                  description for why. IMPORTANT: the weeks here
                                  are Monday-anchored CALENDAR weeks, bucketed
                                  the same way as the maxSessionsPerWeek cap.
                                  matchComponents.sessionsPerWeek counts weeks
                                  differently — consecutive 7-day blocks from
                                  your window’s start, so it stays comparable
                                  with availabilityMatch on
                                  /availability/suppliers. The two can therefore
                                  disagree, and both are right: peak can read 4
                                  against a target of 4 while that component
                                  reads below 1, which is exactly what a
                                  supplier’s mid-plan break looks like.
                              matchNotes:
                                type: array
                                items:
                                  oneOf:
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - SUPPLIER_UNAVAILABLE_WEEK
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            openingsInPool:
                                              type: integer
                                              minimum: 0
                                              description: >-
                                                Days in this week that held at least one
                                                open slot for this supplier, AFTER your
                                                own daysOfWeek and excludeDates filters
                                                were applied. It counts PLACEABLE DAYS,
                                                not raw slots: a plan places at most one
                                                session per local date, so a day
                                                offering five start times counts once
                                                here. That is what makes this number
                                                directly comparable to sessionsTargeted.
                                              example: 2
                                            supplierWorkdays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: >-
                                                The weekdays this supplier works, BEFORE
                                                your filters. Empty here — that is what
                                                makes this code distinct from
                                                WEEK_EXCLUDED_BY_FILTERS.
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - openingsInPool
                                            - supplierWorkdays
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This supplier works NONE of the weekdays
                                        that could have served this week —
                                        supplierWorkdays is empty. Read that as
                                        a fact about their working PATTERN, not
                                        as a check of this particular calendar
                                        week: we do not expand schedule
                                        recurrence to ask whether this specific
                                        week was covered, so a supplier who
                                        works Mondays but was booked or blocked
                                        on this week’s Monday reports a
                                        different code, not this one. Sessions
                                        moved to neighbouring weeks. This is the
                                        case where "wait a week" is the right
                                        thing to tell a client; see the advice
                                        field, which may name the week supply
                                        resumes.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - WEEK_EXCLUDED_BY_FILTERS
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            filter:
                                              type: string
                                              enum:
                                                - daysOfWeek
                                                - excludeDates
                                            supplierWorkdays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            requestedDays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            excludedDates:
                                              type: array
                                              items:
                                                type: string
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - filter
                                            - supplierWorkdays
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        Your own daysOfWeek or excludeDates cut
                                        this week’s candidate days to fewer than
                                        you asked for, and the supplier’s
                                        working PATTERN covers enough days in
                                        this week to have met your target
                                        without that filter. Read
                                        supplierWorkdays exactly as
                                        SUPPLIER_UNAVAILABLE_WEEK asks you to
                                        read it: a fact about which weekdays
                                        this supplier works AT ALL, not a check
                                        of this particular calendar week. We do
                                        not expand schedule recurrence to ask
                                        whether those pattern days were actually
                                        free, so a Mon–Fri supplier already
                                        booked solid across this week reports
                                        this code too. Loosening the filter
                                        named in evidence.filter is therefore
                                        the LIKELY fix, not a guaranteed one —
                                        but it is the best move the data
                                        supports, because a week the supplier’s
                                        pattern could never have met is reported
                                        as WEEK_SUPPLY_INSUFFICIENT instead and
                                        is not your filter’s fault. The one
                                        exception is a daysOfWeek that names no
                                        day this supplier works at all, which
                                        leaves zero candidate days whatever your
                                        target. The opposite call to action from
                                        SUPPLIER_UNAVAILABLE_WEEK: waiting is
                                        not what this code points at, loosening
                                        your filter is.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - WEEK_SUPPLY_INSUFFICIENT
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            openingsInPool:
                                              type: integer
                                              minimum: 0
                                              description: >-
                                                Days in this week that held at least one
                                                open slot for this supplier, AFTER your
                                                own daysOfWeek and excludeDates filters
                                                were applied. It counts PLACEABLE DAYS,
                                                not raw slots: a plan places at most one
                                                session per local date, so a day
                                                offering five start times counts once
                                                here. That is what makes this number
                                                directly comparable to sessionsTargeted.
                                              example: 2
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - openingsInPool
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This week holds fewer sessions than you
                                        asked for and none of the more specific
                                        reasons could be ESTABLISHED. This is
                                        the RESIDUAL code, not a positive
                                        finding about supply: it says only that
                                        this supplier’s working PATTERN is not
                                        empty — a fact about which weekdays they
                                        work AT ALL, not a check of this
                                        calendar week, which is what rules out
                                        SUPPLIER_UNAVAILABLE_WEEK — and that we
                                        could not attribute the shortfall to one
                                        of your filters or to a cap you sent. It
                                        does NOT say a filter or a cap played no
                                        part. Two cases land here with one of
                                        them genuinely involved: a filter that
                                        removed a candidate day from a week the
                                        supplier’s own pattern days could never
                                        have met anyway (attribution is withheld
                                        because loosening the filter provably
                                        could not have reached your target), and
                                        a cap that applied to a week whose
                                        openings were already below your target
                                        (WEEK_CAPPED is reserved for weeks that
                                        had enough openings to make the cap the
                                        thing to raise). So compare
                                        sessionsPlaced and sessionsTargeted
                                        against openingsInPool to see what the
                                        constraint was, rather than assuming a
                                        cause. Below the target, openingsInPool
                                        says the placeable days were not there.
                                        At or above it, the days were there and
                                        the shortfall came from something other
                                        than supply — check the slate for
                                        CADENCE_RELAXED, which reports a cadence
                                        that could not use them and is then the
                                        better thing to tell a client. That
                                        pointer does not always land:
                                        CADENCE_RELAXED is emitted only when the
                                        cadence component scored below 1, and an
                                        AUTHORISED weekday substitution scores a
                                        perfect cadence, so a days-were-there
                                        week can carry no cadence note at all.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - WEEK_CAPPED
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            cap:
                                              type: string
                                              enum:
                                                - maxSessionsPerWeek
                                                - minGapDays
                                            capValue:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - cap
                                            - capValue
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This week held at least sessionsTargeted
                                        placeable days, and a cap YOU sent —
                                        maxSessionsPerWeek or minGapDays — puts
                                        a ceiling on the week that is BELOW your
                                        target, so your target was unreachable
                                        in this week whatever the supplier had
                                        free. Raising the cap named in
                                        evidence.cap is therefore NECESSARY if
                                        you want this week to meet your target.
                                        Whether it is SUFFICIENT is not
                                        something this note can tell you: the
                                        code fires on that ceiling EXISTING, not
                                        on the plan having filled up to it, so
                                        sessionsPlaced can sit below the ceiling
                                        — when it does, all that is established
                                        is that the plan did not fill the week
                                        even to the ceiling. Do not read that
                                        either way; nothing here says what else
                                        was or was not in the way. (capValue is
                                        the number you sent. For minGapDays that
                                        is the gap, not the weekly ceiling it
                                        implies: a gap of 3 admits at most three
                                        sessions in a seven-day week.)
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - SESSIONS_EXHAUSTED
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsRequested:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                            sessionsPlacedBefore:
                                              type: integer
                                              minimum: 0
                                          required:
                                            - sessionsRequested
                                            - sessionsPlacedBefore
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This week is short only because the
                                        package ran out of sessions — nine
                                        sessions at four a week leaves the last
                                        week holding one. NOTHING went wrong
                                        here, and no supply code is emitted for
                                        this week: do not apologise for it in
                                        your copy.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - CADENCE_RELAXED
                                        component:
                                          type: string
                                          enum:
                                            - cadence
                                        evidence:
                                          type: object
                                          properties:
                                            cadenceRelaxation:
                                              type: string
                                              enum:
                                                - EXACT
                                                - INTERVAL_TIGHTENED
                                                - DAYS_ADDED
                                                - DAYS_SUBSTITUTED
                                                - ALL_WORKING_DAYS
                                                - DIRECT_FILL
                                              description: >-
                                                How this slate’s cadence was derived
                                                from the one you requested. EXACT
                                                matches the request. INTERVAL_TIGHTENED
                                                keeps the requested weekdays but runs
                                                more often. DAYS_ADDED keeps every
                                                requested weekday and adds more.
                                                DAYS_SUBSTITUTED replaces them with
                                                weekdays the supplier actually works.
                                                ALL_WORKING_DAYS uses every weekday the
                                                supplier works. DIRECT_FILL follows no
                                                recurrence rule at all — it is the
                                                supplier’s real openings, one session
                                                per day.
                                            requestedDays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            actualDays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                          required:
                                            - cadenceRelaxation
                                      required:
                                        - code
                                        - component
                                        - evidence
                                      description: >-
                                        This slate does not run at the rrule you
                                        sent. cadenceRelaxation says how it was
                                        derived; requestedDays and actualDays
                                        let you show the swap.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - SESSIONS_OUTSIDE_PREFERRED_TIMES
                                        component:
                                          type: string
                                          enum:
                                            - timeOfDay
                                        evidence:
                                          type: object
                                          properties:
                                            sessionIndexes:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                            localTimes:
                                              type: array
                                              items:
                                                type: string
                                          required:
                                            - sessionIndexes
                                            - localTimes
                                      required:
                                        - code
                                        - component
                                        - evidence
                                      description: >-
                                        These sessions (1-based, matching
                                        sessionIndex on each slot) fall outside
                                        every preferredTimes window you sent.
                                        localTimes is aligned to sessionIndexes.
                                        BOTH ARRAYS CAN BE EMPTY: when no
                                        session of this slate lands inside your
                                        requested window at all, the criterion
                                        definitely missed and this note is
                                        emitted, but there is no in-window
                                        session to name — so treat empty arrays
                                        as "outside your preferred times, with
                                        nothing to point at", not as an error.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - FIRST_SESSION_LATE
                                        component:
                                          type: string
                                          enum:
                                            - startDate
                                        evidence:
                                          type: object
                                          properties:
                                            firstSessionDate:
                                              type: string
                                            windowStartDate:
                                              type: string
                                            dayOffset:
                                              type: integer
                                              minimum: 0
                                            earlierSupplyExisted:
                                              type: boolean
                                              description: >-
                                                TRUE when the supplier had open slots
                                                before the first session but the cadence
                                                could not use them — so the late start
                                                is the rrule, not a lack of
                                                availability.
                                          required:
                                            - firstSessionDate
                                            - windowStartDate
                                            - dayOffset
                                            - earlierSupplyExisted
                                      required:
                                        - code
                                        - component
                                        - evidence
                                      description: >-
                                        The plan’s first session is
                                        evidence.dayOffset whole local days
                                        after your window start — that offset is
                                        the fact this code reports, and it is
                                        always at least one day. Whether the
                                        plan started later than it HAD to is a
                                        separate question, answered by
                                        evidence.earlierSupplyExisted: TRUE
                                        means the supplier had open days before
                                        that first session and the cadence could
                                        not use them, so an earlier start really
                                        was there to be had and loosening the
                                        cadence is the fix. FALSE means we found
                                        no opening earlier in your window, so
                                        this is simply where the supplier’s
                                        supply began — nothing was given up, and
                                        copy saying otherwise would be wrong.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - PACKAGE_UNDERFILLED
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsRequested:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                            sessionsFilled:
                                              type: integer
                                              minimum: 0
                                          required:
                                            - sessionsRequested
                                            - sessionsFilled
                                      required:
                                        - code
                                        - evidence
                                      description: >-
                                        Fewer sessions than the package holds
                                        credits for. This slate is PARTIAL —
                                        completeness says so too, and it is not
                                        a matchScore component, so a PARTIAL
                                        slate can still score 1.
                                description: >-
                                  Why this slate departs from what you asked for
                                  — one entry per reason, each a code plus
                                  structured evidence, and no English so you can
                                  write your own copy. ALWAYS PRESENT: empty
                                  means nothing departed, so you can read
                                  .length without a null check. NOT gated on
                                  matchScore — a DIRECT_FILL slate and a PARTIAL
                                  slate can both score 1 and still carry notes,
                                  and those are exactly the slates worth
                                  captioning. Read matchComponents for WHICH
                                  criterion missed and these for WHY. IMPORTANT:
                                  the two count weeks differently, so that
                                  pairing is a guide, not a join key. The
                                  week-level codes here bucket Monday-anchored
                                  CALENDAR weeks — the same bucketing as
                                  cadenceSummary.byWeek and the
                                  maxSessionsPerWeek cap — while
                                  matchComponents.sessionsPerWeek buckets
                                  consecutive 7-day blocks from your window’s
                                  start. The two can therefore disagree, and
                                  both are right: a note can name a short week
                                  for a criterion that component scores as met,
                                  and the reverse. Join a note to
                                  cadenceSummary.byWeek on weekStart, which does
                                  share this bucketing; treat matchComponents as
                                  the per-criterion score, not as a per-week
                                  one.
                              advice:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    enum:
                                      - LATER_START_IMPROVES_CADENCE
                                  earliestSustainedWeek:
                                    type: string
                                    pattern: ^\d{4}-\d{2}-\d{2}$
                                    description: >-
                                      The earliest Monday from which supply
                                      alone could sustain your requested
                                      frequency. Always STRICTLY LATER than the
                                      first week matchNotes reported as short —
                                      this field means "start later", so it
                                      never names a week the notes just
                                      condemned.
                                    example: '2026-09-14'
                                required:
                                  - code
                                  - earliestSustainedWeek
                                description: >-
                                  An advisory hint about a later start, present
                                  only when one applies. Read AdviceSchema’s own
                                  description first: it reports that SUPPLY
                                  exists, not that a slate was built.
                              matchScore:
                                type: number
                                minimum: 0
                                maximum: 1
                                description: >-
                                  How well this slate matches the requested
                                  schedule preferences, from 0 to 1 — the mean
                                  of the components present in matchComponents.
                                  When the caller expressed no schedule
                                  preferences it is 1 and matchComponents is
                                  empty, so a caller distinguishes "perfect
                                  match" from "nothing asked" by reading
                                  matchComponents, not this score. Compare the
                                  availabilityMatch property on
                                  /availability/suppliers, which is ABSENT
                                  entirely for the "nothing asked" case rather
                                  than present with a null score — matchScore
                                  cannot go absent, because it is a required
                                  property on this shipped contract and dropping
                                  it would break the generated SDK types. The
                                  results are already ranked: primarySlate is
                                  the best-matching COMPLETE slate and
                                  alternates follow it in descending order, with
                                  completeness always outranking this score, so
                                  a COMPLETE slate never sits below a PARTIAL
                                  one that scored higher. (cadenceAlternatives
                                  is ordered separately, closest-cadence first.)
                                  Do NOT re-sort the slates you receive by
                                  matchScore: the order carries preferences this
                                  number cannot. matchComponents.sessionsPerWeek
                                  scores a week holding AT LEAST the
                                  sessionsPerWeek you asked for, so against a
                                  target of 2 a slate delivering three sessions
                                  a week scores identically to one delivering
                                  two, and only the order distinguishes them.
                                  Re-sorting silently discards that. This score
                                  is also not a cadence: read
                                  cadenceSummary.peak for how often the plan
                                  actually runs, and cadenceSummary.byWeek for
                                  which weeks are short and why the two numbers
                                  can differ.
                                example: 1
                              matchComponents:
                                type: object
                                properties:
                                  startDate:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      How soon this slate’s first session lands
                                      in the requested window — 1 when session
                                      one lands as early as possible in the
                                      window, lower the later it lands.
                                  timeOfDay:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      Fraction of this slate’s sessions that
                                      fall at a preferred time of day.
                                  daysOfWeek:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      Fraction of this slate’s sessions that
                                      fall on a requested weekday.
                                  sessionsPerWeek:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      Fraction of the window’s whole weeks in
                                      which this slate holds at least the
                                      requested number of sessions — a match
                                      ratio in [0, 1], not a count. For counts
                                      see cadenceSummary, whose peak is the
                                      number to render as "4×/week". THE TWO
                                      COUNT WEEKS DIFFERENTLY, deliberately:
                                      this ratio buckets consecutive 7-day
                                      blocks from your window’s start, so it
                                      stays comparable with availabilityMatch on
                                      /availability/suppliers, while
                                      cadenceSummary uses Monday-anchored
                                      calendar weeks so its weekStart dates are
                                      real Mondays and agree with the
                                      maxSessionsPerWeek cap. Expect them to
                                      disagree on a plan spanning a supplier’s
                                      break — cadenceSummary.peak can read 4
                                      against a target of 4 while this ratio
                                      reads below 1, and both are correct for
                                      what they measure. AT LEAST is literal:
                                      against a target of 2, a week holding 3
                                      sessions counts exactly as a week holding
                                      2, so a denser slate never scores worse
                                      here. The preference for two over three is
                                      expressed only in the ORDER slates come
                                      back in — see matchScore.
                                  cadence:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      1 when this slate runs at the cadence you
                                      requested, and also 1 when the only
                                      departure from it was a weekday
                                      substitution you authorised —
                                      cadenceRelaxation of DAYS_SUBSTITUTED or
                                      ALL_WORKING_DAYS, with
                                      allowWeekdaySubstitution true and no
                                      daysOfWeek sent. 0 when the cadence
                                      changed in a way you did not authorise,
                                      which includes every change to how OFTEN
                                      sessions occur (INTERVAL_TIGHTENED,
                                      DAYS_ADDED): allowing weekday substitution
                                      does not authorise a frequency change, and
                                      sending an explicit daysOfWeek withdraws
                                      the authorisation, because naming your
                                      weekdays says the weekdays are the point.
                                      Absent rather than 0 on a slate that
                                      follows no cadence at all — a DIRECT_FILL
                                      slate and a PARTIAL slate are both greedy
                                      fills that never consult your rrule, so
                                      how well they match a requested cadence is
                                      unanswerable rather than zero, and
                                      matchScore is the mean of the components
                                      that remain. Absent too when you sent no
                                      rrule.
                                description: >-
                                  How well this slate matches the requested
                                  schedule preferences, broken down by
                                  criterion. Only the criteria the caller
                                  supplied are scored here — matchScore is the
                                  mean of exactly these. Present but empty when
                                  the caller expressed no schedule preferences
                                  at all; see matchScore’s description for why
                                  that case is 1 here rather than an absent
                                  availabilityMatch. Also absent on a slate
                                  whose matchScore carries no recorded
                                  per-criterion breakdown. These names mirror
                                  the components object inside availabilityMatch
                                  on /availability/suppliers but NOT their
                                  meaning: there each ratio is measured over the
                                  supplier’s open availability, while here every
                                  ratio is measured over this slate’s own
                                  sessions — a slate of eight Friday sessions
                                  scores 1 on daysOfWeek because all eight
                                  sessions are Fridays, independent of what a
                                  supplier-level daysOfWeek would report.
                            required:
                              - slateId
                              - supplierId
                              - completeness
                              - sessionsRequested
                              - sessionsFilled
                              - startTimeConsistencyPercent
                              - totalTravelTimeMins
                              - slots
                              - matchNotes
                              - matchScore
                            description: >-
                              The best COMPLETE single-supplier slate; book this
                              by slateId.
                          alternates:
                            type: array
                            items:
                              type: object
                              properties:
                                slateId:
                                  type: string
                                  description: >-
                                    Pass this to POST .../package-bookings to
                                    book the whole plan.
                                  example: slate_01kx16ejsqffc9rbgdcc591w2p
                                supplierId:
                                  type: string
                                completeness:
                                  type: string
                                  enum:
                                    - COMPLETE
                                    - PARTIAL
                                sessionsRequested:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                  description: >-
                                    How many sessions were requested (the
                                    package's creditCount).
                                sessionsFilled:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    How many of the requested sessions the plan
                                    could fill.
                                startTimeConsistencyPercent:
                                  type: number
                                  minimum: 0
                                  maximum: 100
                                totalTravelTimeMins:
                                  type: number
                                  minimum: 0
                                slots:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      slotId:
                                        type: string
                                        description: >-
                                          Id of one session; pass a subset of
                                          these as slotIds to cherry-pick.
                                      sessionIndex:
                                        type: integer
                                        minimum: 0
                                        exclusiveMinimum: true
                                        description: >-
                                          1-based index of this session within the
                                          slate.
                                      supplierId:
                                        type: string
                                      serviceId:
                                        type: string
                                      offeringId:
                                        type: string
                                      bookingStartUtc:
                                        type: string
                                        format: date-time
                                      bookingEndUtc:
                                        type: string
                                        format: date-time
                                      bookingTz:
                                        type: string
                                      locationType:
                                        type: string
                                        enum:
                                          - PHYSICAL
                                          - VIRTUAL
                                          - TRAVEL_ZONE
                                      locationId:
                                        type: string
                                        nullable: true
                                      latitude:
                                        type: number
                                        nullable: true
                                      longitude:
                                        type: number
                                        nullable: true
                                      address:
                                        $ref: '#/components/schemas/Address'
                                      travelTimeMins:
                                        type: number
                                        nullable: true
                                        minimum: 0
                                      capacity:
                                        type: integer
                                        minimum: 0
                                        exclusiveMinimum: true
                                      reservationStatus:
                                        type: string
                                        enum:
                                          - FREE
                                          - HELD
                                          - CONVERTED
                                          - RELEASED
                                    required:
                                      - slotId
                                      - sessionIndex
                                      - supplierId
                                      - serviceId
                                      - offeringId
                                      - bookingStartUtc
                                      - bookingEndUtc
                                      - bookingTz
                                      - locationType
                                      - locationId
                                      - latitude
                                      - longitude
                                      - address
                                      - travelTimeMins
                                      - capacity
                                      - reservationStatus
                                position:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    0-based rank of this slate across the whole
                                    response: primarySlate is 0, then
                                    alternates, then partial, then
                                    cadenceAlternatives, in the order returned.
                                    Absent on slates built before this field
                                    existed.
                                  example: 0
                                cadenceRrule:
                                  type: string
                                  nullable: true
                                  description: >-
                                    The recurrence rule this slate’s sessions
                                    actually follow. Null for a direct fill (no
                                    recurrence rule at all). This is PROVENANCE
                                    — it records how the slate was generated and
                                    is NOT re-validated if a slot is later
                                    rescheduled.
                                  example: FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8
                                matchesRequestedCadence:
                                  type: boolean
                                  description: >-
                                    True when cadenceRrule is the rrule you
                                    asked for.
                                  example: false
                                cadenceRelaxation:
                                  type: string
                                  enum:
                                    - EXACT
                                    - INTERVAL_TIGHTENED
                                    - DAYS_ADDED
                                    - DAYS_SUBSTITUTED
                                    - ALL_WORKING_DAYS
                                    - DIRECT_FILL
                                  description: >-
                                    How this slate’s cadence was derived from
                                    the one you requested. EXACT matches the
                                    request. INTERVAL_TIGHTENED keeps the
                                    requested weekdays but runs more often.
                                    DAYS_ADDED keeps every requested weekday and
                                    adds more. DAYS_SUBSTITUTED replaces them
                                    with weekdays the supplier actually works.
                                    ALL_WORKING_DAYS uses every weekday the
                                    supplier works. DIRECT_FILL follows no
                                    recurrence rule at all — it is the
                                    supplier’s real openings, one session per
                                    day.
                                cadenceDistance:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    How far this slate’s cadence is from the one
                                    you requested — 0 is an exact match, lower
                                    is closer. When the request carries no
                                    sessionsPerWeek target, cadenceAlternatives
                                    is sorted by this value alone, closest
                                    first. When it does carry a target,
                                    alternatives are ranked by closeness to that
                                    target first, and this distance only breaks
                                    ties between cadences equally close to it.
                                  example: 2
                                cadenceSummary:
                                  type: object
                                  properties:
                                    requested:
                                      type: integer
                                      nullable: true
                                      minimum: 0
                                      exclusiveMinimum: true
                                      description: >-
                                        The frequency you asked for, in sessions
                                        per week. Your sessionsPerWeek target
                                        when you sent one; otherwise counted
                                        from the weekdays your own rrule named
                                        (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4).
                                        Null when you expressed no frequency at
                                        all, and also null when the rrule was
                                        not yours — a non-weekly FREQ, an
                                        INTERVAL other than 1, a weekly rule
                                        naming no weekdays at all, or a rule
                                        this API synthesised for you — because
                                        reporting a frequency you never asked
                                        for is worse than reporting none.
                                      example: 4
                                    peak:
                                      type: integer
                                      minimum: 0
                                      exclusiveMinimum: true
                                      description: >-
                                        The most sessions this slate holds in
                                        any single week — the number to render
                                        as "4×/week". This is the honest answer
                                        to "how often is this plan", and it is
                                        deliberately NOT an average: when a
                                        supplier has a break mid-plan, an
                                        average reports a rate that none of the
                                        weeks actually run at (nine sessions
                                        split 1/0/4/4 averages 2.25, while the
                                        plan plainly runs at four a week
                                        wherever it runs).
                                      example: 4
                                    average:
                                      type: number
                                      minimum: 0
                                      description: >-
                                        Sessions divided by the number of weeks
                                        in byWeek, to 2 decimal places — so you
                                        can verify it against byWeek yourself.
                                        Weeks are counted across the PLAN’s span
                                        (first session’s week through last
                                        session’s week, gap weeks included),
                                        never across your whole lookAhead
                                        window, so a wide window does not dilute
                                        it. Prefer peak for client-facing copy;
                                        this number is for capacity and
                                        reporting.
                                      example: 2.25
                                    byWeek:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) that
                                              starts this week.
                                            example: '2026-09-14'
                                          sessions:
                                            type: integer
                                            minimum: 0
                                            description: >-
                                              Sessions this slate holds in this week.
                                              0 is a real value and the most
                                              informative entry in the array — it is a
                                              week inside the plan where the supplier
                                              had nothing.
                                            example: 0
                                        required:
                                          - weekStart
                                          - sessions
                                      minItems: 1
                                      description: >-
                                        Every Monday-anchored week from the
                                        first session’s week through the last
                                        session’s, ascending and contiguous,
                                        including weeks holding zero sessions. A
                                        zero week is how you show a client WHY
                                        the plan looks uneven — it is a week the
                                        supplier could not serve, not a gap in
                                        this data. Never empty: a slate with no
                                        sessions omits cadenceSummary entirely
                                        rather than publishing an empty array.
                                  required:
                                    - requested
                                    - peak
                                    - average
                                    - byWeek
                                  description: >-
                                    How often this slate actually runs, against
                                    the frequency you asked for. Present on
                                    every slate holding at least one session, on
                                    every request — absent only for a slate with
                                    no sessions, which has no cadence to
                                    describe. Render peak, not average: see
                                    peak’s description for why. IMPORTANT: the
                                    weeks here are Monday-anchored CALENDAR
                                    weeks, bucketed the same way as the
                                    maxSessionsPerWeek cap.
                                    matchComponents.sessionsPerWeek counts weeks
                                    differently — consecutive 7-day blocks from
                                    your window’s start, so it stays comparable
                                    with availabilityMatch on
                                    /availability/suppliers. The two can
                                    therefore disagree, and both are right: peak
                                    can read 4 against a target of 4 while that
                                    component reads below 1, which is exactly
                                    what a supplier’s mid-plan break looks like.
                                matchNotes:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - SUPPLIER_UNAVAILABLE_WEEK
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              openingsInPool:
                                                type: integer
                                                minimum: 0
                                                description: >-
                                                  Days in this week that held at least one
                                                  open slot for this supplier, AFTER your
                                                  own daysOfWeek and excludeDates filters
                                                  were applied. It counts PLACEABLE DAYS,
                                                  not raw slots: a plan places at most one
                                                  session per local date, so a day
                                                  offering five start times counts once
                                                  here. That is what makes this number
                                                  directly comparable to sessionsTargeted.
                                                example: 2
                                              supplierWorkdays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: >-
                                                  The weekdays this supplier works, BEFORE
                                                  your filters. Empty here — that is what
                                                  makes this code distinct from
                                                  WEEK_EXCLUDED_BY_FILTERS.
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - openingsInPool
                                              - supplierWorkdays
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This supplier works NONE of the weekdays
                                          that could have served this week —
                                          supplierWorkdays is empty. Read that as
                                          a fact about their working PATTERN, not
                                          as a check of this particular calendar
                                          week: we do not expand schedule
                                          recurrence to ask whether this specific
                                          week was covered, so a supplier who
                                          works Mondays but was booked or blocked
                                          on this week’s Monday reports a
                                          different code, not this one. Sessions
                                          moved to neighbouring weeks. This is the
                                          case where "wait a week" is the right
                                          thing to tell a client; see the advice
                                          field, which may name the week supply
                                          resumes.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - WEEK_EXCLUDED_BY_FILTERS
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              filter:
                                                type: string
                                                enum:
                                                  - daysOfWeek
                                                  - excludeDates
                                              supplierWorkdays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                              requestedDays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                              excludedDates:
                                                type: array
                                                items:
                                                  type: string
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - filter
                                              - supplierWorkdays
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          Your own daysOfWeek or excludeDates cut
                                          this week’s candidate days to fewer than
                                          you asked for, and the supplier’s
                                          working PATTERN covers enough days in
                                          this week to have met your target
                                          without that filter. Read
                                          supplierWorkdays exactly as
                                          SUPPLIER_UNAVAILABLE_WEEK asks you to
                                          read it: a fact about which weekdays
                                          this supplier works AT ALL, not a check
                                          of this particular calendar week. We do
                                          not expand schedule recurrence to ask
                                          whether those pattern days were actually
                                          free, so a Mon–Fri supplier already
                                          booked solid across this week reports
                                          this code too. Loosening the filter
                                          named in evidence.filter is therefore
                                          the LIKELY fix, not a guaranteed one —
                                          but it is the best move the data
                                          supports, because a week the supplier’s
                                          pattern could never have met is reported
                                          as WEEK_SUPPLY_INSUFFICIENT instead and
                                          is not your filter’s fault. The one
                                          exception is a daysOfWeek that names no
                                          day this supplier works at all, which
                                          leaves zero candidate days whatever your
                                          target. The opposite call to action from
                                          SUPPLIER_UNAVAILABLE_WEEK: waiting is
                                          not what this code points at, loosening
                                          your filter is.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - WEEK_SUPPLY_INSUFFICIENT
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              openingsInPool:
                                                type: integer
                                                minimum: 0
                                                description: >-
                                                  Days in this week that held at least one
                                                  open slot for this supplier, AFTER your
                                                  own daysOfWeek and excludeDates filters
                                                  were applied. It counts PLACEABLE DAYS,
                                                  not raw slots: a plan places at most one
                                                  session per local date, so a day
                                                  offering five start times counts once
                                                  here. That is what makes this number
                                                  directly comparable to sessionsTargeted.
                                                example: 2
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - openingsInPool
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This week holds fewer sessions than you
                                          asked for and none of the more specific
                                          reasons could be ESTABLISHED. This is
                                          the RESIDUAL code, not a positive
                                          finding about supply: it says only that
                                          this supplier’s working PATTERN is not
                                          empty — a fact about which weekdays they
                                          work AT ALL, not a check of this
                                          calendar week, which is what rules out
                                          SUPPLIER_UNAVAILABLE_WEEK — and that we
                                          could not attribute the shortfall to one
                                          of your filters or to a cap you sent. It
                                          does NOT say a filter or a cap played no
                                          part. Two cases land here with one of
                                          them genuinely involved: a filter that
                                          removed a candidate day from a week the
                                          supplier’s own pattern days could never
                                          have met anyway (attribution is withheld
                                          because loosening the filter provably
                                          could not have reached your target), and
                                          a cap that applied to a week whose
                                          openings were already below your target
                                          (WEEK_CAPPED is reserved for weeks that
                                          had enough openings to make the cap the
                                          thing to raise). So compare
                                          sessionsPlaced and sessionsTargeted
                                          against openingsInPool to see what the
                                          constraint was, rather than assuming a
                                          cause. Below the target, openingsInPool
                                          says the placeable days were not there.
                                          At or above it, the days were there and
                                          the shortfall came from something other
                                          than supply — check the slate for
                                          CADENCE_RELAXED, which reports a cadence
                                          that could not use them and is then the
                                          better thing to tell a client. That
                                          pointer does not always land:
                                          CADENCE_RELAXED is emitted only when the
                                          cadence component scored below 1, and an
                                          AUTHORISED weekday substitution scores a
                                          perfect cadence, so a days-were-there
                                          week can carry no cadence note at all.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - WEEK_CAPPED
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              cap:
                                                type: string
                                                enum:
                                                  - maxSessionsPerWeek
                                                  - minGapDays
                                              capValue:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - cap
                                              - capValue
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This week held at least sessionsTargeted
                                          placeable days, and a cap YOU sent —
                                          maxSessionsPerWeek or minGapDays — puts
                                          a ceiling on the week that is BELOW your
                                          target, so your target was unreachable
                                          in this week whatever the supplier had
                                          free. Raising the cap named in
                                          evidence.cap is therefore NECESSARY if
                                          you want this week to meet your target.
                                          Whether it is SUFFICIENT is not
                                          something this note can tell you: the
                                          code fires on that ceiling EXISTING, not
                                          on the plan having filled up to it, so
                                          sessionsPlaced can sit below the ceiling
                                          — when it does, all that is established
                                          is that the plan did not fill the week
                                          even to the ceiling. Do not read that
                                          either way; nothing here says what else
                                          was or was not in the way. (capValue is
                                          the number you sent. For minGapDays that
                                          is the gap, not the weekly ceiling it
                                          implies: a gap of 3 admits at most three
                                          sessions in a seven-day week.)
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - SESSIONS_EXHAUSTED
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsRequested:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                              sessionsPlacedBefore:
                                                type: integer
                                                minimum: 0
                                            required:
                                              - sessionsRequested
                                              - sessionsPlacedBefore
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This week is short only because the
                                          package ran out of sessions — nine
                                          sessions at four a week leaves the last
                                          week holding one. NOTHING went wrong
                                          here, and no supply code is emitted for
                                          this week: do not apologise for it in
                                          your copy.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - CADENCE_RELAXED
                                          component:
                                            type: string
                                            enum:
                                              - cadence
                                          evidence:
                                            type: object
                                            properties:
                                              cadenceRelaxation:
                                                type: string
                                                enum:
                                                  - EXACT
                                                  - INTERVAL_TIGHTENED
                                                  - DAYS_ADDED
                                                  - DAYS_SUBSTITUTED
                                                  - ALL_WORKING_DAYS
                                                  - DIRECT_FILL
                                                description: >-
                                                  How this slate’s cadence was derived
                                                  from the one you requested. EXACT
                                                  matches the request. INTERVAL_TIGHTENED
                                                  keeps the requested weekdays but runs
                                                  more often. DAYS_ADDED keeps every
                                                  requested weekday and adds more.
                                                  DAYS_SUBSTITUTED replaces them with
                                                  weekdays the supplier actually works.
                                                  ALL_WORKING_DAYS uses every weekday the
                                                  supplier works. DIRECT_FILL follows no
                                                  recurrence rule at all — it is the
                                                  supplier’s real openings, one session
                                                  per day.
                                              requestedDays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                              actualDays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            required:
                                              - cadenceRelaxation
                                        required:
                                          - code
                                          - component
                                          - evidence
                                        description: >-
                                          This slate does not run at the rrule you
                                          sent. cadenceRelaxation says how it was
                                          derived; requestedDays and actualDays
                                          let you show the swap.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - SESSIONS_OUTSIDE_PREFERRED_TIMES
                                          component:
                                            type: string
                                            enum:
                                              - timeOfDay
                                          evidence:
                                            type: object
                                            properties:
                                              sessionIndexes:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  exclusiveMinimum: true
                                              localTimes:
                                                type: array
                                                items:
                                                  type: string
                                            required:
                                              - sessionIndexes
                                              - localTimes
                                        required:
                                          - code
                                          - component
                                          - evidence
                                        description: >-
                                          These sessions (1-based, matching
                                          sessionIndex on each slot) fall outside
                                          every preferredTimes window you sent.
                                          localTimes is aligned to sessionIndexes.
                                          BOTH ARRAYS CAN BE EMPTY: when no
                                          session of this slate lands inside your
                                          requested window at all, the criterion
                                          definitely missed and this note is
                                          emitted, but there is no in-window
                                          session to name — so treat empty arrays
                                          as "outside your preferred times, with
                                          nothing to point at", not as an error.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - FIRST_SESSION_LATE
                                          component:
                                            type: string
                                            enum:
                                              - startDate
                                          evidence:
                                            type: object
                                            properties:
                                              firstSessionDate:
                                                type: string
                                              windowStartDate:
                                                type: string
                                              dayOffset:
                                                type: integer
                                                minimum: 0
                                              earlierSupplyExisted:
                                                type: boolean
                                                description: >-
                                                  TRUE when the supplier had open slots
                                                  before the first session but the cadence
                                                  could not use them — so the late start
                                                  is the rrule, not a lack of
                                                  availability.
                                            required:
                                              - firstSessionDate
                                              - windowStartDate
                                              - dayOffset
                                              - earlierSupplyExisted
                                        required:
                                          - code
                                          - component
                                          - evidence
                                        description: >-
                                          The plan’s first session is
                                          evidence.dayOffset whole local days
                                          after your window start — that offset is
                                          the fact this code reports, and it is
                                          always at least one day. Whether the
                                          plan started later than it HAD to is a
                                          separate question, answered by
                                          evidence.earlierSupplyExisted: TRUE
                                          means the supplier had open days before
                                          that first session and the cadence could
                                          not use them, so an earlier start really
                                          was there to be had and loosening the
                                          cadence is the fix. FALSE means we found
                                          no opening earlier in your window, so
                                          this is simply where the supplier’s
                                          supply began — nothing was given up, and
                                          copy saying otherwise would be wrong.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - PACKAGE_UNDERFILLED
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsRequested:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                              sessionsFilled:
                                                type: integer
                                                minimum: 0
                                            required:
                                              - sessionsRequested
                                              - sessionsFilled
                                        required:
                                          - code
                                          - evidence
                                        description: >-
                                          Fewer sessions than the package holds
                                          credits for. This slate is PARTIAL —
                                          completeness says so too, and it is not
                                          a matchScore component, so a PARTIAL
                                          slate can still score 1.
                                  description: >-
                                    Why this slate departs from what you asked
                                    for — one entry per reason, each a code plus
                                    structured evidence, and no English so you
                                    can write your own copy. ALWAYS PRESENT:
                                    empty means nothing departed, so you can
                                    read .length without a null check. NOT gated
                                    on matchScore — a DIRECT_FILL slate and a
                                    PARTIAL slate can both score 1 and still
                                    carry notes, and those are exactly the
                                    slates worth captioning. Read
                                    matchComponents for WHICH criterion missed
                                    and these for WHY. IMPORTANT: the two count
                                    weeks differently, so that pairing is a
                                    guide, not a join key. The week-level codes
                                    here bucket Monday-anchored CALENDAR weeks —
                                    the same bucketing as cadenceSummary.byWeek
                                    and the maxSessionsPerWeek cap — while
                                    matchComponents.sessionsPerWeek buckets
                                    consecutive 7-day blocks from your window’s
                                    start. The two can therefore disagree, and
                                    both are right: a note can name a short week
                                    for a criterion that component scores as
                                    met, and the reverse. Join a note to
                                    cadenceSummary.byWeek on weekStart, which
                                    does share this bucketing; treat
                                    matchComponents as the per-criterion score,
                                    not as a per-week one.
                                advice:
                                  type: object
                                  properties:
                                    code:
                                      type: string
                                      enum:
                                        - LATER_START_IMPROVES_CADENCE
                                    earliestSustainedWeek:
                                      type: string
                                      pattern: ^\d{4}-\d{2}-\d{2}$
                                      description: >-
                                        The earliest Monday from which supply
                                        alone could sustain your requested
                                        frequency. Always STRICTLY LATER than
                                        the first week matchNotes reported as
                                        short — this field means "start later",
                                        so it never names a week the notes just
                                        condemned.
                                      example: '2026-09-14'
                                  required:
                                    - code
                                    - earliestSustainedWeek
                                  description: >-
                                    An advisory hint about a later start,
                                    present only when one applies. Read
                                    AdviceSchema’s own description first: it
                                    reports that SUPPLY exists, not that a slate
                                    was built.
                                matchScore:
                                  type: number
                                  minimum: 0
                                  maximum: 1
                                  description: >-
                                    How well this slate matches the requested
                                    schedule preferences, from 0 to 1 — the mean
                                    of the components present in
                                    matchComponents. When the caller expressed
                                    no schedule preferences it is 1 and
                                    matchComponents is empty, so a caller
                                    distinguishes "perfect match" from "nothing
                                    asked" by reading matchComponents, not this
                                    score. Compare the availabilityMatch
                                    property on /availability/suppliers, which
                                    is ABSENT entirely for the "nothing asked"
                                    case rather than present with a null score —
                                    matchScore cannot go absent, because it is a
                                    required property on this shipped contract
                                    and dropping it would break the generated
                                    SDK types. The results are already ranked:
                                    primarySlate is the best-matching COMPLETE
                                    slate and alternates follow it in descending
                                    order, with completeness always outranking
                                    this score, so a COMPLETE slate never sits
                                    below a PARTIAL one that scored higher.
                                    (cadenceAlternatives is ordered separately,
                                    closest-cadence first.) Do NOT re-sort the
                                    slates you receive by matchScore: the order
                                    carries preferences this number cannot.
                                    matchComponents.sessionsPerWeek scores a
                                    week holding AT LEAST the sessionsPerWeek
                                    you asked for, so against a target of 2 a
                                    slate delivering three sessions a week
                                    scores identically to one delivering two,
                                    and only the order distinguishes them.
                                    Re-sorting silently discards that. This
                                    score is also not a cadence: read
                                    cadenceSummary.peak for how often the plan
                                    actually runs, and cadenceSummary.byWeek for
                                    which weeks are short and why the two
                                    numbers can differ.
                                  example: 1
                                matchComponents:
                                  type: object
                                  properties:
                                    startDate:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        How soon this slate’s first session
                                        lands in the requested window — 1 when
                                        session one lands as early as possible
                                        in the window, lower the later it lands.
                                    timeOfDay:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        Fraction of this slate’s sessions that
                                        fall at a preferred time of day.
                                    daysOfWeek:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        Fraction of this slate’s sessions that
                                        fall on a requested weekday.
                                    sessionsPerWeek:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        Fraction of the window’s whole weeks in
                                        which this slate holds at least the
                                        requested number of sessions — a match
                                        ratio in [0, 1], not a count. For counts
                                        see cadenceSummary, whose peak is the
                                        number to render as "4×/week". THE TWO
                                        COUNT WEEKS DIFFERENTLY, deliberately:
                                        this ratio buckets consecutive 7-day
                                        blocks from your window’s start, so it
                                        stays comparable with availabilityMatch
                                        on /availability/suppliers, while
                                        cadenceSummary uses Monday-anchored
                                        calendar weeks so its weekStart dates
                                        are real Mondays and agree with the
                                        maxSessionsPerWeek cap. Expect them to
                                        disagree on a plan spanning a supplier’s
                                        break — cadenceSummary.peak can read 4
                                        against a target of 4 while this ratio
                                        reads below 1, and both are correct for
                                        what they measure. AT LEAST is literal:
                                        against a target of 2, a week holding 3
                                        sessions counts exactly as a week
                                        holding 2, so a denser slate never
                                        scores worse here. The preference for
                                        two over three is expressed only in the
                                        ORDER slates come back in — see
                                        matchScore.
                                    cadence:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        1 when this slate runs at the cadence
                                        you requested, and also 1 when the only
                                        departure from it was a weekday
                                        substitution you authorised —
                                        cadenceRelaxation of DAYS_SUBSTITUTED or
                                        ALL_WORKING_DAYS, with
                                        allowWeekdaySubstitution true and no
                                        daysOfWeek sent. 0 when the cadence
                                        changed in a way you did not authorise,
                                        which includes every change to how OFTEN
                                        sessions occur (INTERVAL_TIGHTENED,
                                        DAYS_ADDED): allowing weekday
                                        substitution does not authorise a
                                        frequency change, and sending an
                                        explicit daysOfWeek withdraws the
                                        authorisation, because naming your
                                        weekdays says the weekdays are the
                                        point. Absent rather than 0 on a slate
                                        that follows no cadence at all — a
                                        DIRECT_FILL slate and a PARTIAL slate
                                        are both greedy fills that never consult
                                        your rrule, so how well they match a
                                        requested cadence is unanswerable rather
                                        than zero, and matchScore is the mean of
                                        the components that remain. Absent too
                                        when you sent no rrule.
                                  description: >-
                                    How well this slate matches the requested
                                    schedule preferences, broken down by
                                    criterion. Only the criteria the caller
                                    supplied are scored here — matchScore is the
                                    mean of exactly these. Present but empty
                                    when the caller expressed no schedule
                                    preferences at all; see matchScore’s
                                    description for why that case is 1 here
                                    rather than an absent availabilityMatch.
                                    Also absent on a slate whose matchScore
                                    carries no recorded per-criterion breakdown.
                                    These names mirror the components object
                                    inside availabilityMatch on
                                    /availability/suppliers but NOT their
                                    meaning: there each ratio is measured over
                                    the supplier’s open availability, while here
                                    every ratio is measured over this slate’s
                                    own sessions — a slate of eight Friday
                                    sessions scores 1 on daysOfWeek because all
                                    eight sessions are Fridays, independent of
                                    what a supplier-level daysOfWeek would
                                    report.
                              required:
                                - slateId
                                - supplierId
                                - completeness
                                - sessionsRequested
                                - sessionsFilled
                                - startTimeConsistencyPercent
                                - totalTravelTimeMins
                                - slots
                                - matchNotes
                                - matchScore
                            description: >-
                              Other bookable options beyond primarySlate, ranked
                              best first and capped at the maxAlternates you
                              sent. Under the default supplierPolicy of
                              SAME_SUPPLIER these are other schedules from the
                              SAME supplier as primarySlate; under PREFERRED or
                              ANY they are other suppliers’ best schedules, one
                              per supplier. Two schedules from one supplier
                              count as different options only when they run on
                              different weekdays, or start at least 30 minutes
                              apart — so a supplier offering 09:00 and 09:20
                              gives you one option, not two. Each entry’s
                              slateId is bookable exactly like primarySlate’s.
                          partial:
                            type: object
                            nullable: true
                            properties:
                              slateId:
                                type: string
                                description: >-
                                  Pass this to POST .../package-bookings to book
                                  the whole plan.
                                example: slate_01kx16ejsqffc9rbgdcc591w2p
                              supplierId:
                                type: string
                              completeness:
                                type: string
                                enum:
                                  - COMPLETE
                                  - PARTIAL
                              sessionsRequested:
                                type: integer
                                minimum: 0
                                exclusiveMinimum: true
                                description: >-
                                  How many sessions were requested (the
                                  package's creditCount).
                              sessionsFilled:
                                type: integer
                                minimum: 0
                                description: >-
                                  How many of the requested sessions the plan
                                  could fill.
                              startTimeConsistencyPercent:
                                type: number
                                minimum: 0
                                maximum: 100
                              totalTravelTimeMins:
                                type: number
                                minimum: 0
                              slots:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    slotId:
                                      type: string
                                      description: >-
                                        Id of one session; pass a subset of
                                        these as slotIds to cherry-pick.
                                    sessionIndex:
                                      type: integer
                                      minimum: 0
                                      exclusiveMinimum: true
                                      description: >-
                                        1-based index of this session within the
                                        slate.
                                    supplierId:
                                      type: string
                                    serviceId:
                                      type: string
                                    offeringId:
                                      type: string
                                    bookingStartUtc:
                                      type: string
                                      format: date-time
                                    bookingEndUtc:
                                      type: string
                                      format: date-time
                                    bookingTz:
                                      type: string
                                    locationType:
                                      type: string
                                      enum:
                                        - PHYSICAL
                                        - VIRTUAL
                                        - TRAVEL_ZONE
                                    locationId:
                                      type: string
                                      nullable: true
                                    latitude:
                                      type: number
                                      nullable: true
                                    longitude:
                                      type: number
                                      nullable: true
                                    address:
                                      $ref: '#/components/schemas/Address'
                                    travelTimeMins:
                                      type: number
                                      nullable: true
                                      minimum: 0
                                    capacity:
                                      type: integer
                                      minimum: 0
                                      exclusiveMinimum: true
                                    reservationStatus:
                                      type: string
                                      enum:
                                        - FREE
                                        - HELD
                                        - CONVERTED
                                        - RELEASED
                                  required:
                                    - slotId
                                    - sessionIndex
                                    - supplierId
                                    - serviceId
                                    - offeringId
                                    - bookingStartUtc
                                    - bookingEndUtc
                                    - bookingTz
                                    - locationType
                                    - locationId
                                    - latitude
                                    - longitude
                                    - address
                                    - travelTimeMins
                                    - capacity
                                    - reservationStatus
                              position:
                                type: integer
                                minimum: 0
                                description: >-
                                  0-based rank of this slate across the whole
                                  response: primarySlate is 0, then alternates,
                                  then partial, then cadenceAlternatives, in the
                                  order returned. Absent on slates built before
                                  this field existed.
                                example: 0
                              cadenceRrule:
                                type: string
                                nullable: true
                                description: >-
                                  The recurrence rule this slate’s sessions
                                  actually follow. Null for a direct fill (no
                                  recurrence rule at all). This is PROVENANCE —
                                  it records how the slate was generated and is
                                  NOT re-validated if a slot is later
                                  rescheduled.
                                example: FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8
                              matchesRequestedCadence:
                                type: boolean
                                description: >-
                                  True when cadenceRrule is the rrule you asked
                                  for.
                                example: false
                              cadenceRelaxation:
                                type: string
                                enum:
                                  - EXACT
                                  - INTERVAL_TIGHTENED
                                  - DAYS_ADDED
                                  - DAYS_SUBSTITUTED
                                  - ALL_WORKING_DAYS
                                  - DIRECT_FILL
                                description: >-
                                  How this slate’s cadence was derived from the
                                  one you requested. EXACT matches the request.
                                  INTERVAL_TIGHTENED keeps the requested
                                  weekdays but runs more often. DAYS_ADDED keeps
                                  every requested weekday and adds more.
                                  DAYS_SUBSTITUTED replaces them with weekdays
                                  the supplier actually works. ALL_WORKING_DAYS
                                  uses every weekday the supplier works.
                                  DIRECT_FILL follows no recurrence rule at all
                                  — it is the supplier’s real openings, one
                                  session per day.
                              cadenceDistance:
                                type: integer
                                minimum: 0
                                description: >-
                                  How far this slate’s cadence is from the one
                                  you requested — 0 is an exact match, lower is
                                  closer. When the request carries no
                                  sessionsPerWeek target, cadenceAlternatives is
                                  sorted by this value alone, closest first.
                                  When it does carry a target, alternatives are
                                  ranked by closeness to that target first, and
                                  this distance only breaks ties between
                                  cadences equally close to it.
                                example: 2
                              cadenceSummary:
                                type: object
                                properties:
                                  requested:
                                    type: integer
                                    nullable: true
                                    minimum: 0
                                    exclusiveMinimum: true
                                    description: >-
                                      The frequency you asked for, in sessions
                                      per week. Your sessionsPerWeek target when
                                      you sent one; otherwise counted from the
                                      weekdays your own rrule named
                                      (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null
                                      when you expressed no frequency at all,
                                      and also null when the rrule was not yours
                                      — a non-weekly FREQ, an INTERVAL other
                                      than 1, a weekly rule naming no weekdays
                                      at all, or a rule this API synthesised for
                                      you — because reporting a frequency you
                                      never asked for is worse than reporting
                                      none.
                                    example: 4
                                  peak:
                                    type: integer
                                    minimum: 0
                                    exclusiveMinimum: true
                                    description: >-
                                      The most sessions this slate holds in any
                                      single week — the number to render as
                                      "4×/week". This is the honest answer to
                                      "how often is this plan", and it is
                                      deliberately NOT an average: when a
                                      supplier has a break mid-plan, an average
                                      reports a rate that none of the weeks
                                      actually run at (nine sessions split
                                      1/0/4/4 averages 2.25, while the plan
                                      plainly runs at four a week wherever it
                                      runs).
                                    example: 4
                                  average:
                                    type: number
                                    minimum: 0
                                    description: >-
                                      Sessions divided by the number of weeks in
                                      byWeek, to 2 decimal places — so you can
                                      verify it against byWeek yourself. Weeks
                                      are counted across the PLAN’s span (first
                                      session’s week through last session’s
                                      week, gap weeks included), never across
                                      your whole lookAhead window, so a wide
                                      window does not dilute it. Prefer peak for
                                      client-facing copy; this number is for
                                      capacity and reporting.
                                    example: 2.25
                                  byWeek:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) that
                                            starts this week.
                                          example: '2026-09-14'
                                        sessions:
                                          type: integer
                                          minimum: 0
                                          description: >-
                                            Sessions this slate holds in this week.
                                            0 is a real value and the most
                                            informative entry in the array — it is a
                                            week inside the plan where the supplier
                                            had nothing.
                                          example: 0
                                      required:
                                        - weekStart
                                        - sessions
                                    minItems: 1
                                    description: >-
                                      Every Monday-anchored week from the first
                                      session’s week through the last session’s,
                                      ascending and contiguous, including weeks
                                      holding zero sessions. A zero week is how
                                      you show a client WHY the plan looks
                                      uneven — it is a week the supplier could
                                      not serve, not a gap in this data. Never
                                      empty: a slate with no sessions omits
                                      cadenceSummary entirely rather than
                                      publishing an empty array.
                                required:
                                  - requested
                                  - peak
                                  - average
                                  - byWeek
                                description: >-
                                  How often this slate actually runs, against
                                  the frequency you asked for. Present on every
                                  slate holding at least one session, on every
                                  request — absent only for a slate with no
                                  sessions, which has no cadence to describe.
                                  Render peak, not average: see peak’s
                                  description for why. IMPORTANT: the weeks here
                                  are Monday-anchored CALENDAR weeks, bucketed
                                  the same way as the maxSessionsPerWeek cap.
                                  matchComponents.sessionsPerWeek counts weeks
                                  differently — consecutive 7-day blocks from
                                  your window’s start, so it stays comparable
                                  with availabilityMatch on
                                  /availability/suppliers. The two can therefore
                                  disagree, and both are right: peak can read 4
                                  against a target of 4 while that component
                                  reads below 1, which is exactly what a
                                  supplier’s mid-plan break looks like.
                              matchNotes:
                                type: array
                                items:
                                  oneOf:
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - SUPPLIER_UNAVAILABLE_WEEK
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            openingsInPool:
                                              type: integer
                                              minimum: 0
                                              description: >-
                                                Days in this week that held at least one
                                                open slot for this supplier, AFTER your
                                                own daysOfWeek and excludeDates filters
                                                were applied. It counts PLACEABLE DAYS,
                                                not raw slots: a plan places at most one
                                                session per local date, so a day
                                                offering five start times counts once
                                                here. That is what makes this number
                                                directly comparable to sessionsTargeted.
                                              example: 2
                                            supplierWorkdays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: >-
                                                The weekdays this supplier works, BEFORE
                                                your filters. Empty here — that is what
                                                makes this code distinct from
                                                WEEK_EXCLUDED_BY_FILTERS.
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - openingsInPool
                                            - supplierWorkdays
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This supplier works NONE of the weekdays
                                        that could have served this week —
                                        supplierWorkdays is empty. Read that as
                                        a fact about their working PATTERN, not
                                        as a check of this particular calendar
                                        week: we do not expand schedule
                                        recurrence to ask whether this specific
                                        week was covered, so a supplier who
                                        works Mondays but was booked or blocked
                                        on this week’s Monday reports a
                                        different code, not this one. Sessions
                                        moved to neighbouring weeks. This is the
                                        case where "wait a week" is the right
                                        thing to tell a client; see the advice
                                        field, which may name the week supply
                                        resumes.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - WEEK_EXCLUDED_BY_FILTERS
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            filter:
                                              type: string
                                              enum:
                                                - daysOfWeek
                                                - excludeDates
                                            supplierWorkdays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            requestedDays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            excludedDates:
                                              type: array
                                              items:
                                                type: string
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - filter
                                            - supplierWorkdays
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        Your own daysOfWeek or excludeDates cut
                                        this week’s candidate days to fewer than
                                        you asked for, and the supplier’s
                                        working PATTERN covers enough days in
                                        this week to have met your target
                                        without that filter. Read
                                        supplierWorkdays exactly as
                                        SUPPLIER_UNAVAILABLE_WEEK asks you to
                                        read it: a fact about which weekdays
                                        this supplier works AT ALL, not a check
                                        of this particular calendar week. We do
                                        not expand schedule recurrence to ask
                                        whether those pattern days were actually
                                        free, so a Mon–Fri supplier already
                                        booked solid across this week reports
                                        this code too. Loosening the filter
                                        named in evidence.filter is therefore
                                        the LIKELY fix, not a guaranteed one —
                                        but it is the best move the data
                                        supports, because a week the supplier’s
                                        pattern could never have met is reported
                                        as WEEK_SUPPLY_INSUFFICIENT instead and
                                        is not your filter’s fault. The one
                                        exception is a daysOfWeek that names no
                                        day this supplier works at all, which
                                        leaves zero candidate days whatever your
                                        target. The opposite call to action from
                                        SUPPLIER_UNAVAILABLE_WEEK: waiting is
                                        not what this code points at, loosening
                                        your filter is.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - WEEK_SUPPLY_INSUFFICIENT
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            openingsInPool:
                                              type: integer
                                              minimum: 0
                                              description: >-
                                                Days in this week that held at least one
                                                open slot for this supplier, AFTER your
                                                own daysOfWeek and excludeDates filters
                                                were applied. It counts PLACEABLE DAYS,
                                                not raw slots: a plan places at most one
                                                session per local date, so a day
                                                offering five start times counts once
                                                here. That is what makes this number
                                                directly comparable to sessionsTargeted.
                                              example: 2
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - openingsInPool
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This week holds fewer sessions than you
                                        asked for and none of the more specific
                                        reasons could be ESTABLISHED. This is
                                        the RESIDUAL code, not a positive
                                        finding about supply: it says only that
                                        this supplier’s working PATTERN is not
                                        empty — a fact about which weekdays they
                                        work AT ALL, not a check of this
                                        calendar week, which is what rules out
                                        SUPPLIER_UNAVAILABLE_WEEK — and that we
                                        could not attribute the shortfall to one
                                        of your filters or to a cap you sent. It
                                        does NOT say a filter or a cap played no
                                        part. Two cases land here with one of
                                        them genuinely involved: a filter that
                                        removed a candidate day from a week the
                                        supplier’s own pattern days could never
                                        have met anyway (attribution is withheld
                                        because loosening the filter provably
                                        could not have reached your target), and
                                        a cap that applied to a week whose
                                        openings were already below your target
                                        (WEEK_CAPPED is reserved for weeks that
                                        had enough openings to make the cap the
                                        thing to raise). So compare
                                        sessionsPlaced and sessionsTargeted
                                        against openingsInPool to see what the
                                        constraint was, rather than assuming a
                                        cause. Below the target, openingsInPool
                                        says the placeable days were not there.
                                        At or above it, the days were there and
                                        the shortfall came from something other
                                        than supply — check the slate for
                                        CADENCE_RELAXED, which reports a cadence
                                        that could not use them and is then the
                                        better thing to tell a client. That
                                        pointer does not always land:
                                        CADENCE_RELAXED is emitted only when the
                                        cadence component scored below 1, and an
                                        AUTHORISED weekday substitution scores a
                                        perfect cadence, so a days-were-there
                                        week can carry no cadence note at all.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - WEEK_CAPPED
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsPlaced:
                                              type: integer
                                              minimum: 0
                                              description: Sessions this slate placed in this week.
                                            sessionsTargeted:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                              description: >-
                                                Sessions you asked for in a week — your
                                                sessionsPerWeek target.
                                            cap:
                                              type: string
                                              enum:
                                                - maxSessionsPerWeek
                                                - minGapDays
                                            capValue:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                          required:
                                            - sessionsPlaced
                                            - sessionsTargeted
                                            - cap
                                            - capValue
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This week held at least sessionsTargeted
                                        placeable days, and a cap YOU sent —
                                        maxSessionsPerWeek or minGapDays — puts
                                        a ceiling on the week that is BELOW your
                                        target, so your target was unreachable
                                        in this week whatever the supplier had
                                        free. Raising the cap named in
                                        evidence.cap is therefore NECESSARY if
                                        you want this week to meet your target.
                                        Whether it is SUFFICIENT is not
                                        something this note can tell you: the
                                        code fires on that ceiling EXISTING, not
                                        on the plan having filled up to it, so
                                        sessionsPlaced can sit below the ceiling
                                        — when it does, all that is established
                                        is that the plan did not fill the week
                                        even to the ceiling. Do not read that
                                        either way; nothing here says what else
                                        was or was not in the way. (capValue is
                                        the number you sent. For minGapDays that
                                        is the gap, not the weekly ceiling it
                                        implies: a gap of 3 admits at most three
                                        sessions in a seven-day week.)
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - SESSIONS_EXHAUSTED
                                        component:
                                          type: string
                                          enum:
                                            - sessionsPerWeek
                                        weekStart:
                                          type: string
                                          pattern: ^\d{4}-\d{2}-\d{2}$
                                          description: >-
                                            The Monday (YYYY-MM-DD, local) starting
                                            the week this note is about.
                                          example: '2026-09-14'
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsRequested:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                            sessionsPlacedBefore:
                                              type: integer
                                              minimum: 0
                                          required:
                                            - sessionsRequested
                                            - sessionsPlacedBefore
                                      required:
                                        - code
                                        - component
                                        - weekStart
                                        - evidence
                                      description: >-
                                        This week is short only because the
                                        package ran out of sessions — nine
                                        sessions at four a week leaves the last
                                        week holding one. NOTHING went wrong
                                        here, and no supply code is emitted for
                                        this week: do not apologise for it in
                                        your copy.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - CADENCE_RELAXED
                                        component:
                                          type: string
                                          enum:
                                            - cadence
                                        evidence:
                                          type: object
                                          properties:
                                            cadenceRelaxation:
                                              type: string
                                              enum:
                                                - EXACT
                                                - INTERVAL_TIGHTENED
                                                - DAYS_ADDED
                                                - DAYS_SUBSTITUTED
                                                - ALL_WORKING_DAYS
                                                - DIRECT_FILL
                                              description: >-
                                                How this slate’s cadence was derived
                                                from the one you requested. EXACT
                                                matches the request. INTERVAL_TIGHTENED
                                                keeps the requested weekdays but runs
                                                more often. DAYS_ADDED keeps every
                                                requested weekday and adds more.
                                                DAYS_SUBSTITUTED replaces them with
                                                weekdays the supplier actually works.
                                                ALL_WORKING_DAYS uses every weekday the
                                                supplier works. DIRECT_FILL follows no
                                                recurrence rule at all — it is the
                                                supplier’s real openings, one session
                                                per day.
                                            requestedDays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            actualDays:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                maximum: 6
                                              description: Weekdays as 0 = Sunday … 6 = Saturday.
                                          required:
                                            - cadenceRelaxation
                                      required:
                                        - code
                                        - component
                                        - evidence
                                      description: >-
                                        This slate does not run at the rrule you
                                        sent. cadenceRelaxation says how it was
                                        derived; requestedDays and actualDays
                                        let you show the swap.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - SESSIONS_OUTSIDE_PREFERRED_TIMES
                                        component:
                                          type: string
                                          enum:
                                            - timeOfDay
                                        evidence:
                                          type: object
                                          properties:
                                            sessionIndexes:
                                              type: array
                                              items:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                            localTimes:
                                              type: array
                                              items:
                                                type: string
                                          required:
                                            - sessionIndexes
                                            - localTimes
                                      required:
                                        - code
                                        - component
                                        - evidence
                                      description: >-
                                        These sessions (1-based, matching
                                        sessionIndex on each slot) fall outside
                                        every preferredTimes window you sent.
                                        localTimes is aligned to sessionIndexes.
                                        BOTH ARRAYS CAN BE EMPTY: when no
                                        session of this slate lands inside your
                                        requested window at all, the criterion
                                        definitely missed and this note is
                                        emitted, but there is no in-window
                                        session to name — so treat empty arrays
                                        as "outside your preferred times, with
                                        nothing to point at", not as an error.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - FIRST_SESSION_LATE
                                        component:
                                          type: string
                                          enum:
                                            - startDate
                                        evidence:
                                          type: object
                                          properties:
                                            firstSessionDate:
                                              type: string
                                            windowStartDate:
                                              type: string
                                            dayOffset:
                                              type: integer
                                              minimum: 0
                                            earlierSupplyExisted:
                                              type: boolean
                                              description: >-
                                                TRUE when the supplier had open slots
                                                before the first session but the cadence
                                                could not use them — so the late start
                                                is the rrule, not a lack of
                                                availability.
                                          required:
                                            - firstSessionDate
                                            - windowStartDate
                                            - dayOffset
                                            - earlierSupplyExisted
                                      required:
                                        - code
                                        - component
                                        - evidence
                                      description: >-
                                        The plan’s first session is
                                        evidence.dayOffset whole local days
                                        after your window start — that offset is
                                        the fact this code reports, and it is
                                        always at least one day. Whether the
                                        plan started later than it HAD to is a
                                        separate question, answered by
                                        evidence.earlierSupplyExisted: TRUE
                                        means the supplier had open days before
                                        that first session and the cadence could
                                        not use them, so an earlier start really
                                        was there to be had and loosening the
                                        cadence is the fix. FALSE means we found
                                        no opening earlier in your window, so
                                        this is simply where the supplier’s
                                        supply began — nothing was given up, and
                                        copy saying otherwise would be wrong.
                                    - type: object
                                      properties:
                                        code:
                                          type: string
                                          enum:
                                            - PACKAGE_UNDERFILLED
                                        evidence:
                                          type: object
                                          properties:
                                            sessionsRequested:
                                              type: integer
                                              minimum: 0
                                              exclusiveMinimum: true
                                            sessionsFilled:
                                              type: integer
                                              minimum: 0
                                          required:
                                            - sessionsRequested
                                            - sessionsFilled
                                      required:
                                        - code
                                        - evidence
                                      description: >-
                                        Fewer sessions than the package holds
                                        credits for. This slate is PARTIAL —
                                        completeness says so too, and it is not
                                        a matchScore component, so a PARTIAL
                                        slate can still score 1.
                                description: >-
                                  Why this slate departs from what you asked for
                                  — one entry per reason, each a code plus
                                  structured evidence, and no English so you can
                                  write your own copy. ALWAYS PRESENT: empty
                                  means nothing departed, so you can read
                                  .length without a null check. NOT gated on
                                  matchScore — a DIRECT_FILL slate and a PARTIAL
                                  slate can both score 1 and still carry notes,
                                  and those are exactly the slates worth
                                  captioning. Read matchComponents for WHICH
                                  criterion missed and these for WHY. IMPORTANT:
                                  the two count weeks differently, so that
                                  pairing is a guide, not a join key. The
                                  week-level codes here bucket Monday-anchored
                                  CALENDAR weeks — the same bucketing as
                                  cadenceSummary.byWeek and the
                                  maxSessionsPerWeek cap — while
                                  matchComponents.sessionsPerWeek buckets
                                  consecutive 7-day blocks from your window’s
                                  start. The two can therefore disagree, and
                                  both are right: a note can name a short week
                                  for a criterion that component scores as met,
                                  and the reverse. Join a note to
                                  cadenceSummary.byWeek on weekStart, which does
                                  share this bucketing; treat matchComponents as
                                  the per-criterion score, not as a per-week
                                  one.
                              advice:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    enum:
                                      - LATER_START_IMPROVES_CADENCE
                                  earliestSustainedWeek:
                                    type: string
                                    pattern: ^\d{4}-\d{2}-\d{2}$
                                    description: >-
                                      The earliest Monday from which supply
                                      alone could sustain your requested
                                      frequency. Always STRICTLY LATER than the
                                      first week matchNotes reported as short —
                                      this field means "start later", so it
                                      never names a week the notes just
                                      condemned.
                                    example: '2026-09-14'
                                required:
                                  - code
                                  - earliestSustainedWeek
                                description: >-
                                  An advisory hint about a later start, present
                                  only when one applies. Read AdviceSchema’s own
                                  description first: it reports that SUPPLY
                                  exists, not that a slate was built.
                              matchScore:
                                type: number
                                minimum: 0
                                maximum: 1
                                description: >-
                                  How well this slate matches the requested
                                  schedule preferences, from 0 to 1 — the mean
                                  of the components present in matchComponents.
                                  When the caller expressed no schedule
                                  preferences it is 1 and matchComponents is
                                  empty, so a caller distinguishes "perfect
                                  match" from "nothing asked" by reading
                                  matchComponents, not this score. Compare the
                                  availabilityMatch property on
                                  /availability/suppliers, which is ABSENT
                                  entirely for the "nothing asked" case rather
                                  than present with a null score — matchScore
                                  cannot go absent, because it is a required
                                  property on this shipped contract and dropping
                                  it would break the generated SDK types. The
                                  results are already ranked: primarySlate is
                                  the best-matching COMPLETE slate and
                                  alternates follow it in descending order, with
                                  completeness always outranking this score, so
                                  a COMPLETE slate never sits below a PARTIAL
                                  one that scored higher. (cadenceAlternatives
                                  is ordered separately, closest-cadence first.)
                                  Do NOT re-sort the slates you receive by
                                  matchScore: the order carries preferences this
                                  number cannot. matchComponents.sessionsPerWeek
                                  scores a week holding AT LEAST the
                                  sessionsPerWeek you asked for, so against a
                                  target of 2 a slate delivering three sessions
                                  a week scores identically to one delivering
                                  two, and only the order distinguishes them.
                                  Re-sorting silently discards that. This score
                                  is also not a cadence: read
                                  cadenceSummary.peak for how often the plan
                                  actually runs, and cadenceSummary.byWeek for
                                  which weeks are short and why the two numbers
                                  can differ.
                                example: 1
                              matchComponents:
                                type: object
                                properties:
                                  startDate:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      How soon this slate’s first session lands
                                      in the requested window — 1 when session
                                      one lands as early as possible in the
                                      window, lower the later it lands.
                                  timeOfDay:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      Fraction of this slate’s sessions that
                                      fall at a preferred time of day.
                                  daysOfWeek:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      Fraction of this slate’s sessions that
                                      fall on a requested weekday.
                                  sessionsPerWeek:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      Fraction of the window’s whole weeks in
                                      which this slate holds at least the
                                      requested number of sessions — a match
                                      ratio in [0, 1], not a count. For counts
                                      see cadenceSummary, whose peak is the
                                      number to render as "4×/week". THE TWO
                                      COUNT WEEKS DIFFERENTLY, deliberately:
                                      this ratio buckets consecutive 7-day
                                      blocks from your window’s start, so it
                                      stays comparable with availabilityMatch on
                                      /availability/suppliers, while
                                      cadenceSummary uses Monday-anchored
                                      calendar weeks so its weekStart dates are
                                      real Mondays and agree with the
                                      maxSessionsPerWeek cap. Expect them to
                                      disagree on a plan spanning a supplier’s
                                      break — cadenceSummary.peak can read 4
                                      against a target of 4 while this ratio
                                      reads below 1, and both are correct for
                                      what they measure. AT LEAST is literal:
                                      against a target of 2, a week holding 3
                                      sessions counts exactly as a week holding
                                      2, so a denser slate never scores worse
                                      here. The preference for two over three is
                                      expressed only in the ORDER slates come
                                      back in — see matchScore.
                                  cadence:
                                    type: number
                                    minimum: 0
                                    maximum: 1
                                    description: >-
                                      1 when this slate runs at the cadence you
                                      requested, and also 1 when the only
                                      departure from it was a weekday
                                      substitution you authorised —
                                      cadenceRelaxation of DAYS_SUBSTITUTED or
                                      ALL_WORKING_DAYS, with
                                      allowWeekdaySubstitution true and no
                                      daysOfWeek sent. 0 when the cadence
                                      changed in a way you did not authorise,
                                      which includes every change to how OFTEN
                                      sessions occur (INTERVAL_TIGHTENED,
                                      DAYS_ADDED): allowing weekday substitution
                                      does not authorise a frequency change, and
                                      sending an explicit daysOfWeek withdraws
                                      the authorisation, because naming your
                                      weekdays says the weekdays are the point.
                                      Absent rather than 0 on a slate that
                                      follows no cadence at all — a DIRECT_FILL
                                      slate and a PARTIAL slate are both greedy
                                      fills that never consult your rrule, so
                                      how well they match a requested cadence is
                                      unanswerable rather than zero, and
                                      matchScore is the mean of the components
                                      that remain. Absent too when you sent no
                                      rrule.
                                description: >-
                                  How well this slate matches the requested
                                  schedule preferences, broken down by
                                  criterion. Only the criteria the caller
                                  supplied are scored here — matchScore is the
                                  mean of exactly these. Present but empty when
                                  the caller expressed no schedule preferences
                                  at all; see matchScore’s description for why
                                  that case is 1 here rather than an absent
                                  availabilityMatch. Also absent on a slate
                                  whose matchScore carries no recorded
                                  per-criterion breakdown. These names mirror
                                  the components object inside availabilityMatch
                                  on /availability/suppliers but NOT their
                                  meaning: there each ratio is measured over the
                                  supplier’s open availability, while here every
                                  ratio is measured over this slate’s own
                                  sessions — a slate of eight Friday sessions
                                  scores 1 on daysOfWeek because all eight
                                  sessions are Fridays, independent of what a
                                  supplier-level daysOfWeek would report.
                            required:
                              - slateId
                              - supplierId
                              - completeness
                              - sessionsRequested
                              - sessionsFilled
                              - startTimeConsistencyPercent
                              - totalTravelTimeMins
                              - slots
                              - matchNotes
                              - matchScore
                          cadenceAlternatives:
                            type: array
                            items:
                              type: object
                              properties:
                                slateId:
                                  type: string
                                  description: >-
                                    Pass this to POST .../package-bookings to
                                    book the whole plan.
                                  example: slate_01kx16ejsqffc9rbgdcc591w2p
                                supplierId:
                                  type: string
                                completeness:
                                  type: string
                                  enum:
                                    - COMPLETE
                                    - PARTIAL
                                sessionsRequested:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                  description: >-
                                    How many sessions were requested (the
                                    package's creditCount).
                                sessionsFilled:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    How many of the requested sessions the plan
                                    could fill.
                                startTimeConsistencyPercent:
                                  type: number
                                  minimum: 0
                                  maximum: 100
                                totalTravelTimeMins:
                                  type: number
                                  minimum: 0
                                slots:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      slotId:
                                        type: string
                                        description: >-
                                          Id of one session; pass a subset of
                                          these as slotIds to cherry-pick.
                                      sessionIndex:
                                        type: integer
                                        minimum: 0
                                        exclusiveMinimum: true
                                        description: >-
                                          1-based index of this session within the
                                          slate.
                                      supplierId:
                                        type: string
                                      serviceId:
                                        type: string
                                      offeringId:
                                        type: string
                                      bookingStartUtc:
                                        type: string
                                        format: date-time
                                      bookingEndUtc:
                                        type: string
                                        format: date-time
                                      bookingTz:
                                        type: string
                                      locationType:
                                        type: string
                                        enum:
                                          - PHYSICAL
                                          - VIRTUAL
                                          - TRAVEL_ZONE
                                      locationId:
                                        type: string
                                        nullable: true
                                      latitude:
                                        type: number
                                        nullable: true
                                      longitude:
                                        type: number
                                        nullable: true
                                      address:
                                        $ref: '#/components/schemas/Address'
                                      travelTimeMins:
                                        type: number
                                        nullable: true
                                        minimum: 0
                                      capacity:
                                        type: integer
                                        minimum: 0
                                        exclusiveMinimum: true
                                      reservationStatus:
                                        type: string
                                        enum:
                                          - FREE
                                          - HELD
                                          - CONVERTED
                                          - RELEASED
                                    required:
                                      - slotId
                                      - sessionIndex
                                      - supplierId
                                      - serviceId
                                      - offeringId
                                      - bookingStartUtc
                                      - bookingEndUtc
                                      - bookingTz
                                      - locationType
                                      - locationId
                                      - latitude
                                      - longitude
                                      - address
                                      - travelTimeMins
                                      - capacity
                                      - reservationStatus
                                position:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    0-based rank of this slate across the whole
                                    response: primarySlate is 0, then
                                    alternates, then partial, then
                                    cadenceAlternatives, in the order returned.
                                    Absent on slates built before this field
                                    existed.
                                  example: 0
                                cadenceRrule:
                                  type: string
                                  nullable: true
                                  description: >-
                                    The recurrence rule this slate’s sessions
                                    actually follow. Null for a direct fill (no
                                    recurrence rule at all). This is PROVENANCE
                                    — it records how the slate was generated and
                                    is NOT re-validated if a slot is later
                                    rescheduled.
                                  example: FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8
                                matchesRequestedCadence:
                                  type: boolean
                                  description: >-
                                    True when cadenceRrule is the rrule you
                                    asked for.
                                  example: false
                                cadenceRelaxation:
                                  type: string
                                  enum:
                                    - EXACT
                                    - INTERVAL_TIGHTENED
                                    - DAYS_ADDED
                                    - DAYS_SUBSTITUTED
                                    - ALL_WORKING_DAYS
                                    - DIRECT_FILL
                                  description: >-
                                    How this slate’s cadence was derived from
                                    the one you requested. EXACT matches the
                                    request. INTERVAL_TIGHTENED keeps the
                                    requested weekdays but runs more often.
                                    DAYS_ADDED keeps every requested weekday and
                                    adds more. DAYS_SUBSTITUTED replaces them
                                    with weekdays the supplier actually works.
                                    ALL_WORKING_DAYS uses every weekday the
                                    supplier works. DIRECT_FILL follows no
                                    recurrence rule at all — it is the
                                    supplier’s real openings, one session per
                                    day.
                                cadenceDistance:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    How far this slate’s cadence is from the one
                                    you requested — 0 is an exact match, lower
                                    is closer. When the request carries no
                                    sessionsPerWeek target, cadenceAlternatives
                                    is sorted by this value alone, closest
                                    first. When it does carry a target,
                                    alternatives are ranked by closeness to that
                                    target first, and this distance only breaks
                                    ties between cadences equally close to it.
                                  example: 2
                                cadenceSummary:
                                  type: object
                                  properties:
                                    requested:
                                      type: integer
                                      nullable: true
                                      minimum: 0
                                      exclusiveMinimum: true
                                      description: >-
                                        The frequency you asked for, in sessions
                                        per week. Your sessionsPerWeek target
                                        when you sent one; otherwise counted
                                        from the weekdays your own rrule named
                                        (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4).
                                        Null when you expressed no frequency at
                                        all, and also null when the rrule was
                                        not yours — a non-weekly FREQ, an
                                        INTERVAL other than 1, a weekly rule
                                        naming no weekdays at all, or a rule
                                        this API synthesised for you — because
                                        reporting a frequency you never asked
                                        for is worse than reporting none.
                                      example: 4
                                    peak:
                                      type: integer
                                      minimum: 0
                                      exclusiveMinimum: true
                                      description: >-
                                        The most sessions this slate holds in
                                        any single week — the number to render
                                        as "4×/week". This is the honest answer
                                        to "how often is this plan", and it is
                                        deliberately NOT an average: when a
                                        supplier has a break mid-plan, an
                                        average reports a rate that none of the
                                        weeks actually run at (nine sessions
                                        split 1/0/4/4 averages 2.25, while the
                                        plan plainly runs at four a week
                                        wherever it runs).
                                      example: 4
                                    average:
                                      type: number
                                      minimum: 0
                                      description: >-
                                        Sessions divided by the number of weeks
                                        in byWeek, to 2 decimal places — so you
                                        can verify it against byWeek yourself.
                                        Weeks are counted across the PLAN’s span
                                        (first session’s week through last
                                        session’s week, gap weeks included),
                                        never across your whole lookAhead
                                        window, so a wide window does not dilute
                                        it. Prefer peak for client-facing copy;
                                        this number is for capacity and
                                        reporting.
                                      example: 2.25
                                    byWeek:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) that
                                              starts this week.
                                            example: '2026-09-14'
                                          sessions:
                                            type: integer
                                            minimum: 0
                                            description: >-
                                              Sessions this slate holds in this week.
                                              0 is a real value and the most
                                              informative entry in the array — it is a
                                              week inside the plan where the supplier
                                              had nothing.
                                            example: 0
                                        required:
                                          - weekStart
                                          - sessions
                                      minItems: 1
                                      description: >-
                                        Every Monday-anchored week from the
                                        first session’s week through the last
                                        session’s, ascending and contiguous,
                                        including weeks holding zero sessions. A
                                        zero week is how you show a client WHY
                                        the plan looks uneven — it is a week the
                                        supplier could not serve, not a gap in
                                        this data. Never empty: a slate with no
                                        sessions omits cadenceSummary entirely
                                        rather than publishing an empty array.
                                  required:
                                    - requested
                                    - peak
                                    - average
                                    - byWeek
                                  description: >-
                                    How often this slate actually runs, against
                                    the frequency you asked for. Present on
                                    every slate holding at least one session, on
                                    every request — absent only for a slate with
                                    no sessions, which has no cadence to
                                    describe. Render peak, not average: see
                                    peak’s description for why. IMPORTANT: the
                                    weeks here are Monday-anchored CALENDAR
                                    weeks, bucketed the same way as the
                                    maxSessionsPerWeek cap.
                                    matchComponents.sessionsPerWeek counts weeks
                                    differently — consecutive 7-day blocks from
                                    your window’s start, so it stays comparable
                                    with availabilityMatch on
                                    /availability/suppliers. The two can
                                    therefore disagree, and both are right: peak
                                    can read 4 against a target of 4 while that
                                    component reads below 1, which is exactly
                                    what a supplier’s mid-plan break looks like.
                                matchNotes:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - SUPPLIER_UNAVAILABLE_WEEK
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              openingsInPool:
                                                type: integer
                                                minimum: 0
                                                description: >-
                                                  Days in this week that held at least one
                                                  open slot for this supplier, AFTER your
                                                  own daysOfWeek and excludeDates filters
                                                  were applied. It counts PLACEABLE DAYS,
                                                  not raw slots: a plan places at most one
                                                  session per local date, so a day
                                                  offering five start times counts once
                                                  here. That is what makes this number
                                                  directly comparable to sessionsTargeted.
                                                example: 2
                                              supplierWorkdays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: >-
                                                  The weekdays this supplier works, BEFORE
                                                  your filters. Empty here — that is what
                                                  makes this code distinct from
                                                  WEEK_EXCLUDED_BY_FILTERS.
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - openingsInPool
                                              - supplierWorkdays
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This supplier works NONE of the weekdays
                                          that could have served this week —
                                          supplierWorkdays is empty. Read that as
                                          a fact about their working PATTERN, not
                                          as a check of this particular calendar
                                          week: we do not expand schedule
                                          recurrence to ask whether this specific
                                          week was covered, so a supplier who
                                          works Mondays but was booked or blocked
                                          on this week’s Monday reports a
                                          different code, not this one. Sessions
                                          moved to neighbouring weeks. This is the
                                          case where "wait a week" is the right
                                          thing to tell a client; see the advice
                                          field, which may name the week supply
                                          resumes.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - WEEK_EXCLUDED_BY_FILTERS
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              filter:
                                                type: string
                                                enum:
                                                  - daysOfWeek
                                                  - excludeDates
                                              supplierWorkdays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                              requestedDays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                              excludedDates:
                                                type: array
                                                items:
                                                  type: string
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - filter
                                              - supplierWorkdays
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          Your own daysOfWeek or excludeDates cut
                                          this week’s candidate days to fewer than
                                          you asked for, and the supplier’s
                                          working PATTERN covers enough days in
                                          this week to have met your target
                                          without that filter. Read
                                          supplierWorkdays exactly as
                                          SUPPLIER_UNAVAILABLE_WEEK asks you to
                                          read it: a fact about which weekdays
                                          this supplier works AT ALL, not a check
                                          of this particular calendar week. We do
                                          not expand schedule recurrence to ask
                                          whether those pattern days were actually
                                          free, so a Mon–Fri supplier already
                                          booked solid across this week reports
                                          this code too. Loosening the filter
                                          named in evidence.filter is therefore
                                          the LIKELY fix, not a guaranteed one —
                                          but it is the best move the data
                                          supports, because a week the supplier’s
                                          pattern could never have met is reported
                                          as WEEK_SUPPLY_INSUFFICIENT instead and
                                          is not your filter’s fault. The one
                                          exception is a daysOfWeek that names no
                                          day this supplier works at all, which
                                          leaves zero candidate days whatever your
                                          target. The opposite call to action from
                                          SUPPLIER_UNAVAILABLE_WEEK: waiting is
                                          not what this code points at, loosening
                                          your filter is.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - WEEK_SUPPLY_INSUFFICIENT
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              openingsInPool:
                                                type: integer
                                                minimum: 0
                                                description: >-
                                                  Days in this week that held at least one
                                                  open slot for this supplier, AFTER your
                                                  own daysOfWeek and excludeDates filters
                                                  were applied. It counts PLACEABLE DAYS,
                                                  not raw slots: a plan places at most one
                                                  session per local date, so a day
                                                  offering five start times counts once
                                                  here. That is what makes this number
                                                  directly comparable to sessionsTargeted.
                                                example: 2
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - openingsInPool
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This week holds fewer sessions than you
                                          asked for and none of the more specific
                                          reasons could be ESTABLISHED. This is
                                          the RESIDUAL code, not a positive
                                          finding about supply: it says only that
                                          this supplier’s working PATTERN is not
                                          empty — a fact about which weekdays they
                                          work AT ALL, not a check of this
                                          calendar week, which is what rules out
                                          SUPPLIER_UNAVAILABLE_WEEK — and that we
                                          could not attribute the shortfall to one
                                          of your filters or to a cap you sent. It
                                          does NOT say a filter or a cap played no
                                          part. Two cases land here with one of
                                          them genuinely involved: a filter that
                                          removed a candidate day from a week the
                                          supplier’s own pattern days could never
                                          have met anyway (attribution is withheld
                                          because loosening the filter provably
                                          could not have reached your target), and
                                          a cap that applied to a week whose
                                          openings were already below your target
                                          (WEEK_CAPPED is reserved for weeks that
                                          had enough openings to make the cap the
                                          thing to raise). So compare
                                          sessionsPlaced and sessionsTargeted
                                          against openingsInPool to see what the
                                          constraint was, rather than assuming a
                                          cause. Below the target, openingsInPool
                                          says the placeable days were not there.
                                          At or above it, the days were there and
                                          the shortfall came from something other
                                          than supply — check the slate for
                                          CADENCE_RELAXED, which reports a cadence
                                          that could not use them and is then the
                                          better thing to tell a client. That
                                          pointer does not always land:
                                          CADENCE_RELAXED is emitted only when the
                                          cadence component scored below 1, and an
                                          AUTHORISED weekday substitution scores a
                                          perfect cadence, so a days-were-there
                                          week can carry no cadence note at all.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - WEEK_CAPPED
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsPlaced:
                                                type: integer
                                                minimum: 0
                                                description: Sessions this slate placed in this week.
                                              sessionsTargeted:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                                description: >-
                                                  Sessions you asked for in a week — your
                                                  sessionsPerWeek target.
                                              cap:
                                                type: string
                                                enum:
                                                  - maxSessionsPerWeek
                                                  - minGapDays
                                              capValue:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                            required:
                                              - sessionsPlaced
                                              - sessionsTargeted
                                              - cap
                                              - capValue
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This week held at least sessionsTargeted
                                          placeable days, and a cap YOU sent —
                                          maxSessionsPerWeek or minGapDays — puts
                                          a ceiling on the week that is BELOW your
                                          target, so your target was unreachable
                                          in this week whatever the supplier had
                                          free. Raising the cap named in
                                          evidence.cap is therefore NECESSARY if
                                          you want this week to meet your target.
                                          Whether it is SUFFICIENT is not
                                          something this note can tell you: the
                                          code fires on that ceiling EXISTING, not
                                          on the plan having filled up to it, so
                                          sessionsPlaced can sit below the ceiling
                                          — when it does, all that is established
                                          is that the plan did not fill the week
                                          even to the ceiling. Do not read that
                                          either way; nothing here says what else
                                          was or was not in the way. (capValue is
                                          the number you sent. For minGapDays that
                                          is the gap, not the weekly ceiling it
                                          implies: a gap of 3 admits at most three
                                          sessions in a seven-day week.)
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - SESSIONS_EXHAUSTED
                                          component:
                                            type: string
                                            enum:
                                              - sessionsPerWeek
                                          weekStart:
                                            type: string
                                            pattern: ^\d{4}-\d{2}-\d{2}$
                                            description: >-
                                              The Monday (YYYY-MM-DD, local) starting
                                              the week this note is about.
                                            example: '2026-09-14'
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsRequested:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                              sessionsPlacedBefore:
                                                type: integer
                                                minimum: 0
                                            required:
                                              - sessionsRequested
                                              - sessionsPlacedBefore
                                        required:
                                          - code
                                          - component
                                          - weekStart
                                          - evidence
                                        description: >-
                                          This week is short only because the
                                          package ran out of sessions — nine
                                          sessions at four a week leaves the last
                                          week holding one. NOTHING went wrong
                                          here, and no supply code is emitted for
                                          this week: do not apologise for it in
                                          your copy.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - CADENCE_RELAXED
                                          component:
                                            type: string
                                            enum:
                                              - cadence
                                          evidence:
                                            type: object
                                            properties:
                                              cadenceRelaxation:
                                                type: string
                                                enum:
                                                  - EXACT
                                                  - INTERVAL_TIGHTENED
                                                  - DAYS_ADDED
                                                  - DAYS_SUBSTITUTED
                                                  - ALL_WORKING_DAYS
                                                  - DIRECT_FILL
                                                description: >-
                                                  How this slate’s cadence was derived
                                                  from the one you requested. EXACT
                                                  matches the request. INTERVAL_TIGHTENED
                                                  keeps the requested weekdays but runs
                                                  more often. DAYS_ADDED keeps every
                                                  requested weekday and adds more.
                                                  DAYS_SUBSTITUTED replaces them with
                                                  weekdays the supplier actually works.
                                                  ALL_WORKING_DAYS uses every weekday the
                                                  supplier works. DIRECT_FILL follows no
                                                  recurrence rule at all — it is the
                                                  supplier’s real openings, one session
                                                  per day.
                                              requestedDays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                              actualDays:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 6
                                                description: Weekdays as 0 = Sunday … 6 = Saturday.
                                            required:
                                              - cadenceRelaxation
                                        required:
                                          - code
                                          - component
                                          - evidence
                                        description: >-
                                          This slate does not run at the rrule you
                                          sent. cadenceRelaxation says how it was
                                          derived; requestedDays and actualDays
                                          let you show the swap.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - SESSIONS_OUTSIDE_PREFERRED_TIMES
                                          component:
                                            type: string
                                            enum:
                                              - timeOfDay
                                          evidence:
                                            type: object
                                            properties:
                                              sessionIndexes:
                                                type: array
                                                items:
                                                  type: integer
                                                  minimum: 0
                                                  exclusiveMinimum: true
                                              localTimes:
                                                type: array
                                                items:
                                                  type: string
                                            required:
                                              - sessionIndexes
                                              - localTimes
                                        required:
                                          - code
                                          - component
                                          - evidence
                                        description: >-
                                          These sessions (1-based, matching
                                          sessionIndex on each slot) fall outside
                                          every preferredTimes window you sent.
                                          localTimes is aligned to sessionIndexes.
                                          BOTH ARRAYS CAN BE EMPTY: when no
                                          session of this slate lands inside your
                                          requested window at all, the criterion
                                          definitely missed and this note is
                                          emitted, but there is no in-window
                                          session to name — so treat empty arrays
                                          as "outside your preferred times, with
                                          nothing to point at", not as an error.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - FIRST_SESSION_LATE
                                          component:
                                            type: string
                                            enum:
                                              - startDate
                                          evidence:
                                            type: object
                                            properties:
                                              firstSessionDate:
                                                type: string
                                              windowStartDate:
                                                type: string
                                              dayOffset:
                                                type: integer
                                                minimum: 0
                                              earlierSupplyExisted:
                                                type: boolean
                                                description: >-
                                                  TRUE when the supplier had open slots
                                                  before the first session but the cadence
                                                  could not use them — so the late start
                                                  is the rrule, not a lack of
                                                  availability.
                                            required:
                                              - firstSessionDate
                                              - windowStartDate
                                              - dayOffset
                                              - earlierSupplyExisted
                                        required:
                                          - code
                                          - component
                                          - evidence
                                        description: >-
                                          The plan’s first session is
                                          evidence.dayOffset whole local days
                                          after your window start — that offset is
                                          the fact this code reports, and it is
                                          always at least one day. Whether the
                                          plan started later than it HAD to is a
                                          separate question, answered by
                                          evidence.earlierSupplyExisted: TRUE
                                          means the supplier had open days before
                                          that first session and the cadence could
                                          not use them, so an earlier start really
                                          was there to be had and loosening the
                                          cadence is the fix. FALSE means we found
                                          no opening earlier in your window, so
                                          this is simply where the supplier’s
                                          supply began — nothing was given up, and
                                          copy saying otherwise would be wrong.
                                      - type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - PACKAGE_UNDERFILLED
                                          evidence:
                                            type: object
                                            properties:
                                              sessionsRequested:
                                                type: integer
                                                minimum: 0
                                                exclusiveMinimum: true
                                              sessionsFilled:
                                                type: integer
                                                minimum: 0
                                            required:
                                              - sessionsRequested
                                              - sessionsFilled
                                        required:
                                          - code
                                          - evidence
                                        description: >-
                                          Fewer sessions than the package holds
                                          credits for. This slate is PARTIAL —
                                          completeness says so too, and it is not
                                          a matchScore component, so a PARTIAL
                                          slate can still score 1.
                                  description: >-
                                    Why this slate departs from what you asked
                                    for — one entry per reason, each a code plus
                                    structured evidence, and no English so you
                                    can write your own copy. ALWAYS PRESENT:
                                    empty means nothing departed, so you can
                                    read .length without a null check. NOT gated
                                    on matchScore — a DIRECT_FILL slate and a
                                    PARTIAL slate can both score 1 and still
                                    carry notes, and those are exactly the
                                    slates worth captioning. Read
                                    matchComponents for WHICH criterion missed
                                    and these for WHY. IMPORTANT: the two count
                                    weeks differently, so that pairing is a
                                    guide, not a join key. The week-level codes
                                    here bucket Monday-anchored CALENDAR weeks —
                                    the same bucketing as cadenceSummary.byWeek
                                    and the maxSessionsPerWeek cap — while
                                    matchComponents.sessionsPerWeek buckets
                                    consecutive 7-day blocks from your window’s
                                    start. The two can therefore disagree, and
                                    both are right: a note can name a short week
                                    for a criterion that component scores as
                                    met, and the reverse. Join a note to
                                    cadenceSummary.byWeek on weekStart, which
                                    does share this bucketing; treat
                                    matchComponents as the per-criterion score,
                                    not as a per-week one.
                                advice:
                                  type: object
                                  properties:
                                    code:
                                      type: string
                                      enum:
                                        - LATER_START_IMPROVES_CADENCE
                                    earliestSustainedWeek:
                                      type: string
                                      pattern: ^\d{4}-\d{2}-\d{2}$
                                      description: >-
                                        The earliest Monday from which supply
                                        alone could sustain your requested
                                        frequency. Always STRICTLY LATER than
                                        the first week matchNotes reported as
                                        short — this field means "start later",
                                        so it never names a week the notes just
                                        condemned.
                                      example: '2026-09-14'
                                  required:
                                    - code
                                    - earliestSustainedWeek
                                  description: >-
                                    An advisory hint about a later start,
                                    present only when one applies. Read
                                    AdviceSchema’s own description first: it
                                    reports that SUPPLY exists, not that a slate
                                    was built.
                                matchScore:
                                  type: number
                                  minimum: 0
                                  maximum: 1
                                  description: >-
                                    How well this slate matches the requested
                                    schedule preferences, from 0 to 1 — the mean
                                    of the components present in
                                    matchComponents. When the caller expressed
                                    no schedule preferences it is 1 and
                                    matchComponents is empty, so a caller
                                    distinguishes "perfect match" from "nothing
                                    asked" by reading matchComponents, not this
                                    score. Compare the availabilityMatch
                                    property on /availability/suppliers, which
                                    is ABSENT entirely for the "nothing asked"
                                    case rather than present with a null score —
                                    matchScore cannot go absent, because it is a
                                    required property on this shipped contract
                                    and dropping it would break the generated
                                    SDK types. The results are already ranked:
                                    primarySlate is the best-matching COMPLETE
                                    slate and alternates follow it in descending
                                    order, with completeness always outranking
                                    this score, so a COMPLETE slate never sits
                                    below a PARTIAL one that scored higher.
                                    (cadenceAlternatives is ordered separately,
                                    closest-cadence first.) Do NOT re-sort the
                                    slates you receive by matchScore: the order
                                    carries preferences this number cannot.
                                    matchComponents.sessionsPerWeek scores a
                                    week holding AT LEAST the sessionsPerWeek
                                    you asked for, so against a target of 2 a
                                    slate delivering three sessions a week
                                    scores identically to one delivering two,
                                    and only the order distinguishes them.
                                    Re-sorting silently discards that. This
                                    score is also not a cadence: read
                                    cadenceSummary.peak for how often the plan
                                    actually runs, and cadenceSummary.byWeek for
                                    which weeks are short and why the two
                                    numbers can differ.
                                  example: 1
                                matchComponents:
                                  type: object
                                  properties:
                                    startDate:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        How soon this slate’s first session
                                        lands in the requested window — 1 when
                                        session one lands as early as possible
                                        in the window, lower the later it lands.
                                    timeOfDay:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        Fraction of this slate’s sessions that
                                        fall at a preferred time of day.
                                    daysOfWeek:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        Fraction of this slate’s sessions that
                                        fall on a requested weekday.
                                    sessionsPerWeek:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        Fraction of the window’s whole weeks in
                                        which this slate holds at least the
                                        requested number of sessions — a match
                                        ratio in [0, 1], not a count. For counts
                                        see cadenceSummary, whose peak is the
                                        number to render as "4×/week". THE TWO
                                        COUNT WEEKS DIFFERENTLY, deliberately:
                                        this ratio buckets consecutive 7-day
                                        blocks from your window’s start, so it
                                        stays comparable with availabilityMatch
                                        on /availability/suppliers, while
                                        cadenceSummary uses Monday-anchored
                                        calendar weeks so its weekStart dates
                                        are real Mondays and agree with the
                                        maxSessionsPerWeek cap. Expect them to
                                        disagree on a plan spanning a supplier’s
                                        break — cadenceSummary.peak can read 4
                                        against a target of 4 while this ratio
                                        reads below 1, and both are correct for
                                        what they measure. AT LEAST is literal:
                                        against a target of 2, a week holding 3
                                        sessions counts exactly as a week
                                        holding 2, so a denser slate never
                                        scores worse here. The preference for
                                        two over three is expressed only in the
                                        ORDER slates come back in — see
                                        matchScore.
                                    cadence:
                                      type: number
                                      minimum: 0
                                      maximum: 1
                                      description: >-
                                        1 when this slate runs at the cadence
                                        you requested, and also 1 when the only
                                        departure from it was a weekday
                                        substitution you authorised —
                                        cadenceRelaxation of DAYS_SUBSTITUTED or
                                        ALL_WORKING_DAYS, with
                                        allowWeekdaySubstitution true and no
                                        daysOfWeek sent. 0 when the cadence
                                        changed in a way you did not authorise,
                                        which includes every change to how OFTEN
                                        sessions occur (INTERVAL_TIGHTENED,
                                        DAYS_ADDED): allowing weekday
                                        substitution does not authorise a
                                        frequency change, and sending an
                                        explicit daysOfWeek withdraws the
                                        authorisation, because naming your
                                        weekdays says the weekdays are the
                                        point. Absent rather than 0 on a slate
                                        that follows no cadence at all — a
                                        DIRECT_FILL slate and a PARTIAL slate
                                        are both greedy fills that never consult
                                        your rrule, so how well they match a
                                        requested cadence is unanswerable rather
                                        than zero, and matchScore is the mean of
                                        the components that remain. Absent too
                                        when you sent no rrule.
                                  description: >-
                                    How well this slate matches the requested
                                    schedule preferences, broken down by
                                    criterion. Only the criteria the caller
                                    supplied are scored here — matchScore is the
                                    mean of exactly these. Present but empty
                                    when the caller expressed no schedule
                                    preferences at all; see matchScore’s
                                    description for why that case is 1 here
                                    rather than an absent availabilityMatch.
                                    Also absent on a slate whose matchScore
                                    carries no recorded per-criterion breakdown.
                                    These names mirror the components object
                                    inside availabilityMatch on
                                    /availability/suppliers but NOT their
                                    meaning: there each ratio is measured over
                                    the supplier’s open availability, while here
                                    every ratio is measured over this slate’s
                                    own sessions — a slate of eight Friday
                                    sessions scores 1 on daysOfWeek because all
                                    eight sessions are Fridays, independent of
                                    what a supplier-level daysOfWeek would
                                    report.
                              required:
                                - slateId
                                - supplierId
                                - completeness
                                - sessionsRequested
                                - sessionsFilled
                                - startTimeConsistencyPercent
                                - totalTravelTimeMins
                                - slots
                                - matchNotes
                                - matchScore
                            default: []
                            description: >-
                              Complete N-session slates that fit the supplier’s
                              real availability but do NOT follow the rrule you
                              asked for — e.g. you requested weekly Fridays, no
                              supplier has eight free Fridays, so this carries a
                              Mon+Fri plan instead. Sorted by cadenceDistance,
                              closest first, when the request carries no
                              sessionsPerWeek target; when it does, ranked by
                              closeness to that target first and cadenceDistance
                              only as the tiebreaker. Always empty unless the
                              request set cadenceFlexibility or guaranteeSlate.
                              Each entry’s slateId is bookable exactly like
                              primarySlate’s.
                          requestedCadence:
                            type: string
                            nullable: true
                            description: >-
                              The rrule this request asked for, echoed back so
                              you can diff it against each slate’s cadenceRrule.
                            example: FREQ=WEEKLY;BYDAY=FR;COUNT=8
                        required:
                          - status
                          - reason
                          - suggestionRequestId
                          - resolvableUntil
                          - primarySlate
                          - alternates
                          - partial
                    required:
                      - code
                      - message
                      - statusCode
                      - requestId
                      - freshSuggestions
        '422':
          description: >-
            Slate too large, best-effort not enabled, a PHYSICAL location
            without coordinates (UNPROCESSABLE_ENTITY), or the credit’s offering
            is no longer ACTIVE (NOT_SELLABLE): a service retired since does not
            refuse credits already bought
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Address:
      type: object
      nullable: true
      properties:
        addressOneLine:
          type: string
          minLength: 1
          description: The whole address on one line, as a person would write it.
          example: 10 Main St, Toronto, ON M5V 1A1, Canada
        streetNumber:
          type: string
          minLength: 1
          description: The street number.
          example: '10'
        streetName:
          type: string
          minLength: 1
          description: The street name.
          example: Main St
        city:
          type: string
          minLength: 1
          description: The city or town.
          example: Toronto
        state:
          type: string
          minLength: 1
          description: The state, province or region; an ISO 3166-2 code when one matches.
          example: 'ON'
        country:
          type: string
          minLength: 1
          description: The country; ISO 3166-1 alpha-2, alpha-3 or the English name.
          example: CA
        zipCode:
          type: string
          minLength: 1
          description: The postal or ZIP code, in any national format.
          example: M5V 1A1
        unitNumber:
          type: string
          nullable: true
          description: The unit, suite or apartment, if any.
          example: 4B
      required:
        - addressOneLine
        - streetNumber
        - streetName
        - city
        - state
        - country
        - zipCode
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.