feat(prisma-next): source EQL v3 install SQL from @cipherstash/eql at runtime

Baking the ~1.7 MB install bundle into the v3 baseline migration's ops.json
coupled every @cipherstash/eql upgrade to a prisma-next release: a patch or minor
bump meant re-emitting the migration and cutting a new adapter version.

Now @cipherstash/eql is a runtime dependency (^3.0.0). The committed v3 baseline
op carries a sentinel placeholder; the descriptor (control.ts) injects
readInstallSql() from the installed @cipherstash/eql at build time via
withRuntimeEqlSql(). A patch/minor now flows through npm resolution with no
re-emit and no adapter release — mirroring how the stash CLI already sources v3
SQL (#692).

Safe because the v3 baseline is an invariant-only self-edge (from === to): the
install SQL never contributes to the contract-space hash, and
contractSpaceFromJson passes ops through with no integrity check on their
contents (verifyMigrationHash runs only on the disk read path for the user's
repo, never on the in-memory extension descriptor). The apply planner routes on
the cipherstash:install-eql-v3-bundle-v1 invariant, not SQL content.

ops.json drops from 1,717,297 → 1,219 bytes. No user-facing change — EQL still
installs via `prisma-next migration apply`. 600 tests green; build + biome clean.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

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

@@ -0,0 +1,20 @@
+---
+'@cipherstash/prisma-next': minor
+---
+
+Source the EQL v3 install SQL from `@cipherstash/eql` at runtime instead of
+baking it into the baseline migration.
+
+`@cipherstash/eql` is now a runtime dependency (`^3.0.0`). 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. As a
+result, a `@cipherstash/eql` patch or minor release flows through to
+`prisma-next migration apply` via normal dependency resolution — it no longer
+requires re-emitting the migration and cutting a new `@cipherstash/prisma-next`
+release. This mirrors how the `stash` CLI already sources the v3 SQL.
+
+No change to user-facing behaviour: EQL still installs as part of
+`prisma-next migration apply`. Safe because the v3 baseline is an
+invariant-only self-edge — the install SQL never contributes to the
+contract-space hash.

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

@@ -5,5 +5,5 @@
     "cipherstash:install-eql-v3-bundle-v1"
   ],
   "createdAt": "2026-07-14T20:10:24.325Z",
-  "migrationHash": "sha256:d1ca5a987ab10eb85c2fe05700134b31f17f694d2d5b3df3969e902610b1d9cf"
+  "migrationHash": "sha256:55f261c28b9fe8feee21270a652d758a5c90ccbe7aac9cc79ac50662b956160b"
 }

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

@@ -2,13 +2,14 @@
 /**
  * CipherStash v3 baseline migration — install the EQL v3 bundle.
  *
- * The install SQL is sourced at EMIT time from `@cipherstash/eql/sql`
- * (see `../../src/migration/eql-bundle-v3.ts` — the same source the
- * stack's `installEqlV3IfNeeded` uses) and baked into `ops.json`
- * byte-for-byte. 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.
+ * 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 an
+ * EQL patch/minor flows through npm with no re-emit or re-release. 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
  * it is an **invariant-only edge**: the v3 bundle declares no
@@ -32,7 +33,7 @@ import {
 } from '@prisma-next/target-postgres/migration'
 import { CIPHERSTASH_V3_INVARIANTS } from '../../src/extension-metadata/constants-v3'
 import {
-  readInstallSql,
+  RUNTIME_EQL_SQL_SENTINEL,
   releaseManifest,
 } from '../../src/migration/eql-bundle-v3'
 
@@ -67,7 +68,15 @@ export default class M extends Migration {
         invariantId: CIPHERSTASH_V3_INVARIANTS.installBundle,
         target: { id: 'postgres' },
         precheck: [],
-        execute: [{ description: INSTALL_LABEL, sql: readInstallSql() }],
+        // Placeholder only — the real install SQL is injected at descriptor
+        // build time from the installed `@cipherstash/eql` (see
+        // `../../src/migration/eql-bundle-v3.ts` `withRuntimeEqlSql`), so the
+        // ~1.7 MB bundle is NOT baked into `ops.json` and an EQL patch/minor
+        // needs no re-emit or re-release. Safe because this is an
+        // invariant-only self-edge: the SQL never moves the contract hash.
+        execute: [
+          { description: INSTALL_LABEL, sql: RUNTIME_EQL_SQL_SENTINEL },
+        ],
         postcheck: [
           {
             description: 'verify the "eql_v3" operator schema exists',

packages/prisma-next/migrations/20260601T0100_install_eql_v3_bundle/ops.json

@@ -85,6 +85,7 @@
 		"clean": "rm -rf dist coverage .tmp-output"
 	},
 	"dependencies": {
+		"@cipherstash/eql": "^3.0.0",
 		"@cipherstash/stack": "workspace:*",
 		"@prisma-next/contract": "0.14.0",
 		"@prisma-next/family-sql": "0.14.0",
@@ -99,7 +100,6 @@
 		"arktype": "^2.2.3"
 	},
 	"devDependencies": {
-		"@cipherstash/eql": "3.0.0",
 		"@cipherstash/test-kit": "workspace:*",
 		"@prisma-next/adapter-postgres": "0.14.0",
 		"@prisma-next/cli": "0.14.0",

packages/prisma-next/package.json

@@ -66,6 +66,7 @@ import {
   cipherstashStringCodecHooks,
 } from '../migration/cipherstash-codec'
 import { cipherstashV3CodecControlHooks } from '../migration/cipherstash-codec-v3'
+import { withRuntimeEqlSql } from '../migration/eql-bundle-v3'
 
 const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
   contractJson,
@@ -86,7 +87,12 @@ const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
     {
       dirName: CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
       metadata: v3BaselineMetadata,
-      ops: v3BaselineOps,
+      // 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 an
+      // EQL patch/minor flows through without re-emitting 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),
     },
   ],
   headRef,

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

@@ -1,21 +1,73 @@
 /**
- * CipherStash EQL v3 install SQL, sourced from `@cipherstash/eql/sql` — the
- * same source the stack install script (`packages/stack/scripts/install-eql-v3.ts`
- * / `installEqlV3IfNeeded`) uses. `readInstallSql()` returns the full bundle
- * that creates the `public.eql_v3_*` domains and the `eql_v3.*` operator
- * functions; `releaseManifest.eqlVersion` identifies the pinned release.
+ * CipherStash EQL v3 install SQL, sourced from `@cipherstash/eql/sql` at
+ * RUNTIME — the same source the stack install script (`installEqlV3IfNeeded`)
+ * and the CLI installer (`readV3InstallSql`) use. `readInstallSql()` returns
+ * the full bundle that creates the `public.eql_v3_*` domains and the `eql_v3.*`
+ * operator functions; `releaseManifest.eqlVersion` identifies the pinned
+ * release.
  *
- * The SQL is read at migration EMIT time and baked into the v3 baseline
- * migration's `ops.json`, so `@cipherstash/eql` stays a devDependency of this
- * package (not a runtime dependency of the published artefact). Bumping the
- * pinned `@cipherstash/eql` version requires re-running the maintainer emit
- * loop for `migrations/20260601T0100_install_eql_v3_bundle/` (see that
- * migration's header comment) and re-running `test/descriptor.test.ts` /
- * `test/v3/migration-v3.test.ts`.
+ * ## Runtime-sourced, NOT baked
  *
- * Hash impact: like the v2 bundle (see `./eql-bundle.ts`), the SQL lives in
- * the migration op's `execute[]`, NOT in `contract.json` — the v3 bundle
- * declares no contract-space storage, so the edge is invariant-only and
- * `headRef.hash` does not move.
+ * The v3 baseline migration does **not** embed the ~1.7 MB install SQL in its
+ * `ops.json`. The committed op carries {@link RUNTIME_EQL_SQL_SENTINEL}, and
+ * `src/exports/control.ts` swaps in `readInstallSql()` from the INSTALLED
+ * `@cipherstash/eql` when it builds the descriptor (see {@link withRuntimeEqlSql}).
+ * So `@cipherstash/eql` is a runtime dependency, and a patch/minor bump flows
+ * through npm resolution — no re-emit of the migration, no re-release of this
+ * package. (Baking it in coupled every EQL upgrade to a prisma-next release.)
+ *
+ * Why this is sound: the v3 baseline is an INVARIANT-ONLY self-edge
+ * (`from === to`; the bundle declares no contract-space storage — unlike the v2
+ * bundle's `eql_v2_configuration`). The install SQL therefore never contributes
+ * to the contract-space hash, and `contractSpaceFromJson` passes the ops through
+ * with no integrity check on their contents (`verifyMigrationHash` runs only on
+ * the disk read path for the user's own repo, never on the in-memory extension
+ * descriptor). Swapping the SQL at descriptor-construction time is invisible to
+ * the planner, which routes purely on the `cipherstash:install-eql-v3-bundle-v1`
+ * invariant.
+ */
+import { readInstallSql, releaseManifest } from '@cipherstash/eql/sql'
+
+export { readInstallSql, releaseManifest }
+
+/** The install op's `id` in the v3 baseline `ops.json`. */
+export const V3_INSTALL_OP_ID = 'cipherstash.install-eql-v3-bundle'
+
+/**
+ * Placeholder the committed v3 baseline op carries in `execute[].sql` in place
+ * of the baked install SQL. It is replaced at runtime by {@link withRuntimeEqlSql};
+ * if it ever reached a database directly it is an inert SQL comment.
+ */
+export const RUNTIME_EQL_SQL_SENTINEL =
+  '-- EQL v3 install SQL is injected at runtime from @cipherstash/eql — see packages/prisma-next/src/migration/eql-bundle-v3.ts'
+
+type OpLike = {
+  readonly id?: unknown
+  readonly execute?: ReadonlyArray<{
+    readonly description?: unknown
+    readonly sql?: unknown
+  }>
+}
+
+/**
+ * Return `ops` with the v3 install op's placeholder SQL replaced by the install
+ * SQL from the installed `@cipherstash/eql`. Every other op passes through
+ * untouched. Called by the descriptor in `control.ts` so the applied SQL always
+ * matches the resolved `@cipherstash/eql` version, not a baked snapshot.
  */
-export { readInstallSql, releaseManifest } from '@cipherstash/eql/sql'
+export function withRuntimeEqlSql<T extends OpLike>(ops: readonly T[]): T[] {
+  const sql = readInstallSql()
+  return ops.map((op) =>
+    op.id === V3_INSTALL_OP_ID
+      ? {
+          ...op,
+          execute: [
+            {
+              description: String(op.execute?.[0]?.description ?? ''),
+              sql,
+            },
+          ],
+        }
+      : op,
+  )
+}

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

@@ -2,11 +2,11 @@
  * v3 baseline migration assertions — the on-disk emitted artefacts for
  * `20260601T0100_install_eql_v3_bundle`.
  *
- * The install SQL is sourced at EMIT time from `@cipherstash/eql/sql`
- * (the same source the stack's `installEqlV3IfNeeded` uses) and baked
- * into `ops.json` byte-for-byte. The edge is invariant-only: the v3
- * bundle creates `public.eql_v3_*` domains + `eql_v3.*` functions but
- * no contract-space storage, so `from === to === <v2 baseline head>`.
+ * The install SQL is NOT baked into `ops.json`: the committed op carries a
+ * placeholder, and the descriptor (`control.ts`) injects `readInstallSql()`
+ * from the installed `@cipherstash/eql` at build time. The edge is
+ * 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 { readInstallSql, releaseManifest } from '@cipherstash/eql/sql'
 import { describe, expect, it } from 'vitest'
@@ -20,11 +20,13 @@ import v3Ops from '../../migrations/20260601T0100_install_eql_v3_bundle/ops.json
   type: 'json',
 }
 import headRef from '../../migrations/refs/head.json' with { type: 'json' }
+import cipherstashDescriptor from '../../src/exports/control'
 import { CIPHERSTASH_INVARIANTS } from '../../src/extension-metadata/constants'
 import {
   CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
   CIPHERSTASH_V3_INVARIANTS,
 } from '../../src/extension-metadata/constants-v3'
+import { RUNTIME_EQL_SQL_SENTINEL } from '../../src/migration/eql-bundle-v3'
 
 describe('v3 baseline migration (20260601T0100_install_eql_v3_bundle)', () => {
   it('installs under the v3 invariant with a single data-class rawSql op', () => {
@@ -39,16 +41,34 @@ describe('v3 baseline migration (20260601T0100_install_eql_v3_bundle)', () => {
     expect(op.operationClass).toBe('data')
   })
 
-  it('inlines the @cipherstash/eql install SQL byte-for-byte through ops.json', () => {
+  it('does NOT bake the install SQL into ops.json — it carries the runtime placeholder', () => {
     const op = (
       v3Ops as ReadonlyArray<{
         readonly execute?: ReadonlyArray<{ readonly sql: string }>
       }>
     )[0]!
-    expect(op.execute?.[0]?.sql).toBe(readInstallSql())
+    // The ~1.7 MB bundle must not be committed here — an EQL patch/minor should
+    // not require re-emitting this file. The op carries the sentinel instead.
+    expect(op.execute?.[0]?.sql).toBe(RUNTIME_EQL_SQL_SENTINEL)
+    expect(op.execute?.[0]?.sql).not.toContain('CREATE')
+    expect(JSON.stringify(v3Ops).length).toBeLessThan(5_000)
     expect(releaseManifest.eqlVersion).toBe('3.0.0')
   })
 
+  it('injects readInstallSql() from @cipherstash/eql into the descriptor at build time', () => {
+    // control.ts swaps the placeholder for the install SQL of the INSTALLED
+    // @cipherstash/eql, so the applied SQL always matches the resolved version.
+    const v3Baseline = cipherstashDescriptor.contractSpace.migrations[1]!
+    const op = (
+      v3Baseline.ops as ReadonlyArray<{
+        readonly id: string
+        readonly execute?: ReadonlyArray<{ readonly sql: string }>
+      }>
+    ).find((o) => o.id === 'cipherstash.install-eql-v3-bundle')!
+    expect(op.execute?.[0]?.sql).toBe(readInstallSql())
+    expect(op.execute?.[0]?.sql).toContain('EQL v3 schema creation')
+  })
+
   it('emits no add_search_config / remove_search_config ops', () => {
     const json = JSON.stringify(v3Ops)
     expect(json).not.toContain('add_search_config')