docs: document migration-runner responsibility separation in plan

Author: konokenj

.kiro/specs/pnpm-workspaces/plan.md

@@ -98,19 +98,45 @@ compose.yaml の PostgreSQL を廃止し、開発用 DSQL クラスタを使用
 
 ## migration-runner の設計
 
+### 責務の分離
+
+3 つの責務を明確に分離する。各層は隣接する層だけに依存し、飛び越えた依存を持たない。
+
+1. **マイグレーションコアロジック**（`packages/db/src/migrate.ts`, `check-dsql-compat.ts`）
+   - `pg.Pool` を受け取り、SQL ファイルを 1 文ずつ BEGIN/COMMIT で実行する
+   - drizzle-kit 出力の DSQL 自動変換（statement-breakpoint → 空行、INDEX → ASYNC、FK 除去）
+   - CDK にも Drizzle にも依存しない。ORM に関わらず使える汎用層
+   - 将来的に独立パッケージとして切り出し可能な境界
+
+2. **Lambda ハンドラー**（`apps/cdk/lib/constructs/dsql-migrator/handler.ts`）
+   - コアロジックの `migrate()` を呼ぶ薄いラッパー。Lambda イベントを受けて Pool を生成し、結果を返すだけ
+   - CDK Construct と 1:1 で対応するが、ロジックは持たない
+
+3. **CDK Construct**（`apps/cdk/lib/constructs/dsql-migrator/index.ts`）
+   - DockerImageFunction + CDK Trigger でデプロイ時自動実行を構成する
+   - Database Construct から endpoint と IAM 権限を受け取る
+   - マイグレーションの中身には関与しない
+
+この分離により:
+- コアロジックは Drizzle 以外の ORM（Prisma、手書き SQL）でも利用可能
+- Lambda ハンドラーは CDK 以外のデプロイツール（Terraform、SAM）でも利用可能
+- CDK Construct はマイグレーション SQL の生成方法に依存しない
+
 ### 配置
 
 `packages/db` にコアロジック・CLI・マイグレーション SQL を同居させる。スキーマ定義とマイグレーションが同一パッケージに閉じ、`pnpm --filter @repo/db run migrate` でローカル実行可能。
 
 ```
 packages/db/
   src/
-    schema.ts           # Drizzle スキーマ定義
-    client.ts           # DSQL クライアント（IAM 認証）
-    migrate.ts          # マイグレーションコアロジック（Pool を受け取る、環境非依存）
-    cli.ts              # CLI エントリポイント（cli.ts → migrate.ts）
-  migrations/           # SQL ファイル
-  package.json          # scripts: { "migrate": "tsx src/cli.ts" }
+    schema.ts               # Drizzle スキーマ定義
+    client.ts               # DSQL クライアント（IAM 認証）
+    migrate.ts              # マイグレーションコアロジック（Pool を受け取る、環境非依存）
+    check-dsql-compat.ts    # drizzle-kit 出力の DSQL 自動変換 + バリデーション
+    cli.ts                  # CLI エントリポイント（cli.ts → migrate.ts）
+  drizzle.config.ts         # drizzle-kit 設定（generate 用、DB 接続不要）
+  migrations/               # SQL ファイル + meta/ (drizzle-kit snapshot)
+  package.json              # scripts: { "generate": "...", "migrate": "..." }
 ```
 
 CDK 側は `apps/cdk/lib/constructs/dsql-migrator/` に Lambda ハンドラー（handler.ts）と Construct を配置。handler.ts は `@repo/db` の migrate() を import する薄いラッパー。現行の `event-bus/handler.mjs` と同じパターン。将来的に独立 Construct として切り出す余地を残す。