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

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

@@ -3,7 +3,7 @@
  * 运行(在 ts/ 下):npx tsx scripts/unified-tests.ts
  */
 import assert from 'node:assert/strict';
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseFlightPackToSpec, solveUnified } from '../src/unified.js';
 import { hhmmToMin } from '../src/model.js';
@@ -50,4 +50,81 @@ 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 / #635:云南包的 yn0 衔接段缺 buffer_min/origin_transfer_min/dest_transfer_min
+//    → 旧实现 Number(undefined)=NaN → Int.val(NaN) 在 z3 WASM 里 `Assertion failed`
+//    → 被兜底翻译成「不可行 + unsat_core:['wasm_runtime_error']」。五条红线:
+//    ① 出厂数据包里挂接引擎的每一段(`legs`)三字段必须是非负整数;缺真值的段只能记在
+//       `advisory_legs`(带理由、不挂接)——替它填数等于编造真实世界的事实(ADR-10);
+//    ② 出厂云南包整包可判定,yn0 不进求解(founder 2026-10-05 选「标 advisory」);
+//    ③ 防线仍在:缺字段的包(由测试构造)必须以 solver_error 返回而**绝不**是 infeasible;
+//    ④ 最小输入:健康包里塞一个 NaN 接驳分钟 → 同样是 solver_error;
+//    ⑤ 晋升路径:founder 给出三个真值后,把 advisory 段搬回 legs 即可整包判定。
+const DATA_DIR = join('..', 'data');
+const TRANSFER_FIELDS = ['buffer_min', 'origin_transfer_min', 'dest_transfer_min'];
+const yunnanRaw = JSON.parse(await readFile(join(DATA_DIR, 'yunnan-pack.json'), 'utf-8'));
+// ① 数据完整性:data/ 下每个带 legs 的包,挂接引擎的段三字段齐全;advisory 段自带理由且不与 legs 重名
+let auditedPacks = 0;
+for (const file of (await readdir(DATA_DIR)).filter(f => f.endsWith('.json')).sort()) {
+    const raw = JSON.parse(await readFile(join(DATA_DIR, file), 'utf-8'));
+    if (!Array.isArray(raw['legs']))
+        continue;
+    auditedPacks += 1;
+    const legs = raw['legs'];
+    for (const leg of legs) {
+        for (const field of TRANSFER_FIELDS) {
+            const value = leg[field];
+            assert.ok(typeof value === 'number' && Number.isInteger(value) && value >= 0, `${file}: leg ${String(leg['id'])}.${field} 必须是非负整数(got ${JSON.stringify(value)});缺真值的段请放进 advisory_legs,不要补编造值(issue #635)`);
+        }
+    }
+    const engineIds = new Set(legs.map(leg => String(leg['id'])));
+    for (const advisory of (raw['advisory_legs'] ?? [])) {
+        const reason = advisory['advisory_reason'];
+        assert.ok(typeof reason === 'string' && reason.trim() !== '', `${file}: advisory 段 ${String(advisory['id'])} 必须写明 advisory_reason`);
+        assert.ok(!engineIds.has(String(advisory['id'])), `${file}: ${String(advisory['id'])} 不能同时在 legs 与 advisory_legs`);
+    }
+}
+assert.ok(auditedPacks >= 2, `数据完整性审计应覆盖航班包与云南包(审计了 ${auditedPacks} 个)`);
+// ② 出厂云南包按产品同款路径整包可判定;advisory 段 yn0 不进引擎段链,也不参与求解
+const yunnanSpec = parseFlightPackToSpec(structuredClone(yunnanRaw));
+assert.deepEqual(yunnanSpec.segments.map(s => s.id), ['yn1', 'yn2', 'yn3', 'yn4'], 'advisory 段 yn0 不得进引擎段链');
+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, `出厂云南包应可行(unsat_core=${JSON.stringify(rYunnan.unsat_core)})`);
+assert.deepEqual(rYunnan.legs.map(l => l.leg), ['yn1', 'yn2', 'yn3', 'yn4'], '四段全判定,yn0 不在其中');
+// ③ 防线仍在:缺三个字段的包(由测试从出厂包构造)→ NaN → 必须是显式 solver_error,绝不是「不可行」
+const yunnanGap = structuredClone(yunnanRaw);
+for (const field of TRANSFER_FIELDS)
+    delete yunnanGap['legs'][0][field];
+const yunnanGapSpec = parseFlightPackToSpec(yunnanGap);
+yunnanGapSpec.budgetCny = 9000;
+assert.ok(Number.isNaN(yunnanGapSpec.segments[0].options[0].move.bufferMin), '缺 buffer_min 的事实前提');
+const rYunnanGap = await solveUnified(yunnanGapSpec);
+assert.equal(rYunnanGap.solver_error?.code, 'solver_input_not_integer', `缺字段的包必须以 solver_error 返回(got ${JSON.stringify(rYunnanGap)})`);
+assert.ok(rYunnanGap.solver_error.message.includes('yn1.bufferMin'), `solver_error 必须点名出问题的段与字段(got ${rYunnanGap.solver_error.message})`);
+assert.equal(rYunnanGap.feasible, false, 'solver_error 轮次没有产出可行解');
+assert.deepEqual(rYunnanGap.unsat_core, undefined, '求解器失败不得伪造 unsat_core(机器 token 不进冲突位)');
+assert.ok(!JSON.stringify(rYunnanGap).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 轮次没有产出可行解');
+// ⑤ 晋升路径:三个真值由测试提供(数据包里不写——真值待 founder 校准),把 advisory 段搬回 legs 的头部
+//    → 五段全判定,证明「补齐三个整数」正是 yn0 从 advisory 晋升所需的全部
+const yunnanPromoted = structuredClone(yunnanRaw);
+const [promotedYn0] = yunnanPromoted['advisory_legs'];
+delete promotedYn0['advisory_reason'];
+Object.assign(promotedYn0, { buffer_min: 60, origin_transfer_min: 30, dest_transfer_min: 30 });
+yunnanPromoted['legs'] = [promotedYn0, ...yunnanPromoted['legs']];
+delete yunnanPromoted['advisory_legs'];
+const promotedSpec = parseFlightPackToSpec(yunnanPromoted);
+promotedSpec.budgetCny = 9000;
+const rPromoted = await solveUnified(promotedSpec);
+assert.equal(rPromoted.solver_error, undefined, `补齐三字段后不得再有求解器失败(got ${JSON.stringify(rPromoted.solver_error)})`);
+assert.equal(rPromoted.feasible, true, `晋升后的云南包应可行(unsat_core=${JSON.stringify(rPromoted.unsat_core)})`);
+assert.equal(rPromoted.legs.length, 5, '晋升后五段全判定');
+console.log(`TS UNIFIED TESTS: 5/5 OK(工作窗口生效,f2=VZ303,¥${r1.money_cny};#620/#635 ${auditedPacks} 个包三字段齐全,出厂云南包四段可行,缺字段→solver_error 点名 yn1,晋升后五段可行)`);

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/backend/modules/session-search.js

@@ -384,7 +384,7 @@ export function startSessionSearchModule(options) {
         if (!queue.extensionConnected()) {
             sendJson(res, 200, {
                 ok: true,
-                suppliers: [{ supplier: 'dida-portal', loggedIn: false, reason: 'extension-not-connected', detail: '会话执行环境=管理员浏览器扩展(GoTry Session Bridge);扩展未连接桥——在管理员浏览器安装扩展并配置本服务桥地址' }],
+                suppliers: [{ supplier: 'dida-portal', loggedIn: false, reason: 'extension-not-connected', detail: '会话执行环境=管理员浏览器扩展(Stai Travel Bridge);扩展未连接桥——在管理员浏览器安装扩展并配置本服务桥地址' }],
                 bridge: queue.stats(),
                 checkedAt,
             });

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;
+}