@@ -139,6 +139,50 @@ class MetadataExposedConfig(private val dataSource: DataSource) {
 }
 ```
 
+## Migrating views (projections)
+
+A projection's `CREATE VIEW` is generated from its `origin.*` children, so `meta migrate`
+owns the view. Three things are worth knowing.
+
+**Append projection fields; don't insert them.** Postgres can update a view in place
+(`CREATE OR REPLACE VIEW`) only when the existing output columns are unchanged and any
+new ones are added at the **end**. A view's columns come out in projection *declaration*
+order, so:
+
+- adding a field **at the end** of a projection → non-destructive replace. Dependent
+  views, grants, and the view's identity all survive.
+- inserting a field **in the middle**, reordering, renaming, or removing one → the view
+  must be **dropped and recreated**, which is destructive to anything that depends on it
+  and is therefore gated (`--allow drop-view`).
+
+Body-only changes — a different join path, an `origin.aggregate @filter`, a changed
+aggregate that keeps the same result type — are always non-destructive.
+
+**A cascading drop is blocked, loudly.** If dropping a view would destroy dependent
+objects — another application's view, a materialized view — `meta migrate` blocks and
+names every one of them. Proceeding requires `--allow drop-view,drop-view-cascade`, and
+the emitted migration carries a `WARNING: CASCADE DROP` banner listing what it destroys.
+MetaObjects does not manage those objects and cannot restore them. `--allow drop-view`
+**alone never cascades.**
+
+**One-time upgrade step (`--allow adopt-view`).** Managed views carry a MetaObjects
+fingerprint in their `COMMENT ON VIEW`; that fingerprint — not the view's SQL text — is
+how migrate knows whether a view is current. (It cannot use the text: Postgres does not
+store view SQL, it stores a parse tree and regenerates the SQL in its own style, so what
+you wrote never comes back.) A view with **no** fingerprint is either hand-written or was
+created before fingerprinting existed, and those are indistinguishable — so migrate fails
+closed rather than overwrite somebody's hand-written SQL:
+
+```
+meta migrate --allow adopt-view      # once per environment, after upgrading
+```
+
+That stamps the existing views. Afterwards they converge silently. This is also what
+closes the loop on the doctrine in
+[downstream-metadata-decisions.md](downstream-metadata-decisions.md): a hand-written view
+sitting where a projection expects one is now **visible to `meta verify --db`** as drift,
+instead of being silently invisible to it.
+
 ## Verified by
 
 The following conformance fixtures gate this feature's behavior across ports:
@@ -148,6 +192,7 @@ The following conformance fixtures gate this feature's behavior across ports:
 - [`bootstrap-canonical-from-empty.yaml`](../../fixtures/persistence-conformance/migrations/bootstrap-canonical-from-empty.yaml) — full-CREATE bootstrap from an empty database
 - [`add-nullable-column.yaml`](../../fixtures/persistence-conformance/migrations/add-nullable-column.yaml) — incremental `ALTER TABLE … ADD COLUMN` for a new nullable field
 - [`drop-table-blocked-without-allow.yaml`](../../fixtures/persistence-conformance/migrations/drop-table-blocked-without-allow.yaml) — destructive operations require an explicit allow-flag
+- [`noop-converged-canonical.yaml`](../../fixtures/persistence-conformance/migrations/noop-converged-canonical.yaml) — **the idempotence gate**: apply the whole canonical schema, then diff the same metadata against the database it just produced. A converged schema must emit **zero** SQL. This is what catches any asymmetry between what `emit` writes, what `introspect` reads back, and what the expected schema models — the class of bug that makes `meta migrate` re-propose (and on SQLite, destructively rebuild) unchanged tables forever.
 
 **Template drift (`fixtures/verify-conformance/`)** — the `Renderer.verify` engine
 asserts that every variable, section, partial, and required-tag in a template
 
@@ -148,6 +148,7 @@ CREATE VIEW "v_program" AS
     p.title AS title,
     p.status AS status
   FROM programs p;
+COMMENT ON VIEW "v_program" IS 'metaobjects:v1:sha256:0338b5e7329eb5d951e6d2311bde8d4c95d71204cac6aa895a903d7b7b5cbab4';
 
 CREATE VIEW "v_program_stat" AS
   SELECT
@@ -160,3 +161,4 @@ CREATE VIEW "v_program_stat" AS
   FROM programs p
   LEFT OUTER JOIN weeks w ON w."programId" = p.id
   GROUP BY p.id;
+COMMENT ON VIEW "v_program_stat" IS 'metaobjects:v1:sha256:9120c9f8899e257b52a087c4841b8e55f679d7f9c7a6e58d8823912855f2ab57';
@@ -0,0 +1,29 @@
+name: noop-converged-canonical
+description: |
+  IDEMPOTENCE GATE. Apply the full canonical schema, then immediately diff the
+  SAME canonical metadata against the database it just produced. A converged
+  schema must produce ZERO migration SQL.
+
+  This is the cheapest structural gate in the corpus, and the one whose absence
+  let a family of destructive migrate bugs survive: every other migration
+  scenario applies once and then queries ROWS, so `emit` and `introspect` were
+  never in the same room. Anything emit writes that introspect reads back
+  differently — a synthesized DEFAULT, a normalized type, a dropped index
+  predicate — shows up here as phantom SQL on a schema with no metadata change.
+
+  Concretely, this catches: a uuid-PK table whose emit-time `gen_random_uuid()`
+  DEFAULT is read back as a real default and diffed against an expected side
+  that models uuid generation as `identity` (→ change-column-default on EVERY
+  migrate, forever, and on SQLite/D1 a full destructive table rebuild); an index
+  whose `@where` / `@expr` / `@orders` are dropped on emit; a boolean or string
+  default that round-trips through the engine in a different literal form.
+
+  Keep this scenario asserting NOTHING but emptiness — its value is that it
+  cannot be satisfied by agreeing with itself.
+
+seed-metadata: ../canonical/
+target-metadata: ../canonical/
+
+expect:
+  blocked: []
+  up-empty: true
@@ -65,7 +65,8 @@ MIGRATE FLAGS:
   --slug <name>        Required when changes are present (e.g., --slug add-user-shipping)
   --allow <csv>        Comma-separated destructive-change permissions:
                        drop-column,drop-table,type-change,drop-index,drop-fk,
-                       drop-check,drop-view,nullable-to-not-null
+                       drop-check,drop-view,drop-view-cascade,
+                       adopt-view,nullable-to-not-null
   --on-ambiguous abort|rename|drop-add
                        How to handle ambiguous renames (default: abort)
   --from-db            Introspect live DB instead of using the committed snapshot
 
@@ -69,7 +69,8 @@ MIGRATE FLAGS:
   --slug <name>         Required when changes are present (e.g., add-user-shipping)
   --allow <csv>         Comma-separated destructive-change permissions:
                         drop-column,drop-table,type-change,drop-index,drop-fk,
-                        drop-check,drop-view,nullable-to-not-null
+                        drop-check,drop-view,drop-view-cascade,
+                        adopt-view,nullable-to-not-null
   --on-ambiguous abort|rename|drop-add   Default abort
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1)
 
@@ -18,6 +18,10 @@ const ALLOW_TOKEN_MAP: Record<string, keyof AllowOptions> = {
   // drop-view gates a REAL view removal (the diff's internal drop/create
   // recreate pair around a column change is not gated).
   "drop-view": "dropView",
+  // Gates DROP VIEW ... CASCADE. Additional to drop-view, never implied by it.
+  "drop-view-cascade": "dropViewCascade",
+  // Gates overwriting an unfingerprinted (hand-written or pre-fingerprint) view.
+  "adopt-view": "adoptView",
   "nullable-to-not-null": "nullableToNotNull",
 };
 
 
@@ -168,6 +168,16 @@ const ALLOW_TOKENS = [
   // drop/create recreate pair around a column change is not gated).
   "drop-check",
   "drop-view",
+  // drop-view-cascade is STRICTLY ADDITIONAL to drop-view: it permits
+  // `DROP VIEW ... CASCADE`, which destroys every dependent object — including
+  // views and materialized views owned by OTHER applications, which this tool
+  // neither manages nor can restore. `--allow drop-view` alone never cascades.
+  "drop-view-cascade",
+  // adopt-view permits overwriting an existing view that carries no MetaObjects
+  // fingerprint — i.e. taking ownership of a hand-written view, or of one created
+  // before fingerprinting existed. Every environment upgrading from an older
+  // toolchain needs this exactly once, to stamp its existing views.
+  "adopt-view",
   "nullable-to-not-null",
 ] as const;
 type AllowToken = (typeof ALLOW_TOKENS)[number];
 
@@ -63,7 +63,8 @@ MIGRATE FLAGS:
   --slug <name>         Required when changes are present (e.g., add-user-shipping)
   --allow <csv>         Comma-separated destructive-change permissions:
                         drop-column,drop-table,type-change,drop-index,drop-fk,
-                        drop-check,drop-view,nullable-to-not-null
+                        drop-check,drop-view,drop-view-cascade,
+                        adopt-view,nullable-to-not-null
   --on-ambiguous abort|rename|drop-add   Default abort
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1)
 
@@ -9,6 +9,7 @@
 // drift / snapshot as the `views` input. This is the ONE place view SQL is produced.
 
 import {
+  type AggregateFunction,
   type MetaData,
   MetaRoot,
   MetaSource,
@@ -19,10 +20,28 @@ import {
 import { isProjection } from "./projection-detector.js";
 import { extractViewSpec } from "./extract-view-spec.js";
 import { emitViewDdl } from "./view-ddl-emit.js";
-import type { JoinNode, JoinTree } from "./view-spec.js";
+import type { JoinNode, JoinTree, ViewSpec } from "./view-spec.js";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
 
 /** Structurally matches migrate-ts's `ViewDescriptor` (name + body sql + optional schema). */
+/**
+ * One output column of the view, in SELECT order, described PHYSICALLY (table +
+ * column, not entity + field).
+ *
+ * migrate-ts resolves each of these to a `SqlType` against its own expected table
+ * descriptors. Deliberately no SqlType here: codegen-ts stays ignorant of migrate
+ * concerns, and migrate-ts stays ignorant of metadata traversal — the existing
+ * layering (migrate-ts never imports codegen-ts; the CLI threads views in).
+ *
+ * Postgres allows a non-destructive `CREATE OR REPLACE VIEW` only when the existing
+ * output columns are a PREFIX of the new ones (same names, same types, same order).
+ * That decision cannot be made without knowing the column list, which is why it is
+ * carried here.
+ */
+export type ExpectedViewColumn =
+  | { kind: "passthrough"; name: string; sourceTable: string; sourceColumn: string }
+  | { kind: "aggregate"; name: string; sourceTable: string; sourceColumn: string; agg: AggregateFunction };
+
 export interface ExpectedView {
   name: string;
   schema?: string;
@@ -34,6 +53,15 @@ export interface ExpectedView {
    * so the view must be dropped before and recreated after.
    */
   dependsOn: string[];
+  /**
+   * The view's output columns, in SELECT order — i.e. DECLARATION order, since
+   * extractViewSpec walks the projection's children in order. That is exactly the
+   * order Postgres's OR-REPLACE prefix rule wants: a field appended to the
+   * projection lands last, so the change stays non-destructive. (Re-canonicalizing
+   * to, say, alphabetical order would be strictly WORSE — it would scatter an
+   * appended field into the middle and force a destructive drop+create.)
+   */
+  columns: ExpectedViewColumn[];
 }
 
 export interface BuildProjectionViewsOptions {
@@ -82,16 +110,54 @@ export function buildProjectionViews(
     const body = emitViewDdl(spec, { dialect, baseTableName, joinTables, bodyOnly: true });
     const schema = resolveTableSchema(projection);
     const dependsOn = collectDependsOn(spec.joinTree, baseTableName, joinTables);
+    const columns = collectViewColumns(spec, baseTableName, joinTables);
     out.push({
       name: spec.viewName,
       sql: body,
       dependsOn,
+      columns,
       ...(schema !== undefined ? { schema } : {}),
     });
   }
   return out;
 }
 
+/**
+ * The SELECT list as PHYSICAL (table, column) pairs, in emitted order.
+ *
+ * SelectColumn carries a join ALIAS, which means nothing outside this module — so
+ * resolve every alias to its physical table first.
+ */
+function collectViewColumns(
+  spec: ViewSpec,
+  baseTableName: string,
+  joinTables: Readonly<Record<string, string>>,
+): ExpectedViewColumn[] {
+  const aliasToTable = new Map<string, string>([[spec.joinTree.baseAlias, baseTableName]]);
+  const walk = (node: JoinNode): void => {
+    const t = joinTables[node.targetEntity];
+    if (t) aliasToTable.set(node.alias, t);
+    for (const child of node.children) walk(child);
+  };
+  for (const j of spec.joinTree.joins) walk(j);
+
+  const out: ExpectedViewColumn[] = [];
+  for (const c of spec.selectSpec.columns) {
+    const sourceTable = aliasToTable.get(c.sourceAlias);
+    // An unresolvable alias would make the column list a lie, and a wrong list would
+    // make the diff propose an ILLEGAL `CREATE OR REPLACE VIEW` that fails at apply.
+    // Drop the whole list instead: migrate-ts treats an absent list as "unknown" and
+    // fails safe to a gated drop+create.
+    if (sourceTable === undefined) return [];
+    out.push(
+      c.kind === "aggregate"
+        ? { kind: "aggregate", name: c.dbColAlias, sourceTable, sourceColumn: c.sourceColumn, agg: c.agg }
+        : { kind: "passthrough", name: c.dbColAlias, sourceTable, sourceColumn: c.sourceColumn },
+    );
+  }
+  return out;
+}
+
 /** The base table plus every joined table, deduped — the physical tables the view reads. */
 function collectDependsOn(
   joinTree: JoinTree,