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

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

@@ -0,0 +1,453 @@
+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
+    }
+    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
+  }
+  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 }
+}
+
+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')
+    }
+  }
+  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')
+    }
+  }
+  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')
+    }
+  }
+  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
+}
+
+// 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)

package/ts/src/index.ts

@@ -7,7 +7,7 @@
  *   - gotry_wish_pool_add       「下一次出发」清单(憧憬不被拒绝)
  *
  * 插件形态遵循 dsh 约定(name/inject/Config/apply + ctx.tools.register(defineTool(...))),
- * 对齐已发布 @deepseek-ai/dsh-tools@0.0.1-rc.1 的契约:
+ * 对齐 @deepseek-ai/dsh-tools@0.1.2-alpha.3 的契约:
  * render 位于 output 对象内,参数属性是 ValueSchemaSpec(支持 type:'json')。
  *
  * @module @gotry/plugin
@@ -35,12 +35,18 @@ import { anythingSearch } from '../capabilities/anything.ts'
 import { readUrl, reach, reachStatus } from '../capabilities/agent-reach.ts'
 import { videoSubtitle, githubSearch } from '../capabilities/agent-reach-deep.ts'
 import { sessionLogin } from '../capabilities/session-login.ts'
+import { EXTENSION_STORE_URL } from '../capabilities/session/extension-bridge.ts'
 import { createConsentGate, approvalFromContext } from '../capabilities/session-consent.ts'
+import { installModelOverride } from '../capabilities/model-override.ts'
 import { listArtifacts, readArtifact } from '../capabilities/artifacts.ts'
 import { interpretEffect, declinedObservation } from '../capabilities/effect.ts'
 import { appendFacts, loadFactRegistry } from '../capabilities/fact-log.ts'
 import { factsFromFlyai, factsFromSession } from './bookable-facts.ts'
 import { gateArtifact, type AirlineAirportMap } from './artifact-gate.ts'
+import { installToolBudget } from './tool-budget.ts'
+import { registerBenchmarkEnvironmentBridge, type BenchmarkSubprocessService } from './benchmark-environment-bridge.ts'
+import { installBenchmarkToolIsolation } from './benchmark-tool-isolation.ts'
+import { installBenchmarkAgentConformance } from './benchmark-agent-conformance.ts'
 
 /** 航司→机场映射表(issue #46 冲突检测面;data/airline-airports.json,as_of 快照) */
 let airlineAirportMapCache: AirlineAirportMap | null = null
@@ -58,6 +64,9 @@ async function loadAirlineAirportMap(): Promise<AirlineAirportMap | null> {
 }
 
 export const name = 'gotry-tools'
+// The bridge obtains subprocess through an optional Cordis lookup at apply
+// time. Declaring it as a required injection would make the whole plugin
+// depend on a service that is only needed for explicit benchmark opt-in.
 export const inject = ['tools', 'systemPrompt']
 
 export interface Config {
@@ -69,6 +78,8 @@ export interface Config {
   hbcliBin: string
   /** 账号会话检索总闸(RFC 支柱④「用户明示授权+随时可关」):ask=gotry_session_search 每会话每站点首次调用弹审批卡、会话内记住(默认);allow=用户已在配置明示预授权(直接放行);off=总闸关闭,直接拒绝 */
   sessionAccess: string
+  /** Owner-local benchmark environment bridge config; empty disables the bridge. */
+  benchmarkEnvironmentConfigPath?: string
 }
 
 export const Config: z<Config> = z.object({
@@ -76,6 +87,7 @@ export const Config: z<Config> = z.object({
   timeoutMs: z.number().default(30_000),
   hbcliBin: z.string().default('hbcli'),
   sessionAccess: z.string().default('ask'),
+  benchmarkEnvironmentConfigPath: z.string().default(''),
 })
 
 interface FeasibilityResult {
@@ -152,6 +164,29 @@ type Json = string | number | boolean | null | Json[] | { [k: string]: Json }
 type JsonObject = { [k: string]: Json }
 
 export function apply(ctx: Context, config: Config): void {
+  installToolBudget(ctx)
+
+  const rawBenchmarkEnvironmentConfigPath = config.benchmarkEnvironmentConfigPath ?? ''
+  if (rawBenchmarkEnvironmentConfigPath.trim()) {
+    // Benchmark mode is a deliberately minimal kernel: only the model
+    // override and the environment bridge are installed.  In particular,
+    // product prompt variables, process/consent guards, and guarded product
+    // tools must not be observable on this path.
+    installModelOverride(ctx as unknown as Parameters<typeof installModelOverride>[0])
+    const getService = (ctx as unknown as { get?: (name: string, fallback?: unknown) => unknown }).get
+    const directSubprocess = (typeof getService === 'function'
+      ? getService.call(ctx, 'subprocess')
+      : undefined) as BenchmarkSubprocessService | undefined
+    const projection = registerBenchmarkEnvironmentBridge(
+      rawBenchmarkEnvironmentConfigPath,
+      tool => ctx.tools.register(tool),
+      directSubprocess,
+    )
+    installBenchmarkToolIsolation(ctx)
+    installBenchmarkAgentConformance(ctx, projection)
+    return
+  }
+
   // 时间感知:注册动态变量,persona 里用 {{current_date}} 引用。
   // 每次 assemble 时取系统时钟——LLM 始终知道「今天是几号」。
   const sp = (ctx as unknown as Record<string, unknown>)['systemPrompt'] as {
@@ -193,6 +228,10 @@ export function apply(ctx: Context, config: Config): void {
     }))
   }
 
+  // LLM_MODEL → dsh 会话面模型覆盖(issue #77;机制与分层见
+  // capabilities/model-override.ts 头注)。GOTRY_LLM_MODEL 未设时零行为变化。
+  installModelOverride(ctx as unknown as Parameters<typeof installModelOverride>[0])
+
   // D-NEW 收尾:全部工具 execute 统一异常隔离——单个工具抛错/拒绝不再沿 cordis
   // 传到 dsh 主循环,降级为结构化错误返回给 LLM + incident 落盘(incident-log.ts)。
   const registerGuarded = (tool: ReturnType<typeof defineTool>): void => {
@@ -786,7 +825,7 @@ export function apply(ctx: Context, config: Config): void {
       + 'OPENS the site login entry in the USER\'S OWN Chrome (foreground tab, left open for the user) and waits for the user to finish logging in on the external site. '
       + 'GoTry NEVER collects, stores, or transmits credentials: no passwords, no SMS codes, no cookie values — it only checks the boolean fact "already logged in" (reads cookie NAMES only, zero values). '
       + 'Transport: the GoTry Session Bridge browser extension (one-time install, ZERO Chrome system dialogs). '
-      + 'verdict logged-in (tickets detected) | pending (login tab opened, user not done yet — offer to re-check later) | needs-extension (one-time extension install: npx gotry setup, then chrome://extensions → load unpacked ~/.gotry/extension). '
+      + `verdict logged-in (tickets detected) | pending (login tab opened, user not done yet — offer to re-check later) | needs-extension (one-time extension install: the verdict surfaces the Chrome Web Store installUrl as a clickable link for dsh UI to render — installation is a browser concern, not gotry's). `
       + 'Evidence [会话:<site>-login@ts].',
     parameters: {
       query: { type: 'json', required: true, description: '可空对象 {}: { waitSeconds?: number }(等待用户完成登录的上限秒数,默认 90,至多 300)' },
@@ -800,7 +839,7 @@ export function apply(ctx: Context, config: Config): void {
         : r.verdict === 'pending'
           ? `登录入口已在你的 Chrome 打开;请在弹出的标签页里正常登录携程(登录由你在官网完成,不属于 gotry)。完成后说一声"继续",我再确认。gotry 只检查"是否已登录",永不收集你的账号信息。${r.evidence}`
           : r.verdict === 'needs-extension'
-            ? `需要一次性安装 GoTry Session Bridge 浏览器扩展(约 30 秒,装完零弹窗):跑 npx gotry setup 拿安装指引,在 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension,装好后说一声"重试"。${r.evidence}`
+            ? `需要一次性安装 GoTry Session Bridge 浏览器扩展:这是浏览器的事,gotry 不弹面板不开剪贴板——请直接在 Chrome 应用商店一键装(add-to-chrome 自动更新)。storeUrl=${EXTENSION_STORE_URL}. 装好即生效,装完后告诉我「重试」即可。${r.evidence}`
             : r.verdict === 'needs-attach'
               ? `cdp 车道需要一次性开启你 Chrome 的远程调试开关:在你的 Chrome 地址栏打开 chrome://inspect/#remote-debugging 并打开开关,然后说一声"重试"(默认走扩展车道,无需此步)。${r.evidence}`
               : `登录引导未完成:${r.error ?? '未知原因'} ${r.evidence}`
@@ -808,9 +847,20 @@ export function apply(ctx: Context, config: Config): void {
     },
     presentCall: _args => ({ card: 'generic', title: '登录携程(用你自己的浏览器,不在 gotry 输入)', kind: 'fetch', rawInput: {} }),
     presentResult: (_args, value) => {
-      const r = value as { verdict?: string; tickets?: string[] }
-      const label = r.verdict === 'logged-in' ? `已登录(${(r.tickets ?? []).length} 票据)` : r.verdict === 'pending' ? '等待你在携程页面完成登录' : r.verdict ?? '降级'
-      return { card: 'generic', title: `账号登录:${label}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
+      const r = value as { verdict?: string; tickets?: string[]; installUrl?: string }
+      const needsExt = r.verdict === 'needs-extension'
+      const label = r.verdict === 'logged-in'
+        ? `已登录(${(r.tickets ?? []).length} 票据)`
+        : r.verdict === 'pending'
+          ? '等待你在携程页面完成登录'
+          : needsExt
+            ? '🧩 需装 GoTry Session Bridge 扩展(浏览器商店一键装,自动更新)'
+            : r.verdict ?? '降级'
+      const content: Array<{ type: 'text'; text: string }> = [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }]
+      // needs-extension:把商店 URL 渲成可点链接(浏览器自己当安装器,gotry 不插手)
+      // dsh presentResult 若支持 actions 字段,URL 可被原生渲染;否则 content 里也保留文本兜底
+      if (needsExt && r.installUrl) content.push({ type: 'text', text: `安装链接:${r.installUrl}` })
+      return { card: 'generic', title: `账号登录:${label}`, content }
     },
   }))
 
@@ -822,7 +872,7 @@ export function apply(ctx: Context, config: Config): void {
       + 'Transport: GoTry Session Bridge browser extension (one-time install) — the agent side never talks to Chrome debugging, ZERO system dialogs; read-only by construction (the extension never issues requests; it only passively forwards the site\'s own search responses; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
       + 'Currently ctrip-flight: sniffs the site search API for structured options. Evidence [会话:ctrip-flight@ts]. '
       + 'verdict needs-login = call gotry_session_login (opens the Ctrip login entry in the user\'s own foreground tab — no terminal, no credentials through GoTry); '
-      + 'needs-extension = one-time browser-extension install (npx gotry setup for instructions) — the DEFAULT transport; cdp (chrome://inspect remote debugging) is a diagnostic fallback only via GOTRY_SESSION_TRANSPORT=cdp. '
+      + `needs-extension = one-time browser-extension install (Chrome Web Store one-click, installUrl is also surfaced as a clickable link in the verdict field for dsh UI to render) — the DEFAULT transport; cdp (chrome://inspect remote debugging) is a diagnostic fallback only via GOTRY_SESSION_TRANSPORT=cdp. `
       + 'Rate-limited (≥30s between same-site calls; a challenged/timeout verdict means STOP — never retry, fall back to other tools).',
     parameters: {
       query: { type: 'json', required: true, description: '{ from: "上海", to: "丽江", date: "2026-10-01" }' },
@@ -856,15 +906,18 @@ export function apply(ctx: Context, config: Config): void {
     },
     presentCall: args => ({ card: 'generic', title: `会话检索:${String((args.query as { from?: string })?.from ?? '')}`, kind: 'fetch', rawInput: args.query }),
     presentResult: (_args, value) => {
-      const r = value as { verdict?: string; options?: unknown[] }
+      const r = value as { verdict?: string; options?: unknown[]; installUrl?: string }
+      const needsExt = r.verdict === 'needs-extension'
       const label = r.verdict === 'hit'
         ? `会话 ${r.options!.length} 条`
         : r.verdict === 'needs-login'
           ? '需登录'
-          : r.verdict === 'needs-extension'
-            ? '需装扩展(一次性)'
+          : needsExt
+            ? '🧩 需装 GoTry Session Bridge 扩展(浏览器商店一键装,自动更新)'
             : r.verdict ?? '降级'
-      return { card: 'generic', title: `会话检索:${label}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
+      const content: Array<{ type: 'text'; text: string }> = [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }]
+      if (needsExt && r.installUrl) content.push({ type: 'text', text: `安装链接:${r.installUrl}` })
+      return { card: 'generic', title: `会话检索:${label}`, content }
     },
   }))
 

package/ts/src/state-ledger.ts

@@ -681,6 +681,7 @@ export class StateLedger {
 
   close(): void {
     this.db.close()
+    for (const [key, value] of openLedgers) if (value === this) openLedgers.delete(key)
   }
 }