chore(stack)!: upgrade protect-ffi to 0.31.0

.changeset/cli-near-miss-statement-trim.md

@@ -0,0 +1,15 @@
+---
+'stash': patch
+---
+
+Trim the leading comment block from near-miss statements reported by the Drizzle
+migration rewriter (`stash eql migration --drizzle`, `stash eql install`).
+
+The broad near-miss scan is anchored on the previous `;`, so a
+`SET DATA TYPE … USING …` it could not safely repair was quoted back to the user
+with every preceding comment and blank line glued to its front — in a file
+opening with a comment block, that meant the whole header. The reported
+statement is now the offending statement alone. Detection is unchanged; only the
+text shown to the user is affected.
+
+Keeps this rewriter in sync with its sibling in `@cipherstash/wizard`.

.changeset/cli-v2-cutover-prompt-correction.md

@@ -0,0 +1,13 @@
+---
+'stash': patch
+---
+
+`stash init`'s setup prompt no longer tells agents to declare an EQL v2 cutover
+column with a `types.*` domain.
+
+The `types.*` factories are EQL v3 only — a v2 column is an `eql_v2_encrypted`
+composite — so an agent following the old step-4 guidance would author a schema
+that cannot describe the column it just cut over to. The prompt now says
+explicitly not to use `types.*` for a v2 column, and points at the deprecated
+`@cipherstash/stack/schema` builders with decryption through
+`@cipherstash/stack`, which is the actual read path for legacy v2 rows.

.changeset/decrypt-chaining-docs.md

@@ -0,0 +1,72 @@
+---
+'stash': patch
+'@cipherstash/stack': patch
+---
+
+Correct the shipped documentation for `decryptModel` / `bulkDecryptModels`.
+
+Three places in `skills/stash-encryption` and four in `packages/stack/README.md`
+said these return "a plain `Promise<Result<...>>` (not a chainable operation)"
+and that there is therefore "no `.withLockContext()` to chain". They return an
+`AuditableDecryptModelOperation`, which is thenable and carries both
+`.withLockContext()` and `.audit()` — the same `.audit()` chain the
+audit-on-decrypt work advertises. The skill contradicted itself: its own
+reference table already listed the correct return type.
+
+The skill ships inside the `stash` tarball and `installSkills()` copies it into
+customer repos, so this was steering agents away from an API that exists. The
+README ships in the `@cipherstash/stack` tarball.
+
+The equivalent statement about the **WASM entry** is correct and unchanged —
+`@cipherstash/stack/wasm-inline` really does return a plain promise from decrypt,
+with no lock-context argument.
+
+Also fixes the setup prompt `stash init` writes for coding agents, which
+referenced `protectOps.eq` — an API that does not exist anywhere in the repo.
+Every step naming an integration-specific API now branches on the project's
+actual integration, instead of naming Drizzle's and Supabase's and leaving the
+other two to guess:
+
+- **Query paths.** `createEncryptionOperators(client)` (conventionally `ops`)
+  for Drizzle, the `encryptedSupabase` wrapper's own filters for Supabase, the
+  `eql*` column operators for Prisma Next, and `client.encryptQuery(...)` for a
+  plain Postgres project.
+- **Schema authoring.** The `types.*` column factories for Drizzle, the
+  `eql_v3_encrypted` domain in migration SQL for Supabase, the `cipherstash.*`
+  field constructors in `schema.prisma` for Prisma Next, and `encryptedTable`
+  for plain Postgres. Prisma Next was previously sent at `types.*` /
+  `encryptedTable` — the client `stash schema build` explicitly refuses to
+  scaffold for that integration.
+- **Read paths.** `decryptModel(row, usersSchema)` where that applies, and the
+  wrapper's transparent decryption where it does not.
+- **Skill pointers.** A plain Postgres project installs no integration-specific
+  skill, so each "see the integration skill" was a pointer at a file that was
+  never written. Those now point at `stash-encryption`, which it does get.
+
+`client.encryptQuery` is also shown taking the schema objects themselves
+(`{ table: usersSchema, column: usersSchema.email }`) rather than an
+object-shorthand that read as three required strings — `queryType` is inferred
+from the column's configured indexes.
+
+The cutover and complete-rollout **plan templates** now split EQL v3 from v2.
+Both described the v2 rename swap (`<col>` → `<col>_plaintext`, twin → `<col>`)
+as the only cutover path, so on the default v3 install `stash plan` drafted a
+plan built around `stash encrypt cutover` — a command that refuses v3 columns
+outright ("there is no rename step") and refuses entirely on a v3-only
+database, where `eql_v2_configuration` does not exist. The implement prompt
+already carried this split; the plan templates did not. The version is
+per-column, so the templates tell the agent to establish it per column rather
+than deciding once for the whole plan.
+
+The "already encrypted" stop-and-ask now recognises `eql_v3_*` domains
+alongside the legacy `eql_v2_encrypted` udt, so it can fire on the default
+path at all.
+
+**`stash init` now detects already-encrypted columns on EQL v3.** Database
+introspection marked a column as CipherStash-managed only when its udt was
+exactly `eql_v2_encrypted`. v3 columns carry per-domain types
+(`eql_v3_text_search`, `eql_v3_integer_ord`, …), so on the default path every
+encrypted column was reported as plaintext — shown with its `dataType` and left
+unticked in the column picker, inviting a re-run to encrypt it a second time.
+The picker also labelled any encrypted column with the literal string
+`eql_v2_encrypted`; it now shows the column's real domain.

.changeset/domain-carrier-not-public.md

@@ -0,0 +1,18 @@
+---
+'@cipherstash/stack': patch
+---
+
+The phantom domain carrier on encrypted v3 columns is no longer part of the
+public surface.
+
+Recovering a column's domain after declaration emit requires the type parameter
+to appear bare somewhere in the instance type, which is what makes typed
+`encryptQuery` callable against the published package. That carrier was a
+plainly named `__domain` property, and this build has no `stripInternal`, so
+`@internal` was documentation rather than enforcement: it appeared in
+autocomplete on every column and could be read from consumer code, typed
+`D | undefined` while being `undefined` at runtime in every case.
+
+It is now keyed by a `unique symbol` that is not exported, so it is unnameable
+outside the package while remaining exactly as inferrable. Nothing is emitted at
+runtime and no call site changes.

.changeset/drizzle-encrypted-indexes.md

@@ -2,7 +2,7 @@
 '@cipherstash/stack-drizzle': minor
 ---
 
-New `encryptedIndexes` helper on the `/v3` entry: spread
+New `encryptedIndexes` helper on the package root: spread
 `...encryptedIndexes(t)` in `pgTable`'s third-argument callback and it derives
 the recommended functional indexes for every encrypted column in the table —
 named `<table>_<column>_<capability>`, tracked by `drizzle-kit generate` like

.changeset/dynamodb-eql-v3.md

@@ -11,10 +11,13 @@ Pass a table built with `encryptedTable` + the `types.*` domains from
 the typed client from `EncryptionV3` and the nominal client from
 `Encryption({ config: { eqlVersion: 3 } })` are accepted.
 
-EQL v2 tables continue to work unchanged — this is additive, and no existing
-caller needs to change. The table decides which wire format is used, so a
-DynamoDB table populated under one version must keep being read with that
-version.
+EQL v2 tables continue to be **readable** — `decryptModel` /
+`bulkDecryptModels` still accept one, so existing items stay accessible. Writing
+through a v2 table is a separate matter: `encryptModel` / `bulkEncryptModels`
+narrowed to EQL v3 tables in this same release, so a caller that still encrypts
+through a v2 table does need to change. The table decides which wire format is
+used, so a DynamoDB table populated under one version must keep being read with
+that version.
 
 This fixes a latent bug that made v3 unusable: the write path detected an
 encrypted value by its `k: 'ct'` tag, but EQL v3 scalars carry no `k`
@@ -71,4 +74,4 @@ type, where a declared column `email` becomes `email__source` (plus
 `email`. `decryptModel` / `bulkDecryptModels` invert it via `DecryptedAttributes`.
 `AnyEncryptedTable`, `DynamoDBEncryptionClient` and `AuditConfig` are now
 exported from `@cipherstash/stack/dynamodb` so these signatures can be named.
-The EQL v2 overloads are unchanged.
+The EQL v2 **decrypt** overloads are unchanged; the v2 encrypt overloads are removed in this release.

.changeset/dynamodb-skill-wasm-caveat.md

@@ -0,0 +1,17 @@
+---
+'stash': patch
+---
+
+The `stash-dynamodb` and `stash-encryption` skills documented EQL v2 decrypt as
+unconditionally supported, without noting that `@cipherstash/stack/wasm-inline`
+is EQL v3 only. Since that is the documented entry for Deno, Bun, Cloudflare
+Workers and Supabase Edge Functions — runtimes commonly paired with DynamoDB — a
+reader following the skill hit a runtime refusal with no forewarning. Both skills
+now state that legacy v2 items are readable on the native `@cipherstash/stack`
+entry only.
+
+The `stash-dynamodb` API reference also claimed audit metadata forwards to
+ZeroKMS "regardless of client shape". It does not: the wasm-inline client's
+operations return a plain promise with no `.audit()`, so its audit metadata is
+dropped (logged at debug). The reference now says so, and says the operation
+still succeeds.

.changeset/dynamodb-v2-read-table-forwarding.md

@@ -0,0 +1,27 @@
+---
+'@cipherstash/stack': patch
+---
+
+Fix `encryptedDynamoDB`'s EQL v2 read path, which failed against a v3-configured
+client — the case the v2 read support exists for.
+
+`decryptModel` and `bulkDecryptModels` forwarded the table to the encryption
+client unconditionally. The second argument is only meaningful to the typed EQL
+v3 client, which resolves it against its own reconstructor map; a legacy v2
+table is not in that map, so the call failed with:
+
+```
+[eql/v3]: decryptModel received a table this client was not initialized with
+```
+
+That contradicted the adapter's documented contract — writes are EQL v3 only,
+but decrypt keeps accepting a v2 table so previously stored items stay readable.
+In practice the failure hit exactly the customers the compatibility promise was
+written for: upgraded to a v3 schema, with v2 items still in the table.
+
+The table is now forwarded only when it is an EQL v3 table. A v2 table takes the
+table-less form, and the client derives the table from the payloads themselves.
+
+Both paths are covered by a credential-free test asserting what the adapter
+forwards, so a regression no longer depends on a live-credential integration run
+to surface.

.changeset/dynamodb-wasm-v2-read.md

@@ -0,0 +1,39 @@
+---
+'@cipherstash/stack': patch
+---
+
+`encryptedDynamoDB` now refuses a `@cipherstash/stack/wasm-inline` client paired
+with a legacy EQL v2 table, instead of failing at the first read with a
+misleading error.
+
+The adapter's v2 read path deliberately calls `decryptModel(item)` with **no**
+table — a v2 table means nothing to a v3 client's reconstructor map, and the
+native clients derive the table from the payloads anyway. `WasmEncryptionClient`
+cannot do that: its decrypt requires the table and resolves date fields from a
+per-table map, so the omitted argument surfaced as
+`TypeError: Cannot read properties of undefined (reading 'tableName')` thrown
+from deep inside the client — on the documented entry for Deno, Cloudflare
+Workers and Supabase Edge Functions, which satisfies the adapter's client type
+structurally and so was accepted with no cast.
+
+The pairing is now rejected at the call site, with a message naming both the
+combination and the fix. The message is operation-neutral: the guard runs on all
+four operations, so a plain-JS caller reaching the write path with a v2 table
+gets a message that does not claim a read it never attempted.
+
+`encryptModel` / `bulkEncryptModels` now also tolerate a client whose encrypt
+returns a plain promise. They chained `.audit()` onto the result
+unconditionally, which the wasm-inline client does not carry — so **every EQL v3
+write through this adapter on that entry** failed with
+`client.encryptModel(...).audit is not a function`, surfaced as a
+`DYNAMODB_ENCRYPTION_ERROR` and so indistinguishable from a real encryption
+fault. The read path already handled this; the write path now matches, via the
+same fail-closed check that rejects a malformed result rather than passing an
+unencrypted item through as a success. Audit metadata still has nowhere to go on
+that client, so it is dropped and logged at debug — the write itself succeeds.
+
+Three comments in this package claimed audit metadata was forwarded "regardless
+of client shape" and that "every client this package ships carries `.audit()` on
+decrypt". Neither was true of the wasm-inline client, whose decrypt returns a
+plain promise — the metadata is dropped, observably (it is logged at debug), and
+the comments and the debug message now say so.

.changeset/encrypt-client-guard-parity.md

@@ -0,0 +1,20 @@
+---
+'stash': patch
+---
+
+`stash encrypt backfill` now names the cause when the encryption client has no
+initialized encrypt config, instead of reporting a missing table.
+
+The guard that refuses an unusable client file existed twice — once in
+`loadEncryptConfig` (`stash db push` / `db validate`) and once, hand-copied, in
+`loadEncryptionContext` (`stash encrypt backfill`). The copies had already
+drifted: for a client whose `getEncryptConfig()` returns nothing, `db push`
+exited 1 with `Encryption client in <file> has no initialized encrypt config`,
+while `encrypt backfill` fell through to `Table "users" was not found in the
+encryption client exports. Available: (none)` — naming the symptom rather than
+the cause, which is precisely the failure the guard was added to eliminate.
+
+Both loaders now call one shared guard, so a single file cannot produce two
+different diagnoses, and the refusals are pinned at both public entry points.
+The un-replaced `stash init` scaffold is unaffected — it was already refused by
+both, with the same message.

.changeset/encrypt-lifecycle-mixed-table.md

@@ -0,0 +1,59 @@
+---
+'stash': patch
+---
+
+`stash encrypt cutover` and `stash encrypt drop` no longer act on — or report
+success for — an encrypted column they only guessed at.
+
+On a table holding both a legacy EQL v2 pair (`ssn` / `ssn_encrypted`) and one
+unrelated EQL v3 column, the v2 ciphertext column is not classified as an EQL
+column at all, so column resolution fell through to the "this is the table's
+only EQL column" rule and claimed the unrelated v3 column. Three consequences,
+all now fixed:
+
+- **`cutover` reported success for work it never did.** Its EQL v3 branch had no
+  guard on how the column was resolved, and returned without setting an exit
+  code — so it printed "point your application at `email_enc`" and exited 0
+  while the v2 rename never ran. A scripted rollout read that as complete. It
+  now refuses, and exits 1, exactly as `drop` already did.
+
+- **The recorded pairing was discarded.** `encrypt backfill` writes the true
+  `encryptedColumn` to `.cipherstash/migrations.json`, so the answer was already
+  on disk — but a hint that failed to resolve was dropped entirely and the
+  re-resolution reached the guess. A hint naming a column that still exists but
+  is not an EQL v3 column is now reported as what it is (most often a legacy
+  `eql_v2_encrypted` counterpart) instead of being replaced by a guess. A
+  genuinely stale hint — one naming a column that is gone — still falls back to
+  the naming convention as before.
+
+- **`drop`'s refusal message prescribed the guess.** It told the user to re-run
+  `backfill --encrypted-column <the guessed column>`. Following it recorded the
+  guess as fact, so the next run resolved "by hint", walked past the refusal,
+  and passed the coverage check vacuously — an unrelated but legitimately
+  backfilled column is non-NULL on every row — then generated a live
+  `DROP COLUMN` on the plaintext and exited 0. The message now asks for the
+  column that actually encrypts the named one, and says explicitly not to record
+  the guess.
+
+The `unresolvedHint` refusal is scoped to tables that actually hold EQL v3
+columns a guess could wrongly claim. A **pure-v2** table has none, so it still
+falls through to the EQL v2 lifecycle exactly as before — including when
+`encrypt backfill` recorded an `encryptedColumn` for it, which it does for v2
+columns too.
+
+Two cases DO newly exit 1, both deliberately:
+
+- Any table with at least one EQL v3 column where the manifest records an
+  `encryptedColumn` that exists but is not one of them — not only the
+  v2-pair-plus-one-v3 shape. The recorded pairing is authoritative and
+  disagrees with every candidate, so guessing past it is the bug.
+
+- A column whose encrypted counterpart could only be identified **by
+  elimination** — no recorded `encryptedColumn`, no `<col>_encrypted` name
+  match, one EQL column left once the plaintext column itself is excluded.
+  `cutover` now refuses this as `drop` already did. Note `.cipherstash/` is
+  gitignored, so `migrations.json` is machine-local: a fresh clone or CI runner
+  can hit this on a **pure-v3** table whose encrypted column is named
+  unconventionally, where `cutover` previously exited 0 with "not applicable".
+  Re-run `stash encrypt backfill --table T --column C --encrypted-column <name>`
+  to record the pairing.

.changeset/encryption-schema-arrays.md

@@ -0,0 +1,52 @@
+---
+'@cipherstash/stack': minor
+'@cipherstash/prisma-next': patch
+---
+
+`Encryption({ schemas })` now accepts any non-empty array of EQL v3 tables, not
+only an array literal.
+
+Previously the v3 signature required a non-empty *tuple*, so every indirect form
+was rejected at compile time even though it worked at runtime:
+
+```ts
+// all of these used to fail with TS2769
+export const schemas: AnyV3Table[] = [users, orders]
+await Encryption({ schemas })
+
+const readonlySchemas: ReadonlyArray<AnyV3Table> = [users, orders]
+await Encryption({ schemas: readonlySchemas })
+
+const built: AnyV3Table[] = []
+built.push(users)
+await Encryption({ schemas: built })
+```
+
+They all compile now. `Encryption({ schemas: [] })` is still a compile error, and
+an array literal still gets full per-column typing — passing the wrong plaintext
+for a column's domain, or a table the client was not built with, is still
+rejected.
+
+`EncryptionClientFor<S>` is widened to match, so it names the typed client for a
+loose `readonly AnyV3Table[]` as well as for a tuple. Code that is generic over
+its schemas — an adapter that builds a table per request, say — can now write
+`EncryptionClientFor<readonly AnyV3Table[]>` and keep the typed surface.
+
+If you narrowed a schema array to `readonly [AnyV3Table, ...AnyV3Table[]]` to
+satisfy the old signature, that narrowing is no longer needed.
+
+A wrapper that is itself generic over its schemas keeps working too:
+
+```ts
+async function makeClient<S extends readonly [AnyV3Table, ...AnyV3Table[]]>(
+  schemas: S,
+) {
+  return await Encryption({ schemas })
+}
+```
+
+Note the non-empty tuple constraint. A wrapper generic over a loose
+`readonly AnyV3Table[]` is still rejected — that type admits `readonly []`, so
+the wrapper cannot promise what `Encryption` requires. Constrain it as above, or
+take `EncryptionClientFor<readonly AnyV3Table[]>` as a parameter instead of
+building the client inside the generic function.