@everystack/mcp 0.3.3 → 0.4.0

package/src/resources/derived-objects.md

@@ -0,0 +1,225 @@
+# Derived Objects: functions, views, materialized views, triggers, sequences
+
+> Derived objects don't migrate — they **deploy**. Base tables hold irreplaceable data
+> and change through generated migrations. Functions, views, and materialized views are
+> **compute**: declared source whose results are rebuildable from the tables at any time.
+> You edit their descriptors, and `db:reconcile` makes the database match — no migration
+> file, no journal entry, no numbered anything. Git is the history.
+
+Read this when you need to add or change a view, materialized view, function, trigger, or
+standalone sequence. For tables (`defineModel`) and the operational verbs
+(`db:sync`/`db:plan`/`db:apply`), see `everystack://schema-patterns` and
+`everystack://database-operations`.
+
+## Two layers, two lifecycles
+
+A schema is two different things, and conflating them is the mistake:
+
+| Layer | Objects | Changes via | History |
+|-------|---------|-------------|---------|
+| **State** | tables, constraints, authz, sequences | Models → `db:generate` → migration | migration + `db:pull` |
+| **Compute** | functions, views, matviews, triggers | descriptors → `db:reconcile` | git |
+
+Versioning compute through migrations is a category error — the same as writing a
+migration to edit a Lambda handler. A one-line fix to a materialized view should be a
+one-line git diff, not a restatement of the whole view inside a numbered file. (In one
+real analytics app, 34 of 43 migrations were pure derived-layer churn, including a 701 KB
+migration that fixed a one-line regex.) Descriptors end that.
+
+## The declared home
+
+The whole database — both layers — lives in `db/models/`, in one format:
+
+```
+db/
+├── models/          # the declared database: defineModel tables + derived descriptors
+│   ├── post.ts
+│   ├── derived.ts   # defineView / defineMaterializedView / defineFunction / defineSql
+│   └── index.ts     # defineModule({ models, sequences, derived })
+└── schema.generated.ts   # generated artifact (never edited; db:check refuses drift)
+```
+
+**`db/sql/` is retired.** Raw-SQL derived objects moved into descriptors, and every CLI
+verb hard-fails on a `db/sql/` directory that still carries `.sql` files. If you are
+adopting an app that still has one, see "Adopting an existing database" below.
+
+The boundary rule, uniform with models: **structure is declared** (identity,
+dependencies, authz, security posture, indexes, signatures, trigger events);
+**expressions stay `sql``** (the SELECT, the function body, a WHEN predicate). No query
+DSL, no string mini-grammars in declared properties.
+
+```ts
+import { defineView, defineMaterializedView, defineFunction, defineSql, defineModule,
+         trigger, arg, setof, field, can, index, sql } from '@everystack/model';
+
+// A VIEW — securityInvoker is the one forced decision.
+export const activeUsers = defineView('active_users', {
+  securityInvoker: true,            // REQUIRED, no default:
+                                    // true  = readers' own RLS/grants apply through the view
+                                    // false = definer semantics (the sealed-slice pattern —
+                                    //         a view grant WITHOUT a table grant; the body must seal)
+  abilities: [can('read')],         // grants are AUTHORED, never inherited
+  dependsOn: [users],               // declared, then VERIFIED against the live edges (drift-checked)
+  fields: { id: field.uuid().notNull(), name: field.text().notNull() },  // OPTIONAL: typed SSR
+                                    // reads — emits a pgView().existing() into schema.generated.ts;
+                                    // never touches the DDL or the content hash
+  as: sql`SELECT id, name FROM users WHERE deleted_at IS NULL`,
+});
+
+// A MATERIALIZED VIEW — grants-only authz; refresh/populate declare the HOW.
+export const leaderboard = defineMaterializedView('leaderboard', {
+  abilities: [can('read')],
+  dependsOn: [scores, activeUsers],
+  indexes: [index(['user_id']).unique(), index('tags').using('gin')],
+  refresh: 'concurrently',          // compile-gated: REQUIRES a unique, non-partial index
+  populate: 'deferred',             // create WITH NO DATA, refresh outside the creation lock
+  as: sql`SELECT user_id, sum(points) AS points FROM scores GROUP BY user_id`,
+});
+
+// A FUNCTION — signature structured, body raw.
+export const searchPosts = defineFunction('search_posts', {
+  args: [arg('query', 'text')],
+  returns: setof(posts),            // a descriptor ref — a typo is a TS error, the dep comes free
+  language: 'sql',
+  volatility: 'stable',             // default 'volatile'; 'immutable' enables expression indexes
+  abilities: [can('execute', { role: 'authenticated' })],  // role REQUIRED; PUBLIC is always revoked
+  body: sql`SELECT * FROM posts WHERE ts @@ websearch_to_tsquery(query)`,
+});
+
+// A SECURITY DEFINER function MUST pin its search_path (the classic landmine):
+export const promote = defineFunction('promote_user', {
+  args: [arg('uid', 'uuid')], returns: 'void', language: 'plpgsql',
+  security: 'definer', searchPath: ['pg_catalog', 'public'],   // required with definer
+  abilities: [can('execute', { role: 'admin' })],
+  body: sql`BEGIN UPDATE users SET role = 'admin' WHERE id = uid; END`,
+});
+
+// A TRIGGER FUNCTION is a standalone function returning 'trigger'…
+export const touchUpdatedAt = defineFunction('touch_updated_at', {
+  returns: 'trigger', language: 'plpgsql',
+  body: sql`BEGIN NEW.updated_at = now(); RETURN NEW; END`,
+});
+
+// …and the TRIGGER is declared ON THE MODEL it fires on (owner consent, visible where the
+// table lives) — see defineModel below.
+
+export const appModule = defineModule({
+  models: [posts, users],
+  derived: [activeUsers, leaderboard, searchPosts, promote, touchUpdatedAt],
+  // sequences: [invoiceNo],   // standalone sequences are STATE — see below
+});
+```
+
+Triggers ride the model:
+
+```ts
+export const Post = defineModel('posts', {
+  fields: { id: field.uuid().primaryKey(), updatedAt: field.timestamptz() },
+  abilities: [can('read')],
+  triggers: [trigger('touch', {
+    timing: 'before', events: ['update'], forEach: 'row',
+    execute: touchUpdatedAt,        // the trigger function MUST be in the module's derived set
+  })],
+});
+```
+
+## The rules that make it safe (all enforced)
+
+- **`securityInvoker` is a required decision** on every view — no default. Pick `true`
+  (readers' own RLS applies) or `false` (definer semantics, the sealed slice).
+- **Grants are authored, never inherited.** `can('read')` on a relation → `anon` +
+  `authenticated`; `can('read', { role })` narrows. A granted view whose readers can't
+  reach its underlying tables is a **compile error** — the reachability gate.
+- **SECURITY DEFINER without a pinned `searchPath` is rejected** at define time.
+- **`can('execute')` needs a role** — bare execute has no safe audience; PUBLIC is always
+  revoked by the compiler.
+- **A missing import is caught loudly.** An `undefined` in `dependsOn`/`derived`/a
+  trigger's `execute` (a renamed or missing named import) is rejected at define time,
+  naming the descriptor and the index — never a silent drop.
+- **`dependsOn` is declared, then verified.** The reachability gate walks it at compile
+  time; the live catalog's actual edges check it at plan time. A view that reads a table
+  it never declared (or declares one it never reads) is a `db:check` failure.
+- **REFRESH CONCURRENTLY requires a unique, non-partial index** — compile-gated.
+- **Content hashing is comment- and whitespace-insensitive** — reformatting a body is a
+  no-op; only a real change reconciles.
+
+The escape hatch `defineSql` handles what the structured vocabulary can't say yet
+(aggregates, operators, event triggers) — still declared, hashed, dependency-ordered. It
+refuses a `CREATE [MATERIALIZED] VIEW` so accidental relations land in the read model
+where the gates can see them; its SQL is otherwise trusted as authored.
+
+## Sequences are STATE, not compute
+
+A standalone sequence (one not owned by a serial column) holds a counter value, so it
+migrates with the base schema — declare it with `defineSequence` and pass it on
+`defineModule({ sequences })`. It is fingerprinted with the tables and created before them.
+This is the one derived-looking object that is state, not compute.
+
+```ts
+export const invoiceNo = defineSequence('invoice_no', { start: 1000 });
+```
+
+## Deploying: `db:reconcile`
+
+```bash
+everystack db:reconcile                          # plan (read-only; works via --stage or --database-url)
+everystack db:reconcile --check                  # CI gate: exit 1 when anything differs
+everystack db:reconcile --apply --database-url … # execute (direct connection required)
+```
+
+Planning works over the read-only ops Lambda (`--stage`); **`--apply` needs a direct
+connection** — the deployed query path is read-only by design. On a dev database, prefer
+`db:sync` (it does state + compute in one verb); reach for `db:reconcile --apply` when you
+want compute only.
+
+A plan shows the rebuild cost before you say yes — dependent cascades, matview sizes, row
+counts:
+
+```
+= 51 up to date
+~ replace public.score (source changed)
+↻ refresh public.season_scores (depends on replaced function public.score; 1.2 GB, ~4M rows)
++ create public.weekly_top (new in source)
+≠ regrant public.leaderboard — live grants differ (REVOKE SELECT ON leaderboard FROM intern)
+estimated rebuild: 1.2 GB across 1 matview(s)
+```
+
+`--apply` sends all DDL as **one transaction** (a failed create rolls back the drops
+before it), records provenance and a `schema_log` memoir (the full DDL, when, by whom,
+from which git commit), and rebuilds dependents automatically in dependency order.
+
+## Semantics worth knowing
+
+- **Drift is never overwritten silently.** A hand-edited managed object (someone ran
+  `CREATE OR REPLACE` against the DB) makes the plan report drift and `--apply` refuse.
+  Fix the source to match, or rebuild from source with `--overwrite-drift`.
+- **Grant drift converges without ceremony** — a hand-run GRANT/REVOKE surfaces as an
+  idempotent `regrant` back to the declared abilities. Declared authz is authoritative.
+- **Changing a function REFRESHes the matviews that call it** — their rows are stale the
+  moment the function changes, and the reconciler knows it.
+- **Unmanaged objects are never touched** — live derived objects with no source and no
+  provenance are listed and left alone.
+
+## Adopting an existing database (baseline / rebaseline)
+
+- **First contact wants `--baseline`.** Against a database that already has your derived
+  layer (built by old migrations), the reconciler refuses to guess whether live matches
+  source. `everystack db:pull` renders the live layer as descriptors (bodies from the
+  catalog's canonical deparse, grants as abilities, `dependsOn` from live edges). The path:
+  **pull → review → commit → `db:reconcile --apply --baseline` → a silent check.**
+  Use `db:pull --derived-out db/models/derived.ts` to write the derived layer straight
+  into its own file when you already have a hand-maintained models barrel.
+- **A `db/sql`-era migration wants `--rebaseline`.** When provenance exists but the source
+  was re-rendered (descriptors render canonical SQL, so the source hash differs even for
+  identical SQL), `--rebaseline` re-records the new source hash for every object whose live
+  definition still matches what the reconciler last applied — no drop, no create, no
+  matview repopulation. The live side is VERIFIED; the source side is TRUSTED. Migrate
+  first (verbatim), edit after. `--baseline` and `--rebaseline` compose in one run.
+
+## Current limitations
+
+- **Function identity is by name** — overloads are rejected at define time. Rename one.
+- **Function signature changes** (return/arg types) can't `CREATE OR REPLACE` — drop the
+  old function in a reviewed step, or rename.
+- Postgres can't see function→function dependencies inside bodies — `dependsOn` is your
+  declaration there.

package/src/resources/index.ts

@@ -116,9 +116,23 @@ const RESOURCES: ResourceDef[] = [
     uri: 'everystack://schema-patterns',
     name: 'Schema Design Patterns',
     description:
-      'Drizzle schema design: pgTable, column types, relations, indexes, timestamps, soft delete, UUID vs serial, migration workflow, drizzle-kit commands.',
+      'How to declare TABLES (0.4.0): db/models/ with defineModel (field, can, relations, constraints) — NOT hand-written pgTable or drizzle-kit. Column types, keys, indexes, timestamps, soft delete, UUID vs serial, the private()/readonly()/deprecated() write surface. Read everystack://derived-objects for views/matviews/functions/triggers, and everystack://database-operations for how it reaches a database.',
     filename: 'schema-patterns.md',
   },
+  {
+    uri: 'everystack://derived-objects',
+    name: 'Derived Objects (Views, Matviews, Functions, Triggers)',
+    description:
+      'How to add or change a view, materialized view, function, trigger, or standalone sequence in 0.4.0 — declared descriptors (defineView / defineMaterializedView / defineFunction / defineSql / trigger() / defineSequence) on defineModule({ derived }), deployed by db:reconcile (NEVER migrated). Read this whenever a schema needs compute, not just tables. db/sql/ is retired.',
+    filename: 'derived-objects.md',
+  },
+  {
+    uri: 'everystack://database-operations',
+    name: 'Database Operations (migrate, import data, SAFE remote apply)',
+    description:
+      'The operational playbook: local dev (db:sync, db:branch, db:template:refresh), importing data properly (db:seed, db:backfill, ingest pipeline — never ad-hoc INSERTs), and migrating a REMOTE stage SAFELY (db:check → db:plan → db:apply with fingerprint + fast-forward verification; destructive plans require --confirm + snapshot + approvers). Snapshot-first (db:snapshot vs db:backup) and remote data import (db:seed --stage, pipeline:run, db:fork). READ THIS before touching a deployed database.',
+    filename: 'database-operations.md',
+  },
   {
     uri: 'everystack://deployment',
     name: 'Deployment Guide',

package/src/resources/project-claude-md.md

@@ -19,12 +19,14 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 - **Data lives in PostgreSQL, served through the API — never bundle data into the app.** A
   large `.json`/`.csv` of computed data in the bundle is wrong; model it and serve it, or
   render an empty state if it does not exist yet.
-- **Nobody authors migrations. Schema work has three homes.** Tables and authz are DECLARED
-  in `db/models/` with `defineModel` — edit the Model, then `everystack db:sync` moves the
-  dev database to your checkout (state + authz + derived, fingerprint-verified). Functions,
-  views, and matviews are **authored** in `db/sql/` and deployed by `db:reconcile`/`db:sync`.
-  One-shot DATA moves are authored in `db/backfills/*.sql` and run via `everystack
-  db:backfill` — deliberately, never as a schema side effect. Never hand-write a SQL
+- **Nobody authors migrations. Schema work has two homes.** The WHOLE declared database
+  lives in `db/models/`: tables and authz with `defineModel`, and the derived layer —
+  functions, views, matviews — as descriptors (`defineView` / `defineMaterializedView` /
+  `defineFunction` / `defineSql`, triggers via `trigger()` on the model). Edit the
+  declaration, then `everystack db:sync` moves the dev database to your checkout (state +
+  authz + derived, fingerprint-verified). One-shot DATA moves are authored in
+  `db/backfills/*.sql` and run via `everystack db:backfill` — deliberately, never as a
+  schema side effect. Never hand-write a SQL
   migration, never edit `db/schema.generated.ts`; `everystack db:check` must pass (the CI
   gate: the declared state composes, generated artifacts match regeneration).
 - **Protected stages take plans, not syncs.** `everystack db:plan` mints a reviewable edge
@@ -42,8 +44,8 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 
 ## Start Here
 
-- `db/models/` — `defineModel` tables (the source of truth for schema + authz)
-- `db/sql/` — functions, views, matviews (authored SQL; deploys via `db:reconcile`/`db:sync`)
+- `db/models/` — the declared database: `defineModel` tables + derived descriptors
+  (`defineView`/`defineMaterializedView`/`defineFunction`/`defineSql`; deploys via `db:reconcile`/`db:sync`)
 - `db/backfills/` — one-shot data jobs (authored SQL; run via `db:backfill`, own record)
 - `app/` — Expo Router pages (screens, navigation, API routes)
 - `server/` — Lambda handlers (api.ts, worker.ts, image.ts)
@@ -84,9 +86,9 @@ Declare tables with `defineModel` (`field`, `can`, relations). A package's full
 live state is content-addressed (`db:fingerprint`), and every apply verifies against it. You
 never hand-write migrations, RLS, or handler access-control — they are derived, so they cannot
 drift; `deriveHandlerConfig(models)` derives the API config. The derived layer (functions,
-views, matviews) is the exception that proves the rule: that SQL is authored, in `db/sql/`,
-and *deployed* by reconcile — hand-edits straight against the database surface as drift, and a
-comment-only edit is a no-op. Contraction is a two-step ceremony: `field.deprecated()` first
+views, matviews) follows the same rule: descriptors declare the structure (identity, deps,
+authz, security posture), the body stays `sql\`\``, and reconcile *deploys* it — hand-edits
+straight against the database surface as drift, and a comment-only edit is a no-op. Contraction is a two-step ceremony: `field.deprecated()` first
 (the column stays readable, new writes are rejected, generated types strike it through), the
 physical drop later — a destructive plan, confirmed, snapshotted, approver-gated.
 
@@ -118,7 +120,8 @@ Every feature starts with a failing test. Tests in `__tests__/` mirroring source
 
 - Don't bundle large data into the app — it lives in the DB, served by the API.
 - Don't hand-write migrations or edit `db/schema.ts` — edit the Model, run `db:generate`;
-  for functions/views/matviews edit `db/sql/` and run `db:reconcile`.
+  for functions/views/matviews edit the descriptors in `db/models/` and run `db:reconcile`
+  (`db/sql/` is retired — the verbs fail on it with the migration path).
 - Don't hand-write RLS — declare `can()` abilities.
 - Don't hand-roll a component that exists in `@everystack/ui`; don't use inline `StyleSheet`.
 - Don't put a secret behind `EXPO_PUBLIC_*` — that ships to the client.

package/src/resources/schema-patterns.md

@@ -1,167 +1,153 @@
 # Schema Design Patterns
 
-> Drizzle schema design, migrations, and RLS setup for everystack apps.
+> Declaring TABLES with `defineModel` in `db/models/` — fields, authz, relations, indexes.
 
 ## When to Use
-Read this when designing your database schema or adding tables to an existing app.
+Read this when designing your database schema or adding tables to an existing app. This
+resource covers **tables** (`defineModel`). For the derived layer —
+views, materialized views, functions, triggers, standalone sequences — read
+`everystack://derived-objects` (they deploy via `db:reconcile`, not migrations). For the
+operational verbs that move a database (`db:sync`, `db:generate`, `db:plan`/`db:apply`,
+`db:check`), read `everystack://database-operations`.
 
 ## Schema Location
 
-Schemas live in `db/schema.ts` (or `db/schema/` directory for larger apps). This file is the single source of truth for both the handler and SSR.
+The whole declared database lives in `db/models/` — one `defineModel` per table, composed
+onto a `defineModule`. This is the single source of truth for the handler, SSR, RLS, and
+grants. You do **not** hand-write `db/schema.ts`, and you do **not** run
+`drizzle-kit generate`/`drizzle-kit migrate` — the Model is authored, and everystack
+generates the migration (`db:generate`) and the typed artifact (`db/schema.generated.ts`,
+never edited). Never hand-write a SQL migration.
 
 ## Basic Table
 
 ```typescript
-import { pgTable, serial, text, integer, timestamp, uuid } from 'drizzle-orm/pg-core';
-
-export const posts = pgTable('posts', {
-  id: uuid('id').defaultRandom().primaryKey(),
-  body: text('body').notNull(),
-  authorId: uuid('author_id').notNull().references(() => users.id),
-  status: text('status').default('draft').notNull(),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-  updatedAt: timestamp('updated_at').defaultNow().notNull(),
-  deletedAt: timestamp('deleted_at'),
+import { defineModel, field, can } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    body: field.text().notNull(),
+    authorId: field.uuid().notNull().references('users', 'id'),
+    status: field.text().notNull().default('draft'),
+    createdAt: field.timestamptz().notNull().defaultNow(),
+    updatedAt: field.timestamptz().notNull().defaultNow(),
+    deletedAt: field.timestamptz(),
+  },
+  abilities: [can('read'), can('create'), can('update'), can('delete')],
 });
 ```
 
+Column names are `snake_case` in the database; the field key is the app-side name — the
+generator maps `authorId` → `author_id` for you.
+
 ## Common Patterns
 
 ### UUID vs Serial Primary Keys
 Prefer UUID for user-facing IDs (prevents enumeration attacks). Use serial for internal-only tables.
 
 ```typescript
-id: uuid('id').defaultRandom().primaryKey(),  // Preferred for API-exposed tables
-id: serial('id').primaryKey(),                 // OK for internal tables
+id: field.uuid().primaryKey().defaultRandom(),  // Preferred for API-exposed tables
+id: field.serial().primaryKey(),                 // OK for internal tables
 ```
 
 ### Timestamps
 Always include `createdAt` and `updatedAt`:
 ```typescript
-createdAt: timestamp('created_at').defaultNow().notNull(),
-updatedAt: timestamp('updated_at').defaultNow().notNull(),
+createdAt: field.timestamptz().notNull().defaultNow(),
+updatedAt: field.timestamptz().notNull().defaultNow(),
 ```
 
 ### Soft Delete
 Add `deletedAt` for soft-deletable tables:
 ```typescript
-deletedAt: timestamp('deleted_at'),
+deletedAt: field.timestamptz(),
 ```
 Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
 
 ### Foreign Keys
 ```typescript
-authorId: uuid('author_id').notNull().references(() => users.id),
+authorId: field.uuid().notNull().references('users', 'id'),
 ```
 
 ### Enums
 ```typescript
-import { pgEnum } from 'drizzle-orm/pg-core';
-
-export const roleEnum = pgEnum('role', ['user', 'admin']);
-
-export const users = pgTable('users', {
-  role: roleEnum('role').default('user').notNull(),
-});
+role: field.enum('role', ['user', 'admin']).notNull().default('user'),
 ```
 
-## Relations (Drizzle)
+## Relations
 
-```typescript
-import { relations } from 'drizzle-orm';
+Declare relations on the Model — the generator emits both the Drizzle relations (used by
+the relational query API, `db.query.posts.findMany({ with: { author: true } })`) and the
+handler's embedding config, so they can't drift apart.
 
-export const postsRelations = relations(posts, ({ one, many }) => ({
-  author: one(users, { fields: [posts.authorId], references: [users.id] }),
-  comments: many(comments),
-}));
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  relations: {
+    author: { model: 'users', from: 'authorId', to: 'id' },
+    comments: { model: 'comments', from: 'id', to: 'postId', many: true },
+  },
+  abilities: [can('read')],
+});
 ```
 
-Drizzle relations are used by the relational query API (`db.query.posts.findMany({ with: { author: true } })`). The handler also needs its own `relations` config for embedding.
-
 ## Indexes
 
 ```typescript
-import { index, uniqueIndex } from 'drizzle-orm/pg-core';
-
-export const posts = pgTable('posts', {
-  // columns...
-}, (table) => [
-  index('posts_author_id_idx').on(table.authorId),
-  uniqueIndex('posts_slug_idx').on(table.slug),
-]);
+import { defineModel, field, can, index } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  indexes: [
+    index(['authorId']),
+    index(['slug']).unique(),
+  ],
+  abilities: [can('read')],
+});
 ```
 
-## Migration Workflow
-
-```bash
-# Generate migration from schema changes
-npx drizzle-kit generate
-
-# Apply migrations locally
-npx drizzle-kit migrate
+## Authorization is declared, not migrated
 
-# Apply migrations on deployed Lambda
-everystack db:migrate
-```
+You never hand-write `CREATE ROLE`, `GRANT`, or `CREATE POLICY`. Abilities on the Model
+compile to grants + RLS, and `db:sync`/`db:apply` deploy them. `can('read')` grants `anon`
++ `authenticated`; `can('read', { role: 'admin' })` narrows to a role. RLS is required —
+the CI gate (`db:check`) refuses a table without it. See `everystack://security` for the
+policy patterns the abilities compile to.
 
-Migration files go in `drizzle/` directory. Each migration is a SQL file.
-
-### RLS Migration Template
-
-After creating tables, add a migration for roles and policies:
-
-```sql
--- Create roles (idempotent)
-DO $$ BEGIN
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticator') THEN
-    CREATE ROLE authenticator LOGIN NOINHERIT;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anon') THEN
-    CREATE ROLE anon NOLOGIN;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticated') THEN
-    CREATE ROLE authenticated NOLOGIN;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'admin') THEN
-    CREATE ROLE admin NOLOGIN;
-  END IF;
-END $$;
-
-GRANT anon TO authenticator;
-GRANT authenticated TO authenticator;
-GRANT admin TO authenticator;
-
--- Table grants
-GRANT USAGE ON SCHEMA public TO anon, authenticated, admin;
-GRANT SELECT ON posts TO anon;
-GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO authenticated;
-GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO admin;
-
--- Enable RLS
-ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
-ALTER TABLE posts FORCE ROW LEVEL SECURITY;
-
--- Policies (see everystack://security for templates)
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  abilities: [
+    can('read'),                              // anon + authenticated
+    can('create', { role: 'authenticated' }),
+    can('update', { role: 'authenticated', own: 'authorId' }),  // row ownership
+    can('delete', { role: 'admin' }),
+  ],
+});
 ```
 
 ## Handler Config for Schema
 
+The handler config is **derived** from the Models (`deriveHandlerConfig(models)`), so
+`exposedTables`, `hiddenColumns`, `protectedFields`, and `relations` come from the
+declarations rather than a hand-kept parallel list:
+
 ```typescript
-createHandler(db, schema, {
-  exposedTables: ['posts', 'profiles'],  // Only these are API-accessible
-  hiddenColumns: { users: ['passwordHash', 'resetToken'] },
-  protectedFields: { profiles: ['role', 'deletedAt'] },
-  relations: {
-    posts: { author: { table: 'users', from: 'authorId', to: 'id' } },
-  },
-});
+import { deriveHandlerConfig } from '@everystack/model';
+import { models } from '../db/models';
+
+createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
 ## Gotchas
 
-- Drizzle column names (camelCase) and SQL column names (snake_case) are both specified: `authorId: uuid('author_id')`
-- The handler's `relations` config uses Drizzle property names, not SQL column names
-- `exposedTables` uses Drizzle table variable names, not SQL table names
-- Always run `drizzle-kit generate` after schema changes
-- RLS migration must be run AFTER table creation migration
-- Connect as `authenticator` in production (never RDS master/superuser)
+- Field keys are app-side names (camelCase); the database column is `snake_case` — the
+  generator maps `authorId` → `author_id`.
+- Edit the Model, then move the database with `db:sync` (dev) or `db:generate` +
+  `db:plan`/`db:apply` (protected stages). Never run `drizzle-kit generate`.
+- RLS and grants are declared with `can()`, never hand-written; `db:check` fails a table
+  without RLS.
+- `db/schema.generated.ts` is a generated artifact — never edit it; `db:check` refuses
+  drift.
+- Connect as `authenticator` in production (never RDS master/superuser).