@danceiny/gotry 0.2.0-rc.27 → 0.2.0-rc.28

package/dist/scripts/state-cli.js

@@ -4,6 +4,8 @@
  *   migrate [root]                      one-shot 迁移:旧 JSON/JSONL → 账本 events
  *                                       (导入前自动快照到 gotry-state/pre-ledger-backup/)
  *   export [root]                       local-only:账本 → 旧文件名视图(红线 6:可见可导出;单向,不回流)
+ *                                       另含会话双区派生视图(P4-2):hot-context.jsonl /
+ *                                       notebook.json,从事件 fold 渲染——视图永不是写路径
  *   log [root] [--limit N]              事件账本尾部(append-only 审计面)
  *   stats [root]                        各面计数
  *   rebuild [root] [toSeq]              DROP 投影 → fold 重放(可截到 toSeq;账本/投影
@@ -47,6 +49,7 @@
 import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ensureLedger, ledgerDbPath, ledgerExists, openLedgerIfExists } from '../src/state-ledger.js';
+import { ZONE_EXPORT_HOT_FILE, ZONE_EXPORT_NOTEBOOK_FILE, readZoneExportViews, } from '../src/session-zone-ledger.js';
 import { formatRepairPlan, loadEvidenceMappingFile, planLedgerRepair } from '../src/ledger-repair-plan.js';
 import { applyLedgerRepair, formatRepairApplyResult, restoreRepairBackup, } from '../src/ledger-repair-apply.js';
 import { collectDeepPlanning, makeJournaledSolvePort, settleAsyncTicket } from '../src/loop.js';
@@ -382,6 +385,19 @@ switch (cmd) {
         const trips = ledger.readTrips();
         if (trips.length)
             atomicWrite(join(dir, 'trips.jsonl'), trips.map(e => JSON.stringify(e)).join('\n') + '\n');
+        // 会话双区派生视图(P4-2,design/session-dual-zone-memory-design.md §2):
+        // 从六个事件 kind 的确定性 fold 渲染;空分区不产生空文件(同既有视图纪律)。
+        // 日志触读上界即拒:导出残缺视图比不导出更坏(读者会当它是全量)。
+        const zone = readZoneExportViews(ledger);
+        if (!zone.ok) {
+            console.error(`${zone.code}: ${zone.detail}`);
+            process.exit(1);
+        }
+        const zoneViews = zone.views;
+        if (zoneViews.hotContextJsonl)
+            atomicWrite(join(dir, ZONE_EXPORT_HOT_FILE), zoneViews.hotContextJsonl);
+        if (zoneViews.notebookJson !== '[]')
+            atomicWrite(join(dir, ZONE_EXPORT_NOTEBOOK_FILE), zoneViews.notebookJson);
         console.log(`视图已导出(单向,DB→文件;红线 6):${dir}/`);
         break;
     }

package/dist/scripts/time-eval-tests.js

@@ -26,6 +26,8 @@ import { newState, runTurn } from '../src/loop.js';
 import { parseRequest } from '../src/model.js';
 import { solveChoiceSegment } from '../src/unified.js';
 import { parsePlanningWindow } from '../src/time-anchor.js';
+// issue #617:确定性部分(第 6 节)经 runTurn,其 PoI 探针缺省不得 spawn 本机真实 hbcli(显式设置的值不覆盖)
+process.env['GOTRY_HBCLI_LIVE'] ??= '0';
 const dataset = JSON.parse(readFileSync(join('..', 'data', 'time-slot-eval.json'), 'utf-8'));
 const [ay, am, ad] = dataset.anchor_date.split('-').map(Number);
 const ANCHOR_NOW = new Date(ay, am - 1, ad, 12); // 锚点日中午,避免午夜边界

package/dist/scripts/unified-tests.js

@@ -50,4 +50,40 @@ off.budgetCny = 9000;
 off.workWindow = undefined;
 const r4 = await solveUnified(off);
 assert.deepEqual(r4.work_window_exclusions, []); // 关掉窗口,周五班恢复可选
-console.log(`TS UNIFIED TESTS: 4/4 OK(工作窗口生效,f2=VZ303,¥${r1.money_cny})`);
+// 5. Issue #620:yunnan-pack 的 yn0 段缺 buffer_min/origin_transfer_min/dest_transfer_min
+//    → 旧实现 Number(undefined)=NaN → Int.val(NaN) 在 z3 WASM 里 `Assertion failed`
+//    → 被兜底翻译成「不可行 + unsat_core:['wasm_runtime_error']」。三条红线:
+//    ① parse 边界必须点名拒收(不默认补 0);② 绕过 parse 的 NaN spec 必须以
+//    solver_error 返回而**绝不**是 infeasible;③ 补齐那三个字段后整包必须真能判定。
+const yunnanRaw = JSON.parse(await readFile(join('..', 'data', 'yunnan-pack.json'), 'utf-8'));
+// ① 真实数据包:yn0 的三个缺字段 → NaN → 必须是显式 solver_error,绝不是「不可行」
+const yunnanSpecRaw = parseFlightPackToSpec(structuredClone(yunnanRaw));
+yunnanSpecRaw.budgetCny = 9000;
+assert.ok(Number.isNaN(yunnanSpecRaw.segments[0].options[0].move.bufferMin), 'yn0 缺 buffer_min 的事实前提');
+const rYunnanRaw = await solveUnified(yunnanSpecRaw);
+assert.equal(rYunnanRaw.solver_error?.code, 'solver_input_not_integer', `yunnan 包必须以 solver_error 返回(got ${JSON.stringify(rYunnanRaw)})`);
+assert.ok(rYunnanRaw.solver_error.message.includes('yn0.bufferMin'), `solver_error 必须点名出问题的段与字段(got ${rYunnanRaw.solver_error.message})`);
+assert.equal(rYunnanRaw.feasible, false, 'solver_error 轮次没有产出可行解');
+assert.deepEqual(rYunnanRaw.unsat_core, undefined, '求解器失败不得伪造 unsat_core(机器 token 不进冲突位)');
+assert.ok(!JSON.stringify(rYunnanRaw).includes('wasm_runtime_error'), '不得再出现 wasm_runtime_error 这个伪冲突 token');
+// ② 最小输入:健康包里塞一个 NaN 接驳分钟 → 同样是 solver_error,点名到字段
+const nanSpec = parseFlightPackToSpec(pack);
+nanSpec.budgetCny = 9000;
+nanSpec.segments[0].options[0].move.bufferMin = Number.NaN;
+const rNan = await solveUnified(nanSpec);
+assert.equal(rNan.solver_error?.code, 'solver_input_not_integer', `NaN 接驳必须以 solver_error 返回(got ${JSON.stringify(rNan)})`);
+assert.ok(rNan.solver_error.message.includes('f1.bufferMin'), `solver_error 必须点名字段(got ${rNan.solver_error.message})`);
+assert.equal(rNan.feasible, false, 'solver_error 轮次没有产出可行解');
+// ③ 补齐 yn0 的三个字段(由测试提供,不改数据包:真值待 founder 校准)→ 整包真能判定,
+//    证明断言失败的最小输入正是这三个字段,其余四段编码本身没问题
+const yunnanFixed = structuredClone(yunnanRaw);
+Object.assign(yunnanFixed['legs'][0], {
+    buffer_min: 60, origin_transfer_min: 30, dest_transfer_min: 30,
+});
+const yunnanSpec = parseFlightPackToSpec(yunnanFixed);
+yunnanSpec.budgetCny = 9000;
+const rYunnan = await solveUnified(yunnanSpec);
+assert.equal(rYunnan.solver_error, undefined, `补齐三字段后不得再有求解器失败(got ${JSON.stringify(rYunnan.solver_error)})`);
+assert.equal(rYunnan.feasible, true, `yunnan 整包应可行(unsat_core=${JSON.stringify(rYunnan.unsat_core)})`);
+assert.equal(rYunnan.legs.length, 5, '五段全判定');
+console.log(`TS UNIFIED TESTS: 5/5 OK(工作窗口生效,f2=VZ303,¥${r1.money_cny};#620 yunnan NaN→solver_error 点名 yn0,补齐三字段后可行 ¥${rYunnan.money_cny})`);

package/dist/scripts/z3-race-tests.js

@@ -6,7 +6,9 @@
  * (run-all §1 重试止血与 release-notes rc.2-rc.4 的实录根因)。
  * 修复(z3-shared.ts):单一 WASM 实例 + 单一 Context + 会话级互斥门。
  *
- * 断言:① 并发轮次无 unified WASM 降级(wasm_runtime_error);② 判定与顺序基线一致。
+ * 断言:① 并发轮次无 unified 求解器失败(issue #620 后形态:`solver_error`,
+ *   旧形态是伪造的 `unsat_core:['wasm_runtime_error']`——两条都断言不出现);
+ * ② 判定与顺序基线一致。
  * 运行(在 ts/ 下):npx tsx scripts/z3-race-tests.ts
  */
 import assert from 'node:assert/strict';
@@ -35,6 +37,9 @@ for (let round = 0; round < ROUNDS; round++) {
     void jny;
     assert.equal(eng['recommended'], baseEngine['recommended'], `r${round}: engine recommended 漂移`);
     assert.equal(jny['feasible'], baseJourney['feasible'], `r${round}: journey feasible 漂移`);
+    // issue #620:求解器失败现在是 solver_error(显式类别),不再伪装成 unsat_core 里的
+    // 机器 token。两种形态都断言不出现——旧形态回归也会被这条抓住。
+    assert.equal(uni['solver_error'], undefined, `r${round}: unified 会话求解器失败——race 复发(${JSON.stringify(uni['solver_error'])})`);
     assert.equal((uni['unsat_core'] ?? []).includes('wasm_runtime_error'), false, `r${round}: unified 会话触发 WASM 降级——race 复发`);
     assert.equal(uni['feasible'], true, `r${round}: unified 判定漂移(基线应为可行)`);
 }

package/dist/src/city-scenario-tier.js

@@ -0,0 +1,378 @@
+/**
+ * City × scenario tiering MECHANISM v1 (issue #339 contract slice,
+ * SIMULATED-TRIGGER DRILL — default OFF, zero callers, trigger flag frozen false,
+ * registry frozen EMPTY).
+ *
+ * ⚠ Evidence boundary: this module ships the MECHANISM only. #339's trigger is
+ * "reviewable real usage samples with a stated scenario vocabulary and success
+ * metric"; it has NOT fired. The tracker is explicit that a profile must never be
+ * fabricated from fixtures (「没有样本时保持研究/设计状态,不凭 fixture 造画像」),
+ * so there is deliberately NO taxonomy CONTENT here:
+ *   - `CITY_SCENARIO_TIER_REGISTRY` is frozen `[]`;
+ *   - `CITY_SCENARIO_TIER_TRIGGER_FIRED` is frozen `false`, and `admitTierEntry`
+ *     refuses every admission before validating anything while it is false, so no
+ *     tier can enter the registry without real samples and a founder decision;
+ *   - every resolution therefore returns the NEUTRAL modifier today.
+ * Any scenario vocabulary proposal lives in the drill report as a clearly labelled
+ * unvalidated hypothesis, never in this file.
+ *
+ * Shape (mirrors ts/capabilities/fx-contract.ts #344 / ts/capabilities/geo-atlas.ts
+ * #342 / ts/src/session-zones.ts P4-1): pure functions, zero IO / network / timers,
+ * closed error-code set, typed results, deterministic, versioned, fail-closed.
+ *
+ * Frozen upstream constraints (READ-ONLY reuse):
+ *  - docs/design/memory-design.md §1 item 3: the profile only feeds ranking, never
+ *    hard filters — future shape `semantic × bounded_modifier`, "otherwise memory
+ *    would filter the search down to nothing";
+ *  - docs/rfc/loopx-inspired-upgrades-rfc.md S2: the ranking form
+ *    `rank = semantic × bounded_modifier` and the evidence-grade ordering
+ *    `owner_correction > controlled_replay > deterministic_effect > evaluator_inference`;
+ *  - the ranking-disclosure precedent in `ts/capabilities/` (the sponsored-inventory
+ *    ranker): a non-semantic weight never silently rewrites the sort key, and a
+ *    tie-break bias is disclosed per candidate;
+ *  - ts/src/memory-decay.ts: decay touches behavioural events only and exposes no
+ *    motivation-profile API; this module likewise touches no profile and no store.
+ *
+ * Red lines encoded structurally (each has a falsification test in
+ * ts/scripts/city-scenario-tier-tests.ts, run-all §86):
+ *  1. ranking only — `applyTierRanking` has NO filter/exclude surface at all, and
+ *     the output always contains exactly the input candidates: a modifier may
+ *     reorder, it can never remove a candidate (not even at the lower bound with
+ *     a zero semantic score);
+ *  2. bounded — the modifier is an integer ppm inside declared [min,max] bounds;
+ *     0, negative, non-integer and out-of-range are refused at admission, so no
+ *     tier can zero a candidate out;
+ *  3. neutral fallback, never a guess — unknown city, unknown scenario, conflicting
+ *     evidence, empty registry and trigger-not-fired all return the NEUTRAL
+ *     modifier with a stated reason; conflicting entries never elect a winner;
+ *  4. per-tier provenance (evidence grade + real sample refs + reviewer + freeze
+ *     instant) and a retirement condition + review deadline are MANDATORY;
+ *  5. deterministic and versioned: same inputs → byte-identical result; ties keep
+ *     declaration order.
+ *
+ * Only the real #339 trigger can supply: the taxonomy members themselves, the
+ * scenario vocabulary, the success metric, the numeric bounds justified by data,
+ * and the before/after ranking hypotheses with real counterexamples.
+ *
+ * @module src/city-scenario-tier
+ */
+/** Versioned contract schema id (readers validate it). */
+export const CITY_SCENARIO_TIER_SCHEMA = 'gotry_city_scenario_tier.v1';
+/**
+ * #339 implementation trigger gate, frozen false. Flipping it true requires
+ * reviewable real usage samples plus an explicit scenario vocabulary and success
+ * metric. While false, `admitTierEntry` refuses every admission.
+ */
+export const CITY_SCENARIO_TIER_TRIGGER_FIRED = false;
+/**
+ * Declared modifier bounds, in ppm (1_000_000 = neutral ×1.0).
+ *
+ * NOT data-derived: RFC S2 fixes the FORM (`semantic × bounded_modifier`) but the
+ * repo states no numeric interval anywhere. These values are drill-declared so the
+ * bound CHECK can be proven; the interval itself must be re-frozen from real
+ * samples when #339's trigger fires. The lower bound is deliberately > 0 so no
+ * tier can ever annihilate a candidate's semantic score.
+ */
+export const TIER_MODIFIER_PPM_NEUTRAL = 1_000_000;
+export const TIER_MODIFIER_PPM_MIN = 850_000;
+export const TIER_MODIFIER_PPM_MAX = 1_150_000;
+/** The only admitted application surface. There is no hard-filter surface. */
+export const TIER_APPLICATION_SURFACES = ['ranking'];
+/** Evidence grades, strongest first (RFC S2 ordering, read-only reuse). */
+export const TIER_EVIDENCE_GRADES = ['owner_correction', 'controlled_replay', 'deterministic_effect', 'evaluator_inference'];
+/**
+ * Admitted sample sources. Exactly one member: a reviewable real usage sample.
+ * A fixture / synthetic / model-authored sample is outside the closed set and is
+ * refused by name — this is #339's「不凭 fixture 造画像」as code.
+ */
+export const TIER_SAMPLE_SOURCES = ['real_usage_sample'];
+/** Bounded shapes: keys are vocabulary members, never free prose. */
+export const TIER_KEY_MAX_CHARS = 48;
+export const TIER_TEXT_MAX_CHARS = 200;
+export const TIER_MAX_REGISTRY_ENTRIES = 512;
+function fail(code, detail) {
+    return { ok: false, code, detail };
+}
+function pass(value) {
+    return { ok: true, value };
+}
+// ---------------------------------------------------------------------------
+// Key normalization (deterministic; never a guess)
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a city / scenario key: trim, collapse internal whitespace, lowercase.
+ * No transliteration, no alias expansion, no fuzzy matching — an unrecognized key
+ * stays unrecognized and falls back to neutral (ADR-10: nothing is fabricated).
+ */
+export function normalizeTierKey(value, label) {
+    if (typeof value !== 'string') {
+        return fail('bad_key', `${label} must be a string, got ${JSON.stringify(value)}`);
+    }
+    const normalized = value.trim().replace(/\s+/g, ' ').toLowerCase();
+    if (normalized === '')
+        return fail('bad_key', `${label} must not be blank (a blank key is not an unknown key; callers must pass the key they actually have)`);
+    if (normalized.length > TIER_KEY_MAX_CHARS) {
+        return fail('bad_key', `${label} exceeds ${TIER_KEY_MAX_CHARS} chars (${normalized.length}) — a key is a vocabulary member, never prose`);
+    }
+    return pass(normalized);
+}
+function requiredText(label, value, code) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        return fail(code, `${label} must be a non-empty string, got ${JSON.stringify(value)}`);
+    }
+    if (value.length > TIER_TEXT_MAX_CHARS) {
+        return fail('bound_exceeded', `${label} exceeds ${TIER_TEXT_MAX_CHARS} chars (${value.length})`);
+    }
+    return pass(value.trim());
+}
+function requiredInstant(label, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        return fail('bad_ts', `${label} must be a non-empty ISO-8601 instant, got ${JSON.stringify(value)}`);
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value.trim())) {
+        return fail('bad_ts', `${label} must carry a full time-of-day (date-only '${value}' cannot order a freeze/review)`);
+    }
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return fail('bad_ts', `${label} is not a parseable ISO-8601 instant: ${JSON.stringify(value)}`);
+    return pass(new Date(ms).toISOString());
+}
+/**
+ * Runtime taxonomy registry, frozen EMPTY — #339 forbids fabricating city-scenario
+ * tiers from fixtures. A non-empty value requires reviewable real samples and is a
+ * founder decision; the focused suite asserts this declaration stays `[]` in source.
+ */
+export const CITY_SCENARIO_TIER_REGISTRY = [];
+/** Minimum reviewable real samples behind one tier (a single anecdote is not a tier). */
+export const TIER_MIN_SAMPLE_REFS = 3;
+/**
+ * Admit one taxonomy entry.
+ *
+ * While `CITY_SCENARIO_TIER_TRIGGER_FIRED` is false this refuses BEFORE validating
+ * anything, so no tier can be fabricated from fixtures. Tests and a future admitted
+ * slice pass `{ triggerFired: true }` explicitly to exercise the validation shape.
+ */
+export function admitTierEntry(input, options) {
+    const triggerFired = options?.triggerFired ?? CITY_SCENARIO_TIER_TRIGGER_FIRED;
+    if (!triggerFired) {
+        return fail('trigger_not_fired', '#339 trigger has not fired (reviewable real usage samples + an explicit scenario vocabulary and success metric are required); zero tiers admitted — 不凭 fixture 造画像');
+    }
+    const registry = options?.registry ?? CITY_SCENARIO_TIER_REGISTRY;
+    if (registry.length >= TIER_MAX_REGISTRY_ENTRIES) {
+        return fail('bound_exceeded', `registry already holds ${registry.length} entries (bound ${TIER_MAX_REGISTRY_ENTRIES}); an unbounded taxonomy is not explainable`);
+    }
+    const tierId = requiredText('tier_id', input?.tier_id, 'binding_incomplete');
+    if (!tierId.ok)
+        return tierId;
+    const cityKey = normalizeTierKey(input?.city_key, 'city_key');
+    if (!cityKey.ok)
+        return cityKey;
+    const scenarioKey = normalizeTierKey(input?.scenario_key, 'scenario_key');
+    if (!scenarioKey.ok)
+        return scenarioKey;
+    const version = requiredText('taxonomy_version', input?.taxonomy_version, 'binding_incomplete');
+    if (!version.ok)
+        return version;
+    const modifier = input?.modifier_ppm;
+    if (typeof modifier !== 'number' || !Number.isInteger(modifier)) {
+        return fail('modifier_bounds', `modifier_ppm must be an integer ppm, got ${JSON.stringify(modifier)} (floats drift; ppm integers are exact)`);
+    }
+    if (modifier < TIER_MODIFIER_PPM_MIN || modifier > TIER_MODIFIER_PPM_MAX) {
+        return fail('modifier_bounds', `modifier_ppm ${modifier} is outside the declared bounds [${TIER_MODIFIER_PPM_MIN},${TIER_MODIFIER_PPM_MAX}] (lower bound is > 0 by design: a tier may reorder, never annihilate a candidate)`);
+    }
+    const surface = input?.applies_to ?? 'ranking';
+    if (!TIER_APPLICATION_SURFACES.includes(surface)) {
+        return fail('closed_set', `applies_to must be one of [${TIER_APPLICATION_SURFACES.join('/')}], got ${JSON.stringify(surface)} — memory never enters a hard filter (memory-design §1.3)`);
+    }
+    const prov = input?.provenance;
+    if (prov === null || typeof prov !== 'object') {
+        return fail('provenance_required', 'provenance is mandatory: a tier without a stated evidence source is not evidence');
+    }
+    if (!TIER_EVIDENCE_GRADES.includes(prov['evidence_grade'])) {
+        return fail('closed_set', `provenance.evidence_grade must be one of [${TIER_EVIDENCE_GRADES.join('/')}], got ${JSON.stringify(prov['evidence_grade'])}`);
+    }
+    if (!TIER_SAMPLE_SOURCES.includes(prov['sample_source'])) {
+        return fail('closed_set', `provenance.sample_source must be one of [${TIER_SAMPLE_SOURCES.join('/')}], got ${JSON.stringify(prov['sample_source'])} — fixture/synthetic/model-authored samples are refused (#339: 不凭 fixture 造画像)`);
+    }
+    const refs = prov['sample_refs'];
+    if (!Array.isArray(refs) || refs.length < TIER_MIN_SAMPLE_REFS || !refs.every(r => typeof r === 'string' && r.trim() !== '')) {
+        return fail('provenance_required', `provenance.sample_refs must list at least ${TIER_MIN_SAMPLE_REFS} non-empty reviewable sample references, got ${JSON.stringify(refs)} (a single anecdote is not a tier)`);
+    }
+    const reviewer = requiredText('provenance.reviewer', prov['reviewer'], 'provenance_required');
+    if (!reviewer.ok)
+        return reviewer;
+    const frozenAt = requiredInstant('provenance.frozen_at', prov['frozen_at']);
+    if (!frozenAt.ok)
+        return frozenAt;
+    const ret = input?.retirement;
+    if (ret === null || typeof ret !== 'object') {
+        return fail('retirement_required', 'retirement is mandatory: a tier that cannot expire is not evidence (#339 acceptance 1 requires a retirement condition per class)');
+    }
+    const condition = requiredText('retirement.condition', ret['condition'], 'retirement_required');
+    if (!condition.ok)
+        return condition;
+    const reviewBy = requiredInstant('retirement.review_by', ret['review_by']);
+    if (!reviewBy.ok)
+        return reviewBy;
+    if (reviewBy.value <= frozenAt.value) {
+        return fail('retirement_required', `retirement.review_by ${reviewBy.value} must postdate provenance.frozen_at ${frozenAt.value}`);
+    }
+    if (registry.some(e => e.tier_id === tierId.value)) {
+        return fail('duplicate_tier', `tier_id ${tierId.value} already exists in the registry`);
+    }
+    if (registry.some(e => e.city_key === cityKey.value && e.scenario_key === scenarioKey.value)) {
+        return fail('duplicate_tier', `(city ${cityKey.value}, scenario ${scenarioKey.value}) already carries a tier; a second weight for the same pair is conflicting evidence, not an additional tier`);
+    }
+    return pass(Object.freeze({
+        schema: CITY_SCENARIO_TIER_SCHEMA,
+        tier_id: tierId.value,
+        city_key: cityKey.value,
+        scenario_key: scenarioKey.value,
+        modifier_ppm: modifier,
+        applies_to: surface,
+        provenance: Object.freeze({
+            evidence_grade: prov['evidence_grade'],
+            sample_source: prov['sample_source'],
+            sample_refs: Object.freeze([...refs]),
+            reviewer: reviewer.value,
+            frozen_at: frozenAt.value,
+        }),
+        retirement: Object.freeze({ condition: condition.value, review_by: reviewBy.value }),
+        taxonomy_version: version.value,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Resolution: neutral fallback, never a guess
+// ---------------------------------------------------------------------------
+export const TIER_NEUTRAL_REASONS = [
+    'trigger_not_fired',
+    'empty_registry',
+    'unknown_city',
+    'unknown_scenario',
+    'conflicting_evidence',
+];
+function neutral(reason, explanation, conflicting = []) {
+    return Object.freeze({
+        status: 'neutral',
+        modifier_ppm: TIER_MODIFIER_PPM_NEUTRAL,
+        tier_id: null,
+        reason,
+        conflicting_tier_ids: Object.freeze([...conflicting]),
+        explanation,
+    });
+}
+/**
+ * Resolve the bounded modifier for one (city, scenario) pair.
+ *
+ * Returns NEUTRAL (×1.0) with a stated reason for: trigger not fired, empty
+ * registry, unknown city, unknown scenario, and conflicting evidence. Conflicting
+ * entries never elect a winner (geo-atlas `ambiguous` discipline). A malformed key
+ * is a caller error and is reported as such rather than silently neutralized.
+ */
+export function resolveTier(query, options) {
+    const cityKey = normalizeTierKey(query?.cityKey, 'cityKey');
+    if (!cityKey.ok)
+        return cityKey;
+    const scenarioKey = normalizeTierKey(query?.scenarioKey, 'scenarioKey');
+    if (!scenarioKey.ok)
+        return scenarioKey;
+    const triggerFired = options?.triggerFired ?? CITY_SCENARIO_TIER_TRIGGER_FIRED;
+    if (!triggerFired) {
+        return pass(neutral('trigger_not_fired', '#339 trigger has not fired; every city×scenario pair resolves to the neutral modifier ×1.0 (no tier is guessed)'));
+    }
+    const registry = options?.registry ?? CITY_SCENARIO_TIER_REGISTRY;
+    if (registry.length === 0) {
+        return pass(neutral('empty_registry', 'the taxonomy registry is empty; neutral ×1.0 (an empty taxonomy is not a zero weight)'));
+    }
+    const cityMatches = registry.filter(e => e.city_key === cityKey.value);
+    if (cityMatches.length === 0) {
+        return pass(neutral('unknown_city', `city '${cityKey.value}' carries no tier in taxonomy; neutral ×1.0 (an unknown city is never guessed from a neighbour)`));
+    }
+    const matches = cityMatches.filter(e => e.scenario_key === scenarioKey.value);
+    if (matches.length === 0) {
+        return pass(neutral('unknown_scenario', `scenario '${scenarioKey.value}' carries no tier for city '${cityKey.value}'; neutral ×1.0 (an unknown scenario is never approximated by another scenario)`));
+    }
+    if (matches.length > 1) {
+        return pass(neutral('conflicting_evidence', `city '${cityKey.value}' × scenario '${scenarioKey.value}' carries ${matches.length} conflicting tiers; neutral ×1.0 and no winner is elected (conflict is surfaced, never resolved by guessing)`, matches.map(e => e.tier_id)));
+    }
+    const entry = matches[0];
+    if (entry.modifier_ppm < TIER_MODIFIER_PPM_MIN || entry.modifier_ppm > TIER_MODIFIER_PPM_MAX) {
+        return fail('modifier_bounds', `registry entry ${entry.tier_id} carries modifier_ppm ${entry.modifier_ppm} outside the declared bounds [${TIER_MODIFIER_PPM_MIN},${TIER_MODIFIER_PPM_MAX}] — a defective registry entry is refused, never clamped silently`);
+    }
+    return pass(Object.freeze({
+        status: 'hit',
+        modifier_ppm: entry.modifier_ppm,
+        tier_id: entry.tier_id,
+        taxonomy_version: entry.taxonomy_version,
+        evidence_grade: entry.provenance.evidence_grade,
+        explanation: `tier ${entry.tier_id} (${entry.taxonomy_version}, evidence ${entry.provenance.evidence_grade}) applies ×${(entry.modifier_ppm / 1_000_000).toFixed(6)} to the ranking score of city '${entry.city_key}' under scenario '${entry.scenario_key}'; retire when: ${entry.retirement.condition}`,
+    }));
+}
+/**
+ * Apply tier modifiers to a candidate ranking.
+ *
+ * There is deliberately NO filter, exclude, drop or threshold parameter and no
+ * such field in the result: the returned array always contains exactly the input
+ * candidates (same ids, same count), only reordered. `semantic` is preserved on
+ * every output row so a caller can always recover the unmodified ranking.
+ * Ties keep declaration order (stable).
+ */
+export function applyTierRanking(candidates, context, options) {
+    if (!Array.isArray(candidates))
+        return fail('bad_candidate', 'candidates must be an array');
+    const seen = new Set();
+    for (const c of candidates) {
+        if (c === null || typeof c !== 'object' || typeof c.id !== 'string' || c.id.trim() === '') {
+            return fail('bad_candidate', `every candidate needs a non-empty id, got ${JSON.stringify(c)}`);
+        }
+        if (seen.has(c.id))
+            return fail('bad_candidate', `duplicate candidate id ${c.id} (ranking inputs must be a set)`);
+        seen.add(c.id);
+        if (typeof c.semantic !== 'number' || !Number.isFinite(c.semantic)) {
+            return fail('bad_candidate', `candidate ${c.id} semantic score must be finite, got ${String(c.semantic)}`);
+        }
+        if (c.semantic < 0) {
+            return fail('bad_candidate', `candidate ${c.id} semantic score must be non-negative, got ${String(c.semantic)} — the ranking contract is multiplicative, so a negative score would invert every modifier (a boost would demote)`);
+        }
+    }
+    const ranked = [];
+    for (const c of candidates) {
+        const resolution = resolveTier({ cityKey: c.cityKey, scenarioKey: context?.scenarioKey }, options);
+        if (!resolution.ok)
+            return resolution;
+        const r = resolution.value;
+        ranked.push(Object.freeze({
+            id: c.id,
+            semantic: c.semantic,
+            modifier_ppm: r.modifier_ppm,
+            score: (c.semantic * r.modifier_ppm) / 1_000_000,
+            tier_id: r.status === 'hit' ? r.tier_id : null,
+            explanation: r.explanation,
+        }));
+    }
+    const ordered = ranked
+        .map((row, index) => ({ row, index }))
+        .sort((a, b) => (b.row.score - a.row.score) || (a.index - b.index))
+        .map(({ row }) => row);
+    // Structural invariant: ranking never removes a candidate.
+    if (ordered.length !== candidates.length || !candidates.every(c => ordered.some(r => r.id === c.id))) {
+        return fail('bad_candidate', 'internal invariant violated: tier ranking must preserve the candidate set exactly (memory never enters a hard filter)');
+    }
+    return pass(Object.freeze([...ordered]));
+}
+/**
+ * Mechanical no-hard-filter check a caller (or a gate) can run: the ranked output
+ * must contain exactly the input candidate ids. Returns a violation string, or null.
+ */
+export function tierRankingFilterViolation(before, after) {
+    if (before.length !== after.length) {
+        return `tier ranking changed the candidate count ${before.length} → ${after.length}: memory may reorder, never filter (memory-design §1.3)`;
+    }
+    const missing = before.filter(c => !after.some(r => r.id === c.id)).map(c => c.id);
+    if (missing.length > 0)
+        return `tier ranking dropped candidates [${missing.join(',')}]: memory may reorder, never filter`;
+    const added = after.filter(r => !before.some(c => c.id === r.id)).map(r => r.id);
+    if (added.length > 0)
+        return `tier ranking invented candidates [${added.join(',')}]`;
+    return null;
+}

package/dist/src/dsh-llm.js

@@ -1,7 +1,8 @@
 /**
  * 真 LlmPort:OpenAI 兼容接口的 provider 中立适配器(DeepSeek/MiniMax-M2 实测)。
  * 零新依赖(node 内建 fetch)。环境变量:LLM_API_KEY/LLM_BASE_URL/LLM_MODEL
- * (兼容旧 DEEPSEEK_* 别名)。MiniMax-M2 是推理模型:输出带 <think> 块,
+ * (兼容旧 DEEPSEEK_* 别名);GOTRY_LLM_TIMEOUT_MS = 单次请求总预算(默认 300000ms,
+ * 非正整数忽略)。MiniMax-M2 是推理模型:输出带 <think> 块,
  * 必须先剥离再解析——JSON 藏在 think 里是常见失败模式。
  * 无 key 时抛出明确错误,replay-real 自动回退 mock(ADR-8)。
  * 责任铁律不变:本适配器只做翻译/润色/解释,判定与算术在确定性组件。
@@ -17,12 +18,73 @@ const base = () => (process.env['LLM_BASE_URL'] ?? process.env['DEEPSEEK_BASE_UR
 function emptyUsage() {
     return { calls: 0, inputTokens: 0, outputTokens: 0, inputCacheHitTokens: 0, inputCacheMissTokens: 0, responsesMissingUsage: 0 };
 }
-async function chat(messages, json, usage) {
+/** 单次请求(连接→响应头→正文读完)的默认总预算:对推理模型足够宽松,只兜「连上了却永不应答」的卡死。 */
+export const DEFAULT_LLM_TIMEOUT_MS = 300_000;
+/**
+ * 超时上限 = 2^31-1 ms(≈24.8 天)。Node 对更大的延迟会溢出并**悄悄改成 1ms**
+ * (TimeoutOverflowWarning),即「配得越大越立刻超时」——所以必须夹住,绝不原样透传。
+ */
+const MAX_LLM_TIMEOUT_MS = 2_147_483_647;
+/** 只认十进制正整数(数值或纯数字串);其余(0/负数/小数/NaN/带单位/空串)一律 undefined——绝不退化成「无超时」。 */
+function parseTimeoutMs(raw) {
+    const n = typeof raw === 'string' ? (/^\d+$/.test(raw.trim()) ? Number(raw.trim()) : Number.NaN) : raw;
+    return typeof n === 'number' && Number.isSafeInteger(n) && n > 0 ? Math.min(n, MAX_LLM_TIMEOUT_MS) : undefined;
+}
+/** 解析顺序:本次调用显式值 > 环境变量 GOTRY_LLM_TIMEOUT_MS(调用时取值,同 base()/model())> 默认值。 */
+export function resolveLlmTimeoutMs(callMs) {
+    return parseTimeoutMs(callMs) ?? parseTimeoutMs(process.env['GOTRY_LLM_TIMEOUT_MS']) ?? DEFAULT_LLM_TIMEOUT_MS;
+}
+/**
+ * chat() 请求被截断(超时 / 调用方取消)的类型化失败——不是挂起,也不会被吞。
+ * 与既有错误形态一致,而非另起一套:
+ *  - message 沿用本模块 `llm <kind>: <detail>` 约定(同 `llm 429: …`),只读 .message 的调用方
+ *    (nightly-evidence / persona-sim / time-eval --real)原样可用;
+ *  - name 取平台既有名 TimeoutError / AbortError(AbortSignal.timeout 与手动 abort 抛的同名),
+ *    persona-sim、channel-probe 等按 name 分类的代码零改动即可识别;
+ *  - cause 保留 fetch 抛出的原始错误(调用方自定义的 abort reason 也在其中)。
+ * HTTP 非 2xx(`llm <status>`)、DNS/连接重置、坏 JSON 仍是原样的普通 Error——只改写「被我们的 signal 终止」的失败。
+ */
+export class LlmRequestError extends Error {
+    code;
+    /** 本次生效的超时预算;仅 code === 'timeout' 有值 */
+    timeoutMs;
+    constructor(code, detail, options = {}) {
+        super(`llm ${code}: ${detail}`, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = code === 'timeout' ? 'TimeoutError' : 'AbortError';
+        this.code = code;
+        this.timeoutMs = options.timeoutMs;
+    }
+}
+/**
+ * 发一次请求并读完正文。**同一个 signal 贯穿 fetch 与 res.json()/res.text()**,所以超时覆盖整个请求
+ * (含「响应头已到、正文卡住」与「非 2xx 的错误正文卡住」),调用方取消同理。
+ * 只有「被我们的 signal 终止」才改写成 LlmRequestError;其余错误原样上抛。
+ */
+async function requestCompletion(url, init, request) {
+    const timeoutMs = resolveLlmTimeoutMs(request.timeoutMs);
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = request.signal ? AbortSignal.any([request.signal, timeout]) : timeout;
+    try {
+        const res = await fetch(url, { method: 'POST', headers: init.headers, body: init.body, signal });
+        if (!res.ok)
+            return { ok: false, status: res.status, text: await res.text() };
+        return { ok: true, data: await res.json() };
+    }
+    catch (error) {
+        if (!signal.aborted)
+            throw error;
+        // AbortSignal.any 的 reason 是最先触发的那个源的 reason:等于超时信号的 reason 即超时先到,否则是调用方取消
+        if (timeout.aborted && signal.reason === timeout.reason) {
+            throw new LlmRequestError('timeout', `no complete response within ${timeoutMs}ms (GOTRY_LLM_TIMEOUT_MS)`, { cause: error, timeoutMs });
+        }
+        throw new LlmRequestError('aborted', "request cancelled by the caller's AbortSignal", { cause: error });
+    }
+}
+async function chat(messages, json, usage, request = {}) {
     const key = process.env['LLM_API_KEY'] ?? process.env['DEEPSEEK_API_KEY'];
     if (!key)
         throw new Error('LLM_API_KEY 未设置(兼容 DEEPSEEK_API_KEY 别名)——真 LLM 路径不可用,请回退 mock(ADR-8)');
-    const res = await fetch(`${base()}/chat/completions`, {
-        method: 'POST',
+    const reply = await requestCompletion(`${base()}/chat/completions`, {
         headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
         body: JSON.stringify({
             model: model(),
@@ -30,10 +92,10 @@ async function chat(messages, json, usage) {
             ...(json ? { response_format: { type: 'json_object' } } : {}),
             temperature: json ? 0 : 0.7,
         }),
-    });
-    if (!res.ok)
-        throw new Error(`llm ${res.status}: ${(await res.text()).slice(0, 300)}`);
-    const data = await res.json();
+    }, request);
+    if (!reply.ok)
+        throw new Error(`llm ${reply.status}: ${reply.text.slice(0, 300)}`);
+    const data = reply.data;
     if (usage) {
         usage.calls += 1;
         const u = data.usage;
@@ -75,7 +137,11 @@ const SKELETON_SYSTEM = `你是行程骨架抽取器。从对话中抽取行程
 输出 JSON:{"scenario":"erhai|workation|yunnan|generic","segments":[{"id":"f1","role":"choice|fixed","route":"HKG->HKT","dateHint":"2026-07-18","anchors":{"arriveByMin":885}}]}
 规则:每个跨城移动一段;锚点只放用户明说或必然的(如"当天到"→arriveByMin 23:59=1439);时刻用当日分钟。
 scenario 判定:「洱海/大理/千岛湖/太湖+选目的地」→erhai(候选集);「普吉/workation/远程办公+多城链」→workation(五段链);「云南/大理丽江」→yunnan;不确定→generic。只输出 JSON。`;
-export function createOpenAICompatLlm(flightPackPath, clock = () => new Date()) {
+/**
+ * request:本端口每次 chat() 共用的请求级选项(timeoutMs / signal)。signal 是端口级取消——
+ * 调用方可借它在会话/批次截止时真正掐断在途请求,而不是放着它继续挂在 provider 上。
+ */
+export function createOpenAICompatLlm(flightPackPath, clock = () => new Date(), request = {}) {
     const pack = flightPackPath;
     const usage = emptyUsage();
     const historyText = (h) => h.map(t => `${t.role === 'user' ? '用户' : '助手'}: ${t.text}`).join('\n');
@@ -84,7 +150,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = () => new Date())
     const anchorContext = () => `时间锚点卡:\n${buildTimeAnchor(clock()).card}`;
     return {
         async extractFacts(history) {
-            const out = await chat([{ role: 'system', content: FACTS_SYSTEM }, { role: 'user', content: `${anchorContext()}\n\n${historyText(history)}` }], true, usage);
+            const out = await chat([{ role: 'system', content: FACTS_SYSTEM }, { role: 'user', content: `${anchorContext()}\n\n${historyText(history)}` }], true, usage, request);
             const obj = parseJsonBlock(out);
             if (!obj)
                 return { assumptions: [] };
@@ -96,7 +162,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = () => new Date())
         async extractSpec(history, state) {
             // 架构(ADR-10):LLM 只产骨架与锚点;班次数据永远来自能力层(数据包/未来实时API)
             const context = `${anchorContext()}\n已断言日历:${JSON.stringify(state.calendar.assertedWeekdays)}\nprofile:${JSON.stringify(state.profile)}`;
-            const out = await chat([{ role: 'system', content: SKELETON_SYSTEM }, { role: 'user', content: `${context}\n\n${historyText(history)}` }], true, usage);
+            const out = await chat([{ role: 'system', content: SKELETON_SYSTEM }, { role: 'user', content: `${context}\n\n${historyText(history)}` }], true, usage, request);
             const skeleton = parseJsonBlock(out);
             if (!skeleton || !Array.isArray(skeleton['segments']) || skeleton['segments'].length === 0)
                 return null;
@@ -126,7 +192,11 @@ export function createOpenAICompatLlm(flightPackPath, clock = () => new Date())
                 }
                 packSpec = parseFlightPackToSpec(JSON.parse(await readFile(packPath, 'utf-8')));
             }
-            catch {
+            catch (e) {
+                // issue #620:数据包被 parse 边界拒收时,原因必须留痕——否则用户只看到
+                // 「骨架还不完整」,运维看不到是哪个包的哪个字段把求解面挡住了。
+                const err = e;
+                console.error(`[gotry] extractSpec: 数据包不可用 ${packPath}(${err.code ?? 'parse_failed'}):`, (err.message ?? '').slice(0, 200));
                 return null;
             }
             const anchorsById = new Map(skeleton['segments'].map(s => [String(s['id'] ?? ''), (s['anchors'] ?? {})]));
@@ -142,7 +212,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = () => new Date())
         async extractSlots(history, now) {
             // now 可注入(评测固定锚点);过期判定在 flagExpiredSlots(代码层),模型只管逐字抽取
             const anchor = buildTimeAnchor(now ?? clock());
-            const out = await chat([{ role: 'system', content: buildSlotSystem(anchor) }, { role: 'user', content: historyText(history) }], true, usage);
+            const out = await chat([{ role: 'system', content: buildSlotSystem(anchor) }, { role: 'user', content: historyText(history) }], true, usage, request);
             const obj = parseJsonBlock(out);
             if (!obj)
                 return null;
@@ -152,7 +222,7 @@ export function createOpenAICompatLlm(flightPackPath, clock = () => new Date())
         },
         async polishQuestion(q) {
             const out = await chat([{ role: 'system', content: '把旅行规划的追问润色得更自然,保留全部信息(含为什么问),一两句话,不要加表情。' },
-                { role: 'user', content: `【${q.key}】${q.text}(为什么问:${q.why})` }], false, usage);
+                { role: 'user', content: `【${q.key}】${q.text}(为什么问:${q.why})` }], false, usage, request);
             return out.trim() || `【${q.key}】${q.text}`;
         },
         usage,