feat(stack)!: align the wasm-inline entry to the Result contract

The WASM entry threw on every fallible method — `encrypt`, `decrypt`,
`encryptQuery`, `encryptQueryBulk` — while every other surface in the repo
returns `{ data } | { failure }`. AGENTS.md states that as a contract, not
a preference: "Operations return `{ data }` or `{ failure }`. Preserve
this shape and error `type` values in `EncryptionErrorTypes`."

This was drift, not a design decision. Nothing about WASM prevents it:
`@byteslice/result` is ALREADY bundled into dist/wasm-inline.js
(tsup.config.ts `noExternal`). The cost was that edge code had to be
written in a different shape from every other surface, with failures that
were easy to miss.

Fixed now because it is breaking and 1.0.0 has not shipped —
`@cipherstash/stack@latest` is still 0.19.0, so this surface has only ever
been published under the `rc` tag. After GA it would have waited for a
major. The earlier commit on this branch made the problem worse by adding
two more throwing methods; this corrects both.

All six fallible methods now return `Result<T, EncryptionError>`, with
`failure.type` distinguishing encrypt-side (`EncryptionError`) from
decrypt-side (`DecryptionError`) and `failure.code` carrying the FFI code.
`isEncrypted` stays a bare boolean — a pure predicate with nothing to fail
at, as on the native entry.

Consumers updated: the supabase-worker example (now returns a 500 with the
failure message rather than throwing past the handler), and the WASM
integration adapter via an `unwrap` helper that aborts the harness loudly.

A new `wasm-inline-result-contract.test.ts` pins the contract on both
paths for all six methods so it cannot drift back.

One thing found while testing: `withResult`'s `ensureError` REPLACES any
non-Error throw with `new Error('Something went wrong')` before the error
mapper runs, discarding the original value (@byteslice/result@0.2.0). That
is library-wide — the native entry has it too — so it is pinned as a test
rather than worked around, and will surface if the #532 bump to 0.5.0
changes it.

831 tests pass. Zero new tsc errors (verified by diffing the error set
against main — the pre-existing 107 are unchanged). 0 biome errors.

Author: coderdan

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

@@ -3,9 +3,29 @@
 '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.
+**Breaking (`@cipherstash/stack/wasm-inline`):** every fallible method now returns a `Result` — `{ data } | { failure }` — instead of throwing. And `bulkEncrypt` / `bulkDecrypt` are added, 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.
+### Result alignment
+
+`encrypt`, `decrypt`, `encryptQuery` and `encryptQueryBulk` previously threw on failure, and returned bare values on success. They now return `{ data } | { failure }`, with `failure.type` drawn from `EncryptionErrorTypes` (`EncryptionError` for encrypt-side operations, `DecryptionError` for decrypt-side) and `failure.code` carrying the FFI error code where there is one.
+
+```typescript
+// before
+const encrypted = await client.encrypt(plaintext, { table: users, column: users.email })
+
+// after
+const result = await client.encrypt(plaintext, { table: users, column: users.email })
+if (result.failure) throw new Error(result.failure.message)
+const encrypted = result.data
+```
+
+This is the contract the native entry has always honoured, and the one `AGENTS.md` states outright: *"Operations return `{ data }` or `{ failure }`. Preserve this shape and error `type` values in `EncryptionErrorTypes`."* The WASM entry never followed it. That was drift rather than a design decision — nothing about WASM prevents it (`@byteslice/result` is already bundled into `dist/wasm-inline.js`), and it meant edge code had to be written in a different shape from every other surface, with failures that were easy to miss.
+
+Fixed now because it is a breaking change and 1.0.0 has not shipped: `@cipherstash/stack@latest` is still `0.19.0`, so this surface has only ever been published under the `rc` tag. After GA it would have had to wait for a major.
+
+`isEncrypted` is unchanged — a pure predicate with nothing to fail at, exactly as on the native entry.
+
+### Bulk operations
 
 ```typescript
 // Write: several columns across many rows, one round trip
@@ -18,10 +38,10 @@ const encrypted = await client.bulkEncrypt([
 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 WASM entry previously exposed no bulk operations at all, 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.
 
-**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.
+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 — which is what makes the saving real, since a single-column batch would still cost one round trip per column.
 
-`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.
+`bulkDecrypt` builds on the fallible FFI primitive, so when items fail the `failure.message` 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.

examples/supabase-worker/supabase/functions/cipherstash-roundtrip/index.ts

@@ -61,11 +61,28 @@ Deno.serve(async (_req: Request) => {
     })
 
     const plaintext = 'alice@example.com'
-    const encrypted = await client.encrypt(plaintext, {
+    // Every fallible method returns `{ data } | { failure }` — the same
+    // contract as the native entry (see AGENTS.md).
+    const encryptResult = await client.encrypt(plaintext, {
       column: users.email,
       table: users,
     })
-    const decrypted = await client.decrypt(encrypted)
+    if (encryptResult.failure) {
+      return Response.json(
+        { ok: false, error: encryptResult.failure.message },
+        { status: 500 },
+      )
+    }
+    const encrypted = encryptResult.data
+
+    const decryptResult = await client.decrypt(encrypted)
+    if (decryptResult.failure) {
+      return Response.json(
+        { ok: false, error: decryptResult.failure.message },
+        { status: 500 },
+      )
+    }
+    const decrypted = decryptResult.data
 
     return Response.json(
       {

packages/stack/__tests__/helpers/expect-result.ts

@@ -0,0 +1,28 @@
+import type { Result } from '@byteslice/result'
+import type { EncryptionError } from '../../src/errors'
+
+/**
+ * Narrow a `Result` to its success arm in tests.
+ *
+ * `Result<S, F>` is `Success<S> | Failure<F>`, and `Failure` has NO `data`
+ * property — so `result.data` doesn't type-check until the union is narrowed.
+ * Every assertion on a successful payload would otherwise need its own
+ * `if (r.failure) throw` preamble.
+ *
+ * `F` is pinned to `EncryptionError` rather than left generic: the library
+ * constrains it to `FailureCase | Error`, and a bare type parameter neither
+ * satisfies that constraint nor lets TypeScript discriminate the union.
+ * Every caller here is an encryption operation anyway.
+ *
+ * Throws (rather than using `expect`) so it stays usable outside an assertion
+ * context and reports the failure's own message, which is far more useful than
+ * a bare "expected data to be defined".
+ */
+export function expectData<S>(result: Result<S, EncryptionError>): S {
+  if (result.failure) {
+    throw new Error(
+      `expected { data } but got { failure } (${result.failure.type}): ${result.failure.message}`,
+    )
+  }
+  return result.data
+}

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

@@ -37,6 +37,7 @@ vi.mock('@cipherstash/auth/wasm-inline', () => ({
 
 import { encryptedTable, types } from '../src/eql/v3'
 import { Encryption } from '../src/wasm-inline'
+import { expectData } from './helpers/expect-result'
 
 const users = encryptedTable('users', {
   email: types.TextEq('email'),
@@ -128,12 +129,13 @@ describe('WasmEncryptionClient.bulkEncrypt', () => {
       { plaintext: 'c@d.com', table: users, column: users.email },
     ])
 
-    expect(out).toHaveLength(4)
-    expect(out[0]).toBeNull()
-    expect(out[2]).toBeNull()
+    const values = expectData(out)
+    expect(values).toHaveLength(4)
+    expect(values[0]).toBeNull()
+    expect(values[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' })
+    expect(values[1]).toEqual({ v: 3, i: {}, c: 'ct-0' })
+    expect(values[3]).toEqual({ v: 3, i: {}, c: 'ct-1' })
 
     // Nulls never reach ZeroKMS.
     const [, opts] = ffi.encryptBulk.mock.calls[0]
@@ -147,13 +149,13 @@ describe('WasmEncryptionClient.bulkEncrypt', () => {
       { plaintext: undefined, table: users, column: users.email },
     ])
 
-    expect(out).toEqual([null, null])
+    expect(out).toEqual({ data: [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(await c.bulkEncrypt([])).toEqual({ data: [] })
     expect(ffi.encryptBulk).not.toHaveBeenCalled()
   })
 })
@@ -185,14 +187,16 @@ describe('WasmEncryptionClient.bulkDecrypt', () => {
     const c = await client()
     const out = await c.bulkDecrypt([null, ct('a'), undefined, ct('b')])
 
-    expect(out).toEqual([null, 'plain-0', null, 'plain-1'])
+    expect(out).toEqual({ data: [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(await c.bulkDecrypt([null, undefined])).toEqual({
+      data: [null, null],
+    })
     expect(ffi.decryptBulkFallible).not.toHaveBeenCalled()
   })
 
@@ -208,27 +212,29 @@ describe('WasmEncryptionClient.bulkDecrypt', () => {
     // 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\)/)
+    ).resolves.toMatchObject({
+      failure: {
+        type: 'DecryptionError',
+        message: expect.stringMatching(/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)
+    const res = await c.bulkDecrypt([null, ct('a'), ct('b'), ct('c')])
 
-    expect((err as Error).message).toContain('[2]: boom-one')
-    expect((err as Error).message).toContain('[3]: boom-two')
+    expect(res.failure?.message).toContain('[2]: boom-one')
+    expect(res.failure?.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',
-    ])
+    await expect(c.bulkDecrypt([ct('a'), ct('b')])).resolves.toEqual({
+      data: ['plain-0', 'plain-1'],
+    })
   })
 })
 
@@ -249,7 +255,11 @@ describe('bulk result/input length mismatch', () => {
         { plaintext: 'a', table: users, column: users.email },
         { plaintext: 'b', table: users, column: users.email },
       ]),
-    ).rejects.toThrow(/sent 2 payload\(s\).*received 1 back/s)
+    ).resolves.toMatchObject({
+      failure: {
+        message: expect.stringMatching(/sent 2 payload\(s\).*received 1 back/s),
+      },
+    })
   })
 
   it('bulkDecrypt throws rather than returning a partially-null batch', async () => {
@@ -258,8 +268,10 @@ describe('bulk result/input length mismatch', () => {
     ] as never)
 
     const c = await client()
-    await expect(c.bulkDecrypt([ct('a'), ct('b')])).rejects.toThrow(
-      /sent 2 payload\(s\).*received 1 back/s,
-    )
+    await expect(c.bulkDecrypt([ct('a'), ct('b')])).resolves.toMatchObject({
+      failure: {
+        message: expect.stringMatching(/sent 2 payload\(s\).*received 1 back/s),
+      },
+    })
   })
 })

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

@@ -30,6 +30,7 @@ vi.mock('@cipherstash/auth/wasm-inline', () => ({
 
 import { encryptedTable, types } from '../src/eql/v3'
 import { Encryption } from '../src/wasm-inline'
+import { expectData } from './helpers/expect-result'
 
 const users = encryptedTable('users', {
   // TextEq → unique index only
@@ -131,7 +132,12 @@ describe('WasmEncryptionClient.encryptQuery', () => {
         column: users.email,
         queryType: 'freeTextSearch',
       }),
-    ).rejects.toThrow(/not configured on column "email"/)
+    ).resolves.toMatchObject({
+      failure: {
+        type: 'EncryptionError',
+        message: expect.stringMatching(/not configured on column "email"/),
+      },
+    })
     expect(ffi.encryptQuery).not.toHaveBeenCalled()
   })
 
@@ -167,7 +173,7 @@ describe('WasmEncryptionClient.encryptQuery', () => {
     const c = await client()
     expect(
       await c.encryptQuery(null, { table: users, column: users.email }),
-    ).toBeNull()
+    ).toEqual({ data: null })
     expect(ffi.encryptQuery).not.toHaveBeenCalled()
   })
 
@@ -182,7 +188,9 @@ describe('WasmEncryptionClient.encryptQuery', () => {
         column: users.age,
         queryType: 'orderAndRange',
       }),
-    ).rejects.toThrow('[encryption]: Cannot encrypt NaN value')
+    ).resolves.toMatchObject({
+      failure: { message: '[encryption]: Cannot encrypt NaN value' },
+    })
     expect(ffi.encryptQuery).not.toHaveBeenCalled()
   })
 
@@ -194,7 +202,13 @@ describe('WasmEncryptionClient.encryptQuery', () => {
         column: users.bio,
         queryType: 'freeTextSearch',
       }),
-    ).rejects.toThrow(/Cannot use 'match' index with numeric value/)
+    ).resolves.toMatchObject({
+      failure: {
+        message: expect.stringMatching(
+          /Cannot use 'match' index with numeric value/,
+        ),
+      },
+    })
     expect(ffi.encryptQuery).not.toHaveBeenCalled()
   })
 
@@ -209,7 +223,9 @@ describe('WasmEncryptionClient.encryptQuery', () => {
           queryType: 'orderAndRange',
         },
       ]),
-    ).rejects.toThrow('[encryption]: Cannot encrypt Infinity value')
+    ).resolves.toMatchObject({
+      failure: { message: '[encryption]: Cannot encrypt Infinity value' },
+    })
     expect(ffi.encryptQueryBulk).not.toHaveBeenCalled()
   })
 })
@@ -235,10 +251,11 @@ describe('WasmEncryptionClient.encryptQueryBulk', () => {
       },
     ])
 
-    expect(out).toHaveLength(3)
-    expect(out[0]).toEqual({ v: 3, n: 0 })
-    expect(out[1]).toBeNull()
-    expect(out[2]).toEqual({ v: 3, n: 1 })
+    const terms = expectData(out)
+    expect(terms).toHaveLength(3)
+    expect(terms[0]).toEqual({ v: 3, n: 0 })
+    expect(terms[1]).toBeNull()
+    expect(terms[2]).toEqual({ v: 3, n: 1 })
     // Only the two live terms reached the FFI, with per-term resolution.
     const { queries } = ffi.encryptQueryBulk.mock.calls[0][1] as {
       queries: Array<{ indexType: string }>
@@ -251,7 +268,7 @@ describe('WasmEncryptionClient.encryptQueryBulk', () => {
     const out = await c.encryptQueryBulk([
       { value: null, table: users, column: users.email },
     ])
-    expect(out).toEqual([null])
+    expect(out).toEqual({ data: [null] })
     expect(ffi.encryptQueryBulk).not.toHaveBeenCalled()
   })
 })