# StellaOps.Canonicalization

Deterministic ordering and canonical JSON helpers used across StellaOps.

## Canonical JSON Defaults

`CanonicalJsonSerializer` uses these defaults unless you pass your own `JsonSerializerOptions`:

- Property naming: `JsonNamingPolicy.CamelCase`
- Dictionary key naming: `JsonNamingPolicy.CamelCase`
- Null handling: omit null values
- Encoder: `JavaScriptEncoder.UnsafeRelaxedJsonEscaping`
- Number handling: strict

These defaults are chosen for deterministic output. If you need stricter escaping or a different naming policy, use `JsonSerializerOptions` explicitly.

## Dictionary Key Handling

`StableDictionaryConverter` sorts keys using ordinal comparison of a stable string representation:

- String keys use the provided dictionary key policy (if any).
- Non-string keys use invariant formatting when possible.
- Null keys are rejected.
- Duplicate keys after canonicalization are rejected to avoid ambiguous output.

## Date/Time Handling

`Iso8601DateTimeConverter` serializes `DateTimeOffset` values as UTC using the
format `yyyy-MM-ddTHH:mm:ss.fffZ`. When parsing, offset-less values are treated
as UTC to avoid local-time ambiguity.

## Determinism Verification

`DeterminismVerifier` can compare two JSON payloads and reports structural
differences. Invalid JSON inputs are reported with context.