docs: add Cloudflare target design spec

Worker + Container architecture with D1, Service Binding RPC
for communication, and hatk build --target cloudflare output.

Co-Authored-By: Claude Opus 4.6 <[e-mail]>

docs/superpowers/specs/2026-03-18-cloudflare-target-design.md

···
+# Cloudflare Target Design
+
+## Goal
+
+Add `target: 'cloudflare'` to hatk so apps can deploy to Cloudflare Workers + Containers with D1 as the database. Same hatk project, different deployment target.
+
+## Audience
+
+hatk users who want edge deployment, scale-to-zero, or prefer Cloudflare over Railway/VPS.
+
+## Architecture
+
+When `hatk.config.ts` has `target: 'cloudflare'`, `hatk build` produces two deployment artifacts plus a generated Cloudflare config:
+
+```
+dist/
+├── worker/          # Cloudflare Worker
+│   └── index.ts     # Fetch handler: XRPC + SvelteKit SSR + OAuth + admin
+├── container/       # Cloudflare Container (Node process)
+│   └── index.ts     # Firehose subscription + backfill + label evaluation
+└── wrangler.jsonc   # Generated config (D1 binding, Service Binding, Container)
+```
+
+### Component Split
+
+| Component | Runtime | Responsibilities |
+|-----------|---------|-----------------|
+| **Worker** | Cloudflare Worker | XRPC handlers, SvelteKit SSR, OAuth, admin API |
+| **Container** | Cloudflare Container | Firehose, backfill, label evaluation |
+| **D1** | Shared | All data storage (SQLite-compatible) |
+
+### Communication
+
+Worker → Container via **Service Binding RPC**. The Worker calls methods on the Container directly as function calls (near-zero latency, no HTTP overhead):
+
+- `env.CONTAINER.resync(did)` — trigger backfill for a single repo
+- `env.CONTAINER.resyncAll()` — trigger full re-enumeration
+- `env.CONTAINER.getStatus()` — backfill progress
+
+No Container → Worker communication needed.
+
+---
+
+## D1 Database Adapter
+
+New file: `packages/hatk/src/database/adapters/d1.ts`
+
+Implements the existing `DatabasePort` interface using Cloudflare's D1 binding API. No changes to the interface itself.
+
+### Query Execution
+
+- **`query(sql, params)`** — `d1.prepare(sql).bind(...params).all()`
+- **`execute(sql, params)`** — `d1.prepare(sql).bind(...params).run()`
+- **`executeMultiple(sql)`** — Split by `;`, run as `d1.batch([...])`
+
+### Transactions
+
+D1 has no `BEGIN/COMMIT/ROLLBACK`. The adapter fakes it:
+
+1. `beginTransaction()` — start buffering statements
+2. `execute()` during a transaction — append to buffer instead of executing
+3. `commit()` — flush buffer as `d1.batch([...])` (atomic — all succeed or all fail)
+4. `rollback()` — clear the buffer
+
+This preserves the same atomicity guarantee as real transactions.
+
+### Bulk Insert
+
+The existing `BulkInserter` interface stays the same. The D1 implementation:
+
+1. `append(values)` — generate an INSERT statement, add to batch buffer
+2. `flush()` — send buffer as `d1.batch([...])`, clear buffer
+3. Buffer size tuned to stay under D1's CPU limits per batch
+
+No prepared statements or native appenders — all dynamic SQL generation.
+
+### Dialect
+
+D1 is SQLite under the hood. Reuse the SQLite dialect's type map and placeholder style. No new dialect flags — the D1 adapter handles its own constraints internally.
+
+### FTS
+
+D1 supports FTS5. The existing SQLite search port should work with D1 as-is.
+
+---
+
+## Config
+
+```ts
+// hatk.config.ts
+export default defineConfig({
+  target: 'cloudflare', // new field, default: 'node'
+  // ... everything else stays the same
+})
+```
+
+No other config changes. The `database` path field is ignored when target is `cloudflare` (D1 binding is configured in wrangler.jsonc).
+
+---
+
+## Worker Entry
+
+Standard Cloudflare Workers fetch handler:
+
+```ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // 1. Initialize D1 adapter from env.DB binding
+    // 2. Try XRPC routes (same handlers, D1-backed ctx)
+    // 3. Try admin routes (resync → env.CONTAINER.resync(did) via RPC)
+    // 4. Fall through to SvelteKit for everything else
+  }
+}
+```
+
+XRPC handlers don't change — they receive `ctx` with `ctx.db.query()` backed by D1 instead of SQLite. OAuth is pure JS crypto, no native deps.
+
+SvelteKit uses `@sveltejs/adapter-cloudflare` instead of `adapter-node`.
+
+### Admin Resync Change
+
+The only behavioral difference from the Node target: admin resync calls `env.CONTAINER.resync(did)` over RPC instead of `triggerAutoBackfill(did)` in-process.
+
+---
+
+## Container Entry
+
+A standard Node process (Cloudflare Containers support Node). Essentially the current `main.ts` minus the HTTP server:
+
+- Connects to firehose relay via WebSocket
+- Processes commits, validates records, writes to D1
+- Runs backfill loop for pending repos
+- Exposes RPC methods for the Worker to call
+
+No CPU/memory limits like Workers — it's a real container.
+
+---
+
+## Build Step
+
+`hatk build` with `target: 'cloudflare'`:
+
+1. Run `@sveltejs/adapter-cloudflare` for SvelteKit
+2. Bundle XRPC handlers + OAuth into Worker entry
+3. Bundle firehose + backfill into Container entry
+4. Generate `wrangler.jsonc` with D1 binding, Service Binding to Container
+
+User deploys with `npx wrangler deploy`.
+
+---
+
+## Known Limitations
+
+- **D1 size limit**: 10GB per database. Cannot be increased. Sufficient for most hatk apps, but large-scale indexing may hit this. Document as a constraint of the Cloudflare target.
+- **Backfill speed**: D1 writes are ~30ms (HTTP) vs sub-ms (local SQLite). Backfill will be noticeably slower on Cloudflare.
+- **No horizontal sharding**: Single D1 database. Cloudflare's recommended pattern is per-tenant sharding, but that doesn't apply to firehose indexing.
+
+---
+
+## Implementation Scope
+
+| Component | Estimated Lines | Description |
+|-----------|----------------|-------------|
+| D1 adapter | ~400 | `DatabasePort` implementation with batch transactions, bulk inserter |
+| Dialect update | ~20 | Minimal — reuse SQLite dialect |
+| Adapter factory | ~20 | Add `d1` engine selection |
+| Worker entry | ~150 | Fetch handler wiring XRPC + SvelteKit + OAuth |
+| Container entry | ~100 | Firehose + backfill + RPC methods |
+| Build command | ~200 | `--target cloudflare` output generation + wrangler.jsonc |
+| Config | ~10 | `target` field in `HatkConfig` |
+| **Total** | **~900** | |