feat(stack): add EQL v3 bigint domain family (i64, native JS bigint on protect-ffi 0.28)

Add BIGINT/BIGINT_EQ/BIGINT_ORD_ORE/BIGINT_ORD domain definitions against
the public.bigint* concrete domains, the EncryptedBigint*Column classes,
types.Bigint* factories, barrel exports, and union membership, following the
existing per-domain pattern. The SDK-wide Plaintext union gains bigint, and
PlaintextKind/PlaintextFromKind map cast_as 'bigint' to the JS bigint type
(bigint columns always decrypt to a JS bigint).

Shipped UN-GATED: protect-ffi 0.28 marshals a native JS bigint across the Neon
boundary losslessly (encode on the way in, JsBigInt::from_i64 on decrypt), so
no reconstruction is needed on the decrypt path and the live matrix suites
exercise the round-trip directly. i64 bounds are enforced at the protect-ffi
boundary. Index emission follows the numeric rule: bigint_eq -> unique (hm);
bigint_ord/bigint_ord_ore -> ore (equality via ob).

Removes the base's bigint skip changeset and flips the schema-v3 type guard
from a negative (@ts-expect-error) to a positive assertion. The catalog-driven
capability sweep and live-PG matrix pick up the four public.bigint* rows
automatically (no liveGate).

Re-expressed from james/cip-3291-bigint-stack 2495c65 + e593415 against the
public.* domain surface and protect-ffi 0.28.

Author: tobyhede

.changeset/eql-v3-bigint-domains.md

@@ -0,0 +1,11 @@
+---
+'@cipherstash/stack': minor
+---
+
+Add the EQL v3 bigint domain family to the public DSL: `types.Bigint`,
+`types.BigintEq`, `types.BigintOrdOre`, and `types.BigintOrd`, backed by the
+`public.bigint*` concrete domains. Plaintext is a JS `bigint`, round-tripped
+losslessly across the protect-ffi 0.28 boundary (i64 bounds enforced at the
+FFI — out-of-range values surface as encryption errors). Index emission follows
+the numeric rule: `bigint_eq` → unique (hm); `bigint_ord`/`bigint_ord_ore` →
+ore (equality answered via ob).

.changeset/skip-v3-bigint.md

@@ -1,6 +1,7 @@
 import { describe, expectTypeOf, it } from 'vitest'
 import { Encryption, type EncryptionClient } from '@/encryption'
 import type {
+  EncryptedBigintColumn,
   EncryptedTextSearchColumn,
   InferEncrypted,
   InferPlaintext,
@@ -21,9 +22,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('types.Bigint returns an EncryptedBigintColumn (native bigint round-trip on protect-ffi 0.28)', () => {
+    const col = types.Bigint('large')
+    expectTypeOf(col).toEqualTypeOf<EncryptedBigintColumn>()
   })
 
   it('encryptedTable exposes column builders as typed properties', () => {
@@ -65,6 +66,7 @@ describe('eql_v3 schema type inference', () => {
       active: types.Boolean('active'),
       createdAt: types.Timestamp('created_at'),
       score: types.Double('score'),
+      balance: types.BigintOrd('balance'),
     })
 
     type Plaintext = InferPlaintext<typeof metrics>
@@ -75,6 +77,7 @@ describe('eql_v3 schema type inference', () => {
       active: boolean
       createdAt: Date
       score: number
+      balance: bigint
     }>()
   })
 

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

@@ -170,6 +170,11 @@ describe('eql_v3 concrete type names', () => {
     )
     expect(types.SmallintOrd('n').getEqlType()).toBe('public.smallint_ord')
 
+    expect(types.Bigint('n').getEqlType()).toBe('public.bigint')
+    expect(types.BigintEq('n').getEqlType()).toBe('public.bigint_eq')
+    expect(types.BigintOrdOre('n').getEqlType()).toBe('public.bigint_ord_ore')
+    expect(types.BigintOrd('n').getEqlType()).toBe('public.bigint_ord')
+
     expect(types.Boolean('b').getEqlType()).toBe('public.boolean')
     expect(types.Real('n').getEqlType()).toBe('public.real')
     expect(types.RealEq('n').getEqlType()).toBe('public.real_eq')

packages/stack/__tests__/schema-v3.test.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,16 @@ 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
+// Full i64 bounds (enforced at the protect-ffi boundary): i64::MAX, i64::MIN,
+// zero, a negative, and a mid value beyond Number.MAX_SAFE_INTEGER to prove
+// protect-ffi 0.28 round-trips a JS bigint losslessly.
+const BIGINT_S = [
+  4611686018427387904n,
+  -42n,
+  9223372036854775807n,
+  -9223372036854775808n,
+  0n,
+] 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 +234,11 @@ export const V3_MATRIX = {
   'public.smallint_eq': { builder: types.SmallintEq, ColumnClass: EncryptedSmallintEqColumn, castAs: 'number', capabilities: EQ, indexes: UNIQUE_IDX, samples: SMALLINT_S, errorSamples: NUM_ERR },
   'public.smallint_ord_ore': { builder: types.SmallintOrdOre, ColumnClass: EncryptedSmallintOrdOreColumn, castAs: 'number', capabilities: ORD, indexes: ORE_IDX, samples: SMALLINT_S, errorSamples: NUM_ERR },
   'public.smallint_ord': { builder: types.SmallintOrd, ColumnClass: EncryptedSmallintOrdColumn, castAs: 'number', capabilities: ORD, indexes: ORE_IDX, samples: SMALLINT_S, errorSamples: NUM_ERR },
+  // bigint (int8) — native JS bigint round-trip on protect-ffi 0.28; ungated
+  'public.bigint': { builder: types.Bigint, ColumnClass: EncryptedBigintColumn, castAs: 'bigint', capabilities: STORAGE, indexes: NONE, samples: BIGINT_S },
+  'public.bigint_eq': { builder: types.BigintEq, ColumnClass: EncryptedBigintEqColumn, castAs: 'bigint', capabilities: EQ, indexes: UNIQUE_IDX, samples: BIGINT_S },
+  'public.bigint_ord_ore': { builder: types.BigintOrdOre, ColumnClass: EncryptedBigintOrdOreColumn, castAs: 'bigint', capabilities: ORD, indexes: ORE_IDX, samples: BIGINT_S },
+  'public.bigint_ord': { builder: types.BigintOrd, ColumnClass: EncryptedBigintOrdColumn, castAs: 'bigint', capabilities: ORD, indexes: ORE_IDX, samples: BIGINT_S },
   // date
   'public.date': { builder: types.Date, ColumnClass: EncryptedDateColumn, castAs: 'date', capabilities: STORAGE, indexes: NONE, samples: DATE_S },
   'public.date_eq': { builder: types.DateEq, ColumnClass: EncryptedDateEqColumn, castAs: 'date', capabilities: EQ, indexes: UNIQUE_IDX, samples: DATE_S },

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

@@ -25,6 +25,7 @@ const records = encryptedTable('records', {
   count: V3_MATRIX['public.integer'].builder('count'), // number, storage-only
   score: V3_MATRIX['public.integer_eq'].builder('score'), // number, equality
   rank: V3_MATRIX['public.integer_ord'].builder('rank'), // number, order + range
+  balance: V3_MATRIX['public.bigint_ord'].builder('balance'), // bigint, order + range
   createdAt: V3_MATRIX['public.timestamp_ord'].builder('created_at'), // date
   email: V3_MATRIX['public.text_search'].builder('email'), // string, full-text
   active: V3_MATRIX['public.boolean'].builder('active'), // boolean, storage-only
@@ -36,6 +37,7 @@ describe('eql_v3 type-driven matrix (types)', () => {
       count: number
       score: number
       rank: number
+      balance: bigint
       createdAt: Date
       email: string
       active: boolean
@@ -52,6 +54,9 @@ describe('eql_v3 type-driven matrix (types)', () => {
     expectTypeOf<QueryTypesForColumn<typeof records.rank>>().toEqualTypeOf<
       'equality' | 'orderAndRange'
     >()
+    expectTypeOf<QueryTypesForColumn<typeof records.balance>>().toEqualTypeOf<
+      'equality' | 'orderAndRange'
+    >()
     expectTypeOf<QueryTypesForColumn<typeof records.createdAt>>().toEqualTypeOf<
       'equality' | 'orderAndRange'
     >()

packages/stack/__tests__/v3-matrix/matrix.test-d.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: only date-like casts need per-row reconstruction. `bigint` (int8)
+ * needs none — protect-ffi 0.28 returns a native JS `bigint` on decrypt
+ * (and bounds-checks/encodes it on encrypt), so those columns pass through
+ * unchanged, exactly like `string`/`number`/`boolean`.
  */
 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,31 @@ 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, which round-trips a native bigint losslessly. (`*_ord_ope`
+// variants are out of scope — CIP-3403.)
+export const BIGINT = {
+  eqlType: 'public.bigint',
+  castAs: 'bigint',
+  capabilities: STORAGE_ONLY,
+} as const
+export const BIGINT_EQ = {
+  eqlType: 'public.bigint_eq',
+  castAs: 'bigint',
+  capabilities: EQUALITY_ONLY,
+} as const
+export const BIGINT_ORD_ORE = {
+  eqlType: 'public.bigint_ord_ore',
+  castAs: 'bigint',
+  capabilities: ORDER_AND_RANGE,
+} as const
+export const BIGINT_ORD = {
+  eqlType: 'public.bigint_ord',
+  castAs: 'bigint',
+  capabilities: ORDER_AND_RANGE,
+} as const
+
 export const DATE = {
   eqlType: 'public.date',
   castAs: 'date',
@@ -497,6 +522,19 @@ export class EncryptedSmallintOrdColumn extends EncryptedV3Column<
   typeof SMALLINT_ORD
 > {}
 
+// bigint (int8) — plaintext is a JS `bigint`, round-tripped losslessly by the
+// native protect-ffi boundary (see 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 +622,10 @@ export type AnyEncryptedV3Column =
   | EncryptedSmallintEqColumn
   | EncryptedSmallintOrdOreColumn
   | EncryptedSmallintOrdColumn
+  | EncryptedBigintColumn
+  | EncryptedBigintEqColumn
+  | EncryptedBigintOrdOreColumn
+  | EncryptedBigintOrdColumn
   | EncryptedDateColumn
   | EncryptedDateEqColumn
   | EncryptedDateOrdOreColumn
@@ -625,11 +667,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`, round-tripped losslessly by
+  // the native protect-ffi boundary (see ./columns)
+  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),