If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnet/orleans shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnet/orleans repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnet/orleans.

What it runs against: a local clone of dotnet/orleans — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnet/orleans | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnet/orleans. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnet/orleans.git
#   cd orleans
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnet/orleans and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnet/orleans(\\.git)?\\b" \\
  && ok "origin remote is dotnet/orleans" \\
  || miss "origin remote is not dotnet/orleans (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Orleans.slnx" \\
  && ok "Orleans.slnx" \\
  || miss "missing critical file: Orleans.slnx"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "Directory.Packages.props" \\
  && ok "Directory.Packages.props" \\
  || miss "missing critical file: Directory.Packages.props"
test -f "global.json" \\
  && ok "global.json" \\
  || miss "missing critical file: global.json"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnet/orleans"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Orleans is a .NET framework that implements the Virtual Actor Model for building distributed, cloud-native applications. It abstracts away the complexity of distributed systems by treating grains (stateful actors with user-defined identities) as first-class programming constructs, enabling developers to write scalable, resilient cloud services using familiar C# syntax like async/await and try/catch. Large modular monorepo with Orleans.slnx as the master solution file. Core framework components are split across src/ directories (inferred from typical Orleans structure), test coverage via distributed-tests.yml and es-metadata.yml configurations, build automation through build.ps1/Build.cmd powershell scripts, and separate CI pipeline templates in .azure/pipelines/templates/ for reproducible builds.

.NET developers building cloud services, microservices, and distributed systems who want to avoid low-level distributed systems programming; teams migrating single-server .NET applications to cloud scale; enterprise architects needing a proven framework for highly-available cloud workloads.

Highly mature and production-ready. Created by Microsoft Research, this is a significant OSS project with 17.3MB of C# code across the codebase, comprehensive CI/CD in .azure/pipelines/ and .github/workflows/, automated testing infrastructure (Test.cmd, TestAll.cmd, Parallel-Tests.ps1), and active maintenance evidenced by nightly builds and dependabot configuration.

Low risk for established projects. The framework has been battle-tested in production at scale, maintains automated nightly builds, and uses modern security scanning (CodeQL, Guardian baseline configuration in .config/). Risk is primarily around major version upgrades which may introduce breaking changes to the grain interface contract model.

Active development with nightly builds configured (nightly-main.yaml), GitHub Actions workflows for CI (ci.yml), CodeQL security scanning (codeql.yml), API diff generation to track breaking changes (generate-api-diffs.yml), and dependabot automated dependency management (.azure/dependabot.yml, .github/dependabot.yml).

git clone https://github.com/dotnet/orleans.git && cd orleans && ..\Build.cmd (Windows) or powershell .\build.ps1 (cross-platform). Requires .NET SDK specified in global.json. Use Test.cmd to run the test suite locally.

Daily commands: Windows: .\Build.cmd then .\Test.cmd for basic tests or .\TestAll.cmd for comprehensive suite. Cross-platform: powershell .\build.ps1 then powershell .\Parallel-Tests.ps1 for parallel test execution. Dev container available in .devcontainer/devcontainer.json for isolated environment.

• Orleans.slnx — Solution file that defines the entire Orleans project structure and dependencies; essential for understanding the module organization and build order.
• Directory.Build.props — Central MSBuild properties file that enforces versioning, dependencies, and build settings across all 600 files in the repository.
• Directory.Packages.props — Centralized NuGet package version management; controls all transitive dependencies and is critical for maintaining consistency across the monorepo.
• global.json — Specifies the .NET SDK version and rollForward policy; every contributor must respect this to avoid environment drift.
• .github/workflows/ci.yml — GitHub Actions CI pipeline that runs on every PR; defines the acceptance criteria and build/test matrix all code must pass.
• CONTRIBUTING.md — Contributor guidelines covering code style, PR process, and community standards; foundational for successful collaboration.
• README.md — High-level Orleans framework overview and getting-started guide; provides context for understanding the distributed application model.

Add a new playground example demonstrating Orleans features

1. Create new directory under playground/ with the feature name (e.g., playground/MyFeature/) (playground/)
2. Create AppHost project with Program.cs that configures the Orleans cluster using the builder pattern (playground/ActivationRebalancing/ActivationRebalancing.AppHost/Program.cs)
3. Create a Cluster project that defines grain interfaces and implementations using Orleans abstractions (playground/ActivationRebalancing/ActivationRebalancing.Cluster/Program.cs)
4. Create Frontend project with Controllers (REST API) that interact with the cluster, following the pattern in StatsController (playground/ActivationRebalancing/ActivationRebalancing.Frontend/Controllers/StatsController.cs)
5. Add launchSettings.json for local development and appsettings files for configuration (playground/ActivationRebalancing/ActivationRebalancing.AppHost/Properties/launchSettings.json)

Modify build configuration or enforce new versioning policy

1. Update Directory.Build.props to apply properties globally across all projects (e.g., add LangVersion, Nullable, or custom metadata) (Directory.Build.props)
2. Update Directory.Packages.props if adding or pinning new NuGet dependencies across the monorepo (Directory.Packages.props)
3. Update the .editorconfig to enforce new code style rules that all contributors must follow (.editorconfig)
4. Update Orleans.slnx solution file if creating new projects that need to be part of the standard build (Orleans.slnx)
5. Update .github/workflows/ci.yml if the change requires new build steps or test matrices to be validated (.github/workflows/ci.yml)

Update CI/CD pipeline or testing requirements

1. Modify .github/workflows/ci.yml to add new test jobs, change build matrix, or update validation steps (.github/workflows/ci.yml)
2. Update .azure/pipelines/build.yaml if using Azure Pipelines as the primary CI system (.azure/pipelines/build.yaml)
3. Modify Test.cmd or TestAll.cmd scripts if new test categories or patterns need to be run locally or in CI (Test.cmd)
4. Update global.json if requiring a new .NET SDK version or changing the rollForward strategy (global.json)

Document a new feature or change contributing guidelines

1. Update README.md with feature overview, use cases, and getting-started examples (README.md)
2. Update CONTRIBUTING.md if the contribution workflow, code review process, or submission guidelines change (CONTRIBUTING.md)
3. Update .github/copilot-instructions.md if adding domain-specific guidelines for AI-assisted code generation (.github/copilot-instructions.md)
4. Update SUPPORT.md if new support channels or escalation procedures are established (SUPPORT.md)

• .NET / C# — Orleans is built on .NET to provide familiar OOP and async/await semantics for distributed computing; C# is the primary language.
• GitHub Actions + Azure Pipelines — Multi-platform CI/CD orchestration; GitHub Actions for public PR validation, Azure Pipelines for extended nightly and distributed testing.
• MSBuild / Central Package Management — Unified build system across 600 files; Directory.Build.props and Directory.Packages.props enforce consistent versioning and dependencies.
• NuGet — Package distribution and dependency management; Orleans core, extensions, and samples are delivered as NuGet packages.

• Monorepo structure (Orleans.slnx) with 600 files across multiple projects

  • Why: Allows coordinated development of tightly-coupled components (core, extensions, samples) with unified versioning and testing.
  • Consequence: Requires careful dependency management (Directory.Build.props) and longer CI runs; trade-off is simpler release coordination.

• Centralized MSBuild configuration (Directory.Build.props, Directory.Packages.props)

  • Why: Enforces consistency in code style, package versions, and build flags across all projects without per-project boilerplate.
  • Consequence: Changes to global policy affect all projects; requires careful review and testing before committing to main.

• Playground examples as full-featured applications (AppHost, Cluster, Frontend)

  • Why: Demonstrates real-world Orleans usage patterns and enables contributors to test features end-to-end locally.
  • Consequence: Increases repository size and maintenance burden; examples must stay synchronized with core API changes.

• Multi-CI strategy (GitHub Actions + Azure Pipelines)

  • Why: GitHub Actions for public visibility and PR checks; Azure Pipelines for internal nightly, distributed tests, and compliance scanning.
  • Consequence: Dual maintenance of pipeline definitions; inconsistencies between CI systems can mask issues.

• Does not provide a graphical IDE or development environment (relies on external tools like Visual Studio).
• Does not include authentication or authorization frameworks (expects integrations via middleware).
• Does not implement persistent storage directly (grains are transient; storage backends are pluggable).
• Not a real-time database or stream processing engine; Orleans is for actor-model distributed applications.
• Does not provide a production-ready DevOps dashboard (playgrounds demonstrate diagnostics APIs but not operational monitoring).

The build process requires .NET SDK version specified in global.json—using a different version will fail; TestAll.cmd spawns multiple test processes in parallel and may require significant system memory; grain state persistence depends on configured storage providers (SQL, Azure Table Storage, etc.) being available; the Virtual Actor Model has specific rules about grain identity mutability and lifecycle that aren't enforced by the type system and can cause subtle bugs if violated; breaking changes to grain interfaces can make existing deployments unable to communicate with new versions.

• Virtual Actor Model — The core programming model of Orleans—understanding this model is essential to design grain hierarchies, activation patterns, and understand lifecycle guarantees
• Grain Activation & Deactivation — Orleans automatically manages grain instantiation and memory cleanup; understanding activation lifecycle is critical for correct state management and resource utilization
• Turn-based Concurrency — Orleans executes grain methods serially within a single logical thread per grain instance, eliminating race conditions; this is non-obvious and requires different thinking than traditional async code
• Grain State Persistence — Grains are stateful entities requiring pluggable storage backends; understanding the state read/write contract prevents data loss and consistency issues
• Orleans Silos & Clusters — Orleans runtime runs in 'silos' that form clusters; understanding silo lifecycle, cluster membership, and gossip protocols is essential for deployment and debugging
• Grain Interface Versioning — The API diff generation (generate-api-diffs.yml) indicates this is tracked carefully—breaking grain interface changes require careful migration strategies in distributed deployments
• Observable State Pattern — Orleans uses strongly-typed grain interfaces and state classes to ensure compile-time safety; understanding how state flows through grain methods prevents runtime surprises

• dapr/dapr — Alternative distributed application runtime with similar goals (simplifying distributed systems) but using sidecar architecture instead of in-process actors
• akka/akka.net — Competing .NET actor framework implementing Akka model; shares Virtual Actor Model philosophy but with different API and runtime semantics
• dotnet/aspnetcore — Companion framework for building web frontends and APIs that communicate with Orleans grain clusters
• Azure/azure-sdk-for-net — Required for Orleans integration with Azure services (Event Hubs, Table Storage, Blob Storage) used for persistence and messaging
• microsoft/research — Original research publication source for the Virtual Actor Model and Orleans' foundational concepts

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add distributed integration tests workflow for playground examples

The repo has a new ActivationRebalancing playground example with AppHost, Cluster, and Frontend components, but there's no dedicated GitHub Actions workflow to validate that these interconnected services start and communicate correctly. Currently, ci.yml and nightly-main.yaml don't specifically test playground scenarios. This would catch regressions in the cluster formation, grain activation, and frontend integration early.

• [ ] Create .github/workflows/playground-integration-tests.yml
• [ ] Add steps to build playground/ActivationRebalancing.AppHost, Cluster, and Frontend projects
• [ ] Implement health check logic to verify all three services start and can communicate
• [ ] Add workflow triggers for pushes to playground/* paths and nightly builds
• [ ] Document in CONTRIBUTING.md how to run playground tests locally using the new workflow pattern

Implement CodeQL configuration enhancements for grain serialization security

Orleans is heavily focused on distributed actor grain patterns and serialization (.NET remoting). The .github/codeql.yml exists but is likely minimal. Given the security-critical nature of serialization in a framework handling cross-process/cross-network grain calls, there's an opportunity to add custom CodeQL queries targeting unsafe serialization patterns, grain method signature validation, and activation lifecycle issues specific to Orleans.

• [ ] Review current .github/workflows/codeql.yml configuration
• [ ] Create .github/codeql/custom-queries/ directory with Orleans-specific QL queries
• [ ] Add queries to detect: unsafe BinaryFormatter usage in grain implementations, missing cancellation token handling in long-running grain methods, improper grain state serialization
• [ ] Update .config/guardian/.gdnbaselines to include new query results
• [ ] Document in CONTRIBUTING.md: 'Security scanning for grain serialization' section

Add comprehensive Dependabot-managed transitive dependency analysis documentation

The repo has both .azuredevops/dependabot.yml and .github/dependabot.yml configured, but there's no DEPENDABOT.md or section in CONTRIBUTING.md explaining the dependency update strategy, how to handle security alerts across Orleans' complex multi-project structure (core, clustering, persistence, streaming), and resolution guidelines for grain-serialization-breaking changes. This would reduce friction for contributors dealing with dependency conflicts.

• [ ] Create docs/DEPENDABOT_MANAGEMENT.md with dependency update triage process
• [ ] Document the difference in strategies between .azuredevops and .github dependabot configs
• [ ] Add guidelines for testing transitive updates in distributed test scenarios (using distributed-tests.yml pattern)
• [ ] Create a checklist template for PRs that update core Orleans dependencies (in .github/PULL_REQUEST_TEMPLATE.md)
• [ ] Link from CONTRIBUTING.md to the new Dependabot guide

• Add XML documentation comments to public grain interfaces in src/ that currently lack them, focusing on async method contracts and state management patterns
• Create integration tests demonstrating grain state recovery after failure using the storage backends configured in the pipeline (SQL/PostgreSQL), filling gaps in es-metadata.yml coverage
• Improve CI/CD logging by enhancing .azure/pipelines/templates/vars.yaml to expose build telemetry and add diagnostic output to Build.cmd for developers debugging failed local builds

• Medium · Potential Hardcoded Configuration in appsettings Files — playground/ActivationRebalancing/ActivationRebalancing.AppHost/appsettings.json, playground/ActivationRebalancing/ActivationRebalancing.AppHost/appsettings.Development.json, playground/ActivationRebalancing/ActivationRebalancing.Frontend/appsettings.json, playground/ActivationRebalancing/ActivationRebalancing.Frontend/appsettings.Development.json, playground/ActivationRepartitioning/ActivationRepartitioning.AppHost/appsettings.json, playground/ActivationRepartitioning/ActivationRepartitioning.AppHost/appsettings.Development.json, playground/ActivationRepartitioning/ActivationRepartitioning.Frontend/appsettings.Development.json. Multiple appsettings.json and appsettings.Development.json files are present in the playground projects. These files may contain sensitive configuration data, database connection strings, or API keys that could be accidentally committed to the repository. Fix: Ensure appsettings.Development.json and appsettings.*.json files are in .gitignore. Use user secrets for local development and environment variables for production configuration. Review all appsettings files to ensure no credentials, API keys, or sensitive connection strings are hardcoded.
• Medium · Missing Security Headers Configuration — playground/ActivationRebalancing/ActivationRebalancing.Frontend/Program.cs, playground/ActivationRepartitioning/ActivationRepartitioning.Frontend/Program.cs. Frontend applications (ActivationRebalancing.Frontend, ActivationRepartitioning.Frontend) are present but there is no evidence of security header configuration (HSTS, CSP, X-Frame-Options, etc.) in the visible file structure. This could leave the application vulnerable to various attacks. Fix: Configure security headers in the Program.cs or middleware. Add HSTS, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and other security headers. Use .NET middleware like app.UseHsts(), app.UseXContentTypeOptions(), and custom middleware for CSP.
• Medium · Dependency Vulnerabilities Not Visible — Directory.Packages.props, *.csproj files throughout the repository. No package dependency files (*.csproj, packages.config, Directory.Packages.props content) were provided in the analysis. Orleans and its dependencies may contain known vulnerabilities that cannot be assessed. Fix: Run regular dependency vulnerability scans using: dotnet list package --vulnerable, enable Dependabot alerts (already configured in .azuredevops/dependabot.yml), and use OWASP Dependency-Check. Keep all NuGet packages updated to latest secure versions.
• Low · Development Configuration Exposed — playground/ActivationRebalancing/ActivationRebalancing.AppHost/Properties/launchSettings.json, playground/ActivationRebalancing/ActivationRebalancing.Frontend/Properties/launchSettings.json, playground/ActivationRepartitioning/ActivationRepartitioning.AppHost/Properties/launchSettings.json, playground/ActivationRepartitioning/ActivationRepartitioning.Frontend/Properties/launchSettings.json. LaunchSettings.json files contain development configuration that could expose sensitive information about the application structure and ports. Fix: Ensure launchSettings.json is included in .gitignore and not committed to the repository. Review contents to ensure no sensitive configuration is included. These should be local-only files.
• Low · No Visible Authentication/Authorization Configuration — playground/ActivationRebalancing/ActivationRebalancing.Frontend/Controllers/StatsController.cs. The file structure does not show explicit authentication or authorization configuration in the visible files. Controllers and gRPC services may be vulnerable to unauthorized access. Fix: Implement authentication (e.g., JWT, OAuth2) and authorization policies. Apply [Authorize] attributes to controllers and methods. Use middleware to enforce authentication on sensitive endpoints. Implement role-based access control (RBAC) or claims-based authorization.
• Low · Client-Side Code in Frontend May Have XSS Vulnerabilities — undefined. Frontend applications include JavaScript files (worker.js, index.html) that could potentially be vulnerable to XSS attacks if user input is not properly sanitized. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.