Client Encryption: Adds design for reducing encryption path contention.

[jeet1995]

Description

Parent Issue: #5641

Design-only PR — no code changes. Adds OpenSpec artifacts (proposal, design, specs, tasks) for reducing contention in the client-side encryption path.

Problem: OperationCanceledException under concurrent load due to a global SemaphoreSlim(1,1) in BuildProtectedDataEncryptionKeyAsync. The semaphore guards MDE's ProtectedDataEncryptionKey.GetOrCreate, which on cache miss triggers two synchronous Key Vault HTTP calls (Resolve + UnwrapKey). Every encrypted property in every document contends on this single-permit lock.

Proposed fix (3 capabilities, all gated behind opt-in env var):

1. Async prefetch — call ResolveAsync() + UnwrapKeyAsync() outside the semaphore; sync UnwrapKey inside becomes a cache read (microseconds vs. 200ms–2.4s)
2. Proactive background refresh — single deduplicated AKV call per key before TTL expiry; prevents thundering herd at the 2-hour cache boundary
3. Resolved client cache — cache IKeyEncryptionKey per CMK URL so each refresh makes 1 AKV call instead of 2

No public API changes. No breaking changes. Env var AZURE_COSMOS_ENCRYPTION_OPTIMISTIC_DECRYPTION_ENABLED (off by default).

See openspec/changes/reduce-encryption-contention/ for full proposal, design decisions, specs, and implementation tasks.

Type of change

• This change requires a documentation update

[github-actions]

All good!

[bartelink]

If this isn't dead, probably time to fill in the overview?

[jeet1995]

@bartelink - thanks! I've filled in the PR description (starting this out to document a design) - we'll see if this PR evolves to include code changes (so will keep this PR in a draft state).

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).