sprints work

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

@@ -176,4 +176,109 @@ public static class CanonJson
         var canonical = Canonicalize(obj);
         return Sha256Prefixed(canonical);
     }
+
+    /// <summary>
+    /// Canonicalizes an object with version marker for content-addressed hashing.
+    /// The version marker is embedded as the first field in the canonical JSON,
+    /// ensuring stable hashes even if canonicalization logic evolves.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to canonicalize.</param>
+    /// <param name="version">Canonicalization version (default: Current).</param>
+    /// <returns>UTF-8 encoded canonical JSON bytes with version marker.</returns>
+    public static byte[] CanonicalizeVersioned<T>(T obj, string version = CanonVersion.Current)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(version);
+
+        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 });
+
+        WriteElementVersioned(doc.RootElement, writer, version);
+        writer.Flush();
+        return ms.ToArray();
+    }
+
+    /// <summary>
+    /// Canonicalizes an object with version marker using custom serializer options.
+    /// </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>
+    /// <param name="version">Canonicalization version (default: Current).</param>
+    /// <returns>UTF-8 encoded canonical JSON bytes with version marker.</returns>
+    public static byte[] CanonicalizeVersioned<T>(T obj, JsonSerializerOptions options, string version = CanonVersion.Current)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(version);
+
+        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 });
+
+        WriteElementVersioned(doc.RootElement, writer, version);
+        writer.Flush();
+        return ms.ToArray();
+    }
+
+    private static void WriteElementVersioned(JsonElement el, Utf8JsonWriter w, string version)
+    {
+        if (el.ValueKind == JsonValueKind.Object)
+        {
+            w.WriteStartObject();
+
+            // Write version marker first (underscore prefix ensures lexicographic first position)
+            w.WriteString(CanonVersion.VersionFieldName, version);
+
+            // Write remaining properties sorted
+            foreach (var prop in el.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal))
+            {
+                w.WritePropertyName(prop.Name);
+                WriteElementSorted(prop.Value, w);
+            }
+            w.WriteEndObject();
+        }
+        else
+        {
+            // Non-object root: wrap in object with version marker
+            w.WriteStartObject();
+            w.WriteString(CanonVersion.VersionFieldName, version);
+            w.WritePropertyName("_value");
+            WriteElementSorted(el, w);
+            w.WriteEndObject();
+        }
+    }
+
+    /// <summary>
+    /// Computes SHA-256 hash of versioned canonical representation.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to hash.</param>
+    /// <param name="version">Canonicalization version (default: Current).</param>
+    /// <returns>64-character lowercase hex string.</returns>
+    public static string HashVersioned<T>(T obj, string version = CanonVersion.Current)
+    {
+        var canonical = CanonicalizeVersioned(obj, version);
+        return Sha256Hex(canonical);
+    }
+
+    /// <summary>
+    /// Computes prefixed SHA-256 hash of versioned canonical representation.
+    /// </summary>
+    /// <typeparam name="T">The type to serialize.</typeparam>
+    /// <param name="obj">The object to hash.</param>
+    /// <param name="version">Canonicalization version (default: Current).</param>
+    /// <returns>Hash string with "sha256:" prefix.</returns>
+    public static string HashVersionedPrefixed<T>(T obj, string version = CanonVersion.Current)
+    {
+        var canonical = CanonicalizeVersioned(obj, version);
+        return Sha256Prefixed(canonical);
+    }
 }