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

package/dist/scripts/booking-copilot-startup-proof-tests.js

@@ -0,0 +1,94 @@
+/** Production startup composition proof (dependencies injected; no real model). */
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveBookingCopilotStartupConfig, startBookingCopilotFromEnvironment, } from '../src/booking-surface/startup.js';
+import { BOOKING_FULL_JOURNEY_ACTION_KINDS } from '../src/booking-surface/contracts.js';
+assert.throws(() => resolveBookingCopilotStartupConfig({}), /booking_copilot_api_key_required/);
+assert.throws(() => resolveBookingCopilotStartupConfig({
+    GOTRY_BOOKING_COPILOT_API_KEY: 'bff-key',
+    GOTRY_BOOKING_COPILOT_STATE_ROOT: '/tmp/gotry-booking-startup',
+    GOTRY_BOOKING_COPILOT_ARTIFACT_ID: 'not-a-commit',
+}), /booking_copilot_artifact_id_invalid/);
+assert.throws(() => resolveBookingCopilotStartupConfig({
+    GOTRY_BOOKING_COPILOT_API_KEY: 'bff-key',
+    GOTRY_BOOKING_COPILOT_STATE_ROOT: 'relative/state',
+}), /booking_copilot_state_root_must_be_absolute/);
+const stateRoot = mkdtempSync(join(tmpdir(), 'gotry-booking-startup-'));
+const env = {
+    GOTRY_BOOKING_COPILOT_API_KEY: 'bff-only-key',
+    GOTRY_BOOKING_COPILOT_STATE_ROOT: stateRoot,
+    GOTRY_BOOKING_COPILOT_PORT: '0',
+    GOTRY_BOOKING_COPILOT_ARTIFACT_ID: '1111111111111111111111111111111111111111',
+    LLM_API_KEY: 'model-only-key',
+    LLM_BASE_URL: 'http://model-route.invalid/v1',
+    LLM_MODEL: 'model-v1',
+    LLM_MAX_TOKENS: '8192',
+    PORTAL_TOKEN: 'must-not-enter-planner',
+    HOTELBYTE_TOKEN: 'must-not-enter-planner',
+};
+await assert.rejects(startBookingCopilotFromEnvironment({ ...env, GOTRY_BOOKING_COPILOT_INGRESS_MODE: 'bff-ingress-binding' }, {}), /booking_copilot_ingress_binding_required/, 'explicit ingress mode rejects startup when the trusted BFF seam is absent');
+await assert.rejects(startBookingCopilotFromEnvironment(env, {
+    ingressBinding: { bind: () => ({ taskId: 'partial-task', turnId: 'partial-turn', contextRef: 'partial-context', surface: 'tenant', allowedActions: [...BOOKING_FULL_JOURNEY_ACTION_KINDS] }) },
+}), /booking_copilot_ingress_binding_pair_required/, 'partial trusted BFF seam is rejected before startup');
+await assert.rejects(startBookingCopilotFromEnvironment(env, { principal: { subject: 'partial-bff', scope: 'booking:read' } }), /booking_copilot_ingress_binding_pair_required/, 'principal without a binding is rejected before startup');
+let standaloneIngressMode = '';
+const standaloneStateRoot = mkdtempSync(join(tmpdir(), 'gotry-booking-startup-standalone-'));
+const standalone = await startBookingCopilotFromEnvironment({ ...env, GOTRY_BOOKING_COPILOT_STATE_ROOT: standaloneStateRoot }, {
+    ensureLedger() { return { close() { } }; },
+    runtimeFactory() { return {}; },
+    createPlanner: async () => ({ plannerFactory() { return { async next() { return []; } }; }, async close() { } }),
+    async startServer(options) {
+        standaloneIngressMode = options.ingressMode ?? '';
+        return { server: {}, port: 43122, async close() { } };
+    },
+});
+assert.equal(standalone.port, 43122);
+assert.equal(standaloneIngressMode, 'bff-bound-turn-only', 'standalone production startup uses the explicit bound-turn-only mode');
+await standalone.close();
+rmSync(standaloneStateRoot, { recursive: true, force: true });
+const closeOrder = [];
+let plannerEnv;
+let serverApiKey = '';
+let serverArtifactId = '';
+const trustedEnv = { ...env, GOTRY_BOOKING_COPILOT_INGRESS_MODE: 'bff-ingress-binding' };
+const fakeLedger = { close() { closeOrder.push('ledger'); } };
+const trustedBinding = { bind: () => ({ taskId: 'startup-task', turnId: 'startup-turn', contextRef: 'startup-context', surface: 'tenant', allowedActions: [...BOOKING_FULL_JOURNEY_ACTION_KINDS] }) };
+const started = await startBookingCopilotFromEnvironment(trustedEnv, {
+    ensureLedger() { return fakeLedger; },
+    runtimeFactory() { return {}; },
+    async createPlanner(options) {
+        plannerEnv = options.env;
+        return {
+            plannerFactory() { return { async next() { return []; } }; },
+            async close() { closeOrder.push('planner'); },
+        };
+    },
+    ingressBinding: trustedBinding,
+    principal: { subject: 'startup-bff', scope: 'booking:read' },
+    async startServer(options) {
+        serverApiKey = options.apiKey;
+        serverArtifactId = options.artifactId ?? '';
+        assert.equal(options.ingressMode, 'bff-ingress-binding');
+        return {
+            server: {},
+            port: 43123,
+            async close() { closeOrder.push('server'); },
+        };
+    },
+});
+assert.equal(started.port, 43123);
+assert.equal(serverApiKey, 'bff-only-key', 'BFF deployment key terminates at the HTTP server');
+assert.equal(serverArtifactId, env.GOTRY_BOOKING_COPILOT_ARTIFACT_ID);
+assert.equal(plannerEnv?.DEEPSEEK_API_KEY, 'model-only-key');
+assert.equal(plannerEnv?.DEEPSEEK_BASE_URL, 'http://model-route.invalid/v1');
+assert.equal(plannerEnv?.DEEPSEEK_MODEL, 'model-v1');
+assert.equal(plannerEnv?.DEEPSEEK_MAX_TOKENS, '8192');
+assert.equal(plannerEnv?.GOTRY_BOOKING_COPILOT_API_KEY, undefined);
+assert.equal(plannerEnv?.PORTAL_TOKEN, undefined);
+assert.equal(plannerEnv?.HOTELBYTE_TOKEN, undefined);
+await started.close();
+assert.deepEqual(closeOrder, ['server', 'planner', 'ledger']);
+rmSync(stateRoot, { recursive: true, force: true });
+console.log('BOOKING COPILOT STARTUP PROOF: env split/server+planner+ledger lifecycle OK');

package/dist/scripts/booking-executor-tests.js

@@ -0,0 +1,80 @@
+import { closeBackend, createBackendServer } from '../src/backend/kernel.js';
+import { startBookingExecutorModule } from '../src/backend/modules/booking-executor.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let pass = 0;
+let fail = 0;
+const check = (cond, label) => {
+    if (cond) {
+        pass += 1;
+        console.log(`  ok - ${label}`);
+    }
+    else {
+        fail += 1;
+        console.log(`  FAIL - ${label}`);
+    }
+};
+async function jfetch(url, init) {
+    const r = await fetch(url, init);
+    let body = null;
+    try {
+        body = await r.json();
+    }
+    catch { /* 空体 */ }
+    return { status: r.status, body };
+}
+async function main() {
+    const module = startBookingExecutorModule({
+        apiKey: () => 'test-booking-key',
+        evidenceDir: () => '/tmp/booking-executor-test-evidence',
+        observe: async () => ({
+            ok: true,
+            supplier: 'dida-portal',
+            entryUrl: 'https://portal.dida.com/hotel/find',
+            entryPoints: [{ text: '预订', tag: 'button' }],
+            screenshotPath: '/tmp/evidence/test.png',
+            observedAt: new Date().toISOString(),
+        }),
+    });
+    const handle = await createBackendServer({ modules: [module], port: 0 });
+    const base = `http://127.0.0.1:${handle.port}`;
+    try {
+        // ① 鉴权 fail-closed
+        const noAuth = await jfetch(`${base}/v1/booking/observe`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ supplier: 'dida-portal' }),
+        });
+        check(noAuth.status === 403, '无 token 403');
+        // ② 注入观察器:正常观察
+        const ok = await jfetch(`${base}/v1/booking/observe`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: 'Bearer test-booking-key' },
+            body: JSON.stringify({ supplier: 'dida-portal' }),
+        });
+        const okBody = ok.body;
+        check(ok.status === 200 && okBody.ok === true && okBody.supplier === 'dida-portal', '观察返回 200 + 供应商');
+        check(Array.isArray(okBody.entryPoints) && okBody.entryPoints.length === 1, '入口观察条目形状');
+        // ③ 未知供应商拒绝
+        const bad = await jfetch(`${base}/v1/booking/observe`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: 'Bearer test-booking-key' },
+            body: JSON.stringify({ supplier: 'ctrip-flight' }),
+        });
+        check(bad.status === 400, '未知供应商 400');
+        // ④ 域外 entryUrl 拒绝
+        const evil = await jfetch(`${base}/v1/booking/observe`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: 'Bearer test-booking-key' },
+            body: JSON.stringify({ supplier: 'dida-portal', entryUrl: 'https://evil.example.com/x' }),
+        });
+        check(evil.status === 400, '域外 entryUrl 400');
+    }
+    finally {
+        await closeBackend(handle, [module]).catch(() => { });
+    }
+    await sleep(30);
+    console.log(`\nBOOKING EXECUTOR: ${pass} pass, ${fail} fail`);
+    if (fail > 0)
+        process.exitCode = 1;
+}
+void main();

package/dist/scripts/booking-recovery-chain-tests.js

@@ -0,0 +1,182 @@
+/**
+ * Booking Copilot unavailable/changed 恢复链契约测试（issue #142 非门控切片；全离线纯函数，零真实供应商调用）：
+ *  1. 检测分类（复用 ActionReceipt status 闭集，不发明新通道）：confirmed / changed（版本被取代=价格变动/房型关闭）/
+ *     unavailable（完整负证据）/ inconclusive（partial/stale/failed/gap——不得宣称「市场无房」）/ unrelated（非 offer.check 观测）
+ *  2. 分类 fail-closed：available+empty outcome、!available 却携 verifiedOfferRef、unavailable 却非 empty outcome、
+ *     applied/changed/unavailable 却观测形态不符——全部抛 availability_receipt_incoherent 同名错误
+ *  3. 链开立 fail-closed：confirmed → recovery_chain_not_required；unrelated → recovery_trigger_absent；
+ *     taskId/contextRef/originalSelection 绑定键缺一即拒
+ *  4. 受控恢复（不开新无界重试通道）：approach 闭集 recheck_version/requery_same_hotel/alternative_candidate；
+ *     每次计入预算的恢复轮对齐 planner 三次调用预算（第 4 次拒绝）；终态吸收，其后不得再有 attempt
+ *  5. 用户沟通红线：恢复命中与原选择不同酒店/报价且未先披露 → recovery_silent_swap_forbidden（静默换房换航结构性拒绝）；
+ *     先披露再解决 → 合法；空披露文本拒绝；降级必须携显式披露（静默降级拒绝）
+ *  6. 显式说明变化：版本位移的 resolved 必须产出非空变化说明（old→new versionRef）——不静默换版
+ *  7. 审计可对账（对齐 sagaTraceViolations 形态）：合法链空违例；缺 detected 起点/终态后事件/静默替换/静默降级/未知 kind 全部违例
+ *  8. 纯函数：每次推进返回新状态，原状态不可变；receiptDigestOf 规范摘要稳定且随内容变化
+ *
+ * 运行：cd ts && npx tsx scripts/booking-recovery-chain-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { RECOVERY_CHAIN_SCHEMA, MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER, MAX_RECOVERY_BUDGET_NOTE, classifyRecoveryTrigger, receiptDigestOf, openRecoveryChain, attemptRecoveryStep, discloseSubstitution, degradeRecoveryChain, buildUserDisclosure, recoveryAuditViolations, } from '../src/booking-surface/recovery-chain.js';
+const T0 = '2026-09-11T10:00:00.000Z';
+const T1 = '2026-09-11T10:00:01.000Z';
+const T2 = '2026-09-11T10:00:02.000Z';
+const ORIGINAL = { hotelRef: 'hotel-1', offerRef: 'offer-1', offerVersionRef: 'v1' };
+const CLEAN_CONTRACT = { outcome: 'complete', hardCriteriaMet: true, factRefs: [], gapCodes: [], blockers: [], relaxationsApplied: [] };
+function receipt(overrides) {
+    return {
+        schemaVersion: 'booking.surface',
+        kind: 'action.receipt',
+        actionId: 'act-1',
+        contextRef: 'ctx-1',
+        status: 'applied',
+        revision: 3,
+        observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: true, currentOfferVersionRef: ORIGINAL.offerVersionRef, verifiedOfferRef: 'verified-1', changedFactRefs: [] },
+        resultContract: CLEAN_CONTRACT,
+        ...overrides,
+    };
+}
+function seedChain(overrides = {}) {
+    return openRecoveryChain({
+        taskId: 'task-1',
+        contextRef: 'ctx-1',
+        receipt: receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }),
+        originalSelection: ORIGINAL,
+        at: T0,
+        ...overrides,
+    });
+}
+// ── 1. 检测分类：复用 status 闭集 ────────────────────────────────────────────
+const confirmedCls = classifyRecoveryTrigger(receipt({}));
+assert.equal(confirmedCls.kind, 'confirmed', 'applied+available+版本一致+verified → confirmed');
+assert.equal(confirmedCls.verifiedOfferRef, 'verified-1');
+const changedCls = classifyRecoveryTrigger(receipt({
+    status: 'changed',
+    observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: true, currentOfferVersionRef: 'v2', verifiedOfferRef: undefined, changedFactRefs: ['fact.price'] },
+}));
+assert.equal(changedCls.kind, 'changed', 'changed+available+后继版本 → changed（价格变动/房型关闭的供应商形态）');
+assert.equal(changedCls.currentOfferVersionRef, 'v2');
+assert.deepEqual(changedCls.changedFactRefs, ['fact.price']);
+const unavailableCls = classifyRecoveryTrigger(receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }));
+assert.equal(unavailableCls.kind, 'unavailable', 'unavailable+!available+empty outcome → unavailable（完整负证据）');
+const noMatchCls = classifyRecoveryTrigger(receipt({ status: 'no_match', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }));
+assert.equal(noMatchCls.kind, 'unavailable', 'no_match 同归 unavailable 闭集（既有词汇）');
+for (const [status, extra] of [
+    ['partial', { resultContract: { ...CLEAN_CONTRACT, outcome: 'partial' } }],
+    ['stale', {}],
+    ['failed', {}],
+    ['needs_input', {}],
+]) {
+    const cls = classifyRecoveryTrigger(receipt({ status, observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [], gapCodes: ['check_avail_unverified'] }, ...extra }));
+    assert.equal(cls.kind, 'inconclusive', `${status} → inconclusive`);
+    assert.match(cls.reason, /not_claim_market_empty/, 'inconclusive 必须携带「不得宣称市场无房」语义');
+}
+const gapCls = classifyRecoveryTrigger(receipt({ status: 'partial', observation: { kind: 'gap', code: 'check_avail_failed', factRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'partial' } }));
+assert.equal(gapCls.kind, 'inconclusive', 'gap 观测 → inconclusive（不可确认 ≠ 无房）');
+assert.equal(classifyRecoveryTrigger(receipt({ observation: { kind: 'offers.state', hotelRefs: [ORIGINAL.hotelRef], offerRefs: [ORIGINAL.offerRef], loadedHotelCount: 1 } })).kind, 'unrelated', 'offers.query 观测不是 offer 级恢复触发（generation 折叠归 policy 所有）');
+assert.equal(classifyRecoveryTrigger(receipt({ observation: { kind: 'search.state', resultCount: 3 } })).kind, 'unrelated', 'search.state → unrelated');
+// ── 2. 分类 fail-closed：不连贯 receipt 拒绝 ────────────────────────────────
+assert.throws(() => classifyRecoveryTrigger(receipt({ status: 'unavailable', resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } })), /availability_receipt_incoherent/, 'available=true + unavailable status → 不连贯');
+assert.throws(() => classifyRecoveryTrigger(receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, verifiedOfferRef: 'verified-x', changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } })), /availability_receipt_incoherent/, '!available 却携 verifiedOfferRef → 不连贯');
+assert.throws(() => classifyRecoveryTrigger(receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'partial' } })), /availability_receipt_incoherent/, 'unavailable 却非 empty outcome → 不连贯');
+assert.throws(() => classifyRecoveryTrigger(receipt({ status: 'changed', observation: { kind: 'search.state', resultCount: 1 } })), /availability_observation_required/, 'changed 却无 offer.availability 观测 → 观测缺失');
+// ── 3. 链开立：fail-closed ─────────────────────────────────────────────────
+assert.throws(() => openRecoveryChain({ taskId: 'task-1', contextRef: 'ctx-1', receipt: receipt({}), originalSelection: ORIGINAL, at: T0 }), /recovery_chain_not_required/, 'confirmed 无需恢复链');
+assert.throws(() => openRecoveryChain({ taskId: 'task-1', contextRef: 'ctx-1', receipt: receipt({ observation: { kind: 'search.state', resultCount: 1 } }), originalSelection: ORIGINAL, at: T0 }), /recovery_trigger_absent/, 'unrelated 不开链');
+assert.throws(() => seedChain({ taskId: '' }), /recovery_binding_missing/, 'taskId 缺失即拒');
+assert.throws(() => seedChain({ contextRef: '' }), /recovery_binding_missing/, 'contextRef 缺失即拒');
+assert.throws(() => seedChain({ originalSelection: { ...ORIGINAL, offerRef: '' } }), /recovery_binding_missing/, '原选择 offerRef 缺失即拒');
+const chain = seedChain();
+assert.equal(chain.schemaVersion, RECOVERY_CHAIN_SCHEMA);
+assert.equal(chain.trigger, 'unavailable');
+assert.equal(chain.phase, 'detected');
+assert.equal(chain.countedModelTurns, 0);
+assert.deepEqual(chain.originalSelection, ORIGINAL);
+assert.equal(chain.history.length, 1);
+assert.equal(chain.history[0].kind, 'recovery.detected');
+assert.ok(chain.history[0].receiptDigest?.length === 64, 'detected 事件带 receipt 摘要');
+const changedChain = openRecoveryChain({
+    taskId: 'task-1', contextRef: 'ctx-1',
+    receipt: receipt({ status: 'changed', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: true, currentOfferVersionRef: 'v2', changedFactRefs: ['fact.price'] } }),
+    originalSelection: ORIGINAL, at: T0,
+});
+assert.equal(changedChain.trigger, 'changed');
+// ── 4. 受控恢复：approach 闭集 + 三轮预算 + 终态吸收 ────────────────────────
+const afterQuery = attemptRecoveryStep(chain, { receipt: receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }), target: ORIGINAL, approach: 'requery_same_hotel' }, T1);
+assert.equal(afterQuery.phase, 'recovering');
+assert.equal(afterQuery.countedModelTurns, 1, '恢复轮计入预算');
+assert.equal(afterQuery.history.length, 2);
+assert.equal(afterQuery.history[1].kind, 'recovery.attempt');
+assert.deepEqual(afterQuery.history[1].target, ORIGINAL);
+assert.throws(() => attemptRecoveryStep(chain, { receipt: receipt({}), target: ORIGINAL, approach: 'wild_retry' }, T1), /recovery_approach_invalid/, 'approach 不在闭集即拒（不开新重试通道）');
+assert.throws(() => attemptRecoveryStep(afterQuery, { receipt: receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, verifiedOfferRef: 'verified-x', changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }), target: ORIGINAL, approach: 'requery_same_hotel' }, T1), /availability_receipt_incoherent/, 'attempt 携带不连贯 receipt 拒绝（不可确认当证据）');
+// confirmed 于同 offer 同版本 → resolved（无需替换披露）
+const recovered = attemptRecoveryStep(afterQuery, { receipt: receipt({}), target: ORIGINAL, approach: 'requery_same_hotel' }, T2);
+assert.equal(recovered.phase, 'resolved');
+assert.deepEqual(recovered.resolvedTo, ORIGINAL);
+assert.equal(recovered.history.at(-1).kind, 'recovery.resolved');
+assert.throws(() => attemptRecoveryStep(recovered, { receipt: receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }), target: ORIGINAL, approach: 'requery_same_hotel' }, T2), /recovery_chain_terminal/, '终态吸收：resolved 后不得再有 attempt');
+// changed 触发 → recheck_version 路径也走闭集
+const rechecked = attemptRecoveryStep(changedChain, { receipt: receipt({}), target: { ...ORIGINAL, offerVersionRef: 'v2' }, approach: 'recheck_version' }, T1);
+assert.equal(rechecked.phase, 'resolved');
+assert.deepEqual(rechecked.resolvedTo, { ...ORIGINAL, offerVersionRef: 'v2' });
+const recheckDisclosure = buildUserDisclosure(rechecked);
+assert.equal(recheckDisclosure.substitution, false, '同酒店同报价仅版本位移不是替换');
+assert.equal(recheckDisclosure.versionShifted, true);
+assert.match(recheckDisclosure.text, /v1/, '变化说明必须显式含旧版本');
+assert.match(recheckDisclosure.text, /v2/, '变化说明必须显式含新版本');
+// 三轮模型调用预算（对齐 planner attempt < 3）
+let budgetChain = seedChain();
+for (let turn = 0; turn < MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER; turn += 1) {
+    budgetChain = attemptRecoveryStep(budgetChain, { receipt: receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }), target: ORIGINAL, approach: 'requery_same_hotel' }, T1);
+}
+assert.equal(budgetChain.countedModelTurns, MAX_RECOVERY_MODEL_TURNS_PER_TRIGGER);
+assert.ok(MAX_RECOVERY_BUDGET_NOTE.includes('3'), '预算语义说明对齐 planner 三次调用');
+assert.throws(() => attemptRecoveryStep(budgetChain, { receipt: receipt({ status: 'unavailable', observation: { kind: 'offer.availability', offerRef: ORIGINAL.offerRef, checkedOfferVersionRef: ORIGINAL.offerVersionRef, available: false, changedFactRefs: [] }, resultContract: { ...CLEAN_CONTRACT, outcome: 'empty' } }), target: ORIGINAL, approach: 'requery_same_hotel' }, T1), /recovery_model_turn_budget_exhausted/, '第 4 次计入预算的恢复轮拒绝——必须降级');
+// ── 5. 用户沟通红线：静默换房换航结构性拒绝 ────────────────────────────────
+const substituteTarget = { hotelRef: 'hotel-2', offerRef: 'offer-9', offerVersionRef: 'v9' };
+assert.throws(() => attemptRecoveryStep(afterQuery, { receipt: receipt({}), target: substituteTarget, approach: 'alternative_candidate' }, T2), /recovery_silent_swap_forbidden/, '未披露先换酒店 → 静默换房拒绝');
+assert.equal(afterQuery.phase, 'recovering', '拒绝即不动（纯函数，原状态不变）');
+const disclosed = discloseSubstitution(afterQuery, { target: substituteTarget, disclosureText: '原报价已不可用，替代候选为 hotel-2 的 offer-9（价格已变化）', at: T2 });
+assert.equal(disclosed.substitutionDisclosed, true);
+assert.equal(disclosed.history.at(-1).kind, 'recovery.disclosed');
+assert.equal(disclosed.history.at(-1).substitution, true);
+assert.throws(() => discloseSubstitution(afterQuery, { target: substituteTarget, disclosureText: '', at: T2 }), /recovery_disclosure_required/, '空披露文本拒绝');
+const substituted = attemptRecoveryStep(disclosed, { receipt: receipt({}), target: substituteTarget, approach: 'alternative_candidate' }, T2);
+assert.equal(substituted.phase, 'resolved');
+assert.deepEqual(substituted.resolvedTo, substituteTarget);
+const subDisclosure = buildUserDisclosure(substituted);
+assert.equal(subDisclosure.substitution, true, '替换解决必须显式标记');
+assert.match(subDisclosure.text, /hotel-1/, '说明必须提及原酒店');
+assert.match(subDisclosure.text, /hotel-2/, '说明必须提及替代酒店');
+assert.throws(() => discloseSubstitution(recovered, { target: substituteTarget, disclosureText: 'x', at: T2 }), /recovery_chain_terminal/, '终态后不得再披露');
+// 降级：静默降级拒绝；显式披露后降级合法且吸收
+assert.throws(() => degradeRecoveryChain(budgetChain, { reason: 'budget exhausted', disclosureText: '', at: T2 }), /recovery_degrade_requires_disclosure/, '静默降级拒绝');
+const degraded = degradeRecoveryChain(budgetChain, { reason: 'recovery budget exhausted', disclosureText: '原报价已不可用且恢复预算耗尽，任务显式结束，未做任何替换', at: T2 });
+assert.equal(degraded.phase, 'degraded');
+assert.equal(degraded.history.at(-1).kind, 'recovery.degraded');
+assert.ok(degraded.history.some((event) => event.kind === 'recovery.disclosed'), '降级前必有显式披露事件');
+assert.throws(() => degradeRecoveryChain(degraded, { reason: 'again', disclosureText: 'x', at: T2 }), /recovery_chain_terminal/, '降级吸收');
+// ── 6+7. 审计链校验（sagaTraceViolations 同形态） ──────────────────────────
+assert.deepEqual(recoveryAuditViolations(recovered.history), [], '合法恢复链零违例');
+assert.deepEqual(recoveryAuditViolations(substituted.history), [], '合法替换链零违例');
+assert.deepEqual(recoveryAuditViolations(degraded.history), [], '合法降级链零违例');
+assert.ok(recoveryAuditViolations([{ at: T0, kind: 'recovery.attempt', from: 'detected', to: 'recovering', reason: 'x' }]).length > 0, '缺 detected 起点违例');
+assert.ok(recoveryAuditViolations([...recovered.history, { at: T2, kind: 'recovery.attempt', from: 'resolved', to: 'recovering', reason: 'late' }]).length > 0, '终态后事件违例');
+assert.ok(recoveryAuditViolations([{ at: T0, kind: 'recovery.detected', from: 'detected', to: 'detected', reason: 'x', target: ORIGINAL }, { at: T1, kind: 'recovery.resolved', from: 'detected', to: 'resolved', reason: 'swap', target: substituteTarget }]).length > 0, '静默替换（无披露的异目标 resolved）违例');
+assert.ok(recoveryAuditViolations([{ at: T0, kind: 'recovery.detected', from: 'detected', to: 'detected', reason: 'x', target: ORIGINAL }, { at: T1, kind: 'recovery.degraded', from: 'detected', to: 'degraded', reason: 'x' }]).length > 0, '静默降级（无披露）违例');
+assert.ok(recoveryAuditViolations([{ at: T0, kind: 'recovery.detected', from: 'detected', to: 'detected', reason: 'x', target: ORIGINAL }, { at: T1, kind: 'recovery.exploded', from: 'detected', to: 'recovering', reason: 'x' }]).length > 0, '未知事件 kind 违例');
+assert.ok(recoveryAuditViolations([{ at: T0, kind: 'recovery.detected', from: 'detected', to: 'detected', reason: 'x', target: ORIGINAL }, { at: T1, kind: 'recovery.resolved', from: 'detected', to: 'resolved', reason: 'x', target: ORIGINAL }, { at: T2, kind: 'recovery.resolved', from: 'resolved', to: 'resolved', reason: 'double', target: ORIGINAL }]).length > 0, '双重终态违例');
+// ── 8. 纯函数 + 摘要稳定性 ─────────────────────────────────────────────────
+const before = JSON.stringify(afterQuery);
+assert.throws(() => attemptRecoveryStep(afterQuery, { receipt: receipt({}), target: substituteTarget, approach: 'alternative_candidate' }, T2), /recovery_silent_swap_forbidden/);
+assert.equal(JSON.stringify(afterQuery), before, '拒绝即不动（原状态不变）');
+const advanced = attemptRecoveryStep(afterQuery, { receipt: receipt({}), target: ORIGINAL, approach: 'requery_same_hotel' }, T2);
+assert.equal(JSON.stringify(afterQuery), before, '推进返回新状态，原状态不可变');
+assert.notEqual(JSON.stringify(advanced), before);
+const digestA = receiptDigestOf(receipt({}));
+const digestB = receiptDigestOf(receipt({ actionId: 'act-2' }));
+assert.equal(receiptDigestOf(receipt({})), digestA, '同一内容摘要稳定');
+assert.notEqual(digestA, digestB, '内容不同摘要不同');
+assert.match(digestA, /^[0-9a-f]{64}$/, '摘要为 sha256 hex');
+console.log('booking-recovery-chain-tests: all scenarios passed');

package/dist/scripts/booking-saga-tests.js

@@ -0,0 +1,125 @@
+/**
+ * 预订 saga 状态机回归(booking_saga_fsm.v1,issue #17 采纳锚点,run-all §36):
+ *  1 字母表/边表封闭性:12 个 (origin,trigger) 组合恰好一边或一拒,无空洞无重复;事件命名收敛
+ *  2 触发解析:主路径可达;二次确认与吸收态推进结构化拒绝;解析器与边表/拒绝表十二格全一致
+ *  3 审计链校验器:合法路径零违例;缺起点/双确认/补偿后再推进/空 receipt 均被抓出
+ *  4 物理对账:真账本(pending_writes 行 + write.* 审计事件)与状态机逐格同归宿——
+ *    状态机不是新机器,是 TS-4 saga 基座的具名化(词汇层与物理层分叉即本节红)
+ *  5 多租户:saga 键以 tenant_id 为一等字段,跨租户互不可见(ADR-16)
+ * 运行(在 ts/ 下):npx tsx scripts/booking-saga-tests.ts
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { BOOKING_SAGA_SCHEMA, SAGA_EDGES, SAGA_REJECTIONS, SAGA_STATUSES, SAGA_TRIGGER_EVENT, resolveSagaTrigger, sagaLegalPaths, sagaTraceViolations, } from '../src/booking-saga.js';
+import { ensureLedger } from '../src/state-ledger.js';
+let pass = 0;
+let fail = 0;
+function assert(cond, msg) {
+    if (cond) {
+        pass++;
+        console.log(`  ok - ${msg}`);
+    }
+    else {
+        fail++;
+        console.error(`  FAIL - ${msg}`);
+    }
+}
+function parseReceipt(payload) {
+    try {
+        const doc = JSON.parse(payload);
+        return typeof doc.receipt === 'string' && doc.receipt !== '' ? doc.receipt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---- 1:字母表与边表封闭性 --------------------------------------------------------
+const TRIGGERS = ['propose', 'confirm', 'compensate'];
+const ORIGINS = ['none', ...SAGA_STATUSES];
+const COMBOS = ORIGINS.flatMap(from => TRIGGERS.map(trigger => `${from}:${trigger}`));
+const edgeKeys = new Set(SAGA_EDGES.map(e => `${e.from}:${e.trigger}`));
+const rejectKeys = new Set(SAGA_REJECTIONS.map(e => `${e.from}:${e.trigger}`));
+assert(BOOKING_SAGA_SCHEMA === 'booking_saga_fsm.v1' && SAGA_STATUSES.join(',') === 'pending,confirmed,compensated', 'schema 词唯一;状态字母表与 pending_writes CHECK 逐字一致');
+assert(COMBOS.length === 12 && new Set(COMBOS).size === 12 && edgeKeys.size === SAGA_EDGES.length && rejectKeys.size === SAGA_REJECTIONS.length, '12 个 (origin,trigger) 组合;边表与拒绝表内部无重复');
+assert(COMBOS.every(k => edgeKeys.has(k) !== rejectKeys.has(k)), '每格恰为一条合法边或一条结构化拒绝(全函数,无空洞无第三态)');
+assert(SAGA_EDGES.every(e => SAGA_STATUSES.includes(e.to) && e.event === SAGA_TRIGGER_EVENT[e.trigger] && e.guard.length > 0), '合法边:终点在字母表内、事件 kind 与触发器一一对应、守卫语义齐全');
+const allConsistent = ORIGINS.every(from => TRIGGERS.every(trigger => {
+    const v = resolveSagaTrigger(from, trigger);
+    const edge = SAGA_EDGES.find(e => e.from === from && e.trigger === trigger);
+    if (edge)
+        return v.ok && v.to === edge.to && v.event === edge.event;
+    return !v.ok && v.reason === SAGA_REJECTIONS.find(x => x.from === from && x.trigger === trigger).reason;
+}));
+assert(allConsistent, 'resolveSagaTrigger 十二格与边表/拒绝表全一致(解析器无平行第二逻辑)');
+// ---- 2:主路径、吸收态与审计链校验(纯函数) --------------------------------------
+{
+    const vProp = resolveSagaTrigger('none', 'propose');
+    const vConf = resolveSagaTrigger('pending', 'confirm');
+    const vComp = resolveSagaTrigger('confirmed', 'compensate');
+    assert(vProp.ok && vProp.to === 'pending' && vConf.ok && vConf.to === 'confirmed' && vComp.ok && vComp.to === 'compensated', '主路径 ∅→pending→confirmed→compensated 连通(L2 登记只不执行 / L3 确认携 receipt / saga 补偿)');
+    const vDouble = resolveSagaTrigger('confirmed', 'confirm');
+    assert(!vDouble.ok && vDouble.reason === 'already-confirmed', '二次确认结构化拒绝(already-confirmed)');
+    const vIdem = resolveSagaTrigger('compensated', 'propose');
+    const vRevive = resolveSagaTrigger('compensated', 'confirm');
+    const vReComp = resolveSagaTrigger('compensated', 'compensate');
+    assert(!vIdem.ok && vIdem.reason === 'idem-exists' && !vRevive.ok && vRevive.reason === 'absorbed-compensated' && !vReComp.ok && vReComp.reason === 'already-compensated', 'compensated 吸收态:propose=幂等存在,confirm/compensate 拒绝(无复活路径)');
+    assert(sagaLegalPaths().length === 4, '合法路径恰四条(主路径及其真前缀)');
+    const legalClean = sagaLegalPaths().every(path => {
+        const events = path.map((trigger, i) => ({ seq: i + 1, kind: SAGA_TRIGGER_EVENT[trigger], receipt: trigger === 'confirm' ? 'PNR-X' : undefined }));
+        return sagaTraceViolations(events).length === 0;
+    });
+    assert(legalClean, '四条合法路径的审计链均零违例');
+    const flagOf = (events) => sagaTraceViolations(events)[0];
+    assert(flagOf([{ kind: 'write.confirmed', receipt: 'PNR-A' }]) !== undefined, '缺 pending 起点的 confirm 被审计链抓出');
+    assert(flagOf([{ kind: 'write.pending' }, { kind: 'write.confirmed', receipt: 'PNR-A' }, { kind: 'write.confirmed', receipt: 'PNR-B' }]) !== undefined, '双确认被审计链抓出(每键至多确认一次)');
+    assert(flagOf([{ kind: 'write.pending' }, { kind: 'write.compensated' }, { kind: 'write.confirmed', receipt: 'X' }]) !== undefined, 'compensated 之后不得再有 saga 事件(吸收态)');
+    assert((flagOf([{ kind: 'write.pending' }, { kind: 'write.confirmed' }]) ?? '').includes('receipt'), 'write.confirmed 空 receipt 被抓(L3 必携外部回执)');
+}
+// ---- 3:物理对账(状态机 = 账本 saga 基座的词汇层,分叉即红) ---------------------
+const root = mkdtempSync(join(tmpdir(), 'gotry-booking-saga-'));
+try {
+    const ledger = ensureLedger(root);
+    const sagaEventsOf = (l, key) => {
+        const rows = l.db.prepare(`SELECT seq, kind, payload FROM events WHERE tenant_id = ? AND subject_id = ? AND kind IN ('write.pending','write.confirmed','write.compensated') ORDER BY seq`).all(l.tenant, key);
+        return rows.map(r => ({ seq: r.seq, kind: r.kind, receipt: parseReceipt(r.payload) }));
+    };
+    const K1 = 'booking:K1';
+    const proposed = ledger.requestPendingWrite({ idemKey: K1, seam: 'flight-order-confirm', payload: { flight: 'MU123' } });
+    assert(proposed.created === true && proposed.status === 'pending' && resolveSagaTrigger('none', 'propose').to === 'pending', '物理提议 ∅→pending 与状态机同归宿(L2 只登记不执行)');
+    const dup = ledger.requestPendingWrite({ idemKey: K1, seam: 'flight-order-confirm', payload: { flight: 'MU123' } });
+    assert(dup.created === false && dup.status === 'pending' && resolveSagaTrigger('pending', 'propose').reason === 'idem-exists', '同幂等键重复提议:账本 no-op = 状态机 idem-exists');
+    const confirmed = ledger.confirmPendingWrite(K1, 'PNR-A');
+    assert(confirmed.ok === true && confirmed.status === 'confirmed' && resolveSagaTrigger('pending', 'confirm').to === 'confirmed', 'L3 具名确认 pending→confirmed(携 receipt)');
+    const reConfirmed = ledger.confirmPendingWrite(K1, 'PNR-SHOULD-IGNORE');
+    assert(reConfirmed.ok === false && (ledger.listPendingWrites().find(w => w.idem_key === K1)?.receipt ?? null) === 'PNR-A' && resolveSagaTrigger('confirmed', 'confirm').reason === 'already-confirmed', '二次确认被账本守卫拒绝且 receipt 不可变(仍为 PNR-A)');
+    const compensated = ledger.compensatePendingWrite(K1, '用户改签退款');
+    assert(compensated.ok === true && ledger.listPendingWrites().find(w => w.idem_key === K1)?.status === 'compensated', '已确认副作用可 saga 补偿(pending|confirmed → compensated)');
+    const afterConfirm = ledger.confirmPendingWrite(K1, 'PNR-POST');
+    const afterCompensate = ledger.compensatePendingWrite(K1, '重复补偿');
+    const afterPropose = ledger.requestPendingWrite({ idemKey: K1, seam: 'flight-order-confirm', payload: {} });
+    assert(afterConfirm.ok === false && afterCompensate.ok === false && afterPropose.created === false, '吸收态:compensated 后 confirm/compensate/propose 全拒,零复活');
+    const audit = sagaEventsOf(ledger, K1);
+    assert(audit.map(e => e.kind).join(',') === 'write.pending,write.confirmed,write.compensated', '审计事件链与边表路径同构(被拒调用零事件)');
+    assert(sagaTraceViolations(audit).length === 0, '真实账本审计链过词汇层校验零违例');
+    const K3 = 'booking:K3';
+    ledger.requestPendingWrite({ idemKey: K3, seam: 'hotel-order-confirm', payload: {} });
+    const emptyReceipt = ledger.confirmPendingWrite(K3, '');
+    assert(emptyReceipt.ok === true && sagaTraceViolations(sagaEventsOf(ledger, K3)).some(v => v.includes('receipt')), '已知边界:账本物理层暂不挡空 receipt,词汇层审计链抓出(物理 CHECK 随 M5 拍板入 schema)');
+    const other = ensureLedger(root, 'tenant-b');
+    const crossProp = other.requestPendingWrite({ idemKey: K1, seam: 'flight-order-confirm', payload: {} });
+    assert(crossProp.created === true, '同 idem_key 跨租户互不可见:tenant-b 可建自己的 K1(tenant_id 一等字段,ADR-16)');
+    const sagaRows = other.db.prepare('SELECT tenant_id, idem_key, status FROM pending_writes WHERE idem_key = ? ORDER BY tenant_id').all(K1);
+    assert(sagaRows.map(r => `${r.tenant_id}:${r.status}`).join(',') === 'local:compensated,tenant-b:pending', '同 saga idem_key 的 pending_writes 行按 tenant 绑定,tenant-b 不覆盖 local');
+    assert(sagaEventsOf(other, K1).map(e => e.kind).join(',') === 'write.pending' && other.readEvents('write.pending', 10).every(e => e.tenant_id === 'tenant-b'), 'tenant-b saga 审计事件 owner 不回落 local,readEvents 不串租户');
+    const LOCAL_ONLY = 'booking:local-only';
+    ledger.requestPendingWrite({ idemKey: LOCAL_ONLY, seam: 'flight-order-confirm', payload: {} });
+    const crossMissing = other.confirmPendingWrite(LOCAL_ONLY, 'PNR-CROSS');
+    assert(crossMissing.ok === false && crossMissing.status === 'missing', 'tenant-b 看不到 local 的 saga 键(拒绝 missing)');
+}
+finally {
+    rmSync(root, { recursive: true, force: true });
+}
+console.log(`\nBOOKING SAGA TESTS: ${pass} ok, ${fail} fail`);
+if (fail > 0)
+    process.exit(1);