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

# List a service's packages, each with a ready-to-book slate

> Returns every ACTIVE package of a service, each with a complete N-session plan built from a supplier's real availability. The response entry carries a slateId that can be booked directly via POST /orders/{orderId}/package-bookings. Cadence defaults to FREQ=WEEKLY;COUNT={creditCount}, derived per package. Packages that cannot be planned come back with status NO_COMPLETE_SLATE or NO_AVAILABILITY and a reason — they do not fail the request.

The rrule is the PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) and it applies to every package in the response. An entry that has no complete plan on the requested days then comes back with status ALTERNATIVE_CADENCE and a non-empty cadenceAlternatives: complete slates at a denser, supplier-feasible cadence, sorted closest-first by cadenceDistance. Read the outcome from each entry's status: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome, and ALTERNATIVE_CADENCE is a success — every cadenceAlternatives entry carries a slateId that is bookable in exactly the same way as primarySlate. A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE and cadenceAlternatives comes back empty.

The response carries a `searchId` (also the `X-MB-Search-Id` header, and the correlation id of every suggestion request this call persisted) and each slate its 0-based `position` within its package. 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-options
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-options:
    post:
      tags:
        - Availability
      summary: List a service's packages, each with a ready-to-book slate
      description: >-
        Returns every ACTIVE package of a service, each with a complete
        N-session plan built from a supplier's real availability. The response
        entry carries a slateId that can be booked directly via POST
        /orders/{orderId}/package-bookings. Cadence defaults to
        FREQ=WEEKLY;COUNT={creditCount}, derived per package. Packages that
        cannot be planned come back with status NO_COMPLETE_SLATE or
        NO_AVAILABILITY and a reason — they do not fail the request.


        The rrule is the PREFERRED cadence, not a hard filter — set
        cadenceFlexibility to FALLBACK (or ALWAYS) and it applies to every
        package in the response. An entry that has no complete plan on the
        requested days then comes back with status ALTERNATIVE_CADENCE and a
        non-empty cadenceAlternatives: complete slates at a denser,
        supplier-feasible cadence, sorted closest-first by cadenceDistance. Read
        the outcome from each entry's status: NO_COMPLETE_SLATE is NO LONGER the
        only non-OK outcome, and ALTERNATIVE_CADENCE is a success — every
        cadenceAlternatives entry carries a slateId that is bookable in exactly
        the same way as primarySlate. A caller who does not set
        cadenceFlexibility sees no change at all: it defaults to NONE and
        cadenceAlternatives comes back empty.


        The response carries a `searchId` (also the `X-MB-Search-Id` header, and
        the correlation id of every suggestion request this call persisted) and
        each slate its 0-based `position` within its package. 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 + optional supplier and cadence
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                serviceId:
                  type: string
                  minLength: 1
                  description: >-
                    The service whose ACTIVE packages should be priced and
                    planned.
                  example: srv_01kq8cp17bf03t125zhakpcgyx
                locationId:
                  type: string
                  minLength: 1
                  description: >-
                    Discovery by a stored location id. Provide this OR
                    lat+lng+address.
                lat:
                  anyOf:
                    - type: string
                    - type: number
                  description: Client latitude (travel-zone branch).
                  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.
                supplierId:
                  type: string
                  minLength: 1
                  description: >-
                    Pin every slate to one supplier. Omit to consider all
                    suppliers serving the location.
                timezone:
                  type: string
                  minLength: 1
                  description: IANA timezone. Defaults to the project's defaultTimezone.
                rrule:
                  type: string
                  description: >-
                    Cadence for every package. Omit to default to
                    FREQ=WEEKLY;COUNT={creditCount}, derived per package from
                    its own credit count.
                  example: FREQ=WEEKLY;BYDAY=MO
                lookAheadStartDate:
                  type: string
                  description: >-
                    ISO start of the search window. Defaults to now. When
                    provided, MUST carry a numeric UTC offset (e.g. -04:00), NOT
                    a Z suffix.
                  example: '2026-07-09T00:00:00-04:00'
                preferredTimes:
                  type: array
                  nullable: true
                  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
                  description: >-
                    Maximum entries in alternates — same-supplier schedules or
                    other suppliers, per your supplierPolicy. 0 returns none.
                  example: 3
                persist:
                  type: boolean
                  description: >-
                    Persist slates so primarySlate.slateId is bookable. Defaults
                    to true.
              required:
                - serviceId
              description: A service + a location (+ optionally a supplier and cadence).
      responses:
        '200':
          description: One entry per ACTIVE package
          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
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        package:
                          $ref: '#/components/schemas/ServicePackage'
                        status:
                          type: string
                          enum:
                            - OK
                            - ALTERNATIVE_CADENCE
                            - NO_COMPLETE_SLATE
                            - NO_AVAILABILITY
                          description: >-
                            OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or
                            NO_AVAILABILITY — for THIS package.
                            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
                          description: >-
                            Why this package is not bookable. Null when status
                            is OK.
                        slateId:
                          type: string
                          nullable: true
                          description: >-
                            Book this package by passing this to POST
                            .../package-bookings. Null unless OK.
                        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
                        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 slates for THIS package at a cadence other
                            than the one requested. See
                            PackageSlateResponse.cadenceAlternatives.
                      required:
                        - package
                        - status
                        - reason
                        - slateId
                        - primarySlate
                        - alternates
                        - partial
                required:
                  - searchId
                  - data
        '400':
          description: Validation error
          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: Service not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    ServicePackage:
      type: object
      properties:
        entityType:
          type: string
          enum:
            - SERVICE_PACKAGE
        projectId:
          type: string
        serviceId:
          type: string
        offeringId:
          type: string
        packageId:
          type: string
        name:
          type: object
          additionalProperties:
            type: string
        description:
          type: object
          additionalProperties:
            type: string
        pricingModel:
          type: string
          enum:
            - PER_SESSION
            - FLAT
        pricing:
          type: array
          items:
            type: object
            properties:
              ruleId:
                type: string
                minLength: 1
              scope:
                type: string
                enum:
                  - DEFAULT
                  - COUNTRY
                  - STATE
                  - POSTAL
                description: >-
                  How specifically a price rule targets a region. Resolution
                  picks the most specific match: POSTAL beats STATE beats
                  COUNTRY beats DEFAULT. DEFAULT is the fallback every offering
                  must define ("any region"). On an order item, `priceScope`
                  reports which one actually applied — seeing DEFAULT where you
                  expected a regional price means the region did not resolve.
              country:
                type: string
                minLength: 1
              state:
                type: string
                minLength: 1
              postalCodes:
                type: array
                items:
                  type: string
                  minLength: 1
              price:
                $ref: '#/components/schemas/Money'
              tax:
                type: object
                properties:
                  taxable:
                    type: boolean
                  taxPercentage:
                    type: number
                    minimum: 0
                required:
                  - taxable
            required:
              - ruleId
              - scope
              - price
          minItems: 1
        creditCount:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        discountPercent:
          type: number
          minimum: 0
          maximum: 100
          description: >-
            Percentage discount (0-100) recorded when this package's prices were
            seeded from the offering's prices (price = offering price *
            creditCount * (1 - discountPercent/100)). Informational metadata
            only: `pricing` is the authoritative source of the amounts charged.
            Individual prices can be manually overridden after seeding, and the
            offering's prices may change later, so this value is not guaranteed
            to match the actual prices - never derive amounts from it.
        validityDays:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
        status:
          type: string
          enum:
            - DRAFT
            - ACTIVE
            - ARCHIVED
          description: >-
            Lifecycle of the package bundle. ARCHIVED hides it from the
            storefront and blocks new orders, but order items already placed
            against it stay bookable.
        capacity:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        deleted:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedBy:
          type: string
      required:
        - entityType
        - projectId
        - serviceId
        - offeringId
        - packageId
        - pricingModel
        - pricing
        - creditCount
        - validityDays
        - status
        - capacity
        - deleted
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
    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
    Money:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
        currency:
          type: string
          minLength: 1
          maxLength: 3
      required:
        - amount
        - currency
  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.