> ## 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.

# Reschedule a suggested slot to a new time (server-validated), refreshing its slate

> Moves ONE slot of a proposed slate to a time the client picked, before anything is booked. This is the "actually, can we do Thursday instead" step of a multi-session proposal — it does not touch bookings, which have their own reschedule route. The new time is validated against the supplier's real availability rather than trusted, and on success the parent slate's aggregates are recomputed and the whole updated slate is returned, so re-render from this response instead of patching the one slot locally.

Nearly everything that goes wrong is a 409, and the four causes need different handling — branch on the `code`, never on the status alone. The time may be held or booked on the supplier's calendar, in which case the body names the blocking reservation or booking. The supplier may simply not work then, though the time is valid and in the future. You may have lost a race to a concurrent hold, which returns SLOT_NO_LONGER_FREE and is worth one retry at a different time. Or the suggestion itself may have expired — and that response carries a freshly computed set of suggestions with it, so re-render those rather than starting a new availability search. A past or malformed `bookingStartUtc` is a 400.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule
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}/suggestions/slots/{slotId}/reschedule:
    post:
      tags:
        - Suggestions
      summary: >-
        Reschedule a suggested slot to a new time (server-validated), refreshing
        its slate
      description: >-
        Moves ONE slot of a proposed slate to a time the client picked, before
        anything is booked. This is the "actually, can we do Thursday instead"
        step of a multi-session proposal — it does not touch bookings, which
        have their own reschedule route. The new time is validated against the
        supplier's real availability rather than trusted, and on success the
        parent slate's aggregates are recomputed and the whole updated slate is
        returned, so re-render from this response instead of patching the one
        slot locally.


        Nearly everything that goes wrong is a 409, and the four causes need
        different handling — branch on the `code`, never on the status alone.
        The time may be held or booked on the supplier's calendar, in which case
        the body names the blocking reservation or booking. The supplier may
        simply not work then, though the time is valid and in the future. You
        may have lost a race to a concurrent hold, which returns
        SLOT_NO_LONGER_FREE and is worth one retry at a different time. Or the
        suggestion itself may have expired — and that response carries a freshly
        computed set of suggestions with it, so re-render those rather than
        starting a new availability search. A past or malformed
        `bookingStartUtc` is a 400.
      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
          required: true
          name: slotId
          in: path
      requestBody:
        description: New bookingStartUtc
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                bookingStartUtc:
                  type: string
                  format: date-time
                  description: >-
                    The slot's new start, as a UTC instant. The end keeps the
                    slot's duration; its zone and location are unchanged.
                  example: '2030-07-06T20:00:00.000Z'
              required:
                - bookingStartUtc
      responses:
        '200':
          description: Slot moved; updated slate returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  slotId:
                    type: string
                  slate:
                    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
                required:
                  - slotId
                  - slate
        '400':
          description: Validation error (bad/past time)
          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'
        '409':
          description: >-
            Requested time unavailable, held/booked on the supplier calendar, or
            the suggestion is stale
          content:
            application/json:
              schema:
                anyOf:
                  - 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
                  - 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
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.