tickdb-ts 0.0.0-stage → 0.3.0

package/dist/store.d.ts

@@ -0,0 +1,100 @@
+import type { FileEntry } from './types.js';
+/** local_manifest 全字段行（stale per-file ts 边界删除用）。 */
+export interface LocalManifestRow {
+    path: string;
+    sha256: string;
+    cycle: string;
+    year: number | null;
+    ts_min: string | null;
+    ts_max: string | null;
+}
+/** sync_meta key：kline 存储模式（'duckdb-upsert' | 'parquet-direct'）。 */
+export declare const STORE_MODE_KEY = "store_mode";
+export declare const SCHEMA_STATEMENTS: string[];
+/** open() heal 目标：catalog 中可能处于 read_parquet VIEW 态的名字
+ * （kline parquet-direct + 5 个 extra 聚合）。每个名字必须在
+ * SCHEMA_STATEMENTS 有对应 CREATE TABLE IF NOT EXISTS 条目——heal 只拆
+ * 不建，重建全靠随后的 SCHEMA_STATEMENTS 重放（静态测试防重命名哑弹）。 */
+export declare const SURFACE_HEAL_VIEW_NAMES: readonly string[];
+export declare class DuckdbStore {
+    private instance;
+    private conn;
+    /** v2 parquet-direct：kline view 挂载根（<dataDir>/.cache/parquet）。 */
+    private parquetRoot;
+    /** surface 维护互斥（I1）：单连接无锁，Node 单线程但 await 点交错——
+     * 并发 query()/sync 的「catalog 读型 + DDL」序列交错会把 DROP TABLE
+     * 落在对方刚挂的 VIEW 上（Catalog Error）。promise-chain 把整段
+     * 序列串行化；错误吞进链尾不阻塞后续。 */
+    private surfaceLock;
+    private constructor();
+    static open(path: string): Promise<DuckdbStore>;
+    /** 串行化辅助（I1）：fn 排进 surfaceLock 链尾执行；本类所有
+     * 「catalog 读型 + DDL」序列的公共入口都必须经它（core 方法无锁，
+     * 供锁内复用，防嵌套自死锁）。 */
+    private runExclusive;
+    /** open() 残落 view heal（重启防 brick，C1）：上次进程退出时 catalog
+     * 可能残留指向已删 parquet 的 read_parquet VIEW（stale 删除 extra/
+     * kline 文件是 sync 常规路径，而 ensureExtraSurfaces 的自愈只在
+     * query() 里跑——sync-only 用法的暴露窗口无界）。本 DuckDB 构建的
+     * CREATE VIEW 是 eager binder：SCHEMA_STATEMENTS 里 qfq/hfq DDL 会
+     * 即解析被引用的 kline / adjustment_factors 的 schema，残落 view 读
+     * 已删文件 footer → IO Error → open() 永久失败（客户端 brick，只能
+     * 手工删库 → 丢 local_manifest 全量重下）。kline 半边（v1.3 direct
+     * 起潜伏）与 extra 半边（v1.4）一并 heal：
+     * ① qfq/hfq 先拆（kline 的依赖者，SCHEMA 重放马上 OR REPLACE 重建）；
+     * ② 处于 VIEW 态的名字一律 DROP 回空表位——重建交给 SCHEMA_STATEMENTS
+     * 重放（IF NOT EXISTS，单一来源）。upsert 模式的 TABLE 数据不受影响；
+     * direct/extra view 由 query()/syncOnce 的 surface 维护重挂。 */
+    private healResidueViews;
+    private c;
+    close(): Promise<void>;
+    run(sql: string, params?: unknown[]): Promise<void>;
+    query(sql: string): Promise<Record<string, unknown>[]>;
+    /** v2 parquet-direct 查询前置：glob 重展开（view 注册时展开 glob，新文件才
+     * 可见——与服务端 refresh_views 同因）。upsert 模式零开销直通。
+     * sync_meta 读取走原始连接（getSyncMeta → query → 这里，避免自递归）。 */
+    private maybeRefreshKlineSurfaceCore;
+    setParquetRoot(root: string): void;
+    /** v2 parquet-direct：kline 以 view 挂载 parquet 目录（hive_partitioning 从
+     * cycle={c} 目录名注入 cycle 列——parquet 本身无 cycle 列；与服务端
+     * query_engine 同款）。CREATE OR REPLACE 保证幂等。空目录（sync 前置调用）
+     * 建同 schema 空 view，read_parquet 空 glob 会 IO Error。 */
+    refreshKlineView(cacheRoot: string): Promise<void>;
+    private refreshKlineViewCore;
+    /** 把 kline 表面（surface）对齐到当前模式：direct → read_parquet VIEW
+     * （v1 遗留 TABLE 先 DROP）；upsert → TABLE（v2 遗留 VIEW 先 DROP 重建，
+     * 服务端回滚场景）。依赖视图 qfq/hfq 一并重建。幂等。 */
+    ensureKlineSurface(mode: string, cacheRoot: string): Promise<void>;
+    private ensureKlineSurfaceCore;
+    /** sync_meta 读取走原始连接（不经 query() 的 surface 刷新）。 */
+    getSyncMeta(key: string): Promise<string | null>;
+    /** extra 数据集 view 挂载：**恒 direct**（服务端聚合已全局去重，天然
+     * disjoint——不跟随 kline 的 store_mode；upsert 模式客户端的 extra 也
+     * 用 view，防聚合 parquet 被灌进 kline 表）。文件存在 → DROP schema 空
+     * 表 + read_parquet VIEW（时间列 CAST 与服务端 view 一致）；缺失 →
+     * 保留空表（新装客户端查询 0 行，体验不变）。
+     *
+     * 残落防护（catalog 判型——DuckDB 的 `DROP TABLE IF EXISTS` 对同名
+     * VIEW 照样报错，IF EXISTS 只兜「名字不存在」）：BASE TABLE 且文件在
+     * → DROP TABLE + 挂 VIEW；VIEW 且文件在 → OR REPLACE 幂等重挂；VIEW
+     * 且文件缺失（stale 删除/清缓存后残落）→ DROP VIEW 回落空表
+     * （SCHEMA_STATEMENTS 全 IF NOT EXISTS 重建）；BASE TABLE 且文件缺
+     * 失 → 不动。adjustment_factors 被 kline_qfq/hfq ASOF JOIN 依赖——
+     * duckdb view 晚绑定允许 DROP 后重解析（回归测试钉住该行为）。 */
+    ensureExtraSurfaces(): Promise<void>;
+    private ensureExtraSurfacesCore;
+    setSyncMeta(key: string, value: string): Promise<void>;
+    clearLocalManifest(): Promise<void>;
+    countParquetRows(parquetPath: string): Promise<number>;
+    upsertKlineFromFile(parquetPath: string, cycle: string): Promise<void>;
+    deleteKlineYear(cycle: string, year: number): Promise<void>;
+    /** 按文件 ts 边界删除（含端点，口径同 deleteKlineYear）。月切片 ts 互不重叠，不会误伤相邻月。 */
+    deleteKlineRange(cycle: string, tsMin: string, tsMax: string): Promise<void>;
+    listLocalManifest(): Promise<Map<string, string>>;
+    /** 全字段 local_manifest（stale per-file ts 边界删除用；NULL 边界 → null，调用方回退整年）。 */
+    listLocalManifestFull(): Promise<Map<string, LocalManifestRow>>;
+    upsertLocalManifest(f: FileEntry): Promise<void>;
+    deleteLocalManifest(paths: string[]): Promise<void>;
+    getEtag(): Promise<string | null>;
+    setEtag(etag: string): Promise<void>;
+}

package/dist/store.js

@@ -0,0 +1,401 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { DuckDBInstance } from '@duckdb/node-api';
+import { yearBounds } from './util.js';
+/** sync_meta key：kline 存储模式（'duckdb-upsert' | 'parquet-direct'）。 */
+export const STORE_MODE_KEY = 'store_mode';
+/** 与 Rust 客户端 KLINE_SCHEMA 逐条对齐（duckdb_store.rs）。 */
+const KLINE_TABLE_DDL = `CREATE TABLE IF NOT EXISTS kline (
+    ts TIMESTAMP, symbol VARCHAR, cycle VARCHAR,
+    open DOUBLE, high DOUBLE, low DOUBLE, close DOUBLE,
+    volume BIGINT, amount DOUBLE,
+    PRIMARY KEY (symbol, cycle, ts))`;
+const KLINE_QFQ_VIEW_DDL = `CREATE OR REPLACE VIEW kline_qfq AS
+    SELECT k.ts, k.symbol, k.cycle,
+      k.open * COALESCE(f.factor, 1.0) AS open, k.high * COALESCE(f.factor, 1.0) AS high,
+      k.low * COALESCE(f.factor, 1.0) AS low, k.close * COALESCE(f.factor, 1.0) AS close,
+      k.volume, k.amount
+    FROM kline k
+    ASOF LEFT JOIN adjustment_factors f
+      ON f.symbol = k.symbol AND f.adjust_type = 'qfq' AND k.ts >= f.effective_from`;
+const KLINE_HFQ_VIEW_DDL = `CREATE OR REPLACE VIEW kline_hfq AS
+    SELECT k.ts, k.symbol, k.cycle,
+      k.open * COALESCE(f.factor, 1.0) AS open, k.high * COALESCE(f.factor, 1.0) AS high,
+      k.low * COALESCE(f.factor, 1.0) AS low, k.close * COALESCE(f.factor, 1.0) AS close,
+      k.volume, k.amount
+    FROM kline k
+    ASOF LEFT JOIN adjustment_factors f
+      ON f.symbol = k.symbol AND f.adjust_type = 'hfq' AND k.ts >= f.effective_from`;
+export const SCHEMA_STATEMENTS = [
+    KLINE_TABLE_DDL,
+    `CREATE TABLE IF NOT EXISTS subscriptions (symbol VARCHAR, cycle VARCHAR, added_at TIMESTAMP, PRIMARY KEY (symbol, cycle))`,
+    `CREATE TABLE IF NOT EXISTS sync_state (symbol VARCHAR, cycle VARCHAR, last_ts TIMESTAMP, last_sync_at TIMESTAMP, last_rows BIGINT, PRIMARY KEY (symbol, cycle))`,
+    `CREATE TABLE IF NOT EXISTS sync_state_extra (data_type VARCHAR, last_sync_at TIMESTAMP, last_rows BIGINT, notes VARCHAR, PRIMARY KEY (data_type))`,
+    `CREATE TABLE IF NOT EXISTS securities (symbol VARCHAR PRIMARY KEY, code VARCHAR, name VARCHAR, market VARCHAR, fetched_at TIMESTAMP)`,
+    `CREATE TABLE IF NOT EXISTS quotes_snapshot (
+    ts TIMESTAMP, symbol VARCHAR, price DOUBLE, pre_close DOUBLE, open DOUBLE, high DOUBLE, low DOUBLE,
+    volume DOUBLE, amount DOUBLE,
+    bid1 DOUBLE, bid2 DOUBLE, bid3 DOUBLE, bid4 DOUBLE, bid5 DOUBLE,
+    ask1 DOUBLE, ask2 DOUBLE, ask3 DOUBLE, ask4 DOUBLE, ask5 DOUBLE,
+    bid_vol1 DOUBLE, bid_vol2 DOUBLE, bid_vol3 DOUBLE, bid_vol4 DOUBLE, bid_vol5 DOUBLE,
+    ask_vol1 DOUBLE, ask_vol2 DOUBLE, ask_vol3 DOUBLE, ask_vol4 DOUBLE, ask_vol5 DOUBLE,
+    PRIMARY KEY (symbol, ts))`,
+    `CREATE TABLE IF NOT EXISTS dividend (
+    symbol VARCHAR, date DATE, category SMALLINT, songzhuan DOUBLE, peigu DOUBLE, peigujia DOUBLE,
+    fenhong DOUBLE, liutong DOUBLE, zongguben DOUBLE,
+    PRIMARY KEY (symbol, date, category))`,
+    `CREATE TABLE IF NOT EXISTS sector_members (
+    block_type VARCHAR, block_name VARCHAR, symbol VARCHAR, name VARCHAR, market VARCHAR, asof_date DATE,
+    PRIMARY KEY (block_type, block_name, symbol, asof_date))`,
+    `CREATE TABLE IF NOT EXISTS financial_basic (
+    symbol VARCHAR, fetched_at TIMESTAMP, eps DOUBLE, bvps DOUBLE, cfps DOUBLE,
+    capital_reserve DOUBLE, retained_profit DOUBLE, operating_income DOUBLE, net_profit DOUBLE,
+    gross_profit DOUBLE, total_assets DOUBLE, net_assets DOUBLE, debt_ratio DOUBLE,
+    roe DOUBLE, gross_margin DOUBLE, net_margin DOUBLE,
+    PRIMARY KEY (symbol, fetched_at))`,
+    `CREATE TABLE IF NOT EXISTS adjustment_factors (
+    symbol VARCHAR, effective_from TIMESTAMP, factor DOUBLE, source_date DATE,
+    source_category SMALLINT, adjust_type VARCHAR,
+    PRIMARY KEY (symbol, adjust_type, effective_from))`,
+    KLINE_QFQ_VIEW_DDL,
+    KLINE_HFQ_VIEW_DDL,
+    `CREATE TABLE IF NOT EXISTS local_manifest (
+    path VARCHAR PRIMARY KEY, sha256 VARCHAR, size BIGINT, row_count BIGINT,
+    cycle VARCHAR, year INTEGER, ts_min TIMESTAMP, ts_max TIMESTAMP, synced_at TIMESTAMP)`,
+    `CREATE TABLE IF NOT EXISTS sync_meta (key VARCHAR PRIMARY KEY, value VARCHAR)`,
+];
+/** extra 数据集 view 规格：(表名, 时间列)。与服务端 query_engine 的 extra
+ * view 同一张表——时间列 CAST 成 plain TIMESTAMP（parquet TIMESTAMPTZ
+ * 剥 tz 走 session 时区）；dividend/sector_members 时间列是 DATE（无需
+ * CAST）；quotes_snapshot 不同步，缺席。 */
+const EXTRA_DATASET_VIEW_SPECS = [
+    ['securities', 'fetched_at'],
+    ['dividend', null],
+    ['financial_basic', 'fetched_at'],
+    ['sector_members', null],
+    ['adjustment_factors', 'effective_from'],
+];
+/** open() heal 目标：catalog 中可能处于 read_parquet VIEW 态的名字
+ * （kline parquet-direct + 5 个 extra 聚合）。每个名字必须在
+ * SCHEMA_STATEMENTS 有对应 CREATE TABLE IF NOT EXISTS 条目——heal 只拆
+ * 不建，重建全靠随后的 SCHEMA_STATEMENTS 重放（静态测试防重命名哑弹）。 */
+export const SURFACE_HEAL_VIEW_NAMES = ['kline', ...EXTRA_DATASET_VIEW_SPECS.map(([n]) => n)];
+export class DuckdbStore {
+    instance = null;
+    conn = null;
+    /** v2 parquet-direct：kline view 挂载根（<dataDir>/.cache/parquet）。 */
+    parquetRoot = null;
+    /** surface 维护互斥（I1）：单连接无锁，Node 单线程但 await 点交错——
+     * 并发 query()/sync 的「catalog 读型 + DDL」序列交错会把 DROP TABLE
+     * 落在对方刚挂的 VIEW 上（Catalog Error）。promise-chain 把整段
+     * 序列串行化；错误吞进链尾不阻塞后续。 */
+    surfaceLock = Promise.resolve();
+    constructor() { }
+    static async open(path) {
+        const s = new DuckdbStore();
+        try {
+            s.instance = await DuckDBInstance.create(path);
+            s.conn = await s.instance.connect();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes('Conflicting lock')) {
+                throw new Error(`tickdb 数据库被另一进程占用（如 python/streamlit 或另一个 Node 进程）：${path}。停止对方进程后重试。`);
+            }
+            throw e;
+        }
+        // 时区 pin：DuckDB TIMESTAMPTZ->TIMESTAMP 按 session tz 剥离，必须 UTC（与 Rust 客户端一致，否则 bar 翻倍）
+        await s.conn.run(`SET timezone='UTC'`);
+        await s.healResidueViews();
+        for (const ddl of SCHEMA_STATEMENTS)
+            await s.conn.run(ddl);
+        return s;
+    }
+    /** 串行化辅助（I1）：fn 排进 surfaceLock 链尾执行；本类所有
+     * 「catalog 读型 + DDL」序列的公共入口都必须经它（core 方法无锁，
+     * 供锁内复用，防嵌套自死锁）。 */
+    runExclusive(fn) {
+        const run = this.surfaceLock.then(fn);
+        this.surfaceLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** open() 残落 view heal（重启防 brick，C1）：上次进程退出时 catalog
+     * 可能残留指向已删 parquet 的 read_parquet VIEW（stale 删除 extra/
+     * kline 文件是 sync 常规路径，而 ensureExtraSurfaces 的自愈只在
+     * query() 里跑——sync-only 用法的暴露窗口无界）。本 DuckDB 构建的
+     * CREATE VIEW 是 eager binder：SCHEMA_STATEMENTS 里 qfq/hfq DDL 会
+     * 即解析被引用的 kline / adjustment_factors 的 schema，残落 view 读
+     * 已删文件 footer → IO Error → open() 永久失败（客户端 brick，只能
+     * 手工删库 → 丢 local_manifest 全量重下）。kline 半边（v1.3 direct
+     * 起潜伏）与 extra 半边（v1.4）一并 heal：
+     * ① qfq/hfq 先拆（kline 的依赖者，SCHEMA 重放马上 OR REPLACE 重建）；
+     * ② 处于 VIEW 态的名字一律 DROP 回空表位——重建交给 SCHEMA_STATEMENTS
+     * 重放（IF NOT EXISTS，单一来源）。upsert 模式的 TABLE 数据不受影响；
+     * direct/extra view 由 query()/syncOnce 的 surface 维护重挂。 */
+    async healResidueViews() {
+        await this.c().run('DROP VIEW IF EXISTS kline_qfq; DROP VIEW IF EXISTS kline_hfq');
+        for (const name of SURFACE_HEAL_VIEW_NAMES) {
+            const r = await this.c().run(`SELECT table_type FROM information_schema.tables
+        WHERE table_schema='main' AND table_name='${name}'`);
+            const ty = (await r.getRows())[0]?.[0];
+            if (ty === 'VIEW')
+                await this.c().run(`DROP VIEW IF EXISTS ${name}`);
+        }
+    }
+    c() {
+        if (!this.conn)
+            throw new Error('store closed');
+        return this.conn;
+    }
+    async close() {
+        try {
+            this.conn?.closeSync();
+        }
+        catch { /* already closed */ }
+        this.conn = null;
+        try {
+            this.instance?.closeSync();
+        }
+        catch { /* already closed */ }
+        this.instance = null;
+    }
+    async run(sql, params) {
+        await this.c().run(sql, params);
+    }
+    async query(sql) {
+        // surface 维护整段串行化（I1）且 extra 修复先于 kline refresh（qfq/hfq
+        // view 的 CREATE 在本 DuckDB 构建下即解析被引用的 adjustment_factors
+        // schema——若它还是残落 read_parquet VIEW 会先炸 footer 读取）。两步
+        // 必须在同一临界区：并发交错既会 DROP TABLE 落 VIEW（Catalog Error），
+        // 也会把 extra heal 的名字短暂消失窗口暴露给对方刚建的 qfq/hfq。
+        await this.runExclusive(async () => {
+            await this.ensureExtraSurfacesCore();
+            await this.maybeRefreshKlineSurfaceCore();
+        });
+        const r = await this.c().run(sql);
+        const cols = r.columnNames();
+        const rows = await r.getRows();
+        return rows.map((row) => Object.fromEntries(cols.map((c, i) => [c, mapValue(row[i])])));
+    }
+    /** v2 parquet-direct 查询前置：glob 重展开（view 注册时展开 glob，新文件才
+     * 可见——与服务端 refresh_views 同因）。upsert 模式零开销直通。
+     * sync_meta 读取走原始连接（getSyncMeta → query → 这里，避免自递归）。 */
+    async maybeRefreshKlineSurfaceCore() {
+        if (!this.parquetRoot)
+            return;
+        const r = await this.c().run(`SELECT value FROM sync_meta WHERE key = '${escapeSql(STORE_MODE_KEY)}'`);
+        const rows = await r.getRows();
+        if (rows[0]?.[0] === 'parquet-direct') {
+            await this.refreshKlineViewCore(this.parquetRoot);
+        }
+    }
+    setParquetRoot(root) {
+        this.parquetRoot = root;
+    }
+    /** v2 parquet-direct：kline 以 view 挂载 parquet 目录（hive_partitioning 从
+     * cycle={c} 目录名注入 cycle 列——parquet 本身无 cycle 列；与服务端
+     * query_engine 同款）。CREATE OR REPLACE 保证幂等。空目录（sync 前置调用）
+     * 建同 schema 空 view，read_parquet 空 glob 会 IO Error。 */
+    async refreshKlineView(cacheRoot) {
+        await this.runExclusive(() => this.refreshKlineViewCore(cacheRoot));
+    }
+    async refreshKlineViewCore(cacheRoot) {
+        // kline 可能处于 TABLE 态（open() heal 拆回空表 / upsert 遗留）——
+        // CREATE OR REPLACE VIEW 不跨类型替换，先拆表（依赖视图一并拆，
+        // 随后重建）。VIEW 态则 OR REPLACE 幂等。
+        const t = await this.c().run(`SELECT table_type FROM information_schema.tables
+      WHERE table_schema='main' AND table_name='kline'`);
+        const kty = (await t.getRows())[0]?.[0];
+        if (kty === 'BASE TABLE') {
+            await this.c().run('DROP VIEW IF EXISTS kline_qfq; DROP VIEW IF EXISTS kline_hfq; DROP TABLE kline');
+        }
+        const glob = `${cacheRoot.replaceAll("'", '')}/kline-compacted/cycle=*/*.parquet`;
+        const r = await this.c().run(`SELECT COUNT(*) AS n FROM glob('${glob}')`);
+        const n = Number((await r.getRows())[0][0]);
+        if (n > 0) {
+            await this.c().run(`CREATE OR REPLACE VIEW kline AS
+        SELECT * REPLACE (CAST(ts AS TIMESTAMP) AS ts)
+        FROM read_parquet('${glob}', hive_partitioning=1)`);
+        }
+        else {
+            // 列序与 read_parquet+hive 一致（分区列 cycle 追加在末尾）
+            await this.c().run(`CREATE OR REPLACE VIEW kline AS
+        SELECT CAST(NULL AS TIMESTAMP) AS ts, CAST(NULL AS VARCHAR) AS symbol,
+          CAST(NULL AS DOUBLE) AS open, CAST(NULL AS DOUBLE) AS high,
+          CAST(NULL AS DOUBLE) AS low, CAST(NULL AS DOUBLE) AS close,
+          CAST(NULL AS BIGINT) AS volume, CAST(NULL AS DOUBLE) AS amount,
+          CAST(NULL AS VARCHAR) AS cycle
+        WHERE 1=0`);
+        }
+        await this.c().run(KLINE_QFQ_VIEW_DDL);
+        await this.c().run(KLINE_HFQ_VIEW_DDL);
+    }
+    /** 把 kline 表面（surface）对齐到当前模式：direct → read_parquet VIEW
+     * （v1 遗留 TABLE 先 DROP）；upsert → TABLE（v2 遗留 VIEW 先 DROP 重建，
+     * 服务端回滚场景）。依赖视图 qfq/hfq 一并重建。幂等。 */
+    async ensureKlineSurface(mode, cacheRoot) {
+        await this.runExclusive(() => this.ensureKlineSurfaceCore(mode, cacheRoot));
+    }
+    async ensureKlineSurfaceCore(mode, cacheRoot) {
+        // 原始连接查询（绕过 query() 的 surface 刷新，避免自激）
+        const r = await this.c().run(`SELECT table_type FROM information_schema.tables
+      WHERE table_schema='main' AND table_name='kline'`);
+        const rows = await r.getRows();
+        const ty = rows[0]?.[0];
+        if (mode === 'parquet-direct') {
+            // TABLE→VIEW 拆除在 refreshKlineViewCore 内（heal 后 kline 是空表）
+            await this.refreshKlineViewCore(cacheRoot);
+        }
+        else if (ty === 'VIEW') {
+            await this.run('DROP VIEW IF EXISTS kline_qfq; DROP VIEW IF EXISTS kline_hfq; DROP VIEW kline;');
+            await this.run(KLINE_TABLE_DDL);
+            await this.run(KLINE_QFQ_VIEW_DDL);
+            await this.run(KLINE_HFQ_VIEW_DDL);
+        }
+    }
+    /** sync_meta 读取走原始连接（不经 query() 的 surface 刷新）。 */
+    async getSyncMeta(key) {
+        const r = await this.c().run(`SELECT value FROM sync_meta WHERE key = '${escapeSql(key)}'`);
+        const rows = await r.getRows();
+        return rows.length > 0 ? rows[0][0] : null;
+    }
+    /** extra 数据集 view 挂载：**恒 direct**（服务端聚合已全局去重，天然
+     * disjoint——不跟随 kline 的 store_mode；upsert 模式客户端的 extra 也
+     * 用 view，防聚合 parquet 被灌进 kline 表）。文件存在 → DROP schema 空
+     * 表 + read_parquet VIEW（时间列 CAST 与服务端 view 一致）；缺失 →
+     * 保留空表（新装客户端查询 0 行，体验不变）。
+     *
+     * 残落防护（catalog 判型——DuckDB 的 `DROP TABLE IF EXISTS` 对同名
+     * VIEW 照样报错，IF EXISTS 只兜「名字不存在」）：BASE TABLE 且文件在
+     * → DROP TABLE + 挂 VIEW；VIEW 且文件在 → OR REPLACE 幂等重挂；VIEW
+     * 且文件缺失（stale 删除/清缓存后残落）→ DROP VIEW 回落空表
+     * （SCHEMA_STATEMENTS 全 IF NOT EXISTS 重建）；BASE TABLE 且文件缺
+     * 失 → 不动。adjustment_factors 被 kline_qfq/hfq ASOF JOIN 依赖——
+     * duckdb view 晚绑定允许 DROP 后重解析（回归测试钉住该行为）。 */
+    async ensureExtraSurfaces() {
+        await this.runExclusive(() => this.ensureExtraSurfacesCore());
+    }
+    async ensureExtraSurfacesCore() {
+        if (!this.parquetRoot)
+            return; // 调用方（index.ts/sync）负责 setParquetRoot
+        const fellBack = [];
+        for (const [name, tsCol] of EXTRA_DATASET_VIEW_SPECS) {
+            const path = join(this.parquetRoot, 'extra', `${name}.parquet`);
+            // 原始连接查询（绕过 query() 的 surface 刷新，避免自激）
+            const r = await this.c().run(`SELECT table_type FROM information_schema.tables
+        WHERE table_schema='main' AND table_name='${name}'`);
+            const ty = (await r.getRows())[0]?.[0];
+            if (existsSync(path)) {
+                // 挂 view 前先 DROP 同名 TABLE（CREATE OR REPLACE VIEW 不跨类型
+                // 替换；已是 VIEW 则 OR REPLACE 幂等重挂）。IF EXISTS 双保险：
+                // catalog 判型已排除类型错配，兜并发 DDL 竞态。
+                if (ty === 'BASE TABLE') {
+                    await this.run(`DROP TABLE IF EXISTS ${name}`);
+                }
+                const cast = tsCol
+                    ? `SELECT * REPLACE (CAST(${tsCol} AS TIMESTAMP) AS ${tsCol})`
+                    : 'SELECT *';
+                await this.run(`CREATE OR REPLACE VIEW ${name} AS ${cast}
+          FROM read_parquet('${escapeSql(path)}')`);
+            }
+            else if (ty === 'VIEW') {
+                // 残落 view（底座文件已删）：DROP 回落空表
+                await this.run(`DROP VIEW IF EXISTS ${name}`);
+                fellBack.push(name);
+            }
+        }
+        if (fellBack.length > 0) {
+            // 只重建被 DROP 的 extra 空表（SCHEMA_STATEMENTS 里现成 DDL，单一
+            // 来源）——不跑全量：qfq/hfq 的 CREATE VIEW 会即解析被引用的
+            // kline，若 kline 此刻也是残落 view（整缓存被清场景）会 IO Error。
+            for (const name of fellBack) {
+                const ddl = SCHEMA_STATEMENTS.find((s) => s.startsWith(`CREATE TABLE IF NOT EXISTS ${name} `));
+                if (ddl)
+                    await this.run(ddl);
+            }
+        }
+    }
+    async setSyncMeta(key, value) {
+        await this.run(`INSERT OR REPLACE INTO sync_meta (key, value) VALUES (?, ?)`, [key, value]);
+    }
+    async clearLocalManifest() {
+        await this.run('DELETE FROM local_manifest');
+    }
+    async countParquetRows(parquetPath) {
+        const r = await this.c().run(`SELECT COUNT(*) AS n FROM read_parquet('${escapeSql(parquetPath)}')`);
+        return Number((await r.getRows())[0][0]);
+    }
+    async upsertKlineFromFile(parquetPath, cycle) {
+        await this.run(`INSERT OR REPLACE INTO kline (ts, symbol, cycle, open, high, low, close, volume, amount)
+      SELECT ts, symbol, '${escapeSql(cycle)}', open, high, low, close, volume, amount
+      FROM read_parquet('${escapeSql(parquetPath)}')`);
+    }
+    async deleteKlineYear(cycle, year) {
+        const [lo, hi] = yearBounds(year);
+        await this.run(`DELETE FROM kline WHERE cycle = ? AND ts >= CAST(? AS TIMESTAMP) AND ts <= CAST(? AS TIMESTAMP)`, [cycle, lo, hi]);
+    }
+    /** 按文件 ts 边界删除（含端点，口径同 deleteKlineYear）。月切片 ts 互不重叠，不会误伤相邻月。 */
+    async deleteKlineRange(cycle, tsMin, tsMax) {
+        await this.run(`DELETE FROM kline WHERE cycle = ? AND ts >= CAST(? AS TIMESTAMP) AND ts <= CAST(? AS TIMESTAMP)`, [cycle, tsMin, tsMax]);
+    }
+    async listLocalManifest() {
+        const rows = await this.query('SELECT path, sha256 FROM local_manifest');
+        return new Map(rows.map((r) => [r.path, r.sha256]));
+    }
+    /** 全字段 local_manifest（stale per-file ts 边界删除用；NULL 边界 → null，调用方回退整年）。 */
+    async listLocalManifestFull() {
+        const rows = await this.query('SELECT path, sha256, cycle, year, ts_min, ts_max FROM local_manifest');
+        return new Map(rows.map((r) => [r.path, {
+                path: r.path,
+                sha256: r.sha256,
+                cycle: r.cycle,
+                year: r.year === null || r.year === undefined ? null : Number(r.year),
+                ts_min: r.ts_min === null || r.ts_min === undefined ? null : sqlTs(String(r.ts_min)),
+                ts_max: r.ts_max === null || r.ts_max === undefined ? null : sqlTs(String(r.ts_max)),
+            }]));
+    }
+    async upsertLocalManifest(f) {
+        await this.run(`INSERT OR REPLACE INTO local_manifest
+      (path, sha256, size, row_count, cycle, year, ts_min, ts_max, synced_at)
+      VALUES (?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), now())`, [f.path, f.sha256, f.size, f.row_count, f.cycle, f.year ?? null, f.ts_min, f.ts_max]);
+    }
+    async deleteLocalManifest(paths) {
+        for (let i = 0; i < paths.length; i += 500) {
+            const chunk = paths.slice(i, i + 500);
+            await this.run(`DELETE FROM local_manifest WHERE path IN (${chunk.map(() => '?').join(',')})`, chunk);
+        }
+    }
+    async getEtag() {
+        const rows = await this.query(`SELECT value FROM sync_meta WHERE key = 'manifest_etag'`);
+        return rows.length > 0 ? rows[0].value : null;
+    }
+    async setEtag(etag) {
+        await this.run(`INSERT OR REPLACE INTO sync_meta (key, value) VALUES ('manifest_etag', ?)`, [etag]);
+    }
+}
+function escapeSql(s) {
+    return s.replaceAll("'", "''");
+}
+/** mapValue 产出的 ISO（'2026-02-05T15:00:00.000Z'）→ SQL timestamp 字面量（'2026-02-05 15:00:00'）。 */
+function sqlTs(iso) {
+    return iso.replace('T', ' ').replace(/(\.\d+)?Z$/, '');
+}
+/** DuckDB node-api 值 -> JSON 友好值（对齐 Python cell_to_json 行为）。 */
+function mapValue(v) {
+    if (v === null || typeof v !== 'object') {
+        if (typeof v === 'bigint')
+            return Number(v);
+        return v;
+    }
+    const name = v.constructor?.name;
+    if (name === 'DuckDBTimestampValue' || name === 'DuckDBTimestampTZValue') {
+        return new Date(String(v).replace(' ', 'T') + 'Z').toISOString();
+    }
+    if (name === 'DuckDBDecimalValue')
+        return v.toDouble();
+    if (name === 'DuckDBDateValue' || name === 'DuckDBTimeValue' || name === 'DuckDBIntervalValue'
+        || name === 'DuckDBUUIDValue' || name === 'DuckDBBigIntValue' || name === 'DuckDBHugeIntValue') {
+        return String(v);
+    }
+    return v;
+}

package/dist/sync.d.ts

@@ -0,0 +1,10 @@
+import type { DuckdbStore } from './store.js';
+import type { TickdbHttp } from './http.js';
+import type { SyncReport } from './types.js';
+/** 一轮完整同步：manifest(v1.3 disjoint → 模式判定/切换，版本门) -> diff
+ * -> stale 删除（direct/extra 删文件 / upsert per-file ts 边界删行）->
+ * runPool 并发 fetch+apply（mirror-first 全量文件；extra/ 恒 direct）->
+ * 零错误才写 etag。 */
+export declare function syncOnce(store: DuckdbStore, http: TickdbHttp, cacheDir: string, opts?: {
+    downloadConcurrency?: number;
+}): Promise<SyncReport>;

package/dist/sync.js

@@ -0,0 +1,142 @@
+import { join } from 'node:path';
+import { mkdirSync, rmSync } from 'node:fs';
+import { STORE_MODE_KEY } from './store.js';
+import { computeDiff } from './diff.js';
+import { isExtraFile, parseCycleYear, runPool } from './util.js';
+/** v2 嵌套布局（镜像服务端路径，hive cycle 注入依赖 cycle={c} 目录层级）。 */
+const cachePath = (cacheDir, p) => join(cacheDir, p);
+/** 一轮完整同步：manifest(v1.3 disjoint → 模式判定/切换，版本门) -> diff
+ * -> stale 删除（direct/extra 删文件 / upsert per-file ts 边界删行）->
+ * runPool 并发 fetch+apply（mirror-first 全量文件；extra/ 恒 direct）->
+ * 零错误才写 etag。 */
+export async function syncOnce(store, http, cacheDir, opts = {}) {
+    const report = {
+        notModified: false, filesTotal: 0, filesFetched: 0, filesUnchanged: 0,
+        rowsUpserted: 0, staleDeleted: 0, mirrorFetched: 0, mirrorFallbacks: 0, errors: [],
+    };
+    const etag = await store.getEtag();
+    const res = await http.fetchManifest(etag ?? undefined);
+    if (res.kind === 'not_modified') {
+        report.notModified = true;
+        report.filesTotal = (await store.listLocalManifest()).size;
+        report.filesUnchanged = report.filesTotal;
+        return report;
+    }
+    const { manifest, etag: newEtag } = res;
+    report.filesTotal = manifest.files.length;
+    // ① 模式判定 + 切换（v1.3 disjoint → parquet-direct：文件即行集不 upsert）。
+    // 版本门：只有携带权威 disjoint 字段的 body（v1.3/v1.4）才允许驱动
+    // store_mode 翻转/缓存清除——pre-v1.4 服务端对未知 ?version=v1.4 走默认
+    // 分支回 v1.1 body（disjoint 缺省），若无此门 direct 客户端会被静默翻回
+    // upsert：清缓存 + 全量重下 + 亿行 upsert（小时级慢路）。旧版本 body
+    // 沿袭本地既有 store_mode（无记录默认 duckdb-upsert）。
+    const prevMode = await store.getSyncMeta(STORE_MODE_KEY);
+    const versionGated = manifest.version === 'v1.3' || manifest.version === 'v1.4';
+    const mode = versionGated
+        ? (manifest.disjoint === true ? 'parquet-direct' : 'duckdb-upsert')
+        : (prevMode ?? 'duckdb-upsert');
+    const direct = mode === 'parquet-direct';
+    if (prevMode !== mode) {
+        // 布局全清重来：v1→v2 旧 flat 文件/表行全废；v2→v1 回退按 manifest 重拉重灌。
+        // 例外：本地无 store_mode（v1 客户端升级）且服务端仍 upsert —— 数据布局
+        // 未变，保留 local_manifest/缓存，避免一次无意义的全量重下。
+        const wipe = !(prevMode === null && !direct);
+        if (wipe) {
+            rmSync(cacheDir, { recursive: true, force: true });
+            mkdirSync(cacheDir, { recursive: true });
+            await store.clearLocalManifest();
+        }
+        await store.setSyncMeta(STORE_MODE_KEY, mode);
+    }
+    store.setParquetRoot(cacheDir);
+    // extra surface 先于 kline surface：wipe（模式切换清缓存）后 extra view
+    // 残落，ensureKlineSurface 里 qfq/hfq 的 CREATE 会即解析 adjustment_
+    // factors（read_parquet view 读已删文件 footer → IO Error），先回落
+    // 空表再动 kline。
+    await store.ensureExtraSurfaces();
+    await store.ensureKlineSurface(mode, cacheDir);
+    const diff = computeDiff(manifest.files, await store.listLocalManifest());
+    report.filesUnchanged = diff.unchanged;
+    // ② stale 先删（best-effort：单条失败记 error 不中断）。
+    // direct → 删本地文件（行随文件消失）；upsert → 优先按该文件自己的 ts 边界删
+    // （月文件消失只删它那个月；边界缺失回退整年删除）。
+    // extra/ 前缀在任何模式下都按删文件处理（它是 view 的底座文件，行不在
+    // kline 表里——upsert 模式不分流会走 parseCycleYear → 报错）。
+    const localFull = direct ? new Map() : await store.listLocalManifestFull();
+    const staleOk = [];
+    for (const p of diff.stale) {
+        try {
+            if (direct || isExtraFile(p)) {
+                rmSync(cachePath(cacheDir, p), { force: true });
+            }
+            else {
+                const { cycle, year } = parseCycleYear(p);
+                const row = localFull.get(p);
+                if (row?.ts_min && row?.ts_max) {
+                    await store.deleteKlineRange(cycle, row.ts_min, row.ts_max);
+                }
+                else {
+                    await store.deleteKlineYear(cycle, year);
+                }
+            }
+            staleOk.push(p);
+        }
+        catch (e) {
+            report.errors.push(`stale ${p}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (staleOk.length > 0) {
+        await store.deleteLocalManifest(staleOk);
+        report.staleDeleted = staleOk.length;
+    }
+    // ③ 并发 fetch + apply（单文件失败不中断整轮）。mirror-first：所有文件
+    // （v1.2 的 frozen gate 移除——上传面已扩到全部文件，sha 校验兜底）；
+    // 镜像失败/非 200/sha 不符 → 回落 VPS（带重试），不计 error。
+    // extra/ 聚合文件无视入参 direct——upsert 模式客户端也不灌表（聚合
+    // parquet 的 schema 不是 kline 形状，误灌会 INSERT 报错；本地由
+    // ensureExtraSurfaces 挂 view 直读）。
+    const mirrorBase = manifest.mirror_base_url?.replace(/\/$/, '');
+    await runPool(diff.toFetch, opts.downloadConcurrency ?? 4, async (f) => {
+        try {
+            const dest = cachePath(cacheDir, f.path);
+            mkdirSync(join(dest, '..'), { recursive: true });
+            let viaMirror = false;
+            if (mirrorBase) {
+                const mUrl = `${mirrorBase}/${f.path}`;
+                try {
+                    await http.downloadMirrorToFile(mUrl, dest, { size: f.size, sha256: f.sha256 });
+                    viaMirror = true;
+                    report.mirrorFetched += 1;
+                }
+                catch {
+                    report.mirrorFallbacks += 1; // 回落 VPS，镜像失败不算 error
+                }
+            }
+            if (!viaMirror) {
+                await http.downloadToFile(f.path, f.path, dest, { size: f.size, sha256: f.sha256 });
+            }
+            const fileDirect = direct || isExtraFile(f.path);
+            if (fileDirect) {
+                // v2/extra：文件即行集——不 upsert、不删文件
+                await store.upsertLocalManifest(f);
+                report.rowsUpserted += 0;
+            }
+            else {
+                const rows = await store.countParquetRows(dest);
+                await store.upsertKlineFromFile(dest, f.cycle);
+                await store.upsertLocalManifest(f);
+                rmSync(dest, { force: true });
+                report.rowsUpserted += rows;
+            }
+            report.filesFetched += 1;
+        }
+        catch (e) {
+            report.errors.push(`${f.path}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    // ④ 仅零错误轮写 etag（304 => 本地确实与该 manifest 一致）
+    if (report.errors.length === 0 && newEtag) {
+        await store.setEtag(newEtag);
+    }
+    return report;
+}