fix(stack): address code-review findings on the v3 type restoration

- operators.test-d.ts: add the negative assertion the changeset claimed but
  never made — a `{ encrypt }` double returning `unknown` must be REJECTED by
  createEncryptionOperatorsV3. The prior positive `toBeCallableWith(double)`
  could not catch a re-erasure (a correct value is assignable to `unknown`), so
  the "pinned" guarantee was toothless. The `@ts-expect-error` now goes unused
  and fails the moment the client contract regresses to `unknown`.
- query-builder.ts: type `EncryptedFilterState.encryptedValues` as
  `EncryptedQueryResult[]`, not `unknown[]`. `encryptCollectedTerms` was restored
  to return that type but the value widened straight back to `unknown` at this
  field, so the use site (`encryptedValues[i]`) still saw `unknown` — the
  restoration never reached the consumer for the base builder. Now it does.
- query-builder-v3.ts: guard the `null` arm in `bulkEncryptGroup`. The restored
  `Encrypted | null` type makes null reachable; an unguarded null envelope would
  be `JSON.stringify`'d to the literal `"null"` and sent as a filter operand
  (matching the wrong rows). Treat it as a contract violation.
- changeset: `patch` → `minor`. Tightening the public `createEncryptionOperatorsV3`
  client contract is a compile-time breaking change for loosely-typed downstream
  clients; corrected the "no runtime change" line to note the new null guard.

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

Author: coderdan

.changeset/eql-v3-adapter-type-robustness.md

@@ -1,5 +1,5 @@
 ---
-'@cipherstash/stack': patch
+'@cipherstash/stack': minor
 ---
 
 Restore the EQL v3 envelope and `Result` types the adapters were erasing.
@@ -23,6 +23,16 @@ resolves `Result<T, EncryptionError>`. The Supabase divergence the erasure hid i
 now explicit: the v2 path yields `encryptQuery` composite literals and the v3
 path yields `JSON.stringify`'d envelope strings, and both are `EncryptedQueryResult`.
 
-No runtime change. The un-erasure has teeth: a `{ encrypt }` double returning
-`unknown` no longer satisfies `createEncryptionOperatorsV3`, pinned in
-`operators.test-d.ts`.
+Bumped `minor`, not `patch`: `createEncryptionOperatorsV3` is a public export
+(`@cipherstash/stack/eql/v3/drizzle`), and tightening its client contract from
+`unknown` to a typed operation surface is a compile-time breaking change — a
+downstream consumer passing a loosely-typed (`unknown`-returning) client double
+will now fail `tsc`. That tightening has teeth: `operators.test-d.ts` pins it
+with a negative type-test asserting an `unknown`-returning `{ encrypt }` double
+is rejected (a positive "correctly-typed double is accepted" assertion cannot
+catch a re-erasure, since a correct value is assignable to `unknown`).
+
+Behaviour is otherwise unchanged, with one addition: the Supabase v3 bulk path
+now rejects a `null` envelope returned by `bulkEncrypt` (the restored
+`Encrypted | null` type makes that arm reachable, and a `null` would otherwise
+be `JSON.stringify`'d to the literal `"null"` and sent as a filter operand).

packages/stack/__tests__/drizzle-v3/operators.test-d.ts

@@ -47,4 +47,19 @@ describe('createEncryptionOperatorsV3 - client parameter (M1)', () => {
     }
     expectTypeOf(createEncryptionOperatorsV3).toBeCallableWith(double)
   })
+
+  it('rejects a { encrypt } double that returns `unknown` (the erasure regression)', () => {
+    // The complement of the test above, and the one with teeth: `toBeCallableWith`
+    // a correctly-typed double keeps passing even if the client contract
+    // regressed to `unknown` (a correct value is assignable to `unknown`), so it
+    // cannot catch re-erasure. This can. `encrypt` returning `unknown` must NOT
+    // satisfy the factory, whose contract is `ChainableOperation<Encrypted>`; if
+    // the erasure ever comes back, the `@ts-expect-error` goes unused and fails.
+    const erased = {
+      encrypt: (_plaintext: never, _opts: never): unknown => ({}),
+    }
+    // @ts-expect-error — `encrypt` returning `unknown` does not satisfy the
+    // factory's `ChainableOperation<Encrypted>` client contract.
+    createEncryptionOperatorsV3(erased)
+  })
 })

packages/stack/src/supabase/query-builder-v3.ts

@@ -516,7 +516,19 @@ export class EncryptedQueryBuilderV3Impl<
         `bulk encryption returned ${encrypted.length} terms for ${values.length} values on column "${column.getName()}".`,
       )
     }
-    return encrypted.map((term) => term.data)
+    return encrypted.map((term, i) => {
+      // `BulkEncryptedData` types the element as `Encrypted | null`. A `null`
+      // envelope here would be `JSON.stringify`'d to the literal string `"null"`
+      // and sent as the filter operand — silently matching whatever `"null"`
+      // encodes to rather than failing. A query term should never encrypt to a
+      // null envelope, so treat it as a contract violation, not a value.
+      if (term.data === null) {
+        this.encryptionFailure(
+          `bulk encryption returned a null envelope at position ${i} for column "${column.getName()}".`,
+        )
+      }
+      return term.data
+    })
   }
 
   /** Fallback for a client that predates `bulkEncrypt`. */

packages/stack/src/supabase/query-builder.ts

@@ -1533,7 +1533,11 @@ type TermMapping =
     }
 
 type EncryptedFilterState = {
-  encryptedValues: unknown[]
+  // `EncryptedQueryResult[]`, not `unknown[]` — `encryptCollectedTerms` returns
+  // that type, and typing the field to match is what lets the restored envelope
+  // type reach the use site (`encryptedValues[i]`) instead of widening back to
+  // `unknown` at this boundary.
+  encryptedValues: EncryptedQueryResult[]
   termMap: TermMapping[]
 }