[maoryeh]

The conflict

Two things the spec currently says about Booking.confirmation_mode cannot both hold:

1. it is unconditionally required on every Booking
2. it "reflects the service's confirmation policy at booking time"

A business MAY change a service's confirmation policy whenever it likes, and most do not store the policy alongside the booking. Once the booking is confirmed, such a business has no truthful value left to send. The two it can compute are both wrong:

available value	why it's wrong
the service's current policy	not what the field means — and it silently rewrites the history of every past booking each time the merchant flips the setting
a fixed auto	misreports every booking the merchant actually approved

Found while implementing this field: a provider derives it from the booking's own state (pending → manual), which yields auto for every confirmed booking, or re-reads the service, which yields the current policy rather than the historical one. Neither is the specified value, and no amount of implementation effort fixes it — the information simply isn't retained.

The change

confirmation_mode becomes REQUIRED only while status is pending or requires_action, enforced in the schema rather than prose alone:

"allOf": [
  {
    "if": {
      "properties": { "status": { "enum": ["pending", "requires_action"] } },
      "required": ["status"]
    },
    "then": { "required": ["confirmation_mode"] }
  }
]

Those are exactly the states where a business necessarily knows the answer — the booking is sitting in the flow that policy selected — and the states where the answer is actionable, because the buyer needs to know whether approval is outstanding. Once confirmed, the mode is history rather than something the buyer can act on.

Relaxing alone would not be enough

Making the field merely optional would trade one wrong answer for another, so two rules come with it:

• a business that cannot answer truthfully MUST omit the field rather than report the current policy
• platforms MUST treat absence as unknown, and MUST NOT infer auto from it

And for businesses that do retain the original policy, the field SHOULD still be published on confirmed and completed bookings, where it remains useful for audit and buyer-facing history. The change removes an impossible obligation; it doesn't discard information anyone has.

New §5.2.1 "Confirmation Mode and Booking History" carries the reasoning, and §5.3.4 (Confirm Booking) gains a note that the field is MUST-present on exactly the states that endpoint acts on — so narrowing the requirement doesn't leave its precondition unreadable.

Verification

All eight conditional cases behave as specified:

pending         WITHOUT confirmation_mode  -> REJECT   ('confirmation_mode' is a required property)
requires_action WITHOUT confirmation_mode  -> REJECT
pending         WITH    confirmation_mode  -> ACCEPT
confirmed / completed / canceled WITHOUT   -> ACCEPT
confirmed       WITH    confirmation_mode  -> ACCEPT
confirmed       WITH    bogus value        -> REJECT   (not one of ['auto','manual'])

No example in specification.md, site-docs/ or the playground fixtures newly fails (checked every JSON block with a status), and tools/usp_check.py schemas, refs, vectors all pass with cryptography installed.

Note

Overlaps with #22 only in CHANGE_LOG.md — whichever merges second will need a one-line rebase there.