fix(prisma-next): attest runtime EQL migration ops

Author: coderdan

.changeset/prisma-next-eql-runtime-source.md

@@ -11,7 +11,8 @@ two must move together, so an EQL upgrade is a coordinated version bump, not a
 float. The v3 baseline migration no longer embeds the ~1.7 MB install bundle in
 its `ops.json`: the committed op carries a placeholder, and the extension
 descriptor injects `readInstallSql()` from the installed `@cipherstash/eql` when
-it is built.
+it is built, and recomputes the content-addressed migration hash from the
+injected operations before Prisma Next materialises the package.
 
 The win over baking: bumping the pinned `@cipherstash/eql` no longer requires
 re-running the maintainer emit loop to regenerate a 1.7 MB `ops.json` — it is a

packages/prisma-next/migrations/20260601T0100_install_eql_v3_bundle/migration.ts

@@ -5,10 +5,11 @@
  * The install SQL is NOT baked into `ops.json`. The committed op carries
  * `RUNTIME_EQL_SQL_SENTINEL`; `src/exports/control.ts` injects
  * `readInstallSql()` from the installed `@cipherstash/eql` at descriptor-build
- * time (see `../../src/migration/eql-bundle-v3.ts` `withRuntimeEqlSql`), so
- * bumping the pinned `@cipherstash/eql` needs no re-emit of this ~1.7 MB
- * `ops.json`. The bundle creates the 40 `public.eql_v3_*` storage domains, the
- * `eql_v3` operator-function schema (`eql_v3.eq`, `eql_v3.ord_term`, …), the
+ * time and recomputes the migration hash from those runtime ops (see
+ * `../../src/migration/eql-bundle-v3.ts` `withRuntimeEqlSqlPackage`), so bumping
+ * the pinned `@cipherstash/eql` needs no re-emit of this ~1.7 MB `ops.json`.
+ * The bundle creates the 40 `public.eql_v3_*` storage domains, the `eql_v3`
+ * operator-function schema (`eql_v3.eq`, `eql_v3.ord_term`, …), the
  * `eql_v3.query_*` operand domains, and the `eql_v3_internal` helper schema.
  *
  * This is the SECOND migration in the cipherstash contract space, and

packages/prisma-next/src/exports/control.ts

@@ -66,7 +66,12 @@ import {
   cipherstashStringCodecHooks,
 } from '../migration/cipherstash-codec'
 import { cipherstashV3CodecControlHooks } from '../migration/cipherstash-codec-v3'
-import { withRuntimeEqlSql } from '../migration/eql-bundle-v3'
+import { withRuntimeEqlSqlPackage } from '../migration/eql-bundle-v3'
+
+const v3BaselineRuntimePackage = withRuntimeEqlSqlPackage(
+  v3BaselineMetadata,
+  v3BaselineOps,
+)
 
 const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
   contractJson,
@@ -86,13 +91,13 @@ const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
     // `remove_search_config` ops.
     {
       dirName: CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
-      metadata: v3BaselineMetadata,
+      metadata: v3BaselineRuntimePackage.metadata,
       // The committed `ops.json` carries a placeholder in place of the ~1.7 MB
       // install SQL; inject it here from the installed `@cipherstash/eql` so
-      // bumping the pinned EQL version needs no re-emit of the migration. Safe
-      // because this is an invariant-only self-edge — the SQL never touches the
-      // contract hash and `contractSpaceFromJson` does not integrity-check ops.
-      ops: withRuntimeEqlSql(v3BaselineOps),
+      // bumping the pinned EQL version needs no re-emit of the migration. The
+      // helper also recomputes the content-addressed migration hash from the
+      // injected ops so the descriptor can be materialised and verified.
+      ops: v3BaselineRuntimePackage.ops,
     },
   ],
   headRef,

packages/prisma-next/src/migration/eql-bundle-v3.ts

@@ -31,6 +31,12 @@
  * invariant.
  */
 import { readInstallSql, releaseManifest } from '@cipherstash/eql/sql'
+import type {
+  MigrationOperationClass,
+  MigrationPlanOperation,
+} from '@prisma-next/framework-components/control'
+import { computeMigrationHash } from '@prisma-next/migration-tools/hash'
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata'
 
 // Re-exported for the live-test helpers, which read the same install SQL to set
 // up their databases (`test/live/helpers/eql-v3.ts`, `migration-apply-live-pg`).
@@ -67,6 +73,27 @@ function readV3InstallSql(): string {
 
 type ExecuteStep = { readonly sql?: unknown }
 type OpLike = { readonly execute?: ReadonlyArray<ExecuteStep> }
+type HashableOpLike = OpLike & {
+  readonly id: string
+  readonly label: string
+  readonly operationClass: string
+  readonly invariantId?: string
+}
+type RuntimeMigrationMetadata<TMetadata extends MigrationMetadata> = Omit<
+  TMetadata,
+  'migrationHash'
+> & { readonly migrationHash: string }
+
+function isMigrationOperationClass(
+  value: string,
+): value is MigrationOperationClass {
+  return (
+    value === 'additive' ||
+    value === 'widening' ||
+    value === 'destructive' ||
+    value === 'data'
+  )
+}
 
 /**
  * Return `ops` with every placeholder install-SQL step ({@link
@@ -103,3 +130,41 @@ export function withRuntimeEqlSql<T extends OpLike>(ops: readonly T[]): T[] {
       : op,
   )
 }
+
+/**
+ * Build the complete runtime migration package payload atomically. Replacing
+ * the sentinel changes the content-addressed identity of the migration, so the
+ * metadata hash MUST be recomputed from the injected operations before the
+ * descriptor can materialise the package into a user's migration directory.
+ * Keeping both values behind one helper prevents callers from updating the ops
+ * while accidentally retaining the sentinel-derived hash.
+ */
+export function withRuntimeEqlSqlPackage<
+  TMetadata extends MigrationMetadata,
+  TOp extends HashableOpLike,
+>(
+  metadata: TMetadata,
+  ops: readonly TOp[],
+): {
+  readonly metadata: RuntimeMigrationMetadata<TMetadata>
+  readonly ops: TOp[]
+} {
+  const runtimeOps = withRuntimeEqlSql(ops)
+  const hashOps = runtimeOps.map((op): MigrationPlanOperation => {
+    if (!isMigrationOperationClass(op.operationClass)) {
+      throw new Error(
+        `withRuntimeEqlSqlPackage: invalid migration operation class ${JSON.stringify(op.operationClass)}`,
+      )
+    }
+    // Preserve the target-specific fields consumed by canonical JSON hashing
+    // while narrowing the emitted JSON's widened operationClass string.
+    return { ...op, operationClass: op.operationClass }
+  })
+  return {
+    metadata: {
+      ...metadata,
+      migrationHash: computeMigrationHash(metadata, hashOps),
+    },
+    ops: runtimeOps,
+  }
+}

packages/prisma-next/test/live/migration-apply-live-pg.test.ts

@@ -1,25 +1,24 @@
 /**
  * Live-PG apply of the v3 baseline migration bundle.
  *
- * `installEqlV3IfNeeded` applies `readInstallSql()` — and this suite
- * pins that those are byte-for-byte the SQL baked into the shipped
- * migration's `ops.json` (`migrations/20260601T0100_install_eql_v3_bundle`),
- * so a green run here IS a green apply of the customer-facing
+ * `installEqlV3IfNeeded` applies `readInstallSql()` — and this suite pins that
+ * those are byte-for-byte the SQL injected into the shipped control descriptor
+ * at runtime, so a green run here IS a green apply of the customer-facing
  * migration op. After install it verifies the observable contract: the
- * `public.eql_v3_*` storage domains and the `eql_v3` operator schema
- * exist, the op carries the `cipherstash:install-eql-v3-bundle-v1`
- * invariant, the op's own postchecks hold against the live database,
- * and no v2-style `add_search_config` was executed (v3 needs no
- * per-column search configuration).
+ * `public.eql_v3_*` storage domains and the `eql_v3` operator schema exist, the
+ * op carries the `cipherstash:install-eql-v3-bundle-v1` invariant, the op's own
+ * postchecks hold against the live database, and no v2-style
+ * `add_search_config` was executed (v3 needs no per-column search configuration).
  */
 
 import 'dotenv/config'
-import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'pathe'
 import type postgres from 'postgres'
 import { afterAll, beforeAll, expect, it } from 'vitest'
-import { CIPHERSTASH_V3_INVARIANTS } from '../../src/extension-metadata/constants-v3'
+import cipherstashDescriptor from '../../src/exports/control'
+import {
+  CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
+  CIPHERSTASH_V3_INVARIANTS,
+} from '../../src/extension-metadata/constants-v3'
 import {
   readInstallSql,
   releaseManifest,
@@ -28,12 +27,6 @@ import { installEqlV3IfNeeded, uninstallEqlV3 } from './helpers/eql-v3'
 import { liveConnection } from './helpers/harness'
 import { describeLivePg } from './helpers/live-gate'
 
-const MIGRATION_DIR = join(
-  dirname(dirname(dirname(fileURLToPath(import.meta.url)))),
-  'migrations',
-  '20260601T0100_install_eql_v3_bundle',
-)
-
 interface MigrationOp {
   readonly id: string
   readonly invariantId: string
@@ -48,14 +41,14 @@ interface MigrationOp {
   }>
 }
 
-function readOpsFixture(): MigrationOp {
-  const ops = JSON.parse(
-    readFileSync(join(MIGRATION_DIR, 'ops.json'), 'utf8'),
-  ) as MigrationOp[]
-  const op = ops[0]
-  if (ops.length !== 1 || !op) {
+function readRuntimeDescriptorOp(): MigrationOp {
+  const migration = cipherstashDescriptor.contractSpace?.migrations.find(
+    ({ dirName }) => dirName === CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
+  )
+  const op = migration?.ops[0] as MigrationOp | undefined
+  if (migration?.ops.length !== 1 || !op) {
     throw new Error(
-      `expected exactly one op in the v3 baseline migration, got ${ops.length}`,
+      `expected exactly one op in the v3 baseline migration, got ${migration?.ops.length ?? 0}`,
     )
   }
   return op
@@ -79,14 +72,14 @@ describeLivePg('v3 baseline migration bundle against live Postgres', () => {
     if (sql) await sql.end()
   })
 
-  it('the applied SQL is byte-for-byte the shipped migration op, carrying the v3 invariant', () => {
-    const op = readOpsFixture()
+  it('the applied SQL is byte-for-byte the runtime descriptor op, carrying the v3 invariant', () => {
+    const op = readRuntimeDescriptorOp()
     expect(op.id).toBe('cipherstash.install-eql-v3-bundle')
     expect(op.invariantId).toBe(CIPHERSTASH_V3_INVARIANTS.installBundle)
     expect(op.operationClass).toBe('data')
     expect(op.execute).toHaveLength(1)
-    // Byte identity: what installEqlV3IfNeeded just applied IS the
-    // migration bundle a customer's `prisma-next migrate` applies.
+    // Byte identity: what installEqlV3IfNeeded just applied IS the migration
+    // bundle the control descriptor gives to `prisma-next migrate`.
     expect(op.execute[0]?.sql).toBe(readInstallSql())
   })
 
@@ -117,7 +110,7 @@ describeLivePg('v3 baseline migration bundle against live Postgres', () => {
   }, 60_000)
 
   it("the migration op's own postchecks hold against the live database", async () => {
-    const op = readOpsFixture()
+    const op = readRuntimeDescriptorOp()
     expect(op.postcheck.length).toBeGreaterThan(0)
     for (const check of op.postcheck) {
       const rows = (await sql.unsafe(check.sql)) as unknown as Array<

packages/prisma-next/test/v3/migration-v3.test.ts

@@ -8,7 +8,14 @@
  * invariant-only: the v3 bundle creates `public.eql_v3_*` domains + `eql_v3.*`
  * functions but no contract-space storage, so `from === to === <v2 baseline head>`.
  */
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { readInstallSql, releaseManifest } from '@cipherstash/eql/sql'
+import {
+  materialiseMigrationPackage,
+  readMigrationPackage,
+} from '@prisma-next/migration-tools/io'
 import { describe, expect, it } from 'vitest'
 import v2Metadata from '../../migrations/20260601T0000_install_eql_bundle/migration.json' with {
   type: 'json',
@@ -31,6 +38,16 @@ import {
   withRuntimeEqlSql,
 } from '../../src/migration/eql-bundle-v3'
 
+function runtimeV3Baseline() {
+  const migration = cipherstashDescriptor.contractSpace?.migrations.find(
+    ({ dirName }) => dirName === CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
+  )
+  if (!migration) {
+    throw new Error('runtime descriptor is missing the EQL v3 baseline')
+  }
+  return migration
+}
+
 describe('v3 baseline migration (20260601T0100_install_eql_v3_bundle)', () => {
   it('installs under the v3 invariant with a single data-class rawSql op', () => {
     expect(v3Ops).toHaveLength(1)
@@ -63,17 +80,39 @@ describe('v3 baseline migration (20260601T0100_install_eql_v3_bundle)', () => {
   it('injects readInstallSql() from @cipherstash/eql into the descriptor at build time', () => {
     // control.ts swaps the placeholder for the install SQL of the pinned
     // @cipherstash/eql, so the applied SQL always matches the resolved version.
-    const v3Baseline = cipherstashDescriptor.contractSpace!.migrations[1]!
+    const v3Baseline = runtimeV3Baseline()
     const op = (
       v3Baseline.ops as ReadonlyArray<{
         readonly id: string
         readonly execute?: ReadonlyArray<{ readonly sql: string }>
       }>
-    ).find((o) => o.id === 'cipherstash.install-eql-v3-bundle')!
+    ).find((o) => o.id === 'cipherstash.install-eql-v3-bundle')
+    if (!op) throw new Error('runtime descriptor is missing the EQL v3 op')
     expect(op.execute?.[0]?.sql).toBe(readInstallSql())
     expect(op.execute?.[0]?.sql).toContain('EQL v3 schema creation')
   })
 
+  it('materialises the runtime descriptor package and verifies it on read', async () => {
+    // Round-trip property: the exact package Prisma Next receives from the
+    // descriptor must survive its canonical disk writer + integrity-checking
+    // reader. This pins the migration hash to the injected SQL, not the
+    // sentinel committed in the maintainer artefact.
+    const v3Baseline = runtimeV3Baseline()
+    expect(v3Baseline.metadata.migrationHash).not.toBe(v3Metadata.migrationHash)
+
+    const root = await mkdtemp(join(tmpdir(), 'prisma-next-eql-v3-'))
+    try {
+      await materialiseMigrationPackage(root, v3Baseline)
+      const reloaded = await readMigrationPackage(
+        join(root, v3Baseline.dirName),
+      )
+      expect(reloaded.metadata).toEqual(v3Baseline.metadata)
+      expect(reloaded.ops).toEqual(v3Baseline.ops)
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
   it('withRuntimeEqlSql throws if no op carries the sentinel (drift guard)', () => {
     // Matching on the sentinel string (not an op id) makes injection immune to
     // op-id/label drift; a missing sentinel means the emit source and injector