fix(eql): re-emit against the published 3.0.5, which kept the old name

The subtree sync brought upstream's actual 3.0.5 release, and it is not the
bundle this branch had been carrying under that number. Upstream 142f41d
restored `eql_v3.ste_vec_contains` as a deprecated delegating alias — both
overloads — and retargeted its own changeset from `major` to `patch` in the
same commit. The two decisions are one decision: it is a patch BECAUSE the
old name still resolves.

This branch had taken the other half of that trade — hard removal, still
shipped as a patch — so the tree held SQL stamped 3.0.5 that differed from
published 3.0.5 by 32 lines. That is the defect 9b1c44d exists to prevent,
one level up, and nothing would have caught it: `verify-release-assets.mjs`
compares the manifest's version to package.json and hashes nothing, and
`sync-generated.mjs` preserves `src/generated/release-manifest.ts` rather
than regenerating it, so `check:generated` is blind to it too.

The merge landed on upstream's bytes exactly — every artefact here now
hashes to `accde0030…`, the digest in the published tarball — so no
regeneration was needed beyond re-emitting the two prisma migrations that
bake the bundle.

ONLY TWO MIGRATIONS WERE RE-EMITTED, deliberately. All four `migration.ts`
files call `readVerifiedInstallSql()`, so re-running the 3.0.2 and 3.0.4
edges would silently bake 3.0.5 SQL into artefacts describing historical
releases. Looping over the directory is the obvious thing to do and it is
wrong; the frozen-digest test catches it, but only after the damage.

The one assertion whose MEANING changed is
`not.toContain('ste_vec_contains')`. Re-pinning it would have been wrong in
both directions, so it now asserts the SHAPE the alias has to take: exactly
two definitions, every body delegating to the new name rather than copying
the implementation, and both marked deprecated with `COMMENT ON FUNCTION`
so a DBA reading the schema sees it — not only the generated docs.

Everything else that moved is prose that had inverted. The upgrade note was
the worst of it: `v3.0.5.md` told readers to verify with a query commented
"Must return zero rows" against `proname = 'ste_vec_contains'`, which now
returns two — a reader following it would conclude the upgrade had failed.
The release is now genuinely non-breaking, which leaves U-002 (every EQL
install opens `DROP SCHEMA … CASCADE`) as the only item in it with
operational consequences.

Author: tobyhede

.changeset/eql-3-0-5-migration.md

@@ -14,21 +14,23 @@ are what a PostgREST caller invokes, so PostgREST callers on the documented
 surface are **not** affected. The renamed function is the typed implementation
 those operators dispatch into.
 
-**What does break is hand-written SQL naming the old function** — an
-application query, a view, an RLS policy, or a per-function
-`GRANT EXECUTE ON FUNCTION eql_v3.ste_vec_contains(…)`. After the upgrade
-those fail loudly (`function eql_v3.ste_vec_contains(…) does not exist`)
-rather than silently, but they fail. Grep your migrations, views and policies
-for `ste_vec_contains`.
+**And the old name still works.** eql-3.0.5 ships `eql_v3.ste_vec_contains` as
+a deprecated delegating alias for both overloads, so hand-written SQL naming it
+— an application query, a view, an RLS policy, or a per-function
+`GRANT EXECUTE ON FUNCTION eql_v3.ste_vec_contains(…)` — keeps resolving. The
+typed overload stays inlinable, so a function-form query through the alias
+still matches the same functional GIN index. Migrate to
+`jsonb_document_contains` when convenient; nothing forces it at upgrade time.
 
 **Separately — and true of every EQL upgrade, not just this one:** the install
 bundle opens with `DROP SCHEMA IF EXISTS eql_v3 CASCADE`, so applying it
 destroys every grant on every object in `eql_v3` / `eql_v3_internal`, along
 with anything that depended on them (this is the same mechanism that drops
 functional indexes on encrypted columns). **Re-run your grant script after
 upgrading.** The schema-wide form EQL documents —
-`GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA eql_v3 TO app_role` — picks the new
-name up on its own; a hand-written per-function grant has to be edited first.
+`GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA eql_v3 TO app_role` — picks up both
+the new name and the alias on its own. **With the rename made non-breaking by
+the alias, this is the only part of the upgrade that needs action.**
 
 Two artefacts carry the new bundle:
 

examples/prisma/migrations/cipherstash/20260601T0100_install_eql_v3_bundle/migration.json

@@ -8,5 +8,5 @@
     "cipherstash:upgrade-eql-v3-bundle-3.0.5-v1"
   ],
   "createdAt": "2026-07-14T20:10:24.325Z",
-  "migrationHash": "sha256:1ae732828e9a6fb3574ab8dbede16e99bf1173bd4e5cd7a4b522138e71bc5d05"
+  "migrationHash": "sha256:23c98b0368d22794507a4ef7b02ed4cb04249f36bfcb0b20488005aa62488313"
 }

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

@@ -5,5 +5,5 @@
     "cipherstash:upgrade-eql-v3-bundle-3.0.5-v1"
   ],
   "createdAt": "2026-08-14T00:45:14.365Z",
-  "migrationHash": "sha256:7bafd9d6c5d244332ff0b0943604dbd026c8369e24d2f335b1365c5f78e49d38"
+  "migrationHash": "sha256:3b2b838bee634f2de4a5e88f1625a45d47c327e3021b0e2ccba36c09a9666178"
 }

examples/prisma/migrations/cipherstash/20260814T0000_upgrade_eql_v3_3_0_5/migration.json

@@ -1,9 +1,10 @@
 # Upgrading to EQL 3.0.5
 
-`3.0.5` is a patch release carrying one rename in the public `eql_v3` surface.
-It is a patch, not a major, for the reason 3.0.1 was: a patch reaches every
-consumer already on a `^3.x` range at their next install, and the affected
-call site is one that almost nobody writes by hand.
+`3.0.5` is a patch release carrying one rename in the public `eql_v3` surface,
+with the old name retained as a deprecated alias. **Nothing in it requires you
+to change any SQL.** It is a patch, not a major, for the reason 3.0.1 was: a
+patch reaches every consumer already on a `^3.x` range at their next install —
+and with the alias in place there is no compatibility argument left to have.
 
 This guide also records a second thing, which is **not** new in 3.0.5 but bites
 hardest at upgrade time and has never had a note of its own: applying the EQL
@@ -12,8 +13,9 @@ survive it.
 
 ## TL;DR
 
-1. `eql_v3.ste_vec_contains` is renamed to `eql_v3.jsonb_document_contains` —
-   [U-001](#u-001-the-containment-implementation-is-renamed).
+1. `eql_v3.ste_vec_contains` is renamed to `eql_v3.jsonb_document_contains`.
+   The old name still works — it is now a deprecated alias. Migrate at your
+   convenience — [U-001](#u-001-the-containment-implementation-is-renamed).
 2. Applying any EQL bundle destroys grants, indexes and dependent objects in
    `eql_v3` / `eql_v3_internal`; re-apply them afterwards —
    [U-002](#u-002-grants-and-dependent-objects-do-not-survive-an-install).
@@ -24,7 +26,7 @@ survive it.
 | --- | --- |
 | `@>` / `<@` on `public.eql_v3_json_search` | **Unchanged.** Same operators, same results, same index behaviour. |
 | `eql_v3.jsonb_contains(jsonb, jsonb)` / `eql_v3.jsonb_contained_by(jsonb, jsonb)` | **Unchanged**, byte for byte. These are the function-form entry points for platforms without operator support — PostgREST included — and they are not affected by this release. |
-| `eql_v3.ste_vec_contains` | **Renamed** to `eql_v3.jsonb_document_contains` (both overloads) — see U-001. |
+| `eql_v3.ste_vec_contains` | **Renamed** to `eql_v3.jsonb_document_contains` (both overloads), with the old name kept as a deprecated delegating alias — existing callers keep working. See U-001. |
 | `eql_v3.to_ste_vec_query`, `eql_v3.ste_vec`, `eql_v3.jsonb_array` | **Unchanged.** The documented GIN index recipe still reads `USING gin ((eql_v3.to_ste_vec_query(col)::jsonb) jsonb_path_ops)`. |
 | Wire format, domains, index terms | **Unchanged.** No re-encryption, no data migration. |
 
@@ -36,34 +38,35 @@ survive it.
 `eql_v3.jsonb_document_contains`, in both overloads —
 `(jsonb[], jsonb)` and
 `(public.eql_v3_json_search, public.eql_v3_json_search)`. The body is
-unchanged. The old name is **removed**; there is no compatibility alias.
+unchanged. **The old name is retained** as a deprecated alias for both
+overloads, each delegating to the new one — so this release breaks no caller.
 
 **Why.** It was the last object in the public surface still carrying
 `ste_vec_` naming, after the SteVec entry and query surface became
 `jsonb_entry` / `jsonb_query`. `ste_vec` is an implementation detail of the
 encrypted representation; the operator family it backs is the `jsonb_*` one.
 
-**Who is affected.** Only SQL that names the function directly. In particular
-this is **not** the PostgREST story it might look like: PostgREST calls
-functions rather than operators, but the function-form containment entry points
-it calls are `eql_v3.jsonb_contains` and `eql_v3.jsonb_contained_by`, and both
-are unchanged. `jsonb_document_contains` is what the typed `@>` / `<@`
-operators dispatch into.
+**Who is affected.** Nobody is forced to act. In particular this is **not** the
+PostgREST story it might look like: PostgREST calls functions rather than
+operators, but the function-form containment entry points it calls are
+`eql_v3.jsonb_contains` and `eql_v3.jsonb_contained_by`, and both are unchanged.
+`jsonb_document_contains` is what the typed `@>` / `<@` operators dispatch into.
 
-So the affected callers are hand-written:
+SQL that names the old function directly — application queries, views and
+matviews, RLS `USING` / `WITH CHECK` expressions, wrapping functions and
+triggers, and per-function `GRANT EXECUTE ON FUNCTION
+eql_v3.ste_vec_contains(…)` — all keep resolving, through the alias.
 
-- application queries, views or matviews naming `eql_v3.ste_vec_contains`
-- RLS policies whose `USING` / `WITH CHECK` expression names it
-- SQL functions or triggers that wrap it
-- a per-function grant, `GRANT EXECUTE ON FUNCTION eql_v3.ste_vec_contains(…)`
+The typed overload is deliberately `LANGUAGE sql` and stays inlinable, so a
+function-form query through the alias still matches the same functional GIN
+index it did before the rename. There is no performance cliff for not
+migrating.
 
-**What to do.** Grep your migrations, policies and application SQL for
-`ste_vec_contains` and replace it with `jsonb_document_contains`. Nothing else
-changes — same arguments, same return, same semantics. The failure is loud
-(`function eql_v3.ste_vec_contains(…) does not exist`), so an unfixed caller
-errors rather than silently returning the wrong rows; a view or policy is the
-case to check first, because the error surfaces at query time rather than at
-upgrade time.
+**What to do.** Nothing, to upgrade. When convenient, grep your migrations,
+policies and application SQL for `ste_vec_contains` and replace it with
+`jsonb_document_contains` — same arguments, same return, same semantics. The
+alias is marked deprecated in the database itself (`COMMENT ON FUNCTION`), so
+`\df+ eql_v3.ste_vec_contains` tells a DBA what to move to.
 
 **Verification.**
 
@@ -73,8 +76,8 @@ SELECT p.oid::regprocedure
 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
 WHERE n.nspname = 'eql_v3' AND p.proname = 'jsonb_document_contains';
 
--- Must return zero rows:
-SELECT p.oid::regprocedure
+-- Must ALSO return two rows — the deprecated aliases, which 3.0.5 keeps:
+SELECT p.oid::regprocedure, obj_description(p.oid, 'pg_proc') AS note
 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
 WHERE n.nspname = 'eql_v3' AND p.proname = 'ste_vec_contains';
 
@@ -147,11 +150,14 @@ WHERE indexdef LIKE '%eql_v3.%_term%' OR indexdef LIKE '%to_ste_vec_query%';
 
 ## Rollback
 
-U-001 is reversible by installing the 3.0.4 bundle, which restores the old
-function name. Nothing in the wire format or the stored data changes between
-3.0.4 and 3.0.5, so no re-encryption is involved in either direction — but note
-that rolling back re-runs the `DROP SCHEMA … CASCADE` in U-002, so grants and
-indexes need re-applying again afterwards.
+U-001 needs no rollback: 3.0.5 adds a name and keeps the old one, so anything
+that worked on 3.0.4 works on 3.0.5. Installing the 3.0.4 bundle does reverse
+it, and is the only way to remove `jsonb_document_contains` — but the reason to
+do so would have to come from somewhere other than this rename. Nothing in the
+wire format or the stored data changes between 3.0.4 and 3.0.5, so no
+re-encryption is involved in either direction — but note that rolling back
+re-runs the `DROP SCHEMA … CASCADE` in U-002, so grants and indexes need
+re-applying again afterwards.
 
 ## See also
 

examples/prisma/migrations/cipherstash/20260814T0000_upgrade_eql_v3_3_0_5/ops.json

@@ -10,24 +10,28 @@
   `jsonb_query`). The function backs the `json` `@>` / `<@` containment operators;
   its behaviour is unchanged.
 
-  **Who is affected is narrower than a rename usually implies.** The operators are
-  untouched, and so are the two function-form entry points a PostgREST deployment
-  actually calls — `eql_v3.jsonb_contains(jsonb, jsonb)` and
-  `eql_v3.jsonb_contained_by(jsonb, jsonb)` are byte-identical to 3.0.4. What
-  breaks is hand-written SQL that names `ste_vec_contains` directly: queries,
-  views, RLS policies, and per-function `GRANT`s. The schema-wide grant scripts in
-  `docs/reference/permissions.md` pick the new name up on their next run, and a
-  stale per-function grant fails loudly (`function … does not exist`) rather than
-  silently granting nothing. See [U-001](../../docs/upgrading/v3.0.5.md#u-001-the-containment-implementation-is-renamed),
-  and [U-002](../../docs/upgrading/v3.0.5.md#u-002-grants-and-dependent-objects-do-not-survive-an-install)
-  for the larger fact underneath it — the installer opens with
-  `DROP SCHEMA IF EXISTS eql_v3 CASCADE`, so *every* EQL install drops grants,
-  functional indexes and dependent views, not just this one.
+  **Nothing breaks.** The old name remains as a deprecated delegating alias, both
+  overloads, so direct callers keep working. The operators never moved, and
+  neither did the two function-form entry points a PostgREST deployment actually
+  calls — `eql_v3.jsonb_contains(jsonb, jsonb)` and
+  `eql_v3.jsonb_contained_by(jsonb, jsonb)` are byte-identical to 3.0.4. Hand-written
+  SQL naming `ste_vec_contains` — queries, views, RLS policies, per-function
+  `GRANT`s — continues to resolve; update it at your convenience, not under
+  pressure. See [U-001](../../docs/upgrading/v3.0.5.md#u-001-the-containment-implementation-is-renamed).
+
+  **The thing in this release that does have consequences is not the rename.**
+  The installer opens with `DROP SCHEMA IF EXISTS eql_v3 CASCADE`, so *every* EQL
+  install drops grants, functional indexes and dependent views — true of every
+  release, not just this one, and now the only item here with operational weight.
+  See [U-002](../../docs/upgrading/v3.0.5.md#u-002-grants-and-dependent-objects-do-not-survive-an-install).
 
   Released as a **patch**, matching 3.0.1, which shipped the fuzzy-match operator
   change (`@>` / `<@` → `@@`) at the same level. The parked changeset proposed
   `major`; a patch reaches every consumer already on a `^3.x` range at their next
-  install, which a major would not have done.
+  install, which a major would not have done — and with the alias in place the
+  patch level is not a judgement call at all. Upstream reached the same
+  conclusion independently, retargeting its own changeset from `major` to `patch`
+  in the commit that restored the aliases.
 
   Entered by hand rather than by `changeset version`. The rename landed in the
   tree with the monorepo import and was never released, so the package shipped
@@ -37,6 +41,14 @@
   the whole repository. The bump is therefore applied directly and
   `.changeset/rename-ste-vec-contains.md.deferred` is deleted with it, so the
   cutover cannot apply the same bump a second time.
+
+  The SQL that actually shipped is upstream's, not this tree's: `@cipherstash/eql@3.0.5`
+  was published from `cipherstash/encrypt-query-language` (the last release from
+  there) and carries the restored aliases from upstream `142f41d8`, which this
+  tree did not have when the entry above was first written. The subtree was
+  re-synced to that release so the bundle here is byte-identical to the published
+  one — `installSqlSha256: accde0030…`. The generated entry below is upstream's
+  own changeset for the same release.
 - 4c2bb92: **`eql_v3.ste_vec_contains` is renamed to `eql_v3.jsonb_document_contains`.** This
   consolidates the last `ste_vec_*`-named public object into the `jsonb_*` family,
   matching the earlier renames of the SteVec entry/query surface (`jsonb_entry`,

packages/eql/docs/upgrading/v3.0.5.md

@@ -8,5 +8,5 @@
     "cipherstash:upgrade-eql-v3-bundle-3.0.5-v1"
   ],
   "createdAt": "2026-07-14T20:10:24.325Z",
-  "migrationHash": "sha256:1ae732828e9a6fb3574ab8dbede16e99bf1173bd4e5cd7a4b522138e71bc5d05"
+  "migrationHash": "sha256:23c98b0368d22794507a4ef7b02ed4cb04249f36bfcb0b20488005aa62488313"
 }

packages/eql/packages/eql/CHANGELOG.md

@@ -5,5 +5,5 @@
     "cipherstash:upgrade-eql-v3-bundle-3.0.5-v1"
   ],
   "createdAt": "2026-08-14T00:45:14.365Z",
-  "migrationHash": "sha256:7bafd9d6c5d244332ff0b0943604dbd026c8369e24d2f335b1365c5f78e49d38"
+  "migrationHash": "sha256:3b2b838bee634f2de4a5e88f1625a45d47c327e3021b0e2ccba36c09a9666178"
 }