// -----------------------------------------------------------------------------
// ResolverBoundaryAttribute.cs
// Sprint: SPRINT_20251226_007_BE_determinism_gaps
// Task: DET-GAP-18
// Description: Attribute marking methods/classes as resolver boundaries requiring canonicalization.
// -----------------------------------------------------------------------------

namespace StellaOps.Determinism;

/// <summary>
/// Marks a method or class as a resolver boundary where canonicalization is required.
/// The STELLA0100 analyzer will enforce RFC 8785 JCS canonicalization within marked scopes.
/// </summary>
/// <remarks>
/// Apply this attribute to:
/// <list type="bullet">
///   <item>Methods that compute digests for attestations or signatures</item>
///   <item>Methods that serialize data for replay or comparison</item>
///   <item>Classes that produce deterministic outputs</item>
/// </list>
/// </remarks>
/// <example>
/// <code>
/// [ResolverBoundary]
/// public string ComputeVerdictDigest(VerdictPayload payload)
/// {
///     // Analyzer will warn if JsonSerializer.Serialize is used here
///     var canonicalizer = new Rfc8785JsonCanonicalizer();
///     return canonicalizer.Canonicalize(payload);
/// }
/// </code>
/// </example>
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public sealed class ResolverBoundaryAttribute : Attribute
{
    /// <summary>
    /// Gets or sets whether NFC normalization is required for strings.
    /// </summary>
    public bool RequireNfc { get; set; }

    /// <summary>
    /// Gets or sets whether strict ordering is required for collections.
    /// </summary>
    public bool RequireOrdering { get; set; } = true;

    /// <summary>
    /// Gets or sets a description of the boundary purpose.
    /// </summary>
    public string? Description { get; set; }
}

/// <summary>
/// Marks a method as requiring canonicalization for its output.
/// Alias for <see cref="ResolverBoundaryAttribute"/> for semantic clarity.
/// </summary>
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public sealed class RequiresCanonicalizationAttribute : Attribute
{
    /// <summary>
    /// Gets or sets the canonicalization scheme required.
    /// </summary>
    public string Scheme { get; set; } = "RFC8785";
}

/// <summary>
/// Marks a method as producing deterministic output that must be reproducible.
/// </summary>
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = false, Inherited = true)]
public sealed class DeterministicOutputAttribute : Attribute
{
    /// <summary>
    /// Gets or sets the hash algorithm used for verification.
    /// </summary>
    public string HashAlgorithm { get; set; } = "SHA256";

    /// <summary>
    /// Gets or sets whether the output is signed.
    /// </summary>
    public bool IsSigned { get; set; }
}