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);
+    }
 }

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

@@ -0,0 +1,87 @@
+namespace StellaOps.Canonical.Json;
+
+/// <summary>
+/// Canonicalization version identifiers for content-addressed hashing.
+/// </summary>
+/// <remarks>
+/// Version markers are embedded in canonical JSON to ensure hash stability across
+/// algorithm evolution. When canonicalization logic changes (bug fixes, spec updates,
+/// optimizations), a new version constant is introduced, allowing:
+/// <list type="bullet">
+///   <item>Verifiers to select the correct canonicalization algorithm</item>
+///   <item>Graceful migration without invalidating existing hashes</item>
+///   <item>Clear audit trail of which algorithm produced each hash</item>
+/// </list>
+/// </remarks>
+public static class CanonVersion
+{
+    /// <summary>
+    /// Version 1: RFC 8785 JSON Canonicalization Scheme (JCS) with:
+    /// <list type="bullet">
+    ///   <item>Ordinal key sorting (case-sensitive, lexicographic)</item>
+    ///   <item>No whitespace or formatting variations</item>
+    ///   <item>UTF-8 encoding without BOM</item>
+    ///   <item>IEEE 754 number formatting</item>
+    ///   <item>Minimal escape sequences in strings</item>
+    /// </list>
+    /// </summary>
+    public const string V1 = "stella:canon:v1";
+
+    /// <summary>
+    /// Field name for version marker in canonical JSON.
+    /// Underscore prefix ensures it sorts first lexicographically,
+    /// making version detection a simple prefix check.
+    /// </summary>
+    public const string VersionFieldName = "_canonVersion";
+
+    /// <summary>
+    /// Current default version for new hashes.
+    /// All new content-addressed IDs use this version.
+    /// </summary>
+    public const string Current = V1;
+
+    /// <summary>
+    /// Prefix bytes for detecting versioned canonical JSON.
+    /// Versioned JSON starts with: {"_canonVersion":"
+    /// </summary>
+    internal static ReadOnlySpan<byte> VersionedPrefixBytes => "{\"_canonVersion\":\""u8;
+
+    /// <summary>
+    /// Checks if canonical JSON bytes are versioned (contain version marker).
+    /// </summary>
+    /// <param name="canonicalJson">UTF-8 encoded canonical JSON bytes.</param>
+    /// <returns>True if the JSON contains a version marker at the expected position.</returns>
+    public static bool IsVersioned(ReadOnlySpan<byte> canonicalJson)
+    {
+        // Versioned canonical JSON always starts with: {"_canonVersion":"stella:canon:v
+        // Minimum length: {"_canonVersion":"stella:canon:v1"} = 35 bytes
+        return canonicalJson.Length >= 35 &&
+               canonicalJson.StartsWith(VersionedPrefixBytes);
+    }
+
+    /// <summary>
+    /// Extracts the version string from versioned canonical JSON.
+    /// </summary>
+    /// <param name="canonicalJson">UTF-8 encoded canonical JSON bytes.</param>
+    /// <returns>The version string, or null if not versioned or invalid format.</returns>
+    public static string? ExtractVersion(ReadOnlySpan<byte> canonicalJson)
+    {
+        if (!IsVersioned(canonicalJson))
+        {
+            return null;
+        }
+
+        // Find the closing quote after the version value
+        var prefixLength = VersionedPrefixBytes.Length;
+        var remaining = canonicalJson[prefixLength..];
+
+        var quoteIndex = remaining.IndexOf((byte)'"');
+        if (quoteIndex <= 0)
+        {
+            return null;
+        }
+
+        var versionBytes = remaining[..quoteIndex];
+        return System.Text.Encoding.UTF8.GetString(versionBytes);
+    }
+}