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.

tools/LanguageAnalyzerSmoke/LanguageAnalyzerSmoke.csproj

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0-rc.2.25502.107" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\StellaOps.Scanner.Analyzers.Lang\StellaOps.Scanner.Analyzers.Lang.csproj" />
+    <ProjectReference Include="..\..\src\StellaOps.Scanner.Core\StellaOps.Scanner.Core.csproj" />
+  </ItemGroup>
+</Project>

tools/LanguageAnalyzerSmoke/Program.cs

@@ -0,0 +1,348 @@
+using System.Collections.Immutable;
+using System.Diagnostics;
+using System.Reflection;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging.Abstractions;
+using StellaOps.Scanner.Analyzers.Lang;
+using StellaOps.Scanner.Analyzers.Lang.Plugin;
+using StellaOps.Scanner.Core.Security;
+
+internal sealed record SmokeScenario(string Name, string[] UsageHintRelatives)
+{
+    public IReadOnlyList<string> ResolveUsageHints(string scenarioRoot)
+        => UsageHintRelatives.Select(relative => Path.GetFullPath(Path.Combine(scenarioRoot, relative))).ToArray();
+}
+
+internal sealed class SmokeOptions
+{
+    public string RepoRoot { get; set; } = Directory.GetCurrentDirectory();
+    public string PluginDirectoryName { get; set; } = "StellaOps.Scanner.Analyzers.Lang.Python";
+    public string FixtureRelativePath { get; set; } = Path.Combine("src", "StellaOps.Scanner.Analyzers.Lang.Python.Tests", "Fixtures", "lang", "python");
+
+    public static SmokeOptions Parse(string[] args)
+    {
+        var options = new SmokeOptions();
+
+        for (var index = 0; index < args.Length; index++)
+        {
+            var current = args[index];
+            switch (current)
+            {
+                case "--repo-root":
+                case "-r":
+                    options.RepoRoot = RequireValue(args, ref index, current);
+                    break;
+                case "--plugin-directory":
+                case "-p":
+                    options.PluginDirectoryName = RequireValue(args, ref index, current);
+                    break;
+                case "--fixture-path":
+                case "-f":
+                    options.FixtureRelativePath = RequireValue(args, ref index, current);
+                    break;
+                case "--help":
+                case "-h":
+                    PrintUsage();
+                    Environment.Exit(0);
+                    break;
+                default:
+                    throw new ArgumentException($"Unknown argument '{current}'. Use --help for usage.");
+            }
+        }
+
+        options.RepoRoot = Path.GetFullPath(options.RepoRoot);
+        return options;
+    }
+
+    private static string RequireValue(string[] args, ref int index, string switchName)
+    {
+        if (index + 1 >= args.Length)
+        {
+            throw new ArgumentException($"Missing value for '{switchName}'.");
+        }
+
+        index++;
+        var value = args[index];
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            throw new ArgumentException($"Value for '{switchName}' cannot be empty.");
+        }
+
+        return value;
+    }
+
+    private static void PrintUsage()
+    {
+        Console.WriteLine("Language Analyzer Smoke Harness");
+        Console.WriteLine("Usage: dotnet run --project tools/LanguageAnalyzerSmoke -- [options]");
+        Console.WriteLine();
+        Console.WriteLine("Options:");
+        Console.WriteLine("  -r, --repo-root <path>        Repository root (defaults to current working directory)");
+        Console.WriteLine("  -p, --plugin-directory <name> Analyzer plug-in directory under plugins/scanner/analyzers/lang (defaults to StellaOps.Scanner.Analyzers.Lang.Python)");
+        Console.WriteLine("  -f, --fixture-path <path>     Relative path to fixtures root (defaults to src/StellaOps.Scanner.Analyzers.Lang.Python.Tests/Fixtures/lang/python)");
+        Console.WriteLine("  -h, --help                    Show usage information");
+    }
+}
+
+internal sealed record PluginManifest
+{
+    [JsonPropertyName("schemaVersion")]
+    public string SchemaVersion { get; init; } = string.Empty;
+
+    [JsonPropertyName("id")]
+    public string Id { get; init; } = string.Empty;
+
+    [JsonPropertyName("displayName")]
+    public string DisplayName { get; init; } = string.Empty;
+
+    [JsonPropertyName("version")]
+    public string Version { get; init; } = string.Empty;
+
+    [JsonPropertyName("requiresRestart")]
+    public bool RequiresRestart { get; init; }
+
+    [JsonPropertyName("entryPoint")]
+    public PluginEntryPoint EntryPoint { get; init; } = new();
+
+    [JsonPropertyName("capabilities")]
+    public IReadOnlyList<string> Capabilities { get; init; } = Array.Empty<string>();
+
+    [JsonPropertyName("metadata")]
+    public IReadOnlyDictionary<string, string> Metadata { get; init; } = ImmutableDictionary<string, string>.Empty;
+}
+
+internal sealed record PluginEntryPoint
+{
+    [JsonPropertyName("type")]
+    public string Type { get; init; } = string.Empty;
+
+    [JsonPropertyName("assembly")]
+    public string Assembly { get; init; } = string.Empty;
+
+    [JsonPropertyName("typeName")]
+    public string TypeName { get; init; } = string.Empty;
+}
+
+file static class Program
+{
+    private static readonly SmokeScenario[] PythonScenarios =
+    {
+        new("simple-venv", new[] { Path.Combine("bin", "simple-tool") }),
+        new("pip-cache", new[] { Path.Combine("lib", "python3.11", "site-packages", "cache_pkg-1.2.3.data", "scripts", "cache-tool") }),
+        new("layered-editable", new[] { Path.Combine("layer1", "usr", "bin", "layered-cli") })
+    };
+
+    public static async Task<int> Main(string[] args)
+    {
+        try
+        {
+            var options = SmokeOptions.Parse(args);
+            await RunAsync(options).ConfigureAwait(false);
+            Console.WriteLine("✅ Python analyzer smoke checks passed");
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"❌ {ex.Message}");
+            return 1;
+        }
+    }
+
+    private static async Task RunAsync(SmokeOptions options)
+    {
+        ValidateOptions(options);
+
+        var pluginRoot = Path.Combine(options.RepoRoot, "plugins", "scanner", "analyzers", "lang", options.PluginDirectoryName);
+        var manifestPath = Path.Combine(pluginRoot, "manifest.json");
+        if (!File.Exists(manifestPath))
+        {
+            throw new FileNotFoundException($"Plug-in manifest not found at '{manifestPath}'.", manifestPath);
+        }
+
+        using var manifestStream = File.OpenRead(manifestPath);
+        var manifest = JsonSerializer.Deserialize<PluginManifest>(manifestStream, new JsonSerializerOptions
+        {
+            PropertyNameCaseInsensitive = true,
+            ReadCommentHandling = JsonCommentHandling.Skip
+        }) ?? throw new InvalidOperationException($"Unable to parse manifest '{manifestPath}'.");
+
+        ValidateManifest(manifest, options.PluginDirectoryName);
+
+        var pluginAssemblyPath = Path.Combine(pluginRoot, manifest.EntryPoint.Assembly);
+        if (!File.Exists(pluginAssemblyPath))
+        {
+            throw new FileNotFoundException($"Plug-in assembly '{manifest.EntryPoint.Assembly}' not found under '{pluginRoot}'.", pluginAssemblyPath);
+        }
+
+        var sha256 = ComputeSha256(pluginAssemblyPath);
+        Console.WriteLine($"→ Plug-in assembly SHA-256: {sha256}");
+
+        using var serviceProvider = BuildServiceProvider();
+        var catalog = new LanguageAnalyzerPluginCatalog(new RestartOnlyPluginGuard(), NullLogger<LanguageAnalyzerPluginCatalog>.Instance);
+        catalog.LoadFromDirectory(pluginRoot, seal: true);
+
+        if (catalog.Plugins.Count == 0)
+        {
+            throw new InvalidOperationException($"No analyzer plug-ins were loaded from '{pluginRoot}'.");
+        }
+
+        var analyzerSet = catalog.CreateAnalyzers(serviceProvider);
+        if (analyzerSet.Count == 0)
+        {
+            throw new InvalidOperationException("Language analyzer plug-ins reported no analyzers.");
+        }
+
+        var analyzerIds = analyzerSet.Select(analyzer => analyzer.Id).ToArray();
+        Console.WriteLine($"→ Loaded analyzers: {string.Join(", ", analyzerIds)}");
+
+        if (!analyzerIds.Contains("python", StringComparer.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException("Python analyzer was not created by the plug-in.");
+        }
+
+        var fixtureRoot = Path.GetFullPath(Path.Combine(options.RepoRoot, options.FixtureRelativePath));
+        if (!Directory.Exists(fixtureRoot))
+        {
+            throw new DirectoryNotFoundException($"Fixture directory '{fixtureRoot}' does not exist.");
+        }
+
+        foreach (var scenario in PythonScenarios)
+        {
+            await RunScenarioAsync(scenario, fixtureRoot, catalog, serviceProvider).ConfigureAwait(false);
+        }
+    }
+
+    private static ServiceProvider BuildServiceProvider()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        return services.BuildServiceProvider();
+    }
+
+    private static async Task RunScenarioAsync(SmokeScenario scenario, string fixtureRoot, ILanguageAnalyzerPluginCatalog catalog, IServiceProvider services)
+    {
+        var scenarioRoot = Path.Combine(fixtureRoot, scenario.Name);
+        if (!Directory.Exists(scenarioRoot))
+        {
+            throw new DirectoryNotFoundException($"Scenario '{scenario.Name}' directory missing at '{scenarioRoot}'.");
+        }
+
+        var goldenPath = Path.Combine(scenarioRoot, "expected.json");
+        string? goldenNormalized = null;
+        if (File.Exists(goldenPath))
+        {
+            goldenNormalized = NormalizeJson(await File.ReadAllTextAsync(goldenPath).ConfigureAwait(false));
+        }
+
+        var usageHints = new LanguageUsageHints(scenario.ResolveUsageHints(scenarioRoot));
+        var context = new LanguageAnalyzerContext(scenarioRoot, TimeProvider.System, usageHints, services);
+
+        var coldEngine = new LanguageAnalyzerEngine(catalog.CreateAnalyzers(services));
+        var coldStopwatch = Stopwatch.StartNew();
+        var coldResult = await coldEngine.AnalyzeAsync(context, CancellationToken.None).ConfigureAwait(false);
+        coldStopwatch.Stop();
+
+        if (coldResult.Components.Count == 0)
+        {
+            throw new InvalidOperationException($"Scenario '{scenario.Name}' produced no components during cold run.");
+        }
+
+        var coldJson = NormalizeJson(coldResult.ToJson(indent: true));
+        if (goldenNormalized is string expected && !string.Equals(coldJson, expected, StringComparison.Ordinal))
+        {
+            Console.WriteLine($"⚠️ Scenario '{scenario.Name}' output deviates from repository golden snapshot.");
+        }
+
+        var warmEngine = new LanguageAnalyzerEngine(catalog.CreateAnalyzers(services));
+        var warmStopwatch = Stopwatch.StartNew();
+        var warmResult = await warmEngine.AnalyzeAsync(context, CancellationToken.None).ConfigureAwait(false);
+        warmStopwatch.Stop();
+
+        var warmJson = NormalizeJson(warmResult.ToJson(indent: true));
+        if (!string.Equals(coldJson, warmJson, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException($"Scenario '{scenario.Name}' produced different outputs between cold and warm runs.");
+        }
+
+        EnsureDurationWithinBudget(scenario.Name, coldStopwatch.Elapsed, warmStopwatch.Elapsed);
+
+        Console.WriteLine($"✓ Scenario '{scenario.Name}' — components {coldResult.Components.Count}, cold {coldStopwatch.Elapsed.TotalMilliseconds:F1} ms, warm {warmStopwatch.Elapsed.TotalMilliseconds:F1} ms");
+    }
+
+    private static void EnsureDurationWithinBudget(string scenarioName, TimeSpan coldDuration, TimeSpan warmDuration)
+    {
+        var coldBudget = TimeSpan.FromSeconds(30);
+        var warmBudget = TimeSpan.FromSeconds(5);
+
+        if (coldDuration > coldBudget)
+        {
+            throw new InvalidOperationException($"Scenario '{scenarioName}' cold run exceeded budget ({coldDuration.TotalSeconds:F2}s > {coldBudget.TotalSeconds:F2}s).");
+        }
+
+        if (warmDuration > warmBudget)
+        {
+            throw new InvalidOperationException($"Scenario '{scenarioName}' warm run exceeded budget ({warmDuration.TotalSeconds:F2}s > {warmBudget.TotalSeconds:F2}s).");
+        }
+    }
+
+    private static string NormalizeJson(string json)
+        => json.Replace("\r\n", "\n", StringComparison.Ordinal).TrimEnd();
+
+    private static void ValidateOptions(SmokeOptions options)
+    {
+        if (!Directory.Exists(options.RepoRoot))
+        {
+            throw new DirectoryNotFoundException($"Repository root '{options.RepoRoot}' does not exist.");
+        }
+    }
+
+    private static void ValidateManifest(PluginManifest manifest, string expectedDirectory)
+    {
+        if (!string.Equals(manifest.SchemaVersion, "1.0", StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException($"Unexpected manifest schema version '{manifest.SchemaVersion}'.");
+        }
+
+        if (!manifest.RequiresRestart)
+        {
+            throw new InvalidOperationException("Language analyzer plug-in must be marked as restart-only.");
+        }
+
+        if (!string.Equals(manifest.EntryPoint.Type, "dotnet", StringComparison.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException($"Unsupported entry point type '{manifest.EntryPoint.Type}'.");
+        }
+
+        if (!manifest.Capabilities.Contains("python", StringComparer.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException("Manifest capabilities do not include 'python'.");
+        }
+
+        if (!string.Equals(manifest.EntryPoint.TypeName, "StellaOps.Scanner.Analyzers.Lang.Python.PythonAnalyzerPlugin", StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException($"Unexpected entry point type name '{manifest.EntryPoint.TypeName}'.");
+        }
+
+        if (!string.Equals(manifest.Id, "stellaops.analyzer.lang.python", StringComparison.OrdinalIgnoreCase))
+        {
+            throw new InvalidOperationException($"Manifest id '{manifest.Id}' does not match expected plug-in id for directory '{expectedDirectory}'.");
+        }
+    }
+
+    private static string ComputeSha256(string path)
+    {
+        using var hash = SHA256.Create();
+        using var stream = File.OpenRead(path);
+        var digest = hash.ComputeHash(stream);
+        var builder = new StringBuilder(digest.Length * 2);
+        foreach (var b in digest)
+        {
+            builder.Append(b.ToString("x2"));
+        }
+        return builder.ToString();
+    }
+}

tools/PolicyDslValidator/PolicyDslValidator.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\StellaOps.Policy\StellaOps.Policy.csproj" />
+  </ItemGroup>
+
+</Project>

tools/PolicyDslValidator/Program.cs

@@ -0,0 +1,56 @@
+using StellaOps.Policy;
+
+if (args.Length == 0)
+{
+    Console.Error.WriteLine("Usage: policy-dsl-validator [--strict] [--json] <path-or-glob> [<path-or-glob> ...]");
+    Console.Error.WriteLine("Example: policy-dsl-validator --strict docs/examples/policies");
+    return 64; // EX_USAGE
+}
+
+var inputs = new List<string>();
+var strict = false;
+var outputJson = false;
+
+foreach (var arg in args)
+{
+    switch (arg)
+    {
+        case "--strict":
+        case "-s":
+            strict = true;
+            break;
+
+        case "--json":
+        case "-j":
+            outputJson = true;
+            break;
+
+        case "--help":
+        case "-h":
+        case "-?":
+            Console.WriteLine("Usage: policy-dsl-validator [--strict] [--json] <path-or-glob> [<path-or-glob> ...]");
+            Console.WriteLine("Example: policy-dsl-validator --strict docs/examples/policies");
+            return 0;
+
+        default:
+            inputs.Add(arg);
+            break;
+    }
+}
+
+if (inputs.Count == 0)
+{
+    Console.Error.WriteLine("No input files or directories provided.");
+    return 64; // EX_USAGE
+}
+
+var options = new PolicyValidationCliOptions
+{
+    Inputs = inputs,
+    Strict = strict,
+    OutputJson = outputJson,
+};
+
+var cli = new PolicyValidationCli();
+var exitCode = await cli.RunAsync(options, CancellationToken.None);
+return exitCode;

tools/PolicySchemaExporter/PolicySchemaExporter.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="NJsonSchema" Version="11.5.1" />
+    <PackageReference Include="NJsonSchema.SystemTextJson" Version="11.5.1" />
+    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\StellaOps.Scheduler.Models\StellaOps.Scheduler.Models.csproj" />
+  </ItemGroup>
+
+</Project>

tools/PolicySchemaExporter/Program.cs

@@ -0,0 +1,48 @@
+using System.Collections.Immutable;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using NJsonSchema;
+using NJsonSchema.Generation;
+using NJsonSchema.Generation.SystemTextJson;
+using Newtonsoft.Json;
+using StellaOps.Scheduler.Models;
+
+var output = args.Length switch
+{
+    0 => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "docs", "schemas")),
+    1 => Path.GetFullPath(args[0]),
+    _ => throw new ArgumentException("Usage: dotnet run --project tools/PolicySchemaExporter -- [outputDirectory]")
+};
+
+Directory.CreateDirectory(output);
+
+var generatorSettings = new SystemTextJsonSchemaGeneratorSettings
+{
+    SchemaType = SchemaType.JsonSchema,
+    DefaultReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull,
+    SerializerOptions = new JsonSerializerOptions
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+    },
+};
+
+var generator = new JsonSchemaGenerator(generatorSettings);
+
+var exports = ImmutableArray.Create(
+    (FileName: "policy-run-request.schema.json", Type: typeof(PolicyRunRequest)),
+    (FileName: "policy-run-status.schema.json", Type: typeof(PolicyRunStatus)),
+    (FileName: "policy-diff-summary.schema.json", Type: typeof(PolicyDiffSummary)),
+    (FileName: "policy-explain-trace.schema.json", Type: typeof(PolicyExplainTrace))
+);
+
+foreach (var export in exports)
+{
+    var schema = generator.Generate(export.Type);
+    schema.Title = export.Type.Name;
+    schema.AllowAdditionalProperties = false;
+
+    var outputPath = Path.Combine(output, export.FileName);
+    await File.WriteAllTextAsync(outputPath, schema.ToJson(Formatting.Indented) + Environment.NewLine);
+    Console.WriteLine($"Wrote {outputPath}");
+}

tools/PolicySimulationSmoke/PolicySimulationSmoke.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\StellaOps.Policy\StellaOps.Policy.csproj" />
+  </ItemGroup>
+
+</Project>

tools/PolicySimulationSmoke/Program.cs

@@ -0,0 +1,291 @@
+using System.Collections.Immutable;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using StellaOps.Policy;
+
+var scenarioRoot = "samples/policy/simulations";
+string? outputDir = null;
+
+for (var i = 0; i < args.Length; i++)
+{
+    var arg = args[i];
+    switch (arg)
+    {
+        case "--scenario-root":
+        case "-r":
+            if (i + 1 >= args.Length)
+            {
+                Console.Error.WriteLine("Missing value for --scenario-root.");
+                return 64;
+            }
+            scenarioRoot = args[++i];
+            break;
+        case "--output":
+        case "-o":
+            if (i + 1 >= args.Length)
+            {
+                Console.Error.WriteLine("Missing value for --output.");
+                return 64;
+            }
+            outputDir = args[++i];
+            break;
+        case "--help":
+        case "-h":
+        case "-?":
+            PrintUsage();
+            return 0;
+        default:
+            Console.Error.WriteLine($"Unknown argument '{arg}'.");
+            PrintUsage();
+            return 64;
+    }
+}
+
+if (!Directory.Exists(scenarioRoot))
+{
+    Console.Error.WriteLine($"Scenario root '{scenarioRoot}' does not exist.");
+    return 66;
+}
+
+var scenarioFiles = Directory.GetFiles(scenarioRoot, "scenario.json", SearchOption.AllDirectories);
+if (scenarioFiles.Length == 0)
+{
+    Console.Error.WriteLine($"No scenario.json files found under '{scenarioRoot}'.");
+    return 0;
+}
+
+var loggerFactory = NullLoggerFactory.Instance;
+var snapshotStore = new PolicySnapshotStore(
+    new NullPolicySnapshotRepository(),
+    new NullPolicyAuditRepository(),
+    TimeProvider.System,
+    loggerFactory.CreateLogger<PolicySnapshotStore>());
+var previewService = new PolicyPreviewService(snapshotStore, loggerFactory.CreateLogger<PolicyPreviewService>());
+
+var serializerOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web)
+{
+    PropertyNameCaseInsensitive = true,
+    ReadCommentHandling = JsonCommentHandling.Skip,
+};
+
+var summary = new List<ScenarioResult>();
+var success = true;
+
+foreach (var scenarioFile in scenarioFiles.OrderBy(static f => f, StringComparer.OrdinalIgnoreCase))
+{
+    var scenarioText = await File.ReadAllTextAsync(scenarioFile);
+    var scenario = JsonSerializer.Deserialize<PolicySimulationScenario>(scenarioText, serializerOptions);
+    if (scenario is null)
+    {
+        Console.Error.WriteLine($"Failed to deserialize scenario '{scenarioFile}'.");
+        success = false;
+        continue;
+    }
+
+    var repoRoot = Directory.GetCurrentDirectory();
+    var policyPath = Path.Combine(repoRoot, scenario.PolicyPath);
+    if (!File.Exists(policyPath))
+    {
+        Console.Error.WriteLine($"Policy file '{scenario.PolicyPath}' referenced by scenario '{scenario.Name}' does not exist.");
+        success = false;
+        continue;
+    }
+
+    var policyContent = await File.ReadAllTextAsync(policyPath);
+    var policyFormat = PolicySchema.DetectFormat(policyPath);
+    var findings = scenario.Findings.Select(ToPolicyFinding).ToImmutableArray();
+    var baseline = scenario.Baseline?.Select(ToPolicyVerdict).ToImmutableArray() ?? ImmutableArray<PolicyVerdict>.Empty;
+
+    var request = new PolicyPreviewRequest(
+        ImageDigest: $"sha256:simulation-{scenario.Name}",
+        Findings: findings,
+        BaselineVerdicts: baseline,
+        SnapshotOverride: null,
+        ProposedPolicy: new PolicySnapshotContent(
+            Content: policyContent,
+            Format: policyFormat,
+            Actor: "ci",
+            Source: "ci/simulation-smoke",
+            Description: $"CI simulation for scenario '{scenario.Name}'"));
+
+    var response = await previewService.PreviewAsync(request, CancellationToken.None);
+    var scenarioResult = EvaluateScenario(scenario, response);
+    summary.Add(scenarioResult);
+
+    if (!scenarioResult.Success)
+    {
+        success = false;
+    }
+}
+
+if (outputDir is not null)
+{
+    Directory.CreateDirectory(outputDir);
+    var summaryPath = Path.Combine(outputDir, "policy-simulation-summary.json");
+    await File.WriteAllTextAsync(summaryPath, JsonSerializer.Serialize(summary, new JsonSerializerOptions { WriteIndented = true }));
+}
+
+return success ? 0 : 1;
+
+static void PrintUsage()
+{
+    Console.WriteLine("Usage: policy-simulation-smoke [--scenario-root <path>] [--output <dir>]");
+    Console.WriteLine("Example: policy-simulation-smoke --scenario-root samples/policy/simulations --output artifacts/policy-simulations");
+}
+
+static PolicyFinding ToPolicyFinding(ScenarioFinding finding)
+{
+    var tags = finding.Tags is null ? ImmutableArray<string>.Empty : ImmutableArray.CreateRange(finding.Tags);
+    var severity = Enum.Parse<PolicySeverity>(finding.Severity, ignoreCase: true);
+    return new PolicyFinding(
+        finding.FindingId,
+        severity,
+        finding.Environment,
+        finding.Source,
+        finding.Vendor,
+        finding.License,
+        finding.Image,
+        finding.Repository,
+        finding.Package,
+        finding.Purl,
+        finding.Cve,
+        finding.Path,
+        finding.LayerDigest,
+        tags);
+}
+
+static PolicyVerdict ToPolicyVerdict(ScenarioBaseline baseline)
+{
+    var status = Enum.Parse<PolicyVerdictStatus>(baseline.Status, ignoreCase: true);
+    var inputs = baseline.Inputs?.ToImmutableDictionary(StringComparer.OrdinalIgnoreCase) ?? ImmutableDictionary<string, double>.Empty;
+    return new PolicyVerdict(
+        baseline.FindingId,
+        status,
+        RuleName: baseline.RuleName,
+        RuleAction: baseline.RuleAction,
+        Notes: baseline.Notes,
+        Score: baseline.Score,
+        ConfigVersion: baseline.ConfigVersion ?? PolicyScoringConfig.Default.Version,
+        Inputs: inputs,
+        QuietedBy: null,
+        Quiet: false,
+        UnknownConfidence: null,
+        ConfidenceBand: null,
+        UnknownAgeDays: null,
+        SourceTrust: null,
+        Reachability: null);
+}
+
+static ScenarioResult EvaluateScenario(PolicySimulationScenario scenario, PolicyPreviewResponse response)
+{
+    var result = new ScenarioResult(scenario.Name);
+    if (!response.Success)
+    {
+        result.Failures.Add("Preview failed.");
+        return result with { Success = false, ChangedCount = response.ChangedCount };
+    }
+
+    var diffs = response.Diffs.ToDictionary(diff => diff.Projected.FindingId, StringComparer.OrdinalIgnoreCase);
+    foreach (var expected in scenario.ExpectedDiffs)
+    {
+        if (!diffs.TryGetValue(expected.FindingId, out var diff))
+        {
+            result.Failures.Add($"Expected finding '{expected.FindingId}' missing from diff.");
+            continue;
+        }
+
+        var projectedStatus = diff.Projected.Status.ToString();
+        result.ActualStatuses[expected.FindingId] = projectedStatus;
+        if (!string.Equals(projectedStatus, expected.Status, StringComparison.OrdinalIgnoreCase))
+        {
+            result.Failures.Add($"Finding '{expected.FindingId}' expected status '{expected.Status}' but was '{projectedStatus}'.");
+        }
+    }
+
+    foreach (var diff in diffs.Values)
+    {
+        if (!result.ActualStatuses.ContainsKey(diff.Projected.FindingId))
+        {
+            result.ActualStatuses[diff.Projected.FindingId] = diff.Projected.Status.ToString();
+        }
+    }
+
+    var success = result.Failures.Count == 0;
+    return result with
+    {
+        Success = success,
+        ChangedCount = response.ChangedCount
+    };
+}
+
+internal sealed record PolicySimulationScenario
+{
+    public string Name { get; init; } = "scenario";
+    public string PolicyPath { get; init; } = string.Empty;
+    public List<ScenarioFinding> Findings { get; init; } = new();
+    public List<ScenarioExpectedDiff> ExpectedDiffs { get; init; } = new();
+    public List<ScenarioBaseline>? Baseline { get; init; }
+}
+
+internal sealed record ScenarioFinding
+{
+    public string FindingId { get; init; } = string.Empty;
+    public string Severity { get; init; } = "Low";
+    public string? Environment { get; init; }
+    public string? Source { get; init; }
+    public string? Vendor { get; init; }
+    public string? License { get; init; }
+    public string? Image { get; init; }
+    public string? Repository { get; init; }
+    public string? Package { get; init; }
+    public string? Purl { get; init; }
+    public string? Cve { get; init; }
+    public string? Path { get; init; }
+    public string? LayerDigest { get; init; }
+    public string[]? Tags { get; init; }
+}
+
+internal sealed record ScenarioExpectedDiff
+{
+    public string FindingId { get; init; } = string.Empty;
+    public string Status { get; init; } = "Pass";
+}
+
+internal sealed record ScenarioBaseline
+{
+    public string FindingId { get; init; } = string.Empty;
+    public string Status { get; init; } = "Pass";
+    public string? RuleName { get; init; }
+    public string? RuleAction { get; init; }
+    public string? Notes { get; init; }
+    public double Score { get; init; }
+    public string? ConfigVersion { get; init; }
+    public Dictionary<string, double>? Inputs { get; init; }
+}
+
+internal sealed record ScenarioResult(string ScenarioName)
+{
+    public bool Success { get; init; } = true;
+    public int ChangedCount { get; init; }
+    public List<string> Failures { get; } = new();
+    public Dictionary<string, string> ActualStatuses { get; } = new(StringComparer.OrdinalIgnoreCase);
+}
+
+internal sealed class NullPolicySnapshotRepository : IPolicySnapshotRepository
+{
+    public Task AddAsync(PolicySnapshot snapshot, CancellationToken cancellationToken = default) => Task.CompletedTask;
+
+    public Task<PolicySnapshot?> GetLatestAsync(CancellationToken cancellationToken = default) => Task.FromResult<PolicySnapshot?>(null);
+
+    public Task<IReadOnlyList<PolicySnapshot>> ListAsync(int limit, CancellationToken cancellationToken = default)
+        => Task.FromResult<IReadOnlyList<PolicySnapshot>>(Array.Empty<PolicySnapshot>());
+}
+
+internal sealed class NullPolicyAuditRepository : IPolicyAuditRepository
+{
+    public Task AddAsync(PolicyAuditEntry entry, CancellationToken cancellationToken = default) => Task.CompletedTask;
+
+    public Task<IReadOnlyList<PolicyAuditEntry>> ListAsync(int limit, CancellationToken cancellationToken = default)
+        => Task.FromResult<IReadOnlyList<PolicyAuditEntry>>(Array.Empty<PolicyAuditEntry>());
+}