@everystack/mcp 0.3.3 → 0.4.0

package/dist/adding-database.md

@@ -13,7 +13,7 @@ You already have a running Expo app. Now you're adding:
 - **@everystack/logging** — structured logging so you can see what your app is doing.
 - **@everystack/security** — device attestation and biometric auth.
 - **@everystack/query** — React hooks that make it easy to fetch and display data.
-- **Drizzle ORM** — defines your database tables in TypeScript. You describe what data you want to store, and Drizzle creates the tables for you.
+- **@everystack/model** — declares your database tables in TypeScript with `defineModel`. You describe what data you want to store and who can read/write it, and everystack generates the migration and the typed schema for you.
 
 ## Step 1: Install PostgreSQL
 
@@ -64,24 +64,31 @@ You should see a table with the value `1`. If so, your database is ready.
 From your project directory:
 
 ```bash
-pnpm add @everystack/api @everystack/auth @everystack/admin @everystack/logging @everystack/security @everystack/query
+pnpm add @everystack/api @everystack/auth @everystack/admin @everystack/logging @everystack/security @everystack/query @everystack/model
 pnpm add drizzle-orm
-pnpm add -D drizzle-kit
 ```
 
-## Step 4: Create your database schema
+## Step 4: Declare your database schema
 
-The schema defines what data your app stores. Create a file at `db/schema.ts`.
+The schema defines what data your app stores. Create your tables in `db/models/` — one
+`defineModel` per table (for example `db/models/post.ts`), composed onto a `defineModule`
+in `db/models/index.ts`.
 
-A schema is like designing a spreadsheet before you start filling in data. You decide what columns each table has, what type of data goes in each column, and how tables relate to each other.
+A model is like designing a spreadsheet before you start filling in data. You decide what columns each table has, what type of data goes in each column, and how tables relate to each other — plus who can read and write each table.
 
-Read everystack://schema-patterns for design patterns and examples. Key conventions:
+You do **not** hand-write `db/schema.ts` and you do **not** run `drizzle-kit generate` —
+everystack generates the migration and the typed artifact from your Models.
 
-- UUID primary keys with `defaultRandom()`
-- `created_at` and `updated_at` timestamps on all tables
-- Foreign key references with proper cascading
-- Relations defined for both SSR and API query embedding
-- Snake_case column names
+Read everystack://schema-patterns for the `defineModel` patterns and examples. Key conventions:
+
+- UUID primary keys with `field.uuid().primaryKey().defaultRandom()`
+- `createdAt` and `updatedAt` timestamps on all tables
+- Foreign key references with `.references('users', 'id')`
+- Relations declared on the Model (used for both SSR and API query embedding)
+- Authorization declared with `can()` abilities (compiles to grants + RLS)
+
+For views, materialized views, functions, and triggers, read everystack://derived-objects
+— they are declared as descriptors and deploy via `db:reconcile`, not migrations.
 
 ## Step 5: Configure the handler
 
@@ -121,29 +128,35 @@ export async function POST(request: Request) {
 // ... PATCH, DELETE
 ```
 
-## Step 8: Run migrations
+## Step 8: Move your database to match your Models
 
-Migrations create the actual tables in your database based on your schema.
+`db:sync` makes your local dev database match your checkout — tables, authz, and the
+derived layer — in one command. You never run `drizzle-kit` or write a SQL migration.
 
 ```bash
-npx drizzle-kit generate
-npx drizzle-kit migrate
+everystack db:sync --database-url "$DATABASE_URL"
 ```
 
-The first command generates SQL files from your schema. The second runs them against your database.
+This is the dev edit loop: change `db/models/`, run `db:sync`, test, repeat. When you're
+ready to record the change as a migration for protected stages, run `everystack db:generate`
+(and later reach a deployed stage with `db:plan` → `db:apply`).
+
+Read everystack://database-operations for the full workflow — the dev loop, importing data,
+and safely migrating a deployed stage.
 
 ## Step 9: Security
 
 **This is not optional.** Read everystack://security for the three-layer security model.
 
-Your database needs Row Level Security (RLS) policies. These are rules that control who can see and change what data. Even if your app code has a bug, the database enforces access control.
+Your database needs Row Level Security (RLS) — rules that control who can see and change what data. Even if your app code has a bug, the database enforces access control.
 
-At minimum:
-- Create database roles (`anon`, `authenticated`, `admin`)
-- Add RLS policies to every table
-- Set up GRANTs so each role can only access what it should
+In everystack you **declare** this on your Models rather than hand-writing SQL: `can()`
+abilities on each `defineModel` compile to database roles (`anon`, `authenticated`,
+`admin`), GRANTs, and RLS policies, and `db:sync` deploys them. `db:check` (the CI gate)
+refuses a table without RLS. Never hand-write `CREATE ROLE`, `GRANT`, or `CREATE POLICY`.
 
-The security resource has copy-paste SQL templates for common patterns.
+The security resource explains the policies your abilities compile to and the patterns
+behind them.
 
 ## Step 10: Verify
 

package/dist/cli.md

@@ -28,11 +28,52 @@ everystack update --channel staging --platform web
 Flags: `--channel` (default: production), `--message`, `--platform` (ios/android/web/all), `--skip-export`.
 
 ### Database
+
+You declare tables in `db/models/` (`defineModel`) and derived objects as descriptors;
+these verbs move a database. Full operational guidance: everystack://database-operations.
+
+**Schema (declare → deploy)**
+```bash
+everystack db:sync            # Make a dev DB match your checkout — state + authz + compute, one verb
+everystack db:generate        # STATE layer (tables) → next migration file (--dry-run prints the SQL, writes nothing)
+everystack db:reconcile       # Deploy the compute layer only (views/matviews/functions/triggers)
+everystack db:check           # CI gate: declared state composes + generated artifacts match regeneration
+everystack db:fingerprint     # Content-address the live base schema vs the Models — MATCH/MISMATCH
+everystack db:diff            # The state edge between two declared states — no DB, CI-pure
+```
+
+**Safe remote migration (protected stages)**
+```bash
+everystack db:plan --stage X --out X.plan.json     # Mint a reviewable edge — read-only, ephemeral
+everystack db:apply --plan X.plan.json --stage X   # Verify → apply → verify, credential-free via the ops Lambda
+everystack db:approvers --stage X --set "…"        # Declare who may run destructive applies (STS-verified)
+```
+
+**Backups & safety**
+```bash
+everystack db:snapshot --stage X       # Physical RDS snapshot (instant DR)
+everystack db:snapshots --stage X       # List manual RDS snapshots
+everystack db:backup --stage X          # Logical pg_dump → private S3 backups bucket
+everystack db:backups --stage X         # List logical backups
+everystack db:backup:download <id> --stage X   # Presigned download URL (1h)
+everystack db:restore --from <id> --stage X --confirm   # Restore a backup INTO a stage (destructive)
+```
+
+**Local dev databases**
+```bash
+everystack db:template:refresh          # Build the dev template from declared state + seed
+everystack db:branch                    # Per-git-branch dev DB from the template (--list / --prune)
+everystack db:fork --from-stage src --stage tgt --confirm   # Fork a deployed stage's DB into a feature stage
+```
+
+**Data**
 ```bash
-everystack db:migrate                                    # Run migrations via Lambda
-everystack db:seed                                       # Seed database (dev only)
+everystack db:seed --stage dev          # Declarative seed script (dev only; refuses on production)
+everystack db:backfill --apply          # One-shot data moves from db/backfills/*.sql (own record)
+everystack pipeline:run --stage X       # Ingest pipeline (credential-free in the ops Lambda)
+everystack db:migrate                   # Run the generated migration on a deployed stage via Lambda invoke
 everystack db:psql --stage dev -c "SELECT * FROM posts"  # Read-only SQL via Lambda
-everystack console --stage dev                           # Interactive REPL with db + schema
+everystack console --stage dev          # Interactive REPL with db + schema
 ```
 
 The REPL has `db`, `schema`, `eq`, `and`, `or`, `gt`, `lt`, `count`, `sum`, `avg`, `sql`, `desc`, `asc` in scope.

package/dist/core.md

@@ -158,11 +158,24 @@ const { data } = await api.rpc('timeline', { limit: 20 });
 
 All infrastructure commands use **AWS IAM credentials** (not shared secrets).
 
+You declare tables in `db/models/` with `defineModel` and the derived layer as descriptors
+(see everystack://derived-objects); the CLI moves the database — you never run
+`drizzle-kit` or hand-write a migration. Full operational guidance:
+everystack://database-operations.
+
 | Command | What it does |
 |---------|-------------|
 | `everystack update --channel production` | OTA deploy (no infrastructure changes) |
-| `everystack db:migrate` | Run Drizzle migrations via Lambda invoke |
+| `everystack db:sync` | Dev DB ← your checkout (state + authz + compute), one verb |
+| `everystack db:generate` | STATE layer (tables) → next migration file |
+| `everystack db:reconcile` | Deploy the compute layer (views/matviews/functions/triggers) |
+| `everystack db:check` | CI gate: declared state composes + artifacts match regeneration |
+| `everystack db:plan --stage X` | Mint a reviewable, fingerprint-pinned edge (read-only) |
+| `everystack db:apply --plan … --stage X` | Verify → apply → verify, credential-free via the ops Lambda |
+| `everystack db:snapshot / db:backup --stage X` | Physical RDS snapshot / logical pg_dump before a risky migration |
 | `everystack db:seed` | Seed database via Lambda invoke (dev only) |
+| `everystack db:backfill --apply` | One-shot data moves from `db/backfills/*.sql` |
+| `everystack db:migrate` | Run the generated migration on a deployed stage via Lambda invoke |
 | `everystack db:psql --stage dev -c "SQL"` | Execute read-only SQL via Lambda |
 | `everystack console --stage dev` | Interactive REPL with db + schema in scope |
 | `everystack logs:errors --stage dev` | Query recent error logs |
@@ -173,6 +186,11 @@ All infrastructure commands use **AWS IAM credentials** (not shared secrets).
 | `everystack diag URL` | Diagnose deployed page freshness |
 | `everystack analyze:ssr` | Static analysis for SSR anti-patterns |
 
+On a dev database you `db:sync` freely; a protected stage takes `db:plan` → `db:apply`
+(fingerprint-verified, snapshot + approver gates on destructive plans); `db:check` is the
+per-PR CI gate; `db:reconcile` deploys compute; `db:seed`/`db:backfill` move data;
+`db:snapshot`/`db:backup` are the safety net.
+
 ## Key Patterns
 
 **Schema-agnostic.** The library knows nothing about your tables. You pass your Drizzle schema to `createHandler()`. Your schema, your migrations, your database.

package/dist/database-operations.md

@@ -0,0 +1,236 @@
+# Database Operations: local dev, data import, and SAFE remote migration
+
+> The one thing to internalize: **on a dev database you `db:sync` freely; on any protected
+> stage you `db:plan`, snapshot, `db:apply`, and a human approves destruction.** The
+> database's own declared state is the authority — every change is verified against a
+> content-addressed fingerprint, and the operator never holds a production database URL.
+
+Read this to change a deployed schema, import data, or set up a local dev database. For
+declaring the objects themselves, see `everystack://schema-patterns` (tables) and
+`everystack://derived-objects` (views/matviews/functions/triggers).
+
+## The model: two layers, three verbs by target
+
+The schema is **state** (tables, constraints, authz, sequences — migrated) and **compute**
+(functions, views, matviews, triggers — reconciled). You almost never run the layer verbs
+by hand; you run one of three verbs, chosen by WHERE you are applying:
+
+| Target | Verb | What it does |
+|--------|------|--------------|
+| **Dev database** (yours, direct URL) | `db:sync` | Make the database match your checkout — state + compute + authz, one verb. Fast, no ceremony. |
+| **Protected stage** (dev/staging/prod, deployed) | `db:plan` → `db:apply` | Mint a reviewable edge, then apply it credential-free with before/after verification. |
+| **CI / every PR** | `db:check` | Gate: the declared state composes and generated artifacts match regeneration. Exit 1 on drift. |
+
+`db:sync` is for databases you own directly. `db:plan`/`db:apply` is for databases you
+reach through the deployed ops Lambda — you never hold their URL.
+
+## Local development
+
+### A per-branch dev database
+
+```bash
+everystack db:template:refresh        # build the dev template <base>_tpl from the DECLARED
+                                      # state + the app's db:seed script (never a data copy)
+everystack db:branch                  # mint a dev DB for the current git branch from the template
+                                      # (seed rows inherited); db:sync evolves it as you edit
+everystack db:branch --list           # what branch DBs exist
+everystack db:branch --prune --confirm # drop DBs whose branches are gone (mapped via COMMENT)
+```
+
+The template is built from your **declared** models + seed, never copied from a real
+database — so a fresh branch DB is reproducible and PII-free.
+
+### The edit loop
+
+```bash
+# edit db/models/ — a table field, or a descriptor body in derived.ts
+everystack db:sync --database-url "$DATABASE_URL"   # the DB now matches your checkout
+pnpm test
+# iterate; commit when happy — the model/descriptor diff IS the change
+```
+
+`db:sync` flags: `--allow-drops` (include destructive changes; held back by default),
+`--overwrite-drift` (rebuild a hand-edited derived object from source).
+
+### Seeing the change as SQL first
+
+```bash
+everystack db:generate --dry-run --database-url "$DATABASE_URL"   # the edge as SQL, writes NOTHING
+everystack db:diff --from-models db/models/index.ts --check       # models-vs-models edge, no DB at all (CI-pure)
+```
+
+`db:generate` (without `--dry-run`) writes the next migration file for the STATE layer;
+`db:sync` and `db:apply` are how it reaches a database.
+
+## Importing data properly
+
+Data has three legitimate homes. **Never hand-write ad-hoc `INSERT`s in a migration or run
+them through `psql` for anything repeatable** — that is unversioned, unrepeatable, and a
+cheat gate flags bundled data.
+
+1. **`db:seed`** — the app's declarative seed script, for dev/demo rows. Runs on dev
+   databases (and dev-tier stages); refuses on production.
+   ```bash
+   everystack db:seed --stage dev
+   ```
+2. **`db:backfill`** — one-shot DATA moves authored as SQL in `db/backfills/*.sql`. Identity
+   is the file's **content hash** (renaming or reformatting is a no-op), each database keeps
+   its own record (`everystack.backfill_log`), an edited-after-run file is **BLOCKED**, and
+   it **never runs as a schema side effect** — you run it deliberately.
+   ```bash
+   everystack db:backfill              # list pending (dry)
+   everystack db:backfill --apply      # run the pending backfills
+   ```
+   Use it for expand → backfill → contract: add the new column (schema), move the data
+   (backfill), drop the old column later (a separate destructive plan).
+3. **The ingest pipeline** — for real, ongoing data ingestion (`defineStage`/`definePipeline`,
+   run via `pipeline:run`). This is the framework path for loading a dataset, not a script.
+   ```bash
+   everystack pipeline:run --stage dev            # credential-free, runs in the ops Lambda
+   ```
+
+## Migrating a REMOTE stage SAFELY
+
+This is the ceremony. Every step exists because a shortcut here loses data or races another
+operator. Do them in order.
+
+### 1. Gate it in CI
+
+```bash
+everystack db:check          # the declared state composes; generated artifacts match regeneration
+```
+
+`db:check` is the per-PR gate. With a scratch PostgreSQL it builds the whole declared
+database from scratch and requires a fingerprint MATCH. A PR that fails `db:check` is not
+mergeable — the schema is broken before it ever reaches a stage.
+
+### 2. Mint a reviewable plan
+
+```bash
+everystack db:plan --stage production --out prod.plan.json
+```
+
+`db:plan` is **read-only**. It asks the target its live fingerprint, diffs your checkout
+against it, and writes one plan file: the edge plus both endpoint fingerprints. It prints
+the **shape first** — a histogram (`shape: 402 policies, 398 grants, 201 rls, …`) before any
+SQL wall — and itemizes every DESTRUCTIVE statement in red with the rebuild cost. A plan
+with held drops refuses to mint unless you pass `--allow-drops` (destruction is carried
+explicitly). Plans are **ephemeral** — attach them to the PR/release, never commit them.
+
+### 3. Read the plan
+
+Look at the shape, the destructive itemization, and the rebuild estimate. This is the
+review surface — the point where a human (or you) decides the edge is what was intended.
+
+### 4. Apply it credential-free
+
+```bash
+everystack db:apply --plan prod.plan.json --stage production
+```
+
+With `--stage`, the WRITE runs **inside the ops Lambda over IAM — the operator never holds
+the database URL**. `db:apply` verifies → applies → verifies, and **refuses** unless:
+
+- **the live fingerprint still equals `plan.from`** (the concurrency lock — nobody changed
+  the target since you minted the plan; if they did, re-mint), AND
+- **your checkout descends from the commit that declares the target's state** (the
+  fast-forward rule — "rebase first"; a stale checkout can't silently revert merged work).
+
+Every refusal is recorded in `everystack.schema_log`. `--database-url` is local-dev-only;
+protected stages always go through `--stage`.
+
+### 5. Destructive plans carry more gates
+
+A plan is DESTRUCTIVE if it drops (table/column/type) or narrows a type (a lossy
+`SET DATA TYPE`). Those additionally require, all of them:
+
+- **`--confirm`** — always, explicitly.
+- **A snapshot** — taken automatically via `db:backup` when you pass `--stage` (or supply
+  one with `--snapshot-ref`). No snapshot, no destructive apply.
+- **The stage's approver set** — if declared, `db:apply` verifies the caller's AWS identity
+  (STS) against it. Set it with `db:approvers`:
+  ```bash
+  everystack db:approvers --stage production --set "cto,arn:aws:iam::…:user/cto"
+  everystack db:approvers --stage production --set ''     # disable destructive applies entirely
+  ```
+
+Prefer never to destroy in place. The safe path for removing a column is the **contract
+phase**: `field.deprecated()` first (the column stays readable, new writes are rejected,
+generated types strike it through), then the physical drop later as its own confirmed,
+snapshotted, approver-gated plan.
+
+## Snapshot-first: the safety net
+
+Two backup mechanisms, different shapes — know when to reach for each:
+
+| | `db:snapshot` | `db:backup` |
+|---|---|---|
+| Kind | **Physical** RDS snapshot (whole instance) | **Logical** `pg_dump` of one database → private S3 |
+| Speed to safety | Instant (control-plane, no VPC) | Minutes (dumps the data) |
+| Restore | RDS restore (new instance) — instant DR | `db:restore` INTO a stage; downloadable, portable |
+| Requires | RDS (not Aurora Serverless v2 the same way) | any Postgres reachable by the ops Lambda |
+
+```bash
+everystack db:snapshot  --stage production     # physical, instant — the "oh no" button
+everystack db:snapshots --stage production      # list manual snapshots
+everystack db:backup    --stage production      # logical pg_dump → S3 backups bucket
+everystack db:backups   --stage production      # list logical backups
+everystack db:backup:download <id> --stage production   # presigned download URL (1h)
+```
+
+**RDS snapshot first?** For a destructive apply, `db:apply` already forces a logical backup —
+you cannot destroy without one. But before any large or risky migration on a stage that
+holds real data, take a **physical `db:snapshot` first** as well: it is instant, it captures
+the whole instance, and restoring it is the fastest path back if something the plan didn't
+foresee goes wrong. Cheap insurance; take it.
+
+## Importing data into a REMOTE stage
+
+- **`db:seed --stage dev`** — the declarative seed, dev-tier only (refuses on production).
+- **`pipeline:run --stage <name>`** — the ingest pipeline, credential-free in the ops
+  Lambda. The way to load a real dataset into a deployed stage.
+- **`db:fork --from-stage <src> --stage <tgt> --confirm`** — copy a DEPLOYED stage's
+  database (schema + data) into a feature stage: backup → presigned URL (the cross-stage
+  hand-off) → restore via the target's ops Lambda. **Production is never a target**, and
+  forking FROM a prod-tier stage warns about PII. Use it to get realistic data into a
+  throwaway stage.
+- **`db:restore --from <id> --stage <name> --confirm`** — restore a logical backup INTO a
+  stage. Destructive (it replaces the target), so `--confirm` is required.
+
+## Why `--stage` is the safe boundary
+
+Operator verbs that touch a protected database run their WRITE inside that stage's **ops
+Lambda**, invoked over IAM. The operator's own credentials never resolve the database URL —
+your AWS identity IS the authorization, CloudTrail records the access, and a leaked laptop
+can't dump production. `--database-url` exists only for local dev databases you own outright.
+
+## Command index
+
+```bash
+# Declare (edit files), then:
+everystack db:sync            # dev DB ← your checkout (state + compute), one verb
+everystack db:reconcile       # compute layer only (views/matviews/functions/triggers)
+everystack db:generate        # STATE layer → migration file / --apply / --dry-run
+everystack db:check           # CI gate: declared state composes; artifacts match
+everystack db:fingerprint     # content-address live schema vs models — MATCH/MISMATCH
+
+# Reach a protected stage safely:
+everystack db:plan --stage X --out X.plan.json     # mint a reviewable edge (read-only)
+everystack db:apply --plan X.plan.json --stage X   # verify → apply → verify (credential-free)
+everystack db:approvers --stage X --set "…"        # who may run destructive applies
+
+# Back up / restore:
+everystack db:snapshot --stage X    # physical RDS snapshot (instant DR)
+everystack db:backup   --stage X    # logical pg_dump → S3
+everystack db:restore --from <id> --stage X --confirm
+
+# Local dev databases:
+everystack db:template:refresh      # build the dev template from declared state + seed
+everystack db:branch                # per-branch dev DB from the template
+
+# Data:
+everystack db:seed --stage dev      # declarative seed (dev only)
+everystack db:backfill --apply      # one-shot data moves (db/backfills/*.sql)
+everystack pipeline:run --stage X   # ingest pipeline (credential-free)
+everystack db:fork --from-stage prod --stage feature --confirm   # copy a stage's data
+```

package/dist/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.