@everystack/mcp 0.3.2 → 0.4.0

package/src/resources/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/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,21 @@ 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.
-- **Schema changes have two homes; neither is a hand-written migration.** Tables and authz
-  are generated from Models: declare with `defineModel` (in `db/models/`), run
-  `everystack db:generate` — never hand-write a SQL migration, never edit the generated
-  `db/schema.ts`; after any change `db:generate` must be a clean no-op. Functions, views,
-  and matviews are **authored** in `db/sql/` and **deployed** with `everystack db:reconcile`
-  — edit the SQL file, reconcile, done; `db:reconcile --check` must exit 0.
+- **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
+  pinned by fingerprints at both ends; `db:apply` verifies before and after, requires the
+  checkout to descend from the commit declaring the target's state ("rebase first"), and
+  gates destructive plans: `--confirm` always, snapshot always, the stage's approver set
+  (`db:approvers`) when declared.
 - **Authorization is declared, not hand-written.** Use `can()` abilities on the Model; they
   compile to RLS + grants. Never hand-write `CREATE POLICY`/`GRANT`. RLS is required.
 - **Reuse `@everystack/ui`.** Do not hand-roll a component that already exists there. Style
@@ -35,11 +44,12 @@ 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/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)
-- `db/schema.generated.ts`, `drizzle/` — generated artifacts (do not edit by hand)
+- `db/schema.generated.ts` — generated artifact (never edit; `db:check` refuses drift)
 - `lib/` — shared code (auth context, API client)
 - `sst.config.ts` — AWS infrastructure definition
 - `docs/RUNBOOK.md` — how to operate this app; regenerate with `everystack runbook`
@@ -54,9 +64,12 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 pnpm install                                 # Install dependencies
 pnpm dev                                     # Start the Expo dev server
 pnpm test                                    # Run all tests (TDD)
-everystack db:generate                       # Models → next migration (data + authz)
-everystack db:reconcile --apply              # Deploy functions/views/matviews from db/sql (no migrations)
-everystack db:migrate                        # Apply migrations on the deployed Lambda
+everystack db:sync                           # Dev edit loop: the database follows your checkout (state + authz + derived)
+everystack db:check                          # CI gate: declared state composes; generated artifacts match regeneration
+everystack db:plan | db:apply                # Protected stages: reviewable, fingerprint-verified edges
+everystack db:branch                         # Per-git-branch dev DB from the seeded template (db:template:refresh builds it)
+everystack db:backfill --apply               # Run one-shot data jobs from db/backfills/ (own record)
+everystack db:generate                       # Models → the diff as SQL (review surface)
 everystack db:seed                           # Seed the database (dev only)
 everystack deploy --stage dev                # Deploy infrastructure (SST)
 everystack update --channel production        # OTA update (no redeploy)
@@ -69,12 +82,15 @@ everystack bundle:audit <url>                # Audit a deployed bundle (weight +
 ### Models are the source of truth (v3)
 
 Declare tables with `defineModel` (`field`, `can`, relations). A package's full DB slice is a
-`defineModule`; the app composes Modules. `everystack db:generate` compiles them to one
-migration (schema + RLS + grants); `deriveHandlerConfig(models)` derives the API config. You
+`defineModule`; the app composes Modules. The database's own schema is the authority — the
+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. The derived layer (functions, views, matviews) is the exception that proves the rule:
-that SQL is authored, in `db/sql/`, and *deployed* with `db:reconcile` — hand-edits straight
-against the database surface as drift, and a comment-only edit is a no-op.
+drift; `deriveHandlerConfig(models)` derives the API config. The derived layer (functions,
+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.
 
 ### Security over all else
 
@@ -104,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.