feat(stack)!: align wasm-inline to the Result contract, and add bulkEncrypt/bulkDecrypt (#741)

* feat(stack): bulkEncrypt/bulkDecrypt on the wasm-inline entry (#737)

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.

* 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.

* fix(stack): preserve non-Error rejection detail on the wasm-inline entry

`withResult`'s default `ensureError` REPLACES any non-Error throw with
`new Error('Something went wrong')`, discarding the original value
(@byteslice/result@0.2.0, dist/result.js:27). But that is only the
FALLBACK — the library prefers an `onException` hook:

    const error = hooks?.onException?.(ex) ?? ensureError(ex)

Nothing in this repo passes it. On the native entry that rarely bites,
because the FFI throws real `ProtectError` instances. On WASM it is a
live hazard: wasm-bindgen rejects with the raw `JsValue` the Rust side
produced (`throw takeFromExternrefTable0(...)` in the generated glue),
and the WASM build exports no `ProtectError` class at all — so a genuine
FFI failure can arrive as a bare string or object.

That made the Result conversion in the previous commit a partial
REGRESSION: the old throwing behaviour at least propagated the raw value
to the caller, whereas `withResult` was silently swallowing it. Fixed by
supplying `onException`.

The six call sites now go through one `wasmResult()` seam that binds both
the failure shape and the hook, so a method added later cannot omit
either — an omission would not fail a build, it would just quietly
degrade failure messages, which is the whole bug.

`toError` preserves strings as-is, JSON-serializes objects (so
`{code, detail}` survives rather than becoming "[object Object]"), and
falls back to `String()` for cycles and other unserializable values.

+2 tests covering string and object preservation, plus the cyclic
fallback. 833 pass; 0 biome errors; zero new tsc errors (diffed against
main's error set, not counted).

* fix(stack): address review — native FFI leak, Result plumbing, batch bugs

Review found 15 issues. This commit takes the source and test ones.

CRITICAL (1/15) — the entry pulled in the NATIVE protect-ffi.
`@/encryption/helpers/error-code` value-imports `ProtectError` for an
`instanceof` narrow, and protect-ffi is not in tsup `noExternal`, so
`dist/wasm-inline.js` carried a bare `@cipherstash/protect-ffi` import —
the NAPI entry, in the one bundle that exists to avoid it. On Workers /
Edge the non-`node` condition resolves it to a module exporting no
`ProtectError`; under Deno it resolves to the NAPI loader.

I had previously dismissed this as pre-existing. That was wrong: I ran
`git stash -u` on a clean tree, so it stashed nothing and I rebuilt my
own branch and compared it against itself. Re-verified properly by
swapping in main's `wasm-inline.ts` and rebuilding: main emits only the
`/wasm-inline` specifier, mine emitted both. Replaced with a structural
`readErrorCode` — which is the only thing that could ever work here
anyway, since the WASM build ships no error class for `instanceof` to
match. GH #744 is filed on my faulty premise and needs correcting.

New `wasm-inline-bundle-isolation.test.ts` asserts the built bundle's
external imports, so this class of regression fails CI. Verified it
catches the exact regression by reintroducing it (2 of 3 assertions
fail), rather than assuming.

3/15 — `failure.code` could never be populated: `withResult` runs
`onException` first, so the mapper only ever saw a fresh Error. `toError`
now carries a structural `code` onto the synthesized Error, and
`bulkDecrypt` puts each item's FFI code in its per-index message (a batch
has no single code, but dropping it lost the only machine-readable part).

9/15 — `toError`'s `String(ex)` fallback could itself throw on a
null-prototype object, escaping the Result contract entirely and
rejecting the call. Guarded with `safeString`.

10/15 — sparse inputs. `items.map(() => null)` SKIPS holes, so a hole
came back `undefined` rather than the documented `null` while lengths
still matched, which the length guard cannot see. Now `Array.from`.

15/15 — the positional-batch scaffolding was hand-rolled three times, so
a fourth batch method could omit `assertBatchLength` with no build
failure. One `runBatch` helper owns compaction, short-circuit, length
assert and scatter; the sparse fix lives there once.

5/15, 6/15, 7/15 — docs and surface: removed a duplicate stale `@returns`,
migrated the module-header and all five `encryptQuery` examples off the
pre-Result contract (they interpolated the envelope straight into SQL),
corrected the pending `.changeset/wasm-encrypt-query.md` sentence that
still said errors throw, and exported `EncryptionError` /
`EncryptionErrorTypes` so an edge consumer can discriminate
`failure.type` from the same import.

`WasmResult<T>` is now declared locally rather than re-exporting
`@byteslice/result`'s. Re-exporting put that specifier in the emitted
`.d.ts`, which Deno cannot resolve — the same reason `WasmPlaintext`
re-declares protect-ffi's `JsPlaintext`.

14/15 — test gaps: falsy-but-live values (`0` / `''` / `false`) per batch
method, the sparse-hole case, `encryptQueryBulk`'s previously untested
length guard, and the two stale "throws" titles.

840 tests pass. Zero new tsc errors, diffed against main's error set.
0 biome errors. Bundle verified free of the native FFI.

* fix(stack): review round 2 — e2e, example, skill, and adapter bulk usage

2/15 — the Deno e2e suites still consumed bare values, so with live
credentials `isEncrypted(encrypted)` received a Result, `decrypt` was
handed the envelope as ciphertext, and every `assertV3Term` saw
`term.v === undefined`. Secret-gated, so it would have landed silently.
Both suites now unwrap at each boundary. `roundtrip` also gains the first
live coverage of `bulkEncrypt`/`bulkDecrypt` anywhere in the repo —
including the index-aligned null hole — which the unit tests' "live
coverage runs in the Deno e2e" claim previously had no backing for.

(`deno check` reports pre-existing column-brand errors on these files;
the task runs `--no-check` deliberately for that reason, documented in
`e2e/wasm/deno.json`. Confirmed no NEW error kinds were introduced.)

4/15 — the supabase-worker example could not run against any published
version: it pinned `@^0.18.0` (bare-value entry, so `encryptResult.data`
was undefined and `decrypt` threw), and bumping the pin broke it earlier
still because it authored a v2 schema the v3-only entry rejects. Pinned
to `^1.0.0-rc.3` and migrated to `types.TextEq`. README's surface claim
updated with it.

8/15 — the skill's WASM bulk section sat in a file where the running
`client` is the NATIVE one, so an agent would apply the per-item shape to
`bulkEncrypt(plaintexts, { table, column })` and fail in a customer repo.
It now constructs the WASM client explicitly, with a callout that it is a
different client, and `@cipherstash/stack/wasm-inline` is listed in the
subpath table.

13/15 — the WASM integration adapter encrypted one field per request
inside `Promise.all`: concurrency hides latency, not request count, so a
100-row × 5-field family was 500 ZeroKMS requests. Now one `bulkEncrypt`
per row, which also makes the harness live coverage for the path.

840 tests pass; zero new tsc errors; 0 biome errors.

Author: coderdan

.changeset/wasm-encrypt-query.md

@@ -14,5 +14,6 @@ free-text match, ORE range, and JSON containment/selector — with the same
 index-type resolution as the native client (explicit `queryType`, or
 inference from the column's configured indexes). Cast the term to the
 column's `eql_v3.query_<domain>` type in SQL to reach the indexed operators.
-Errors throw, consistent with the WASM surface's `encrypt`/`decrypt`; the
-bulk form is position-stable (`null` values pass through as `null`).
+Both return `{ data } | { failure }`, consistent with the WASM surface's
+`encrypt`/`decrypt`; the bulk form is position-stable (`null` values pass
+through as `null`).

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

@@ -0,0 +1,47 @@
+---
+'@cipherstash/stack': minor
+'stash': patch
+---
+
+**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.
+
+### 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
+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))
+```
+
+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.
+
+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 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.

e2e/wasm/query-types.test.ts

@@ -72,6 +72,26 @@ const catalog = encryptedTable('wasm_query_matrix', {
 })
 
 /** A v3 SCALAR query term: versioned envelope (`v: 3`), NO ciphertext. */
+/**
+ * Unwrap a `{ data } | { failure }` Result (#741 — every fallible method on
+ * this entry returns one). Asserting on the envelope instead of its payload
+ * silently passes: `term.v` is `undefined` on a Result, so a shape check reads
+ * as "not v3" rather than "you forgot to unwrap".
+ */
+function unwrap<T>(
+  result:
+    | { data: T; failure?: never }
+    | { data?: never; failure: { message: string } },
+  label: string,
+): T {
+  assertEquals(
+    result.failure,
+    undefined,
+    `${label}: ${result.failure?.message}`,
+  )
+  return result.data as T
+}
+
 function assertV3Term(term: unknown, label: string) {
   assertExists(term, `${label}: encryptQuery returned null`)
   const obj = term as Record<string, unknown>
@@ -119,42 +139,54 @@ Deno.test({
 
     // equality → unique index
     assertV3Term(
-      await client.encryptQuery('alice@example.com', {
-        table: catalog,
-        column: catalog.email,
-        queryType: 'equality',
-      }),
+      unwrap(
+        await client.encryptQuery('alice@example.com', {
+          table: catalog,
+          column: catalog.email,
+          queryType: 'equality',
+        }),
+        'equality',
+      ),
       'equality',
     )
 
     // freeTextSearch → match index
     assertV3Term(
-      await client.encryptQuery('needle phrase', {
-        table: catalog,
-        column: catalog.bio,
-        queryType: 'freeTextSearch',
-      }),
+      unwrap(
+        await client.encryptQuery('needle phrase', {
+          table: catalog,
+          column: catalog.bio,
+          queryType: 'freeTextSearch',
+        }),
+        'freeTextSearch',
+      ),
       'freeTextSearch',
     )
 
     // orderAndRange → ore index (numeric)
     assertV3Term(
-      await client.encryptQuery(42, {
-        table: catalog,
-        column: catalog.age,
-        queryType: 'orderAndRange',
-      }),
+      unwrap(
+        await client.encryptQuery(42, {
+          table: catalog,
+          column: catalog.age,
+          queryType: 'orderAndRange',
+        }),
+        'orderAndRange',
+      ),
       'orderAndRange',
     )
 
     // searchableJson, string value → ste_vec_selector (JSONPath). By
     // contract the selector "term" is a BARE selector-hash string — no
     // envelope — bound as the text argument of `->` / `->>`.
-    const selector = await client.encryptQuery('$.theme', {
-      table: catalog,
-      column: catalog.prefs,
-      queryType: 'searchableJson',
-    })
+    const selector = unwrap(
+      await client.encryptQuery('$.theme', {
+        table: catalog,
+        column: catalog.prefs,
+        queryType: 'searchableJson',
+      }),
+      'selector',
+    )
     assertExists(selector, 'selector: encryptQuery returned null')
     assertEquals(
       typeof selector,
@@ -171,30 +203,36 @@ Deno.test({
     // strict {sv: [...]}, no version envelope — per the eql_v3.query_jsonb
     // wire contract)
     assertContainmentNeedle(
-      await client.encryptQuery(
-        { theme: 'dark' },
-        {
-          table: catalog,
-          column: catalog.prefs,
-          queryType: 'searchableJson',
-        },
+      unwrap(
+        await client.encryptQuery(
+          { theme: 'dark' },
+          {
+            table: catalog,
+            column: catalog.prefs,
+            queryType: 'searchableJson',
+          },
+        ),
+        'searchableJson/containment',
       ),
       'searchableJson/containment',
     )
 
     // Omitted queryType → inference from the column's indexes (TextEq has
     // exactly one: unique), mirroring the native client.
     assertV3Term(
-      await client.encryptQuery('bob@example.com', {
-        table: catalog,
-        column: catalog.email,
-      }),
+      unwrap(
+        await client.encryptQuery('bob@example.com', {
+          table: catalog,
+          column: catalog.email,
+        }),
+        'inference',
+      ),
       'inference',
     )
 
     // Bulk: one round trip across mixed query types, position-stable with
     // nulls passing through.
-    const bulk = await client.encryptQueryBulk([
+    const bulkResult = await client.encryptQueryBulk([
       {
         value: 'alice@example.com',
         table: catalog,
@@ -225,6 +263,7 @@ Deno.test({
         queryType: 'searchableJson',
       },
     ])
+    const bulk = unwrap(bulkResult, 'bulk')
     assertEquals(bulk.length, 5)
     assertV3Term(bulk[0], 'bulk/equality')
     assertEquals(bulk[1], null, 'bulk: null value must yield null')

e2e/wasm/roundtrip.test.ts

@@ -102,10 +102,19 @@ Deno.test({
 
     const plaintext = `wasm-v3-smoke-${crypto.randomUUID()}@example.com`
 
-    const encrypted = await client.encrypt(plaintext, {
+    // Every fallible method returns `{ data } | { failure }` (#741). Unwrap
+    // at each boundary — passing an envelope on would fail in ways that look
+    // like an encryption bug rather than a plumbing one.
+    const encryptResult = await client.encrypt(plaintext, {
       column: users.email,
       table: users,
     })
+    assertEquals(
+      encryptResult.failure,
+      undefined,
+      `encrypt() failed: ${encryptResult.failure?.message}`,
+    )
+    const encrypted = encryptResult.data
 
     assertEquals(
       isEncrypted(encrypted),
@@ -138,17 +147,28 @@ Deno.test({
     }
     assertEquals(String(wire.v), '3', 'wire envelope is not v3')
 
-    const decrypted = await client.decrypt(encrypted)
-    assertEquals(decrypted, plaintext, 'round-trip plaintext mismatch')
+    const decryptResult = await client.decrypt(encrypted)
+    assertEquals(
+      decryptResult.failure,
+      undefined,
+      `decrypt() failed: ${decryptResult.failure?.message}`,
+    )
+    assertEquals(decryptResult.data, plaintext, 'round-trip plaintext mismatch')
 
     // 5. (#662) Searchable encryption is reachable on the edge: mint a v3
     //    QUERY TERM for the column's free-text index. Terms are
     //    ciphertext-free needles — assert the wire shape, not decryption.
-    const term = (await client.encryptQuery(plaintext, {
+    const termResult = await client.encryptQuery(plaintext, {
       column: users.email,
       table: users,
       queryType: 'freeTextSearch',
-    })) as Record<string, unknown> | null
+    })
+    assertEquals(
+      termResult.failure,
+      undefined,
+      `encryptQuery() failed: ${termResult.failure?.message}`,
+    )
+    const term = termResult.data as Record<string, unknown> | null
     assertExists(term, 'encryptQuery() returned null for live plaintext')
     assertEquals(term.v, 3, 'query term is not EQL v3')
     assertEquals(
@@ -158,12 +178,48 @@ Deno.test({
     )
 
     // Bulk form is position-stable, nulls pass through.
-    const bulk = await client.encryptQueryBulk([
+    const bulkResult = await client.encryptQueryBulk([
       { value: plaintext, column: users.email, table: users },
       { value: null, column: users.email, table: users },
     ])
+    assertEquals(
+      bulkResult.failure,
+      undefined,
+      `encryptQueryBulk() failed: ${bulkResult.failure?.message}`,
+    )
+    const bulk = bulkResult.data
     assertEquals(bulk.length, 2)
     assertExists(bulk[0])
     assertEquals(bulk[1], null)
+
+    // 6. (#741) The value-level bulk ops — the whole reason a list read on the
+    //    edge is one ZeroKMS round trip instead of N. Nothing else in the repo
+    //    exercises these against real ZeroKMS.
+    const second = `wasm-v3-bulk-${crypto.randomUUID()}@example.com`
+    const bulkEncrypted = await client.bulkEncrypt([
+      { plaintext, column: users.email, table: users },
+      { plaintext: null, column: users.email, table: users },
+      { plaintext: second, column: users.email, table: users },
+    ])
+    assertEquals(
+      bulkEncrypted.failure,
+      undefined,
+      `bulkEncrypt() failed: ${bulkEncrypted.failure?.message}`,
+    )
+    const payloads = bulkEncrypted.data
+    assertEquals(payloads.length, 3, 'bulkEncrypt is not index-aligned')
+    assertEquals(payloads[1], null, 'null plaintext did not yield null')
+    assertExists(payloads[0])
+    assertExists(payloads[2])
+    assertEquals(isEncrypted(payloads[0]), true, 'bulkEncrypt[0] not a payload')
+
+    const bulkDecrypted = await client.bulkDecrypt(payloads)
+    assertEquals(
+      bulkDecrypted.failure,
+      undefined,
+      `bulkDecrypt() failed: ${bulkDecrypted.failure?.message}`,
+    )
+    // Round-trips at the ORIGINAL indices, with the null hole preserved.
+    assertEquals(bulkDecrypted.data, [plaintext, null, second])
   },
 })

examples/supabase-worker/README.md

@@ -59,7 +59,7 @@ There are none. The `@cipherstash/stack/wasm-inline` subpath embeds the protect-
 ## What this verifies
 
 - Protect's WASM build works inside Supabase Edge Functions.
-- The full `@cipherstash/stack/wasm-inline` developer surface (`Encryption`, `encryptedTable`, `encryptedColumn`, …) is usable from an Edge Function with no native dependencies.
+- The full `@cipherstash/stack/wasm-inline` developer surface (`Encryption`, `encryptedTable`, the `types.*` EQL v3 domains, …) is usable from an Edge Function with no native dependencies.
 - A CipherStash service-to-service `AccessKeyStrategy` is the right credential shape for serverless / edge environments.
 
 Automated coverage of the same code path lives at `e2e/wasm/roundtrip.test.ts` and runs in CI on every PR — this example is the runnable runbook version.

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

@@ -15,13 +15,17 @@
 
 import {
   Encryption,
-  encryptedColumn,
   encryptedTable,
   isEncrypted,
-} from 'npm:@cipherstash/stack@^0.18.0/wasm-inline'
+  types,
+} from 'npm:@cipherstash/stack@^1.0.0-rc.3/wasm-inline'
 
+// EQL v3: the WASM entry exports the v3 authoring surface only (`types.*`),
+// not the v2 chainable builders — `encryptedColumn('email').equality()` is
+// rejected by the factory outright. `TextEq` is the v3 equality-capable text
+// domain, i.e. the direct replacement.
 const users = encryptedTable('users', {
-  email: encryptedColumn('email').equality(),
+  email: types.TextEq('email'),
 })
 
 Deno.serve(async (_req: Request) => {
@@ -61,11 +65,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(
       {