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

package/dist/capabilities/fx-contract.js

@@ -0,0 +1,293 @@
+/**
+ * Money/FX fact 合同 v1（issue #344 契约切片，创始人 2026-10-02 授权提前启动，默认关闭、零活体汇率源）。
+ *
+ * 形态（对齐 `ts/data/llm-price-table.json` 的 fail-closed 纪律与 gotry_bookable_fact 证据链形态）：
+ *   - 类型化 Money（原币金额 = 币种 + 最小单位整数，杜绝浮点漂移）；
+ *   - 类型化 FxFact（base/quote 汇率事实：rate + provider + provenance + as_of 估值时点 + fetched_at 抓取时刻，
+ *     全字段必填，unknown/missing 一律 fail-closed，禁止猜测汇率——与「未知模型不猜价」同一条纪律）；
+ *   - 主源+降级只做契约 seam（FxProviderDescriptor/FxRateSource 接口与数据形状）：
+ *     运行时注册表冻结为空（LIVE_FX_PROVIDER_DESCRIPTORS = []），FX_TRIGGER_FIRED = false；
+ *     触发前零浮动汇率源被咨询（consultFxSources 在读任何源之前直接结构化拒绝，docs/architecture.md §10 D-26 边界不变）；
+ *   - 同一估值时点比较：跨币种比较/聚合必须经同一 as_of 的规范化值（NormalizedAmount），
+ *     混时点比较显式拒绝（fail-closed 并给出带证据的错误）；无宽限期数值——估值时点绑定即口径，
+ *     stale/miss/error 不得伪装为当前准确换算（不发明容差）。
+ *
+ * 冻结的舍入规则：仅在「换算落位到目标币种最小单位」这一步舍入，half-away-from-zero；
+ * 交叉汇率（经中转币两腿）每腿落位一次（中间腿按中转币最小单位舍入），无中间无理数携带。
+ *
+ * 边界（D-26 / #344 触发后置保持）：
+ *   - 本模块纯函数、零 IO、零网络、零依赖新增；
+ *   - 不选定任何主源/降级源（那是触发后 founders 决策）；注册表非空 + FX_TRIGGER_FIRED 置真
+ *     都需要真实非 CNY 供应商报价、用户预算或目的地需求触发后另行准入；
+ *   - CNY-only 结算路径不受影响（现有 budgetCny/priceCny 算术不动，ts/src/model.ts 内核钉住未改）。
+ *
+ * @module capabilities/fx-contract
+ */
+import { makeFactId } from '../src/bookable-facts.js';
+/** 合同 schema 标识（版本化，读取端校验）。 */
+export const FX_FACT_SCHEMA = 'gotry_fx_fact.v1';
+/** 币种封闭集：ISO 4217 字母码 → 最小单位指数（客观公共标准数据，类比 IANA 时区名的运行时权威口径；
+ * 未知币种不在集内即 fail-closed，不做任何猜测映射）。 */
+const ISO_4217_MINOR_UNIT_EXPONENTS = {
+    CNY: 2, USD: 2, EUR: 2, GBP: 2, HKD: 2, SGD: 2, THB: 2, MYR: 2,
+    JPY: 0, KRW: 0,
+};
+/** 合同违规（fail-closed）：消息必须带证据（两侧估值时点/fact_id/provider 等）。 */
+export class FxContractError extends Error {
+    constructor(message) {
+        super(`fx contract: ${message} (fail-closed, no guessed rate)`);
+        this.name = 'FxContractError';
+    }
+}
+/** 解析并准入币种：必须是大写三字母且在封闭集内；未知/小写/变体一律拒绝。 */
+export function parseCurrency(code) {
+    if (typeof code !== 'string' || !/^[A-Z]{3}$/.test(code)) {
+        throw new FxContractError(`currency code must be an uppercase 3-letter ISO 4217 code, got: ${JSON.stringify(code)}`);
+    }
+    const exponent = ISO_4217_MINOR_UNIT_EXPONENTS[code];
+    if (exponent === undefined) {
+        throw new FxContractError(`unknown currency code ${code} not in the frozen closed set [${Object.keys(ISO_4217_MINOR_UNIT_EXPONENTS).join('/')}] — extend the set via PR`);
+    }
+    return code;
+}
+/** 币种最小单位指数（ISO 4217）。 */
+export function currencyExponent(currency) {
+    const exponent = ISO_4217_MINOR_UNIT_EXPONENTS[currency];
+    if (exponent === undefined)
+        throw new FxContractError(`unknown currency ${currency}`);
+    return exponent;
+}
+/** 严格十进制金额解析：`-?(0|[1-9][0-9]*)(\.[0-9]+)?`——无千分位、无指数记法、
+ * 小数位不得超过币种最小单位指数（JPY「0.5」即拒）。 */
+export function parseMoney(currency, decimal) {
+    const cur = parseCurrency(currency);
+    if (typeof decimal !== 'string' || !/^-?(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(decimal)) {
+        throw new FxContractError(`money decimal for ${cur} must be a plain decimal like '1234.56' (no separators/exponent/plus), got: ${JSON.stringify(decimal)}`);
+    }
+    const negative = decimal.startsWith('-');
+    const unsigned = negative ? decimal.slice(1) : decimal;
+    const [intPart, fracPart = ''] = unsigned.split('.');
+    const exponent = currencyExponent(cur);
+    if (fracPart.length > exponent) {
+        throw new FxContractError(`money decimal ${decimal} for ${cur} exceeds its ${exponent}-digit minor unit (sub-minor precision rejected, no silent rounding)`);
+    }
+    const padded = (fracPart + '0'.repeat(exponent)).slice(0, exponent);
+    const magnitude = BigInt(intPart + padded);
+    return { currency: cur, amountMinor: negative ? -magnitude : magnitude };
+}
+/** 原币展示（验收 3：保留原币展示与供应商金额）。 */
+export function formatMoney(money) {
+    const exponent = currencyExponent(money.currency);
+    const negative = money.amountMinor < 0n;
+    const magnitude = negative ? -money.amountMinor : money.amountMinor;
+    const digits = magnitude.toString().padStart(exponent + 1, '0');
+    const body = exponent === 0 ? digits : `${digits.slice(0, -exponent)}.${digits.slice(-exponent)}`;
+    return `${negative ? '-' : ''}${body} ${money.currency}`;
+}
+/** UTC 时刻解析与规范化：接受完整 ISO-8601 时刻（含 Z/偏移），规范化为毫秒精度 UTC ISO 串；
+ * 仅日期（无时刻）、垃圾串、缺值一律拒绝（缺时刻 fail-closed）。 */
+export function parseUtcInstant(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new FxContractError(`${label} must be a non-empty ISO-8601 UTC instant string, got: ${JSON.stringify(value)}`);
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value.trim())) {
+        throw new FxContractError(`${label} must carry a full time-of-day (date-only '${value}' is not a valuation instant — mixed-date comparison would be ambiguous)`);
+    }
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms)) {
+        throw new FxContractError(`${label} is not a parseable ISO-8601 instant: ${JSON.stringify(value)}`);
+    }
+    return new Date(ms).toISOString();
+}
+/** 汇率严格十进制解析：无符号、无指数记法、必须严格大于 0（零/负汇率不是事实）、小数位 ≤ 12。
+ * 返回归一化字符串（去尾零）+ 分子 + 小数位，供精确 bigint 换算与 fact_id 幂等。 */
+function parseRateDecimal(rate) {
+    if (typeof rate !== 'string' || !/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(rate)) {
+        throw new FxContractError(`fx rate must be a plain positive decimal like '7.25' (no sign/exponent/separators), got: ${JSON.stringify(rate)}`);
+    }
+    const [intPart, fracPart = ''] = rate.split('.');
+    if (fracPart.length > 12) {
+        throw new FxContractError(`fx rate ${rate} exceeds 12 fractional digits (absurd precision is not evidence)`);
+    }
+    const trimmedFrac = fracPart.replace(/0+$/, '');
+    const normalized = trimmedFrac.length === 0 ? intPart : `${intPart}.${trimmedFrac}`;
+    const numerator = BigInt(intPart + trimmedFrac);
+    if (numerator <= 0n) {
+        throw new FxContractError(`fx rate must be strictly positive, got: ${rate} (zero/negative rate is never a valid conversion fact)`);
+    }
+    return { normalized, numerator, scale: trimmedFrac.length };
+}
+/** 精确除法 + half-away-from-zero 落位（冻结舍入规则的实现核心）。 */
+function roundDivHalfAwayFromZero(n, d) {
+    const sign = n < 0n ? -1n : 1n;
+    const magnitude = n < 0n ? -n : n;
+    const q = magnitude / d;
+    const rem = magnitude % d;
+    return sign * (rem * 2n >= d ? q + 1n : q);
+}
+/** 运行时源注册表：冻结为空（触发后置，D-26 边界不变）。任何非空变更都是创始人准入决策。 */
+export const LIVE_FX_PROVIDER_DESCRIPTORS = [];
+/** FX 实现触发闸：冻结为 false。置真 = 首条真实非 CNY 供应商报价、用户预算或目的地需求已出现（#344 触发条件）。 */
+export const FX_TRIGGER_FIRED = false;
+/** 咨询活体汇率源的唯一入口。触发未开（FX_TRIGGER_FIRED=false）时在读任何源之前直接结构化拒绝
+ * （零浮动汇率源被咨询）；触发后按 primary→fallback 顺位，且每条结果仍必须过 buildFxFact 全字段校验。 */
+export async function consultFxSources(query, options) {
+    const triggerFired = options?.triggerFired ?? FX_TRIGGER_FIRED;
+    const sources = options?.sources ?? [];
+    if (!triggerFired) {
+        return {
+            ok: false,
+            code: 'trigger-deferred',
+            detail: 'FX implementation trigger has not fired (#344: first real non-CNY supplier quote, user budget, or destination demand); zero floating-rate sources consulted (D-26 boundary unchanged)',
+        };
+    }
+    if (sources.length === 0) {
+        return { ok: false, code: 'no-source-admitted', detail: 'no FX provider admitted in the registry; admitting one is a founder decision with legal_basis' };
+    }
+    let lastMiss;
+    for (const source of sources) {
+        const out = await source.fetchRate(query);
+        if (out.ok)
+            return { ok: true, fact: out.fact };
+        lastMiss = out;
+    }
+    return lastMiss ?? { ok: false, code: 'miss', detail: 'no FX source produced a rate' };
+}
+/** 构建汇率事实（全字段必填校验入口，对齐价格表「未知模型即拒」的纪律）。
+ * registry 默认 = 冻结空的运行时注册表 → 生产路径任何 provider 都被拒（来源不明）；
+ * 测试/未来适配器以显式注入的 registry 构造离线事实。 */
+export function buildFxFact(input, registry = LIVE_FX_PROVIDER_DESCRIPTORS) {
+    const base = parseCurrency(input.base);
+    const quote = parseCurrency(input.quote);
+    if (base === quote) {
+        throw new FxContractError(`base and quote must differ (${base}→${quote}); an identity rate would bypass conversion evidence`);
+    }
+    const rate = parseRateDecimal(input.rate);
+    if (typeof input.provider !== 'string' || input.provider.length === 0) {
+        throw new FxContractError(`fx fact provider must be a non-empty source identifier, got: ${JSON.stringify(input.provider)}`);
+    }
+    const descriptor = registry.find(d => d.id === input.provider);
+    if (!descriptor) {
+        throw new FxContractError(`fx fact provider not admitted in the registry: ${JSON.stringify(input.provider)} (来源不明 fail-closed; admitted: [${registry.map(d => d.id).join('/') || 'none'}])`);
+    }
+    if (typeof descriptor.legal_basis !== 'string' || descriptor.legal_basis.length === 0) {
+        throw new FxContractError(`admitted provider ${descriptor.id} carries no legal_basis — registry entry is defective`);
+    }
+    if (typeof input.provenance !== 'string' || input.provenance.length === 0) {
+        throw new FxContractError(`fx fact provenance must be a non-empty evidence-chain description, got: ${JSON.stringify(input.provenance)}`);
+    }
+    const asOf = parseUtcInstant(input.as_of, 'fx fact as_of (估值时点)');
+    const fetchedAt = parseUtcInstant(input.fetched_at, 'fx fact fetched_at (抓取时刻)');
+    if (asOf > fetchedAt) {
+        throw new FxContractError(`fx fact as_of ${asOf} is later than fetched_at ${fetchedAt} — impossible provenance (valuation instant must not postdate observation)`);
+    }
+    return {
+        schema: FX_FACT_SCHEMA,
+        fact_id: makeFactId(['fx', base, quote, descriptor.id, asOf, rate.normalized]),
+        base,
+        quote,
+        rate: rate.normalized,
+        provider: descriptor.id,
+        provenance: input.provenance,
+        as_of: asOf,
+        fetched_at: fetchedAt,
+        rounding: 'minor-unit-half-away-from-zero',
+    };
+}
+/** 原币即比较币时的恒等钉时点：金额不经任何汇率（同币种 rate=1 是恒等式，不是汇率猜测），
+ * 只把估值时点绑定到规范化值上，使原生币种金额能与 FX 规范化金额在同一口径下比较/聚合。 */
+export function pinNativeMoney(money, valuationAsOf) {
+    const pinned = parseUtcInstant(valuationAsOf, 'native pin valuation as_of');
+    return {
+        currency: money.currency,
+        amountMinor: money.amountMinor,
+        valuationAsOf: pinned,
+        fx: { fact_id: `native:${money.currency}`, provider: 'native-identity', base: money.currency, quote: money.currency, rate: '1' },
+        original: money,
+    };
+}
+/** 校验 FxFact 覆盖给定换算对（供应商币种变化/拿错腿在此显式拒绝）。 */
+function assertFactPair(fact, from, to) {
+    if (fact.base !== from || fact.quote !== to) {
+        throw new FxContractError(`fx fact ${fact.fact_id} pair ${fact.base}→${fact.quote} does not cover the requested conversion ${from}→${to} (supplier currency changed or wrong leg — no cross-pair substitution)`);
+    }
+}
+/** 断言 fact 的估值时点等于调用方钉住的估值时点（旧 rate 不得混入新时点比较；无宽限数值，精确绑定）。 */
+function assertPinnedValuation(fact, pinnedAsOf) {
+    if (pinnedAsOf === undefined)
+        return;
+    const pinned = parseUtcInstant(pinnedAsOf, 'pinned valuation as_of');
+    if (fact.as_of !== pinned) {
+        throw new FxContractError(`fx fact ${fact.fact_id} (${fact.base}→${fact.quote}, provider ${fact.provider}) as_of ${fact.as_of} does not match the pinned valuation instant ${pinned} — stale/未对齐 rate 不得当作该时点的准确换算`);
+    }
+}
+function fxRef(fact) {
+    return { fact_id: fact.fact_id, provider: fact.provider, base: fact.base, quote: fact.quote, rate: fact.rate };
+}
+/** 单腿换算：money × rate，仅在目标币最小单位落位时舍入（half-away-from-zero）。
+ * valuationAsOf 可选钉住时点：给了就必须与 fact.as_of 完全一致（混时点 fail-closed）。 */
+export function convertMoney(money, target, fact, valuationAsOf) {
+    const targetCurrency = parseCurrency(target);
+    assertFactPair(fact, money.currency, targetCurrency);
+    assertPinnedValuation(fact, valuationAsOf);
+    const fromExponent = currencyExponent(money.currency);
+    const toExponent = currencyExponent(targetCurrency);
+    const rate = parseRateDecimal(fact.rate);
+    // amountMinor × rateNumerator × 10^toExponent / 10^(fromExponent + rateScale)
+    const numerator = money.amountMinor * rate.numerator * 10n ** BigInt(toExponent);
+    const denominator = 10n ** BigInt(fromExponent + rate.scale);
+    const amountMinor = roundDivHalfAwayFromZero(numerator, denominator);
+    return {
+        currency: targetCurrency,
+        amountMinor,
+        valuationAsOf: fact.as_of,
+        fx: fxRef(fact),
+        original: money,
+    };
+}
+/** 交叉汇率（两腿显式合成）：两腿估值时点必须完全一致（混时点显式拒绝，带两侧证据）；
+ * 中间腿按中转币最小单位落位一次（冻结规则，无隐藏精度携带）。 */
+export function convertMoneyViaPivot(money, pivot, target, legBaseToPivot, legPivotToTarget, valuationAsOf) {
+    if (legBaseToPivot.as_of !== legPivotToTarget.as_of) {
+        throw new FxContractError(`cross-rate legs must share the same valuation instant: leg1 ${legBaseToPivot.base}→${legBaseToPivot.quote} (${legBaseToPivot.provider}, ${legBaseToPivot.fact_id}) as_of ${legBaseToPivot.as_of} vs leg2 ${legPivotToTarget.base}→${legPivotToTarget.quote} (${legPivotToTarget.provider}, ${legPivotToTarget.fact_id}) as_of ${legPivotToTarget.as_of} — 混时点合成拒绝`);
+    }
+    const pivotCurrency = parseCurrency(pivot);
+    const intermediate = convertMoney(money, pivotCurrency, legBaseToPivot, valuationAsOf);
+    const pivotMoney = { currency: pivotCurrency, amountMinor: intermediate.amountMinor };
+    return convertMoney(pivotMoney, target, legPivotToTarget, valuationAsOf);
+}
+/** 混时点/混币种比较的带证据拒绝。 */
+function assertSameComparisonBasis(a, b, op) {
+    if (a.currency !== b.currency) {
+        throw new FxContractError(`${op} requires the same normalized currency: ${a.currency} (fx ${a.fx.provider} ${a.fx.fact_id}) vs ${b.currency} (fx ${b.fx.provider} ${b.fx.fact_id}) — normalize both sides first`);
+    }
+    if (a.valuationAsOf !== b.valuationAsOf) {
+        throw new FxContractError(`${op} requires the same valuation instant (同一估值时点): side A ${a.currency} as_of ${a.valuationAsOf} (fx ${a.fx.provider} ${a.fx.fact_id} ${a.fx.base}→${a.fx.quote} @${a.fx.rate}) vs side B ${b.currency} as_of ${b.valuationAsOf} (fx ${b.fx.provider} ${b.fx.fact_id} ${b.fx.base}→${b.fx.quote} @${b.fx.rate}) — 混时点比较显式拒绝`);
+    }
+}
+/** 比较（预算比较的唯一口径）：两侧必须同为规范化值、同币种、同一估值时点。返回 -1/0/1。 */
+export function compareMoney(a, b) {
+    assertSameComparisonBasis(a, b, 'money comparison');
+    if (a.amountMinor < b.amountMinor)
+        return -1;
+    if (a.amountMinor > b.amountMinor)
+        return 1;
+    return 0;
+}
+/** 预算判定（验收 3 的比较口径）：total ≤ budget，同一估值时点。 */
+export function withinBudget(total, budget) {
+    return compareMoney(total, budget) <= 0;
+}
+/** 聚合（求和）：非空、同币种、同一估值时点；返回保留该估值时点的规范化金额。 */
+export function sumMoney(items) {
+    if (items.length === 0) {
+        throw new FxContractError('sumMoney requires at least one normalized amount (empty aggregate is not a fact)');
+    }
+    const [first, ...rest] = items;
+    for (const item of rest)
+        assertSameComparisonBasis(first, item, 'money aggregation');
+    let total = 0n;
+    for (const item of items)
+        total += item.amountMinor;
+    return { currency: first.currency, amountMinor: total, valuationAsOf: first.valuationAsOf, fx: first.fx };
+}

package/dist/capabilities/geo-atlas.js

@@ -0,0 +1,246 @@
+/**
+ * Offline administrative-division atlas loader (issue #342, mechanism only —
+ * default OFF, zero callers).
+ *
+ * Reads the script-built snapshot under ts/data/geo-atlas/<version>/ (built by
+ * scripts/build-geo-atlas.mjs from Natural Earth, public domain) and answers
+ * by-name / by-id boundary lookups with typed provenance. Read-only: this
+ * module performs zero network access (node:fs + node:crypto only) and is not
+ * imported anywhere in the product path; activation stays gated on the
+ * offline-first trigger per docs/data-sources.md §2 / §7.
+ *
+ * Semantics (fail-closed, three-valued — mirrors the data-sources L4 contract):
+ * - Same-name places → `ambiguous` with candidates; the loader never picks a
+ *   winner (clarification belongs to the caller).
+ * - Boundary changes → the snapshot is frozen as-of `fetchedAt`/`version`;
+ *   every result carries that provenance so no boundary is presented as live.
+ * - Unknown region → `unknown`: a miss inside the snapshot is not proof of
+ *   nonexistence (admin-1 coverage is partial by design — 50m set).
+ * - Multilingual names → `nameZh` is surfaced when the source carries it;
+ *   when absent only the English name is returned, never a fabricated
+ *   translation (ADR-10: the LLM fabricates nothing, and neither do we).
+ * - Missing / tampered / corrupt / shape-drifted snapshots → load `error`
+ *   (SHA-256 verified against the manifest; nothing degrades silently).
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const GEO_ATLAS_MANIFEST_SCHEMA = 'gotry_geo_atlas_manifest_v1';
+function sha256(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+/** NFKC + casefold + whitespace collapse so "  cHina " ≡ "China". */
+export function normalizeAtlasName(value) {
+    return value.normalize('NFKC').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+function isGeoAtlasLayer(value) {
+    return value === 'admin-0' || value === 'admin-1';
+}
+function parseManifest(text) {
+    const manifest = JSON.parse(text);
+    if (manifest.schemaVersion !== GEO_ATLAS_MANIFEST_SCHEMA) {
+        throw new Error(`schemaVersion ${JSON.stringify(manifest.schemaVersion)} ≠ ${GEO_ATLAS_MANIFEST_SCHEMA}`);
+    }
+    for (const key of ['dataset', 'version']) {
+        if (typeof manifest[key] !== 'string' || manifest[key] === '')
+            throw new Error(`field "${key}" missing`);
+    }
+    if (!Array.isArray(manifest.artifacts) || manifest.artifacts.length === 0) {
+        throw new Error('artifacts empty');
+    }
+    for (const artifact of manifest.artifacts) {
+        if (!isGeoAtlasLayer(String(artifact.layer)))
+            throw new Error(`artifact layer "${artifact.layer}" unknown`);
+        for (const key of ['file', 'upstreamUrl', 'sha256']) {
+            if (typeof artifact[key] !== 'string' || artifact[key] === '')
+                throw new Error(`artifact field "${key}" missing`);
+        }
+    }
+    if (typeof manifest.upstream?.repository !== 'string' || typeof manifest.license?.name !== 'string') {
+        throw new Error('upstream/license block missing');
+    }
+    return manifest;
+}
+function toRecord(feature, layer, layerProvenance) {
+    const properties = feature.properties ?? {};
+    const id = properties.id;
+    const name = properties.name;
+    if (typeof id !== 'string' || id === '')
+        throw new Error('feature without string "id"');
+    if (typeof name !== 'string' || name === '')
+        throw new Error(`feature "${id}" without string "name"`);
+    if (feature.geometry?.type !== 'MultiPolygon' || !Array.isArray(feature.geometry.coordinates)) {
+        throw new Error(`feature "${id}" geometry is not MultiPolygon`);
+    }
+    const coordinates = feature.geometry.coordinates;
+    if (coordinates.length === 0 || coordinates.some((polygon) => !Array.isArray(polygon) || polygon.length === 0)) {
+        throw new Error(`feature "${id}" geometry has no polygons`);
+    }
+    const optional = (key) => {
+        const value = properties[key];
+        return typeof value === 'string' && value !== '' ? value : null;
+    };
+    return {
+        id,
+        name,
+        nameZh: optional('name_zh'),
+        admin: optional('admin'),
+        isoA2: optional('iso_a2'),
+        isoA3: optional('iso_a3'),
+        adm0A3: optional('adm0_a3'),
+        typeEn: optional('type_en'),
+        geometry: { type: 'MultiPolygon', coordinates },
+        provenance: layerProvenance,
+    };
+}
+function atlasError(reason, details) {
+    return { status: 'error', reason, details };
+}
+/**
+ * Load and verify an atlas snapshot. `root` is the version directory that
+ * contains manifest.json plus the artifact files it lists.
+ * Offline by construction: filesystem reads only, every artifact byte-verified
+ * against its manifest SHA-256 before indexing.
+ */
+export async function loadGeoAtlas(root) {
+    let manifestText;
+    try {
+        manifestText = await readFile(join(root, 'manifest.json'), 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT'
+            ? atlasError('manifest-missing', `no manifest.json under ${root}`)
+            : atlasError('manifest-unreadable', String(error.message));
+    }
+    let manifest;
+    try {
+        manifest = parseManifest(manifestText);
+    }
+    catch (error) {
+        return error instanceof SyntaxError
+            ? atlasError('manifest-corrupt', `manifest.json is not valid JSON: ${error.message}`)
+            : atlasError('manifest-invalid', error.message);
+    }
+    const snapshot = {
+        dataset: manifest.dataset,
+        version: manifest.version,
+        license: manifest.license.name,
+        upstream: manifest.upstream,
+        fetchedAt: manifest.build.fetchedAt,
+    };
+    const byId = new Map();
+    const byName = new Map();
+    const counts = new Map();
+    for (const artifact of manifest.artifacts) {
+        const layer = artifact.layer;
+        let bytes;
+        try {
+            bytes = await readFile(join(root, artifact.file));
+        }
+        catch {
+            return atlasError('artifact-missing', `${artifact.file} listed in manifest but absent`);
+        }
+        const digest = sha256(bytes);
+        if (digest !== artifact.sha256) {
+            return atlasError('artifact-sha-mismatch', `${artifact.file}: manifest ${artifact.sha256} ≠ actual ${digest}`);
+        }
+        let collection;
+        try {
+            collection = JSON.parse(bytes.toString('utf8'));
+        }
+        catch (error) {
+            return atlasError('artifact-corrupt', `${artifact.file} is not valid JSON: ${error.message}`);
+        }
+        if (collection.type !== 'FeatureCollection' || !Array.isArray(collection.features)) {
+            return atlasError('artifact-invalid', `${artifact.file} is not a FeatureCollection`);
+        }
+        const layerProvenance = {
+            layer,
+            upstreamUrl: artifact.upstreamUrl,
+            upstreamSha256: artifact.upstreamSha256,
+            snapshotFile: artifact.file,
+            snapshotSha256: digest,
+        };
+        counts.set(layer, collection.features.length);
+        for (const feature of collection.features) {
+            let record;
+            try {
+                record = toRecord(feature, layer, layerProvenance);
+            }
+            catch (error) {
+                return atlasError('artifact-invalid', `${artifact.file}: ${error.message}`);
+            }
+            const normalizedId = normalizeAtlasName(record.id);
+            if (byId.has(normalizedId)) {
+                return atlasError('duplicate-id', `"${record.id}" appears twice across the snapshot; id is not a stable key`);
+            }
+            const entry = {
+                layer,
+                id: record.id,
+                normalizedName: normalizeAtlasName(record.name),
+                normalizedZhName: record.nameZh ? normalizeAtlasName(record.nameZh) : null,
+                record,
+            };
+            byId.set(normalizedId, entry);
+            for (const key of [entry.normalizedName, entry.normalizedZhName]) {
+                if (key == null || key === '')
+                    continue;
+                const bucket = byName.get(key);
+                if (bucket)
+                    bucket.push(entry);
+                else
+                    byName.set(key, [entry]);
+            }
+        }
+    }
+    const atlas = {
+        version: manifest.version,
+        snapshot,
+        byId,
+        byName,
+        recordCount: (layer) => (layer ? (counts.get(layer) ?? 0) : byId.size),
+    };
+    return { status: 'ok', atlas };
+}
+const UNKNOWN_NOTE = 'not found in this snapshot; a miss here is not proof the place does not exist (admin-1 coverage is partial by design)';
+function unknown(snapshot) {
+    return { status: 'unknown', snapshot, note: UNKNOWN_NOTE };
+}
+/** Exact id lookup (e.g. "CHN" admin-0, "CN-YN" admin-1). Offline, read-only. */
+export function lookupById(atlas, id) {
+    const loaded = atlas;
+    const entry = loaded.byId.get(normalizeAtlasName(id));
+    if (!entry)
+        return unknown(loaded.snapshot);
+    return { status: 'hit', record: entry.record, snapshot: loaded.snapshot };
+}
+/**
+ * Name lookup against English and zh names; `options.layer` narrows to one
+ * layer before the hit/ambiguous decision. One match → hit; several distinct
+ * ids → ambiguous with candidates (the loader never picks a winner); none →
+ * unknown (three-valued).
+ */
+export function lookupByName(atlas, name, options) {
+    const loaded = atlas;
+    const key = normalizeAtlasName(name);
+    if (key === '')
+        return unknown(loaded.snapshot);
+    const matched = (loaded.byName.get(key) ?? []).filter((entry) => options?.layer ? entry.layer === options.layer : true);
+    if (matched.length === 0)
+        return unknown(loaded.snapshot);
+    const distinct = matched.filter((entry, index) => matched.findIndex((other) => other.record.id === entry.record.id) === index);
+    if (distinct.length === 1)
+        return { status: 'hit', record: distinct[0].record, snapshot: loaded.snapshot };
+    return {
+        status: 'ambiguous',
+        candidates: distinct.map((entry) => ({
+            layer: entry.layer,
+            id: entry.record.id,
+            name: entry.record.name,
+            admin: entry.record.admin,
+        })),
+        snapshot: loaded.snapshot,
+        note: 'same-name match in more than one place; clarify (country/parent or id) before use',
+    };
+}