tickdb-ts 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# tickdb-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+offline-first A 股 K 线客户端（TypeScript / Node）。服务端（`growinpublic.ai/tickdb`）从通达信拉行情写 parquet，本客户端在本地维护 DuckDB，增量同步、离线可查——与 Rust CLI / Python 绑定同款体验。
+
+## 安装
+
+要求 Node ≥ 18（开发机验证：Node 22）。
+
+```bash
+# 本仓库内开发
+cd tickdb/clients/tickdb-ts
+npm install
+npm run build        # 产出 dist/
+
+# 在你自己的项目里使用
+npm install /path/to/growinpublic/tickdb/clients/tickdb-ts
+# 或打 tarball: npm pack → npm install tickdb-ts-0.1.0.tgz
+```
+
+## Token
+
+`tik_` 开头的 opaque 字符串，`read` scope 即可。获取方式：
+
+- 主站 `/console`（admin 在页面上签发/吊销 tickdb token）
+- 或找管理员执行 `tickdb token-issue --label <名字> --scopes read`
+
+⚠️ token 明文存在 `<dataDir>/config.json`，注意目录权限；泄露了让管理员吊销重发。
+
+## 五分钟上手
+
+```ts
+import tickdb from 'tickdb-ts';
+
+await tickdb.init({ token: 'tik_...' });   // 默认 dataDir ~/.tickdb；autoSync 默认 true（300s daemon + 立即一轮）
+await tickdb.sync();                        // 显式同步一轮（首次全量 ~1GB，耐心等）
+
+const rows = await tickdb.query(`
+  SELECT ts, close, volume FROM kline
+  WHERE symbol = 'SH600000' AND cycle = 'D'
+  ORDER BY ts DESC LIMIT 5`);
+console.log(rows);
+// [{ ts: '2026-10-22T15:00:00.000Z', close: 12.34, volume: 5678900 }, ...]
+```
+
+不想自动同步：`init({ token, autoSync: false })`，之后自己调 `await tickdb.sync()`。
+
+## API 参考
+
+| 方法 | 说明 |
+|---|---|
+| `init(opts?)` | 初始化。`opts`: `dataDir`（默认 `~/.tickdb`）、`token`、`serverUrl`（默认生产地址）、`autoSync`（默认 `true`）、`syncIntervalSecs`（默认 300）。幂等——重复调用直接 return。autoSync 时起后台 daemon 并立即后台同步一轮 |
+| `sync()` | 显式同步一轮，`await` 完成返回 `SyncReport`；**错误上抛**。并发调用第二个直接抛 `sync already running` |
+| `syncStart()` | 后台立即一轮（fire-and-forget），错误只进 `syncStatus().lastError`，进程不 crash |
+| `syncDaemonStart(intervalSecs?)` | 起/重启后台 daemon（默认 300s，强制 ≥ 60s） |
+| `syncDaemonStop()` | 停 daemon |
+| `syncStatus()` | 返回 `SyncStatus` 快照（见下），反映**最近完成的一轮** |
+| `query(sql)` | 对本地 DuckDB 跑任意 SQL，返回 `Record<string, unknown>[]`；TIMESTAMP → ISO 字符串、DATE → `YYYY-MM-DD`、数值 → number |
+| `close()` | 停 daemon + 关 DuckDB（进程退出前可选调用） |
+
+```ts
+interface SyncReport {
+  notModified: boolean;   // true = ETag 304 整轮 no-op
+  filesTotal: number; filesFetched: number; filesUnchanged: number;
+  rowsUpserted: number; staleDeleted: number;
+  mirrorFetched: number; mirrorFallbacks: number;  // v1.2：镜像命中 / 回落 VPS 计数
+  errors: string[];       // 单文件失败不中断整轮
+}
+interface SyncStatus {
+  running: boolean; startedAt: number; finishedAt: number;  // unix 秒
+  filesTotal: number; filesFetched: number; filesUnchanged: number;
+  rowsUpserted: number; staleDeleted: number; errorsCount: number;
+  daemonIntervalSecs: number; daemonRunning: boolean;
+  lastError: string | null;
+}
+```
+
+## 本地数据
+
+```
+~/.tickdb/                 （或你传的 dataDir）
+├── config.json            # token/serverUrl/interval
+├── tickdb.duckdb          # 本地 DuckDB（数据 + local_manifest + sync_meta）
+└── .cache/parquet/        # 下载暂存，upsert 成功后即删，正常为空
+```
+
+**kline 表**（主键 `symbol, cycle, ts`）：
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| ts | TIMESTAMP | bar 时间（A 股收盘 15:00 的日线 ts 就是 15:00:00，见 FAQ） |
+| symbol | VARCHAR | `SH600000` / `SZ000001` 风格 |
+| cycle | VARCHAR | `1m / 5m / 15m / 30m / 60m / D` |
+| open/high/low/close | DOUBLE | 价格 |
+| volume | BIGINT | 成交量（股） |
+| amount | DOUBLE | 成交额 |
+
+另有 `local_manifest`（已同步文件清单）、`sync_meta`（manifest ETag），以及与 Rust 客户端对齐的 extra 表和 `kline_qfq` / `kline_hfq` 复权视图——**v1 同步协议只覆盖 kline**，extra 表（含 `adjustment_factors`）没有数据，复权视图的 factor 恒为 1（等价不复权），后续版本再开。
+
+常用 SQL：
+
+```sql
+-- 个股近 30 个交易日日线
+SELECT ts, open, high, low, close, volume FROM kline
+WHERE symbol = 'SH600000' AND cycle = 'D'
+  AND ts >= NOW()::TIMESTAMP - INTERVAL '30 DAY'
+ORDER BY ts;
+
+-- 全市场今日（最新一天）涨幅榜前 10
+SELECT symbol, close / lag_close - 1 AS pct
+FROM (
+  SELECT symbol, close, LAG(close) OVER (PARTITION BY symbol ORDER BY ts) AS lag_close,
+         ROW_NUMBER() OVER (PARTITION BY symbol ORDER BY ts DESC) AS rn
+  FROM kline WHERE cycle = 'D'
+) WHERE rn = 1 AND lag_close IS NOT NULL
+ORDER BY pct DESC LIMIT 10;
+
+-- 同步状态
+SELECT COUNT(*) AS files, MAX(synced_at) AS last_sync FROM local_manifest;
+```
+
+## 同步机制（简版）
+
+1. `GET /api/v1/manifest?version=v1.2` 带 `If-None-Match`，未变收 304 整轮 no-op
+2. 与本地 `local_manifest` 按 `path + sha256` 求 diff
+3. 服务端消失的文件（stale）优先按该文件自己的 `ts_min..ts_max` 边界删本地行（月文件消失只删它那个月）；边界缺失回退整年删除
+4. 串行下载变化的 parquet：流式写 `.part` → size + sha256 双校验 → 原子 rename（3 次重试线性退避）。frozen 文件先试镜像（manifest v1.2 下发的公开 URL，无认证），失败/污染回落 VPS 不计错误
+5. `INSERT OR REPLACE` 进 kline 表——**union 语义**：同主键的修正 bar 覆盖旧值；新文件里消失的行保留本地
+6. 只有整轮零错误才写回 ETag（保证 304 ⇒ 本地确实与服务端一致）
+
+## FAQ
+
+**Q: ts 为什么日线是 15:00:00？**
+A 股收盘 15:00 的墙钟时间。服务端 parquet 的时间戳是 `TIMESTAMPTZ`，本客户端打开 DuckDB 后第一句就 `SET timezone='UTC'` 再转 TIMESTAMP——和 Rust/Python 客户端同一套时区 pin 逻辑，保证去重主键一致、bar 不翻倍。查询时拿到的 ISO 字符串（带 Z）就是当日墙钟时间。
+
+**Q: 报「tickdb 数据库被另一进程占用」？**
+DuckDB 是单写者。同一份 `tickdb.duckdb` 被别的进程开着（python/streamlit/另一个 Node 进程）就会锁冲突。停掉对方进程，或者给本客户端换个 `dataDir`。
+
+**Q: securities / dividend / financial_basic 这些表怎么没数据？**
+服务端 manifest（v1/v1.1/v1.2）只覆盖 kline（K 线）。Python/Rust 客户端同样如此。要查财报/分红请走服务端 HTTP API（`POST /tickdb/api/v1/query`）或等后续版本扩展同步协议。
+
+**Q: 断网能用吗？**
+能。`query()` 全部走本地 DuckDB。`sync()` 会报错（显式调用错误上抛）；后台 daemon 的错误只记在 `syncStatus().lastError`，恢复后下一轮自动追上。
+
+**Q: 首次同步要多久 / 占多大空间？**
+当前生产数据 ~60+ 个 parquet / ~1GB / 9000 万+ bar，串行下载，跨国链路大约 10-40 分钟。之后每轮只重拉 sha 变化的文件（通常只有当年/当月的几个）。
+
+**Q: 和 Rust CLI / Python 绑定能用同一个 dataDir 吗？**
+不建议。三者 schema 一致，但 DuckDB 单写者 + 版本差异，先后打开同一 db 文件容易锁冲突。给 TS 客户端单独一个 `dataDir` 最省心。
+
+## 开发
+
+```bash
+npm test            # node:test + tsx，43 个测试（含 fixture 服务器 + 镜像回落集成测试）
+npm run typecheck   # tsc --noEmit
+npm run build       # tsc -> dist/
+```
+
+协议实现与 Rust 客户端（`crates/tickdb-client`）逐条对照：
+
+| 本包 | Rust 对照 |
+|---|---|
+| `src/http.ts` | `http_client.rs`（ETag/304、流式下载校验） |
+| `src/sync.ts` | `manifest_sync.rs`（syncOnce 全流程） |
+| `src/diff.ts` | `manifest_sync.rs::compute_diff` |
+| `src/store.ts` | `duckdb_store.rs`（schema/upsert/时区 pin） |
+| `src/daemon.ts` + `src/status.ts` | `tickdb-python/src/lib.rs` 的 daemon/atomics |

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+import type { InitOptions } from './types.js';
+export declare const DEFAULT_SERVER_URL = "https://growinpublic.ai/tickdb";
+export interface ResolvedConfig {
+    dataDir: string;
+    token: string;
+    serverUrl: string;
+    syncIntervalSecs: number;
+    downloadConcurrency: number;
+}
+export declare function configPath(dataDir: string): string;
+export declare function loadMergedConfig(dataDir: string, opts: InitOptions): ResolvedConfig;
+export declare function saveConfig(cfg: ResolvedConfig): void;

package/dist/config.js

@@ -0,0 +1,24 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const DEFAULT_SERVER_URL = 'https://growinpublic.ai/tickdb';
+export function configPath(dataDir) {
+    return join(dataDir, 'config.json');
+}
+export function loadMergedConfig(dataDir, opts) {
+    let saved = {};
+    try {
+        saved = JSON.parse(readFileSync(configPath(dataDir), 'utf8'));
+    }
+    catch { /* absent or corrupt: start fresh */ }
+    const token = opts.token && opts.token.length > 0 ? opts.token : (saved.token ?? '');
+    const serverUrl = opts.serverUrl && opts.serverUrl.length > 0 ? opts.serverUrl : (saved.serverUrl ?? DEFAULT_SERVER_URL);
+    const syncIntervalSecs = opts.syncIntervalSecs ?? saved.syncIntervalSecs ?? 300;
+    const downloadConcurrency = Math.min(6, Math.max(1, opts.downloadConcurrency ?? saved.downloadConcurrency ?? 4));
+    return { dataDir, token, serverUrl, syncIntervalSecs, downloadConcurrency };
+}
+export function saveConfig(cfg) {
+    writeFileSync(configPath(cfg.dataDir), JSON.stringify({
+        token: cfg.token, serverUrl: cfg.serverUrl, syncIntervalSecs: cfg.syncIntervalSecs,
+        downloadConcurrency: cfg.downloadConcurrency,
+    }, null, 2));
+}

package/dist/daemon.d.ts

@@ -0,0 +1,11 @@
+import type { SyncStateHolder } from './status.js';
+export interface DaemonHandle {
+    tickNow(): Promise<void>;
+    stop(): void;
+}
+/** setInterval(unref) + generation 计数；tickNow 供测试与「立即触发」。 */
+export declare function createDaemon(opts: {
+    onTick: () => Promise<void>;
+    intervalSecs: number;
+    state: SyncStateHolder;
+}): DaemonHandle;

package/dist/daemon.js

@@ -0,0 +1,32 @@
+let generation = 0;
+/** setInterval(unref) + generation 计数；tickNow 供测试与「立即触发」。 */
+export function createDaemon(opts) {
+    generation += 1;
+    const myGen = generation;
+    const intervalSecs = Math.max(60, opts.intervalSecs);
+    opts.state.update({ daemonIntervalSecs: intervalSecs, daemonRunning: true });
+    const runTick = async () => {
+        if (myGen !== generation)
+            return;
+        if (opts.state.get().running)
+            return;
+        try {
+            await opts.onTick();
+        }
+        catch {
+            // onTick 自己负责把错误写进 state.lastError；daemon 永不 crash 进程
+        }
+    };
+    const timer = setInterval(() => void runTick(), intervalSecs * 1000);
+    timer.unref();
+    return {
+        tickNow: runTick,
+        stop() {
+            if (myGen !== generation)
+                return;
+            generation += 1;
+            clearInterval(timer);
+            opts.state.update({ daemonRunning: false, daemonIntervalSecs: 0 });
+        },
+    };
+}

package/dist/diff.d.ts

@@ -0,0 +1,8 @@
+import type { FileEntry } from './types.js';
+export interface ManifestDiff {
+    toFetch: FileEntry[];
+    stale: string[];
+    unchanged: number;
+}
+/** 纯函数：只按 path + sha256 判定（与 Rust 客户端一致）。local: path -> sha256。 */
+export declare function computeDiff(serverFiles: FileEntry[], local: Map<string, string>): ManifestDiff;

package/dist/diff.js

@@ -0,0 +1,16 @@
+/** 纯函数：只按 path + sha256 判定（与 Rust 客户端一致）。local: path -> sha256。 */
+export function computeDiff(serverFiles, local) {
+    const serverPaths = new Set(serverFiles.map((f) => f.path));
+    const toFetch = [];
+    let unchanged = 0;
+    for (const f of serverFiles) {
+        if (local.get(f.path) === f.sha256)
+            unchanged++;
+        else
+            toFetch.push(f);
+    }
+    const stale = [...local.keys()].filter((p) => !serverPaths.has(p));
+    toFetch.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    stale.sort();
+    return { toFetch, stale, unchanged };
+}

package/dist/http.d.ts

@@ -0,0 +1,32 @@
+import type { Manifest } from './types.js';
+export type ManifestResult = {
+    kind: 'not_modified';
+} | {
+    kind: 'fresh';
+    manifest: Manifest;
+    etag?: string;
+};
+/** 下载总超时：保底 10 分钟，按 64 KiB/s 地板速率随文件大小上浮（慢链路上大文件不会被误杀）。 */
+export declare function downloadTimeoutMs(size: number): number;
+export declare class TickdbHttp {
+    private readonly serverUrl;
+    private readonly token;
+    constructor(serverUrl: string, token: string);
+    private headers;
+    fetchManifest(ifNoneMatch?: string): Promise<ManifestResult>;
+    /** 单文件：流式写 .part -> size+sha256 校验 -> 原子 rename；失败重试 attempts 次（线性退避）。调用方负责串行。 */
+    downloadToFile(label: string, urlPath: string, dest: string, expect: {
+        size: number;
+        sha256: string;
+    }, opts?: {
+        attempts?: number;
+        backoffMs?: number;
+    }): Promise<void>;
+    /** 镜像下载：无认证绝对 URL，单次尝试（失败由调用方回落 VPS，VPS 的重试循环就是重试）。sha/size 校验与原子 rename 复用同一内核。 */
+    downloadMirrorToFile(url: string, dest: string, expect: {
+        size: number;
+        sha256: string;
+    }): Promise<void>;
+    private tryDownload;
+    private tryDownloadUrl;
+}

package/dist/http.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream, renameSync, rmSync } from 'node:fs';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { parseManifest } from './manifest.js';
+import { sleep } from './util.js';
+/** 下载总超时：保底 10 分钟，按 64 KiB/s 地板速率随文件大小上浮（慢链路上大文件不会被误杀）。 */
+export function downloadTimeoutMs(size) {
+    return Math.max(600_000, Math.ceil(size / 65_536) * 1000);
+}
+export class TickdbHttp {
+    serverUrl;
+    token;
+    constructor(serverUrl, token) {
+        this.serverUrl = serverUrl;
+        this.token = token;
+    }
+    headers() {
+        return { Authorization: `Bearer ${this.token}` };
+    }
+    async fetchManifest(ifNoneMatch) {
+        const headers = this.headers();
+        if (ifNoneMatch)
+            headers['If-None-Match'] = ifNoneMatch;
+        const res = await fetch(`${this.serverUrl}/api/v1/manifest?version=v1.3`, {
+            headers,
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (res.status === 304)
+            return { kind: 'not_modified' };
+        if (!res.ok)
+            throw new Error(`manifest HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+        const etag = res.headers.get('etag') ?? undefined;
+        return { kind: 'fresh', manifest: parseManifest(await res.json()), etag };
+    }
+    /** 单文件：流式写 .part -> size+sha256 校验 -> 原子 rename；失败重试 attempts 次（线性退避）。调用方负责串行。 */
+    async downloadToFile(label, urlPath, dest, expect, opts = {}) {
+        const attempts = opts.attempts ?? 3;
+        const backoffMs = opts.backoffMs ?? 250;
+        let lastErr = null;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                await this.tryDownload(urlPath, dest, expect);
+                return;
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt < attempts)
+                    await sleep(backoffMs * attempt);
+            }
+        }
+        throw new Error(`download failed after ${attempts} attempts (${label}): ${errText(lastErr)}`);
+    }
+    /** 镜像下载：无认证绝对 URL，单次尝试（失败由调用方回落 VPS，VPS 的重试循环就是重试）。sha/size 校验与原子 rename 复用同一内核。 */
+    async downloadMirrorToFile(url, dest, expect) {
+        await this.tryDownloadUrl(url, dest, expect, {});
+    }
+    async tryDownload(urlPath, dest, expect) {
+        await this.tryDownloadUrl(`${this.serverUrl}/api/v1/data/${urlPath}`, dest, expect, this.headers());
+    }
+    async tryDownloadUrl(url, dest, expect, headers) {
+        const res = await fetch(url, {
+            headers,
+            signal: AbortSignal.timeout(downloadTimeoutMs(expect.size)),
+        });
+        if (!res.ok || !res.body)
+            throw new Error(`data HTTP ${res.status} (${url})`);
+        const part = `${dest}.part`;
+        const hash = createHash('sha256');
+        let bytes = 0;
+        const counter = new Transform({
+            transform(chunk, _enc, cb) {
+                bytes += chunk.length;
+                hash.update(chunk);
+                cb(null, chunk);
+            },
+        });
+        try {
+            await pipeline(Readable.fromWeb(res.body), counter, createWriteStream(part));
+            if (bytes !== expect.size)
+                throw new Error(`size mismatch: got ${bytes}, want ${expect.size}`);
+            const sha = hash.digest('hex');
+            if (sha !== expect.sha256)
+                throw new Error(`sha256 mismatch: got ${sha}, want ${expect.sha256}`);
+            renameSync(part, dest);
+        }
+        catch (e) {
+            rmSync(part, { force: true });
+            throw e;
+        }
+    }
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import type { InitOptions, SyncReport, SyncStatus } from './types.js';
+export declare function init(opts?: InitOptions): Promise<void>;
+/** 显式同步：await 完成，错误上抛。 */
+export declare function sync(): Promise<SyncReport>;
+/** 后台立即一轮：错误只进 syncStatus().lastError，进程不 crash。 */
+export declare function syncStart(): void;
+export declare function syncDaemonStart(intervalSecs?: number): void;
+export declare function syncDaemonStop(): void;
+export declare function syncStatus(): SyncStatus;
+export declare function query(sql: string): Promise<Record<string, unknown>[]>;
+export declare function close(): Promise<void>;
+/** 测试专用：重置单例。勿在应用代码使用。 */
+export declare function _resetForTest(): void;
+/** 测试专用：手动触发 daemon tick。 */
+export declare function _daemonTickForTest(): Promise<void>;
+declare const tickdb: {
+    init: typeof init;
+    sync: typeof sync;
+    syncStart: typeof syncStart;
+    syncDaemonStart: typeof syncDaemonStart;
+    syncDaemonStop: typeof syncDaemonStop;
+    syncStatus: typeof syncStatus;
+    query: typeof query;
+    close: typeof close;
+    _daemonTickForTest: typeof _daemonTickForTest;
+};
+export default tickdb;

package/dist/index.js

@@ -0,0 +1,109 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DuckdbStore } from './store.js';
+import { TickdbHttp } from './http.js';
+import { syncOnce } from './sync.js';
+import { SyncStateHolder } from './status.js';
+import { createDaemon } from './daemon.js';
+import { loadMergedConfig, saveConfig } from './config.js';
+import { expandHome, nowSec } from './util.js';
+let lib = null;
+export async function init(opts = {}) {
+    if (lib)
+        return; // 幂等（热重载场景安全）
+    const dataDir = expandHome(opts.dataDir ?? '~/.tickdb');
+    const cacheDir = join(dataDir, '.cache', 'parquet');
+    mkdirSync(cacheDir, { recursive: true });
+    const cfg = loadMergedConfig(dataDir, opts);
+    saveConfig(cfg);
+    const store = await DuckdbStore.open(join(dataDir, 'tickdb.duckdb'));
+    store.setParquetRoot(cacheDir); // v2 查询前置刷新用；upsert 模式零影响
+    const state = new SyncStateHolder();
+    const http = new TickdbHttp(cfg.serverUrl, cfg.token);
+    lib = { dataDir, cacheDir, store, http, state, daemon: null, downloadConcurrency: cfg.downloadConcurrency };
+    if ((opts.autoSync ?? true) && cfg.token) {
+        lib.daemon = createDaemon({
+            onTick: () => backgroundSync(),
+            intervalSecs: opts.syncIntervalSecs ?? cfg.syncIntervalSecs,
+            state,
+        });
+        void backgroundSync(); // init 后立即来一轮（后台，错误不抛）
+    }
+}
+function requireLib() {
+    if (!lib)
+        throw new Error('tickdb not initialized: call init() first');
+    return lib;
+}
+/** 带状态跟踪的一轮同步。 */
+async function runRound() {
+    const l = requireLib();
+    if (l.state.get().running)
+        throw new Error('sync already running');
+    l.state.update({ running: true, startedAt: nowSec() });
+    try {
+        const report = await syncOnce(l.store, l.http, l.cacheDir, { downloadConcurrency: l.downloadConcurrency });
+        l.state.update({
+            running: false, finishedAt: nowSec(),
+            filesTotal: report.filesTotal, filesFetched: report.filesFetched,
+            filesUnchanged: report.filesUnchanged, rowsUpserted: report.rowsUpserted,
+            staleDeleted: report.staleDeleted, errorsCount: report.errors.length,
+            lastError: report.errors.length > 0 ? report.errors[0] : null,
+        });
+        return report;
+    }
+    catch (e) {
+        l.state.update({ running: false, finishedAt: nowSec(), lastError: e instanceof Error ? e.message : String(e) });
+        throw e;
+    }
+}
+/** 显式同步：await 完成，错误上抛。 */
+export async function sync() {
+    return runRound();
+}
+/** 后台立即一轮：错误只进 syncStatus().lastError，进程不 crash。 */
+export function syncStart() {
+    void backgroundSync();
+}
+async function backgroundSync() {
+    try {
+        await runRound();
+    }
+    catch (e) {
+        // close() 后 lib 可能为 null：只记不再抛，进程永不 crash
+        lib?.state.setError(e instanceof Error ? e.message : String(e));
+    }
+}
+export function syncDaemonStart(intervalSecs = 300) {
+    const l = requireLib();
+    l.daemon?.stop();
+    l.daemon = createDaemon({ onTick: () => backgroundSync(), intervalSecs, state: l.state });
+}
+export function syncDaemonStop() {
+    const l = requireLib();
+    l.daemon?.stop();
+    l.daemon = null;
+}
+export function syncStatus() {
+    return requireLib().state.get();
+}
+export async function query(sql) {
+    return requireLib().store.query(sql);
+}
+export async function close() {
+    if (!lib)
+        return;
+    lib.daemon?.stop();
+    await lib.store.close();
+    lib = null;
+}
+/** 测试专用：重置单例。勿在应用代码使用。 */
+export function _resetForTest() {
+    lib = null;
+}
+/** 测试专用：手动触发 daemon tick。 */
+export async function _daemonTickForTest() {
+    await requireLib().daemon?.tickNow();
+}
+const tickdb = { init, sync, syncStart, syncDaemonStart, syncDaemonStop, syncStatus, query, close, _daemonTickForTest };
+export default tickdb;

package/dist/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { Manifest } from './types.js';
+/** 把线上 JSON（snake_case）解析成 Manifest，字段不合法直接抛错。 */
+export declare function parseManifest(raw: unknown): Manifest;

package/dist/manifest.js

@@ -0,0 +1,40 @@
+/** 把线上 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') {
+        throw new Error(`unsupported manifest version: ${String(r.version)}`);
+    }
+    if (!Array.isArray(r.files))
+        throw new Error('manifest: files is not an array');
+    const files = r.files.map((f, i) => {
+        if (typeof f !== 'object' || f === null)
+            throw new Error(`manifest files[${i}]: not an object`);
+        const e = f;
+        for (const k of ['path', 'sha256', 'symbol', 'cycle', 'ts_min', 'ts_max']) {
+            if (typeof e[k] !== 'string')
+                throw new Error(`manifest files[${i}].${k}: expected string`);
+        }
+        for (const k of ['size', 'row_count']) {
+            if (typeof e[k] !== 'number')
+                throw new Error(`manifest files[${i}].${k}: expected number`);
+        }
+        return {
+            path: e.path, sha256: e.sha256, size: e.size,
+            row_count: e.row_count, symbol: e.symbol, cycle: e.cycle,
+            ts_min: e.ts_min, ts_max: e.ts_max,
+            year: typeof e.year === 'number' ? e.year : undefined,
+            symbols_count: typeof e.symbols_count === 'number' ? e.symbols_count : undefined,
+            frozen: e.frozen === true ? true : undefined,
+        };
+    });
+    return {
+        version: r.version,
+        schema: typeof r.schema === 'string' ? r.schema : 'symbol-partitioned',
+        generatedAt: typeof r.generated_at === 'string' ? r.generated_at : '',
+        files,
+        mirror_base_url: typeof r.mirror_base_url === 'string' ? r.mirror_base_url : undefined,
+        disjoint: r.disjoint === true ? true : undefined,
+    };
+}

package/dist/status.d.ts

@@ -0,0 +1,8 @@
+import type { SyncStatus } from './types.js';
+export declare class SyncStateHolder {
+    private s;
+    get(): SyncStatus;
+    update(patch: Partial<SyncStatus>): void;
+    /** 覆盖 lastError；传 null 清除。 */
+    setError(msg: string | null): void;
+}

package/dist/status.js

@@ -0,0 +1,16 @@
+function fresh() {
+    return {
+        running: false, startedAt: 0, finishedAt: 0,
+        filesTotal: 0, filesFetched: 0, filesUnchanged: 0,
+        rowsUpserted: 0, staleDeleted: 0, errorsCount: 0,
+        daemonIntervalSecs: 0, daemonRunning: false,
+        lastError: null,
+    };
+}
+export class SyncStateHolder {
+    s = fresh();
+    get() { return { ...this.s }; }
+    update(patch) { this.s = { ...this.s, ...patch }; }
+    /** 覆盖 lastError；传 null 清除。 */
+    setError(msg) { this.s = { ...this.s, lastError: msg }; }
+}

package/dist/store.d.ts

@@ -0,0 +1,54 @@
+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 class DuckdbStore {
+    private instance;
+    private conn;
+    /** v2 parquet-direct：kline view 挂载根（<dataDir>/.cache/parquet）。 */
+    private parquetRoot;
+    private constructor();
+    static open(path: string): Promise<DuckdbStore>;
+    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 maybeRefreshKlineSurface;
+    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>;
+    /** 把 kline 表面（surface）对齐到当前模式：direct → read_parquet VIEW
+     * （v1 遗留 TABLE 先 DROP）；upsert → TABLE（v2 遗留 VIEW 先 DROP 重建，
+     * 服务端回滚场景）。依赖视图 qfq/hfq 一并重建。幂等。 */
+    ensureKlineSurface(mode: string, cacheRoot: string): Promise<void>;
+    /** sync_meta 读取走原始连接（不经 query() 的 surface 刷新）。 */
+    getSyncMeta(key: string): Promise<string | null>;
+    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,269 @@
+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`;
+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)`,
+];
+export class DuckdbStore {
+    instance = null;
+    conn = null;
+    /** v2 parquet-direct：kline view 挂载根（<dataDir>/.cache/parquet）。 */
+    parquetRoot = null;
+    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'`);
+        for (const ddl of SCHEMA_STATEMENTS)
+            await s.conn.run(ddl);
+        return s;
+    }
+    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) {
+        await this.maybeRefreshKlineSurface();
+        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 maybeRefreshKlineSurface() {
+        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);
+        }
+    }
+    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) {
+        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) {
+        // 原始连接查询（绕过 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);
+        }
+        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;
+    }
+    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,9 @@
+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。 */
+export declare function syncOnce(store: DuckdbStore, http: TickdbHttp, cacheDir: string, opts?: {
+    downloadConcurrency?: number;
+}): Promise<SyncReport>;

package/dist/sync.js

@@ -0,0 +1,122 @@
+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';
+/** 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。 */
+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）。
+    const mode = manifest.disjoint === true ? 'parquet-direct' : 'duckdb-upsert';
+    const direct = mode === 'parquet-direct';
+    const prevMode = await store.getSyncMeta(STORE_MODE_KEY);
+    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);
+    await store.ensureKlineSurface(mode, cacheDir);
+    const diff = computeDiff(manifest.files, await store.listLocalManifest());
+    report.filesUnchanged = diff.unchanged;
+    // ② stale 先删（best-effort：单条失败记 error 不中断）。
+    // direct → 删本地文件（行随文件消失）；upsert → 优先按该文件自己的 ts 边界删
+    // （月文件消失只删它那个月；边界缺失回退整年删除）。
+    const localFull = direct ? new Map() : await store.listLocalManifestFull();
+    const staleOk = [];
+    for (const p of diff.stale) {
+        try {
+            if (direct) {
+                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。
+    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 });
+            }
+            if (direct) {
+                // v2：文件即行集——不 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;
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/** manifest FileEntry 字段与线上 JSON 完全一致（snake_case）。 */
+export interface FileEntry {
+    path: string;
+    sha256: string;
+    size: number;
+    row_count: number;
+    symbol: string;
+    cycle: string;
+    ts_min: string;
+    ts_max: string;
+    year?: number;
+    symbols_count?: number;
+    /** v1.2：文件已冻结上云（内容永不再变，可从镜像下载）。 */
+    frozen?: boolean;
+}
+export interface Manifest {
+    version: string;
+    schema: string;
+    generatedAt: string;
+    files: FileEntry[];
+    /** v1.2：对象存储公开基底 URL（未启用 mirror 时缺省）。 */
+    mirror_base_url?: string;
+    /** v1.3：服务端 compacted 文件 (symbol, ts) 互斥（重分区完成）。 */
+    disjoint?: boolean;
+}
+export interface InitOptions {
+    dataDir?: string;
+    token?: string;
+    serverUrl?: string;
+    autoSync?: boolean;
+    syncIntervalSecs?: number;
+    downloadConcurrency?: number;
+}
+export interface SyncReport {
+    notModified: boolean;
+    filesTotal: number;
+    filesFetched: number;
+    filesUnchanged: number;
+    rowsUpserted: number;
+    staleDeleted: number;
+    mirrorFetched: number;
+    mirrorFallbacks: number;
+    errors: string[];
+}
+export interface SyncStatus {
+    running: boolean;
+    startedAt: number;
+    finishedAt: number;
+    filesTotal: number;
+    filesFetched: number;
+    filesUnchanged: number;
+    rowsUpserted: number;
+    staleDeleted: number;
+    errorsCount: number;
+    daemonIntervalSecs: number;
+    daemonRunning: boolean;
+    lastError: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,10 @@
+/** 固定并发工作池：items 逐个领取，任何 fn 抛错由 fn 自身捕获（调用方负责 per-item try/catch）。 */
+export declare function runPool<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
+export declare function parseCycleYear(path: string): {
+    cycle: string;
+    year: number;
+};
+export declare function yearBounds(year: number): [string, string];
+export declare function expandHome(p: string): string;
+export declare const nowSec: () => number;
+export declare const sleep: (ms: number) => Promise<void>;

package/dist/util.js

@@ -0,0 +1,32 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 固定并发工作池：items 逐个领取，任何 fn 抛错由 fn 自身捕获（调用方负责 per-item try/catch）。 */
+export async function runPool(items, limit, fn) {
+    let i = 0;
+    const n = Math.max(1, Math.min(limit, items.length));
+    const workers = Array.from({ length: n }, async () => {
+        while (i < items.length) {
+            const idx = i++;
+            await fn(items[idx]);
+        }
+    });
+    await Promise.all(workers);
+}
+export function parseCycleYear(path) {
+    const m = /cycle=([^/]+)\/year=(\d{4})(?:-month=\d{2})?\.parquet$/.exec(path);
+    if (!m)
+        throw new Error(`cannot parse cycle/year from manifest path: ${path}`);
+    return { cycle: m[1], year: Number(m[2]) };
+}
+export function yearBounds(year) {
+    return [`${year}-01-01 00:00:00`, `${year}-12-31 23:59:59`];
+}
+export function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+export const nowSec = () => Math.floor(Date.now() / 1000);
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "tickdb-ts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "offline-first TypeScript client for tickdb (A-share market data): manifest sync + local DuckDB",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" } },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chuanlei-coding/growinpublic.git",
+    "directory": "tickdb/clients/tickdb-ts"
+  },
+  "license": "MIT",
+  "dependencies": { "@duckdb/node-api": "^2.0.0-r.1" },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}