@danceiny/gotry 0.2.0-rc.31 → 0.2.0-rc.33

package/ts/src/index.ts

@@ -523,7 +523,7 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
   // 派生的后台规划会话:唯一出口 converge + 长 leash——前台转后台,后台
   // 必须产出最终交付物,不得再次 handoff(否则无限递归)。
   if (!rawBenchmarkEnvironmentConfigPath) {
-    registerGotryWebApi(ctx, config.stateRoot ?? '.')
+    registerGotryWebApi(ctx, config.stateRoot ?? '.', config.hbcliBin)
     registerArtifactDeliveries(ctx)
   }
   const handoffChild = process.env.GOTRY_HANDOFF_CHILD === '1'
@@ -1419,10 +1419,15 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       const resp = itp.result
       const dir = await ensureStateDir(config.stateRoot)
       const isLive = resp.via === 'hbcli-realtime'
-      const evidence = isLive ? resp.evidence : '[静态包:估算]'
+      const staticStays = (resp.hotels as { stays?: unknown[] } | null)?.stays
+      const hasEstimate = Array.isArray(staticStays) && staticStays.length > 0
+      const liveList = (resp.hotels as { list?: unknown[] } | null)?.list
+      const verdict = isLive ? (liveList?.length ? 'hit' : 'miss') : hasEstimate ? 'estimated' : 'error'
+      const evidence = hasEstimate ? '[静态包:估算]' : resp.evidence
       await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `hotel_search:${resp.via}`).catch(() => {})
       const payload = {
-        ok: true,
+        ok: isLive || hasEstimate,
+        verdict,
         hotels: resp.hotels ?? null,
         evidence,
         destination: q.destination,
@@ -1430,6 +1435,7 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
         latency_ms: Date.now() - started,
         summary: resp.summary,
         error: resp.error,
+        ...(verdict !== 'hit' ? await routingField('search-hotel', 'hbcli-hotel') : {}),
         ...(dateNotes.length ? { date_notes: dateNotes } : {}),
       } as never
       return JSON.parse(JSON.stringify(payload)) as never
@@ -1456,13 +1462,14 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
         }
       }
       const h = r.hotels
-      const liveCount = Array.isArray(h) ? h.length : 0
+      const liveList = (h as { list?: unknown[] } | null)?.list
+      const liveCount = Array.isArray(liveList) ? liveList.length : 0
       // 静态包是 {meta, stays} 对象而非数组(issue #24:此前计数恒 0 → UI 显示「无结果」)
       const stays = !Array.isArray(h) && h && typeof h === 'object' ? (h as { stays?: unknown[] }).stays : undefined
       const staticCount = Array.isArray(stays) ? stays.length : 0
       const tag = r.via === 'hbcli-realtime'
-        ? (liveCount ? `实时 ${liveCount} 家` : '实时')
-        : staticCount ? `静态包 ${staticCount} 块` : (liveCount ? `${liveCount} 家` : '无结果')
+        ? `实时 ${liveCount} 家`
+        : staticCount ? `静态包 ${staticCount} 块` : '查询未完成'
       return {
         card: 'generic',
         title: `酒店:${r.destination ?? ''} ${tag}`,
@@ -1859,8 +1866,9 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       'Search on the USER\'S OWN browser session (Ctrip kind="flight"(default)/"hotel"; 12306 kind="train" — public query face, no login needed). '
       + '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). '
       + 'Transport: Stai Travel 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). '
-      + 'kind="flight": from/to 中文城市名 + date YYYY-MM-DD — sniffs the site search API for structured options. Evidence [会话:ctrip-flight@ts]. '
-      + 'kind="hotel": to=目的地中文, cityId? = the numeric city= in a hotels.ctrip.com list URL (web-search it when the destination is outside the built-in city table), checkIn?/checkOut? (YYYY-MM-DD), adults?; hotel prices are the user\'s real logged-in prices. Evidence [会话:ctrip-hotel@ts]. '
+      + 'kind="flight": from/to city or airport names (Chinese/English) + date YYYY-MM-DD; unknown names resolve from supplier metadata, ambiguous names require confirmation; optional fromCityCode/toCityCode are explicit Ctrip three-letter codes — sniffs the site search API for structured options. '
+      + 'ui?="bridge" (default; the user\'s own logged-in session, real member prices) | "gui" (gotry opens its OWN isolated anonymous Chrome window and drives the Ctrip PC search form — roundtrip via backDate? and ANY city by construction: the site\'s own autocomplete resolves cities; anonymous public prices, NOT logged-in prices; verdicts carry anonymous=true; result-binding iteration tracked in #661). Evidence [会话:ctrip-flight@ts] / [会话:ctrip-flight-gui@ts]. '
+      + 'kind="hotel": to=destination name, country? for same-name disambiguation; cityId? = explicit numeric city= from a Ctrip hotel list URL; otherwise resolves from the hotel destination service, checkIn?/checkOut? (YYYY-MM-DD), adults?; hotel prices are the user\'s real logged-in prices. Evidence [会话:ctrip-hotel@ts]. '
       + 'kind="dida": Dida supplier-portal realtime hotel rates on the employee\'s own logged-in session (hotel-be portal integration line) — no from/to needed; the portal find page\'s own requests are sniffed passively. Rates carry ratePlanId/referenceNo for the server-side booking chain. Evidence [会话:dida-portal@ts]. '
       + 'kind="train": from/to/date(YYYY-MM-DD) + fromStationTelecode?/toStationTelecode? (three-letter codes in the kyfw query URL, for cities outside the built-in table) — 12306 left-ticket query (public face): train codes, times, durations, seat availability; the list API carries NO prices (prices live on the 12306 page). Evidence [会话:train-12306@ts]. '
       + '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); '
@@ -1873,21 +1881,28 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
     // execute 内归一后走原条件闸,结构化报错不崩。flyai 因 kind required 仍在宿主权即拒。
     parameters: {
       kind: { type: 'string', enum: ['flight', 'hotel', 'train', 'dida'], description: '默认 flight 机票;hotel 携程酒店(用户登录态真实价);train 12306 余票(公开面);dida 供应商门户实时价(员工登录态)' },
-      from: { type: 'string', description: '出发城市中文(词表内),如 上海——kind=flight|train 必填' },
+      from: { type: 'string', description: '出发城市名（机票支持中英文及机场名，自动解析），如 上海——kind=flight|train 必填' },
       to: { type: 'string', description: '到达城市中文——kind=flight|train 必填;kind=hotel 时为目的地(必填)' },
       date: { type: 'string', description: '出发日期 YYYY-MM-DD——kind=flight|train 必填,须为今天或未来' },
-      cityId: { type: 'integer', description: '携程酒店 city= 数字,仅 kind=hotel;目的地码表外时 web 搜 hotels.ctrip.com list URL 取 city=' },
+      fromCityCode: { type: 'string', description: '显式携程出发城市／机场三字码，仅 kind=flight；同名城市确认后使用' },
+      toCityCode: { type: 'string', description: '显式携程到达城市／机场三字码，仅 kind=flight；同名城市确认后使用' },
+      cityId: { type: 'integer', description: '显式携程酒店 city= 数字，仅 kind=hotel；未提供时自动解析酒店目的地，不能使用机票城市码' },
+      country: { type: 'string', description: '目的地国家中英文，仅 kind=hotel；用于同名城市消歧，例如 阿联酋' },
       checkIn: { type: 'string', description: '入住日 YYYY-MM-DD,仅 kind=hotel 可选' },
       checkOut: { type: 'string', description: '退房日 YYYY-MM-DD,仅 kind=hotel 可选' },
       adults: { type: 'integer', description: '成人数,仅 kind=hotel 可选' },
       fromStationTelecode: { type: 'string', description: '出发站三位电报码,仅 kind=train;城市码表外时填(kyfw 查询页 URL 里)' },
       toStationTelecode: { type: 'string', description: '到达站三位电报码,仅 kind=train,同上' },
+      backDate: { type: 'string', description: '回程日期 YYYY-MM-DD,仅 kind=flight;存在即往返检索——须 ui=gui(GUI 车道站点表单原生往返;bridge 车道不知往返 URL 形状,不猜)' },
+      ui: { type: 'string', enum: ['bridge', 'gui'], description: 'kind=flight|hotel:bridge(默认,用户登录态被动嗅探)|gui(gotry 隔离匿名窗口驱动 PC 表单——flight 往返/多程/任意城市原生+低价日历;hotel 任意目的地原生;匿名公开价)' },
+      legs: { type: 'string', description: '多程段 JSON 数组,仅 kind=flight+ui=gui:[{"from":"香港","to":"迪拜","date":"2026-12-06"},{"from":"迪拜","to":"上海","date":"2026-12-10"}](2–3 段)' },
+      interactiveLogin: { type: 'boolean', description: '仅 ui=gui:登录墙命中时窗口停在携程官方登录页,等用户本人在窗口内完成登录(最多 6 分钟)后自动重查,拿登录态真实数据(行程明细/酒店真实价)。gotry 永不经手密码/验证码/cookie 值' },
     },
     output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String((v as { summary?: string }).summary ?? JSON.stringify(v).slice(0, 600)) }] },
     async execute(args, _exec) {
       const selectedKind = resolveSessionSearchKind(args)
       if (!selectedKind.ok) return { ok: false, summary: selectedKind.reason } as const
-      const q = { ...unwrapQuery<{ kind?: string; from?: string; to?: string; date?: string; cityId?: number | string; checkIn?: string; checkOut?: string; adults?: number; fromStationTelecode?: string; toStationTelecode?: string }>(args), kind: selectedKind.kind }
+      const q = { ...unwrapQuery<{ kind?: string; from?: string; to?: string; date?: string; fromCityCode?: string; toCityCode?: string; cityId?: number | string; country?: string; checkIn?: string; checkOut?: string; adults?: number; fromStationTelecode?: string; toStationTelecode?: string; backDate?: string; ui?: string; legs?: string; interactiveLogin?: boolean }>(args), kind: selectedKind.kind }
       const runSessionEffect = seams.effect ?? interpretEffect
       // ---- Dida 供应商门户(2026-09-09 实装;hotel-be portal integration 迁移线)----
       if (q.kind === 'dida') {
@@ -1955,16 +1970,17 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       }
       if (q.kind === 'hotel') {
         if (!q.to) {
-          return { ok: false, summary: 'kind=hotel 需要 to(目的地中文;城市码表外带 cityId=携程酒店 list 页 URL 里的 city= 数字)' } as const
+          return { ok: false, summary: 'kind=hotel 需要 to（目的地名称）；自动解析城市，同名城市可带 country 或确认后的 cityId' } as const
         }
         const itp = await runSessionEffect({
-          effect: 'SESSION_HOTEL_SEARCH',
+          effect: q.ui === 'gui' ? 'SESSION_HOTEL_GUI_SEARCH' : 'SESSION_HOTEL_SEARCH',
           params: {
-            to: q.to, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults,
+            to: q.to, country: q.country, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults,
+            ...(q.ui === 'gui' && q.interactiveLogin ? { interactiveLoginMs: 360_000 } : {}),
             auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
           },
         })
-        if (!itp.result) return declinedObservation('SESSION_HOTEL_SEARCH', itp.trace)
+        if (!itp.result) return declinedObservation(q.ui === 'gui' ? 'SESSION_HOTEL_GUI_SEARCH' : 'SESSION_HOTEL_SEARCH', itp.trace)
         const r = itp.result
         await noteChannel('session:ctrip-hotel', r.verdict)
         // D-26(issue #118):exact-date 会话酒店 hit/miss 落账(摸底无档期不落;cooldown 是节律闸非结论,不落)
@@ -1986,14 +2002,42 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
         })) as Record<string, never>
       }
       if (!q.from || !q.to || !q.date) {
-        return { ok: false, summary: '需要 from/to(中文城市名,词表内)与 date(YYYY-MM-DD);酒店/火车检索分别用 kind=hotel / kind=train' } as const
+        return { ok: false, summary: '需要 from/to（城市或机场名）与 date（YYYY-MM-DD）;酒店/火车检索分别用 kind=hotel / kind=train' } as const
       }
       // 效应解译层(ADR-18):SESSION 通道策略=永不重试/不熔断,节律闸在渠道内;
       // 解译器只做分发与证据拼装,verdict 语义(risk 型 needs-login/challenged)原样透传
+      // GUI 车道(2026-10-14):ui=gui → gotry 隔离匿名窗口驱动 PC 表单(往返 backDate/任意城市原生)。
+      if (q.ui !== undefined && q.ui !== 'bridge' && q.ui !== 'gui') {
+        return { ok: false, summary: 'kind=flight 的 ui 只接受 bridge(默认,登录态被动嗅探)|gui(隔离匿名窗口驱动表单)' } as const
+      }
+      // 多程段(仅 gui;严格形状闸——2–3 段、城市非空、日期 YMD、段内日期递增)
+      let legs: Array<{ from: string; to: string; date: string }> | undefined
+      if (q.legs !== undefined) {
+        if (q.ui !== 'gui') return { ok: false, summary: 'legs(多程)仅支持 ui=gui(GUI 车道驱动多程表单)' } as const
+        try {
+          const parsed = JSON.parse(q.legs) as unknown
+          if (!Array.isArray(parsed) || parsed.length < 2 || parsed.length > 3) throw new Error('段数须 2–3')
+          legs = parsed.map((raw: unknown) => {
+            const leg = raw as { from?: unknown; to?: unknown; date?: unknown }
+            if (typeof leg.from !== 'string' || !leg.from.trim() || typeof leg.to !== 'string' || !leg.to.trim() || typeof leg.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(leg.date)) {
+              throw new Error('每段须 {from,to,date(YYYY-MM-DD)}')
+            }
+            return { from: leg.from.trim(), to: leg.to.trim(), date: leg.date }
+          })
+          for (let i = 1; i < legs.length; i += 1) {
+            if (legs[i]!.date <= legs[i - 1]!.date) throw new Error('段日期须递增')
+          }
+        } catch (e) {
+          return { ok: false, summary: `legs 形状非法:${(e as Error).message}` } as const
+        }
+      }
       const itp = await runSessionEffect({
-        effect: 'SESSION_FLIGHT_SEARCH',
+        effect: q.ui === 'gui' ? 'SESSION_FLIGHT_GUI_SEARCH' : 'SESSION_FLIGHT_SEARCH',
         params: {
-          from: q.from, to: q.to, date: q.date,
+          from: q.from, to: q.to, date: q.date, fromCityCode: q.fromCityCode, toCityCode: q.toCityCode,
+          ...(q.backDate ? { backDate: q.backDate } : {}),
+          ...(legs ? { legs } : {}),
+          ...(q.ui === 'gui' && q.interactiveLogin ? { interactiveLoginMs: 360_000 } : {}),
           // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
           auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
         },
@@ -2005,8 +2049,12 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       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 lane = q.ui === 'gui' ? `GUI 车道(携程,匿名公开价${q.backDate ? ',往返' : ''})` : '会话检索(携程,用户本人登录态)'
+      const cal = (r.calendar ?? []).slice(0, 14).map(d => `${d.date} ${d.price !== undefined ? `¥${d.price}` : (d.priceRaw ?? '?')}`)
+      const calBlock = cal.length > 0 ? `\n低价日历(匿名公开价,该航线哪些日期有票):\n${cal.join(' | ')}` : ''
+      const urlBlock = q.ui === 'gui' && r.listUrl ? `\nlistUrl(站点真实形状,#663 URL 教师):${r.listUrl.slice(0, 160)}` : ''
       const summary = r.verdict === 'hit'
-        ? `${q.from}→${q.to} ${q.date} 会话检索(携程,用户本人登录态)前 ${top.length} 条:\n${top.join('\n')}\n${r.evidence}`
+        ? `${q.from}→${q.to} ${q.date} ${lane}${(r.options ?? []).length > 0 ? ` 行情前 ${top.length} 条:\n${top.join('\n')}` : ''}${calBlock}${urlBlock}\n${r.evidence}`
         : `会话检索未取回(${r.verdict}):${r.error ?? ''} ${r.evidence}`
       return JSON.parse(JSON.stringify({
         ...r, summary,

package/ts/src/llm-price-table.ts

@@ -0,0 +1,180 @@
+/**
+ * The frozen LLM price table (ADR-20) and the one function that turns measured usage into dollars.
+ *
+ * Moved verbatim from `scripts/nightly-evidence.ts`, which re-exports it, so the nightly evidence producer, the
+ * persona simulation and the AaaS quota meter all price through the same code. Prices live in
+ * `data/llm-price-table.json` and change only by PR (never auto-applied). Pricing is a peak-conservative upper bound,
+ * an unknown model has no price, and usage a provider omitted is unprovable: both fail closed and never guess.
+ *
+ * Schema evolution (issue #49): `gotry_llm_price_table_v1` is DeepSeek only, with flat fields under `prices.<model>`;
+ * `gotry_llm_price_table_v2` is `providers.<id>.models.<model>`, provider-aware, and lets a provider without an
+ * off-peak column fill it with the peak price. `loadPriceTable` reads both.
+ */
+
+import { readFileSync } from 'node:fs'
+import type { LlmUsageTracker } from './dsh-llm.ts'
+
+export interface PriceEntry {
+  input_cache_miss_usd_per_1m_peak: number
+  input_cache_miss_usd_per_1m_offpeak: number
+  input_cache_hit_usd_per_1m_peak: number
+  input_cache_hit_usd_per_1m_offpeak: number
+  output_usd_per_1m_peak: number
+  output_usd_per_1m_offpeak: number
+}
+
+export interface LlmPriceTable {
+  schema_version: 'gotry_llm_price_table_v1' | 'gotry_llm_price_table_v2'
+  aliases: Record<string, string>
+  prices: Record<string, PriceEntry>
+}
+
+function round6(value: number): number {
+  return Number(value.toFixed(6))
+}
+
+function assertPriceEntry(label: string, value: unknown): PriceEntry {
+  const entry = typeof value === 'object' && value !== null ? value as Record<string, unknown> : null
+  if (!entry) throw new Error(`${label} must be an object`)
+  for (const field of ['input_cache_miss_usd_per_1m_peak', 'input_cache_hit_usd_per_1m_peak', 'output_usd_per_1m_peak']) {
+    const num = entry[field]
+    if (typeof num !== 'number' || !Number.isFinite(num) || num < 0) {
+      throw new Error(`${label}.${field} must be a non-negative finite number`)
+    }
+  }
+  return value as PriceEntry
+}
+
+export function loadPriceTable(path: string): LlmPriceTable {
+  const raw = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+  const schemaVersion = raw['schema_version']
+  if (schemaVersion === 'gotry_llm_price_table_v2') {
+    return loadPriceTableV2(raw)
+  }
+  if (schemaVersion === 'gotry_llm_price_table_v1') {
+    return loadPriceTableV1(raw)
+  }
+  throw new Error(`price table schema_version must be gotry_llm_price_table_v1 or _v2, got: ${String(schemaVersion)}`)
+}
+
+function loadPriceTableV1(raw: Record<string, unknown>): LlmPriceTable {
+  const aliases = typeof raw['aliases'] === 'object' && raw['aliases'] !== null ? raw['aliases'] as Record<string, string> : {}
+  for (const [from, to] of Object.entries(aliases)) {
+    if (typeof to !== 'string') throw new Error(`price table alias ${from} must map to a model name`)
+  }
+  const prices: Record<string, PriceEntry> = {}
+  for (const [name, entry] of Object.entries(typeof raw['prices'] === 'object' && raw['prices'] !== null ? raw['prices'] as Record<string, unknown> : {})) {
+    prices[name] = assertPriceEntry(`price table entry ${name}`, entry)
+  }
+  return { schema_version: 'gotry_llm_price_table_v1', aliases, prices }
+}
+
+interface ProviderEntry {
+  family: string
+  price_strategy: 'tiered_peak_offpeak' | 'flat_no_offpeak' | string
+  api_base?: string
+  source_url?: string
+  aliases: Record<string, string>
+  models: Record<string, PriceEntry>
+}
+
+/** v2 reader: providers.<id>.models.<model> flattened into one aliases/prices pair, so the exposed API does not change.
+ *  Lookup for a model name:
+ *    1. an alias jumps to its target (qualified `providerId:model`);
+ *    2. otherwise the qualified `providerId:model` key is looked up in prices;
+ *    3. otherwise the bare `model` key (transparent with one provider, e.g. MiniMax-M3 is unique under minimax:models);
+ *    4. still not found: fail closed. */
+function loadPriceTableV2(raw: Record<string, unknown>): LlmPriceTable {
+  const providersObj = typeof raw['providers'] === 'object' && raw['providers'] !== null ? raw['providers'] as Record<string, unknown> : null
+  if (!providersObj) throw new Error('price table v2 requires providers object')
+  const aliases: Record<string, string> = {}
+  const prices: Record<string, PriceEntry> = {}
+  for (const [providerId, rawProvider] of Object.entries(providersObj)) {
+    const provider = assertProviderEntry(`price table provider ${providerId}`, rawProvider)
+    for (const [aliasName, target] of Object.entries(provider.aliases)) {
+      if (typeof target !== 'string') throw new Error(`provider ${providerId} alias ${aliasName} must map to a model name`)
+      if (!provider.models[target]) {
+        throw new Error(`provider ${providerId} alias ${aliasName} -> ${target} has no entry; update data/llm-price-table.json via PR`)
+      }
+      aliases[aliasName] = target
+    }
+    for (const [modelName, entry] of Object.entries(provider.models)) {
+      const qualified = `${providerId}:${modelName}`
+      const validated = assertPriceEntry(`price table provider ${providerId} model ${modelName}`, entry)
+      if (prices[qualified]) throw new Error(`duplicate price table key ${qualified}`)
+      prices[qualified] = validated
+      if (prices[modelName]) throw new Error(`duplicate price table key ${modelName} (across providers, disambiguate via aliases or qualified lookup)`)
+      prices[modelName] = validated
+    }
+  }
+  return { schema_version: 'gotry_llm_price_table_v2', aliases, prices }
+}
+
+function assertProviderEntry(label: string, value: unknown): ProviderEntry {
+  const entry = typeof value === 'object' && value !== null ? value as Record<string, unknown> : null
+  if (!entry) throw new Error(`${label} must be an object`)
+  const family = entry['family']
+  if (typeof family !== 'string' || family.length === 0) throw new Error(`${label}.family must be a non-empty string`)
+  const strategy = entry['price_strategy']
+  if (strategy !== 'tiered_peak_offpeak' && strategy !== 'flat_no_offpeak') {
+    throw new Error(`${label}.price_strategy must be 'tiered_peak_offpeak' or 'flat_no_offpeak', got: ${String(strategy)}`)
+  }
+  const aliases = typeof entry['aliases'] === 'object' && entry['aliases'] !== null ? entry['aliases'] as Record<string, string> : {}
+  const models = typeof entry['models'] === 'object' && entry['models'] !== null ? entry['models'] as Record<string, PriceEntry> : {}
+  return {
+    family,
+    price_strategy: strategy,
+    api_base: typeof entry['api_base'] === 'string' ? entry['api_base'] as string : undefined,
+    source_url: typeof entry['source_url'] === 'string' ? entry['source_url'] as string : undefined,
+    aliases,
+    models,
+  }
+}
+
+/** Dollars for one run's measured usage (peak-conservative upper bound: the table's peak columns, never a guess). */
+export function priceRunCost(model: string, usage: LlmUsageTracker, table: LlmPriceTable): number {
+  if (usage.responsesMissingUsage > 0) {
+    throw new Error(`usage provider omitted usage on ${usage.responsesMissingUsage} response(s) — cost unprovable, refusing to price (fail-closed)`)
+  }
+  const alias = table.aliases[model]
+  if (alias && !table.prices[alias]) throw new Error(`price table alias ${model} -> ${alias} has no entry; update data/llm-price-table.json via PR`)
+  const entry = table.prices[alias ?? model]
+  if (!entry) throw new Error(`price table has no entry for model ${model}; update data/llm-price-table.json via PR (fail-closed, no guessed price)`)
+  const cost = (usage.inputCacheMissTokens * entry.input_cache_miss_usd_per_1m_peak
+    + usage.inputCacheHitTokens * entry.input_cache_hit_usd_per_1m_peak
+    + usage.outputTokens * entry.output_usd_per_1m_peak) / 1_000_000
+  return round6(cost)
+}
+
+/** The usage a planner invocation reports: fresh input, cache-read input and output tokens, as the gateway adapter maps them. */
+export interface MeasuredLlmUsage {
+  readonly inputTokens: number
+  readonly outputTokens: number
+  readonly cacheReadTokens?: number
+}
+
+function nonNegativeInteger(name: string, value: unknown): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative integer`)
+  return value
+}
+
+/** `priceRunCost` for one measured usage report. Malformed counts are rejected rather than priced. */
+export function priceMeasuredUsage(model: string, usage: MeasuredLlmUsage, table: LlmPriceTable): { readonly tokens: number; readonly costUsd: number } {
+  const inputTokens = nonNegativeInteger('inputTokens', usage.inputTokens)
+  const outputTokens = nonNegativeInteger('outputTokens', usage.outputTokens)
+  const cacheReadTokens = nonNegativeInteger('cacheReadTokens', usage.cacheReadTokens ?? 0)
+  const costUsd = priceRunCost(model, {
+    calls: 1,
+    inputTokens: inputTokens + cacheReadTokens,
+    outputTokens,
+    inputCacheHitTokens: cacheReadTokens,
+    inputCacheMissTokens: inputTokens,
+    responsesMissingUsage: 0,
+  }, table)
+  return { tokens: inputTokens + cacheReadTokens + outputTokens, costUsd }
+}
+
+/** Throws unless the table prices `model`. Used at composition time so an unpriced model stops the service before any spend. */
+export function assertModelPriced(model: string, table: LlmPriceTable): void {
+  priceRunCost(model, { calls: 0, inputTokens: 0, outputTokens: 0, inputCacheHitTokens: 0, inputCacheMissTokens: 0, responsesMissingUsage: 0 }, table)
+}

package/ts/src/tenant-seam/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The trusted seam of the AaaS line (docs/rfc/aaas-rfc.md §4.4): tenant derivation from the authenticated caller, and
+ * the quotas and metering that keep one tenant or organization from moving another's latency budget. Outside the kernel.
+ */
+
+export * from './quotas.ts'
+export * from './seam.ts'
+export * from './llm-broker.ts'
+export * from './process-governor.ts'