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

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) => {

packages/stack/integration/wasm/adapter.ts

@@ -244,21 +244,36 @@ export function makeWasmAdapter(): IntegrationAdapter {
 
   async function encryptRow(row: PlainRow): Promise<Record<string, unknown>> {
     const assignments: Record<string, unknown> = { row_key: row.rowKey }
-    // Field encrypts are independent ZeroKMS round-trips — run them
-    // concurrently rather than paying fields × RTT per row.
-    await Promise.all(
-      Object.entries(row.values).map(async ([slug, value]) => {
-        const encrypted = unwrap(
-          await client.encrypt(toWasmPlaintext(value), {
-            table: tableSchema,
-            column: col(slug).column,
-          }),
-          'encrypt',
-        )
-        assertWireEnvelope(slug, encrypted)
-        assignments[slug] = encrypted
-      }),
+
+    // ONE ZeroKMS round trip for the whole row, not one per field. This was
+    // `Promise.all` over per-field `client.encrypt` — concurrency hides
+    // latency but not request count, so a 100-row × 5-field family was 500
+    // requests. `bulkEncrypt`'s per-item `{ plaintext, table, column }`
+    // routing exists precisely for this shape (#737).
+    //
+    // It also makes this harness the live coverage for the bulk path: the
+    // unit tests mock the FFI, so without this nothing in the repo exercises
+    // `bulkEncrypt` against real ZeroKMS.
+    const entries = Object.entries(row.values)
+    const encrypted = unwrap(
+      await client.bulkEncrypt(
+        entries.map(([slug, value]) => ({
+          plaintext: toWasmPlaintext(value),
+          table: tableSchema,
+          column: col(slug).column,
+        })),
+      ),
+      'bulkEncrypt',
     )
+
+    entries.forEach(([slug], i) => {
+      const payload = encrypted[i]
+      // A null here means the fixture value was null/undefined — the column
+      // is genuinely absent, not an encryption failure.
+      if (payload === null || payload === undefined) return
+      assertWireEnvelope(slug, payload)
+      assignments[slug] = payload
+    })
     return assignments
   }
 

skills/stash-encryption/SKILL.md

@@ -189,6 +189,7 @@ The SDK never logs plaintext data.
 | `@cipherstash/stack/types` | All TypeScript types |
 | `@cipherstash/stack-drizzle/v3` | Drizzle ORM integration for EQL v3 schemas (see the `stash-drizzle` skill) |
 | `@cipherstash/stack-supabase` | `encryptedSupabaseV3` wrapper for Supabase (see the `stash-supabase` skill) |
+| `@cipherstash/stack/wasm-inline` | The **edge** entry — Deno, Bun, Cloudflare Workers, Supabase Edge Functions. Its own `Encryption` factory plus the v3 authoring surface, `EncryptionErrorTypes`, and the WASM build of protect-ffi inlined into the bundle. No native binding, so no bundler externalisation needed. |
 | `@cipherstash/stack/dynamodb` | `encryptedDynamoDB` — **still requires the legacy v2 schema surface**; see "Legacy: EQL v2" below |
 | `@cipherstash/stack/schema`, `@cipherstash/stack/client`, `@cipherstash/stack/encryption` | Legacy v2 schema builders and client surface — see "Legacy: EQL v2" below |
 
@@ -424,8 +425,27 @@ for (const item of decrypted.data) {
 
 **On the WASM entry (`@cipherstash/stack/wasm-inline`), the batch shape differs** — do not copy the shape above onto the edge. The `{ data } | { failure }` Result is the same, but there are no `{ id, plaintext }` envelopes: each entry carries its own table and column, and the payload is a plain index-aligned array.
 
+> [!IMPORTANT]
+> The `client` below is a **different client** from the one used everywhere else in this skill. The edge entry has its own `Encryption` factory — the native `EncryptionV3` client's `bulkEncrypt` takes `(plaintexts, { table, column })` and will fail at runtime if given the per-item shape below. Construct the WASM client explicitly:
+
+```typescript
+// Deno / Workers / Supabase Edge Functions — note the import path
+import { Encryption, encryptedTable, types } from "@cipherstash/stack/wasm-inline"
+
+const users = encryptedTable("users", { email: types.TextEq("email") })
+
+const client = await Encryption({
+  schemas: [users],
+  config: {
+    workspaceCrn: Deno.env.get("CS_WORKSPACE_CRN")!,
+    accessKey: Deno.env.get("CS_CLIENT_ACCESS_KEY")!,
+    clientId: Deno.env.get("CS_CLIENT_ID")!,
+    clientKey: Deno.env.get("CS_CLIENT_KEY")!,
+  },
+})
+```
+
 ```typescript
-// Deno / Workers / Supabase Edge Functions
 const encrypted = await client.bulkEncrypt([
   { plaintext: "alice@example.com", table: users, column: users.email },
   { plaintext: "hello", table: users, column: users.bio },