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