既存 Sinatra → Cloudflare Workers 移行

homura 本体（app/app.rb + app/routes/canonical_all.rb）が実際に踏んでいるパターンに基づきます。誇張せず、このスタックで動作確認済みの範囲だけを書きます。

対象と非対象

向いているもの

• Sinatra 4.2 系で、ルートが DSL（get / post 等）中心のアプリ。
• DB を D1 + Sequel に寄せられる（または API のみで D1 不要）。
• テンプレートを ERB のままビルド時プリコンパイルできる。

厳しいもの（早期に見送り判断）

• ActiveRecord 前提の複雑なモデル層、多数の Rack ミドルウェア、サーバー側 File.read 前提のテンプレート運用。
• Puma / Unicorn 専用に深く依存した起動フック。

6 ステップ（推奨順）

1. Gemfile: opal-homura（require: 'opal'）、homura-runtime、sinatra-homura を追加。D1 を使うなら sequel-d1 も追加します。
2. エントリ: app.rb（またはメイン定義ファイル）の先頭付近に # await: マジックコメントを付与（JWT / D1 / fetch など非同期が混ざるファイルは必須。Phase 15-C 教訓）。続けて require 'sinatra/cloudflare_workers'。
3. ルート: 既存の get / post を可能な限りそのまま移植。Sinatra の DSL は互換パッチ側で吸収。
4. DB: Sequel.connect(adapter: :d1, d1: env['cloudflare.env'].DB) の形へ。マイグレーションは bundle exec cloudflare-workers-migrate compile db/migrations → apply（sequel-d1 README 参照）。
5. ビュー: bundle exec cloudflare-workers-erb-compile --input views --output build/templates.rb --namespace …（プロジェクトの Rake / npm に合わせる）。
6. Workers 向けビルド: bundle exec cloudflare-workers-build（または --standalone）で build/worker.entrypoint.mjs を生成し、wrangler.toml の main と一致させて wrangler deploy。

よくあるハマりポイント

• # await:: ルート内で __await__ が必要なのにマジックコメントが無いと、Promise がそのまま残って 1101 等で落ちます。
• 同期 FS: Workers ではリクエスト処理中の File.read は使えません。ERB／アセットはビルド時に埋め込み。
• require パス: vendor/ や gem lib を Opal の -I に載せる順序が重要（sequel-d1 README のとおり gems/sequel-d1/lib を vendor より前）。
• direct eval: Opal の制約へはビルド後 patch-opal-evals.mjs が自動適用（cloudflare-workers-build パイプライン）。
• 起動 CPU: 重い定数初期化はリクエストをまたぐとタイムアウトしやすい。homura では分割・遅延初期化で対処済みの箇所あり（具体値は本番計測に依存）。
• Cookie セッション: 本リポジトリの /login は署名クッキー方式。JWT も別ルートで利用可能。

動かない・優先度を下げる例

• リクエスト中にローカルファイルキャッシュへ何度も読みに行く設計。
• 巨大な gem をそのまま require し、Opal 未対応のネイティブ拡張に依存している。
• WebSocket やストリーミングが必須だが、Workers 側の制約と握れていない（別途検証が必要）。