Portability: ensure identical behavior across all provider backends

Goal

We need test coverage that verifies that every portable feature of the SDK produces identical functional behavior regardless of the underlying database provider (Cosmos DB, DynamoDB, Spanner). Performance characteristics need not match precisely, but should be within the same order of magnitude for equivalent operations.

Scope

1. CRUD Semantics

• upsert → read roundtrip preserves all fields and types exactly
• upsert on an existing key fully replaces the document (no partial merge)
• read of a nonexistent key returns null (not an exception)
• delete of an existing key makes subsequent read return null
• delete of a nonexistent key throws HyperscaleDbException with category NOT_FOUND
• create of a duplicate key throws with category CONFLICT
• Document field types survive roundtrip identically: strings, integers, floats, booleans, nulls, nested objects, arrays

2. Portable Query Expressions

• All comparison operators (=, !=, <, >, <=, >=) return the same result sets
• Logical composition (AND, OR, NOT) evaluates identically
• Portable functions (starts_with, contains, field_exists, string_length, collection_size) return the same results
• IN and BETWEEN expressions produce equivalent result sets
• Parameter binding (@param) works identically across providers
• Queries with no matches return an empty page (not null, not an exception)

3. Pagination

• pageSize limits the number of items per page consistently
• Continuation token–based iteration yields the complete result set (no duplicates, no omissions)
• Iterating to exhaustion (null continuation token) produces the same total items regardless of page size

4. Partition Key Scoping

• Query scoped to a partition key returns only items from that partition
• Query without partition key scoping returns items across all partitions
• Query against a nonexistent partition returns an empty page

5. Error Normalization

• Each HyperscaleDbErrorCategory maps to the same semantic condition across providers:
  • NOT_FOUND, CONFLICT, THROTTLED, INVALID_REQUEST, AUTHENTICATION_FAILED, TRANSIENT_FAILURE
• HyperscaleDbException always carries OperationDiagnostics with non-null provider, operation name, and non-negative duration
• isRetryable() is consistent for equivalent error conditions

6. Capabilities Reporting

• capabilities() accurately reflects what the provider supports
• Invoking an unsupported capability throws with category UNSUPPORTED_CAPABILITY (not a provider-specific error)
• Capability names are consistent across providers (same strings, same semantics)

7. Portability Warnings

• Default client configuration emits zero portability warnings on all providers
• Provider-specific feature flags emit warnings but do not break client creation
• Warnings are surfaced identically (same PortabilityWarning structure)

8. Configuration & Lifecycle

• HyperscaleDbClientFactory.create(config) succeeds for each provider with equivalent minimal config
• close() is idempotent and does not throw
• ensureDatabase() and ensureContainer() are idempotent across providers

9. Native Expression Passthrough

• A provider-native query expression executes correctly on its own provider
• A provider-native query expression on the wrong provider fails predictably (not silently returns wrong results)

Approach

• Extend CrudConformanceTests (the existing provider-agnostic base class) to cover all gaps above
• Each test should run against all three providers via the existing subclass pattern (CosmosConformanceTest, DynamoConformanceTest, SpannerConformanceTest)
• Add cross-provider data fidelity tests: write with provider A, read-back with provider B (where infrastructure allows)
• Add performance baseline assertions where feasible (e.g., single-document read completes within 5× of the fastest provider)

Acceptance Criteria

• Every test case listed above passes on all three providers
• No provider-specific workarounds or conditional logic in test assertions
• CI runs the full suite against Cosmos emulator and DynamoDB Local; Spanner emulator added when CI support is available