[FEATURE] Define a portable numeric value contract across providers

Problem / motivation

The portable API does not currently define one provider-independent numeric domain for Java/Jackson inputs and public results. Cosmos DB, DynamoDB, and Spanner have different native numeric ranges and representations, so the same value can be rounded, rejected, or returned with a different Java/Jackson type depending on the provider and operation.

This was discovered while reviewing #105, but it predates partial update and should be addressed across the full SDK rather than added to that feature PR.

Proposed solution

Define and implement a normative portable numeric contract covering:

• accepted Java and Jackson numeric input types;
• integral and non-integral ranges shared by all supported providers;
• canonical provider-bound and public-result representations;
• whether an out-of-domain value is rejected or rounded;
• structured INVALID_REQUEST details for local validation failures;
• a visible, raw-value-free warning policy for any accepted value-changing normalization;
• identical behavior for create, upsert, update, query, read, and change-feed paths.

The implementation must not mutate caller-owned maps, lists, arrays, or JSON trees.

Provider scope

• Portable across all providers
• Azure Cosmos DB only
• Amazon DynamoDB only
• Google Cloud Spanner only
• Not sure

Acceptance criteria

• The portable numeric domain and canonical Java/Jackson types are normative and documented.
• Equivalent values produce equivalent provider-bound values and public results across all providers.
• Values outside the domain fail before provider I/O with structured, non-retryable INVALID_REQUEST details.
• No precision-changing conversion is silent; the selected warning/rejection policy is tested without logging raw values.
• Native query input remains explicitly provider-specific and is not accidentally normalized.
• API, provider, and conformance tests cover positive/negative boundaries, zero, nested containers, and unsupported Number implementations.
• README, API reference, compatibility guide, changelogs, and relevant specs describe the same contract.

Alternatives considered

Implementing numeric rules only for partial update was rejected because it would create operation-dependent behavior in the portable API.

Additional context

Related umbrella issues: #37 and #64.

Tracked follow-ups

• #108 — query numeric literals, parameters, and native-path bypass
• #109 — nested Spanner numeric decoding across result paths
• #110 — DynamoDB N/NS decoding fidelity

No files or entry points are named. Start by tracing numeric handling through portable create, upsert, update, query, read, and change-feed paths for Cosmos DB, DynamoDB, and Spanner, then review the existing API, provider, and conformance tests. Done means one documented contract with consistent validation, representations, warnings, and coverage across all listed paths and providers.