docs(solutions): port the use-cases section into /solutions

[coderdan]

Ports content/stack/reference/use-cases/* into /solutions, per the mapping in v2-redirects.mjs. Four pages: the section index, ai-and-rag, data-residency, provable-access.

Three API errors found and fixed

This was supposed to be a mechanical port. It wasn't. I checked every code example against the generated TypeDoc for @cipherstash/stack v0.18.0, and three of them were wrong:

1. provable-access used an API that does not exist. Every code block called client.withLockContext({ identityToken: jwt }).encrypt(...). The real API constructs a LockContext, identifies it with the JWT (which returns a Result, because the CTS token exchange can fail), and attaches it to the operation:

const lockContext = await new LockContext().identify(providerJwt)
if (lockContext.failure) throw new Error(lockContext.failure.message)

const result = await client
  .encrypt(diagnosis, { column: patients.diagnosis, table: patients })
  .withLockContext(lockContext.data)

2. data-residency passed credentials as top-level keys to Encryption({ schemas, workspaceCrn, clientId, ... }). EncryptionClientConfig puts them in a nested config object.

3. ai-and-rag queried with eql_v2.eq(user_id, $1), removed in EQL 3.0.0. Now uses a typed operand, WHERE user_id = $1::public.text_eq, with a pointer to the typed-operand rule and to indexes, since that predicate needs a functional index to avoid a sequential scan.

The provable-access bug is exactly the signature drift this overhaul exists to eliminate, and it survived on a live page.

The legacy index was not an index

use-cases/index.mdx was three unrelated things. Handled as follows:

• "What data should I protect?" (PII, PHI, financial, authentication, with applicable regulations) moves onto the Solutions index, where it works as orientation for the audience door.
• "Data sovereignty" duplicated data-residency almost line for line. Folded in; the distinct material (the three properties that give you residency) is now that page's opening section.
• "CipherStash vs data vaults" (Skyflow, VGS) is a vendor comparison, not a solution. Not ported here. Tracked separately, since it belongs in /concepts/compare/data-vaults and is a sixth comparison page beyond the five in IA.md. It is distinct from hashicorp-vault: Skyflow and VGS are PII data vaults, HashiCorp Vault is a secrets manager. Until that lands, /stack/reference/use-cases redirects to /solutions and that comparison is not reachable from its old URL.

Other changes

• Added a callout to ai-and-rag noting that CipherStash encrypts chunks and metadata, not the embeddings, and that embeddings should themselves be treated as sensitive. The original page implied full coverage.
• ai-and-rag ingest now uses encryptModel and retrieval uses bulkDecryptModels rather than per-field calls in a Promise.all, so a reranking pass is one ZeroKMS round trip instead of one per row.
• Softened provable-access's "mathematically impossible to bypass" framing. A lock context moves enforcement into key derivation; it does not stop a caller holding a valid token.
• Added a note that keysets, not lock contexts, are usually the right tool for coarse tenant isolation.

Checks

• bun run build passes; all four pages prerender.
• bun run validate-redirects passes (194 legacy pages covered).
• All internal links resolve. Targets not yet built (/stack/cipherstash/kms/*, /stack/cipherstash/proxy/audit) point at legacy homes and are tracked for repointing.
• Code examples verified against generated TypeDoc, packageVersion: v0.18.0. Pages carry verifiedAgainst: { stack: "0.18.0" }.

One upstream nit

The TypeDoc for EncryptionClient contains an example that passes the Result to .withLockContext(lockContext), while LockContext's own example correctly passes .withLockContext(identified.data). withLockContext takes a LockContext, so the EncryptionClient example is wrong. Worth fixing in the SDK's doc comments.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, Comment	Jul 9, 2026 6:08am