@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

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

@@ -0,0 +1,201 @@
+/** Production composition entry for GoTry's BFF-only Booking Copilot server. */
+
+import { mkdirSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { ensureLedger, type StateLedger } from '../state-ledger.ts'
+import {
+  buildDshPlannerEnvironment,
+  createDshEmbeddedBookingPlanner,
+  type DshEmbeddedBookingPlannerHandle,
+  type DshEmbeddedBookingPlannerOptions,
+} from './dsh-planner.ts'
+import { BookingCopilotTaskRuntime } from './runtime.ts'
+import { BOOKING_COPILOT_INGRESS_MODES, type BookingCopilotIngressMode, type BookingIngressBinding, type BookingIngressPrincipal } from './contracts.ts'
+import {
+  startBookingCopilotServer,
+  type BookingCopilotServerHandle,
+  type BookingCopilotServerOptions,
+} from './server.ts'
+
+export interface BookingCopilotStartupConfig {
+  apiKey: string
+  stateRoot: string
+  host: string
+  port: number
+  artifactId?: string
+  /** Planner turn deadline in ms; the planner's own default applies when unset. */
+  plannerTurnTimeoutMs?: number
+  /** Defaults to bound-turn-only; a complete injected seam enables ingress. */
+  ingressMode: BookingCopilotIngressMode
+}
+
+export interface BookingCopilotStartupHandle {
+  port: number
+  close(): Promise<void>
+}
+
+export interface BookingCopilotStartupDependencies {
+  ensureLedger(stateRoot: string): StateLedger
+  runtimeFactory(ledger: StateLedger): BookingCopilotTaskRuntime
+  createPlanner(options: DshEmbeddedBookingPlannerOptions): Promise<DshEmbeddedBookingPlannerHandle>
+  /** Optional in-process BFF identity seam; standalone use is bound-turn-only. */
+  ingressBinding?: BookingIngressBinding
+  principal?: BookingIngressPrincipal
+  startServer(options: BookingCopilotServerOptions): Promise<BookingCopilotServerHandle>
+}
+
+const DEFAULT_DEPENDENCIES: BookingCopilotStartupDependencies = {
+  ensureLedger,
+  runtimeFactory: (ledger) => new BookingCopilotTaskRuntime(ledger),
+  createPlanner: createDshEmbeddedBookingPlanner,
+  startServer: startBookingCopilotServer,
+}
+
+function parsePort(raw: string | undefined): number {
+  if (raw === undefined || raw === '') return 3_082
+  const value = Number(raw)
+  if (!Number.isSafeInteger(value) || value < 0 || value > 65_535) throw new Error('booking_copilot_invalid_port')
+  return value
+}
+
+/** Operator-tunable planner deadline; the bounds mirror the planner's own validation. */
+function parsePlannerTurnTimeout(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw.trim() === '') return undefined
+  const value = Number(raw)
+  if (!Number.isSafeInteger(value) || value < 1 || value > 120_000) {
+    throw new Error('booking_copilot_planner_timeout_invalid')
+  }
+  return value
+}
+
+export function resolveBookingCopilotStartupConfig(
+  env: Record<string, string | undefined> = process.env,
+): BookingCopilotStartupConfig {
+  const apiKey = env.GOTRY_BOOKING_COPILOT_API_KEY ?? ''
+  if (!apiKey) throw new Error('booking_copilot_api_key_required')
+  const stateRoot = env.GOTRY_BOOKING_COPILOT_STATE_ROOT ?? ''
+  if (!stateRoot) throw new Error('booking_copilot_state_root_required')
+  if (!isAbsolute(stateRoot)) throw new Error('booking_copilot_state_root_must_be_absolute')
+  const artifactId = env.GOTRY_BOOKING_COPILOT_ARTIFACT_ID || undefined
+  if (artifactId !== undefined && !/^[0-9a-f]{40}$/.test(artifactId)) {
+    throw new Error('booking_copilot_artifact_id_invalid')
+  }
+  const rawIngressMode = env.GOTRY_BOOKING_COPILOT_INGRESS_MODE
+  const ingressMode = rawIngressMode === undefined || rawIngressMode === '' ? 'bff-bound-turn-only' : rawIngressMode
+  if (!(BOOKING_COPILOT_INGRESS_MODES as readonly string[]).includes(ingressMode)) {
+    throw new Error('booking_copilot_ingress_mode_invalid')
+  }
+  return {
+    apiKey,
+    stateRoot,
+    host: env.GOTRY_BOOKING_COPILOT_HOST || '127.0.0.1',
+    port: parsePort(env.GOTRY_BOOKING_COPILOT_PORT),
+    artifactId,
+    plannerTurnTimeoutMs: parsePlannerTurnTimeout(env.GOTRY_BOOKING_COPILOT_PLANNER_TIMEOUT_MS),
+    ingressMode: ingressMode as BookingCopilotIngressMode,
+  }
+}
+
+async function closeAll(
+  server: BookingCopilotServerHandle | undefined,
+  planner: DshEmbeddedBookingPlannerHandle | undefined,
+  ledger: StateLedger | undefined,
+): Promise<void> {
+  const failures: unknown[] = []
+  for (const close of [
+    server ? () => server.close() : undefined,
+    planner ? () => planner.close() : undefined,
+    ledger ? () => Promise.resolve(ledger.close()) : undefined,
+  ]) {
+    if (!close) continue
+    try { await close() } catch (error) { failures.push(error) }
+  }
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) throw new AggregateError(failures, 'booking_copilot_shutdown_failed')
+}
+
+/**
+ * Boot one process-scoped dsh core and task-scoped sessions behind the typed
+ * HTTP/SSE server. Only the HTTP layer receives the BFF deployment key.
+ */
+export async function startBookingCopilotFromEnvironment(
+  env: Record<string, string | undefined> = process.env,
+  dependencies: BookingCopilotStartupDependencies = DEFAULT_DEPENDENCIES,
+): Promise<BookingCopilotStartupHandle> {
+  const config = resolveBookingCopilotStartupConfig(env)
+  const activeDependencies = dependencies
+  const hasIngressBinding = Boolean(activeDependencies.ingressBinding)
+  const hasPrincipal = Boolean(activeDependencies.principal)
+  if (hasIngressBinding !== hasPrincipal) throw new Error('booking_copilot_ingress_binding_pair_required')
+  const ingressPair = hasIngressBinding && hasPrincipal
+  if (ingressPair && env.GOTRY_BOOKING_COPILOT_INGRESS_MODE !== undefined && config.ingressMode === 'bff-bound-turn-only') {
+    throw new Error('booking_copilot_ingress_mode_conflict')
+  }
+  if (!ingressPair && config.ingressMode === 'bff-ingress-binding') throw new Error('booking_copilot_ingress_binding_required')
+  if (ingressPair && (typeof activeDependencies.ingressBinding?.bind !== 'function'
+    || typeof activeDependencies.principal?.subject !== 'string' || activeDependencies.principal.subject.length === 0 || activeDependencies.principal.subject.length > 256
+    || typeof activeDependencies.principal?.scope !== 'string' || activeDependencies.principal.scope.length === 0 || activeDependencies.principal.scope.length > 256)) {
+    throw new Error('booking_copilot_ingress_binding_invalid')
+  }
+  const activeIngressMode: BookingCopilotIngressMode = ingressPair ? 'bff-ingress-binding' : 'bff-bound-turn-only'
+  mkdirSync(config.stateRoot, { recursive: true })
+  let ledger: StateLedger | undefined
+  let planner: DshEmbeddedBookingPlannerHandle | undefined
+  let server: BookingCopilotServerHandle | undefined
+  try {
+    ledger = dependencies.ensureLedger(config.stateRoot)
+    const plannerOptions = {
+      stateRoot: config.stateRoot,
+      env: buildDshPlannerEnvironment(env),
+      ...(config.plannerTurnTimeoutMs === undefined ? {} : { turnTimeoutMs: config.plannerTurnTimeoutMs }),
+    }
+    const runtime = activeDependencies.runtimeFactory(ledger)
+    planner = await activeDependencies.createPlanner(plannerOptions)
+    server = await activeDependencies.startServer({
+      apiKey: config.apiKey, runtime, plannerFactory: planner.plannerFactory,
+      ...(ingressPair ? { ingressBinding: activeDependencies.ingressBinding, principal: activeDependencies.principal } : {}),
+      ingressMode: activeIngressMode,
+      host: config.host, port: config.port, artifactId: config.artifactId,
+    })
+  } catch (error) {
+    try { await closeAll(server, planner, ledger) } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'booking_copilot_startup_and_cleanup_failed')
+    }
+    throw error
+  }
+
+  let closed = false
+  return {
+    port: server.port,
+    async close() {
+      if (closed) return
+      closed = true
+      await closeAll(server, planner, ledger)
+    },
+  }
+}
+
+async function runCli(): Promise<void> {
+  const handle = await startBookingCopilotFromEnvironment()
+  process.stderr.write(`[gotry-booking-copilot] listening on http://127.0.0.1:${handle.port}/a2a/booking-copilot/turn\n`)
+  let stopping = false
+  const stop = () => {
+    if (stopping) return
+    stopping = true
+    void handle.close().then(() => process.exit(0), (error) => {
+      process.stderr.write(`[gotry-booking-copilot] shutdown failed: ${error instanceof Error ? error.message : String(error)}\n`)
+      process.exit(1)
+    })
+  }
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : ''
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`[gotry-booking-copilot] startup failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  })
+}

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

@@ -0,0 +1,217 @@
+import { readFileSync } from 'node:fs'
+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 intentSchema = JSON.parse(readFileSync(new URL('../../../schemas/booking.intent.schema.json', import.meta.url), 'utf8')) as Record<string, unknown>
+/** Canonical schema bytes (single source of truth) for prompt/tool derivations elsewhere. */
+export const bookingSurfaceSchema = schema
+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 validateIntentCanonical = ajv.compile(intentSchema)
+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
+    }
+    if (/^[1-9]\d{7,14}$/.test(digits)) return true
+  }
+  return false
+}
+
+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 shortlisted = Array.isArray(workspace.shortlistedOfferRefs) ? workspace.shortlistedOfferRefs : []
+  if (shortlisted.some((ref: unknown) => typeof ref !== 'string' || !loadedOffers.some((offer: any) => offer?.offerRef === ref))) {
+    e.push(`${path}.shortlistedOfferRefs: every ref must be a loaded offer`)
+  }
+  if (workspace.selectedOfferRef !== undefined && !loadedOffers.some((offer: any) => offer?.offerRef === workspace.selectedOfferRef)) {
+    e.push(`${path}.selectedOfferRef: loaded offer required`)
+  }
+  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'],
+    }
+    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')
+    }
+  }
+  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`)
+    }
+  }
+  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 validateBookingIntentProjection(value: unknown): BookingSurfaceValidationResult { return fromCanonical(validateIntentCanonical, 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 }
+}

package/ts/src/companions.ts

@@ -0,0 +1,113 @@
+/**
+ * 同行人档案(memory-design M5 层,P2):同行人及其约束(行动/健康/偏好)的持久化。
+ *
+ * 立场(memory-design §1):
+ *  - 溯源 P0:每条约束伴 evidence(用户原话),追加不删史;
+ *  - 约束只进排序与行程结构建议,永不进硬过滤;
+ *  - **负面清单守卫**:证件号/电话/地址等敏感字段拒收入库(需要时后端从登录态
+ *    填充,fail-closed)——health 存的是「高血压/晕车」这类行为约束,不是病历;
+ *  - upsert 合并语义同 mergeProfile:追加不删史/同内容幂等。
+ */
+
+export interface CompanionConstraints {
+  /** 行动/体力:如「走不了一段」「坐轮椅」 */
+  mobility?: string
+  /** 健康类行为约束:如「轻度高血压」「晕车」(非病历,禁止诊断性描述) */
+  health?: string[]
+  /** 偏好:如「怕吵」「爱吃辣」 */
+  prefs?: string[]
+}
+
+export interface CompanionProfile {
+  schema: 'companion_profile.v1'
+  /** 稳定主键:label 语义派生(去空白) */
+  companion_id: string
+  label: string
+  constraints: CompanionConstraints
+  /** 用户原话,追加不删史 */
+  evidence: string[]
+  ts: string
+}
+
+/** 负面清单:命中即拒收(红线 6 + 隐私立场) */
+const SENSITIVE_PATTERNS: Array<{ re: RegExp; label: string }> = [
+  { re: /\d{15,17}[Xx]?/, label: '疑似证件号/卡号' },
+  { re: /1[3-9]\d{9}/, label: '疑似手机号' },
+  { re: /(护照|身份证|证件号|通行证)\s*号?\s*[:：]?\s*\w+/i, label: '证件信息' },
+]
+
+/** 守门:内容命中负面清单 → 返回拒收理由;否则 null */
+export function sensitiveViolation(text: string): string | null {
+  for (const { re, label } of SENSITIVE_PATTERNS) {
+    if (re.test(text)) return `负面清单拒收:${label}不入库(需要时由后端从登录态填充)`
+  }
+  return null
+}
+
+/** 稳定主键:label 去空白 */
+export function companionId(label: string): string {
+  return label.replace(/\s+/g, '')
+}
+
+function mergeStrArray(oldArr: string[] | undefined, newArr: string[] | undefined): { merged: string[]; added: boolean } {
+  const a = oldArr ?? []
+  let added = false
+  for (const x of newArr ?? []) {
+    if (!a.includes(x)) {
+      a.push(x)
+      added = true
+    }
+  }
+  return { merged: a, added }
+}
+
+/**
+ * upsert 合并(纯函数,不改入参):同 companion_id 按 label 归并——
+ * constraints 逐字段取新值(新值覆盖旧行为约束,追加数组项),evidence 追加不删史,
+ * 全量无新增 → 幂等 no-op(appended:false)。
+ */
+export function upsertCompanion(
+  profiles: CompanionProfile[],
+  patch: { label: string; constraints: CompanionConstraints; evidence: string },
+): { profiles: CompanionProfile[]; appended: boolean; companionId: string; reason?: string } {
+  if (!patch.label?.trim()) return { profiles, appended: false, companionId: '', reason: 'label 必填' }
+  const violation = sensitiveViolation(JSON.stringify(patch))
+  if (violation) return { profiles, appended: false, companionId: '', reason: violation }
+  const id = companionId(patch.label)
+  const existing = profiles.find(p => p.companion_id === id)
+  if (!existing) {
+    const full: CompanionProfile = {
+      schema: 'companion_profile.v1',
+      companion_id: id,
+      label: patch.label.trim(),
+      constraints: {
+        mobility: patch.constraints.mobility,
+        health: patch.constraints.health ? [...patch.constraints.health] : undefined,
+        prefs: patch.constraints.prefs ? [...patch.constraints.prefs] : undefined,
+      },
+      evidence: [patch.evidence],
+      ts: new Date().toISOString(),
+    }
+    return { profiles: [...profiles, full], appended: true, companionId: id }
+  }
+  const mergedConstraints: CompanionConstraints = {
+    mobility: patch.constraints.mobility ?? existing.constraints.mobility,
+    health: mergeStrArray(existing.constraints.health, patch.constraints.health).merged,
+    prefs: mergeStrArray(existing.constraints.prefs, patch.constraints.prefs).merged,
+  }
+  const ev = mergeStrArray(existing.evidence, [patch.evidence])
+  const healthLen = mergedConstraints.health?.length ?? 0
+  const prefsLen = mergedConstraints.prefs?.length ?? 0
+  const changed =
+    mergedConstraints.mobility !== existing.constraints.mobility ||
+    healthLen !== (existing.constraints.health?.length ?? 0) ||
+    prefsLen !== (existing.constraints.prefs?.length ?? 0) ||
+    ev.added
+  if (!changed) return { profiles, appended: false, companionId: id }
+  const next = profiles.map(p =>
+    p.companion_id === id
+      ? { ...p, constraints: mergedConstraints, evidence: ev.merged, ts: new Date().toISOString() }
+      : p,
+  )
+  return { profiles: next, appended: true, companionId: id }
+}

package/ts/src/contracts.ts

@@ -1,5 +1,5 @@
 /**
- * Stage 1 契约层(S1,docs/stage1-top-down-design.md §2)——顶层数据与工具面契约。
+ * Stage 1 契约层(S1,docs/design/stage1-top-down-design.md §2)——顶层数据与工具面契约。
  *
  * 自顶向下纪律:本文件是唯一权威契约。实现(mock 循环/求解器挂载/真 LLM)都向这里对齐;
  * 契约变更需走设计文档升版,不随实现漂移。
@@ -16,8 +16,10 @@ export interface CalendarState {
   assertedWeekdays: Record<string, 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun'>
 }
 
-export interface WorkWindowProfile {
-  homeTzOffsetMin: number
+export interface ScheduledWorkWindowProfile {
+  /** Legacy v1 only; v2 pack metadata owns the IANA home zone. */
+  homeTzOffsetMin?: number
+  vacation?: false
   startMin: number
   endMin: number
   workdays: number[]
@@ -25,6 +27,14 @@ export interface WorkWindowProfile {
   evidence: string
 }
 
+/** Explicit leave means this trip has no work-time restriction. */
+export interface VacationWorkWindowProfile {
+  vacation: true
+  evidence?: string
+}
+
+export type WorkWindowProfile = ScheduledWorkWindowProfile | VacationWorkWindowProfile
+
 export interface TravelerProfile {
   workWindow?: WorkWindowProfile
   companions?: string[]