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

package/dist/scripts/flyai-tool-registration-contract-tests.js

@@ -0,0 +1,91 @@
+/** Offline registration contract for the eight public FlyAI search kinds. */
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { apply } from '../src/index.js';
+const stateRoot = await mkdtemp(join(tmpdir(), 'gotry-flyai-registration-'));
+const calls = [];
+const tools = [];
+const context = {
+    tools: { register: (tool) => tools.push(tool) },
+    systemPrompt: { variable: () => { } },
+    on: () => () => { },
+    get: () => undefined,
+};
+const config = { stateRoot, timeoutMs: 5_000, hbcliBin: 'unavailable', sessionAccess: 'off' };
+const effect = async (input) => {
+    calls.push(input);
+    return {
+        result: {
+            ok: false,
+            via: 'flyai',
+            kind: input.params.kind,
+            verdict: 'miss',
+            evidence: '[contract-test:flyai]',
+        },
+        trace: {},
+    };
+};
+apply(context, config, { effect: effect });
+const search = tools.find(tool => tool.name === 'gotry_flyai_search');
+assert.ok(search, 'apply must register gotry_flyai_search');
+assert.ok(tools.some(tool => tool.name === 'gotry_flyai_setup'), 'apply must register gotry_flyai_setup');
+const publicSchema = JSON.stringify(search.parameters);
+for (const forbidden of ['cliBin', 'cliPrefixArgs', 'credential', 'apiKey', 'endpoint', 'signal']) {
+    assert.equal(publicSchema.includes(forbidden), false, `search schema must not expose ${forbidden}`);
+}
+assert.deepEqual(search.parameters.properties.kind.enum, [
+    'flight', 'train', 'hotel', 'poi', 'keyword', 'ai', 'marriott-hotel', 'marriott-package',
+]);
+const signal = new AbortController().signal;
+const queries = [
+    { kind: 'flight', from: '上海' },
+    { kind: 'train', origin: '上海', destination: '大理', depDateStart: '2099-10-01', depDateEnd: '2099-10-03' },
+    { kind: 'hotel', to: '大理' },
+    { kind: 'poi', cityName: '大理', category: '自然风光' },
+    { kind: 'keyword', query: '大理古城' },
+    { kind: 'ai', query: '大理周末' },
+    { kind: 'marriott-hotel', destName: '大理' },
+    { kind: 'marriott-package', keyword: '早餐' },
+];
+for (const query of queries) {
+    const result = await search.execute(query, { signal });
+    assert.equal(result.verdict, 'miss', `registered ${String(query.kind)} should execute`);
+    const call = calls.at(-1);
+    assert.ok(call, `${String(query.kind)} should reach the effect seam`);
+    assert.equal(call?.effect, 'FLYAI_SEARCH');
+    assert.equal(call?.params.kind, query.kind);
+    assert.equal(call?.params.signal, signal, `${String(query.kind)} must receive params.signal`);
+    assert.equal(call?.signal, signal, `${String(query.kind)} must preserve outer cancellation`);
+    assert.equal('cliBin' in (call?.params ?? {}), false);
+    assert.equal('credential' in (call?.params ?? {}), false);
+    assert.equal('endpoint' in (call?.params ?? {}), false);
+}
+const callsBeforeUnknown = calls.length;
+const unknown = await search.execute({ kind: 'spaceship', from: '上海', to: '月球', date: '2099-10-01' }, { signal });
+assert.equal(calls.length, callsBeforeUnknown, 'unknown kind must be rejected before the effect');
+assert.equal(unknown.ok, false);
+for (const invalid of [
+    { kind: 'flight', to: '丽江' },
+    { kind: 'flight', from: '上海', date: '2099-02-29' },
+    { kind: 'train', from: '上海', dateStart: '2099-10-03', dateEnd: '2099-10-01' },
+    { kind: 'flight', from: '上海', sortType: '9' },
+    { kind: 'marriott-hotel', destName: '大理', hotelStars: '5' },
+    { kind: 'poi', cityName: '' },
+    { kind: 'keyword' },
+    { kind: 'marriott-package' },
+]) {
+    const before = calls.length;
+    const rejected = await search.execute(invalid, { signal });
+    assert.equal(calls.length, before, `${String(invalid.kind)} missing required input must not reach the effect`);
+    assert.equal(rejected.ok, false);
+}
+const marriott = await search.execute({ kind: 'marriott-hotel', destName: '大理', hotelBrands: '万豪', hotelName: '大理酒店' }, { signal });
+assert.equal(marriott.verdict, 'miss');
+const marriottCall = calls.at(-1);
+assert.equal(marriottCall?.params.keyWords, '万豪 大理酒店', 'Marriott name/brand must map to official --key-words');
+assert.equal('hotelBrands' in (marriottCall?.params ?? {}), false);
+assert.equal('hotelName' in (marriottCall?.params ?? {}), false);
+await rm(stateRoot, { recursive: true, force: true });
+console.log('flyai registration contract OK');

package/dist/scripts/fx-contract-tests.js

@@ -0,0 +1,201 @@
+/**
+ * Money/FX fact 合同 v1 测试（issue #344 契约切片；全离线、零网络、零活体汇率源）：
+ *
+ *  A. 币种封闭集 + 原币金额解析（未知币种/小写/精度超位/千分位/指数记法 fail-closed；负值与零结构可载）
+ *  B. FxFact 构建（全字段必填/fact_id 幂等/rate 归一；缺源·来源不明·缺时刻·日期无时刻·as_of 晚于抓取·
+ *     零/负/伪精度汇率·同币种自兑·provenance 空 各负例；默认注册表为空 → 生产路径任何 provider 均拒）
+ *  C. 单腿换算（精确 bigint·half-away-from-zero 落位·JPY 0 位指数·原币展示保留；
+ *     供应商币种变化/方向拿反 显式拒绝）
+ *  D. 同一估值时点比较（同 as_of 不同拼写可比/预算判定/聚合；混时点·午夜切换·旧 rate 钉时点·
+ *     混币种·空聚合 各负例且错误带证据）
+ *  E. 交叉汇率（两腿同 as_of 显式合成；混时点两腿拒绝）
+ *  F. 契约 seam（注册表冻结为空/触发闸冻结 false；触发前 consultFxSources 结构化拒绝且
+ *     fetch spy 零调用=零浮动汇率源被咨询；触发后 primary→fallback 顺位与 miss/error/stale 不伪装）
+ *
+ * 运行（在 ts/ 下）：npx tsx scripts/fx-contract-tests.ts
+ */
+import { FX_FACT_SCHEMA, FX_TRIGGER_FIRED, LIVE_FX_PROVIDER_DESCRIPTORS, FxContractError, buildFxFact, compareMoney, consultFxSources, convertMoney, convertMoneyViaPivot, formatMoney, parseCurrency, parseMoney, pinNativeMoney, sumMoney, withinBudget, } from '../capabilities/fx-contract.js';
+let passed = 0;
+function check(cond, msg) {
+    if (cond) {
+        passed++;
+        console.log(`  ok - ${msg}`);
+    }
+    else {
+        console.error(`  FAIL - ${msg}`);
+        process.exitCode = 1;
+    }
+}
+/** 负向断言：必须抛 FxContractError，且消息携带证据片段「needle」。 */
+function expectReject(fn, needle, msg) {
+    try {
+        fn();
+        check(false, `${msg}（应拒绝但未拒绝）`);
+    }
+    catch (e) {
+        const text = e instanceof Error ? e.message : String(e);
+        check(e instanceof FxContractError && text.includes(needle), `${msg}（拒绝且证据含「${needle}」）`);
+    }
+}
+/** 测试专用离线 registry（仅存在于测试文件；生产注册表冻结为空）。 */
+const TEST_REGISTRY = [
+    { id: 'fixture-offline-table', tier: 'primary', legal_basis: 'test-only offline fixture table (no live source, issue #344 contract slice)' },
+    { id: 'fixture-offline-fallback', tier: 'fallback', legal_basis: 'test-only offline fixture table (no live source, issue #344 contract slice)' },
+];
+const T1 = '2026-10-02T00:00:00.000Z';
+const T1_ALT_SPELLING = '2026-10-02T08:00:00+08:00'; // 与 T1 同一时刻的另一种拼写（+08:00 偏移）
+const T2 = '2026-10-02T12:00:00.000Z';
+const T_MIDNIGHT_BEFORE = '2026-10-01T23:59:59.000Z';
+const T_MIDNIGHT_AFTER = '2026-10-02T00:00:01.000Z';
+function fixtureFact(base, quote, rate, provider, asOf) {
+    return buildFxFact({ base, quote, rate, provider, provenance: `[汇率:fixture@契约测试:${provider}]`, as_of: asOf, fetched_at: '2026-10-02T12:00:01.000Z' }, TEST_REGISTRY);
+}
+// ---------------------------------------------------------------- A. 币种与金额
+console.log('A. 币种封闭集与原币金额解析');
+check(parseCurrency('CNY') === 'CNY', '已知币种准入（CNY）');
+expectReject(() => parseCurrency('usd'), 'uppercase 3-letter', '未知形态币种（小写 usd）拒绝');
+expectReject(() => parseCurrency('XXY'), 'unknown currency code XXY', '未知币种（XXY 不在封闭集）拒绝');
+expectReject(() => parseCurrency('US'), 'uppercase 3-letter', '两位币种码拒绝');
+expectReject(() => parseCurrency(42), 'uppercase 3-letter', '非字符串币种拒绝');
+check(parseMoney('CNY', '1234.56').amountMinor === 123456n, '金额解析：1234.56 CNY = 123456 最小单位');
+check(formatMoney(parseMoney('CNY', '1234.56')) === '1234.56 CNY', '原币展示保留（1234.56 CNY）');
+check(parseMoney('JPY', '1000').amountMinor === 1000n, 'JPY（0 位最小单位）整数金额解析');
+check(parseMoney('CNY', '-50.00').amountMinor === -5000n, '负值金额结构可载（退款/抹零是真实数据）');
+check(parseMoney('CNY', '0.00').amountMinor === 0n, '零金额结构可载');
+check(formatMoney(parseMoney('CNY', '-50.00')) === '-50.00 CNY', '负值原币展示');
+expectReject(() => parseMoney('JPY', '1000.5'), 'exceeds its 0-digit minor unit', 'JPY 带小数（亚最小单位精度）拒绝');
+expectReject(() => parseMoney('CNY', '1,234.56'), 'no separators', '千分位分隔符拒绝');
+expectReject(() => parseMoney('CNY', '1.234'), 'exceeds its 2-digit minor unit', 'CNY 三位小数拒绝');
+expectReject(() => parseMoney('CNY', '1e3'), 'plain decimal', '指数记法金额拒绝');
+expectReject(() => parseMoney('CNY', ' 12.34'), 'plain decimal', '带空白金额拒绝');
+// ---------------------------------------------------------------- B. FxFact 构建
+console.log('B. FxFact 构建（全字段必填 + fail-closed 负例）');
+const usdCnyAtT1 = fixtureFact('USD', 'CNY', '7.20', 'fixture-offline-table', T1);
+check(usdCnyAtT1.schema === FX_FACT_SCHEMA && FX_FACT_SCHEMA === 'gotry_fx_fact.v1', 'schema 版本化标识 gotry_fx_fact.v1');
+check(usdCnyAtT1.rate === '7.2', 'rate 归一化（去尾零：7.20 → 7.2）');
+check(usdCnyAtT1.as_of === T1 && usdCnyAtT1.fetched_at === '2026-10-02T12:00:01.000Z', 'as_of/fetched_at 规范化保留');
+check(usdCnyAtT1.rounding === 'minor-unit-half-away-from-zero', '舍入规则冻结在事实内（可审计）');
+const usdCnyAtT1Again = fixtureFact('USD', 'CNY', '7.2', 'fixture-offline-table', T1);
+check(usdCnyAtT1.fact_id === usdCnyAtT1Again.fact_id, 'fact_id 幂等（rate 拼写差异不影响）');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'mystery-rate-api', provenance: 'p', as_of: T1, fetched_at: T2 }, TEST_REGISTRY), 'not admitted in the registry: "mystery-rate-api"', '来源不明（未注册 provider）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: '', provenance: 'p', as_of: T1, fetched_at: T2 }, TEST_REGISTRY), 'non-empty source identifier', '缺源（provider 空串）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: undefined, provenance: 'p', as_of: T1, fetched_at: T2 }, TEST_REGISTRY), 'non-empty source identifier', '缺源（provider 缺失）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: 'p', as_of: T1, fetched_at: T2 }), 'not admitted in the registry', '默认注册表（生产路径，冻结为空）任何 provider 均拒——零活体源');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'no-basis-source', provenance: 'p', as_of: T1, fetched_at: T2 }, [{ id: 'no-basis-source', tier: 'primary', legal_basis: '' }]), 'carries no legal_basis', 'registry 条目缺 legal_basis（缺陷注册表）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: 'p', as_of: '', fetched_at: T2 }, TEST_REGISTRY), 'non-empty ISO-8601 UTC instant', '缺估值时刻（as_of 空串）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: 'p', as_of: undefined, fetched_at: T2 }, TEST_REGISTRY), 'non-empty ISO-8601 UTC instant', '缺估值时刻（as_of 缺失）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: 'p', as_of: '2026-10-02', fetched_at: T2 }, TEST_REGISTRY), 'date-only', '日期无时刻（date-only as_of）拒绝——非估值时点');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: 'p', as_of: 'not-a-time', fetched_at: T2 }, TEST_REGISTRY), 'not a parseable ISO-8601 instant', '垃圾估值时刻拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: 'p', as_of: T1, fetched_at: '' }, TEST_REGISTRY), 'non-empty ISO-8601 UTC instant', '缺抓取时刻（fetched_at 空串）拒绝');
+expectReject(() => fixtureFact('USD', 'CNY', '7.2', 'fixture-offline-table', '2026-10-02T12:00:02.000Z'), 'impossible provenance', 'as_of 晚于 fetched_at（不可能的 provenance）拒绝');
+expectReject(() => buildFxFact({ base: 'USD', quote: 'CNY', rate: '7.2', provider: 'fixture-offline-table', provenance: '', as_of: T1, fetched_at: T2 }, TEST_REGISTRY), 'non-empty evidence-chain description', 'provenance 空串拒绝');
+expectReject(() => fixtureFact('USD', 'USD', '1', 'fixture-offline-table', T1), 'base and quote must differ', '同币种自兑（恒等汇率绕过证据）拒绝');
+expectReject(() => fixtureFact('USD', 'CNY', '0', 'fixture-offline-table', T1), 'strictly positive', '零汇率拒绝');
+expectReject(() => fixtureFact('USD', 'CNY', '-7.2', 'fixture-offline-table', T1), 'plain positive decimal', '负汇率拒绝（记法即拒）');
+expectReject(() => fixtureFact('USD', 'CNY', '1e5', 'fixture-offline-table', T1), 'plain positive decimal', '指数记法汇率拒绝');
+expectReject(() => fixtureFact('USD', 'CNY', '7.1234567890123', 'fixture-offline-table', T1), 'exceeds 12 fractional digits', '伪精度汇率（13 位小数）拒绝');
+expectReject(() => fixtureFact('USD', 'CNY', 7.2, 'fixture-offline-table', T1), 'plain positive decimal', '非字符串汇率（浮点）拒绝');
+expectReject(() => fixtureFact('XXY', 'CNY', '7.2', 'fixture-offline-table', T1), 'unknown currency code XXY', '事实构建侧未知币种拒绝');
+// ---------------------------------------------------------------- C. 换算
+console.log('C. 单腿换算（精确 bigint + 冻结舍入 + 原币保留）');
+const usd100 = parseMoney('USD', '100.00');
+const cny720 = convertMoney(usd100, 'CNY', usdCnyAtT1);
+check(cny720.amountMinor === 72000n, 'USD 100.00 × 7.2 = CNY 720.00（72000 最小单位）');
+check(cny720.valuationAsOf === T1, '换算值绑定估值时点 = fact.as_of');
+check(formatMoney(cny720.original) === '100.00 USD', '原币金额与供应商金额原样保留');
+check(cny720.original === usd100, 'original 即传入原币对象（零改写）');
+check(cny720.fx.fact_id === usdCnyAtT1.fact_id && cny720.fx.provider === 'fixture-offline-table' && cny720.fx.rate === '7.2', '汇率证据引用完整（fact_id/provider/rate）');
+const halfUp = convertMoney(parseMoney('USD', '0.01'), 'CNY', fixtureFact('USD', 'CNY', '7.5', 'fixture-offline-table', T1));
+check(halfUp.amountMinor === 8n, 'half-away-from-zero 上取整：USD 0.01 × 7.5 = ¥0.075 → 0.08');
+const halfDownNegative = convertMoney(parseMoney('USD', '-0.01'), 'CNY', fixtureFact('USD', 'CNY', '7.5', 'fixture-offline-table', T1));
+check(halfDownNegative.amountMinor === -8n, '负值对称远离零：-¥0.075 → -0.08');
+const jpyTarget = convertMoney(usd100, 'JPY', fixtureFact('USD', 'JPY', '150.5', 'fixture-offline-table', T1));
+check(jpyTarget.amountMinor === 15050n && jpyTarget.currency === 'JPY', 'JPY 目标币（0 位最小单位）：USD 100 × 150.5 = 15050 円');
+const zeroMoney = convertMoney(parseMoney('USD', '0.00'), 'CNY', usdCnyAtT1);
+check(zeroMoney.amountMinor === 0n, '零金额换算确定性（0 × rate = 0）');
+expectReject(() => convertMoney(parseMoney('EUR', '100.00'), 'CNY', usdCnyAtT1), 'does not cover the requested conversion EUR→CNY', '供应商币种变化（fact 币种对不覆盖）显式拒绝');
+expectReject(() => convertMoney(usd100, 'CNY', fixtureFact('CNY', 'USD', '0.1389', 'fixture-offline-table', T1)), 'does not cover the requested conversion USD→CNY', '方向拿反（CNY→USD 腿不能反向用）拒绝');
+// ---------------------------------------------------------------- D. 同一估值时点比较
+console.log('D. 同一估值时点比较（混时点/午夜切换/旧 rate fail-closed）');
+const usdCnyAtT1AltSpelling = fixtureFact('USD', 'CNY', '7.2', 'fixture-offline-table', T1_ALT_SPELLING);
+check(usdCnyAtT1AltSpelling.as_of === T1, '时刻规范化：+08:00 偏移拼写归一到同一 UTC 毫秒时点');
+const cny720Alt = convertMoney(usd100, 'CNY', usdCnyAtT1AltSpelling);
+check(compareMoney(cny720, cny720Alt) === 0, '同一估值时点（不同拼写归一后）可比');
+const budget1000 = pinNativeMoney(parseMoney('CNY', '1000.00'), T1);
+check(compareMoney(cny720, budget1000) === -1 && withinBudget(cny720, budget1000) === true, '预算判定：¥720 ≤ ¥1000（FX 规范化值 vs 原生钉时点，同 as_of）');
+const cny600 = pinNativeMoney(parseMoney('CNY', '600.00'), T1);
+check(withinBudget(budget1000, cny600) === false, '预算判定方向语义：¥1000 ≤ ¥600 为假');
+const summed = sumMoney([cny720, pinNativeMoney(parseMoney('CNY', '280.00'), T1)]);
+check(summed.amountMinor === 100000n && summed.valuationAsOf === T1, '聚合求和（同币种同 as_of：720+280=1000）');
+const usdCnyAtT2 = fixtureFact('USD', 'CNY', '7.2', 'fixture-offline-fallback', T2);
+const cny720AtT2 = convertMoney(usd100, 'CNY', usdCnyAtT2);
+expectReject(() => compareMoney(cny720, cny720AtT2), '同一估值时点', '混时点比较显式拒绝（错误提示含规则名）');
+expectReject(() => compareMoney(cny720, cny720AtT2), usdCnyAtT1.fact_id, '混时点错误携带 side A 证据（fact_id）');
+expectReject(() => compareMoney(cny720, cny720AtT2), usdCnyAtT2.fact_id, '混时点错误携带 side B 证据（fact_id）');
+expectReject(() => compareMoney(cny720, cny720AtT2), 'as_of 2026-10-02T00:00:00.000Z', '混时点错误携带两侧估值时点');
+expectReject(() => withinBudget(cny720, cny720AtT2), '同一估值时点', '混时点预算判定拒绝');
+expectReject(() => sumMoney([cny720, cny720AtT2]), 'money aggregation', '混时点聚合拒绝');
+const midnightFact = fixtureFact('USD', 'CNY', '7.2', 'fixture-offline-table', T_MIDNIGHT_BEFORE);
+const midnightOther = fixtureFact('USD', 'CNY', '7.2', 'fixture-offline-fallback', T_MIDNIGHT_AFTER);
+expectReject(() => compareMoney(convertMoney(usd100, 'CNY', midnightFact), convertMoney(usd100, 'CNY', midnightOther)), 'as_of 2026-10-01T23:59:59.000Z', '午夜切换：跨日 2 秒的相邻时点仍判混时点');
+expectReject(() => convertMoney(usd100, 'CNY', usdCnyAtT1, T2), 'does not match the pinned valuation instant', '旧 rate（钉住 T2 但只有 T1 事实）拒绝——stale 不伪装为当前准确换算');
+expectReject(() => convertMoney(usd100, 'CNY', usdCnyAtT1, '2026-10-02'), 'date-only', '钉住时点为日期无时刻也拒绝');
+check(convertMoney(usd100, 'CNY', usdCnyAtT1, T1_ALT_SPELLING).amountMinor === 72000n, '钉住时点拼写不同但同时刻可换算');
+const jpyCnyAtT1 = convertMoney(parseMoney('JPY', '20000'), 'CNY', fixtureFact('JPY', 'CNY', '0.048', 'fixture-offline-table', T1));
+check(compareMoney(cny720, jpyCnyAtT1) === -1, '两条外币报价（USD/JPY）经各自 FX 事实规范化到 CNY 后同 as_of 可比（720 < 960）');
+check(pinNativeMoney(parseMoney('CNY', '960.00'), T1).amountMinor === 96000n, '原生恒等钉时点保留金额（960.00 CNY）');
+expectReject(() => pinNativeMoney(parseMoney('CNY', '1.00'), 'not-a-time'), 'not a parseable ISO-8601 instant', '原生钉时点同样要求合法时刻');
+expectReject(() => sumMoney([]), 'at least one normalized amount', '空聚合拒绝（空聚合不是事实）');
+// ---------------------------------------------------------------- E. 交叉汇率
+console.log('E. 交叉汇率（两腿显式合成，同 as_of）');
+const cnyThbAtT1 = fixtureFact('CNY', 'THB', '4.85', 'fixture-offline-table', T1);
+const usdThb = convertMoneyViaPivot(usd100, 'CNY', 'THB', usdCnyAtT1, cnyThbAtT1);
+check(usdThb.currency === 'THB' && usdThb.amountMinor === 349200n, 'USD 100 → CNY 720 → THB 3492.00（两腿同 as_of）');
+expectReject(() => compareMoney(cny720, usdThb), 'same normalized currency', '未归一到同币种的比较拒绝（CNY vs THB，提示先规范化）');
+check(usdThb.valuationAsOf === T1, '交叉汇率合成值绑定同一估值时点');
+const cnyThbAtT2 = fixtureFact('CNY', 'THB', '4.85', 'fixture-offline-fallback', T2);
+expectReject(() => convertMoneyViaPivot(usd100, 'CNY', 'THB', usdCnyAtT1, cnyThbAtT2), 'must share the same valuation instant', '交叉汇率混时点两腿拒绝（错误含两腿 fact_id）');
+expectReject(() => convertMoneyViaPivot(usd100, 'CNY', 'THB', usdCnyAtT1, cnyThbAtT2), cnyThbAtT2.fact_id, '交叉汇率混时点错误携带第二腿证据');
+// ---------------------------------------------------------------- F. 契约 seam（零活体源咨询）
+console.log('F. 契约 seam：触发前零浮动汇率源被咨询（D-26 边界不变）');
+check(LIVE_FX_PROVIDER_DESCRIPTORS.length === 0, '运行时源注册表冻结为空');
+check(FX_TRIGGER_FIRED === false, '触发闸冻结为 false（#344 触发后置）');
+const deferred = await consultFxSources({ base: parseCurrency('USD'), quote: parseCurrency('CNY') });
+check(deferred.ok === false && deferred.code === 'trigger-deferred', '触发未开：consultFxSources 结构化拒绝（trigger-deferred）');
+check(deferred.ok === false && deferred.detail.includes('zero floating-rate sources consulted'), '拒绝理由明示「零浮动汇率源被咨询」与 D-26 边界');
+let spyCalls = 0;
+const spySource = {
+    descriptor: TEST_REGISTRY[0],
+    fetchRate: async () => {
+        spyCalls++;
+        return { ok: true, fact: usdCnyAtT1 };
+    },
+};
+const refused = await consultFxSources({ base: parseCurrency('USD'), quote: parseCurrency('CNY') }, { sources: [spySource], triggerFired: false });
+check(refused.ok === false && refused.code === 'trigger-deferred', '即使传入源列表，触发未开仍在读源之前拒绝');
+check(spyCalls === 0, 'fetch spy 零调用 = 零浮动汇率源被咨询（W2A 式 inert 合同）');
+const noSource = await consultFxSources({ base: parseCurrency('USD'), quote: parseCurrency('CNY') }, { sources: [], triggerFired: true });
+check(noSource.ok === false && noSource.code === 'no-source-admitted', '触发已开但注册表为空：no-source-admitted（不猜源）');
+const viaSpy = await consultFxSources({ base: parseCurrency('USD'), quote: parseCurrency('CNY') }, { sources: [spySource], triggerFired: true });
+check(viaSpy.ok === true && spyCalls === 1 && viaSpy.fact.fact_id === usdCnyAtT1.fact_id, 'seam 数据形状可用：触发后单源返回完整证据事实');
+let primaryCalls = 0;
+let fallbackCalls = 0;
+const missPrimary = {
+    descriptor: { id: 'miss-primary', tier: 'primary', legal_basis: 'test-only' },
+    fetchRate: async () => {
+        primaryCalls++;
+        return { ok: false, code: 'miss', detail: 'no quote for pair at instant' };
+    },
+};
+const fallbackSource = {
+    descriptor: { id: 'fallback-hit', tier: 'fallback', legal_basis: 'test-only' },
+    fetchRate: async () => {
+        fallbackCalls++;
+        return { ok: true, fact: usdCnyAtT1 };
+    },
+};
+const degraded = await consultFxSources({ base: parseCurrency('USD'), quote: parseCurrency('CNY') }, { sources: [missPrimary, fallbackSource], triggerFired: true });
+check(degraded.ok === true && primaryCalls === 1 && fallbackCalls === 1, '降级顺位形状：primary miss → fallback 命中（各一次）');
+const allMiss = await consultFxSources({ base: parseCurrency('USD'), quote: parseCurrency('CNY') }, { sources: [missPrimary], triggerFired: true });
+check(allMiss.ok === false && allMiss.code === 'miss', 'miss 不伪装为当前准确换算（结构化 miss 直传）');
+console.log(`\nFX CONTRACT TESTS: ${passed} pass${process.exitCode ? ', FAIL' : ' (全绿)'}`);

package/dist/scripts/g5-guard-tests.js

@@ -0,0 +1,131 @@
+/**
+ * G5 机械闸自测(issue #348;全离线,零网络,零共享 state 写入)。
+ *
+ * 覆盖:
+ *  1. (17) pattern 命中/不命中双向——真桥接形状(G5_BRIDGE/g5Bridge/
+ *     capability-travel-mcp/t-system bridge/G5桥)必须命中;承运人代码
+ *     G5/G52667、persona-bench 案例 G5、base64 噪声、「提到 G5 门」的
+ *     门定义句必须不命中(误报会把 tracker 自身打红);
+ *  2. (7) 台账解析——GRANT 缺 issue/决策链接 → 拒收(fail closed);
+ *     code fence 内模板行不计入;glob 语义(** 跨段 / * 单段);覆盖判定;
+ *  3. (2) 命名面豁免存在(master-outline 对 + 台账/guard 对);
+ *  4. (4) CLI 端到端(临时 git fixture,--root 注入):未授权引用 → exit 1
+ *     且输出可操作指引;GRANT 覆盖后 → exit 0;干净仓 → exit 0;
+ *     台账缺失 → exit 2(闸自身不可用,而非放行)。
+ *
+ * 运行:cd ts && npx tsx scripts/g5-guard-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { globToRegExp, grantCovers, parseGrants, scanContent, NAMING_SURFACES } from './g5-guard.js';
+let assertions = 0;
+function ok(value, message) {
+    assert.ok(value, message);
+    assertions += 1;
+}
+// ── 1. pattern 命中/不命中双向 ──────────────────────────────────────────────
+const mustHit = [
+    ['env key', 'G5_BRIDGE_ENDPOINT=https://internal.example'],
+    ['camelCase identifier', 'const g5Bridge = createBridge()'],
+    ['hyphen path', 'see ts/src/adapters/g5-bridge/client.ts'],
+    ['internal MCP plugin id', 'registerPlugin("capability-travel-mcp")'],
+    ['t-system bridge', 't-system bridge adapter for flights'],
+    ['bridge adjacent t-system', 'BridgeTSystem flights'],
+    ['chinese adjacency', '启用 G5 桥'],
+    ['chinese bridge g5', '桥 G5 工具'],
+    ['chinese t-system prefix', '桥接 T 系统 的机票工具'],
+    ['chinese t-system suffix', 'T 系统适配层'],
+];
+for (const [label, text] of mustHit) {
+    ok(scanContent('fixture.ts', text).length === 1, `pattern 应命中: ${label} (${text})`);
+}
+const mustNotHit = [
+    ['carrier code', '{ "carrier_codes": ["CA", "CZ", "G5", "GS"] }'],
+    ['flight number', '"known_flights": ["G52667", "CZ5817"]'],
+    ['persona-bench case id', '| G5 | 万xx 指代 | = 甲米 |'],
+    ['gate mention without bridge adjacency', 'constrained by G5); ② reference'],
+    ['gate row phrase', 'G5 (internal travel bridge approval)'],
+    ['base64-ish noise', '"integrity": "sha512-mQ+/0Fo3LTIX+4k3m+P4y9e9IA6/BeNHrWW19U+G5x0Z8BlybHDELZIB=="'],
+    ['zh gate row phrase', '内部差旅工具桥（T 系统侧，脱敏）的内部审批'],
+];
+for (const [label, text] of mustNotHit) {
+    ok(scanContent('fixture.ts', text).length === 0, `pattern 不应命中(误报): ${label} (${text})`);
+}
+// ── 2. 台账解析 + glob 语义 ────────────────────────────────────────────────
+const empty = parseGrants('# G5 Authorization Ledger\n\n(empty)\n');
+ok(empty.grants.length === 0 && empty.malformed === 0, '空台账应解析为 0 授权');
+const noLink = parseGrants('- GRANT: src/** — some bridge\n');
+ok(noLink.grants.length === 0 && noLink.malformed === 1, '缺 issue/决策链接的 GRANT 应被拒收(fail closed)');
+const ledger = parseGrants([
+    '# ledger',
+    '- GRANT: src/adapters/** — masked flight reads, tenant X — issue: #348',
+    '- GRANT: docs/notes.md — demo — decision: https://example/decision',
+].join('\n'));
+ok(ledger.grants.length === 2 && ledger.malformed === 0, '带 issue/决策链接的 GRANT 应成立');
+ok(grantCovers(ledger.grants[0], 'src/adapters/flight/client.ts'), '`**` 应跨段覆盖');
+ok(!grantCovers(ledger.grants[0], 'docs/notes.md'), '不匹配的路径不应被覆盖');
+const withTemplate = parseGrants([
+    '# ledger',
+    '```',
+    '- GRANT: <path-glob> — system/purpose/scope one-liner — issue/decision: #<n> or URL',
+    '```',
+    '- GRANT: src/** — real entry — issue: #348',
+].join('\n'));
+ok(withTemplate.grants.length === 1 && withTemplate.malformed === 0, 'code fence 内的模板行不应计入 GRANT/畸形');
+const single = globToRegExp('docs/*.md');
+ok(single.test('docs/a.md') && !single.test('docs/sub/b.md'), '`*` 应限单段');
+// ── 3. 命名面豁免 ──────────────────────────────────────────────────────────
+ok(NAMING_SURFACES.has('docs/gotry-master-outline.md') && NAMING_SURFACES.has('docs/gotry-master-outline.zh-CN.md'), '门定义对必须在命名面');
+ok(NAMING_SURFACES.has('docs/g5-authorization-ledger.md') && NAMING_SURFACES.has('ts/scripts/g5-guard.ts'), '台账与 guard 自身必须在命名面');
+// ── 4. CLI 端到端(临时 git fixture) ───────────────────────────────────────
+const tsRoot = join(import.meta.dirname, '..');
+const guardScript = join(tsRoot, 'scripts', 'g5-guard.ts');
+const tsxBin = join(tsRoot, 'node_modules', '.bin', 'tsx');
+function makeFixture(files) {
+    const root = mkdtempSync(join(tmpdir(), 'g5-guard-fixture-'));
+    for (const [rel, content] of Object.entries(files)) {
+        const abs = join(root, rel);
+        mkdirSync(join(abs, '..'), { recursive: true });
+        writeFileSync(abs, content);
+    }
+    spawnSync('git', ['init', '-q'], { cwd: root });
+    spawnSync('git', ['add', '-A'], { cwd: root });
+    return root;
+}
+function runGuard(root) {
+    const result = spawnSync(tsxBin, [guardScript, '--root', root], { encoding: 'utf8' });
+    return { status: result.status ?? -1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+const LEDGER_HEADER = [
+    '# G5 Authorization Ledger',
+    '',
+    '## Entries',
+    '',
+    '(empty)',
+    '',
+].join('\n');
+// 红:未授权桥接引用 → exit 1 + 可操作指引
+const redRoot = makeFixture({
+    'src/adapter.ts': 'export const endpoint = process.env.G5_BRIDGE_ENDPOINT\n',
+    'docs/README.md': 'docs index\n',
+    'docs/g5-authorization-ledger.md': LEDGER_HEADER,
+});
+const red = runGuard(redRoot);
+ok(red.status === 1 && red.stderr.includes('src/adapter.ts') && red.stderr.includes('issues/348'), `未授权引用应 exit 1 且给出路径与 #348 指引(status=${red.status}, stderr=${red.stderr.slice(0, 200)})`);
+// 绿:创始人侧 GRANT 覆盖后 → exit 0(fixture 内的 GRANT 仅演示解析,非真实授权)
+writeFileSync(join(redRoot, 'docs', 'g5-authorization-ledger.md'), LEDGER_HEADER + '- GRANT: src/** — fixture demo only, not a real grant — issue: #348\n');
+const green = runGuard(redRoot);
+ok(green.status === 0, `GRANT 覆盖后应 exit 0(status=${green.status}, stderr=${green.stderr.slice(0, 200)})`);
+rmSync(redRoot, { recursive: true, force: true });
+// 绿:干净仓(无任何引用)→ exit 0
+const cleanRoot = makeFixture({ 'src/adapter.ts': 'export const endpoint = "https://api.hotelbyte.example"\n', 'docs/g5-authorization-ledger.md': LEDGER_HEADER });
+ok(runGuard(cleanRoot).status === 0, '干净仓应 exit 0');
+rmSync(cleanRoot, { recursive: true, force: true });
+// exit 2:台账缺失 → 闸不可用,而不是放行
+const noLedgerRoot = makeFixture({ 'src/adapter.ts': 'export const x = 1\n' });
+ok(runGuard(noLedgerRoot).status === 2, '台账缺失应 exit 2(闸配置错误),不得放行');
+rmSync(noLedgerRoot, { recursive: true, force: true });
+console.log(`G5 GUARD TESTS: ${assertions}/${assertions} OK(命中/不命中双向 / 台账 fail-closed+glob / 命名面 / CLI 红绿+exit2)`);

package/dist/scripts/g5-guard.js

@@ -0,0 +1,189 @@
+/**
+ * G5 内部差旅桥机械闸(issue #348;governance/复用矩阵纪律的机械化,不是新政策)。
+ *
+ * 背景:G5 = 「内部差旅工具桥(T 系统侧,脱敏)」的创始人审批门,当前关闭
+ * (docs/gotry-master-outline.md 决策门表 + #348)。复用矩阵纪律:内部资产只能
+ * bridge/reference,桥接前必须有创始人显式授权。本脚本把该约束落成机械检查:
+ *   1. 扫描全部 git-tracked 文件(排除第三方/生成物/创始人私有 state)中
+ *      「G5 桥接引用」形状的标识符/配置/文案;
+ *   2. 命中时要求 docs/g5-authorization-ledger.md 存在覆盖该路径的 GRANT 条目
+ *      (含 issue/决策链接);没有 → exit 1,输出可操作指引。
+ *
+ * 边界(诚实声明):本闸只证明「无授权记录 → 桥接引用不落地」;
+ * GRANT 条目只能由创始人侧维护,agent 自助授权不被本闸承认(作者身份靠
+ * git review,机械不可证)。真实 G5 授权本身仍是创始人决策(#348)。
+ *
+ * 命名面豁免(NAMING_SURFACES):门定义/授权台账/guard 自身必须能「提到」
+ * 这条关闭中的 lane,否则 tracker 无法描述自己的门。除此之外一律要求 GRANT。
+ *
+ * 用法:cd ts && npx tsx scripts/g5-guard.ts [--root <dir>]
+ * 退出码:0 = 通过;1 = 存在未授权引用;2 = 闸自身无法运行(缺台账/git 失败)。
+ * 自测:cd ts && npx tsx scripts/g5-guard-tests.ts(全离线,临时 fixture)。
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const LEDGER_REL = 'docs/g5-authorization-ledger.md';
+export const ISSUE_348_URL = 'https://github.com/Danceiny/gotry/issues/348';
+/**
+ * 「G5 桥接引用」的机械形状:标识符/配置键/插件名/中英文邻接短语。
+ * 边界用显式 lookaround 而非 `\b`:下划线是 word char,`\b` 会漏掉
+ * snake_case(G5_BRIDGE_*)与 camelCase(G5Bridge)相邻形状。
+ */
+export const G5_BRIDGE_PATTERNS = [
+    { name: 'g5-adjacent-bridge-identifier', regex: /(?<![a-z0-9])g5[\s_-]{0,2}(bridge|bridged|bridging|adapter|adaptor|mcp)/i },
+    { name: 'bridge-adjacent-g5-identifier', regex: /(?<![a-z0-9])(bridge|bridged|bridging|adapter|adaptor)[\s_-]{0,2}g5(?![0-9])/i },
+    { name: 'internal-travel-mcp-plugin-id', regex: /\bcapability-travel-mcp\b/i },
+    { name: 't-system-bridge-identifier', regex: /(?<![a-z0-9])t[-_ ]?system[\s_-]{0,2}(bridge|bridged|bridging|adapter|adaptor|mcp)/i },
+    { name: 'bridge-adjacent-t-system', regex: /(?<![a-z0-9])(bridge|bridged|bridging|adapter|adaptor)[\s_-]{0,2}t[-_ ]?system/i },
+    { name: 'chinese-g5-bridge-adjacency', regex: /g5\s*桥|桥\s*g5/i },
+    { name: 'chinese-t-system-bridge-adjacency', regex: /T\s*系统\s*(桥|适配|接入)|(桥接|接入)\s*T\s*系统/ },
+];
+/**
+ * 命名面豁免:这些文件被允许「提到」G5 lane(定义它/授权它/检测它),
+ * 它们不是授权——真实桥接落在其它任何文件都仍需台账 GRANT。
+ *  - master-outline 对:G5 门定义 + 复用矩阵 T 系统行(tracker 本体);
+ *  - 授权台账对:授权面自身;
+ *  - guard + 自测:检测器必须含有自己的检测串。
+ */
+export const NAMING_SURFACES = new Set([
+    'docs/gotry-master-outline.md',
+    'docs/gotry-master-outline.zh-CN.md',
+    'docs/g5-authorization-ledger.md',
+    'docs/g5-authorization-ledger.zh-CN.md',
+    'ts/scripts/g5-guard.ts',
+    'ts/scripts/g5-guard-tests.ts',
+]);
+/** 排除段:第三方闭包/生成物/创始人私有产品数据(只读红线目录也不扫)。 */
+const EXCLUDED_SEGMENTS = ['node_modules', 'vendor', 'dist', '.git', 'dsh-runtime', 'gotry-state'];
+const LOCKFILE_BASENAMES = new Set(['package-lock.json', 'pnpm-lock.yaml', 'uv.lock', 'bun.lock', 'bun.lockb', 'npm-shrinkwrap.json']);
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.mp4', '.mov', '.zip', '.gz', '.tgz', '.bz2', '.7z', '.pdf', '.wasm', '.node', '.dylib', '.so', '.bin', '.icns',
+]);
+export function isExcludedPath(relPath) {
+    const segments = relPath.split('/');
+    if (segments.some((s) => EXCLUDED_SEGMENTS.includes(s)))
+        return true;
+    const base = segments[segments.length - 1];
+    if (LOCKFILE_BASENAMES.has(base))
+        return true;
+    const dot = base.lastIndexOf('.');
+    if (dot >= 0 && BINARY_EXTENSIONS.has(base.slice(dot).toLowerCase()))
+        return true;
+    return false;
+}
+/** 单文件内容扫描:返回全部命中行(文件级,供 collectHits 逐文件调用)。 */
+export function scanContent(relPath, content) {
+    const hits = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        for (const { name, regex } of G5_BRIDGE_PATTERNS) {
+            if (regex.test(line)) {
+                hits.push({ path: relPath, line: i + 1, pattern: name, text: line.trim().slice(0, 160) });
+                break; // 一行一次足矣,避免同 pattern 行内重复刷屏
+            }
+        }
+    }
+    return hits;
+}
+/** 台账 GRANT 行:`- GRANT: <glob> — <说明,必须含 issue/决策链接>`;code fence 内的行(模板/示例)不算数。 */
+export function parseGrants(ledgerText) {
+    const grants = [];
+    let malformed = 0;
+    let inFence = false;
+    for (const rawLine of ledgerText.split('\n')) {
+        if (/^`{3,}/.test(rawLine.trim())) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = rawLine.match(/^-\s*GRANT:\s*(\S+)\s+—\s+(.+)$/);
+        if (!match)
+            continue;
+        // 无 issue/决策链接的 GRANT 视为不成立(fail closed),单独计数以便报错指引
+        if (!/#\d+|https?:\/\//.test(match[2])) {
+            malformed += 1;
+            continue;
+        }
+        grants.push({ glob: match[1], description: match[2].trim() });
+    }
+    return { grants, malformed };
+}
+/** glob → 路径正则:`**` 跨段,`*` 单段内,`?` 单字符。 */
+export function globToRegExp(glob) {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '\u0000')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]')
+        .replace(/\u0000/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+export function grantCovers(grant, relPath) {
+    return globToRegExp(grant.glob).test(relPath);
+}
+function listTrackedFiles(root) {
+    const result = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'buffer' });
+    if (result.error || result.status !== 0) {
+        console.error(`G5 GUARD: 无法枚举 git-tracked 文件(需要 git 仓库): ${result.error?.message ?? result.stderr?.toString().trim()}`);
+        process.exit(2);
+    }
+    return result.stdout.toString().split('\0').filter(Boolean);
+}
+function main() {
+    const args = process.argv.slice(2);
+    const rootIndex = args.indexOf('--root');
+    const root = rootIndex >= 0 ? resolve(args[rootIndex + 1]) : resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const ledgerPath = join(root, LEDGER_REL);
+    if (!existsSync(ledgerPath)) {
+        console.error(`G5 GUARD: 授权台账不存在: ${LEDGER_REL}(闸配置错误,exit 2;台账由创始人侧维护)`);
+        process.exit(2);
+    }
+    const ledger = parseGrants(readFileSync(ledgerPath, 'utf8'));
+    const hits = [];
+    let scanned = 0;
+    for (const relPath of listTrackedFiles(root)) {
+        if (isExcludedPath(relPath))
+            continue;
+        if (NAMING_SURFACES.has(relPath))
+            continue;
+        const abs = join(root, relPath);
+        let content;
+        try {
+            content = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue; // 不可读(权限/符号链接悬空):跳过,不属于闸的裁决面
+        }
+        if (content.includes('\0'))
+            continue; // 二进制内容:跳过
+        scanned += 1;
+        hits.push(...scanContent(relPath, content));
+    }
+    if (hits.length === 0) {
+        console.log(`G5 GUARD: OK — ${scanned} 个 tracked 文件中无未授权 G5 桥引用;台账 GRANT: ${ledger.grants.length}${ledger.malformed ? `(另有 ${ledger.malformed} 条缺 issue/决策链接的 GRANT 被拒)` : ''}`);
+        process.exit(0);
+    }
+    const uncovered = hits.filter((hit) => !ledger.grants.some((grant) => grantCovers(grant, hit.path)));
+    for (const hit of hits) {
+        const covered = ledger.grants.some((grant) => grantCovers(grant, hit.path));
+        console.error(`  ${hit.path}:${hit.line} [${hit.pattern}]${covered ? ' (已授权)' : ''} ${hit.text}`);
+    }
+    if (uncovered.length === 0) {
+        console.log(`G5 GUARD: OK — ${hits.length} 处 G5 桥引用均被台账 GRANT 覆盖`);
+        process.exit(0);
+    }
+    console.error(`G5 GUARD: FAIL — ${uncovered.length} 处未授权的 G5 内部差旅桥引用(共扫描 ${scanned} 个文件):`);
+    console.error('G5 门当前关闭:桥接内部旅行系统(T 系统)前必须获得创始人显式授权,可执行其一:');
+    console.error(`  1. 由创始人在 ${LEDGER_REL} 增加覆盖上述路径的 GRANT 条目(含 issue/决策链接;仅创始人侧维护,agent 不得自助授权);`);
+    console.error('  2. 或移除引用,保持外部供应商路径(公共 MIT hotelbyte-cli 进程桥)。');
+    console.error(`Tracker: ${ISSUE_348_URL}(复用矩阵:内部资产只能 bridge/reference,禁止代码/schema 搬运)`);
+    process.exit(1);
+}
+const isDirectRun = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectRun)
+    main();