@mantajs/core 0.2.0-beta.0 → 0.2.0-beta.10

package/docs/01-getting-started.md

@@ -3,6 +3,7 @@
 ## Prerequisites
 
 - Node.js 18+ (AsyncLocalStorage required)
+- Manta packages require Node.js 20+ in published projects
 - PostgreSQL (local or cloud — Neon, Supabase, etc.)
 - pnpm
 
@@ -26,8 +27,11 @@ my-app/
 │   ├── subscribers/
 │   ├── jobs/
 │   ├── links/
-│   └── contexts/
+│   └── spa/
 ├── drizzle/migrations/
+├── AGENT.md
+├── .codex/skills/mantajs/
+├── .claude/skills/mantajs/
 └── tsconfig.json
 ```
 
@@ -86,7 +90,7 @@ This gives you 8 CRUD methods for free + the custom `publish` method. No imports
 
 ## Step 4 — Define a command
 
-Create `src/commands/create-post.ts`:
+Create `src/commands/admin/create-post.ts`:
 
 ```typescript
 export default defineCommand({
@@ -131,21 +135,14 @@ export default defineSubscriber({
 })
 ```
 
-## Step 6 — Define a context
+## Step 6 — Expose reads for the admin context
 
-Create `src/contexts/admin.ts`:
+In Manta V2, the context is the folder name under `src/commands/{context}` and `src/queries/{context}`. `src/commands/admin/create-post.ts` creates `POST /api/admin/command/create-post`.
+
+Create `src/queries/admin/graph.ts` so the dashboard and SDK can read blog data:
 
 ```typescript
-export default defineContext({
-  name: 'admin',
-  basePath: '/api/admin',
-  actors: ['admin'],
-  modules: {
-    blog: { expose: '*' },
-  },
-  commands: ['create-post'],
-  ai: { enabled: true },
-})
+export default defineQueryGraph('*')
 ```
 
 ## Step 7 — Generate migrations and run
@@ -163,14 +160,13 @@ manta dev
 
 Output:
 ```
-  [codegen] .manta/types/ (1 modules, 3 events)
+  [codegen] .manta/generated.d.ts (1 entities, 1 commands, 0 agents, 1 actors, 3 events)
   Module: blog (Post) ✓
   Subscriber: post.created → post-created ✓
-  Command: create-post ✓
-  Context: admin → /api/admin ✓
+  Command: admin/create-post ✓
 
   Server running at http://localhost:9000
-  API docs at http://localhost:9000/api/docs
+  OpenAPI at http://localhost:9000/api/openapi.json
 ```
 
 ## Step 9 — Test it
@@ -188,37 +184,38 @@ curl -X POST http://localhost:9000/api/admin/command/create-post \
   }'
 ```
 
-Query posts:
+Query posts through the graph:
 ```bash
-curl -X POST http://localhost:9000/api/admin/query/blog \
+curl -X POST http://localhost:9000/api/admin/graph \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <jwt>" \
-  -d '{"filters": {"status": "published"}}'
+  -d '{"entity":"post","filters":{"status":"published"}}'
 ```
 
 View API docs:
 ```
-open http://localhost:9000/api/docs
+open http://localhost:9000/api/openapi.json
 ```
 
 ## What happened automatically
 
-From your 4 files (model, service, command, context), Manta generated:
+From your files (model, service, command, query graph), Manta generated:
 
 - PostgreSQL table `posts` with all columns + indexes
 - 8 CRUD methods on `app.modules.blog`
 - HTTP endpoint `POST /api/admin/command/create-post`
-- HTTP endpoint `POST /api/admin/query/blog`
+- HTTP endpoint `POST /api/admin/graph`
 - AI tool schema for `create-post` (Zod → JSON Schema)
 - OpenAPI spec with full schema documentation
-- TypeScript types for autocomplete (`.manta/types/`)
+- TypeScript types for autocomplete (`.manta/generated.d.ts`)
 - Event wiring for `post.created` subscriber
 - Compensation logic (if create-post fails, the post is deleted)
+- Codex and Claude skills pointing to `node_modules/@mantajs/core/docs/`
 
 ## Next steps
 
 - Add more modules (see [Models](./02-models.md) and [Services](./03-services.md))
-- Add cross-module relations (see [Links](./07-links.md))
-- Add scheduled tasks (see [Events](./06-events.md))
-- Expose a storefront API (see [Contexts](./08-contexts.md))
-- Deploy to production (see [Config](./09-config.md))
+- Add cross-module relations (see [Links](./08-links.md))
+- Add scheduled tasks (see [Events](./07-events.md))
+- Expose a storefront API with `src/commands/store/` and `src/queries/store/` (see [Queries](./06-queries.md))
+- Deploy to production (see [Config](./11-config.md))

package/docs/03-services.md

@@ -4,7 +4,7 @@
 
 **1 entity = 1 service. Always.**
 
-A service defines the mutations (writes) for **one** entity. The repository it receives is typed for that entity only. A service cannot mutate another entity — that's a command.
+A service defines the mutations (writes) for **one** entity. It receives the generated repository for compensated CRUD and the schema-aware Drizzle client for explicit SQL-shaped writes. A service should own one entity's invariants; if you need to coordinate multiple entities, write a command that orchestrates the services or use a transaction deliberately.
 
 A module can have multiple entities, and therefore multiple services. If you need to mutate two entities together, write a module command that orchestrates them.
 
@@ -13,23 +13,26 @@ If you don't have an entity, you don't have a module. Use `app.infra.*` for infr
 ## defineService()
 
 ```typescript
-export default defineService('product', ({ db, log }) => ({
+import { eq } from 'drizzle-orm'
+
+export default defineService('product', ({ db, drizzle, schema, log }) => ({
   activate: async (id: string) => {
-    await db.update({ id, status: 'active' })
+    await drizzle.update(schema.products).set({ status: 'active' }).where(eq(schema.products.id, id))
     log.info(`Product ${id} activated`)
   },
 
   archive: async (id: string) => {
+    // Generated repository remains useful for simple compensated CRUD.
     await db.update({ id, status: 'archived' })
     log.info(`Product ${id} archived`)
   },
 }))
 ```
 
-**Signature:** `defineService(entityName: string, factory: ({ db, log }) => Methods, options?)`
+**Signature:** `defineService(entityName: string, factory: ({ db, drizzle, schema, database, sql, log }) => Methods, options?)`
 
 - `entityName` — Entity name as a string (autocompletes from codegen)
-- `factory` — Receives `{ db, log }` (typed repository + logger), returns methods
+- `factory` — Receives the typed repository, Drizzle runtime, generated schema, database adapter, SQL helper, and logger
 - `options.publicMethods` — (optional) Array of method names visible to other modules
 
 No imports needed — `defineService` is a global. Compensation is automatic — the repo snapshots state before every mutation. No `service.method()` wrapper needed.
@@ -67,6 +70,21 @@ activate: async (id: string) => {
 
 **How it works:** The framework auto-snapshots repository state before every mutation. In a workflow, if step 3 fails, steps 1 and 2 are automatically rolled back using the snapshots. You don't write compensation logic — the framework handles it.
 
+## Data APIs in services
+
+Use `drizzle`, `schema`, and `sql` when the mutation is easier to express as SQL/Drizzle, needs custom predicates, bulk operations, joins, or transaction-shaped code.
+
+Use `db` for simple generated CRUD that should participate in the repository snapshot compensation path.
+
+```typescript
+const products = schema.products
+
+await drizzle
+  .update(products)
+  .set({ status: 'archived', updated_at: new Date() })
+  .where(eq(products.id, id))
+```
+
 ## TypedRepository — the db API
 
 The `db` parameter is a `TypedRepository<T>` where `T` is the inferred entity type:

package/docs/04-users.md

@@ -63,7 +63,7 @@ All on `/api/admin/`:
 | Route | Method | Auth | Description |
 |-------|--------|------|-------------|
 | `/login` | POST | Public | Email/password → JWT (`{ id, type: 'admin' }`) |
-| `/logout` | DELETE | Public | Blacklists token in cache |
+| `/logout` | DELETE | Public | Clears auth cookies/local credentials and attempts server-side token revocation |
 | `/refresh` | POST | Public | Exchange refresh token for new JWT |
 | `/forgot-password` | POST | Public | Generates reset token |
 | `/reset-password` | POST | Public | Validates token + resets password |
@@ -80,8 +80,52 @@ All on `/api/admin/`:
 
 All `/api/admin/*` routes (except public auth routes):
 1. Verify JWT Bearer token
-2. Check `auth.type === 'admin'`
-3. Reject with 401/403 if invalid
+2. Reject tokens present in `auth:blacklist:{auth_identity_id}` when a durable cache is reachable
+3. Check `auth.type === 'admin'`
+4. Reject with 401/403 if invalid
+
+### Logout and token revocation
+
+`DELETE /api/{context}/logout` always clears framework auth cookies and returns a successful logout response for the browser. If a Bearer/access token is present, Manta also writes `auth:blacklist:{auth_identity_id}` to `ICachePort` for 30 days.
+
+Response shape:
+
+```json
+{ "success": true, "revoked": true }
+```
+
+If the cache backend is temporarily unreachable, the route still clears cookies and returns:
+
+```json
+{ "success": true, "revoked": false, "warning": "TOKEN_REVOCATION_FAILED" }
+```
+
+In that degraded case, a JWT already issued remains valid until its normal expiry unless the client discards it. Production deployments that use `defineUserModel()` therefore need a durable, reachable `ICachePort`.
+
+Supported durable cache choices:
+
+```typescript
+// Default Vercel/Cloudflare-style production cache
+adapters: {
+  ICachePort: {
+    adapter: '@mantajs/adapter-cache-upstash',
+    options: {
+      url: process.env.UPSTASH_REDIS_REST_URL,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN,
+    },
+  },
+}
+```
+
+```typescript
+// Durable Postgres fallback, reusing the configured IDatabasePort connection
+adapters: {
+  ICachePort: {
+    adapter: '@mantajs/adapter-database-pg/cache',
+    options: { tableName: 'manta_cache' },
+  },
+}
+```
 
 ### Dev seed
 

package/docs/05-commands.md

@@ -95,7 +95,7 @@ await step.service.inventory.adjustQuantity(inventoryId, -1)
 Every `step.service.*` call is:
 - **Checkpointed** — saved to storage, skipped on retry
 - **Compensated** — rollback registered in LIFO order
-- **Typed** — autocomplete from codegen (`.manta/types/`)
+- **Typed** — autocomplete from codegen (`.manta/generated.d.ts`)
 
 ### step.service.MODULE.link — Create links
 

package/docs/06-queries.md

@@ -1,14 +1,17 @@
-# Queries — defineQuery() & defineQueryGraph()
+# Queries — Drizzle-first defineQuery()
 
-Queries are the CQRS read side. They expose data as GET endpoints. Two primitives:
+Queries are the CQRS read side. They expose data as GET endpoints.
 
-- `defineQuery()` — named query with custom handler (specific reads)
-- `defineQueryGraph()` — expose the query graph to frontend (flexible reads)
+- `defineQuery()` is the primary application API. New code should query with the schema-aware Drizzle client.
+- `defineQueryGraph()` is reserved for generated/admin/dynamic surfaces that need entity-level browsing.
+
+Manta does not try to replace SQL. `defineModel()` generates the Drizzle schema and migrations; `defineQuery()` gives handlers the Drizzle client, generated schema, tagged SQL helper, auth context, logging, and request headers.
 
 ## defineQuery()
 
 ```typescript
 // src/queries/admin/list-products.ts
+import { eq } from 'drizzle-orm'
 import { z } from 'zod'
 
 export default defineQuery({
@@ -18,12 +21,19 @@ export default defineQuery({
     status: z.string().optional(),
     ...listParams(),
   }),
-  handler: async (input, { query, log, auth, headers }) => {
-    return query.graph({
-      entity: 'product',
-      filters: input.status ? { status: input.status } : undefined,
-      pagination: { take: input.limit, skip: input.offset },
-    })
+  handler: async (input, { drizzle, schema, sql }) => {
+    const products = schema.products
+    return drizzle
+      .select({
+        id: products.id,
+        title: products.title,
+        status: products.status,
+        totalVariants: sql<number>`count(*) over()::int`,
+      })
+      .from(products)
+      .where(input.status ? eq(products.status, input.status) : undefined)
+      .limit(input.limit)
+      .offset(input.offset)
   },
 })
 ```
@@ -43,14 +53,21 @@ defineQuery({
 
 ```typescript
 {
-  query: QueryService,                          // query.graph() for cross-module joins
+  drizzle: unknown,                             // schema-aware Drizzle client
+  db: unknown,                                  // alias for drizzle
+  schema: Record<string, unknown>,              // generated Drizzle tables
+  sql: typeof import('drizzle-orm').sql,        // tagged SQL helper
+  database: IDatabasePort,                      // raw SQL, pool, transactions
+  query: QueryService,                          // generated/admin query graph
   log: ILoggerPort,                             // Structured logging
   auth: AuthContext | null,                     // Authenticated user
   headers: Record<string, string | undefined>,  // Raw request headers
 }
 ```
 
-**No `app` access** — queries are forced to use `query.graph()` for reads. This ensures consistent access control.
+Prefer Drizzle for all application reads, including simple lists, dashboards, analytics, counts, search, and joins. Use `sql` fragments when a PostgreSQL feature is clearer than query-builder syntax.
+
+`query.graph()` remains available for generated admin screens and dynamic entity browsing. It must not be used to hide analytical work in JavaScript. If a query needs `COUNT`, `SUM`, `GROUP BY`, `FILTER`, CTEs, window functions, full-text search, or dashboard KPIs, write it as Drizzle/SQL in `defineQuery()`.
 
 ### Routing
 
@@ -65,6 +82,18 @@ Query parameters are passed as URL query string:
 GET /api/admin/list-products?status=active&limit=10&offset=0
 ```
 
+### Serverless fast routes
+
+For serverless and worker builds, Manta generates route-level functions for compatible `defineQuery()` files. These fast routes do not import `bootstrapApp()`, jobs, workflows, AI, command registries, or the catch-all Manta adapter.
+
+Fast routes are generated when:
+
+- the project uses filesystem V2 contexts (`src/queries/{context}`), not legacy `src/contexts/*.ts`
+- the file exports `defineQuery()`, not `defineQueryGraph()`
+- the query does not call `query.graph()`, `query.graphAndCount()`, `query.index()`, or `query.gql()`
+
+Pure synthetic queries do not initialize the database or generated schema. Queries that reference `drizzle`, `db`, `schema`, or `database` initialize only the DB adapter and generated Drizzle schema needed by the handler.
+
 ### Input helpers
 
 ```typescript
@@ -85,22 +114,24 @@ z.object({
 ### Auth in queries
 
 ```typescript
-handler: async (input, { query, auth }) => {
+handler: async (input, { drizzle, schema, auth }) => {
   // auth.id — user ID
   // auth.type — context ('admin', 'customer')
   // auth.email — user email
 
   // Example: only return MY orders
-  return query.graph({
-    entity: 'order',
-    filters: { customer_id: auth!.id },
-  })
+  return drizzle
+    .select()
+    .from(schema.orders)
+    .where(eq(schema.orders.customer_id, auth!.id))
 }
 ```
 
 ## defineQueryGraph()
 
-Exposes the query graph to the frontend. The frontend can compose arbitrary queries.
+Exposes the query graph to the frontend. The frontend can compose entity browsing queries for generated/admin screens.
+
+Do not use the graph as the main application query language. It is intentionally less expressive than SQL. Complex reads belong in `defineQuery()` with Drizzle.
 
 ### Wildcard — full access (admin/AI)
 
@@ -163,11 +194,11 @@ POST /api/admin/graph
 
 | Use case | Primitive | Why |
 |----------|-----------|-----|
-| Admin dashboard | `defineQueryGraph('*')` | Admin sees everything, AI needs full access |
-| Storefront public catalog | `defineQueryGraph({ product: true })` | Frontend composes queries freely, scoped |
-| Storefront orders | `defineQuery` or scoped graph | Need row-level filtering by customer |
-| Complex aggregation | `defineQuery` | Custom handler with business logic |
-| API for third parties | `defineQuery` | Fixed contract, no graph exposure |
+| Generated admin entity table | `defineQueryGraph('*')` | Dynamic browsing over known entities |
+| Storefront catalog | `defineQuery` | Stable contract, optimized Drizzle query |
+| Customer orders | `defineQuery` | Auth-scoped SQL with explicit filters |
+| Dashboard / analytics | `defineQuery` | Aggregations run in Postgres |
+| Third-party API | `defineQuery` | Fixed contract, no graph exposure |
 
 ## extendQueryGraph() — external entity resolvers
 

package/docs/10-spa.md

@@ -34,7 +34,13 @@ src/spa/admin/
 - **`.ts`** — exports `definePage()` or `defineForm()` spec (declarative, no React)
 - **`.tsx`** — exports a React component (full control, for complex cases)
 
-**Defaults**: `@mantajs/dashboard` shell + `@mantajs/ui` preset. Override in config if needed:
+**Defaults**: `@mantajs/dashboard` shell + `@mantajs/ui` preset. The generated entry imports the public stylesheet export:
+
+```typescript
+import '@mantajs/dashboard/index.css'
+```
+
+Override in config if needed:
 
 ```typescript
 // manta.config.ts — optional, only for overrides
@@ -46,6 +52,62 @@ export default defineConfig({
 })
 ```
 
+### Mount path
+
+By default, a SPA named `admin` is mounted at `/admin`:
+
+| Generated setting | Default for `src/spa/admin` |
+| --- | --- |
+| React Router basename | `/admin` |
+| Vite `base` | `/admin/` |
+| Static output | `public/admin` |
+| Vercel SPA rewrite | `/admin/:path*` → `/admin/index.html` |
+
+Use `mountPath: '/'` for a dashboard on a dedicated subdomain, such as `admin.fancypalas.com/paniers`:
+
+```typescript
+// manta.config.ts
+export default defineConfig({
+  spa: {
+    admin: { mountPath: '/' },
+  },
+})
+```
+
+With `mountPath: '/'`, React Router uses `basename="/"`, Vite uses `base: '/'`, the SPA builds into `public/`, and generated Vercel rewrites exclude `/api/*`.
+
+### Dev Vite port
+
+`manta dev` starts one Vite server per detected SPA. Ports default to `5200`, then increment for additional SPAs.
+
+Configure the port in `manta.config.ts` when another project already uses the default:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: { vitePort: 5310 },
+  },
+})
+```
+
+Environment overrides are also supported:
+
+```bash
+MANTA_VITE_PORT=5310 manta dev
+MANTA_VITE_PORT_ADMIN=5311 manta dev
+```
+
+The SPA-specific variable wins over the global one. The suffix uses the SPA name uppercased with non-alphanumeric characters replaced by `_`.
+
+### Local production fallback
+
+`manta build` writes a SPA fallback manifest into `.manta/server/spa-manifest.ts`. For the Node preset, `manta start` uses it to mirror the Vercel SPA behavior locally:
+
+- `/` redirects to the single SPA mount path when the SPA is not mounted at `/`
+- `/login`, `/reset-password`, and `/accept-invite` redirect under that mount path
+- `/admin/*` and other configured SPA mount paths serve the built `index.html`
+- `/api/*` and asset URLs remain server-side/static and are not swallowed by the SPA fallback
+
 ---
 
 ## SPA Configuration — defineSpa()