tickdb-ts 0.2.0 → 0.3.0

package/dist/http.js

@@ -22,7 +22,10 @@ export class TickdbHttp {
         const headers = this.headers();
         if (ifNoneMatch)
             headers['If-None-Match'] = ifNoneMatch;
-        const res = await fetch(`${this.serverUrl}/api/v1/manifest?version=v1.3`, {
+        // v1.4 = v1.3 + extra/<name>.parquet 聚合数据集条目（disjoint 门保留）。
+        // pre-v1.4 服务端对未知 version 走默认分支回 v1.1 body——parseManifest
+        // 全版本兼容；syncOnce 的版本门保证旧 body 不翻转 store_mode。
+        const res = await fetch(`${this.serverUrl}/api/v1/manifest?version=v1.4`, {
             headers,
             signal: AbortSignal.timeout(60_000),
         });

package/dist/manifest.js

@@ -1,9 +1,11 @@
+const SUPPORTED_VERSIONS = ['v1', 'v1.1', 'v1.2', 'v1.3', 'v1.4'];
 /** 把线上 JSON（snake_case）解析成 Manifest，字段不合法直接抛错。 */
 export function parseManifest(raw) {
     if (typeof raw !== 'object' || raw === null)
         throw new Error('manifest: not an object');
     const r = raw;
-    if (r.version !== 'v1' && r.version !== 'v1.1' && r.version !== 'v1.2' && r.version !== 'v1.3') {
+    const version = SUPPORTED_VERSIONS.find((v) => v === r.version);
+    if (!version) {
         throw new Error(`unsupported manifest version: ${String(r.version)}`);
     }
     if (!Array.isArray(r.files))
@@ -30,7 +32,7 @@ export function parseManifest(raw) {
         };
     });
     return {
-        version: r.version,
+        version,
         schema: typeof r.schema === 'string' ? r.schema : 'symbol-partitioned',
         generatedAt: typeof r.generated_at === 'string' ? r.generated_at : '',
         files,

package/dist/store.d.ts

@@ -10,13 +10,42 @@ export interface LocalManifestRow {
 }
 /** 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>;
@@ -24,19 +53,36 @@ export declare class DuckdbStore {
     /** v2 parquet-direct 查询前置：glob 重展开（view 注册时展开 glob，新文件才
      * 可见——与服务端 refresh_views 同因）。upsert 模式零开销直通。
      * sync_meta 读取走原始连接（getSyncMeta → query → 这里，避免自递归）。 */
-    private maybeRefreshKlineSurface;
+    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>;

package/dist/store.js

@@ -1,3 +1,5 @@
+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'）。 */
@@ -24,7 +26,7 @@ const KLINE_HFQ_VIEW_DDL = `CREATE OR REPLACE VIEW kline_hfq AS
     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`;
-const SCHEMA_STATEMENTS = [
+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))`,
@@ -62,11 +64,32 @@ const SCHEMA_STATEMENTS = [
     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();
@@ -83,10 +106,42 @@ export class DuckdbStore {
         }
         // 时区 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');
@@ -108,7 +163,15 @@ export class DuckdbStore {
         await this.c().run(sql, params);
     }
     async query(sql) {
-        await this.maybeRefreshKlineSurface();
+        // 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();
@@ -117,13 +180,13 @@ export class DuckdbStore {
     /** v2 parquet-direct 查询前置：glob 重展开（view 注册时展开 glob，新文件才
      * 可见——与服务端 refresh_views 同因）。upsert 模式零开销直通。
      * sync_meta 读取走原始连接（getSyncMeta → query → 这里，避免自递归）。 */
-    async maybeRefreshKlineSurface() {
+    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.refreshKlineView(this.parquetRoot);
+            await this.refreshKlineViewCore(this.parquetRoot);
         }
     }
     setParquetRoot(root) {
@@ -134,6 +197,18 @@ export class DuckdbStore {
      * 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]);
@@ -159,16 +234,17 @@ export class DuckdbStore {
      * （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') {
-            if (ty === 'BASE TABLE') {
-                await this.run('DROP VIEW IF EXISTS kline_qfq; DROP VIEW IF EXISTS kline_hfq; DROP TABLE kline;');
-            }
-            await this.refreshKlineView(cacheRoot);
+            // 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;');
@@ -183,6 +259,62 @@ export class DuckdbStore {
         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]);
     }

package/dist/sync.d.ts

@@ -1,9 +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 删文件 / upsert per-file ts 边界删行）-> runPool 并发 fetch+apply
- * （mirror-first 全量文件）-> 零错误才写 etag。 */
+/** 一轮完整同步：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

@@ -2,12 +2,13 @@ import { join } from 'node:path';
 import { mkdirSync, rmSync } from 'node:fs';
 import { STORE_MODE_KEY } from './store.js';
 import { computeDiff } from './diff.js';
-import { parseCycleYear, runPool } from './util.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 删文件 / upsert per-file ts 边界删行）-> runPool 并发 fetch+apply
- * （mirror-first 全量文件）-> 零错误才写 etag。 */
+/** 一轮完整同步：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,
@@ -24,9 +25,17 @@ export async function syncOnce(store, http, cacheDir, opts = {}) {
     const { manifest, etag: newEtag } = res;
     report.filesTotal = manifest.files.length;
     // ① 模式判定 + 切换（v1.3 disjoint → parquet-direct：文件即行集不 upsert）。
-    const mode = manifest.disjoint === true ? 'parquet-direct' : 'duckdb-upsert';
-    const direct = mode === 'parquet-direct';
+    // 版本门：只有携带权威 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 —— 数据布局
@@ -40,17 +49,24 @@ export async function syncOnce(store, http, cacheDir, opts = {}) {
         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) {
+            if (direct || isExtraFile(p)) {
                 rmSync(cachePath(cacheDir, p), { force: true });
             }
             else {
@@ -76,6 +92,9 @@ export async function syncOnce(store, http, cacheDir, opts = {}) {
     // ③ 并发 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 {
@@ -96,8 +115,9 @@ export async function syncOnce(store, http, cacheDir, opts = {}) {
             if (!viaMirror) {
                 await http.downloadToFile(f.path, f.path, dest, { size: f.size, sha256: f.sha256 });
             }
-            if (direct) {
-                // v2：文件即行集——不 upsert、不删文件
+            const fileDirect = direct || isExtraFile(f.path);
+            if (fileDirect) {
+                // v2/extra：文件即行集——不 upsert、不删文件
                 await store.upsertLocalManifest(f);
                 report.rowsUpserted += 0;
             }

package/dist/types.d.ts

@@ -13,8 +13,11 @@ export interface FileEntry {
     /** v1.2：文件已冻结上云（内容永不再变，可从镜像下载）。 */
     frozen?: boolean;
 }
+/** 支持的 manifest 版本字面量（parseManifest 收窄到这个联合；新增版本
+ * 时同步 SUPPORTED_VERSIONS 与 sync.ts 的版本门判定）。 */
+export type ManifestVersion = 'v1' | 'v1.1' | 'v1.2' | 'v1.3' | 'v1.4';
 export interface Manifest {
-    version: string;
+    version: ManifestVersion;
     schema: string;
     generatedAt: string;
     files: FileEntry[];

package/dist/util.d.ts

@@ -4,6 +4,10 @@ export declare function parseCycleYear(path: string): {
     cycle: string;
     year: number;
 };
+/** extra/ 前缀 = 聚合数据集文件（manifest v1.4）：恒 direct 分流——
+ * 落盘 + view 直读，不进 kline upsert / 按 cycle-year 删行逻辑
+ * （对齐 Rust is_extra_file）。 */
+export declare function isExtraFile(p: string): boolean;
 export declare function yearBounds(year: number): [string, string];
 export declare function expandHome(p: string): string;
 export declare const nowSec: () => number;

package/dist/util.js

@@ -18,6 +18,12 @@ export function parseCycleYear(path) {
         throw new Error(`cannot parse cycle/year from manifest path: ${path}`);
     return { cycle: m[1], year: Number(m[2]) };
 }
+/** extra/ 前缀 = 聚合数据集文件（manifest v1.4）：恒 direct 分流——
+ * 落盘 + view 直读，不进 kline upsert / 按 cycle-year 删行逻辑
+ * （对齐 Rust is_extra_file）。 */
+export function isExtraFile(p) {
+    return p.startsWith('extra/');
+}
 export function yearBounds(year) {
     return [`${year}-01-01 00:00:00`, `${year}-12-31 23:59:59`];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickdb-ts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "offline-first TypeScript client for tickdb (A-share market data): manifest sync + local DuckDB",
   "type": "module",
   "main": "dist/index.js",