tickdb-ts 0.0.0-stage → 0.3.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,98 @@
+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;
+        // 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),
+        });
+        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,42 @@
+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;
+    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))
+        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,
+        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 }; }
+}