@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/capabilities/hbcli.js

@@ -1,168 +1,181 @@
+/**
+ * hotelbyte-cli(hbcli)能力层封装:进程内 spawn bun + hbcli --json。
+ *
+ * 拿到外部资源信息能力的三条路径:
+ *   1. 实时 hbcli 调用(能力强,延迟 1-3s,需凭证 + 证书有效)
+ *   2. 静态数据包(data/hotels_2026.json)——证据标注 [静态包:估算]
+ *   3. 简易降级返回(什么都不查得到时,提供"工具暂不可用"而不是抛错)
+ *
+ * 证书/凭证/网络问题一律降级,不抛到调用方——能力层契约:永远返回一种结果。
+ *
+ * §7-1/§7-2 L4 不变量:证据链标注([实时API:hbcli@<ts>] / [静态包:估算]);
+ * 估算必须显式标记。这是 L4 与 L1 透明卡片的接缝。
+ */
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+/**
+ * hbcli 二进制候选路径(gotry setup 按官方脚本装到 ~/.local/bin/hbcli,
+ * symlink 指向 ~/.staicli/current/hbcli——当 PATH 不含 ~/.local/bin 时裸名
+ * spawn 仍 ENOENT,按已知安装位回退)。仅对默认名 'hbcli' 扩展;显式自定义
+ * 名(如测试注入的不存在路径)不扩展,保持配置即所用的可测性。
+ */
 export function hbcliBinCandidates(bin, homeDir = homedir()) {
-    if (bin !== 'hbcli') return [
-        bin
-    ];
-    return [
-        bin,
-        join(homeDir, '.local/bin/hbcli'),
-        join(homeDir, '.staicli/current/hbcli')
-    ];
+    if (bin !== 'hbcli')
+        return [bin];
+    return [bin, join(homeDir, '.local/bin/hbcli'), join(homeDir, '.staicli/current/hbcli')];
 }
+/** 单个候选的一次 spawn 封装:失败不抛,返回降级结果(spawnError 标记 ENOENT 类失败供上层换候选) */
 function attemptHbcli(bin, args, opts) {
     const started = Date.now();
-    return new Promise((resolve)=>{
+    return new Promise((resolve) => {
         let stdout = '';
         let stderr = '';
         let settled = false;
-        const child = spawn(bin, args, {
-            env: {
-                ...process.env,
-                ...opts.envVars
-            }
-        });
-        const timer = setTimeout(()=>{
+        const child = spawn(bin, args, { env: { ...process.env, ...opts.envVars } });
+        const timer = setTimeout(() => {
             if (!settled) {
                 settled = true;
                 child.kill('SIGKILL');
                 resolve({
-                    via: 'hbcli-error',
-                    exitCode: -1,
-                    result: null,
+                    via: 'hbcli-error', exitCode: -1, result: null,
                     evidence: `[实时API:hbcli@timeout@${new Date().toISOString()}]`,
-                    latencyMs: Date.now() - started,
-                    error: `timeout after ${opts.timeoutMs}ms`
+                    latencyMs: Date.now() - started, error: `timeout after ${opts.timeoutMs}ms`,
                 });
             }
         }, opts.timeoutMs);
-        child.stdout.on('data', (d)=>{
-            stdout += d.toString();
-        });
-        child.stderr.on('data', (d)=>{
-            stderr += d.toString();
-        });
-        child.on('close', (code)=>{
-            if (settled) return;
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        child.on('close', (code) => {
+            if (settled)
+                return;
             settled = true;
             clearTimeout(timer);
             const latencyMs = Date.now() - started;
             if (code !== 0) {
+                // 不抛错,降级返回。证据链显式标注:实时 API 调用失败+原因+时间戳。
                 resolve({
-                    via: 'hbcli-error',
-                    exitCode: code ?? -1,
-                    result: null,
+                    via: 'hbcli-error', exitCode: code ?? -1, result: null,
                     evidence: `[实时API:hbcli@error@${new Date().toISOString()}]`,
                     stderr: stderr.slice(0, 2000),
-                    latencyMs,
-                    error: stderr.trim().slice(0, 200) || `exit ${code}`
+                    latencyMs, error: stderr.trim().slice(0, 200) || `exit ${code}`,
                 });
                 return;
             }
+            // 尝试 JSON 解析
             const jStart = stdout.search(/[\{\[]/);
             const jsonStr = jStart >= 0 ? stdout.slice(jStart) : '';
             let result = null;
             if (jsonStr) {
                 try {
                     result = JSON.parse(jsonStr);
-                } catch  {}
+                }
+                catch { /* 非 JSON 输出,留给调用方处理 */ }
             }
             resolve({
-                via: 'hbcli-realtime',
-                exitCode: 0,
-                result,
+                via: 'hbcli-realtime', exitCode: 0, result,
                 evidence: `[实时API:hbcli@${new Date().toISOString()}]`,
-                stdout: stdout.slice(0, 2000),
-                latencyMs
+                stdout: stdout.slice(0, 2000), latencyMs,
             });
         });
-        child.on('error', (e)=>{
-            if (settled) return;
+        child.on('error', (e) => {
+            if (settled)
+                return;
             settled = true;
             clearTimeout(timer);
+            // ENOENT (二进制不存在) 等也走降级路径;spawnError 供上层按候选路径重试
             resolve({
-                via: 'hbcli-error',
-                exitCode: -1,
-                result: null,
+                via: 'hbcli-error', exitCode: -1, result: null,
                 evidence: `[实时API:hbcli@spawn_error@${new Date().toISOString()}]`,
-                latencyMs: Date.now() - started,
-                error: e.message,
-                spawnError: true
+                latencyMs: Date.now() - started, error: e.message, spawnError: true,
             });
         });
     });
 }
+/** 通用 hbcli JSON 调用封装:失败不抛,而是返回降级结果 */
 export async function callHbcliJson(args, opts = {}) {
     const env = opts.env ?? 'uat';
-    const envVars = {
-        HOTELBYTE_ENV: env
-    };
-    if (opts.token) envVars['HOTELBYTE_TOKEN'] = opts.token;
-    const callOpts = {
-        timeoutMs: opts.timeoutMs ?? 15_000,
-        env,
-        envVars
-    };
+    const envVars = { HOTELBYTE_ENV: env };
+    if (opts.token)
+        envVars['HOTELBYTE_TOKEN'] = opts.token;
+    const callOpts = { timeoutMs: opts.timeoutMs ?? 15_000, env, envVars };
     const candidates = hbcliBinCandidates(opts.hbcliBin ?? 'hbcli');
     let last;
-    for (const bin of candidates){
+    for (const bin of candidates) {
         last = await attemptHbcli(bin, args, callOpts);
-        if (!(last.spawnError && candidates.indexOf(bin) < candidates.length - 1)) return last;
+        // spawn 级失败(ENOENT 等)且还有候选 → 换下一个已知安装位;其余失败(退码/超时)无重试意义
+        if (!(last.spawnError && candidates.indexOf(bin) < candidates.length - 1))
+            return last;
     }
     return last;
 }
+/** 上游 i18n 名称容错读取(zh 优先,中文优先产品口径;回退 en/ar) */
 function i18nName(v) {
-    if (!v) return '';
-    if (typeof v === 'string') return v;
+    if (!v)
+        return '';
+    if (typeof v === 'string')
+        return v;
     return v.zh || v.en || v.ar || '';
 }
+/**
+ * 实时 hotelList 响应 → 模型可读紧凑行(id/名称/星级/最低价)。
+ * issue #195:render 面只透 summary,若 summary 不含数据,模型只看到
+ * 「实时返回」四个字——工具调用等于白调。id 必须在行内,hotel-rates 的入参
+ * 就来自这里。上游 wire:HotelListResp{list:[Hotel{id,name:{en,zh},star,minPrice:{amount,currency}}]}。
+ */
 function hotelLines(result, max = 8) {
     const list = result?.list;
-    if (!Array.isArray(list) || list.length === 0) return '';
+    if (!Array.isArray(list) || list.length === 0)
+        return '';
     const lines = [];
-    for (const item of list.slice(0, max)){
+    for (const item of list.slice(0, max)) {
         const h = item;
         const name = i18nName(h.name) || `hotel ${h.id ?? '?'}`;
         const star = typeof h.star === 'number' && h.star > 0 ? ` ${h.star}★` : '';
-        const price = h.minPrice && typeof h.minPrice.amount === 'number' ? ` 低至 ${h.minPrice.amount}${h.minPrice.currency ? ` ${h.minPrice.currency}` : ''}` : '';
+        const price = h.minPrice && typeof h.minPrice.amount === 'number'
+            ? ` 低至 ${h.minPrice.amount}${h.minPrice.currency ? ` ${h.minPrice.currency}` : ''}`
+            : '';
         lines.push(`- id=${h.id ?? '?'} ${name}${star}${price}`);
     }
-    if (list.length > max) lines.push(`…(共 ${list.length} 家,仅列前 ${max})`);
+    if (list.length > max)
+        lines.push(`…(共 ${list.length} 家,仅列前 ${max})`);
     return lines.join('\n');
 }
+/** 高层语义化封装:酒店列表查询(down-tier to 静态包 + 证据链标注) */
 export async function searchHotels(query, opts = {}) {
-    const hbArgs = [
-        'search',
-        'hotel-list',
-        '--json',
-        '--page-size',
-        '10'
-    ];
-    if (query.destination) hbArgs.push('--destination-name', query.destination);
-    if (query.checkIn) hbArgs.push('--check-in', query.checkIn);
-    if (query.checkOut) hbArgs.push('--check-out', query.checkOut);
-    if (query.adults) hbArgs.push('--room-occupancies', JSON.stringify([
-        {
-            adultCount: query.adults,
-            childrenAges: []
-        }
-    ]));
+    // 旗标对齐上游 CLI(hotelbyte-com/hotelbyte-cli):--destination-name + --room-occupancies;
+    // hotel-list 支持日期旗标(--check-in/--check-out,上游帮助文档在册)——issue #195 教训:
+    // 「日期不传上游」会让实时价退化为当前窗口价,用户要下周五的房给的是今天的价。
+    const hbArgs = ['search', 'hotel-list', '--json', '--page-size', '10'];
+    if (query.destination)
+        hbArgs.push('--destination-name', query.destination);
+    if (query.checkIn)
+        hbArgs.push('--check-in', query.checkIn);
+    if (query.checkOut)
+        hbArgs.push('--check-out', query.checkOut);
+    if (query.adults)
+        hbArgs.push('--room-occupancies', JSON.stringify([{ adultCount: query.adults, childrenAges: [] }]));
     const live = await callHbcliJson(hbArgs, opts);
     if (live.via === 'hbcli-realtime') {
+        // summary 即模型面(render 只透 summary):必须自带紧凑数据行 + 证据链,
+        // 否则模型只看到「实时返回」占位一句话(issue #195 实锤)。
         const list = live.result?.list;
         const n = Array.isArray(list) ? list.length : 0;
-        const dateTag = query.checkIn ? `入住 ${query.checkIn}${query.checkOut ? ` → 退房 ${query.checkOut}` : ''}` : '未传日期(上游按当前窗口价)';
+        const dateTag = query.checkIn
+            ? `入住 ${query.checkIn}${query.checkOut ? ` → 退房 ${query.checkOut}` : ''}`
+            : '未传日期(上游按当前窗口价)';
         const lines = hotelLines(live.result);
         const summary = `${query.destination}:hbcli 实时 ${n} 家(${dateTag})${lines ? `\n${lines}` : ''}\n${live.evidence}`;
-        return {
-            ...live,
-            hotels: live.result,
-            summary
-        };
+        return { ...live, hotels: live.result, summary };
     }
+    // 降级原因人话化(issue #24):hbcli 未安装时按 gotry setup 指引(npm 安装期已
+    // 自动跑过官方脚本;PATH 未含 ~/.local/bin 时上方候选路径也已兜住),
+    // 裸 "spawn hbcli ENOENT" 读起来像工具坏了——实际静态包降级是设计行为
     const rawReason = live.error ?? live.via;
-    const reason = /ENOENT/i.test(rawReason) ? '未安装 hbcli(可选实时源;npx gotry setup 可按官方脚本安装)' : rawReason;
+    const reason = /ENOENT/i.test(rawReason) ? '未安装 hbcli(可选实时源;npx @danceiny/gotry setup 可按官方脚本安装)' : rawReason;
+    // 降级:读静态包,按目的地过滤命中的住宿块(issue #24)——整包倾倒会把无关场景
+    // (深圳/普吉/曼谷/云南/大理混装)灌给模型且不指明哪块相关;包内无该目的地时明示
+    // 「无数据」而不是伪装成可用结果。
     const fallback = opts.fallbackPath;
     if (fallback) {
         try {
@@ -170,81 +183,64 @@ export async function searchHotels(query, opts = {}) {
             const pack = JSON.parse(await readFile(fallback, 'utf-8'));
             const kw = query.destination.trim();
             const stays = Array.isArray(pack.stays) ? pack.stays : [];
-            const matched = kw ? stays.filter((s)=>JSON.stringify(s).includes(kw)) : stays;
+            const matched = kw ? stays.filter(s => JSON.stringify(s).includes(kw)) : stays;
             if (matched.length) {
                 return {
                     ...live,
-                    hotels: {
-                        stays: matched
-                    },
-                    summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块:\n${JSON.stringify(matched).slice(0, 1600)}`
+                    hotels: { stays: matched },
+                    // summary 即模型面:静态块内容(note/options/recommendation)直接内联,
+                    // 模型不必再猜「命中 N 块」里有什么(issue #195)
+                    summary: `${query.destination}:hbcli 实时源不可用(${reason}),已降级到静态包(公开渠道估算,非实时),命中 ${matched.length} 个住宿块:\n${JSON.stringify(matched).slice(0, 1600)}`,
                 };
             }
             return {
                 ...live,
                 hotels: null,
-                summary: `${query.destination}:hbcli 实时源不可用(${reason}),且静态包无「${query.destination}」住宿数据(静态包仅覆盖内置场景)`
+                summary: `${query.destination}:hbcli 实时源不可用(${reason}),且静态包无「${query.destination}」住宿数据(静态包仅覆盖内置场景)`,
             };
-        } catch  {}
+        }
+        catch { /* 静态包读不到也优雅降级 */ }
     }
-    return {
-        ...live,
-        summary: `${query.destination}:hbcli 实时源不可用(${reason})且无静态包(仅返回错误)`
-    };
+    return { ...live, summary: `${query.destination}:hbcli 实时源不可用(${reason})且无静态包(仅返回错误)` };
 }
+/** 高层语义化封装:目的地列表(无数据依赖,通常 hbcli dest 命令可独立调通) */
 export async function listDestinations(opts = {}) {
-    const r = await callHbcliJson([
-        'search',
-        'destinations',
-        '--json'
-    ], opts);
-    return {
-        ...r,
-        destinations: r.result
-    };
+    const r = await callHbcliJson(['search', 'destinations', '--json'], opts);
+    return { ...r, destinations: r.result };
 }
+/**
+ * 高层语义化封装:房型报价(hotel-rates;上游 hotelRates 创建后端 session,
+ * 产出带 RatePkgId 的房型列表——check-avail 与 book 的入参来源)。
+ *
+ * 价格面无静态降级(fail-closed):hotel-list 的静态包降级是定性住宿信息,
+ * 房价是钱——估算价格冒充实时价是红线;不可用就诚实失败,证据链标注,
+ * 与 bookable-facts 证据分级(live_inventory 才可进确认卡)同口径。
+ */
 export async function hotelRates(query, opts = {}) {
-    const hbArgs = [
-        'search',
-        'hotel-rates',
-        '--json',
-        '--hotel-id',
-        query.hotelId
-    ];
-    if (query.checkIn) hbArgs.push('--check-in', query.checkIn);
-    if (query.checkOut) hbArgs.push('--check-out', query.checkOut);
-    if (query.countryCode) hbArgs.push('--country-code', query.countryCode);
-    if (query.nationalityCode) hbArgs.push('--nationality-code', query.nationalityCode);
-    if (query.residencyCode) hbArgs.push('--residency-code', query.residencyCode);
-    if (query.adults) hbArgs.push('--room-occupancies', JSON.stringify([
-        {
-            adultCount: query.adults,
-            childrenAges: []
-        }
-    ]));
+    const hbArgs = ['search', 'hotel-rates', '--json', '--hotel-id', query.hotelId];
+    if (query.checkIn)
+        hbArgs.push('--check-in', query.checkIn);
+    if (query.checkOut)
+        hbArgs.push('--check-out', query.checkOut);
+    if (query.countryCode)
+        hbArgs.push('--country-code', query.countryCode);
+    if (query.nationalityCode)
+        hbArgs.push('--nationality-code', query.nationalityCode);
+    if (query.residencyCode)
+        hbArgs.push('--residency-code', query.residencyCode);
+    if (query.adults)
+        hbArgs.push('--room-occupancies', JSON.stringify([{ adultCount: query.adults, childrenAges: [] }]));
     const live = await callHbcliJson(hbArgs, opts);
-    const summary = live.via === 'hbcli-realtime' ? `hotel ${query.hotelId}:hbcli 实时报价${query.checkIn ? `(${query.checkIn} → ${query.checkOut ?? '?'})` : ''}` : `hotel ${query.hotelId}:hbcli 实时报价不可用(${live.error ?? live.via});价格面无静态降级,fail-closed 不估算`;
-    return {
-        ...live,
-        rates: live.result,
-        summary
-    };
+    const summary = live.via === 'hbcli-realtime'
+        ? `hotel ${query.hotelId}:hbcli 实时报价${query.checkIn ? `(${query.checkIn} → ${query.checkOut ?? '?'})` : ''}`
+        : `hotel ${query.hotelId}:hbcli 实时报价不可用(${live.error ?? live.via});价格面无静态降级,fail-closed 不估算`;
+    return { ...live, rates: live.result, summary };
 }
+/** 高层语义化封装:下单前实时验价(check-avail;入参 RatePkgId 来自 hotel-rates 产物)。价格面同上:不可用即诚实失败。 */
 export async function checkAvail(query, opts = {}) {
-    const live = await callHbcliJson([
-        'search',
-        'check-avail',
-        '--json',
-        '--rate-pkg-id',
-        query.ratePkgId
-    ], opts);
-    const summary = live.via === 'hbcli-realtime' ? `ratePkg ${query.ratePkgId}:hbcli 实时验价(库存与价格以后端为准)` : `ratePkg ${query.ratePkgId}:hbcli 实时验价不可用(${live.error ?? live.via});价格面无静态降级,fail-closed`;
-    return {
-        ...live,
-        avail: live.result,
-        summary
-    };
+    const live = await callHbcliJson(['search', 'check-avail', '--json', '--rate-pkg-id', query.ratePkgId], opts);
+    const summary = live.via === 'hbcli-realtime'
+        ? `ratePkg ${query.ratePkgId}:hbcli 实时验价(库存与价格以后端为准)`
+        : `ratePkg ${query.ratePkgId}:hbcli 实时验价不可用(${live.error ?? live.via});价格面无静态降级,fail-closed`;
+    return { ...live, avail: live.result, summary };
 }
-
-
-//# sourceURL=ts/capabilities/hbcli.ts

package/dist/capabilities/hotelbyte-transaction.js

@@ -0,0 +1,194 @@
+/**
+ * HotelByte 交易 bridge 与 unknown 查单对账契约层(issue #232 契约/模块切片)。
+ *
+ * ⚠ 非运行时激活:本模块是纯函数契约层,不 spawn 子进程、不发起网络请求、
+ * 不读取任何凭据,与真实 HotelByte 二进制/UAT 零接触(见 issue #318 的
+ * GOTRY_HBCLI_LIVE 显式 opt-in 门——真实调用面在 M5 Entry 后才允许接线,
+ * 且必须挂在该门之后)。一切行为由 fixture/合成数据证明(hotelbyte-reconcile-tests)。
+ *
+ * 词汇与边界(上游文档为准):
+ *   - docs/design/write-gate-production-design.md §3(SupplierOutcome/WriteEffectIntent/
+ *     attempt_id/fencing)、§5.3(dispatch 未知态)、§6(准入矩阵)、§7(unknown 查单/恢复窗口);
+ *   - docs/design/fact-writegate-seam.md(读侧 fact 与写侧 SupplierOutcome 两闸分离)。
+ *
+ * 与 #231(WriteGate outbox)的接口边界:本模块只消费 outbox intent 的**引用 ID 字符串**
+ * (`outboxIntentRef` 占位)与审批凭证摘要,不实现、不触碰 outbox/dispatch 持久化——
+ * attempt 领取、fencing token、账本事务由 #231 落地;两者以该 ID 关联(#231 未合前为占位)。
+ *
+ * 对账红线(全部结构性编码,见 advanceReconciliation):
+ *   - unknown/无法确认的查单结果必须有显式对账分类——不静默当成功,也不静默丢弃;
+ *   - CLI exit0 非成功证明:timeout/kill/坏响应/无绑定成功/部分确认一律 unknown;
+ *   - 查单 miss 在恢复窗口内(后端 180s Phase1 + 最长 10min Phase2)保持 unknown,禁止重订;
+ *   - 时间届满本身不是无订单证明——只转人工,不自动 reconciled_failed;
+ *   - 只有绑定 attempt/customerReferenceNo 的权威终态负证据(供应商终态取消/失败、
+ *     绑定 attempt 的人工无订单确认)才允许新 intent;
+ *   - 同 ref 多单/参考号不匹配 = 冲突,显式 manual_reconcile;
+ *   - 终态后出现反证只置 conflict 交人工,不静默翻转;
+ *   - 每次推进追加审计事件(带 probeDigest),记录不可变(pure function)。
+ */
+import { createHash } from 'node:crypto';
+/** HotelByte 后端恢复窗口:Phase1 180s + Phase2 最长 10min(600s);上界 780s。 */
+export const RECOVERY_WINDOW_PHASE1_SECONDS = 180;
+export const RECOVERY_WINDOW_PHASE2_MAX_SECONDS = 600;
+export const RECOVERY_WINDOW_TOTAL_MAX_SECONDS = RECOVERY_WINDOW_PHASE1_SECONDS + RECOVERY_WINDOW_PHASE2_MAX_SECONDS;
+function requireBinding(key, value) {
+    const v = (value ?? '').trim();
+    if (!v)
+        throw new Error(`hotelbyte-reconcile: 对账记录缺绑定键 ${key}(fail-closed;无绑定键即无法追溯)`);
+    return v;
+}
+function probeDigest(input) {
+    return createHash('sha256').update(JSON.stringify(input ?? null)).digest('hex');
+}
+/** 恢复窗口上界:enterUnknownAt + 780s(180s Phase1 + 最长 10min Phase2)。 */
+export function recoveryWindowEndsAt(enteredUnknownAt) {
+    return new Date(Date.parse(enteredUnknownAt) + RECOVERY_WINDOW_TOTAL_MAX_SECONDS * 1000).toISOString();
+}
+/**
+ * 进入 unknown:booking 结果不可判定(超时/被杀/坏响应/部分确认)即建对账记录。
+ * 绑定键缺失直接抛错——没有绑定键的对账是不可追溯的黑洞,红线拒绝。
+ */
+export function enterUnknown(seed) {
+    const attemptId = requireBinding('attemptId', seed.attemptId);
+    const customerReferenceNo = requireBinding('customerReferenceNo', seed.customerReferenceNo);
+    const intentIdemKey = requireBinding('intentIdemKey', seed.intentIdemKey);
+    const requestFingerprintSha256 = requireBinding('requestFingerprintSha256', seed.requestFingerprintSha256);
+    const recoveryWindowEndsAtV = requireBinding('recoveryWindowEndsAt', seed.recoveryWindowEndsAt);
+    const enteredUnknownAt = requireBinding('enteredUnknownAt', seed.enteredUnknownAt);
+    if (Number.isNaN(Date.parse(enteredUnknownAt)) || Number.isNaN(Date.parse(recoveryWindowEndsAtV))) {
+        throw new Error('hotelbyte-reconcile: enteredUnknownAt/recoveryWindowEndsAt 必须是可解析时间');
+    }
+    return {
+        attemptId,
+        customerReferenceNo,
+        intentIdemKey,
+        requestFingerprintSha256,
+        enteredUnknownAt,
+        recoveryWindowEndsAt: recoveryWindowEndsAtV,
+        factId: seed.factId,
+        approvalReceiptDigest: seed.approvalReceiptDigest,
+        outboxIntentRef: seed.outboxIntentRef,
+        status: 'unknown',
+        nextAction: 'keep_querying',
+        conflict: false,
+        history: [{
+                at: enteredUnknownAt,
+                action: 'enter_unknown',
+                from: 'unknown',
+                to: 'unknown',
+                reason: 'booking 结果不可判定,进入显式对账(禁止盲目重试/重订)',
+                probeDigest: probeDigest(seed),
+            }],
+    };
+}
+function parseBookPayload(stdout) {
+    const start = stdout.search(/[{[]/);
+    if (start < 0)
+        return { json: null, parseError: 'no-json-marker' };
+    try {
+        const parsed = JSON.parse(stdout.slice(start));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { json: null, parseError: 'non-object-json' };
+        }
+        return { json: parsed };
+    }
+    catch (e) {
+        return { json: null, parseError: `unparseable:${e.message.slice(0, 80)}` };
+    }
+}
+/**
+ * book 执行分类(验收 §3:CLI exit0 非成功证明;timeout/kill/坏响应/结果不确定归 unknown):
+ *   - timedOut / signal / 非零退码且无显式业务结论 → unknown;
+ *   - exit0 + 非 JSON → unknown;exit0 + 显式业务失败 → supplier_failed;
+ *   - exit0 + success 但缺/错 customerReferenceNo 绑定 → unknown(不可归因即不可当成功);
+ *   - exit0 + pending/部分确认 → unknown;
+ *   - exit0 + success + 参考号匹配本 attempt → binding_verified。
+ */
+export function classifyBookExecution(r, expectedReferenceNo) {
+    if (r.timedOut)
+        return { kind: 'unknown', reason: 'timeout(30s abort;后端可能仍在处理,进入 unknown 对账)' };
+    if (r.signal)
+        return { kind: 'unknown', reason: `process_killed:${r.signal}(副作用不可判定)` };
+    const { json, parseError } = parseBookPayload(r.stdout);
+    if (r.exitCode !== 0) {
+        if (json?.status === 'failed')
+            return { kind: 'supplier_failed', reason: 'nonzero-exit + explicit failed payload', payload: json };
+        return { kind: 'unknown', reason: `nonzero_exit:${r.exitCode ?? 'null'}(无显式业务结论,不假定无副作用${parseError ? `;${parseError}` : ''})` };
+    }
+    if (!json)
+        return { kind: 'unknown', reason: `exit0_non_json(坏响应,不可当成功;${parseError ?? 'empty'})` };
+    if (json.status === 'failed')
+        return { kind: 'supplier_failed', reason: 'explicit failed payload', payload: json };
+    if (json.status === 'success') {
+        const ref = typeof json.customerReferenceNo === 'string' ? json.customerReferenceNo.trim() : '';
+        if (!ref)
+            return { kind: 'unknown', reason: 'exit0_success_missing_reference(无绑定成功不可归因)' };
+        if (ref !== expectedReferenceNo)
+            return { kind: 'unknown', reason: `exit0_success_reference_mismatch(返回 ${ref},本 attempt ${expectedReferenceNo})` };
+        return { kind: 'binding_verified', customerReferenceNo: ref, payload: json };
+    }
+    // pending / 其它一切不确定状态:部分确认 ≠ 成功
+    return { kind: 'unknown', reason: `partial_or_indeterminate(status=${String(json.status ?? 'absent')})` };
+}
+/** 供应商终态取消/失败词汇(权威负证据来源;迟到自动取消按回执收敛)。 */
+const SUPPLIER_TERMINAL_NEGATIVE = new Set(['cancelled', 'canceled', 'auto_canceled', 'failed', 'expired']);
+/**
+ * 对账状态机推进(纯函数;原状态不可变,返回带追加审计事件的新状态)。
+ * 转移表对齐 write-gate-production-design §7 矩阵,红线见模块头注释。
+ */
+export function advanceReconciliation(state, probe, now) {
+    const digest = probeDigest(probe);
+    const append = (next, action, reason) => ({
+        ...next,
+        history: [...state.history, { at: now, action, from: state.status, to: next.status, reason, probeDigest: digest }],
+    });
+    // 终态吸收 + 反证只置 conflict(不静默翻转)
+    if (state.status !== 'unknown') {
+        if (probe.kind === 'hit' && probe.orders.length > 0) {
+            return append({ ...state, conflict: true, nextAction: 'manual_reconcile' }, 'conflict_late_hit_after_terminal', `终态(${state.status})后出现订单证据 → 显式冲突交人工复核,不静默翻转`);
+        }
+        return { ...state };
+    }
+    if (probe.kind === 'manual_no_order') {
+        const evidence = (probe.operatorEvidence ?? '').trim();
+        if (!evidence)
+            throw new Error('hotelbyte-reconcile: 人工无订单确认必须携带非空操作证据(绑定 attempt 可追溯)');
+        return append({ ...state, status: 'reconciled_failed', nextAction: 'terminal', conflict: false }, 'manual_no_order_confirmed', `人工权威负证据:${evidence.slice(0, 200)}`);
+    }
+    const withinWindow = Date.parse(now) <= Date.parse(state.recoveryWindowEndsAt);
+    switch (probe.kind) {
+        case 'miss': {
+            if (withinWindow) {
+                return append({ ...state, status: 'unknown', nextAction: 'keep_querying', conflict: false }, 'query_miss_within_window', '恢复窗口内查无 → 保持 unknown;供应商可能迟到建单,禁止重订');
+            }
+            return append({ ...state, status: 'unknown', nextAction: 'manual_reconcile', conflict: false }, 'query_miss_after_window', '窗口届满查无 → 仍 unknown(时间届满本身不是无订单证明),转人工');
+        }
+        case 'hit': {
+            if (probe.orders.length > 1) {
+                return append({ ...state, status: 'unknown', nextAction: 'manual_reconcile', conflict: true }, 'conflict_multiple_orders', `同参考号返回 ${probe.orders.length} 笔订单 → 冲突,人工对账(不静默择一)`);
+            }
+            const order = probe.orders[0];
+            if (order.customerReferenceNo !== state.customerReferenceNo) {
+                return append({ ...state, status: 'unknown', nextAction: 'manual_reconcile', conflict: true }, 'conflict_reference_mismatch', `返回订单参考号 ${order.customerReferenceNo} ≠ 本 attempt ${state.customerReferenceNo} → 冲突,人工对账`);
+            }
+            const status = order.supplierStatus.toLowerCase();
+            if (SUPPLIER_TERMINAL_NEGATIVE.has(status)) {
+                return append({ ...state, status: 'reconciled_failed', nextAction: 'terminal', conflict: false }, 'supplier_terminal_negative', `绑定 attempt 的供应商终态(${order.supplierStatus},orderRef=${order.orderRef})→ 权威负证据,收敛 reconciled_failed`);
+            }
+            if (status === 'confirmed' || status === 'success' || status === 'completed') {
+                return append({ ...state, status: 'reconciled_success', nextAction: 'terminal', conflict: false }, 'supplier_terminal_success', `绑定 attempt 的供应商终态成功(orderRef=${order.orderRef})→ reconciled_success(含迟到成功,不重订)`);
+            }
+            return append({ ...state, status: 'unknown', nextAction: 'keep_querying', conflict: false }, 'hit_not_terminal', `订单存在但非终态(${order.supplierStatus})→ 保持 unknown 继续查`);
+        }
+        case 'query_failed':
+            return append({ ...state, status: 'unknown', nextAction: 'keep_querying', conflict: false }, 'query_failed', `查询自身失败(${probe.reason.slice(0, 120)})→ 探针失败不证明订单不存在,保持 unknown`);
+        case 'malformed':
+            return append({ ...state, status: 'unknown', nextAction: 'keep_querying', conflict: false }, 'query_malformed', `畸形响应(${probe.reason.slice(0, 120)})→ 不静默当 miss,保持 unknown`);
+        case 'permission_denied':
+            return append({ ...state, status: 'unknown', nextAction: 'manual_reconcile', conflict: false }, 'query_permission_denied', '查询权限拒绝 → 自助查单不可用,转人工对账');
+    }
+}
+/** 是否允许对同一请求发起新 intent:仅当收敛自绑定 attempt 的权威终态负证据且无未决冲突。 */
+export function newIntentAllowed(state) {
+    return state.status === 'reconciled_failed' && !state.conflict;
+}