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

package/dist/scripts/channel-probe.js

@@ -0,0 +1,169 @@
+/**
+ * 通道探针 tick(外部事件接缝落地第 1 段,docs/design/external-event-seam.md §6①;
+ * issue #82 兼容方向)——外部事件作为健康面第二个生产者的本地形态。
+ *
+ * 设计边界(设计文档 §4,边界即信任):
+ *  - 只读探测:每通道一个无副作用最小调用(whoami/免费公开 GET),不检索、不下单;
+ *  - 本地生产者免鉴权(§3.2 本地可信):异常写 `down` 事件进
+ *    <stateRoot>/gotry-state/channel-health.jsonl,routingAdvice/doctor 零改动受益;
+ *  - 恢复走事件:探测通过且该通道此前处于 down → 写 'ok' 恢复事件
+ *    (readLatestChannelEvents latest-wins 超越 down);此前健康则零写放大;
+ *  - session:* 通道(需用户 Chrome 会话)无头不可探,显式 skip 不误报;
+ *  - flyai 默认不探(匿名共享额度,探针烧额度弊大于利)——`--only flyai` 显式选入;
+ *  - 不做常驻监听:tick 由 loopx/cron 驱动,一次运行一轮探测后退出。
+ *
+ * 用法(loopx/cron 驱动):
+ *   npx tsx ts/scripts/channel-probe.ts --state-root <root>            # 探测+落账
+ *   npx tsx ts/scripts/channel-probe.ts --dry-run                      # 只打印不落账
+ *   npx tsx ts/scripts/channel-probe.ts --only hbcli-hotel,open-meteo  # 选通道
+ *   npx tsx ts/scripts/channel-probe.ts --list                         # 列探测面
+ *
+ * @module scripts/channel-probe
+ */
+import { recordChannelEvent, readLatestChannelEvents } from '../capabilities/channel-health.js';
+function timeout(ms) {
+    return AbortSignal.timeout(ms);
+}
+async function fetchOk(url, what, ms = 8000) {
+    const t0 = Date.now();
+    try {
+        const res = await fetch(url, { signal: timeout(ms), headers: { Accept: 'application/json' } });
+        if (res.ok)
+            return { ok: true, ms: Date.now() - t0 };
+        return { ok: false, reason: `${what}-http-${res.status}`, ms: Date.now() - t0 };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.name : String(err);
+        return { ok: false, reason: msg === 'TimeoutError' ? 'timeout' : 'unreachable', ms: Date.now() - t0 };
+    }
+}
+function spawnOk(cmd, args, what, ms = 10000) {
+    return async () => {
+        const t0 = Date.now();
+        try {
+            const { spawn } = await import('node:child_process');
+            const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'ignore'] });
+            const code = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('timeout')); }, ms);
+                child.on('exit', (c) => { clearTimeout(timer); resolve(c ?? 1); });
+                child.on('error', (e) => { clearTimeout(timer); reject(e); });
+            });
+            return code === 0 ? { ok: true, ms: Date.now() - t0 } : { ok: false, reason: `${what}-exit-${code}`, ms: Date.now() - t0 };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { ok: false, reason: msg === 'timeout' ? 'timeout' : 'spawn-failed', ms: Date.now() - t0 };
+        }
+    };
+}
+/** 默认探测面(设计文档 §6①「关键通道」的无头子集;session 系与 flyai 显式 skip) */
+export function defaultProbes() {
+    return [
+        {
+            channel: 'hbcli-hotel',
+            probeable: true,
+            run: spawnOk('hbcli', ['auth', 'whoami'], 'auth-denied'),
+        },
+        {
+            channel: 'open-meteo',
+            probeable: true,
+            run: () => fetchOk('https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m', 'weather'),
+        },
+        {
+            channel: 'opensky',
+            probeable: true,
+            run: () => fetchOk('https://opensky-network.org/api/states/all?lamin=24.0&lomin=53.0&lamax=26.5&lomax=56.5', 'flights', 12000),
+        },
+        { channel: 'flyai', probeable: false, skipReason: 'anonymous-shared-quota——探针烧额度弊大于利;--only flyai 显式选入', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'session:ctrip-flight', probeable: false, skipReason: '需用户 Chrome 会话,无头不可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'session:ctrip-hotel', probeable: false, skipReason: '需用户 Chrome 会话,无头不可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'session:12306-train', probeable: false, skipReason: '需用户 Chrome 会话,无头不可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'anything-geo', probeable: false, skipReason: '静态包通道,无远端可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'static-hotel', probeable: false, skipReason: '静态包通道,无远端可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'web-read', probeable: false, skipReason: '依赖 agent-reach 装配态,探测意义低;--only 显式选入可探', run: async () => ({ ok: true, ms: 0 }) },
+    ];
+}
+/**
+ * 探测结果 → 事件序列(纯函数,测试锚点):
+ *  - fail → down 事件(永远落,哪怕已 down——重申事实,消费方幂等);
+ *  - ok 且此前处于 down → 'ok' 恢复事件(latest-wins 超越);
+ *  - ok 且此前健康 → 不落(零写放大);
+ *  - skip(probeable=false)→ 不产生事件。
+ */
+export function evaluateProbeResults(results, priorDown, now = new Date()) {
+    const events = [];
+    for (const { probe, result } of results) {
+        if (!probe.probeable)
+            continue;
+        if (result.ok) {
+            if (priorDown.has(probe.channel)) {
+                events.push({ channel: probe.channel, state: 'ok', at: now.toISOString() });
+            }
+            continue;
+        }
+        events.push({ channel: probe.channel, state: 'down', reason: result.reason, at: now.toISOString() });
+    }
+    return events;
+}
+export function parseArgs(argv) {
+    let stateRoot;
+    let only;
+    let dryRun = false;
+    let list = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--state-root')
+            stateRoot = argv[++i];
+        else if (a === '--only')
+            only = (argv[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        else if (a === '--dry-run')
+            dryRun = true;
+        else if (a === '--list')
+            list = true;
+    }
+    return { stateRoot, only, dryRun, list };
+}
+export async function main(argv) {
+    const args = parseArgs(argv);
+    const all = defaultProbes();
+    if (args.list) {
+        for (const p of all) {
+            console.log(`${p.probeable ? 'probe' : 'skip '}  ${p.channel}${p.skipReason ? `  # ${p.skipReason}` : ''}`);
+        }
+        return 0;
+    }
+    const selected = args.only?.length ? all.filter((p) => args.only.includes(p.channel)) : all.filter((p) => p.probeable);
+    if (selected.length === 0) {
+        console.error('[channel-probe] --only 未匹配任何通道;--list 查看探测面');
+        return 2;
+    }
+    const results = [];
+    for (const probe of selected) {
+        const result = await probe.run();
+        results.push({ probe, result });
+        console.log(`[channel-probe] ${result.ok ? 'ok  ' : 'FAIL'} ${probe.channel} (${result.ms}ms)${result.ok ? '' : ` reason=${result.reason}`}`);
+    }
+    const failures = results.filter((r) => !r.result.ok).length;
+    if (args.dryRun || !args.stateRoot) {
+        if (!args.stateRoot)
+            console.log('[channel-probe] 未给 --state-root:只探测不落账(等价 --dry-run)');
+        return failures > 0 ? 1 : 0;
+    }
+    let priorDown = new Set();
+    try {
+        const latest = await readLatestChannelEvents(args.stateRoot);
+        priorDown = new Set([...latest.entries()].filter(([, ev]) => ev.state === 'down' || ev.state === 'cooldown').map(([ch]) => ch));
+    }
+    catch { /* 读不到按全健康处理 */ }
+    for (const ev of evaluateProbeResults(results, priorDown)) {
+        await recordChannelEvent(args.stateRoot, ev);
+        console.log(`[channel-probe] 记录 ${ev.state} ${ev.channel}${ev.reason ? `(${ev.reason})` : ''}`);
+    }
+    return failures > 0 ? 1 : 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
+        console.error('[channel-probe] fatal:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}

package/dist/scripts/channel-registry-tests.js

@@ -0,0 +1,208 @@
+/**
+ * 通道注册表 + 通道健康面测试(issue #106/#107/#108 编排设计落地,
+ * docs/design/tool-orchestration-design.md §2/§3;全离线,隔离 tmp stateRoot):
+ *  1. 注册表封闭性:id 唯一/quotaClass·tier·intent 闭集/静态包不可路由
+ *  2. 意图顺位:证据级降序(官方API > 会话 > 网页兜底),同 tier 按效率
+ *  3. routingAdvice:down 通道被排除/发起通道被排除/limit 截断;hit 即恢复;
+ *     Dida down 时推进到下一个健康酒店通道
+ *  4. noteChannelVerdict 映射:needs-setup→down/hit→清除/miss·error→不动/cooldown 过期
+ *  5. persona 路由卡:确定性渲染,含改道规则与意图顺位行
+ *  6. JSONL 持久面:record/readLatest 往返 + 坏行容忍 + limitDays 过滤
+ *  7. doctor 集成:flyai 最近达限时间可见;calendar 三态(默认不挂载/opt-in 未配置/opt-in 已配置);
+ *     patch 宿主插件两态照亮(map-tools/ask-user,issue #113 L1 残量)
+ *  8. apply 接线:channel_routing_card 变量已注册;参数级拒绝不带 routing 字段;
+ *     工具描述首行生成(检索工具前置意图顺位卡,非检索工具原样,#113)
+ *  9. 持久健康面投影(#436):persistedDownChannels 纯投影(有效 down 才排除;
+ *     ok/cooldown/缺时间戳/坏时间戳/未来时间戳一律不排除)+ routingAdvice
+ *     与会话态的并集语义(会话失败永不被持久面解除)
+ *
+ * 运行: cd ts && npx tsx scripts/channel-registry-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CHANNELS, channelsForIntent, routingAdvice, renderRoutingCard, toolRoutingHeadline, INTENT_LABELS, persistedDownChannels, } from '../capabilities/channel-registry.js';
+import { noteChannelVerdict, channelState, clearChannel, resetChannelHealth, recordChannelEvent, readLatestChannelEvents, } from '../capabilities/channel-health.js';
+import { runDoctorChecks } from '../capabilities/doctor.js';
+import { apply } from '../src/index.js';
+const NOW = 1_700_000_000_000;
+// 1. 注册表封闭性
+const QUOTA_CLASSES = ['user-session', 'user-key', 'anonymous-trial', 'free-public', 'static'];
+const TIERS = ['realtime-api', 'session', 'best-effort', 'static'];
+const INTENTS = Object.keys(INTENT_LABELS);
+const ids = new Set();
+for (const c of CHANNELS) {
+    assert.ok(!ids.has(c.id), `通道 id 重复:${c.id}`);
+    ids.add(c.id);
+    assert.ok(QUOTA_CLASSES.includes(c.quotaClass), `${c.id} quotaClass 越界`);
+    assert.ok(TIERS.includes(c.tier), `${c.id} tier 越界`);
+    assert.ok(c.intents.length > 0 && c.intents.every(i => INTENTS.includes(i)), `${c.id} intents 越界`);
+    assert.ok(c.tool.startsWith('gotry_'), `${c.id} 工具名形态`);
+    if (c.quotaClass === 'static')
+        assert.equal(c.routable, false, '静态包不进模型可选路由');
+}
+assert.ok(CHANNELS.length >= 9, '注册表覆盖面(≥9 通道)');
+console.log('1. 注册表封闭性 OK');
+// 2. 意图顺位(证据级降序)
+resetChannelHealth();
+assert.deepEqual(channelsForIntent('search-flight').map(c => c.id), ['flyai', 'session:ctrip-flight', 'web-read'], '机票顺位');
+assert.deepEqual(channelsForIntent('search-train').map(c => c.id), ['flyai', 'session:12306-train', 'web-read'], '火车顺位');
+assert.deepEqual(channelsForIntent('search-hotel').map(c => c.id), ['flyai', 'hbcli-hotel', 'session:ctrip-hotel', 'session:dida-portal', 'web-read'], '酒店完整顺位(Dida 登记后仍钉全序)');
+assert.deepEqual(channelsForIntent('weather').map(c => c.id), ['open-meteo'], '单通道意图');
+console.log('2. 意图顺位(证据级 > 效率)OK');
+// 3. routingAdvice:健康面驱动
+const base = routingAdvice('search-flight');
+assert.equal(base.alternatives[0].channel, 'flyai', '健康时 flyai 首荐(零 setup 摩擦)');
+assert.ok(base.alternatives[0].why.length > 4 && (base.alternatives[0].setup?.length ?? 0) > 0, 'why/setup 齐备');
+// #559 B 步:flyai setup 行必须显式提到 Trial limit reached 后果,给匿名试用用户
+// 一眼看见「达限后会改道 gotry_session_search」(避免装好的人替没装的人以为整盘不可用)
+assert.match(base.alternatives[0].setup ?? '', /Trial limit reached/, 'flyai setup 行必显 Trial limit reached');
+assert.match(base.alternatives[0].setup ?? '', /gotry_session_search/, 'flyai setup 行必显 fallback 路径');
+noteChannelVerdict('flyai', 'needs-setup', { now: NOW });
+const afterDown = routingAdvice('search-flight', { now: NOW });
+assert.ok(!afterDown.alternatives.some(a => a.channel === 'flyai'), 'flyai 达限后从建议表排除(#108 病灶)');
+assert.equal(afterDown.alternatives[0].channel, 'session:ctrip-flight', 'session 升首荐(优先级=健康面投影)');
+const excl = routingAdvice('search-flight', { excludeChannel: 'session:ctrip-flight', now: NOW });
+assert.ok(!excl.alternatives.some(a => a.channel === 'session:ctrip-flight'), '发起通道被排除');
+assert.equal(routingAdvice('search-flight', { limit: 1, now: NOW }).alternatives.length, 1, 'limit 截断');
+noteChannelVerdict('flyai', 'hit', { now: NOW });
+assert.equal(routingAdvice('search-flight', { now: NOW }).alternatives[0].channel, 'flyai', 'hit 即恢复(#107:补 key 不被陈旧状态锁死)');
+// Dida 已是酒店 session 通道的一员:#297 后先让更高顺位通道不可用,证明 Dida
+// 成为当前首选；再把 Dida 标 down,必须推进到注册表中的后继 web-read。
+resetChannelHealth();
+for (const channel of ['flyai', 'hbcli-hotel', 'session:ctrip-hotel']) {
+    noteChannelVerdict(channel, 'needs-setup', { now: NOW });
+}
+assert.equal(routingAdvice('search-hotel', { now: NOW }).alternatives[0].channel, 'session:dida-portal', '前三个酒店通道 down 后 Dida 升为首荐');
+noteChannelVerdict('session:dida-portal', 'needs-login', { now: NOW });
+assert.equal(routingAdvice('search-hotel', { now: NOW }).alternatives[0].channel, 'web-read', 'Dida down 后推进到后继健康酒店通道');
+console.log('3. routingAdvice(down 排除/发起排除/limit/hit 恢复 + Dida down→后继)OK');
+// 4. noteChannelVerdict 映射闭集
+resetChannelHealth();
+assert.ok(noteChannelVerdict('x', 'needs-setup', { now: NOW }), 'needs-setup → down 事件');
+assert.equal(channelState('x', NOW)?.state, 'down');
+assert.equal(noteChannelVerdict('x', 'challenged', { now: NOW })?.reason, 'challenged', 'challenged → down');
+assert.equal(noteChannelVerdict('x', 'needs-login', { now: NOW })?.reason, 'needs-login', 'needs-login → down');
+assert.equal(noteChannelVerdict('x', 'needs-extension', { now: NOW })?.reason, 'needs-extension', 'needs-extension → down');
+assert.equal(noteChannelVerdict('x', 'miss', { now: NOW }), undefined, '业务 miss ≠ 通道故障');
+assert.equal(noteChannelVerdict('x', 'error', { now: NOW }), undefined, '业务 error ≠ 通道故障');
+clearChannel('x');
+assert.equal(channelState('x', NOW), undefined, '清除后无状态');
+const cd = noteChannelVerdict('y', 'cooldown', { now: NOW, cooldownMs: 30_000 });
+assert.equal(cd?.state, 'cooldown', 'cooldown → cooldown 事件');
+assert.equal(channelState('y', NOW + 29_999)?.state, 'cooldown', '冷却未满仍在');
+assert.equal(channelState('y', NOW + 30_001), undefined, '冷却满惰性过期');
+console.log('4. noteChannelVerdict 映射闭集 OK');
+// 5. persona 路由卡
+const card1 = renderRoutingCard(new Date(NOW));
+const card2 = renderRoutingCard(new Date(NOW));
+assert.equal(card1, card2, '同刻渲染确定');
+assert.match(card1, /检索通道顺位/, '卡头');
+assert.match(card1, /verdict≠hit/, '改道规则在卡内');
+assert.match(card1, /- 机票: .+gotry_flyai_search.+→.+gotry_session_search/, '机票顺位行');
+assert.match(card1, /- 火车: .+12306 公开查询面.+kind=train/, '火车行带 kind 消歧');
+assert.match(card1, /匿名试用=首次体验导流/, '额度口径脚注(D-7)');
+assert.ok(!card1.includes('- 天气'), '单通道意图不上卡');
+console.log('5. persona 路由卡 OK');
+// 6. JSONL 持久面往返(事件时间用真实时钟——limitDays 窗口以读方时钟为基准)
+const stateRoot = await mkdtemp(join(tmpdir(), 'gotry-channel-test-'));
+const realNow = Date.now();
+await recordChannelEvent(stateRoot, { channel: 'flyai', state: 'down', reason: 'needs-setup', at: new Date(realNow - 86_400_000).toISOString() });
+await recordChannelEvent(stateRoot, { channel: 'flyai', state: 'down', reason: 'needs-setup', at: new Date(realNow).toISOString() });
+await recordChannelEvent(stateRoot, { channel: 'session:ctrip-flight', state: 'cooldown', at: new Date(realNow).toISOString() });
+const latest = await readLatestChannelEvents(stateRoot);
+assert.equal(latest.get('flyai')?.at, new Date(realNow).toISOString(), '每通道取最新');
+assert.equal(latest.get('session:ctrip-flight')?.state, 'cooldown');
+await recordChannelEvent(stateRoot, { channel: 'legacy', state: 'down', at: new Date(realNow - 40 * 86_400_000).toISOString() });
+assert.ok(!((await readLatestChannelEvents(stateRoot)).has('legacy')), '40 天前事件被 limitDays 过滤');
+const raw = `${stateRoot}/gotry-state/channel-health.jsonl`;
+await writeFile(raw, `${await readFile(raw, 'utf-8')}not-json\n{"half":true}\n`, 'utf-8');
+assert.equal((await readLatestChannelEvents(stateRoot)).size, 2, '坏行容忍');
+console.log('6. JSONL 持久面 OK');
+// 7. doctor 集成:flyai 配额可见 + calendar 三态(setup 状态面,非 env)
+const emptyRepo = join(stateRoot, 'repo');
+const emptyHome = join(stateRoot, 'home');
+await mkdir(emptyRepo, { recursive: true });
+await mkdir(join(emptyHome, '.gotry'), { recursive: true });
+const calStatePath = join(emptyHome, '.gotry', 'calendar.json');
+const d1 = await runDoctorChecks({ repoRoot: emptyRepo, homeDir: emptyHome, env: {}, stateRoot });
+assert.match(d1.items.find(i => i.id === 'flyai').detail, /最近一次试用达限/, '最近达限时间进 doctor(#107 可见性)');
+assert.equal(d1.items.find(i => i.id === 'calendar').status, 'ok', 'calendar 默认不挂载=ok(D-9)');
+assert.match(d1.items.find(i => i.id === 'calendar').detail, /默认未挂载/, '默认态人话');
+await writeFile(calStatePath, JSON.stringify({ enabled: true }), 'utf-8');
+const d2 = await runDoctorChecks({ repoRoot: emptyRepo, homeDir: emptyHome, env: {} });
+assert.equal(d2.items.find(i => i.id === 'calendar').status, 'degraded', 'setup 开启但未配置 username=degraded');
+assert.match(d2.items.find(i => i.id === 'calendar').fix ?? '', /npx @danceiny\/gotry setup calendar/, 'fix 指向 setup 状态面');
+const profileDir = join(emptyHome, '.dsh/profiles/web');
+await mkdir(profileDir, { recursive: true });
+await writeFile(join(profileDir, 'cordis.patch.yml'), '- id: dsh-calendar\n  config:\n    username: someone\n', 'utf-8');
+const d3 = await runDoctorChecks({ repoRoot: emptyRepo, homeDir: emptyHome, env: {} });
+assert.equal(d3.items.find(i => i.id === 'calendar').status, 'ok', 'setup 开启且已配置=ok');
+const d4 = await runDoctorChecks({ repoRoot: emptyRepo, homeDir: emptyHome, env: {} });
+assert.ok(!/最近一次试用达限/.test(d4.items.find(i => i.id === 'flyai').detail), '无 stateRoot 不读持久面(向后兼容)');
+// patch 宿主插件两态照亮(issue #113):隔离环境两者皆 missing——静默剔除面进 doctor 可见
+const mapItem = d4.items.find(i => i.id === 'map-tools');
+const askItem = d4.items.find(i => i.id === 'ask-user');
+assert.equal(mapItem.status, 'missing', '隔离环境 map-tools=missing(静默剔除面可见)');
+assert.match(mapItem.detail, /静默剔除/, 'map-tools detail 说明静默剔除语义');
+assert.equal(askItem.status, 'missing', '隔离环境 ask-user=missing');
+assert.match(askItem.detail, /散文追问/, 'ask-user detail 说明退化面');
+console.log('7. doctor 集成(flyai 配额可见 + calendar setup 状态面三态 + 宿主插件两态)OK');
+// 8. apply 接线:变量注册 + 参数级拒绝不带 routing
+resetChannelHealth();
+const variables = {};
+const registered = [];
+const ctx = {
+    tools: { register: (t) => registered.push(t) },
+    systemPrompt: { variable: (name, provider) => { variables[name] = provider; } },
+    on: () => () => { },
+};
+apply(ctx, { stateRoot, timeoutMs: 30_000, hbcliBin: 'hbcli-not-on-path', sessionAccess: 'ask' });
+assert.equal(typeof variables.channel_routing_card, 'function', 'channel_routing_card 变量已注册');
+assert.match(variables.channel_routing_card(), /检索通道顺位/, '卡片可渲染');
+const pastDate = await registered.find(t => t.name === 'gotry_flyai_search').execute({ kind: 'flight', from: '深圳', to: '普吉', date: '2026-01-01' }, null);
+assert.ok(!('routing' in pastDate), '参数级预校验拒绝不带 routing(未发起检索,无改道语义)');
+// D-30 迁移锁(issue #112):typed 平铺契约下 legacy blob 包裹在宿主权校验即拒绝,
+// 拒绝形状保持 ADR-13 ToolFailure(guardToolExecute 兜底:ok:false + evidence)且不带 routing
+const legacyBlob = await registered.find(t => t.name === 'gotry_flyai_search').execute({ query: { kind: 'flight', from: '深圳', to: '普吉', date: '2026-01-01' } }, null);
+assert.ok(legacyBlob.ok === false && !('routing' in legacyBlob) && !!legacyBlob.evidence, 'legacy blob → 结构化拒绝(ToolFailure,无 routing)');
+// 工具描述首行生成(issue #113):检索工具前置注册表生成的意图顺位卡;非检索工具原样
+const flyaiTool = registered.find(t => t.name === 'gotry_flyai_search');
+const doctorToolDesc = registered.find(t => t.name === 'gotry_doctor');
+assert.ok(flyaiTool, 'flyai 工具已注册');
+assert.match(toolRoutingHeadline('gotry_flyai_search'), /机票: 飞猪官方 API\(gotry_flyai_search\) → 携程·用户登录态/, 'flyai 首行卡:机票顺位 flyai 在前(证据级)');
+assert.match(toolRoutingHeadline('gotry_session_search'), /火车: .*12306 公开查询面\(gotry_session_search kind=train\)/, 'session 首行卡带 kind 消歧');
+assert.equal(toolRoutingHeadline('gotry_doctor'), '', '非检索工具无首行卡(原样描述)');
+assert.ok(flyaiTool.description?.startsWith('本工具服务的检索意图与通道顺位'), 'flyai 描述已前置首行卡(接线生效)');
+assert.ok(!doctorToolDesc.description?.startsWith('本工具服务的检索意图'), 'doctor 描述无首行卡(接线不误伤)');
+console.log('8. apply 接线 + 描述首行生成 OK');
+// 9. 持久健康面投影 + 并集语义(issue #436)
+resetChannelHealth();
+const latestEvents = new Map([
+    ['down-valid', { state: 'down', at: new Date(NOW - 60_000).toISOString() }],
+    ['down-now', { state: 'down', at: new Date(NOW).toISOString() }],
+    ['ok-latest', { state: 'ok', at: new Date(NOW).toISOString() }],
+    ['cooldown-latest', { state: 'cooldown', at: new Date(NOW).toISOString() }],
+    ['down-no-at', { state: 'down' }],
+    ['down-bad-at', { state: 'down', at: 'not-a-date' }],
+    ['down-future', { state: 'down', at: new Date(NOW + 86_400_000).toISOString() }],
+]);
+assert.deepEqual([...persistedDownChannels(latestEvents, NOW)].sort(), ['down-now', 'down-valid'], '投影:只有带有效时间戳且不在未来的 down 才排除(cooldown 是节律、ok 是恢复)');
+assert.ok(persistedDownChannels(new Map(), NOW).size === 0, '空事件表=零排除');
+// 并集语义:持久集合只加排除,不能解除会话态;顺位表本身不变
+const noPersisted = routingAdvice('search-flight', { now: NOW });
+assert.ok(noPersisted.alternatives.some(a => a.channel === 'session:ctrip-flight'), '无持久集合=原会话态口径');
+const persistedExcl = routingAdvice('search-flight', { now: NOW, persistedDownChannels: new Set(['session:ctrip-flight']) });
+assert.ok(!persistedExcl.alternatives.some(a => a.channel === 'session:ctrip-flight'), '持久 down 通道被排除');
+assert.equal(persistedExcl.alternatives[0].channel, 'flyai', '顺位不变,只过滤');
+const persistedLimit = routingAdvice('search-hotel', { now: NOW, persistedDownChannels: new Set(['flyai', 'hbcli-hotel']), limit: 1 });
+assert.deepEqual(persistedLimit.alternatives.map(a => a.channel), ['session:ctrip-hotel'], '持久排除叠加后 limit 仍截断');
+noteChannelVerdict('session:ctrip-flight', 'challenged', { now: NOW });
+assert.ok(!routingAdvice('search-flight', { now: NOW, persistedDownChannels: new Set() }).alternatives.some(a => a.channel === 'session:ctrip-flight'), '会话 down 在空持久集合(含持久 ok 恢复)下仍排除——持久面不解锁会话失败');
+assert.equal(channelState('session:ctrip-flight', NOW)?.state, 'down', '会话态未被持久面改写');
+clearChannel('session:ctrip-flight');
+assert.ok(routingAdvice('search-flight', { now: NOW, persistedDownChannels: new Set() }).alternatives.some(a => a.channel === 'session:ctrip-flight'), '会话清除 + 持久面无 down → 通道恢复(恢复只对没有会话 down 的通道生效)');
+console.log('9. 持久健康面投影 + 并集语义(#436)OK');
+await rm(stateRoot, { recursive: true, force: true });
+console.log('channel-registry-tests: 全部通过');

package/dist/scripts/city-scenario-tier-tests.js

@@ -0,0 +1,234 @@
+/**
+ * City × scenario tiering MECHANISM tests (issue #339 contract slice,
+ * SIMULATED-TRIGGER DRILL — fully offline, zero network, zero state).
+ *
+ * ⚠ Evidence label: `simulated_trigger_drill` / `fixture_contract`. #339's real
+ * trigger (reviewable real usage samples + an explicit scenario vocabulary and
+ * success metric) has NOT fired. Every registry used below is a TEST-ONLY shape
+ * probe constructed with `{ triggerFired: true }`; its city/scenario strings are
+ * deliberately meaningless placeholders (`city-a`, `scenario-x`) so that nothing
+ * here can be mistaken for a taxonomy. The product registry stays frozen EMPTY —
+ * #339 forbids fabricating a profile from fixtures.
+ *
+ * Sections:
+ *  A. Default-off proof: trigger frozen false, registry frozen empty in SOURCE,
+ *     admission refused before any validation, every resolution neutral.
+ *  B. Admission shape: mandatory provenance (evidence grade / real sample source /
+ *     ≥3 sample refs / reviewer / freeze instant) and retirement (condition +
+ *     review deadline postdating the freeze); each omission fail-closed.
+ *  C. Bounded modifier: integer ppm inside declared bounds; 0, negative,
+ *     out-of-range, float and non-numeric refused — no tier can annihilate a score.
+ *  D. Neutral fallback: unknown city, unknown scenario, conflicting evidence,
+ *     empty registry; a conflict elects no winner.
+ *  E. Ranking-only falsification: a modifier reorders but can NEVER remove a
+ *     candidate (incl. lower bound × zero semantic), the result exposes no filter
+ *     surface, and the mechanical no-hard-filter check passes.
+ *  F. Determinism + versioning: identical inputs → byte-identical output; ties keep
+ *     declaration order; a defective registry entry is refused, never clamped.
+ *
+ * Run (from ts/): npx tsx scripts/city-scenario-tier-tests.ts
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CITY_SCENARIO_TIER_REGISTRY, CITY_SCENARIO_TIER_SCHEMA, CITY_SCENARIO_TIER_TRIGGER_FIRED, TIER_APPLICATION_SURFACES, TIER_EVIDENCE_GRADES, TIER_KEY_MAX_CHARS, TIER_MIN_SAMPLE_REFS, TIER_MODIFIER_PPM_MAX, TIER_MODIFIER_PPM_MIN, TIER_MODIFIER_PPM_NEUTRAL, TIER_NEUTRAL_REASONS, TIER_SAMPLE_SOURCES, admitTierEntry, applyTierRanking, normalizeTierKey, resolveTier, tierRankingFilterViolation, } from '../src/city-scenario-tier.js';
+let passed = 0;
+function check(cond, msg) {
+    if (cond) {
+        passed++;
+        console.log(`  ok - ${msg}`);
+    }
+    else {
+        console.error(`  FAIL - ${msg}`);
+        process.exitCode = 1;
+    }
+}
+function expectRefusal(result, code, needle, msg) {
+    if (result.ok) {
+        check(false, `${msg} (expected refusal ${code}, got ok)`);
+        return;
+    }
+    check(result.code === code && result.detail.includes(needle), `${msg} (refused ${result.code}${result.code === code ? '' : ` ≠ ${code}`}, evidence contains "${needle}": ${result.detail.includes(needle)})`);
+}
+const FROZEN_AT = '2026-10-04T00:00:00.000Z';
+const REVIEW_BY = '2027-04-04T00:00:00.000Z';
+/** TEST-ONLY shape probe. The keys are meaningless placeholders, not a taxonomy. */
+function probeEntryInput(overrides = {}) {
+    return {
+        tier_id: 'probe-tier-1',
+        city_key: 'city-a',
+        scenario_key: 'scenario-x',
+        modifier_ppm: 1_100_000,
+        applies_to: 'ranking',
+        provenance: {
+            evidence_grade: 'controlled_replay',
+            sample_source: 'real_usage_sample',
+            sample_refs: ['sample-ref-1', 'sample-ref-2', 'sample-ref-3'],
+            reviewer: 'drill-reviewer',
+            frozen_at: FROZEN_AT,
+        },
+        retirement: { condition: 'withdraw if the controlled replay no longer reproduces the ordering', review_by: REVIEW_BY },
+        taxonomy_version: 'probe.v0',
+        ...overrides,
+    };
+}
+function admittedProbe(overrides = {}, registry = []) {
+    const r = admitTierEntry(probeEntryInput(overrides), { triggerFired: true, registry });
+    if (!r.ok)
+        throw new Error(`probe admission failed unexpectedly: ${r.code} ${r.detail}`);
+    return r.value;
+}
+// ---------------------------------------------------------------------------
+// A. Default-off proof
+// ---------------------------------------------------------------------------
+console.log('A. default-off: trigger frozen false, registry frozen EMPTY, nothing admitted');
+check(CITY_SCENARIO_TIER_TRIGGER_FIRED === false, '#339 trigger gate frozen false');
+check(CITY_SCENARIO_TIER_REGISTRY.length === 0, 'the runtime taxonomy registry is empty');
+check(CITY_SCENARIO_TIER_SCHEMA === 'gotry_city_scenario_tier.v1', 'the taxonomy schema id is versioned');
+const MODULE_SOURCE = readFileSync(join(fileURLToPath(new URL('.', import.meta.url)), '..', 'src', 'city-scenario-tier.ts'), 'utf8');
+check(MODULE_SOURCE.includes('export const CITY_SCENARIO_TIER_REGISTRY: readonly CityScenarioTierEntry[] = []'), 'the registry declaration is literally `= []` in source (no taxonomy content in code)');
+check(MODULE_SOURCE.includes('export const CITY_SCENARIO_TIER_TRIGGER_FIRED = false'), 'the trigger declaration is literally `= false` in source');
+expectRefusal(admitTierEntry(probeEntryInput()), 'trigger_not_fired', '不凭 fixture 造画像', 'with the default trigger, admission is refused before any validation');
+expectRefusal(admitTierEntry({ tier_id: '', city_key: '', scenario_key: '', modifier_ppm: -1, taxonomy_version: '' }), 'trigger_not_fired', '#339 trigger has not fired', 'even a wholly invalid entry is refused by the trigger gate first (pre-trigger refusal precedes validation)');
+const defaultResolution = resolveTier({ cityKey: 'any-city', scenarioKey: 'any-scenario' });
+check(defaultResolution.ok && defaultResolution.value.status === 'neutral' && defaultResolution.value.modifier_ppm === TIER_MODIFIER_PPM_NEUTRAL, 'with the default trigger every pair resolves to the neutral modifier ×1.0');
+check(defaultResolution.ok && defaultResolution.value.status === 'neutral' && defaultResolution.value.reason === 'trigger_not_fired', 'the neutral reason is trigger_not_fired, stated rather than implied');
+check(TIER_MODIFIER_PPM_NEUTRAL === 1_000_000, 'the neutral modifier is exactly ×1.0');
+check(TIER_NEUTRAL_REASONS.length === 5 && TIER_NEUTRAL_REASONS.includes('conflicting_evidence'), 'the neutral-reason set is closed and names conflicting evidence');
+// ---------------------------------------------------------------------------
+// B. Admission shape (mandatory provenance + retirement)
+// ---------------------------------------------------------------------------
+console.log('B. admission shape: provenance and retirement are mandatory per tier');
+const admitted = admitTierEntry(probeEntryInput(), { triggerFired: true, registry: [] });
+check(admitted.ok && admitted.value.schema === CITY_SCENARIO_TIER_SCHEMA && admitted.value.taxonomy_version === 'probe.v0', 'a complete probe entry is admitted and carries its schema + taxonomy version');
+check(admitted.ok && admitted.value.applies_to === 'ranking' && TIER_APPLICATION_SURFACES.length === 1, 'the only application surface is `ranking` (there is no hard-filter surface)');
+check(admitted.ok && admitted.value.provenance.sample_refs.length === 3 && admitted.value.retirement.review_by === REVIEW_BY, 'provenance sample refs and the retirement deadline are preserved');
+expectRefusal(admitTierEntry(probeEntryInput({ provenance: undefined }), { triggerFired: true }), 'provenance_required', 'a tier without a stated evidence source is not evidence', 'missing provenance refused');
+expectRefusal(admitTierEntry(probeEntryInput({ retirement: undefined }), { triggerFired: true }), 'retirement_required', 'a tier that cannot expire is not evidence', 'missing retirement refused');
+expectRefusal(admitTierEntry(probeEntryInput({ provenance: { ...probeEntryInput().provenance, sample_source: 'fixture' } }), { triggerFired: true }), 'closed_set', '不凭 fixture 造画像', 'a fixture-sourced sample is refused by name (#339 red line)');
+check(TIER_SAMPLE_SOURCES.length === 1 && TIER_SAMPLE_SOURCES[0] === 'real_usage_sample', 'the admitted sample-source set has exactly one member: real_usage_sample');
+expectRefusal(admitTierEntry(probeEntryInput({ provenance: { ...probeEntryInput().provenance, evidence_grade: 'vibes' } }), { triggerFired: true }), 'closed_set', TIER_EVIDENCE_GRADES[0], 'an evidence grade outside the RFC S2 ordering is refused');
+expectRefusal(admitTierEntry(probeEntryInput({ provenance: { ...probeEntryInput().provenance, sample_refs: ['only-one'] } }), { triggerFired: true }), 'provenance_required', 'a single anecdote is not a tier', `fewer than ${TIER_MIN_SAMPLE_REFS} sample refs refused`);
+expectRefusal(admitTierEntry(probeEntryInput({ provenance: { ...probeEntryInput().provenance, reviewer: '' } }), { triggerFired: true }), 'provenance_required', 'reviewer', 'a tier with no accountable reviewer refused');
+expectRefusal(admitTierEntry(probeEntryInput({ provenance: { ...probeEntryInput().provenance, frozen_at: '2026-10-04' } }), { triggerFired: true }), 'bad_ts', 'date-only', 'a date-only freeze instant refused');
+expectRefusal(admitTierEntry(probeEntryInput({ retirement: { condition: '', review_by: REVIEW_BY } }), { triggerFired: true }), 'retirement_required', 'retirement.condition', 'an empty retirement condition refused');
+expectRefusal(admitTierEntry(probeEntryInput({ retirement: { condition: 'c', review_by: FROZEN_AT } }), { triggerFired: true }), 'retirement_required', 'must postdate', 'a review deadline that does not postdate the freeze refused');
+expectRefusal(admitTierEntry(probeEntryInput({ applies_to: 'hard_filter' }), { triggerFired: true }), 'closed_set', 'memory never enters a hard filter', 'applies_to = hard_filter refused by name');
+expectRefusal(admitTierEntry(probeEntryInput({ taxonomy_version: '' }), { triggerFired: true }), 'binding_incomplete', 'taxonomy_version', 'an unversioned tier refused');
+expectRefusal(admitTierEntry(probeEntryInput({ tier_id: '  ' }), { triggerFired: true }), 'binding_incomplete', 'tier_id', 'a blank tier id refused');
+expectRefusal(admitTierEntry(probeEntryInput({ city_key: '' }), { triggerFired: true }), 'bad_key', 'must not be blank', 'a blank city key refused (blank ≠ unknown)');
+expectRefusal(admitTierEntry(probeEntryInput({ scenario_key: 'x'.repeat(TIER_KEY_MAX_CHARS + 1) }), { triggerFired: true }), 'bad_key', 'never prose', 'an over-long scenario key refused');
+const oneEntry = [admittedProbe()];
+expectRefusal(admitTierEntry(probeEntryInput({ tier_id: 'probe-tier-2' }), { triggerFired: true, registry: oneEntry }), 'duplicate_tier', 'conflicting evidence, not an additional tier', 'a second tier for the same (city, scenario) pair is refused at admission');
+expectRefusal(admitTierEntry(probeEntryInput({ city_key: 'city-b' }), { triggerFired: true, registry: oneEntry }), 'duplicate_tier', 'already exists', 'a duplicate tier_id refused');
+// ---------------------------------------------------------------------------
+// C. Bounded modifier
+// ---------------------------------------------------------------------------
+console.log('C. bounded modifier: declared [min,max], lower bound > 0 by design');
+check(TIER_MODIFIER_PPM_MIN > 0 && TIER_MODIFIER_PPM_MIN < TIER_MODIFIER_PPM_NEUTRAL && TIER_MODIFIER_PPM_MAX > TIER_MODIFIER_PPM_NEUTRAL, 'bounds straddle neutral and the lower bound is strictly positive');
+check(admitTierEntry(probeEntryInput({ modifier_ppm: TIER_MODIFIER_PPM_MIN }), { triggerFired: true }).ok, 'the lower bound itself is admissible (inclusive)');
+check(admitTierEntry(probeEntryInput({ modifier_ppm: TIER_MODIFIER_PPM_MAX }), { triggerFired: true }).ok, 'the upper bound itself is admissible (inclusive)');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: 0 }), { triggerFired: true }), 'modifier_bounds', 'never annihilate a candidate', 'a zero modifier is refused (it would annihilate a candidate score)');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: -1_000_000 }), { triggerFired: true }), 'modifier_bounds', 'outside the declared bounds', 'a negative modifier refused');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: TIER_MODIFIER_PPM_MIN - 1 }), { triggerFired: true }), 'modifier_bounds', 'outside the declared bounds', 'one ppm below the lower bound refused');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: TIER_MODIFIER_PPM_MAX + 1 }), { triggerFired: true }), 'modifier_bounds', 'outside the declared bounds', 'one ppm above the upper bound refused');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: 1_100_000.5 }), { triggerFired: true }), 'modifier_bounds', 'ppm integers are exact', 'a fractional ppm refused');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: '1100000' }), { triggerFired: true }), 'modifier_bounds', 'must be an integer ppm', 'a string modifier refused');
+expectRefusal(admitTierEntry(probeEntryInput({ modifier_ppm: Number.NaN }), { triggerFired: true }), 'modifier_bounds', 'must be an integer ppm', 'NaN modifier refused');
+// ---------------------------------------------------------------------------
+// D. Neutral fallback, never a guess
+// ---------------------------------------------------------------------------
+console.log('D. neutral fallback: unknown city / unknown scenario / conflicting evidence');
+const probeRegistry = [admittedProbe()];
+const hit = resolveTier({ cityKey: 'city-a', scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true });
+check(hit.ok && hit.value.status === 'hit' && hit.value.modifier_ppm === 1_100_000, 'a known (city, scenario) pair resolves to its bounded modifier');
+check(hit.ok && hit.value.status === 'hit' && hit.value.explanation.includes('retire when:'), 'a hit explains itself and surfaces its retirement condition');
+check(hit.ok && hit.value.status === 'hit' && hit.value.evidence_grade === 'controlled_replay' && hit.value.taxonomy_version === 'probe.v0', 'a hit carries the evidence grade and taxonomy version');
+const unknownCity = resolveTier({ cityKey: 'city-zz', scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true });
+check(unknownCity.ok && unknownCity.value.status === 'neutral' && unknownCity.value.reason === 'unknown_city' && unknownCity.value.modifier_ppm === TIER_MODIFIER_PPM_NEUTRAL, 'unknown city → neutral ×1.0 with reason unknown_city');
+check(unknownCity.ok && unknownCity.value.status === 'neutral' && unknownCity.value.explanation.includes('never guessed from a neighbour'), 'the unknown-city fallback states that no neighbour is substituted');
+const unknownScenario = resolveTier({ cityKey: 'city-a', scenarioKey: 'scenario-zz' }, { registry: probeRegistry, triggerFired: true });
+check(unknownScenario.ok && unknownScenario.value.status === 'neutral' && unknownScenario.value.reason === 'unknown_scenario', 'unknown scenario → neutral ×1.0 with reason unknown_scenario');
+const emptyRegistry = resolveTier({ cityKey: 'city-a', scenarioKey: 'scenario-x' }, { registry: [], triggerFired: true });
+check(emptyRegistry.ok && emptyRegistry.value.status === 'neutral' && emptyRegistry.value.reason === 'empty_registry', 'empty registry → neutral ×1.0, not a zero weight');
+/** Conflicting registry built by bypassing the admission duplicate guard (a defective registry). */
+const conflicting = [
+    admittedProbe({ tier_id: 'probe-conflict-a', modifier_ppm: 1_100_000 }),
+    admittedProbe({ tier_id: 'probe-conflict-b', modifier_ppm: 900_000 }),
+];
+const conflict = resolveTier({ cityKey: 'city-a', scenarioKey: 'scenario-x' }, { registry: conflicting, triggerFired: true });
+check(conflict.ok && conflict.value.status === 'neutral' && conflict.value.reason === 'conflicting_evidence' && conflict.value.modifier_ppm === TIER_MODIFIER_PPM_NEUTRAL, 'conflicting evidence → neutral ×1.0, no winner elected');
+check(conflict.ok && conflict.value.status === 'neutral' && conflict.value.conflicting_tier_ids.join(',') === 'probe-conflict-a,probe-conflict-b', 'the conflict surfaces both tier ids for diagnosis (without choosing)');
+check(conflict.ok && conflict.value.tier_id === null, 'a neutral resolution never reports a tier id');
+check(normalizeTierKey(' City-A ', 'k').ok, 'keys normalize: trim + lowercase');
+const n1 = normalizeTierKey('  City   A ', 'k');
+const n2 = normalizeTierKey('city a', 'k');
+check(n1.ok && n2.ok && n1.value === n2.value, 'whitespace collapse + case folding are deterministic and agree');
+const caseHit = resolveTier({ cityKey: 'CITY-A', scenarioKey: ' Scenario-X ' }, { registry: probeRegistry, triggerFired: true });
+check(caseHit.ok && caseHit.value.status === 'hit', 'a case/whitespace variant of a known key still hits (normalization, not fuzzy matching)');
+expectRefusal(resolveTier({ cityKey: '   ', scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true }), 'bad_key', 'must not be blank', 'a blank city key is a caller error, not a silent neutral');
+expectRefusal(resolveTier({ cityKey: 42, scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true }), 'bad_key', 'must be a string', 'a non-string key is a caller error');
+// ---------------------------------------------------------------------------
+// E. Ranking-only falsification
+// ---------------------------------------------------------------------------
+console.log('E. FALSIFICATION: a modifier may reorder, it can NEVER remove a candidate');
+const candidates = [
+    { id: 'cand-boosted', cityKey: 'city-a', semantic: 0.50 },
+    { id: 'cand-plain-1', cityKey: 'city-b', semantic: 0.54 },
+    { id: 'cand-plain-2', cityKey: 'city-c', semantic: 0.10 },
+    { id: 'cand-zero', cityKey: 'city-a', semantic: 0 },
+];
+const neutralRank = applyTierRanking(candidates, { scenarioKey: 'scenario-x' });
+check(neutralRank.ok && neutralRank.value.length === candidates.length, 'default (trigger off): all candidates survive');
+check(neutralRank.ok && neutralRank.value.map(r => r.id).join(',') === 'cand-plain-1,cand-boosted,cand-plain-2,cand-zero', 'default ordering is pure semantic order (every modifier neutral)');
+check(neutralRank.ok && neutralRank.value.every(r => r.modifier_ppm === TIER_MODIFIER_PPM_NEUTRAL && r.tier_id === null), 'default: every row carries the neutral modifier and no tier id');
+check(neutralRank.ok && tierRankingFilterViolation(candidates, neutralRank.value) === null, 'the mechanical no-hard-filter check passes for the default ranking');
+const boostedRank = applyTierRanking(candidates, { scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true });
+check(boostedRank.ok && boostedRank.value.map(r => r.id).join(',') === 'cand-boosted,cand-plain-1,cand-plain-2,cand-zero', 'a ×1.1 tier REORDERS: 0.50×1.1 = 0.55 overtakes the plain 0.54');
+check(boostedRank.ok && boostedRank.value.length === candidates.length, 'reordering preserves the candidate count exactly');
+check(boostedRank.ok && tierRankingFilterViolation(candidates, boostedRank.value) === null, 'the mechanical no-hard-filter check passes for the reordered ranking');
+check(boostedRank.ok && boostedRank.value.every(r => candidates.some(c => c.id === r.id && c.semantic === r.semantic)), 'every row preserves its original semantic score (the unmodified ranking is always recoverable)');
+check(boostedRank.ok && (boostedRank.value.find(r => r.id === 'cand-boosted')?.explanation ?? '').includes('probe-tier-1'), 'the applied bias is disclosed per candidate (ranking-disclosure precedent)');
+/** The most hostile admissible tier: the lower bound applied to a zero semantic score. */
+const minTier = [admittedProbe({ tier_id: 'probe-min', modifier_ppm: TIER_MODIFIER_PPM_MIN })];
+const minRank = applyTierRanking(candidates, { scenarioKey: 'scenario-x' }, { registry: minTier, triggerFired: true });
+check(minRank.ok && minRank.value.length === candidates.length, 'FALSIFICATION: even the lower-bound modifier removes nobody (count unchanged)');
+check(minRank.ok && minRank.value.some(r => r.id === 'cand-zero' && r.score === 0), 'FALSIFICATION: a zero-semantic candidate scores 0 and is still PRESENT (score 0 ≠ removal)');
+check(minRank.ok && tierRankingFilterViolation(candidates, minRank.value) === null, 'FALSIFICATION: the no-hard-filter check passes at the hostile bound');
+check(minRank.ok && !Object.keys(minRank.value[0]).some(k => /exclud|filter|drop|reject|threshold/i.test(k)), 'the ranked row shape exposes no exclude/filter/drop/threshold field (no filter surface exists)');
+let everPresent = true;
+for (let semantic = 0; semantic <= 10; semantic++) {
+    for (const registry of [[], probeRegistry, minTier]) {
+        const probe = applyTierRanking([{ id: 'solo', cityKey: 'city-a', semantic: semantic / 10 }], { scenarioKey: 'scenario-x' }, { registry, triggerFired: true });
+        if (!probe.ok || probe.value.length !== 1 || probe.value[0].id !== 'solo')
+            everPresent = false;
+    }
+}
+check(everPresent, 'FALSIFICATION battery: across 11 semantic scores × 3 registries the candidate is never dropped');
+expectRefusal(applyTierRanking([{ id: '', cityKey: 'city-a', semantic: 1 }], { scenarioKey: 'scenario-x' }), 'bad_candidate', 'non-empty id', 'a blank candidate id refused');
+expectRefusal(applyTierRanking([{ id: 'a', cityKey: 'city-a', semantic: Number.NaN }], { scenarioKey: 'scenario-x' }), 'bad_candidate', 'must be finite', 'a non-finite semantic score refused');
+expectRefusal(applyTierRanking([{ id: 'a', cityKey: 'city-a', semantic: -0.5 }], { scenarioKey: 'scenario-x' }), 'bad_candidate', 'would invert every modifier', 'a NEGATIVE semantic score is refused: the contract is multiplicative, so a boost would demote it');
+expectRefusal(applyTierRanking([{ id: 'ok', cityKey: 'city-b', semantic: 0.5 }, { id: 'neg', cityKey: 'city-a', semantic: -1 }], { scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true }), 'bad_candidate', 'must be non-negative', 'one negative candidate refuses the whole ranking (no partial ordering over inverted semantics)');
+check(applyTierRanking([{ id: 'zero', cityKey: 'city-a', semantic: 0 }], { scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true }).ok, 'zero is admissible (it is the boundary, not a negative)');
+check(applyTierRanking([{ id: 'negzero', cityKey: 'city-a', semantic: -0 }], { scenarioKey: 'scenario-x' }).ok, 'negative zero is admissible (it equals zero, not below it)');
+expectRefusal(applyTierRanking([{ id: 'a', cityKey: 'city-a', semantic: 1 }, { id: 'a', cityKey: 'city-b', semantic: 2 }], { scenarioKey: 'scenario-x' }), 'bad_candidate', 'duplicate candidate id', 'duplicate candidate ids refused (ranking inputs are a set)');
+check(tierRankingFilterViolation(candidates, []) !== null, 'the mechanical check CATCHES a dropped-candidate violation (the check itself is falsifiable)');
+check(tierRankingFilterViolation(candidates, (neutralRank.ok ? neutralRank.value : []).slice(0, 3)) !== null, 'the mechanical check catches a partial drop');
+// ---------------------------------------------------------------------------
+// F. Determinism + versioning
+// ---------------------------------------------------------------------------
+console.log('F. determinism, stable ties, defective registry refused');
+const runA = applyTierRanking(candidates, { scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true });
+const runB = applyTierRanking(candidates, { scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true });
+check(runA.ok && runB.ok && JSON.stringify(runA.value) === JSON.stringify(runB.value), 'identical inputs produce byte-identical output (deterministic)');
+const ties = [
+    { id: 'tie-1', cityKey: 'city-b', semantic: 0.4 },
+    { id: 'tie-2', cityKey: 'city-c', semantic: 0.4 },
+    { id: 'tie-3', cityKey: 'city-d', semantic: 0.4 },
+];
+const tieRank = applyTierRanking(ties, { scenarioKey: 'scenario-x' }, { registry: probeRegistry, triggerFired: true });
+check(tieRank.ok && tieRank.value.map(r => r.id).join(',') === 'tie-1,tie-2,tie-3', 'ties keep declaration order (stable sort)');
+const defective = [{ ...admittedProbe(), modifier_ppm: 5_000_000 }];
+expectRefusal(resolveTier({ cityKey: 'city-a', scenarioKey: 'scenario-x' }, { registry: defective, triggerFired: true }), 'modifier_bounds', 'never clamped silently', 'a defective registry entry is refused at read time, never clamped silently');
+expectRefusal(applyTierRanking(candidates, { scenarioKey: 'scenario-x' }, { registry: defective, triggerFired: true }), 'modifier_bounds', 'defective registry entry', 'ranking propagates the defective-registry refusal instead of degrading');
+console.log(`\nCITY-SCENARIO TIER MECHANISM TESTS (#339, simulated_trigger_drill / fixture_contract; registry stays EMPTY): ${passed} pass${process.exitCode ? ', FAIL' : ' (all green)'}`);