feat(clone): automated, provably-correct cloning for options and layers

.editorconfig

@@ -159,12 +159,23 @@ csharp_space_between_square_brackets = false
 # License header
 file_header_template = Licensed to the .NET Foundation under one or more agreements.\nThe .NET Foundation licenses this file to you under the MIT license.
 
+# ADN0057 is informational for NuGet consumers, whose custom initialization-only constructor
+# arguments may be intentional. In this repository it is an acceptance gate: every shipped layer
+# must either preserve the value or classify its entropy semantics explicitly.
+dotnet_diagnostic.ADN0057.severity = error
+
+# Concrete models and layers in the shipped source must use generated/base lifecycle plumbing.
+# The analyzer remains informational for external consumers, whose own base contracts may require
+# an override; this repository raises it to an acceptance error.
+dotnet_diagnostic.ADN0063.severity = error
+
 # Dedicated test doubles deliberately override parameter surfaces to simulate malformed,
 # throwing, or streaming implementations. Production descriptors remain compiler errors; this
 # explicit path-scoped policy keeps those fixtures buildable without an assembly-name heuristic.
 [tests/AiDotNet.Tests/**/*.cs]
 dotnet_diagnostic.AIDN081.severity = warning
 dotnet_diagnostic.AIDN082.severity = warning
+dotnet_diagnostic.ADN0063.severity = warning
 
 [src/libraries/System.Net.Http/src/System/Net/Http/{SocketsHttpHandler/Http3RequestStream.cs,BrowserHttpHandler/BrowserHttpHandler.cs}]
 # disable CA2025, the analyzer throws a NullReferenceException when processing this file: https://github.com/dotnet/roslyn-analyzers/issues/7652

.github/scripts/find-pr-new-failures.ps1

@@ -0,0 +1,108 @@
+<#
+.SYNOPSIS
+Builds a VSTest filter for failures present in a PR shard but absent from the exact master baseline.
+
+.DESCRIPTION
+This is deliberately a retry selector, not a verdict engine. It reads the initial shard TRX and
+either the compact baseline ledger or the legacy baseline TRX, writes the candidate inventory, and
+publishes rerun_count/filter outputs. The aggregate analyzer consumes both the original and retry
+TRX and owns the final policy decision.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string] $CurrentResultsPath,
+    [string] $BaselineResultsPath,
+    [string] $BaselineLedgerPath,
+    [Parameter(Mandatory = $true)]
+    [string] $OutputFile
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Get-TrxResults {
+    param([string] $Root)
+
+    $results = New-Object System.Collections.Generic.List[object]
+    foreach ($trx in @(Get-ChildItem -LiteralPath $Root -Recurse -Filter '*.trx' -File -ErrorAction SilentlyContinue)) {
+        [xml] $document = Get-Content -LiteralPath $trx.FullName -Raw
+        $definitions = @{}
+        foreach ($unitTest in @($document.SelectNodes('//*[local-name()="UnitTest"]'))) {
+            $method = $unitTest.SelectSingleNode('./*[local-name()="TestMethod"]')
+            if ($method -and $unitTest.id) {
+                $className = [string] $method.className
+                $methodName = [string] $method.name
+                $definitions[[string] $unitTest.id] = if ($className) {
+                    "$className.$methodName"
+                } else { $methodName }
+            }
+        }
+
+        foreach ($result in @($document.SelectNodes('//*[local-name()="UnitTestResult"]'))) {
+            $display = [string] $result.testName
+            $fullyQualified = $definitions[[string] $result.testId]
+            if ([string]::IsNullOrWhiteSpace($fullyQualified)) { $fullyQualified = $display }
+            $identity = if ($display -and $display -ne $fullyQualified) {
+                "$fullyQualified::$display"
+            } else { $fullyQualified }
+            if (-not [string]::IsNullOrWhiteSpace($identity)) {
+                $results.Add([PSCustomObject]@{
+                    identity = $identity
+                    fullyQualifiedName = $fullyQualified
+                    displayName = $display
+                    outcome = [string] $result.outcome
+                })
+            }
+        }
+    }
+    return $results.ToArray()
+}
+
+function Set-ActionOutput {
+    param([string] $Name, [string] $Value)
+    Write-Host "$Name=$Value"
+    if ($env:GITHUB_OUTPUT) { Add-Content -LiteralPath $env:GITHUB_OUTPUT -Value "$Name=$Value" }
+}
+
+if (-not (Test-Path -LiteralPath $CurrentResultsPath)) {
+    throw "Current result directory not found: $CurrentResultsPath"
+}
+
+$current = @(Get-TrxResults $CurrentResultsPath)
+$baseline = if ($BaselineLedgerPath) {
+    if (-not (Test-Path -LiteralPath $BaselineLedgerPath)) {
+        throw "Baseline ledger not found: $BaselineLedgerPath"
+    }
+    @((Get-Content -LiteralPath $BaselineLedgerPath -Raw | ConvertFrom-Json).tests)
+} elseif ($BaselineResultsPath) {
+    if (-not (Test-Path -LiteralPath $BaselineResultsPath)) {
+        throw "Baseline result directory not found: $BaselineResultsPath"
+    }
+    @(Get-TrxResults $BaselineResultsPath)
+} else {
+    throw 'BaselineLedgerPath or BaselineResultsPath is required.'
+}
+
+$baselineFailures = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::Ordinal)
+foreach ($failure in @($baseline | Where-Object outcome -eq 'Failed')) {
+    [void] $baselineFailures.Add([string] $failure.identity)
+}
+
+$candidates = @($current |
+    Where-Object { $_.outcome -eq 'Failed' -and -not $baselineFailures.Contains([string] $_.identity) } |
+    Sort-Object identity -Unique)
+$methods = @($candidates.fullyQualifiedName | Where-Object { $_ } | Sort-Object -Unique)
+$filterParts = @($methods | ForEach-Object { "FullyQualifiedName=$_" })
+$filter = $filterParts -join '|'
+
+$outputParent = Split-Path -Parent $OutputFile
+if ($outputParent) { New-Item -Path $outputParent -ItemType Directory -Force | Out-Null }
+[PSCustomObject]@{
+    candidateCount = $candidates.Count
+    methodCount = $methods.Count
+    candidates = $candidates
+} | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $OutputFile -Encoding utf8
+
+Set-ActionOutput 'rerun_count' ([string] $methods.Count)
+Set-ActionOutput 'filter' $filter

.github/scripts/find-test-baseline.ps1

@@ -0,0 +1,73 @@
+<#
+.SYNOPSIS
+Finds the exact Actions run/artifact that represents a pull request's base SHA.
+
+.DESCRIPTION
+Prefers the compact TRX ledger emitted by the aggregate job. For the first run
+after this feature is introduced, falls back to the legacy coverage/TRX artifacts
+from the exact master SHA so the rollout does not require a manual baseline.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string] $BaseSha,
+    [string] $Repository = $env:GITHUB_REPOSITORY,
+    [string] $Workflow = 'sonarcloud.yml',
+    [string] $ShardSlug
+)
+
+$ErrorActionPreference = 'Stop'
+if (-not $Repository) { throw 'Repository is required (owner/name).' }
+if (-not $env:GITHUB_STEP_SUMMARY -and -not $env:GITHUB_OUTPUT) {
+    Write-Verbose 'Running outside Actions; outputs will be written to the console only.'
+}
+
+function Invoke-GhJson {
+    param([string] $Endpoint)
+    $raw = & gh api $Endpoint
+    if ($LASTEXITCODE -ne 0) { throw "gh api failed for '$Endpoint'." }
+    return $raw | ConvertFrom-Json
+}
+
+function Set-ActionOutput {
+    param([string] $Name, [string] $Value)
+    Write-Host "$Name=$Value"
+    if ($env:GITHUB_OUTPUT) { Add-Content -LiteralPath $env:GITHUB_OUTPUT -Value "$Name=$Value" }
+}
+
+$artifactName = "test-outcome-ledger-$BaseSha"
+$encodedName = [Uri]::EscapeDataString($artifactName)
+$artifactResponse = Invoke-GhJson "repos/$Repository/actions/artifacts?name=$encodedName&per_page=100"
+$ledgerArtifact = @($artifactResponse.artifacts |
+    Where-Object {
+        -not $_.expired -and $_.name -eq $artifactName -and
+        $_.workflow_run -and $_.workflow_run.head_sha -eq $BaseSha
+    } |
+    Sort-Object created_at -Descending | Select-Object -First 1)
+
+if ($ledgerArtifact.Count -gt 0) {
+    Set-ActionOutput 'baseline_mode' 'ledger'
+    Set-ActionOutput 'baseline_run_id' ([string] $ledgerArtifact[0].workflow_run.id)
+    Set-ActionOutput 'baseline_sha' $BaseSha
+    if ($ShardSlug) { Set-ActionOutput 'baseline_artifact_name' $artifactName }
+    exit 0
+}
+
+# Bootstrap path: this base SHA predates compact ledgers. Locate the exact push
+# run and let download-artifact fetch its coverage-<sha>-* artifacts. Conclusion
+# is intentionally unrestricted: master workflows can be cancelled by CodeQL
+# after every test shard has already uploaded a valid TRX.
+$encodedWorkflow = [Uri]::EscapeDataString($Workflow)
+$runs = Invoke-GhJson "repos/$Repository/actions/workflows/$encodedWorkflow/runs?head_sha=$BaseSha&event=push&per_page=100"
+$run = @($runs.workflow_runs |
+    Where-Object { $_.head_sha -eq $BaseSha -and $_.status -eq 'completed' } |
+    Sort-Object run_attempt, created_at -Descending | Select-Object -First 1)
+if ($run.Count -eq 0) {
+    throw "No completed '$Workflow' push run exists for exact baseline SHA $BaseSha."
+}
+
+Set-ActionOutput 'baseline_mode' 'trx'
+Set-ActionOutput 'baseline_run_id' ([string] $run[0].id)
+Set-ActionOutput 'baseline_sha' $BaseSha
+if ($ShardSlug) { Set-ActionOutput 'baseline_artifact_name' "coverage-$BaseSha-$ShardSlug" }

.github/scripts/report-test-totals.ps1

@@ -0,0 +1,158 @@
+# Report aggregate test totals across every shard artifact downloaded by CI.
+#
+# This is a reporter, not a gate. It always exits zero and writes stable outputs for the CI Gate.
+# Counts are explicitly labelled as a floor when a TRX is missing/unreadable, a blame-hang sequence
+# is present, or the TRX counters show that not every discovered test executed.
+
+[CmdletBinding()]
+param(
+    [string]$ResultsPath = 'TestResults',
+    [string]$WorkflowPath = '.github/workflows/sonarcloud.yml',
+    [int]$ExpectedShardCount = 0
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Add-Summary {
+    param([string]$Line)
+    Write-Host $Line
+    if ($env:GITHUB_STEP_SUMMARY) {
+        try { Add-Content -LiteralPath $env:GITHUB_STEP_SUMMARY -Value $Line -ErrorAction Stop }
+        catch { Write-Host "::warning::Could not append aggregate test totals to the step summary: $($_.Exception.Message)" }
+    }
+}
+
+function Set-CiOutput {
+    param([string]$Name, [string]$Value)
+    if ($env:GITHUB_OUTPUT) {
+        try { Add-Content -LiteralPath $env:GITHUB_OUTPUT -Value "$Name=$Value" -ErrorAction Stop }
+        catch { Write-Host "::warning::Could not write aggregate output '$Name': $($_.Exception.Message)" }
+    }
+}
+
+$body = {
+    $expectedShards = $ExpectedShardCount
+    if ($expectedShards -le 0 -and (Test-Path -LiteralPath $WorkflowPath)) {
+        # Keep this self-updating with the matrix instead of hard-coding 110. Job keys are indented
+        # two spaces and shard entries ten, so the next job key closes the section unambiguously.
+        $insideShardedJob = $false
+        foreach ($line in Get-Content -LiteralPath $WorkflowPath) {
+            if ($line -match '^  test-net10-sharded:\s*$') {
+                $insideShardedJob = $true
+                continue
+            }
+            if ($insideShardedJob -and $line -match '^  [A-Za-z0-9_-]+:\s*$') { break }
+            if ($insideShardedJob -and $line -match '^          - name:\s+') { $expectedShards++ }
+        }
+    }
+
+    $trxFiles = @(Get-ChildItem -LiteralPath $ResultsPath -Recurse -Filter '*.trx' -ErrorAction SilentlyContinue)
+    $sequenceFiles = @(Get-ChildItem -LiteralPath $ResultsPath -Recurse -Filter 'Sequence_*.xml' -ErrorAction SilentlyContinue)
+    $failedOccurrences = 0
+    $failedNames = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal)
+    $hangVictims = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal)
+    $unparseableTrx = [System.Collections.Generic.List[string]]::new()
+    $unparseableSequence = [System.Collections.Generic.List[string]]::new()
+    $executed = 0
+    $discovered = 0
+    $missingCounters = 0
+
+    foreach ($trx in $trxFiles) {
+        try {
+            [xml]$document = Get-Content -LiteralPath $trx.FullName -Raw
+            $failures = @($document.SelectNodes("//*[local-name()='UnitTestResult' and @outcome='Failed']"))
+            $failedOccurrences += $failures.Count
+            foreach ($failure in $failures) {
+                $name = [string]$failure.testName
+                if (-not [string]::IsNullOrWhiteSpace($name)) { [void]$failedNames.Add($name) }
+            }
+
+            $counters = $document.SelectSingleNode("//*[local-name()='Counters']")
+            if ($counters) {
+                $executed += [int]$counters.executed
+                $discovered += [int]$counters.total
+            } else {
+                $missingCounters++
+            }
+        } catch {
+            $unparseableTrx.Add("$($trx.FullName): $($_.Exception.Message)")
+        }
+    }
+
+    foreach ($sequence in $sequenceFiles) {
+        try {
+            [xml]$document = Get-Content -LiteralPath $sequence.FullName -Raw
+            $elements = @($document.SelectNodes("//*[local-name()='UnitTestElement']"))
+            if ($elements.Count -eq 0) { continue }
+            $last = $elements[$elements.Count - 1]
+            $name = [string]$last.FullyQualifiedName
+            if ([string]::IsNullOrWhiteSpace($name)) { $name = [string]$last.InnerText }
+            if (-not [string]::IsNullOrWhiteSpace($name)) { [void]$hangVictims.Add($name.Trim()) }
+        } catch {
+            $unparseableSequence.Add("$($sequence.FullName): $($_.Exception.Message)")
+        }
+    }
+
+    # A blame-hang victim normally has no failed TRX row because the host was killed while it ran.
+    # Count only victims not already present so the aggregate matches the normalized baseline logic.
+    $additionalHangFailures = 0
+    foreach ($victim in $hangVictims) {
+        if ($failedNames.Add($victim)) { $additionalHangFailures++ }
+    }
+
+    $knownFailures = $failedOccurrences + $additionalHangFailures
+    $incomplete = $trxFiles.Count -eq 0 -or $expectedShards -le 0 -or
+        $trxFiles.Count -ne $expectedShards -or $unparseableTrx.Count -gt 0 -or
+        $unparseableSequence.Count -gt 0 -or
+        $missingCounters -gt 0 -or $hangVictims.Count -gt 0 -or
+        ($discovered -gt 0 -and $executed -lt $discovered)
+
+    $failureOutput = if ($trxFiles.Count -eq 0) { 'unknown' } else { [string]$knownFailures }
+    $distinctOutput = if ($trxFiles.Count -eq 0) { 'unknown' } else { [string]$failedNames.Count }
+    $expectedShardOutput = if ($expectedShards -gt 0) { [string]$expectedShards } else { 'unknown' }
+    Set-CiOutput 'failed_test_occurrences' $failureOutput
+    Set-CiOutput 'distinct_failing_tests' $distinctOutput
+    Set-CiOutput 'executed_tests' ([string]$executed)
+    Set-CiOutput 'discovered_tests' ([string]$discovered)
+    Set-CiOutput 'reported_shards' ([string]$trxFiles.Count)
+    Set-CiOutput 'expected_shards' $expectedShardOutput
+    Set-CiOutput 'test_totals_incomplete' $incomplete.ToString().ToLowerInvariant()
+
+    Add-Summary '## Aggregate test totals'
+    Add-Summary ''
+    Add-Summary '| Metric | Total |'
+    Add-Summary '|---|---:|'
+    Add-Summary "| Failed test occurrences (including unique hang victims) | $failureOutput |"
+    Add-Summary "| Distinct failing tests | $distinctOutput |"
+    Add-Summary "| Executed tests | $executed |"
+    Add-Summary "| Discovered tests | $discovered |"
+    Add-Summary "| Parsed TRX files | $($trxFiles.Count - $unparseableTrx.Count) / $($trxFiles.Count) |"
+    Add-Summary "| Reported shards | $($trxFiles.Count) / $expectedShardOutput |"
+    Add-Summary "| Blame-hang victims | $($hangVictims.Count) |"
+
+    if ($incomplete) {
+        Add-Summary ''
+        Add-Summary ':warning: **These failure totals are incomplete or unknown.** Treat numeric values as a floor.'
+    }
+    if ($unparseableTrx.Count -gt 0) {
+        foreach ($errorText in $unparseableTrx) { Add-Summary ('    ' + $errorText) }
+    }
+    if ($unparseableSequence.Count -gt 0) {
+        foreach ($errorText in $unparseableSequence) { Add-Summary ('    ' + $errorText) }
+    }
+}
+
+try {
+    & $body
+} catch {
+    Write-Host "::warning::report-test-totals.ps1 could not complete: $($_.Exception.Message)"
+    Set-CiOutput 'failed_test_occurrences' 'unknown'
+    Set-CiOutput 'distinct_failing_tests' 'unknown'
+    Set-CiOutput 'executed_tests' 'unknown'
+    Set-CiOutput 'discovered_tests' 'unknown'
+    Set-CiOutput 'reported_shards' 'unknown'
+    Set-CiOutput 'expected_shards' 'unknown'
+    Set-CiOutput 'test_totals_incomplete' 'true'
+}
+
+exit 0