How a trip becomes a flight

The booking model.

An intent moves through a guarded state machine. Three actors touch it in order — the human taps, the state advances, the operator confirms — and three invariants hold at every step.

The state machine

The mainline runs left to right. Each transition is guarded server-side.

Branches

Off the mainline, an intent can settle into a terminal branch state.

• matching → no_match no compatible demand or operator
• quoted → expired quote lapsed before commit
• confirming → declined operator rejects the request
• any → cancelled owner or operator cancels

The three invariants

1 — Human-tap commit

A trip never advances to confirming without an explicit human tap. The quoted → confirming transition is rejected server-side without a recorded commit token, and the skill asks the human anyway — defense in depth, not redundancy. A tap is an unambiguous "yes, book it," not an inference or a default.

2 — Operator confirm is the only path to booked

Nothing reaches booked except POST /v1/operator/confirm, called with an operator key. No agent and no other endpoint can flip confirming → booked. The chain is: human taps, state becomes confirming, operator confirms, state becomes booked.

3 — BasiFly never touches charter funds

Two money flows, never merged. Charter funds move traveler to operator directly, over the operator's own rails. BasiFly's money is its x402 micropayments and a disclosed coordination fee, billed separately. In a quote, fee_breakdown and basifly_fee are structurally separate objects — present them as two amounts, never summed.

{
  "fee_breakdown": {
    "occupied_leg_usd": 9800,
    "reposition_usd": 0,
    "federal_excise_tax_usd": 755,
    "segment_fees_usd": 13.5,
    "operator_subtotal_usd": 10568.5
  },
  "basifly_fee": {
    "amount_usd": 528,
    "basis": "coordination fee, disclosed traveler-side",
    "note": "coordination fee only; never part of the charter price"
  }
}

Two confidence fields, two entities

The word confidence appears on two different entities. Do not conflate them.

A firm price is still not a booking. Even operator_firm needs the human tap and the operator confirm before a leg is booked.

The same constraints, in the skill's own words, are in references/booking-etiquette.md. Endpoint shapes are on the API reference.