fix(migrate): offline --allow adopt-view drop+creates a structural projection change (#240)

Follow-up to #239. The 0.20.4 fix keyed the legal/illegal CREATE OR REPLACE decision on
BOTH column sets being known. But the OFFLINE (snapshot-based) migrate path diffs against a
pre-fingerprint snapshot that records NO view columns, so `actual.columns` is undefined and
the adopt branch fell back to a non-destructive replace-view — an illegal CREATE OR REPLACE
for a projection whose desired shape is fully known (structural change → rejected at apply).

The decision now keys on the EXPECTED (desired) view's columns only: a known projection runs
`viewReplaceIsLegal`, which fail-safes to `false` (→ drop+create) when the actual columns are
unknown too — exactly the offline adopt case. An opaque `@sql` body (expected columns unknown)
still keeps its non-destructive replace on adoption (#208). #239 online + real-PG round-trip
and the #208 @SQL adopt (view-lifecycle-pg 17/17) are unchanged.

Diagnosed by reproducing the offline path: buildProjectionViews/buildExpectedSchema DO
populate expected columns; it's the snapshot ACTUAL side that lacks them.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014xy8powhHYJ6gfFt9Ut8dL

Author: dmealing

CHANGELOG.md

@@ -5,6 +5,22 @@ here. The format follows [Keep a Changelog](https://keepachangelog.com/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 (pre-1.0; MINOR bumps may introduce breaking changes with notice).
 
+## [Unreleased]
+
+### Fixed — offline `--allow adopt-view` illegal `CREATE OR REPLACE` for a projection (#240)
+
+**npm-only** (`migrate-ts`). Follow-up to #239: the 0.20.4 fix keyed the legal/illegal
+`CREATE OR REPLACE` decision on **both** column sets being known, but the OFFLINE
+(snapshot-based) migrate path — the primary authoring path — diffs against a pre-fingerprint
+snapshot that records **no view columns**, so `actual.columns` is undefined and the adopt
+branch fell back to a non-destructive `replace-view` (= illegal `CREATE OR REPLACE`) even for
+a projection whose desired shape is fully known. The decision now keys on the **expected**
+(desired) view's columns only: a known projection runs `viewReplaceIsLegal` (which fail-safes
+to drop+create when the actual columns are unknown), so a structural change drop+creates
+offline too; an opaque `@sql` body (expected columns unknown) still keeps its non-destructive
+replace on adoption. Gated by a diff unit test (expected-known / actual-columns-absent →
+drop+create, still gated on `adoptView`); #208 `@sql` adopt + #239 real-PG round-trip unchanged.
+
 ## [0.20.4] — 2026-07-26
 
 **npm-only** (NuGet `0.19.4` / PyPI `0.19.6` / Maven Central `7.11.4` unchanged — schema

server/typescript/packages/migrate-ts/src/diff/index.ts

@@ -613,15 +613,20 @@ function pushViewUpdate(
 ): void {
   const sx = schemaSpread(expected.schema);
   const adopt = unmanaged ? { unmanagedActual: true as const } : {};
-  // #239: emit a replace only when it is a legal CREATE OR REPLACE. When both column
-  // sets are KNOWN (a projection), that's viewReplaceIsLegal (a prefix-extension) — a
-  // structural change (rename/reorder/mid-insert) is PROVABLY illegal and must be
-  // drop+create. When the columns are UNKNOWN (an opaque `@sql` body), legality is
-  // unprovable: a MANAGED body change still drops+creates (a real change is safest
-  // rebuilt), but an ADOPTION keeps the non-destructive replace — the common
-  // "re-stamp an identical, pre-fingerprint view" case (its behavior before #239).
+  // #239/#240: emit a replace only when it is a legal CREATE OR REPLACE. The decision
+  // keys on the EXPECTED (desired) view's column knowledge, NOT on both sides:
+  //   - EXPECTED columns KNOWN (a projection): run viewReplaceIsLegal. It fails safe to
+  //     `false` (→ drop+create) when the ACTUAL columns are unknown too — which is
+  //     exactly the OFFLINE adopt case (#240): a pre-fingerprint snapshot records no
+  //     view columns, yet the projection's desired shape IS known, so a structural
+  //     change must still drop+create, never an illegal OR REPLACE. (Also fails safe
+  //     when actual is known but non-prefix — the #239 online case.)
+  //   - EXPECTED columns UNKNOWN (an opaque `@sql` body): legality is unprovable. A
+  //     MANAGED change drops+creates (a real body change is safest rebuilt); an ADOPTION
+  //     keeps the non-destructive replace (the common "re-stamp an identical,
+  //     pre-fingerprint hand-written view" case, #208 — its behavior before #239).
   const legal =
-    expected.columns !== undefined && actual.columns !== undefined
+    expected.columns !== undefined
       ? viewReplaceIsLegal(expected.columns, actual.columns)
       : unmanaged;
   if (legal) {

server/typescript/packages/migrate-ts/test/unit/diff.test.ts

@@ -212,6 +212,28 @@ describe("diff — Postgres adopt-view legality (#239)", () => {
     expect(r.changes.find((c) => c.kind === "drop-view")).toBeUndefined();
   });
 
+  test("#240 offline adopt: expected columns KNOWN but actual (old snapshot) has NO columns → drop+create", async () => {
+    // A pre-fingerprint snapshot records no view columns (actual.columns undefined), but
+    // a projection's desired shape IS known. The decision keys on EXPECTED knowledge, so
+    // a structural change still drop+creates — never an illegal CREATE OR REPLACE.
+    const actualNoCols = { name: "v_foo", sql: "SELECT t.a AS a, t.b AS b FROM t" }; // no columns, no fingerprint
+    const r = await diff(
+      { tables: [], views: [expView(["a", "c"])] }, // expected knows [a, c] (b renamed to c)
+      { tables: [], views: [actualNoCols] },
+      opts(true),
+    );
+    expect(r.changes.find((c) => c.kind === "replace-view")).toBeUndefined();
+    expect(r.changes.find((c) => c.kind === "drop-view")).toMatchObject({ kind: "drop-view", view: "v_foo" });
+    expect(r.changes.find((c) => c.kind === "create-view")).toBeDefined();
+    // Still gated on adoptView (unmanagedActual on the drop half).
+    const rBlocked = await diff(
+      { tables: [], views: [expView(["a", "c"])] },
+      { tables: [], views: [actualNoCols] },
+      opts(false),
+    );
+    expect(rBlocked.changes.find((c) => c.kind === "drop-view")?.status.state).toBe("blocked");
+  });
+
   test("OPAQUE @sql body (columns unknown) adopts via non-destructive replace-view, not drop+create", async () => {
     // A hand-written @sql view has no parsed columns, so replace legality is unprovable.
     // The common case is re-stamping an identical pre-fingerprint view (#208), which a