@spfn/core 0.2.0-beta.5 → 0.2.0-beta.51

package/README.md

@@ -1,1308 +1,208 @@
-# @spfn/core - Technical Architecture Documentation
+# @spfn/core — Type-safe Next.js + Hono backend framework (route DSL → RPC proxy → typed client)
 
-Full-stack type-safe framework for building Next.js + Node.js applications with end-to-end type inference.
+`@spfn/core` is the backend runtime for SPFN: a tRPC-style **route DSL** (TypeBox-validated,
+end-to-end typed), a Drizzle/postgres.js **data layer**, an HTTP **server** entry point, and a
+Next.js **RPC proxy + typed client** that wires a browser/RSC app to that backend with
+compile-time-only type inference.
 
-[![npm version](https://badge.fury.io/js/@spfn%2Fcore.svg)](https://www.npmjs.com/package/@spfn/core)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+There is **no root barrel** — `@spfn/core` itself imports nothing. Everything is reached
+through subpath exports (`@spfn/core/route`, `@spfn/core/db`, `@spfn/core/nextjs`, …). Each
+module is canonically documented in its own `src/<mod>/README.md`; this file is the index +
+end-to-end flow. Follow the links for API detail.
 
-> **Beta Release**: SPFN is currently in beta. Core APIs are stable but may have minor changes before 1.0.
+## Install
 
----
-
-## Table of Contents
-
-- [Overview & Philosophy](#overview--philosophy)
-- [System Architecture](#system-architecture)
-- [Module Architecture](#module-architecture)
-- [Type System](#type-system)
-- [Integration Points](#integration-points)
-- [Design Decisions](#design-decisions)
-- [Extension Points](#extension-points)
-- [Migration Guides](#migration-guides)
-- [Module Exports](#module-exports)
-- [Quick Reference](#quick-reference)
-
----
-
-## Overview & Philosophy
-
-SPFN (Superfunction) is a full-stack TypeScript framework that provides **end-to-end type safety** from database to frontend with a **tRPC-inspired developer experience**.
-
-### Core Principles
-
-1. **Type Safety First**: Types flow from database schema → server routes → client API
-2. **Developer Experience**: tRPC-style API with method chaining (`.params().query().call()`)
-3. **Explicit over Magic**: No file-based routing, explicit imports for tree-shaking
-4. **Security by Default**: HttpOnly cookies, API Route Proxy, environment isolation
-5. **Production Ready**: Transaction management, read/write separation, graceful shutdown
-
-### Design Philosophy
-
-**Inspired by tRPC, Built for Production:**
-
-```typescript
-// tRPC-style API calls with structured input
-const user = await api.getUser.call({
-    params: { id: '123' },
-    query: { include: 'posts' }
-});
-//    ^? { id: string; name: string; email: string; posts: Post[] }
-```
-
-**But with production features:**
-- Cookie handling via API Route Proxy
-- Transaction management with AsyncLocalStorage
-- Read/Write database separation
-- Graceful shutdown and health checks
-- Lifecycle hooks for extensibility
-
----
-
-## System Architecture
-
-### High-Level Overview
-
-```
-+---------------------------------------------------------------+
-|                    Next.js Application                         |
-|  +----------------------------------------------------------+  |
-|  |  Frontend (React)                                        |  |
-|  |  - Server Components: SSR, ISR, Static                   |  |
-|  |  - Client Components: Interactive UI                     |  |
-|  +---------------------------+------------------------------+  |
-|                              |                                 |
-|                              | import { api } from '@spfn/...' |
-|                              | api.getUser.call({ params })   |
-|                              v                                 |
-|  +----------------------------------------------------------+  |
-|  |  RPC Proxy (Edge/Node.js)                                |  |
-|  |  app/api/rpc/[routeName]/route.ts                        |  |
-|  |                                                           |  |
-|  |  1. Resolve routeName → method/path from router          |  |
-|  |                                                           |  |
-|  |  2. Request Interceptors                                 |  |
-|  |     - Auth token injection                               |  |
-|  |     - Cookie forwarding                                  |  |
-|  |     - Header manipulation                                |  |
-|  |                                                           |  |
-|  |  3. Forward to SPFN Server                               |  |
-|  |     fetch(SPFN_API_URL + resolvedPath)                   |  |
-|  |                                                           |  |
-|  |  4. Response Interceptors                                |  |
-|  |     - Set HttpOnly cookies                               |  |
-|  |     - Transform response                                 |  |
-|  |     - Error handling                                     |  |
-|  +---------------------------+------------------------------+  |
-+-------------------------------+--------------------------------+
-                                |
-                                | HTTP Request
-                                v
-+---------------------------------------------------------------+
-|                      SPFN API Server (Node.js)                 |
-|  +----------------------------------------------------------+  |
-|  |  Hono Web Framework                                      |  |
-|  |                                                           |  |
-|  |  12-Step Middleware Pipeline:                            |  |
-|  |  1. Logger                                               |  |
-|  |  2. CORS                                                 |  |
-|  |  3. Global Middlewares                                   |  |
-|  |  4. Route-specific Middlewares                           |  |
-|  |  5. Request Validation (TypeBox)                         |  |
-|  |  6. Route Handler                                        |  |
-|  |  7-12. Response processing, error handling               |  |
-|  +---------------------------+------------------------------+  |
-|                              |                                 |
-|                              | define-route System             |
-|                              v                                 |
-|  +----------------------------------------------------------+  |
-|  |  Route Handlers                                          |  |
-|  |  - Type-safe input validation                            |  |
-|  |  - Transaction middleware                                |  |
-|  |  - Business logic                                        |  |
-|  +---------------------------+------------------------------+  |
-|                              |                                 |
-|                              | Database Queries                |
-|                              v                                 |
-|  +----------------------------------------------------------+  |
-|  |  Database Layer (Drizzle ORM)                            |  |
-|  |  - Helper functions (findOne, create, etc.)              |  |
-|  |  - Transaction propagation (AsyncLocalStorage)           |  |
-|  |  - Read/Write separation                                 |  |
-|  +---------------------------+------------------------------+  |
-+-------------------------------+--------------------------------+
-                                |
-                                | SQL Queries
-                                v
-+---------------------------------------------------------------+
-|                    PostgreSQL Database                         |
-|  - Primary (Read/Write)                                        |
-|  - Replica (Read-only) [optional]                              |
-+---------------------------------------------------------------+
-```
-
-### Request Flow Example
-
-```typescript
-// 1. Client Call (Next.js Server Component)
-// app/users/[id]/page.tsx
-import { createApi } from '@spfn/core/nextjs';
-import type { AppRouter } from '@/server/router';
-
-const api = createApi<AppRouter>();
-const user = await api.getUser.call({ params: { id: params.id } });
-// → GET /api/rpc/getUser?input={"params":{"id":"123"}}
-
-// 2. RPC Proxy
-// app/api/rpc/[routeName]/route.ts
-import { appRouter } from '@/server/router';
-import { createRpcProxy } from '@spfn/core/nextjs/server';
-
-export const { GET, POST } = createRpcProxy({ router: appRouter });
-// - Resolves routeName → method/path from router
-// - Forwards to http://localhost:8790/users/123
-// - Applies interceptors (auth, cookies)
-
-// 3. SPFN Server Route Handler
-// src/server/routes/users.ts
-export const getUser = route.get('/users/:id')
-    .input({
-        params: Type.Object({ id: Type.String() }),
-    })
-    .handler(async (c) => {
-        const { params } = await c.data();
-        const user = await userRepo.findById(params.id);
-        return user;
-    });
-
-// 4. Database Query
-// Drizzle ORM with helper function
-// SELECT * FROM users WHERE id = $1
-
-// 5. Response flows back through interceptors → proxy → client
-```
-
----
-
-## Module Architecture
-
-### 1. Route System (`src/route/`)
-
-**Purpose**: Type-safe routing with automatic validation
-
-**Architecture**:
-
-```
-route.get('/users/:id')
-    .input({ params, query, body })
-    .handler(async (c) => { ... })
-    |
-    |-- Type Inference: RouteDef<TInput, TResponse>
-    |-- Validation: TypeBox schema
-    |-- Middleware: Skip control per route
-    |-- Response: Direct return / c.json() / helpers
-```
-
-**Key Components**:
-
-- `defineRouter()`: Combines route definitions into typed router
-- `route.get/post/put/patch/delete()`: Route builder with method chaining
-- Input validation: Automatic TypeBox validation
-- Middleware control: Per-route middleware skip
-
-**Design Pattern**: Builder pattern with type inference
-
-**[→ Full Documentation](./src/route/README.md)**
-
----
-
-### 2. Server System (`src/server/`)
-
-**Purpose**: HTTP server with lifecycle management
-
-**Architecture**:
-
-```
-Configuration Sources (Priority Order):
-1. Runtime config (startServer({ port: 3000 }))
-2. server.config.ts (defineServerConfig().build())
-3. Environment variables (PORT, DATABASE_URL)
-4. Defaults
-
-    |
-    v
-Middleware Pipeline:
-1. Request Logger
-2. CORS
-3. Global Middlewares
-4. Named Middlewares
-5. beforeRoutes hook
-6. Route Registration
-7. afterRoutes hook
-8. Route-specific Middlewares
-9. Request Validation
-10. Route Handler Execution
-11. Response Serialization
-12. Error Handler
-
-    |
-    v
-Lifecycle Hooks:
-- beforeInfrastructure
-- afterInfrastructure
-- beforeRoutes
-- afterRoutes
-- afterStart
-- beforeShutdown
-```
-
-**Key Components**:
-
-- `defineServerConfig()`: Fluent configuration builder
-- `createServer()`: Creates Hono app with routes
-- `startServer()`: Starts HTTP server with lifecycle
-- Lifecycle hooks: beforeInfrastructure, afterInfrastructure, beforeRoutes, afterRoutes, afterStart, beforeShutdown
-- Graceful shutdown: SIGTERM/SIGINT handling
-
-**Design Pattern**: Builder + Lifecycle hooks
-
-**[→ Full Documentation](./src/server/README.md)**
-
----
-
-### 3. Database System (`src/db/`)
-
-**Purpose**: Type-safe database operations with transactions
-
-**Architecture**:
-
-```
-Application Code
-    |
-    | findOne(users, { id: 1 })
-    v
-Helper Functions (Facade)
-    |
-    | Check AsyncLocalStorage for transaction
-    v
-Transaction Context?
-    |-- Yes: Use transaction instance
-    |-- No: Use default database connection
-    |
-    v
-Drizzle ORM Query Builder
-    |
-    v
-PostgreSQL (Primary or Replica)
-```
-
-**Key Components**:
-
-- Helper functions: `findOne`, `findMany`, `create`, `update`, `delete`, `count`
-- Transaction middleware: `Transactional()` with AsyncLocalStorage propagation
-- Read/Write separation: Automatic routing based on operation
-- Schema helpers: `id()`, `timestamps()`, `foreignKey()`, `enumText()`
-
-**Design Pattern**: Facade + AsyncLocalStorage for transaction propagation
-
-**[→ Full Documentation](./src/db/README.md)**
-
-**Transaction Flow**:
-
-```typescript
-// Route with Transactional middleware
-app.bind(createUserContract, [Transactional()], async (c) => {
-    // All database operations use the same transaction
-    const user = await create(users, { name: 'John' });
-    const profile = await create(profiles, { userId: user.id });
-
-    // Auto-commit on success
-    // Auto-rollback on error
-    return c.json(user);
-});
-```
-
----
-
-### 4. Client System (`src/nextjs/`)
-
-**Purpose**: Type-safe API client for Next.js with tRPC-style DX
-
-**Architecture**:
-
-```
-Client Code
-    |
-    | api.getUser.call({ params: { id: '123' } })
-    v
-ApiClient (Proxy)
-    |
-    | body 유무로 GET/POST 결정
-    | GET /api/rpc/getUser?input={...}
-    | POST /api/rpc/createUser body: {...}
-    v
-fetch() to Next.js API Route
-    |
-    v
-RpcProxy (API Route Handler)
-    |
-    | 1. Extract routeName from URL
-    | 2. Lookup method/path from appRouter
-    | 3. Execute request interceptors
-    | 4. Forward to SPFN_API_URL with resolved path
-    | 5. Execute response interceptors
-    | 6. Set cookies from ctx.setCookies
-    v
-Return NextResponse
-```
-
-**Key Components**:
-
-- `createApi()`: tRPC-style client with type inference (no metadata needed)
-- `createRpcProxy()`: RPC-style API Route handler with route resolution
-- `registerInterceptors()`: Registry for plugin interceptors
-- Path matching: Wildcard and param support (`/_auth/*`, `/users/:id`)
-- Cookie handling: `setCookies` array in response interceptors
-
-**Design Pattern**: Proxy for client, RPC resolution for proxy
-
-**[→ Full Documentation](./src/nextjs/README.md)**
-
----
-
-### 5. Error System (`src/errors/`)
-
-**Purpose**: Structured error handling with HTTP status codes
-
-**Key Components**:
-
-- `ApiError`: Base error class
-- `ValidationError`: Input validation failures (400)
-- `NotFoundError`: Resource not found (404)
-- `ConflictError`: Duplicate resources (409)
-- `UnauthorizedError`: Authentication required (401)
-
-**[→ Full Documentation](./src/errors/README.md)**
-
----
-
-### 6. Logger System (`src/logger/`)
-
-**Purpose**: Structured logging with transports and masking
-
-**Key Components**:
-
-- Adapter pattern: Pino (default) or custom
-- Sensitive data masking: Passwords, tokens, API keys
-- File rotation: Date and size-based with cleanup
-- Multiple transports: Console, File, Slack, Email
-
-**[→ Full Documentation](./src/logger/README.md)**
-
----
-
-### 7. Cache System (`src/cache/`)
-
-**Purpose**: Valkey/Redis integration with master-replica support
-
-**Key Components**:
-
-- `initCache()`: Initialize connections
-- `getCache()`: Write operations (master)
-- `getCacheRead()`: Read operations (replica or master)
-- `isCacheDisabled()`: Check if cache is disabled
-- Graceful degradation when cache unavailable
-
-**[→ Full Documentation](./src/cache/README.md)**
-
----
-
-### 8. Middleware System (`src/middleware/`)
-
-**Purpose**: Named middleware with skip control
-
-**Key Components**:
-
-- `defineMiddleware()`: Create named middleware
-- Skip control: Routes can skip specific middlewares
-- Built-in: Logger, CORS, Error handler
-
-**[→ Full Documentation](./src/middleware/README.md)**
-
----
-
-### 9. Job System (`src/job/`)
-
-**Purpose**: Background job processing with pg-boss
-
-**Architecture**:
-
-```
-job('send-email')
-    .input(schema)
-    .options({ retryLimit: 3 })
-    .cron('0 9 * * *')
-    .on(eventDef)
-    .handler(async (input) => { ... })
-```
-
-**Key Components**:
-
-- `job()`: Fluent job builder
-- `defineJobRouter()`: Group jobs for registration
-- Job types: Standard, Cron, RunOnce, Event-driven
-- `initBoss()`, `registerJobs()`: pg-boss lifecycle
-
-**Design Pattern**: Builder pattern (same as routes)
-
----
-
-### 10. Event System (`src/event/`)
-
-**Purpose**: Decoupled pub/sub event system
-
-**Architecture**:
-
-```
-defineEvent('user.created', schema)
-    → emit(payload)
-    → handlers (in-memory)
-    → job queues (pg-boss)
-    → cache pub/sub (multi-instance)
-```
-
-**Key Components**:
-
-- `defineEvent()`: Define typed events
-- `event.emit()`: Emit event to all subscribers
-- `event.subscribe()`: In-memory subscription
-- `event.useCache()`: Multi-instance pub/sub via Redis
-
-**Integration**: `job().on(event)` for event-driven jobs
-
----
-
-## Type System
-
-### End-to-End Type Safety Flow
-
-```typescript
-// 1. Database Schema (Source of Truth)
-// src/server/entities/users.ts
-export const users = pgTable('users', {
-    id: id(),
-    name: text('name').notNull(),
-    email: text('email').notNull().unique(),
-    ...timestamps(),
-});
-
-export type User = typeof users.$inferSelect;
-//   ^? { id: string; name: string; email: string; createdAt: Date; updatedAt: Date }
-
-// 2. Server Route Definition
-// src/server/routes/users.ts
-import { route } from '@spfn/core/route';
+```bash
+pnpm add @spfn/core
+# peer (optional): next ^15 || ^16
+# optional deps: ioredis (cache), ws (websocket events); pg-boss ships as a direct dep for jobs
+```
+
+Node `>=18.18.0`. ESM-only.
+
+> **Apps that define entities must declare the Postgres driver directly:** add
+> `postgres` (and `pg`) to your app's `dependencies`. `@spfn/core` uses postgres.js
+> internally, and Drizzle branches its type resolution on the `postgres`/`pg` peer. If
+> the app doesn't pin the same driver, pnpm resolves `drizzle-orm` to a second instance,
+> `BaseRepository` generics collapse to `unknown`, and RPC responses lose their types.
+> `spfn create` adds these automatically; declare them by hand only when wiring SPFN into
+> an existing app.
+>
+> ```bash
+> pnpm add postgres pg
+> ```
+
+## Modules
+
+Each entry below is exactly one subpath from `package.json` `exports`. Import path → one-line
+purpose → canonical README.
+
+| Import path | Purpose | Doc |
+|-------------|---------|-----|
+| `@spfn/core/route` | tRPC-style route DSL (`route.get(...).input(...).handler(...)`) + `defineRouter` / `registerRoutes` / `defineMiddleware`. The core. | [src/route/README.md](./src/route/README.md) |
+| `@spfn/core/route/types` | Shared route types (`HttpMethod`, route/router type primitives). | [src/route/README.md](./src/route/README.md) |
+| `@spfn/core/server` | HTTP server entry: `defineServerConfig()` → `startServer()`; middleware auto-wiring, infra init, graceful shutdown. | [src/server/README.md](./src/server/README.md) |
+| `@spfn/core/nextjs` | Client-safe: `createApi<AppRouter>()`, `ApiError`, client types. No `next/headers`. | [src/nextjs/README.md](./src/nextjs/README.md) |
+| `@spfn/core/nextjs/server` | Server-only: `createRpcProxy({ routeMap })`, `registerInterceptors`. Uses `next/headers`. | [src/nextjs/README.md](./src/nextjs/README.md) |
+| `@spfn/core/db` | Type-safe PostgreSQL (Drizzle): CRUD helpers, `BaseRepository`, schema helpers, transactions, PG error mapping. Single entry point. | [src/db/README.md](./src/db/README.md) |
+| `@spfn/core/db` → manager | Connection lifecycle, pool, primary/replica, health-check, reconnect (`initDatabase`, `getDatabase`). Re-exported from `@spfn/core/db`. | [src/db/manager/README.md](./src/db/manager/README.md) |
+| `@spfn/core/db` → schema | Drizzle column helpers (`id`, `uuid`, `timestamps`, `foreignKey`, `enumText`, `typedJsonb`, `softDelete`, …). Re-exported from `@spfn/core/db`. | [src/db/schema/README.md](./src/db/schema/README.md) |
+| `@spfn/core/db` → transaction | `Transactional` middleware + `runInTransaction`; AsyncLocalStorage propagation to every repo. Re-exported from `@spfn/core/db`. | [src/db/transaction/README.md](./src/db/transaction/README.md) |
+| `@spfn/core/middleware` | Built-in Hono middleware: `ErrorHandler`, `RequestLogger` (+ masking helper). | [src/middleware/README.md](./src/middleware/README.md) |
+| `@spfn/core/errors` | Serializable HTTP/DB error classes + `ErrorRegistry` for cross-boundary deserialization. | [src/errors/README.md](./src/errors/README.md) |
+| `@spfn/core/env` | Schema-based env validation/parsing (isomorphic). `@spfn/core/env/loader` is the **server-only** file loader (`node:fs`). | [src/env/README.md](./src/env/README.md) |
+| `@spfn/core/config` | `@spfn/core`'s own validated env config (`env`, `envSchema`, `registry`) built on `@spfn/core/env`. | [src/config/README.md](./src/config/README.md) |
+| `@spfn/core/logger` | Zero-dependency structured singleton `logger` + child loggers, level masking. | [src/logger/README.md](./src/logger/README.md) |
+| `@spfn/core/cache` | Singleton Valkey/Redis (ioredis) manager, graceful-degrading (`getCache`, `getCacheRead`). | [src/cache/README.md](./src/cache/README.md) |
+| `@spfn/core/job` | pg-boss background jobs: fluent `job()` builder, cron/run-once/event-driven, `defineJobRouter`. | [src/job/README.md](./src/job/README.md) |
+| `@spfn/core/event` | Decoupled pub/sub (`defineEvent`, `defineEventRouter`, `eventRouteMap`); SSE/WS variants below. | [src/event/README.md](./src/event/README.md) |
+| `@spfn/core/event/sse` | Server SSE handler + token manager (SERVER ONLY). | [src/event/README.md](./src/event/README.md) |
+| `@spfn/core/event/sse/client` | Browser SSE (`EventSource`) client. | [src/event/README.md](./src/event/README.md) |
+| `@spfn/core/event/ws` | Server WebSocket handler (SERVER ONLY; `ws` optional dep). | [src/event/README.md](./src/event/README.md) |
+| `@spfn/core/event/ws/client` | Browser WebSocket client. | [src/event/README.md](./src/event/README.md) |
+| `@spfn/core/codegen` | Pluggable codegen orchestrator + the built-in `@spfn/core:route-map` generator that produces the proxy's `routeMap`. | [src/codegen/README.md](./src/codegen/README.md) |
+
+`db/manager`, `db/schema`, `db/transaction` have **no package subpath** of their own — they are
+internal modules re-exported by `@spfn/core/db`. Import them from `@spfn/core/db`. (See Pitfalls
+for the `./client` subpath.)
+
+## How it works
+
+End-to-end, a SPFN backend is **defined once** on the server and consumed type-safely from the
+Next.js app. Types flow purely through TypeScript inference; the only generated artifact is the
+proxy's `routeMap`.
+
+```
+ ① route DSL            ② defineRouter           ③ defineServerConfig → startServer
+ route.get('/users/:id')   defineRouter({ getUser,    defineServerConfig()
+   .input({ params })        createUser })               .routes(appRouter).build()
+   .handler(c => …)        export type AppRouter        startServer()  →  Hono on :8790
+        │                       = typeof appRouter            ▲
+        │ TypeBox = runtime validation + compile-time types   │ registerRoutes mounts routes
+        ▼                                                      │
+ ④ codegen (@spfn/core:route-map)  ──►  routeMap = { getUser: { method:'GET', path:'/users/:id' }, … }
+        │
+        ▼
+ ⑤ Next.js RPC proxy                         ⑥ typed client
+ app/api/rpc/[routeName]/route.ts            lib/api.ts
+ createRpcProxy({ routeMap })                createApi<AppRouter>()   (no codegen for the client)
+   GET/POST /api/rpc/{routeName}               api.getUser.call({ params:{ id } })
+   resolves real method+path from routeMap       └─ fully typed input + output
+   forwards to backend, runs interceptors
+```
+
+1. **Define a route** with `route.<method>(path).input({...}).handler(c => …)` from
+   `@spfn/core/route`. TypeBox schemas in `.input()` give both runtime validation and the
+   compile-time types the handler (`await c.data()`) and the client see. The handler's **return
+   type is inferred** — no manual response typing.
+2. **Compose routes** with `defineRouter({ … })` and export `type AppRouter = typeof appRouter`.
+   That type is the single source of truth for the client; no client codegen reads it.
+3. **Boot the server** with `defineServerConfig().routes(appRouter).build()` then `startServer()`
+   (`@spfn/core/server`). It auto-wires `ErrorHandler`/`RequestLogger`, inits DB/cache, mounts
+   routes via `registerRoutes`, and runs jobs/events. A request is matched by Hono → global
+   middleware → route middleware (`.use([...])`, e.g. `Transactional()`) → input validation/type
+   conversion → handler → serialized response.
+4. **Generate the route-map** with codegen (`@spfn/core:route-map`, e.g. `pnpm codegen`). It emits
+   `routeName → { method, path }` — the only thing the proxy needs to resolve the *real* backend
+   method/path.
+5. **Mount the RPC proxy** in Next.js: `createRpcProxy({ routeMap })` from
+   `@spfn/core/nextjs/server` as the `app/api/rpc/[routeName]/route.ts` catch-all. The client only
+   ever sends `GET` (no body) or `POST` (body/formData) to `/api/rpc/{routeName}`; the proxy looks
+   up `routeMap[routeName]`, substitutes `:params`, and forwards to the backend with the resolved
+   method. Package route maps (`authRouteMap`, `eventRouteMap`) merge into the same `routeMap`.
+6. **Call it** through `createApi<AppRouter>()` from `@spfn/core/nextjs`. The client is a `Proxy`
+   over `AppRouter` — `api.getUser.call({ params })` is fully typed in and out, with zero runtime
+   type cost. Errors come back as `ApiError`, or as the original typed error when its class is in
+   the client's `errorRegistry` (the core registry is always merged in).
+
+## Quick example
+
+```typescript
+// server/router.ts — ① + ②
+import { defineRouter, route } from '@spfn/core/route';
+import { Transactional } from '@spfn/core/db';
 import { Type } from '@sinclair/typebox';
 
-export const getUser = route.get('/users/:id')
-    .input({
-        params: Type.Object({
-            id: Type.String(),
-        }),
-        query: Type.Object({
-            include: Type.Optional(Type.String()),
-        }),
-    })
-    .handler(async (c) => {
-        const { params, query } = await c.data();
-        //      ^? { params: { id: string }, query: { include?: string } }
-
-        const user = await findOne(users, { id: params.id });
-        //    ^? User | null
-
-        return user;
-        //     ^? Response type inferred from return value
-    });
-
-// 3. Router Type Export
-// src/server/router.ts
 export const appRouter = defineRouter({
-    getUser,
-    // ... other routes
-});
-
-export type AppRouter = typeof appRouter;
-//   ^? Router<{ getUser: RouteDef<..., ...>, ... }>
-
-// 4. Client API Call (Next.js)
-// app/users/[id]/page.tsx
-import { api } from '@spfn/core/nextjs/server';
-
-const user = await api.getUser
-    .params({ id: '123' })    // Type-checked: must be { id: string }
-    .query({ include: 'posts' }) // Type-checked: { include?: string }
-    .call();
-//  ^? User (inferred from server handler return type)
-
-// Full type inference chain:
-// User type → RouteDef → Router → Client API → return type
-```
-
-### Type Inference Utilities
-
-```typescript
-// Extract input type from route
-type GetUserInput = InferRouteInput<typeof getUser>;
-//   ^? { params: { id: string }; query: { include?: string } }
-
-// Extract output type from route
-type GetUserOutput = InferRouteOutput<typeof getUser>;
-//   ^? User
-
-// Client type inference
-type ApiClient<TRouter> = {
-    [K in keyof TRouter['routes']]: TRouter['routes'][K] extends RouteDef<infer TInput, infer TOutput>
-        ? RouteClient<TInput, TOutput>
-        : never;
-};
-```
-
----
-
-## Integration Points
-
-### 1. Server ↔ Database: Transaction Context
-
-**Mechanism**: AsyncLocalStorage propagates transaction across async calls
-
-```typescript
-// Route handler
-app.bind(createPostContract, [Transactional()], async (c) => {
-    // AsyncLocalStorage stores transaction
-    const post = await create(posts, { title: 'Hello' });
-
-    // Same transaction is used automatically
-    const tag = await create(tags, { postId: post.id, name: 'news' });
-
-    // Auto-commit on success, auto-rollback on error
-    return c.json(post);
-});
-```
-
-**Why**: No need to pass transaction object through function calls
-
----
-
-### 2. Server ↔ Client: Type Inference
-
-**Mechanism**: `typeof appRouter` captures all route types
-
-```typescript
-// Server: Export router type
-export const appRouter = defineRouter({ getUser, createUser });
-export type AppRouter = typeof appRouter;
-
-// Client: Import type (not value!)
-import type { AppRouter } from '@/server/router';
-const api = createApi<AppRouter>(/* ... */);
-
-// Automatic type inference for all routes
-const user = await api.getUser.params({ id: '123' }).call();
-//    ^? Full type safety without manual type definitions
-```
-
-**Why**: Single source of truth (server) → client types automatically sync
-
----
-
-### 3. Next.js ↔ SPFN: RPC Proxy
-
-**Mechanism**: Next.js API Route resolves routeName and forwards to SPFN server
-
-```typescript
-// app/api/rpc/[routeName]/route.ts
-import { appRouter } from '@/server/router';
-import { createRpcProxy } from '@spfn/core/nextjs/server';
-
-export const { GET, POST } = createRpcProxy({ router: appRouter });
-
-// Automatically:
-// 1. Resolves routeName → method/path from router
-// 2. Forwards to http://localhost:8790/{resolved-path}
-// 3. Applies interceptors (auth, cookies)
-// 4. Returns NextResponse
-```
-
-**Why**:
-- HttpOnly cookie support (browser → Next.js includes cookies automatically)
-- Security (SPFN_API_URL hidden from browser)
-- No CORS (same-origin requests)
-- No metadata codegen required
-
----
-
-### 4. Packages: Registry System
-
-**Mechanism**: Packages register interceptors on import
-
-```typescript
-// @spfn/auth package
-import { registerInterceptors } from '@spfn/core/nextjs/server';
-
-registerInterceptors('auth', [
-    {
-        pathPattern: '/_auth/*',
-        response: async (ctx, next) => {
-            // Set session cookie
-            ctx.setCookies.push({ name: 'session', value: token });
-            await next();
-        },
-    },
-]);
-
-// App: Auto-discovery
-import '@spfn/auth/adapters/nextjs'; // Registers interceptors
-export { GET, POST } from '@spfn/core/nextjs/server'; // Uses registered interceptors
-```
-
-**Why**: Zero-config integration for plugin packages
-
----
-
-## Design Decisions
-
-### 1. Why tRPC-Style API over REST Client?
-
-**Decision**: Method chaining with `.params().query().call()`
-
-**Reasons**:
-- Better DX: Fluent API guides usage
-- Type safety: Each method is type-checked
-- Flexibility: Optional parameters can be omitted
-- Discovery: IDE autocomplete shows available options
-
-**Example**:
-```typescript
-// tRPC-style (SPFN)
-const user = await api.getUser
-    .params({ id: '123' })
-    .query({ include: 'posts' })
-    .call();
-
-// vs Traditional REST client
-const user = await client.get('/users/123', {
-    params: { include: 'posts' } // No type safety
-});
-```
-
----
-
-### 2. Why API Route Proxy Pattern?
-
-**Decision**: Next.js API Route forwards to SPFN server
-
-**Reasons**:
-- **HttpOnly Cookies**: Browser automatically sends cookies to same-origin
-- **Security**: SPFN API URL hidden from browser
-- **No CORS**: Same-origin requests (localhost:3000 → localhost:3000)
-- **Unified Path**: Server Components and Client Components use same API
-
-**Alternative Rejected**: Direct calls from browser to SPFN server
-- Would expose SPFN_API_URL to browser
-- CORS configuration required
-- Cannot use HttpOnly cookies from browser
-
----
-
-### 3. Why define-route over File-Based Routing?
-
-**Decision**: Explicit route imports with `defineRouter()`
-
-**Reasons**:
-- **Explicit Imports**: Better tree-shaking, clear dependencies
-- **Type Safety**: `typeof appRouter` captures all routes
-- **Flexibility**: Routes can be defined anywhere
-- **No Magic**: No file system scanning at runtime
-
-**Alternative Rejected**: File-based routing (like Next.js)
-- Runtime file system scanning
-- Implicit route registration
-- Harder to trace route definitions
-- Less flexible for monorepo setups
-
-**Migration Path**: Deprecated contract-based and file-based routing systems
-
----
-
-### 4. Why AsyncLocalStorage for Transactions?
-
-**Decision**: Transaction propagation without explicit passing
-
-**Reasons**:
-- **Clean API**: No need to pass `tx` object through all functions
-- **Automatic**: Works across async boundaries
-- **Safe**: Isolated per request
-- **Compatible**: Works with existing code
-
-**Example**:
-```typescript
-// With AsyncLocalStorage (SPFN)
-async function createPostWithTags(data) {
-    const post = await create(posts, data);
-    const tags = await createMany(tags, data.tags.map(t => ({ postId: post.id, ...t })));
-    // Same transaction automatically
-}
-
-// vs Explicit transaction passing
-async function createPostWithTags(tx, data) {
-    const post = await tx.insert(posts).values(data);
-    const tags = await tx.insert(tags).values(...);
-    // Must pass tx everywhere
-}
-```
-
----
-
-### 5. Why Hono over Express?
-
-**Decision**: Hono as the underlying web framework
-
-**Reasons**:
-- **TypeScript First**: Better type inference
-- **Performance**: Faster than Express
-- **Modern**: Built for Edge/Serverless
-- **Lightweight**: Smaller bundle size
-
----
-
-### 6. Why TypeBox over Zod?
-
-**Decision**: TypeBox for schema validation
-
-**Reasons**:
-- **JSON Schema**: Standard, interoperable
-- **Performance**: Faster validation (JIT compilation)
-- **OpenAPI**: Easy OpenAPI generation
-- **Smaller**: Smaller bundle size
-
-**Note**: Both are supported, TypeBox is the default
-
----
-
-## Extension Points
-
-### 1. Custom Middleware
-
-Add global or route-specific middleware:
-
-```typescript
-// server.config.ts
-import { defineServerConfig } from '@spfn/core/server';
-import { defineMiddleware } from '@spfn/core/route';
-
-const rateLimitMiddleware = defineMiddleware('rateLimit', async (c, next) => {
-    const ip = c.req.header('x-forwarded-for');
-    if (await isRateLimited(ip)) {
-        return c.json({ error: 'Rate limit exceeded' }, 429);
-    }
-    await next();
-});
-
-export default defineServerConfig()
-    .middlewares([rateLimitMiddleware])
-    .build();
-
-// Route can skip middleware
-export const publicRoute = route.get('/public')
-    .middleware({ skip: ['rateLimit'] })
-    .handler(async (c) => { ... });
-```
-
----
-
-### 2. Custom Interceptors
-
-Add request/response interceptors:
-
-```typescript
-// app/api/rpc/[routeName]/route.ts
-import { appRouter } from '@/server/router';
-import { createRpcProxy } from '@spfn/core/nextjs/server';
+    getUser: route.get('/users/:id')
+        .input({ params: Type.Object({ id: Type.String() }) })
+        .handler(async (c) =>
+        {
+            const { params } = await c.data();   // params.id: string
+            return { id: params.id, name: 'John' };   // return type inferred
+        }),
 
-export const { GET, POST } = createRpcProxy({
-    router: appRouter,
-    interceptors: [
+    createUser: route.post('/users')
+        .input({ body: Type.Object({ name: Type.String() }) })
+        .use([Transactional()])                  // auto commit/rollback
+        .handler(async (c) =>
         {
-            pathPattern: '/admin/*',
-            request: async (ctx, next) => {
-                // Check admin role
-                const isAdmin = await checkAdminRole(ctx.cookies);
-                if (!isAdmin) {
-                    throw new Error('Unauthorized');
-                }
-                await next();
-            },
-        },
-    ],
+            const { body } = await c.data();
+            return { id: '2', name: body.name };
+        }),
 });
-```
-
----
-
-### 3. Plugin System
-
-Create SPFN packages with auto-discovery:
-
-```typescript
-// @yourcompany/spfn-analytics package
-import { registerInterceptors } from '@spfn/core/nextjs/server';
-
-registerInterceptors('analytics', [
-    {
-        pathPattern: '*',
-        response: async (ctx, next) => {
-            await analytics.track({
-                path: ctx.path,
-                status: ctx.response.status,
-                duration: Date.now() - ctx.metadata.startTime,
-            });
-            await next();
-        },
-    },
-]);
-
-// App: Auto-discovery
-import '@yourcompany/spfn-analytics/adapters/nextjs';
-export { GET, POST } from '@spfn/core/nextjs/server';
-```
-
----
-
-### 4. Custom Database Helpers
-
-Extend database layer with domain-specific functions:
-
-```typescript
-// src/server/repositories/users.repository.ts
-import { findOne, create } from '@spfn/core/db';
-import { users } from '../entities/users';
-
-export async function findUserByEmail(email: string) {
-    return findOne(users, { email });
-}
-
-export async function createUserWithProfile(data) {
-    const user = await create(users, data.user);
-    const profile = await create(profiles, {
-        ...data.profile,
-        userId: user.id,
-    });
-    return { user, profile };
-}
-```
-
----
-
-## Migration Guides
-
-### From Contract-Based to define-route
-
-**Before** (Deprecated):
-```typescript
-// contract.ts
-export const getUserContract = {
-    method: 'GET' as const,
-    path: '/users/:id',
-    params: Type.Object({ id: Type.String() }),
-    response: Type.Object({ id: Type.String(), name: Type.String() }),
-} as const satisfies RouteContract;
-
-// route.ts
-import { createApp } from '@spfn/core/route';
-const app = createApp();
-app.bind(getUserContract, async (c) => { ... });
-export default app;
-```
 
-**After** (Current):
-```typescript
-// routes/users.ts
-import { route } from '@spfn/core/route';
-
-export const getUser = route.get('/users/:id')
-    .input({
-        params: Type.Object({ id: Type.String() }),
-    })
-    .handler(async (c) => {
-        const { params } = await c.data();
-        return { id: params.id, name: 'John' };
-    });
-
-// router.ts
-import { defineRouter } from '@spfn/core/route';
-export const appRouter = defineRouter({ getUser });
 export type AppRouter = typeof appRouter;
 ```
 
-**Benefits**:
-- Better type inference
-- Explicit imports (tree-shaking)
-- No separate contract files
-
----
-
-### From File-Based to define-route
-
-**Before** (Deprecated):
 ```typescript
-// routes/users/[id].ts
-export default async function handler(c) { ... }
+// server/index.ts — ③
+import { defineServerConfig, startServer } from '@spfn/core/server';
+import { appRouter } from './router';
 
-// Automatic file system scanning
+export default defineServerConfig().port(8790).routes(appRouter).build();
+await startServer();   // Hono on :8790
 ```
 
-**After** (Current):
 ```typescript
-// routes/users.ts
-export const getUser = route.get('/users/:id')...
-
-// router.ts
-export const appRouter = defineRouter({ getUser });
-
-// server.config.ts
-export default defineServerConfig()
-    .routes(appRouter)
-    .build();
-```
-
-**Benefits**:
-- Explicit route registration
-- Better IDE support
-- No runtime file system scanning
-
----
-
-### From ContractClient to tRPC-Style API
-
-**Before** (Old Client):
-```typescript
-import { ContractClient } from '@spfn/core/client';
-import { getUserContract } from '@/contracts/users';
-
-const client = new ContractClient({ baseUrl: 'http://localhost:8790' });
-const user = await client.call(getUserContract, {
-    params: { id: '123' },
-});
-```
-
-**After** (Current):
-```typescript
-import { api } from '@spfn/core/nextjs/server';
-
-const user = await api.getUser
-    .params({ id: '123' })
-    .call();
-```
-
-**Benefits**:
-- tRPC-style DX
-- Method chaining
-- Better type inference
-- Automatic cookie handling
-
----
-
-## Module Exports
-
-### Main Server Exports
-
-```typescript
-import {
-    startServer,
-    createServer,
-    defineServerConfig,
-} from '@spfn/core';
-```
-
-### Route System
-
-```typescript
-import {
-    route,
-    defineRouter,
-} from '@spfn/core/route';
-
-import type {
-    RouteDef,
-    Router,
-    RouteInput,
-} from '@spfn/core/route';
-```
-
-### Database System
-
-```typescript
-import {
-    getDatabase,
-    findOne,
-    findMany,
-    create,
-    createMany,
-    updateOne,
-    updateMany,
-    deleteOne,
-    deleteMany,
-    count,
-} from '@spfn/core/db';
-
-import {
-    Transactional,
-    getTransaction,
-    runWithTransaction,
-} from '@spfn/core/db';
-```
-
-### Client System
-
-```typescript
-// Client-safe exports (works in Client Components)
-import {
-    createApi,
-    ApiError,
-} from '@spfn/core/nextjs';
-
-// Server-only exports (API Routes)
-import {
-    createRpcProxy,
-    registerInterceptors,
-} from '@spfn/core/nextjs/server';
-```
-
-### Error System
-
-```typescript
-import {
-    ApiError,
-    ValidationError,
-    NotFoundError,
-    ConflictError,
-    UnauthorizedError,
-} from '@spfn/core/errors';
-```
-
-### Logger System
-
-```typescript
-import { logger } from '@spfn/core';
-```
-
-### Cache System
-
-```typescript
-import {
-    initCache,
-    getCache,
-    getCacheRead,
-    isCacheDisabled,
-    closeCache,
-} from '@spfn/core/cache';
-```
-
-### Environment System
-
-```typescript
-import {
-    defineEnvSchema,
-    createEnvRegistry,
-    envString,
-    envNumber,
-    envBoolean,
-    envEnum,
-} from '@spfn/core/env';
-```
-
-### Configuration System
-
-```typescript
-import { env, envSchema } from '@spfn/core/config';
-```
-
-### Job System
-
-```typescript
-import {
-    job,
-    defineJobRouter,
-    registerJobs,
-    initBoss,
-    getBoss,
-    stopBoss,
-} from '@spfn/core/job';
-
-import type {
-    JobDef,
-    JobRouter,
-    JobOptions,
-    BossOptions,
-    InferJobInput,
-} from '@spfn/core/job';
-```
-
-### Event System
-
-```typescript
-import { defineEvent } from '@spfn/core/event';
-
-import type {
-    EventDef,
-    EventHandler,
-    InferEventPayload,
-    PubSubCache,
-} from '@spfn/core/event';
-```
-
----
-
-## Quick Reference
-
-### Environment Variables
-
-```bash
-# Database (required)
-DATABASE_URL=postgresql://user:pass@localhost:5432/db
-
-# Database Read Replica (optional)
-DATABASE_READ_URL=postgresql://user:pass@replica:5432/db
-
-# Cache - Valkey/Redis (optional)
-CACHE_URL=redis://localhost:6379
-CACHE_WRITE_URL=redis://master:6379
-CACHE_READ_URL=redis://replica:6379
-
-# Next.js App URL (for Server Components calling API Routes)
-SPFN_APP_URL=http://localhost:3000
-
-# SPFN API Server URL (for API Route Proxy)
-SPFN_API_URL=http://localhost:8790
-
-# Server
-PORT=8790
-HOST=localhost
-NODE_ENV=development
-
-# Server Timeouts (optional, milliseconds)
-SERVER_TIMEOUT=120000
-SERVER_KEEPALIVE_TIMEOUT=65000
-SERVER_HEADERS_TIMEOUT=60000
-SHUTDOWN_TIMEOUT=30000
-
-# Logger (optional)
-LOGGER_ADAPTER=pino
-LOGGER_FILE_ENABLED=true
-LOG_DIR=/var/log/myapp
-```
-
----
-
-### Basic Setup
-
-**1. Install**
-```bash
-npm install @spfn/core hono drizzle-orm postgres @sinclair/typebox
-```
-
-**2. Define Routes**
-```typescript
-// src/server/routes/users.ts
-export const getUser = route.get('/users/:id')
-    .input({ params: Type.Object({ id: Type.String() }) })
-    .handler(async (c) => {
-        const { params } = await c.data();
-        return { id: params.id, name: 'John' };
-    });
-```
-
-**3. Create Router**
-```typescript
-// src/server/router.ts
-export const appRouter = defineRouter({ getUser });
-export type AppRouter = typeof appRouter;
-```
-
-**4. Configure Server**
-```typescript
-// src/server/server.config.ts
-export default defineServerConfig()
-    .port(8790)
-    .routes(appRouter)
-    .build();
-```
-
-**5. Create RPC Proxy (Next.js)**
-```typescript
-// app/api/rpc/[routeName]/route.ts
-import { appRouter } from '@/server/router';
+// app/api/rpc/[routeName]/route.ts — ⑤  (server-only)
 import { createRpcProxy } from '@spfn/core/nextjs/server';
+import { routeMap } from '@/generated/route-map';   // ④ codegen output
 
-export const { GET, POST } = createRpcProxy({ router: appRouter });
+export const { GET, POST } = createRpcProxy({ routeMap });
 ```
 
-**6. Use Client**
 ```typescript
-// app/users/[id]/page.tsx
+// lib/api.ts — ⑥  (client-safe; no codegen)
 import { createApi } from '@spfn/core/nextjs';
 import type { AppRouter } from '@/server/router';
 
-const api = createApi<AppRouter>();
-const user = await api.getUser.call({ params: { id: '123' } });
-```
-
----
-
-## Documentation
-
-### Technical Architecture
-- [Route System](./src/route/README.md) - define-route system, type inference
-- [Server System](./src/server/README.md) - Configuration, middleware pipeline, lifecycle
-- [Database System](./src/db/README.md) - Helper functions, transactions, schema helpers
-- [Client System](./src/nextjs/README.md) - tRPC-style API, TypedProxy, interceptors
-
-### Guides
-- [Transaction Management](./src/db/docs/transactions.md)
-- [Error Handling](./src/errors/README.md)
-- [Logger](./src/logger/README.md)
-- [Cache](./src/cache/README.md)
-- [Middleware](./src/middleware/README.md)
-- [Code Generation](./src/codegen/README.md)
-
----
-
-## Requirements
-
-- Node.js >= 18
-- Next.js 15+ with App Router (when using client integration)
-- PostgreSQL
-- Valkey/Redis (optional)
-- TypeScript >= 5.0
-
----
-
-## Testing
-
-```bash
-npm test                    # Run all tests
-npm test -- route           # Run route tests only
-npm test -- --coverage      # With coverage
-```
-
-**Test Coverage**: 650+ tests across all modules
-
----
-
-## License
-
-MIT
-
----
-
-Part of the [Superfunction Framework](https://github.com/spfn/spfn)
+export const api = createApi<AppRouter>();
+
+// anywhere (RSC / client / server action):
+const user = await api.getUser.call({ params: { id: '123' } });    // typed { id, name }
+const made = await api.createUser.call({ body: { name: 'A' } });
+```
+
+## Pitfalls
+
+- **No root barrel.** `import … from '@spfn/core'` does not resolve. Import from a subpath
+  (`@spfn/core/route`, `@spfn/core/db`, …). The list above *is* the complete public surface.
+- **Use `@spfn/core/nextjs` for the client, not `@spfn/core/client`.** `package.json` still lists a
+  `./client` export, but the build does not emit it (no `src/client`; the tsup `client` entry is
+  disabled). `createApi` / `ApiError` and all client types ship from **`@spfn/core/nextjs`**. Treat
+  `@spfn/core/client` as non-functional.
+- **Client vs. server boundary is load-bearing.** `@spfn/core/nextjs/server` pulls in
+  `next/headers` + `next/server`; never import it from a Client Component. `@spfn/core/env/loader`,
+  `@spfn/core/event/sse`, `@spfn/core/event/ws` are server-only (`node:fs` / Hono / `node:crypto`).
+  Client code uses the `*/client` and isomorphic entry points only.
+- **`db/manager`, `db/schema`, `db/transaction` are not package subpaths.** Importing
+  `@spfn/core/db/transaction` fails to resolve — import those symbols from `@spfn/core/db`.
+- **The client needs no codegen; the proxy does.** `createApi<AppRouter>()` is metadata-free and
+  driven by the `AppRouter` *type*. The generated `routeMap` is consumed by `createRpcProxy`. A
+  `routeName` missing from the merged `routeMap` is a **proxy 404**, not a backend 404 — re-run
+  codegen after adding routes.
+- **The proxy decides the real HTTP method.** The client only sends GET/POST to `/api/rpc/...`; a
+  PUT/PATCH/DELETE route still works because the backend method comes from `routeMap[routeName]`.
+- **Cache/event/job degrade or depend on optional deps.** `@spfn/core/cache` runs disabled (getters
+  return `undefined`) without `CACHE_*` config or `ioredis`; WebSocket events need the optional `ws`
+  dep. Don't assume they throw.
+
+## Related packages
+
+Other SPFN packages build on `@spfn/core`:
+
+- [`@spfn/auth`](../auth/README.md) — auth/session; exports `authRouteMap` and auto-registers proxy
+  interceptors (merge its route map into `createRpcProxy`).
+- `@spfn/cms`, `@spfn/workflow`, `@spfn/notification`, `@spfn/monitor`, `@spfn/cli`
+  — see each package's README under `packages/`.