fix(prisma-next): pin @cipherstash/eql exact, sentinel-match + fail-fast injection

Code-review follow-ups on the runtime EQL-SQL sourcing:

- Pin @cipherstash/eql exact (3.0.0), not ^3.0.0. prisma-next's v3 domain TYPES
  come from @cipherstash/stack (which encodes them against a specific EQL
  release); floating the install SQL via a caret would let the applied schema
  drift from the pinned type surface, and diverge from the exact pins in
  @cipherstash/stack and the stash CLI (both install into the same DB). Exact
  keeps types and SQL coherent and still removes the 1.7 MB re-emit coupling —
  the actual win. Reframed the "flows through" wording to "no re-emit" throughout.

- withRuntimeEqlSql now matches the placeholder by its SENTINEL value (not an
  op id) and THROWS if no placeholder is present. Matching an op id required
  three hardcoded copies to agree; a drift silently applied the inert sentinel
  comment as the "install" (empty EQL, caught only by an indirect postcheck, or
  not at all when postchecks are disabled). Sentinel-match is immune to op-id
  drift and fails loudly at descriptor build. Dropped the V3_INSTALL_OP_ID const.

- The SQL read is wrapped (readV3InstallSql) with an actionable error, since it
  now runs at control.ts import for every control-plane consumer (was a raw
  readFileSync throw). Mirrors the CLI's guard.

- Non-lossy swap: only the sentinel step's `sql` is rewritten; sibling execute
  steps and extra fields are preserved. Added a drift-guard + non-lossy test.

601 tests green; build + biome + frozen-lockfile clean.

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

Author: coderdan

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

@@ -5,16 +5,22 @@
 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.
+`@cipherstash/eql` is now a runtime dependency, pinned exact (`3.0.0`) to match
+the release `@cipherstash/stack` encodes its v3 domain **types** against — the
+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.
+
+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
+one-line version bump plus a rebuild. 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.
+contract-space hash. Injection matches the placeholder by value and fails loudly
+if it is absent, so a drift between the emit source and the injector can never
+silently ship an empty install.

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

@@ -5,10 +5,10 @@
  * 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
+ * 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
  * `eql_v3.query_*` operand domains, and the `eql_v3_internal` helper schema.
  *
  * This is the SECOND migration in the cipherstash contract space, and
@@ -71,8 +71,8 @@ export default class M extends Migration {
         // 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
+        // ~1.7 MB bundle is NOT baked into `ops.json` and bumping the pinned
+        // `@cipherstash/eql` needs no re-emit. 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 },

packages/prisma-next/package.json

@@ -85,7 +85,7 @@
 		"clean": "rm -rf dist coverage .tmp-output"
 	},
 	"dependencies": {
-		"@cipherstash/eql": "^3.0.0",
+		"@cipherstash/eql": "3.0.0",
 		"@cipherstash/stack": "workspace:*",
 		"@prisma-next/contract": "0.14.0",
 		"@prisma-next/family-sql": "0.14.0",

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

@@ -88,8 +88,8 @@ const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
       dirName: CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
       metadata: v3BaselineMetadata,
       // 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
+      // 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),

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

@@ -10,11 +10,15 @@
  *
  * 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
+ * `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.)
+ * `@cipherstash/eql` is therefore a runtime dependency, pinned exact (`3.0.0`)
+ * to match the version `@cipherstash/stack` encodes its v3 domain TYPES against
+ * — the two must move together, so this is a coordinated bump, not a float.
+ *
+ * The win over baking: upgrading the pinned `@cipherstash/eql` no longer means
+ * re-emitting the 1.7 MB `ops.json` (which coupled every EQL bump to a manual
+ * re-emit loop) — it is a one-line version bump plus a rebuild.
  *
  * 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
@@ -28,45 +32,71 @@
  */
 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'
+export { releaseManifest }
 
 /**
  * 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.
+ * of the baked install SQL. {@link withRuntimeEqlSql} swaps it for the real
+ * bundle at descriptor-build time; if it ever reached a database directly it is
+ * an inert SQL comment. It is ALSO the join key the injector matches on — the
+ * exact string the committed `ops.json` carries — so injection targets exactly
+ * the placeholder and is immune to op-id / label drift.
  */
 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
-  }>
+/**
+ * Read the EQL v3 install SQL from the installed `@cipherstash/eql`, turning a
+ * missing/broken package into an actionable error instead of a raw
+ * `readFileSync` failure at descriptor-import time (this runs whenever any
+ * control-plane consumer imports the descriptor). Mirrors the CLI's
+ * `readV3InstallSql`.
+ */
+function readV3InstallSql(): string {
+  try {
+    return readInstallSql()
+  } catch (cause) {
+    throw new Error(
+      'Failed to read the EQL v3 install SQL from `@cipherstash/eql`. Reinstall dependencies — the package ships the bundle in `dist/sql/`.',
+      { cause },
+    )
+  }
 }
 
+type ExecuteStep = { readonly sql?: unknown }
+type OpLike = { readonly execute?: ReadonlyArray<ExecuteStep> }
+
 /**
- * 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
+ * Return `ops` with every placeholder install-SQL step ({@link
+ * RUNTIME_EQL_SQL_SENTINEL}) replaced by the install SQL from the installed
+ * `@cipherstash/eql`. Non-placeholder steps and every other op field are
+ * preserved as-is (only the matched step's `sql` is rewritten), so the swap is
+ * non-lossy. Called by the descriptor in `control.ts` so the applied SQL always
  * matches the resolved `@cipherstash/eql` version, not a baked snapshot.
+ *
+ * Throws if NO placeholder is present: the committed v3 baseline op MUST carry
+ * the sentinel, so a missing match means the emit source and this injector have
+ * diverged (e.g. real SQL was baked back in, or the sentinel string changed) —
+ * fail loudly at descriptor build rather than silently apply the inert comment
+ * as the "install" and leave the database with no EQL.
  */
 export function withRuntimeEqlSql<T extends OpLike>(ops: readonly T[]): T[] {
-  const sql = readInstallSql()
+  const hasPlaceholder = ops.some((op) =>
+    op.execute?.some((step) => step.sql === RUNTIME_EQL_SQL_SENTINEL),
+  )
+  if (!hasPlaceholder) {
+    throw new Error(
+      'withRuntimeEqlSql: no op carried RUNTIME_EQL_SQL_SENTINEL — the v3 baseline ops.json must carry the placeholder for runtime EQL-SQL injection. The emit source and this injector have diverged.',
+    )
+  }
+  const sql = readV3InstallSql()
   return ops.map((op) =>
-    op.id === V3_INSTALL_OP_ID
+    op.execute?.some((step) => step.sql === RUNTIME_EQL_SQL_SENTINEL)
       ? {
           ...op,
-          execute: [
-            {
-              description: String(op.execute?.[0]?.description ?? ''),
-              sql,
-            },
-          ],
+          execute: op.execute.map((step) =>
+            step.sql === RUNTIME_EQL_SQL_SENTINEL ? { ...step, sql } : step,
+          ),
         }
       : op,
   )

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

@@ -26,7 +26,10 @@ 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'
+import {
+  RUNTIME_EQL_SQL_SENTINEL,
+  withRuntimeEqlSql,
+} 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', () => {
@@ -47,16 +50,18 @@ describe('v3 baseline migration (20260601T0100_install_eql_v3_bundle)', () => {
         readonly execute?: ReadonlyArray<{ readonly sql: string }>
       }>
     )[0]!
-    // 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.
+    // The ~1.7 MB bundle must not be committed here — bumping @cipherstash/eql
+    // should not require re-emitting this file. The op carries the sentinel.
     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)
+    // @cipherstash/eql is pinned exact (matching @cipherstash/stack, which
+    // encodes the v3 domain types against this same release).
     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
+    // 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 op = (
@@ -69,6 +74,30 @@ describe('v3 baseline migration (20260601T0100_install_eql_v3_bundle)', () => {
     expect(op.execute?.[0]?.sql).toContain('EQL v3 schema creation')
   })
 
+  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
+    // diverged, so fail loudly rather than apply the inert comment as install.
+    expect(() =>
+      withRuntimeEqlSql([{ execute: [{ sql: 'SELECT 1' }] }]),
+    ).toThrow(/RUNTIME_EQL_SQL_SENTINEL/)
+    // A non-lossy swap: only the sentinel step's `sql` changes; sibling steps
+    // and extra fields on the matched op are preserved.
+    const [op] = withRuntimeEqlSql([
+      {
+        id: 'cipherstash.install-eql-v3-bundle',
+        execute: [
+          { description: 'keep me', sql: RUNTIME_EQL_SQL_SENTINEL },
+          { description: 'sibling', sql: 'SELECT 2' },
+        ],
+      },
+    ])
+    expect(op.id).toBe('cipherstash.install-eql-v3-bundle')
+    expect(op.execute[0].description).toBe('keep me')
+    expect(op.execute[0].sql).toBe(readInstallSql())
+    expect(op.execute[1]).toEqual({ description: 'sibling', sql: 'SELECT 2' })
+  })
+
   it('emits no add_search_config / remove_search_config ops', () => {
     const json = JSON.stringify(v3Ops)
     expect(json).not.toContain('add_search_config')