@danceiny/gotry 0.0.1-rc.17 → 0.0.1-rc.19

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

@@ -1,453 +1,205 @@
-import {
-  BOOKING_READ_ACTION_KINDS,
-  BOOKING_RECEIPT_STATUSES,
-  BOOKING_SURFACES,
-  BOOKING_SURFACE_EVENT_KINDS,
-  type ActionReceiptV1,
-  type BookingCopilotIngressTurnV1,
-  type BookingCopilotTurnV1,
-  type BookingReadActionKindV1,
-  type BookingReadActionV1,
-  type BookingSurfaceEventV1,
-  type BookingWorkspaceIngressSnapshotV1,
-  type BookingWorkspaceSnapshotV1,
-} from './contracts.ts'
-import { Ajv2020, type ErrorObject, type ValidateFunction } from 'ajv/dist/2020.js'
 import { readFileSync } from 'node:fs'
-
-const CANONICAL_SCHEMA = JSON.parse(readFileSync(
-  new URL('../../../schemas/booking.surface.v1.schema.json', import.meta.url),
-  'utf8',
-)) as Record<string, unknown>
-const CANONICAL_SCHEMA_ID = 'https://gotry.dev/schemas/booking.surface.v1.schema.json'
-const canonicalAjv = new Ajv2020({ allErrors: true, strict: true })
-canonicalAjv.addSchema(CANONICAL_SCHEMA)
-const validateCanonicalAction = canonicalAjv.compile({
-  $ref: `${CANONICAL_SCHEMA_ID}#/$defs/BookingReadActionV1`,
-}) as ValidateFunction
-const validateCanonicalReceipt = canonicalAjv.compile({
-  $ref: `${CANONICAL_SCHEMA_ID}#/$defs/ActionReceiptV1`,
-}) as ValidateFunction
-const validateCanonicalWorkspace = canonicalAjv.compile({ $ref: `${CANONICAL_SCHEMA_ID}#/$defs/BookingWorkspaceSnapshotV1` }) as ValidateFunction
-const validateCanonicalIngressTurn = canonicalAjv.compile({ $ref: `${CANONICAL_SCHEMA_ID}#/$defs/BookingCopilotIngressTurnV1` }) as ValidateFunction
-const validateCanonicalTurn = canonicalAjv.compile({ $ref: `${CANONICAL_SCHEMA_ID}#/$defs/BookingCopilotTurnV1` }) as ValidateFunction
-
-export type BookingSurfaceValidationResult =
-  | { ok: true }
-  | { ok: false; errors: string[] }
-
-const ACTION_KINDS = new Set<string>(BOOKING_READ_ACTION_KINDS)
-const RECEIPT_STATUSES = new Set<string>(BOOKING_RECEIPT_STATUSES)
-const SURFACES = new Set<string>(BOOKING_SURFACES)
-const EVENT_KINDS = new Set<string>(BOOKING_SURFACE_EVENT_KINDS)
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === 'string' && value.length > 0
-}
-
-function isRevision(value: unknown): value is number {
-  return Number.isInteger(value) && Number(value) >= 0
-}
-
-function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every(isNonEmptyString)
-}
-
-function isCount(value: unknown): value is number {
-  return Number.isInteger(value) && Number(value) >= 0
-}
-function isSafeCode(value: unknown): value is string { return typeof value === 'string' && /^[a-z][a-z0-9._-]*$/.test(value) }
-
-function receiptContainsUnsafeOpaqueText(value: unknown): boolean {
-  if (typeof value === 'string') return /[^\s@]+@[^\s@]+\.[^\s@]+|Bearer\s+[^\s]+|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/i.test(value)
-  if (Array.isArray(value)) return value.some(receiptContainsUnsafeOpaqueText)
-  if (isRecord(value)) return Object.values(value).some(receiptContainsUnsafeOpaqueText)
-  return false
-}
-
-function exactKeys(
-  value: Record<string, unknown>,
-  allowed: readonly string[],
-  required: readonly string[],
-  at: string,
-  errors: string[],
-): void {
-  const allow = new Set(allowed)
-  for (const key of Object.keys(value)) if (!allow.has(key)) errors.push(`${at}.${key}: additional property is forbidden`)
-  for (const key of required) if (!Object.hasOwn(value, key)) errors.push(`${at}.${key}: required`)
-}
-
-function validateIngressWorkspace(value: unknown, at: string, errors: string[]): value is BookingWorkspaceIngressSnapshotV1 {
-  if (!isRecord(value)) { errors.push(`${at}: object required`); return false }
-  exactKeys(value, [
-    'schemaVersion', 'revision', 'locale', 'currency', 'searchDraft', 'results',
-    'visibleHotels', 'loadedOffers', 'focusedHotelRef', 'shortlistedOfferRefs',
-    'selectedOfferRef', 'verifiedOfferRef',
-  ], [
-    'schemaVersion', 'revision', 'locale', 'currency', 'searchDraft', 'results',
-    'visibleHotels', 'loadedOffers', 'shortlistedOfferRefs',
-  ], at, errors)
-  if (value.schemaVersion !== 'booking.surface.v1') errors.push(`${at}.schemaVersion: booking.surface.v1 required`)
-  if (!isRevision(value.revision)) errors.push(`${at}.revision: non-negative integer required`)
-  if (!isNonEmptyString(value.locale)) errors.push(`${at}.locale: non-empty string required`)
-  if (typeof value.currency !== 'string' || !/^[A-Z]{3}$/.test(value.currency)) errors.push(`${at}.currency: ISO-4217 code required`)
-  if (!isRecord(value.searchDraft)) errors.push(`${at}.searchDraft: object required`)
-  if (!isRecord(value.results)) errors.push(`${at}.results: object required`)
-  if (!Array.isArray(value.visibleHotels)) errors.push(`${at}.visibleHotels: array required`)
-  if (!Array.isArray(value.loadedOffers)) errors.push(`${at}.loadedOffers: array required`)
-  if (!isStringArray(value.shortlistedOfferRefs)) errors.push(`${at}.shortlistedOfferRefs: opaque-ref array required`)
-  return errors.length === 0
-}
-
-function validateWorkspace(value: unknown, at: string, errors: string[]): value is BookingWorkspaceSnapshotV1 {
-  if (!isRecord(value)) { errors.push(`${at}: object required`); return false }
-  const {
-    contextRef: _contextRef,
-    surface: _surface,
-    capabilities: _capabilities,
-    ...ingressShape
-  } = value
-  validateIngressWorkspace(ingressShape, at, errors)
-  const allowed = [
-    'schemaVersion', 'contextRef', 'surface', 'revision', 'locale', 'currency',
-    'searchDraft', 'results', 'visibleHotels', 'loadedOffers', 'focusedHotelRef',
-    'shortlistedOfferRefs', 'selectedOfferRef', 'verifiedOfferRef', 'capabilities',
-  ]
-  exactKeys(value, allowed, [
-    'schemaVersion', 'contextRef', 'surface', 'revision', 'locale', 'currency',
-    'searchDraft', 'results', 'visibleHotels', 'loadedOffers', 'shortlistedOfferRefs',
-    'capabilities',
-  ], at, errors)
-  if (!isNonEmptyString(value.contextRef)) errors.push(`${at}.contextRef: server-minted opaque ref required`)
-  if (typeof value.surface !== 'string' || !SURFACES.has(value.surface)) errors.push(`${at}.surface: unsupported surface`)
-  if (!isRecord(value.capabilities)) {
-    errors.push(`${at}.capabilities: object required`)
-  } else {
-    exactKeys(value.capabilities, ['surface', 'allowedActions'], ['surface', 'allowedActions'], `${at}.capabilities`, errors)
-    if (value.capabilities.surface !== value.surface) errors.push(`${at}.capabilities.surface: must equal workspace.surface`)
-    const actionKinds = value.capabilities.allowedActions
-    if (!Array.isArray(actionKinds) || !actionKinds.every((kind) => typeof kind === 'string' && ACTION_KINDS.has(kind))) {
-      errors.push(`${at}.capabilities.allowedActions: closed action-kind array required`)
-    } else if (new Set(actionKinds).size !== actionKinds.length) {
-      errors.push(`${at}.capabilities.allowedActions: duplicates forbidden`)
-    }
-  }
-  appendCanonicalErrors(validateCanonicalWorkspace, value, at, errors)
-  return errors.length === 0
-}
-
-const ACTION_INPUT_KEYS: Record<BookingReadActionKindV1, { allowed: readonly string[]; required: readonly string[] }> = {
-  'search.patch': { allowed: ['patch'], required: ['patch'] },
-  'search.run': { allowed: [], required: [] },
-  'results.view.patch': { allowed: ['patch'], required: ['patch'] },
-  'hotel.focus': { allowed: ['hotelRef'], required: ['hotelRef'] },
-  'hotel.select': { allowed: ['hotelRef'], required: ['hotelRef'] },
-  'offers.query': { allowed: ['hotelRefs', 'criteria'], required: ['hotelRefs', 'criteria'] },
-  'offers.view.patch': { allowed: ['hotelRef', 'criteria'], required: ['hotelRef', 'criteria'] },
-  'offers.compare': { allowed: ['offerRefs', 'requestedCount'], required: ['offerRefs', 'requestedCount'] },
-  'offer.select': { allowed: ['offerRef'], required: ['offerRef'] },
-  'offer.check': { allowed: ['offerRef'], required: ['offerRef'] },
-  'checkout.prepare': { allowed: ['offerRef', 'verifiedOfferRef'], required: ['offerRef', 'verifiedOfferRef'] },
-  'order.observe': { allowed: ['orderRef'], required: ['orderRef'] },
-}
-
-function collectBookingReadActionErrors(value: unknown, at: string): string[] {
-  const errors: string[] = []
-  if (!isRecord(value)) return [`${at}: typed action object required; text is never executable`]
-  exactKeys(value, [
-    'schemaVersion', 'kind', 'actionId', 'contextRef', 'expectedRevision',
-    'reason', 'factRefs', 'input',
-  ], [
-    'schemaVersion', 'kind', 'actionId', 'contextRef', 'expectedRevision',
-    'reason', 'factRefs', 'input',
-  ], at, errors)
-  if (value.schemaVersion !== 'booking.surface.v1') errors.push(`${at}.schemaVersion: booking.surface.v1 required`)
-  if (typeof value.kind !== 'string' || !ACTION_KINDS.has(value.kind)) {
-    errors.push(`${at}.kind: unregistered read action`)
-  }
-  if (!isNonEmptyString(value.actionId)) errors.push(`${at}.actionId: opaque ref required`)
-  if (!isNonEmptyString(value.contextRef)) errors.push(`${at}.contextRef: opaque ref required`)
-  if (!isRevision(value.expectedRevision)) errors.push(`${at}.expectedRevision: non-negative integer required`)
-  if (!isNonEmptyString(value.reason)) errors.push(`${at}.reason: non-empty explanation required`)
-  if (!isStringArray(value.factRefs)) errors.push(`${at}.factRefs: opaque-ref array required`)
-  if (!isRecord(value.input)) {
-    errors.push(`${at}.input: typed object required`)
-  } else if (typeof value.kind === 'string' && ACTION_KINDS.has(value.kind)) {
-    const spec = ACTION_INPUT_KEYS[value.kind as BookingReadActionKindV1]
-    exactKeys(value.input, spec.allowed, spec.required, `${at}.input`, errors)
-  }
-  if (!validateCanonicalAction(value)) {
-    for (const error of validateCanonicalAction.errors ?? []) {
-      errors.push(canonicalError(error, at))
-    }
-  }
-  return errors
-}
-
-function canonicalError(error: ErrorObject, at: string): string {
-  const path = error.instancePath ? error.instancePath.replaceAll('/', '.') : ''
-  const property = error.keyword === 'additionalProperties'
-    ? `.${String((error.params as { additionalProperty?: unknown }).additionalProperty ?? '')}`
-    : ''
-  return `${at}${path}${property}: ${error.message ?? error.keyword}`
-}
-
-function appendCanonicalErrors(validate: ValidateFunction, value: unknown, at: string, errors: string[]): void {
-  if (!validate(value)) for (const error of validate.errors ?? []) errors.push(canonicalError(error, at))
-}
-
-export function validateBookingReadActionV1(value: unknown): BookingSurfaceValidationResult {
-  const errors = collectBookingReadActionErrors(value, '$')
-  return errors.length === 0 ? { ok: true } : { ok: false, errors }
-}
-
-function collectReceiptErrors(value: unknown, at: string): string[] {
-  const errors: string[] = []
-  if (!isRecord(value)) return [`${at}: typed receipt object required`]
-  exactKeys(value, [
-    'schemaVersion', 'kind', 'actionId', 'contextRef', 'status', 'revision',
-    'observation', 'resultContract', 'undoToken',
-  ], [
-    'schemaVersion', 'kind', 'actionId', 'contextRef', 'status', 'revision',
-    'observation', 'resultContract',
-  ], at, errors)
-  if (value.schemaVersion !== 'booking.surface.v1') errors.push(`${at}.schemaVersion: booking.surface.v1 required`)
-  if (value.kind !== 'action.receipt') errors.push(`${at}.kind: action.receipt required`)
-  if (!isNonEmptyString(value.actionId)) errors.push(`${at}.actionId: opaque ref required`)
-  if (!isNonEmptyString(value.contextRef)) errors.push(`${at}.contextRef: opaque ref required`)
-  if (typeof value.status !== 'string' || !RECEIPT_STATUSES.has(value.status)) errors.push(`${at}.status: unregistered receipt status`)
-  if (!isRevision(value.revision)) errors.push(`${at}.revision: non-negative integer required`)
-  if (value.undoToken !== undefined && !isNonEmptyString(value.undoToken)) errors.push(`${at}.undoToken: opaque ref required`)
-  validateActionObservation(value.observation, `${at}.observation`, errors)
-  validateResultContract(value.resultContract, `${at}.resultContract`, errors)
-  return errors
-}
-
-function validateActionObservation(value: unknown, at: string, errors: string[]): void {
-  if (!isRecord(value)) {
-    errors.push(`${at}: discriminated object required`)
-    return
-  }
-
-  switch (value.kind) {
-    case 'search.state':
-      exactKeys(value, ['kind', 'searchSessionRef', 'resultCount'], ['kind'], at, errors)
-      if (value.searchSessionRef !== undefined && !isNonEmptyString(value.searchSessionRef)) errors.push(`${at}.searchSessionRef: opaque ref required`)
-      if (value.resultCount !== undefined && !isCount(value.resultCount)) errors.push(`${at}.resultCount: non-negative integer required`)
-      return
-    case 'results.state':
-      exactKeys(value, ['kind', 'matchedHotelRefs', 'visibleCount'], ['kind', 'matchedHotelRefs', 'visibleCount'], at, errors)
-      if (!isStringArray(value.matchedHotelRefs)) errors.push(`${at}.matchedHotelRefs: opaque-ref array required`)
-      if (!isCount(value.visibleCount)) errors.push(`${at}.visibleCount: non-negative integer required`)
-      return
-    case 'hotel.focus':
-      exactKeys(value, ['kind', 'hotelRef'], ['kind', 'hotelRef'], at, errors)
-      if (!isNonEmptyString(value.hotelRef)) errors.push(`${at}.hotelRef: opaque ref required`)
-      return
-    case 'hotel.selection':
-      exactKeys(value, ['kind', 'hotelRef'], ['kind', 'hotelRef'], at, errors)
-      if (!isNonEmptyString(value.hotelRef)) errors.push(`${at}.hotelRef: opaque ref required`)
-      return
-    case 'offers.state':
-      exactKeys(value, ['kind', 'hotelRefs', 'offerRefs', 'loadedHotelCount'], ['kind', 'hotelRefs', 'offerRefs', 'loadedHotelCount'], at, errors)
-      if (!isStringArray(value.hotelRefs)) errors.push(`${at}.hotelRefs: opaque-ref array required`)
-      if (!isStringArray(value.offerRefs)) errors.push(`${at}.offerRefs: opaque-ref array required`)
-      if (!isCount(value.loadedHotelCount)) errors.push(`${at}.loadedHotelCount: non-negative integer required`)
-      return
-    case 'offer.selection':
-      exactKeys(value, ['kind', 'offerRef'], ['kind', 'offerRef'], at, errors)
-      if (!isNonEmptyString(value.offerRef)) errors.push(`${at}.offerRef: opaque ref required`)
-      return
-    case 'offer.availability':
-      exactKeys(value, ['kind', 'offerRef', 'verifiedOfferRef', 'available', 'changedFactRefs'], ['kind', 'offerRef', 'available', 'changedFactRefs'], at, errors)
-      if (!isNonEmptyString(value.offerRef)) errors.push(`${at}.offerRef: opaque ref required`)
-      if (value.verifiedOfferRef !== undefined && !isNonEmptyString(value.verifiedOfferRef)) errors.push(`${at}.verifiedOfferRef: opaque ref required`)
-      if (typeof value.available !== 'boolean') errors.push(`${at}.available: boolean required`)
-      if (!isStringArray(value.changedFactRefs)) errors.push(`${at}.changedFactRefs: opaque-ref array required`)
-      return
-    case 'checkout.handoff':
-      exactKeys(value, ['kind', 'offerRef', 'verifiedOfferRef', 'handoffRef'], ['kind', 'offerRef', 'verifiedOfferRef', 'handoffRef'], at, errors)
-      if (!isNonEmptyString(value.offerRef)) errors.push(`${at}.offerRef: opaque ref required`)
-      if (!isNonEmptyString(value.verifiedOfferRef)) errors.push(`${at}.verifiedOfferRef: opaque ref required`)
-      if (!isNonEmptyString(value.handoffRef)) errors.push(`${at}.handoffRef: opaque ref required`)
-      return
-    case 'order.state': {
-      exactKeys(value, ['kind', 'orderRef', 'state'], ['kind', 'orderRef', 'state'], at, errors)
-      const states = new Set(['pending', 'verified', 'failed', 'unknown'])
-      if (!isNonEmptyString(value.orderRef)) errors.push(`${at}.orderRef: opaque ref required`)
-      if (typeof value.state !== 'string' || !states.has(value.state)) errors.push(`${at}.state: unregistered order state`)
-      return
+import { Ajv2020, type ValidateFunction } from 'ajv/dist/2020.js'
+import { BOOKING_READ_ACTION_KINDS, BOOKING_BLOCKER_CODES, BOOKING_GAP_CODES } from './contracts.ts'
+
+const schema = JSON.parse(readFileSync(new URL('../../../schemas/booking.surface.schema.json', import.meta.url), 'utf8')) as Record<string, unknown>
+const ajv = new Ajv2020({ allErrors: true, strict: true })
+ajv.addSchema(schema)
+const validate: ValidateFunction = ajv.compile(schema)
+const validateActionCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Action` })
+const validateBlockerCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Blocker` })
+const validateApprovalCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Approval` })
+const validateEventCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Event` })
+const kinds = new Set<string>(BOOKING_READ_ACTION_KINDS)
+const codes = new Set<string>(BOOKING_BLOCKER_CODES)
+const gapCodes = new Set<string>(BOOKING_GAP_CODES)
+const safeOpaque = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(value)
+const safeRequestKey = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{7,127}$/.test(value) && !secret.test(value)
+const secret = /(?:Bearer\s+\S|\bsk-(?!ill(?:s)?\b)[A-Za-z0-9_-]{12,}|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)/i
+// `.example` is reserved for documentation, so these identifiers cannot be a
+// real mailbox. Do not allowlist lookalikes on routable domains.
+const technicalEmail = /^(?:schema|version)@[a-z0-9-]+\.example$/i
+const currencyAmount = /\b(?:[A-Z]{3}\s*\d+(?:\.\d+)?|\d+(?:\.\d+)?\s*[A-Z]{3})\b/
+const rfc3339DateTime = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|([+-])(\d{2}):(\d{2}))$/
+
+export function isBookingDateTime(value: unknown): value is string {
+  if (typeof value !== 'string') return false
+  const match = rfc3339DateTime.exec(value)
+  if (!match) return false
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText] = match
+  const year = Number(yearText)
+  const month = Number(monthText)
+  const day = Number(dayText)
+  const hour = Number(hourText)
+  const minute = Number(minuteText)
+  const second = Number(secondText)
+  const offsetHour = match[9] === undefined ? 0 : Number(match[9])
+  const offsetMinute = match[10] === undefined ? 0 : Number(match[10])
+  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) return false
+  const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate()
+  if (day < 1 || day > daysInMonth) return false
+  return !Number.isNaN(Date.parse(value))
+}
+
+function normalizedWords(value: string): string {
+  return value.normalize('NFKC').replace(/[^\p{L}\p{N}.]+/gu, ' ').trim()
+}
+
+function hasSupplierCost(value: string): boolean {
+  const normalized = normalizedWords(value)
+  const lower = normalized.toLowerCase()
+  return (
+    /\b(?:supplier|vendor|internal)\b/.test(lower) &&
+    /\b(?:cost|rate|price)\b/.test(lower) &&
+    currencyAmount.test(normalized.toUpperCase())
+  )
+}
+
+function hasInternationalPhone(value: string): boolean {
+  const normalized = value.normalize('NFKC')
+  for (const plusIndex of normalized.split('').flatMap((char, index) => char === '+' ? [index] : [])) {
+    let digits = ''
+    for (const char of normalized.slice(plusIndex + 1, plusIndex + 48)) {
+      if (/\d/u.test(char)) digits += char
+      else if (/\p{L}|@/u.test(char)) break
+      if (digits.length > 15) break
     }
-    case 'gap':
-      exactKeys(value, ['kind', 'code', 'factRefs'], ['kind', 'code', 'factRefs'], at, errors)
-      if (!isSafeCode(value.code)) errors.push(`${at}.code: safe identifier required`)
-      if (!isStringArray(value.factRefs)) errors.push(`${at}.factRefs: opaque-ref array required`)
-      return
-    default:
-      errors.push(`${at}.kind: unregistered observation kind`)
-  }
-}
-
-function validateResultContract(value: unknown, at: string, errors: string[]): void {
-  if (!isRecord(value)) {
-    errors.push(`${at}: object required`)
-    return
+    if (/^[1-9]\d{7,14}$/.test(digits)) return true
   }
-  exactKeys(value, ['outcome', 'requestedCount', 'actualCount', 'hardCriteriaMet', 'factRefs', 'gapCodes'], ['outcome', 'hardCriteriaMet', 'factRefs', 'gapCodes'], at, errors)
-  const outcomes = new Set(['complete', 'partial', 'empty'])
-  if (typeof value.outcome !== 'string' || !outcomes.has(value.outcome)) errors.push(`${at}.outcome: complete, partial, or empty required`)
-  if (value.requestedCount !== undefined && !isCount(value.requestedCount)) errors.push(`${at}.requestedCount: non-negative integer required`)
-  if (value.actualCount !== undefined && !isCount(value.actualCount)) errors.push(`${at}.actualCount: non-negative integer required`)
-  if (typeof value.hardCriteriaMet !== 'boolean') errors.push(`${at}.hardCriteriaMet: boolean required`)
-  if (!isStringArray(value.factRefs)) errors.push(`${at}.factRefs: opaque-ref array required`)
-  if (!Array.isArray(value.gapCodes) || !value.gapCodes.every(isSafeCode)) errors.push(`${at}.gapCodes: safe identifier array required`)
-}
-
-export function validateActionReceiptV1(value: unknown): BookingSurfaceValidationResult {
-  const errors = collectReceiptErrors(value, '$')
-  if (receiptContainsUnsafeOpaqueText(value)) errors.push('$: receipt contains unsafe non-opaque text')
-  if (!validateCanonicalReceipt(value)) {
-    for (const error of validateCanonicalReceipt.errors ?? []) errors.push(canonicalError(error, '$'))
-  }
-  return errors.length === 0 ? { ok: true } : { ok: false, errors }
-}
-
-export function validateBookingCopilotIngressTurnV1(value: unknown): BookingSurfaceValidationResult {
-  const errors: string[] = []
-  if (!isRecord(value)) return { ok: false, errors: ['$: object required'] }
-  exactKeys(value, [
-    'schemaVersion', 'kind', 'taskId', 'contextRef', 'surfaceHint', 'workspace', 'request',
-  ], ['schemaVersion', 'kind', 'surfaceHint', 'workspace', 'request'], '$', errors)
-  if (value.schemaVersion !== 'booking.surface.v1') errors.push('$.schemaVersion: booking.surface.v1 required')
-  if (value.kind !== 'user.turn.ingress') errors.push('$.kind: user.turn.ingress required')
-  if (value.contextRef !== undefined && value.contextRef !== null) errors.push('$.contextRef: bootstrap may only omit it or send null')
-  if (typeof value.surfaceHint !== 'string' || !SURFACES.has(value.surfaceHint)) errors.push('$.surfaceHint: unsupported surface hint')
-  validateIngressWorkspace(value.workspace, '$.workspace', errors)
-  if (!isRecord(value.request)) {
-    errors.push('$.request: object required')
-  } else {
-    exactKeys(value.request, ['text'], ['text'], '$.request', errors)
-    if (!isNonEmptyString(value.request.text)) errors.push('$.request.text: non-empty string required')
-  }
-  appendCanonicalErrors(validateCanonicalIngressTurn, value, '$', errors)
-  return errors.length === 0 ? { ok: true } : { ok: false, errors }
-}
-
-export function validateBookingCopilotTurnV1(value: unknown): BookingSurfaceValidationResult {
-  const errors: string[] = []
-  if (!isRecord(value)) return { ok: false, errors: ['$: object required'] }
-  if (value.kind === 'user.turn') {
-    exactKeys(value, ['schemaVersion', 'kind', 'taskId', 'workspace', 'request'], ['schemaVersion', 'kind', 'workspace', 'request'], '$', errors)
-    if (!isRecord(value.request)) errors.push('$.request: object required')
-    else {
-      exactKeys(value.request, ['text'], ['text'], '$.request', errors)
-      if (!isNonEmptyString(value.request.text)) errors.push('$.request.text: non-empty string required')
-    }
-  } else if (value.kind === 'action.receipt.continuation') {
-    exactKeys(value, ['schemaVersion', 'kind', 'taskId', 'workspace', 'receipt'], ['schemaVersion', 'kind', 'taskId', 'workspace', 'receipt'], '$', errors)
-    if (!isNonEmptyString(value.taskId)) errors.push('$.taskId: opaque ref required')
-    errors.push(...collectReceiptErrors(value.receipt, '$.receipt'))
-    const receiptValidation = validateActionReceiptV1(value.receipt)
-    if (!receiptValidation.ok) errors.push(...receiptValidation.errors.map((error) => `$.receipt${error.slice(1)}`))
-  } else {
-    errors.push('$.kind: user.turn or action.receipt.continuation required')
-  }
-  if (value.schemaVersion !== 'booking.surface.v1') errors.push('$.schemaVersion: booking.surface.v1 required')
-  validateWorkspace(value.workspace, '$.workspace', errors)
-  if (value.kind === 'action.receipt.continuation' && isRecord(value.workspace) && isRecord(value.receipt)) {
-    if (value.receipt.contextRef !== value.workspace.contextRef) errors.push('$.receipt.contextRef: must equal workspace.contextRef')
-    if (value.receipt.revision !== value.workspace.revision) errors.push('$.receipt.revision: must equal workspace.revision')
-  }
-  appendCanonicalErrors(validateCanonicalTurn, value, '$', errors)
-  return errors.length === 0 ? { ok: true } : { ok: false, errors }
+  return false
 }
 
-export function validateBookingSurfaceEventV1(value: unknown): BookingSurfaceValidationResult {
-  const errors: string[] = []
-  if (!isRecord(value)) return { ok: false, errors: ['$: typed event object required'] }
-  const common = ['schemaVersion', 'eventId', 'taskId', 'contextRef', 'sequence', 'emittedAt', 'kind'] as const
-  const branchKeys: Record<string, string> = {
-    status: 'status',
-    question: 'question',
-    operation: 'action',
-    explanation: 'explanation',
-    terminal: 'terminal',
-    error: 'error',
-  }
-  const branchKey = typeof value.kind === 'string' ? branchKeys[value.kind] : undefined
-  exactKeys(value, [...common, ...(branchKey ? [branchKey] : [])], [...common, ...(branchKey ? [branchKey] : [])], '$', errors)
-  if (value.schemaVersion !== 'booking.surface.v1') errors.push('$.schemaVersion: booking.surface.v1 required')
-  if (!isNonEmptyString(value.eventId)) errors.push('$.eventId: opaque ref required')
-  if (!isNonEmptyString(value.taskId)) errors.push('$.taskId: opaque ref required')
-  if (!isNonEmptyString(value.contextRef)) errors.push('$.contextRef: server-minted opaque ref required')
-  if (!Number.isInteger(value.sequence) || Number(value.sequence) < 1) errors.push('$.sequence: positive integer required')
-  if (!isNonEmptyString(value.emittedAt)) errors.push('$.emittedAt: timestamp required')
-  if (typeof value.kind !== 'string' || !EVENT_KINDS.has(value.kind)) errors.push('$.kind: unregistered event kind')
-  if (value.kind === 'status') {
-    const statuses = new Set(['submitted', 'working', 'waiting_receipt', 'input_required'])
-    if (typeof value.status !== 'string' || !statuses.has(value.status)) errors.push('$.status: unregistered task status')
-  }
-  if (value.kind === 'question') {
-    if (!isRecord(value.question)) {
-      errors.push('$.question: typed object required')
-    } else {
-      exactKeys(value.question, ['questionId', 'prompt', 'missingFields'], ['questionId', 'prompt', 'missingFields'], '$.question', errors)
-      if (!isNonEmptyString(value.question.questionId)) errors.push('$.question.questionId: opaque ref required')
-      if (!isNonEmptyString(value.question.prompt)) errors.push('$.question.prompt: non-empty string required')
-      if (!isStringArray(value.question.missingFields)) errors.push('$.question.missingFields: string array required')
-    }
-  }
-  if (value.kind === 'operation') errors.push(...collectBookingReadActionErrors(value.action, '$.action'))
-  if (value.kind === 'explanation') {
-    if (!isRecord(value.explanation)) {
-      errors.push('$.explanation: typed object required')
-    } else {
-      exactKeys(value.explanation, ['text', 'factRefs'], ['text', 'factRefs'], '$.explanation', errors)
-      if (!isNonEmptyString(value.explanation.text)) errors.push('$.explanation.text: non-empty string required')
-      if (!isStringArray(value.explanation.factRefs)) errors.push('$.explanation.factRefs: opaque-ref array required')
+function hasPaymentCard(value: string): boolean {
+  const normalized = value.normalize('NFKC')
+  const candidates = normalized.match(/(?:\d[ -]?){12,18}\d/g) ?? []
+  const explicitlyLabeled = /\b(?:card|payment|visa|mastercard)\b/i.test(normalized)
+  return candidates.some((candidate) => (explicitlyLabeled || /[ -]/.test(candidate)) && luhn(candidate))
+}
+
+function hasSensitiveText(value: string, opts: { allowOpaqueNumericId?: boolean } = {}): boolean {
+  const normalized = value.normalize('NFKC')
+  if (normalized.includes('@') && !technicalEmail.test(normalized.trim())) return true
+  return secret.test(normalized) || hasInternationalPhone(normalized) || hasSupplierCost(normalized) || (!opts.allowOpaqueNumericId && hasPaymentCard(normalized))
+}
+function luhn(value: string): boolean { const digits = value.replaceAll(/\D/g, ''); if (digits.length < 13 || digits.length > 19) return false; let sum = 0; for (let i = digits.length - 1, parity = 0; i >= 0; i--, parity++) { let n = Number(digits[i]); if (parity % 2 === 1) { n *= 2; if (n > 9) n -= 9 } sum += n } return sum % 10 === 0 }
+const opaqueFieldNames = new Set([
+  'eventId', 'taskId', 'contextRef', 'actionId', 'hotelRef', 'offerRef', 'offerVersionRef', 'checkedOfferVersionRef', 'currentOfferVersionRef', 'verifiedOfferRef',
+  'orderRef', 'searchSessionRef', 'handoffRef', 'questionId', 'blockerId', 'approvalId',
+  'sourceActionId', 'targetActionId', 'sourceTurnId', 'turnId', 'requestKey', 'taskHandle',
+  'nonce', 'deliveryNonce', 'optionDigest', 'sourceReceiptDigest', 'valueDigest',
+])
+function isOpaqueFieldPath(path: string): boolean {
+  const clean = path.replace(/\[\]$/g, '')
+  const field = clean.split('.').at(-1)
+  return field ? opaqueFieldNames.has(field) || field.endsWith('Ref') || field.endsWith('Refs') : false
+}
+const scan = (v: unknown, path = '$'): boolean => typeof v === 'string'
+  ? hasSensitiveText(v, { allowOpaqueNumericId: isOpaqueFieldPath(path) })
+  : Array.isArray(v)
+    ? v.some((child) => scan(child, `${path}[]`))
+    : !!v && typeof v === 'object'
+      ? Object.entries(v).some(([k,x]) => /cost|price/i.test(k) ? /supplier|internal|wholesale/i.test(String(x)) : scan(x, `${path}.${k}`))
+      : false
+export function isSafeBookingRequestKey(value: unknown): value is string { return safeRequestKey(value) }
+export type BookingSurfaceValidationResult = { ok: true } | { ok: false; errors: string[] }
+function errors(v: ValidateFunction): string[] { return (v.errors ?? []).map(e => `${e.instancePath || '$'}: ${e.message ?? e.keyword}`) }
+function workspaceErrors(workspace: Record<string, any> | undefined, path: string): string[] {
+  const e: string[] = []
+  if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace)) return e
+  const loadedOffers = Array.isArray(workspace.loadedOffers) ? workspace.loadedOffers : []
+  const offerRefs = loadedOffers.map((offer: any) => offer?.offerRef).filter((ref: unknown): ref is string => typeof ref === 'string')
+  const offerVersionRefs = loadedOffers.map((offer: any) => offer?.offerVersionRef).filter((ref: unknown): ref is string => typeof ref === 'string')
+  if (new Set(offerRefs).size !== offerRefs.length) e.push(`${path}.loadedOffers: duplicate offerRef`)
+  if (new Set(offerVersionRefs).size !== offerVersionRefs.length) e.push(`${path}.loadedOffers: duplicate offerVersionRef`)
+  const verified = workspace.verifiedOffer
+  if (verified !== undefined) {
+    if (!loadedOffers.some((offer: any) => offer?.offerRef === verified.offerRef && offer?.offerVersionRef === verified.offerVersionRef)) e.push(`${path}.verifiedOffer: loaded offer version required`)
+    if (!safeOpaque(verified.verifiedOfferRef) || !isBookingDateTime(verified.expiresAt)) e.push(`${path}.verifiedOffer: safe ref and parseable expiry required`)
+  }
+  return e
+}
+function cross(value: unknown): string[] {
+  const e: string[] = []
+  if (scan(value)) e.push('$: unsafe PII/payment/supplier-cost/credential text')
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return e
+  const x = value as Record<string, any>
+  const semantic = x.kind === 'action.receipt.continuation' ? x.receipt : x
+  if (x.workspace && x.kind !== 'user.turn.ingress') e.push(...workspaceErrors(x.workspace, '$.workspace'))
+  if (x.schemaVersion === 'booking.surface' && Array.isArray(x.loadedOffers)) e.push(...workspaceErrors(x, '$'))
+  if (x.kind === 'user.turn.ingress') {
+    if (!safeRequestKey(x.requestKey)) e.push('$.requestKey: safe opaque request key required')
+    const workspace = x.workspace as Record<string, any> | undefined
+    e.push(...workspaceErrors(workspace, '$.workspace'))
+    const visibleHotels = Array.isArray(workspace?.visibleHotels) ? workspace.visibleHotels : []
+    const loadedOffers = Array.isArray(workspace?.loadedOffers) ? workspace.loadedOffers : []
+    if (workspace?.focusedHotelRef !== undefined && !visibleHotels.some((hotel: any) => hotel?.hotelRef === workspace.focusedHotelRef)) e.push('$.workspace.focusedHotelRef: visible hotel required')
+    const selectedOffer = workspace?.selectedOfferRef === undefined ? undefined : loadedOffers.find((offer: any) => offer?.offerRef === workspace.selectedOfferRef)
+    if (workspace?.selectedOfferRef !== undefined && !selectedOffer) e.push('$.workspace.selectedOfferRef: loaded offer required')
+    if (selectedOffer && !visibleHotels.some((hotel: any) => hotel?.hotelRef === selectedOffer.hotelRef)) e.push('$.workspace.selectedOfferRef: offer hotel must be visible')
+  }
+  if (semantic !== x && semantic?.resultContract?.hardCriteriaMet === true && semantic.resultContract.blockers?.length) e.push('$.receipt.resultContract: hardCriteriaMet cannot coexist with blockers')
+  if (kinds.has(x.kind)) {
+    const allowed: Record<string, string[]> = {
+      'search.patch': ['patch'], 'search.run': [], 'results.view.patch': ['patch'],
+      'hotel.focus': ['hotelRef'], 'hotel.select': ['hotelRef'],
+      'offers.query': ['hotelRefs', 'criteria'], 'offers.view.patch': ['hotelRef', 'criteria'],
+      'offers.compare': ['offerRefs', 'requestedCount'], 'offer.select': ['offerRef', 'offerVersionRef'],
+      'offer.check': ['offerRef', 'offerVersionRef'], 'checkout.prepare': ['offerRef', 'offerVersionRef', 'verifiedOfferRef'], 'order.observe': ['orderRef'],
     }
-  }
-  if (value.kind === 'terminal') {
-    if (!isRecord(value.terminal)) {
-      errors.push('$.terminal: typed object required')
-    } else {
-      exactKeys(value.terminal, ['status', 'summary', 'factRefs'], ['status', 'summary', 'factRefs'], '$.terminal', errors)
-      const statuses = new Set(['completed', 'stopped'])
-      if (typeof value.terminal.status !== 'string' || !statuses.has(value.terminal.status)) errors.push('$.terminal.status: completed or stopped required')
-      if (!isNonEmptyString(value.terminal.summary)) errors.push('$.terminal.summary: non-empty string required')
-      if (!isStringArray(value.terminal.factRefs)) errors.push('$.terminal.factRefs: opaque-ref array required')
+    const input = x.input
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(k => !allowed[x.kind].includes(k))) e.push('$.input: closed kind-specific input required')
+  }
+  if (x.kind === 'action.receipt' && x.resultContract?.hardCriteriaMet === true && x.resultContract.blockers?.length) e.push('$.resultContract: hardCriteriaMet cannot coexist with blockers')
+  if (x.kind === 'user.turn' && Array.isArray(x.request?.approval)) e.push('$.request.approval: at most one approval')
+  if (x.kind === 'action.receipt' || x.kind === 'action.receipt.continuation') {
+    const r = x.kind === 'action.receipt.continuation' ? x.receipt : x
+    if (r?.resultContract?.gapCodes?.some((code: unknown) => !gapCodes.has(String(code)))) e.push('$.resultContract.gapCodes: unregistered gap code')
+    const observation = r?.observation
+    if (observation?.kind === 'offer.availability') {
+      if (r.status === 'applied' && (observation.available !== true || !observation.verifiedOfferRef || observation.currentOfferVersionRef !== observation.checkedOfferVersionRef || observation.changedFactRefs?.length || observation.gapCodes?.length)) e.push('$.observation: applied availability requires unchanged checked/current version, verified ref, and no gaps')
+      if (r.status === 'applied' && (r.resultContract?.outcome !== 'complete' || r.resultContract?.hardCriteriaMet !== true || r.resultContract?.gapCodes?.length || r.resultContract?.blockers?.length)) e.push('$.resultContract: applied availability requires complete hard-criteria result without gaps or blockers')
+      if (r.status === 'changed' && (observation.available !== true || !observation.currentOfferVersionRef || observation.currentOfferVersionRef === observation.checkedOfferVersionRef || !observation.changedFactRefs?.length || observation.verifiedOfferRef)) e.push('$.observation: changed availability requires available replacement current version without verified ref')
+      if ((r.status === 'unavailable' || r.status === 'no_match') && (observation.available !== false || observation.currentOfferVersionRef || observation.verifiedOfferRef)) e.push('$.observation: negative availability must not expose current or verified version')
+      if (r.status !== 'applied' && observation.verifiedOfferRef) e.push('$.observation: only applied availability may expose verified ref')
     }
   }
-  if (value.kind === 'error') {
-    if (!isRecord(value.error)) {
-      errors.push('$.error: typed object required')
-    } else {
-      exactKeys(value.error, ['code', 'message', 'retryable'], ['code', 'message', 'retryable'], '$.error', errors)
-      if (!isNonEmptyString(value.error.code)) errors.push('$.error.code: non-empty string required')
-      if (!isNonEmptyString(value.error.message)) errors.push('$.error.message: non-empty string required')
-      if (typeof value.error.retryable !== 'boolean') errors.push('$.error.retryable: boolean required')
+  const blocker = x.blocker ?? x.question?.blocker
+  if (blocker && !/^(searchDraft|results|offers|checkout)(\.[A-Za-z][A-Za-z0-9_]*){0,3}$/.test(blocker.criterionPath ?? '')) e.push('$.blocker.criterionPath: closed criterion path required')
+  if (blocker?.evidence?.factRefs && new Set(blocker.evidence.factRefs).size !== blocker.evidence.factRefs.length) e.push('$.blocker.evidence.factRefs: unique refs required')
+  if (x.kind === 'question' && blocker && Array.isArray(x.question?.approvalOptions)) {
+    for (const [i, option] of x.question.approvalOptions.entries()) {
+      const result = validateApprovalAgainstBlocker(option?.approval, blocker)
+      if (!result.ok) e.push(...result.errors.map(error => `$.question.approvalOptions[${i}].${error.slice(2)}`))
+      if (option?.approval?.taskId !== x.taskId) e.push(`$.question.approvalOptions[${i}].approval.taskId: must match event`)
+      if (option?.approval?.contextRef !== x.contextRef) e.push(`$.question.approvalOptions[${i}].approval.contextRef: must match event`)
     }
   }
-  return errors.length === 0 ? { ok: true } : { ok: false, errors }
-}
-
-/**
- * The only executable event seam. It performs no text parsing: non-operation
- * events always return null even when their prose happens to look like JSON.
- */
-export function bookingOperationFromEvent(value: unknown): BookingReadActionV1 | null {
-  if (!isRecord(value) || value.kind !== 'operation') return null
-  if (!validateBookingSurfaceEventV1(value).ok) return null
-  return value.action as BookingReadActionV1
+  if (kinds.has(String(x.kind)) && x.relaxationApprovalRef) {
+    const ref = x.relaxationApprovalRef
+    if (ref.contextRef !== x.contextRef) e.push('$.relaxationApprovalRef.contextRef: must match action')
+    if (ref.sourceRevision !== x.expectedRevision) e.push('$.relaxationApprovalRef.sourceRevision: must equal action revision')
+    if (ref.targetActionKind !== x.kind) e.push('$.relaxationApprovalRef.targetActionKind: must match action kind')
+    if (ref.targetActionId !== x.actionId) e.push('$.relaxationApprovalRef.targetActionId: must match action id')
+    // Expiry and one-time consumption are runtime concerns; validation checks only structure/binding.
+    if (!safeOpaque(ref.nonce) || !isBookingDateTime(ref.expiresAt)) e.push('$.relaxationApprovalRef: invalid expiry or nonce')
+  }
+  if (x.kind === 'question' && (!Array.isArray(x.question?.approvalOptions) || x.question.approvalOptions.length < 1 || x.question.approvalOptions.length > 2)) e.push('$.question.approvalOptions: one or two options required')
+  return e
+}
+export function validateBookingSurface(value: unknown): BookingSurfaceValidationResult { const ok = validate(value); const e = ok ? [] : errors(validate); e.push(...cross(value)); return e.length ? { ok: false, errors: e } : { ok: true } }
+function fromCanonical(fn: ValidateFunction, value: unknown): BookingSurfaceValidationResult { const ok = fn(value); const e = ok ? [] : errors(fn); e.push(...cross(value)); return e.length ? { ok: false, errors: e } : { ok: true } }
+export function validateBookingReadAction(value: unknown): BookingSurfaceValidationResult { return fromCanonical(validateActionCanonical, value) }
+export function validateCriterionBlocker(value: unknown): BookingSurfaceValidationResult { return fromCanonical(validateBlockerCanonical, value) }
+export function validateRelaxationApproval(value: unknown): BookingSurfaceValidationResult { return fromCanonical(validateApprovalCanonical, value) }
+export function validateBookingSurfaceEvent(value: unknown): BookingSurfaceValidationResult { return fromCanonical(validateEventCanonical, value) }
+export function validateApprovalAgainstBlocker(approval: unknown, blocker: unknown): BookingSurfaceValidationResult {
+  const a = approval as any
+  const b = blocker as any
+  const blockerResult = validateCriterionBlocker(b)
+  if (!blockerResult.ok) return blockerResult
+  const approvalResult = validateRelaxationApproval(a)
+  if (!approvalResult.ok) return approvalResult
+  const fields = ['blockerId', 'sourceActionId', 'sourceReceiptDigest', 'scope', 'code', 'criterionPath', 'valueDigest']
+  const mismatches = fields.filter(field => a[field] !== b?.[field])
+  return mismatches.length ? { ok: false, errors: mismatches.map(field => `$.${field}: approval does not match blocker`) } : { ok: true }
 }
-
-// Keep the public predicates assignable to their declared wire types.
-void (null as unknown as BookingCopilotIngressTurnV1)
-void (null as unknown as BookingCopilotTurnV1)
-void (null as unknown as BookingReadActionV1)
-void (null as unknown as ActionReceiptV1)
-void (null as unknown as BookingSurfaceEventV1)