feat(runtime): add deterministic dissemination broadcast and repair

.github/scripts/dissemination-compatibility.ps1

@@ -0,0 +1,143 @@
+[CmdletBinding()]
+param(
+    [string] $BaselineDirectory = '.dissemination-baseline',
+    [string] $ArtifactsDirectory = 'Artifacts/DisseminationCompatibility',
+    [switch] $SkipBuild
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+$baselineSha = '6739589254b746a8790cf53524e6abe372bb53d4'
+$root = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot '../..'))
+$artifacts = [System.IO.Path]::GetFullPath((Join-Path $root $ArtifactsDirectory))
+$binaries = Join-Path $artifacts 'bin'
+$results = Join-Path $artifacts 'results'
+New-Item -ItemType Directory -Force $binaries, $results | Out-Null
+
+function Invoke-DotNet([string[]] $Arguments) {
+    & dotnet @Arguments
+    if ($LASTEXITCODE -ne 0) {
+        throw "dotnet failed ($LASTEXITCODE): $($Arguments -join ' ')"
+    }
+}
+
+function Get-Revision([string] $Directory) {
+    $revision = & git -C $Directory rev-parse HEAD
+    if ($LASTEXITCODE -ne 0) {
+        throw "Not a source checkout: $Directory"
+    }
+    return $revision.Trim()
+}
+
+function Publish-Silo([string] $Checkout, [string] $Runtime, [string] $Revision) {
+    $project = Join-Path $Checkout 'test/Dissemination.IntegrationHarness/Silo/Dissemination.Silo.csproj'
+    $output = Join-Path $binaries $Runtime
+    Invoke-DotNet @(
+        'publish', $project, '--configuration', 'Release', '--framework', 'net10.0',
+        '--output', $output, '--verbosity', 'minimal',
+        "-p:HarnessRuntime=$Runtime", "-p:SourceRevisionId=$Revision",
+        '-p:OfficialBuild=true', "-p:BUILD_SOURCEVERSION=$Revision",
+        "-bl:$(Join-Path $artifacts "build-$Runtime.binlog")"
+    )
+    $assemblyPath = Join-Path $output 'Orleans.Runtime.dll'
+    $identity = [System.Reflection.AssemblyName]::GetAssemblyName($assemblyPath)
+    $assemblies = @{}
+    foreach ($file in Get-ChildItem -LiteralPath $output -Filter 'Orleans*.dll' -File) {
+        $name = [System.Reflection.AssemblyName]::GetAssemblyName($file.FullName)
+        $assemblies[$name.Name] = @{
+            AssemblyVersion = $name.Version.ToString()
+            Sha256 = (Get-FileHash -LiteralPath $file.FullName -Algorithm SHA256).Hash
+        }
+    }
+    @{
+        Runtime = $Runtime
+        SourceRevision = $Revision
+        AssemblyName = $identity.Name
+        AssemblyVersion = $identity.Version.ToString()
+        Sha256 = (Get-FileHash -LiteralPath $assemblyPath -Algorithm SHA256).Hash
+        Assemblies = $assemblies
+    } | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $output 'manifest.json')
+}
+
+if (!$SkipBuild) {
+    if ($env:GITHUB_ACTIONS -ne 'true') {
+        throw 'Building the pinned baseline is CI-only. Download the workflow binary artifact and use -SkipBuild for explicit local reproduction.'
+    }
+
+    $baseline = [System.IO.Path]::GetFullPath((Join-Path $root $BaselineDirectory))
+    if ($baseline -eq $root) {
+        throw 'The baseline must not be the feature checkout.'
+    }
+    $baselineTopLevel = (& git -C $baseline rev-parse --show-toplevel)
+    if ($LASTEXITCODE -ne 0 -or [System.IO.Path]::GetFullPath($baselineTopLevel.Trim()) -ne $baseline) {
+        throw 'The baseline must have its own isolated git checkout, not merely a directory in the feature checkout.'
+    }
+    if ((Get-Revision $baseline) -ne $baselineSha) {
+        throw "Baseline must be pinned to $baselineSha."
+    }
+    $sourceChanges = & git -C $baseline status --porcelain --untracked-files=all -- src
+    if ($LASTEXITCODE -ne 0 -or $sourceChanges) {
+        throw 'Pinned baseline runtime sources have local modifications.'
+    }
+    if (Test-Path -LiteralPath (Join-Path $baseline 'src/Orleans.Runtime/Dissemination')) {
+        throw 'The pinned baseline unexpectedly contains the new dissemination implementation.'
+    }
+
+    # Only the test executable is copied. Every Orleans source project resolves inside its own checkout.
+    $harnessSource = Join-Path $root 'test/Dissemination.IntegrationHarness'
+    $harnessDestination = Join-Path $baseline 'test/Dissemination.IntegrationHarness'
+    if (Test-Path -LiteralPath $harnessDestination) {
+        throw "Refusing to overwrite an existing baseline harness: $harnessDestination"
+    }
+    New-Item -ItemType Directory -Force $harnessDestination | Out-Null
+    foreach ($part in @('Silo', 'Shared')) {
+        New-Item -ItemType Directory -Force (Join-Path $harnessDestination $part) | Out-Null
+        Get-ChildItem -LiteralPath (Join-Path $harnessSource $part) -File |
+            Where-Object { $_.Extension -in '.cs', '.csproj' } |
+            Copy-Item -Destination (Join-Path $harnessDestination $part)
+    }
+
+    Publish-Silo $baseline 'Old' $baselineSha
+    Publish-Silo $root 'New' (Get-Revision $root)
+    Invoke-DotNet @(
+        'publish', (Join-Path $root 'test/Dissemination.IntegrationHarness/Tests/Dissemination.IntegrationHarness.Tests.csproj'),
+        '--configuration', 'Release', '--framework', 'net10.0',
+        '--output', (Join-Path $binaries 'Runner'), '--verbosity', 'minimal',
+        "-bl:$(Join-Path $artifacts 'build-runner.binlog')"
+    )
+}
+
+$env:ORLEANS_DISSEMINATION_OLD = Join-Path $binaries 'Old'
+$env:ORLEANS_DISSEMINATION_NEW = Join-Path $binaries 'New'
+$env:ORLEANS_DISSEMINATION_RESULTS = $results
+$runner = Join-Path $binaries 'Runner/Dissemination.IntegrationHarness.Tests.dll'
+if (!(Test-Path -LiteralPath $runner)) {
+    throw "Published runner not found: $runner"
+}
+$testClass = 'Orleans.Dissemination.IntegrationHarness.VersionSkewTests'
+$minimum = '10'
+
+@{
+    PinnedBaseline = $baselineSha
+    CurrentCommit = Get-Revision $root
+    StartUtc = [DateTimeOffset]::UtcNow
+    Command = "dotnet $runner --filter-class $testClass --minimum-expected-tests $minimum --report-trx"
+    Environment = 'Separate loopback OS processes with a controlled test membership provider.'
+} | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $results 'invocation.json')
+
+Push-Location $root
+try {
+    Invoke-DotNet @(
+        $runner, '--filter-class', 'Orleans.Dissemination.IntegrationHarness.CompatibilityHarnessTests',
+        '--minimum-expected-tests', '8', '--report-trx',
+        '--results-directory', (Join-Path $results 'harness-checks')
+    )
+
+    Invoke-DotNet @(
+        $runner, '--filter-class', $testClass, '--minimum-expected-tests', $minimum,
+        '--report-trx', '--results-directory', $results
+    )
+}
+finally {
+    Pop-Location
+}

.github/workflows/dissemination-compatibility.yml

@@ -0,0 +1,78 @@
+name: Dissemination compatibility
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/workflows/dissemination-compatibility.yml'
+      - '.github/scripts/dissemination-compatibility.ps1'
+      - 'test/Dissemination.IntegrationHarness/**'
+      - 'src/Orleans.Core.Abstractions/IDs/SiloAddress.cs'
+      - 'src/Orleans.Runtime/Dissemination/**'
+      - 'src/Orleans.Runtime/MembershipService/**'
+      - 'src/Orleans.Runtime/Placement/DeploymentLoadPublisher.cs'
+      - 'src/Orleans.Runtime/Configuration/Options/DeploymentLoadPublisherOptions.cs'
+      - 'src/Orleans.Runtime/Configuration/Options/DisseminationOptionsValidator.cs'
+      - 'src/Orleans.Runtime/Hosting/DefaultSiloServices.cs'
+      - 'src/Orleans.Runtime/OrleansContracts.txt'
+      - 'src/Orleans.Core/OrleansContracts.txt'
+      - 'src/Orleans.Core/Runtime/Constants.cs'
+      - 'src/Orleans.Core/Runtime/MembershipTableSnapshot.cs'
+      - 'src/Orleans.Core/SystemTargetInterfaces/IDisseminationSystemTarget.cs'
+      - 'src/Orleans.Core/SystemTargetInterfaces/IDeploymentLoadPublisher.cs'
+      - 'src/Orleans.Core/SystemTargetInterfaces/IMembershipTable.cs'
+      - 'src/Orleans.Core/Configuration/Options/ClusterMembershipOptions.cs'
+      - 'src/Orleans.Core/Configuration/Options/DisseminationOptions.cs'
+  merge_group:
+    types: [checks_requested]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dissemination-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+  DOTNET_NOLOGO: true
+
+jobs:
+  version-skew:
+    name: Pinned-binary upgrade, rollback and recovery
+    runs-on: ubuntu-latest
+    timeout-minutes: 35
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - name: Isolated pre-dissemination checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          repository: dotnet/orleans
+          ref: 6739589254b746a8790cf53524e6abe372bb53d4
+          path: .dissemination-baseline
+          persist-credentials: false
+      - uses: actions/setup-dotnet@c2fa09f4bde5ebb9d1777cf28262a3eb3db3ced7 # v5
+        with:
+          global-json-file: global.json
+      - name: Build isolated binaries and run bounded merge-gate checks
+        shell: pwsh
+        run: ./.github/scripts/dissemination-compatibility.ps1
+      - name: Preserve test results and process diagnostics
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: dissemination-compatibility-results
+          retention-days: 14
+          path: |
+            Artifacts/DisseminationCompatibility/results
+            Artifacts/DisseminationCompatibility/*.binlog
+      - name: Preserve reproducible binary pair
+        if: success()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: dissemination-compatibility-binaries
+          retention-days: 7
+          path: Artifacts/DisseminationCompatibility/bin

docs/site/src/content/docs/host/monitoring/index.md

@@ -1,7 +1,7 @@
 ---
 title: Orleans observability
 description: Configure OpenTelemetry logging, metrics, and tracing for Orleans.
-ms.date: 08/02/2026
+ms.date: 09/04/2026
 ms.topic: overview
 ---
 
@@ -79,6 +79,7 @@ The example's 10% head-sampling ratio is a starting point, not a universal produ
 ## Next steps
 
 - [Monitor Orleans metrics](metrics.md)
+- [Monitor runtime dissemination](runtime-dissemination.md)
 - [Interpret Orleans signals](signals.md)
 - [Troubleshoot Orleans incidents](troubleshooting.md)
 - [Secure and operate the Orleans Dashboard](../../dashboard/index.md)

docs/site/src/content/docs/host/monitoring/metrics-catalog.md

@@ -1,7 +1,7 @@
 ---
 title: Orleans metrics catalog
 description: Complete reference for metrics emitted by the Microsoft.Orleans meter.
-ms.date: 08/18/2026
+ms.date: 09/04/2026
 ms.topic: reference
 ---
 
@@ -65,6 +65,29 @@ Request latency covers the interval until the caller's callback completes, inclu
 
 `Destination` and `silo` contain silo addresses and incarnations. They are useful during incident diagnosis and can create new time series during restarts.
 
+## Runtime dissemination
+
+| Instrument | Type | Unit | Attributes | Description |
+|---|---|---|---|---|
+| `orleans-dissemination-anti-entropy-digests` | C | `digests` | `direction` | Digest entries sent in successful outbound exchanges or received in inbound exchanges. |
+| `orleans-dissemination-anti-entropy-exchanges` | C | `operations` | `direction`, `truncated` | Successful anti-entropy requests and responses. `truncated=true` indicates that response budgets left candidates for a later exchange. |
+| `orleans-dissemination-anti-entropy-failures` | C | `operations` | `reason` | Outbound anti-entropy peer operations which ended in `timeout` or `error`. |
+| `orleans-dissemination-anti-entropy-values` | C | `values` | `direction` | Repair values returned by successful anti-entropy exchanges. |
+| `orleans-dissemination-broadcast-received` | C | `messages` | `namespace`, `kind` | Broadcast batches received, counted once for each namespace represented in the batch. |
+| `orleans-dissemination-broadcast-scheduled` | C | `schedules` | `reason` | Per-peer pump schedules split into `immediate` and `retry`. |
+| `orleans-dissemination-broadcast-send-failures` | C | `attempts` | `reason` | Broadcast send attempts which ended in `timeout` or `error`. |
+| `orleans-dissemination-broadcast-sent` | C | `messages` | `namespace`, `kind` | Successfully completed broadcast sends, counted once for each namespace represented in the batch. |
+| `orleans-dissemination-bytes-sent` | C | `bytes` | `namespace`, `kind` | Serialized dissemination payload bytes in successful broadcasts. |
+| `orleans-dissemination-payload-dropped` | C | `values` | `namespace`, `reason` | Values rejected by a payload guard. |
+| `orleans-dissemination-pump-failures` | C | `failures` | `status` | Unexpected peer-pump failures split into `recovered` and `permanent`. |
+| `orleans-dissemination-publications` | C | `operations` | `namespace`, `result`, `reason` | Publication attempts classified as `accepted` or `rejected`. Rejection reasons identify disabled namespaces, unavailable membership or values, invalid versions or repairs, and over-budget repairs. |
+| `orleans-dissemination-queue-admission-rejected` | C | `keys` | `namespace`, `reason` | New distinct keys rejected after a namespace reached its per-peer pending-key limit. |
+| `orleans-dissemination-values-applied` | C | `values` | `namespace`, `result` | Received values classified by the namespace apply result. |
+| `orleans-dissemination-values-received` | C | `values` | `namespace`, `kind` | Values included in received broadcast batches before individual application. |
+| `orleans-dissemination-values-sent` | C | `values` | `namespace`, `kind` | Values included in successfully completed broadcast sends. |
+
+All dissemination attributes have bounded runtime-defined values. Keys and peer addresses are available through opt-in diagnostic events instead of metric attributes. See [Monitor runtime dissemination](runtime-dissemination.md).
+
 ## Scheduling, activations, and grains
 
 | Instrument | Type | Unit | Attributes | Description |