fix: apply feedback from v3 migration field testing

Three derivative projects migrated from v2 to v3, revealing gaps in
documentation, tooling, and package configuration.

Documentation (migration-prompt.ja.md):
- Add DSQL uuid vs text implicit cast warning to incompatibility table
- Warn that Vpc.applyRemovalPolicy(RETAIN) does not propagate to child
  resources (subnets, route tables, IGWs); recommend two-phase deploy
- Document DSQL COPY FROM STDIN support with 3,000-row tx limit

Documentation (design.ja.md):
- Explain why lint-staged omits typeCheck (staged-file-only args are
  incompatible with project-wide tsconfig resolution; CI covers it)

Tooling (dsql-compat.ts):
- Strip USING btree from drizzle-kit output; DSQL indexes default to
  B-tree and reject the USING clause

Package fix (apps/cdk/package.json):
- Move @types/aws-lambda from dependencies to devDependencies per
  AGENTS.md convention (only native binaries belong in dependencies)

Author: konokenj

.serverless-full-stack-webapp-starter-kit/docs/v3.0.0/design.ja.md

@@ -223,7 +223,7 @@ DSQL 非互換パターンをコーディング時とマイグレーション時
 
 各サブパッケージが定型タスク名（`dev`、`build`、`test:unit`、`lint`、`check:ci` 等）を自身の `package.json` に定義し、ルートからは `pnpm -r run <task>` で一括実行する。ルート `package.json` にはタスクのエイリアススクリプトを置かない — 各パッケージが自身のスクリプトを持つため冗長であり、`--if-present` 付きの間接呼び出しはデバッグを困難にする。
 
-pre-commit フックは `simple-git-hooks` + `lint-staged` で構成し、ステージ済みファイルに oxlint/oxfmt を実行した後、全パッケージの `test:unit` を実行する。`prepare` スクリプトにより `pnpm install` 時にフックが自動インストールされる。
+pre-commit フックは `simple-git-hooks` + `lint-staged` で構成し、ステージ済みファイルに oxlint/oxfmt を実行した後、全パッケージの `test:unit` を実行する。`prepare` スクリプトにより `pnpm install` 時にフックが自動インストールされる。lint-staged の oxlint 呼び出しでは `typeCheck` による型チェックが効かない — lint-staged はステージ済みファイルのみを引数に渡すため、プロジェクト全体の tsconfig 解決が必要な型チェックと非互換。型チェックは CI の `check:ci`（`oxlintrc.json` の `typeCheck: true`）で担保する。
 
 ### Docker ビルドの制約
 

.serverless-full-stack-webapp-starter-kit/docs/v3.0.0/migration-prompt.ja.md

@@ -95,6 +95,7 @@ schema.prisma を主たるデータソースとする。理由: Prisma スキー
 | 検出対象                                 | DSQL での対処                                    | 判断基準                                                                                                                                                                                                                   |
 | ---------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `SERIAL` / `BIGSERIAL` 主キー            | `uuid().defaultRandom()` または IDENTITY 列      | 既存データに外部参照がある場合は UUID 変換時に参照元も更新が必要                                                                                                                                                           |
+| `@default(uuid())` の主キー              | `uuid()` または `text()` を選択                  | **DSQL は `uuid = text` の暗黙型キャストをサポートしない。** アプリコードやクエリで文字列リテラルと比較している場合は `text()` を使うこと。`uuid()` を選ぶ場合は全ての比較箇所で型を一致させる必要がある                   |
 | `ENUM` 型                                | `text()` + Zod バリデーション                    | 既存の ENUM 値を洗い出し、Zod スキーマに列挙する                                                                                                                                                                           |
 | `JSON` / `JSONB` カラム                  | `text()` + アプリ層でシリアライズ                | 既存データの JSON 構造を確認し、型定義を作成する。**Prisma は Json 型を自動で parse/stringify するが、Drizzle の text() は手動変換が必要。** Phase 3-4 で全ての読み書き箇所に `JSON.parse`/`JSON.stringify` を追加すること |
 | 外部キー制約（`@relation`）              | 削除（Drizzle `relations()` で代替）             | **`onDelete: Cascade` / `onDelete: SetNull` に依存する削除ロジックを特定すること。** DSQL は FK をサポートしないため、cascade 削除はアプリ層で `db.transaction()` 内の明示的な削除に変換が必要                             |
@@ -368,7 +369,7 @@ cd apps/webapp && pnpm run dev
 
 ### Phase 5-1: DSQL クラスタ作成（CDK デプロイ 1回目）
 
-1. **Aurora v2 リソースに RemovalPolicy.RETAIN を設定**: CDK の Aurora Serverless v2 クラスタ、VPC、関連リソースに `removalPolicy: cdk.RemovalPolicy.RETAIN` を追加。これにより CloudFormation の `DeletionPolicy` が `Retain` に変わり、後のデプロイでリソース定義を削除しても実リソースは残る。
+1. **Aurora v2 リソースに RemovalPolicy.RETAIN を設定**: CDK の Aurora Serverless v2 クラスタ、VPC、関連リソースに `removalPolicy: cdk.RemovalPolicy.RETAIN` を追加。これにより CloudFormation の `DeletionPolicy` が `Retain` に変わり、後のデプロイでリソース定義を削除しても実リソースは残る。**注意: `Vpc.applyRemovalPolicy(RETAIN)` は子リソース（サブネット、ルートテーブル、インターネットゲートウェイ等）に伝播しない。** VPC を RETAIN する場合は、`vpc.node.findAll()` で子リソースを列挙し個別に `applyRemovalPolicy(RETAIN)` を設定するか、Phase 5-3 で VPC リソース定義を削除する際に2段階デプロイ（1回目: Lambda の VPC 設定を外す → 2回目: VPC 定義を削除）で ENI の解放を待つこと。
 
 2. **CDK に DSQL クラスタを追加**: v3 キットからコピー済みの `database.ts` を使用。webapp と async-job はまだ Aurora v2 に接続したまま。
 
@@ -404,6 +405,8 @@ pnpm --filter @repo/db run migrate
 
 Phase 1-3 で記録した各テーブルの行数に基づいて移行方法を選択する。
 
+**DSQL は `COPY FROM STDIN` をサポートする。** `pg_dump --data-only` のデフォルト出力（COPY 形式）をそのまま `psql` で投入できるため、小〜中規模データの移行では最も簡単な方法。ただし DSQL の 3,000 行/トランザクション制限があるため、大テーブルは COPY 文をテーブルごとに分割し、各 COPY を個別トランザクションで実行すること。
+
 `pg_dump --data-only` で取得したダンプを DSQL に投入する場合、以下の変換が必要:
 
 - `pg_dump` のプリアンブル（`SET`、`SELECT pg_catalog.*`、`\restrict`、`\unrestrict`）を除去

apps/cdk/package.json

@@ -18,13 +18,13 @@
     "@aws-appsync/utils": "^1.12.0",
     "@aws-sdk/client-cognito-identity-provider": "^3.987.0",
     "@cdklabs/deploy-time-build": "^0.1.1",
-    "@types/aws-lambda": "^8.10.149",
     "aws-cdk-lib": "^2.189.1",
     "cdk-nag": "^2.14.29",
     "constructs": "^10.0.0",
     "source-map-support": "^0.5.21"
   },
   "devDependencies": {
+    "@types/aws-lambda": "^8.10.149",
     "@types/jest": "^27.5.0",
     "@types/node": "^22.14.1",
     "aws-cdk": "^2.1007.0",

packages/db/src/dsql-compat.test.ts

@@ -34,6 +34,11 @@ describe('transformSql', () => {
     expect(transformSql(input)).toBe(input);
   });
 
+  test('T4b: USING btree removed from CREATE INDEX', () => {
+    const input = 'CREATE INDEX "idx" ON "T" USING btree ("col");';
+    expect(transformSql(input)).toBe('CREATE INDEX ASYNC "idx" ON "T" ("col");');
+  });
+
   test('T5: inline REFERENCES removed, column definition preserved', () => {
     const result = transformSql(readFixture('add-fk-inline.input.sql'));
     expect(result).toBe(readFixture('add-fk-inline.expected.sql'));

packages/db/src/dsql-compat.ts

@@ -20,6 +20,9 @@ export function transformSql(sql: string): string {
     unique ? `CREATE UNIQUE INDEX ASYNC` : `CREATE INDEX ASYNC`,
   );
 
+  // Remove USING btree — DSQL indexes are B-tree by default and do not support the USING clause.
+  result = result.replace(/\s+USING\s+btree/gi, '');
+
   // Remove standalone FOREIGN KEY constraint lines BEFORE inline REFERENCES removal.
   // The inline REFERENCES regex would strip the REFERENCES part, leaving a partial CONSTRAINT line.
   // Pattern: ,\n\tCONSTRAINT "..." FOREIGN KEY (...) REFERENCES "..."("...")