Add Policy DSL Validator, Schema Exporter, and Simulation Smoke tools

- Implemented PolicyDslValidator with command-line options for strict mode and JSON output.
- Created PolicySchemaExporter to generate JSON schemas for policy-related models.
- Developed PolicySimulationSmoke tool to validate policy simulations against expected outcomes.
- Added project files and necessary dependencies for each tool.
- Ensured proper error handling and usage instructions across tools.

src/StellaOps.Aoc/AocForbiddenKeys.cs

@@ -0,0 +1,25 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public static class AocForbiddenKeys
+{
+    private static readonly ImmutableHashSet<string> ForbiddenTopLevel = new[]
+    {
+        "severity",
+        "cvss",
+        "cvss_vector",
+        "effective_status",
+        "effective_range",
+        "merged_from",
+        "consensus_provider",
+        "reachability",
+        "asset_criticality",
+        "risk_score",
+    }.ToImmutableHashSet(StringComparer.OrdinalIgnoreCase);
+
+    public static bool IsForbiddenTopLevel(string propertyName) => ForbiddenTopLevel.Contains(propertyName);
+
+    public static bool IsDerivedField(string propertyName)
+        => propertyName.StartsWith("effective_", StringComparison.OrdinalIgnoreCase);
+}

src/StellaOps.Aoc/AocGuardException.cs

@@ -0,0 +1,17 @@
+using System;
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public sealed class AocGuardException : Exception
+{
+    public AocGuardException(AocGuardResult result)
+        : base("AOC guard validation failed.")
+    {
+        Result = result ?? throw new ArgumentNullException(nameof(result));
+    }
+
+    public AocGuardResult Result { get; }
+
+    public ImmutableArray<AocViolation> Violations => Result.Violations;
+}

src/StellaOps.Aoc/AocGuardExtensions.cs

@@ -0,0 +1,22 @@
+using System.Text.Json;
+
+namespace StellaOps.Aoc;
+
+public static class AocGuardExtensions
+{
+    public static AocGuardResult ValidateOrThrow(this IAocGuard guard, JsonElement document, AocGuardOptions? options = null)
+    {
+        if (guard is null)
+        {
+            throw new ArgumentNullException(nameof(guard));
+        }
+
+        var result = guard.Validate(document, options);
+        if (!result.IsValid)
+        {
+            throw new AocGuardException(result);
+        }
+
+        return result;
+    }
+}

src/StellaOps.Aoc/AocGuardOptions.cs

@@ -0,0 +1,29 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public sealed record AocGuardOptions
+{
+    private static readonly ImmutableHashSet<string> DefaultRequiredTopLevel = new[]
+    {
+        "tenant",
+        "source",
+        "upstream",
+        "content",
+        "linkset",
+    }.ToImmutableHashSet(StringComparer.OrdinalIgnoreCase);
+
+    public static AocGuardOptions Default { get; } = new();
+
+    public ImmutableHashSet<string> RequiredTopLevelFields { get; init; } = DefaultRequiredTopLevel;
+
+    /// <summary>
+    /// When true, signature metadata is required under upstream.signature.
+    /// </summary>
+    public bool RequireSignatureMetadata { get; init; } = true;
+
+    /// <summary>
+    /// When true, tenant must be a non-empty string.
+    /// </summary>
+    public bool RequireTenant { get; init; } = true;
+}

src/StellaOps.Aoc/AocGuardResult.cs

@@ -0,0 +1,14 @@
+using System.Collections.Immutable;
+
+namespace StellaOps.Aoc;
+
+public sealed record AocGuardResult(bool IsValid, ImmutableArray<AocViolation> Violations)
+{
+    public static AocGuardResult Success { get; } = new(true, ImmutableArray<AocViolation>.Empty);
+
+    public static AocGuardResult FromViolations(IEnumerable<AocViolation> violations)
+    {
+        var array = violations.ToImmutableArray();
+        return array.IsDefaultOrEmpty ? Success : new(false, array);
+    }
+}

src/StellaOps.Aoc/AocViolation.cs

@@ -0,0 +1,13 @@
+using System.Text.Json.Serialization;
+
+namespace StellaOps.Aoc;
+
+public sealed record AocViolation(
+    [property: JsonPropertyName("code")] AocViolationCode Code,
+    [property: JsonPropertyName("errorCode")] string ErrorCode,
+    [property: JsonPropertyName("path")] string Path,
+    [property: JsonPropertyName("message")] string Message)
+{
+    public static AocViolation Create(AocViolationCode code, string path, string message)
+        => new(code, code.ToErrorCode(), path, message);
+}

src/StellaOps.Aoc/AocViolationCode.cs

@@ -0,0 +1,34 @@
+namespace StellaOps.Aoc;
+
+public enum AocViolationCode
+{
+    None = 0,
+    ForbiddenField,
+    MergeAttempt,
+    IdempotencyViolation,
+    MissingProvenance,
+    SignatureInvalid,
+    DerivedFindingDetected,
+    UnknownField,
+    MissingRequiredField,
+    InvalidTenant,
+    InvalidSignatureMetadata,
+}
+
+public static class AocViolationCodeExtensions
+{
+    public static string ToErrorCode(this AocViolationCode code) => code switch
+    {
+        AocViolationCode.ForbiddenField => "ERR_AOC_001",
+        AocViolationCode.MergeAttempt => "ERR_AOC_002",
+        AocViolationCode.IdempotencyViolation => "ERR_AOC_003",
+        AocViolationCode.MissingProvenance => "ERR_AOC_004",
+        AocViolationCode.SignatureInvalid => "ERR_AOC_005",
+        AocViolationCode.DerivedFindingDetected => "ERR_AOC_006",
+        AocViolationCode.UnknownField => "ERR_AOC_007",
+        AocViolationCode.MissingRequiredField => "ERR_AOC_004",
+        AocViolationCode.InvalidTenant => "ERR_AOC_004",
+        AocViolationCode.InvalidSignatureMetadata => "ERR_AOC_005",
+        _ => "ERR_AOC_000",
+    };
+}

src/StellaOps.Aoc/AocWriteGuard.cs

@@ -0,0 +1,127 @@
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Text.Json;
+
+namespace StellaOps.Aoc;
+
+public interface IAocGuard
+{
+    AocGuardResult Validate(JsonElement document, AocGuardOptions? options = null);
+}
+
+public sealed class AocWriteGuard : IAocGuard
+{
+    public AocGuardResult Validate(JsonElement document, AocGuardOptions? options = null)
+    {
+        options ??= AocGuardOptions.Default;
+        var violations = ImmutableArray.CreateBuilder<AocViolation>();
+        var presentTopLevel = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var property in document.EnumerateObject())
+        {
+            presentTopLevel.Add(property.Name);
+
+            if (AocForbiddenKeys.IsForbiddenTopLevel(property.Name))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.ForbiddenField, $"/{property.Name}", $"Field '{property.Name}' is forbidden in AOC documents."));
+                continue;
+            }
+
+            if (AocForbiddenKeys.IsDerivedField(property.Name))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.DerivedFindingDetected, $"/{property.Name}", $"Derived field '{property.Name}' must not be written during ingestion."));
+            }
+        }
+
+        foreach (var required in options.RequiredTopLevelFields)
+        {
+            if (!document.TryGetProperty(required, out var element) || element.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined)
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, $"/{required}", $"Required field '{required}' is missing."));
+                continue;
+            }
+
+            if (options.RequireTenant && string.Equals(required, "tenant", StringComparison.OrdinalIgnoreCase))
+            {
+                if (element.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(element.GetString()))
+                {
+                    violations.Add(AocViolation.Create(AocViolationCode.InvalidTenant, "/tenant", "Tenant must be a non-empty string."));
+                }
+            }
+        }
+
+        if (document.TryGetProperty("upstream", out var upstream) && upstream.ValueKind == JsonValueKind.Object)
+        {
+            if (!upstream.TryGetProperty("content_hash", out var contentHash) || contentHash.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(contentHash.GetString()))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.MissingProvenance, "/upstream/content_hash", "Upstream content hash is required."));
+            }
+
+            if (!upstream.TryGetProperty("signature", out var signature) || signature.ValueKind != JsonValueKind.Object)
+            {
+                if (options.RequireSignatureMetadata)
+                {
+                    violations.Add(AocViolation.Create(AocViolationCode.MissingProvenance, "/upstream/signature", "Signature metadata is required."));
+                }
+            }
+            else if (options.RequireSignatureMetadata)
+            {
+                ValidateSignature(signature, violations);
+            }
+        }
+        else
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, "/upstream", "Upstream metadata is required."));
+        }
+
+        if (document.TryGetProperty("content", out var content) && content.ValueKind == JsonValueKind.Object)
+        {
+            if (!content.TryGetProperty("raw", out var raw) || raw.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined)
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.MissingProvenance, "/content/raw", "Raw upstream payload must be preserved."));
+            }
+        }
+        else
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, "/content", "Content metadata is required."));
+        }
+
+        if (!document.TryGetProperty("linkset", out var linkset) || linkset.ValueKind != JsonValueKind.Object)
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.MissingRequiredField, "/linkset", "Linkset metadata is required."));
+        }
+
+        return AocGuardResult.FromViolations(violations);
+    }
+
+    private static void ValidateSignature(JsonElement signature, ImmutableArray<AocViolation>.Builder violations)
+    {
+        if (!signature.TryGetProperty("present", out var presentElement) || presentElement.ValueKind is not (JsonValueKind.True or JsonValueKind.False))
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.InvalidSignatureMetadata, "/upstream/signature/present", "Signature metadata must include 'present' boolean."));
+            return;
+        }
+
+        var signaturePresent = presentElement.GetBoolean();
+
+        if (!signaturePresent)
+        {
+                return;
+            }
+
+            if (!signature.TryGetProperty("format", out var formatElement) || formatElement.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(formatElement.GetString()))
+            {
+                violations.Add(AocViolation.Create(AocViolationCode.InvalidSignatureMetadata, "/upstream/signature/format", "Signature format is required when signature is present."));
+        }
+
+        if (!signature.TryGetProperty("sig", out var sigElement) || sigElement.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(sigElement.GetString()))
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.SignatureInvalid, "/upstream/signature/sig", "Signature payload is required when signature is present."));
+        }
+
+        if (!signature.TryGetProperty("key_id", out var keyIdElement) || keyIdElement.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(keyIdElement.GetString()))
+        {
+            violations.Add(AocViolation.Create(AocViolationCode.InvalidSignatureMetadata, "/upstream/signature/key_id", "Signature key identifier is required when signature is present."));
+        }
+    }
+}

src/StellaOps.Aoc/ServiceCollectionExtensions.cs

@@ -0,0 +1,17 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace StellaOps.Aoc;
+
+public static class ServiceCollectionExtensions
+{
+    public static IServiceCollection AddAocGuard(this IServiceCollection services)
+    {
+        if (services is null)
+        {
+            throw new ArgumentNullException(nameof(services));
+        }
+
+        services.AddSingleton<IAocGuard, AocWriteGuard>();
+        return services;
+    }
+}

src/StellaOps.Aoc/StellaOps.Aoc.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <LangVersion>preview</LangVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+</Project>