feat(stack): re-enable EQL v3 bigint domain family on protect-ffi 0.28

Native bigint round-tripping landed in protect-ffi 0.28, so restore the
bigint domains that skip-v3-bigint deferred:

- columns.ts: BIGINT/BIGINT_EQ/BIGINT_ORD/BIGINT_ORD_ORE definitions
  (concrete domain eql_v3.int8* per the SQL fixture, castAs 'bigint'),
  EncryptedBigint*Column classes, AnyEncryptedV3Column union, and
  PlaintextKind/PlaintextFromKind mapping 'bigint' -> JS bigint.
- types.ts / index.ts: types.Bigint* factories and barrel exports.
- v3-matrix/catalog.ts: four int8 rows with i64-bound samples (max/min/0
  and a value past Number.MAX_SAFE_INTEGER); samples widened to bigint.
  Drizzle operator coverage is catalog-driven, so it picks these up too.
- schema-v3.test-d: flip the "bigint not public" negative test to assert
  the factories now exist.
- encryption/v3.ts: bigint needs no decrypt reconstruction (FFI returns a
  real JS bigint on 0.28).
- drop .changeset/skip-v3-bigint.md; add re-enable changeset.

i64 bounds are enforced at the protect-ffi boundary. *_ord_ope is out of
scope (CIP-3403).

Author: tobyhede

.changeset/eql-v3-bigint.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/stack': minor
+---
+
+Re-enable the EQL v3 bigint domain family now that native bigint round-tripping landed in `@cipherstash/protect-ffi` 0.28. Adds the `types.Bigint` / `types.BigintEq` / `types.BigintOrd` / `types.BigintOrdOre` factories (concrete Postgres domains `eql_v3.int8`, `eql_v3.int8_eq`, `eql_v3.int8_ord`, `eql_v3.int8_ord_ore`), their `EncryptedBigint*Column` classes, and full test-matrix + Drizzle operator coverage. Bigint columns take and decrypt to a JS `bigint`; i64 bounds (`-2^63 … 2^63 - 1`) are enforced at the protect-ffi boundary.

.changeset/skip-v3-bigint.md

@@ -1,6 +1,8 @@
 import { describe, expectTypeOf, it } from 'vitest'
 import { Encryption, type EncryptionClient } from '@/encryption'
 import type {
+  EncryptedBigintColumn,
+  EncryptedBigintOrdColumn,
   EncryptedTextSearchColumn,
   InferEncrypted,
   InferPlaintext,
@@ -21,9 +23,9 @@ describe('eql_v3 schema type inference', () => {
     expectTypeOf(col).toEqualTypeOf<EncryptedTextSearchColumn>()
   })
 
-  it('does not expose bigint factories until native bigint round-tripping lands', () => {
-    // @ts-expect-error - bigint v3 domains are intentionally not public yet
-    types.Bigint('large')
+  it('exposes bigint factories (native round-tripping landed in protect-ffi 0.28)', () => {
+    expectTypeOf(types.Bigint('large')).toEqualTypeOf<EncryptedBigintColumn>()
+    expectTypeOf(types.BigintOrd('large')).toEqualTypeOf<EncryptedBigintOrdColumn>()
   })
 
   it('encryptedTable exposes column builders as typed properties', () => {

packages/stack/__tests__/schema-v3.test-d.ts

@@ -23,6 +23,10 @@ import type {
   QueryCapabilities,
 } from '@/eql/v3'
 import {
+  EncryptedBigintColumn,
+  EncryptedBigintEqColumn,
+  EncryptedBigintOrdColumn,
+  EncryptedBigintOrdOreColumn,
   EncryptedBooleanColumn,
   EncryptedDateColumn,
   EncryptedDateEqColumn,
@@ -99,7 +103,7 @@ export type DomainSpec = Readonly<{
    * tell `integer` from `double`, and a fractional value on an int-named domain is
    * untested territory (it would truncate against a real narrow PG column).
    */
-  samples: ReadonlyArray<string | number | boolean | Date>
+  samples: ReadonlyArray<string | number | bigint | boolean | Date>
   /**
    * Values that MUST fail encryption. Number domains reject `NaN`/`±Infinity`
    * via a global guard; other domains omit this.
@@ -175,6 +179,14 @@ const TEXT_SEARCH_IDX: Indexes = {
 // smallint/integer, fractionals for real/double/numeric. See `DomainSpec.samples`.
 const SMALLINT_S = [0, -1, 32767, -32768] as const
 const INTEGER_S = [0, -42, 2147483647, -2147483648] as const
+// bigint (int8) plaintexts: i64 bounds, 0, and a value beyond
+// Number.MAX_SAFE_INTEGER (2^53 - 1) that would lose precision as a JS `number`.
+const BIGINT_S = [
+  0n,
+  9223372036854775807n,
+  -9223372036854775808n,
+  9007199254740993n,
+] as const
 const REAL_S = [0, 77.5, -117.25, 0.5] as const
 const DOUBLE_S = [0, -117.123456, 1e15, -1e15] as const
 const NUMERIC_S = [0, 12345.678, -42, -0.5] as const
@@ -220,6 +232,11 @@ export const V3_MATRIX = {
   'eql_v3.smallint_eq': { builder: types.SmallintEq, ColumnClass: EncryptedSmallintEqColumn, castAs: 'number', capabilities: EQ, indexes: UNIQUE_IDX, samples: SMALLINT_S, errorSamples: NUM_ERR },
   'eql_v3.smallint_ord_ore': { builder: types.SmallintOrdOre, ColumnClass: EncryptedSmallintOrdOreColumn, castAs: 'number', capabilities: ORD, indexes: ORE_IDX, samples: SMALLINT_S, errorSamples: NUM_ERR },
   'eql_v3.smallint_ord': { builder: types.SmallintOrd, ColumnClass: EncryptedSmallintOrdColumn, castAs: 'number', capabilities: ORD, indexes: ORE_IDX, samples: SMALLINT_S, errorSamples: NUM_ERR },
+  // bigint (int8) — plaintext is a JS `bigint`; no errorSamples (bigint has no NaN/Infinity)
+  'eql_v3.int8': { builder: types.Bigint, ColumnClass: EncryptedBigintColumn, castAs: 'bigint', capabilities: STORAGE, indexes: NONE, samples: BIGINT_S },
+  'eql_v3.int8_eq': { builder: types.BigintEq, ColumnClass: EncryptedBigintEqColumn, castAs: 'bigint', capabilities: EQ, indexes: UNIQUE_IDX, samples: BIGINT_S },
+  'eql_v3.int8_ord_ore': { builder: types.BigintOrdOre, ColumnClass: EncryptedBigintOrdOreColumn, castAs: 'bigint', capabilities: ORD, indexes: ORE_IDX, samples: BIGINT_S },
+  'eql_v3.int8_ord': { builder: types.BigintOrd, ColumnClass: EncryptedBigintOrdColumn, castAs: 'bigint', capabilities: ORD, indexes: ORE_IDX, samples: BIGINT_S },
   // date
   'eql_v3.date': { builder: types.Date, ColumnClass: EncryptedDateColumn, castAs: 'date', capabilities: STORAGE, indexes: NONE, samples: DATE_S },
   'eql_v3.date_eq': { builder: types.DateEq, ColumnClass: EncryptedDateEqColumn, castAs: 'date', capabilities: EQ, indexes: UNIQUE_IDX, samples: DATE_S },

packages/stack/__tests__/v3-matrix/catalog.ts

@@ -128,8 +128,10 @@ export interface TypedEncryptionClient<S extends readonly AnyV3Table[]> {
  * row-invariant, but non-trivial to build — is derived once per call site,
  * not once per row on the bulk path.
  *
- * NOTE: `bigint` (int8) reconstruction is intentionally absent — int8 domains are
- * omitted from the v3 SDK until the native FFI supports lossless bigint I/O.
+ * NOTE: `bigint` (int8) columns need NO reconstruction here — protect-ffi 0.28
+ * marshals a JS `bigint` across the Neon boundary and returns a real JS `bigint`
+ * on decrypt, which the model decrypt path passes through with no JSON
+ * round-trip that could destroy it. Only date-like domains are rebuilt below.
  */
 function rowReconstructor(
   table: AnyV3Table,

packages/stack/src/encryption/v3.ts

@@ -40,7 +40,7 @@ export type DateLikeCast = (typeof DATE_LIKE_CASTS)[number]
 
 /** The plaintext (TypeScript) kind a v3 domain decrypts to. A subset of the
  * SDK `CastAs` enum, restricted to the scalar kinds v3 domains actually use. */
-type PlaintextKind = 'string' | 'number' | 'boolean' | DateLikeCast
+type PlaintextKind = 'string' | 'number' | 'bigint' | 'boolean' | DateLikeCast
 
 /**
  * The full, literal definition of a v3 domain. This is the LOAD-BEARING type:
@@ -152,6 +152,33 @@ export const SMALLINT_ORD = {
   capabilities: ORDER_AND_RANGE,
 } as const
 
+// bigint (int8) domains. Plaintext is a JS `bigint` (always decrypts to
+// `bigint`); bounds are the full i64 range, enforced at the protect-ffi
+// boundary. Native round-tripping landed in protect-ffi 0.28 (`JsPlaintext`
+// marshals a JS `bigint` across the Neon boundary), so live encrypt/decrypt is
+// no longer gated (`*_ord_ope` variants are out of scope — CIP-3403). The
+// concrete domain is the SQL fixture's `int8` name, not `bigint`.
+export const BIGINT = {
+  eqlType: 'eql_v3.int8',
+  castAs: 'bigint',
+  capabilities: STORAGE_ONLY,
+} as const
+export const BIGINT_EQ = {
+  eqlType: 'eql_v3.int8_eq',
+  castAs: 'bigint',
+  capabilities: EQUALITY_ONLY,
+} as const
+export const BIGINT_ORD_ORE = {
+  eqlType: 'eql_v3.int8_ord_ore',
+  castAs: 'bigint',
+  capabilities: ORDER_AND_RANGE,
+} as const
+export const BIGINT_ORD = {
+  eqlType: 'eql_v3.int8_ord',
+  castAs: 'bigint',
+  capabilities: ORDER_AND_RANGE,
+} as const
+
 export const DATE = {
   eqlType: 'eql_v3.date',
   castAs: 'date',
@@ -497,6 +524,19 @@ export class EncryptedSmallintOrdColumn extends EncryptedV3Column<
   typeof SMALLINT_ORD
 > {}
 
+// bigint (int8) — native round-trips landed in protect-ffi 0.28; see the note
+// by the BIGINT domain definitions above.
+export class EncryptedBigintColumn extends EncryptedV3Column<typeof BIGINT> {}
+export class EncryptedBigintEqColumn extends EncryptedV3Column<
+  typeof BIGINT_EQ
+> {}
+export class EncryptedBigintOrdOreColumn extends EncryptedV3Column<
+  typeof BIGINT_ORD_ORE
+> {}
+export class EncryptedBigintOrdColumn extends EncryptedV3Column<
+  typeof BIGINT_ORD
+> {}
+
 // date
 export class EncryptedDateColumn extends EncryptedV3Column<typeof DATE> {}
 export class EncryptedDateEqColumn extends EncryptedV3Column<typeof DATE_EQ> {}
@@ -584,6 +624,10 @@ export type AnyEncryptedV3Column =
   | EncryptedSmallintEqColumn
   | EncryptedSmallintOrdOreColumn
   | EncryptedSmallintOrdColumn
+  | EncryptedBigintColumn
+  | EncryptedBigintEqColumn
+  | EncryptedBigintOrdOreColumn
+  | EncryptedBigintOrdColumn
   | EncryptedDateColumn
   | EncryptedDateEqColumn
   | EncryptedDateOrdOreColumn
@@ -625,11 +669,13 @@ type PlaintextFromKind<K extends PlaintextKind> = K extends 'string'
   ? string
   : K extends 'number'
     ? number
-    : K extends 'boolean'
-      ? boolean
-      : K extends DateLikeCast
-        ? Date
-        : never
+    : K extends 'bigint'
+      ? bigint
+      : K extends 'boolean'
+        ? boolean
+        : K extends DateLikeCast
+          ? Date
+          : never
 
 /**
  * The plaintext type for a single v3 column, read from the literal domain

packages/stack/src/eql/v3/columns.ts

@@ -18,6 +18,10 @@ export type {
 } from './columns'
 
 export {
+  EncryptedBigintColumn,
+  EncryptedBigintEqColumn,
+  EncryptedBigintOrdColumn,
+  EncryptedBigintOrdOreColumn,
   EncryptedBooleanColumn,
   EncryptedDateColumn,
   EncryptedDateEqColumn,

packages/stack/src/eql/v3/index.ts

@@ -1,4 +1,8 @@
 import {
+  BIGINT,
+  BIGINT_EQ,
+  BIGINT_ORD,
+  BIGINT_ORD_ORE,
   BOOLEAN,
   DATE,
   DATE_EQ,
@@ -8,6 +12,10 @@ import {
   DOUBLE_EQ,
   DOUBLE_ORD,
   DOUBLE_ORD_ORE,
+  EncryptedBigintColumn,
+  EncryptedBigintEqColumn,
+  EncryptedBigintOrdColumn,
+  EncryptedBigintOrdOreColumn,
   EncryptedBooleanColumn,
   EncryptedDateColumn,
   EncryptedDateEqColumn,
@@ -117,6 +125,14 @@ export const types = {
   SmallintOrd: (name: string) =>
     new EncryptedSmallintOrdColumn(name, SMALLINT_ORD),
 
+  // bigint (int8) — plaintext is a JS `bigint` (i64-bounded at the protect-ffi
+  // boundary); native round-tripping landed in protect-ffi 0.28
+  Bigint: (name: string) => new EncryptedBigintColumn(name, BIGINT),
+  BigintEq: (name: string) => new EncryptedBigintEqColumn(name, BIGINT_EQ),
+  BigintOrdOre: (name: string) =>
+    new EncryptedBigintOrdOreColumn(name, BIGINT_ORD_ORE),
+  BigintOrd: (name: string) => new EncryptedBigintOrdColumn(name, BIGINT_ORD),
+
   // date
   Date: (name: string) => new EncryptedDateColumn(name, DATE),
   DateEq: (name: string) => new EncryptedDateEqColumn(name, DATE_EQ),