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

package/dist/capabilities/sponsor-plugin.js

@@ -0,0 +1,341 @@
+/**
+ * sponsor 插件契约面(issue #235,M6 备产;B2B principal/sponsor 插件化与同内核端到端复用证明)。
+ *
+ * ⚠ 非运行时激活:本模块是纯函数契约层——不 spawn 子进程、不发起网络请求、不读取任何凭据、
+ * 不接真实供应商/交易调用;运行激活默认关闭(SPONSOR_RUNTIME_ACTIVATION_DEFAULT=false,
+ * 未来真实运行时接线必须挂显式 opt-in 门,形态同 #318 GOTRY_HBCLI_LIVE,且在 #137 M6 Entry
+ * 之后)。一切行为由 fixture 合成数据证明(sponsor-reuse-tests,run-all §61)。
+ *
+ * 定位(milestones/m6-b2b-reuse-walkthrough.md,P6 draft;issue #137 总控):
+ *   - 三主体分离:traveler principal(动机主体)/sponsor(商业与库存主体)/BFF principal
+ *     (鉴权主体,ADR-23)三个词位互不混用——sponsor 配置里三者缺一即拒,sponsorId
+ *     冒充 traveler principal 结构性拒绝;
+ *   - sponsor 只包三个插件槽:入口(路由授权)、库存池(候选)、配置/披露(佣金+偏置声明),
+ *     不写 MotivationProfile,不改旅行者约束;
+ *   - 同内核复用证明面:本模块只 import 内核函数(src/booking-saga.ts 的
+ *     booking_saga_fsm.v1 状态机 + src/wish-pool.ts 的条件评分),零拷贝零重声明;
+ *     B2C 与 B2B 两种形态由同一 runner(runBookingScenario)以"是否携带 sponsor 插件"
+ *     参数化,saga 边序列逐格相同——内核 diff 为零即本件证明目标
+ *     (PR 内核文件 diff 必须为空,内核漂移即本套件红);
+ *   - 隔离:C 端默认路径不 import 本模块(sponsor-reuse-tests 4c 机械闸),
+ *     无插件参数即 B2C 形态,trace 经 sponsorLeakFindings 检查零 sponsor 字段。
+ *
+ * 红线(结构性编码,全部 fixture 证明):
+ *   - 排序不能以赞助收益伪造用户效用:候选必须先过内核条件评分(全命中强制),
+ *     佣金不可赎回未命中的条件;同分 tie-break 只按 sponsor 申报顺位,
+ *     且赞助受益位必须显式标记 sponsorTieBreakApplied 并携偏置声明;
+ *   - sponsor 佣金/收益明确披露并进入确认指纹:disclosureDigestSha256 参与
+ *     buildConfirmationFingerprint——披露口径变化则确认指纹变化;
+ *   - 相同 WriteGate 与未知态/取消退款规则:确认必携外部回执(空 receipt 两种形态同拒,
+ *     无 B2B 豁免);取消退款走同一内核边表(propose→confirm→compensate),回放零违例;
+ *   - 路由授权:供应商 route 必须在 sponsor 声明的授权闭集内(selector)+ session/order
+ *     绑定——禁止复制 Buyer/credentials 规避(本模块全链无凭据字段)。
+ */
+import { createHash } from 'node:crypto';
+import { resolveSagaTrigger, sagaTraceViolations, } from '../src/booking-saga.js';
+import { scoreWishMatch } from '../src/wish-pool.js';
+export const SPONSOR_PLUGIN_SCHEMA = 'sponsor.plugin.v1';
+/** 运行激活默认态:关闭。真实运行时激活属 M6 Entry(#137)后的显式 opt-in 面。 */
+export const SPONSOR_RUNTIME_ACTIVATION_DEFAULT = false;
+function sha256Canon(value) {
+    const canon = (v) => {
+        if (Array.isArray(v))
+            return v.map(canon);
+        if (v && typeof v === 'object') {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, x]) => [k, canon(x)]));
+        }
+        return v;
+    };
+    return createHash('sha256').update(JSON.stringify(canon(value))).digest('hex');
+}
+function requireNonEmpty(field, value) {
+    const v = typeof value === 'string' ? value.trim() : '';
+    if (!v)
+        throw new Error(`sponsor-plugin: 缺必填字段 ${field}(fail-closed;三主体与披露口径缺一即拒)`);
+    return v;
+}
+/**
+ * 构造 sponsor 插件(fail-closed):三主体标识、授权路由闭集、披露口径缺一即拒;
+ * sponsorId 与 travelerPrincipalId 混同(三主体边界破坏)即拒。
+ */
+export function createSponsorPlugin(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('sponsor-plugin: 配置必须是对象(fail-closed)');
+    }
+    const sponsorId = requireNonEmpty('sponsorId', config.sponsorId);
+    const travelerPrincipalId = requireNonEmpty('travelerPrincipalId', config.travelerPrincipalId);
+    const bffPrincipalId = requireNonEmpty('bffPrincipalId', config.bffPrincipalId);
+    if (sponsorId === travelerPrincipalId) {
+        throw new Error('sponsor-plugin: sponsorId 不得与 travelerPrincipalId 相同(traveler/sponsor/BFF 三主体分离,walkthrough §1)');
+    }
+    const routes = config.allowedRoutes;
+    if (!Array.isArray(routes) || routes.length === 0) {
+        throw new Error('sponsor-plugin: allowedRoutes 必须是非空数组(授权路由闭集;空闭集 = 不可提出任何候选)');
+    }
+    const cleaned = routes.map((r) => requireNonEmpty('allowedRoutes[]', r));
+    if (new Set(cleaned).size !== cleaned.length) {
+        throw new Error('sponsor-plugin: allowedRoutes 存在重复(授权闭集必须无歧义)');
+    }
+    const d = (config.disclosure ?? {});
+    const statement = requireNonEmpty('disclosure.statement', d.statement);
+    const rankingBiasNotice = requireNonEmpty('disclosure.rankingBiasNotice', d.rankingBiasNotice);
+    if (typeof d.commissionBps !== 'number' || !Number.isInteger(d.commissionBps) || d.commissionBps < 0) {
+        throw new Error('sponsor-plugin: disclosure.commissionBps 必须是非负整数基点(佣金必须显式申报)');
+    }
+    const frozen = Object.freeze({
+        sponsorId,
+        travelerPrincipalId,
+        bffPrincipalId,
+        allowedRoutes: Object.freeze(cleaned),
+        disclosure: Object.freeze({ commissionBps: d.commissionBps, statement, rankingBiasNotice }),
+    });
+    return Object.freeze({
+        schemaVersion: SPONSOR_PLUGIN_SCHEMA,
+        config: frozen,
+        disclosureDigestSha256: sha256Canon({ sponsorId, ...frozen.disclosure }),
+    });
+}
+/**
+ * 运行激活门(默认关闭):除显式 true 外一律抛错。
+ * 本件(#235)是结构性证明,不是运行时激活——真实交易路径在 #137 M6 Entry 之后。
+ */
+export function requireRuntimeActivation(enabled) {
+    if (enabled !== true) {
+        throw new Error('sponsor-plugin: 运行激活默认关闭(SPONSOR_RUNTIME_ACTIVATION_DEFAULT=false);真实运行时接线须显式 opt-in 且在 #137 M6 Entry 之后');
+    }
+}
+/**
+ * 供应商路由授权:路由必须在 sponsor 声明的授权闭集内(selector),且必须携带
+ * session 绑定(order 可选)——缺绑定即拒,禁止以复制 Buyer/credentials 方式规避
+ * (本模块全链无凭据字段;授权只认 principal 标识 + 会话/订单引用)。
+ */
+export function authorizeSponsorRoute(plugin, route, binding) {
+    if (!plugin.config.allowedRoutes.includes(route)) {
+        return { ok: false, reason: 'route-unauthorized', detail: `路由 ${route} 不在 sponsor ${plugin.config.sponsorId} 的授权闭集内(越权路由拒绝)` };
+    }
+    const sessionRef = typeof binding.sessionRef === 'string' ? binding.sessionRef.trim() : '';
+    if (!sessionRef) {
+        return { ok: false, reason: 'missing-session-binding', detail: '授权路由缺 session/order 绑定(禁止复制 Buyer/credentials 规避)' };
+    }
+    const orderRef = typeof binding.orderRef === 'string' && binding.orderRef.trim() ? binding.orderRef.trim() : null;
+    return { ok: true, route, sessionRef, orderRef };
+}
+/**
+ * 内核条件评分包装(两形态共用):候选映射为 wish 条目后调用内核 scoreWishMatch,
+ * 并强制「申报条件全命中才可预订」——部分命中不算(sponsor 不可放宽旅行者约束,
+ * wish conditions 强制红线)。内核不满足 → null。
+ */
+export function scoreCandidateAgainstWish(candidate, wish) {
+    const c = candidate.conditions;
+    const declared = [typeof c.days === 'number', typeof c.budget_cny === 'number', Array.isArray(c.best_months)].filter(Boolean).length;
+    const match = scoreWishMatch({ wish_id: candidate.candidateRef, name: candidate.name, conditions: c }, wish);
+    if (!match || match.hits.length < declared)
+        return null;
+    return { candidate, hits: match.hits };
+}
+/**
+ * sponsor 库存排序:①路由越权 → 排除(不进入评分);②内核条件评分非全命中 → 排除
+ * (佣金不可赎回——排序不能以赞助收益伪造用户效用);③排序键 = 内核评分降序,
+ * 同分 tie 按 sponsor 申报顺位(入参顺序;佣金数值从不进入排序键),
+ * tie 中申报顺位受益位(其佣金高于组内最低)显式标记 sponsorTieBreakApplied。
+ */
+export function rankSponsorCandidates(plugin, candidates, wish) {
+    const ranked = [];
+    const excluded = [];
+    const scored = [];
+    for (const cand of candidates) {
+        if (!plugin.config.allowedRoutes.includes(cand.route)) {
+            excluded.push({ candidateRef: cand.candidateRef, why: 'route-unauthorized' });
+            continue;
+        }
+        const match = scoreCandidateAgainstWish(cand, wish);
+        if (!match) {
+            excluded.push({ candidateRef: cand.candidateRef, why: 'conditions-not-met' });
+            continue;
+        }
+        scored.push({ cand, hits: match.hits });
+    }
+    // 内核评分降序;同分保持申报顺位(稳定排序)——申报顺位即 sponsor 声明的偏好序
+    const ordered = [...scored].sort((a, b) => b.hits.length - a.hits.length);
+    // 逐同分组判定 tie 受益位
+    let i = 0;
+    while (i < ordered.length) {
+        let j = i;
+        while (j + 1 < ordered.length && ordered[j + 1].hits.length === ordered[i].hits.length)
+            j++;
+        const group = ordered.slice(i, j + 1);
+        const minCommission = Math.min(...group.map((g) => g.cand.commissionBps ?? 0));
+        for (const g of group) {
+            ranked.push({
+                candidate: g.cand,
+                kernelScore: g.hits.length,
+                kernelHits: g.hits,
+                disclosure: {
+                    sponsorId: plugin.config.sponsorId,
+                    statement: plugin.config.disclosure.statement,
+                    rankingBiasNotice: plugin.config.disclosure.rankingBiasNotice,
+                    commissionBps: plugin.config.disclosure.commissionBps,
+                    disclosureDigestSha256: plugin.disclosureDigestSha256,
+                },
+                sponsorTieBreakApplied: group.length > 1 && (g.cand.commissionBps ?? 0) > minCommission,
+            });
+        }
+        i = j + 1;
+    }
+    return { ranked, excluded, biasNotice: plugin.config.disclosure.rankingBiasNotice };
+}
+/** 确认指纹:规范 JSON(键排序)后 sha256;披露摘要参与,披露口径变化 → 指纹变化。 */
+export function buildConfirmationFingerprint(parts) {
+    return sha256Canon({
+        schema: SPONSOR_PLUGIN_SCHEMA,
+        businessId: parts.businessId,
+        travelerPrincipalId: parts.travelerPrincipalId,
+        sponsorId: parts.sponsorId,
+        candidateRef: parts.candidateRef,
+        route: parts.route,
+        priceCny: parts.priceCny,
+        disclosureDigestSha256: parts.disclosureDigestSha256,
+    });
+}
+/**
+ * approval 绑定:必携非空外部回执(L3 具名确认红线,与内核 write.confirmed 空 receipt
+ * 违例同源;B2B 无豁免)。
+ */
+export function bindApproval(input) {
+    const receipt = typeof input.receipt === 'string' ? input.receipt.trim() : '';
+    if (!receipt)
+        throw new Error('sponsor-plugin: 确认必携外部回执(空 receipt 红线;B2B 与 C 端同一 WriteGate 规则)');
+    if (!input.fingerprintSha256)
+        throw new Error('sponsor-plugin: approval 必须绑定确认指纹');
+    return { receipt, fingerprintSha256: input.fingerprintSha256, travelerPrincipalId: input.travelerPrincipalId, sponsorId: input.sponsorId };
+}
+/** approval 绑定校验:指纹不一致(含跨 sponsor/跨租户重放)一律失败。 */
+export function verifyApprovalBinding(expectedFingerprintSha256, approval) {
+    return approval.fingerprintSha256 === expectedFingerprintSha256;
+}
+/**
+ * 端到端预订场景(fixture 合成数据;纯函数,零真实调用):
+ * 同一段代码驱动 B2C 与 B2B——内核调用(resolveSagaTrigger/scoreWishMatch/
+ * sagaTraceViolations)在两种形态下逐字相同,差异只在 sponsor 插件槽
+ * (路由授权/披露标注)。任何一步不合法即 fail-closed 抛错,不静默降级。
+ */
+export function runBookingScenario(input) {
+    const businessId = requireNonEmpty('businessId', input.businessId);
+    const travelerPrincipalId = requireNonEmpty('travelerPrincipalId', input.travelerPrincipalId);
+    const plugin = input.plugin ?? null;
+    const form = plugin ? 'b2b-sponsor' : 'b2c';
+    const scope = {
+        businessId,
+        travelerPrincipalId,
+        sponsorId: plugin ? plugin.config.sponsorId : null,
+        key: `${businessId}|${travelerPrincipalId}|${plugin ? plugin.config.sponsorId : 'c-side'}`,
+    };
+    const receipt = typeof input.receipt === 'string' ? input.receipt.trim() : '';
+    if (!receipt)
+        throw new Error('sponsor-plugin: 确认必携外部回执(空 receipt 红线;B2B 与 C 端同一 WriteGate 规则)');
+    let sessionRef = null;
+    if (plugin) {
+        sessionRef = typeof input.sessionRef === 'string' ? input.sessionRef.trim() : '';
+        if (!sessionRef)
+            throw new Error('sponsor-plugin: B2B 场景缺 session/order 绑定(路由授权前置条件)');
+    }
+    // 库存/规划:同一内核评分包装,两形态共用;B2B 附加路由授权闭集过滤
+    const eligible = [];
+    const events = [];
+    let seq = 0;
+    const push = (e) => {
+        events.push({ ...e, seq: seq++, scope });
+    };
+    for (const cand of input.candidates) {
+        if (plugin) {
+            const auth = authorizeSponsorRoute(plugin, cand.route, { sessionRef, orderRef: null });
+            if (!auth.ok) {
+                throw new Error(`sponsor-plugin: 端到端 ${auth.reason}(${auth.detail};candidate=${cand.candidateRef})`);
+            }
+        }
+        const match = scoreCandidateAgainstWish(cand, input.wish);
+        if (match)
+            eligible.push({ cand, hits: match.hits });
+    }
+    if (eligible.length === 0) {
+        throw new Error('sponsor-plugin: 无可预订候选(条件全命中强制;赞助权重不可伪造用户效用)');
+    }
+    eligible.sort((a, b) => b.hits.length - a.hits.length);
+    const top = eligible[0];
+    const fingerprint = buildConfirmationFingerprint({
+        businessId,
+        travelerPrincipalId,
+        sponsorId: scope.sponsorId,
+        candidateRef: top.cand.candidateRef,
+        route: top.cand.route,
+        priceCny: top.cand.priceCny,
+        disclosureDigestSha256: plugin ? plugin.disclosureDigestSha256 : null,
+    });
+    if (plugin) {
+        push({
+            kind: 'route.authorized', sagaEvent: null, from: null, to: null, guard: null,
+            detail: `route=${top.cand.route} selector=sponsor-allowed-routes session=${sessionRef} sponsor=${plugin.config.sponsorId}`,
+        });
+    }
+    push({
+        kind: 'candidate.ranked', sagaEvent: null, from: null, to: null, guard: null,
+        fingerprintSha256: fingerprint,
+        detail: `candidate=${top.cand.candidateRef} score=${top.hits.length} hits=[${top.hits.join(',')}]`
+            + (plugin ? ` bias=${plugin.config.disclosure.rankingBiasNotice}` : ' bias=null'),
+    });
+    // 确认闸:唯一状态推进词汇 = 内核 booking_saga_fsm.v1 边表(两形态同一张表)
+    let stage = 'none';
+    /** propose 必先执行(否则 fire 内即抛);settled 后为终态 */
+    let settled = null;
+    const approval = bindApproval({ fingerprintSha256: fingerprint, receipt, travelerPrincipalId, sponsorId: scope.sponsorId });
+    const fire = (trigger, extra = {}) => {
+        const verdict = resolveSagaTrigger(stage, trigger);
+        if (!verdict.ok)
+            throw new Error(`sponsor-plugin: saga 拒绝(${stage} --${trigger}--> ${verdict.reason};内核边表唯一归宿)`);
+        stage = verdict.to;
+        settled = verdict.to;
+        push({
+            kind: verdict.event, sagaEvent: verdict.event, from: verdict.from, to: verdict.to, guard: verdict.guard,
+            ...(trigger === 'confirm' ? { receipt: approval.receipt } : {}),
+            ...extra,
+            detail: `business=${businessId} candidate=${top.cand.candidateRef} route=${top.cand.route} priceCny=${top.cand.priceCny} fp=${fingerprint.slice(0, 12)}`,
+        });
+    };
+    fire('propose', { fingerprintSha256: fingerprint });
+    fire('confirm', { fingerprintSha256: fingerprint });
+    if (input.action === 'cancel')
+        fire('compensate');
+    // 审计/回放:内核校验器对 write.* 事件链逐段校验(必携回执/吸收态/拒绝闭包)
+    const audit = events
+        .filter((e) => e.sagaEvent !== null)
+        .map((e) => ({ seq: e.seq, kind: e.sagaEvent, receipt: e.receipt ?? null }));
+    const violations = sagaTraceViolations(audit);
+    if (settled === null)
+        throw new Error('sponsor-plugin: saga 未推进(不可达:propose 必先执行)');
+    return { form, scope, selectedCandidateRef: top.cand.candidateRef, sagaStatus: settled, events, sagaViolations: violations };
+}
+// ── 隔离检查器(C 端 trace 零 sponsor 渗入) ─────────────────────────────────
+/**
+ * sponsor 字段泄漏检查:递归扫描 trace,凡键名含 sponsor 且值非空(或 scope.sponsorId
+ * 非 null)即记一条发现。C 端默认形态 trace 必须零发现;B2B trace 必有发现
+ * (双向断言保证检查器自身有效)。
+ */
+export function sponsorLeakFindings(trace) {
+    const findings = [];
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((v, i) => walk(v, `${path}[${i}]`));
+            return;
+        }
+        if (node && typeof node === 'object') {
+            for (const [k, v] of Object.entries(node)) {
+                const empty = v === null || v === undefined || v === '';
+                if (/sponsor/i.test(k) && !empty)
+                    findings.push(`${path}.${k}`);
+                walk(v, `${path}.${k}`);
+            }
+        }
+    };
+    walk(trace, 'trace');
+    return findings;
+}

package/dist/capabilities/visa-policy.js

@@ -1,126 +1,140 @@
+/**
+ * 政策事实生产端 v1(issue #141,D-26 收口切片)——C 档数据源:中国领事服务网
+ * (cs.mfa.gov.cn,外交部一手口径,免费权威)的「了解目的地」国家指南树。
+ *
+ * 形态:VISA_POLICY_FETCH 效应(effect 注册表行,礼貌抓取:UA 标识 + 超时 +
+ * 永不重试 + 断路器护站)→ 国家页 HTML → 「签证入境」章节文本 → PolicyFact[]
+ * (as_of + review_by + cs.mfa.gov.cn 来源证据链)。
+ *
+ * 纪律(ADR-19 + 抓取红线):
+ *   - 永不抛错(永不抛错能力层契约);传输失败 → {ok:false, via:'visa-policy-error'},
+ *     **不落负事实**(无结论不是证据);
+ *   - 抓取失败/页面缺失 → 结构化降级,不猜不填;
+ *   - 政策事实恒带 review_by 复核 gate(默认 D-30);
+ *   - 礼貌抓取:单站点串行 + 调用方控制频率;站点不可达不重试(策略表 null)。
+ *
+ * 升级路径:D-31 后可切 B 档 Sherpa° 商业源(effect 注册表行可插拔替换)。
+ *
+ * @module capabilities/visa-policy
+ */
 import { readFileSync } from 'node:fs';
 import { BOOKABLE_FACT_SCHEMA, makeFactId } from '../src/bookable-facts.js';
 const SOURCE_HOST = 'https://cs.mfa.gov.cn';
 const SOURCE_ID = 'cs-mfa';
 const USER_AGENT = 'GoTry/0.0.1 (+https://github.com/Danceiny/gotry; polite policy reader)';
 const CONTINENTS = [
-    'yz_645708',
-    'feizhou_645714',
-    'ouzhou_645711',
-    'bz_645718',
-    'dyz_645717'
+    'yz_645708', // 亚洲
+    'feizhou_645714', // 非洲
+    'ouzhou_645711', // 欧洲
+    'bz_645718', // 美洲(北/南)
+    'dyz_645717', // 大洋洲
 ];
+/** 国家路径 → 政策页 URL(抓取纪律:仅此两种 URL 形态,不拼接任意输入) */
 export function countryPageUrl(continent, country) {
-    if (!/^[a-z0-9_]+$/.test(continent) || !/^[a-z0-9_]+$/.test(country)) return null;
+    if (!/^[a-z0-9_]+$/.test(continent) || !/^[a-z0-9_]+$/.test(country))
+        return null;
     return `${SOURCE_HOST}/zggmcg/ljmdd/${continent}/${country}/`;
 }
+/** 剥 HTML 标签 → 纯文本(保守:不执行任何内嵌脚本/样式) */
 function stripTags(html) {
-    return html.replace(/<(script|style)[\s\S]*?<\/\1>/gi, ' ').replace(/<[^>]+>/g, ' ').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/\s+/g, ' ');
+    return html
+        .replace(/<(script|style)[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/\s+/g, ' ');
 }
+/**
+ * 从国家页文本抽取「签证入境」章节(到下一个同级标题为止)。
+ * 页面为 MFA 编辑器产出的散文(如中泰互免协定生效日期/停留期限条款),逐段保留原句。
+ */
 export function extractVisaSection(pageText) {
     const text = stripTags(pageText);
     const start = text.indexOf('签证入境');
-    if (start < 0) return null;
+    if (start < 0)
+        return null;
     const rest = text.slice(start + '签证入境'.length);
-    const sectionEnds = [
-        '海关检查',
-        '海关申报',
-        '医疗条件',
-        '交通出行',
-        '实用信息',
-        '领事保护',
-        '国家安全',
-        '特别提醒'
-    ].map((kw)=>rest.indexOf(kw)).filter((i)=>i > 0);
-    const numHeaders = Array.from(rest.matchAll(/[一二三四五六七八九十]+、(?!免签|落地签|签证|入境规定)/g)).map((m)=>m.index).filter((i)=>i > 0);
-    const allEnds = [
-        ...sectionEnds,
-        ...numHeaders
-    ].sort((a, b)=>a - b);
+    // 下一大节标题探测:中文数字编号(非签证词)+已知下一节名(不用正文高频词做边界)
+    const sectionEnds = ['海关检查', '海关申报', '医疗条件', '交通出行', '实用信息', '领事保护', '国家安全', '特别提醒']
+        .map(kw => rest.indexOf(kw))
+        .filter(i => i > 0);
+    const numHeaders = Array.from(rest.matchAll(/[一二三四五六七八九十]+、(?!免签|落地签|签证|入境规定)/g)).map(m => m.index).filter(i => i > 0);
+    const allEnds = [...sectionEnds, ...numHeaders].sort((a, b) => a - b);
     const end = allEnds.length > 0 ? allEnds[0] : Math.min(rest.length, 4_000);
     const section = rest.slice(0, end).trim();
     return section.length > 20 ? section : null;
 }
+/**
+ * 章节 → 政策陈述条目:按中文序号段落切分(一、二、…),每段一条 PolicyFact 原料。
+ * 免签/落地签/签证要求各成一条,供闸侧逐条回溯。
+ */
 export function splitPolicyEntries(section) {
-    const parts = section.split(/(?:[一二三四五六七八九十]+、|[（(]\s*[一二三四五六七八九十]+\s*[）)])\s*/).map((p)=>p.trim());
-    return parts.filter((p)=>p.length > 30);
+    const parts = section.split(/(?:[一二三四五六七八九十]+、|[（(]\s*[一二三四五六七八九十]+\s*[）)])\s*/).map(p => p.trim());
+    return parts.filter(p => p.length > 30);
 }
 export function policyFactsFromMfa(input) {
     const entries = splitPolicyEntries(input.section);
     const asOf = input.fetchedAt.slice(0, 10);
     const queryId = `visa-policy:${SOURCE_ID}:${input.countryPath}:${asOf}`;
-    return entries.map((entry, i)=>({
-            schema: BOOKABLE_FACT_SCHEMA,
-            fact_id: makeFactId([
-                input.countryPath,
-                String(i),
-                entry.slice(0, 64),
-                queryId
-            ]),
-            kind: 'policy',
-            subject: `${input.countryLabel} 签证入境(条款 ${i + 1})`,
-            statement: entry,
-            source: `${SOURCE_ID}@${input.fetchedAt}`,
-            query_id: queryId,
-            fetched_at: input.fetchedAt,
-            as_of: asOf,
-            review_by: defaultReviewBy(input.fetchedAt)
-        }));
+    return entries.map((entry, i) => ({
+        schema: BOOKABLE_FACT_SCHEMA,
+        fact_id: makeFactId([input.countryPath, String(i), entry.slice(0, 64), queryId]),
+        kind: 'policy',
+        subject: `${input.countryLabel} 签证入境(条款 ${i + 1})`,
+        statement: entry,
+        source: `${SOURCE_ID}@${input.fetchedAt}`,
+        query_id: queryId,
+        fetched_at: input.fetchedAt,
+        as_of: asOf,
+        review_by: defaultReviewBy(input.fetchedAt),
+    }));
 }
+/** 政策复核 gate:抓取日 +30 天(D-30 族) */
 export function defaultReviewBy(fetchedAt) {
     const d = new Date(fetchedAt);
     d.setDate(d.getDate() + 30);
     return d.toISOString().slice(0, 10);
 }
+/** 从洲列表页 HTML 提取国家路径段(相对形态 ./tg_647570/ → tg_647570;仅收本站链接) */
 export function listCountryPaths(continentListHtml, continent) {
     const hits = continentListHtml.matchAll(new RegExp(`href="(\\./([a-z0-9_]+)/)"[^>]*>([^<]{2,20})<`, 'g'));
     const out = [];
-    for (const m of hits){
-        if (!m[2] || !m[3]) continue;
-        out.push({
-            path: m[2],
-            label: m[3].trim()
-        });
+    for (const m of hits) {
+        if (!m[2] || !m[3])
+            continue;
+        out.push({ path: m[2], label: m[3].trim() });
     }
-    return out.map((x)=>x.path).filter((p)=>/^[a-z0-9_]+$/.test(p));
+    return out.map(x => x.path).filter(p => /^[a-z0-9_]+$/.test(p));
 }
+/** 洲路径段 → 洲列表页 URL(形态受控,不拼接任意输入) */
 export function continentListUrl(continent) {
-    if (!/^[a-z0-9_]+$/.test(continent)) return null;
+    if (!/^[a-z0-9_]+$/.test(continent))
+        return null;
     return `${SOURCE_HOST}/zggmcg/ljmdd/${continent}/`;
 }
+/** 从本地 fixture 读页面(测试确定性;生产走 fetchVisaPolicyPage) */
 export function readPageFixture(path) {
     return readFileSync(path, 'utf-8');
 }
+/** 礼貌抓取国家页(永不抛错;失败 = 结构化降级,不落负事实) */
 export async function fetchVisaPolicyPage(url, timeoutMs = 20_000) {
     const controller = new AbortController();
-    const timer = setTimeout(()=>controller.abort(), timeoutMs);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
-            headers: {
-                'user-agent': USER_AGENT,
-                'accept-language': 'zh-CN,zh'
-            },
+            headers: { 'user-agent': USER_AGENT, 'accept-language': 'zh-CN,zh' },
             signal: controller.signal,
-            redirect: 'follow'
+            redirect: 'follow',
         });
-        if (!res.ok) return {
-            ok: false,
-            error: `HTTP ${res.status}`
-        };
-        return {
-            ok: true,
-            html: await res.text()
-        };
-    } catch (e) {
+        if (!res.ok)
+            return { ok: false, error: `HTTP ${res.status}` };
+        return { ok: true, html: await res.text() };
+    }
+    catch (e) {
         const msg = controller.signal.aborted ? `timeout after ${timeoutMs}ms` : String(e.message ?? e);
-        return {
-            ok: false,
-            error: msg
-        };
-    } finally{
+        return { ok: false, error: msg };
+    }
+    finally {
         clearTimeout(timer);
     }
 }
-
-
-//# sourceURL=ts/capabilities/visa-policy.ts