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

# Build a single-supplier N-session package slate (policy-driven), persisting suggestions

> Builds one or more "slates" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable.

The rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.

The response carries a `searchId` (also the `X-MB-Search-Id` header, and the persisted suggestion request's correlation id) and each slate its 0-based `position` across the whole response. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/availability/package-slate
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}/availability/package-slate:
    post:
      tags:
        - Availability
      summary: >-
        Build a single-supplier N-session package slate (policy-driven),
        persisting suggestions
      description: >-
        Builds one or more "slates" — complete N-session plans for a package —
        from a single supplier's availability. Name what to plan in ONE of two
        ways: packageId (session count is derived from its creditCount), or a
        client's credit — orderId together with orderItemId (a package line of
        that order). A credit plans its remaining sessions in its own
        service/offering, ends the window at the credit's expiresAt, and works
        even when the package has since been deleted. Naming neither source, or
        both, is a 400. With a credit, an optional clientId names the client it
        must belong to: another client's order is refused exactly like a missing
        one (400 INVALID_ORDER_REFERENCE). When the window is derived from the
        cadence (no lookAheadDays or endDate) and no relaxation is asked for, a
        credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose
        reason names the expiry. When you size the window yourself
        (lookAheadDays or endDate), or opt in to relaxation, the window is cut
        at the expiry instead, and an expiry too early for the sessions gives
        the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule
        COUNT is replaced by the session count (the package's creditCount, or
        the credit's remaining sessions). Give a location (locationId, or
        lat+lng+address for travel zones), a timezone, a lookAheadStartDate with
        a numeric offset, and an rrule with a bounded COUNT. When persist is
        true (default) the returned primarySlate.slateId can be booked directly
        via POST /orders/{orderId}/package-bookings with { slateId }. Returns
        422 when nothing is bookable.


        The rrule is your PREFERRED cadence, not a hard filter — set
        cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When
        the supplier has no complete plan on the days you asked for, the
        response then carries cadenceAlternatives: complete slates at a denser,
        supplier-feasible cadence (you asked for weekly Fridays, we offer
        Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read
        the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE
        is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS —
        it means primarySlate is null but cadenceAlternatives is not empty, and
        every entry there is bookable in exactly the same way as primarySlate
        (same shape, same slateId, same POST /orders/{orderId}/package-bookings
        call). A caller who does not set cadenceFlexibility sees no change at
        all: it defaults to NONE, cadenceAlternatives comes back empty, and an
        unbookable request is still a 422.


        The response carries a `searchId` (also the `X-MB-Search-Id` header, and
        the persisted suggestion request's correlation id) and each slate its
        0-based `position` across the whole response. Keep `searchId` for the
        session if you want attribution. Two optional request headers tag the
        search for insights and are never acted on: `X-MB-Session-Key` (an
        opaque key you choose, up to 64 characters) and `X-MB-Client-Kind`
        (`browser`, `server`, `monitor` or `loadtest`).
      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
      requestBody:
        description: Service + location + cadence + policy knobs
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                packageId:
                  type: string
                  minLength: 1
                  description: >-
                    The package to plan sessions for. serviceId, offeringId and
                    the session count (creditCount) are resolved from it
                    server-side.
                  example: pkg_01kv7n10k0fnptwk81wkm59vj7
                locationId:
                  type: string
                  minLength: 1
                  description: Discovery by a stored location id. Provide this OR lat+lng.
                  example: loc_01kv60qgs4e4nbjhzradnqtj0h
                lat:
                  anyOf:
                    - type: string
                    - type: number
                  description: >-
                    Client latitude (travel-zone branch). Provide with lng
                    instead of locationId.
                  example: 43.6532
                lng:
                  anyOf:
                    - type: string
                    - type: number
                  description: Client longitude (travel-zone branch).
                  example: -79.3832
                address:
                  type: object
                  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
                  description: >-
                    Structured client address. Required on the lat/lng
                    (travel-zone) branch — it is stamped onto every returned
                    slot so a later book-by-id satisfies the TRAVEL_ZONE address
                    rule.
                supplierId:
                  type: string
                  minLength: 1
                  description: >-
                    Pin the plan to one supplier; only that supplier is
                    considered.
                  example: sup_01kv60qgnef2kt3pvqgwmkbzfr
                timezone:
                  type: string
                  minLength: 1
                  description: IANA timezone for the plan.
                  example: America/Toronto
                lookAheadStartDate:
                  type: string
                  description: >-
                    When the recurring window starts. MUST carry a numeric UTC
                    offset (e.g. -04:00), NOT a Z suffix.
                  example: '2026-07-09T00:00:00-04:00'
                rrule:
                  type: string
                  description: >-
                    Your PREFERRED cadence for the sessions. MUST include a
                    bounded, positive COUNT. When cadenceFlexibility is FALLBACK
                    or ALWAYS and no supplier can meet this exactly, denser
                    supplier-feasible cadences come back in cadenceAlternatives
                    instead of a 422.
                  example: FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8
                lookAheadDays:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                endDate:
                  type: string
                preferredTimes:
                  type: array
                  items:
                    type: object
                    properties:
                      startTime:
                        type: string
                      endTime:
                        type: string
                    required:
                      - startTime
                      - endTime
                daysOfWeek:
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 6
                  minItems: 1
                  maxItems: 7
                  description: >-
                    Weekdays sessions may fall on (0 = Sunday … 6 = Saturday).
                    At least one weekday is required when this field is present
                    — omit the field entirely for "any day"; an empty array is
                    rejected. This is a HARD filter, not a preference: a weekday
                    you leave out is removed from the supplier availability the
                    planner sees, so no session can land on it and cadence
                    relaxation cannot reintroduce it.
                  example:
                    - 1
                    - 2
                excludeDates:
                  type: array
                  items:
                    type: string
                    pattern: ^\d{4}-\d{2}-\d{2}$
                  maxItems: 90
                  description: >-
                    Local calendar dates (YYYY-MM-DD) that must not carry a
                    session — a holiday, a trip. Matched against each slot's own
                    local calendar date as the planner buckets it, not against a
                    UTC instant. Pass each date individually; there is no range
                    form.
                  example:
                    - '2026-08-20'
                    - '2026-08-21'
                    - '2026-08-22'
                sessionsPerWeek:
                  type: integer
                  minimum: 1
                  maximum: 14
                  description: >-
                    How many sessions a week you want, independent of which
                    weekdays. A TARGET, not a cap: distinct from
                    maxSessionsPerWeek, which bounds sessions per
                    Monday-anchored week and applies only to direct-fill slates.
                    The target is always SCORED —
                    matchComponents.sessionsPerWeek reports it on every slate —
                    but it only STEERS which slates get built when cadence
                    relaxation actually runs: cadenceFlexibility ALWAYS,
                    cadenceFlexibility FALLBACK once the requested cadence
                    yields nothing, or guaranteeSlate true, which promotes NONE
                    to FALLBACK. On the default cadenceFlexibility of NONE your
                    rrule fixes the schedule completely, so the target is scored
                    and reported but changes nothing about which slates come
                    back — send it together with cadenceFlexibility FALLBACK or
                    ALWAYS to have it steer. Where it steers, it steers the
                    ORDER too, and that order carries the half of your
                    preference matchScore cannot:
                    matchComponents.sessionsPerWeek asks for AT LEAST the
                    target, so against a target of 2 a three-a-week slate scores
                    exactly as well as a two-a-week one. Take the results in the
                    order they arrive; re-sorting them by matchScore throws that
                    preference away.
                  example: 3
                cadenceFlexibility:
                  type: string
                  enum:
                    - NONE
                    - FALLBACK
                    - ALWAYS
                  default: NONE
                  description: >-
                    How hard to try when the supplier cannot meet your rrule
                    exactly. NONE (default) is today’s behaviour: no cadence at
                    the requested rrule means no slate. FALLBACK also returns
                    cadenceAlternatives — complete slates at a DENSER,
                    supplier-feasible cadence (you asked for weekly Fridays, we
                    offer Mon+Fri) — but only when the requested cadence yields
                    nothing. ALWAYS returns them alongside a successful
                    primarySlate too, so you can show "…or twice a week".
                  example: FALLBACK
                guaranteeSlate:
                  type: boolean
                  default: false
                  description: >-
                    Try harder before giving up. When every relaxed cadence also
                    fails, fall back to a direct fill: all N sessions picked
                    straight from the supplier’s openings with no recurrence
                    rule, one per day, at the most consistent start time
                    available. This guarantees flexibility of CADENCE, not of
                    capacity — a supplier without N open days still yields no
                    complete plan, and an under-filled plan is surfaced (or not)
                    by the project’s allowPartialPackages setting via `partial`,
                    exactly as it is today. Implies cadenceFlexibility FALLBACK.
                  example: true
                maxCadenceAlternatives:
                  type: integer
                  minimum: 0
                  maximum: 10
                  default: 3
                  description: >-
                    Max entries in cadenceAlternatives. Ignored when
                    cadenceFlexibility is NONE.
                  example: 3
                allowWeekdaySubstitution:
                  type: boolean
                  default: true
                  description: >-
                    Whether a relaxed cadence may DROP a requested weekday. Set
                    false to keep every weekday you asked for and only ever add
                    to them — use it when the requested day is non-negotiable
                    (e.g. the client is only home on Fridays).
                  example: true
                minGapDays:
                  type: integer
                  minimum: 0
                  maximum: 90
                  description: >-
                    Minimum whole days between consecutive sessions in a
                    direct-fill slate. Use it to stop a dense fallback from
                    stacking sessions on back-to-back days. It reaches only the
                    direct fill, not any relaxed cadence-ladder rung, so a rung
                    can still land sessions closer together than this.
                  example: 2
                maxSessionsPerWeek:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 14
                  description: >-
                    Cap on sessions per Monday-anchored calendar week in a
                    direct-fill slate — it reaches only the direct fill, not any
                    relaxed cadence-ladder rung, so a rung built at a denser
                    cadence can still land more sessions in a week than this.
                    See sessionsPerWeek for the corresponding TARGET.
                  example: 3
                maxAlternates:
                  type: integer
                  minimum: 0
                  default: 3
                  description: >-
                    Maximum entries in alternates — same-supplier schedules or
                    other suppliers, per your supplierPolicy. 0 returns none.
                  example: 3
                persist:
                  type: boolean
                  default: true
                  description: >-
                    Persist the slate so it can be booked later by slateId.
                    Defaults true.
                  example: true
                orderId:
                  type: string
                  minLength: 1
                  description: >-
                    The order holding the credit. With orderItemId, instead of
                    packageId: plans the credit's remaining sessions in its own
                    service/offering, ending at its expiresAt.
                  example: ord_01kv7n10k0fnptwk81wkm59vj7
                orderItemId:
                  type: string
                  minLength: 1
                  description: >-
                    The PACKAGE order item (credit) to plan for. Requires
                    orderId.
                  example: oi_01kv7n10k0fnptwk81wkm59vj7
                clientId:
                  type: string
                  minLength: 1
                  description: >-
                    Optional, with orderId + orderItemId only: the client the
                    credit must belong to. When the order is another client's,
                    the slate is refused exactly as for an order that does not
                    exist (400 INVALID_ORDER_REFERENCE).
                  example: cli_01kv7n10k0fnptwk81wkm59vj7
      responses:
        '200':
          description: >-
            Primary slate (OK), a usable partial slate, or — when
            cadenceFlexibility was set — bookable cadenceAlternatives
            (ALTERNATIVE_CADENCE)
          content:
            application/json:
              schema:
                type: object
                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
        '400':
          description: >-
            Validation error (code: BAD_REQUEST), or a credit that cannot be
            planned (code: INVALID_ORDER_REFERENCE | NOT_A_PACKAGE_ITEM)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: 'The package, order or order item was not found (code: NOT_FOUND)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: >-
            The credit has no sessions left to plan, has expired, or is on a
            cancelled order (code: ORDER_ITEM_QUANTITY_UNAVAILABLE |
            PACKAGE_EXPIRED | ORDER_CANCELLED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: >-
            No complete or bookable slate — no primarySlate, no partial, and no
            cadenceAlternatives (code: NO_COMPLETE_SLATE | NO_AVAILABILITY)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Address:
      type: object
      nullable: true
      properties:
        addressOneLine:
          type: string
          minLength: 1
          description: The whole address on one line, as a person would write it.
          example: 10 Main St, Toronto, ON M5V 1A1, Canada
        streetNumber:
          type: string
          minLength: 1
          description: The street number.
          example: '10'
        streetName:
          type: string
          minLength: 1
          description: The street name.
          example: Main St
        city:
          type: string
          minLength: 1
          description: The city or town.
          example: Toronto
        state:
          type: string
          minLength: 1
          description: The state, province or region; an ISO 3166-2 code when one matches.
          example: 'ON'
        country:
          type: string
          minLength: 1
          description: The country; ISO 3166-1 alpha-2, alpha-3 or the English name.
          example: CA
        zipCode:
          type: string
          minLength: 1
          description: The postal or ZIP code, in any national format.
          example: M5V 1A1
        unitNumber:
          type: string
          nullable: true
          description: The unit, suite or apartment, if any.
          example: 4B
      required:
        - addressOneLine
        - streetNumber
        - streetName
        - city
        - state
        - country
        - zipCode
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

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