@aiquants/duckdb-helper 1.5.0 → 1.6.2

package/docs/specs/2026.04.11 [AI] 02-service.md

@@ -1,6 +1,7 @@
 # DuckDBService 詳細仕様書
 
 > ソースファイル: `src/services/duckdb.ts`
+> 最終更新: 2026-07-05（v1.6.0 — 初期化ライフサイクル / トランザクション / 型推定の堅牢化）
 
 ## 1. 概要
 
@@ -11,47 +12,36 @@ Web Worker の初期化、コネクション管理、SQL クエリの実行、
 
 ### 2.1 デザインパターン
 
-- **シングルトンパターン**: `getInstance()` で唯一のインスタンスを取得する。アプリケーション全体で DuckDB Worker を1つだけ保持し、メモリとリソースを節約する。
-- **オブザーバーパターン**: `addStatusListener` / `removeStatusListener` でステータス変更を監視できる。React Hook (`useDuckDB`) がこれを利用している。
+- **シングルトンパターン**: `getInstance()` で唯一のインスタンスを取得する。アプリ全体で DuckDB Worker を1つだけ保持し、メモリとリソースを節約する。
+- **オブザーバーパターン**: `addStatusListener` / `removeStatusListener` でステータス変更を購読できる（push 型）。React Hook (`useDuckDB`) がこれを利用する。**状態遷移のたびに `notifyListeners()` が必ず呼ばれる**ため、ポーリングは不要。
+- **操作直列化キュー**: 単一の共有コネクション上で、`executeQuery` / `getTableInfo` / `listTables` と `createTableFromData` の DDL/DML が相互に割り込まないよう、内部の `operationQueue` で直列化する。
 
 ### 2.2 プライベートプロパティ
 
 | プロパティ名 | 型 | 初期値 | 説明 |
 |-------------|------|--------|------|
 | `instance` | `DuckDBService \| null` | `null` | シングルトンインスタンス（static） |
-| `operationFlags` | `Map<string, boolean>` | 空の Map | テーブル作成の重複実行防止フラグ |
-| `workerInstance` | `AsyncDuckDB \| null` | `null` | DuckDB Worker インスタンス |
+| `operationFlags` | `Map<string, Promise<void>>` | 空の Map | **進行中の**テーブル作成 Promise（重複呼び出しは同じ Promise を await する） |
+| `workerInstance` | `AsyncDuckDB \| null` | `null` | DuckDB Worker インスタンス（**instantiate 成功後にのみ設定**） |
 | `connectionInstance` | `AsyncDuckDBConnection \| null` | `null` | DB コネクション（再利用される） |
+| `connectionPromise` | `Promise<AsyncDuckDBConnection> \| null` | `null` | コネクション生成中の Promise（同時 connect の二重実行防止） |
 | `isInitializing` | `boolean` | `false` | 初期化中フラグ |
 | `initPromise` | `Promise<AsyncDuckDB> \| null` | `null` | 初期化 Promise（重複呼び出し防止用） |
 | `hasError` | `boolean` | `false` | エラー発生フラグ |
+| `pendingWorker` | `Worker \| null` | `null` | 初期化中の Worker（タイムアウト時などに terminate するため保持） |
+| `pendingWorkerUrl` | `string \| null` | `null` | 初期化中の Blob URL（同上、revoke するため保持） |
+| `operationQueue` | `Promise<unknown>` | `Promise.resolve()` | 操作直列化キュー |
 | `listeners` | `Set<() => void>` | 空の Set | ステータス変更リスナー群 |
 
 ## 3. メソッド仕様
 
 ### 3.1 `getInstance(): DuckDBService` (static)
 
-```typescript
-public static getInstance(): DuckDBService
-```
-
-| 項目 | 内容 |
-|------|------|
-| 戻り値 | `DuckDBService` のシングルトンインスタンス |
-| 副作用 | インスタンスが未作成の場合、新規作成する |
-| スレッド安全性 | JavaScript はシングルスレッドなので問題なし |
-
-**処理フロー**:
-1. `instance` が `null` → 新しい `DuckDBService` を作成して `instance` に格納
-2. `instance` を返す
+インスタンスが未作成なら生成し、シングルトンを返す。JavaScript はシングルスレッドのため排他制御は不要。
 
 ---
 
-### 3.2 `getStatus(): string`
-
-```typescript
-public getStatus(): "not-initialized" | "initializing" | "ready" | "error"
-```
+### 3.2 `getStatus(): "not-initialized" | "initializing" | "ready" | "error"`
 
 | ステータス | 条件 | 意味 |
 |-----------|------|------|
@@ -60,21 +50,17 @@ public getStatus(): "not-initialized" | "initializing" | "ready" | "error"
 | `"ready"` | `workerInstance !== null` | 利用可能 |
 | `"not-initialized"` | 上記いずれでもない | まだ初期化されていない |
 
-> **判定順序に注意**: `error` が最優先。`isInitializing` が `true` かつ `hasError` が `true` の場合は `"error"` になる。
+> **v1.6.0 での整合性改善**: 初期化に失敗すると `workerInstance` は必ず `null` にリセットされる。したがって `isReady()`（`workerInstance !== null`）と `getStatus()`（`"error"`）が矛盾しなくなった（旧実装では失敗後に `isReady() === true` かつ `getStatus() === "error"` という不整合が起きていた）。
 
 ---
 
 ### 3.3 `initialize(): Promise<AsyncDuckDB>`
 
-```typescript
-public async initialize(): Promise<duckdb.AsyncDuckDB>
-```
-
 | 項目 | 内容 |
 |------|------|
 | 戻り値 | 初期化された `AsyncDuckDB` インスタンス |
 | 例外 | 初期化失敗時（タイムアウト含む）に throw |
-| タイムアウト | 120秒（120,000ms） |
+| タイムアウト | 120秒（120,000ms、`INIT_TIMEOUT_MS`） |
 
 **処理フロー**:
 
@@ -84,304 +70,192 @@ flowchart TD
     B -- Yes --> C["そのまま返す（高速パス）"]
     B -- No --> D{既に初期化中?}
     D -- Yes --> E["initPromise を返す（重複防止）"]
-    D -- No --> F["isInitializing = true, hasError = false\nリスナーに通知（status: initializing）"]
-    F --> G["Promise.race(\n  internalInitializeWorker(),\n  タイムアウト 120秒\n)"]
-    G -- 成功 --> H["isInitializing = false\nリスナーに通知（status: ready）\nAsyncDuckDB を返す"]
-    G -- 失敗 --> I["isInitializing = false, hasError = true\nリスナーに通知（status: error）\ninitPromise = null（リトライ可能）\nエラーを throw"]
+    D -- No --> F["isInitializing = true, hasError = false\nリスナーに通知（initializing）\nアボートシグナル + タイムアウトタイマーを用意"]
+    F --> G["Promise.race(\n  internalInitializeWorker(signal),\n  120秒タイムアウト\n)"]
+    G -- 成功 --> H["clearTimeout\nisInitializing = false\nリスナー通知（ready）\nAsyncDuckDB を返す"]
+    G -- 失敗/タイムアウト --> I["clearTimeout\nsignal.aborted = true\nisInitializing = false, hasError = true\nworkerInstance / connectionInstance / connectionPromise / initPromise を null\nabortPendingWorker()（Worker terminate + Blob URL revoke）\nリスナー通知（error）\nエラーを throw"]
 ```
 
-**重複呼び出し防止の仕組み**:
-複数の箇所から同時に `initialize()` が呼ばれても、2回目以降は `initPromise` を返すため、Worker は1回だけ作成される。
+**v1.6.0 での重要な修正**:
 
----
+1. **失敗後の完全リセットと再試行可能性**: 失敗/タイムアウト時に `workerInstance` を含む全状態を初期化する。旧実装では失敗しても `workerInstance` が「生成済み・未 instantiate」のまま残り、次回 `initialize()` が高速パスで壊れたインスタンスを返し、`hasError` も解除されず、**セッション全体で永久に復旧不能**になっていた。現在は `initialize()` を再度呼べばクリーンに再初期化される。
+2. **タイマーの確実な解除**: タイムアウト用 `setTimeout` を成功/失敗どちらの経路でも `clearTimeout` する（旧実装は解除漏れで最大120秒間タイマーが残留）。
+3. **タイムアウト後の遅延結果を無視**: アボートシグナルにより、タイムアウト後に遅れて `instantiate()` が解決しても、壊れた/整合しないインスタンスを公開しない。
 
-### 3.4 `internalInitializeWorker(): Promise<AsyncDuckDB>` (private)
+**重複呼び出し防止**: 同時に `initialize()` が複数回呼ばれても、2回目以降は `initPromise` を返すため Worker は1回だけ作成される。
 
-```typescript
-private async internalInitializeWorker(): Promise<duckdb.AsyncDuckDB>
-```
+---
+
+### 3.4 `internalInitializeWorker(signal): Promise<AsyncDuckDB>` (private)
 
-Worker の実際の初期化処理。以下のステップを順番に実行する。
+Worker の実際の初期化処理。**`workerInstance` は全ステップ成功後にのみ `this` に公開する**（途中で失敗/アボートした場合はローカルの Worker / Blob URL を破棄し、壊れたインスタンスを絶対に残さない）。
 
 | ステップ | 処理内容 | 補足 |
 |---------|---------|------|
-| 1 | `duckdb.getJsDelivrBundles()` で CDN バンドル一覧を取得 | jsDelivr CDN を使用 |
-| 2 | `duckdb.selectBundle()` でブラウザ互換のバンドルを選択 | ブラウザの機能に応じて最適なものを選択 |
-| 3 | Blob URL を作成して Web Worker を生成 | `importScripts()` で Worker スクリプトを読み込む |
-| 4 | `new duckdb.AsyncDuckDB(logger, worker)` でインスタンス作成 | ConsoleLogger を使用 |
-| 5 | `workerInstance.instantiate()` で WASM モジュールを読み込み | メインモジュールと pthread Worker |
-| 6 | `splink_udfs` 拡張をインストール・ロード | **一時コネクション**を開き、`INSTALL` → `LOAD` を実行後、`finally` で close する。メインの `connectionInstance` とは別。失敗しても初期化は続行 |
-| 7 | Blob URL を `revokeObjectURL` で解放 | メモリリーク防止 |
-
-**splink_udfs について**:
-- 名寄せ（レコードリンケージ）用の UDF（ユーザー定義関数）
-- `INSTALL splink_udfs FROM community;` → `LOAD splink_udfs;`
-- インストール/ロードに失敗しても `warn` ログを出すだけで、初期化全体は失敗しない
+| 1 | `duckdb.getJsDelivrBundles()` | jsDelivr CDN のバンドル一覧 |
+| 2 | `duckdb.selectBundle()` → **アボート確認** | ブラウザ互換バンドルを選択 |
+| 3 | Blob URL を作成し Web Worker を生成、`pendingWorker`/`pendingWorkerUrl` に退避 | 失敗時の破棄用 |
+| 4 | `new duckdb.AsyncDuckDB(logger, worker)`（ローカル変数 `db`） | まだ `this` に代入しない |
+| 5 | `db.instantiate()` → **アボート確認** | WASM モジュール読み込み |
+| 6 | `splink_udfs` を一時コネクションで INSTALL/LOAD（失敗しても続行、`finally` で close）→ **アボート確認** | 名寄せ用 UDF |
+| 7 | **成功**: `this.workerInstance = db`、`pendingWorker`/`pendingWorkerUrl` をクリア、Blob URL を revoke | ここで初めて公開 |
+| 失敗時 | ローカル `worker.terminate()` と `URL.revokeObjectURL()` を**必ず**実行（各々 try/catch で握りつぶす）、エラーを rethrow | Worker/Blob URL リーク防止 |
 
 ---
 
 ### 3.5 `getConnection(): Promise<AsyncDuckDBConnection>`
 
-```typescript
-public async getConnection(): Promise<duckdb.AsyncDuckDBConnection>
-```
-
 | 項目 | 内容 |
 |------|------|
-| 戻り値 | DuckDB コネクション |
+| 戻り値 | DuckDB コネクション（1つを保持・再利用） |
 | 動作 | コネクションが無ければ `initialize()` → `connect()` で作成。あれば再利用 |
 
-**注意**: コネクションは1つだけ保持・再利用される。並列クエリの実行には対応していない。
+**v1.6.0 での修正**: 生成中の `connectionPromise` を共有することで、**同時呼び出し時の二重 `connect()` を防止**する。`connect()` が失敗した場合は `connectionPromise` を `null` に戻し、次回リトライ可能にする。
 
 ---
 
 ### 3.6 `executeQuery(sql: string): Promise<unknown>`
 
-```typescript
-public async executeQuery(sql: string): Promise<unknown>
-```
-
 | 項目 | 内容 |
 |------|------|
-| 引数 | `sql` - 実行する SQL 文字列 |
 | 戻り値 | クエリ結果（Apache Arrow Table）。型は `unknown` |
-| タイムアウト | 60秒（60,000ms） |
-| 例外 | クエリ失敗時・タイムアウト時に throw |
+| タイムアウト | 60秒（60,000ms、`QUERY_TIMEOUT_MS`） |
+| 直列化 | `operationQueue` で他操作と直列化（テーブル構築中の割り込み read を防止） |
 
-**処理フロー**:
-1. `getConnection()` でコネクションを取得
-2. `connection.query(sql)` を実行
-3. 60秒のタイムアウトと `Promise.race` で競合
-4. 結果を返す（またはエラーを throw）
+**v1.6.0 での修正**:
+- タイムアウト用 `setTimeout` を成功/失敗どちらの経路でも `clearTimeout` する（旧実装はクエリ1回ごとに最大60秒残留するタイマーを生成していた）。
+- **タイムアウト時にコネクションを破棄する**: タイムアウトしたクエリはワーカー側で走り続けるため、使用中コネクションを `connectionInstance`/`connectionPromise` から外して close（best-effort）する。これにより後続クエリが詰まったコネクションで待たされず、次回は新しいコネクションで実行される（内部の `runQueryWithTimeout` が担当）。コネクション取得（`getConnection`）自体がハングした場合もタイムアウトが働き、破棄対象が無ければ何もしない。
 
 ---
 
 ### 3.7 `executeQueries(queries: string[]): Promise<unknown[]>`
 
-```typescript
-public async executeQueries(queries: string[]): Promise<unknown[]>
-```
+配列の順番通りに1つずつ**逐次実行**し、結果を配列で返す。CREATE → INSERT → SELECT のような依存クエリ列に適する。
 
-| 項目 | 内容 |
-|------|------|
-| 引数 | `queries` - SQL 文字列の配列 |
-| 戻り値 | 各クエリの結果を順番に格納した配列 |
-| 実行方法 | **逐次実行**（並列ではない） |
-
-> **重要**: クエリは配列の順番通りに1つずつ実行される。CREATE TABLE → INSERT → SELECT のように依存関係があるクエリ列に適している。
+**v1.6.0 での修正**: バッチ全体を**1つのキュー単位**（単一 `enqueue`）として実行するため、他操作がクエリ列の途中に割り込まない（`executeQuery` を個別に enqueue する旧実装では、Q1 と Q2 の間に別操作が挟まり得た）。各クエリには従来どおり 60 秒タイムアウトが適用される。なお DB レベルのトランザクション（原子性）ではないため、原子性が必要な場合は `createTableFromData` か明示的な BEGIN/COMMIT を用いる。
 
 ---
 
 ### 3.8 `createTableFromData<T>(tableName, data, options): Promise<void>`
 
-```typescript
-public async createTableFromData<T extends Record<string, unknown>>(
-    tableName: string,
-    data: T[],
-    options: {
-        dropIfExists?: boolean
-        primaryKey?: string
-        verbose?: boolean
-    } = {},
-): Promise<void>
-```
-
 JavaScript の配列データから DuckDB テーブルを作成する高レベルメソッド。
 
 #### 引数
 
 | 引数名 | 型 | 必須 | 説明 |
 |--------|------|------|------|
-| `tableName` | `string` | Yes | 作成するテーブル名 |
-| `data` | `T[]` | Yes | テーブルに投入するデータ配列（1行以上必須） |
-| `options.dropIfExists` | `boolean` | No | `true` の場合、既存テーブルを削除してから作成 |
-| `options.primaryKey` | `string` | No | 主キーとして設定するカラム名 |
-| `options.verbose` | `boolean` | No | ログ出力の有無（デフォルト: `true`） |
+| `tableName` | `string` | Yes | 作成するテーブル名（識別子として安全にクォートされる） |
+| `data` | `T[]` | Yes | 投入データ配列（1行以上必須） |
+| `options.dropIfExists` | `boolean` | No | `true` で既存テーブルを削除してから作成 |
+| `options.primaryKey` | `string` | No | 主キーに設定するカラム名 |
+| `options.verbose` | `boolean` | No | **ログ出力の有無のみ**を制御（デフォルト `true`）。DB への追加クエリは発行しない |
 
 #### 処理フロー
 
 ```mermaid
 flowchart TD
-    A["createTableFromData(tableName, data, options)"] --> B{data が空配列?}
-    B -- Yes --> C["Error を throw"]
-    B -- No --> D{operationFlags に\n同名テーブルが進行中?}
-    D -- Yes --> E["スキップして return"]
-    D -- No --> F["operationFlags にフラグをセット"]
-    F --> G{dropIfExists === true?}
-    G -- Yes --> H["DROP TABLE IF EXISTS を実行"]
-    G -- No --> I1["SHOW TABLES（作成前の確認ログ）"]
-    H --> I1
-    I1 --> I2["型推定（inferColumnTypes）\n先頭100行→関数内部で先頭10行を使用"]
-    I2 --> J["CREATE TABLE 文を生成・実行"]
-    J --> J1["SHOW TABLES + information_schema\n（作成後の検証ログ）"]
-    J1 --> K["データを1000行ずつバッチ INSERT\nformatValueForSQL で値を変換"]
-    K --> L["operationFlags からフラグを削除（finally）"]
+    A["createTableFromData(...)"] --> B{data が空 (null / 長さ0)?}
+    B -- Yes --> C["Error: 'Data array is empty' を throw"]
+    B -- No --> D{operationFlags に同名の進行中 Promise?}
+    D -- Yes --> E["**その Promise を await して返す**\n（早期 void 解決しない）"]
+    D -- No --> F["buildTable を operationQueue に積み、\noperationFlags に Promise を登録"]
+    F --> G["await 完了 → finally で operationFlags を削除"]
 ```
 
-> **注意**: `SHOW TABLES` と `information_schema` による検証ステップは `verbose` が `true`（デフォルト）の場合にログ出力される。検証自体が失敗しても処理は続行される（`try/catch` で `warn` ログのみ）。
+**v1.6.0 での重複排除の修正**: 同名テーブルへの同時呼び出しは、進行中の**同一 Promise を await** する。旧実装は2回目の呼び出しが「テーブル未完成のまま即 `void` 解決」し、呼び出し側が存在しない/部分的なテーブルを read してしまう危険があった。
+
+#### `buildTable`（private）— トランザクションによる原子的構築
 
-#### 型推定ルール（`inferColumnTypes`）
+```mermaid
+flowchart TD
+    A["列名 = 全行の和集合（collectColumnNames）"] --> B["型推定（先頭 100 行、inferColumnTypes）"]
+    B --> C["BEGIN TRANSACTION"]
+    C --> D{dropIfExists?}
+    D -- Yes --> E["DROP TABLE IF EXISTS"]
+    D -- No --> F["CREATE TABLE"]
+    E --> F
+    F --> G["1000 行ずつ INSERT（formatValueForSQL）"]
+    G --> H["COMMIT"]
+    H -.->|途中で失敗| I["ROLLBACK（失敗しても warn のみ）→ 元エラーを rethrow"]
+```
 
-`createTableFromData` は先頭100行を `inferColumnTypes` に渡すが、`inferColumnTypes` 内部でさらに `data.slice(0, Math.min(data.length, 10))` で先頭10行に絞り込む。したがって**実効的なサンプルサイズは最大10行**。
+- **原子性**: DROP/CREATE/INSERT を1トランザクションにまとめ、途中失敗時は `ROLLBACK` する。**半端に作成されたテーブルを残さない**（旧実装は失敗時にデータ無し/部分ロードのテーブルが残った）。
+- **列名は全行の和集合**（`collectColumnNames`）から決定する。旧実装は先頭行のキーのみを使い、後続行だけが持つ列を**無警告で欠落**させていた。CREATE と INSERT で同じ列集合を使う。
+- **`null`/`undefined` 行**はすべて `NULL` として挿入する（不揃いデータへの耐性）。
+
+#### 型推定ルール（`inferColumnTypes`、サンプル = 先頭 100 行）
 
 | JavaScript の値 | 推定される DuckDB 型 | 条件 |
 |----------------|---------------------|------|
-| `number`（整数） | `INTEGER` | `Number.isInteger()` が true かつ 32bit 範囲内 |
-| `number`（整数、大きい） | `BIGINT` | `Number.isInteger()` が true かつ 32bit 範囲外 |
-| `number`（小数） | `DOUBLE` | 整数でない number |
-| `boolean` | `BOOLEAN` | typeof === "boolean" |
+| `number`（有限・整数） | `BIGINT` | `Number.isFinite` かつ `Number.isInteger`（桁あふれ回避のため一律 BIGINT） |
+| `number`（有限・小数） | `DOUBLE` | 有限だが整数でない |
+| `bigint` | `BIGINT` | `typeof === "bigint"` |
+| `number`（非有限） | （数値扱いしない） | `NaN` / `Infinity` は文字列カウント（挿入時は NULL） |
+| `boolean` | `BOOLEAN` | |
 | `Date` オブジェクト | `TIMESTAMP` | `instanceof Date` |
-| `string`（日付形式） | `TIMESTAMP` | `new Date(value)` が有効かつ "-" を含む |
-| `string`（その他） | `VARCHAR` | 上記以外 |
-| `null` / `undefined` のみ | `VARCHAR` | 値がすべて null/undefined の場合のフォールバック |
+| `string`（**厳密**日付） | `TIMESTAMP` | `TIMESTAMP_PATTERN`（`YYYY-MM-DD[ T HH:MM...]`）に一致し、かつ `new Date` が有効 |
+| その他 / 混在 | `VARCHAR` | 上記以外、値がすべて null、型が混在する場合のフォールバック |
+
+> **v1.6.0 での修正**:
+> - 整数は `INTEGER` ではなく **`BIGINT`** を採用し、int32 を超える値でのオーバーフローを解消。
+> - TIMESTAMP 推定を厳密化。旧実装の「`new Date()` が有効 かつ `"-"` を含む」は緩すぎ、`ABC-123` のような文字列まで日付扱いして後続行のキャスト失敗を招いた。現在は厳密な日付/日時パターンに一致する場合のみ TIMESTAMP。
+> - サンプルは実際に先頭 100 行を使用（旧実装は「100 行」と称しつつ内部で 10 行に絞る二重スライスのバグがあった）。
 
 #### SQL 値フォーマットルール（`formatValueForSQL`）
 
 | JavaScript の値 | SQL 出力 | 補足 |
 |----------------|---------|------|
 | `null` / `undefined` | `NULL` | |
-| `string` | `'エスケープ済み文字列'` | シングルクォートは `''` にエスケープ |
-| `Date` | `'2024-01-01T00:00:00.000Z'` | ISO 8601 形式 |
+| `string` | `'エスケープ済み'` | シングルクォートを `''` にエスケープ |
+| `Date` | `'2024-01-01T00:00:00.000Z'` | ISO 8601 |
 | `boolean` | `TRUE` / `FALSE` | |
-| `number` | `123` / `45.67` | そのまま文字列化 |
-| その他 | `String(value)` | |
+| `bigint` | `123` | `toString()` |
+| `number`（有限） | `123` / `45.67` | |
+| `number`（非有限: NaN/Infinity） | `NULL` | 有効な SQL 数値リテラルでないため NULL 化 |
+| オブジェクト / 配列 | `'{"x":1}'` / `'["a","b"]'` | `JSON.stringify` してクォート・エスケープ。stringify 不能（循環参照・`undefined`）は `NULL` |
 
----
+> **v1.6.0 での修正**: 旧実装はオブジェクト/配列を `String(value)` で `[object Object]` や `a,b`（列数ずれ）に、非有限数を裸の `NaN`/`Infinity`（無効 SQL）に変換し、INSERT バッチ全体を失敗させ得た。
 
-### 3.9 `getTableInfo(tableName: string): Promise<unknown>`
+#### 識別子のクォート（`quoteIdentifier`）
 
-```typescript
-public async getTableInfo(tableName: string): Promise<unknown>
-```
-
-| 項目 | 内容 |
-|------|------|
-| 実行 SQL | `DESCRIBE {tableName}` |
-| 戻り値 | テーブルのカラム情報（名前、型、NULL 可否など） |
+`tableName` / カラム名 / `primaryKey` はすべて `"..."` でクォートし、内部のダブルクォートを `""` にエスケープする。空文字列や文字列以外の識別子は `Error("Invalid SQL identifier")` を投げる。旧実装は `tableName` を無クォートで DDL/DML に、`information_schema` の `WHERE table_name = '...'` に**文字列リテラルとして生挿入**しており、スペース/予約語/クォートを含む名前で破綻し、リテラル注入点も存在した（診断クエリ自体も v1.6.0 で撤去）。
 
 ---
 
-### 3.10 `listTables(): Promise<unknown>`
+### 3.9 `getTableInfo(tableName: string): Promise<unknown>`
 
-```typescript
-public async listTables(): Promise<unknown>
-```
+`DESCRIBE "<tableName>"`（クォート済み）を `operationQueue` 経由で実行し、カラム情報を返す。
 
-| 項目 | 内容 |
-|------|------|
-| 実行 SQL | `SHOW TABLES` |
-| 戻り値 | 現在のデータベースに存在するテーブル一覧 |
+### 3.10 `listTables(): Promise<unknown>`
 
----
+`SHOW TABLES` を `operationQueue` 経由で実行し、テーブル一覧を返す。
 
 ### 3.11 `isReady(): boolean`
 
-```typescript
-public isReady(): boolean
-```
-
-| 項目 | 内容 |
-|------|------|
-| 戻り値 | `workerInstance !== null` の場合 `true` |
-| 用途 | 同期的に初期化完了を確認したい場合 |
-
----
+`workerInstance !== null` を返す。§3.2 のとおり失敗時は `null` にリセットされるため `getStatus()` と整合する。
 
 ### 3.12 `cleanup(): Promise<void>`
 
-```typescript
-public async cleanup(): Promise<void>
-```
-
-リソースの完全な解放を行う。
-
 | ステップ | 処理 |
 |---------|------|
 | 1 | コネクションを close |
 | 2 | Worker を terminate |
-| 3 | すべての内部状態をリセット |
-| 4 | リスナーと operationFlags をクリア |
-
-> **注意**: cleanup 後に再度 `initialize()` を呼べば再初期化できる。
+| 3 | `pendingWorker`/`pendingWorkerUrl` を破棄（`abortPendingWorker`） |
+| 4 | 全内部状態（`isInitializing`/`hasError`/`initPromise`/`connectionPromise`/`operationQueue`/`operationFlags`）をリセット |
+| 5 | リスナーに通知してから `listeners` をクリア |
 
----
+teardown 中に例外が出ても `Logger.error` でログするのみで throw しない。cleanup 後に `initialize()` を再度呼べば再初期化できる。
 
 ### 3.13 `resetInstance(): void` (static)
 
-```typescript
-public static resetInstance(): void
-```
-
-| 項目 | 内容 |
-|------|------|
-| 用途 | テスト時にシングルトンをリセットする |
-| 動作 | `cleanup()` を呼び出し（**await しない**）、直後に `instance = null` にする |
-
-> **注意**: `cleanup()` は `async` メソッドだが、`resetInstance()` は同期メソッド（`void`）であり `cleanup()` を await しない。コネクションの close や Worker の terminate が完了する前にインスタンスが `null` になる。テストで確実にリソースを解放したい場合は、`resetInstance()` の前に `await DuckDBService.getInstance().cleanup()` を明示的に呼ぶこと。
-
----
-
-### 3.14 ステータスリスナー
-
-```typescript
-public addStatusListener(listener: () => void): void
-public removeStatusListener(listener: () => void): void
-```
-
-| メソッド | 説明 |
-|---------|------|
-| `addStatusListener` | ステータス変更時に呼ばれるコールバックを登録 |
-| `removeStatusListener` | 登録済みコールバックを削除 |
-
-リスナーが呼ばれるタイミング:
-- `initialize()` 開始時（→ `"initializing"`）
-- `initialize()` 成功時（→ `"ready"`）
-- `initialize()` 失敗時（→ `"error"`）
-
-## 4. エクスポート
-
-`services/duckdb.ts` のエクスポート:
-
-```typescript
-// 名前付きエクスポート（クラス本体）
-export { DuckDBService }
-
-// デフォルトエクスポート（シングルトンインスタンス）— services/duckdb.ts 内でのみ default
-export default DuckDBService.getInstance()
-```
-
-`index.ts` での re-export:
-
-```typescript
-export { DuckDBService, default as duckDBService } from "./services/duckdb"
-```
-
-> **注意**: `services/duckdb.ts` はデフォルトエクスポートを持つが、`index.ts` はそれを `duckDBService` という**名前付きエクスポート**として re-export する。パッケージ自体にデフォルトエクスポートは存在しない。
-
-| エクスポート | インポート方法 | 用途 |
-|------------|--------------|------|
-| `DuckDBService`（クラス） | `import { DuckDBService } from '...'` | `getInstance()` や `resetInstance()` を呼びたい場合 |
-| `duckDBService`（インスタンス） | `import { duckDBService } from '...'` | 通常利用。シングルトンインスタンスを直接使う |
-
-## 5. ステータス遷移図
-
-```mermaid
-stateDiagram-v2
-    state "not-initialized" as not_init
-    [*] --> not_init
-    not_init --> initializing : initialize()
-    initializing --> ready : 成功
-    initializing --> error : 失敗
-    ready --> not_init : cleanup()
-    error --> initializing : initialize()（リトライ）
-    error --> not_init : cleanup()
-```
+`cleanup()` を呼び出し（**await しない**）、直後に `instance = null` にする。主にテスト用。`instance` が既に `null` の場合は何もしない。
 
-## 6. 新人向けポイント
+## 4. 内部定数
 
-1. **`import { duckDBService } from '@aiquants/duckdb-helper'` が最も簡単な使い方**。シングルトンインスタンスがそのまま使える。
-2. **`initialize()` は何回呼んでも安全**。既に初期化済みならすぐ返る。初期化中なら同じ Promise を返す。
-3. **コネクションは自動で再利用される**。`getConnection()` を何度呼んでも、内部では1つのコネクションが使い回される。
-4. **`createTableFromData` が便利**。JavaScript の配列をそのまま DuckDB テーブルにできる。型推定も自動。
-5. **テスト時は `DuckDBService.resetInstance()` でリセット**できる。テスト間の状態汚染を防げる。
-6. **splink_udfs の失敗は無視される**。名寄せ機能が不要な環境でもエラーにならない。
+| 定数 | 値 | 用途 |
+|------|------|------|
+| `INIT_TIMEOUT_MS` | `120000` | 初期化タイムアウト |
+| `QUERY_TIMEOUT_MS` | `60000` | クエリタイムアウト |
+| `BATCH_SIZE` | `1000` | バッチ INSERT の行数 |
+| `TYPE_INFERENCE_SAMPLE_SIZE` | `100` | 型推定のサンプル行数 |
+| `TIMESTAMP_PATTERN` | 正規表現 | 文字列を TIMESTAMP とみなす厳密パターン |

package/docs/specs/2026.04.11 [AI] 03-hooks.md

@@ -63,36 +63,21 @@ export interface UseDuckDBResult {
 
 ### 2.4 内部動作の詳細
 
-#### ステータス同期の仕組み
+#### ステータス同期の仕組み（v1.6.0 で push 型に一本化）
 
-`useDuckDB` は2つの方法で `DuckDBService` のステータスを React の状態に同期する。
+`useDuckDB` は**ステータスリスナー（push 型）のみ**で `DuckDBService` のステータスを React の状態に同期する。
 
-**方法1: ステータスリスナー**
 ```
 DuckDBService
-  ├── addStatusListener(updateStatus)  ← マウント時に登録
+  ├── addStatusListener(updateStatus)  ← マウント時に登録し、updateStatus() を1回即時実行して初期値を取得
   └── removeStatusListener(updateStatus) ← アンマウント時に解除
 ```
 
-**方法2: ポーリング（フォールバック）**
-```
-setInterval(pollStatus, 1000)  ← 1秒ごとにステータスをチェック
-```
+`DuckDBService` は状態遷移（initializing / ready / error）と `cleanup()` のたびに必ず `notifyListeners()` を呼ぶため、リスナーだけで全遷移を漏れなく受け取れる。
 
-> **なぜ2つの方法があるのか**: リスナーだけではステータス変更が漏れる可能性がある（例: 別のコンポーネントから直接サービスを操作した場合）。ポーリングは保険として機能する。
+> **v1.6.0 での変更（1秒ポーリングの撤去）**: 旧実装は上記リスナーに加えて `setInterval(pollStatus, 1000)` を各フックインスタンスに常設していた。`useDuckDBQuery` は内部で `useDuckDB()` を呼ぶため、`root.tsx` のアプリ全体マウントと合わせて **消費者ごとに永久 1 秒タイマー** が積み上がり、しかも push リスナーと完全に重複していた。リスナーで全遷移が届く以上ポーリングは不要と判断し、effect ごと削除した。
 
-**ポーリングのガード条件**（2つの条件を AND で結合）:
-```typescript
-if (currentStatus !== status && currentStatus !== "initializing") {
-    setStatus(currentStatus)
-}
-```
-1. `currentStatus !== status` — サービスの現在のステータスが React state と異なる場合のみ更新
-2. `currentStatus !== "initializing"` — サービスが `"initializing"` を返す場合は更新しない
-
-両方を満たした場合のみ React state が更新される。`"initializing"` への遷移はリスナー経由でのみ通知される。
-
-**SSR 環境での動作**: `typeof window === "undefined"` の場合（SSR / Node.js 環境）、`setInterval` は設定されず、`pollStatus` を1回だけ同期的に実行してから effect を終了する。ブラウザ環境でも `setInterval` 設定直後に `pollStatus()` が1回即時実行される。
+**SSR 環境での動作**: リスナー登録は `useEffect` 内で行われ、SSR（サーバー）では effect が実行されないため副作用は発生しない。初期レンダリングの `status` は `"not-initialized"` となる。
 
 #### 自動初期化フロー
 
@@ -224,6 +209,10 @@ flowchart TD
 3. `isReady` が `false` → `true` に変わった（初期化完了）
 4. `refetch()` を手動で呼んだ
 
+> **`data` は生の Arrow Table**: `data` は `executeQuery()` の戻り値そのもの（Apache Arrow Table）であり、**行配列ではない**。`.length` や `.map` は持たないため、行として扱うときは必ず `duckdbTableToArray<Row>(data)` で変換すること（型パラメータ `T` には行の型ではなく Arrow Table 相当の型を想定する）。単一クエリの型付き行配列がほしい場合は `useDuckDB().executeQuery()` + `duckdbTableToArray()` の組み合わせが明快。
+
+> **`dependencies` の扱い（v1.6.0）**: 内部では可変長の `dependencies` を effect の依存配列へ直接スプレッドせず、`Object.is` 比較で変化を検知する**固定サイズのバージョン番号**（`useDependencyVersion`）に変換して `[refetch, version]` を依存にする。これにより、レンダー間で `dependencies` の**長さが変わっても** React の「依存配列サイズ変更」エラーを起こさず、要素の変化（React と同じ参照比較）で再フェッチされる。
+
 ### 3.6 使用パターン
 
 #### パターン1: 基本的なデータ取得

package/docs/specs/2026.04.11 [AI] 05-logger.md

@@ -139,9 +139,7 @@ private formatMessage(message: unknown): unknown[] {
 
 ### 開発中（すべてのログを表示）
 
-> **重要**: `Logger` と `LogLevel` は `index.ts` から公開エクスポートされておらず、`package.json` の `exports` にもサブパスが定義されていないため、**現状では利用側から直接インポートできない**。ログレベルを変更するには、パッケージ側で `index.ts` にエクスポートを追加する必要がある（追加方法は[開発ガイド](../guides/2026.04.11%20%5BAI%5D%20development.md)の「Q: Logger を公開 API にしたい」を参照）。
-
-パッケージ側でエクスポートが追加された場合の使用例:
+> **v1.6.0 で公開**: `Logger` / `LogLevel` / `ILogger` は `index.ts` から公開エクスポートされるようになった。利用側から直接インポートしてログレベルを制御できる（旧バージョンではエクスポートされておらず、初期化ログを有効化する手段が無かった）。
 
 ```typescript
 import { Logger, LogLevel } from '@aiquants/duckdb-helper'
@@ -176,8 +174,8 @@ Logger.setImplementation(customLogger)
 
 ## 7. 注意事項
 
-1. **Logger / LogLevel は `index.ts` から公開エクスポートされていない**。ライブラリ内部用の位置づけ。`package.json` の `exports` にもサブパスが未定義のため、`@aiquants/duckdb-helper/utils/simple-logger` のような直接パスインポートも動作しない。利用側からログレベルを変更するにはパッケージのエクスポートを拡張する必要がある。
-2. **デフォルトレベルは `WARN`**。つまり `DuckDBService` 内の `Logger.info(...)` による初期化ログは通常表示されない。デバッグ時にログを見たい場合は `Logger.setLevel(LogLevel.DEBUG)` を設定する。
+1. **Logger / LogLevel / ILogger は `index.ts` から公開エクスポートされている（v1.6.0〜）**。`import { Logger, LogLevel } from '@aiquants/duckdb-helper'` で利用でき、`Logger.setLevel()` などでログレベルや実装を制御できる。
+2. **デフォルトレベルは `WARN`**。つまり `DuckDBService` 内の `Logger.info(...)` による初期化ログは通常表示されない。ただし初期化の**失敗**（`Logger.error`）は WARN でも表示される。詳細なステップを見たい場合は `Logger.setLevel(LogLevel.DEBUG)` を設定する。
 3. **リスナーでの例外はキャッチされる**。`DuckDBService.notifyListeners()` 内でリスナーが例外を投げた場合、`Logger.error` でログに出力されるが、他のリスナーへの通知は続行される。
 
 ## 8. 新人向けポイント

package/docs/specs/2026.04.11 [AI] 06-build-config.md

@@ -121,7 +121,6 @@ export default defineConfig({
 | `build:watch` | `tsup --watch` | ファイル変更時に自動リビルド |
 | `dev` | `tsup --watch` | 開発用（build:watch と同一） |
 | `watch` | `tsup --watch` | ウォッチモード |
-| `type-check` | `tsc --noEmit` | 型チェックのみ実行 |
 | `clean` | `rimraf dist` | ビルド成果物を削除 |
 | `prepare` | `pnpm run build` | パッケージインストール後に自動ビルド |
 | `prepublishOnly` | clean → typecheck → test(`--if-present`) → build | 公開前の品質チェック |
@@ -131,9 +130,10 @@ export default defineConfig({
 | `format:fix` | `biome format --write src/` | Biome によるフォーマット自動修正 |
 | `check` | `biome check src/` | Lint + フォーマットの同時チェック |
 | `check:fix` | `biome check --write src/` | Lint + フォーマットの同時自動修正 |
-| `typecheck` | `npm run type-check` | `type-check` のエイリアス |
+| `typecheck` | `tsc --noEmit` | 本体（`src`）の型チェック |
+| `typecheck:test` | `tsc --noEmit -p tsconfig.test.json` | テストを含む型チェック（v1.6.0〜） |
 | `test` | `vitest run` | テスト実行 |
-| `test:coverage` | `vitest run --coverage` | カバレッジ付きテスト |
+| `test:coverage` | `vitest run --coverage` | カバレッジ付きテスト（閾値 100%） |
 | `license-check` | `pnpm dlx license-checker ...` | 許可ライセンスのチェック |
 | `license-check:json` | `pnpm dlx license-checker ... --json` | ライセンスチェック（JSON 出力） |
 | `publish:patch` | version patch → publish | パッチバージョン公開 |
@@ -148,6 +148,24 @@ export default defineConfig({
 
 npm に公開されるファイル。`src/` はパッケージに含まれない。
 
+## 4.5 テスト設定（v1.6.0〜）
+
+| ファイル | 役割 |
+|---------|------|
+| `vitest.config.ts` | Vitest 設定。`environment: "jsdom"`、`globals: true`、カバレッジは `v8` プロバイダで `src/**`（`src/types` 除外）を対象に閾値 100%（lines / functions / branches / statements） |
+| `tsconfig.test.json` | `tsconfig.json` を継承し `tests/**` を含めた型チェック用設定 |
+
+### テスト関連 devDependencies
+
+| パッケージ | 用途 |
+|-----------|------|
+| `vitest` | テストランナー |
+| `@vitest/coverage-v8` | V8 カバレッジプロバイダ |
+| `jsdom` | ブラウザ相当の DOM 環境（`window` / `URL` / React フックのレンダリング） |
+| `@testing-library/react`, `@testing-library/dom` | React フックのテスト（`renderHook` 等） |
+
+> テストでは `@duckdb/duckdb-wasm` を `vi.mock` で制御可能なフェイクに差し替え、`Worker` / `URL.createObjectURL` / `Blob` をスタブすることで、実際の WASM ダウンロードや Worker 生成なしに全経路を検証する。詳細は[テスト仕様書](./2026.07.05%20%5BAI%5D%2007-testing.md)を参照。
+
 ## 5. ビルド成果物の構成
 
 ```
@@ -164,7 +182,7 @@ dist/
 
 1. **`pnpm run build` でビルド**。`dist/` にファイルが生成される。
 2. **`pnpm run dev` で開発中はウォッチモード**を使うと、ソース変更が自動で反映される。
-3. **`pnpm run type-check` で型エラーだけ確認**できる。ビルドせずに素早くチェック。
+3. **`pnpm run typecheck` で型エラーだけ確認**できる。ビルドせずに素早くチェック。
 4. **`external` に指定されたパッケージはバンドルに含まれない**。利用側でインストールが必要。
 5. **ビルドは tsup（esbuild ベース）が行い、tsc は型チェック専用**。この分業により高速ビルドと厳密な型チェックを両立。
 6. **`src/` は npm パッケージに含まれない**。利用者が見るのは `dist/` のビルド済みコードのみ。