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

package/ts/capabilities/session/adapters/rail-12306.ts

@@ -0,0 +1,392 @@
+/**
+ * 12306 火车站点适配器(2026-09-03,继 ctrip-hotel 后会话面第三通道):
+ *   - entry:https://kyfw.12306.cn/otn/leftTicket/init?linktypeid=dc&fs=<城市名,电报码>&ts=<...>&date=YYYY-MM-DD&flag=N,N,Y
+ *     (电报码表官方站表全量校准 2026-09-03,129 城;曾纠出南宁 NIZ→NNZ 错码)
+ *   - networkHints:kyfw leftTicket/query(负载均衡变体 queryG/queryZ/queryA 等全部命中)
+ *   - 解析:leftTicket/query 返回 data.result[] 管道行(12306 经典 | 拼接格式)。
+ *     **第一方校准(2026-09-03)**:字段索引与站名映射(data.map[电报码])逐一
+ *     取自官方前端 queryLeftTicket_end_js.js 的 cN(result,map) 转换函数——旧版
+ *     公开常识索引与官方现行映射不符(站名/座位桶全错),真会话前即纠;行级
+ *     签名校验(车次码/时刻形态)继续兜住未来漂移:失配整行跳过,fail-visible
+ *
+ * 与机/酒通道的两点刻意差异:
+ *   - 无登录闸:12306 余票查询是公开面(登录只关系下单),无账号数据过手;
+ *     扩展照样只读被动嗅探(零写行为),证据链标注「公开查询面」
+ *   - 列表接口不含票价:如实只呈现 车次/时刻/历时/余票,票价以 12306 落地页为准
+ */
+
+/** 城市电报码表(**官方口径校准 2026-09-03**:全部条目逐一核对自
+ * kyfw.12306.cn/otn/resources/js/framework/station_name.js 官方全量站表
+ * ——曾借此抓出南宁 NIZ→NNZ 错码;代表站规则=城市同名站,fs/ts 用城市码
+ * 服务端扩到市内全部站。词表外 unresolved 逐字保留,调用方可显式传电报码
+ * 覆盖——kyfw 查询页 URL 里的 fs=城市,XXX 三位码;核对快照见
+ * data/stations-12306-verify.json) */
+export const STATION_TELECODES: Record<string, string> = {
+  "三亚": 'SEQ',
+  "上海": 'SHH',
+  "上饶": 'SRG',
+  "东莞": 'RTQ',
+  "中卫": 'ZWJ',
+  "中山": 'ZSQ',
+  "丽江": 'LHM',
+  "乌鲁木齐": 'WAR',
+  "乐山": 'IVW',
+  "九江": 'JJG',
+  "伊宁": 'YMR',
+  "佛山": 'FSQ',
+  "保山": 'BAM',
+  "六盘水": 'UMW',
+  "兰州": 'LZJ',
+  "包头": 'BTC',
+  "北京": 'BJP',
+  "北海": 'BHZ',
+  "十堰": 'SNN',
+  "南京": 'NJH',
+  "南充": 'NCW',
+  "南宁": 'NNZ',
+  "南昌": 'NCG',
+  "南通": 'NUH',
+  "南阳": 'NFF',
+  "厦门": 'XMS',
+  "台州": 'TEU',
+  "合肥": 'HFH',
+  "吉林": 'JLL',
+  "吐鲁番": 'TFR',
+  "呼和浩特": 'HHC',
+  "咸阳": 'XYY',
+  "哈密": 'HMR',
+  "哈尔滨": 'HBB',
+  "喀什": 'KSR',
+  "嘉兴": 'JXH',
+  "嘉峪关": 'JGJ',
+  "大同": 'DTV',
+  "大庆": 'DZX',
+  "大理": 'DKM',
+  "大连": 'DLT',
+  "天水": 'TSJ',
+  "天津": 'TJP',
+  "太原": 'TYV',
+  "宁波": 'NGH',
+  "安顺": 'ASW',
+  "宜宾": 'YKE',
+  "宜昌": 'YCN',
+  "宝鸡": 'BJY',
+  "岳阳": 'YYQ',
+  "常州": 'CZH',
+  "常德": 'VGQ',
+  "广州": 'GZQ',
+  "库尔勒": 'KLR',
+  "延安": 'YWY',
+  "开封": 'KFF',
+  "张掖": 'ZYJ',
+  "徐州": 'XCH',
+  "德阳": 'DYW',
+  "惠州": 'HCQ',
+  "成都": 'CDW',
+  "扬州": 'YLH',
+  "承德": 'CDP',
+  "抚顺": 'FET',
+  "拉萨": 'LSO',
+  "揭阳": 'JYA',
+  "新乡": 'XXF',
+  "无锡": 'WGH',
+  "日喀则": 'RKO',
+  "昆明": 'KMM',
+  "普洱": 'PEM',
+  "景德镇": 'JCG',
+  "曲靖": 'QJM',
+  "杭州": 'HZH',
+  "林芝": 'LZO',
+  "柳州": 'LZZ',
+  "株洲": 'ZZQ',
+  "格尔木": 'GRO',
+  "桂林": 'GLZ',
+  "梧州": 'WZZ',
+  "武汉": 'WHN',
+  "汉中": 'HOY',
+  "汕头": 'OTQ',
+  "沈阳": 'SYT',
+  "泉州": 'QYS',
+  "泸州": 'LUE',
+  "洛阳": 'LYF',
+  "济南": 'JNK',
+  "深圳": 'SZQ',
+  "温州": 'RZH',
+  "湛江": 'ZJZ',
+  "漳州": 'ZUS',
+  "潮州": 'CKQ',
+  "牡丹江": 'MDB',
+  "珠海": 'ZHQ',
+  "盐城": 'AFH',
+  "石家庄": 'SJP',
+  "福州": 'FZS',
+  "秦皇岛": 'QTP',
+  "绍兴": 'SOH',
+  "绵阳": 'MYW',
+  "芜湖": 'WHH',
+  "苏州": 'SZH',
+  "茂名": 'MDQ',
+  "莆田": 'PTS',
+  "衡阳": 'HYQ',
+  "襄阳": 'XFN',
+  "西宁": 'XNO',
+  "西安": 'XAY',
+  "西昌": 'ECW',
+  "贵阳": 'GIW',
+  "赣州": 'GZG',
+  "达州": 'RXW',
+  "遵义": 'ZYE',
+  "郑州": 'ZZF',
+  "重庆": 'CUW',
+  "金华": 'JBH',
+  "银川": 'YIJ',
+  "镇江": 'ZJH',
+  "长春": 'CCT',
+  "长沙": 'CSQ',
+  "阜阳": 'FYH',
+  "青岛": 'QDK',
+  "鞍山": 'AST',
+  "韶关": 'SNQ',
+  "香格里拉": 'EUM',
+  "香港": 'XJA',
+  "齐齐哈尔": 'QHX',
+  "龙岩": 'LYS',
+}
+
+export interface TrainEntryQuery {
+  from: string
+  to: string
+  /** YYYY-MM-DD */
+  date: string
+  /** 显式城市电报码(覆盖码表;kyfw 查询页 URL fs=城市,XXX 的三位码) */
+  fromStationTelecode?: string
+  toStationTelecode?: string
+}
+
+export interface AdapterEntry {
+  ok: boolean
+  url?: string
+  unresolved?: string[]
+}
+
+export interface TrainQueryTelecodes {
+  fromStationTelecode: string
+  toStationTelecode: string
+  date: string
+}
+
+export interface TrainResponseBinding extends TrainQueryTelecodes {
+  /** Exact URL observed on the response whose body was parsed. */
+  url: string
+}
+
+export type TrainResponseUrlValidation =
+  | { ok: true; binding: TrainResponseBinding }
+  | { ok: false; reason: string }
+
+export function resolveTrainQueryTelecodes(q: TrainEntryQuery): { ok: true; telecodes: TrainQueryTelecodes } | { ok: false; unresolved: string[] } {
+  const unresolved: string[] = []
+  const fromTc = (q.fromStationTelecode ?? '').trim().toUpperCase() || STATION_TELECODES[q.from.trim()]
+  const toTc = (q.toStationTelecode ?? '').trim().toUpperCase() || STATION_TELECODES[q.to.trim()]
+  if (!fromTc) unresolved.push(q.from)
+  if (!toTc) unresolved.push(q.to)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(q.date)) unresolved.push(q.date)
+  if (unresolved.length > 0 || !fromTc || !toTc) return { ok: false, unresolved }
+  return { ok: true, telecodes: { fromStationTelecode: fromTc, toStationTelecode: toTc, date: q.date } }
+}
+
+/** Bind a parsed body to the exact 12306 query request that this invocation built. */
+export function validateTrainQueryResponseUrl(observedUrl: string, expected: TrainQueryTelecodes): TrainResponseUrlValidation {
+  let parsed: URL
+  try {
+    parsed = new URL(observedUrl)
+  } catch {
+    return { ok: false, reason: 'response URL malformed' }
+  }
+  if (parsed.protocol !== 'https:' || parsed.hostname.toLowerCase() !== TRAIN_SITE_HOST || parsed.port) {
+    return { ok: false, reason: 'response URL host/protocol is not the 12306 HTTPS host' }
+  }
+  if (!/^\/otn\/leftTicket\/query[A-Za-z0-9_-]*$/i.test(parsed.pathname)
+    || !TRAIN_NETWORK_HINTS.some((hint) => hint.test(parsed.pathname))) {
+    return { ok: false, reason: 'response URL is not an allowed leftTicket query endpoint' }
+  }
+  const exactParam = (name: string): string | undefined => {
+    const values = parsed.searchParams.getAll(name)
+    return values.length === 1 ? values[0] : undefined
+  }
+  if (exactParam('leftTicketDTO.train_date') !== expected.date
+    || exactParam('leftTicketDTO.from_station') !== expected.fromStationTelecode
+    || exactParam('leftTicketDTO.to_station') !== expected.toStationTelecode) {
+    return { ok: false, reason: 'response URL query route/date does not match the invocation' }
+  }
+  return { ok: true, binding: { url: observedUrl, ...expected } }
+}
+
+export function buildTrainEntryUrl(q: TrainEntryQuery): AdapterEntry {
+  const resolved = resolveTrainQueryTelecodes(q)
+  if (!resolved.ok) return { ok: false, unresolved: resolved.unresolved }
+  const { fromStationTelecode: fromTc, toStationTelecode: toTc } = resolved.telecodes
+  const fs = encodeURIComponent(`${q.from.trim()},${fromTc}`)
+  const ts = encodeURIComponent(`${q.to.trim()},${toTc}`)
+  return { ok: true, url: `https://kyfw.12306.cn/otn/leftTicket/init?linktypeid=dc&fs=${fs}&ts=${ts}&date=${q.date}&flag=N,N,Y` }
+}
+
+/** networkHints:余票查询 XHR(queryG/Z/A/U 等负载均衡变体全命中) */
+export const TRAIN_NETWORK_HINTS = [/leftTicket\/query/i]
+
+/** 12306 页域(content_scripts 注入面与 background 白名单的对账源) */
+export const TRAIN_SITE_HOST = 'kyfw.12306.cn'
+
+export interface SessionTrainOption {
+  /** 车次(G1375 / K79 等) */
+  trainCode: string
+  fromStation: string
+  toStation: string
+  /** 出发/到达时刻(HH:MM;跨日由到达时刻本身表达,官方 DTO 无隔日字段) */
+  depTime: string
+  arrTime: string
+  /** 历时(分钟) */
+  durationMin: number
+  /** 12306 train-origin date(YYYY-MM-DD);validated and preserved, not passenger query date */
+  startTrainDate?: string
+  /** Y=可预订 / N=不可 / 其他上游原话 */
+  canWebBuy: string
+  /** 余票分桶(第一方校准索引,见 SEAT_BUCKETS;值原样:数字 / 有 / 无 / --) */
+  seats: Record<string, string>
+  /** 查询落地页(由人选车完成预订;gotry 不碰) */
+  jumpUrl?: string
+}
+
+/** 座位桶索引表(**第一方校准 2026-09-03**:逐字段取自 12306 官方前端
+ * queryLeftTicket_end_js.js 的 cN(result,map) 转换函数——旧版公开常识索引
+ * (19-28 段)与官方现行映射不符,首查前即纠);label=页面席别口径,未知席别
+ * 保留上游字段 id 原样 */
+const SEAT_BUCKETS: Array<{ index: number; field: string; label: string }> = [
+  { index: 20, field: 'gg_num', label: '其他(通勤)' },
+  { index: 21, field: 'gr_num', label: '高级软卧' },
+  { index: 22, field: 'qt_num', label: '其他' },
+  { index: 23, field: 'rw_num', label: '软卧(一等卧)' },
+  { index: 24, field: 'rz_num', label: '软座' },
+  { index: 25, field: 'tz_num', label: '特等座' },
+  { index: 26, field: 'wz_num', label: '无座' },
+  { index: 27, field: 'yb_num', label: 'yp_b(上游席别)' },
+  { index: 28, field: 'yw_num', label: '硬卧(二等卧)' },
+  { index: 29, field: 'yz_num', label: '硬座' },
+  { index: 30, field: 'ze_num', label: '二等座' },
+  { index: 31, field: 'zy_num', label: '一等座' },
+  { index: 32, field: 'swz_num', label: '商务座' },
+  { index: 33, field: 'srrb_num', label: '动卧' },
+]
+
+const TRAIN_CODE_RE = /^[GDCZTKYLSF]\d{1,5}[A-Z]?$/i
+const HHMM_RE = /^\d{2}:\d{2}$/
+
+export const TRAIN_QUERY_PARSE_SCHEMA = 'gotry_session_train_parse.v1' as const
+
+export type TrainQueryParseOutcome =
+  | { kind: 'recognized-nonempty'; trains: SessionTrainOption[] }
+  | { kind: 'recognized-empty'; trains: [] }
+  | { kind: 'malformed'; reason: string }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** 历时 "07:52" → 分钟 */
+function lishiToMin(s: string | undefined): number {
+  const m = /^(\d{1,3}):(\d{2})$/.exec((s ?? '').trim())
+  if (!m) return 0
+  if (Number(m[2]) > 59) return 0
+  return Number(m[1]) * 60 + Number(m[2])
+}
+
+function normalizeStartTrainDate(value: string): string | undefined {
+  if (!/^\d{8}$/.test(value)) return undefined
+  const normalized = `${value.slice(0, 4)}-${value.slice(4, 6)}-${value.slice(6, 8)}`
+  const parsed = new Date(`${normalized}T00:00:00.000Z`)
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== normalized) return undefined
+  return normalized
+}
+
+/** 行级签名:车次码形态 + 时刻形态不符即整行跳过(索引漂移 fail-visible,不造数) */
+function rowToOption(row: string, stationMap: Record<string, unknown> | undefined, entryUrl: string): SessionTrainOption | null {
+  const f = row.split('|')
+  if (f.length < 34) return null
+  const trainCode = (f[3] ?? '').trim()
+  const depTime = (f[8] ?? '').trim()
+  const arrTime = (f[9] ?? '').trim()
+  const durationMin = lishiToMin(f[10])
+  const startTrainDateRaw = (f[13] ?? '').trim()
+  const startTrainDate = normalizeStartTrainDate(startTrainDateRaw)
+  const validHm = (value: string): boolean => HHMM_RE.test(value)
+    && Number(value.slice(0, 2)) <= 23 && Number(value.slice(3, 5)) <= 59
+  if (!TRAIN_CODE_RE.test(trainCode) || !validHm(depTime) || !validHm(arrTime)
+    || durationMin <= 0 || !startTrainDate || !(f[6] ?? '').trim() || !(f[7] ?? '').trim()) return null
+  // 官方 cN 口径:站名 = data.map[电报码](map 缺失/缺键时退电报码原样,不猜名)
+  const stationName = (code: string): string | null => {
+    if (!stationMap || !Object.prototype.hasOwnProperty.call(stationMap, code)) return code
+    const mapped = stationMap[code]
+    return typeof mapped === 'string' && mapped.trim() ? mapped.trim() : null
+  }
+  const fromStation = stationName((f[6] ?? '').trim())
+  const toStation = stationName((f[7] ?? '').trim())
+  if (!fromStation || !toStation) return null
+  const seats: Record<string, string> = {}
+  for (const b of SEAT_BUCKETS) {
+    const v = (f[b.index] ?? '').trim()
+    if (v && v !== '--') seats[b.label] = v
+  }
+  return {
+    trainCode,
+    fromStation,
+    toStation,
+    depTime,
+    arrTime,
+    durationMin,
+    startTrainDate,
+    canWebBuy: (f[11] ?? '').trim(),
+    seats,
+    jumpUrl: entryUrl,
+  }
+}
+
+/** 解析 leftTicket/query 响应的 typed outcome。
+ * recognized-empty 只代表明确存在的 data.result=[];
+ * recognized-nonempty 要求批次每一行都通过签名校验,任一畸形行即整个批次
+ * malformed,不暴露部分候选。transport/runtime failure 不在此纯解析函数伪造。
+ */
+export function parseLeftTicketQueryResult(body: string, entryUrl: string, opts: { maxItems?: number } = {}): TrainQueryParseOutcome {
+  let raw: unknown
+  try {
+    raw = JSON.parse(body) as unknown
+  } catch {
+    return { kind: 'malformed', reason: 'response body is not valid JSON' }
+  }
+  if (!isRecord(raw) || !isRecord(raw.data)) return { kind: 'malformed', reason: 'response root/data is not an object' }
+  const rows = raw.data.result
+  if (!Array.isArray(rows)) return { kind: 'malformed', reason: 'data.result is not an array' }
+  if (raw.data.map !== undefined && !isRecord(raw.data.map)) {
+    return { kind: 'malformed', reason: 'data.map is not an object' }
+  }
+  if (rows.length === 0) return { kind: 'recognized-empty', trains: [] }
+  const map = raw.data.map as Record<string, unknown> | undefined
+  const out: SessionTrainOption[] = []
+  for (const r of rows) {
+    if (typeof r !== 'string') return { kind: 'malformed', reason: 'data.result contains a non-string row' }
+    const opt = rowToOption(r, map, entryUrl)
+    if (!opt) return { kind: 'malformed', reason: 'data.result contains a malformed or unrecognized row' }
+    if (out.length < (opts.maxItems ?? 30)) out.push(opt)
+  }
+  return { kind: 'recognized-nonempty', trains: out }
+}
+
+/** 兼容旧调用方:typed outcome 之外仍保留旧的数组投影,错误与 genuine empty 均为 []。 */
+export function parseLeftTicketQuery(body: string, entryUrl: string, opts: { maxItems?: number } = {}): SessionTrainOption[] {
+  const outcome = parseLeftTicketQueryResult(body, entryUrl, opts)
+  return outcome.kind === 'recognized-nonempty' ? outcome.trains : []
+}
+
+/** Positive availability is deliberately a small closed set, not canWebBuy alone. */
+export function hasRecognizedAvailableSeat(option: SessionTrainOption): boolean {
+  return Object.values(option.seats).some(value => value === '有' || /^[1-9]\d*$/.test(value))
+}

package/ts/capabilities/session/benchmark.ts

@@ -0,0 +1,276 @@
+/**
+ * Session 双源字段合同与 fixture 评分器。
+ *
+ * 只处理已经脱敏、结构化的证据；不打开浏览器、不读登录态，也不执行任何写操作。
+ */
+
+export type SessionEvidenceVerdict = 'hit' | 'miss' | 'error' | 'challenged' | 'cooldown' | 'needs-login' | 'needs-attach' | 'needs-extension'
+
+export const SESSION_BENCHMARK_SCHEMA_VERSION = 'session-double-source.v1' as const
+export const SESSION_FIELD_ACCURACY_THRESHOLD = 0.9
+export const REQUIRED_COMPARABLE_FIELDS = [
+  'query_id',
+  'route_segments',
+  'journey_type',
+  'route_segments[].departure_at',
+  'route_segments[].arrival_at',
+  'route_segments[].transport_number',
+  'currency',
+  'price',
+  'source',
+  'fetched_at',
+  'verdict',
+] as const
+
+export interface SessionComparableSegment {
+  from: string
+  to: string
+  departure_at: string
+  arrival_at: string
+  transport_number: string
+}
+
+export interface SessionComparableRecord {
+  query_id: string
+  route_segments: SessionComparableSegment[]
+  journey_type: 'direct' | 'transfer'
+  currency: string
+  price: number
+  /** 具体通道标识,如 flyai / ctrip-flight;official/session 角色由双源输入位置表达。 */
+  source: string
+  fetched_at: string
+  verdict: SessionEvidenceVerdict
+  latency_ms: number
+  read_guard_blocked: number
+}
+
+export interface SessionFixtureScore {
+  pass: boolean
+  threshold: number
+  correct: number
+  total: number
+  accuracy: number
+  missing: string[]
+  incorrect: string[]
+  fixture_errors: string[]
+}
+
+interface ComparableRecordInput {
+  query_id?: unknown
+  route_segments?: Array<Partial<SessionComparableSegment>>
+  journey_type?: unknown
+  currency?: unknown
+  price?: unknown
+  source?: unknown
+  fetched_at?: unknown
+  verdict?: unknown
+  latency_ms?: unknown
+  read_guard_blocked?: unknown
+}
+
+interface FieldComparison {
+  path: string
+  expected: unknown
+  actual: unknown
+}
+
+function isMissing(value: unknown): boolean {
+  return value === undefined || value === null || (typeof value === 'string' && value.trim() === '')
+}
+
+function sameValue(left: unknown, right: unknown): boolean {
+  if (typeof left !== typeof right) return false
+  return typeof left === 'number' && typeof right === 'number'
+    ? Object.is(left, right)
+    : left === right
+}
+
+function sameComparison(row: FieldComparison): boolean {
+  if (/\.(?:departure_at|arrival_at)$/.test(row.path)
+    && typeof row.expected === 'string'
+    && typeof row.actual === 'string') {
+    const expectedAt = Date.parse(row.expected)
+    const actualAt = Date.parse(row.actual)
+    if (Number.isFinite(expectedAt) && Number.isFinite(actualAt)) return expectedAt === actualAt
+  }
+  return sameValue(row.expected, row.actual)
+}
+
+function fixtureComparisons(expected: SessionComparableRecord, actual: ComparableRecordInput): FieldComparison[] {
+  const rows: FieldComparison[] = [
+    { path: 'query_id', expected: expected.query_id, actual: actual.query_id },
+    { path: 'route_segments.length', expected: expected.route_segments.length, actual: actual.route_segments?.length },
+    { path: 'journey_type', expected: expected.journey_type, actual: actual.journey_type },
+    { path: 'currency', expected: expected.currency, actual: actual.currency },
+    { path: 'price', expected: expected.price, actual: actual.price },
+    { path: 'source', expected: expected.source, actual: actual.source },
+    { path: 'fetched_at', expected: expected.fetched_at, actual: actual.fetched_at },
+    { path: 'verdict', expected: expected.verdict, actual: actual.verdict },
+  ]
+  for (let index = 0; index < expected.route_segments.length; index += 1) {
+    const exp = expected.route_segments[index]!
+    const act = actual.route_segments?.[index]
+    rows.push(
+      { path: `route_segments[${index}].from`, expected: exp.from, actual: act?.from },
+      { path: `route_segments[${index}].to`, expected: exp.to, actual: act?.to },
+      { path: `route_segments[${index}].departure_at`, expected: exp.departure_at, actual: act?.departure_at },
+      { path: `route_segments[${index}].arrival_at`, expected: exp.arrival_at, actual: act?.arrival_at },
+      { path: `route_segments[${index}].transport_number`, expected: exp.transport_number, actual: act?.transport_number },
+    )
+  }
+  return rows
+}
+
+export function scoreSessionFixture(
+  expected: SessionComparableRecord,
+  actual: ComparableRecordInput,
+  threshold = SESSION_FIELD_ACCURACY_THRESHOLD,
+): SessionFixtureScore {
+  const rows = fixtureComparisons(expected, actual)
+  const fixtureErrors = [
+    ...rows.filter((row) => isMissing(row.expected)).map((row) => row.path),
+    ...requiredMissing(expected),
+  ]
+  const missing: string[] = []
+  const incorrect: string[] = []
+  let correct = 0
+  for (const row of rows) {
+    if (isMissing(row.actual)) {
+      missing.push(row.path)
+    } else if (!sameValue(row.expected, row.actual)) {
+      incorrect.push(row.path)
+    } else {
+      correct += 1
+    }
+  }
+  const total = rows.length
+  const accuracy = total > 0 ? correct / total : 0
+  return {
+    pass: fixtureErrors.length === 0 && accuracy >= threshold,
+    threshold,
+    correct,
+    total,
+    accuracy,
+    missing,
+    incorrect,
+    fixture_errors: [...new Set(fixtureErrors)],
+  }
+}
+
+export type DoubleSourceState =
+  | 'comparable'
+  | 'divergent'
+  | 'waiting_attach'
+  | 'waiting_login'
+  | 'waiting_extension'
+  | 'challenge_stop'
+  | 'guard_violation'
+  | 'source_unavailable'
+  | 'invalid_contract'
+
+export interface DoubleSourceEvaluation {
+  state: DoubleSourceState
+  retry_allowed: boolean
+  quota_disposition: 'evidence_ready' | 'no_spend_waiting_user' | 'no_spend_stop'
+  mismatches: string[]
+  missing: string[]
+  price_delta?: number
+}
+
+function isIsoTimestamp(value: string): boolean {
+  return value.trim() !== '' && Number.isFinite(Date.parse(value))
+}
+
+function requiredMissing(record: SessionComparableRecord): string[] {
+  const missing: string[] = []
+  if (!record.query_id.trim()) missing.push('query_id')
+  if (record.route_segments.length === 0) missing.push('route_segments')
+  if (!record.currency.trim()) missing.push('currency')
+  if (!(record.price > 0)) missing.push('price')
+  if (!record.source.trim()) missing.push('source')
+  if (!isIsoTimestamp(record.fetched_at)) missing.push('fetched_at')
+  if (record.journey_type === 'direct' && record.route_segments.length !== 1) missing.push('journey_type/route_segments')
+  if (record.journey_type === 'transfer' && record.route_segments.length < 2) missing.push('journey_type/route_segments')
+  for (let index = 0; index < record.route_segments.length; index += 1) {
+    const segment = record.route_segments[index]!
+    if (!segment.from.trim()) missing.push(`route_segments[${index}].from`)
+    if (!segment.to.trim()) missing.push(`route_segments[${index}].to`)
+    if (!isIsoTimestamp(segment.departure_at)) missing.push(`route_segments[${index}].departure_at`)
+    if (!isIsoTimestamp(segment.arrival_at)) missing.push(`route_segments[${index}].arrival_at`)
+    if (!segment.transport_number.trim()) missing.push(`route_segments[${index}].transport_number`)
+  }
+  return missing
+}
+
+function baseEvaluation(
+  state: DoubleSourceState,
+  quotaDisposition: DoubleSourceEvaluation['quota_disposition'],
+  extra: Partial<Pick<DoubleSourceEvaluation, 'mismatches' | 'missing' | 'price_delta'>> = {},
+): DoubleSourceEvaluation {
+  return {
+    state,
+    retry_allowed: false,
+    quota_disposition: quotaDisposition,
+    mismatches: extra.mismatches ?? [],
+    missing: extra.missing ?? [],
+    ...(extra.price_delta === undefined ? {} : { price_delta: extra.price_delta }),
+  }
+}
+
+function alignmentComparisons(official: SessionComparableRecord, session: SessionComparableRecord): FieldComparison[] {
+  const rows: FieldComparison[] = [
+    { path: 'query_id', expected: official.query_id, actual: session.query_id },
+    { path: 'route_segments.length', expected: official.route_segments.length, actual: session.route_segments.length },
+    { path: 'journey_type', expected: official.journey_type, actual: session.journey_type },
+    { path: 'currency', expected: official.currency, actual: session.currency },
+  ]
+  const comparableSegments = Math.min(official.route_segments.length, session.route_segments.length)
+  for (let index = 0; index < comparableSegments; index += 1) {
+    const exp = official.route_segments[index]!
+    const act = session.route_segments[index]!
+    rows.push(
+      { path: `route_segments[${index}].from`, expected: exp.from, actual: act.from },
+      { path: `route_segments[${index}].to`, expected: exp.to, actual: act.to },
+      { path: `route_segments[${index}].departure_at`, expected: exp.departure_at, actual: act.departure_at },
+      { path: `route_segments[${index}].arrival_at`, expected: exp.arrival_at, actual: act.arrival_at },
+      { path: `route_segments[${index}].transport_number`, expected: exp.transport_number, actual: act.transport_number },
+    )
+  }
+  return rows
+}
+
+export function evaluateDoubleSource(input: {
+  official?: SessionComparableRecord
+  session?: SessionComparableRecord
+}): DoubleSourceEvaluation {
+  const official = input.official
+  const session = input.session
+  if (session?.verdict === 'challenged' || official?.verdict === 'challenged') {
+    return baseEvaluation('challenge_stop', 'no_spend_stop')
+  }
+  if ((session?.read_guard_blocked ?? 0) !== 0 || (official?.read_guard_blocked ?? 0) !== 0) {
+    return baseEvaluation('guard_violation', 'no_spend_stop')
+  }
+  if (!session) return baseEvaluation('source_unavailable', 'no_spend_stop')
+  if (session.verdict === 'needs-attach') return baseEvaluation('waiting_attach', 'no_spend_waiting_user')
+  // 扩展车道(2026-08-29 PRIMARY 传输)未就绪:与 waiting-* 同族 no-spend,等待用户一次性安装
+  if (session.verdict === 'needs-extension') return baseEvaluation('waiting_extension', 'no_spend_waiting_user')
+  if (session.verdict === 'needs-login') return baseEvaluation('waiting_login', 'no_spend_waiting_user')
+  if (!official || official.verdict !== 'hit' || session.verdict !== 'hit') {
+    return baseEvaluation('source_unavailable', 'no_spend_stop')
+  }
+  const missing = [
+    ...requiredMissing(official).map((path) => `official.${path}`),
+    ...requiredMissing(session).map((path) => `session.${path}`),
+  ]
+  if (missing.length > 0) {
+    return baseEvaluation('invalid_contract', 'no_spend_stop', { missing })
+  }
+  const mismatches = alignmentComparisons(official, session)
+    .filter((row) => !sameComparison(row))
+    .map((row) => row.path)
+  return baseEvaluation(mismatches.length === 0 ? 'comparable' : 'divergent', 'evidence_ready', {
+    mismatches,
+    price_delta: session.price - official.price,
+  })
+}