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

package/ts/capabilities/session/health-watch.ts

@@ -0,0 +1,264 @@
+/**
+ * 扩展健康检查 + 自动重放(issue #21 onboarding UX,P3.6 gotry-session-onboarding-goal,
+ * RFC docs/rfc/user-session-data-rfc.md §3.3)。
+ *
+ * 动机:首次 `sessionFlightSearch` 遇 `needs-extension` 时,旧版要求用户装完扩展后**自己重跑命令**;
+ * 本模块把「用户手工重跑」改成「后台有界轮询 + 扩展一就位自动重放同一 query_id」——
+ * 用户装完扩展零后续动作,gotry 自己感知到 ready 后立刻跑同一条 query。
+ *
+ * 形态:
+ * - `startExtensionHealthWatch({ timeoutMs, intervalMs, probe })` 启后台轮询。
+ *   probe 是异步检测函数(默认 GET http://127.0.0.1:{port}/status,扩展 ≤30s 心跳一次,
+ *   1.5 倍容差 EXTENSION_CONNECTED_WINDOW_MS=45s;§38 已经验证扩展心跳节奏)。
+ * - 命中 ready → 调用方自动重放(query_id / args 不变;同一证据文件覆盖)。
+ * - 超时(timeoutMs 默认 120_000)→ 返回 'timeout',调用方降级回 `needs-extension` 错误面。
+ *
+ * 离线合同(run-all §40 onboarding-tests 5/5):
+ * - 三时序分支:probe 0ms ready / 中途 ready / 120s+1ms 超时;
+ * - 同 query_id 重放语义(参数透传);
+ * - 取消语义(timeoutMs=0 立即 timeout;cancel() 立即返回 'cancelled');
+ * - 重放上限(防止 watch 反复 ready/抖动导致无限重放;maxRetries 默认 1)。
+ *
+ * 纪律:
+ * - 不引 GUI 依赖;只 spawn `node:http` 探活(已经在扩展桥验证过,§38 24 断言覆盖);
+ * - 不持锁、不轮询文件、不读 dsh-runtime 共享状态;
+ * - 不污染扩展桥 single-instance;probe 走独立短连接。
+ */
+
+import { request } from 'node:http'
+import {
+  BRIDGE_PORTS,
+  EXTENSION_CONNECTED_WINDOW_MS,
+  type SessionBridgeOptions,
+} from './extension-bridge.ts'
+
+export type HealthWatchOutcome =
+  | { ready: true; attempts: number; waitedMs: number }
+  | { ready: false; reason: 'timeout' | 'cancelled'; attempts: number; waitedMs: number }
+
+export interface HealthWatchOptions extends SessionBridgeOptions {
+  /** 最长等多久(默认 120s);0 = 立即 timeout(便于测试) */
+  timeoutMs?: number
+  /** 探活间隔(默认 5s);必须 < EXTENSION_CONNECTED_WINDOW_MS,否则抖动期漏心跳 */
+  intervalMs?: number
+  /** 探活函数:返回 true 即视为扩展就绪(测试可注入 fake probe)。
+   * 默认走双因子:① 心跳 `/status` extensionConnected === true
+   * + ② 业务探针 cookie-names 真回包(timeout 5s);二者同时通过才算真 ready。
+   * 仅心跳通过但 cookie-names 失败 = 扩展 SW 跑着但 chrome.cookies 权限缺 → 不算 ready。 */
+  probe?: () => Promise<boolean>
+  /** 最大重放次数(默认 1);防止 ready 抖动反复触发 query 重放 */
+  maxRetries?: number
+  /** 取消信号(可选)——给调用方提供立刻终止 watch 的逃生口 */
+  signal?: AbortSignal
+  /** 时间源(测试可注入 fake clock) */
+  now?: () => number
+  /**
+   * 是否启用业务探针(cookie-names)。wizard 默认 true(用户刚装扩展,首次需要双因子验证);
+   * 上线 session 检索可传 false(快速心跳足矣,业务探针会另发一次请求)。
+   */
+  businessProbe?: boolean
+}
+
+export interface HealthWatchController {
+  /** Promise:resolve 时扩展已 ready,可执行重放 */
+  waitReady(): Promise<HealthWatchOutcome>
+  /** 立刻取消;waitReady 立即 resolve {ready:false, reason:'cancelled'} */
+  cancel(reason?: string): void
+  /** 当前 ready 次数(供诊断/审计) */
+  readonly readyCount: number
+}
+
+interface InternalState {
+  cancelled: boolean
+  readyCount: number
+  resolveOutcome: ((o: HealthWatchOutcome) => void) | null
+}
+
+/**
+ * 双因子 probe(默认):心跳 + 业务探针(cookie-names)。
+ * 心跳通过只能证 SW 跑着;业务探针通过证 chrome.cookies 权限齐——二者同过才算
+ * 扩展真正 ready。wizard 必须双因子(用户刚装的扩展可能权限不全),上线 session
+ * 检索可传 `businessProbe:false` 跳业务探针(避免每次检索额外打一次 cookie-names)。
+ *
+ * 不直接 import extension-channel.ts(避免环)—用 dynamic import 懒拿。
+ */
+export async function combinedProbe(opts: HealthWatchOptions, businessProbe: boolean): Promise<boolean> {
+  if (!(await defaultProbe(opts))) return false
+  if (!businessProbe) return true
+  try {
+    // 动态 import 避免 health-watch ↔ extension-channel 双向环
+    const channel = await import('./extension-channel.ts')
+    const bridge = await import('./extension-bridge.ts')
+    // 双因子探针需要常驻桥(wizard 期间):keepBridge=true 透传到 bridge 单例
+    bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true })
+    // 心跳已 ready(刚 defaultProbe 通过)= 扩展一定在线;cookie-names 超时给 8s,
+    // 比心跳间隔 5s 长——保证 tick 间不会撞死 cookie job
+    const cookie = await channel.extensionCookieNames({
+      site: 'ctrip-flight',
+      domain: 'ctrip.com',
+      ticketNames: ['cticket', 'uid'],
+      timeoutMs: 8_000,
+    })
+    // cookie-names.ok = true 表示扩展 SW 真能调 chrome.cookies.getAll(权限齐全);
+    // cookie-names.ok = true + names = [] 也算 ok(用户没登携程但扩展权限齐)。
+    // cookie-names.ok = false 分两类:bridge-unavailable/extension-not-connected(心跳 false 时) / timeout(扩展没回包)——
+    // 后者更可能是 SW 卡了,不应当 ready。但 wizard 必须严格:让用户明确知道权限缺或登录缺。
+    return cookie.ok
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 默认 probe:GET http://127.0.0.1:{port}/status,看 extensionConnected: true
+ * (扩展心跳 ≤30s 一刷,窗口 EXTENSION_CONNECTED_WINDOW_MS=45s 容差)。
+ * 不在端口池内挑一个试——端口是已启动桥的事实,直接拿 opts.ports[0] 或 8791。
+ * 测试可注入 fake probe 跳过网络。
+ */
+export async function defaultProbe(opts: HealthWatchOptions): Promise<boolean> {
+  const ports = opts.ports ?? [...BRIDGE_PORTS]
+  for (const port of ports) {
+    const ok = await new Promise<boolean>((resolve) => {
+      const req = request(
+        { host: '127.0.0.1', port, path: '/status', method: 'GET', timeout: 2_000 },
+        (res) => {
+          if (!res.statusCode || res.statusCode >= 400) { resolve(false); return }
+          let buf = ''
+          res.setEncoding('utf8')
+          res.on('data', (c: string) => { buf += c })
+          res.on('end', () => {
+            try {
+              const payload = JSON.parse(buf) as { extensionConnected?: boolean }
+              resolve(payload.extensionConnected === true)
+            } catch { resolve(false) }
+          })
+          res.on('error', () => resolve(false))
+        },
+      )
+      req.on('error', () => resolve(false))
+      req.on('timeout', () => { req.destroy(); resolve(false) })
+      req.end()
+    })
+    if (ok) return true
+  }
+  return false
+}
+
+export function startExtensionHealthWatch(opts: HealthWatchOptions = {}): HealthWatchController {
+  const timeoutMs = opts.timeoutMs ?? 120_000
+  const intervalMs = opts.intervalMs ?? 5_000
+  const maxRetries = opts.maxRetries ?? 1
+  const businessProbe = opts.businessProbe ?? true
+  // 关键:wizard 期间需要常驻桥(keepBridge=true 透传到 getOrCreateSessionBridge),
+  // 否则启桥后 wizard main 一退桥就退,扩展心跳发不进来。
+  // 用 dynamic import 避免与 extension-bridge 顶层环(channel 也引 bridge,但 health-watch 引 channel/bridge 双向会死循环)
+  const probe = opts.probe ?? (async () => {
+    // 先确保桥存在 + keepBridge
+    const bridge = await import('./extension-bridge.ts')
+    const created = await bridge.getOrCreateSessionBridge({ keepBridge: opts.keepBridge === true, ports: opts.ports })
+    // The default path must keep scanning the canonical pool: another GoTry
+    // process may already own the extension-connected bridge. An explicit
+    // port override is an isolation boundary, so probe only the bridge that
+    // this process actually bound (including an ephemeral `0` request).
+    const probeOpts = created.ok && opts.ports
+      ? { ...opts, ports: [created.bridge.port] }
+      : opts
+    return combinedProbe(probeOpts, businessProbe)
+  })
+  const now = opts.now ?? Date.now
+  const state: InternalState = { cancelled: false, readyCount: 0, resolveOutcome: null }
+
+  const finish = (outcome: HealthWatchOutcome): void => {
+    if (state.resolveOutcome) {
+      const resolve = state.resolveOutcome
+      state.resolveOutcome = null
+      resolve(outcome)
+    }
+  }
+
+  // 取消信号 -> 立刻 timeout-ish 终态(不进 ready 路径)
+  const onAbort = (): void => {
+    state.cancelled = true
+    finish({ ready: false, reason: 'cancelled', attempts: state.readyCount, waitedMs: 0 })
+  }
+  opts.signal?.addEventListener('abort', onAbort, { once: true })
+
+  const waitReady = (): Promise<HealthWatchOutcome> => new Promise<HealthWatchOutcome>((resolve) => {
+    if (state.cancelled) { resolve({ ready: false, reason: 'cancelled', attempts: 0, waitedMs: 0 }); return }
+    if (timeoutMs === 0) { resolve({ ready: false, reason: 'timeout', attempts: 0, waitedMs: 0 }); return }
+    state.resolveOutcome = resolve
+    const deadline = now() + timeoutMs
+    let attempts = 0
+    let waitedMs = 0
+
+    const tick = async (): Promise<void> => {
+      if (state.cancelled || state.resolveOutcome === null) return
+      attempts += 1
+      try {
+        const ready = await probe()
+        if (ready && !state.cancelled) {
+          state.readyCount += 1
+          waitedMs = timeoutMs - Math.max(0, deadline - now())
+          // readyCount > maxRetries → 视为抖动,继续等(避免一次性重放洪流)
+          if (state.readyCount <= maxRetries) {
+            finish({ ready: true, attempts, waitedMs: waitedMs > 0 ? waitedMs : 0 })
+            return
+          }
+        }
+      } catch { /* probe 失败继续轮询,不挡主流程 */ }
+      waitedMs = timeoutMs - Math.max(0, deadline - now())
+      if (now() >= deadline) {
+        finish({ ready: false, reason: 'timeout', attempts, waitedMs })
+        return
+      }
+      // 间隔 = intervalMs;若剩余时间 < intervalMs 则最后一次等剩余时间
+      const remaining = deadline - now()
+      const delay = Math.min(intervalMs, Math.max(0, remaining))
+      if (delay <= 0) {
+        finish({ ready: false, reason: 'timeout', attempts, waitedMs })
+        return
+      }
+      setTimeout(tick, delay)
+    }
+    void tick()
+  })
+
+  return {
+    waitReady,
+    cancel: () => onAbort(),
+    get readyCount() { return state.readyCount },
+  }
+}
+
+/**
+ * 自动重放 wrapper:首次调用走 fetch(返回 needs-extension) → 启 watch →
+ * 扩展 ready → 同 query 重放。语义:用户侧**只看到一条 query 的最终结果**;
+ * 中间产物(query_id 标记 + 尝试次数)落 evidence 文件,便于离线追溯。
+ *
+ * 这是 §3.3「用户零手工重跑」的对外契约:调用方把 fetch 包成 withAutoRetryOnExtension,
+ * 用户装完扩展→自然出结果;用户不装→等 120s 后返回 needs-extension,而不是「再跑一次试试」。
+ */
+export async function withAutoRetryOnExtension<T>(args: {
+  fetch: () => Promise<T>
+  isExtensionNeeded: (result: T) => boolean
+  /** watch 配置(测试可注入 fake probe) */
+  watch?: HealthWatchOptions
+  /** 重放 fetcher(默认复用 fetch) */
+  retry?: () => Promise<T>
+}): Promise<{ result: T; retried: boolean; attempts: number; outcome: HealthWatchOutcome }> {
+  const first = await args.fetch()
+  if (!args.isExtensionNeeded(first)) {
+    return { result: first, retried: false, attempts: 1, outcome: { ready: true, attempts: 0, waitedMs: 0 } }
+  }
+  const watch = startExtensionHealthWatch(args.watch ?? {})
+  const outcome = await watch.waitReady()
+  if (!outcome.ready) {
+    return { result: first, retried: false, attempts: 1, outcome }
+  }
+  const retriedResult = await (args.retry ?? args.fetch)()
+  return { result: retriedResult, retried: true, attempts: 2, outcome }
+}
+
+/** 留作运行时只读检查,防止扩展心跳节律假设漂移(§38 防漂移同款语义) */
+export const HEALTH_WATCH_INTERVAL_FLOOR_MS = 1_000
+export const HEALTH_WATCH_INTERVAL_CEIL_MS = EXTENSION_CONNECTED_WINDOW_MS - 1_000

package/ts/capabilities/session/read-guard.ts

@@ -0,0 +1,141 @@
+/**
+ * ReadGuard:会话检索面的只读物理隔离(RFC docs/rfc/user-session-data-rfc.md §3.3)。
+ *
+ * 写不是「被禁止的行为」,是「不存在的原语」——WriteGate(L0-L4)的检索态前置:
+ *   ① 网络层:route 拦截——命中硬支付模式(任意方法)或写方法+写URL模式 → abort + 审计落盘;
+ *   ② DOM 层:提交类按钮文本黑名单,从快照/断言文本中剔除(模型看不到可点的提交件);
+ *   ③ fail-closed:guard 未装上,session transport 不允许导航(openSession 装不上即整会话失败)。
+ *
+ * 审计:append-only JSONL(session-incidents.jsonl,对齐 incident-log 惯例),隔离 stateRoot。
+ * 注意:搜索接口多为 POST(如携程 batchSearch),因此写判定必须「方法 × URL 模式」双因子,
+ * 不能一刀切禁 POST——batchSearch 不含写词,放行。
+ */
+
+import { mkdirSync, appendFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** 硬支付模式:任意方法(含 GET)都视为写——进支付/收银面本身就是风险 */
+const HARD_PAY_RE = /\/(pay|payment|cashier)(\/|\?|$)/i
+/** 驼峰复合写词(OTA 常见 /submitOrder、/createOrder):段式正则漏接,单列 */
+const WRITE_COMPOUND_RE = /(submitorder|createorder|placeorder|cancelorder|refundorder|orderconfirm|orderpay|confirmpay)/i
+/** 写词 URL 模式:仅在写方法(POST/PUT/DELETE/PATCH)下触发 */
+const WRITE_URL_RE = /\/(order|orders|submit|trade|booking|book|purchase|buy|create|cancel|refund)(\/|\?|$)/i
+const WRITE_METHODS = new Set(['POST', 'PUT', 'DELETE', 'PATCH'])
+/** DOM 提交件文本黑名单(§3.3-②):命中即从可交互面剔除 */
+export const SUBMIT_TEXT_RE = /下单|去支付|支付|预订|订票|购买|提交订单|确认订单/
+
+/** 网络层写判定(纯函数,测试锚点) */
+export function classifyRequest(method: string, url: string): 'allow' | 'block' {
+  if (HARD_PAY_RE.test(url) || WRITE_COMPOUND_RE.test(url)) return 'block'
+  if (WRITE_METHODS.has(method.toUpperCase()) && WRITE_URL_RE.test(url)) return 'block'
+  return 'allow'
+}
+
+/** DOM 层提交件过滤(纯函数,测试锚点):true=剔除 */
+export function isSubmitText(text: string): boolean {
+  return SUBMIT_TEXT_RE.test(text ?? '')
+}
+
+export interface GuardAuditEntry {
+  ts: string
+  kind: 'blocked-write-request'
+  method: string
+  url: string
+}
+
+export interface ReadGuardHandle {
+  /** 被拦截的写请求数(测试断言锚点) */
+  blockedCount(): number
+  /** 经手的请求总数 */
+  requestCount(): number
+}
+
+export interface RoutableContext {
+  route(glob: string, handler: (route: { request(): { method(): string; url(): string }; abort(code?: string): Promise<void>; continue(): Promise<void> }) => Promise<void>): Promise<void>
+}
+
+/**
+ * 装上网络层守卫(fail-closed 的「closed」在调用方:openSession 装不上 guard 即失败,不给无 guard 的会话)。
+ * 审计落 auditPath(JSONL append);auditPath 缺省不落盘(仅内存计数)。
+ */
+export async function attachReadGuard(ctx: RoutableContext, auditPath?: string): Promise<ReadGuardHandle> {
+  let blocked = 0
+  let total = 0
+  await ctx.route('**/*', async (route) => {
+    const req = route.request()
+    total += 1
+    const verdict = classifyRequest(req.method(), req.url())
+    if (verdict === 'block') {
+      blocked += 1
+      if (auditPath) {
+        const entry: GuardAuditEntry = { ts: new Date().toISOString(), kind: 'blocked-write-request', method: req.method(), url: req.url().slice(0, 400) }
+        try {
+          mkdirSync(dirname(auditPath), { recursive: true })
+          appendFileSync(auditPath, JSON.stringify(entry) + '\n')
+        } catch { /* 审计失败不阻塞拦截本身 */ }
+      }
+      await route.abort('blockedbyclient')
+      return
+    }
+    await route.continue()
+  })
+  return {
+    blockedCount: () => blocked,
+    requestCount: () => total,
+  }
+}
+
+/* ============ puppeteer-core 适配(2026-08-28 传输层定案:Chrome 144+ 调试服务与 playwright 不兼容) ============ */
+
+interface PpRequest {
+  method(): string
+  url(): string
+  continue(): Promise<void>
+  abort(code?: string): Promise<void>
+}
+interface PpPage {
+  setRequestInterception(on: boolean): Promise<void>
+  on(event: 'request', handler: (req: PpRequest) => void): void
+}
+interface PpBrowser {
+  pages(): Promise<PpPage[]>
+  on(event: string, handler: (target: { type(): string; page(): Promise<PpPage> }) => void): unknown
+}
+
+/**
+ * puppeteer 版守卫:对既有页面与新建页面全部开启请求拦截,写请求 abort + 审计。
+ * 与 playwright 版共用 classifyRequest 判定与审计条目(单一事实源)。
+ */
+export async function attachReadGuardPuppeteer(browser: PpBrowser, auditPath?: string): Promise<ReadGuardHandle> {
+  let blocked = 0
+  let total = 0
+  const wire = (page: PpPage): void => {
+    void (async () => {
+      try {
+        await page.setRequestInterception(true)
+        page.on('request', async (req) => {
+          total += 1
+          const verdict = classifyRequest(req.method(), req.url())
+          if (verdict === 'block') {
+            blocked += 1
+            if (auditPath) {
+              const entry: GuardAuditEntry = { ts: new Date().toISOString(), kind: 'blocked-write-request', method: req.method(), url: req.url().slice(0, 400) }
+              try {
+                mkdirSync(dirname(auditPath), { recursive: true })
+                appendFileSync(auditPath, JSON.stringify(entry) + '\n')
+              } catch { /* 审计失败不阻塞拦截本身 */ }
+            }
+            await req.abort('blockedbyclient').catch(() => { /* 目标已销毁等竞态 */ })
+            return
+          }
+          await req.continue().catch(() => { /* 竞态容忍 */ })
+        })
+      } catch { /* 已关闭的 target 容忍 */ }
+    })()
+  }
+  for (const p of await browser.pages()) wire(p)
+  browser.on('targetcreated', (t) => {
+    if (t.type() === 'page') void t.page().then(wire).catch(() => { /* ignore */ })
+  })
+  return { blockedCount: () => blocked, requestCount: () => total }
+}

package/ts/capabilities/session/static-flight-golden.ts

@@ -0,0 +1,209 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { SessionComparableRecord, SessionComparableSegment } from './benchmark.ts'
+
+export type GoldenSource = 'manual' | 'flyai' | 'static'
+
+export interface StaticFlightRouteLeg {
+  from_iata: string
+  to_iata: string
+  carrier_codes: string[]
+}
+
+export interface StaticFlightRoute {
+  query_id: string
+  from_city: string
+  to_city: string
+  route_kind: 'direct' | 'transfer'
+  legs: StaticFlightRouteLeg[]
+}
+
+export interface StaticFlightSnapshot {
+  schema_version: 'sf-static-routes.v1'
+  source: {
+    name: string
+    url: string
+    revision: string
+    license: string
+    retrieved_at: string
+    limitations: string[]
+  }
+  routes: StaticFlightRoute[]
+}
+
+export interface StaticGoldenResolution {
+  requested_source: 'static'
+  effective_source: 'static-openflights+manual-band' | 'manual-golden'
+  record: SessionComparableRecord
+  fallback_reason?: string
+  estimated_fields: string[]
+  provenance: {
+    route_source: string
+    route_revision: string
+    route_license: string
+    band_source: 'sf-golden-manifest.json'
+  }
+}
+
+export function parseGoldenSource(args: string[]): GoldenSource {
+  const raw = args.find((arg) => arg.startsWith('--golden='))?.slice('--golden='.length) ?? 'manual'
+  if (raw === 'manual' || raw === 'flyai' || raw === 'static') return raw
+  throw new Error(`不支持的 golden vendor: ${raw}`)
+}
+
+export function loadStaticFlightSnapshot(
+  path = join(import.meta.dirname, '..', '..', 'data', 'sf-static-routes.json'),
+): StaticFlightSnapshot {
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+  if (!isRecord(parsed) || parsed.schema_version !== 'sf-static-routes.v1') {
+    throw new Error(`invalid static snapshot schema_version: ${String(isRecord(parsed) ? parsed.schema_version : undefined)}`)
+  }
+  const source = parsed.source
+  if (!isRecord(source)
+    || !['name', 'url', 'revision', 'license', 'retrieved_at'].every((key) => typeof source[key] === 'string')
+    || !Array.isArray(source.limitations)
+    || !source.limitations.every((item) => typeof item === 'string')) {
+    throw new Error('invalid static snapshot source')
+  }
+  if (!Array.isArray(parsed.routes) || !parsed.routes.every(isStaticFlightRoute)) {
+    throw new Error('invalid static snapshot routes')
+  }
+  return parsed as unknown as StaticFlightSnapshot
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isStaticFlightRoute(value: unknown): boolean {
+  if (!isRecord(value)
+    || typeof value.query_id !== 'string'
+    || typeof value.from_city !== 'string'
+    || typeof value.to_city !== 'string'
+    || (value.route_kind !== 'direct' && value.route_kind !== 'transfer')
+    || !Array.isArray(value.legs)
+    || value.legs.length === 0) return false
+  return value.legs.every((leg) => isRecord(leg)
+    && typeof leg.from_iata === 'string'
+    && typeof leg.to_iata === 'string'
+    && Array.isArray(leg.carrier_codes)
+    && leg.carrier_codes.every((carrier) => typeof carrier === 'string'))
+}
+
+function provenance(snapshot?: StaticFlightSnapshot): StaticGoldenResolution['provenance'] {
+  return {
+    route_source: snapshot?.source.url ?? '',
+    route_revision: snapshot?.source.revision ?? '',
+    route_license: snapshot?.source.license ?? '',
+    band_source: 'sf-golden-manifest.json',
+  }
+}
+
+function formatWithOffset(timestampMs: number, offset: string): string {
+  const sign = offset.startsWith('-') ? -1 : 1
+  const [hours, minutes] = offset.slice(1).split(':').map(Number)
+  const offsetMinutes = sign * ((hours ?? 0) * 60 + (minutes ?? 0))
+  const local = new Date(timestampMs + offsetMinutes * 60_000).toISOString().slice(0, 19)
+  return `${local}${offset}`
+}
+
+function buildSegments(
+  query: { from: string; to: string },
+  route: StaticFlightRoute,
+  manualSegment: SessionComparableSegment,
+): SessionComparableSegment[] | null {
+  if (route.route_kind === 'direct' && route.legs.length === 1) {
+    return [{
+      from: query.from,
+      to: query.to,
+      departure_at: manualSegment.departure_at,
+      arrival_at: manualSegment.arrival_at,
+      transport_number: `${route.legs[0]!.carrier_codes[0]}-STATIC`,
+    }]
+  }
+  if (route.route_kind !== 'transfer' || route.legs.length !== 2) return null
+  const departureMs = Date.parse(manualSegment.departure_at)
+  const arrivalMs = Date.parse(manualSegment.arrival_at)
+  if (!Number.isFinite(departureMs) || !Number.isFinite(arrivalMs) || arrivalMs <= departureMs) return null
+  const offset = manualSegment.departure_at.match(/([+-]\d{2}:\d{2})$/)?.[1] ?? '+08:00'
+  const totalMinutes = Math.floor((arrivalMs - departureMs) / 60_000)
+  if (totalMinutes < 90) return null
+  const layoverMinutes = Math.min(60, Math.floor(totalMinutes / 3))
+  const travelMinutes = totalMinutes - layoverMinutes
+  const firstTravelMinutes = Math.floor(travelMinutes / 2)
+  const secondDepartureMs = arrivalMs - (travelMinutes - firstTravelMinutes) * 60_000
+  const middle = route.legs[0]!.to_iata
+  return [
+    {
+      from: query.from,
+      to: middle,
+      departure_at: manualSegment.departure_at,
+      arrival_at: formatWithOffset(departureMs + firstTravelMinutes * 60_000, offset),
+      transport_number: `${route.legs[0]!.carrier_codes[0]}-STATIC`,
+    },
+    {
+      from: middle,
+      to: query.to,
+      departure_at: formatWithOffset(secondDepartureMs, offset),
+      arrival_at: manualSegment.arrival_at,
+      transport_number: `${route.legs[1]!.carrier_codes[0]}-STATIC`,
+    },
+  ]
+}
+
+export function resolveStaticGolden(input: {
+  query: { id: string; from: string; to: string; date: string }
+  manualRecord: SessionComparableRecord
+  snapshot?: StaticFlightSnapshot
+  snapshotError?: string
+  warn?: (message: string) => void
+}): StaticGoldenResolution {
+  const route = input.snapshot?.routes.find((candidate) => candidate.query_id === input.query.id)
+  let fallbackReason: string | undefined
+  if (input.snapshotError) {
+    fallbackReason = `static snapshot unavailable: ${input.snapshotError}`
+  } else if (!route) {
+    fallbackReason = `static route missing for ${input.query.id}`
+  } else if (route.from_city !== input.query.from || route.to_city !== input.query.to) {
+    fallbackReason = `static route mismatch for ${input.query.id}`
+  } else if (route.legs.some((leg) => leg.carrier_codes.length === 0)) {
+    fallbackReason = `static carrier coverage missing for ${input.query.id}`
+  }
+
+  const manualSegment = input.manualRecord.route_segments[0]
+  const segments = !fallbackReason && route && manualSegment
+    ? buildSegments(input.query, route, manualSegment)
+    : null
+  if (!fallbackReason && !segments) fallbackReason = `static route cannot form comparable record for ${input.query.id}`
+
+  if (fallbackReason) {
+    input.warn?.(`[sf-live-benchmark] static vendor failed for ${input.query.id}: ${fallbackReason}; fallback=manual-golden`)
+    return {
+      requested_source: 'static',
+      effective_source: 'manual-golden',
+      record: input.manualRecord,
+      fallback_reason: fallbackReason,
+      estimated_fields: [],
+      provenance: provenance(input.snapshot),
+    }
+  }
+
+  return {
+    requested_source: 'static',
+    effective_source: 'static-openflights+manual-band',
+    record: {
+      ...input.manualRecord,
+      route_segments: segments!,
+      journey_type: route!.route_kind,
+      source: 'static-openflights+manual-band',
+    },
+    estimated_fields: [
+      'route_segments[].departure_at',
+      'route_segments[].arrival_at',
+      'route_segments[].transport_number',
+      'price',
+    ],
+    provenance: provenance(input.snapshot),
+  }
+}