@danceiny/gotry 0.0.1-rc.16 → 0.0.1-rc.18

package/ts/src/booking-surface/canonical-schema.js

@@ -0,0 +1,113 @@
+/**
+ * Runtime projection of the canonical booking.surface.v1 JSON Schema.
+ *
+ * dsh tools need self-contained JSON Schemas, while the canonical document is
+ * organized with local $refs. This helper derives each action branch directly
+ * from those canonical bytes and recursively inlines local references. No
+ * model-facing action schema is maintained by hand.
+ */
+
+import { readFileSync } from 'node:fs'
+
+const schemaUrl = new URL('../../../schemas/booking.surface.v1.schema.json', import.meta.url)
+export const canonicalBookingSurfaceSchemaV1 = JSON.parse(readFileSync(schemaUrl, 'utf8'))
+const schemaV2Url = new URL('../../../schemas/booking.surface.v2.schema.json', import.meta.url)
+export const canonicalBookingSurfaceSchemaV2 = JSON.parse(readFileSync(schemaV2Url, 'utf8'))
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function definitionFromRef(ref, schema) {
+  const prefix = '#/$defs/'
+  if (typeof ref !== 'string') {
+    throw new Error(`booking_schema_external_ref_forbidden:${String(ref)}`)
+  }
+  const externalV1 = 'https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/'
+  const definitionSchema = ref.startsWith(prefix) ? schema : ref.startsWith(externalV1) ? canonicalBookingSurfaceSchemaV1 : undefined
+  if (!definitionSchema) throw new Error(`booking_schema_external_ref_forbidden:${String(ref)}`)
+  const name = ref.startsWith(prefix) ? ref.slice(prefix.length) : ref.slice(externalV1.length)
+  const definition = definitionSchema.$defs?.[name]
+  if (!definition) throw new Error(`booking_schema_missing_definition:${name}`)
+  return definition
+}
+
+function inlineLocalRefs(value, schema, stack = []) {
+  if (Array.isArray(value)) return value.map((item) => inlineLocalRefs(item, schema, stack))
+  if (typeof value !== 'object' || value === null) return value
+  if (typeof value.$ref === 'string') {
+    if (stack.includes(value.$ref)) throw new Error(`booking_schema_recursive_ref:${value.$ref}`)
+    const { $ref, ...siblings } = value
+    const definitionSchema = typeof $ref === 'string' && $ref.startsWith('https://gotry.dev/schemas/booking.surface.v1.schema.json#/$defs/') ? canonicalBookingSurfaceSchemaV1 : schema
+    return {
+      ...inlineLocalRefs(definitionFromRef($ref, schema), definitionSchema, [...stack, $ref]),
+      ...inlineLocalRefs(siblings, schema, stack),
+    }
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, inlineLocalRefs(item, schema, stack)]))
+}
+
+function canonicalActionSchemaForKind(kind, schema, definitionName) {
+  const action = schema.$defs?.[definitionName]
+  if (!action) throw new Error('booking_schema_action_union_missing')
+  if (Array.isArray(action.allOf)) {
+    const branch = action.allOf.find((candidate) => candidate?.if?.properties?.kind?.const === kind)
+    const input = branch?.then?.properties?.input
+    if (!input) throw new Error(`booking_schema_action_kind_missing:${kind}`)
+    return clone(inlineLocalRefs({
+      type: action.type,
+      required: action.required,
+      properties: { ...action.properties, kind: { type: 'string', const: kind }, input },
+      additionalProperties: action.additionalProperties,
+    }, schema))
+  }
+  if (!Array.isArray(action.oneOf)) throw new Error('booking_schema_action_union_missing')
+  const branch = action.oneOf.find((candidate) => candidate?.allOf?.some((part) => part?.properties?.kind?.const === kind))
+  const base = schema.$defs?.ActionBase
+  const input = branch?.allOf?.find((part) => part?.properties?.input)?.properties?.input
+  if (!base || !input) throw new Error(`booking_schema_action_kind_missing:${kind}`)
+  return clone(inlineLocalRefs({
+    ...base,
+    properties: { ...base.properties, kind: { type: 'string', const: kind }, input },
+  }, schema))
+}
+
+export function canonicalBookingActionSchemaForKind(kind) {
+  return canonicalActionSchemaForKind(kind, canonicalBookingSurfaceSchemaV1, 'BookingReadActionV1')
+}
+
+export function canonicalBookingActionSchemaForKindV2(kind) {
+  return canonicalActionSchemaForKind(kind, canonicalBookingSurfaceSchemaV2, 'Action')
+}
+
+const DSH_JSON_SCHEMA_KEYS = new Set([
+  'type', 'oneOf', 'properties', 'required', 'additionalProperties', 'items',
+  'enum', 'const', 'description', 'title', 'default', 'examples',
+])
+
+function projectDshSchema(value) {
+  if (Array.isArray(value)) return value.map(projectDshSchema)
+  if (typeof value !== 'object' || value === null) return value
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => DSH_JSON_SCHEMA_KEYS.has(key))
+    .map(([key, item]) => {
+      if (key === 'properties') {
+        return [key, Object.fromEntries(Object.entries(item).map(([name, property]) => [name, projectDshSchema(property)]))]
+      }
+      return [key, projectDshSchema(item)]
+    }))
+}
+
+/**
+ * dsh-tools intentionally supports a smaller enforced JSON-Schema vocabulary.
+ * Keep the canonical shape/type/enum/closure guarantees at the model seam;
+ * the full canonical AJV validator remains the runtime authority for numeric,
+ * pattern, size and uniqueness constraints before an operation can be issued.
+ */
+export function dshBookingActionSchemaForKind(kind) {
+  return projectDshSchema(canonicalBookingActionSchemaForKind(kind))
+}
+
+export function dshBookingActionSchemaForKindV2(kind) {
+  return projectDshSchema(canonicalBookingActionSchemaForKindV2(kind))
+}

package/ts/src/booking-surface/contracts-v2.ts

@@ -0,0 +1,118 @@
+import type { BookingReadActionKindV1, BookingWorkspaceSnapshotV1, SearchCriteriaPatchV1, ResultsViewPatchV1, OfferCriteriaV1, EvidenceLevelV1 } from './contracts.ts'
+
+export const BOOKING_SURFACE_SCHEMA_VERSION_V2 = 'booking.surface.v2' as const
+/**
+ * Process composition modes are deliberately separate from the payload
+ * schema. The default accepts turns already bound by HotelByte's BFF; the
+ * second mode is reserved for an in-process BFF binding seam.
+ */
+export const BOOKING_COPILOT_V2_INGRESS_MODES = ['bff-bound-turn-only', 'bff-ingress-binding'] as const
+export type BookingCopilotV2IngressMode = typeof BOOKING_COPILOT_V2_INGRESS_MODES[number]
+export const BOOKING_COPILOT_V2_ACCEPTED_TURN_KINDS = ['user.turn', 'action.receipt.continuation'] as const
+export const BOOKING_COPILOT_V2_INGRESS_TURN_KIND = 'user.turn.ingress' as const
+/** Hard task-level operation budget. The counter is persisted in the v2 ledger. */
+export const BOOKING_COPILOT_MAX_OPERATIONS_V2 = 20 as const
+export const BOOKING_SURFACE_SCHEMA_V2_SHA256 = '45df62db1b19d30a4fd22ddc94eb550e8ff32d8a225558b5ff13ba303588fc03' as const
+export const BOOKING_READ_ACTION_KINDS_V2 = ['search.patch','search.run','results.view.patch','hotel.focus','hotel.select','offers.query','offers.view.patch','offers.compare','offer.select','offer.check','checkout.prepare','order.observe'] as const satisfies readonly BookingReadActionKindV1[]
+export type BookingReadActionKindV2 = typeof BOOKING_READ_ACTION_KINDS_V2[number]
+export type BookingSurfaceV2 = 'tenant' | 'customer_portal' | 'storefront' | 'payment_link'
+/** Product-owned least-privilege action matrix. BFF bindings may narrow these lists, never expand them. */
+export const BOOKING_SURFACE_ALLOWED_ACTIONS_V2: Record<BookingSurfaceV2, readonly BookingReadActionKindV2[]> = {
+  tenant: BOOKING_READ_ACTION_KINDS_V2,
+  customer_portal: BOOKING_READ_ACTION_KINDS_V2,
+  storefront: ['search.patch', 'search.run', 'results.view.patch', 'hotel.focus'],
+  payment_link: ['search.patch', 'search.run', 'results.view.patch', 'hotel.focus', 'hotel.select'],
+}
+/** Stable product-matrix observation for UAT and server readiness proofs. */
+export function bookingSurfaceAllowedActionsV2(surface: BookingSurfaceV2): BookingReadActionKindV2[] {
+  return [...BOOKING_SURFACE_ALLOWED_ACTIONS_V2[surface]]
+}
+export type BookingRequestKeyV2 = string
+/** Runtime-owned idempotency key; this is not a browser request key. */
+export type BookingInternalDecisionKeyV2 = string
+export const BOOKING_V2_BLOCKER_CODES = ['no_hotels_matched','hotel_not_visible','hotel_rates_failed','criterion_must_not_met','offer_target_not_reached','offer_unavailable'] as const
+export type BookingV2BlockerCode = typeof BOOKING_V2_BLOCKER_CODES[number]
+export const BOOKING_V2_GAP_CODES = ['byos_mapped_risk','check_avail_failed','check_avail_unverified','component_executor_unavailable','hotel_not_visible','hotel_rates_failed','offer_facts_changed','offer_not_loaded','offer_unavailable','order_not_found','order_outcome_not_observed','order_state_unknown','order_status_unavailable','requested_offers_not_loaded','search_failed','search_form_invalid','search_session_expired','search_terminal_timeout','stale_revision','surface_adapter_failed','undo_token_not_found','unhandled','unsupported','verified_offer_required','workspace_changed_during_action','criterion_must_not_met','no_hotels_matched','offer_target_not_reached'] as const
+export type BookingV2GapCode = typeof BOOKING_V2_GAP_CODES[number]
+export type BookingV2BlockerScope = 'search' | 'offer' | 'availability' | 'checkout'
+export interface CriterionBlockerV2 { blockerId: string; sourceActionId: string; sourceReceiptDigest: string; scope: BookingV2BlockerScope; code: BookingV2BlockerCode; criterionPath: string; strength: 'must'; valueDigest: string; valueLabel?: string; evidence: { factRefs: string[]; gapCodes: BookingV2GapCode[]; requested?: number; actual?: number } }
+export interface RelaxationApprovalV2 {
+  taskId: string
+  contextRef: string
+  sourceTurnId: string
+  presentationRequestKey: string
+  optionDigest: string
+  approvalId: string
+  deliveryNonce: string
+  blockerId: string
+  sourceActionId: string
+  sourceReceiptDigest: string
+  scope: BookingV2BlockerScope
+  code: BookingV2BlockerCode
+  criterionPath: string
+  valueDigest: string
+  from: 'must'
+  to: 'prefer' | 'drop'
+  approved: true
+}
+export interface RelaxationApprovalRefV2 { approvalId: string; blockerId: string; contextRef: string; sourceTurnId: string; presentationRequestKey: string; sourceActionId: string; targetActionId: string; sourceRevision: number; targetActionKind: BookingReadActionKindV2; to: 'prefer'|'drop'; expiresAt: string; nonce: string; sourceReceiptDigest: string; scope: BookingV2BlockerScope; code: BookingV2BlockerCode; criterionPath: string; valueDigest: string }
+interface Base<K extends BookingReadActionKindV2, I> { schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION_V2; kind: K; actionId: string; contextRef: string; expectedRevision: number; reason: string; factRefs: string[]; input: I; relaxationApprovalRef?: RelaxationApprovalRefV2 }
+export type SearchPatchActionV2 = Base<'search.patch', { patch: SearchCriteriaPatchV1 }>
+export type SearchRunActionV2 = Base<'search.run', Record<string, never>>
+export type ResultsViewPatchActionV2 = Base<'results.view.patch', { patch: ResultsViewPatchV1 }>
+export type HotelFocusActionV2 = Base<'hotel.focus', { hotelRef: string }>
+export type HotelSelectActionV2 = Base<'hotel.select', { hotelRef: string }>
+export type OffersQueryActionV2 = Base<'offers.query', { hotelRefs: string[]; criteria: OfferCriteriaV1 }>
+export type OffersViewPatchActionV2 = Base<'offers.view.patch', { hotelRef: string; criteria: OfferCriteriaV1 }>
+export type OffersCompareActionV2 = Base<'offers.compare', { offerRefs: string[]; requestedCount: number }>
+export interface LoadedOfferFactV2 { offerRef: string; offerVersionRef: string; hotelRef: string; evidenceLevel: EvidenceLevelV1; factRefs: string[] }
+export interface VerifiedOfferCapabilityV2 { offerRef: string; offerVersionRef: string; verifiedOfferRef: string; expiresAt: string }
+export type OfferSelectActionV2 = Base<'offer.select', { offerRef: string; offerVersionRef: string }>
+export type OfferCheckActionV2 = Base<'offer.check', { offerRef: string; offerVersionRef: string }>
+export type CheckoutPrepareActionV2 = Base<'checkout.prepare', { offerRef: string; offerVersionRef: string; verifiedOfferRef: string }>
+export type OrderObserveActionV2 = Base<'order.observe', { orderRef: string }>
+export type BookingReadActionV2=SearchPatchActionV2|SearchRunActionV2|ResultsViewPatchActionV2|HotelFocusActionV2|HotelSelectActionV2|OffersQueryActionV2|OffersViewPatchActionV2|OffersCompareActionV2|OfferSelectActionV2|OfferCheckActionV2|CheckoutPrepareActionV2|OrderObserveActionV2
+export interface BookingWorkspaceSnapshotV2 extends Omit<BookingWorkspaceSnapshotV1,'schemaVersion'|'surface'|'capabilities'|'loadedOffers'|'verifiedOfferRef'>{schemaVersion:typeof BOOKING_SURFACE_SCHEMA_VERSION_V2;surface:BookingSurfaceV2;loadedOffers:LoadedOfferFactV2[];verifiedOffer?:VerifiedOfferCapabilityV2;capabilities:{surface:BookingSurfaceV2;allowedActions:BookingReadActionKindV2[]}}
+export type BookingWorkspaceIngressSnapshotV2 = Pick<BookingWorkspaceSnapshotV2, 'schemaVersion'|'revision'|'locale'|'currency'|'searchDraft'|'results'|'visibleHotels'|'loadedOffers'|'focusedHotelRef'|'shortlistedOfferRefs'|'selectedOfferRef'>
+export type ActionObservationV2 =
+  | { kind: 'search.state'; searchSessionRef?: string; resultCount?: number; gapCodes?: BookingV2GapCode[] }
+  | { kind: 'results.state'; matchedHotelRefs: string[]; visibleCount: number; gapCodes?: BookingV2GapCode[] }
+  | { kind: 'hotel.focus'; hotelRef: string }
+  | { kind: 'hotel.selection'; hotelRef: string }
+  | { kind: 'offers.state'; hotelRefs: string[]; offerRefs: string[]; loadedHotelCount: number; gapCodes?: BookingV2GapCode[] }
+  | { kind: 'offer.selection'; offerRef: string; offerVersionRef: string }
+  | { kind: 'offer.availability'; offerRef: string; checkedOfferVersionRef: string; currentOfferVersionRef?: string; verifiedOfferRef?: string; available: boolean; changedFactRefs: string[]; gapCodes?: BookingV2GapCode[] }
+  | { kind: 'checkout.handoff'; offerRef: string; offerVersionRef: string; verifiedOfferRef: string; handoffRef: string }
+  | { kind: 'order.state'; orderRef: string; state: 'pending'|'verified'|'failed'|'unknown'; gapCodes?: BookingV2GapCode[] }
+  | { kind: 'gap'; code: BookingV2GapCode; factRefs: string[] }
+export interface ResultContractV2 {outcome:'complete'|'partial'|'empty';requestedCount?:number;actualCount?:number;hardCriteriaMet:boolean;factRefs:string[];gapCodes:BookingV2GapCode[];blockers:CriterionBlockerV2[];relaxationsApplied:RelaxationApprovalV2[]}
+export interface ActionReceiptV2 {schemaVersion:typeof BOOKING_SURFACE_SCHEMA_VERSION_V2;kind:'action.receipt';actionId:string;contextRef:string;status:'applied'|'needs_input'|'partial'|'no_match'|'unavailable'|'changed'|'stale'|'unsupported'|'failed';revision:number;observation:ActionObservationV2;resultContract:ResultContractV2;undoToken?:string}
+export interface UserTurnV2 {schemaVersion:typeof BOOKING_SURFACE_SCHEMA_VERSION_V2;kind:'user.turn';taskId:string;turnId:string;workspace:BookingWorkspaceSnapshotV2;request:{text:string;approval?:RelaxationApprovalV2}}
+/** Browser-to-BFF ingress. Identity is deliberately absent from this shape. */
+export interface IngressTurnV2 {schemaVersion:typeof BOOKING_SURFACE_SCHEMA_VERSION_V2;kind:'user.turn.ingress';requestKey:BookingRequestKeyV2;taskHandle?:string;surfaceHint:BookingSurfaceV2;workspace:BookingWorkspaceIngressSnapshotV2;request:{text:string}}
+export interface ReceiptContinuationV2 {schemaVersion:typeof BOOKING_SURFACE_SCHEMA_VERSION_V2;kind:'action.receipt.continuation';taskId:string;workspace:BookingWorkspaceSnapshotV2;receipt:ActionReceiptV2}
+export type BookingCopilotTurnV2=UserTurnV2|IngressTurnV2|ReceiptContinuationV2
+/** Typed BFF seam: implementations authenticate ingress and return only
+ * server-issued identity. The HTTP adapter constructs the internal UserTurn. */
+export interface BookingIngressIdentityBindingV2 {
+  taskId: string
+  turnId: string
+  contextRef: string
+  /** Authoritative BFF surface; never copied from the browser hint. */
+  surface: BookingSurfaceV2
+  /** BFF-authorized closed action subset for this surface. */
+  allowedActions: BookingReadActionKindV2[]
+}
+export interface BookingIngressPrincipalV2 { subject: string; scope: string }
+export interface BookingIngressBindingV2 {
+  bind(input: IngressTurnV2, principal: BookingIngressPrincipalV2): BookingIngressIdentityBindingV2 | Promise<BookingIngressIdentityBindingV2>
+}
+export interface BookingQuestionEventV2 {schemaVersion:typeof BOOKING_SURFACE_SCHEMA_VERSION_V2;eventId:string;taskId:string;contextRef:string;sequence:number;emittedAt:string;kind:'question';question:{questionId:string;prompt:string;missingFields:string[];type:'relaxation_approval_required';blocker:CriterionBlockerV2;approvalOptions:Array<{approval:RelaxationApprovalV2}>}}
+export interface BookingEventBaseV2 { schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION_V2; eventId: string; taskId: string; contextRef: string; sequence: number; emittedAt: string }
+export type BookingSurfaceEventV2 =
+  | (BookingEventBaseV2 & { kind: 'status'; status: 'submitted'|'working'|'waiting_receipt'|'input_required' })
+  | BookingQuestionEventV2
+  | (BookingEventBaseV2 & { kind: 'operation'; action: BookingReadActionV2 })
+  | (BookingEventBaseV2 & { kind: 'explanation'; explanation: { text: string; factRefs: string[] } })
+  | (BookingEventBaseV2 & { kind: 'terminal'; terminal: { status: 'completed'|'stopped'; summary: string; factRefs: string[] } })
+  | (BookingEventBaseV2 & { kind: 'error'; error: { code: string; message: string; retryable: boolean } })

package/ts/src/booking-surface/contracts.ts

@@ -0,0 +1,380 @@
+/**
+ * Canonical TypeScript contract for HotelByte's embedded Booking Copilot.
+ *
+ * Executable facts cross this boundary only as discriminated data. Human text
+ * is limited to a user turn or an explanation and is never parsed as an action.
+ */
+
+export const BOOKING_SURFACE_SCHEMA_VERSION = 'booking.surface.v1' as const
+/** SHA-256 of schemas/booking.surface.v1.schema.json; package proof pins drift. */
+export const BOOKING_SURFACE_SCHEMA_SHA256 = 'd9c2194ec839bd1168e70e8a201581addc005039d9b299660e20650bbb65df81' as const
+export const BOOKING_SURFACE_VERSION_HEADER = 'x-booking-surface-version' as const
+export const BOOKING_SURFACE_SCHEMA_SHA256_HEADER = 'x-booking-surface-schema-sha256' as const
+
+export const BOOKING_SURFACES = [
+  'tenant',
+  'customer_portal',
+  'storefront',
+  'payment_link',
+] as const
+export type BookingSurfaceV1 = (typeof BOOKING_SURFACES)[number]
+
+export const BOOKING_READ_ACTION_KINDS = [
+  'search.patch',
+  'search.run',
+  'results.view.patch',
+  'hotel.focus',
+  'hotel.select',
+  'offers.query',
+  'offers.view.patch',
+  'offers.compare',
+  'offer.select',
+  'offer.check',
+  'checkout.prepare',
+  'order.observe',
+] as const
+export type BookingReadActionKindV1 = (typeof BOOKING_READ_ACTION_KINDS)[number]
+
+export const BOOKING_RECEIPT_STATUSES = [
+  'applied',
+  'needs_input',
+  'partial',
+  'no_match',
+  'unavailable',
+  'changed',
+  'stale',
+  'unsupported',
+  'failed',
+] as const
+export type ActionReceiptStatusV1 = (typeof BOOKING_RECEIPT_STATUSES)[number]
+
+export const BOOKING_SURFACE_EVENT_KINDS = [
+  'status',
+  'question',
+  'operation',
+  'explanation',
+  'terminal',
+  'error',
+] as const
+export type BookingSurfaceEventKindV1 = (typeof BOOKING_SURFACE_EVENT_KINDS)[number]
+
+export type ContextRefV1 = string
+export type FactRefV1 = string
+export type HotelRefV1 = string
+export type OfferRefV1 = string
+export type VerifiedOfferRefV1 = string
+export type OrderRefV1 = string
+
+export type CriterionStrengthV1 = 'must' | 'prefer'
+export interface CriterionV1<T> {
+  strength: CriterionStrengthV1
+  value: T
+}
+
+export interface MoneyV1 {
+  /** Decimal string supplied by the authoritative page object; never recomputed by GoTry. */
+  amount: string
+  currency: string
+  sourceFactRef: FactRefV1
+}
+
+export interface OccupancyRoomV1 {
+  adults: number
+  childAges: number[]
+}
+
+export interface SearchCriteriaPatchV1 {
+  destination?: {
+    query?: string
+    placeRef?: string
+  }
+  hotel?: CriterionV1<{
+    name?: string
+    hotelRef?: HotelRefV1
+  }>
+  stay?: {
+    checkIn?: string
+    checkOut?: string
+  }
+  occupancy?: {
+    rooms: OccupancyRoomV1[]
+  }
+  budget?: CriterionV1<{
+    min?: MoneyV1
+    max?: MoneyV1
+  }>
+  starRating?: CriterionV1<{
+    min?: number
+    max?: number
+  }>
+  guestRating?: CriterionV1<{
+    min: number
+  }>
+  facilities?: CriterionV1<{
+    allOf: string[]
+  }>
+  distance?: CriterionV1<{
+    anchorLabel?: string
+    anchorRef?: string
+    maxKm: number
+  }>
+}
+
+export type ResultSortV1 =
+  | 'recommended'
+  | 'price_asc'
+  | 'price_desc'
+  | 'rating_desc'
+  | 'distance_asc'
+
+export interface ResultsViewPatchV1 {
+  starRating?: { min?: number; max?: number } | null
+  guestRatingMin?: number | null
+  facilitiesAllOf?: string[] | null
+  distance?: { anchorRef: string; maxKm: number } | null
+  price?: { min?: MoneyV1; max?: MoneyV1 } | null
+  sort?: ResultSortV1
+}
+
+export interface OfferCriteriaV1 {
+  roomType?: CriterionV1<string[]>
+  bedType?: CriterionV1<string[]>
+  meals?: CriterionV1<string[]>
+  freeCancellation?: CriterionV1<boolean>
+  freeCancellationUntil?: CriterionV1<string>
+  totalPriceMax?: CriterionV1<MoneyV1>
+  roomsAvailableMin?: CriterionV1<number>
+  payAtProperty?: CriterionV1<boolean>
+  mobileRate?: CriterionV1<boolean>
+  targetCount?: number
+  sort?: 'best_match' | 'total_price_asc' | 'cancellation_latest'
+}
+
+export type EvidenceLevelV1 = 'listed' | 'rate_loaded' | 'checked'
+
+export interface SurfaceCapabilitiesV1 {
+  surface: BookingSurfaceV1
+  allowedActions: BookingReadActionKindV1[]
+}
+
+export interface SearchDraftSnapshotV1 {
+  destination?: { query?: string; placeRef?: string }
+  stay?: { checkIn?: string; checkOut?: string }
+  occupancy?: { rooms: OccupancyRoomV1[] }
+  criteria?: SearchCriteriaPatchV1
+}
+
+export interface ResultViewSnapshotV1 {
+  status: 'idle' | 'loading' | 'ready' | 'partial' | 'failed'
+  filters?: ResultsViewPatchV1
+  sort?: ResultSortV1
+  resultCount?: number
+  searchSessionRef?: string
+}
+
+export interface VisibleHotelFactV1 {
+  hotelRef: HotelRefV1
+  name: string
+  starRating?: number
+  guestRating?: number
+  distanceKm?: number
+  facilityCodes?: string[]
+  factRefs: FactRefV1[]
+}
+
+export interface LoadedOfferFactV1 {
+  offerRef: OfferRefV1
+  hotelRef: HotelRefV1
+  evidenceLevel: EvidenceLevelV1
+  factRefs: FactRefV1[]
+}
+
+export interface BookingWorkspaceSnapshotV1 {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  contextRef: ContextRefV1
+  surface: BookingSurfaceV1
+  revision: number
+  locale: string
+  currency: string
+  searchDraft: SearchDraftSnapshotV1
+  results: ResultViewSnapshotV1
+  visibleHotels: VisibleHotelFactV1[]
+  loadedOffers: LoadedOfferFactV1[]
+  focusedHotelRef?: HotelRefV1
+  shortlistedOfferRefs: OfferRefV1[]
+  selectedOfferRef?: OfferRefV1
+  verifiedOfferRef?: VerifiedOfferRefV1
+  capabilities: SurfaceCapabilitiesV1
+}
+
+/**
+ * Browser bootstrap snapshot before the same-origin BFF binds an actor and
+ * mints contextRef/capabilities. It deliberately cannot assert any identity or
+ * capability field.
+ */
+export type BookingWorkspaceIngressSnapshotV1 = Omit<
+  BookingWorkspaceSnapshotV1,
+  'contextRef' | 'surface' | 'capabilities'
+>
+
+interface BookingReadActionBaseV1<K extends BookingReadActionKindV1, I> {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  kind: K
+  actionId: string
+  contextRef: ContextRefV1
+  expectedRevision: number
+  reason: string
+  factRefs: FactRefV1[]
+  input: I
+}
+
+export type SearchPatchActionV1 = BookingReadActionBaseV1<'search.patch', { patch: SearchCriteriaPatchV1 }>
+export type SearchRunActionV1 = BookingReadActionBaseV1<'search.run', Record<string, never>>
+export type ResultsViewPatchActionV1 = BookingReadActionBaseV1<'results.view.patch', { patch: ResultsViewPatchV1 }>
+export type HotelFocusActionV1 = BookingReadActionBaseV1<'hotel.focus', { hotelRef: HotelRefV1 }>
+export type HotelSelectActionV1 = BookingReadActionBaseV1<'hotel.select', { hotelRef: HotelRefV1 }>
+export type OffersQueryActionV1 = BookingReadActionBaseV1<'offers.query', { hotelRefs: HotelRefV1[]; criteria: OfferCriteriaV1 }>
+export type OffersViewPatchActionV1 = BookingReadActionBaseV1<'offers.view.patch', { hotelRef: HotelRefV1; criteria: OfferCriteriaV1 }>
+export type OffersCompareActionV1 = BookingReadActionBaseV1<'offers.compare', { offerRefs: OfferRefV1[]; requestedCount: number }>
+export type OfferSelectActionV1 = BookingReadActionBaseV1<'offer.select', { offerRef: OfferRefV1 }>
+export type OfferCheckActionV1 = BookingReadActionBaseV1<'offer.check', { offerRef: OfferRefV1 }>
+export type CheckoutPrepareActionV1 = BookingReadActionBaseV1<'checkout.prepare', { offerRef: OfferRefV1; verifiedOfferRef: VerifiedOfferRefV1 }>
+export type OrderObserveActionV1 = BookingReadActionBaseV1<'order.observe', { orderRef: OrderRefV1 }>
+
+export type BookingReadActionV1 =
+  | SearchPatchActionV1
+  | SearchRunActionV1
+  | ResultsViewPatchActionV1
+  | HotelFocusActionV1
+  | HotelSelectActionV1
+  | OffersQueryActionV1
+  | OffersViewPatchActionV1
+  | OffersCompareActionV1
+  | OfferSelectActionV1
+  | OfferCheckActionV1
+  | CheckoutPrepareActionV1
+  | OrderObserveActionV1
+
+export type ActionObservationV1 =
+  | { kind: 'search.state'; searchSessionRef?: string; resultCount?: number }
+  | { kind: 'results.state'; matchedHotelRefs: HotelRefV1[]; visibleCount: number }
+  | { kind: 'hotel.focus'; hotelRef: HotelRefV1 }
+  | { kind: 'hotel.selection'; hotelRef: HotelRefV1 }
+  | { kind: 'offers.state'; hotelRefs: HotelRefV1[]; offerRefs: OfferRefV1[]; loadedHotelCount: number }
+  | { kind: 'offer.selection'; offerRef: OfferRefV1 }
+  | { kind: 'offer.availability'; offerRef: OfferRefV1; verifiedOfferRef?: VerifiedOfferRefV1; available: boolean; changedFactRefs: FactRefV1[] }
+  | { kind: 'checkout.handoff'; offerRef: OfferRefV1; verifiedOfferRef: VerifiedOfferRefV1; handoffRef: string }
+  | { kind: 'order.state'; orderRef: OrderRefV1; state: 'pending' | 'verified' | 'failed' | 'unknown' }
+  | { kind: 'gap'; code: string; factRefs: FactRefV1[] }
+
+export interface ResultContractV1 {
+  outcome: 'complete' | 'partial' | 'empty'
+  requestedCount?: number
+  actualCount?: number
+  hardCriteriaMet: boolean
+  factRefs: FactRefV1[]
+  gapCodes: string[]
+}
+
+export interface ActionReceiptV1 {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  kind: 'action.receipt'
+  actionId: string
+  contextRef: ContextRefV1
+  status: ActionReceiptStatusV1
+  revision: number
+  observation: ActionObservationV1
+  resultContract: ResultContractV1
+  undoToken?: string
+}
+
+export interface UserTurnV1 {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  kind: 'user.turn'
+  taskId?: string
+  workspace: BookingWorkspaceSnapshotV1
+  request: {
+    /** Transport-only natural language. It must never be persisted as executable state. */
+    text: string
+  }
+}
+
+export interface BookingCopilotIngressTurnV1 {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  kind: 'user.turn.ingress'
+  taskId?: string
+  /** Bootstrap may omit this field or send null. A browser cannot mint it. */
+  contextRef?: null
+  surfaceHint: BookingSurfaceV1
+  workspace: BookingWorkspaceIngressSnapshotV1
+  request: {
+    text: string
+  }
+}
+
+export interface ActionReceiptContinuationV1 {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  kind: 'action.receipt.continuation'
+  taskId: string
+  workspace: BookingWorkspaceSnapshotV1
+  receipt: ActionReceiptV1
+}
+
+export type BookingCopilotTurnV1 = UserTurnV1 | ActionReceiptContinuationV1
+
+interface BookingSurfaceEventBaseV1<K extends BookingSurfaceEventKindV1> {
+  schemaVersion: typeof BOOKING_SURFACE_SCHEMA_VERSION
+  eventId: string
+  taskId: string
+  contextRef: ContextRefV1
+  sequence: number
+  emittedAt: string
+  kind: K
+}
+
+export type BookingStatusEventV1 = BookingSurfaceEventBaseV1<'status'> & {
+  status: 'submitted' | 'working' | 'waiting_receipt' | 'input_required'
+}
+
+export type BookingQuestionEventV1 = BookingSurfaceEventBaseV1<'question'> & {
+  question: {
+    questionId: string
+    prompt: string
+    missingFields: string[]
+  }
+}
+
+export type BookingOperationEventV1 = BookingSurfaceEventBaseV1<'operation'> & {
+  action: BookingReadActionV1
+}
+
+export type BookingExplanationEventV1 = BookingSurfaceEventBaseV1<'explanation'> & {
+  explanation: {
+    text: string
+    factRefs: FactRefV1[]
+  }
+}
+
+export type BookingTerminalEventV1 = BookingSurfaceEventBaseV1<'terminal'> & {
+  terminal: {
+    status: 'completed' | 'stopped'
+    summary: string
+    factRefs: FactRefV1[]
+  }
+}
+
+export type BookingErrorEventV1 = BookingSurfaceEventBaseV1<'error'> & {
+  error: {
+    code: string
+    message: string
+    retryable: boolean
+  }
+}
+
+export type BookingSurfaceEventV1 =
+  | BookingStatusEventV1
+  | BookingQuestionEventV1
+  | BookingOperationEventV1
+  | BookingExplanationEventV1
+  | BookingTerminalEventV1
+  | BookingErrorEventV1