feat(stack): bulkEncrypt/bulkDecrypt on the wasm-inline entry (CIP-3584)

The WASM entry exposed no bulk operations at all — only encrypt/decrypt —
so rendering an N-row list on Deno, Cloudflare Workers, or Supabase Edge
Functions cost N sequential ZeroKMS round trips. Combined with the ~6.6s
cold start that made list endpoints impractical on the edge, and it left
the entry with no access to the bulk path AGENTS.md names as the way to
exercise ZeroKMS bulk speed. Surfaced as M1 in the rc.3 skilltester run.

The FFI already had the primitives — `encryptBulk`, `decryptBulkFallible`
are exported from protect-ffi's WASM build (identical in 0.29 and 0.30).
This wires them up; no new capability was needed underneath.

Signature deliberately differs from the native entry's bulk methods. It
follows `encryptQueryBulk`, the bulk primitive already on this client: an
index-aligned array with per-item table/column routing, throwing rather
than a `{ data } | { failure }` envelope. No `{ id, plaintext }` payload
envelopes either — protect-ffi's `EncryptPayload` has no `id` field, so
the native one is dropped at the boundary and buys nothing once positions
are stable. Consistency within this surface beats parity with a different
entry point, since a WASM caller is reading this module's API.

Per-item routing is what makes the saving real: one call covers several
columns across many rows, where a single-column batch would still cost one
round trip per column.

Two failure modes are handled rather than assumed away:

- `bulkDecrypt` builds on the FALLIBLE primitive, so when items fail it
  throws once naming every failing index and reason, instead of surfacing
  the first and discarding work the caller already paid for.
- Both methods assert the FFI returned as many results as were sent.
  Matching is positional (no correlation id), so a short response would
  silently leave trailing slots null — indistinguishable from "this row
  had no value". That is silent wrong data, so it throws.

Model helpers stay Node-only: this entry has no single-model operation to
build them on, so adding bulk-model alone would be incoherent. Noted in
the class docblock as a separate port.

14 new unit tests: one-FFI-call-per-batch, payload shape, mixed
tables/columns with declared-vs-property column names, position stability
across null/undefined, all-null and empty short-circuits, per-index
failure reporting, and both length-mismatch guards. 823 tests pass;
typecheck and build clean; 0 biome errors.

Skill updated — `stash-encryption` documented only the native bulk shape,
which would not compile on the edge.

Author: coderdan

.changeset/wasm-inline-bulk-ops.md

@@ -0,0 +1,27 @@
+---
+'@cipherstash/stack': minor
+'stash': patch
+---
+
+Add `bulkEncrypt` / `bulkDecrypt` to `@cipherstash/stack/wasm-inline`, so a list of encrypted rows costs **one** ZeroKMS round trip instead of one per row.
+
+The WASM entry previously exposed no bulk operations at all — only `encrypt` / `decrypt` — so rendering an N-row list on Deno, Cloudflare Workers, or Supabase Edge Functions meant N sequential ZeroKMS calls. Combined with the WASM cold start, that made list endpoints impractical on the edge, and it left the entry with no access to the bulk path the docs recommend for throughput.
+
+```typescript
+// Write: several columns across many rows, one round trip
+const encrypted = await client.bulkEncrypt([
+  { plaintext: "alice@example.com", table: users, column: users.email },
+  { plaintext: "hello", table: users, column: users.bio },
+])
+
+// Read: a whole page in one call
+const emails = await client.bulkDecrypt(rows.map((r) => r.email))
+```
+
+Both are index-aligned with their input, and `null` / `undefined` entries yield `null` at the same index without reaching ZeroKMS (an all-null batch makes no call at all). Because each entry names its own table and column, a single `bulkEncrypt` can cover several columns across many rows.
+
+**The signature deliberately differs from the native entry's** `bulkEncrypt` / `bulkDecrypt`. It follows `encryptQueryBulk`, the bulk primitive already on this client: a plain index-aligned array with per-item routing, and errors that throw rather than a `{ data } | { failure }` envelope. There are no `{ id, plaintext }` payload envelopes — protect-ffi's `EncryptPayload` has no `id` field, so the native one is dropped at the FFI boundary and buys nothing when positions are already stable.
+
+`bulkDecrypt` builds on the fallible FFI primitive, so when items fail it throws once and names **every** failing index with its reason, rather than surfacing the first and discarding the rest.
+
+The model helpers (`encryptModel` / `decryptModel` and their bulk forms) remain Node-only: the WASM entry has no single-model operation to build them on, so those need their own port.

packages/stack/__tests__/helpers/stub-protect-ffi-wasm-inline.ts

@@ -14,12 +14,24 @@ export const decrypt = (): never => {
   )
 }
 
+export const decryptBulkFallible = (): never => {
+  throw new Error(
+    '[test stub]: protect-ffi/wasm-inline decryptBulkFallible not implemented',
+  )
+}
+
 export const encrypt = (): never => {
   throw new Error(
     '[test stub]: protect-ffi/wasm-inline encrypt not implemented',
   )
 }
 
+export const encryptBulk = (): never => {
+  throw new Error(
+    '[test stub]: protect-ffi/wasm-inline encryptBulk not implemented',
+  )
+}
+
 export const encryptQuery = (): never => {
   throw new Error(
     '[test stub]: protect-ffi/wasm-inline encryptQuery not implemented',

packages/stack/__tests__/wasm-inline-bulk.test.ts

@@ -0,0 +1,265 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// #737: the WASM entry exposed no bulk operations, so an N-row list on the
+// edge cost N ZeroKMS round trips. These tests pin the new surface: the FFI
+// payload shape (`{ plaintext, table, column }` / `{ ciphertext }` — the
+// protect-ffi `EncryptPayload` has no `id`, unlike the native entry's), that
+// exactly ONE FFI call is made per batch (the whole point), position
+// stability across nulls, and the per-index failure reporting that
+// `decryptBulkFallible` makes possible. protect-ffi is mocked; live coverage
+// runs in the Deno e2e.
+
+const ffi = vi.hoisted(() => ({
+  newClient: vi.fn(async () => ({ handle: 'wasm-client' })),
+  encrypt: vi.fn(async () => ({ v: 3, i: {}, c: 'ct' })),
+  decrypt: vi.fn(async () => 'plain'),
+  isEncrypted: vi.fn(() => true),
+  encryptQuery: vi.fn(async () => ({ v: 3, i: {} })),
+  encryptQueryBulk: vi.fn(async () => []),
+  encryptBulk: vi.fn(
+    async (_client: unknown, { plaintexts }: { plaintexts: unknown[] }) =>
+      plaintexts.map((_, n) => ({ v: 3, i: {}, c: `ct-${n}` })),
+  ),
+  decryptBulkFallible: vi.fn(
+    async (_client: unknown, { ciphertexts }: { ciphertexts: unknown[] }) =>
+      ciphertexts.map((_, n) => ({ data: `plain-${n}` })),
+  ),
+}))
+vi.mock('@cipherstash/protect-ffi/wasm-inline', () => ffi)
+vi.mock('@cipherstash/auth/wasm-inline', () => ({
+  AccessKeyStrategy: {
+    create: vi.fn(() => ({
+      data: { getToken: async () => ({ token: 'test' }) },
+    })),
+  },
+  OidcFederationStrategy: {},
+}))
+
+import { encryptedTable, types } from '../src/eql/v3'
+import { Encryption } from '../src/wasm-inline'
+
+const users = encryptedTable('users', {
+  email: types.TextEq('email'),
+  bio: types.TextSearch('bio'),
+})
+
+// A column whose declared DB name differs from the property, so the payload
+// assertion proves `getColumnName` is applied rather than the property key.
+const accounts = encryptedTable('accounts', {
+  emailAddress: types.TextEq('email_address'),
+})
+
+async function client() {
+  return Encryption({
+    schemas: [users, accounts],
+    config: {
+      workspaceCrn: 'crn:test:ws',
+      accessKey: 'test-key',
+      clientId: 'id',
+      clientKey: 'key',
+    },
+  })
+}
+
+const ct = (c: string) => ({ v: 3, i: { t: 'users', c: 'email' }, c }) as never
+
+describe('WasmEncryptionClient.bulkEncrypt', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('sends one FFI call for the whole batch', async () => {
+    const c = await client()
+    await c.bulkEncrypt([
+      { plaintext: 'a@b.com', table: users, column: users.email },
+      { plaintext: 'hello', table: users, column: users.bio },
+      { plaintext: 'c@d.com', table: users, column: users.email },
+    ])
+
+    // The entire reason this method exists: 3 values, 1 round trip.
+    expect(ffi.encryptBulk).toHaveBeenCalledTimes(1)
+    expect(ffi.encrypt).not.toHaveBeenCalled()
+  })
+
+  it('builds the FFI payload as { plaintext, table, column } with no id', async () => {
+    const c = await client()
+    await c.bulkEncrypt([
+      { plaintext: 'a@b.com', table: users, column: users.email },
+      { plaintext: 'hello', table: users, column: users.bio },
+    ])
+
+    const [, opts] = ffi.encryptBulk.mock.calls[0]
+    expect(opts.plaintexts).toEqual([
+      { plaintext: 'a@b.com', table: 'users', column: 'email' },
+      { plaintext: 'hello', table: 'users', column: 'bio' },
+    ])
+    // protect-ffi's EncryptPayload has no `id` — the native entry's is
+    // dropped at the boundary, so sending one would be dead weight.
+    for (const p of opts.plaintexts as Array<Record<string, unknown>>) {
+      expect(p).not.toHaveProperty('id')
+    }
+  })
+
+  it('mixes tables and columns in a single batch', async () => {
+    const c = await client()
+    await c.bulkEncrypt([
+      { plaintext: 'a@b.com', table: users, column: users.email },
+      {
+        plaintext: 'x@y.com',
+        table: accounts,
+        column: accounts.emailAddress,
+      },
+    ])
+
+    const [, opts] = ffi.encryptBulk.mock.calls[0]
+    expect(opts.plaintexts).toEqual([
+      { plaintext: 'a@b.com', table: 'users', column: 'email' },
+      // The DECLARED column name, not the property key.
+      { plaintext: 'x@y.com', table: 'accounts', column: 'email_address' },
+    ])
+  })
+
+  it('is position-stable across null and undefined plaintexts', async () => {
+    const c = await client()
+    const out = await c.bulkEncrypt([
+      { plaintext: null, table: users, column: users.email },
+      { plaintext: 'a@b.com', table: users, column: users.email },
+      { plaintext: undefined, table: users, column: users.email },
+      { plaintext: 'c@d.com', table: users, column: users.email },
+    ])
+
+    expect(out).toHaveLength(4)
+    expect(out[0]).toBeNull()
+    expect(out[2]).toBeNull()
+    // Live values keep their ORIGINAL indices, not their compacted ones.
+    expect(out[1]).toEqual({ v: 3, i: {}, c: 'ct-0' })
+    expect(out[3]).toEqual({ v: 3, i: {}, c: 'ct-1' })
+
+    // Nulls never reach ZeroKMS.
+    const [, opts] = ffi.encryptBulk.mock.calls[0]
+    expect(opts.plaintexts).toHaveLength(2)
+  })
+
+  it('short-circuits an all-null batch without calling the FFI', async () => {
+    const c = await client()
+    const out = await c.bulkEncrypt([
+      { plaintext: null, table: users, column: users.email },
+      { plaintext: undefined, table: users, column: users.email },
+    ])
+
+    expect(out).toEqual([null, null])
+    expect(ffi.encryptBulk).not.toHaveBeenCalled()
+  })
+
+  it('returns an empty array for an empty batch, with no FFI call', async () => {
+    const c = await client()
+    expect(await c.bulkEncrypt([])).toEqual([])
+    expect(ffi.encryptBulk).not.toHaveBeenCalled()
+  })
+})
+
+describe('WasmEncryptionClient.bulkDecrypt', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('sends one FFI call for the whole batch', async () => {
+    const c = await client()
+    await c.bulkDecrypt([ct('a'), ct('b'), ct('c')])
+
+    expect(ffi.decryptBulkFallible).toHaveBeenCalledTimes(1)
+    expect(ffi.decrypt).not.toHaveBeenCalled()
+  })
+
+  it('builds the FFI payload as { ciphertext }', async () => {
+    const c = await client()
+    const a = ct('a')
+    const b = ct('b')
+    await c.bulkDecrypt([a, b])
+
+    const [, opts] = ffi.decryptBulkFallible.mock.calls[0]
+    expect(opts.ciphertexts).toEqual([{ ciphertext: a }, { ciphertext: b }])
+  })
+
+  it('is position-stable across null and undefined ciphertexts', async () => {
+    const c = await client()
+    const out = await c.bulkDecrypt([null, ct('a'), undefined, ct('b')])
+
+    expect(out).toEqual([null, 'plain-0', null, 'plain-1'])
+    const [, opts] = ffi.decryptBulkFallible.mock.calls[0]
+    expect(opts.ciphertexts).toHaveLength(2)
+  })
+
+  it('short-circuits an all-null batch without calling the FFI', async () => {
+    const c = await client()
+    expect(await c.bulkDecrypt([null, undefined])).toEqual([null, null])
+    expect(ffi.decryptBulkFallible).not.toHaveBeenCalled()
+  })
+
+  it('reports EVERY failing index, not just the first', async () => {
+    ffi.decryptBulkFallible.mockResolvedValueOnce([
+      { data: 'ok' },
+      { error: 'boom-one' },
+      { error: 'boom-two' },
+    ] as never)
+
+    const c = await client()
+    // Indices are into the INPUT array, so the leading null shifts them:
+    // input 1/2/3 map to live 0/1/2, and the two failures are inputs 2 and 3.
+    await expect(
+      c.bulkDecrypt([null, ct('a'), ct('b'), ct('c')]),
+    ).rejects.toThrow(/failed for 2 of 3 payload\(s\)/)
+
+    ffi.decryptBulkFallible.mockResolvedValueOnce([
+      { data: 'ok' },
+      { error: 'boom-one' },
+      { error: 'boom-two' },
+    ] as never)
+    const err = await c
+      .bulkDecrypt([null, ct('a'), ct('b'), ct('c')])
+      .catch((e: Error) => e)
+
+    expect((err as Error).message).toContain('[2]: boom-one')
+    expect((err as Error).message).toContain('[3]: boom-two')
+  })
+
+  it('succeeds when every item decrypts', async () => {
+    const c = await client()
+    await expect(c.bulkDecrypt([ct('a'), ct('b')])).resolves.toEqual([
+      'plain-0',
+      'plain-1',
+    ])
+  })
+})
+
+// Results are matched to inputs BY POSITION — the FFI payloads carry no
+// correlation id. A short response would otherwise leave trailing slots null,
+// which a caller cannot tell apart from "this row had no value".
+describe('bulk result/input length mismatch', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('bulkEncrypt throws rather than returning a partially-null batch', async () => {
+    ffi.encryptBulk.mockResolvedValueOnce([{ v: 3, i: {}, c: 'only-one' }])
+
+    const c = await client()
+    await expect(
+      c.bulkEncrypt([
+        { plaintext: 'a', table: users, column: users.email },
+        { plaintext: 'b', table: users, column: users.email },
+      ]),
+    ).rejects.toThrow(/sent 2 payload\(s\).*received 1 back/s)
+  })
+
+  it('bulkDecrypt throws rather than returning a partially-null batch', async () => {
+    ffi.decryptBulkFallible.mockResolvedValueOnce([
+      { data: 'only-one' },
+    ] as never)
+
+    const c = await client()
+    await expect(c.bulkDecrypt([ct('a'), ct('b')])).rejects.toThrow(
+      /sent 2 payload\(s\).*received 1 back/s,
+    )
+  })
+})