fix(stack-prisma): reclassify EQL install as additive so fresh-database db init passes, and pin eql-3.0.4 by coderdan · Pull Request #820 · cipherstash/stack

coderdan · 2026-07-28T10:16:35Z

Closes #850.

Problem

Prisma Compute's GitHub preview deploy runs prisma-next db init (additive-only policy) against each branch database. The cipherstash space's install-eql-v3-bundle op is classed data, so every preview deploy of an app using @cipherstash/stack-prisma fails:

PN-RUN-3020: Operation cipherstash.install-eql-v3-bundle has class "data"
which is not allowed by policy. Policy only allows: additive.

Hit in a live dogfooding run (rc.4 consumer app + Compute push-to-deploy).

Why `data` was there, and why it's safe to change

The in-file rationale says data satisfies the aggregate integrity checker's no-op self-edge rule (sameSourceAndTarget, PN-MIG-CHECK-007). Verified against migration-tools 0.16.0: that rule only fires when from === to. The genesis edge runs from: null → the empty-storage hash — not a self-edge — so additive passes the checker. Empirically confirmed both ways: flipping an upgrade edge (a true A → A self-edge) to additive trips PN-MIG-CHECK-007; flipping the install edge does not.

additive is also the truthful class on the policy axis: the bundle only CREATEs its own schemas, domains, and functions; it cannot damage user data.

Keeping fresh databases off the upgrade self-edges

The upgrade edges must keep data (true self-edges). So the re-emitted install edge now also carries every upgrade invariant via no-SQL additive carrier ops — legitimate because the baked bundle already IS the pinned release, a superset of every earlier v3 surface. computeExtensionSpaceApplyPath picks the shortest invariant-covering path, so a fresh database satisfies the head ref from the single all-additive genesis edge and never walks an upgrade edge. Databases installed at an older bundle still upgrade through those edges via migrate (all classes allowed).

EQL bundle pinned 3.0.2 → 3.0.4

Per review, the install baseline should target the latest EQL release:

@cipherstash/eql pinned 3.0.2 → 3.0.4 in stack-prisma, cli, and stack (already in minimumReleaseAgeExclude as a first-party package, so no cooldown bypass needed)
the re-emitted baseline bakes the eql-3.0.4 bundle and carries both upgrade invariants (3.0.2 + 3.0.4)
new data-classed 3.0.4 upgrade self-edge (20260728T0000_upgrade_eql_v3_3_0_4) for databases installed at an older bundle, walked via migrate only
head ref gains the 3.0.4 invariant; descriptor wires the new edge; example vendored space synced

Consumer impact (pre-GA, deliberate)

One-time authorized re-emit of a published artefact. Both content-addressed pins on the install package change: its migrationHash and its baked installSqlSha256 — the latter because the baked SQL is now the 3.0.4 bundle rather than 3.0.2. (An earlier revision of this description claimed the baked digest was unchanged; that was true only of the pre-3.0.4 version of this branch — thanks @copilot for catching it.) The 3.0.2 upgrade edge keeps its own original digest, pinned to its own release.

RC consumers with a vendored migrations/cipherstash/ should delete the space directory and re-run prisma-next migration plan to pick up the re-emitted artefacts. Frozen-hash tests re-pinned with a comment recording the exception; example app's vendored copy synced.

Verification

@cipherstash/stack-prisma: 345 passed / 27 skipped (frozen-hash pins re-pinned for the re-emitted baseline, new edge pinned)
@cipherstash/stack: 1017 passed; stash: 931 passed; supply-chain e2e: 18 passed; code:check 0 errors
pnpm install --frozen-lockfile clean — lockfile diff is eql-only (9 lines)
Consumer app end-to-end: migration check passes; db init on a fresh database succeeds (previously PN-RUN-3020), applying the cipherstash space additively, with eql_v3.version() reporting 3.0.4
Existing already-migrated databases: reachable via the upgrade edges under migrate, confirmed on the dogfooding app

Branch housekeeping

This branch originally targeted remove_v2; when that merged as a squash the base retargeted to main but the fork point did not, leaving 100 commits and a conflicted diff. Rebased onto main down to this PR's own commits, with the packages/prisma-next → packages/stack-prisma rename (#844) applied and the changeset key corrected to @cipherstash/stack-prisma. All commits are GPG-signed.

Closes #850.

Related: #819 (backfill support, same dogfooding run).

Summary by CodeRabbit

Bug Fixes
- Fixed fresh-database initialization so prisma-next db init completes successfully, including Prisma Compute preview deployments.
- Added a reliable upgrade path for existing installations.
Documentation
- Updated EQL compatibility and PostgREST limitation guidance to reference EQL 3.0.4.
Maintenance
- Updated the bundled EQL version to 3.0.4.

coderabbitai · 2026-07-28T10:16:43Z

📝 Walkthrough

Walkthrough

The PR updates EQL to 3.0.4, re-emits the baseline install migration as additive with invariant carriers, adds a data-classed 3.0.4 upgrade self-edge, wires migration metadata, and updates tests and documentation.

Changes

EQL 3.0.4 migration flow

Layer / File(s)	Summary
Additive EQL install migration `packages/stack-prisma/migrations/20260601T0100_install_eql_v3_bundle/*`, `examples/prisma/migrations/...`	The baseline install is reclassified as additive, embeds EQL 3.0.4, and carries the 3.0.2 and 3.0.4 invariants.
EQL 3.0.4 upgrade self-edge `packages/stack-prisma/migrations/20260728T0000_upgrade_eql_v3_3_0_4/*`, `examples/prisma/migrations/...`	A data-classed self-edge applies the verified EQL 3.0.4 bundle and checks its version and typed query domains.
Migration descriptor and package wiring `packages/stack-prisma/src/...`, `packages/stack-prisma/migrations/refs/`, `packages//package.json`	The new migration and invariant are added to the contract-space descriptor, references, and package versions.
Migration validation and release documentation `packages/stack-prisma/test/`, `.changeset/`, `packages/stack-supabase/README.md`, `skills/stash-supabase/SKILL.md`	Tests validate the expanded migration chain and pinned metadata; release notes and Supabase documentation reference EQL 3.0.4.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

cipherstash/stack issue 762 — Both changes concern the EQL v3 migration artifact and baked EQL 3.0.4 bundle structure.

Possibly related PRs

cipherstash/stack#655 — Introduced the EQL v3 baseline migration artifacts that this PR re-emits and extends.

Suggested reviewers: tobyhede

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR satisfies `#850` by making the install edge additive, keeping upgrade self-edges data-classed, re-emitting artefacts, and pinning EQL 3.0.4.
Out of Scope Changes check	✅ Passed	The extra docs, tests, and example updates appear to support the EQL 3.0.4 re-emit and migration changes rather than add unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: reclassifying the EQL install as additive and pinning EQL to 3.0.4.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/eql-bundle-operation-class

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

changeset-bot · 2026-07-28T10:16:48Z

🦋 Changeset detected

Latest commit: 9ad92c4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@cipherstash/stack-prisma	Patch
@cipherstash/stack	Patch
stash	Patch
@cipherstash/prisma-example	Patch
@cipherstash/bench	Patch
@cipherstash/migrate	Patch
@cipherstash/stack-drizzle	Patch
@cipherstash/stack-supabase	Patch
@cipherstash/test-kit	Patch
@cipherstash/basic-example	Patch
@cipherstash/e2e	Patch
@cipherstash/wizard	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Addresses review on #820: the install baseline must target the latest EQL release, not 3.0.2. - @cipherstash/eql pinned 3.0.2 -> 3.0.4 in prisma-next, cli, and stack (lockfile updated via the one-off cooldown bypass; @cipherstash/eql is already in minimumReleaseAgeExclude as a first-party package) - the re-emitted install baseline now bakes the eql-3.0.4 bundle and carries BOTH upgrade invariants (3.0.2 + 3.0.4) via no-SQL additive carrier ops, so fresh-database `db init` still satisfies the head ref from the single all-additive genesis edge - new `data`-classed 3.0.4 upgrade self-edge (20260728T0000_upgrade_eql_v3_3_0_4) for databases installed at an older bundle, walked via `migrate` only - head ref gains the 3.0.4 invariant; descriptor wires the new edge; example vendored space synced; changeset added Tests: prisma-next 345 passed (frozen-hash pins re-pinned for the re-emitted baseline, new edge pinned); stack 1107; cli 947. Verified live against a consumer app: fresh-database `db init` applies the cipherstash space additively and `eql_v3.version()` reports 3.0.4.

Copilot

Pull request overview

This PR updates the @cipherstash/prisma-next contract-space migration graph so fresh-database prisma-next db init can succeed under an additive-only policy, while still preserving data-classed self-edge upgrades for already-installed databases. It also bumps the pinned @cipherstash/eql bundle to 3.0.4 across the repo and re-pins the frozen migration artefact assertions accordingly.

Changes:

Reclassify the v3 baseline install op as additive and add additive, no-SQL “invariant carrier” ops so a fresh database satisfies head invariants without traversing data self-edges.
Add a new data-classed 3.0.4 upgrade self-edge migration and extend head invariants to include the 3.0.4 invariant.
Bump pinned @cipherstash/eql to 3.0.4 (cli/stack/prisma-next) and sync the example’s vendored cipherstash migration refs; add a changeset.

Reviewed changes

Copilot reviewed 16 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Updates lockfile entries for `@cipherstash/eql@3.0.4`.
packages/stack/package.json	Pins devDependency `@cipherstash/eql` to 3.0.4.
packages/cli/package.json	Pins dependency `@cipherstash/eql` to 3.0.4.
packages/prisma-next/package.json	Pins dependency `@cipherstash/eql` to 3.0.4.
packages/prisma-next/src/extension-metadata/constants-v3.ts	Adds 3.0.4 upgrade migration name and invariant constant.
packages/prisma-next/src/exports/control.ts	Publishes the new 3.0.4 upgrade migration edge in the descriptor.
packages/prisma-next/migrations/refs/head.json	Extends head invariants to include the 3.0.4 upgrade invariant.
packages/prisma-next/migrations/20260601T0100_install_eql_v3_bundle/migration.ts	Reclassifies baseline install op to `additive` and adds invariant-carrier ops.
packages/prisma-next/migrations/20260601T0100_install_eql_v3_bundle/migration.json	Updates baseline provided invariants and migrationHash.
packages/prisma-next/migrations/20260728T0000_upgrade_eql_v3_3_0_4/migration.ts	Adds a new 3.0.4 upgrade self-edge migration (`data`-classed).
packages/prisma-next/migrations/20260728T0000_upgrade_eql_v3_3_0_4/migration.json	Records the 3.0.4 upgrade edge metadata and migrationHash.
packages/prisma-next/test/v3/migration-v3.test.ts	Re-pins frozen migration artefact hashes/digests and adds assertions for the 3.0.4 upgrade edge + carriers.
packages/prisma-next/test/descriptor.test.ts	Updates descriptor expectations for three migrations and deduped invariant coverage.
examples/prisma/migrations/cipherstash/refs/head.json	Syncs example vendored head ref invariants (adds 3.0.4).
examples/prisma/migrations/cipherstash/20260601T0100_install_eql_v3_bundle/migration.json	Syncs example vendored baseline migration metadata to match re-emit.
examples/prisma/migrations/cipherstash/20260728T0000_upgrade_eql_v3_3_0_4/migration.json	Adds example vendored 3.0.4 upgrade migration metadata.
.changeset/eql-additive-install-304.md	Adds a changeset describing the `db init` fix and EQL 3.0.4 bump.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

Comments suppressed due to low confidence (1)

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

The test title/comment says there are "two" additive ops, but the baseline migration now contains three ops (install + two invariant carriers). This mismatch makes the test misleading for future maintainers reading failures or grepping for expected behavior.

  it('installs under the v3 invariants with two additive rawSql ops', () => {
    // Two ops, both `additive`, so fresh-database `db init` (additive-only
    // policy) can walk this genesis edge: the bundle install itself, plus a
    // no-SQL carrier op that declares the 3.0.2 upgrade invariant (the baked
    // bundle IS the pinned release, so a fresh install lands at 3.0.2 and

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Addresses review on #820: the install baseline must target the latest EQL release, not 3.0.2. - @cipherstash/eql pinned 3.0.2 -> 3.0.4 in prisma-next, cli, and stack (lockfile updated via the one-off cooldown bypass; @cipherstash/eql is already in minimumReleaseAgeExclude as a first-party package) - the re-emitted install baseline now bakes the eql-3.0.4 bundle and carries BOTH upgrade invariants (3.0.2 + 3.0.4) via no-SQL additive carrier ops, so fresh-database `db init` still satisfies the head ref from the single all-additive genesis edge - new `data`-classed 3.0.4 upgrade self-edge (20260728T0000_upgrade_eql_v3_3_0_4) for databases installed at an older bundle, walked via `migrate` only - head ref gains the 3.0.4 invariant; descriptor wires the new edge; example vendored space synced; changeset added Tests: prisma-next 345 passed (frozen-hash pins re-pinned for the re-emitted baseline, new edge pinned); stack 1107; cli 947. Verified live against a consumer app: fresh-database `db init` applies the cipherstash space additively and `eql_v3.version()` reports 3.0.4.

…820 review) Addresses Copilot review on #820. The 3.0.4 bump left three comments describing the 3.0.2-era state: - the install migration's invariant-carrier comment still named the baked bundle `eql-3.0.2` while the same sentence called the pinned release 3.0.4 - the same file's PUBLISHED banner described the re-emit as adding one 3.0.2 carrier, omitting the bundle bump, the second carrier, and the fact that the baked `installSqlSha256` changed too (not just the `migrationHash`) - the baseline test was still named "two additive rawSql ops" and its comment described a single carrier landing at 3.0.2, while the assertion below it already expected three ops Comments only — `migrationHash` covers `ops.json` and `migration.json`, not `migration.ts`, so the published artefact identity is untouched (frozen-hash pins still pass).

`prisma-next db init` enforces an additive-only operation policy, but the cipherstash space's install-eql-v3-bundle op was classed `data`, so every fresh-database init — including Prisma Compute's GitHub preview deploys — failed with PN-RUN-3020 (POLICY_VIOLATION). The `data` class existed to satisfy the aggregate integrity checker's no-op self-edge rule, but that rule only fires when from === to; the genesis edge runs from: null → the empty-storage hash and is not a self-edge, so `additive` — the truthful class for a bundle that only CREATEs its own schemas/domains/functions — passes the checker. The 3.0.2 upgrade edge IS a true self-edge and must keep its `data` class. To stop fresh databases needing that edge at all, the re-emitted install edge now also carries the 3.0.2 upgrade invariant via a no-SQL additive carrier op (the baked bundle is already the pinned 3.0.2 release). The shortest-path planner then satisfies the head ref from the single all-additive genesis edge; databases installed at 3.0.0 still reach 3.0.2 through the upgrade edge via `migrate`, whose policy allows all classes. This is a one-time authorized pre-GA re-emit of the published install artefact (migrationHash changes). RC consumers with a vendored migrations/cipherstash/ must refresh the install package's ops.json and migration.json (or delete the space dir and re-run migration plan). The baked SQL digest is unchanged. The example app's vendored copy is synced. Verified end-to-end against a consumer app: `prisma-next migration check` passes, and `prisma-next db init` on a fresh database applies the cipherstash space additively (previously PN-RUN-3020), installing eql_v3 with both encrypted-column domains, then signs the database.

Addresses review on #820: the install baseline must target the latest EQL release, not 3.0.2. - @cipherstash/eql pinned 3.0.2 -> 3.0.4 in prisma-next, cli, and stack (lockfile updated via the one-off cooldown bypass; @cipherstash/eql is already in minimumReleaseAgeExclude as a first-party package) - the re-emitted install baseline now bakes the eql-3.0.4 bundle and carries BOTH upgrade invariants (3.0.2 + 3.0.4) via no-SQL additive carrier ops, so fresh-database `db init` still satisfies the head ref from the single all-additive genesis edge - new `data`-classed 3.0.4 upgrade self-edge (20260728T0000_upgrade_eql_v3_3_0_4) for databases installed at an older bundle, walked via `migrate` only - head ref gains the 3.0.4 invariant; descriptor wires the new edge; example vendored space synced; changeset added Tests: prisma-next 345 passed (frozen-hash pins re-pinned for the re-emitted baseline, new edge pinned); stack 1107; cli 947. Verified live against a consumer app: fresh-database `db init` applies the cipherstash space additively and `eql_v3.version()` reports 3.0.4.

…820 review) Addresses Copilot review on #820. The 3.0.4 bump left three comments describing the 3.0.2-era state: - the install migration's invariant-carrier comment still named the baked bundle `eql-3.0.2` while the same sentence called the pinned release 3.0.4 - the same file's PUBLISHED banner described the re-emit as adding one 3.0.2 carrier, omitting the bundle bump, the second carrier, and the fact that the baked `installSqlSha256` changed too (not just the `migrationHash`) - the baseline test was still named "two additive rawSql ops" and its comment described a single carrier landing at 3.0.2, while the assertion below it already expected three ops Comments only — `migrationHash` covers `ops.json` and `migration.json`, not `migration.ts`, so the published artefact identity is untouched (frozen-hash pins still pass).

coderdan requested a review from a team as a code owner July 28, 2026 10:16

coderdan commented Jul 28, 2026

View reviewed changes

Comment thread examples/prisma/migrations/cipherstash/20260601T0100_install_eql_v3_bundle/ops.json

coderdan requested a review from Copilot July 28, 2026 10:53

Copilot started reviewing on behalf of coderdan July 28, 2026 10:54 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

Comment thread packages/stack-prisma/migrations/20260601T0100_install_eql_v3_bundle/migration.ts Outdated

Comment thread packages/stack-prisma/test/v3/migration-v3.test.ts

tobyhede force-pushed the remove-v2 branch from 69a1156 to 17393b9 Compare July 28, 2026 23:19

Base automatically changed from remove-v2 to main July 29, 2026 07:06

coderdan force-pushed the fix/eql-bundle-operation-class branch from b22cc69 to 053441f Compare July 30, 2026 05:00

coderdan force-pushed the fix/eql-bundle-operation-class branch from 053441f to 7a6badd Compare July 30, 2026 05:07

coderdan changed the title ~~fix(prisma-next): reclassify EQL install as additive so fresh-database db init passes~~ fix(stack-prisma): reclassify EQL install as additive so fresh-database db init passes, and pin eql-3.0.4 Jul 30, 2026

This was referenced Jul 30, 2026

fix(stack-prisma): db init fails PN-RUN-3020 on fresh databases — EQL install op is classed data under an additive-only policy #850

Closed

fix(cli): make stash encrypt work in Prisma Next projects #819

Merged

coderdan requested a review from tobyhede July 30, 2026 05:59

coderdan mentioned this pull request Jul 30, 2026

stash encrypt backfill cannot run in a Prisma Next project #851

Closed

coderdan added 4 commits July 30, 2026 16:44

docs(supabase): align docs with EQL 3.0.4

9ad92c4

coderdan force-pushed the fix/eql-bundle-operation-class branch from 025dd25 to 9ad92c4 Compare July 30, 2026 06:46

tobyhede approved these changes Jul 30, 2026

View reviewed changes

coderdan merged commit c54f19c into main Jul 30, 2026
18 checks passed

coderdan deleted the fix/eql-bundle-operation-class branch July 30, 2026 07:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(stack-prisma): reclassify EQL install as additive so fresh-database db init passes, and pin eql-3.0.4 - #820

fix(stack-prisma): reclassify EQL install as additive so fresh-database db init passes, and pin eql-3.0.4#820
coderdan merged 4 commits into
mainfrom
fix/eql-bundle-operation-class

coderdan commented Jul 28, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

coderdan commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Why data was there, and why it's safe to change

Keeping fresh databases off the upgrade self-edges

EQL bundle pinned 3.0.2 → 3.0.4

Consumer impact (pre-GA, deliberate)

Verification

Branch housekeeping

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

changeset-bot Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderdan commented Jul 28, 2026 •

edited

Loading

Why `data` was there, and why it's safe to change

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

changeset-bot Bot commented Jul 28, 2026 •

edited

Loading