save progress

src/__Libraries/StellaOps.Canonicalization/README.md

@@ -0,0 +1,35 @@
+# 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.