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

package/ts/src/booking-saga.ts

@@ -0,0 +1,133 @@
+/**
+ * 预订 saga 状态机(booking_saga_fsm.v1)——issue #17 采纳三点的具名化落点。
+ *
+ * 立场(docs/booking-saga-fsm.md / ADR-17):不引入编排框架;预订 saga 的状态字母表与边表
+ * 就是账本 pending_writes(status CHECK:pending|confirmed|compensated)的显式化。
+ * 本模块是纯函数词汇层,零依赖、零行为、不接线任何 seam——M5 拍板 WriteGate 生产化时
+ * 以此为唯一状态推进词汇(具名化 = 状态与边不再散落在 SQL 字符串里)。
+ *
+ * 物理对账目标(state-ledger.ts,TS-4 基座):
+ *  - propose  = requestPendingWrite(∅ → pending,L2 只登记不执行;idem_key UNIQUE,重复提议 no-op)
+ *  - confirm  = confirmPendingWrite(pending → confirmed,L3 具名 seam 确认,携 receipt;无 receipt 则视为缺省空串)
+ *  - compensate = compensatePendingWrite(pending|confirmed → compensated,吸收态,无出边)
+ *  - 审计事件 kind:write.pending / write.confirmed / write.compensated
+ */
+
+export const BOOKING_SAGA_SCHEMA = 'booking_saga_fsm.v1'
+
+export type SagaStatus = 'pending' | 'confirmed' | 'compensated'
+export type SagaOrigin = 'none' | SagaStatus
+export type SagaTrigger = 'propose' | 'confirm' | 'compensate'
+export type SagaLedgerEvent = 'write.pending' | 'write.confirmed' | 'write.compensated'
+
+/** 状态字母表(与 pending_writes.status CHECK 约束逐字一致) */
+export const SAGA_STATUSES = ['pending', 'confirmed', 'compensated'] as const satisfies readonly SagaStatus[]
+
+export interface SagaEdge {
+  from: SagaOrigin
+  trigger: SagaTrigger
+  to: SagaStatus
+  event: SagaLedgerEvent
+  /** 边的守卫说明;物理执行在账本事务内(UNIQUE 守卫/CHECK),此处为语义面 */
+  guard: string
+}
+
+/**
+ * 边表(预订流程 FSM 的全部合法转移):
+ *  ∅ --propose--> pending --confirm--> confirmed
+ *        │             │
+ *        └---(任何状态) --compensate--> compensated(吸收态,无出边)
+ */
+export const SAGA_EDGES: ReadonlyArray<SagaEdge> = [
+  { from: 'none', trigger: 'propose', to: 'pending', event: 'write.pending', guard: 'L2 只登记不执行;idem_key UNIQUE(重复提议 no-op)' },
+  { from: 'pending', trigger: 'confirm', to: 'confirmed', event: 'write.confirmed', guard: 'L3 具名 seam 确认,必携 receipt;已确认不可再确认' },
+  { from: 'pending', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '外部写未发生,取消即终态(无补偿动作)' },
+  { from: 'confirmed', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '已发生副作用的 saga 补偿(退改),receipt 保留(COALESCE)' },
+]
+
+export type SagaRejection =
+  | 'missing-subject'
+  | 'idem-exists'
+  | 'already-confirmed'
+  | 'absorbed-compensated'
+  | 'already-compensated'
+
+/** 非边组合的拒绝理由(结构化,拒绝即不动——与账本 changes=0 同义) */
+export const SAGA_REJECTIONS: ReadonlyArray<{ from: SagaOrigin; trigger: SagaTrigger; reason: SagaRejection }> = [
+  { from: 'none', trigger: 'confirm', reason: 'missing-subject' },
+  { from: 'none', trigger: 'compensate', reason: 'missing-subject' },
+  { from: 'pending', trigger: 'propose', reason: 'idem-exists' },
+  { from: 'confirmed', trigger: 'propose', reason: 'idem-exists' },
+  { from: 'confirmed', trigger: 'confirm', reason: 'already-confirmed' },
+  { from: 'compensated', trigger: 'propose', reason: 'idem-exists' },
+  { from: 'compensated', trigger: 'confirm', reason: 'absorbed-compensated' },
+  { from: 'compensated', trigger: 'compensate', reason: 'already-compensated' },
+]
+
+export type SagaVerdict =
+  | { ok: true; from: SagaOrigin; trigger: SagaTrigger; to: SagaStatus; event: SagaLedgerEvent; guard: string; reason: null }
+  | { ok: false; from: SagaOrigin; trigger: SagaTrigger; to: null; event: null; guard: null; reason: SagaRejection }
+
+/** 触发解析:唯一归宿或结构化拒绝(预订 seam 的状态推进只许走这张表的边) */
+export function resolveSagaTrigger(origin: SagaOrigin, trigger: SagaTrigger): SagaVerdict {
+  const edge = SAGA_EDGES.find(e => e.from === origin && e.trigger === trigger)
+  if (edge) return { ok: true, from: origin, trigger, to: edge.to, event: edge.event, guard: edge.guard, reason: null }
+  const rejection = SAGA_REJECTIONS.find(e => e.from === origin && e.trigger === trigger)
+  return { ok: false, from: origin, trigger, to: null, event: null, guard: null, reason: rejection!.reason }
+}
+
+/** 触发器 → 账本事件 kind 的唯一映射(写入侧命名不再各处硬编码) */
+export const SAGA_TRIGGER_EVENT: Record<SagaTrigger, SagaLedgerEvent> = {
+  propose: 'write.pending',
+  confirm: 'write.confirmed',
+  compensate: 'write.compensated',
+}
+
+/** 账本事件 kind → 触发器(读取/审计侧);非 saga 事件返回 null */
+export function triggerOfEventKind(kind: string): SagaTrigger | null {
+  if (kind === 'write.pending') return 'propose'
+  if (kind === 'write.confirmed') return 'confirm'
+  if (kind === 'write.compensated') return 'compensate'
+  return null
+}
+
+export interface SagaAuditEvent {
+  seq?: number
+  kind: string
+  /** write.confirmed 携带的外部回执(payload.receipt) */
+  receipt?: string | null
+}
+
+/**
+ * 审计链校验(单 idem_key 的 write.* 事件序列):必须恰好走出边表的一条合法路径。
+ *  - 链以 write.pending 开头;
+ *  - confirm/compensate 至多各一次;
+ *  - compensated 之后不允许任何 saga 事件(吸收态);
+ *  - write.confirmed 的 receipt 为空(缺省/空串)即违例——L3 具名确认必携外部回执;
+ *  - 非 write.* 事件(其他域审计)穿插不计。
+ * 返回违例清单(空数组 = 链合法)。
+ */
+export function sagaTraceViolations(events: ReadonlyArray<SagaAuditEvent>): string[] {
+  const violations: string[] = []
+  let stage: SagaOrigin = 'none'
+  for (const ev of events) {
+    const trigger = triggerOfEventKind(ev.kind)
+    if (!trigger) continue
+    const verdict = resolveSagaTrigger(stage, trigger)
+    const at = `seq=${ev.seq ?? '?'} ${ev.kind}`
+    if (!verdict.ok) {
+      violations.push(`${at}: 非法(${stage} --${trigger}--> 拒绝 ${verdict.reason})`)
+      continue
+    }
+    stage = verdict.to
+    if (trigger === 'confirm' && (ev.receipt === undefined || ev.receipt === null || ev.receipt === '')) {
+      violations.push(`${at}: receipt 为空(L3 具名确认必携外部回执)`)
+    }
+  }
+  return violations
+}
+
+/** 完整合法路径集合(文档/测试共用):∅→pending→confirmed→compensated 与其前缀 */
+export function sagaLegalPaths(): ReadonlyArray<ReadonlyArray<SagaTrigger>> {
+  return [['propose'], ['propose', 'compensate'], ['propose', 'confirm'], ['propose', 'confirm', 'compensate']]
+}

package/ts/src/dsh-llm.ts

@@ -18,7 +18,25 @@ import { buildSlotSystem, flagExpiredSlots, normalizeExtraction, type TravelSlot
 const model = () => process.env['LLM_MODEL'] ?? process.env['DEEPSEEK_MODEL'] ?? 'MiniMax-M2'
 const base = () => (process.env['LLM_BASE_URL'] ?? process.env['DEEPSEEK_BASE_URL'] ?? 'https://api.minimax.io/v1').replace(/\/$/, '')
 
-async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>, json: boolean): Promise<string> {
+/**
+ * Token 用量累计器(OpenAI 兼容 usage 映射)。nightly real-LLM 成本证据(Issue #22
+ * `gotry_m3_nightly_run_v1.cost_usd`)的唯一测量来源——成本不允许凭空断言,只允许
+ * 这里实测出的 tokens × 封存价表换算;responsesMissingUsage > 0 时成本不可证,调用方必须 fail-closed。
+ */
+export interface LlmUsageTracker {
+  calls: number
+  inputTokens: number
+  outputTokens: number
+  inputCacheHitTokens: number
+  inputCacheMissTokens: number
+  responsesMissingUsage: number
+}
+
+function emptyUsage(): LlmUsageTracker {
+  return { calls: 0, inputTokens: 0, outputTokens: 0, inputCacheHitTokens: 0, inputCacheMissTokens: 0, responsesMissingUsage: 0 }
+}
+
+async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>, json: boolean, usage?: LlmUsageTracker): Promise<string> {
   const key = process.env['LLM_API_KEY'] ?? process.env['DEEPSEEK_API_KEY']
   if (!key) throw new Error('LLM_API_KEY 未设置(兼容 DEEPSEEK_API_KEY 别名)——真 LLM 路径不可用,请回退 mock(ADR-8)')
   const res = await fetch(`${base()}/chat/completions`, {
@@ -32,7 +50,20 @@ async function chat(messages: Array<{ role: 'system' | 'user' | 'assistant'; con
     }),
   })
   if (!res.ok) throw new Error(`llm ${res.status}: ${(await res.text()).slice(0, 300)}`)
-  const data = await res.json() as { choices: Array<{ message: { content: string } }> }
+  const data = await res.json() as { choices: Array<{ message: { content: string } }>; usage?: { prompt_tokens?: number; completion_tokens?: number; prompt_cache_hit_tokens?: number; prompt_cache_miss_tokens?: number } }
+  if (usage) {
+    usage.calls += 1
+    const u = data.usage
+    if (u && Number.isFinite(u.prompt_tokens) && Number.isFinite(u.completion_tokens)) {
+      usage.inputTokens += u.prompt_tokens ?? 0
+      usage.outputTokens += u.completion_tokens ?? 0
+      usage.inputCacheHitTokens += u.prompt_cache_hit_tokens ?? 0
+      // 无缓存明细的 provider:全部输入按 miss 记(随后按 peak miss 价换算,只高不低)
+      usage.inputCacheMissTokens += u.prompt_cache_miss_tokens ?? (u.prompt_tokens ?? 0)
+    } else {
+      usage.responsesMissingUsage += 1
+    }
+  }
   const raw = data.choices[0]?.message?.content ?? ''
   // 推理模型(MiniMax-M2 等):剥 <think> 块,只留正文;未闭合时留全文由上层容错
   return raw.replace(/<think>[\s\S]*?<\/think>/g, '').trim() || raw
@@ -62,8 +93,9 @@ const SKELETON_SYSTEM = `你是行程骨架抽取器。从对话中抽取行程
 规则:每个跨城移动一段;锚点只放用户明说或必然的(如"当天到"→arriveByMin 23:59=1439);时刻用当日分钟。
 scenario 判定:「洱海/大理/千岛湖/太湖+选目的地」→erhai(候选集);「普吉/workation/远程办公+多城链」→workation(五段链);「云南/大理丽江」→yunnan;不确定→generic。只输出 JSON。`
 
-export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date = () => new Date()): LlmPort {
+export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date = () => new Date()): LlmPort & { usage: LlmUsageTracker } {
   const pack = flightPackPath
+  const usage = emptyUsage()
   const historyText = (h: Turn[]) => h.map(t => `${t.role === 'user' ? '用户' : '助手'}: ${t.text}`).join('\n')
   // 时间锚点卡:每条抽取链路都带上「今天」——legacy 路径此前无时间注入,
   // 过期/相对日期语义全靠它(算术在 time-anchor 层,LLM 只查卡)。
@@ -73,6 +105,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: FACTS_SYSTEM }, { role: 'user', content: `${anchorContext()}\n\n${historyText(history)}` }],
         true,
+        usage,
       )
       const obj = parseJsonBlock(out)
       if (!obj) return { assumptions: [] }
@@ -87,6 +120,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: SKELETON_SYSTEM }, { role: 'user', content: `${context}\n\n${historyText(history)}` }],
         true,
+        usage,
       )
       const skeleton = parseJsonBlock(out)
       if (!skeleton || !Array.isArray(skeleton['segments']) || (skeleton['segments'] as unknown[]).length === 0) return null
@@ -136,6 +170,7 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
       const out = await chat(
         [{ role: 'system', content: buildSlotSystem(anchor) }, { role: 'user', content: historyText(history) }],
         true,
+        usage,
       )
       const obj = parseJsonBlock(out)
       if (!obj) return null
@@ -148,8 +183,10 @@ export function createOpenAICompatLlm(flightPackPath?: string, clock: () => Date
         [{ role: 'system', content: '把旅行规划的追问润色得更自然,保留全部信息(含为什么问),一两句话,不要加表情。' },
          { role: 'user', content: `【${q.key}】${q.text}(为什么问:${q.why})` }],
         false,
+        usage,
       )
       return out.trim() || `【${q.key}】${q.text}`
     },
+    usage,
   }
 }

package/ts/src/index.ts

@@ -22,7 +22,6 @@ import { ensureStateDir, recordLatency } from './bridge.ts'
 import { segmentsFromCandidate, solveChoiceSegment } from './unified.ts'
 import { checkConnectivity } from '../scripts/skeleton-check.ts'
 import { parseCandidate, parseRequest } from './model.ts'
-import { searchHotels as hbcliSearchHotels } from '../capabilities/hbcli.ts'
 import { installProcessGuards, guardToolExecute } from '../capabilities/incident-log.ts'
 import { interpretArgs, type GotryObservation } from './tool-packet.ts'
 import { projectUtility } from './memory-utility.ts'
@@ -31,15 +30,32 @@ import { resolveTimelineDate } from './travel-timeline.ts'
 import { ensureLedger, readCompanionsWithFallback, readMotivationWithFallback, readTripsWithFallback, readWishPoolWithFallback } from './state-ledger.ts'
 import { buildTimeAnchor } from './time-anchor.ts'
 import { resolveSlotDate } from './slot-spec.ts'
-import { geocodePlace, getForecast, getClimate, wmoLabel } from '../capabilities/weather.ts'
-import { verifyFlight } from '../capabilities/opensky.ts'
+import { wmoLabel } from '../capabilities/weather.ts'
 import { anythingSearch } from '../capabilities/anything.ts'
 import { readUrl, reach, reachStatus } from '../capabilities/agent-reach.ts'
 import { videoSubtitle, githubSearch } from '../capabilities/agent-reach-deep.ts'
-import { flyaiSearch } from '../capabilities/flyai.ts'
-import { sessionFlightSearch } from '../capabilities/session-search.ts'
 import { sessionLogin } from '../capabilities/session-login.ts'
 import { createConsentGate, approvalFromContext } from '../capabilities/session-consent.ts'
+import { listArtifacts, readArtifact } from '../capabilities/artifacts.ts'
+import { interpretEffect, declinedObservation } from '../capabilities/effect.ts'
+import { appendFacts, loadFactRegistry } from '../capabilities/fact-log.ts'
+import { factsFromFlyai, factsFromSession } from './bookable-facts.ts'
+import { gateArtifact, type AirlineAirportMap } from './artifact-gate.ts'
+
+/** 航司→机场映射表(issue #46 冲突检测面;data/airline-airports.json,as_of 快照) */
+let airlineAirportMapCache: AirlineAirportMap | null = null
+async function loadAirlineAirportMap(): Promise<AirlineAirportMap | null> {
+  if (airlineAirportMapCache) return airlineAirportMapCache
+  try {
+    const { readFile } = await import('node:fs/promises')
+    airlineAirportMapCache = JSON.parse(
+      await readFile(join(import.meta.dirname, '..', '..', 'data', 'airline-airports.json'), 'utf-8'),
+    ) as AirlineAirportMap
+    return airlineAirportMapCache
+  } catch {
+    return null // 映射缺失不阻塞检索主路径;闸工具侧另行显式报错
+  }
+}
 
 export const name = 'gotry-tools'
 export const inject = ['tools', 'systemPrompt']
@@ -493,10 +509,14 @@ export function apply(ctx: Context, config: Config): void {
         if (r.raw !== r.date) dateNotes.push(`slot-resolved: ${r.raw} → ${r.date}`)
         return r.date
       }
-      const resp = await hbcliSearchHotels(
-        { destination: q.destination, checkIn: resolveDate(q.checkIn), checkOut: resolveDate(q.checkOut), adults: q.adults },
-        { hbcliBin: config.hbcliBin, timeoutMs: config.timeoutMs, fallbackPath },
-      )
+      // 效应解译层(ADR-18):渠道选择/韧性(重试/熔断)在解译器,result 原样透传——
+      // 断路拒绝时返回平铺失败面(不发起查询,不伪装成 miss)
+      const itp = await interpretEffect({
+        effect: 'HBCLI_HOTEL_SEARCH',
+        params: { destination: q.destination, checkIn: resolveDate(q.checkIn), checkOut: resolveDate(q.checkOut), adults: q.adults, hbcliBin: config.hbcliBin, timeoutMs: config.timeoutMs, fallbackPath },
+      })
+      if (!itp.result) return declinedObservation('HBCLI_HOTEL_SEARCH', itp.trace)
+      const resp = itp.result
       const dir = await ensureStateDir(config.stateRoot)
       const isLive = resp.via === 'hbcli-realtime'
       const evidence = isLive ? resp.evidence : '[静态包:估算]'
@@ -583,7 +603,9 @@ export function apply(ctx: Context, config: Config): void {
       let placeLabel = q.place ?? `${q.lat},${q.lng}`
       if (lat === undefined || lng === undefined) {
         if (!q.place) throw new Error('gotry_weather_check requires place name or lat/lng')
-        const geo = await geocodePlace(q.place)
+        const geoItp = await interpretEffect({ effect: 'WEATHER_GEOCODE', params: { name: q.place } })
+        if (!geoItp.result) return declinedObservation('WEATHER_GEOCODE', geoItp.trace)
+        const geo = geoItp.result
         if (!geo.ok || geo.results.length === 0) {
           return JSON.parse(JSON.stringify({ ok: false, summary: `地点「${q.place}」地理编码失败:${geo.error ?? '无结果'}`, evidence: geo.evidence })) as Record<string, never>
         }
@@ -592,9 +614,11 @@ export function apply(ctx: Context, config: Config): void {
         placeLabel = `${hit.name}(${hit.admin1 ?? hit.country ?? ''})`
       }
       const isClimate = q.mode === 'climate' || (q.month !== undefined && q.mode !== 'forecast')
-      const r = isClimate
-        ? await getClimate({ latitude: lat, longitude: lng }, q.month ?? new Date().getMonth() + 1)
-        : await getForecast({ latitude: lat, longitude: lng }, { days: q.days })
+      const wxItp = isClimate
+        ? await interpretEffect({ effect: 'WEATHER_CLIMATE', params: { latitude: lat, longitude: lng, month: q.month ?? new Date().getMonth() + 1 } })
+        : await interpretEffect({ effect: 'WEATHER_FORECAST', params: { latitude: lat, longitude: lng, days: q.days } })
+      if (!wxItp.result) return declinedObservation(isClimate ? 'WEATHER_CLIMATE' : 'WEATHER_FORECAST', wxItp.trace)
+      const r = wxItp.result
       const dir = await ensureStateDir(config.stateRoot)
       await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `weather:${r.via}`).catch(() => {})
       const dailyLines = (r.daily ?? []).slice(0, 7).map(d =>
@@ -649,7 +673,9 @@ export function apply(ctx: Context, config: Config): void {
       if (!q.callsign) {
         return JSON.parse(JSON.stringify({ verdict: 'unavailable', evidence: '[校验不可用:无 callsign]', summary: 'callsign 必填' })) as Record<string, never>
       }
-      const r = await verifyFlight({ callsign: q.callsign, airport: q.airport, timeoutMs: q.timeoutMs })
+      const itp = await interpretEffect({ effect: 'OPENSKY_FLIGHT_VERIFY', params: { callsign: q.callsign, airport: q.airport, timeoutMs: q.timeoutMs } })
+      if (!itp.result) return declinedObservation('OPENSKY_FLIGHT_VERIFY', itp.trace)
+      const r = itp.result
       const dir = await ensureStateDir(config.stateRoot)
       await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `flight_verify:${r.via}`).catch(() => {})
       const summary = r.verdict === 'observed'
@@ -701,7 +727,9 @@ export function apply(ctx: Context, config: Config): void {
             return { ok: false, summary: 'checkOut 需 YYYY-MM-DD(与 checkIn 成对)' } as const
           }
         }
-        const r = await flyaiSearch({ kind: 'hotel', destName: dest, checkInDate: q.checkIn, checkOutDate: q.checkOut, keyWords: q.keyWords })
+        const itp = await interpretEffect({ effect: 'FLYAI_SEARCH', params: { kind: 'hotel', destName: dest, checkInDate: q.checkIn, checkOutDate: q.checkOut, keyWords: q.keyWords } })
+        if (!itp.result) return declinedObservation('FLYAI_SEARCH', itp.trace)
+        const r = itp.result
         const top = (r.hotels ?? []).slice(0, 8).map(o => `${o.name}${o.star ? `(${o.star})` : ''} ${o.priceRaw ?? '价待询'}${o.poi ? ` · ${o.poi}` : ''}`)
         const summary = r.verdict === 'hit'
           ? `${dest} 酒店(飞猪官方只读)前 ${top.length} 家(价格多为打码,真实价以 jumpUrl 为准):\n${top.join('\n')}\n${r.evidence}`
@@ -724,7 +752,13 @@ export function apply(ctx: Context, config: Config): void {
             + `多为用户时间表达未带年份所致——向用户确认年份(或按未来最近的同月日修正)后再查。`,
         })) as Record<string, never>
       }
-      const r = await flyaiSearch({ kind, origin: q.from, destination: q.to, depDate: q.date })
+      const itp = await interpretEffect({ effect: 'FLYAI_SEARCH', params: { kind, origin: q.from, destination: q.to, depDate: q.date } })
+      if (!itp.result) return declinedObservation('FLYAI_SEARCH', itp.trace)
+      const r = itp.result
+      // issue #46 事实落账(ADR-19):exact-date 检索结论(hit 正事实 / miss 负事实)追加进
+      // bookable-facts 侧车——产物事实闸(gotry_fact_gate)的唯一事实源;落盘失败不阻塞检索
+      const avMap = await loadAirlineAirportMap()
+      await appendFacts(config.stateRoot ?? '.', factsFromFlyai({ kind, origin: q.from, destination: q.to, date: q.date }, r, new Date().toISOString(), avMap?.city_alias))
       const top = (r.options ?? []).slice(0, 8).map(o => `${o.no} ${o.name} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`)
       // issue #24:miss(上游正常返回 0 条)与 error(限流/网络)分开陈述,不再混写「无结果或失败」
       // (过去日期已被上方预校验拦下,此处不会出现过期查询)
@@ -749,9 +783,10 @@ export function apply(ctx: Context, config: Config): void {
     name: 'gotry_session_login',
     description:
       'Productized login bootstrap for the account session channel (call this when gotry_session_search returns needs-login — the user never needs a terminal). ' + 'AUTO-DETECTION FIRST: it reads ticket-cookie NAMES before anything else — if the user already logged in (on the external site) it confirms instantly WITHOUT opening any page. '
-      + 'OPENS the site login entry in the USER\'S OWN Chrome and waits for the user to finish logging in on the external site. '
+      + 'OPENS the site login entry in the USER\'S OWN Chrome (foreground tab, left open for the user) and waits for the user to finish logging in on the external site. '
       + 'GoTry NEVER collects, stores, or transmits credentials: no passwords, no SMS codes, no cookie values — it only checks the boolean fact "already logged in" (reads cookie NAMES only, zero values). '
-      + 'verdict logged-in (tickets detected) | pending (login tab opened, user not done yet — offer to re-check later) | needs-attach (one-time Chrome remote-debugging switch instructions). '
+      + 'Transport: the GoTry Session Bridge browser extension (one-time install, ZERO Chrome system dialogs). '
+      + 'verdict logged-in (tickets detected) | pending (login tab opened, user not done yet — offer to re-check later) | needs-extension (one-time extension install: npx gotry setup, then chrome://extensions → load unpacked ~/.gotry/extension). '
       + 'Evidence [会话:<site>-login@ts].',
     parameters: {
       query: { type: 'json', required: true, description: '可空对象 {}: { waitSeconds?: number }(等待用户完成登录的上限秒数,默认 90,至多 300)' },
@@ -764,9 +799,11 @@ export function apply(ctx: Context, config: Config): void {
         ? `${r.site} 登录完成确认(票据 cookie 名已检出,只读名字)。说明:登录是在携程官网、用你自己的浏览器完成的——gotry 全程未接触任何密码/验证码/cookie 值。现在可以继续会话检索了。${r.evidence}`
         : r.verdict === 'pending'
           ? `登录入口已在你的 Chrome 打开;请在弹出的标签页里正常登录携程(登录由你在官网完成,不属于 gotry)。完成后说一声"继续",我再确认。gotry 只检查"是否已登录",永不收集你的账号信息。${r.evidence}`
-          : r.verdict === 'needs-attach'
-            ? `需要一次性开启你 Chrome 的远程调试开关:在你的 Chrome 地址栏打开 chrome://inspect/#remote-debugging 并打开开关,然后说一声"重试"。${r.evidence}`
-            : `登录引导未完成:${r.error ?? '未知原因'} ${r.evidence}`
+          : r.verdict === 'needs-extension'
+            ? `需要一次性安装 GoTry Session Bridge 浏览器扩展(约 30 秒,装完零弹窗):跑 npx gotry setup 拿安装指引,在 chrome://extensions 开发者模式「加载已解压的扩展程序」指向 ~/.gotry/extension,装好后说一声"重试"。${r.evidence}`
+            : r.verdict === 'needs-attach'
+              ? `cdp 车道需要一次性开启你 Chrome 的远程调试开关:在你的 Chrome 地址栏打开 chrome://inspect/#remote-debugging 并打开开关,然后说一声"重试"(默认走扩展车道,无需此步)。${r.evidence}`
+              : `登录引导未完成:${r.error ?? '未知原因'} ${r.evidence}`
       return JSON.parse(JSON.stringify({ ...r, summary })) as Record<string, never>
     },
     presentCall: _args => ({ card: 'generic', title: '登录携程(用你自己的浏览器,不在 gotry 输入)', kind: 'fetch', rawInput: {} }),
@@ -782,9 +819,10 @@ export function apply(ctx: Context, config: Config): void {
     description:
       'Search on the USER\'S OWN logged-in browser session (Ctrip flights today; the account channel, not an anonymous instance). '
       + 'Consent gate: the FIRST call in a session asks the user via the runtime approval card; once granted it holds for the session, a refusal revokes it for the session (no repeat prompting). '
-      + 'ReadGuard = physically read-only (write requests aborted at network layer; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
+      + 'Transport: GoTry Session Bridge browser extension (one-time install) — the agent side never talks to Chrome debugging, ZERO system dialogs; read-only by construction (the extension never issues requests; it only passively forwards the site\'s own search responses; agent NEVER touches credentials/captcha; on captcha it stops and returns challenged). '
       + 'Currently ctrip-flight: sniffs the site search API for structured options. Evidence [会话:ctrip-flight@ts]. '
-      + 'verdict needs-login = call gotry_session_login (product tool: opens the Ctrip login entry in the user\'s own Chrome and waits for them to log in on the external site — no terminal, no credentials through GoTry); needs-attach = one-time Chrome remote-debugging switch. '
+      + 'verdict needs-login = call gotry_session_login (opens the Ctrip login entry in the user\'s own foreground tab — no terminal, no credentials through GoTry); '
+      + 'needs-extension = one-time browser-extension install (npx gotry setup for instructions) — the DEFAULT transport; cdp (chrome://inspect remote debugging) is a diagnostic fallback only via GOTRY_SESSION_TRANSPORT=cdp. '
       + 'Rate-limited (≥30s between same-site calls; a challenged/timeout verdict means STOP — never retry, fall back to other tools).',
     parameters: {
       query: { type: 'json', required: true, description: '{ from: "上海", to: "丽江", date: "2026-10-01" }' },
@@ -795,11 +833,21 @@ export function apply(ctx: Context, config: Config): void {
       if (!q.from || !q.to || !q.date) {
         return { ok: false, summary: '需要 from/to(中文城市名,词表内)与 date(YYYY-MM-DD)' } as const
       }
-      const r = await sessionFlightSearch({
-        from: q.from, to: q.to, date: q.date,
-        // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
-        auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
+      // 效应解译层(ADR-18):SESSION 通道策略=永不重试/不熔断,节律闸在渠道内;
+      // 解译器只做分发与证据拼装,verdict 语义(risk 型 needs-login/challenged)原样透传
+      const itp = await interpretEffect({
+        effect: 'SESSION_FLIGHT_SEARCH',
+        params: {
+          from: q.from, to: q.to, date: q.date,
+          // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
+          auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
+        },
       })
+      if (!itp.result) return declinedObservation('SESSION_FLIGHT_SEARCH', itp.trace)
+      const r = itp.result
+      // issue #46 事实落账(ADR-19):会话面 exact-date 结论同样进事实注册表(独立 source 并列标注)
+      const avMapS = await loadAirlineAirportMap()
+      await appendFacts(config.stateRoot ?? '.', factsFromSession({ origin: q.from, destination: q.to, date: q.date }, r, new Date().toISOString(), avMapS?.city_alias))
       const top = (r.options ?? []).slice(0, 8).map(o => `${o.flightNo} ${o.airline} ${o.depDateTime.slice(11, 16)}→${o.arrDateTime.slice(11, 16)} ¥${o.price}`)
       const summary = r.verdict === 'hit'
         ? `${q.from}→${q.to} ${q.date} 会话检索(携程,用户本人登录态)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}`
@@ -809,7 +857,13 @@ export function apply(ctx: Context, config: Config): void {
     presentCall: args => ({ card: 'generic', title: `会话检索:${String((args.query as { from?: string })?.from ?? '')}`, kind: 'fetch', rawInput: args.query }),
     presentResult: (_args, value) => {
       const r = value as { verdict?: string; options?: unknown[] }
-      const label = r.verdict === 'hit' ? `会话 ${r.options!.length} 条` : (r.verdict === 'needs-login' ? '需登录' : r.verdict ?? '降级')
+      const label = r.verdict === 'hit'
+        ? `会话 ${r.options!.length} 条`
+        : r.verdict === 'needs-login'
+          ? '需登录'
+          : r.verdict === 'needs-extension'
+            ? '需装扩展(一次性)'
+            : r.verdict ?? '降级'
       return { card: 'generic', title: `会话检索:${label}`, content: [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }] }
     },
   }))
@@ -1073,4 +1127,152 @@ export function apply(ctx: Context, config: Config): void {
       }
     },
   }))
+
+  // ---- 产物面(issue #25):agent 生成的文件可在 dsh 内发现与阅读,不再只是本地文件名 ----
+
+  registerGuarded(defineTool({
+    name: 'gotry_artifacts_list',
+    description:
+      'List GoTry artifacts — deep-planning deliverables (async runs from the state ledger) plus agent-written markdown files ' +
+      'in the working directory (trip plans etc.). READ-ONLY discovery. ' +
+      'Use when the user asks to see/open/revisit a previously generated artifact ' +
+      '(「看看刚才生成的行程」「上次的规划在哪」「打开那个 md」) — list first, then read with gotry_artifacts_read.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ limit?: 20 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 600)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ limit?: number }>(args, 'limit')
+      const r = await listArtifacts({ stateRoot: config.stateRoot ?? '.', limit: q.limit })
+      const lines = r.artifacts.map(a =>
+        `- [${a.source}] ${a.title}${a.status ? `(${a.status})` : ''} — ${a.path}${a.updated ? ` @ ${a.updated.slice(0, 16).replace('T', ' ')}` : ''}`)
+      const summary = r.artifacts.length
+        ? `在册产物 ${r.artifacts.length}/${r.total} 项${r.truncated ? '(截断,可加 limit)' : ''}:\n${lines.join('\n')}`
+        : '无在册产物(异步深度规划交付与工作目录 md 文件都会出现在这里)'
+      return JSON.parse(JSON.stringify({ ok: true, artifacts: r.artifacts, total: r.total, truncated: r.truncated, summary })) as Record<string, never>
+    },
+    presentCall: () => ({ card: 'generic', title: '列出产物', kind: 'search' }),
+    presentResult: (_args, value) => {
+      const r = value as { summary?: string; total?: number }
+      return {
+        card: 'generic',
+        title: `产物:${r.total ?? 0} 项在册`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
+
+  registerGuarded(defineTool({
+    name: 'gotry_artifacts_read',
+    description:
+      'Read one GoTry artifact as a line-numbered file view rendered directly in the chat UI. ' +
+      'Input: the path from gotry_artifacts_list, or a bare async ticket id (e.g. dp-xxxx). ' +
+      'Optional offset (1-based) / limit window for paging large files. ' +
+      'READ-ONLY; text artifacts only (md/txt/json/jsonl/csv/log/yaml).',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ path: "<list 返回的路径或工单 id>", offset?: 1, limit?: 400 }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { content?: string }).content ?? JSON.stringify(value).slice(0, 600)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ path?: string; offset?: number; limit?: number }>(args, 'path')
+      if (!q.path) return JSON.parse(JSON.stringify({ ok: false, error: 'path 必填(来自 gotry_artifacts_list)' })) as Record<string, never>
+      const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', path: q.path, offset: q.offset, limit: q.limit })
+      if (!r.ok) return JSON.parse(JSON.stringify(r)) as Record<string, never>
+      return JSON.parse(JSON.stringify({
+        ...r,
+        summary: `${r.path}(${r.totalLines} 行)第 ${r.offset}-${r.offset + r.lines.length - 1} 行${r.windowed ? `(共 ${r.totalLines} 行,可翻页)` : ''}`,
+      })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: `读产物:${String((args.query as { path?: string })?.path ?? '')}`, kind: 'read', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as unknown as { ok?: boolean; path?: string; offset?: number; lines?: Array<{ number: number; text: string }>; totalLines?: number; lang?: string; content?: string; error?: string }
+      if (!r.ok) {
+        return { card: 'generic', title: '读产物失败', content: [{ type: 'text', text: String(r.error ?? '') }] }
+      }
+      // dsh read 卡:UI 渲染为行号文件视图(issue #25 的「插件能力查看 artifacts」落点)
+      return {
+        card: 'read' as const,
+        title: r.path?.split('/').pop() ?? r.path ?? '',
+        path: r.path ?? '',
+        offset: r.offset ?? 1,
+        lines: r.lines ?? [],
+        totalLines: r.totalLines ?? 0,
+        lang: r.lang,
+        content: [{ type: 'text', text: r.content ?? '' }],
+      }
+    },
+  }))
+
+  // ---- 产物事实闸(issue #46,ADR-19):含可下单事实的产物交付前必过 ----
+  // 每个航班号/时刻/机场/价格/政策断言必须回溯到本会话 exact-date 工具结果
+  // (bookable-facts 侧车,query_id 可重放);无法回溯即 blocked——不得宣称「已验证方案」。
+
+  registerGuarded(defineTool({
+    name: 'gotry_fact_gate',
+    description:
+      'Factuality gate for itinerary artifacts (issue #46): call BEFORE delivering any artifact that contains bookable facts '
+      + '(flight numbers, times, airports, prices, visa/entry policies). Every bookable claim in the markdown is checked against '
+      + 'the session fact registry (exact-date tool results recorded by gotry_flyai_search / gotry_session_search — hit AND miss). '
+      + 'Blocked when: a claimed flight is absent from the exact-date source (never backfill from route pages/history/adjacent dates); '
+      + 'route+date never queried; times contradict the snapshot; carrier→airport mapping conflicts (FD=DMK vs VZ=BKK are NOT interchangeable); '
+      + '「联程」without protected_connection=true; policy claims without 「截至 YYYY-MM-DD」; unconditional ✓ on unverified claims. '
+      + 'Optional itinerary object enables machine invariants (hotel_nights + onboard_nights = total nights, O&D segments vs flight legs, '
+      + 'budget floor ≥ sum of item minimums). verdict=blocked ⇒ fix or downgrade wording — never present as a verified plan.',
+    parameters: {
+      query: {
+        type: 'json',
+        required: true,
+        description: '{ markdown?: "<产物全文>", path?: "<产物路径(artifacts_list 返回的)>— 二选一", tripYear?: 2027, itinerary?: { trip_start, trip_end, stays: [{place,check_in,check_out}], onboard_nights, od_segments: [{from,to,date,mode,legs}], budget_items: [{label,min_cny,max_cny}], claimed_floor_cny? } }',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? JSON.stringify(value).slice(0, 800)) }],
+    },
+    async execute(args: { query: unknown }, _exec: unknown) {
+      const q = unwrapQuery<{ markdown?: string; path?: string; tripYear?: number; itinerary?: Record<string, unknown> }>(args, 'markdown')
+      const avMap = await loadAirlineAirportMap()
+      if (!avMap) {
+        return JSON.parse(JSON.stringify({ ok: false, summary: '航司机场映射缺失(data/airline-airports.json)——事实闸不可用,fail closed:产物不得宣称已验证' })) as Record<string, never>
+      }
+      let markdown = q.markdown
+      if (!markdown && q.path) {
+        const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', path: q.path })
+        if (!r.ok) return JSON.parse(JSON.stringify({ ok: false, summary: `产物读取失败:${String((r as { error?: string }).error ?? '')}` })) as Record<string, never>
+        markdown = r.content
+      }
+      if (!markdown) return JSON.parse(JSON.stringify({ ok: false, summary: '需要 markdown(产物全文)或 path(产物路径)' })) as Record<string, never>
+      const itinerary = q.itinerary as import('./bookable-facts.ts').ItineraryFacts | undefined
+      const registry = await loadFactRegistry(config.stateRoot ?? '.')
+      const report = gateArtifact(markdown, registry, avMap, { trip_year: q.tripYear, itinerary })
+      const lines = report.violations.slice(0, 20).map(v => `  L${v.line} [${v.kind}] ${v.detail}`)
+      const summary = report.verdict === 'pass'
+        ? `事实闸 PASS:${report.traceable}/${report.claims_checked} 可下单 claim 全部回溯到 exact-date 工具结果(query_id 可重放)——可宣称「已验证方案」。`
+        : `事实闸 BLOCKED(${report.violations.length} 违例,${report.traceable}/${report.claims_checked} claim 可回溯)——不得宣称「已验证方案」:\n${lines.join('\n')}\n修正路径:逐条改成 exact-date 源返回的事实,或降级为「未确认/当前不可售,到 D-xx 复核」;exact-date miss 的 route+date 不得用历史班期/相邻日期/航线页填充。`
+      return JSON.parse(JSON.stringify({ ok: true, ...report, summary })) as Record<string, never>
+    },
+    presentCall: args => ({ card: 'generic', title: '产物事实闸', kind: 'execute', rawInput: args.query }),
+    presentResult: (_args, value) => {
+      const r = value as { verdict?: string; violations?: unknown[]; summary?: string }
+      return {
+        card: 'generic',
+        title: `事实闸:${r.verdict === 'pass' ? '✅ pass' : `⛔ blocked(${r.violations?.length ?? '?'})`}`,
+        content: [{ type: 'text', text: String(r.summary ?? '') }],
+      }
+    },
+  }))
 }