{"owner":"dotnet","repo":"orleans","hasSkills":true,"totalSkillsCount":8,"totalTokensCount":5969,"categories":["root-instruction","plugin-manifest","copilot-instructions","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["test/AGENTS.md","docs/tools/PackageJsonGenerator/README.md","samples/AGENTS.md","test/Extensions/Google/Emulators/README.md","docs/AGENTS.md",".github/copilot-instructions.md","test/Extensions/Google/Emulators/firebase.json","AGENTS.md"],"skills":{"test/AGENTS.md":"# Orleans testing guidance\n\nThese rules apply recursively to tests under `test/`. The repository-level\nimplementation principles also apply.\n\n## Test design\n\n- Model-based tests compare implementation behavior with contracts across operation\n sequences, including relevant concurrency and failures.\n- Property-based failures must be reproducible, with effective shrinking.\n- Keep snapshots deterministic and focused; inspect baseline changes for intended\n semantics.\n\n## Reliability\n\n- Isolate mutable fixture state between tests, including clocks, clusters, topology,\n storage, and background tasks.\n- Give one orchestrator sole ownership of fake-time advancement; workers request\n or await progress.\n- Use `FakeTimeProvider` for grain-facing time, keyed `TimeProviderNames` for\n subsystem clocks, and `TimeProviderTestingExtensions.UseTimeProviderForBackgroundAreas`\n for unrelated real-time work (`src/Orleans.TestingHost/TimeProviderTestingExtensions.cs`).\n For timer-schedule synchronization, follow `TrackingFakeTimeProvider` in\n `test/Orleans.DefaultCluster.Tests/FakeTimeSilo.cs`.\n- Replace sleeps and polling with explicit phase barriers: wait for ownership and readiness, arm observers or synchronization primitives, perform one action or time advance, then await completion.\n- Use exact assertions with controlled time and synchronization; fix nondeterminism\n instead of widening expected ranges.\n- Observe lifecycle transitions with `DiagnosticListener` and `DiagnosticEventCollector`\n (`src/Orleans.TestingHost/Diagnostics/DiagnosticEventCollector.cs`); see\n `test/Orleans.GrainDirectory.Tests/GrainDirectory/GrainDirectoryLeaseTests.cs`.\n For in-process synchronization, use `InProcessTestCluster.TryGetGrainContext`\n where appropriate; preserve production behavior.\n- Arm and materialize waits before triggering the event. Materialize lazy `IEnumerable` sequences so subscriptions exist before the action occurs.\n- Stress the complete shared-fixture class or suite in its relevant test order, not only an isolated test. Test every supported target framework when runtime behavior can differ.\n- Diagnose timeouts by the missing transition or event. Include phase, entity ID,\n expected/actual state, ownership, and armed schedules.\n- Verify the patch itself. Do not rely on unrelated CI runs from branches that do not contain the change.\n","docs/tools/PackageJsonGenerator/README.md":"# PackageJsonGenerator\n\nGenerates deterministic per-package JSON describing the public .NET API in an Orleans assembly. The schema matches the package API data consumed by the `microsoft/aspire.dev` Astro site.\n\nUse `docs/scripts/Generate-ApiData.ps1` from the repository root to discover and build the packable Orleans projects, assemble each project's reference closure, and generate the complete package data set.\n\n```powershell\npwsh ./docs/scripts/Generate-ApiData.ps1\n```\n\nThe default output is `docs/site/src/data/pkgs`. Pass `-OutputDirectory` to generate into a staging directory, `-TargetFramework` to select another supported TFM, or `-SkipBuild` when all selected package projects have already been built.\n\nProjects are discovered from `src/**/*.csproj` using evaluated MSBuild properties. A project is included when it targets the selected framework and has both `IsPackable=true` and `IncludeBuildOutput=true`. This excludes test projects, implementation-only projects, analyzers, code generators, and assembly-free meta-packages without maintaining a package list.\n\nEach output file is named `{PackageId}.{PackageVersion}.json`. Only public types and members declared by that package assembly are emitted; project, package, and framework dependencies are resolution-only Roslyn references. Portable PDB paths are resolved against the verified local repository tree and a tracked-file allowlist from the advertised commit, avoiding network-dependent output and broken generated/inferred links. The script validates XML documentation, package metadata, source repository/commit information, and duplicate type identities before removing stale generator-owned JSON files.\n\nAPI selection uses `GeneratedCodeAttribute` and `CompilerGeneratedAttribute` to filter implementation types and members, including nested types and enum members. Authored partial types retain their API entries when generated members carry these attributes individually.\n\nBy default, source links target the latest commit which changed `src`. Generation fails when `src` has uncommitted changes. Automation can pass `-SourceCommit` to select an explicit full commit SHA.\n\n## Upstream attribution\n\nThis tool is adapted from [`microsoft/aspire.dev`'s `PackageJsonGenerator`](https://github.com/microsoft/aspire.dev/tree/9aa68083af47da79b63bc15b80f44c1927bf9c08/src/tools/PackageJsonGenerator) at commit `9aa68083af47da79b63bc15b80f44c1927bf9c08`.\n\nThe adapted source retains the upstream .NET Foundation and MIT license headers. Orleans-specific changes cover repository URL normalization, relevant Orleans attributes, project/package discovery, and local build orchestration.\n","samples/AGENTS.md":"# Orleans samples guidance\n\nThese rules apply recursively to everything under `samples/`. The repository-level guidance also applies.\n\n## Orchestration\n\n- Use [Aspire](https://aspire.dev) app hosts for new or reworked multi-process\n samples and external dependencies. Model dependencies as resources with local\n emulators or containers; use `aspire run` rather than manual setup scripts.\n- Wire Orleans through `Aspire.Hosting.Orleans`: `builder.AddOrleans(\"default\")`, then `WithClustering(...)`, `WithGrainStorage(...)`, and so on, and give service projects a `WithReference(orleans)`. See `JournaledTodoList` for the canonical layout and `JournalingAzureBlobJson` for a single-service one.\n- Name the app host project `.AppHost`, set `IsAspireHost`, and reference the `Aspire.AppHost.Sdk`. Add a `.ServiceDefaults` project when the sample has more than one service, and call `AddServiceDefaults()` from each service.\n- Use `WaitFor(...)` for resources a service needs at startup, and `WithExternalHttpEndpoints()` for endpoints the user opens in a browser.\n- Self-contained samples such as single-process `UseLocalhostClustering()` consoles\n can run without an app host.\n- Samples that exist to demonstrate a specific deployment target, such as those under `Deployment/`, keep the infrastructure assets that target requires.\n\n## Projects\n\n- Every sample project targets `net10.0` and is non-packable.\n- Keep each sample copyable and independently buildable. Reference Orleans through\n `Microsoft.Orleans.*` NuGet packages; project references stay within the sample.\n- `Build-Samples.ps1` packs `Orleans.slnx` with a unique prerelease version and builds\n `Samples.slnx` against those packages.\n- Each sample owns a `Directory.Packages.props` with versions for every dependency.\n The root samples file declares none; NuGet reads only the nearest file. Shared\n samples such as `Streaming/Common` use their shared parent as the copy-out unit.\n- `PackageReference` elements must not carry `Version` or `VersionOverride`. Keep a package pinned to the same version across all samples, keep Aspire hosting and component versions aligned, and pin vulnerable transitive dependencies explicitly since `CentralPackageTransitivePinningEnabled` is on.\n- Follow `.editorconfig`; keep idiomatic teaching code and comments focused on the\n Orleans concept being demonstrated.\n\n## Registration and documentation\n\n- `samples/Samples.slnx` must contain exactly the projects under `samples/`, grouped in a folder per sample. Add every new project, including app hosts and service defaults.\n- Add new samples to `gallery.json` following an existing entry and the schema in\n `Validate-Samples.ps1`. Tag Aspire-orchestrated samples with `aspire`.\n- `samples/README.md` is generated. Run `pwsh ./samples/Update-Readme.ps1` after changing `gallery.json`; never hand-edit it.\n- Give each sample a `README.md` explaining what it demonstrates and how to run it. Imported samples keep their existing front matter and their original source repository and license.\n\n## Validation\n\n- Run `pwsh ./samples/Validate-Samples.ps1` for any change under `samples/`. It checks the gallery manifest, README freshness, solution membership, package version declarations, sample self-containment, and invokes `Build-Samples.ps1` to build all samples against locally packed Orleans packages.\n- For instruction-only edits, use `-NoBuild`.\n- Verify a new or changed sample still builds standalone: copy its folder outside the repository and run `dotnet build`. A sample using an Orleans package which has not been published yet is exempt until that package ships; the in-tree solution still builds it from the local package source.\n- Building a sample must not require cloud credentials. Only running a sample may.\n- Check `git diff --check` before committing.\n","test/Extensions/Google/Emulators/README.md":"# Google Cloud emulators\n\nFirebase does not publish an official Emulator Suite container. Use the official Firebase CLI package instead.\n\nInstall Java 21 and Firebase CLI version 15.24.0:\n\n```shell\nnpm install --global firebase-tools@15.24.0\n```\n\nFrom this directory, start the configured emulators:\n\n```shell\nfirebase emulators:start --only firestore,pubsub,storage --project orleans-test\n```\n","docs/AGENTS.md":"# Orleans documentation guidance\n\nThese rules apply recursively to documentation, snippets, and samples under\n`docs/`. The repository-level guidance also applies.\n\n## Code examples\n\n- Put every C# example in a `snippets` project and include it with a named `:::code`\n region. Add hidden declarations outside the region when a displayed fragment\n needs context; don't use inline C# fences.\n- Keep snippets minimal, current, and self-contained, including declarations\n required by the displayed region.\n- Compile every affected snippet project. Don't publish pseudo-code as if it were a copyable example.\n- Documentation and snippet projects target `net10.0`.\n- Every `Microsoft.Orleans.*` package reference must use the approved version `10.2.2`. Keep the Orleans package family aligned and centralize versions where the project structure supports it.\n- Use an older Orleans package only for a narrow migration example whose purpose\n requires that version. Keep it under `migration` and document the reason in\n `OrleansDocumentationVersionException` in that project.\n- Keep direct dependency versions at or above the minimums required by the selected Orleans packages.\n- Don't demonstrate an unreleased API using an older package that doesn't contain it. Link to its API reference until a compilable source- or package-based example is available.\n\n## Links\n\n- Orleans documentation links should be relative so they work under `https://dotnet.github.io/orleans`.\n- Use fully qualified, locale-neutral canonical external links, such as `https://learn.microsoft.com/azure/...`.\n- Don't carry migrated repository `.md` suffixes into published links.\n- Verify newly added or changed external links and run the documentation site's link validation.\n\n## API references\n\n- Link public .NET symbols to generated API documentation using DocFX xref syntax instead of formatting the symbol only as inline code.\n- Use `` for types and `` for members or overload groups.\n- Add `?displayProperty=nameWithType` when the fully qualified display name improves clarity.\n- Use inline code for literals, configuration values, CLI commands, filenames,\n provider names, and syntax that isn't a linkable public symbol. Avoid\n repeatedly linking a symbol when an earlier contextual link is clearer.\n- Confirm the xref target exists in the generated API surface before publishing.\n\nExamples:\n\n```markdown\nUse for persistent grain state.\n\nConfigure it with .\n```\n\n## Documentation types\n\nAddress relevant operational concerns: correctness, security, availability,\nupgrades, capacity, cost, and diagnosis under load.\n\n- **Architecture**: components, protocols, invariants, consistency, failure and\n concurrency semantics, and design trade-offs under scale and version skew.\n- **How-to/cookbook**: one task, with prerequisites, pitfalls, and verification.\n- **Tutorial**: a working start-to-finish learning path.\n- **Conceptual**: the mental model, suitability, trade-offs, and verified constraints.\n- **API reference**: semantics, thread-safety, lifetime, exceptions, defaults, and examples.\n- **FAQ/troubleshooting**: observed symptoms, causes, remedies, and prevention.\n\nPlace updates in the appropriate category and cross-link rather than mix purposes.\n\n## Content\n\n- Keep ordinary conceptual and how-to documentation timeless. Name Orleans releases only in migration or upgrade guidance where the release boundary matters.\n- Describe implemented behavior and verified constraints: relevant triggers,\n runtime actions, outcomes, and operator responses. Attribute responsibilities to\n the mechanism that performs them.\n- Preserve useful content and authoritative references; update affected contracts\n and behavior. Remove obsolete or redundant material.\n- Treat hub pages as overviews: link to peer detail pages instead of singling out one provider or feature for inline configuration guidance.\n- Preserve stable URLs and anchors when moving content, or provide an explicit redirect or compatibility anchor.\n\n## Sources and generated output\n\n- Register every new page in `docs/site/src/content/docs/toc.yml` under the\n section that matches its documentation type. A compatibility page retained\n only for stable inbound routes can set `navigation: hidden`; link it to the\n current focused pages.\n- Keep recursive includes within the documentation source tree. Missing,\n circular, traversal, absolute, drive-relative, or symlink-escaping includes\n are invalid. Edit the include source and ensure active includes participate in\n link validation.\n- Don't hand-edit generated site output, generated API data, dependency folders,\n or build output such as generated `.mdx` siblings, `dist`, `node_modules`,\n `bin`, or `obj`.\n\n## Validation\n\n- Run the parser-backed link, include, redirect, navigation, and project-policy\n checks that cover the changed content.\n- Run `docs/site/src/content/docs/validate-snippets.ps1` for changed snippets\n and snippet project policy changes. It builds ordinary snippet projects and\n runs projects marked with `IsTestProject=true`, so executable testing examples\n are validated behaviorally.\n- Run `samples/Validate-Samples.ps1` when samples change.\n- When `docs/Docs.slnx` is present after integration, build it as the aggregate documentation project.\n- From `docs/site`, run `npm run validate`, including redirect and rendered\n output auditing.\n- Check `git diff --check` before committing.\n",".github/copilot-instructions.md":"## Implementation and code review\n\nFollow root `AGENTS.md` and applicable directory instructions for implementation principles and repository workflow.\n\nFor code review, use `.github/skills/code-review/SKILL.md`.\n\n## Build, test, and style commands\n\n* The repo builds with the .NET SDK from `global.json` (`10.0.400`, roll-forward `major`). Do not edit `global.json` unless explicitly asked.\n* Build the solution with `dotnet build Orleans.slnx -bl`. CI uses this form and uploads the binlog.\n* On Windows, `.\\Build.cmd` runs `build.ps1`, which restores, builds, and packs `Orleans.slnx`, writes restore/build/pack binlogs, and outputs packages under `Artifacts\\`. Set `BuildConfiguration=Release` to build release artifacts.\n* Run tests with `dotnet test --solution Orleans.slnx --framework net10.0 --minimum-expected-tests 1 --max-parallel-test-modules 1`. CI also runs `net8.0`; source projects default to `net8.0;net10.0`.\n* Run a category with `dotnet test --solution Orleans.slnx --framework net10.0 --filter-trait \"Category=BVT\" --minimum-expected-tests 1 --max-parallel-test-modules 1`. Common categories are `BVT`, `SlowBVT`, `Functional`, and provider-specific categories such as `Redis`, `Cassandra`, `SqlServer`, `Azure`, `AWS`, and `Streaming`.\n* Run one test with `dotnet test --project test\\Orleans.Core.Tests\\Orleans.Core.Tests.csproj --framework net10.0 --filter-class \"*MyTestClass*\" --filter-method \"*MyTestMethod*\" --minimum-expected-tests 1`.\n* `.\\Test.cmd` runs the scripted Windows test subset using the default xUnit query filter `/[(Category=BVT)|(Category=SlowBVT)]`. `.\\TestAll.cmd` adds the `Functional` category.\n* Provider tests often need external services, connection-string environment variables, or secrets. Match `.github\\workflows\\ci.yml` and `test\\TestInfrastructure\\TestExtensions\\TestDefaultConfiguration.cs` for the required setup.\n* Style is enforced by `dotnet build` because `Directory.Build.props` sets `EnforceCodeStyleInBuild=true` and `TreatWarningsAsErrors=true`.\n\n## High-level architecture\n\n* Orleans is a virtual actor framework. User code defines grain interfaces (`IGrainWithStringKey`, `IGrainWithGuidKey`, etc.) and grain classes; the runtime activates, places, deactivates, persists, and routes calls to grains across silos.\n* `src\\Orleans.Core.Abstractions` contains the public programming model: grain interfaces, grain references, attributes, and shared abstractions used by both clients and silos.\n* `src\\Orleans.Serialization.Abstractions` and `src\\Orleans.Serialization` provide the version-tolerant serializer, serialization attributes, runtime serialization services, and source-generator integration. Additional serializer packages live under `src\\Orleans.Serialization.*` and `src\\Serializers`.\n* `src\\Orleans.Core` contains shared client/server runtime infrastructure such as messaging, hosting integration, configuration, and serialization integration.\n* `src\\Orleans.Runtime` is the silo implementation: activation lifecycle, placement, cluster membership, reminders, runtime services, and grain execution.\n* `src\\Orleans.Sdk`, `src\\Orleans.Client`, and `src\\Orleans.Server` are packaging/metapackage projects. The SDK brings in core packages plus analyzers/code generation; the client/server packages compose the SDK with client or silo dependencies.\n* Provider packages are intentionally split by backend and capability under `src\\Azure`, `src\\AWS`, `src\\AdoNet`, `src\\Cassandra`, `src\\Redis`, and related top-level provider directories. They usually expose builder extensions in `Orleans.Hosting` and options in `Orleans.Configuration`.\n* Tests mirror runtime areas under `test\\`. Shared test infrastructure is in `test\\TestInfrastructure\\TestExtensions`, test grains and grain interfaces are under `test\\Grains`, and `Orleans.TestingHost`/`TestClusterBuilder` are the primary integration-test harnesses.\n* `src\\api` contains generated public API surfaces. Follow the regeneration and package compatibility commands in root `AGENTS.md`.\n\n## Key conventions\n\n* Central package management is enabled in `Directory.Packages.props`; add or update package versions there instead of putting versions in individual projects.\n* Use project references for repo-internal dependencies. `CONTRIBUTING.md` explicitly discourages DLL references and unnecessary `Private=True` metadata.\n* `src\\Directory.Build.props` makes source projects packable by default; `test\\Directory.Build.props` makes test projects non-packable and configures MTP test applications. The root `Directory.Build.targets` copies `test\\testconfig.json` under each test assembly name.\n* Build-time code generation is controlled by `OrleansBuildTimeCodeGen=true`, which imports the Orleans code generator and analyzers as build analyzers for framework projects.\n* Serializable Orleans types that cross grain calls, storage, or streams generally need `[GenerateSerializer]` plus stable `[Id(n)]` members. Do not renumber existing serialization IDs.\n* Tests use xUnit with the custom `[TestCategory(\"...\")]` attribute from `test\\TestInfrastructure\\TestExtensions\\TestCategory.cs`; this maps categories to xUnit traits for `dotnet test --filter-trait \"Category=...\"`.\n* Cluster tests usually derive from or compose fixtures in `test\\TestInfrastructure\\TestExtensions` and configure silos through `TestClusterBuilder`, `ISiloConfigurator`, or `ISiloBuilder`. The default cluster fixture uses in-memory reminders, durable jobs, and grain storage.\n* Follow `.editorconfig`: C# uses file-scoped namespaces, system directives first, `var` preferences, braces on new lines, `_camelCase` private fields, and preview language features. Nullable is enabled for source projects and disabled for test projects.\n* Add XML docs for new or changed public APIs even though CS1591 is currently suppressed; package projects generate documentation files.\n","test/Extensions/Google/Emulators/firebase.json":"{\n \"emulators\": {\n \"firestore\": {\n \"port\": 8080\n },\n \"pubsub\": {\n \"port\": 8085\n },\n \"storage\": {\n \"port\": 9199\n },\n \"ui\": {\n \"enabled\": true,\n \"port\": 9000\n },\n \"singleProjectMode\": false\n },\n \"storage\": {\n \"rules\": \"storage.rules\"\n }\n}","AGENTS.md":"# Implementation principles\n\nApply these principles during design, implementation, and validation, alongside\ncorrectness, security, compatibility, concurrency, and reliability.\n\n## Priorities\n\n- Rank goals as correctness (including safety) > simplicity > performance >\n convenience; seek a design that serves all of them before trading one away.\n- Safety (no corruption, data loss, broken invariants, or security violations)\n precedes liveness.\n- Ask the maintainer (in reviews, raise a question) before relying on an invariant\n that is not yet established, changing a surface that may have shipped or been\n persisted, or adding a dependency.\n\n## Approach\n\n- **Essence over accident.** The hard part is the spec and the conceptual model;\n code is its representation. Spend effort there.\n- **KISS.** Simplicity is the hardest revision, not the first draft. Iterate until\n the design is obviously right.\n- **YAGNI.** Build for today's requirements. \"If in doubt, leave it out.\"\n- **Grow, don't build.** Keep a running end-to-end skeleton; add function\n incrementally.\n- **Zero debt in what ships.** Fewer features, each solid. Fix showstoppers when\n found.\n- **Always say why.** Every non-obvious decision carries its rationale (comment,\n commit message, PR).\n\n## Layering, contracts, and invariants\n\n- Establish each layer's required and provided guarantees. Keep responsibilities\n and invariant enforcement in their owning layer; preserve contracts across\n callers, overrides, concurrency, failures, and lifecycle transitions.\n- Document non-obvious or changed contracts near the code in comments or XML API\n docs; use architecture documentation for broader design context.\n- Use side-effect-free assertions at API boundaries for caller preconditions and\n internal invariants. Prefer debug-time assertions (`Debug.Assert`) for product\n programming errors where contracts are established or maintained. Exercise\n assertion-enabled code in CI and surface assertion failures as test failures.\n Preserve required behavior and external-input validation when assertions are compiled out.\n- Within established contracts, rely on proven guarantees rather than adding\n redundant assertions or checks. Avoid unnecessary fallback state, retries, or catches.\n Validate external inputs and handle realistic failures with explicit error reporting.\n- Seek additional invariants that simplify code. Establish their feasibility,\n owning layer, and enforcement cost, then enforce and document them before use.\n\n## Clean, minimal implementations\n\n- Make the smallest complete change; reuse patterns and helpers. Keep unrelated\n refactoring and formatting out of scope.\n- Add abstractions, inheritance, virtual dispatch, options, fields, properties,\n caches, and states only for concrete requirements or boundaries. Derive values\n from existing state when correctness and efficiency permit.\n\n## Runtime performance\n\n- Assess CPU, throughput, latency, and scalability under relevant workloads,\n including algorithmic complexity, repeated work, I/O, contention, and scheduling.\n- Prioritize low allocation and retained-memory costs. Minimize copies, object sizes\n (including alignment), and retained graphs, especially per grain, activation, or\n message. Account for count and lifetime; justify optimizations by net benefit,\n ownership safety, and complexity. Support quantitative claims with evidence.\n\n## Testing and documentation\n\n- Assert observable outcomes and contracts across relevant boundaries, failures,\n and transitions. Use Accordant model-based tests, CsCheck property-based tests,\n Verify for xUnit snapshots (`Verify.XunitV3`), or unit/integration tests as\n appropriate. Reuse test infrastructure; follow `test/AGENTS.md` under `test/`.\n- Aim for greater than 80% CI code coverage. Consult the automated PR coverage\n comment for affected-code gaps and regressions; state when results are unavailable.\n Use behavioral assertions to establish guarantees.\n- Match documentation to affected behavior, audience, and document type. Update\n READMEs only for highly relevant end-user setup, usage, or public behavior.\n Describe affirmative behavior and outcomes.\n- For reviews, use `.github/skills/code-review/SKILL.md`.\n\n# Repository workflow\n\n- **New pull requests:** branch from `dotnet/orleans`'s `main`, push to the authenticated user's fork, and open the PR against `dotnet/orleans`.\n- **Existing contributor pull requests:** when maintainer edits are enabled and authentication permits, push updates to the PR author's head fork and branch.\n- **Every push:** run `git remote -v` and verify the destination by URL. Use the authenticated user's fork for new work or the PR author's fork for an existing PR; never rely on remote names or hard-code `origin`.\n- Never push a feature branch to a remote whose URL points to `github.com/dotnet/orleans`, over HTTPS or SSH. Delete it immediately if this happens accidentally.\n- After rebasing a PR branch, use `--force-with-lease`, never `--force`.\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commits and PR titles. Update nonconforming PR titles during review.\n- Keep PR descriptions focused on the problem, solution, and rationale; omit test-command sections.\n\n# Package compatibility\n\n- Packable source projects validate their produced packages against the released baseline configured in `src/Directory.Build.props`. Treat `CP*` and `PKV*` failures as compatibility findings, not warnings to disable globally.\n- When a public API break is intentional, first run the affected project's normal Release pack to capture the compatibility failure:\n `dotnet pack --configuration Release`.\n- Regenerate that project's suppression file with:\n `dotnet pack --configuration Release /p:GenerateCompatibilitySuppressionFile=true`.\n- Review the generated `CompatibilitySuppressions.xml` beside the project. Retain only entries which describe the approved break, keep the suppression scoped to the affected package and API, and commit it with the breaking change.\n- Run the normal Release pack again without `GenerateCompatibilitySuppressionFile` and require it to pass. Do not resolve compatibility failures by disabling package validation or adding `CP*`/`PKV*` diagnostics to `NoWarn`.\n- For an intentional target-framework removal, add a package-specific `PackageValidationBaselineFrameworkToIgnore` item instead of an API suppression.\n- After a release containing the break becomes the configured baseline, regenerate or remove the suppression file so obsolete entries do not accumulate.\n\n# Generated API surfaces\n\n- Files under `src/api` are generated public API surfaces. Do not edit them manually.\n- After changing public API in a packable source project, regenerate that project's API file using the same restore configuration and GenAPI target as CI:\n `dotnet restore --configfile .github/NuGet.GenAPI.Config -p:GenerateOrleansApiSource=true`,\n then `dotnet build --framework net8.0 --configuration Release --no-incremental --no-restore -p:GenerateOrleansApiSource=true /t:\"Build;GenAPIGenerateReferenceAssemblySource\"`.\n- Review and commit the generated `src/api` change with the implementation. The `GenerateOrleansApiSource` property activates the GenAPI package, and the dedicated NuGet config maps that package to its public transport feed; ordinary restores use only the repository's CFS source.\n"},"files":{"test/AGENTS.md":"# Orleans testing guidance\n\nThese rules apply recursively to tests under `test/`. The repository-level\nimplementation principles also apply.\n\n## Test design\n\n- Model-based tests compare implementation behavior with contracts across operation\n sequences, including relevant concurrency and failures.\n- Property-based failures must be reproducible, with effective shrinking.\n- Keep snapshots deterministic and focused; inspect baseline changes for intended\n semantics.\n\n## Reliability\n\n- Isolate mutable fixture state between tests, including clocks, clusters, topology,\n storage, and background tasks.\n- Give one orchestrator sole ownership of fake-time advancement; workers request\n or await progress.\n- Use `FakeTimeProvider` for grain-facing time, keyed `TimeProviderNames` for\n subsystem clocks, and `TimeProviderTestingExtensions.UseTimeProviderForBackgroundAreas`\n for unrelated real-time work (`src/Orleans.TestingHost/TimeProviderTestingExtensions.cs`).\n For timer-schedule synchronization, follow `TrackingFakeTimeProvider` in\n `test/Orleans.DefaultCluster.Tests/FakeTimeSilo.cs`.\n- Replace sleeps and polling with explicit phase barriers: wait for ownership and readiness, arm observers or synchronization primitives, perform one action or time advance, then await completion.\n- Use exact assertions with controlled time and synchronization; fix nondeterminism\n instead of widening expected ranges.\n- Observe lifecycle transitions with `DiagnosticListener` and `DiagnosticEventCollector`\n (`src/Orleans.TestingHost/Diagnostics/DiagnosticEventCollector.cs`); see\n `test/Orleans.GrainDirectory.Tests/GrainDirectory/GrainDirectoryLeaseTests.cs`.\n For in-process synchronization, use `InProcessTestCluster.TryGetGrainContext`\n where appropriate; preserve production behavior.\n- Arm and materialize waits before triggering the event. Materialize lazy `IEnumerable` sequences so subscriptions exist before the action occurs.\n- Stress the complete shared-fixture class or suite in its relevant test order, not only an isolated test. Test every supported target framework when runtime behavior can differ.\n- Diagnose timeouts by the missing transition or event. Include phase, entity ID,\n expected/actual state, ownership, and armed schedules.\n- Verify the patch itself. Do not rely on unrelated CI runs from branches that do not contain the change.\n","docs/tools/PackageJsonGenerator/README.md":"# PackageJsonGenerator\n\nGenerates deterministic per-package JSON describing the public .NET API in an Orleans assembly. The schema matches the package API data consumed by the `microsoft/aspire.dev` Astro site.\n\nUse `docs/scripts/Generate-ApiData.ps1` from the repository root to discover and build the packable Orleans projects, assemble each project's reference closure, and generate the complete package data set.\n\n```powershell\npwsh ./docs/scripts/Generate-ApiData.ps1\n```\n\nThe default output is `docs/site/src/data/pkgs`. Pass `-OutputDirectory` to generate into a staging directory, `-TargetFramework` to select another supported TFM, or `-SkipBuild` when all selected package projects have already been built.\n\nProjects are discovered from `src/**/*.csproj` using evaluated MSBuild properties. A project is included when it targets the selected framework and has both `IsPackable=true` and `IncludeBuildOutput=true`. This excludes test projects, implementation-only projects, analyzers, code generators, and assembly-free meta-packages without maintaining a package list.\n\nEach output file is named `{PackageId}.{PackageVersion}.json`. Only public types and members declared by that package assembly are emitted; project, package, and framework dependencies are resolution-only Roslyn references. Portable PDB paths are resolved against the verified local repository tree and a tracked-file allowlist from the advertised commit, avoiding network-dependent output and broken generated/inferred links. The script validates XML documentation, package metadata, source repository/commit information, and duplicate type identities before removing stale generator-owned JSON files.\n\nAPI selection uses `GeneratedCodeAttribute` and `CompilerGeneratedAttribute` to filter implementation types and members, including nested types and enum members. Authored partial types retain their API entries when generated members carry these attributes individually.\n\nBy default, source links target the latest commit which changed `src`. Generation fails when `src` has uncommitted changes. Automation can pass `-SourceCommit` to select an explicit full commit SHA.\n\n## Upstream attribution\n\nThis tool is adapted from [`microsoft/aspire.dev`'s `PackageJsonGenerator`](https://github.com/microsoft/aspire.dev/tree/9aa68083af47da79b63bc15b80f44c1927bf9c08/src/tools/PackageJsonGenerator) at commit `9aa68083af47da79b63bc15b80f44c1927bf9c08`.\n\nThe adapted source retains the upstream .NET Foundation and MIT license headers. Orleans-specific changes cover repository URL normalization, relevant Orleans attributes, project/package discovery, and local build orchestration.\n","samples/AGENTS.md":"# Orleans samples guidance\n\nThese rules apply recursively to everything under `samples/`. The repository-level guidance also applies.\n\n## Orchestration\n\n- Use [Aspire](https://aspire.dev) app hosts for new or reworked multi-process\n samples and external dependencies. Model dependencies as resources with local\n emulators or containers; use `aspire run` rather than manual setup scripts.\n- Wire Orleans through `Aspire.Hosting.Orleans`: `builder.AddOrleans(\"default\")`, then `WithClustering(...)`, `WithGrainStorage(...)`, and so on, and give service projects a `WithReference(orleans)`. See `JournaledTodoList` for the canonical layout and `JournalingAzureBlobJson` for a single-service one.\n- Name the app host project `.AppHost`, set `IsAspireHost`, and reference the `Aspire.AppHost.Sdk`. Add a `.ServiceDefaults` project when the sample has more than one service, and call `AddServiceDefaults()` from each service.\n- Use `WaitFor(...)` for resources a service needs at startup, and `WithExternalHttpEndpoints()` for endpoints the user opens in a browser.\n- Self-contained samples such as single-process `UseLocalhostClustering()` consoles\n can run without an app host.\n- Samples that exist to demonstrate a specific deployment target, such as those under `Deployment/`, keep the infrastructure assets that target requires.\n\n## Projects\n\n- Every sample project targets `net10.0` and is non-packable.\n- Keep each sample copyable and independently buildable. Reference Orleans through\n `Microsoft.Orleans.*` NuGet packages; project references stay within the sample.\n- `Build-Samples.ps1` packs `Orleans.slnx` with a unique prerelease version and builds\n `Samples.slnx` against those packages.\n- Each sample owns a `Directory.Packages.props` with versions for every dependency.\n The root samples file declares none; NuGet reads only the nearest file. Shared\n samples such as `Streaming/Common` use their shared parent as the copy-out unit.\n- `PackageReference` elements must not carry `Version` or `VersionOverride`. Keep a package pinned to the same version across all samples, keep Aspire hosting and component versions aligned, and pin vulnerable transitive dependencies explicitly since `CentralPackageTransitivePinningEnabled` is on.\n- Follow `.editorconfig`; keep idiomatic teaching code and comments focused on the\n Orleans concept being demonstrated.\n\n## Registration and documentation\n\n- `samples/Samples.slnx` must contain exactly the projects under `samples/`, grouped in a folder per sample. Add every new project, including app hosts and service defaults.\n- Add new samples to `gallery.json` following an existing entry and the schema in\n `Validate-Samples.ps1`. Tag Aspire-orchestrated samples with `aspire`.\n- `samples/README.md` is generated. Run `pwsh ./samples/Update-Readme.ps1` after changing `gallery.json`; never hand-edit it.\n- Give each sample a `README.md` explaining what it demonstrates and how to run it. Imported samples keep their existing front matter and their original source repository and license.\n\n## Validation\n\n- Run `pwsh ./samples/Validate-Samples.ps1` for any change under `samples/`. It checks the gallery manifest, README freshness, solution membership, package version declarations, sample self-containment, and invokes `Build-Samples.ps1` to build all samples against locally packed Orleans packages.\n- For instruction-only edits, use `-NoBuild`.\n- Verify a new or changed sample still builds standalone: copy its folder outside the repository and run `dotnet build`. A sample using an Orleans package which has not been published yet is exempt until that package ships; the in-tree solution still builds it from the local package source.\n- Building a sample must not require cloud credentials. Only running a sample may.\n- Check `git diff --check` before committing.\n","test/Extensions/Google/Emulators/README.md":"# Google Cloud emulators\n\nFirebase does not publish an official Emulator Suite container. Use the official Firebase CLI package instead.\n\nInstall Java 21 and Firebase CLI version 15.24.0:\n\n```shell\nnpm install --global firebase-tools@15.24.0\n```\n\nFrom this directory, start the configured emulators:\n\n```shell\nfirebase emulators:start --only firestore,pubsub,storage --project orleans-test\n```\n","docs/AGENTS.md":"# Orleans documentation guidance\n\nThese rules apply recursively to documentation, snippets, and samples under\n`docs/`. The repository-level guidance also applies.\n\n## Code examples\n\n- Put every C# example in a `snippets` project and include it with a named `:::code`\n region. Add hidden declarations outside the region when a displayed fragment\n needs context; don't use inline C# fences.\n- Keep snippets minimal, current, and self-contained, including declarations\n required by the displayed region.\n- Compile every affected snippet project. Don't publish pseudo-code as if it were a copyable example.\n- Documentation and snippet projects target `net10.0`.\n- Every `Microsoft.Orleans.*` package reference must use the approved version `10.2.2`. Keep the Orleans package family aligned and centralize versions where the project structure supports it.\n- Use an older Orleans package only for a narrow migration example whose purpose\n requires that version. Keep it under `migration` and document the reason in\n `OrleansDocumentationVersionException` in that project.\n- Keep direct dependency versions at or above the minimums required by the selected Orleans packages.\n- Don't demonstrate an unreleased API using an older package that doesn't contain it. Link to its API reference until a compilable source- or package-based example is available.\n\n## Links\n\n- Orleans documentation links should be relative so they work under `https://dotnet.github.io/orleans`.\n- Use fully qualified, locale-neutral canonical external links, such as `https://learn.microsoft.com/azure/...`.\n- Don't carry migrated repository `.md` suffixes into published links.\n- Verify newly added or changed external links and run the documentation site's link validation.\n\n## API references\n\n- Link public .NET symbols to generated API documentation using DocFX xref syntax instead of formatting the symbol only as inline code.\n- Use `` for types and `` for members or overload groups.\n- Add `?displayProperty=nameWithType` when the fully qualified display name improves clarity.\n- Use inline code for literals, configuration values, CLI commands, filenames,\n provider names, and syntax that isn't a linkable public symbol. Avoid\n repeatedly linking a symbol when an earlier contextual link is clearer.\n- Confirm the xref target exists in the generated API surface before publishing.\n\nExamples:\n\n```markdown\nUse for persistent grain state.\n\nConfigure it with .\n```\n\n## Documentation types\n\nAddress relevant operational concerns: correctness, security, availability,\nupgrades, capacity, cost, and diagnosis under load.\n\n- **Architecture**: components, protocols, invariants, consistency, failure and\n concurrency semantics, and design trade-offs under scale and version skew.\n- **How-to/cookbook**: one task, with prerequisites, pitfalls, and verification.\n- **Tutorial**: a working start-to-finish learning path.\n- **Conceptual**: the mental model, suitability, trade-offs, and verified constraints.\n- **API reference**: semantics, thread-safety, lifetime, exceptions, defaults, and examples.\n- **FAQ/troubleshooting**: observed symptoms, causes, remedies, and prevention.\n\nPlace updates in the appropriate category and cross-link rather than mix purposes.\n\n## Content\n\n- Keep ordinary conceptual and how-to documentation timeless. Name Orleans releases only in migration or upgrade guidance where the release boundary matters.\n- Describe implemented behavior and verified constraints: relevant triggers,\n runtime actions, outcomes, and operator responses. Attribute responsibilities to\n the mechanism that performs them.\n- Preserve useful content and authoritative references; update affected contracts\n and behavior. Remove obsolete or redundant material.\n- Treat hub pages as overviews: link to peer detail pages instead of singling out one provider or feature for inline configuration guidance.\n- Preserve stable URLs and anchors when moving content, or provide an explicit redirect or compatibility anchor.\n\n## Sources and generated output\n\n- Register every new page in `docs/site/src/content/docs/toc.yml` under the\n section that matches its documentation type. A compatibility page retained\n only for stable inbound routes can set `navigation: hidden`; link it to the\n current focused pages.\n- Keep recursive includes within the documentation source tree. Missing,\n circular, traversal, absolute, drive-relative, or symlink-escaping includes\n are invalid. Edit the include source and ensure active includes participate in\n link validation.\n- Don't hand-edit generated site output, generated API data, dependency folders,\n or build output such as generated `.mdx` siblings, `dist`, `node_modules`,\n `bin`, or `obj`.\n\n## Validation\n\n- Run the parser-backed link, include, redirect, navigation, and project-policy\n checks that cover the changed content.\n- Run `docs/site/src/content/docs/validate-snippets.ps1` for changed snippets\n and snippet project policy changes. It builds ordinary snippet projects and\n runs projects marked with `IsTestProject=true`, so executable testing examples\n are validated behaviorally.\n- Run `samples/Validate-Samples.ps1` when samples change.\n- When `docs/Docs.slnx` is present after integration, build it as the aggregate documentation project.\n- From `docs/site`, run `npm run validate`, including redirect and rendered\n output auditing.\n- Check `git diff --check` before committing.\n",".github/copilot-instructions.md":"## Implementation and code review\n\nFollow root `AGENTS.md` and applicable directory instructions for implementation principles and repository workflow.\n\nFor code review, use `.github/skills/code-review/SKILL.md`.\n\n## Build, test, and style commands\n\n* The repo builds with the .NET SDK from `global.json` (`10.0.400`, roll-forward `major`). Do not edit `global.json` unless explicitly asked.\n* Build the solution with `dotnet build Orleans.slnx -bl`. CI uses this form and uploads the binlog.\n* On Windows, `.\\Build.cmd` runs `build.ps1`, which restores, builds, and packs `Orleans.slnx`, writes restore/build/pack binlogs, and outputs packages under `Artifacts\\`. Set `BuildConfiguration=Release` to build release artifacts.\n* Run tests with `dotnet test --solution Orleans.slnx --framework net10.0 --minimum-expected-tests 1 --max-parallel-test-modules 1`. CI also runs `net8.0`; source projects default to `net8.0;net10.0`.\n* Run a category with `dotnet test --solution Orleans.slnx --framework net10.0 --filter-trait \"Category=BVT\" --minimum-expected-tests 1 --max-parallel-test-modules 1`. Common categories are `BVT`, `SlowBVT`, `Functional`, and provider-specific categories such as `Redis`, `Cassandra`, `SqlServer`, `Azure`, `AWS`, and `Streaming`.\n* Run one test with `dotnet test --project test\\Orleans.Core.Tests\\Orleans.Core.Tests.csproj --framework net10.0 --filter-class \"*MyTestClass*\" --filter-method \"*MyTestMethod*\" --minimum-expected-tests 1`.\n* `.\\Test.cmd` runs the scripted Windows test subset using the default xUnit query filter `/[(Category=BVT)|(Category=SlowBVT)]`. `.\\TestAll.cmd` adds the `Functional` category.\n* Provider tests often need external services, connection-string environment variables, or secrets. Match `.github\\workflows\\ci.yml` and `test\\TestInfrastructure\\TestExtensions\\TestDefaultConfiguration.cs` for the required setup.\n* Style is enforced by `dotnet build` because `Directory.Build.props` sets `EnforceCodeStyleInBuild=true` and `TreatWarningsAsErrors=true`.\n\n## High-level architecture\n\n* Orleans is a virtual actor framework. User code defines grain interfaces (`IGrainWithStringKey`, `IGrainWithGuidKey`, etc.) and grain classes; the runtime activates, places, deactivates, persists, and routes calls to grains across silos.\n* `src\\Orleans.Core.Abstractions` contains the public programming model: grain interfaces, grain references, attributes, and shared abstractions used by both clients and silos.\n* `src\\Orleans.Serialization.Abstractions` and `src\\Orleans.Serialization` provide the version-tolerant serializer, serialization attributes, runtime serialization services, and source-generator integration. Additional serializer packages live under `src\\Orleans.Serialization.*` and `src\\Serializers`.\n* `src\\Orleans.Core` contains shared client/server runtime infrastructure such as messaging, hosting integration, configuration, and serialization integration.\n* `src\\Orleans.Runtime` is the silo implementation: activation lifecycle, placement, cluster membership, reminders, runtime services, and grain execution.\n* `src\\Orleans.Sdk`, `src\\Orleans.Client`, and `src\\Orleans.Server` are packaging/metapackage projects. The SDK brings in core packages plus analyzers/code generation; the client/server packages compose the SDK with client or silo dependencies.\n* Provider packages are intentionally split by backend and capability under `src\\Azure`, `src\\AWS`, `src\\AdoNet`, `src\\Cassandra`, `src\\Redis`, and related top-level provider directories. They usually expose builder extensions in `Orleans.Hosting` and options in `Orleans.Configuration`.\n* Tests mirror runtime areas under `test\\`. Shared test infrastructure is in `test\\TestInfrastructure\\TestExtensions`, test grains and grain interfaces are under `test\\Grains`, and `Orleans.TestingHost`/`TestClusterBuilder` are the primary integration-test harnesses.\n* `src\\api` contains generated public API surfaces. Follow the regeneration and package compatibility commands in root `AGENTS.md`.\n\n## Key conventions\n\n* Central package management is enabled in `Directory.Packages.props`; add or update package versions there instead of putting versions in individual projects.\n* Use project references for repo-internal dependencies. `CONTRIBUTING.md` explicitly discourages DLL references and unnecessary `Private=True` metadata.\n* `src\\Directory.Build.props` makes source projects packable by default; `test\\Directory.Build.props` makes test projects non-packable and configures MTP test applications. The root `Directory.Build.targets` copies `test\\testconfig.json` under each test assembly name.\n* Build-time code generation is controlled by `OrleansBuildTimeCodeGen=true`, which imports the Orleans code generator and analyzers as build analyzers for framework projects.\n* Serializable Orleans types that cross grain calls, storage, or streams generally need `[GenerateSerializer]` plus stable `[Id(n)]` members. Do not renumber existing serialization IDs.\n* Tests use xUnit with the custom `[TestCategory(\"...\")]` attribute from `test\\TestInfrastructure\\TestExtensions\\TestCategory.cs`; this maps categories to xUnit traits for `dotnet test --filter-trait \"Category=...\"`.\n* Cluster tests usually derive from or compose fixtures in `test\\TestInfrastructure\\TestExtensions` and configure silos through `TestClusterBuilder`, `ISiloConfigurator`, or `ISiloBuilder`. The default cluster fixture uses in-memory reminders, durable jobs, and grain storage.\n* Follow `.editorconfig`: C# uses file-scoped namespaces, system directives first, `var` preferences, braces on new lines, `_camelCase` private fields, and preview language features. Nullable is enabled for source projects and disabled for test projects.\n* Add XML docs for new or changed public APIs even though CS1591 is currently suppressed; package projects generate documentation files.\n","test/Extensions/Google/Emulators/firebase.json":"{\n \"emulators\": {\n \"firestore\": {\n \"port\": 8080\n },\n \"pubsub\": {\n \"port\": 8085\n },\n \"storage\": {\n \"port\": 9199\n },\n \"ui\": {\n \"enabled\": true,\n \"port\": 9000\n },\n \"singleProjectMode\": false\n },\n \"storage\": {\n \"rules\": \"storage.rules\"\n }\n}","AGENTS.md":"# Implementation principles\n\nApply these principles during design, implementation, and validation, alongside\ncorrectness, security, compatibility, concurrency, and reliability.\n\n## Priorities\n\n- Rank goals as correctness (including safety) > simplicity > performance >\n convenience; seek a design that serves all of them before trading one away.\n- Safety (no corruption, data loss, broken invariants, or security violations)\n precedes liveness.\n- Ask the maintainer (in reviews, raise a question) before relying on an invariant\n that is not yet established, changing a surface that may have shipped or been\n persisted, or adding a dependency.\n\n## Approach\n\n- **Essence over accident.** The hard part is the spec and the conceptual model;\n code is its representation. Spend effort there.\n- **KISS.** Simplicity is the hardest revision, not the first draft. Iterate until\n the design is obviously right.\n- **YAGNI.** Build for today's requirements. \"If in doubt, leave it out.\"\n- **Grow, don't build.** Keep a running end-to-end skeleton; add function\n incrementally.\n- **Zero debt in what ships.** Fewer features, each solid. Fix showstoppers when\n found.\n- **Always say why.** Every non-obvious decision carries its rationale (comment,\n commit message, PR).\n\n## Layering, contracts, and invariants\n\n- Establish each layer's required and provided guarantees. Keep responsibilities\n and invariant enforcement in their owning layer; preserve contracts across\n callers, overrides, concurrency, failures, and lifecycle transitions.\n- Document non-obvious or changed contracts near the code in comments or XML API\n docs; use architecture documentation for broader design context.\n- Use side-effect-free assertions at API boundaries for caller preconditions and\n internal invariants. Prefer debug-time assertions (`Debug.Assert`) for product\n programming errors where contracts are established or maintained. Exercise\n assertion-enabled code in CI and surface assertion failures as test failures.\n Preserve required behavior and external-input validation when assertions are compiled out.\n- Within established contracts, rely on proven guarantees rather than adding\n redundant assertions or checks. Avoid unnecessary fallback state, retries, or catches.\n Validate external inputs and handle realistic failures with explicit error reporting.\n- Seek additional invariants that simplify code. Establish their feasibility,\n owning layer, and enforcement cost, then enforce and document them before use.\n\n## Clean, minimal implementations\n\n- Make the smallest complete change; reuse patterns and helpers. Keep unrelated\n refactoring and formatting out of scope.\n- Add abstractions, inheritance, virtual dispatch, options, fields, properties,\n caches, and states only for concrete requirements or boundaries. Derive values\n from existing state when correctness and efficiency permit.\n\n## Runtime performance\n\n- Assess CPU, throughput, latency, and scalability under relevant workloads,\n including algorithmic complexity, repeated work, I/O, contention, and scheduling.\n- Prioritize low allocation and retained-memory costs. Minimize copies, object sizes\n (including alignment), and retained graphs, especially per grain, activation, or\n message. Account for count and lifetime; justify optimizations by net benefit,\n ownership safety, and complexity. Support quantitative claims with evidence.\n\n## Testing and documentation\n\n- Assert observable outcomes and contracts across relevant boundaries, failures,\n and transitions. Use Accordant model-based tests, CsCheck property-based tests,\n Verify for xUnit snapshots (`Verify.XunitV3`), or unit/integration tests as\n appropriate. Reuse test infrastructure; follow `test/AGENTS.md` under `test/`.\n- Aim for greater than 80% CI code coverage. Consult the automated PR coverage\n comment for affected-code gaps and regressions; state when results are unavailable.\n Use behavioral assertions to establish guarantees.\n- Match documentation to affected behavior, audience, and document type. Update\n READMEs only for highly relevant end-user setup, usage, or public behavior.\n Describe affirmative behavior and outcomes.\n- For reviews, use `.github/skills/code-review/SKILL.md`.\n\n# Repository workflow\n\n- **New pull requests:** branch from `dotnet/orleans`'s `main`, push to the authenticated user's fork, and open the PR against `dotnet/orleans`.\n- **Existing contributor pull requests:** when maintainer edits are enabled and authentication permits, push updates to the PR author's head fork and branch.\n- **Every push:** run `git remote -v` and verify the destination by URL. Use the authenticated user's fork for new work or the PR author's fork for an existing PR; never rely on remote names or hard-code `origin`.\n- Never push a feature branch to a remote whose URL points to `github.com/dotnet/orleans`, over HTTPS or SSH. Delete it immediately if this happens accidentally.\n- After rebasing a PR branch, use `--force-with-lease`, never `--force`.\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commits and PR titles. Update nonconforming PR titles during review.\n- Keep PR descriptions focused on the problem, solution, and rationale; omit test-command sections.\n\n# Package compatibility\n\n- Packable source projects validate their produced packages against the released baseline configured in `src/Directory.Build.props`. Treat `CP*` and `PKV*` failures as compatibility findings, not warnings to disable globally.\n- When a public API break is intentional, first run the affected project's normal Release pack to capture the compatibility failure:\n `dotnet pack --configuration Release`.\n- Regenerate that project's suppression file with:\n `dotnet pack --configuration Release /p:GenerateCompatibilitySuppressionFile=true`.\n- Review the generated `CompatibilitySuppressions.xml` beside the project. Retain only entries which describe the approved break, keep the suppression scoped to the affected package and API, and commit it with the breaking change.\n- Run the normal Release pack again without `GenerateCompatibilitySuppressionFile` and require it to pass. Do not resolve compatibility failures by disabling package validation or adding `CP*`/`PKV*` diagnostics to `NoWarn`.\n- For an intentional target-framework removal, add a package-specific `PackageValidationBaselineFrameworkToIgnore` item instead of an API suppression.\n- After a release containing the break becomes the configured baseline, regenerate or remove the suppression file so obsolete entries do not accumulate.\n\n# Generated API surfaces\n\n- Files under `src/api` are generated public API surfaces. Do not edit them manually.\n- After changing public API in a packable source project, regenerate that project's API file using the same restore configuration and GenAPI target as CI:\n `dotnet restore --configfile .github/NuGet.GenAPI.Config -p:GenerateOrleansApiSource=true`,\n then `dotnet build --framework net8.0 --configuration Release --no-incremental --no-restore -p:GenerateOrleansApiSource=true /t:\"Build;GenAPIGenerateReferenceAssemblySource\"`.\n- Review and commit the generated `src/api` change with the implementation. The `GenerateOrleansApiSource` property activates the GenAPI package, and the dedicated NuGet config maps that package to its public transport feed; ordinary restores use only the repository's CFS source.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Implementation principles\n\nApply these principles during design, implementation, and validation, alongside\ncorrectness, security, compatibility, concurrency, and reliability.\n\n## Priorities\n\n- Rank goals as correctness (including safety) > simplicity > performance >\n convenience; seek a design that serves all of them before trading one away.\n- Safety (no corruption, data loss, broken invariants, or security violations)\n precedes liveness.\n- Ask the maintainer (in reviews, raise a question) before relying on an invariant\n that is not yet established, changing a surface that may have shipped or been\n persisted, or adding a dependency.\n\n## Approach\n\n- **Essence over accident.** The hard part is the spec and the conceptual model;\n code is its representation. Spend effort there.\n- **KISS.** Simplicity is the hardest revision, not the first draft. Iterate until\n the design is obviously right.\n- **YAGNI.** Build for today's requirements. \"If in doubt, leave it out.\"\n- **Grow, don't build.** Keep a running end-to-end skeleton; add function\n incrementally.\n- **Zero debt in what ships.** Fewer features, each solid. Fix showstoppers when\n found.\n- **Always say why.** Every non-obvious decision carries its rationale (comment,\n commit message, PR).\n\n## Layering, contracts, and invariants\n\n- Establish each layer's required and provided guarantees. Keep responsibilities\n and invariant enforcement in their owning layer; preserve contracts across\n callers, overrides, concurrency, failures, and lifecycle transitions.\n- Document non-obvious or changed contracts near the code in comments or XML API\n docs; use architecture documentation for broader design context.\n- Use side-effect-free assertions at API boundaries for caller preconditions and\n internal invariants. Prefer debug-time assertions (`Debug.Assert`) for product\n programming errors where contracts are established or maintained. Exercise\n assertion-enabled code in CI and surface assertion failures as test failures.\n Preserve required behavior and external-input validation when assertions are compiled out.\n- Within established contracts, rely on proven guarantees rather than adding\n redundant assertions or checks. Avoid unnecessary fallback state, retries, or catches.\n Validate external inputs and handle realistic failures with explicit error reporting.\n- Seek additional invariants that simplify code. Establish their feasibility,\n owning layer, and enforcement cost, then enforce and document them before use.\n\n## Clean, minimal implementations\n\n- Make the smallest complete change; reuse patterns and helpers. Keep unrelated\n refactoring and formatting out of scope.\n- Add abstractions, inheritance, virtual dispatch, options, fields, properties,\n caches, and states only for concrete requirements or boundaries. Derive values\n from existing state when correctness and efficiency permit.\n\n## Runtime performance\n\n- Assess CPU, throughput, latency, and scalability under relevant workloads,\n including algorithmic complexity, repeated work, I/O, contention, and scheduling.\n- Prioritize low allocation and retained-memory costs. Minimize copies, object sizes\n (including alignment), and retained graphs, especially per grain, activation, or\n message. Account for count and lifetime; justify optimizations by net benefit,\n ownership safety, and complexity. Support quantitative claims with evidence.\n\n## Testing and documentation\n\n- Assert observable outcomes and contracts across relevant boundaries, failures,\n and transitions. Use Accordant model-based tests, CsCheck property-based tests,\n Verify for xUnit snapshots (`Verify.XunitV3`), or unit/integration tests as\n appropriate. Reuse test infrastructure; follow `test/AGENTS.md` under `test/`.\n- Aim for greater than 80% CI code coverage. Consult the automated PR coverage\n comment for affected-code gaps and regressions; state when results are unavailable.\n Use behavioral assertions to establish guarantees.\n- Match documentation to affected behavior, audience, and document type. Update\n READMEs only for highly relevant end-user setup, usage, or public behavior.\n Describe affirmative behavior and outcomes.\n- For reviews, use `.github/skills/code-review/SKILL.md`.\n\n# Repository workflow\n\n- **New pull requests:** branch from `dotnet/orleans`'s `main`, push to the authenticated user's fork, and open the PR against `dotnet/orleans`.\n- **Existing contributor pull requests:** when maintainer edits are enabled and authentication permits, push updates to the PR author's head fork and branch.\n- **Every push:** run `git remote -v` and verify the destination by URL. Use the authenticated user's fork for new work or the PR author's fork for an existing PR; never rely on remote names or hard-code `origin`.\n- Never push a feature branch to a remote whose URL points to `github.com/dotnet/orleans`, over HTTPS or SSH. Delete it immediately if this happens accidentally.\n- After rebasing a PR branch, use `--force-with-lease`, never `--force`.\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commits and PR titles. Update nonconforming PR titles during review.\n- Keep PR descriptions focused on the problem, solution, and rationale; omit test-command sections.\n\n# Package compatibility\n\n- Packable source projects validate their produced packages against the released baseline configured in `src/Directory.Build.props`. Treat `CP*` and `PKV*` failures as compatibility findings, not warnings to disable globally.\n- When a public API break is intentional, first run the affected project's normal Release pack to capture the compatibility failure:\n `dotnet pack --configuration Release`.\n- Regenerate that project's suppression file with:\n `dotnet pack --configuration Release /p:GenerateCompatibilitySuppressionFile=true`.\n- Review the generated `CompatibilitySuppressions.xml` beside the project. Retain only entries which describe the approved break, keep the suppression scoped to the affected package and API, and commit it with the breaking change.\n- Run the normal Release pack again without `GenerateCompatibilitySuppressionFile` and require it to pass. Do not resolve compatibility failures by disabling package validation or adding `CP*`/`PKV*` diagnostics to `NoWarn`.\n- For an intentional target-framework removal, add a package-specific `PackageValidationBaselineFrameworkToIgnore` item instead of an API suppression.\n- After a release containing the break becomes the configured baseline, regenerate or remove the suppression file so obsolete entries do not accumulate.\n\n# Generated API surfaces\n\n- Files under `src/api` are generated public API surfaces. Do not edit them manually.\n- After changing public API in a packable source project, regenerate that project's API file using the same restore configuration and GenAPI target as CI:\n `dotnet restore --configfile .github/NuGet.GenAPI.Config -p:GenerateOrleansApiSource=true`,\n then `dotnet build --framework net8.0 --configuration Release --no-incremental --no-restore -p:GenerateOrleansApiSource=true /t:\"Build;GenAPIGenerateReferenceAssemblySource\"`.\n- Review and commit the generated `src/api` change with the implementation. The `GenerateOrleansApiSource` property activates the GenAPI package, and the dedicated NuGet config maps that package to its public transport feed; ordinary restores use only the repository's CFS source.\n","isInternal":false,"tokens":1529,"sizeBytes":7450},{"name":"AGENTS.md","path":"docs/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/docs/AGENTS.md","title":"docs - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Orleans documentation guidance\n\nThese rules apply recursively to documentation, snippets, and samples under\n`docs/`. The repository-level guidance also applies.\n\n## Code examples\n\n- Put every C# example in a `snippets` project and include it with a named `:::code`\n region. Add hidden declarations outside the region when a displayed fragment\n needs context; don't use inline C# fences.\n- Keep snippets minimal, current, and self-contained, including declarations\n required by the displayed region.\n- Compile every affected snippet project. Don't publish pseudo-code as if it were a copyable example.\n- Documentation and snippet projects target `net10.0`.\n- Every `Microsoft.Orleans.*` package reference must use the approved version `10.2.2`. Keep the Orleans package family aligned and centralize versions where the project structure supports it.\n- Use an older Orleans package only for a narrow migration example whose purpose\n requires that version. Keep it under `migration` and document the reason in\n `OrleansDocumentationVersionException` in that project.\n- Keep direct dependency versions at or above the minimums required by the selected Orleans packages.\n- Don't demonstrate an unreleased API using an older package that doesn't contain it. Link to its API reference until a compilable source- or package-based example is available.\n\n## Links\n\n- Orleans documentation links should be relative so they work under `https://dotnet.github.io/orleans`.\n- Use fully qualified, locale-neutral canonical external links, such as `https://learn.microsoft.com/azure/...`.\n- Don't carry migrated repository `.md` suffixes into published links.\n- Verify newly added or changed external links and run the documentation site's link validation.\n\n## API references\n\n- Link public .NET symbols to generated API documentation using DocFX xref syntax instead of formatting the symbol only as inline code.\n- Use `` for types and `` for members or overload groups.\n- Add `?displayProperty=nameWithType` when the fully qualified display name improves clarity.\n- Use inline code for literals, configuration values, CLI commands, filenames,\n provider names, and syntax that isn't a linkable public symbol. Avoid\n repeatedly linking a symbol when an earlier contextual link is clearer.\n- Confirm the xref target exists in the generated API surface before publishing.\n\nExamples:\n\n```markdown\nUse for persistent grain state.\n\nConfigure it with .\n```\n\n## Documentation types\n\nAddress relevant operational concerns: correctness, security, availability,\nupgrades, capacity, cost, and diagnosis under load.\n\n- **Architecture**: components, protocols, invariants, consistency, failure and\n concurrency semantics, and design trade-offs under scale and version skew.\n- **How-to/cookbook**: one task, with prerequisites, pitfalls, and verification.\n- **Tutorial**: a working start-to-finish learning path.\n- **Conceptual**: the mental model, suitability, trade-offs, and verified constraints.\n- **API reference**: semantics, thread-safety, lifetime, exceptions, defaults, and examples.\n- **FAQ/troubleshooting**: observed symptoms, causes, remedies, and prevention.\n\nPlace updates in the appropriate category and cross-link rather than mix purposes.\n\n## Content\n\n- Keep ordinary conceptual and how-to documentation timeless. Name Orleans releases only in migration or upgrade guidance where the release boundary matters.\n- Describe implemented behavior and verified constraints: relevant triggers,\n runtime actions, outcomes, and operator responses. Attribute responsibilities to\n the mechanism that performs them.\n- Preserve useful content and authoritative references; update affected contracts\n and behavior. Remove obsolete or redundant material.\n- Treat hub pages as overviews: link to peer detail pages instead of singling out one provider or feature for inline configuration guidance.\n- Preserve stable URLs and anchors when moving content, or provide an explicit redirect or compatibility anchor.\n\n## Sources and generated output\n\n- Register every new page in `docs/site/src/content/docs/toc.yml` under the\n section that matches its documentation type. A compatibility page retained\n only for stable inbound routes can set `navigation: hidden`; link it to the\n current focused pages.\n- Keep recursive includes within the documentation source tree. Missing,\n circular, traversal, absolute, drive-relative, or symlink-escaping includes\n are invalid. Edit the include source and ensure active includes participate in\n link validation.\n- Don't hand-edit generated site output, generated API data, dependency folders,\n or build output such as generated `.mdx` siblings, `dist`, `node_modules`,\n `bin`, or `obj`.\n\n## Validation\n\n- Run the parser-backed link, include, redirect, navigation, and project-policy\n checks that cover the changed content.\n- Run `docs/site/src/content/docs/validate-snippets.ps1` for changed snippets\n and snippet project policy changes. It builds ordinary snippet projects and\n runs projects marked with `IsTestProject=true`, so executable testing examples\n are validated behaviorally.\n- Run `samples/Validate-Samples.ps1` when samples change.\n- When `docs/Docs.slnx` is present after integration, build it as the aggregate documentation project.\n- From `docs/site`, run `npm run validate`, including redirect and rendered\n output auditing.\n- Check `git diff --check` before committing.\n","isInternal":false,"tokens":1135,"sizeBytes":5619},{"name":"AGENTS.md","path":"samples/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/samples/AGENTS.md","title":"samples - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Orleans samples guidance\n\nThese rules apply recursively to everything under `samples/`. The repository-level guidance also applies.\n\n## Orchestration\n\n- Use [Aspire](https://aspire.dev) app hosts for new or reworked multi-process\n samples and external dependencies. Model dependencies as resources with local\n emulators or containers; use `aspire run` rather than manual setup scripts.\n- Wire Orleans through `Aspire.Hosting.Orleans`: `builder.AddOrleans(\"default\")`, then `WithClustering(...)`, `WithGrainStorage(...)`, and so on, and give service projects a `WithReference(orleans)`. See `JournaledTodoList` for the canonical layout and `JournalingAzureBlobJson` for a single-service one.\n- Name the app host project `.AppHost`, set `IsAspireHost`, and reference the `Aspire.AppHost.Sdk`. Add a `.ServiceDefaults` project when the sample has more than one service, and call `AddServiceDefaults()` from each service.\n- Use `WaitFor(...)` for resources a service needs at startup, and `WithExternalHttpEndpoints()` for endpoints the user opens in a browser.\n- Self-contained samples such as single-process `UseLocalhostClustering()` consoles\n can run without an app host.\n- Samples that exist to demonstrate a specific deployment target, such as those under `Deployment/`, keep the infrastructure assets that target requires.\n\n## Projects\n\n- Every sample project targets `net10.0` and is non-packable.\n- Keep each sample copyable and independently buildable. Reference Orleans through\n `Microsoft.Orleans.*` NuGet packages; project references stay within the sample.\n- `Build-Samples.ps1` packs `Orleans.slnx` with a unique prerelease version and builds\n `Samples.slnx` against those packages.\n- Each sample owns a `Directory.Packages.props` with versions for every dependency.\n The root samples file declares none; NuGet reads only the nearest file. Shared\n samples such as `Streaming/Common` use their shared parent as the copy-out unit.\n- `PackageReference` elements must not carry `Version` or `VersionOverride`. Keep a package pinned to the same version across all samples, keep Aspire hosting and component versions aligned, and pin vulnerable transitive dependencies explicitly since `CentralPackageTransitivePinningEnabled` is on.\n- Follow `.editorconfig`; keep idiomatic teaching code and comments focused on the\n Orleans concept being demonstrated.\n\n## Registration and documentation\n\n- `samples/Samples.slnx` must contain exactly the projects under `samples/`, grouped in a folder per sample. Add every new project, including app hosts and service defaults.\n- Add new samples to `gallery.json` following an existing entry and the schema in\n `Validate-Samples.ps1`. Tag Aspire-orchestrated samples with `aspire`.\n- `samples/README.md` is generated. Run `pwsh ./samples/Update-Readme.ps1` after changing `gallery.json`; never hand-edit it.\n- Give each sample a `README.md` explaining what it demonstrates and how to run it. Imported samples keep their existing front matter and their original source repository and license.\n\n## Validation\n\n- Run `pwsh ./samples/Validate-Samples.ps1` for any change under `samples/`. It checks the gallery manifest, README freshness, solution membership, package version declarations, sample self-containment, and invokes `Build-Samples.ps1` to build all samples against locally packed Orleans packages.\n- For instruction-only edits, use `-NoBuild`.\n- Verify a new or changed sample still builds standalone: copy its folder outside the repository and run `dotnet build`. A sample using an Orleans package which has not been published yet is exempt until that package ships; the in-tree solution still builds it from the local package source.\n- Building a sample must not require cloud credentials. Only running a sample may.\n- Check `git diff --check` before committing.\n","isInternal":false,"tokens":832,"sizeBytes":3840},{"name":"AGENTS.md","path":"test/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/test/AGENTS.md","title":"test - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Orleans testing guidance\n\nThese rules apply recursively to tests under `test/`. The repository-level\nimplementation principles also apply.\n\n## Test design\n\n- Model-based tests compare implementation behavior with contracts across operation\n sequences, including relevant concurrency and failures.\n- Property-based failures must be reproducible, with effective shrinking.\n- Keep snapshots deterministic and focused; inspect baseline changes for intended\n semantics.\n\n## Reliability\n\n- Isolate mutable fixture state between tests, including clocks, clusters, topology,\n storage, and background tasks.\n- Give one orchestrator sole ownership of fake-time advancement; workers request\n or await progress.\n- Use `FakeTimeProvider` for grain-facing time, keyed `TimeProviderNames` for\n subsystem clocks, and `TimeProviderTestingExtensions.UseTimeProviderForBackgroundAreas`\n for unrelated real-time work (`src/Orleans.TestingHost/TimeProviderTestingExtensions.cs`).\n For timer-schedule synchronization, follow `TrackingFakeTimeProvider` in\n `test/Orleans.DefaultCluster.Tests/FakeTimeSilo.cs`.\n- Replace sleeps and polling with explicit phase barriers: wait for ownership and readiness, arm observers or synchronization primitives, perform one action or time advance, then await completion.\n- Use exact assertions with controlled time and synchronization; fix nondeterminism\n instead of widening expected ranges.\n- Observe lifecycle transitions with `DiagnosticListener` and `DiagnosticEventCollector`\n (`src/Orleans.TestingHost/Diagnostics/DiagnosticEventCollector.cs`); see\n `test/Orleans.GrainDirectory.Tests/GrainDirectory/GrainDirectoryLeaseTests.cs`.\n For in-process synchronization, use `InProcessTestCluster.TryGetGrainContext`\n where appropriate; preserve production behavior.\n- Arm and materialize waits before triggering the event. Materialize lazy `IEnumerable` sequences so subscriptions exist before the action occurs.\n- Stress the complete shared-fixture class or suite in its relevant test order, not only an isolated test. Test every supported target framework when runtime behavior can differ.\n- Diagnose timeouts by the missing transition or event. Include phase, entity ID,\n expected/actual state, ownership, and armed schedules.\n- Verify the patch itself. Do not rely on unrelated CI runs from branches that do not contain the change.\n","isInternal":false,"tokens":470,"sizeBytes":2371},{"name":"firebase.json","path":"test/Extensions/Google/Emulators/firebase.json","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/test/Extensions/Google/Emulators/firebase.json","title":"Emulators Skill","category":"anthropic-skill","format":"json","content":"{\n \"emulators\": {\n \"firestore\": {\n \"port\": 8080\n },\n \"pubsub\": {\n \"port\": 8085\n },\n \"storage\": {\n \"port\": 9199\n },\n \"ui\": {\n \"enabled\": true,\n \"port\": 9000\n },\n \"singleProjectMode\": false\n },\n \"storage\": {\n \"rules\": \"storage.rules\"\n }\n}","frontmatter":{"emulators":{"firestore":{"port":8080},"pubsub":{"port":8085},"storage":{"port":9199},"ui":{"enabled":true,"port":9000},"singleProjectMode":false},"storage":{"rules":"storage.rules"}},"isInternal":false,"tokens":101,"sizeBytes":295},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"## Implementation and code review\n\nFollow root `AGENTS.md` and applicable directory instructions for implementation principles and repository workflow.\n\nFor code review, use `.github/skills/code-review/SKILL.md`.\n\n## Build, test, and style commands\n\n* The repo builds with the .NET SDK from `global.json` (`10.0.400`, roll-forward `major`). Do not edit `global.json` unless explicitly asked.\n* Build the solution with `dotnet build Orleans.slnx -bl`. CI uses this form and uploads the binlog.\n* On Windows, `.\\Build.cmd` runs `build.ps1`, which restores, builds, and packs `Orleans.slnx`, writes restore/build/pack binlogs, and outputs packages under `Artifacts\\`. Set `BuildConfiguration=Release` to build release artifacts.\n* Run tests with `dotnet test --solution Orleans.slnx --framework net10.0 --minimum-expected-tests 1 --max-parallel-test-modules 1`. CI also runs `net8.0`; source projects default to `net8.0;net10.0`.\n* Run a category with `dotnet test --solution Orleans.slnx --framework net10.0 --filter-trait \"Category=BVT\" --minimum-expected-tests 1 --max-parallel-test-modules 1`. Common categories are `BVT`, `SlowBVT`, `Functional`, and provider-specific categories such as `Redis`, `Cassandra`, `SqlServer`, `Azure`, `AWS`, and `Streaming`.\n* Run one test with `dotnet test --project test\\Orleans.Core.Tests\\Orleans.Core.Tests.csproj --framework net10.0 --filter-class \"*MyTestClass*\" --filter-method \"*MyTestMethod*\" --minimum-expected-tests 1`.\n* `.\\Test.cmd` runs the scripted Windows test subset using the default xUnit query filter `/[(Category=BVT)|(Category=SlowBVT)]`. `.\\TestAll.cmd` adds the `Functional` category.\n* Provider tests often need external services, connection-string environment variables, or secrets. Match `.github\\workflows\\ci.yml` and `test\\TestInfrastructure\\TestExtensions\\TestDefaultConfiguration.cs` for the required setup.\n* Style is enforced by `dotnet build` because `Directory.Build.props` sets `EnforceCodeStyleInBuild=true` and `TreatWarningsAsErrors=true`.\n\n## High-level architecture\n\n* Orleans is a virtual actor framework. User code defines grain interfaces (`IGrainWithStringKey`, `IGrainWithGuidKey`, etc.) and grain classes; the runtime activates, places, deactivates, persists, and routes calls to grains across silos.\n* `src\\Orleans.Core.Abstractions` contains the public programming model: grain interfaces, grain references, attributes, and shared abstractions used by both clients and silos.\n* `src\\Orleans.Serialization.Abstractions` and `src\\Orleans.Serialization` provide the version-tolerant serializer, serialization attributes, runtime serialization services, and source-generator integration. Additional serializer packages live under `src\\Orleans.Serialization.*` and `src\\Serializers`.\n* `src\\Orleans.Core` contains shared client/server runtime infrastructure such as messaging, hosting integration, configuration, and serialization integration.\n* `src\\Orleans.Runtime` is the silo implementation: activation lifecycle, placement, cluster membership, reminders, runtime services, and grain execution.\n* `src\\Orleans.Sdk`, `src\\Orleans.Client`, and `src\\Orleans.Server` are packaging/metapackage projects. The SDK brings in core packages plus analyzers/code generation; the client/server packages compose the SDK with client or silo dependencies.\n* Provider packages are intentionally split by backend and capability under `src\\Azure`, `src\\AWS`, `src\\AdoNet`, `src\\Cassandra`, `src\\Redis`, and related top-level provider directories. They usually expose builder extensions in `Orleans.Hosting` and options in `Orleans.Configuration`.\n* Tests mirror runtime areas under `test\\`. Shared test infrastructure is in `test\\TestInfrastructure\\TestExtensions`, test grains and grain interfaces are under `test\\Grains`, and `Orleans.TestingHost`/`TestClusterBuilder` are the primary integration-test harnesses.\n* `src\\api` contains generated public API surfaces. Follow the regeneration and package compatibility commands in root `AGENTS.md`.\n\n## Key conventions\n\n* Central package management is enabled in `Directory.Packages.props`; add or update package versions there instead of putting versions in individual projects.\n* Use project references for repo-internal dependencies. `CONTRIBUTING.md` explicitly discourages DLL references and unnecessary `Private=True` metadata.\n* `src\\Directory.Build.props` makes source projects packable by default; `test\\Directory.Build.props` makes test projects non-packable and configures MTP test applications. The root `Directory.Build.targets` copies `test\\testconfig.json` under each test assembly name.\n* Build-time code generation is controlled by `OrleansBuildTimeCodeGen=true`, which imports the Orleans code generator and analyzers as build analyzers for framework projects.\n* Serializable Orleans types that cross grain calls, storage, or streams generally need `[GenerateSerializer]` plus stable `[Id(n)]` members. Do not renumber existing serialization IDs.\n* Tests use xUnit with the custom `[TestCategory(\"...\")]` attribute from `test\\TestInfrastructure\\TestExtensions\\TestCategory.cs`; this maps categories to xUnit traits for `dotnet test --filter-trait \"Category=...\"`.\n* Cluster tests usually derive from or compose fixtures in `test\\TestInfrastructure\\TestExtensions` and configure silos through `TestClusterBuilder`, `ISiloConfigurator`, or `ISiloBuilder`. The default cluster fixture uses in-memory reminders, durable jobs, and grain storage.\n* Follow `.editorconfig`: C# uses file-scoped namespaces, system directives first, `var` preferences, braces on new lines, `_camelCase` private fields, and preview language features. Nullable is enabled for source projects and disabled for test projects.\n* Add XML docs for new or changed public APIs even though CS1591 is currently suppressed; package projects generate documentation files.\n","isInternal":false,"tokens":1273,"sizeBytes":5876},{"name":"README.md","path":"docs/tools/PackageJsonGenerator/README.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/docs/tools/PackageJsonGenerator/README.md","title":"PackageJsonGenerator Documentation","category":"plugin-manifest","format":"markdown","content":"# PackageJsonGenerator\n\nGenerates deterministic per-package JSON describing the public .NET API in an Orleans assembly. The schema matches the package API data consumed by the `microsoft/aspire.dev` Astro site.\n\nUse `docs/scripts/Generate-ApiData.ps1` from the repository root to discover and build the packable Orleans projects, assemble each project's reference closure, and generate the complete package data set.\n\n```powershell\npwsh ./docs/scripts/Generate-ApiData.ps1\n```\n\nThe default output is `docs/site/src/data/pkgs`. Pass `-OutputDirectory` to generate into a staging directory, `-TargetFramework` to select another supported TFM, or `-SkipBuild` when all selected package projects have already been built.\n\nProjects are discovered from `src/**/*.csproj` using evaluated MSBuild properties. A project is included when it targets the selected framework and has both `IsPackable=true` and `IncludeBuildOutput=true`. This excludes test projects, implementation-only projects, analyzers, code generators, and assembly-free meta-packages without maintaining a package list.\n\nEach output file is named `{PackageId}.{PackageVersion}.json`. Only public types and members declared by that package assembly are emitted; project, package, and framework dependencies are resolution-only Roslyn references. Portable PDB paths are resolved against the verified local repository tree and a tracked-file allowlist from the advertised commit, avoiding network-dependent output and broken generated/inferred links. The script validates XML documentation, package metadata, source repository/commit information, and duplicate type identities before removing stale generator-owned JSON files.\n\nAPI selection uses `GeneratedCodeAttribute` and `CompilerGeneratedAttribute` to filter implementation types and members, including nested types and enum members. Authored partial types retain their API entries when generated members carry these attributes individually.\n\nBy default, source links target the latest commit which changed `src`. Generation fails when `src` has uncommitted changes. Automation can pass `-SourceCommit` to select an explicit full commit SHA.\n\n## Upstream attribution\n\nThis tool is adapted from [`microsoft/aspire.dev`'s `PackageJsonGenerator`](https://github.com/microsoft/aspire.dev/tree/9aa68083af47da79b63bc15b80f44c1927bf9c08/src/tools/PackageJsonGenerator) at commit `9aa68083af47da79b63bc15b80f44c1927bf9c08`.\n\nThe adapted source retains the upstream .NET Foundation and MIT license headers. Orleans-specific changes cover repository URL normalization, relevant Orleans attributes, project/package discovery, and local build orchestration.\n","isInternal":false,"tokens":538,"sizeBytes":2658},{"name":"README.md","path":"test/Extensions/Google/Emulators/README.md","rawUrl":"https://raw.githubusercontent.com/dotnet/orleans/HEAD/test/Extensions/Google/Emulators/README.md","title":"Emulators Documentation","category":"plugin-manifest","format":"markdown","content":"# Google Cloud emulators\n\nFirebase does not publish an official Emulator Suite container. Use the official Firebase CLI package instead.\n\nInstall Java 21 and Firebase CLI version 15.24.0:\n\n```shell\nnpm install --global firebase-tools@15.24.0\n```\n\nFrom this directory, start the configured emulators:\n\n```shell\nfirebase emulators:start --only firestore,pubsub,storage --project orleans-test\n```\n","isInternal":false,"tokens":91,"sizeBytes":394}],"systemPromptSnippet":"\n\n# Implementation principles\n\nApply these principles during design, implementation, and validation, alongside\ncorrectness, security, compatibility, concurrency, and reliability.\n\n## Priorities\n\n- Rank goals as correctness (including safety) > simplicity > performance >\n convenience; seek a design that serves all of them before trading one away.\n- Safety (no corruption, data loss, broken invariants, or security violations)\n precedes liveness.\n- Ask the maintainer (in reviews, raise a question) before relying on an invariant\n that is not yet established, changing a surface that may have shipped or been\n persisted, or adding a dependency.\n\n## Approach\n\n- **Essence over accident.** The hard part is the spec and the conceptual model;\n code is its representation. Spend effort there.\n- **KISS.** Simplicity is the hardest revision, not the first draft. Iterate until\n the design is obviously right.\n- **YAGNI.** Build for today's requirements. \"If in doubt, leave it out.\"\n- **Grow, don't build.** Keep a running end-to-end skeleton; add function\n incrementally.\n- **Zero debt in what ships.** Fewer features, each solid. Fix showstoppers when\n found.\n- **Always say why.** Every non-obvious decision carries its rationale (comment,\n commit message, PR).\n\n## Layering, contracts, and invariants\n\n- Establish each layer's required and provided guarantees. Keep responsibilities\n and invariant enforcement in their owning layer; preserve contracts across\n callers, overrides, concurrency, failures, and lifecycle transitions.\n- Document non-obvious or changed contracts near the code in comments or XML API\n docs; use architecture documentation for broader design context.\n- Use side-effect-free assertions at API boundaries for caller preconditions and\n internal invariants. Prefer debug-time assertions (`Debug.Assert`) for product\n programming errors where contracts are established or maintained. Exercise\n assertion-enabled code in CI and surface assertion failures as test failures.\n Preserve required behavior and external-input validation when assertions are compiled out.\n- Within established contracts, rely on proven guarantees rather than adding\n redundant assertions or checks. Avoid unnecessary fallback state, retries, or catches.\n Validate external inputs and handle realistic failures with explicit error reporting.\n- Seek additional invariants that simplify code. Establish their feasibility,\n owning layer, and enforcement cost, then enforce and document them before use.\n\n## Clean, minimal implementations\n\n- Make the smallest complete change; reuse patterns and helpers. Keep unrelated\n refactoring and formatting out of scope.\n- Add abstractions, inheritance, virtual dispatch, options, fields, properties,\n caches, and states only for concrete requirements or boundaries. Derive values\n from existing state when correctness and efficiency permit.\n\n## Runtime performance\n\n- Assess CPU, throughput, latency, and scalability under relevant workloads,\n including algorithmic complexity, repeated work, I/O, contention, and scheduling.\n- Prioritize low allocation and retained-memory costs. Minimize copies, object sizes\n (including alignment), and retained graphs, especially per grain, activation, or\n message. Account for count and lifetime; justify optimizations by net benefit,\n ownership safety, and complexity. Support quantitative claims with evidence.\n\n## Testing and documentation\n\n- Assert observable outcomes and contracts across relevant boundaries, failures,\n and transitions. Use Accordant model-based tests, CsCheck property-based tests,\n Verify for xUnit snapshots (`Verify.XunitV3`), or unit/integration tests as\n appropriate. Reuse test infrastructure; follow `test/AGENTS.md` under `test/`.\n- Aim for greater than 80% CI code coverage. Consult the automated PR coverage\n comment for affected-code gaps and regressions; state when results are unavailable.\n Use behavioral assertions to establish guarantees.\n- Match documentation to affected behavior, audience, and document type. Update\n READMEs only for highly relevant end-user setup, usage, or public behavior.\n Describe affirmative behavior and outcomes.\n- For reviews, use `.github/skills/code-review/SKILL.md`.\n\n# Repository workflow\n\n- **New pull requests:** branch from `dotnet/orleans`'s `main`, push to the authenticated user's fork, and open the PR against `dotnet/orleans`.\n- **Existing contributor pull requests:** when maintainer edits are enabled and authentication permits, push updates to the PR author's head fork and branch.\n- **Every push:** run `git remote -v` and verify the destination by URL. Use the authenticated user's fork for new work or the PR author's fork for an existing PR; never rely on remote names or hard-code `origin`.\n- Never push a feature branch to a remote whose URL points to `github.com/dotnet/orleans`, over HTTPS or SSH. Delete it immediately if this happens accidentally.\n- After rebasing a PR branch, use `--force-with-lease`, never `--force`.\n- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commits and PR titles. Update nonconforming PR titles during review.\n- Keep PR descriptions focused on the problem, solution, and rationale; omit test-command sections.\n\n# Package compatibility\n\n- Packable source projects validate their produced packages against the released baseline configured in `src/Directory.Build.props`. Treat `CP*` and `PKV*` failures as compatibility findings, not warnings to disable globally.\n- When a public API break is intentional, first run the affected project's normal Release pack to capture the compatibility failure:\n `dotnet pack --configuration Release`.\n- Regenerate that project's suppression file with:\n `dotnet pack --configuration Release /p:GenerateCompatibilitySuppressionFile=true`.\n- Review the generated `CompatibilitySuppressions.xml` beside the project. Retain only entries which describe the approved break, keep the suppression scoped to the affected package and API, and commit it with the breaking change.\n- Run the normal Release pack again without `GenerateCompatibilitySuppressionFile` and require it to pass. Do not resolve compatibility failures by disabling package validation or adding `CP*`/`PKV*` diagnostics to `NoWarn`.\n- For an intentional target-framework removal, add a package-specific `PackageValidationBaselineFrameworkToIgnore` item instead of an API suppression.\n- After a release containing the break becomes the configured baseline, regenerate or remove the suppression file so obsolete entries do not accumulate.\n\n# Generated API surfaces\n\n- Files under `src/api` are generated public API surfaces. Do not edit them manually.\n- After changing public API in a packable source project, regenerate that project's API file using the same restore configuration and GenAPI target as CI:\n `dotnet restore --configfile .github/NuGet.GenAPI.Config -p:GenerateOrleansApiSource=true`,\n then `dotnet build --framework net8.0 --configuration Release --no-incremental --no-restore -p:GenerateOrleansApiSource=true /t:\"Build;GenAPIGenerateReferenceAssemblySource\"`.\n- Review and commit the generated `src/api` change with the implementation. The `GenerateOrleansApiSource` property activates the GenAPI package, and the dedicated NuGet config maps that package to its public transport feed; ordinary restores use only the repository's CFS source.\n\n\n# Orleans documentation guidance\n\nThese rules apply recursively to documentation, snippets, and samples under\n`docs/`. The repository-level guidance also applies.\n\n## Code examples\n\n- Put every C# example in a `snippets` project and include it with a named `:::code`\n region. Add hidden declarations outside the region when a displayed fragment\n needs context; don't use inline C# fences.\n- Keep snippets minimal, current, and self-contained, including declarations\n required by the displayed region.\n- Compile every affected snippet project. Don't publish pseudo-code as if it were a copyable example.\n- Documentation and snippet projects target `net10.0`.\n- Every `Microsoft.Orleans.*` package reference must use the approved version `10.2.2`. Keep the Orleans package family aligned and centralize versions where the project structure supports it.\n- Use an older Orleans package only for a narrow migration example whose purpose\n requires that version. Keep it under `migration` and document the reason in\n `OrleansDocumentationVersionException` in that project.\n- Keep direct dependency versions at or above the minimums required by the selected Orleans packages.\n- Don't demonstrate an unreleased API using an older package that doesn't contain it. Link to its API reference until a compilable source- or package-based example is available.\n\n## Links\n\n- Orleans documentation links should be relative so they work under `https://dotnet.github.io/orleans`.\n- Use fully qualified, locale-neutral canonical external links, such as `https://learn.microsoft.com/azure/...`.\n- Don't carry migrated repository `.md` suffixes into published links.\n- Verify newly added or changed external links and run the documentation site's link validation.\n\n## API references\n\n- Link public .NET symbols to generated API documentation using DocFX xref syntax instead of formatting the symbol only as inline code.\n- Use `` for types and `` for members or overload groups.\n- Add `?displayProperty=nameWithType` when the fully qualified display name improves clarity.\n- Use inline code for literals, configuration values, CLI commands, filenames,\n provider names, and syntax that isn't a linkable public symbol. Avoid\n repeatedly linking a symbol when an earlier contextual link is clearer.\n- Confirm the xref target exists in the generated API surface before publishing.\n\nExamples:\n\n```markdown\nUse for persistent grain state.\n\nConfigure it with .\n```\n\n## Documentation types\n\nAddress relevant operational concerns: correctness, security, availability,\nupgrades, capacity, cost, and diagnosis under load.\n\n- **Architecture**: components, protocols, invariants, consistency, failure and\n concurrency semantics, and design trade-offs under scale and version skew.\n- **How-to/cookbook**: one task, with prerequisites, pitfalls, and verification.\n- **Tutorial**: a working start-to-finish learning path.\n- **Conceptual**: the mental model, suitability, trade-offs, and verified constraints.\n- **API reference**: semantics, thread-safety, lifetime, exceptions, defaults, and examples.\n- **FAQ/troubleshooting**: observed symptoms, causes, remedies, and prevention.\n\nPlace updates in the appropriate category and cross-link rather than mix purposes.\n\n## Content\n\n- Keep ordinary conceptual and how-to documentation timeless. Name Orleans releases only in migration or upgrade guidance where the release boundary matters.\n- Describe implemented behavior and verified constraints: relevant triggers,\n runtime actions, outcomes, and operator responses. Attribute responsibilities to\n the mechanism that performs them.\n- Preserve useful content and authoritative references; update affected contracts\n and behavior. Remove obsolete or redundant material.\n- Treat hub pages as overviews: link to peer detail pages instead of singling out one provider or feature for inline configuration guidance.\n- Preserve stable URLs and anchors when moving content, or provide an explicit redirect or compatibility anchor.\n\n## Sources and generated output\n\n- Register every new page in `docs/site/src/content/docs/toc.yml` under the\n section that matches its documentation type. A compatibility page retained\n only for stable inbound routes can set `navigation: hidden`; link it to the\n current focused pages.\n- Keep recursive includes within the documentation source tree. Missing,\n circular, traversal, absolute, drive-relative, or symlink-escaping includes\n are invalid. Edit the include source and ensure active includes participate in\n link validation.\n- Don't hand-edit generated site output, generated API data, dependency folders,\n or build output such as generated `.mdx` siblings, `dist`, `node_modules`,\n `bin`, or `obj`.\n\n## Validation\n\n- Run the parser-backed link, include, redirect, navigation, and project-policy\n checks that cover the changed content.\n- Run `docs/site/src/content/docs/validate-snippets.ps1` for changed snippets\n and snippet project policy changes. It builds ordinary snippet projects and\n runs projects marked with `IsTestProject=true`, so executable testing examples\n are validated behaviorally.\n- Run `samples/Validate-Samples.ps1` when samples change.\n- When `docs/Docs.slnx` is present after integration, build it as the aggregate documentation project.\n- From `docs/site`, run `npm run validate`, including redirect and rendered\n output auditing.\n- Check `git diff --check` before committing.\n\n\n# Orleans samples guidance\n\nThese rules apply recursively to everything under `samples/`. The repository-level guidance also applies.\n\n## Orchestration\n\n- Use [Aspire](https://aspire.dev) app hosts for new or reworked multi-process\n samples and external dependencies. Model dependencies as resources with local\n emulators or containers; use `aspire run` rather than manual setup scripts.\n- Wire Orleans through `Aspire.Hosting.Orleans`: `builder.AddOrleans(\"default\")`, then `WithClustering(...)`, `WithGrainStorage(...)`, and so on, and give service projects a `WithReference(orleans)`. See `JournaledTodoList` for the canonical layout and `JournalingAzureBlobJson` for a single-service one.\n- Name the app host project `.AppHost`, set `IsAspireHost`, and reference the `Aspire.AppHost.Sdk`. Add a `.ServiceDefaults` project when the sample has more than one service, and call `AddServiceDefaults()` from each service.\n- Use `WaitFor(...)` for resources a service needs at startup, and `WithExternalHttpEndpoints()` for endpoints the user opens in a browser.\n- Self-contained samples such as single-process `UseLocalhostClustering()` consoles\n can run without an app host.\n- Samples that exist to demonstrate a specific deployment target, such as those under `Deployment/`, keep the infrastructure assets that target requires.\n\n## Projects\n\n- Every sample project targets `net10.0` and is non-packable.\n- Keep each sample copyable and independently buildable. Reference Orleans through\n `Microsoft.Orleans.*` NuGet packages; project references stay within the sample.\n- `Build-Samples.ps1` packs `Orleans.slnx` with a unique prerelease version and builds\n `Samples.slnx` against those packages.\n- Each sample owns a `Directory.Packages.props` with versions for every dependency.\n The root samples file declares none; NuGet reads only the nearest file. Shared\n samples such as `Streaming/Common` use their shared parent as the copy-out unit.\n- `PackageReference` elements must not carry `Version` or `VersionOverride`. Keep a package pinned to the same version across all samples, keep Aspire hosting and component versions aligned, and pin vulnerable transitive dependencies explicitly since `CentralPackageTransitivePinningEnabled` is on.\n- Follow `.editorconfig`; keep idiomatic teaching code and comments focused on the\n Orleans concept being demonstrated.\n\n## Registration and documentation\n\n- `samples/Samples.slnx` must contain exactly the projects under `samples/`, grouped in a folder per sample. Add every new project, including app hosts and service defaults.\n- Add new samples to `gallery.json` following an existing entry and the schema in\n `Validate-Samples.ps1`. Tag Aspire-orchestrated samples with `aspire`.\n- `samples/README.md` is generated. Run `pwsh ./samples/Update-Readme.ps1` after changing `gallery.json`; never hand-edit it.\n- Give each sample a `README.md` explaining what it demonstrates and how to run it. Imported samples keep their existing front matter and their original source repository and license.\n\n## Validation\n\n- Run `pwsh ./samples/Validate-Samples.ps1` for any change under `samples/`. It checks the gallery manifest, README freshness, solution membership, package version declarations, sample self-containment, and invokes `Build-Samples.ps1` to build all samples against locally packed Orleans packages.\n- For instruction-only edits, use `-NoBuild`.\n- Verify a new or changed sample still builds standalone: copy its folder outside the repository and run `dotnet build`. A sample using an Orleans package which has not been published yet is exempt until that package ships; the in-tree solution still builds it from the local package source.\n- Building a sample must not require cloud credentials. Only running a sample may.\n- Check `git diff --check` before committing.\n\n\n# Orleans testing guidance\n\nThese rules apply recursively to tests under `test/`. The repository-level\nimplementation principles also apply.\n\n## Test design\n\n- Model-based tests compare implementation behavior with contracts across operation\n sequences, including relevant concurrency and failures.\n- Property-based failures must be reproducible, with effective shrinking.\n- Keep snapshots deterministic and focused; inspect baseline changes for intended\n semantics.\n\n## Reliability\n\n- Isolate mutable fixture state between tests, including clocks, clusters, topology,\n storage, and background tasks.\n- Give one orchestrator sole ownership of fake-time advancement; workers request\n or await progress.\n- Use `FakeTimeProvider` for grain-facing time, keyed `TimeProviderNames` for\n subsystem clocks, and `TimeProviderTestingExtensions.UseTimeProviderForBackgroundAreas`\n for unrelated real-time work (`src/Orleans.TestingHost/TimeProviderTestingExtensions.cs`).\n For timer-schedule synchronization, follow `TrackingFakeTimeProvider` in\n `test/Orleans.DefaultCluster.Tests/FakeTimeSilo.cs`.\n- Replace sleeps and polling with explicit phase barriers: wait for ownership and readiness, arm observers or synchronization primitives, perform one action or time advance, then await completion.\n- Use exact assertions with controlled time and synchronization; fix nondeterminism\n instead of widening expected ranges.\n- Observe lifecycle transitions with `DiagnosticListener` and `DiagnosticEventCollector`\n (`src/Orleans.TestingHost/Diagnostics/DiagnosticEventCollector.cs`); see\n `test/Orleans.GrainDirectory.Tests/GrainDirectory/GrainDirectoryLeaseTests.cs`.\n For in-process synchronization, use `InProcessTestCluster.TryGetGrainContext`\n where appropriate; preserve production behavior.\n- Arm and materialize waits before triggering the event. Materialize lazy `IEnumerable` sequences so subscriptions exist before the action occurs.\n- Stress the complete shared-fixture class or suite in its relevant test order, not only an isolated test. Test every supported target framework when runtime behavior can differ.\n- Diagnose timeouts by the missing transition or event. Include phase, entity ID,\n expected/actual state, ownership, and armed schedules.\n- Verify the patch itself. Do not rely on unrelated CI runs from branches that do not contain the change.\n\n\n{\n \"emulators\": {\n \"firestore\": {\n \"port\": 8080\n },\n \"pubsub\": {\n \"port\": 8085\n },\n \"storage\": {\n \"port\": 9199\n },\n \"ui\": {\n \"enabled\": true,\n \"port\": 9000\n },\n \"singleProjectMode\": false\n },\n \"storage\": {\n \"rules\": \"storage.rules\"\n }\n}\n\n\n## Implementation and code review\n\nFollow root `AGENTS.md` and applicable directory instructions for implementation principles and repository workflow.\n\nFor code review, use `.github/skills/code-review/SKILL.md`.\n\n## Build, test, and style commands\n\n* The repo builds with the .NET SDK from `global.json` (`10.0.400`, roll-forward `major`). Do not edit `global.json` unless explicitly asked.\n* Build the solution with `dotnet build Orleans.slnx -bl`. CI uses this form and uploads the binlog.\n* On Windows, `.\\Build.cmd` runs `build.ps1`, which restores, builds, and packs `Orleans.slnx`, writes restore/build/pack binlogs, and outputs packages under `Artifacts\\`. Set `BuildConfiguration=Release` to build release artifacts.\n* Run tests with `dotnet test --solution Orleans.slnx --framework net10.0 --minimum-expected-tests 1 --max-parallel-test-modules 1`. CI also runs `net8.0`; source projects default to `net8.0;net10.0`.\n* Run a category with `dotnet test --solution Orleans.slnx --framework net10.0 --filter-trait \"Category=BVT\" --minimum-expected-tests 1 --max-parallel-test-modules 1`. Common categories are `BVT`, `SlowBVT`, `Functional`, and provider-specific categories such as `Redis`, `Cassandra`, `SqlServer`, `Azure`, `AWS`, and `Streaming`.\n* Run one test with `dotnet test --project test\\Orleans.Core.Tests\\Orleans.Core.Tests.csproj --framework net10.0 --filter-class \"*MyTestClass*\" --filter-method \"*MyTestMethod*\" --minimum-expected-tests 1`.\n* `.\\Test.cmd` runs the scripted Windows test subset using the default xUnit query filter `/[(Category=BVT)|(Category=SlowBVT)]`. `.\\TestAll.cmd` adds the `Functional` category.\n* Provider tests often need external services, connection-string environment variables, or secrets. Match `.github\\workflows\\ci.yml` and `test\\TestInfrastructure\\TestExtensions\\TestDefaultConfiguration.cs` for the required setup.\n* Style is enforced by `dotnet build` because `Directory.Build.props` sets `EnforceCodeStyleInBuild=true` and `TreatWarningsAsErrors=true`.\n\n## High-level architecture\n\n* Orleans is a virtual actor framework. User code defines grain interfaces (`IGrainWithStringKey`, `IGrainWithGuidKey`, etc.) and grain classes; the runtime activates, places, deactivates, persists, and routes calls to grains across silos.\n* `src\\Orleans.Core.Abstractions` contains the public programming model: grain interfaces, grain references, attributes, and shared abstractions used by both clients and silos.\n* `src\\Orleans.Serialization.Abstractions` and `src\\Orleans.Serialization` provide the version-tolerant serializer, serialization attributes, runtime serialization services, and source-generator integration. Additional serializer packages live under `src\\Orleans.Serialization.*` and `src\\Serializers`.\n* `src\\Orleans.Core` contains shared client/server runtime infrastructure such as messaging, hosting integration, configuration, and serialization integration.\n* `src\\Orleans.Runtime` is the silo implementation: activation lifecycle, placement, cluster membership, reminders, runtime services, and grain execution.\n* `src\\Orleans.Sdk`, `src\\Orleans.Client`, and `src\\Orleans.Server` are packaging/metapackage projects. The SDK brings in core packages plus analyzers/code generation; the client/server packages compose the SDK with client or silo dependencies.\n* Provider packages are intentionally split by backend and capability under `src\\Azure`, `src\\AWS`, `src\\AdoNet`, `src\\Cassandra`, `src\\Redis`, and related top-level provider directories. They usually expose builder extensions in `Orleans.Hosting` and options in `Orleans.Configuration`.\n* Tests mirror runtime areas under `test\\`. Shared test infrastructure is in `test\\TestInfrastructure\\TestExtensions`, test grains and grain interfaces are under `test\\Grains`, and `Orleans.TestingHost`/`TestClusterBuilder` are the primary integration-test harnesses.\n* `src\\api` contains generated public API surfaces. Follow the regeneration and package compatibility commands in root `AGENTS.md`.\n\n## Key conventions\n\n* Central package management is enabled in `Directory.Packages.props`; add or update package versions there instead of putting versions in individual projects.\n* Use project references for repo-internal dependencies. `CONTRIBUTING.md` explicitly discourages DLL references and unnecessary `Private=True` metadata.\n* `src\\Directory.Build.props` makes source projects packable by default; `test\\Directory.Build.props` makes test projects non-packable and configures MTP test applications. The root `Directory.Build.targets` copies `test\\testconfig.json` under each test assembly name.\n* Build-time code generation is controlled by `OrleansBuildTimeCodeGen=true`, which imports the Orleans code generator and analyzers as build analyzers for framework projects.\n* Serializable Orleans types that cross grain calls, storage, or streams generally need `[GenerateSerializer]` plus stable `[Id(n)]` members. Do not renumber existing serialization IDs.\n* Tests use xUnit with the custom `[TestCategory(\"...\")]` attribute from `test\\TestInfrastructure\\TestExtensions\\TestCategory.cs`; this maps categories to xUnit traits for `dotnet test --filter-trait \"Category=...\"`.\n* Cluster tests usually derive from or compose fixtures in `test\\TestInfrastructure\\TestExtensions` and configure silos through `TestClusterBuilder`, `ISiloConfigurator`, or `ISiloBuilder`. The default cluster fixture uses in-memory reminders, durable jobs, and grain storage.\n* Follow `.editorconfig`: C# uses file-scoped namespaces, system directives first, `var` preferences, braces on new lines, `_camelCase` private fields, and preview language features. Nullable is enabled for source projects and disabled for test projects.\n* Add XML docs for new or changed public APIs even though CS1591 is currently suppressed; package projects generate documentation files.\n\n\n# PackageJsonGenerator\n\nGenerates deterministic per-package JSON describing the public .NET API in an Orleans assembly. The schema matches the package API data consumed by the `microsoft/aspire.dev` Astro site.\n\nUse `docs/scripts/Generate-ApiData.ps1` from the repository root to discover and build the packable Orleans projects, assemble each project's reference closure, and generate the complete package data set.\n\n```powershell\npwsh ./docs/scripts/Generate-ApiData.ps1\n```\n\nThe default output is `docs/site/src/data/pkgs`. Pass `-OutputDirectory` to generate into a staging directory, `-TargetFramework` to select another supported TFM, or `-SkipBuild` when all selected package projects have already been built.\n\nProjects are discovered from `src/**/*.csproj` using evaluated MSBuild properties. A project is included when it targets the selected framework and has both `IsPackable=true` and `IncludeBuildOutput=true`. This excludes test projects, implementation-only projects, analyzers, code generators, and assembly-free meta-packages without maintaining a package list.\n\nEach output file is named `{PackageId}.{PackageVersion}.json`. Only public types and members declared by that package assembly are emitted; project, package, and framework dependencies are resolution-only Roslyn references. Portable PDB paths are resolved against the verified local repository tree and a tracked-file allowlist from the advertised commit, avoiding network-dependent output and broken generated/inferred links. The script validates XML documentation, package metadata, source repository/commit information, and duplicate type identities before removing stale generator-owned JSON files.\n\nAPI selection uses `GeneratedCodeAttribute` and `CompilerGeneratedAttribute` to filter implementation types and members, including nested types and enum members. Authored partial types retain their API entries when generated members carry these attributes individually.\n\nBy default, source links target the latest commit which changed `src`. Generation fails when `src` has uncommitted changes. Automation can pass `-SourceCommit` to select an explicit full commit SHA.\n\n## Upstream attribution\n\nThis tool is adapted from [`microsoft/aspire.dev`'s `PackageJsonGenerator`](https://github.com/microsoft/aspire.dev/tree/9aa68083af47da79b63bc15b80f44c1927bf9c08/src/tools/PackageJsonGenerator) at commit `9aa68083af47da79b63bc15b80f44c1927bf9c08`.\n\nThe adapted source retains the upstream .NET Foundation and MIT license headers. Orleans-specific changes cover repository URL normalization, relevant Orleans attributes, project/package discovery, and local build orchestration.\n\n\n# Google Cloud emulators\n\nFirebase does not publish an official Emulator Suite container. Use the official Firebase CLI package instead.\n\nInstall Java 21 and Firebase CLI version 15.24.0:\n\n```shell\nnpm install --global firebase-tools@15.24.0\n```\n\nFrom this directory, start the configured emulators:\n\n```shell\nfirebase emulators:start --only firestore,pubsub,storage --project orleans-test\n```\n"}