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

package/dist/src/bookable-facts.js

@@ -0,0 +1,533 @@
+/**
+ * 可下单事实模型 gotry_bookable_fact.v1(issue #46,ADR-19)。
+ *
+ * 问题(2026-08-29 实测会话):exact-date 工具全部 miss 后,LLM 用航线页当日班期
+ * (2026 快照)填充 2027 行程,航班号/时刻/机场/价格以「✓/推荐」确定性语气手写进
+ * 产物——「错误但看起来已验证」比 unknown 更危险。
+ *
+ * 本层职责(纯函数,零 I/O——持久化见 capabilities/fact-log.ts):
+ *   1. 结构化事实 schema:route/exact local date/时刻/航班号/营销与实际承运(分开)/
+ *      机场/直飞或中转/价格/币种/source/query_id/fetched_at/as_of/confidence/bookability;
+ *   2. 证据分层永不合并:live_inventory(exact-date 命中)/ route_exists(只验证航线)/
+ *      historical_schedule(旧航季)/ benchmark_price(历史促销价)——miss 落「负事实」,
+ *      exact-date 无库存 ≠ 可用历史填充;
+ *   3. 判定原语:航班 claim 可述性(fail closed)/ 同日衔接硬约束 / 行程统计不变量
+ *      (酒店夜+机上夜/O&D 段数/flight legs/预算自洽)/ 回头路检测;
+ *   4. 确定性渲染:航班行/政策行只从结构化对象生成,政策恒带 as_of + 复核日期,
+ *      分票永不称「联程」(protected_connection=true 才允许)。
+ *
+ * 渲染闸(从 markdown 反向核验)在 artifact-gate.ts。
+ */
+import { createHash } from 'node:crypto';
+import { hasRecognizedAvailableSeat, validateTrainQueryResponseUrl } from '../capabilities/session/adapters/rail-12306.js';
+export const BOOKABLE_FACT_SCHEMA = 'gotry_bookable_fact.v1';
+// ---------------------------------------------------------------------------
+// id 与查询词(可重放:query_id 即重放凭证)
+// ---------------------------------------------------------------------------
+function sha16(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+export function makeQueryId(source, kind, origin, destination, date) {
+    return `${source}:${kind}:${origin}-${destination}:${date}`;
+}
+export function makeFactId(parts) {
+    return sha16(parts.map(p => p ?? '').join('|'));
+}
+function iataOf(alias, city) {
+    return alias?.[city] ?? city;
+}
+/** 12306 exact-date fact freshness rule: capture must be non-future and <=15 minutes old. */
+export const TRAIN_FACT_FRESHNESS_RULE = 'captured_at_non_future_and_max_age_15m';
+export const TRAIN_FACT_MAX_AGE_MS = 15 * 60 * 1000;
+const YMD = /^\d{4}-\d{2}-\d{2}$/;
+function hmOf(dateTime) {
+    const m = dateTime?.match(/T?(\d{2}:\d{2})/);
+    return m?.[1];
+}
+function dateOf(dateTime, fallback) {
+    const m = dateTime?.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m?.[1] ?? fallback;
+}
+/** exact-date miss → 负事实(route+date 级「当前不可售/无结果」记录,fail-closed 的另一半) */
+export function negativeFact(queryId, kind, origin, destination, date, source, fetchedAt, alias) {
+    return {
+        schema: BOOKABLE_FACT_SCHEMA,
+        fact_id: makeFactId(['neg', kind, iataOf(alias, origin), iataOf(alias, destination), date, queryId]),
+        kind,
+        route: { origin: iataOf(alias, origin), destination: iataOf(alias, destination) },
+        date,
+        flight_no: '',
+        tier: 'live_inventory',
+        bookability: 'unavailable_exact_date',
+        source,
+        query_id: queryId,
+        fetched_at: fetchedAt,
+        as_of: fetchedAt.slice(0, 10),
+    };
+}
+/** flyai hit/miss → 事实列(error 不落事实——无结论不是证据) */
+export function factsFromFlyai(q, r, fetchedAt, alias) {
+    const source = 'flyai';
+    const queryId = makeQueryId(source, q.kind, q.origin, q.destination, q.date);
+    const origin = iataOf(alias, q.origin);
+    const destination = iataOf(alias, q.destination);
+    if (r.verdict !== 'hit' && r.verdict !== 'miss')
+        return [];
+    if (r.verdict === 'miss')
+        return [negativeFact(queryId, q.kind, q.origin, q.destination, q.date, source, fetchedAt, alias)];
+    const facts = [];
+    for (const o of r.options ?? []) {
+        if (!o.no || !o.depDateTime)
+            continue;
+        const numeric = typeof o.price === 'number' && Number.isFinite(o.price) && o.price > 0 ? o.price : undefined;
+        facts.push({
+            schema: BOOKABLE_FACT_SCHEMA,
+            fact_id: makeFactId([q.kind, origin, destination, q.date, o.no, queryId]),
+            kind: q.kind,
+            route: { origin, destination, origin_airport: o.depStation, dest_airport: o.arrStation },
+            date: dateOf(o.depDateTime, q.date),
+            flight_no: o.no,
+            marketing_carrier: o.name || undefined,
+            operating_carrier: undefined, // flyai 上游只给营销承运;实际承运未知 ≠ 相同,留空不猜
+            dep_local: hmOf(o.depDateTime),
+            arr_local: hmOf(o.arrDateTime),
+            nonstop: o.nonstop !== false,
+            price: numeric,
+            currency: numeric !== undefined ? 'CNY' : undefined,
+            tier: 'live_inventory',
+            bookability: 'bookable_exact_date',
+            source,
+            query_id: queryId,
+            fetched_at: fetchedAt,
+            as_of: fetchedAt.slice(0, 10),
+        });
+    }
+    // hit 但解析后零有效条目 = 与 miss 同语义(无可用事实,落负事实)
+    return facts.length > 0 ? facts : [negativeFact(queryId, q.kind, q.origin, q.destination, q.date, source, fetchedAt, alias)];
+}
+/** 会话检索 hit → 事实列(用户本人登录态来源,与 flyai 并列独立 source) */
+export function factsFromSession(q, r, fetchedAt, alias) {
+    const source = 'session:ctrip-flight';
+    const queryId = makeQueryId(source, 'flight', q.origin, q.destination, q.date);
+    const origin = iataOf(alias, q.origin);
+    const destination = iataOf(alias, q.destination);
+    if (r.verdict !== 'hit') {
+        // miss/cooldown/challenged/needs-login:仅「正常返回 0 条」是负事实;通道不可用不落事实
+        return r.verdict === 'miss' ? [negativeFact(queryId, 'flight', q.origin, q.destination, q.date, source, fetchedAt, alias)] : [];
+    }
+    const facts = [];
+    for (const o of r.options ?? []) {
+        if (!o.flightNo || !o.depDateTime)
+            continue;
+        const numeric = typeof o.price === 'number' && Number.isFinite(o.price) && o.price > 0 ? o.price : undefined;
+        facts.push({
+            schema: BOOKABLE_FACT_SCHEMA,
+            fact_id: makeFactId(['flight', origin, destination, q.date, o.flightNo, queryId]),
+            kind: 'flight',
+            route: { origin, destination, origin_airport: o.depAirport, dest_airport: o.arrAirport },
+            date: dateOf(o.depDateTime, q.date),
+            flight_no: o.flightNo,
+            marketing_carrier: o.airline || undefined,
+            operating_carrier: undefined,
+            dep_local: hmOf(o.depDateTime),
+            arr_local: hmOf(o.arrDateTime),
+            nonstop: true,
+            price: numeric,
+            currency: numeric !== undefined ? 'CNY' : undefined,
+            tier: 'live_inventory',
+            bookability: 'bookable_exact_date',
+            source,
+            query_id: queryId,
+            fetched_at: fetchedAt,
+            as_of: fetchedAt.slice(0, 10),
+        });
+    }
+    return facts;
+}
+function trainCollectionIsFresh(q, r, now) {
+    const c = r.collection;
+    if (!c || !c.batchId.trim() || !c.queryId.trim() || c.queryId !== `session:12306-train:${c.batchId}`)
+        return false;
+    if (c.requested.from !== q.from || c.requested.to !== q.to || c.requested.date !== q.date)
+        return false;
+    if (!c.request || !c.response
+        || c.request.date !== c.requested.date
+        || c.response.fromStationTelecode !== c.request.fromStationTelecode
+        || c.response.toStationTelecode !== c.request.toStationTelecode
+        || c.response.date !== c.request.date
+        || !validateTrainQueryResponseUrl(c.response.url, c.request).ok)
+        return false;
+    const fetchedMs = Date.parse(c.fetchedAt);
+    const nowMs = now.getTime();
+    if (!Number.isFinite(fetchedMs) || !Number.isFinite(nowMs))
+        return false;
+    return fetchedMs <= nowMs && nowMs - fetchedMs <= TRAIN_FACT_MAX_AGE_MS;
+}
+/** 12306 typed outcome → exact-date train facts.
+ * The converter never invents collection identity or timestamps: both must come
+ * from the session invocation binding. Only recognized-empty can create a
+ * negative fact. A recognized row needs Y plus a closed-set available seat token.
+ */
+export function factsFromSessionTrain(q, r, now = new Date()) {
+    if (!trainCollectionIsFresh(q, r, now))
+        return [];
+    const c = r.collection;
+    const source = 'session:12306-train';
+    const fetchedAt = c.fetchedAt;
+    if (r.outcome.kind === 'recognized-empty') {
+        return [negativeFact(c.queryId, 'train', q.from, q.to, q.date, source, fetchedAt)];
+    }
+    if (r.outcome.kind !== 'recognized-nonempty')
+        return [];
+    const facts = [];
+    for (const o of r.outcome.trains ?? []) {
+        if (o.canWebBuy !== 'Y' || !hasRecognizedAvailableSeat(o))
+            continue;
+        facts.push({
+            schema: BOOKABLE_FACT_SCHEMA,
+            fact_id: makeFactId(['train', q.from, q.to, q.date, o.trainCode, c.queryId]),
+            kind: 'train',
+            route: { origin: q.from, destination: q.to },
+            date: q.date,
+            flight_no: o.trainCode,
+            dep_local: o.depTime,
+            arr_local: o.arrTime,
+            tier: 'live_inventory',
+            bookability: 'bookable_exact_date',
+            source,
+            query_id: c.queryId,
+            fetched_at: fetchedAt,
+            as_of: fetchedAt.slice(0, 10),
+        });
+    }
+    return facts;
+}
+// ---------------------------------------------------------------------------
+// 注册表(纯函数视图;持久化在 capabilities/fact-log.ts)
+// ---------------------------------------------------------------------------
+/** 同 fact_id 去重,保留 fetched_at 最新(重查覆盖旧快照,历史不丢——append-only 由持久层保证) */
+export function dedupeFacts(facts) {
+    const byId = new Map();
+    for (const f of facts) {
+        const prev = byId.get(f.fact_id);
+        if (!prev || prev.fetched_at <= f.fetched_at)
+            byId.set(f.fact_id, f);
+    }
+    return [...byId.values()].sort((a, b) => a.fetched_at.localeCompare(b.fetched_at) || a.fact_id.localeCompare(b.fact_id));
+}
+/** route+date 的最新查询结论(同日多次查询:最新一次为准,避免「昨天 miss 今天 hit」陈旧否定) */
+export function latestFactsForRouteDate(facts, origin, destination, date, kind) {
+    const hits = facts.filter((f) => (f.kind === 'flight' || f.kind === 'train')
+        && (!kind || f.kind === kind)
+        && f.route.origin === origin && f.route.destination === destination && f.date === date);
+    const latestQueryTs = new Map();
+    for (const f of hits) {
+        const prev = latestQueryTs.get(f.query_id);
+        if (!prev || prev < f.fetched_at)
+            latestQueryTs.set(f.query_id, f.fetched_at);
+    }
+    const latestTs = [...latestQueryTs.values()].sort().pop();
+    if (!latestTs)
+        return [];
+    return hits.filter(f => f.fetched_at === latestTs);
+}
+/**
+ * 航班 claim 裁决(flight-only):注册表只接受 `kind:'flight'` 的同号事实
+ * ——train 事实走 `railClaimVerdict` 独立裁决,不得混入航班 not_in_source
+ * 路径(issue #299)。中文高铁/动车/城际/直达代码(G/D/C/Z + 3–4 位)在
+ * 闸侧 `extractClaims` 已分流到 `trains` claim,本函数无需再做扩展。
+ */
+export function flightClaimVerdict(facts, claim) {
+    const no = claim.flight_no.toUpperCase().replace(/\s+/g, '');
+    const sameNo = facts.filter((f) => f.kind === 'flight' && f.flight_no.toUpperCase() === no && f.bookability === 'bookable_exact_date');
+    const routeMatched = sameNo.filter(f => (!claim.origin || f.route.origin === claim.origin || f.route.origin_airport === claim.origin)
+        && (!claim.destination || f.route.destination === claim.destination || f.route.dest_airport === claim.destination)
+        && (!claim.date || f.date === claim.date));
+    if (routeMatched.length > 0)
+        return { verdict: 'traceable', fact: routeMatched[0], reason: `回溯 ${routeMatched[0].query_id}` };
+    // 无同号可下单事实:该 route+date 是否查过?
+    if (claim.origin && claim.destination && claim.date) {
+        const scoped = latestFactsForRouteDate(facts, claim.origin, claim.destination, claim.date, 'flight');
+        if (scoped.length > 0) {
+            return {
+                verdict: 'not_in_source',
+                reason: scoped.some(f => f.bookability === 'unavailable_exact_date')
+                    ? `${claim.origin}→${claim.destination} ${claim.date} exact-date 源返回 0 条(${scoped[0].query_id})——不得用历史班期/相邻日期填充`
+                    : `${claim.origin}→${claim.destination} ${claim.date} exact-date 源在架 ${scoped.filter(f => f.bookability === 'bookable_exact_date').map(f => f.flight_no).join('/')}——无 ${no}`,
+            };
+        }
+        return { verdict: 'route_unqueried', reason: `${claim.origin}→${claim.destination} ${claim.date} 从未经 exact-date 源核验` };
+    }
+    return { verdict: 'route_unqueried', reason: `航班 ${no} 无可回溯的 exact-date 事实(缺 route/date 上下文)` };
+}
+const TRAIN_FACT_SOURCES = new Set(['flyai', 'session:12306-train']);
+function isStructuredTrainFact(f) {
+    return f.kind === 'train'
+        && f.schema === BOOKABLE_FACT_SCHEMA
+        && TRAIN_FACT_SOURCES.has(f.source)
+        && f.query_id.trim().length > 0
+        && f.tier === 'live_inventory';
+}
+export function railClaimVerdict(facts, claim) {
+    const no = claim.flight_no.toUpperCase().replace(/\s+/g, '');
+    if (!claim.origin || !claim.destination || !claim.date) {
+        return { verdict: 'rail_claim_unverified', reason: `车次 ${no} 无可回溯的 exact-date 事实(缺完整 route/date 上下文)` };
+    }
+    // 先按 train kind 选择该 route+date 的最新查询批次,再在该批次匹配车次。
+    // 这样旧 hit 不会越过更新的 miss/unavailable,flight 批次也不能遮蔽 train 批次。
+    const scoped = latestFactsForRouteDate(facts, claim.origin, claim.destination, claim.date, 'train')
+        .filter(isStructuredTrainFact);
+    const sameNo = scoped.filter(f => f.flight_no.toUpperCase() === no
+        && f.bookability === 'bookable_exact_date');
+    if (sameNo.length > 0)
+        return { verdict: 'traceable', fact: sameNo[0], reason: `回溯 ${sameNo[0].query_id}` };
+    if (scoped.length > 0) {
+        return {
+            verdict: 'not_in_source',
+            reason: scoped.some(f => f.bookability === 'unavailable_exact_date')
+                ? `${claim.origin}→${claim.destination} ${claim.date} train exact-date 源返回 0 条(${scoped[0].query_id})——不得用历史班期/相邻日期填充`
+                : `${claim.origin}→${claim.destination} ${claim.date} train exact-date 源在架 ${scoped.filter(f => f.bookability === 'bookable_exact_date').map(f => f.flight_no).join('/')}——无 ${no}`,
+        };
+    }
+    return { verdict: 'route_unqueried', reason: `${claim.origin}→${claim.destination} ${claim.date} train 路线从未经 exact-date 源核验` };
+}
+function hmToMin(hm) {
+    const [h, m] = hm.split(':').map(Number);
+    return (h ?? 0) * 60 + (m ?? 0);
+}
+function minToHm(min) {
+    return `${String(Math.floor(min / 60)).padStart(2, '0')}:${String(min % 60).padStart(2, '0')}`;
+}
+/**
+ * 「上午办事 + 当天下午直飞」类核心衔接判定:
+ * 最早起飞 = errand_end + 门到机场 + 值机截止;exact-date 在架直飞逐班过闸。
+ * 在架为空的失败语义与「有班但接不上」分开陈述(前者是库存问题,后者是约束问题)。
+ */
+export function checkSameDayDeparture(facts, q, c) {
+    const earliest = hmToMin(c.errand_end_local) + c.airport_transit_min + c.checkin_deadline_min;
+    const scoped = latestFactsForRouteDate(facts, q.origin, q.destination, q.date, 'flight');
+    const nonstopBookable = scoped.filter(f => f.bookability === 'bookable_exact_date' && f.nonstop !== false);
+    const feasible = [];
+    const excluded = [];
+    for (const f of nonstopBookable) {
+        const dep = f.dep_local ? hmToMin(f.dep_local) : null;
+        if (dep === null) {
+            excluded.push({ flight_no: f.flight_no, reason: '缺起飞时刻,不参与衔接判定' });
+        }
+        else if (dep >= earliest) {
+            feasible.push(f);
+        }
+        else {
+            excluded.push({ flight_no: f.flight_no, reason: `${f.dep_local} 起飞早于最早可接时刻 ${minToHm(earliest)}(${c.errand_end_local} 结束事务 + ${c.airport_transit_min}m 到机场 + ${c.checkin_deadline_min}m 值机)` });
+        }
+    }
+    const ok = feasible.length > 0;
+    const suggestions = [];
+    if (!ok) {
+        const inStock = nonstopBookable.map(f => `${f.flight_no} ${f.dep_local ?? '?'}`).join('、');
+        suggestions.push(`增加 1 个${q.origin}住宿夜:改乘次日早班${inStock ? `(当日在架:${inStock})` : ''}`);
+        suggestions.push('或提前一天完成地面事务/提前一天出发,把同日衔接改为隔夜衔接');
+    }
+    return { feasible: ok, earliest_departure_local: minToHm(earliest), feasible_flights: feasible, excluded, suggestions };
+}
+function daysBetween(a, b) {
+    return Math.round((Date.parse(`${b}T00:00:00Z`) - Date.parse(`${a}T00:00:00Z`)) / 86_400_000);
+}
+export function itineraryInvariants(it) {
+    const violations = [];
+    const totalNights = daysBetween(it.trip_start, it.trip_end);
+    let hotelNights = 0;
+    for (const s of it.stays) {
+        const n = daysBetween(s.check_in, s.check_out);
+        if (n <= 0)
+            violations.push({ kind: 'date_order', detail: `${s.place} 住宿 ${s.check_in}→${s.check_out} 晚数 ≤0` });
+        else
+            hotelNights += n;
+    }
+    if (hotelNights + it.onboard_nights !== totalNights) {
+        violations.push({
+            kind: 'nights_inconsistent',
+            detail: `酒店夜 ${hotelNights} + 机上夜 ${it.onboard_nights} = ${hotelNights + it.onboard_nights} ≠ 行程总夜数 ${totalNights}(${it.trip_start}→${it.trip_end})——夜数口径必须由结构化住宿反算,不许自然语言估算`,
+        });
+    }
+    for (const seg of it.od_segments) {
+        if (seg.mode === 'flight' && seg.legs < 1) {
+            violations.push({ kind: 'legs_inconsistent', detail: `${seg.from}→${seg.to}(${seg.date})flight O&D 段 legs=${seg.legs}——每段至少 1 leg` });
+        }
+        if (seg.date < it.trip_start || seg.date > it.trip_end) {
+            violations.push({ kind: 'date_order', detail: `${seg.from}→${seg.to} 日期 ${seg.date} 落在行程窗 ${it.trip_start}→${it.trip_end} 之外` });
+        }
+    }
+    const minSum = it.budget_items.reduce((acc, b) => acc + b.min_cny, 0);
+    if (it.claimed_floor_cny !== undefined && it.claimed_floor_cny < minSum) {
+        violations.push({
+            kind: 'budget_floor_inconsistent',
+            detail: `预算分项最低合计 ¥${minSum.toLocaleString()} > 产物声称可压到 ¥${it.claimed_floor_cny.toLocaleString()}——下限话术不得低于分项最低合计`,
+        });
+    }
+    return violations;
+}
+export function detectBacktrack(stops, nonstopEdges) {
+    const findings = [];
+    for (let i = 0; i + 2 < stops.length; i++) {
+        const a = stops[i], b = stops[i + 1], c = stops[i + 2];
+        if (a !== c)
+            continue;
+        // A→B→A 回头;若 B→D(下一站)有直飞边,建议「去程后直接 B→D」
+        const d = stops[i + 3];
+        const suggestion = d && nonstopEdges.has(`${b}-${d}`)
+            ? `${b}→${d} 有直飞:改为 ${a}→${b} 后直接 ${b}→${d},消除 ${a}→${b}→${a} 回头路`
+            : undefined;
+        findings.push({ kind: 'backtrack', path: [a, b, c], suggestion });
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// 确定性渲染:航班/政策行只从结构化对象生成(issue #46 期望①:禁止凭记忆抄写)
+// ---------------------------------------------------------------------------
+/** 远期复核默认 gate:出发前 30 天 */
+export function defaultReviewBy(tripDate) {
+    const d = new Date(Date.parse(`${tripDate}T00:00:00Z`) - 30 * 86_400_000);
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * 航班/车次事实行。bookable_exact_date 才允许完整班次行;其余一律 fail-closed 措辞。
+ * train 复用此 canonical renderer 但只输出车次语义,不输出直飞或价格;永不输出无条件 ✓;
+ * 证据链(source/query_id/fetched_at)随行必达。
+ */
+export function renderFlightFact(f) {
+    return renderFlightFactInner(f) + ` <!-- fact:${f.fact_id} -->`;
+}
+function renderFlightFactInner(f) {
+    // 单向生成锚点(D-26):每条事实行内嵌 fact_id,闸侧锚点匹配 = 确定性回溯
+    const anchor = ` <!-- fact:${f.fact_id} -->`;
+    const route = `${f.route.origin}→${f.route.destination}`;
+    const evidence = `[${f.source}@${f.fetched_at} #${f.query_id}]`;
+    if (f.kind === 'train' && f.bookability === 'unavailable_exact_date') {
+        const review = f.review_by ?? defaultReviewBy(f.date);
+        return `- ${route} ${f.date} 车次${f.flight_no ? ` ${f.flight_no}` : ''}:**未确认/当前不可售**——exact-date 源 ${f.source} 于 ${f.fetched_at.slice(0, 10)} 返回 0 条;到 ${review} 复核,不得用历史班期/相邻日期填充 ${evidence}`;
+    }
+    if (f.kind === 'train' && f.bookability !== 'bookable_exact_date') {
+        return `- ${route} ${f.date} 车次${f.flight_no ? ` ${f.flight_no}` : ''}:**未核验**(${f.bookability})——仅作参考,不得作为可下单方案呈现 ${evidence}`;
+    }
+    if (f.bookability === 'unavailable_exact_date') {
+        const review = f.review_by ?? defaultReviewBy(f.date);
+        return `- ${route} ${f.date}:**未确认/当前不可售**——exact-date 源 ${f.source} 于 ${f.fetched_at.slice(0, 10)} 返回 0 条;到 ${review} 复核,不得用历史班期/相邻日期填充 ${evidence}`;
+    }
+    if (f.bookability !== 'bookable_exact_date') {
+        return `- ${route} ${f.date} ${f.flight_no || ''}:**未核验**(${f.bookability})——仅作参考,不得作为可下单方案呈现 ${evidence}`;
+    }
+    if (f.kind === 'train') {
+        const times = f.dep_local && f.arr_local ? ` ${f.dep_local}→${f.arr_local}` : '';
+        return `- ${route} ${f.date} 车次 ${f.flight_no}${times} ${evidence}`;
+    }
+    const carrier = f.operating_carrier && f.operating_carrier !== f.marketing_carrier
+        ? `营销 ${f.marketing_carrier ?? '?'} / 实际承运 ${f.operating_carrier}`
+        : (f.marketing_carrier ?? '');
+    const times = f.dep_local && f.arr_local ? ` ${f.dep_local}→${f.arr_local}` : '';
+    const nonstop = f.nonstop === false ? '(中转)' : ' 直飞';
+    // 双机场城市防混淆:落点机场码与城市码不同时显式标注(FD 落 DMK / VZ 落 BKK 不互换)
+    const airportNote = f.route.dest_airport && f.route.dest_airport !== f.route.destination
+        ? `(落 ${f.route.dest_airport})`
+        : '';
+    const price = f.price !== undefined ? ` ¥${f.price}` : ' 价待询';
+    const baggage = f.baggage_included === false ? ',不含托运行李' : '';
+    return `- ${route} ${f.date} ${f.flight_no}${carrier ? `(${carrier})` : ''}${times}${nonstop}${airportNote}${price}${baggage} ${evidence}`;
+}
+/**
+ * 联程/分票连接行:只有同票保护(protected_connection=true)才允许称「联程」;
+ * 分票必须显式标红自助转机风险(无行李直挂/误机无保护)。
+ */
+export function renderConnection(legA, legB) {
+    const through = legA.protected_connection === true && legB.protected_connection === true;
+    const head = `${legA.route.origin}→${legA.route.destination} ${legA.flight_no} + ${legB.route.origin}→${legB.route.destination} ${legB.flight_no}`;
+    return through
+        ? `- ${head}:联程(同一票号/行李直挂/误机保护)`
+        : `- ${head}:⚠️ **分票/自助转机**——两段接得上 ≠ 联程;无同一票号、行李需自取重挂、误机无保护,缓冲与风险自担`;
+}
+/**
+ * 政策事实行:恒为「截至 as_of 的现行政策」表述 + 复核 gate,永不用无条件 ✓。
+ * 远期(出发日晚于 as_of)必须附 review_by(默认 D-30)。
+ *
+ * 行尾内嵌 `<!-- fact:<fact_id> -->` 锚点(issue #273,ADR-19 typed-anchor 单向生成):
+ * 产物经渲染原语生成即自带溯源锚,闸侧锚点确定性回溯;手改/伪造锚点 = fact_anchor_unknown。
+ * 与 renderFlightFact / renderHotelFact 同源:启发式 POLICY_WORD 仅覆盖手写/历史产物。
+ */
+export function renderPolicyFact(p, tripStart) {
+    return `${policyCanonicalBody(p, tripStart)} <!-- fact:${p.fact_id} -->`;
+}
+/**
+ * 政策行 canonical body(不含锚点;issue #359,D-26 残余收口):
+ * 闸侧锚点回溯用同一原文,subject/statement/source/fetched_at/query_id 任意一项
+ * 改动 → 行文本不再等于 canonical body → fact_anchor_unknown fail-closed。
+ * 不走宽松 substring/subset 匹配,避免锚点行被改写 subject/statement 后仍 pass。
+ * 复核提醒(review_by 或 tripStart 派生的 defaultReviewBy)是合法的可选段——
+ * `tripStart` 与 renderPolicyFact 同一传入,产物与闸两侧语义一致。
+ */
+export function policyCanonicalBody(p, tripStart) {
+    const review = p.review_by ?? (tripStart ? defaultReviewBy(tripStart) : undefined);
+    const reviewNote = review ? `;远期政策须复核——到 ${review} 再核验一次` : '';
+    return `- ${p.subject}:截至 ${p.as_of} 的现行政策——${p.statement}${reviewNote} [${p.source}@${p.fetched_at} #${p.query_id}]`;
+}
+/** 从结构化行程渲染夜数口径行(机器反算,唯一口径) */
+export function renderNightsLine(it) {
+    const totalNights = daysBetween(it.trip_start, it.trip_end);
+    const hotelNights = it.stays.reduce((acc, s) => acc + Math.max(0, daysBetween(s.check_in, s.check_out)), 0);
+    const flightOd = it.od_segments.filter(s => s.mode === 'flight').length;
+    const flightLegs = it.od_segments.filter(s => s.mode === 'flight').reduce((acc, s) => acc + s.legs, 0);
+    return `共 ${daysBetween(it.trip_start, it.trip_end) + 1} 天 ${totalNights} 晚 = ${hotelNights} 个酒店夜 + ${it.onboard_nights} 个机上夜;航班按 O&D ${flightOd} 段(共 ${flightLegs} 个 flight legs)`;
+}
+// ---------------------------------------------------------------------------
+// 酒店事实(D-26,issue #118):exact-date 酒店检索 hit/miss 落账
+// 纪律:摸底(未定档期)不落账(无 exact-date 语义);needs-setup/error 传输失败永不落负事实
+// ---------------------------------------------------------------------------
+export function factsFromHotel(input) {
+    if (!input.checkIn || !input.checkOut)
+        return [];
+    if (input.verdict !== 'hit' && input.verdict !== 'miss')
+        return [];
+    const queryId = `hotel:${input.source}:${input.destination}:${input.checkIn}_${input.checkOut}`;
+    return [{
+            schema: BOOKABLE_FACT_SCHEMA,
+            kind: 'hotel',
+            fact_id: makeFactId([input.destination, input.checkIn, input.checkOut, queryId]),
+            destination: input.destination,
+            check_in: input.checkIn,
+            check_out: input.checkOut,
+            verdict: input.verdict,
+            bookability: input.verdict === 'hit' ? 'bookable_exact_date' : 'unavailable_exact_date',
+            options_masked: input.options,
+            source: input.source,
+            query_id: queryId,
+            fetched_at: input.fetchedAt,
+            as_of: input.fetchedAt.slice(0, 10),
+            tier: 'live_inventory',
+        }];
+}
+/** 酒店 claim 回溯:同目的地+同档期的 exact-date 事实裁决(无事实=unverified,fail-closed) */
+export function hotelClaimVerdict(facts, claim) {
+    const scoped = facts.filter((f) => f.kind === 'hotel' && f.destination === claim.destination
+        && (!claim.check_in || f.check_in === claim.check_in)
+        && (!claim.check_out || f.check_out === claim.check_out));
+    if (scoped.length === 0) {
+        return {
+            verdict: 'unverified',
+            reason: `酒店 claim(${claim.destination}${claim.check_in ? ` ${claim.check_in}→${claim.check_out ?? '?'}` : ''})未经 exact-date 源核验——先检索再写结论`,
+        };
+    }
+    const hit = scoped.find(f => f.bookability === 'bookable_exact_date');
+    if (hit)
+        return { verdict: 'traceable', fact: hit, reason: 'exact-date 命中' };
+    const latest = scoped[scoped.length - 1];
+    return { verdict: 'not_in_source', fact: latest, reason: `该档期 exact-date 源正常返回 0 条(${latest.fetched_at})——不得写有房/可订` };
+}
+// ---------------------------------------------------------------------------
+// 渲染原语(单向生成,issue #118):事实 → 行,锚点内嵌 fact_id;
+// 产物经原语渲染即自带溯源锚,闸侧锚点匹配 = 确定性回溯,不靠行文猜测
+// ---------------------------------------------------------------------------
+export function renderHotelFact(f) {
+    if (f.verdict !== 'hit') {
+        return `- ${f.destination} ${f.check_in}→${f.check_out}:exact-date 源 0 条在架(不可订) <!-- fact:${f.fact_id} -->`;
+    }
+    return `- ${f.destination} ${f.check_in}→${f.check_out}:住宿已核验(在架 ${f.options_masked} 家;价格上游打码,真实价以落地页为准) <!-- fact:${f.fact_id} -->`;
+}

package/dist/src/booking-saga.js

@@ -0,0 +1,97 @@
+/**
+ * 预订 saga 状态机(booking_saga_fsm.v1)——issue #17 采纳三点的具名化落点。
+ *
+ * 立场(docs/design/booking-saga-fsm.md / ADR-17):不引入编排框架;预订 saga 的状态字母表与边表
+ * 就是账本 pending_writes(status CHECK:pending|confirmed|compensated)的显式化。
+ * 本模块是纯函数词汇层,零依赖、零行为、不接线任何 seam——M5 拍板 WriteGate 生产化时
+ * 以此为唯一状态推进词汇(具名化 = 状态与边不再散落在 SQL 字符串里)。
+ *
+ * 物理对账目标(state-ledger.ts,TS-4 基座):
+ *  - propose  = requestPendingWrite(∅ → pending,L2 只登记不执行;idem_key UNIQUE,重复提议 no-op)
+ *  - confirm  = confirmPendingWrite(pending → confirmed,L3 具名 seam 确认,携 receipt;无 receipt 则视为缺省空串)
+ *  - compensate = compensatePendingWrite(pending|confirmed → compensated,吸收态,无出边)
+ *  - 审计事件 kind:write.pending / write.confirmed / write.compensated
+ */
+export const BOOKING_SAGA_SCHEMA = 'booking_saga_fsm.v1';
+/** 状态字母表(与 pending_writes.status CHECK 约束逐字一致) */
+export const SAGA_STATUSES = ['pending', 'confirmed', 'compensated'];
+/**
+ * 边表(预订流程 FSM 的全部合法转移):
+ *  ∅ --propose--> pending --confirm--> confirmed
+ *        │             │
+ *        └---(任何状态) --compensate--> compensated(吸收态,无出边)
+ */
+export const SAGA_EDGES = [
+    { from: 'none', trigger: 'propose', to: 'pending', event: 'write.pending', guard: 'L2 只登记不执行;idem_key UNIQUE(重复提议 no-op)' },
+    { from: 'pending', trigger: 'confirm', to: 'confirmed', event: 'write.confirmed', guard: 'L3 具名 seam 确认,必携 receipt;已确认不可再确认' },
+    { from: 'pending', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '外部写未发生,取消即终态(无补偿动作)' },
+    { from: 'confirmed', trigger: 'compensate', to: 'compensated', event: 'write.compensated', guard: '已发生副作用的 saga 补偿(退改),receipt 保留(COALESCE)' },
+];
+/** 非边组合的拒绝理由(结构化,拒绝即不动——与账本 changes=0 同义) */
+export const SAGA_REJECTIONS = [
+    { from: 'none', trigger: 'confirm', reason: 'missing-subject' },
+    { from: 'none', trigger: 'compensate', reason: 'missing-subject' },
+    { from: 'pending', trigger: 'propose', reason: 'idem-exists' },
+    { from: 'confirmed', trigger: 'propose', reason: 'idem-exists' },
+    { from: 'confirmed', trigger: 'confirm', reason: 'already-confirmed' },
+    { from: 'compensated', trigger: 'propose', reason: 'idem-exists' },
+    { from: 'compensated', trigger: 'confirm', reason: 'absorbed-compensated' },
+    { from: 'compensated', trigger: 'compensate', reason: 'already-compensated' },
+];
+/** 触发解析:唯一归宿或结构化拒绝(预订 seam 的状态推进只许走这张表的边) */
+export function resolveSagaTrigger(origin, trigger) {
+    const edge = SAGA_EDGES.find(e => e.from === origin && e.trigger === trigger);
+    if (edge)
+        return { ok: true, from: origin, trigger, to: edge.to, event: edge.event, guard: edge.guard, reason: null };
+    const rejection = SAGA_REJECTIONS.find(e => e.from === origin && e.trigger === trigger);
+    return { ok: false, from: origin, trigger, to: null, event: null, guard: null, reason: rejection.reason };
+}
+/** 触发器 → 账本事件 kind 的唯一映射(写入侧命名不再各处硬编码) */
+export const SAGA_TRIGGER_EVENT = {
+    propose: 'write.pending',
+    confirm: 'write.confirmed',
+    compensate: 'write.compensated',
+};
+/** 账本事件 kind → 触发器(读取/审计侧);非 saga 事件返回 null */
+export function triggerOfEventKind(kind) {
+    if (kind === 'write.pending')
+        return 'propose';
+    if (kind === 'write.confirmed')
+        return 'confirm';
+    if (kind === 'write.compensated')
+        return 'compensate';
+    return null;
+}
+/**
+ * 审计链校验(单 idem_key 的 write.* 事件序列):必须恰好走出边表的一条合法路径。
+ *  - 链以 write.pending 开头;
+ *  - confirm/compensate 至多各一次;
+ *  - compensated 之后不允许任何 saga 事件(吸收态);
+ *  - write.confirmed 的 receipt 为空(缺省/空串)即违例——L3 具名确认必携外部回执;
+ *  - 非 write.* 事件(其他域审计)穿插不计。
+ * 返回违例清单(空数组 = 链合法)。
+ */
+export function sagaTraceViolations(events) {
+    const violations = [];
+    let stage = 'none';
+    for (const ev of events) {
+        const trigger = triggerOfEventKind(ev.kind);
+        if (!trigger)
+            continue;
+        const verdict = resolveSagaTrigger(stage, trigger);
+        const at = `seq=${ev.seq ?? '?'} ${ev.kind}`;
+        if (!verdict.ok) {
+            violations.push(`${at}: 非法(${stage} --${trigger}--> 拒绝 ${verdict.reason})`);
+            continue;
+        }
+        stage = verdict.to;
+        if (trigger === 'confirm' && (ev.receipt === undefined || ev.receipt === null || ev.receipt === '')) {
+            violations.push(`${at}: receipt 为空(L3 具名确认必携外部回执)`);
+        }
+    }
+    return violations;
+}
+/** 完整合法路径集合(文档/测试共用):∅→pending→confirmed→compensated 与其前缀 */
+export function sagaLegalPaths() {
+    return [['propose'], ['propose', 'compensate'], ['propose', 'confirm'], ['propose', 'confirm', 'compensate']];
+}