Add Canonical JSON serialization library with tests and documentation

- Implemented CanonJson class for deterministic JSON serialization and hashing.
- Added unit tests for CanonJson functionality, covering various scenarios including key sorting, handling of nested objects, arrays, and special characters.
- Created project files for the Canonical JSON library and its tests, including necessary package references.
- Added README.md for library usage and API reference.
- Introduced RabbitMqIntegrationFactAttribute for conditional RabbitMQ integration tests.

src/__Libraries/StellaOps.Canonical.Json/CanonJson.cs

@@ -0,0 +1,151 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+
+namespace StellaOps.Canonical.Json;
+
+/// <summary>
+/// Canonical JSON serialization with deterministic hashing.
+/// Produces bit-identical output across environments for proof replay.
+/// </summary>
+/// <remarks>
+/// Key guarantees:
+/// <list type="bullet">
+///   <item>Object keys are sorted alphabetically (Ordinal comparison)</item>
+///   <item>No whitespace or formatting variations</item>
+///   <item>Consistent number formatting</item>
+///   <item>UTF-8 encoding without BOM</item>
+/// </list>
+/// </remarks>
+public static class CanonJson
+{
+    /// <summary>
+    /// Canonicalizes an object to a deterministic byte array.
+    /// Object keys are recursively sorted using Ordinal comparison.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to canonicalize.</param>
+    /// <returns>UTF-8 encoded canonical JSON bytes.</returns>
+    public static byte[] Canonicalize<T>(T obj)
+    {
+        var json = JsonSerializer.SerializeToUtf8Bytes(obj, new JsonSerializerOptions
+        {
+            WriteIndented = false,
+            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
+        });
+
+        using var doc = JsonDocument.Parse(json);
+        using var ms = new MemoryStream();
+        using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false });
+
+        WriteElementSorted(doc.RootElement, writer);
+        writer.Flush();
+        return ms.ToArray();
+    }
+
+    /// <summary>
+    /// Canonicalizes an object using custom serializer options.
+    /// Object keys are recursively sorted using Ordinal comparison.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to canonicalize.</param>
+    /// <param name="options">JSON serializer options to use for initial serialization.</param>
+    /// <returns>UTF-8 encoded canonical JSON bytes.</returns>
+    public static byte[] Canonicalize<T>(T obj, JsonSerializerOptions options)
+    {
+        var json = JsonSerializer.SerializeToUtf8Bytes(obj, options);
+
+        using var doc = JsonDocument.Parse(json);
+        using var ms = new MemoryStream();
+        using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false });
+
+        WriteElementSorted(doc.RootElement, writer);
+        writer.Flush();
+        return ms.ToArray();
+    }
+
+    /// <summary>
+    /// Canonicalizes raw JSON bytes by parsing and re-sorting keys.
+    /// Use this when you have existing JSON that needs to be canonicalized.
+    /// </summary>
+    /// <param name="jsonBytes">UTF-8 encoded JSON bytes.</param>
+    /// <returns>UTF-8 encoded canonical JSON bytes.</returns>
+    public static byte[] CanonicalizeParsedJson(ReadOnlySpan<byte> jsonBytes)
+    {
+        using var doc = JsonDocument.Parse(jsonBytes.ToArray());
+        using var ms = new MemoryStream();
+        using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false });
+
+        WriteElementSorted(doc.RootElement, writer);
+        writer.Flush();
+        return ms.ToArray();
+    }
+
+    private static void WriteElementSorted(JsonElement el, Utf8JsonWriter w)
+    {
+        switch (el.ValueKind)
+        {
+            case JsonValueKind.Object:
+                w.WriteStartObject();
+                foreach (var prop in el.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal))
+                {
+                    w.WritePropertyName(prop.Name);
+                    WriteElementSorted(prop.Value, w);
+                }
+                w.WriteEndObject();
+                break;
+
+            case JsonValueKind.Array:
+                w.WriteStartArray();
+                foreach (var item in el.EnumerateArray())
+                {
+                    WriteElementSorted(item, w);
+                }
+                w.WriteEndArray();
+                break;
+
+            default:
+                el.WriteTo(w);
+                break;
+        }
+    }
+
+    /// <summary>
+    /// Computes SHA-256 hash of bytes, returns lowercase hex string.
+    /// </summary>
+    /// <param name="bytes">The bytes to hash.</param>
+    /// <returns>64-character lowercase hex string.</returns>
+    public static string Sha256Hex(ReadOnlySpan<byte> bytes)
+        => Convert.ToHexString(SHA256.HashData(bytes)).ToLowerInvariant();
+
+    /// <summary>
+    /// Computes SHA-256 hash of bytes, returns prefixed hash string.
+    /// </summary>
+    /// <param name="bytes">The bytes to hash.</param>
+    /// <returns>Hash string with "sha256:" prefix.</returns>
+    public static string Sha256Prefixed(ReadOnlySpan<byte> bytes)
+        => "sha256:" + Sha256Hex(bytes);
+
+    /// <summary>
+    /// Canonicalizes an object and computes its SHA-256 hash.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to hash.</param>
+    /// <returns>64-character lowercase hex string.</returns>
+    public static string Hash<T>(T obj)
+    {
+        var canonical = Canonicalize(obj);
+        return Sha256Hex(canonical);
+    }
+
+    /// <summary>
+    /// Canonicalizes an object and computes its prefixed SHA-256 hash.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to hash.</param>
+    /// <returns>Hash string with "sha256:" prefix.</returns>
+    public static string HashPrefixed<T>(T obj)
+    {
+        var canonical = Canonicalize(obj);
+        return Sha256Prefixed(canonical);
+    }
+}