@danceiny/gotry 0.0.1-rc.18 → 0.0.1-rc.20

package/ts/src/benchmark-environment-bridge.ts

@@ -1,17 +1,34 @@
 import { accessSync, constants, lstatSync, readFileSync, statSync } from 'node:fs'
 import { getuid } from 'node:process'
 import { isAbsolute } from 'node:path'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import {
+  assertSupportedJsonSchema,
+  validateJsonSchemaValue,
+  ToolArgsError,
+  type JsonSchemaNode,
+  type ObjectJsonSchema,
+  type ToolDefinition,
+} from '@deepseek-ai/dsh-tools'
 import {
   validateTerminalOutputConfig,
   type BenchmarkBridgeProjection,
   type TerminalOutputConfig,
 } from './benchmark-agent-conformance.ts'
 
-const SCHEMA_VERSION = 'gotry_benchmark_environment_bridge_v2'
+const SCHEMA_VERSION = 'gotry_benchmark_environment_bridge_v3'
+export const BENCHMARK_TOOL_RESULT_SCHEMA_VERSION = 'gotry_benchmark_tool_result_v1'
+export const BENCHMARK_DOMAIN_RECOVERIES = ['none', 'retry_same', 'revise_arguments', 'choose_alternative'] as const
+type BenchmarkDomainRecovery = typeof BENCHMARK_DOMAIN_RECOVERIES[number]
 const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]*$/
-const CONFIG_KEYS = ['allowed_tools', 'argv_prefix', 'cwd', 'enabled', 'executable', 'isolation', 'max_output_bytes', 'schema_version', 'terminal_output', 'timeout_ms']
-const OPTIONAL_CONFIG_KEYS = ['allowed_output_keys']
+const RECOVERIES = new Set<string>(BENCHMARK_DOMAIN_RECOVERIES)
+const CONFIG_KEYS = ['argv_prefix', 'cwd', 'enabled', 'executable', 'isolation', 'max_output_bytes', 'schema_version', 'terminal_output', 'timeout_ms', 'tools']
+const INPUT_SCHEMA_MAX_BYTES = 16 * 1024
+const INPUT_SCHEMA_MAX_DEPTH = 8
+const INPUT_SCHEMA_MAX_NODES = 256
+const INPUT_SCHEMA_MAX_PROPERTIES = 256
+const INPUT_SCHEMA_MAX_ENUM_VALUES = 256
+const INPUT_SCHEMA_MAX_DESCRIPTION_LENGTH = 512
+const INPUT_SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'array', 'object'])
 
 export interface BenchmarkEnvironmentBridgeConfig {
   schema_version: typeof SCHEMA_VERSION
@@ -19,8 +36,7 @@ export interface BenchmarkEnvironmentBridgeConfig {
   executable: string
   cwd: string
   argv_prefix: string[]
-  allowed_tools: string[]
-  allowed_output_keys?: Record<string, string[]>
+  tools: BenchmarkToolDescriptor[]
   timeout_ms: number
   max_output_bytes: number
   terminal_output: TerminalOutputConfig
@@ -31,10 +47,56 @@ export interface BenchmarkEnvironmentBridgeConfig {
   }
 }
 
+export interface BenchmarkToolDescriptor {
+  name: string
+  description: string
+  input_schema: ObjectJsonSchema
+  output_keys: string[]
+  domain_outcomes: Array<{ status: 'miss' | 'error'; code: string; recovery: BenchmarkDomainRecovery }>
+}
+
+function descriptorSchema(tools: readonly BenchmarkToolDescriptor[]): JsonSchemaNode {
+  return {
+    oneOf: [
+      {
+        type: 'object',
+        description: 'List the frozen benchmark tool descriptors.',
+        properties: { action: { type: 'string', const: 'tools' } },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      {
+        type: 'object',
+        description: 'List the frozen bridge error contract.',
+        properties: { action: { type: 'string', const: 'errors' } },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      ...tools.map<JsonSchemaNode>(tool => ({
+        type: 'object',
+        description: tool.description,
+        properties: {
+          action: { type: 'string', const: 'call' },
+          tool: { type: 'string', const: tool.name },
+          arguments: tool.input_schema,
+        },
+        required: ['action', 'tool', 'arguments'],
+        additionalProperties: false,
+      })),
+    ],
+  }
+}
+
 function plainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+function deepFreezeJson<T>(value: T): T {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value
+  for (const child of Object.values(value as Record<string, unknown>)) deepFreezeJson(child)
+  return Object.freeze(value)
+}
+
 function existingExecutable(value: unknown): value is string {
   if (typeof value !== 'string' || !isAbsolute(value)) return false
   try {
@@ -55,17 +117,111 @@ function existingDirectory(value: unknown): value is string {
   }
 }
 
-function identifiers(value: unknown): value is string[] {
-  return Array.isArray(value) && value.length > 0 && value.length <= 64 && new Set(value).size === value.length && value.every(
+function identifiers(value: unknown, allowEmpty = false): value is string[] {
+  return Array.isArray(value) && (allowEmpty || value.length > 0) && value.length <= 64 && new Set(value).size === value.length && value.every(
     item => typeof item === 'string' && item.length > 0 && IDENTIFIER.test(item),
   )
 }
 
-function allowedOutputKeys(value: unknown, allowedTools: string[]): value is Record<string, string[]> {
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  return Object.keys(value).every(key => allowed.includes(key))
+}
+
+function validDescription(value: unknown, required = false): boolean {
+  if (value === undefined) return !required
+  return typeof value === 'string'
+    && (!required || value.trim().length > 0)
+    && value.length <= INPUT_SCHEMA_MAX_DESCRIPTION_LENGTH
+    && !/[\u0000-\u001f\u007f]/.test(value)
+}
+
+function scalarMatches(type: string, value: unknown): boolean {
+  if (type === 'string') return typeof value === 'string' && value.length <= 512
+  if (type === 'number') return typeof value === 'number' && Number.isFinite(value)
+  if (type === 'integer') return typeof value === 'number' && Number.isSafeInteger(value)
+  if (type === 'boolean') return typeof value === 'boolean'
+  return type === 'null' && value === null
+}
+
+function validInputSchema(value: unknown): value is ObjectJsonSchema {
   if (!plainObject(value)) return false
-  const keys = Object.keys(value)
-  return keys.length > 0 && keys.length <= 64
-    && keys.every(tool => allowedTools.includes(tool) && identifiers(value[tool]))
+  let serialized: string
+  try {
+    serialized = JSON.stringify(value)
+  } catch {
+    return false
+  }
+  if (Buffer.byteLength(serialized, 'utf8') > INPUT_SCHEMA_MAX_BYTES) return false
+
+  const pending: Array<{ node: Record<string, unknown>; depth: number }> = [{ node: value, depth: 0 }]
+  const seen = new Set<object>()
+  let nodes = 0
+  let properties = 0
+  let enumValues = 0
+  while (pending.length > 0) {
+    const { node, depth } = pending.pop()!
+    if (seen.has(node) || ++nodes > INPUT_SCHEMA_MAX_NODES || depth > INPUT_SCHEMA_MAX_DEPTH) return false
+    seen.add(node)
+    if (!INPUT_SCHEMA_TYPES.has(String(node.type)) || !validDescription(node.description)) return false
+
+    if (node.type === 'object') {
+      if (!exactKeys(node, ['type', 'description', 'properties', 'required', 'additionalProperties'])
+        || !plainObject(node.properties)
+        || !Array.isArray(node.required)
+        || node.additionalProperties !== false) return false
+      const propertyEntries = Object.entries(node.properties)
+      properties += propertyEntries.length
+      if (properties > INPUT_SCHEMA_MAX_PROPERTIES || propertyEntries.some(([key, child]) => !IDENTIFIER.test(key) || !plainObject(child))) return false
+      const required = node.required
+      if (required.length > propertyEntries.length
+        || new Set(required).size !== required.length
+        || required.some(key => typeof key !== 'string' || !Object.hasOwn(node.properties as Record<string, unknown>, key))) return false
+      for (const [, child] of propertyEntries) pending.push({ node: child as Record<string, unknown>, depth: depth + 1 })
+      continue
+    }
+
+    if (node.type === 'array') {
+      if (!exactKeys(node, ['type', 'description', 'items']) || !plainObject(node.items)) return false
+      pending.push({ node: node.items, depth: depth + 1 })
+      continue
+    }
+
+    if (!exactKeys(node, ['type', 'description', 'enum', 'const'])
+      || (Object.hasOwn(node, 'enum') && Object.hasOwn(node, 'const'))) return false
+    if (Object.hasOwn(node, 'const') && !scalarMatches(String(node.type), node.const)) return false
+    if (Object.hasOwn(node, 'enum')) {
+      if (!Array.isArray(node.enum) || node.enum.length === 0 || node.enum.length > 64) return false
+      enumValues += node.enum.length
+      if (enumValues > INPUT_SCHEMA_MAX_ENUM_VALUES
+        || new Set(node.enum).size !== node.enum.length
+        || node.enum.some(item => !scalarMatches(String(node.type), item))) return false
+    }
+  }
+  return value.type === 'object'
+}
+
+function toolDescriptors(value: unknown): value is BenchmarkToolDescriptor[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 64) return false
+  const names = new Set<string>()
+  return value.every(item => {
+    if (!plainObject(item)) return false
+    const keys = Object.keys(item).sort()
+    const required = ['description', 'domain_outcomes', 'input_schema', 'name']
+    if (JSON.stringify(keys) !== JSON.stringify([...required, 'output_keys'].sort())) return false
+    if (typeof item.name !== 'string' || !IDENTIFIER.test(item.name) || names.has(item.name)) return false
+    names.add(item.name)
+    if (!validDescription(item.description, true) || !validInputSchema(item.input_schema)) return false
+    if (!Array.isArray(item.domain_outcomes) || item.domain_outcomes.length > 64) return false
+    const outcomeKeys = new Set<string>()
+    if (!item.domain_outcomes.every(outcome => plainObject(outcome)
+      && JSON.stringify(Object.keys(outcome).sort()) === JSON.stringify(['code', 'recovery', 'status'])
+      && (outcome.status === 'miss' || outcome.status === 'error')
+      && typeof outcome.code === 'string' && IDENTIFIER.test(outcome.code)
+      && typeof outcome.recovery === 'string' && RECOVERIES.has(outcome.recovery)
+      && !outcomeKeys.has(outcome.code)
+      && (outcomeKeys.add(outcome.code), true))) return false
+    return identifiers(item.output_keys)
+  })
 }
 
 // These are passed as direct argv entries (never through a shell), so options
@@ -98,20 +254,19 @@ function validBound(value: unknown, maximum: number): value is number {
 function validate(value: unknown): value is BenchmarkEnvironmentBridgeConfig {
   const configKeys = plainObject(value) ? Object.keys(value).sort() : []
   const baseKeys = [...CONFIG_KEYS].sort()
-  const extendedKeys = [...CONFIG_KEYS, ...OPTIONAL_CONFIG_KEYS].sort()
   if (!plainObject(value)
-    || ![baseKeys, extendedKeys].some(keys => JSON.stringify(configKeys) === JSON.stringify(keys))
+    || JSON.stringify(configKeys) !== JSON.stringify(baseKeys)
     || value.schema_version !== SCHEMA_VERSION
     || value.enabled !== true
     || !existingExecutable(value.executable)
     || !existingDirectory(value.cwd)
     || !argvPrefix(value.argv_prefix)
-    || !identifiers(value.allowed_tools)
+    || !toolDescriptors(value.tools)
     || !validBound(value.timeout_ms, 120_000)
     || !validBound(value.max_output_bytes, 10 * 1024 * 1024)
     || !validateTerminalOutputConfig(value.terminal_output)
     || !exactIsolation(value.isolation)
-    || (Object.hasOwn(value, 'allowed_output_keys') && !allowedOutputKeys(value.allowed_output_keys, value.allowed_tools))) return false
+    ) return false
   return true
 }
 
@@ -124,13 +279,13 @@ export function loadBenchmarkEnvironmentConfig(path: string): BenchmarkEnvironme
     if (typeof getuid !== 'function' || metadata.uid !== getuid()) return null
     if ((metadata.mode & 0o022) !== 0) return null
     const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return validate(parsed) ? parsed : null
+    return validate(parsed) ? deepFreezeJson(parsed) : null
   } catch {
     return null
   }
 }
 
-type Register = (tool: ReturnType<typeof defineTool>) => void
+type Register = (tool: ToolDefinition) => void
 interface CollectedText {
   readFrom(offset: number): { text: string; nextOffset: number; lossy?: boolean }
 }
@@ -176,6 +331,19 @@ const FORBIDDEN_OUTPUT_KEY_FRAGMENTS = [
   'loadermetadata', 'oracle', 'reference', 'reward', 'score',
 ]
 
+export const BRIDGE_ERROR_CONTRACT: Record<string, { recoverable: boolean; remedy: string }> = Object.freeze({
+  invalid_action: { recoverable: true, remedy: 'action 只允许 tools、call 或 errors' },
+  disallowed_tool: { recoverable: true, remedy: '先 action=tools 列出 allowed_tools 清单,再从清单内选工具' },
+  invalid_arguments: { recoverable: true, remedy: 'arguments 必须是可序列化 JSON 对象(≤64KB、深度≤12);收窄后重试' },
+  timed_out: { recoverable: true, remedy: '上游超时;可原样重试一次或换其他工具' },
+  output_truncated: { recoverable: true, remedy: '输出超出上限;让被调工具收窄查询范围后重试' },
+  invalid_json: { recoverable: true, remedy: '上游输出不是合法 JSON;重试一次或换工具' },
+  invalid_output: { recoverable: true, remedy: '上游输出结构不符;重试或换工具' },
+  runner_failed: { recoverable: true, remedy: '上游进程非零退出;可重试一次,持续失败换工具' },
+  spawn_failed: { recoverable: false, remedy: '可执行文件不可用——环境问题,调用方不可恢复' },
+  forbidden_output: { recoverable: false, remedy: '输出含未授权键(策略边界)——不可恢复,换工具或放弃' },
+})
+
 function inspectOutput(value: unknown): 'ok' | 'forbidden_key' | 'structure_limit' {
   const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }]
   let nodes = 0
@@ -199,19 +367,22 @@ function inspectOutput(value: unknown): 'ok' | 'forbidden_key' | 'structure_limi
 
 function inspectAllowedOutput(value: unknown, allowedKeys: string[]): boolean {
   const allowed = new Set(allowedKeys)
-  const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }]
+  const pending: Array<{ value: unknown; depth: number; coveredByDeclaredKey: boolean }> = [{ value, depth: 0, coveredByDeclaredKey: false }]
   let nodes = 0
   while (pending.length > 0) {
     const current = pending.pop()!
     if (++nodes > 10_000 || current.depth > 24) return false
     if (Array.isArray(current.value)) {
-      for (const child of current.value) pending.push({ value: child, depth: current.depth + 1 })
+      for (const child of current.value) pending.push({ value: child, depth: current.depth + 1, coveredByDeclaredKey: current.coveredByDeclaredKey })
+      continue
+    }
+    if (!plainObject(current.value)) {
+      if (!current.coveredByDeclaredKey) return false
       continue
     }
-    if (!plainObject(current.value)) continue
     for (const [key, child] of Object.entries(current.value)) {
       if (!allowed.has(key)) return false
-      pending.push({ value: child, depth: current.depth + 1 })
+      pending.push({ value: child, depth: current.depth + 1, coveredByDeclaredKey: true })
     }
   }
   return true
@@ -254,31 +425,41 @@ export function registerBenchmarkEnvironmentBridge(
   if (!bridge) throw new Error('benchmark environment bridge configuration unavailable')
   if (!subprocess) throw new Error('benchmark environment bridge subprocess unavailable')
 
-  register(defineTool({
+  const parameters: Record<string, unknown> = deepFreezeJson({
+    oneOf: descriptorSchema(bridge.tools).oneOf,
+  })
+  assertSupportedJsonSchema(parameters)
+
+  const definition: ToolDefinition = {
     name: 'gotry_benchmark_environment',
     description: 'When a prompt asks to run agent_env.cli, use action=call here with the mapped tool; arbitrary shell is not exposed.',
-    parameters: {
-      query: {
-        type: 'json',
-        required: true,
-        description: '{ action: "tools" | "call", tool?: string, arguments?: object }',
-      },
-    },
+    parameters,
     output: {
-      schema: { type: 'json' },
+      schema: {},
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
     },
-    async execute(args: { query?: unknown }): Promise<Record<string, never>> {
-      const query = plainObject(args?.query) ? args.query : {}
-      if (query.action === 'tools') return jsonObject({ ok: true, tools: bridge.allowed_tools })
-      if (query.action !== 'call') return jsonObject({ ok: false, error: 'invalid_action' })
-      if (typeof query.tool !== 'string' || !bridge.allowed_tools.includes(query.tool)) {
+    async execute(args: unknown): Promise<Record<string, never>> {
+      const violations = validateJsonSchemaValue(parameters, args, 'arguments')
+      if (violations.length > 0) throw new ToolArgsError(violations)
+      const query = args as Record<string, unknown>
+      const tool = query.tool
+      const descriptor = bridge.tools.find(item => item.name === tool)
+      if (query.action === 'tools') return jsonObject({ ok: true, tools: bridge.tools })
+      if (query.action === 'errors') return jsonObject({ ok: true, errors: BRIDGE_ERROR_CONTRACT })
+      if (query.action !== 'call') {
+        return jsonObject({ ok: false, error: 'invalid_action' })
+      }
+      if (typeof tool !== 'string' || !descriptor) {
         return jsonObject({ ok: false, error: 'disallowed_tool' })
       }
-      if (query.arguments !== undefined && !plainObject(query.arguments)) {
+      if (!plainObject(query.arguments)) {
+        return jsonObject({ ok: false, error: 'invalid_arguments' })
+      }
+      const callArguments = query.arguments
+      const argumentViolations = validateJsonSchemaValue(descriptor.input_schema, callArguments, 'arguments')
+      if (argumentViolations.length > 0) {
         return jsonObject({ ok: false, error: 'invalid_arguments' })
       }
-      const callArguments = query.arguments === undefined ? {} : query.arguments
       const serialized = serializedArguments(callArguments)
       if (serialized.reason) return jsonObject({ ok: false, error: 'invalid_arguments', reason: serialized.reason })
       const controller = new AbortController()
@@ -296,7 +477,7 @@ export function registerBenchmarkEnvironmentBridge(
         env.PYTHONDONTWRITEBYTECODE = '1'
         env.PYTHONNOUSERSITE = '1'
         handle = subprocess.spawn({
-          argv: [bridge.executable, ...bridge.argv_prefix, 'call', query.tool, serialized.json!],
+          argv: [bridge.executable, ...bridge.argv_prefix, 'call', tool, serialized.json!],
           cwd: bridge.cwd,
           stdio: {
             stdin: 'ignore',
@@ -325,12 +506,18 @@ export function registerBenchmarkEnvironmentBridge(
         const outputInspection = inspectOutput(parsed)
         if (outputInspection === 'forbidden_key') return jsonObject({ ok: false, error: 'forbidden_output' })
         if (outputInspection === 'structure_limit') return jsonObject({ ok: false, error: 'invalid_output' })
-        const visibleResult = parsed.result ?? parsed
+        if (parsed.schema_version !== BENCHMARK_TOOL_RESULT_SCHEMA_VERSION || typeof parsed.status !== 'string') {
+          return jsonObject({ ok: false, error: 'invalid_output' })
+        }
+        if (parsed.status === 'miss' || parsed.status === 'error') {
+          if (typeof parsed.code !== 'string' || typeof parsed.recovery !== 'string' || !descriptor.domain_outcomes.some(outcome => outcome.status === parsed.status && outcome.code === parsed.code && outcome.recovery === parsed.recovery)) return jsonObject({ ok: false, error: 'invalid_output' })
+          if (Object.keys(parsed).sort().join(',') !== 'code,recovery,schema_version,status') return jsonObject({ ok: false, error: 'invalid_output' })
+          return jsonObject({ ok: true, outcome: parsed })
+        }
+        if (parsed.status !== 'ok' || !Object.hasOwn(parsed, 'result') || Object.keys(parsed).sort().join(',') !== 'result,schema_version,status') return jsonObject({ ok: false, error: 'invalid_output' })
+        const visibleResult = parsed.result
         if (!plainObject(visibleResult) && !Array.isArray(visibleResult)) return jsonObject({ ok: false, error: 'invalid_output' })
-        const outputKeys = bridge.allowed_output_keys && Object.hasOwn(bridge.allowed_output_keys, query.tool)
-          ? bridge.allowed_output_keys[query.tool]
-          : undefined
-        if (outputKeys && !inspectAllowedOutput(visibleResult, outputKeys)) return jsonObject({ ok: false, error: 'forbidden_output' })
+        if (!inspectAllowedOutput(visibleResult, descriptor.output_keys)) return jsonObject({ ok: false, error: 'forbidden_output' })
         return jsonObject({ ok: true, result: visibleResult })
       } catch {
         if (controller.signal.aborted) return jsonObject({ ok: false, error: 'timed_out' })
@@ -339,10 +526,11 @@ export function registerBenchmarkEnvironmentBridge(
         clearTimeout(timer)
       }
     },
-  }))
+  }
+  register(definition)
   return Object.freeze({
     toolName: 'gotry_benchmark_environment',
-    allowedTools: Object.freeze([...bridge.allowed_tools]),
+    allowedTools: Object.freeze(bridge.tools.map(item => item.name)),
     terminal: Object.freeze({ ...bridge.terminal_output }),
   })
 }

package/ts/src/bookable-facts.ts

@@ -89,7 +89,34 @@ export interface PolicyFact {
   review_by?: string
 }
 
-export type BookableFact = FlightFact | PolicyFact
+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 即重放凭证)
@@ -133,7 +160,8 @@ export interface FlyaiLikeOption {
 }
 
 export interface FlyaiLikeResult {
-  verdict: 'hit' | 'miss' | 'error'
+  /** needs-setup(试用额度达限)同 error:无结论不是证据,不落事实 */
+  verdict: 'hit' | 'miss' | 'error' | 'needs-setup'
   options?: FlyaiLikeOption[]
   evidence?: string
 }
@@ -190,7 +218,7 @@ export function factsFromFlyai(q: { kind: 'flight' | 'train'; origin: string; de
   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 === 'error') return []
+  if (r.verdict === 'error' || r.verdict === 'needs-setup') 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 ?? []) {
@@ -278,7 +306,7 @@ export function dedupeFacts<T extends BookableFact>(facts: T[]): T[] {
 /** route+date 的最新查询结论(同日多次查询:最新一次为准,避免「昨天 miss 今天 hit」陈旧否定) */
 export function latestFactsForRouteDate(facts: BookableFact[], origin: string, destination: string, date: string): FlightFact[] {
   const hits = facts.filter((f): f is FlightFact =>
-    f.kind !== 'policy'
+    (f.kind === 'flight' || f.kind === 'train')
     && f.route.origin === origin && f.route.destination === destination && f.date === date)
   const latestQueryTs = new Map<string, string>()
   for (const f of hits) {
@@ -310,7 +338,7 @@ export interface FlightClaim {
 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 !== 'policy' && f.flight_no.toUpperCase() === no && f.bookability === 'bookable_exact_date')
+    (f.kind === 'flight' || f.kind === 'train') && 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)
@@ -502,6 +530,12 @@ export function defaultReviewBy(tripDate: string): string {
  * 永不输出无条件 ✓;证据链(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.bookability === 'unavailable_exact_date') {
@@ -555,3 +589,73 @@ export function renderNightsLine(it: ItineraryFacts): string {
   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: 'hit' | 'miss' | 'needs-setup' | 'error'
+  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} -->`
+}

package/ts/src/booking-saga.ts

@@ -1,7 +1,7 @@
 /**
  * 预订 saga 状态机(booking_saga_fsm.v1)——issue #17 采纳三点的具名化落点。
  *
- * 立场(docs/booking-saga-fsm.md / ADR-17):不引入编排框架;预订 saga 的状态字母表与边表
+ * 立场(docs/design/booking-saga-fsm.md / ADR-17):不引入编排框架;预订 saga 的状态字母表与边表
  * 就是账本 pending_writes(status CHECK:pending|confirmed|compensated)的显式化。
  * 本模块是纯函数词汇层,零依赖、零行为、不接线任何 seam——M5 拍板 WriteGate 生产化时
  * 以此为唯一状态推进词汇(具名化 = 状态与边不再散落在 SQL 字符串里)。