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

package/dist/scripts/state-repair-cli.js

@@ -0,0 +1,66 @@
+/**
+ * state-ledger 数据修复 CLI(issue #254 控制面)。owner-local 工具。
+ *
+ * 子命令:
+ *   inventory <stateRoot>                       只读 inventory(JSON 报告,零写入)
+ *   plan <stateRoot> <mapping.json>             只读迁移计划(变更/冲突/错误)
+ *   execute <stateRoot> <mapping.json>          受限执行(自动 backup+journal;幂等)
+ *   rollback <stateRoot> <backupDir>            从校验过的 backup 恢复
+ *
+ * 纪律:默认拒绝把 `ts/dsh-runtime`(founder 真实产品数据)作为操作对象——
+ * 真实数据的 execute 是单独的 owner gate,必须显式传 --i-understand-founder-data。
+ * 输出恒为单个 JSON 对象;inventory/plan 天然 dry-run(只读连接)。
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { executeRepair, inventoryRepair, planRepair, rollbackRepair } from '../src/state-repair.js';
+function fail(msg) {
+    console.log(JSON.stringify({ ok: false, error: msg }));
+    process.exit(1);
+}
+const [, , cmd, stateRootArg, mappingPath] = process.argv;
+const executeFlag = process.argv.includes('--execute');
+const founderDataFlag = process.argv.includes('--i-understand-founder-data');
+if (!cmd || !stateRootArg)
+    fail('usage: state-repair-cli.ts <inventory|plan|execute|rollback> <stateRoot> [mapping.json] [--execute] [--i-understand-founder-data]');
+const stateRoot = resolve(stateRootArg);
+// founder 真实产品数据守卫:路径含 dsh-runtime 即视为 owner 数据
+if (stateRoot.includes('dsh-runtime') && !founderDataFlag) {
+    fail('refusing to operate on founder runtime state without --i-understand-founder-data (real repair is a separate owner gate)');
+}
+try {
+    if (cmd === 'inventory') {
+        if (executeFlag)
+            fail('inventory is read-only; --execute is not applicable');
+        console.log(JSON.stringify({ ok: true, inventory: inventoryRepair(stateRoot) }));
+    }
+    else if (cmd === 'plan') {
+        if (!mappingPath)
+            fail('plan requires mapping.json');
+        if (executeFlag)
+            fail('plan is read-only; --execute is not applicable');
+        const mapping = JSON.parse(readFileSync(resolve(mappingPath), 'utf8'));
+        console.log(JSON.stringify({ ok: true, plan: planRepair(stateRoot, mapping) }));
+    }
+    else if (cmd === 'execute') {
+        if (!mappingPath)
+            fail('execute requires mapping.json');
+        if (!executeFlag)
+            fail('execute is a gated action: pass --execute after reviewing the plan (real-data repair is a separate owner gate)');
+        const mapping = JSON.parse(readFileSync(resolve(mappingPath), 'utf8'));
+        console.log(JSON.stringify({ ok: true, result: executeRepair(stateRoot, mapping) }));
+    }
+    else if (cmd === 'rollback') {
+        if (!mappingPath)
+            fail('rollback requires backupDir');
+        if (executeFlag)
+            fail('rollback is a direct restore; --execute is not applicable');
+        console.log(JSON.stringify({ ok: true, result: rollbackRepair(stateRoot, resolve(mappingPath)) }));
+    }
+    else {
+        fail(`unknown command: ${cmd}`);
+    }
+}
+catch (e) {
+    fail(e instanceof Error ? e.message : String(e));
+}

package/dist/scripts/state-repair-tests.js

@@ -0,0 +1,140 @@
+/**
+ * state-ledger 数据修复控制面测试(issue #254;run-all 新节)。
+ * 全部在隔离 stateRoot fixture 上验证:
+ *  1. inventory 零写入(库哈希不变)+ 候选/无标记行分类正确;
+ *  2. plan:缺映射/非 local 现状/非法目标租户逐项报错;跨 tenant 同 idem_key 冲突显式暴露;
+ *  3. execute:--execute 缺省拒绝 CLI;from 守卫逐行 UPDATE;幂等重跑 skipped;
+ *  4. rollback:从 backup 恢复且校验和验证;损毁 backup 拒绝恢复;
+ *  5. 中途失败恢复:journal 已应用行在重跑时跳过,失败行后续补齐;
+ *  6. founder 数据守卫:dsh-runtime 路径拒绝无标志操作。
+ * 运行(在 ts/ 下):npx tsx scripts/state-repair-tests.ts
+ */
+import Database from 'better-sqlite3';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { ensureLedger } from '../src/state-ledger.js';
+import { executeRepair, inventoryRepair, planRepair, rollbackRepair } from '../src/state-repair.js';
+let pass = 0;
+function ok(msg) { pass += 1; console.log(`  ok - ${msg}`); }
+function cli(args) {
+    const r = spawnSync('npx', ['tsx', 'scripts/state-repair-cli.ts', ...args], { encoding: 'utf-8', cwd: join(process.cwd()) });
+    const start = r.stdout.indexOf('{');
+    return { json: JSON.parse(r.stdout.slice(start >= 0 ? start : 0)), stdout: r.stdout };
+}
+function dbHash(root) {
+    return createHash('sha256').update(readFileSync(join(root, 'gotry-state', 'gotry-state.db'))).digest('hex');
+}
+function seed(root) {
+    const ledger = ensureLedger(root, 'local');
+    ledger.close();
+    const db = new Database(join(root, 'gotry-state', 'gotry-state.db'));
+    db.exec(`INSERT INTO events (tenant_id, ts, actor, kind, subject_id, payload, idem_key) VALUES
+    ('local', '2026-09-01T00:00:00Z', 'runtime', 'wish_pool_add', 'w-1', '{"name":"本地愿望","tenant_id":"local"}', 'local-1'),
+    ('local', '2026-09-01T00:00:01Z', 'tenant:acme', 'wish_pool_add', 'w-2', '{"name":"误记愿望","tenant_id":"acme"}', 'local-2'),
+    ('local', '2026-09-01T00:00:02Z', 'runtime', 'motivation_save', '', '{"brief":"普通本地画像"}', 'local-3'),
+    ('acme', '2026-09-01T00:00:03Z', 'runtime', 'wish_pool_add', 'w-2', '{"name":"acme 同 idem 愿望"}', 'local-2')`);
+    db.close();
+}
+// ---- 1. inventory 零写入 + 分类 ----
+{
+    const root = mkdtempSync(join(tmpdir(), 'gotry-repair-'));
+    seed(root);
+    const before = dbHash(root);
+    const inv = inventoryRepair(root);
+    assert.equal(inv.integrity, 'ok', 'inventory integrity_check ok');
+    assert.equal(inv.localRowCounts.events, 3, 'inventory counts local events');
+    assert.equal(inv.candidates.length, 1, 'inventory flags exactly the explicit-marker row');
+    assert.equal(inv.candidates[0].key.seq, 2, 'candidate is the tenant:acme event');
+    assert.ok(inv.candidates[0].evidence.length >= 1, 'candidate carries explicit evidence');
+    assert.equal(dbHash(root), before, 'inventory is zero-write (db hash unchanged)');
+    console.log('  #1 inventory zero-write + classification OK');
+}
+// ---- 2. plan 校验与冲突暴露 ----
+{
+    const root = mkdtempSync(join(tmpdir(), 'gotry-repair-plan-'));
+    seed(root);
+    const bad = { events: [{ seq: 2, to: 'local' }, { seq: 2, to: 'bad tenant!' }] };
+    const plan = planRepair(root, bad);
+    assert.ok(plan.errors.length >= 2, 'plan reports invalid target tenants (local / illegal chars)');
+    const missing = { events: [{ seq: 999, to: 'acme' }, { seq: 1, to: 'acme' }] };
+    const planMissing = planRepair(root, missing);
+    assert.ok(planMissing.errors.some(e => e.includes('seq=999: not found')), 'plan reports not-found seq');
+    assert.equal(planMissing.changes.length, 1, 'plan still lists the existing mapped row');
+    const good = { events: [{ seq: 2, to: 'acme' }] };
+    const plan2 = planRepair(root, good);
+    assert.equal(plan2.errors.length, 0, 'valid mapping plans clean');
+    assert.equal(plan2.changes.length, 1, 'one planned change');
+    assert.equal(plan2.collisions.length, 1, 'cross-tenant same idem_key collision exposed in plan');
+    assert.ok(plan2.collisions[0].reason.includes('idem_key'), 'collision reason names the unique constraint');
+    console.log('  #2 plan validation + collision OK');
+}
+// ---- 3/4/5. execute(--execute 闸/from 守卫/幂等)+ rollback + 中途失败恢复 ----
+{
+    const root = mkdtempSync(join(tmpdir(), 'gotry-repair-exec-'));
+    seed(root);
+    // CLI 缺 --execute 必须拒绝
+    const refused = cli(['execute', root, '/nonexistent.json']);
+    assert.equal(refused.json.ok, false, 'CLI execute without --execute is refused');
+    assert.ok(refused.stdout.includes('gated action'), 'refusal names the gate');
+    // founder 数据守卫
+    const founderRefused = cli(['inventory', '/Users/bytedance/work/gotry/ts/dsh-runtime']);
+    assert.equal(founderRefused.json.ok, false, 'founder runtime state refused without explicit flag');
+    const mapping = { events: [{ seq: 2, to: 'globex' }] };
+    const result = executeRepair(root, mapping);
+    assert.equal(result.applied.length, 1, 'execute applies exactly the mapped row');
+    assert.ok(result.backupSha256, 'backup taken with SHA-256');
+    assert.ok(existsSync(result.journalPath), 'journal written');
+    assert.equal(result.integrity, 'ok', 'post-repair integrity ok');
+    const db = new Database(join(root, 'gotry-state', 'gotry-state.db'));
+    const moved = db.prepare("SELECT tenant_id FROM events WHERE seq = 2").get();
+    assert.equal(moved.tenant_id, 'globex', 'row moved to target tenant');
+    const unchanged = db.prepare("SELECT tenant_id FROM events WHERE seq = 3").get();
+    assert.equal(unchanged.tenant_id, 'local', 'unmapped row untouched');
+    db.close();
+    // 幂等重跑
+    const again = executeRepair(root, mapping);
+    assert.equal(again.applied.length, 0, 're-run applies nothing (idempotent via journal)');
+    assert.equal(again.skipped, 1, 're-run skips the journalized row');
+    // 重定向 + 扩展:journal 化行改靶(acme 冲突故用 zenith),新行补齐
+    const mapping2 = { events: [{ seq: 2, to: 'zenith' }, { seq: 3, to: 'globex' }] };
+    const third = executeRepair(root, mapping2);
+    assert.equal(third.applied.length, 2, 'retarget + extend apply together');
+    const db3 = new Database(join(root, 'gotry-state', 'gotry-state.db'));
+    const seq2 = db3.prepare("SELECT tenant_id FROM events WHERE seq = 2").get();
+    const seq3 = db3.prepare("SELECT tenant_id FROM events WHERE seq = 3").get();
+    assert.equal(seq2.tenant_id, 'zenith', 'retargeted row lands at zenith');
+    assert.equal(seq3.tenant_id, 'globex', 'new row lands at globex');
+    db3.close();
+    // rollback:校验和验证 + 恢复 + 损毁拒绝
+    const rolled = rollbackRepair(root, result.backupDir);
+    assert.ok(rolled.verified, 'rollback verifies backup checksum');
+    const db2 = new Database(join(root, 'gotry-state', 'gotry-state.db'));
+    const restored = db2.prepare("SELECT tenant_id FROM events WHERE seq = 2").get();
+    assert.equal(restored.tenant_id, 'local', 'rollback restores original tenant');
+    db2.close();
+    const tampered = mkdtempSync(join(tmpdir(), 'gotry-repair-bad-'));
+    const { writeFileSync, copyFileSync } = await import('node:fs');
+    copyFileSync(join(result.backupDir, 'gotry-state.db'), join(tampered, 'gotry-state.db'));
+    writeFileSync(join(tampered, 'backup-sha256.txt'), 'deadbeef');
+    assert.throws(() => rollbackRepair(root, tampered), /checksum mismatch/, 'tampered backup refused');
+    rmSync(tampered, { recursive: true, force: true });
+    console.log('  #3-5 execute/idempotency/rollback OK');
+}
+// ---- 6. CLI plan/execute JSON 面(真 mapping 文件) ----
+{
+    const root = mkdtempSync(join(tmpdir(), 'gotry-repair-cli-'));
+    seed(root);
+    const { writeFileSync } = await import('node:fs');
+    const mapPath = join(root, 'mapping.json');
+    writeFileSync(mapPath, JSON.stringify({ events: [{ seq: 2, to: 'acme' }] }));
+    const planned = cli(['plan', root, mapPath]);
+    assert.equal(planned.json.ok, true, 'CLI plan returns ok JSON');
+    assert.equal(planned.json.plan.changes.length, 1, 'CLI plan lists the mapped change');
+    assert.equal(planned.json.plan.collisions.length, 1, 'CLI plan surfaces the collision');
+    console.log('  #6 CLI JSON surface OK');
+}
+console.log('STATE REPAIR TESTS: OK (inventory/plan/execute/idempotency/rollback/CLI founder-guard)');

package/dist/scripts/static-golden-tests.js

@@ -0,0 +1,165 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const modulePath = '../capabilities/session/static-flight-golden.js';
+const provider = await import(modulePath).catch(() => ({}));
+assert.equal(typeof provider.parseGoldenSource, 'function', '缺少 parseGoldenSource 时 CLI 会把未知 vendor 静默当成 manual');
+const parseGoldenSource = provider.parseGoldenSource;
+assert.equal(parseGoldenSource(['--golden=static']), 'static');
+assert.equal(parseGoldenSource([]), 'manual');
+assert.throws(() => parseGoldenSource(['--golden=ctrip-open']), /不支持的 golden vendor: ctrip-open/, '未知 vendor 必须 fail-closed，不能静默回退 manual');
+assert.equal(typeof provider.loadStaticFlightSnapshot, 'function', 'static vendor 必须从有 provenance 的版本化快照加载，不能复用 manual 并改标签');
+const snapshot = provider.loadStaticFlightSnapshot();
+assert.equal(snapshot.schema_version, 'sf-static-routes.v1');
+assert.deepEqual(snapshot.source, {
+    name: 'OpenFlights routes.dat',
+    url: 'https://raw.githubusercontent.com/jpatokal/openflights/4b969f8e91eb800c45f0e0e2355a0fbb93de27e4/data/routes.dat',
+    revision: '4b969f8e91eb800c45f0e0e2355a0fbb93de27e4',
+    license: 'ODbL-1.0',
+    retrieved_at: '2026-08-30',
+    limitations: ['route/carrier coverage only', 'no schedule', 'no price', 'no availability'],
+});
+assert.deepEqual(snapshot.routes.map((route) => route.query_id), ['sf-01', 'sf-02', 'sf-03', 'sf-04', 'sf-05', 'sf-06', 'sf-07', 'sf-08'], '静态快照必须逐条覆盖本批 8 query，不能靠全量 manual fallback 蒙混');
+for (const route of snapshot.routes) {
+    assert.ok(route.legs.length >= 1, `${route.query_id} 必须至少有一个静态 OD leg`);
+    for (const leg of route.legs) {
+        assert.match(leg.from_iata, /^[A-Z]{3}$/);
+        assert.match(leg.to_iata, /^[A-Z]{3}$/);
+        assert.ok(leg.carrier_codes.length >= 1);
+    }
+    assert.equal('departure_at' in route, false, 'OpenFlights 静态包不得伪造班期时刻');
+    assert.equal('price' in route, false, 'OpenFlights 静态包不得伪造价格');
+    assert.equal('availability' in route, false, 'OpenFlights 静态包不得伪造库存');
+}
+assert.equal(typeof provider.resolveStaticGolden, 'function', '缺少 static→comparable record 解译时 --golden=static 仍不可执行');
+const manualRecord = {
+    query_id: 'sf-02',
+    route_segments: [{
+            from: '北京',
+            to: '大理',
+            departure_at: '2026-10-02T14:00:00+08:00',
+            arrival_at: '2026-10-02T17:00:00+08:00',
+            transport_number: 'CA1441',
+        }],
+    journey_type: 'direct',
+    currency: 'CNY',
+    price: 2650,
+    source: 'manual-golden',
+    fetched_at: '2026-08-30T12:00:00.000Z',
+    verdict: 'hit',
+    latency_ms: 0,
+    read_guard_blocked: 0,
+};
+const staticResolution = provider.resolveStaticGolden({
+    query: { id: 'sf-02', from: '北京', to: '大理', date: '2026-10-02' },
+    manualRecord,
+    snapshot,
+});
+assert.equal(staticResolution.requested_source, 'static');
+assert.equal(staticResolution.effective_source, 'static-openflights+manual-band');
+assert.equal(staticResolution.fallback_reason, undefined);
+assert.equal(staticResolution.record.source, 'static-openflights+manual-band');
+assert.equal(staticResolution.record.journey_type, 'transfer');
+assert.equal(staticResolution.record.route_segments.length, 2);
+assert.deepEqual(staticResolution.record.route_segments.map((segment) => [segment.from, segment.to, segment.transport_number]), [['北京', 'KMG', '8L-STATIC'], ['KMG', '大理', '8L-STATIC']]);
+assert.equal(staticResolution.record.route_segments[0]?.departure_at, '2026-10-02T14:00:00+08:00');
+assert.equal(staticResolution.record.route_segments[0]?.arrival_at, '2026-10-02T15:00:00+08:00');
+assert.equal(staticResolution.record.route_segments[1]?.departure_at, '2026-10-02T16:00:00+08:00');
+assert.equal(staticResolution.record.route_segments[1]?.arrival_at, '2026-10-02T17:00:00+08:00');
+assert.equal(staticResolution.record.price, 2650);
+assert.deepEqual(staticResolution.estimated_fields, [
+    'route_segments[].departure_at',
+    'route_segments[].arrival_at',
+    'route_segments[].transport_number',
+    'price',
+]);
+assert.deepEqual(staticResolution.provenance, {
+    route_source: snapshot.source.url,
+    route_revision: '4b969f8e91eb800c45f0e0e2355a0fbb93de27e4',
+    route_license: 'ODbL-1.0',
+    band_source: 'sf-golden-manifest.json',
+});
+const expectedStaticCoverage = [
+    { id: 'sf-01', from: '上海', to: '丽江', date: '2026-10-01', transport: ['MU-STATIC'] },
+    { id: 'sf-02', from: '北京', to: '大理', date: '2026-10-02', transport: ['8L-STATIC', '8L-STATIC'] },
+    { id: 'sf-03', from: '上海', to: '三亚', date: '2026-11-11', transport: ['9C-STATIC'] },
+    { id: 'sf-04', from: '广州', to: '昆明', date: '2026-12-20', transport: ['CA-STATIC'] },
+    { id: 'sf-05', from: '深圳', to: '成都', date: '2026-10-05', transport: ['3U-STATIC'] },
+    { id: 'sf-06', from: '杭州', to: '厦门', date: '2026-10-06', transport: ['CA-STATIC'] },
+    { id: 'sf-07', from: '西安', to: '桂林', date: '2026-10-07', transport: ['CA-STATIC'] },
+    { id: 'sf-08', from: '重庆', to: '贵阳', date: '2026-10-08', transport: ['CA-STATIC'] },
+];
+for (const expected of expectedStaticCoverage) {
+    const record = {
+        ...manualRecord,
+        query_id: expected.id,
+        route_segments: [{
+                ...manualRecord.route_segments[0],
+                from: expected.from,
+                to: expected.to,
+                departure_at: `${expected.date}T06:00:00+08:00`,
+                arrival_at: `${expected.date}T12:00:00+08:00`,
+            }],
+    };
+    const resolution = provider.resolveStaticGolden({
+        query: { id: expected.id, from: expected.from, to: expected.to, date: expected.date },
+        manualRecord: record,
+        snapshot,
+    });
+    assert.equal(resolution.effective_source, 'static-openflights+manual-band', `${expected.id} 不得全量回退 manual`);
+    assert.equal(resolution.fallback_reason, undefined);
+    assert.equal(resolution.record.route_segments.length, expected.transport.length);
+    assert.equal(resolution.record.route_segments[0]?.from, expected.from);
+    assert.equal(resolution.record.route_segments.at(-1)?.to, expected.to);
+    assert.deepEqual(resolution.record.route_segments.map((segment) => segment.transport_number), expected.transport, `${expected.id} 运行时首选 carrier 必须来自已核对的 pinned route row`);
+    for (const segment of resolution.record.route_segments) {
+        assert.match(segment.transport_number, /^[A-Z0-9]{2}-STATIC$/);
+        assert.ok(Number.isFinite(Date.parse(segment.departure_at)));
+        assert.ok(Number.isFinite(Date.parse(segment.arrival_at)));
+        assert.ok(Date.parse(segment.arrival_at) > Date.parse(segment.departure_at));
+    }
+}
+const warnings = [];
+const fallbackRecord = { ...manualRecord, query_id: 'sf-99' };
+const fallbackResolution = provider.resolveStaticGolden({
+    query: { id: 'sf-99', from: '北京', to: '大理', date: '2026-10-02' },
+    manualRecord: fallbackRecord,
+    snapshot,
+    warn: (message) => warnings.push(message),
+});
+assert.equal(fallbackResolution.effective_source, 'manual-golden');
+assert.equal(fallbackResolution.record, fallbackRecord, 'fallback 必须原样使用 manual record');
+assert.equal(fallbackResolution.fallback_reason, 'static route missing for sf-99');
+assert.deepEqual(warnings, [
+    '[sf-live-benchmark] static vendor failed for sf-99: static route missing for sf-99; fallback=manual-golden',
+]);
+const snapshotWarnings = [];
+const unavailableResolution = provider.resolveStaticGolden({
+    query: { id: 'sf-02', from: '北京', to: '大理', date: '2026-10-02' },
+    manualRecord,
+    snapshotError: 'invalid static snapshot schema_version',
+    warn: (message) => snapshotWarnings.push(message),
+});
+assert.equal(unavailableResolution.effective_source, 'manual-golden');
+assert.equal(unavailableResolution.fallback_reason, 'static snapshot unavailable: invalid static snapshot schema_version');
+assert.deepEqual(snapshotWarnings, [
+    '[sf-live-benchmark] static vendor failed for sf-02: static snapshot unavailable: invalid static snapshot schema_version; fallback=manual-golden',
+]);
+const malformedRoot = mkdtempSync(join(tmpdir(), 'gotry-static-golden-'));
+try {
+    const malformedPath = join(malformedRoot, 'malformed.json');
+    writeFileSync(malformedPath, JSON.stringify({ schema_version: 'sf-static-routes.v0', source: {}, routes: [] }));
+    assert.throws(() => provider.loadStaticFlightSnapshot(malformedPath), /invalid static snapshot schema_version: sf-static-routes.v0/, '未知 schema 不得被类型断言伪装成有效 static vendor');
+    const malformedRoutesPath = join(malformedRoot, 'malformed-routes.json');
+    writeFileSync(malformedRoutesPath, JSON.stringify({
+        schema_version: 'sf-static-routes.v1',
+        source: snapshot.source,
+        routes: null,
+    }));
+    assert.throws(() => provider.loadStaticFlightSnapshot(malformedRoutesPath), /invalid static snapshot routes/, 'schema 名正确但 routes 损坏时也必须由 loader 截获，runner 才能降级 manual');
+}
+finally {
+    rmSync(malformedRoot, { recursive: true, force: true });
+}
+console.log('STATIC GOLDEN TESTS: parser + snapshot + resolve/fallback contract OK');