feat(stack)!: replace like/ilike with contains on the v3 supabase surface

EQL v3 free-text search is token containment over a bloom filter, not SQL
wildcard matching: `%` is tokenized like any other character, so a `like`
pattern is a category error. The v3 Drizzle integration already omits
`like`/`ilike` in favour of `contains`; the supabase adapter now matches.

This is a surface rename, not a re-encoding. The bundle declares

    CREATE OPERATOR @> (FUNCTION = eql_v3.contains,
                        LEFTARG = public.text_search, RIGHTARG = jsonb)

so PostgREST's `cs` already resolved through `@>` into `eql_v3.contains` →
`match_term(a) @> match_term(b)` → smallint[] bloom containment. It was never
the built-in `jsonb @> jsonb`. The emitted operator and the full-envelope
operand are unchanged; no ciphertext moves. The live PostgREST suite proves the
resolution: a 3-character needle matches while a 7-character one does not, and
neither shares the stored `c`.

`contains` is narrowed at compile time to freeTextSearch-capable domains
(text_match, text_search). The shared builder interface is now parameterised by
its own return type, so `like` is absent at every chain depth rather than only
on the first call; the runtime still throws for untyped JS callers, and passes
`like` through on a genuine plaintext column.

Three silent-failure bugs fixed alongside.

order() on ANY encrypted v3 column now throws, including the ORE-capable ones —
the non-obvious half. The `*_ord` domains are `DOMAIN … AS jsonb` and the bundle
declares no btree operator class on any domain (it lints against one), so
`ORDER BY col` resolved through jsonb's default `jsonb_cmp` and sorted by the
envelope's byte structure, first key `bf`. Stable, plausible-looking, and
meaningless, with no error. Confirmed against the live database: integer_ord has
zero operator classes and a jsonb base type. Correct ordering is
`ORDER BY eql_v3.ord_term(col)`, which PostgREST's `order=` cannot express. The
old guard rejected exactly the columns where the wrongness was obvious and
admitted the ones where it was silent. gte/lte remain correct: the comparison
operators ARE declared on the ord domains; only sorting resolves through the
missing operator class.

or() now understands PostgREST's `column.not.<op>.<value>` negation. The parser
split on the first two dots, read `not` as the operator, and so
`or('nickname.not.in.(ada,grace)')` on an encrypted column encrypted the literal
string `in.(ada,grace)` as one plaintext — a filter that silently matched
nothing. A malformed `col.not.<value>` is passed through for PostgREST to
reject rather than dropped, which would quietly widen the result set.

Raw filter() derives its query type from the operator on v3 instead of always
encrypting an equality term, so `.filter('bio','cs',…)` on a text_match column
(equality: false, freeTextSearch: true) answers the query it was given rather
than being rejected. Unknown operators throw. The v2 base still returns
'equality' verbatim: there `queryType` selects the encryptQuery narrowing, so
correcting it moves v2 ciphertext. Tracked separately.

Every new test was mutation-checked against the implementation it protects.

The include_original substring defect is untouched and still pinned by a test
asserting the broken behaviour: the operand is a storage envelope whose bloom
carries the whole needle as an extra token, so a substring only matches when it
equals the stored value or is exactly the tokenizer's 3-character window. Shared
with v3 Drizzle's contains and tracked upstream in EQL.

BREAKING CHANGE: `like`/`ilike` are removed from the EQL v3 supabase builder —
use `contains`. `order()` on an encrypted v3 column now throws; order by a
plaintext column, expose `eql_v3.ord_term()` as a generated column or view, or
use the EQL v3 Drizzle integration. v2 (`encryptedSupabase`) is unchanged.

Author: tobyhede

.changeset/eql-v3-supabase-adapter.md

@@ -20,9 +20,46 @@ Every column name a query carries — filters, `match`, `not`, raw `filter`,
 `or()`, `order()`, and the `onConflict` option — is now resolved from its JS
 property name to its DB column name in a single pass before the query is built,
 so a declared rename round-trips everywhere rather than only on the paths that
-remembered to translate. `order()` on a column whose domain has no
-`orderAndRange` capability (e.g. a storage-only `public.boolean`) is rejected —
-at compile time when `schemas` is supplied, and at runtime otherwise — instead
-of silently sorting by the raw ciphertext envelope.
+remembered to translate.
 
-v2 (`encryptedSupabase`) is unchanged.
+`order()` on ANY encrypted v3 column is now rejected — at compile time when
+`schemas` is supplied, and at runtime otherwise. The EQL v3 domains are
+`DOMAIN … AS jsonb` and the bundle declares no btree operator class on them, so
+`ORDER BY col` resolves through jsonb's default `jsonb_cmp` and sorts by the
+envelope's byte structure: a stable, plausible-looking, meaningless row order,
+with no error. Correct ordering is `ORDER BY eql_v3.ord_term(col)`, which
+PostgREST's `order=` cannot express. Order by a plaintext column, expose
+`eql_v3.ord_term()` as a generated column or view, or use the EQL v3 Drizzle
+integration, which emits `ord_term` directly. Note `gte`/`lte` filters remain
+correct: the comparison operators *are* declared on the ord domains, and only
+sorting resolves through the missing operator class.
+
+`.or()` now understands PostgREST's `column.not.<op>.<value>` negation. It was
+previously parsed as `{ op: 'not', value: '<op>.<value>' }`, so on an encrypted
+column `or('nickname.not.in.(ada,grace)')` encrypted the literal string
+`in.(ada,grace)` as a single plaintext and produced a filter that silently
+matched nothing.
+
+Free-text search on the v3 builder is `contains(column, value)`. `like`/`ilike`
+are not exposed, because EQL v3 free-text search is token containment over a
+bloom filter (`@>`, backed by `eql_v3.contains`) rather than SQL wildcard
+matching — `%` is tokenized like any other character, so a `like` pattern is a
+category error. This matches the v3 Drizzle integration, which omits them for
+the same reason. On an encrypted column `like`/`ilike` now throw and name
+`contains`; on a plaintext column they remain ordinary PostgREST filters.
+
+`contains` is narrowed at compile time to columns whose domain carries the
+`freeTextSearch` capability (`public.text_match`, `public.text_search`), and
+guarded at runtime for the untyped surface. A raw `filter(column, operator, …)`
+on an encrypted v3 column now derives its query type from the operator instead
+of always encrypting an equality term, so `filter('bio', 'cs', …)` on a
+`public.text_match` column works rather than being rejected, and an unsupported
+operator throws instead of silently encrypting the wrong term.
+
+Substring `contains` still matches only when the needle equals the stored value
+or is exactly the tokenizer's window (3 characters): the operand is a storage
+envelope whose bloom carries the whole needle as an `include_original` token.
+This is shared with v3 Drizzle's `contains` and tracked upstream in EQL.
+
+v2 (`encryptedSupabase`) is unchanged: it keeps `like`/`ilike` (`eql_v2.like`,
+`~~`) and its raw-`filter` query-type mapping, so no v2 ciphertext moves.

packages/stack/__tests__/helpers/supabase-mock.ts

@@ -155,6 +155,7 @@ export function createMockSupabase(resultData: unknown = []) {
     'lte',
     'like',
     'ilike',
+    'contains',
     'is',
     'in',
     'filter',

packages/stack/__tests__/supabase-helpers.test.ts

@@ -62,6 +62,7 @@ describe('addJsonbCastsV3', () => {
     expect(addJsonbCastsV3('a:toString', propToDb)).toBe('a:toString')
   })
 
+  // Pins the leading-whitespace capture: drop it and ` email` loses its space.
   it('maps each token of a multi-column select independently', () => {
     expect(addJsonbCastsV3('id, email, createdAt', propToDb)).toBe(
       'id, email::jsonb, createdAt:created_at::jsonb',
@@ -82,8 +83,8 @@ describe('addJsonbCastsV3', () => {
 const ENVELOPE = '{"v":1,"i":{"t":"users","c":"email"},"c":"ct:abc"}'
 
 /** `rebuildOrString` takes DB-space conditions; `column` is a branded `DbName`. */
-function cond(column: string, op: string, value: unknown) {
-  return { column, op, value } as unknown as DbPendingOrCondition
+function cond(column: string, op: string, value: unknown, negate?: boolean) {
+  return { column, op, value, negate } as unknown as DbPendingOrCondition
 }
 
 describe('rebuildOrString quoting', () => {
@@ -110,7 +111,9 @@ describe('rebuildOrString quoting', () => {
 
 describe('parseOrString / rebuildOrString round-trip', () => {
   it('round-trips an encrypted JSON envelope operand', () => {
-    const conditions = [{ column: 'email', op: 'eq', value: ENVELOPE }]
+    const conditions = [
+      { column: 'email', op: 'eq', negate: false, value: ENVELOPE },
+    ]
     expect(
       parseOrString(
         rebuildOrString(conditions.map((c) => cond(c.column, c.op, c.value))),
@@ -119,7 +122,9 @@ describe('parseOrString / rebuildOrString round-trip', () => {
   })
 
   it('round-trips a value carrying backslashes and quotes', () => {
-    const conditions = [{ column: 'a', op: 'eq', value: 'x\\"y,z' }]
+    const conditions = [
+      { column: 'a', op: 'eq', negate: false, value: 'x\\"y,z' },
+    ]
     expect(
       parseOrString(
         rebuildOrString(conditions.map((c) => cond(c.column, c.op, c.value))),
@@ -138,3 +143,86 @@ describe('parseOrString / rebuildOrString round-trip', () => {
     expect(parsed[1].value).toBe('7')
   })
 })
+
+// ---------------------------------------------------------------------------
+// PostgREST negation inside .or()
+//
+// The parser split on the first two dots, so `col.not.in.(a,b)` yielded
+// `{ op: 'not', value: 'in.(a,b)' }`. On a plaintext column that round-tripped
+// by accident (rebuild re-joins the pieces verbatim). On an ENCRYPTED column the
+// literal string `in.(a,b)` was encrypted as one plaintext, producing a filter
+// that silently matched nothing.
+// ---------------------------------------------------------------------------
+
+describe('parseOrString negation', () => {
+  it('lifts a not. prefix off the operator', () => {
+    expect(parseOrString('nickname.not.eq.ada')).toEqual([
+      { column: 'nickname', op: 'eq', negate: true, value: 'ada' },
+    ])
+  })
+
+  it('parses a negated in-list as a real list, not a literal string', () => {
+    expect(parseOrString('nickname.not.in.(ada,grace)')).toEqual([
+      { column: 'nickname', op: 'in', negate: true, value: ['ada', 'grace'] },
+    ])
+  })
+
+  it('parses not.is.null', () => {
+    expect(parseOrString('email.not.is.null')).toEqual([
+      { column: 'email', op: 'is', negate: true, value: null },
+    ])
+  })
+
+  it('leaves a non-negated condition unnegated', () => {
+    expect(parseOrString('nickname.in.(ada,grace)')).toEqual([
+      { column: 'nickname', op: 'in', negate: false, value: ['ada', 'grace'] },
+    ])
+  })
+
+  it('does not mistake a column or value named "not" for the prefix', () => {
+    expect(parseOrString('not.eq.ada')).toEqual([
+      { column: 'not', op: 'eq', negate: false, value: 'ada' },
+    ])
+    expect(parseOrString('nickname.eq.not')).toEqual([
+      { column: 'nickname', op: 'eq', negate: false, value: 'not' },
+    ])
+  })
+
+  it('does not swallow a condition whose not. prefix has no operator', () => {
+    // `col.not.<value>` is malformed PostgREST. Consuming the prefix would leave
+    // no operator, and the condition would be silently DROPPED from the or-string
+    // — quietly widening the result set. Pass it through so PostgREST rejects it.
+    expect(parseOrString('nickname.not.ada')).toEqual([
+      { column: 'nickname', op: 'not', negate: false, value: 'ada' },
+    ])
+    expect(
+      rebuildOrString(
+        parseOrString('nickname.not.ada') as DbPendingOrCondition[],
+      ),
+    ).toBe('nickname.not.ada')
+  })
+})
+
+describe('rebuildOrString negation', () => {
+  it('re-emits the not. prefix', () => {
+    expect(rebuildOrString([cond('nickname', 'eq', 'ada', true)])).toBe(
+      'nickname.not.eq.ada',
+    )
+  })
+
+  it('round-trips a negated in-list through parse → rebuild', () => {
+    const parsed = parseOrString('nickname.not.in.(ada,grace)')
+    expect(rebuildOrString(parsed as DbPendingOrCondition[])).toBe(
+      'nickname.not.in.(ada,grace)',
+    )
+  })
+
+  it('omits the prefix when negate is false or absent', () => {
+    expect(rebuildOrString([cond('nickname', 'eq', 'ada', false)])).toBe(
+      'nickname.eq.ada',
+    )
+    expect(rebuildOrString([cond('nickname', 'eq', 'ada')])).toBe(
+      'nickname.eq.ada',
+    )
+  })
+})