@metaobjectsdev/migrate-ts 0.15.21-rc.1 → 0.16.0-rc.1

package/src/introspect/postgres.ts

@@ -30,6 +30,9 @@ import type { Kysely } from "kysely";
 import { sql } from "kysely";
 import type { SchemaSnapshot, TableDescriptor, ColumnDescriptor, ColumnDefault, IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor, CheckDescriptor } from "../types.js";
 import type { SqlType } from "../sql-type.js";
+import type { DependentRelation } from "../types.js";
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+import { parseFingerprintMarker } from "../view-fingerprint.js";
 import { MIGRATIONS_TABLE } from "../apply/ledger.js";
 import { stripCheckWrapper } from "../check-expr-compare.js";
 
@@ -76,12 +79,32 @@ export async function introspectPostgres(db: Kysely<Record<string, unknown>>): P
  * before matching.
  *
  * If character_maximum_length is available, callers should pass `maxLength`.
+ *
+ * `numeric` carries its qualifier OUT-OF-BAND: `data_type` is a bare "numeric"
+ * for both NUMERIC and NUMERIC(9,4), so callers reading information_schema must
+ * pass `numeric.precision` / `numeric.scale` (from numeric_precision /
+ * numeric_scale) or the qualifier is lost. An inline "numeric(9,4)" string is
+ * still parsed — that form arrives from format_type()/pg_catalog callers and
+ * from unit tests — but it is NOT what information_schema produces.
+ *
+ * Only the numeric/decimal branch consults the qualifier: information_schema
+ * also populates numeric_precision for INTEGER columns (int4 → 32, radix 2),
+ * which has nothing to do with a NUMERIC qualifier.
  */
-export function pgTypeToSqlType(dataType: string, maxLength?: number | null, udtName?: string): SqlType {
+export function pgTypeToSqlType(
+  dataType: string,
+  maxLength?: number | null,
+  udtName?: string,
+  numeric?: { precision: number | null; scale: number | null },
+): SqlType {
   const dt = dataType.toLowerCase().trim();
 
   // Array columns: information_schema reports data_type "ARRAY" and the element
   // type in udt_name with a leading underscore (e.g. "_uuid", "_text", "_varchar").
+  // The element is deliberately left UNQUALIFIED: information_schema reports no
+  // qualifiers for array elements (numeric_precision/character_maximum_length are
+  // NULL when data_type = 'ARRAY'), and the expected side builds unqualified
+  // elements to match (see arrayElementSqlType in expected-schema).
   if (dt === "array" && typeof udtName === "string") {
     const elemUdt = udtName.replace(/^_/, "").toLowerCase();
     return { kind: "array", element: pgTypeToSqlType(elemUdt, maxLength) };
@@ -117,12 +140,20 @@ export function pgTypeToSqlType(dataType: string, maxLength?: number | null, udt
   if (dt === "float4" || dt === "real") return { kind: "real4" };
   if (dt === "float8" || dt === "double precision") return { kind: "real" };
 
-  // Arbitrary-precision numeric — "numeric(p,s)" or bare "numeric"/"decimal"
+  // Arbitrary-precision numeric — "numeric(p,s)" or bare "numeric"/"decimal".
+  // An inline qualifier wins when present; otherwise fall back to the
+  // out-of-band numeric_precision/numeric_scale, which is the only form
+  // information_schema ever gives us. An unconstrained NUMERIC reports both as
+  // NULL and stays a bare { kind: "numeric" }.
   const numMatch = /^(?:numeric|decimal)(?:\((\d+)(?:,\s*(\d+))?\))?$/.exec(dt);
   if (numMatch) {
     const out: SqlType = { kind: "numeric" };
-    if (numMatch[1]) out.precision = parseInt(numMatch[1], 10);
-    if (numMatch[2]) out.scale = parseInt(numMatch[2], 10);
+    const precision = numMatch[1] !== undefined ? parseInt(numMatch[1], 10) : numeric?.precision ?? null;
+    const scale = numMatch[1] !== undefined
+      ? (numMatch[2] !== undefined ? parseInt(numMatch[2], 10) : null)
+      : numeric?.scale ?? null;
+    if (precision !== null) out.precision = precision;
+    if (scale !== null) out.scale = scale;
     return out;
   }
 
@@ -257,10 +288,16 @@ async function readPgViews(k: RawKysely): Promise<ViewDescriptor[]> {
     // `public`) belongs to the extension, not the model — reporting it makes
     // the very next migrate propose `DROP VIEW "pg_stat_statements";`, and
     // dropping it would break the extension.
-    const rows = await sql<{ table_name: string; table_schema: string; view_definition: string | null }>`
+    const rows = await sql<{
+      table_name: string;
+      table_schema: string;
+      view_definition: string | null;
+      view_comment: string | null;
+    }>`
       SELECT c.relname AS table_name,
              n.nspname AS table_schema,
-             pg_get_viewdef(c.oid) AS view_definition
+             pg_get_viewdef(c.oid) AS view_definition,
+             obj_description(c.oid, 'pg_class') AS view_comment
       FROM pg_class c
       JOIN pg_namespace n ON n.oid = c.relnamespace
       WHERE c.relkind = 'v'
@@ -274,34 +311,132 @@ async function readPgViews(k: RawKysely): Promise<ViewDescriptor[]> {
         )
       ORDER BY n.nspname, c.relname
     `.execute(k);
-    return rows.rows.map((r) => {
+
+    const dependents = await readPgViewDependents(k);
+
+    const views: ViewDescriptor[] = [];
+    for (const r of rows.rows) {
       const view: ViewDescriptor = { name: r.table_name, schema: r.table_schema };
+      // The deparsed body. NOT a comparison input on Postgres — pg_get_viewdef
+      // regenerates SQL from the parse tree and can never return the text we wrote.
+      // It IS valid SQL that reproduces the view, so it is the restore payload for a
+      // down migration.
       if (r.view_definition) view.sql = r.view_definition;
-      return view;
-    });
+      // The fingerprint is what the diff actually compares. Absent ⇒ the view carries
+      // no MetaObjects stamp ⇒ hand-written or pre-fingerprint ⇒ the diff fails closed.
+      const marker = parseFingerprintMarker(r.view_comment);
+      if (marker !== null) view.fingerprint = marker.fingerprint;
+      // A view is a relation: information_schema.columns describes its output columns
+      // exactly like a table's, so the same reader gives us the list (and the types)
+      // that decide whether a CREATE OR REPLACE is legal.
+      view.columns = (await readColumns(k, r.table_schema, r.table_name)).map((c) => ({
+        name: c.name,
+        sqlType: c.sqlType,
+      }));
+      views.push(view);
+    }
+
+    // Attach dependents, now that we know which views are managed (fingerprinted) —
+    // a CASCADE that destroys an UNMANAGED object is the dangerous case.
+    const managed = new Set(views.filter((v) => v.fingerprint !== undefined).map((v) => viewKey(v.schema, v.name)));
+    for (const view of views) {
+      const direct = dependents.get(viewKey(view.schema, view.name));
+      if (direct === undefined) continue;
+      view.dependents = direct.map((d) => ({ ...d, managed: managed.has(viewKey(d.schema, d.name)) }));
+    }
+    return views;
   } catch {
     // pg-mem: pg_class/pg_depend catalog introspection not supported — return empty view list.
     return [];
   }
 }
 
+function viewKey(schema: string | undefined, name: string): string {
+  return `${schema ?? DEFAULT_DB_SCHEMA_POSTGRES}.${name}`;
+}
+
+/**
+ * Every view's DIRECT dependents, in one query (no per-view N+1). Keyed by the
+ * depended-ON view; the transitive closure is computed in the diff.
+ *
+ * The catalog gotcha: a view's dependency on the relations it reads is NOT recorded as
+ * view-depends-on-relation. It is recorded as the view's REWRITE RULE (its `_RETURN`
+ * rule in pg_rewrite, which holds the parse tree) depending on each referenced
+ * relation. So finding dependents means joining pg_depend → pg_rewrite → pg_class —
+ * and every view depends on ITSELF through its own `_RETURN` rule, which must be
+ * excluded or a dependency walk never terminates.
+ *
+ * Materialized views (relkind 'm') are included deliberately: migrate does not manage
+ * them, but they can depend on our views and a CASCADE would destroy them anyway.
+ */
+async function readPgViewDependents(k: RawKysely): Promise<Map<string, Omit<DependentRelation, "managed">[]>> {
+  const out = new Map<string, Omit<DependentRelation, "managed">[]>();
+  try {
+    const rows = await sql<{
+      on_schema: string; on_name: string;
+      dep_schema: string; dep_name: string; dep_relkind: string;
+    }>`
+      SELECT ref_ns.nspname   AS on_schema,
+             ref_cl.relname   AS on_name,
+             dep_ns.nspname   AS dep_schema,
+             dep_cl.relname   AS dep_name,
+             dep_cl.relkind   AS dep_relkind
+      FROM pg_depend d
+      JOIN pg_rewrite    r      ON r.oid = d.objid
+      JOIN pg_class      dep_cl ON dep_cl.oid = r.ev_class
+      JOIN pg_namespace  dep_ns ON dep_ns.oid = dep_cl.relnamespace
+      JOIN pg_class      ref_cl ON ref_cl.oid = d.refobjid
+      JOIN pg_namespace  ref_ns ON ref_ns.oid = ref_cl.relnamespace
+      WHERE d.classid    = 'pg_rewrite'::regclass
+        AND d.refclassid = 'pg_class'::regclass
+        AND d.deptype    = 'n'
+        AND ref_cl.relkind = 'v'
+        AND dep_cl.oid <> ref_cl.oid
+        AND ref_ns.nspname NOT IN ('pg_catalog', 'information_schema')
+        AND ref_ns.nspname NOT LIKE 'pg_%'
+    `.execute(k);
+    for (const r of rows.rows) {
+      if (r.dep_relkind !== "v" && r.dep_relkind !== "m") continue;
+      const key = viewKey(r.on_schema, r.on_name);
+      const list = out.get(key) ?? [];
+      list.push({ schema: r.dep_schema, name: r.dep_name, relkind: r.dep_relkind });
+      out.set(key, list);
+    }
+  } catch {
+    // pg-mem: no pg_rewrite. Dependents unknown → treated as none. The real-PG
+    // integration tests are the gate for this path.
+  }
+  return out;
+}
+
 interface RawColumn {
   column_name: string;
   data_type: string;
   udt_name: string;
   character_maximum_length: number | null;
+  numeric_precision: number | null;
+  numeric_scale: number | null;
   is_nullable: string;   // 'YES' | 'NO'
   column_default: string | null;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function readColumns(k: Kysely<any>, schema: string, tableName: string): Promise<ColumnDescriptor[]> {
+  // numeric_precision/_scale are the ONLY place a NUMERIC(p,s) qualifier survives:
+  // information_schema.columns.data_type reports a bare "numeric" for every
+  // NUMERIC column regardless of its qualifier, and character_maximum_length is
+  // NULL for numerics. Selecting them is what lets a `field.decimal @precision
+  // @scale` column converge — without them the expected side says NUMERIC(9,4),
+  // introspection reads back a bare NUMERIC, and the diff reports a (lossy, so
+  // BLOCKED) change-column-type on every single migrate, forever.
   const rows = await sql<RawColumn>`
     SELECT
       column_name,
       data_type,
       udt_name,
       character_maximum_length,
+      numeric_precision,
+      numeric_scale,
       is_nullable,
       column_default
     FROM information_schema.columns
@@ -311,7 +446,10 @@ async function readColumns(k: Kysely<any>, schema: string, tableName: string): P
   `.execute(k);
 
   return rows.rows.map((r) => {
-    const sqlType = pgTypeToSqlType(r.data_type, r.character_maximum_length, r.udt_name);
+    const sqlType = pgTypeToSqlType(r.data_type, r.character_maximum_length, r.udt_name, {
+      precision: r.numeric_precision,
+      scale: r.numeric_scale,
+    });
     const col: ColumnDescriptor = {
       name: r.column_name,
       sqlType,

package/src/snapshot/plan.ts

@@ -2,7 +2,8 @@
 import type { ColumnNamingStrategy, MetaData } from "@metaobjectsdev/metadata";
 import { buildExpectedSchema } from "../expected-schema.js";
 import { diff, type DiffArgs } from "../diff/index.js";
-import type { Dialect, DiffResult, SchemaSnapshot, ViewDescriptor } from "../types.js";
+import type { Dialect, DiffResult, SchemaSnapshot } from "../types.js";
+import type { ExpectedViewInput } from "../expected-schema.js";
 
 export interface PlanOfflineArgs extends Pick<DiffArgs, "allow" | "onAmbiguous" | "ignoreTables"> {
   metadata: MetaData;
@@ -11,7 +12,7 @@ export interface PlanOfflineArgs extends Pick<DiffArgs, "allow" | "onAmbiguous"
   snapshot: SchemaSnapshot;
   columnNamingStrategy?: ColumnNamingStrategy;
   /** Expected views (via codegen-ts `buildProjectionViews`) — threaded into buildExpectedSchema. */
-  views?: readonly ViewDescriptor[];
+  views?: readonly ExpectedViewInput[];
 }
 
 export interface PlanOfflineResult {
@@ -48,7 +49,7 @@ export function baselineFromMetadata(
   metadata: MetaData,
   dialect: Dialect,
   columnNamingStrategy?: ColumnNamingStrategy,
-  views?: readonly ViewDescriptor[],
+  views?: readonly ExpectedViewInput[],
 ): SchemaSnapshot {
   return buildExpectedSchema(metadata, {
     dialect,

package/src/snapshot/serialize.ts

@@ -5,8 +5,22 @@ import type { SchemaSnapshot } from "../types.js";
  * On-disk format version for the committed schema snapshot. Bump when the
  * SchemaSnapshot descriptor gains a field (a DDL-coverage feature); add the
  * matching upgrade branch in parseSnapshot at the same time.
+ *
+ * v3 — ViewDescriptor gained `fingerprint`, `columns` and `dependents`. The
+ * fingerprint is how Postgres decides whether a view is up to date (Postgres deparses
+ * view SQL, so the emitted text can never be compared against what it stores). A
+ * toolchain that does not understand these fields would silently fall back to the old
+ * text comparison and re-propose every view on every migrate — so a v3 snapshot must
+ * hard-fail on an older reader rather than be quietly misread. Reading an OLDER (v2)
+ * snapshot stays fine: the missing fields read as `undefined`, which every consumer
+ * treats as "unknown" and fails safe on.
+ *
+ * NOTE for anyone touching canonicalize(): a view's `columns` array is ORDER-SENSITIVE.
+ * Postgres allows a non-destructive CREATE OR REPLACE only when the old column list is
+ * a PREFIX of the new one, so sorting that array would destroy the very information the
+ * decision rests on.
  */
-export const SNAPSHOT_FORMAT_VERSION = 2;
+export const SNAPSHOT_FORMAT_VERSION = 3;
 
 interface SnapshotFile {
   formatVersion: number;

package/src/types.ts

@@ -111,6 +111,27 @@ export interface FkDescriptor {
 
 export type FkAction = "cascade" | "set-null" | "restrict" | "no-action";
 
+/** One output column of a view, in SELECT order. */
+export interface ViewColumnDescriptor {
+  name: string;
+  sqlType: SqlType;
+}
+
+/** A relation that depends on a view — i.e. what a `DROP ... CASCADE` would destroy. */
+export interface DependentRelation {
+  schema: string;
+  name: string;
+  /** 'v' = view, 'm' = materialized view. */
+  relkind: "v" | "m";
+  /**
+   * True when this dependent is a view MetaObjects manages (it carries our
+   * fingerprint). A managed dependent that the same migration recreates is
+   * harmless; an UNMANAGED one is somebody else's object and a CASCADE destroys
+   * it irrecoverably.
+   */
+  managed: boolean;
+}
+
 export interface ViewDescriptor {
   name: string;
   /** Same semantics as TableDescriptor.schema. */
@@ -119,16 +140,49 @@ export interface ViewDescriptor {
    * View definition SQL.
    *
    * On the EXPECTED side (`buildExpectedSchema` / `buildExpectedViews`) this is
-   * the view body — the SELECT clause through the FROM/WHERE/GROUP-BY tail.
+   * the view body — the SELECT clause through the FROM/WHERE/GROUP-BY tail. It is
+   * the input to `viewFingerprint()`.
+   *
+   * On the ACTUAL side (`introspect`) this is whatever the DB catalog stores.
+   * Its role is DIALECT-DEPENDENT, and this is load-bearing:
    *
-   * On the ACTUAL side (`introspect`) this is whatever the DB catalog stores:
-   * sqlite's `sqlite_master.sql` is the full `CREATE VIEW <name> AS <body>`
-   * statement, while Postgres' `information_schema.views.view_definition` is the
-   * body only. `diff`'s view-body comparator normalizes both sides (strips any
-   * leading `CREATE VIEW ... AS`, collapses whitespace) before comparing, so a
-   * body change triggers a `replace-view`.
+   *   - SQLite/D1 store `sqlite_master.sql` VERBATIM — the exact text we wrote —
+   *     so there the body is a sound basis for comparison (`viewSqlEquals`).
+   *
+   *   - Postgres does NOT store view SQL. It stores the parse tree, and
+   *     `pg_get_viewdef()` DEPARSES it back into Postgres's own canonical style
+   *     (lowercased functions, `LEFT OUTER JOIN` → `LEFT JOIN`, parenthesized FROM
+   *     items and ON predicates, dropped redundant aliases). It can never equal
+   *     what we emitted, so on Postgres the body is NOT used for comparison —
+   *     `fingerprint` is. The deparsed body is still carried, as the RESTORE
+   *     payload for a down migration (it is valid SQL that reproduces the view).
    */
   sql?: string;
+  /**
+   * Content hash of the generated body — `metaobjects:v1:sha256:<hex>` — stamped
+   * into the view's `COMMENT ON VIEW` at emit time and read back at introspect
+   * time. This, not the body text, is how Postgres decides whether a view is
+   * up to date (see view-fingerprint.ts).
+   *
+   * Absent on the actual side means the view carries NO MetaObjects stamp: either
+   * it is hand-written, or it predates fingerprinting. The two are
+   * indistinguishable on Postgres, so the diff fails CLOSED and blocks pending
+   * `allow.adoptView`.
+   */
+  fingerprint?: string;
+  /**
+   * The view's output columns, in SELECT order. Drives the replace-vs-drop
+   * decision: Postgres permits `CREATE OR REPLACE VIEW` only when the existing
+   * columns are a PREFIX of the new ones (same names, same types, same order,
+   * additions at the end only). Undefined = unknown → fail safe to drop+create.
+   */
+  columns?: readonly ViewColumnDescriptor[];
+  /**
+   * Relations that depend on this view (transitively). Populated on the ACTUAL
+   * side by introspection. A `DROP VIEW` with dependents needs CASCADE, which
+   * destroys every one of them — including views owned by other applications.
+   */
+  dependents?: readonly DependentRelation[];
   /**
    * Physical tables this view reads (base + joined tables). Populated on the
    * EXPECTED side only (the view producer knows the join graph; introspection
@@ -175,8 +229,36 @@ export type Change =
   | { kind: "drop-check"; table: string; schema?: string; check: string; restore?: CheckDescriptor; status: ChangeStatus }
   // Declared for v0.3, never produced in v0.1:
   | { kind: "create-view"; view: ViewDescriptor; schema?: string; status: ChangeStatus }
-  | { kind: "drop-view"; view: string; schema?: string; status: ChangeStatus }
-  | { kind: "replace-view"; view: ViewDescriptor; schema?: string; status: ChangeStatus };
+  | {
+      kind: "drop-view";
+      view: string;
+      schema?: string;
+      status: ChangeStatus;
+      /** The view as it exists in the DB — lets the down migration recreate it. */
+      restore?: ViewDescriptor;
+      /**
+       * Relations a CASCADE would destroy. EXTERNAL dependents only: a managed view
+       * this same migration recreates is filtered out (it comes back). Non-empty ⇒
+       * a plain DROP VIEW would fail at apply, and CASCADE would destroy objects we
+       * do not manage — so this is blocked pending `allow.dropViewCascade`.
+       */
+      dependents?: readonly DependentRelation[];
+    }
+  | {
+      kind: "replace-view";
+      view: ViewDescriptor;
+      schema?: string;
+      status: ChangeStatus;
+      /** The view as it exists in the DB — lets the down migration restore the old body. */
+      restore?: ViewDescriptor;
+      /**
+       * The DB view carries no MetaObjects fingerprint — hand-written, or created
+       * before fingerprinting existed. We cannot tell which (Postgres deparses away
+       * the text evidence), and overwriting a hand-written view destroys SQL no down
+       * migration can recover. Blocked pending `allow.adoptView`.
+       */
+      unmanagedActual?: boolean;
+    };
 
 export type ChangeKind = Change["kind"];
 
@@ -204,6 +286,24 @@ export interface AllowOptions {
    * view is re-created in the same migration).
    */
   dropView?: boolean;
+  /**
+   * Gates `DROP VIEW ... CASCADE`. A view with dependents cannot be dropped plainly
+   * (Postgres refuses), and CASCADE destroys every dependent — including views and
+   * materialized views owned by OTHER applications, which this tool does not manage
+   * and cannot restore. Strictly ADDITIONAL to `dropView`: `--allow drop-view` alone
+   * never cascades, and a plain non-cascading DROP VIEW stays the emitted form
+   * whenever there are no dependents, so Postgres itself backstops a stale
+   * dependents snapshot rather than silently cascading.
+   */
+  dropViewCascade?: boolean;
+  /**
+   * Gates overwriting an existing view that carries NO MetaObjects fingerprint —
+   * i.e. taking ownership of it. It is either hand-written or predates
+   * fingerprinting, and on Postgres those are indistinguishable. Every environment
+   * upgrading from an older toolchain needs exactly one `--allow adopt-view` run to
+   * stamp its existing views; after that they are fingerprinted and silent.
+   */
+  adoptView?: boolean;
   /** Existing data must satisfy NOT NULL; diff cannot verify this. */
   nullableToNotNull?: boolean;
 }

package/src/view-column-types.ts

@@ -0,0 +1,110 @@
+// view-column-types.ts — resolve a view's output columns to SqlTypes.
+//
+// Needed to decide whether a view change is non-destructively REPLACEABLE. Postgres
+// permits `CREATE OR REPLACE VIEW` only when the existing output columns are a prefix
+// of the new ones on (name, type, position); getting the types wrong would make the
+// diff propose an OR REPLACE that Postgres rejects at APPLY time
+// ("cannot change data type of view column ..."), aborting the migration mid-flight
+// with no plan-time warning. So every resolution failure here degrades to `undefined`
+// — "unknown" — which the diff treats as not-replaceable and routes through a gated,
+// loud drop+create. Wrong-but-confident is the only outcome we must never produce.
+
+import type { SqlType } from "./sql-type.js";
+import { sqlTypeEquals } from "./sql-type.js";
+import type { TableDescriptor, ViewColumnDescriptor } from "./types.js";
+
+/** The codegen-side description of a view column: physical, but untyped. */
+export type ExpectedViewColumnInput =
+  | { kind: "passthrough"; name: string; sourceTable: string; sourceColumn: string }
+  | { kind: "aggregate"; name: string; sourceTable: string; sourceColumn: string; agg: string };
+
+/**
+ * Can `existing` be turned into `target` with a `CREATE OR REPLACE VIEW`?
+ *
+ * Postgres permits it only when the new query produces the same columns as the existing
+ * view — same names, same types, same order — with additions allowed at the END.
+ * Formally: `existing` must be a PREFIX of `target`.
+ * https://www.postgresql.org/docs/current/sql-createview.html
+ *
+ * Used in BOTH directions. Forward (target = expected, existing = live) it decides
+ * replace-vs-drop. Backward, in a down migration (target = the old view, existing = the
+ * one we just created), it decides the same thing — and usually says NO, because undoing
+ * an append means REMOVING a column, which OR REPLACE cannot do.
+ *
+ * Fails SAFE: unknown columns on either side → false → the caller uses drop+create.
+ * A wrong "yes" is not a failed check, it is a statement Postgres rejects at APPLY time,
+ * aborting the migration with no plan-time warning.
+ */
+export function viewReplaceIsLegal(
+  target: readonly ViewColumnDescriptor[] | undefined,
+  existing: readonly ViewColumnDescriptor[] | undefined,
+): boolean {
+  if (target === undefined || existing === undefined) return false;
+  if (existing.length > target.length) return false;
+  return existing.every((ec, i) => {
+    const tc = target[i]!;
+    return ec.name === tc.name && sqlTypeEquals(ec.sqlType, tc.sqlType);
+  });
+}
+
+/**
+ * Postgres aggregate result types. Not the argument type — `count(int)` is bigint and
+ * `avg(int)` is numeric — so a naive "same as input" rule would mis-type the column and
+ * mis-plan the replace.
+ *
+ * https://www.postgresql.org/docs/current/functions-aggregate.html
+ */
+function aggregateResultType(agg: string, arg: SqlType | undefined): SqlType | undefined {
+  switch (agg) {
+    // count() is bigint regardless of its argument — it need not even resolve.
+    case "count":
+      return { kind: "integer", bits: 64 };
+    case "min":
+    case "max":
+      return arg; // same as the argument type
+    case "sum":
+      if (arg === undefined) return undefined;
+      if (arg.kind === "integer") {
+        // smallint/integer → bigint; bigint → numeric (sum can overflow).
+        return arg.bits === 64 ? { kind: "numeric" } : { kind: "integer", bits: 64 };
+      }
+      // numeric → numeric, real → real, double → double.
+      if (arg.kind === "numeric" || arg.kind === "real" || arg.kind === "real4") return arg;
+      return undefined;
+    case "avg":
+      if (arg === undefined) return undefined;
+      if (arg.kind === "integer" || arg.kind === "numeric") return { kind: "numeric" };
+      if (arg.kind === "real" || arg.kind === "real4") return { kind: "real" };
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Resolve every view column against the expected TABLE descriptors.
+ *
+ * Returns undefined if ANY column cannot be resolved — a partial list is worse than
+ * none, because the prefix comparison would silently compare the wrong positions.
+ */
+export function resolveViewColumns(
+  inputs: readonly ExpectedViewColumnInput[] | undefined,
+  tables: readonly TableDescriptor[],
+): ViewColumnDescriptor[] | undefined {
+  if (inputs === undefined || inputs.length === 0) return undefined;
+
+  const byTable = new Map(tables.map((t) => [t.name, t] as const));
+  const columnType = (table: string, column: string): SqlType | undefined =>
+    byTable.get(table)?.columns.find((c) => c.name === column)?.sqlType;
+
+  const out: ViewColumnDescriptor[] = [];
+  for (const input of inputs) {
+    const arg = columnType(input.sourceTable, input.sourceColumn);
+    const sqlType = input.kind === "aggregate"
+      ? aggregateResultType(input.agg, arg)
+      : arg;
+    if (sqlType === undefined) return undefined;
+    out.push({ name: input.name, sqlType });
+  }
+  return out;
+}

package/src/view-fingerprint.ts

@@ -0,0 +1,97 @@
+// view-fingerprint.ts — how Postgres decides whether a managed view is up to date.
+//
+// WHY THIS EXISTS
+//
+// Postgres does not store view SQL. It stores the parse tree (as the view's `_RETURN`
+// rewrite rule), and `pg_get_viewdef()` DEPARSES that back into Postgres's own
+// canonical style. For one of our generated projection views, live PG 16 returns:
+//
+//   we emit :  SELECT p.id AS "programId", COUNT(DISTINCT w.id) AS "weekCount"
+//                FROM programs p LEFT OUTER JOIN weeks w ON w."programId" = p.id
+//   PG says :  SELECT p.id AS "programId", count(DISTINCT w.id) AS "weekCount"
+//                FROM (programs p LEFT JOIN weeks w ON ((w."programId" = p.id)))
+//
+// — lowercased functions, LEFT OUTER JOIN rewritten, FROM item and ON predicate
+// parenthesized. No textual normalizer can bridge that without reimplementing the
+// deparser, so comparing our text against PG's text ALWAYS reports a difference. That
+// is what made `replace-view` fire on every migrate for every view, forever, and kept
+// `verify --db` permanently red for any project with a projection.
+//
+// THE FIX: never compare against the deparser. Hash the body WE generate, stamp the
+// hash into the view's COMMENT at emit time, and read the stamp back at introspect
+// time. Both sides of the comparison then come from the same emitter, and the
+// deparsed body is never an input.
+//
+// The deparsed body is still useful — it is valid SQL that reproduces the view — so it
+// is carried as the RESTORE payload for down migrations.
+//
+// SQLite/D1 need none of this: `sqlite_master.sql` is the verbatim text we wrote, so
+// the body comparator (view-sql-compare.ts) is exact there.
+
+import { createHash } from "node:crypto";
+
+/**
+ * Marker format version. Bump ONLY if the normalization rules or the marker grammar
+ * change — i.e. if the same body would hash differently. The algorithm is tagged
+ * separately (`sha256:`), so swapping algorithms does not need a version bump.
+ */
+export const FINGERPRINT_FORMAT_VERSION = 1;
+
+const MARKER_PREFIX = "metaobjects";
+
+/** Trailing-line marker: any human comment text may sit ABOVE it. */
+const MARKER_RE = /(?:^|\n)metaobjects:v(\d+):sha256:([0-9a-f]{64})\s*$/;
+
+const CREATE_VIEW_PREFIX =
+  /^\s*create\s+(?:or\s+replace\s+)?(?:temp(?:orary)?\s+)?view\s+(?:if\s+not\s+exists\s+)?[^\s(]+(?:\s*\([^)]*\))?\s+as\s+/i;
+
+/**
+ * Canonicalize a view body for hashing.
+ *
+ * Collapses whitespace (so reindenting the emitter does not re-stamp every deployed
+ * view) and strips an optional CREATE VIEW wrapper and trailing semicolon — and
+ * NOTHING else.
+ *
+ * Deliberately does NOT lowercase, unlike `normalizeViewSql`. That lowercasing exists
+ * only to chase Postgres's deparser, and it masks drift inside case-sensitive string
+ * literals — which `origin.aggregate @filter` predicates now carry (`status = 'Active'`
+ * and `status = 'active'` are different views). We never chase the deparser here, so
+ * there is nothing to buy and real drift to lose.
+ */
+export function normalizeForFingerprint(body: string): string {
+  return body
+    .replace(CREATE_VIEW_PREFIX, "")
+    .replace(/\s+/g, " ")
+    .replace(/;\s*$/, "")
+    .trim();
+}
+
+/** sha256 of the normalized body, lowercase hex. */
+export function viewFingerprint(body: string): string {
+  return createHash("sha256").update(normalizeForFingerprint(body), "utf8").digest("hex");
+}
+
+/** The marker line stamped into `COMMENT ON VIEW`. */
+export function renderFingerprintMarker(fingerprint: string): string {
+  return `${MARKER_PREFIX}:v${FINGERPRINT_FORMAT_VERSION}:sha256:${fingerprint}`;
+}
+
+/**
+ * Read a fingerprint marker out of a view's comment.
+ *
+ * Returns null when there is no marker — meaning the view carries no MetaObjects
+ * stamp and is therefore either hand-written or older than fingerprinting. Callers
+ * MUST fail closed on null: on Postgres those two cases are indistinguishable, and
+ * overwriting the first destroys hand-written SQL nothing can restore.
+ *
+ * An unknown VERSION still parses (the view is ours, stamped by a different
+ * toolchain) — the caller re-stamps it, which makes format migration self-healing.
+ */
+export function parseFingerprintMarker(
+  comment: string | null | undefined,
+): { version: number; fingerprint: string } | null {
+  if (typeof comment !== "string" || comment.length === 0) return null;
+  const m = MARKER_RE.exec(comment.trim());
+  if (m === null) return null;
+  return { version: parseInt(m[1]!, 10), fingerprint: m[2]! };
+}