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

package/ts/src/bookable-facts.ts

@@ -0,0 +1,837 @@
+/**
+ * 可下单事实模型 gotry_bookable_fact.v1(issue #46,ADR-19)。
+ *
+ * 问题(2026-08-29 实测会话):exact-date 工具全部 miss 后,LLM 用航线页当日班期
+ * (2026 快照)填充 2027 行程,航班号/时刻/机场/价格以「✓/推荐」确定性语气手写进
+ * 产物——「错误但看起来已验证」比 unknown 更危险。
+ *
+ * 本层职责(纯函数,零 I/O——持久化见 capabilities/fact-log.ts):
+ *   1. 结构化事实 schema:route/exact local date/时刻/航班号/营销与实际承运(分开)/
+ *      机场/直飞或中转/价格/币种/source/query_id/fetched_at/as_of/confidence/bookability;
+ *   2. 证据分层永不合并:live_inventory(exact-date 命中)/ route_exists(只验证航线)/
+ *      historical_schedule(旧航季)/ benchmark_price(历史促销价)——miss 落「负事实」,
+ *      exact-date 无库存 ≠ 可用历史填充;
+ *   3. 判定原语:航班 claim 可述性(fail closed)/ 同日衔接硬约束 / 行程统计不变量
+ *      (酒店夜+机上夜/O&D 段数/flight legs/预算自洽)/ 回头路检测;
+ *   4. 确定性渲染:航班行/政策行只从结构化对象生成,政策恒带 as_of + 复核日期,
+ *      分票永不称「联程」(protected_connection=true 才允许)。
+ *
+ * 渲染闸(从 markdown 反向核验)在 artifact-gate.ts。
+ */
+
+import { createHash } from 'node:crypto'
+import { hasRecognizedAvailableSeat, validateTrainQueryResponseUrl, type SessionTrainOption } from '../capabilities/session/adapters/rail-12306.ts'
+
+export const BOOKABLE_FACT_SCHEMA = 'gotry_bookable_fact.v1' as const
+
+/** 证据分层:四层永不合并(issue #46 根因②——skeleton/historical/live 被混写) */
+export type EvidenceTier =
+  | 'live_inventory'      // exact-date 实时库存命中(唯一可下单层)
+  | 'route_exists'        // 只验证了「航线存在」(骨架/航线页),不得升级为「该日期有该航班」
+  | 'historical_schedule' // 历史/旧航季班期,只作参考叙述
+  | 'benchmark_price'     // 历史促销价,只作 benchmark,不进预算下限
+
+/** 可下单状态:fail-closed 四态 */
+export type Bookability =
+  | 'bookable_exact_date'      // exact-date 源返回,可下单
+  | 'unavailable_exact_date'   // exact-date 源正常返回 0 条(负事实)
+  | 'unverified'               // 未经 exact-date 核验
+  | 'conflict'                 // 两源冲突,不得给 ✓
+
+export interface FlightFact {
+  schema: typeof BOOKABLE_FACT_SCHEMA
+  /** 语义派生 id:sha(route|date|flight_no|query_id)——同查询重放幂等 */
+  fact_id: string
+  kind: 'flight' | 'train'
+  route: { origin: string; destination: string; origin_airport?: string; dest_airport?: string }
+  /** 出发地当地日期 YYYY-MM-DD(exact local date) */
+  date: string
+  /** 营销航班号(如 CZ8582);负事实为空串 */
+  flight_no: string
+  /** 营销承运与实际承运分开保存(codeshare 必须两者同输出) */
+  marketing_carrier?: string
+  operating_carrier?: string
+  dep_local?: string // HH:MM
+  arr_local?: string // HH:MM
+  nonstop?: boolean
+  price?: number
+  currency?: string
+  baggage_included?: boolean
+  /** 仅当同票联程(同一票号/行李直挂/误机保护)为 true;两段接得上 ≠ 联程 */
+  protected_connection?: boolean
+  tier: EvidenceTier
+  bookability: Bookability
+  /** 数据源标识(flyai / session:ctrip-flight / …) */
+  source: string
+  /** 可重放查询 id(如 flyai:flight:HKG-HKT:2027-07-17) */
+  query_id: string
+  /** 取数时刻 ISO */
+  fetched_at: string
+  /** 数据快照日(证据 as_of) */
+  as_of: string
+  /** 下次复核截止(远期班期/政策必带) */
+  review_by?: string
+}
+
+/** 动态政策事实:签证/免签/入境申报只允许「截至 as_of 的现行政策」表述 */
+export interface PolicyFact {
+  schema: typeof BOOKABLE_FACT_SCHEMA
+  fact_id: string
+  kind: 'policy'
+  /** 政策对象(如 泰国免签 / 迪拜入境) */
+  subject: string
+  /** 政策内容陈述(不带时间无条件断言) */
+  statement: string
+  source: string
+  query_id: string
+  fetched_at: string
+  as_of: string
+  /** 复核 gate(通常 D-30/D-7) */
+  review_by?: string
+}
+
+export type BookableFact = FlightFact | PolicyFact | HotelFact
+
+/**
+ * 酒店事实(D-26,issue #118):exact-date 酒店检索(hit/miss)的唯一事实形态。
+ * 纪律与机/火同源:①未定档期的摸底检索不落账(无 exact-date 语义);
+ * ②needs-setup/error 是传输失败,永不落负事实;③价格上游打码(¥7xx)——
+ * 本事实**不落数字价**,只记在架家数,真实价以落地页为准(打码价保真纪律)。
+ */
+export interface HotelFact {
+  schema: typeof BOOKABLE_FACT_SCHEMA
+  /** 语义派生 id:sha(destination|checkIn|checkOut|query_id)——同查询重放幂等 */
+  fact_id: string
+  kind: 'hotel'
+  /** 目的地中文(flyai/session 的 to;闸侧 claim 匹配键) */
+  destination: string
+  check_in?: string   // YYYY-MM-DD
+  check_out?: string  // YYYY-MM-DD
+  verdict: 'hit' | 'miss'
+  bookability: Bookability
+  /** 在架条数(hit 时;价格打码不落数字价) */
+  options_masked: number
+  source: string      // flyai-hotel / session:ctrip-hotel
+  /** 可重放查询 id(如 flyai:hotel:大理:2026-10-01_2026-10-03) */
+  query_id: string
+  fetched_at: string
+  as_of: string
+  tier: EvidenceTier
+}
+
+// ---------------------------------------------------------------------------
+// id 与查询词(可重放:query_id 即重放凭证)
+// ---------------------------------------------------------------------------
+
+function sha16(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16)
+}
+
+export function makeQueryId(source: string, kind: string, origin: string, destination: string, date: string): string {
+  return `${source}:${kind}:${origin}-${destination}:${date}`
+}
+
+export function makeFactId(parts: Array<string | undefined>): string {
+  return sha16(parts.map(p => p ?? '').join('|'))
+}
+
+/** 城市→IATA 词表(data/airline-airports.json city_alias);转换时把 route 归一到 IATA 空间 */
+export type CityAlias = Record<string, string>
+
+function iataOf(alias: CityAlias | undefined, city: string): string {
+  return alias?.[city] ?? city
+}
+
+// ---------------------------------------------------------------------------
+// 工具结果 → 事实(转换器):hit 落正事实,miss 落负事实,error 不落(无结论)
+// ---------------------------------------------------------------------------
+
+/** flyai 机/火结果形状(capabilities/flyai.ts FlyaiOption 的输入侧最小面) */
+export interface FlyaiLikeOption {
+  no?: string
+  name?: string
+  depDateTime?: string
+  arrDateTime?: string
+  depStation?: string
+  arrStation?: string
+  price?: number
+  priceRaw?: string
+  /** 直达/中转;缺省视为直达(单段条目),中转条目必须显式 false */
+  nonstop?: boolean
+}
+
+export interface FlyaiLikeResult {
+  /** needs-setup/auth-error/forbidden/rate-limited/timeout 同 error:无结论不是证据,不落事实 */
+  verdict: 'hit' | 'miss' | 'error' | 'needs-setup' | 'auth-error' | 'forbidden' | 'rate-limited' | 'timeout' | 'cancelled'
+  options?: FlyaiLikeOption[]
+  evidence?: string
+}
+
+/** 会话检索(携程)结果形状(session-search.ts 最小面) */
+export interface SessionLikeOption {
+  flightNo?: string
+  airline?: string
+  depDateTime?: string
+  arrDateTime?: string
+  depAirport?: string
+  arrAirport?: string
+  price?: number
+}
+
+export interface SessionLikeResult {
+  verdict: string
+  options?: SessionLikeOption[]
+}
+
+/** 12306 exact-date fact freshness rule: capture must be non-future and <=15 minutes old. */
+export const TRAIN_FACT_FRESHNESS_RULE = 'captured_at_non_future_and_max_age_15m' as const
+export const TRAIN_FACT_MAX_AGE_MS = 15 * 60 * 1000
+
+export interface SessionTrainFactResult {
+  outcome: {
+    kind: 'recognized-nonempty' | 'recognized-empty' | 'malformed' | 'transport-runtime-error'
+    trains?: SessionTrainOption[]
+  }
+  collection?: {
+    requested: { from: string; to: string; date: string }
+    request: { fromStationTelecode: string; toStationTelecode: string; date: string }
+    response: { url: string; fromStationTelecode: string; toStationTelecode: string; date: string }
+    batchId: string
+    queryId: string
+    fetchedAt: string
+  }
+}
+
+const YMD = /^\d{4}-\d{2}-\d{2}$/
+
+function hmOf(dateTime: string | undefined): string | undefined {
+  const m = dateTime?.match(/T?(\d{2}:\d{2})/)
+  return m?.[1]
+}
+
+function dateOf(dateTime: string | undefined, fallback: string): string {
+  const m = dateTime?.match(/^(\d{4}-\d{2}-\d{2})/)
+  return m?.[1] ?? fallback
+}
+
+/** exact-date miss → 负事实(route+date 级「当前不可售/无结果」记录,fail-closed 的另一半) */
+export function negativeFact(queryId: string, kind: 'flight' | 'train', origin: string, destination: string, date: string, source: string, fetchedAt: string, alias?: CityAlias): FlightFact {
+  return {
+    schema: BOOKABLE_FACT_SCHEMA,
+    fact_id: makeFactId(['neg', kind, iataOf(alias, origin), iataOf(alias, destination), date, queryId]),
+    kind,
+    route: { origin: iataOf(alias, origin), destination: iataOf(alias, destination) },
+    date,
+    flight_no: '',
+    tier: 'live_inventory',
+    bookability: 'unavailable_exact_date',
+    source,
+    query_id: queryId,
+    fetched_at: fetchedAt,
+    as_of: fetchedAt.slice(0, 10),
+  }
+}
+
+/** flyai hit/miss → 事实列(error 不落事实——无结论不是证据) */
+export function factsFromFlyai(q: { kind: 'flight' | 'train'; origin: string; destination: string; date: string }, r: FlyaiLikeResult, fetchedAt: string, alias?: CityAlias): FlightFact[] {
+  const source = 'flyai'
+  const queryId = makeQueryId(source, q.kind, q.origin, q.destination, q.date)
+  const origin = iataOf(alias, q.origin)
+  const destination = iataOf(alias, q.destination)
+  if (r.verdict !== 'hit' && r.verdict !== 'miss') return []
+  if (r.verdict === 'miss') return [negativeFact(queryId, q.kind, q.origin, q.destination, q.date, source, fetchedAt, alias)]
+  const facts: FlightFact[] = []
+  for (const o of r.options ?? []) {
+    if (!o.no || !o.depDateTime) continue
+    const numeric = typeof o.price === 'number' && Number.isFinite(o.price) && o.price > 0 ? o.price : undefined
+    facts.push({
+      schema: BOOKABLE_FACT_SCHEMA,
+      fact_id: makeFactId([q.kind, origin, destination, q.date, o.no, queryId]),
+      kind: q.kind,
+      route: { origin, destination, origin_airport: o.depStation, dest_airport: o.arrStation },
+      date: dateOf(o.depDateTime, q.date),
+      flight_no: o.no,
+      marketing_carrier: o.name || undefined,
+      operating_carrier: undefined, // flyai 上游只给营销承运;实际承运未知 ≠ 相同,留空不猜
+      dep_local: hmOf(o.depDateTime),
+      arr_local: hmOf(o.arrDateTime),
+      nonstop: o.nonstop !== false,
+      price: numeric,
+      currency: numeric !== undefined ? 'CNY' : undefined,
+      tier: 'live_inventory',
+      bookability: 'bookable_exact_date',
+      source,
+      query_id: queryId,
+      fetched_at: fetchedAt,
+      as_of: fetchedAt.slice(0, 10),
+    })
+  }
+  // hit 但解析后零有效条目 = 与 miss 同语义(无可用事实,落负事实)
+  return facts.length > 0 ? facts : [negativeFact(queryId, q.kind, q.origin, q.destination, q.date, source, fetchedAt, alias)]
+}
+
+/** 会话检索 hit → 事实列(用户本人登录态来源,与 flyai 并列独立 source) */
+export function factsFromSession(q: { origin: string; destination: string; date: string }, r: SessionLikeResult, fetchedAt: string, alias?: CityAlias): FlightFact[] {
+  const source = 'session:ctrip-flight'
+  const queryId = makeQueryId(source, 'flight', q.origin, q.destination, q.date)
+  const origin = iataOf(alias, q.origin)
+  const destination = iataOf(alias, q.destination)
+  if (r.verdict !== 'hit') {
+    // miss/cooldown/challenged/needs-login:仅「正常返回 0 条」是负事实;通道不可用不落事实
+    return r.verdict === 'miss' ? [negativeFact(queryId, 'flight', q.origin, q.destination, q.date, source, fetchedAt, alias)] : []
+  }
+  const facts: FlightFact[] = []
+  for (const o of r.options ?? []) {
+    if (!o.flightNo || !o.depDateTime) continue
+    const numeric = typeof o.price === 'number' && Number.isFinite(o.price) && o.price > 0 ? o.price : undefined
+    facts.push({
+      schema: BOOKABLE_FACT_SCHEMA,
+      fact_id: makeFactId(['flight', origin, destination, q.date, o.flightNo, queryId]),
+      kind: 'flight',
+      route: { origin, destination, origin_airport: o.depAirport, dest_airport: o.arrAirport },
+      date: dateOf(o.depDateTime, q.date),
+      flight_no: o.flightNo,
+      marketing_carrier: o.airline || undefined,
+      operating_carrier: undefined,
+      dep_local: hmOf(o.depDateTime),
+      arr_local: hmOf(o.arrDateTime),
+      nonstop: true,
+      price: numeric,
+      currency: numeric !== undefined ? 'CNY' : undefined,
+      tier: 'live_inventory',
+      bookability: 'bookable_exact_date',
+      source,
+      query_id: queryId,
+      fetched_at: fetchedAt,
+      as_of: fetchedAt.slice(0, 10),
+    })
+  }
+  return facts
+}
+
+function trainCollectionIsFresh(
+  q: { from: string; to: string; date: string },
+  r: SessionTrainFactResult,
+  now: Date,
+): r is SessionTrainFactResult & { collection: NonNullable<SessionTrainFactResult['collection']> } {
+  const c = r.collection
+  if (!c || !c.batchId.trim() || !c.queryId.trim() || c.queryId !== `session:12306-train:${c.batchId}`) return false
+  if (c.requested.from !== q.from || c.requested.to !== q.to || c.requested.date !== q.date) return false
+  if (!c.request || !c.response
+    || c.request.date !== c.requested.date
+    || c.response.fromStationTelecode !== c.request.fromStationTelecode
+    || c.response.toStationTelecode !== c.request.toStationTelecode
+    || c.response.date !== c.request.date
+    || !validateTrainQueryResponseUrl(c.response.url, c.request).ok) return false
+  const fetchedMs = Date.parse(c.fetchedAt)
+  const nowMs = now.getTime()
+  if (!Number.isFinite(fetchedMs) || !Number.isFinite(nowMs)) return false
+  return fetchedMs <= nowMs && nowMs - fetchedMs <= TRAIN_FACT_MAX_AGE_MS
+}
+
+/** 12306 typed outcome → exact-date train facts.
+ * The converter never invents collection identity or timestamps: both must come
+ * from the session invocation binding. Only recognized-empty can create a
+ * negative fact. A recognized row needs Y plus a closed-set available seat token.
+ */
+export function factsFromSessionTrain(
+  q: { from: string; to: string; date: string },
+  r: SessionTrainFactResult,
+  now: Date = new Date(),
+): FlightFact[] {
+  if (!trainCollectionIsFresh(q, r, now)) return []
+  const c = r.collection
+  const source = 'session:12306-train'
+  const fetchedAt = c.fetchedAt
+  if (r.outcome.kind === 'recognized-empty') {
+    return [negativeFact(c.queryId, 'train', q.from, q.to, q.date, source, fetchedAt)]
+  }
+  if (r.outcome.kind !== 'recognized-nonempty') return []
+  const facts: FlightFact[] = []
+  for (const o of r.outcome.trains ?? []) {
+    if (o.canWebBuy !== 'Y' || !hasRecognizedAvailableSeat(o)) continue
+    facts.push({
+      schema: BOOKABLE_FACT_SCHEMA,
+      fact_id: makeFactId(['train', q.from, q.to, q.date, o.trainCode, c.queryId]),
+      kind: 'train',
+      route: { origin: q.from, destination: q.to },
+      date: q.date,
+      flight_no: o.trainCode,
+      dep_local: o.depTime,
+      arr_local: o.arrTime,
+      tier: 'live_inventory',
+      bookability: 'bookable_exact_date',
+      source,
+      query_id: c.queryId,
+      fetched_at: fetchedAt,
+      as_of: fetchedAt.slice(0, 10),
+    })
+  }
+  return facts
+}
+
+// ---------------------------------------------------------------------------
+// 注册表(纯函数视图;持久化在 capabilities/fact-log.ts)
+// ---------------------------------------------------------------------------
+
+/** 同 fact_id 去重,保留 fetched_at 最新(重查覆盖旧快照,历史不丢——append-only 由持久层保证) */
+export function dedupeFacts<T extends BookableFact>(facts: T[]): T[] {
+  const byId = new Map<string, T>()
+  for (const f of facts) {
+    const prev = byId.get(f.fact_id)
+    if (!prev || prev.fetched_at <= f.fetched_at) byId.set(f.fact_id, f)
+  }
+  return [...byId.values()].sort((a, b) => a.fetched_at.localeCompare(b.fetched_at) || a.fact_id.localeCompare(b.fact_id))
+}
+
+/** route+date 的最新查询结论(同日多次查询:最新一次为准,避免「昨天 miss 今天 hit」陈旧否定) */
+export function latestFactsForRouteDate(
+  facts: BookableFact[], origin: string, destination: string, date: string,
+  kind?: 'flight' | 'train',
+): FlightFact[] {
+  const hits = facts.filter((f): f is FlightFact =>
+    (f.kind === 'flight' || f.kind === 'train')
+    && (!kind || f.kind === kind)
+    && f.route.origin === origin && f.route.destination === destination && f.date === date)
+  const latestQueryTs = new Map<string, string>()
+  for (const f of hits) {
+    const prev = latestQueryTs.get(f.query_id)
+    if (!prev || prev < f.fetched_at) latestQueryTs.set(f.query_id, f.fetched_at)
+  }
+  const latestTs = [...latestQueryTs.values()].sort().pop()
+  if (!latestTs) return []
+  return hits.filter(f => f.fetched_at === latestTs)
+}
+
+// ---------------------------------------------------------------------------
+// 判定原语①:航班 claim 可述性(fail closed,flight-only)
+// ---------------------------------------------------------------------------
+
+export type FlightClaimVerdict =
+  | 'traceable'          // 注册表内有 bookable_exact_date 的该航班事实
+  | 'not_in_source'      // 该 route+date 查过 exact-date,结果里没有它——最强违例(填充历史/相邻日期)
+  | 'route_unqueried'    // 该 route+date 从未查过 exact-date——无证据断言
+  | 'contradicted'       // 注册表内有同号航班但事实字段冲突(时刻/机场)
+
+export interface FlightClaim {
+  flight_no: string
+  origin?: string
+  destination?: string
+  date?: string
+}
+
+/**
+ * 航班 claim 裁决(flight-only):注册表只接受 `kind:'flight'` 的同号事实
+ * ——train 事实走 `railClaimVerdict` 独立裁决,不得混入航班 not_in_source
+ * 路径(issue #299)。中文高铁/动车/城际/直达代码(G/D/C/Z + 3–4 位)在
+ * 闸侧 `extractClaims` 已分流到 `trains` claim,本函数无需再做扩展。
+ */
+export function flightClaimVerdict(facts: BookableFact[], claim: FlightClaim): { verdict: FlightClaimVerdict; fact?: FlightFact; reason: string } {
+  const no = claim.flight_no.toUpperCase().replace(/\s+/g, '')
+  const sameNo = facts.filter((f): f is FlightFact =>
+    f.kind === 'flight' && f.flight_no.toUpperCase() === no && f.bookability === 'bookable_exact_date')
+  const routeMatched = sameNo.filter(f =>
+    (!claim.origin || f.route.origin === claim.origin || f.route.origin_airport === claim.origin)
+    && (!claim.destination || f.route.destination === claim.destination || f.route.dest_airport === claim.destination)
+    && (!claim.date || f.date === claim.date))
+  if (routeMatched.length > 0) return { verdict: 'traceable', fact: routeMatched[0], reason: `回溯 ${routeMatched[0]!.query_id}` }
+  // 无同号可下单事实:该 route+date 是否查过?
+  if (claim.origin && claim.destination && claim.date) {
+    const scoped = latestFactsForRouteDate(facts, claim.origin, claim.destination, claim.date, 'flight')
+    if (scoped.length > 0) {
+      return {
+        verdict: 'not_in_source',
+        reason: scoped.some(f => f.bookability === 'unavailable_exact_date')
+          ? `${claim.origin}→${claim.destination} ${claim.date} exact-date 源返回 0 条(${scoped[0]!.query_id})——不得用历史班期/相邻日期填充`
+          : `${claim.origin}→${claim.destination} ${claim.date} exact-date 源在架 ${scoped.filter(f => f.bookability === 'bookable_exact_date').map(f => f.flight_no).join('/')}——无 ${no}`,
+      }
+    }
+    return { verdict: 'route_unqueried', reason: `${claim.origin}→${claim.destination} ${claim.date} 从未经 exact-date 源核验` }
+  }
+  return { verdict: 'route_unqueried', reason: `航班 ${no} 无可回溯的 exact-date 事实(缺 route/date 上下文)` }
+}
+
+// ---------------------------------------------------------------------------
+// 判定原语①b:车次 claim 可述性(rail-only,fail closed;issue #299)
+//   闸侧 `extractClaims` 已把 G/D/C/Z + 3–4 位 token 收集为 train claim;
+//   本裁决只在 train 事实里查同号 bookable_exact_date,缺事实/缺上下文/
+// 路线未查均 fail-closed。支持的事实生产端是 `factsFromFlyai kind:'train'`
+// 与 `factsFromSessionTrain`,两者均经真实工具路径追加到事实日志; session
+// 结果必须先通过 typed parser outcome + seat availability/freshness contract。
+// 不得用历史班期或 static-schedule 凑合格回溯。
+// ---------------------------------------------------------------------------
+
+export type RailClaimVerdict =
+  | 'traceable'          // 注册表内有 bookable_exact_date 的该 train 事实(同号+同 route+同 date)
+  | 'not_in_source'      // 该 route+date 查过 exact-date,结果里没有它——最强违例
+  | 'route_unqueried'    // 该 route+date 从未查过 exact-date——无证据断言
+  | 'rail_claim_unverified' // 缺 route/date 上下文,或缺同号事实且 route/date 无 exact-date 证据
+
+export interface RailClaim {
+  flight_no: string
+  origin?: string
+  destination?: string
+  date?: string
+}
+
+const TRAIN_FACT_SOURCES = new Set(['flyai', 'session:12306-train'])
+
+function isStructuredTrainFact(f: BookableFact): f is FlightFact {
+  return f.kind === 'train'
+    && f.schema === BOOKABLE_FACT_SCHEMA
+    && TRAIN_FACT_SOURCES.has(f.source)
+    && f.query_id.trim().length > 0
+    && f.tier === 'live_inventory'
+}
+
+export function railClaimVerdict(facts: BookableFact[], claim: RailClaim): { verdict: RailClaimVerdict; fact?: FlightFact; reason: string } {
+  const no = claim.flight_no.toUpperCase().replace(/\s+/g, '')
+  if (!claim.origin || !claim.destination || !claim.date) {
+    return { verdict: 'rail_claim_unverified', reason: `车次 ${no} 无可回溯的 exact-date 事实(缺完整 route/date 上下文)` }
+  }
+  // 先按 train kind 选择该 route+date 的最新查询批次,再在该批次匹配车次。
+  // 这样旧 hit 不会越过更新的 miss/unavailable,flight 批次也不能遮蔽 train 批次。
+  const scoped = latestFactsForRouteDate(facts, claim.origin, claim.destination, claim.date, 'train')
+    .filter(isStructuredTrainFact)
+  const sameNo = scoped.filter(f =>
+    f.flight_no.toUpperCase() === no
+      && f.bookability === 'bookable_exact_date')
+  if (sameNo.length > 0) return { verdict: 'traceable', fact: sameNo[0], reason: `回溯 ${sameNo[0]!.query_id}` }
+  if (scoped.length > 0) {
+    return {
+      verdict: 'not_in_source',
+      reason: scoped.some(f => f.bookability === 'unavailable_exact_date')
+        ? `${claim.origin}→${claim.destination} ${claim.date} train exact-date 源返回 0 条(${scoped[0]!.query_id})——不得用历史班期/相邻日期填充`
+        : `${claim.origin}→${claim.destination} ${claim.date} train exact-date 源在架 ${scoped.filter(f => f.bookability === 'bookable_exact_date').map(f => f.flight_no).join('/')}——无 ${no}`,
+    }
+  }
+  return { verdict: 'route_unqueried', reason: `${claim.origin}→${claim.destination} ${claim.date} train 路线从未经 exact-date 源核验` }
+}
+
+// ---------------------------------------------------------------------------
+// 判定原语②:同日衔接硬约束(办事结束 → 门到机场 → 值机截止 → 起飞)
+// ---------------------------------------------------------------------------
+
+export interface SameDayDepartureConstraint {
+  /** 当日地面事务最早结束(当地 HH:MM,如银行办事) */
+  errand_end_local: string
+  /** 事务地点→机场门到门分钟(含步行/等车) */
+  airport_transit_min: number
+  /** 起飞前值机/安检截止分钟(国际建议 120) */
+  checkin_deadline_min: number
+}
+
+export interface SameDayDepartureVerdict {
+  feasible: boolean
+  /** 事务约束下的最早可接起飞时刻(当地 HH:MM) */
+  earliest_departure_local: string
+  /** exact-date 在架且满足硬约束的直飞 */
+  feasible_flights: FlightFact[]
+  /** 被约束排除的在架直飞(带排除原因) */
+  excluded: Array<{ flight_no: string; reason: string }>
+  /** 不可行时的结构化最小改动建议 */
+  suggestions: string[]
+}
+
+function hmToMin(hm: string): number {
+  const [h, m] = hm.split(':').map(Number)
+  return (h ?? 0) * 60 + (m ?? 0)
+}
+
+function minToHm(min: number): string {
+  return `${String(Math.floor(min / 60)).padStart(2, '0')}:${String(min % 60).padStart(2, '0')}`
+}
+
+/**
+ * 「上午办事 + 当天下午直飞」类核心衔接判定:
+ * 最早起飞 = errand_end + 门到机场 + 值机截止;exact-date 在架直飞逐班过闸。
+ * 在架为空的失败语义与「有班但接不上」分开陈述(前者是库存问题,后者是约束问题)。
+ */
+export function checkSameDayDeparture(
+  facts: BookableFact[],
+  q: { origin: string; destination: string; date: string },
+  c: SameDayDepartureConstraint,
+): SameDayDepartureVerdict {
+  const earliest = hmToMin(c.errand_end_local) + c.airport_transit_min + c.checkin_deadline_min
+  const scoped = latestFactsForRouteDate(facts, q.origin, q.destination, q.date, 'flight')
+  const nonstopBookable = scoped.filter(f => f.bookability === 'bookable_exact_date' && f.nonstop !== false)
+  const feasible: FlightFact[] = []
+  const excluded: Array<{ flight_no: string; reason: string }> = []
+  for (const f of nonstopBookable) {
+    const dep = f.dep_local ? hmToMin(f.dep_local) : null
+    if (dep === null) {
+      excluded.push({ flight_no: f.flight_no, reason: '缺起飞时刻,不参与衔接判定' })
+    } else if (dep >= earliest) {
+      feasible.push(f)
+    } else {
+      excluded.push({ flight_no: f.flight_no, reason: `${f.dep_local} 起飞早于最早可接时刻 ${minToHm(earliest)}(${c.errand_end_local} 结束事务 + ${c.airport_transit_min}m 到机场 + ${c.checkin_deadline_min}m 值机)` })
+    }
+  }
+  const ok = feasible.length > 0
+  const suggestions: string[] = []
+  if (!ok) {
+    const inStock = nonstopBookable.map(f => `${f.flight_no} ${f.dep_local ?? '?'}`).join('、')
+    suggestions.push(`增加 1 个${q.origin}住宿夜:改乘次日早班${inStock ? `(当日在架:${inStock})` : ''}`)
+    suggestions.push('或提前一天完成地面事务/提前一天出发,把同日衔接改为隔夜衔接')
+  }
+  return { feasible: ok, earliest_departure_local: minToHm(earliest), feasible_flights: feasible, excluded, suggestions }
+}
+
+// ---------------------------------------------------------------------------
+// 判定原语③:行程统计不变量(机器断言,不许自然语言总结反算)
+// ---------------------------------------------------------------------------
+
+export interface ItineraryFacts {
+  trip_start: string // YYYY-MM-DD
+  trip_end: string   // YYYY-MM-DD(回到家的当地日期)
+  stays: Array<{ place: string; check_in: string; check_out: string }>
+  /** 机上夜(红眼跨夜)数 */
+  onboard_nights: number
+  /** O&D 段(用户视角段);flight 段含 legs 数(中转一段多 leg) */
+  od_segments: Array<{ from: string; to: string; date: string; mode: 'flight' | 'rail' | 'car'; legs: number }>
+  budget_items: Array<{ label: string; min_cny: number; max_cny: number }>
+  /** 产物里的预算下限话术(「可压到 ¥N」) */
+  claimed_floor_cny?: number
+}
+
+export interface InvariantViolation {
+  kind: 'nights_inconsistent' | 'legs_inconsistent' | 'budget_floor_inconsistent' | 'date_order'
+  detail: string
+}
+
+function daysBetween(a: string, b: string): number {
+  return Math.round((Date.parse(`${b}T00:00:00Z`) - Date.parse(`${a}T00:00:00Z`)) / 86_400_000)
+}
+
+export function itineraryInvariants(it: ItineraryFacts): InvariantViolation[] {
+  const violations: InvariantViolation[] = []
+  const totalNights = daysBetween(it.trip_start, it.trip_end)
+  let hotelNights = 0
+  for (const s of it.stays) {
+    const n = daysBetween(s.check_in, s.check_out)
+    if (n <= 0) violations.push({ kind: 'date_order', detail: `${s.place} 住宿 ${s.check_in}→${s.check_out} 晚数 ≤0` })
+    else hotelNights += n
+  }
+  if (hotelNights + it.onboard_nights !== totalNights) {
+    violations.push({
+      kind: 'nights_inconsistent',
+      detail: `酒店夜 ${hotelNights} + 机上夜 ${it.onboard_nights} = ${hotelNights + it.onboard_nights} ≠ 行程总夜数 ${totalNights}(${it.trip_start}→${it.trip_end})——夜数口径必须由结构化住宿反算,不许自然语言估算`,
+    })
+  }
+  for (const seg of it.od_segments) {
+    if (seg.mode === 'flight' && seg.legs < 1) {
+      violations.push({ kind: 'legs_inconsistent', detail: `${seg.from}→${seg.to}(${seg.date})flight O&D 段 legs=${seg.legs}——每段至少 1 leg` })
+    }
+    if (seg.date < it.trip_start || seg.date > it.trip_end) {
+      violations.push({ kind: 'date_order', detail: `${seg.from}→${seg.to} 日期 ${seg.date} 落在行程窗 ${it.trip_start}→${it.trip_end} 之外` })
+    }
+  }
+  const minSum = it.budget_items.reduce((acc, b) => acc + b.min_cny, 0)
+  if (it.claimed_floor_cny !== undefined && it.claimed_floor_cny < minSum) {
+    violations.push({
+      kind: 'budget_floor_inconsistent',
+      detail: `预算分项最低合计 ¥${minSum.toLocaleString()} > 产物声称可压到 ¥${it.claimed_floor_cny.toLocaleString()}——下限话术不得低于分项最低合计`,
+    })
+  }
+  return violations
+}
+
+// ---------------------------------------------------------------------------
+// 判定原语④:回头路检测(A→B→A;存在 B→下一站直飞时给最小改动建议)
+// ---------------------------------------------------------------------------
+
+export interface BacktrackFinding {
+  kind: 'backtrack'
+  /** 回头路径,如 ['HKT','KBV','HKT'] */
+  path: string[]
+  /** 最小改动建议(存在 B→C 直飞边时) */
+  suggestion?: string
+}
+
+export function detectBacktrack(stops: string[], nonstopEdges: ReadonlySet<string>): BacktrackFinding[] {
+  const findings: BacktrackFinding[] = []
+  for (let i = 0; i + 2 < stops.length; i++) {
+    const a = stops[i]!, b = stops[i + 1]!, c = stops[i + 2]!
+    if (a !== c) continue
+    // A→B→A 回头;若 B→D(下一站)有直飞边,建议「去程后直接 B→D」
+    const d = stops[i + 3]
+    const suggestion = d && nonstopEdges.has(`${b}-${d}`)
+      ? `${b}→${d} 有直飞:改为 ${a}→${b} 后直接 ${b}→${d},消除 ${a}→${b}→${a} 回头路`
+      : undefined
+    findings.push({ kind: 'backtrack', path: [a, b, c], suggestion })
+  }
+  return findings
+}
+
+// ---------------------------------------------------------------------------
+// 确定性渲染:航班/政策行只从结构化对象生成(issue #46 期望①:禁止凭记忆抄写)
+// ---------------------------------------------------------------------------
+
+/** 远期复核默认 gate:出发前 30 天 */
+export function defaultReviewBy(tripDate: string): string {
+  const d = new Date(Date.parse(`${tripDate}T00:00:00Z`) - 30 * 86_400_000)
+  return d.toISOString().slice(0, 10)
+}
+
+/**
+ * 航班/车次事实行。bookable_exact_date 才允许完整班次行;其余一律 fail-closed 措辞。
+ * train 复用此 canonical renderer 但只输出车次语义,不输出直飞或价格;永不输出无条件 ✓;
+ * 证据链(source/query_id/fetched_at)随行必达。
+ */
+export function renderFlightFact(f: FlightFact): string {
+  return renderFlightFactInner(f) + ` <!-- fact:${f.fact_id} -->`
+}
+
+function renderFlightFactInner(f: FlightFact): string {
+  // 单向生成锚点(D-26):每条事实行内嵌 fact_id,闸侧锚点匹配 = 确定性回溯
+  const anchor = ` <!-- fact:${f.fact_id} -->`
+  const route = `${f.route.origin}→${f.route.destination}`
+  const evidence = `[${f.source}@${f.fetched_at} #${f.query_id}]`
+  if (f.kind === 'train' && f.bookability === 'unavailable_exact_date') {
+    const review = f.review_by ?? defaultReviewBy(f.date)
+    return `- ${route} ${f.date} 车次${f.flight_no ? ` ${f.flight_no}` : ''}:**未确认/当前不可售**——exact-date 源 ${f.source} 于 ${f.fetched_at.slice(0, 10)} 返回 0 条;到 ${review} 复核,不得用历史班期/相邻日期填充 ${evidence}`
+  }
+  if (f.kind === 'train' && f.bookability !== 'bookable_exact_date') {
+    return `- ${route} ${f.date} 车次${f.flight_no ? ` ${f.flight_no}` : ''}:**未核验**(${f.bookability})——仅作参考,不得作为可下单方案呈现 ${evidence}`
+  }
+  if (f.bookability === 'unavailable_exact_date') {
+    const review = f.review_by ?? defaultReviewBy(f.date)
+    return `- ${route} ${f.date}:**未确认/当前不可售**——exact-date 源 ${f.source} 于 ${f.fetched_at.slice(0, 10)} 返回 0 条;到 ${review} 复核,不得用历史班期/相邻日期填充 ${evidence}`
+  }
+  if (f.bookability !== 'bookable_exact_date') {
+    return `- ${route} ${f.date} ${f.flight_no || ''}:**未核验**(${f.bookability})——仅作参考,不得作为可下单方案呈现 ${evidence}`
+  }
+  if (f.kind === 'train') {
+    const times = f.dep_local && f.arr_local ? ` ${f.dep_local}→${f.arr_local}` : ''
+    return `- ${route} ${f.date} 车次 ${f.flight_no}${times} ${evidence}`
+  }
+  const carrier = f.operating_carrier && f.operating_carrier !== f.marketing_carrier
+    ? `营销 ${f.marketing_carrier ?? '?'} / 实际承运 ${f.operating_carrier}`
+    : (f.marketing_carrier ?? '')
+  const times = f.dep_local && f.arr_local ? ` ${f.dep_local}→${f.arr_local}` : ''
+  const nonstop = f.nonstop === false ? '(中转)' : ' 直飞'
+  // 双机场城市防混淆:落点机场码与城市码不同时显式标注(FD 落 DMK / VZ 落 BKK 不互换)
+  const airportNote = f.route.dest_airport && f.route.dest_airport !== f.route.destination
+    ? `(落 ${f.route.dest_airport})`
+    : ''
+  const price = f.price !== undefined ? ` ¥${f.price}` : ' 价待询'
+  const baggage = f.baggage_included === false ? ',不含托运行李' : ''
+  return `- ${route} ${f.date} ${f.flight_no}${carrier ? `(${carrier})` : ''}${times}${nonstop}${airportNote}${price}${baggage} ${evidence}`
+}
+
+/**
+ * 联程/分票连接行:只有同票保护(protected_connection=true)才允许称「联程」;
+ * 分票必须显式标红自助转机风险(无行李直挂/误机无保护)。
+ */
+export function renderConnection(legA: FlightFact, legB: FlightFact): string {
+  const through = legA.protected_connection === true && legB.protected_connection === true
+  const head = `${legA.route.origin}→${legA.route.destination} ${legA.flight_no} + ${legB.route.origin}→${legB.route.destination} ${legB.flight_no}`
+  return through
+    ? `- ${head}:联程(同一票号/行李直挂/误机保护)`
+    : `- ${head}:⚠️ **分票/自助转机**——两段接得上 ≠ 联程;无同一票号、行李需自取重挂、误机无保护,缓冲与风险自担`
+}
+
+/**
+ * 政策事实行:恒为「截至 as_of 的现行政策」表述 + 复核 gate,永不用无条件 ✓。
+ * 远期(出发日晚于 as_of)必须附 review_by(默认 D-30)。
+ *
+ * 行尾内嵌 `<!-- fact:<fact_id> -->` 锚点(issue #273,ADR-19 typed-anchor 单向生成):
+ * 产物经渲染原语生成即自带溯源锚,闸侧锚点确定性回溯;手改/伪造锚点 = fact_anchor_unknown。
+ * 与 renderFlightFact / renderHotelFact 同源:启发式 POLICY_WORD 仅覆盖手写/历史产物。
+ */
+export function renderPolicyFact(p: PolicyFact, tripStart?: string): string {
+  return `${policyCanonicalBody(p, tripStart)} <!-- fact:${p.fact_id} -->`
+}
+
+/**
+ * 政策行 canonical body(不含锚点;issue #359,D-26 残余收口):
+ * 闸侧锚点回溯用同一原文,subject/statement/source/fetched_at/query_id 任意一项
+ * 改动 → 行文本不再等于 canonical body → fact_anchor_unknown fail-closed。
+ * 不走宽松 substring/subset 匹配,避免锚点行被改写 subject/statement 后仍 pass。
+ * 复核提醒(review_by 或 tripStart 派生的 defaultReviewBy)是合法的可选段——
+ * `tripStart` 与 renderPolicyFact 同一传入,产物与闸两侧语义一致。
+ */
+export function policyCanonicalBody(p: PolicyFact, tripStart?: string): string {
+  const review = p.review_by ?? (tripStart ? defaultReviewBy(tripStart) : undefined)
+  const reviewNote = review ? `;远期政策须复核——到 ${review} 再核验一次` : ''
+  return `- ${p.subject}:截至 ${p.as_of} 的现行政策——${p.statement}${reviewNote} [${p.source}@${p.fetched_at} #${p.query_id}]`
+}
+
+/** 从结构化行程渲染夜数口径行(机器反算,唯一口径) */
+export function renderNightsLine(it: ItineraryFacts): string {
+  const totalNights = daysBetween(it.trip_start, it.trip_end)
+  const hotelNights = it.stays.reduce((acc, s) => acc + Math.max(0, daysBetween(s.check_in, s.check_out)), 0)
+  const flightOd = it.od_segments.filter(s => s.mode === 'flight').length
+  const flightLegs = it.od_segments.filter(s => s.mode === 'flight').reduce((acc, s) => acc + s.legs, 0)
+  return `共 ${daysBetween(it.trip_start, it.trip_end) + 1} 天 ${totalNights} 晚 = ${hotelNights} 个酒店夜 + ${it.onboard_nights} 个机上夜;航班按 O&D ${flightOd} 段(共 ${flightLegs} 个 flight legs)`
+}
+
+// ---------------------------------------------------------------------------
+// 酒店事实(D-26,issue #118):exact-date 酒店检索 hit/miss 落账
+// 纪律:摸底(未定档期)不落账(无 exact-date 语义);needs-setup/error 传输失败永不落负事实
+// ---------------------------------------------------------------------------
+
+export function factsFromHotel(input: {
+  source: string
+  destination: string
+  checkIn?: string
+  checkOut?: string
+  verdict: string
+  options: number
+  evidence: string
+  fetchedAt: string
+}): HotelFact[] {
+  if (!input.checkIn || !input.checkOut) return []
+  if (input.verdict !== 'hit' && input.verdict !== 'miss') return []
+  const queryId = `hotel:${input.source}:${input.destination}:${input.checkIn}_${input.checkOut}`
+  return [{
+    schema: BOOKABLE_FACT_SCHEMA,
+    kind: 'hotel',
+    fact_id: makeFactId([input.destination, input.checkIn, input.checkOut, queryId]),
+    destination: input.destination,
+    check_in: input.checkIn,
+    check_out: input.checkOut,
+    verdict: input.verdict,
+    bookability: input.verdict === 'hit' ? 'bookable_exact_date' : 'unavailable_exact_date',
+    options_masked: input.options,
+    source: input.source,
+    query_id: queryId,
+    fetched_at: input.fetchedAt,
+    as_of: input.fetchedAt.slice(0, 10),
+    tier: 'live_inventory',
+  }]
+}
+
+/** 酒店 claim 回溯:同目的地+同档期的 exact-date 事实裁决(无事实=unverified,fail-closed) */
+export function hotelClaimVerdict(
+  facts: BookableFact[],
+  claim: { destination: string; check_in?: string; check_out?: string },
+): { verdict: 'traceable' | 'not_in_source' | 'unverified'; fact?: HotelFact; reason: string } {
+  const scoped = facts.filter((f): f is HotelFact =>
+    f.kind === 'hotel' && f.destination === claim.destination
+    && (!claim.check_in || f.check_in === claim.check_in)
+    && (!claim.check_out || f.check_out === claim.check_out))
+  if (scoped.length === 0) {
+    return {
+      verdict: 'unverified',
+      reason: `酒店 claim(${claim.destination}${claim.check_in ? ` ${claim.check_in}→${claim.check_out ?? '?'}` : ''})未经 exact-date 源核验——先检索再写结论`,
+    }
+  }
+  const hit = scoped.find(f => f.bookability === 'bookable_exact_date')
+  if (hit) return { verdict: 'traceable', fact: hit, reason: 'exact-date 命中' }
+  const latest = scoped[scoped.length - 1]!
+  return { verdict: 'not_in_source', fact: latest, reason: `该档期 exact-date 源正常返回 0 条(${latest.fetched_at})——不得写有房/可订` }
+}
+
+// ---------------------------------------------------------------------------
+// 渲染原语(单向生成,issue #118):事实 → 行,锚点内嵌 fact_id;
+// 产物经原语渲染即自带溯源锚,闸侧锚点匹配 = 确定性回溯,不靠行文猜测
+// ---------------------------------------------------------------------------
+
+
+export function renderHotelFact(f: HotelFact): string {
+  if (f.verdict !== 'hit') {
+    return `- ${f.destination} ${f.check_in}→${f.check_out}:exact-date 源 0 条在架(不可订) <!-- fact:${f.fact_id} -->`
+  }
+  return `- ${f.destination} ${f.check_in}→${f.check_out}:住宿已核验(在架 ${f.options_masked} 家;价格上游打码,真实价以落地页为准) <!-- fact:${f.fact_id} -->`
+}