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

package/dist/scripts/g5-guard.js

@@ -0,0 +1,193 @@
+/**
+ * G5 内部差旅桥机械闸(issue #348;governance/复用矩阵纪律的机械化,不是新政策)。
+ *
+ * 背景:G5 = 「内部差旅工具桥(T 系统侧,脱敏)」的创始人审批门,当前关闭
+ * (docs/gotry-master-outline.md 决策门表 + #348)。复用矩阵纪律:内部资产只能
+ * bridge/reference,桥接前必须有创始人显式授权。本脚本把该约束落成机械检查:
+ *   1. 扫描全部 git-tracked 文件(排除第三方/生成物/创始人私有 state)中
+ *      「G5 桥接引用」形状的标识符/配置/文案;
+ *   2. 命中时要求 docs/g5-authorization-ledger.md 存在覆盖该路径的 GRANT 条目
+ *      (含 issue/决策链接);没有 → exit 1,输出可操作指引。
+ *
+ * 边界(诚实声明):本闸只证明「无授权记录 → 桥接引用不落地」;
+ * GRANT 条目只能由创始人侧维护,agent 自助授权不被本闸承认(作者身份靠
+ * git review,机械不可证)。真实 G5 授权本身仍是创始人决策(#348)。
+ *
+ * 命名面豁免(NAMING_SURFACES):门定义/授权台账/guard 自身必须能「提到」
+ * 这条关闭中的 lane,否则 tracker 无法描述自己的门。除此之外一律要求 GRANT。
+ *
+ * 用法:cd ts && npx tsx scripts/g5-guard.ts [--root <dir>]
+ * 退出码:0 = 通过;1 = 存在未授权引用;2 = 闸自身无法运行(缺台账/git 失败)。
+ * 自测:cd ts && npx tsx scripts/g5-guard-tests.ts(全离线,临时 fixture)。
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const LEDGER_REL = 'docs/g5-authorization-ledger.md';
+export const ISSUE_348_URL = 'https://github.com/Danceiny/gotry/issues/348';
+/**
+ * 「G5 桥接引用」的机械形状:标识符/配置键/插件名/中英文邻接短语。
+ * 边界用显式 lookaround 而非 `\b`:下划线是 word char,`\b` 会漏掉
+ * snake_case(G5_BRIDGE_*)与 camelCase(G5Bridge)相邻形状。
+ */
+export const G5_BRIDGE_PATTERNS = [
+    { name: 'g5-adjacent-bridge-identifier', regex: /(?<![a-z0-9])g5[\s_-]{0,2}(bridge|bridged|bridging|adapter|adaptor|mcp)/i },
+    { name: 'bridge-adjacent-g5-identifier', regex: /(?<![a-z0-9])(bridge|bridged|bridging|adapter|adaptor)[\s_-]{0,2}g5(?![0-9])/i },
+    { name: 'internal-travel-mcp-plugin-id', regex: /\bcapability-travel-mcp\b/i },
+    { name: 't-system-bridge-identifier', regex: /(?<![a-z0-9])t[-_ ]?system[\s_-]{0,2}(bridge|bridged|bridging|adapter|adaptor|mcp)/i },
+    { name: 'bridge-adjacent-t-system', regex: /(?<![a-z0-9])(bridge|bridged|bridging|adapter|adaptor)[\s_-]{0,2}t[-_ ]?system/i },
+    { name: 'chinese-g5-bridge-adjacency', regex: /g5\s*桥|桥\s*g5/i },
+    { name: 'chinese-t-system-bridge-adjacency', regex: /T\s*系统\s*(桥|适配|接入)|(桥接|接入)\s*T\s*系统/ },
+];
+/**
+ * 命名面豁免:这些文件被允许「提到」G5 lane(定义它/授权它/检测它),
+ * 它们不是授权——真实桥接落在其它任何文件都仍需台账 GRANT。
+ *  - master-outline 对:G5 门定义 + 复用矩阵 T 系统行(tracker 本体);
+ *  - 授权台账对:授权面自身;
+ *  - guard + 自测:检测器必须含有自己的检测串;
+ *  - CHANGELOG.md:由 ts/scripts/build-changelog.ts 从 commit 标题**原样镜像**生成(#621)——描述这条闸的提交
+ *    标题一旦进入某个版本段,生成物就会「提到」它。豁免它不削弱闸:真正的桥接代码/配置落在别的文件里,
+ *    仍被逐文件扫描(g5-guard-tests 钉死豁免只作用于这一个路径)。
+ */
+export const NAMING_SURFACES = new Set([
+    'docs/gotry-master-outline.md',
+    'docs/gotry-master-outline.zh-CN.md',
+    'docs/g5-authorization-ledger.md',
+    'docs/g5-authorization-ledger.zh-CN.md',
+    'ts/scripts/g5-guard.ts',
+    'ts/scripts/g5-guard-tests.ts',
+    'CHANGELOG.md',
+]);
+/** 排除段:第三方闭包/生成物/创始人私有产品数据(只读红线目录也不扫)。 */
+const EXCLUDED_SEGMENTS = ['node_modules', 'vendor', 'dist', '.git', 'dsh-runtime', 'gotry-state'];
+const LOCKFILE_BASENAMES = new Set(['package-lock.json', 'pnpm-lock.yaml', 'uv.lock', 'bun.lock', 'bun.lockb', 'npm-shrinkwrap.json']);
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.mp4', '.mov', '.zip', '.gz', '.tgz', '.bz2', '.7z', '.pdf', '.wasm', '.node', '.dylib', '.so', '.bin', '.icns',
+]);
+export function isExcludedPath(relPath) {
+    const segments = relPath.split('/');
+    if (segments.some((s) => EXCLUDED_SEGMENTS.includes(s)))
+        return true;
+    const base = segments[segments.length - 1];
+    if (LOCKFILE_BASENAMES.has(base))
+        return true;
+    const dot = base.lastIndexOf('.');
+    if (dot >= 0 && BINARY_EXTENSIONS.has(base.slice(dot).toLowerCase()))
+        return true;
+    return false;
+}
+/** 单文件内容扫描:返回全部命中行(文件级,供 collectHits 逐文件调用)。 */
+export function scanContent(relPath, content) {
+    const hits = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        for (const { name, regex } of G5_BRIDGE_PATTERNS) {
+            if (regex.test(line)) {
+                hits.push({ path: relPath, line: i + 1, pattern: name, text: line.trim().slice(0, 160) });
+                break; // 一行一次足矣,避免同 pattern 行内重复刷屏
+            }
+        }
+    }
+    return hits;
+}
+/** 台账 GRANT 行:`- GRANT: <glob> — <说明,必须含 issue/决策链接>`;code fence 内的行(模板/示例)不算数。 */
+export function parseGrants(ledgerText) {
+    const grants = [];
+    let malformed = 0;
+    let inFence = false;
+    for (const rawLine of ledgerText.split('\n')) {
+        if (/^`{3,}/.test(rawLine.trim())) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = rawLine.match(/^-\s*GRANT:\s*(\S+)\s+—\s+(.+)$/);
+        if (!match)
+            continue;
+        // 无 issue/决策链接的 GRANT 视为不成立(fail closed),单独计数以便报错指引
+        if (!/#\d+|https?:\/\//.test(match[2])) {
+            malformed += 1;
+            continue;
+        }
+        grants.push({ glob: match[1], description: match[2].trim() });
+    }
+    return { grants, malformed };
+}
+/** glob → 路径正则:`**` 跨段,`*` 单段内,`?` 单字符。 */
+export function globToRegExp(glob) {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '\u0000')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]')
+        .replace(/\u0000/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+export function grantCovers(grant, relPath) {
+    return globToRegExp(grant.glob).test(relPath);
+}
+function listTrackedFiles(root) {
+    const result = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'buffer' });
+    if (result.error || result.status !== 0) {
+        console.error(`G5 GUARD: 无法枚举 git-tracked 文件(需要 git 仓库): ${result.error?.message ?? result.stderr?.toString().trim()}`);
+        process.exit(2);
+    }
+    return result.stdout.toString().split('\0').filter(Boolean);
+}
+function main() {
+    const args = process.argv.slice(2);
+    const rootIndex = args.indexOf('--root');
+    const root = rootIndex >= 0 ? resolve(args[rootIndex + 1]) : resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const ledgerPath = join(root, LEDGER_REL);
+    if (!existsSync(ledgerPath)) {
+        console.error(`G5 GUARD: 授权台账不存在: ${LEDGER_REL}(闸配置错误,exit 2;台账由创始人侧维护)`);
+        process.exit(2);
+    }
+    const ledger = parseGrants(readFileSync(ledgerPath, 'utf8'));
+    const hits = [];
+    let scanned = 0;
+    for (const relPath of listTrackedFiles(root)) {
+        if (isExcludedPath(relPath))
+            continue;
+        if (NAMING_SURFACES.has(relPath))
+            continue;
+        const abs = join(root, relPath);
+        let content;
+        try {
+            content = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue; // 不可读(权限/符号链接悬空):跳过,不属于闸的裁决面
+        }
+        if (content.includes('\0'))
+            continue; // 二进制内容:跳过
+        scanned += 1;
+        hits.push(...scanContent(relPath, content));
+    }
+    if (hits.length === 0) {
+        console.log(`G5 GUARD: OK — ${scanned} 个 tracked 文件中无未授权 G5 桥引用;台账 GRANT: ${ledger.grants.length}${ledger.malformed ? `(另有 ${ledger.malformed} 条缺 issue/决策链接的 GRANT 被拒)` : ''}`);
+        process.exit(0);
+    }
+    const uncovered = hits.filter((hit) => !ledger.grants.some((grant) => grantCovers(grant, hit.path)));
+    for (const hit of hits) {
+        const covered = ledger.grants.some((grant) => grantCovers(grant, hit.path));
+        console.error(`  ${hit.path}:${hit.line} [${hit.pattern}]${covered ? ' (已授权)' : ''} ${hit.text}`);
+    }
+    if (uncovered.length === 0) {
+        console.log(`G5 GUARD: OK — ${hits.length} 处 G5 桥引用均被台账 GRANT 覆盖`);
+        process.exit(0);
+    }
+    console.error(`G5 GUARD: FAIL — ${uncovered.length} 处未授权的 G5 内部差旅桥引用(共扫描 ${scanned} 个文件):`);
+    console.error('G5 门当前关闭:桥接内部旅行系统(T 系统)前必须获得创始人显式授权,可执行其一:');
+    console.error(`  1. 由创始人在 ${LEDGER_REL} 增加覆盖上述路径的 GRANT 条目(含 issue/决策链接;仅创始人侧维护,agent 不得自助授权);`);
+    console.error('  2. 或移除引用,保持外部供应商路径(公共 MIT hotelbyte-cli 进程桥)。');
+    console.error(`Tracker: ${ISSUE_348_URL}(复用矩阵:内部资产只能 bridge/reference,禁止代码/schema 搬运)`);
+    process.exit(1);
+}
+const isDirectRun = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectRun)
+    main();

package/dist/scripts/gen-lunar-anchors.js

@@ -0,0 +1,106 @@
+/**
+ * 春节锚点表生成器(issue #274,D-9 清偿:手抄常量表已被否决——「换个日子的同款债务」)。
+ *
+ * 用 lunar-typescript(devDependency,MIT,零传递依赖,不进 runtime bundle)在构建期把
+ * 正月初一锚点机械生成到 SPRING_FESTIVAL 表,回写 ../src/time-anchor.ts 的生成块
+ * ([gen:lunar-anchors:begin/end] 标记之间);首次运行会把旧手抄表原位迁移为生成块。
+ * 扩表/换库 = 重跑本命令;表未变则为无 diff 幂等(生成时间只在表真变时刷新)。
+ *
+ * 运行(在 ts/ 下):
+ *   npx tsx scripts/gen-lunar-anchors.ts           # 生成并回写(全离线,不访问网络)
+ *   npx tsx scripts/gen-lunar-anchors.ts --check   # 只比对不写:表/库版本漂移即非零退出
+ *                                                  # (挂 run-all-tests.sh §58 漂移闸)
+ *
+ * 交叉验证不在这里做:2026-2031 旧表 6 条 + 港天文台 2032-2040 核实 9 条已固化为
+ * time-eval §7 的双 oracle 断言(红→绿:生成前 oracle B 必红)。
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Lunar } from 'lunar-typescript';
+const TARGET = join(import.meta.dirname, '..', 'src', 'time-anchor.ts');
+const BEGIN = '// [gen:lunar-anchors:begin] 生成块起点——手改会被下次生成覆盖';
+const END = '// [gen:lunar-anchors:end]';
+const START_YEAR = 2026;
+const END_YEAR = 2099;
+/** 正月初一 → 公历 YYYY-MM-DD(lunar-typescript:农历年 y 正月初一 的 Solar)。 */
+function springFestivalOf(lunarYear) {
+    return Lunar.fromYmd(lunarYear, 1, 1).getSolar().toYmd();
+}
+function buildTable() {
+    const table = {};
+    for (let y = START_YEAR; y <= END_YEAR; y++)
+        table[y] = springFestivalOf(y);
+    return table;
+}
+function libVersion() {
+    const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'node_modules', 'lunar-typescript', 'package.json'), 'utf-8'));
+    return pkg.version;
+}
+function renderBlock(table, generatedAt) {
+    const entries = Object.keys(table).map(y => `  ${y}: '${table[Number(y)]}',`).join('\n');
+    return `/**
+ * 春节锚点表(正月初一;仅此节日漂移大,故表驱动;元旦/国庆固定月日按「下一次发生」算)。
+ * 本块由构建期生成器机械生成,禁止手改(issue #274:手抄常量表=换个日子的同款债务,已否决)。
+ * provenance:lunar-typescript@${libVersion()}(MIT,零传递依赖,devDependency 不进 runtime)· 生成时间 ${generatedAt}
+ * 命令:cd ts && npx tsx scripts/gen-lunar-anchors.ts(扩表/换库=重跑;--check=漂移闸,run-all §58)
+ * 交叉验证:2026-2031 旧表 6 条 + 港天文台 2032-2040 核实 9 条逐条一致(time-eval §7 双 oracle)。
+ * 到期守卫:springFestivalHorizonOk——最晚锚点年份 < 当前年+3 测试即红(临近耗尽先红于静默缺失)。
+ */
+${BEGIN}
+export const SPRING_FESTIVAL: Record<number, string> = {
+${entries}
+}
+${END}`;
+}
+/** 提取文件中现有生成块;无标记则匹配旧手抄声明(含其上一行单行 doc 注释)原位迁移。 */
+function extractExisting(src) {
+    const b = src.indexOf(BEGIN);
+    const e = src.indexOf(END);
+    if (b !== -1 && e !== -1) {
+        const end = e + END.length;
+        return { block: src.slice(b, end), replaceFrom: next => src.slice(0, b) + next + src.slice(end) };
+    }
+    const legacy = src.match(/(?:\/\*\*[^\n]*\*\/\n)?(?:export )?const SPRING_FESTIVAL: Record<number, string> = \{\n(?:  \d{4}: '\d{4}-\d{2}-\d{2}',\n)+\}/);
+    if (!legacy)
+        throw new Error('未找到 SPRING_FESTIVAL 表(既无生成标记也无手抄声明)');
+    const m = legacy[0];
+    return { block: null, replaceFrom: next => src.replace(m, next) };
+}
+/** 从块文本解析 年→日期 映射(--check 与幂等判定用,生成时间/库版本不参与比较)。 */
+function parseTable(block) {
+    const table = {};
+    if (!block)
+        return table;
+    for (const m of block.matchAll(/(\d{4}): '(\d{4}-\d{2}-\d{2})'/g))
+        table[Number(m[1])] = m[2];
+    return table;
+}
+function tablesEqual(a, b) {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every(k => a[Number(k)] === b[Number(k)]);
+}
+const check = process.argv.includes('--check');
+const table = buildTable();
+const src = readFileSync(TARGET, 'utf-8');
+const { block, replaceFrom } = extractExisting(src);
+if (block && tablesEqual(parseTable(block), table)) {
+    console.log(`lunar-anchors:表已是最新(${START_YEAR}-${END_YEAR},共 ${Object.keys(table).length} 条),无 diff`);
+    process.exit(0);
+}
+const next = renderBlock(table, new Date().toISOString());
+if (check) {
+    console.error(`lunar-anchors:漂移!${TARGET} 与生成器输出不一致(表内容或生成块缺失),应重跑:cd ts && npx tsx scripts/gen-lunar-anchors.ts`);
+    if (block) {
+        const have = parseTable(block);
+        const want = table;
+        for (let y = Math.min(START_YEAR, ...Object.keys(have).map(Number)); y <= END_YEAR; y++) {
+            if (have[y] !== want[y])
+                console.error(`  ${y}: 文件=${have[y] ?? '(缺)'} 生成=${want[y] ?? '(缺)'}`);
+        }
+    }
+    process.exit(1);
+}
+writeFileSync(TARGET, replaceFrom(next));
+const diffYears = Object.keys(table).filter(y => !block || parseTable(block)[Number(y)] !== table[Number(y)]);
+console.log(`lunar-anchors:已回写 ${TARGET}(覆盖 ${START_YEAR}-${END_YEAR},共 ${Object.keys(table).length} 条;本次新增/变更 ${diffYears.length} 条)`);

package/dist/scripts/geo-atlas-tests.js

@@ -0,0 +1,283 @@
+/**
+ * Offline geo-atlas loader contract tests (issue #342, mechanism only —
+ * default off, zero product callers).
+ *
+ * Run: cd ts && npx tsx scripts/geo-atlas-tests.ts
+ *
+ * Fully offline: driven by a small synthetic fixture GeoJSON written to a
+ * temp directory (never the committed build output, never the network). The
+ * offline claim itself is executed: globalThis.fetch is replaced by a
+ * throwing spy for the whole run and asserted to stay at zero calls.
+ */
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GEO_ATLAS_MANIFEST_SCHEMA, loadGeoAtlas, lookupById, lookupByName, normalizeAtlasName, } from '../capabilities/geo-atlas.js';
+function sha256(data) {
+    return createHash('sha256').update(Buffer.from(data, 'utf8')).digest('hex');
+}
+const SQUARE = [[[[100.0, 21.0], [102.0, 21.0], [102.0, 25.0], [100.0, 25.0], [100.0, 21.0]]]];
+const OTHER_SQUARE = [[[[11.0, 60.0], [13.0, 60.0], [13.0, 62.0], [11.0, 62.0], [11.0, 60.0]]]];
+function feature(properties, coordinates = SQUARE) {
+    return { type: 'Feature', properties, geometry: { type: 'MultiPolygon', coordinates } };
+}
+const ADMIN_0_FEATURES = [
+    feature({ id: 'CHN', name: 'China', name_zh: '中华人民共和国', admin: 'China', iso_a2: 'CN', iso_a3: 'CHN' }),
+    feature({ id: 'NOR', name: 'Norway', name_zh: '挪威', admin: 'Norway', iso_a2: 'NO', iso_a3: 'NOR' }, OTHER_SQUARE),
+    feature({ id: 'TL', name: 'Testland', admin: 'Testland', iso_a2: 'TX' }),
+];
+const ADMIN_1_FEATURES = [
+    feature({ id: 'CN-YN', name: 'Yunnan', name_zh: '云南省', admin: 'China', iso_a2: 'CN', adm0_a3: 'CHN' }),
+    feature({ id: 'NO-18', name: 'Nordland', admin: 'Norway', iso_a2: 'NO', adm0_a3: 'NOR' }, OTHER_SQUARE),
+    feature({ id: 'TL-NR', name: 'Nordland', admin: 'Testland', iso_a2: 'TX', adm0_a3: 'TL' }),
+];
+const UPSTREAM = { repository: 'https://example.invalid/natural-earth-vector', tag: 'fixture-tag', commit: 'fixture-commit' };
+const LICENSE = 'Natural Earth — public domain (no attribution required)';
+async function writeFixture(dir, options = {}) {
+    const versionDir = join(dir, 'fixture-v1');
+    await mkdir(versionDir, { recursive: true });
+    const admin0Text = options.admin0Text ?? JSON.stringify({ type: 'FeatureCollection', features: ADMIN_0_FEATURES });
+    const admin1Text = options.admin1Text ?? JSON.stringify({ type: 'FeatureCollection', features: ADMIN_1_FEATURES });
+    await writeFile(join(versionDir, 'admin-0.geojson'), admin0Text, 'utf8');
+    await writeFile(join(versionDir, 'admin-1.geojson'), admin1Text, 'utf8');
+    const manifest = {
+        schemaVersion: GEO_ATLAS_MANIFEST_SCHEMA,
+        dataset: 'natural-earth',
+        version: 'fixture-v1',
+        upstream: UPSTREAM,
+        license: { name: LICENSE },
+        build: { fetchedAt: '2026-10-02T00:00:00.000Z' },
+        artifacts: [
+            {
+                layer: 'admin-0',
+                file: 'admin-0.geojson',
+                upstreamUrl: 'https://example.invalid/admin-0.geojson',
+                upstreamSha256: 'a'.repeat(64),
+                recordCount: 3,
+                bytes: Buffer.byteLength(admin0Text),
+                sha256: sha256(admin0Text),
+            },
+            {
+                layer: 'admin-1',
+                file: 'admin-1.geojson',
+                upstreamUrl: 'https://example.invalid/admin-1.geojson',
+                upstreamSha256: 'b'.repeat(64),
+                recordCount: 3,
+                bytes: Buffer.byteLength(admin1Text),
+                sha256: sha256(admin1Text),
+            },
+        ],
+    };
+    await writeFile(join(versionDir, 'manifest.json'), options.manifestText ?? JSON.stringify(manifest, null, 2), 'utf8');
+    return versionDir;
+}
+async function loadOk(dir) {
+    const result = await loadGeoAtlas(dir);
+    assert.equal(result.status, 'ok', `fixture load must succeed, got ${JSON.stringify(result)}`);
+    return result.atlas;
+}
+async function loadErr(dir) {
+    const result = await loadGeoAtlas(dir);
+    assert.equal(result.status, 'error', `fixture load must fail, got ${JSON.stringify(result)}`);
+    return result.reason;
+}
+async function withFixture(name, fn) {
+    const root = await mkdtemp(join(tmpdir(), name));
+    try {
+        await fn(await writeFixture(root));
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+const tests = [];
+tests.push({
+    name: 'green path: SHA-256 verified load, both layers indexed, provenance asserted',
+    fn: async () => {
+        await withFixture('geo-atlas-green-', async (versionDir) => {
+            const atlas = await loadOk(versionDir);
+            assert.equal(atlas.version, 'fixture-v1');
+            assert.equal(atlas.recordCount(), 6);
+            assert.equal(atlas.recordCount('admin-0'), 3);
+            assert.equal(atlas.recordCount('admin-1'), 3);
+            assert.equal(atlas.snapshot.dataset, 'natural-earth');
+            assert.equal(atlas.snapshot.license, LICENSE);
+            assert.deepEqual(atlas.snapshot.upstream, UPSTREAM);
+            assert.equal(atlas.snapshot.fetchedAt, '2026-10-02T00:00:00.000Z');
+            const hit = lookupByName(atlas, 'China');
+            assert.equal(hit.status, 'hit');
+            if (hit.status !== 'hit')
+                return;
+            assert.equal(hit.record.id, 'CHN');
+            assert.equal(hit.record.nameZh, '中华人民共和国');
+            assert.equal(hit.record.geometry.type, 'MultiPolygon');
+            assert.ok(hit.record.geometry.coordinates.length >= 1);
+            assert.equal(hit.record.provenance.layer, 'admin-0');
+            assert.equal(hit.record.provenance.snapshotFile, 'admin-0.geojson');
+            assert.equal(hit.record.provenance.upstreamUrl, 'https://example.invalid/admin-0.geojson');
+            const onDisk = await readFile(join(versionDir, 'admin-0.geojson'), 'utf8');
+            assert.equal(hit.record.provenance.snapshotSha256, sha256(onDisk));
+            assert.equal(hit.snapshot.version, 'fixture-v1');
+        });
+    },
+});
+tests.push({
+    name: 'by-name matches the zh name and normalizes case/whitespace',
+    fn: async () => {
+        await withFixture('geo-atlas-names-', async (versionDir) => {
+            const atlas = await loadOk(versionDir);
+            const zh = lookupByName(atlas, '中华人民共和国');
+            assert.equal(zh.status, 'hit');
+            if (zh.status === 'hit')
+                assert.equal(zh.record.id, 'CHN');
+            const messy = lookupByName(atlas, '   cHina ');
+            assert.equal(messy.status, 'hit');
+            assert.equal(normalizeAtlasName('  YUNNAN '), 'yunnan');
+        });
+    },
+});
+tests.push({
+    name: 'by-id lookup hits with the layer provenance of that record',
+    fn: async () => {
+        await withFixture('geo-atlas-id-', async (versionDir) => {
+            const atlas = await loadOk(versionDir);
+            const hit = lookupById(atlas, 'CN-YN');
+            assert.equal(hit.status, 'hit');
+            if (hit.status !== 'hit')
+                return;
+            assert.equal(hit.record.admin, 'China');
+            assert.equal(hit.record.provenance.layer, 'admin-1');
+            assert.equal(hit.record.provenance.snapshotFile, 'admin-1.geojson');
+            assert.equal(hit.record.provenance.snapshotSha256, sha256(await readFile(join(versionDir, 'admin-1.geojson'), 'utf8')));
+            const country = lookupById(atlas, 'chn');
+            assert.equal(country.status, 'hit');
+        });
+    },
+});
+tests.push({
+    name: 'same-name place → ambiguous with candidates, never a silent pick; layer filter narrows',
+    fn: async () => {
+        await withFixture('geo-atlas-ambig-', async (versionDir) => {
+            const atlas = await loadOk(versionDir);
+            const ambiguous = lookupByName(atlas, 'Nordland');
+            assert.equal(ambiguous.status, 'ambiguous');
+            if (ambiguous.status !== 'ambiguous')
+                return;
+            assert.equal(ambiguous.candidates.length, 2);
+            const ids = ambiguous.candidates.map((c) => c.id).sort();
+            assert.deepEqual(ids, ['NO-18', 'TL-NR']);
+            for (const candidate of ambiguous.candidates) {
+                assert.equal(candidate.layer, 'admin-1');
+                assert.ok(candidate.admin);
+            }
+            assert.match(ambiguous.note, /clarify/i);
+            const narrowed = lookupByName(atlas, 'Nordland', { layer: 'admin-0' });
+            assert.equal(narrowed.status, 'unknown');
+        });
+    },
+});
+tests.push({
+    name: 'unknown region → three-valued miss, snapshot provenance still attached',
+    fn: async () => {
+        await withFixture('geo-atlas-unknown-', async (versionDir) => {
+            const atlas = await loadOk(versionDir);
+            for (const miss of [lookupByName(atlas, 'Atlantis'), lookupById(atlas, 'XX-XX')]) {
+                assert.equal(miss.status, 'unknown');
+                if (miss.status !== 'unknown')
+                    continue;
+                assert.equal(miss.snapshot.version, 'fixture-v1');
+                assert.match(miss.note, /not proof/);
+            }
+            const empty = lookupByName(atlas, '   ');
+            assert.equal(empty.status, 'unknown');
+        });
+    },
+});
+tests.push({
+    name: 'fail-closed: missing/corrupt/invalid manifest, missing/tampered/corrupt/invalid artifact, duplicate id',
+    fn: async () => {
+        const base = await mkdtemp(join(tmpdir(), 'geo-atlas-fail-'));
+        try {
+            const missing = await loadGeoAtlas(join(base, 'no-such-dir'));
+            assert.equal(missing.status, 'error');
+            const rawManifestDir = join(base, 'raw-manifest');
+            await mkdir(rawManifestDir, { recursive: true });
+            await writeFile(join(rawManifestDir, 'manifest.json'), '{not json', 'utf8');
+            assert.equal(await loadErr(rawManifestDir), 'manifest-corrupt');
+            const badSchemaDir = await writeFixture(base, {
+                manifestText: JSON.stringify({ schemaVersion: 'something-else', dataset: 'x', version: 'y', artifacts: [] }),
+            });
+            assert.equal(await loadErr(badSchemaDir), 'manifest-invalid');
+            const missingArtifactDir = await writeFixture(base);
+            await rm(join(missingArtifactDir, 'admin-1.geojson'));
+            assert.equal(await loadErr(missingArtifactDir), 'artifact-missing');
+            // Tamper happens AFTER the manifest is on disk: the snapshot file no
+            // longer matches its recorded SHA-256 (this is the fail-closed seam).
+            const tamperedDir = await writeFixture(base);
+            await writeFile(join(tamperedDir, 'admin-1.geojson'), await readFile(join(tamperedDir, 'admin-1.geojson'), 'utf8') + ' ', 'utf8');
+            assert.equal(await loadErr(tamperedDir), 'artifact-sha-mismatch');
+            const brokenJson = JSON.stringify({ type: 'FeatureCollection', features: ADMIN_1_FEATURES }).slice(0, 40);
+            const corruptArtifactDir = await writeFixture(base, { admin1Text: brokenJson });
+            assert.equal(await loadErr(corruptArtifactDir), 'artifact-corrupt');
+            const shapeDriftText = JSON.stringify({
+                type: 'FeatureCollection',
+                features: [{ type: 'Feature', properties: { id: 'NO-18', name: 'Nordland' } }, ...ADMIN_1_FEATURES.slice(1)],
+            });
+            const shapeDriftDir = await writeFixture(base, { admin1Text: shapeDriftText });
+            assert.equal(await loadErr(shapeDriftDir), 'artifact-invalid');
+            const notACollection = JSON.stringify({ type: 'Feature', geometry: null });
+            const notCollectionDir = await writeFixture(base, { admin0Text: notACollection });
+            assert.equal(await loadErr(notCollectionDir), 'artifact-invalid');
+            const duplicateText = JSON.stringify({
+                type: 'FeatureCollection',
+                features: [...ADMIN_0_FEATURES, feature({ id: 'CHN', name: 'China Duplicate' })],
+            });
+            const duplicateDir = await writeFixture(base, { admin0Text: duplicateText });
+            assert.equal(await loadErr(duplicateDir), 'duplicate-id');
+        }
+        finally {
+            await rm(base, { recursive: true, force: true });
+        }
+    },
+});
+tests.push({
+    name: 'determinism: two loads of the same root answer identically',
+    fn: async () => {
+        await withFixture('geo-atlas-det-', async (versionDir) => {
+            const first = await loadOk(versionDir);
+            const second = await loadOk(versionDir);
+            assert.deepEqual(first.snapshot, second.snapshot);
+            assert.deepEqual(lookupByName(first, 'Yunnan'), lookupByName(second, 'Yunnan'));
+            assert.deepEqual(lookupById(first, 'TL-NR'), lookupById(second, 'TL-NR'));
+        });
+    },
+});
+// The offline spy wraps the entire suite (installed before any test runs and
+// asserted afterwards): zero network is an executed contract, not a claim.
+const realFetch = globalThis.fetch;
+let fetchCalls = 0;
+globalThis.fetch = ((...args) => {
+    fetchCalls += 1;
+    throw new Error(`geo-atlas loader must be offline; fetch called with ${JSON.stringify(args[0])}`);
+});
+let failed = 0;
+for (const test of tests) {
+    try {
+        await test.fn();
+        console.log(`ok - ${test.name}`);
+    }
+    catch (error) {
+        failed += 1;
+        console.error(`FAIL - ${test.name}`);
+        console.error(error);
+    }
+}
+globalThis.fetch = realFetch;
+assert.equal(fetchCalls, 0, `loader made ${fetchCalls} network call(s); offline contract violated`);
+if (failed > 0) {
+    console.error(`${failed} geo-atlas test(s) failed`);
+    process.exit(1);
+}
+console.log(`geo-atlas contract tests: ${tests.length} passed, 0 failed (fetch calls: ${fetchCalls})`);