sprints work

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