@cratis/pi 7.102.0 → 7.103.1

package/package/corpus/skills/orleans/references/grains.md

@@ -0,0 +1,75 @@
+# Grains, State, and Runtime Primitives
+
+Use this reference when the main question is inside grain design rather than hosting or deployment.
+
+## Core Grain Modeling
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Start with the grain programming model | [Develop grains](https://learn.microsoft.com/dotnet/orleans/grains/) | Grain classes, interfaces, and the core programming surface |
+| Understand grain references | [Grain references](https://learn.microsoft.com/dotnet/orleans/grains/grain-references) | How grains are addressed and invoked |
+| Pick the right identity shape | [Grain identity](https://learn.microsoft.com/dotnet/orleans/grains/grain-identity) | Keys, namespaces, and identity semantics |
+| Understand default placement | [Grain placement](https://learn.microsoft.com/dotnet/orleans/grains/grain-placement) | Runtime placement model and locality tradeoffs |
+| Filter or constrain placement | [Grain placement filtering](https://learn.microsoft.com/dotnet/orleans/grains/grain-placement-filtering) | Placement filters and targeting rules |
+| Add extension points to grains | [Grain extensions](https://learn.microsoft.com/dotnet/orleans/grains/grain-extensions) | Grain extension patterns |
+| Generate serializers and proxies correctly | [Code generation](https://learn.microsoft.com/dotnet/orleans/grains/code-generation) | Codegen expectations and generated artifacts |
+
+## Timers, Reminders, and Execution Flow
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Choose timers vs reminders | [Timers and reminders](https://learn.microsoft.com/dotnet/orleans/grains/timers-and-reminders) | Activation-local timers versus durable reminders |
+| Schedule one-time future grain work | [Durable Jobs README](https://github.com/dotnet/orleans/blob/main/src/Orleans.DurableJobs/README.md) | Experimental at-least-once one-time scheduling, cancellation, retry, and shard ownership |
+| Push updates back to clients | [Observers](https://learn.microsoft.com/dotnet/orleans/grains/observers) | Grain observers and callback patterns |
+| Cancel grain work safely | [Cancellation tokens](https://learn.microsoft.com/dotnet/orleans/grains/cancellation-tokens) | Cancellation behavior across grain calls |
+| Reason about reentrancy and ordering | [Request scheduling](https://learn.microsoft.com/dotnet/orleans/grains/request-scheduling) | Scheduler rules, interleaving, and request ordering |
+| Flow ambient metadata | [Request context](https://learn.microsoft.com/dotnet/orleans/grains/request-context) | Request-scoped metadata across calls |
+| Hook into activation stages | [Grain lifecycle](https://learn.microsoft.com/dotnet/orleans/grains/grain-lifecycle) | Lifecycle stages and activation events |
+| Offload stateless fan-out | [Stateless worker grains](https://learn.microsoft.com/dotnet/orleans/grains/stateless-worker-grains) | Stateless scaling patterns |
+| Use external tasks safely | [External tasks and grains](https://learn.microsoft.com/dotnet/orleans/grains/external-tasks-and-grains) | Mixing Orleans scheduling with external async work |
+| Add interceptors or filters | [Interceptors](https://learn.microsoft.com/dotnet/orleans/grains/interceptors) | Cross-cutting interception points |
+| Create runtime helper services | [GrainServices](https://learn.microsoft.com/dotnet/orleans/grains/grainservices) | Cluster-local services for shared runtime behavior |
+| Use fire-and-forget deliberately | [One-way requests](https://learn.microsoft.com/dotnet/orleans/grains/oneway) | One-way call semantics and limits |
+
+## Persistence and State
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Choose grain state versus a query database | [Grain persistence](https://learn.microsoft.com/dotnet/orleans/grains/grain-persistence/) | Per-identity state loading/writing; use [persistence-api.md](persistence-api.md) for the query/read-model boundary |
+| Persist grain state | [Grain persistence](https://learn.microsoft.com/dotnet/orleans/grains/grain-persistence/) | Persistent state model and provider wiring |
+| Use operation-journaled durable collections | [Orleans.Journaling README](https://github.com/dotnet/orleans/blob/main/src/Orleans.Journaling/README.md) | Experimental durable dictionaries/lists/queues/sets/values and replay |
+| Use Azure Cosmos DB storage | [Azure Cosmos DB persistence](https://learn.microsoft.com/dotnet/orleans/grains/grain-persistence/azure-cosmos-db) | Cosmos-backed state provider setup |
+| Use relational storage | [Relational storage (ADO.NET)](https://learn.microsoft.com/dotnet/orleans/grains/grain-persistence/relational-storage) | SQL-backed provider options |
+| Use Azure Storage | [Azure storage persistence](https://learn.microsoft.com/dotnet/orleans/grains/grain-persistence/azure-storage) | Azure Table/Blob-backed state provider guidance |
+| Use DynamoDB | [Amazon DynamoDB storage](https://learn.microsoft.com/dotnet/orleans/grains/grain-persistence/dynamodb-storage) | DynamoDB-backed persistence options |
+
+## Event Sourcing
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Decide whether to use event sourcing | [Event sourcing overview](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/) | Journaled grain model and tradeoffs |
+| Start with `JournaledGrain` | [JournaledGrain basics](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/journaledgrain-basics) | Core journaled grain API and state evolution |
+| Diagnose journaled grains | [JournaledGrain diagnostics](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/journaledgrain-diagnostics) | Troubleshooting and diagnostics for journaled grains |
+| Choose confirmation mode | [Immediate vs delayed confirmation](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/immediate-vs-delayed-confirmation) | Consistency and confirmation tradeoffs |
+| Publish event notifications | [Notifications](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/notifications) | Observer/notification patterns for journaled grains |
+| Configure event sourcing | [Event sourcing configuration](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/event-sourcing-configuration) | Provider and configuration model |
+| Review built-in providers | [Built-in log-consistency providers](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/log-consistency-providers) | Available log consistency implementations |
+| Understand replicated instances | [Replicated instances](https://learn.microsoft.com/dotnet/orleans/grains/event-sourcing/replicated-instances) | Multi-instance replication behavior |
+
+## Transactions and Versioning
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Use transactional state | [Transactions](https://learn.microsoft.com/dotnet/orleans/grains/transactions) | Orleans ACID transaction model |
+| Plan contract evolution | [Grain versioning overview](https://learn.microsoft.com/dotnet/orleans/grains/grain-versioning/grain-versioning) | Interface and implementation versioning |
+| Preserve compatibility | [Backward compatibility guidelines](https://learn.microsoft.com/dotnet/orleans/grains/grain-versioning/backward-compatibility-guidelines) | Safe versioning rules |
+| Mark compatible implementations | [Compatible grains](https://learn.microsoft.com/dotnet/orleans/grains/grain-versioning/compatible-grains) | Compatibility declarations |
+| Control version selection | [Version selector strategy](https://learn.microsoft.com/dotnet/orleans/grains/grain-versioning/version-selector-strategy) | Version routing rules |
+| Roll out new grain versions | [Deploying new versions of grains](https://learn.microsoft.com/dotnet/orleans/grains/grain-versioning/deploying-new-versions-of-grains) | Deployment workflow for upgrades |
+
+## Usage Guidance
+
+- Start here when the dominant question is grain boundaries, runtime primitives, or state semantics.
+- Use [scheduling-and-services.md](scheduling-and-services.md) when deciding among timers, reminders, Durable Jobs, stateless workers, hosted services, startup tasks, and grain services.
+- Jump to [hosting.md](hosting.md) when the problem is cluster wiring, clients, observability, or deployment.
+- Jump to [implementation.md](implementation.md) when you need runtime-internals or testing details.

package/package/corpus/skills/orleans/references/hosting.md

@@ -0,0 +1,71 @@
+# Hosting, Configuration, and Operations
+
+Use this reference when the main question is about running Orleans, wiring providers, or operating a cluster.
+
+## Host and Client Entry Points
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Connect external processes to a cluster | [Clients](https://learn.microsoft.com/dotnet/orleans/host/client) | `UseOrleansClient`, gateways, and client topology |
+| Add operational visibility | [Dashboard](https://learn.microsoft.com/dotnet/orleans/dashboard/) | Orleans Dashboard setup and operational usage |
+| Wire Orleans through Aspire | [.NET Aspire integration](https://learn.microsoft.com/dotnet/orleans/host/aspire-integration) | AppHost resources, `.AsClient()`, and orchestration wiring |
+| Understand silo host stages | [Silo lifecycle](https://learn.microsoft.com/dotnet/orleans/host/silo-lifecycle) | Silo startup and shutdown lifecycle |
+| Run mixed silo roles | [Heterogeneous silos](https://learn.microsoft.com/dotnet/orleans/host/heterogeneous-silos) | Different silo capabilities in one cluster |
+| Reason about activation lookups | [Grain directory](https://learn.microsoft.com/dotnet/orleans/host/grain-directory) | Directory behavior and placement lookup mechanics |
+| Secure transport | [Transport Layer Security (TLS)](https://learn.microsoft.com/dotnet/orleans/host/transport-layer-security) | TLS between Orleans cluster participants |
+
+## Configuration Guide
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Start with cluster configuration | [Configuration overview](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/) | Main configuration surface |
+| Set up local development | [Local development configuration](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/local-development-configuration) | Dev cluster setup and local defaults |
+| Configure clients | [Client configuration](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/client-configuration) | Client-side settings and connectivity |
+| Configure silos | [Server configuration](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/server-configuration) | Silo-side options and runtime wiring |
+| Review common recipes | [Typical configurations](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/typical-configurations) | Canonical configuration examples |
+| Look up available options | [List of options classes](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/list-of-options-classes) | Option types exposed by Orleans |
+| Add metadata to silos | [Silo metadata](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/silo-metadata) | Metadata and node labeling |
+| Tune deactivation | [Activation collection](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/activation-collection) | Activation cleanup and collection rules |
+| Tune GC for Orleans | [Configure .NET garbage collection](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/configuring-garbage-collection) | GC recommendations for Orleans hosts |
+| Configure relational providers | [Configure ADO.NET providers](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/configuring-ado-dot-net-providers) | ADO.NET provider registration and setup |
+| Set up ADO.NET databases | [ADO.NET database configuration](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/adonet-configuration) | Database-side setup for Orleans SQL providers |
+| Understand Orleans serialization | [Serialization overview](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/serialization) | Serializer model and contracts |
+| Use immutable types | [Serialization of immutable types](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/serialization-immutability) | Immutable-type handling |
+| Configure serialization | [Configure serialization](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/serialization-configuration) | Serializer configuration switches |
+| Customize serializers | [Customize serialization](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/serialization-customization) | Custom serializers and codecs |
+| Run host-owned background work or startup hooks | [Background services and startup tasks](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/startup-tasks) | Prefer `BackgroundService`/`IHostedService`; use Orleans startup tasks only for lifecycle-specific fail-fast hooks |
+| Shut clusters down cleanly | [Graceful shutdown](https://learn.microsoft.com/dotnet/orleans/host/configuration-guide/shutting-down-orleans) | Drain and shutdown behavior |
+
+## Observability
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Start with monitoring | [Observability overview](https://learn.microsoft.com/dotnet/orleans/host/monitoring/) | Logs, metrics, and monitoring guidance |
+| Decode silo-side errors | [Silo error code monitoring](https://learn.microsoft.com/dotnet/orleans/host/monitoring/silo-error-code-monitoring) | Error-code reference for silo issues |
+| Decode client-side errors | [Client error code monitoring](https://learn.microsoft.com/dotnet/orleans/host/monitoring/client-error-code-monitoring) | Error-code reference for clients |
+
+Orleans 10.2 moved metrics access away from the removed static meter path. When upgrading code that directly referenced Orleans runtime metrics, resolve `OrleansInstruments` from DI and use its `Meter` instead of hardcoded static access.
+
+For `Orleans.Journaling`, JSON Lines is the default format for new writes in 10.2. Existing journals with stored format metadata continue to read correctly; pin `JournaledStateManagerOptions.JournalFormatKey` only when a deployment must keep writing the old binary format.
+
+## Deployment and Failures
+
+| Need | Official Source | What It Covers |
+|---|---|---|
+| Start from deployment basics | [Running the app](https://learn.microsoft.com/dotnet/orleans/deployment/) | Deployment overview and entry points |
+| Deploy to Azure App Service | [Azure App Service](https://learn.microsoft.com/dotnet/orleans/deployment/deploy-to-azure-app-service) | App Service hosting guidance |
+| Deploy to Azure Container Apps | [Azure Container Apps](https://learn.microsoft.com/dotnet/orleans/deployment/deploy-to-azure-container-apps) | ACA deployment shape |
+| Deploy to Kubernetes | [Kubernetes](https://learn.microsoft.com/dotnet/orleans/deployment/kubernetes) | K8s deployment and clustering |
+| Deploy to Service Fabric | [Service Fabric](https://learn.microsoft.com/dotnet/orleans/deployment/service-fabric) | Service Fabric runtime integration |
+| Handle cluster failures | [Handle failures](https://learn.microsoft.com/dotnet/orleans/deployment/handling-failures) | Failure modes and recovery patterns |
+| Deploy with Consul | [Consul deployments](https://learn.microsoft.com/dotnet/orleans/deployment/consul-deployment) | Consul-based clustering |
+| Troubleshoot deployments | [Troubleshoot deployments](https://learn.microsoft.com/dotnet/orleans/deployment/troubleshooting-deployments) | Common deployment diagnostics |
+| Troubleshoot legacy Azure Cloud Services | [Azure Cloud Services troubleshooting](https://learn.microsoft.com/dotnet/orleans/deployment/troubleshooting-azure-cloud-services-deployments) | Legacy deployment troubleshooting |
+
+## Usage Guidance
+
+- Start here when the problem is cluster wiring, clients, provider registration, or operational readiness.
+- Use [scheduling-and-services.md](scheduling-and-services.md) when ownership is unclear between per-host services, per-silo grain services, per-grain reminders/timers, or one-time Durable Jobs.
+- Use [grains.md](grains.md) when the problem is inside a grain rather than in the hosting model.
+- Use [implementation.md](implementation.md) when you need runtime internals, messaging guarantees, or testing behavior.
+- Use [testing-patterns.md](testing-patterns.md) when the hosting question is specifically about mixing Orleans, Aspire, `WebApplicationFactory`, SignalR, or Playwright in integration tests.