migration check rejects invariantId-carrying additive self-edges (NOOP_SELF_EDGE) its own invariants doc sanctions

[teamgbg]

versions

• @prisma/orm-postgres 8.0.0-rc.8
• prisma CLI 8.0.0-rc.8 (dist bundle, skills sync 2026-09-02)

what we hit

A migration package whose from == to (a true contract self-edge) is refused by migration check with MIGRATION.CHECK_NOOP_SELF_EDGE unless it carries an op with operationClass: "data".

But the shipped skill reference (skills/prisma-8/references/... invariants module doc, deriveProvidedInvariants) states the two axes are orthogonal:

Both data-class ops (data-transforms, e.g. backfills) and additive-class opaque DDL (e.g. cipherstash's vendored EQL bundle via installEqlBundleOp) may declare invariantIds: ... an extension can ship additive non-IR-derivable DDL (the only way the planner can know the bundle is already applied is via the invariantId on the marker) without needing to mis-classify it as data-class.

installEqlBundleOp is cited as exactly the sanctioned shape: an additive, non-IR-derivable DDL self-edge whose invariantId records marker bookkeeping. Under the checker's current rule (pkg.ops.some(op => op.operationClass === "data") in the bundle), that package would be flagged NOOP_SELF_EDGE.

our concrete case (not hypothetical)

Two real migrations on a live project, authored the documented way (rawSql with precheck/execute/postcheck + invariantId, self-emitted ops.json + migration.json with populated providedInvariants):

1. ALTER TYPE public.lane_liveness_state ADD VALUE 'capture_declared_off' (+ COMMENT ON TYPE)
2. CREATE OR REPLACE VIEW public.cli_session_liveness AS ... (view bodies are not contract-visible, so a view-body replace can never be a from != to edge)

Both are pure additive DDL. Neither has any honest data component (a view replace has nothing to backfill), so neither can carry a data-class op, so both are refused as "true no-op self-edges" — which they are not: they change database objects and have real postchecks.

A parallel package in the same repo that DOES have a backfill passes, confirming the checker's data-only gate.

ask

Either:

1. Relax the self-edge check to accept self-edges whose ops carry invariantIds (the documented marker-bookkeeping case), or
2. Document that additive-only self-edges are unsupported and give the sanctioned pattern for non-IR-derivable DDL that has no data component (e.g. view-body replaces, enum-value additions that must precede dependent DDL in a separate transaction).

repro sketch

prisma migration new --name x --from <current-hash>   # no contract change
# migration.ts: one rawSql({ operationClass: "additive", invariantId: "ns:thing", precheck, execute, postcheck })
prisma migration check
# -> MIGRATION.CHECK_NOOP_SELF_EDGE

[teamgbg]

Follow-up: measured the boundary precisely (it is sharper than the original report)

We attempted the dataTransform route in full and hit a hard wall. Four measured facts:

1. rawSql ops cannot carry the invariant. invariantId placed in rawSql options reaches ops.json but the collector (deriveProvidedInvariants) does not see it on the applied path — migration check still fails MIGRATION.CHECK_NOOP_SELF_EDGE with the invariantId present in the manifest's providedInvariants.

2. dataTransform is the only invariantId carrier — this.dataTransform(endContract, name, { invariantId, check, run }) compiles and the collector reads it.

3. But run closures must lower through the query builder. A raw-lane tagged template (postgresStatic(...).raw.sql) produces a node the plan lowerer rejects:

   • returned directly: plan.meta.storageHash undefined (not a plan);
   • wrapped via planFromAst(raw..., contract): ast.collectParamRefs is not a function (the raw node is not a lowerable AST).

   The only working run shapes are builder table mutations (db.public.<t>.update(...) with fns.raw fragments inside WHERE/SET — the pattern in our working backfill migration).

4. Catalog DDL has no builder surface. ALTER TYPE ... ADD VALUE, COMMENT ON TYPE, and CREATE OR REPLACE VIEW cannot be expressed as builder table mutations. And a view-body change can never ride a contract edge either: views are absent from the emitted contract, so replacing a view body cannot move the contract hash.

Net: under Prisma 8.0.0-rc.8, a migration whose content is catalog DDL or a view-body replace has NO representable carrier — self-edges require a dataTransform, dataTransforms require builder table mutations, and contract edges cannot see views or non-PSL catalog objects. Our concrete stranded case is exactly the pair: an enum ADD VALUE that must precede (in a separate transaction, per Postgres' unsafe-use rule) a CREATE OR REPLACE VIEW that references the new value.

The escape that would unblock us: allow dataTransform run closures to lower raw statements (a raw-statement plan constructor with a lowerable AST), or a documented raw-DDL operation class for self-edges.