@cratis/pi 7.102.0 → 7.103.0

package/package/corpus/skills/msbuild/references/msbuild-antipatterns.md

@@ -0,0 +1,401 @@
+# MSBuild anti-pattern catalog
+
+## Contents
+
+- AP-01: Exec for operations with built-in tasks
+- AP-02: Unquoted string comparisons
+- AP-03: Hardcoded absolute paths
+- AP-04: Restating SDK defaults
+- AP-05: Redundant file lists in SDK-style projects
+- AP-06: Package DLL HintPaths instead of package references
+- AP-07: Build-only packages exposed to consumers
+- AP-08: Copy-pasted shared properties
+- AP-09: Unintended package-version drift
+- AP-10: Monolithic targets
+- AP-11: Untracked artifact-producing targets
+- AP-12: Defaults defined after their consumers
+- AP-13: Missing guards on optional imports
+- AP-14: Backslashes where path normalization does not apply
+- AP-15: Unexpected property overrides across scopes
+
+Based on the original msbuild antipatterns skill. The numbered catalog retains its
+smell, impact, and correction structure. Use relevant entries for troubleshooting or an
+explicit authoring review, not as a mandate to rewrite every matching pattern.
+
+Confirm evaluated behavior and exceptions before editing. Preserve framework/package versions,
+intentional overrides, item metadata, and public/output contracts. Legacy project-system
+migration is a separate task, not an automatic consequence of finding verbose XML.
+
+## AP-01: Exec for operations with built-in tasks
+
+**Smell:** shell `mkdir`, `copy`, or `del` commands in a target.
+
+**Impact:** shell-specific syntax, weak file-level logging, and more difficult incremental
+tracking. Built-in tasks integrate with MSBuild, but using one does not automatically make the
+containing target incremental.
+
+```xml
+<!-- BAD: shell-dependent file operations. -->
+<Target Name="PrepareOutput">
+  <Exec Command="mkdir $(OutputPath)logs" />
+  <Exec Command="copy config.json $(OutputPath)" />
+  <Exec Command="del $(IntermediateOutputPath)*.tmp" />
+</Target>
+
+<!-- GOOD: preserve the intended operation with built-in tasks. -->
+<Target Name="PrepareOutput">
+  <MakeDir Directories="$(OutputPath)logs" />
+  <Copy SourceFiles="config.json" DestinationFolder="$(OutputPath)" />
+  <ItemGroup>
+    <TempFiles Include="$(IntermediateOutputPath)*.tmp" />
+  </ItemGroup>
+  <Delete Files="@(TempFiles)" />
+</Target>
+```
+
+| Shell operation | MSBuild task |
+| --- | --- |
+| `mkdir` | `MakeDir` |
+| `copy` / `cp` / recursive copy | `Copy`, with the intended item set |
+| `del` / `rm` | `Delete`, scoped to known owned files |
+| `move` / `mv` | `Move` |
+| Write text | `WriteLinesToFile` |
+| Update a timestamp | `Touch` |
+
+Keep real external tools as tools, with correct quoting, platform support, and error handling.
+Preserve copy/reset semantics and never widen the deletion scope during this conversion.
+
+## AP-02: Unquoted string comparisons
+
+**Smell:** `Condition="$(Foo) == Bar"`.
+
+**Impact:** empty values or values containing spaces/special characters can change parsing.
+
+```xml
+<!-- BAD -->
+<PropertyGroup Condition="$(Configuration) == Release">
+  <Optimize>true</Optimize>
+</PropertyGroup>
+
+<!-- GOOD -->
+<PropertyGroup Condition="'$(Configuration)' == 'Release'">
+  <Optimize>true</Optimize>
+</PropertyGroup>
+```
+
+Quote both string operands. Do not flag valid boolean/function conditions merely because they
+are not string comparisons.
+
+## AP-03: Hardcoded absolute paths
+
+**Smell:** machine-specific tool or import paths.
+
+**Impact:** builds fail on another checkout, machine, or operating system.
+
+```xml
+<!-- BAD -->
+<PropertyGroup>
+  <ToolPath>C:\tools\mytool\mytool.exe</ToolPath>
+</PropertyGroup>
+<Import Project="C:\repos\shared\common.props" />
+
+<!-- GOOD: RepoRoot must be defined by the repository. -->
+<PropertyGroup>
+  <ToolPath>$(MSBuildThisFileDirectory)tools\mytool\mytool.exe</ToolPath>
+</PropertyGroup>
+<Import Project="$(RepoRoot)eng\common.props" />
+```
+
+| Property/function | Meaning |
+| --- | --- |
+| `MSBuildThisFileDirectory` | Directory of the file defining the current import/logic |
+| `MSBuildProjectDirectory` | Directory of the project being built |
+| `GetDirectoryNameOfFileAbove` / `GetPathOfFileAbove` | Find a repository marker or parent file |
+| `NormalizePath` / `NormalizeDirectory` | Combine and normalize path segments |
+
+Resolve relative paths against the intended owner, not an incidental caller working directory.
+
+## AP-04: Restating SDK defaults
+
+**Smell:** properties repeat the selected SDK's defaults.
+
+**Impact:** noise can obscure real overrides and accidentally pin behavior across SDK changes.
+
+```xml
+<!-- Potentially redundant for a library named MyLib with these SDK defaults. -->
+<PropertyGroup>
+  <OutputType>Library</OutputType>
+  <EnableDefaultItems>true</EnableDefaultItems>
+  <EnableDefaultCompileItems>true</EnableDefaultCompileItems>
+  <RootNamespace>MyLib</RootNamespace>
+  <AssemblyName>MyLib</AssemblyName>
+  <AppendTargetFrameworkToOutputPath>true</AppendTargetFrameworkToOutputPath>
+</PropertyGroup>
+
+<!-- Keep the settings that actually express the project's contract. -->
+<PropertyGroup>
+  <TargetFramework>net8.0</TargetFramework>
+</PropertyGroup>
+```
+
+Verify the actual SDK/imports, configurations, naming, and intentional pins first. A setting that
+matches today's default can still deliberately preserve behavior; do not remove it blindly.
+
+## AP-05: Redundant file lists in SDK-style projects
+
+**Smell:** explicit C#/VB source includes duplicate enabled SDK default items.
+
+**Impact:** duplicate items, merge noise, and source additions that can be missed when defaults
+have instead been disabled.
+
+```xml
+<!-- BAD when default Compile items already contain these files. -->
+<ItemGroup>
+  <Compile Include="Program.cs" />
+  <Compile Include="Services\MyService.cs" />
+</ItemGroup>
+
+<!-- GOOD: keep only intentional exclusions or metadata. -->
+<ItemGroup>
+  <Compile Remove="LegacyCode\**" />
+  <Compile Update="Services\MyService.cs" Visible="false" />
+</ItemGroup>
+```
+
+**Exceptions:** legacy projects, projects with default items intentionally disabled, linked files
+outside default globs, generated files, and items with special metadata need their actual contract
+preserved. `Update` modifies an existing item; it does not add a missing one.
+
+**F# is order-dependent.** Keep explicit `.fsproj` compile items in dependency order. An `.fsi`
+signature must immediately precede its matching `.fs`; the entry point is last. Do not apply C#
+implicit-glob cleanup to F#.
+
+## AP-06: Package DLL HintPaths instead of package references
+
+**Smell:** package assemblies referenced through a legacy `packages` directory.
+
+**Impact:** the project depends on a fixed restored layout instead of PackageReference asset
+selection. This is a migration candidate, not proof that existing packages.config restore is broken.
+
+```xml
+<!-- Legacy package reference. -->
+<Reference Include="Newtonsoft.Json">
+  <HintPath>..\packages\Newtonsoft.Json.13.0.3\lib\netstandard2.0\Newtonsoft.Json.dll</HintPath>
+</Reference>
+
+<!-- PackageReference replacement, when migration is authorized and compatible. -->
+<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+```
+
+Preserve package versions, conditions, content/build assets, and restore behavior. Do not remove
+GAC, local, or vendor assembly references just because they use `Reference` or `HintPath`.
+
+## AP-07: Build-only packages exposed to consumers
+
+**Smell:** a local analyzer/tool becomes an unwanted dependency or build asset of consumers.
+
+**Impact:** consumers can receive implementation-only dependencies or transitive build behavior.
+Inspect effective metadata and package assets; absence of a literal `PrivateAssets` attribute
+does not prove all analyzer assets propagate.
+
+Use `PrivateAssets="all"` for dependencies intended to remain entirely private. Preserve
+intentionally public/transitive build contracts. See
+[private-assets.md](antipatterns/private-assets.md) for examples and exceptions.
+
+## AP-08: Copy-pasted shared properties
+
+**Smell:** the same property block is repeated across several projects.
+
+**Impact:** inconsistent updates and unclear ownership.
+
+```xml
+<!-- Directory.Build.props at the intended shared scope. -->
+<Project>
+  <PropertyGroup>
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>
+```
+
+Move only genuinely shared values. Preserve project overrides and property evaluation timing.
+Only the nearest Directory.Build file is automatically discovered; see
+[extension-points](extension-points.md#directorybuild-discovery) before changing hierarchy.
+
+## AP-09: Unintended package-version drift
+
+**Smell:** projects unintentionally use different versions of the same package.
+
+**Impact:** divergent behavior, conflicts, and difficult dependency maintenance.
+
+```xml
+<!-- ProjectA.csproj -->
+<PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
+<!-- ProjectB.csproj -->
+<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+```
+
+Central Package Management can consolidate versions when that migration is requested; see
+[the NuGet guidance](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management).
+Keep intentional framework/project differences. Do not silently upgrade packages or centralize
+the whole repository while fixing an unrelated build.
+
+## AP-10: Monolithic targets
+
+**Smell:** one target mixes generation, copying, signing, and other unrelated operations.
+
+**Impact:** the steps cannot be scheduled, diagnosed, or skipped independently.
+
+```xml
+<!-- BAD: unrelated work in one target. -->
+<Target Name="PrepareRelease" BeforeTargets="Build">
+  <WriteLinesToFile File="version.txt" Lines="$(Version)" Overwrite="true" />
+  <Copy SourceFiles="LICENSE" DestinationFolder="$(OutputPath)" />
+  <Exec Command="signtool sign /f cert.pfx $(OutputPath)*.dll" />
+</Target>
+
+<!-- GOOD: separate responsibilities with their own contracts. -->
+<Target Name="WriteVersionFile" BeforeTargets="CoreCompile">
+  <MakeDir Directories="$(IntermediateOutputPath)" />
+  <WriteLinesToFile File="$(IntermediateOutputPath)version.txt"
+                    Lines="$(Version)" Overwrite="true" WriteOnlyWhenDifferent="true" />
+  <ItemGroup>
+    <FileWrites Include="$(IntermediateOutputPath)version.txt" />
+  </ItemGroup>
+</Target>
+<Target Name="CopyLicense" AfterTargets="CopyFilesToOutputDirectory">
+  <Copy SourceFiles="LICENSE" DestinationFolder="$(OutputPath)" SkipUnchangedFiles="true">
+    <Output TaskParameter="CopiedFiles" ItemName="FileWrites" />
+  </Copy>
+</Target>
+<Target Name="SignAssemblies" AfterTargets="Build" DependsOnTargets="CopyLicense"
+        Condition="'$(SignAssemblies)' == 'true'">
+  <ItemGroup>
+    <AssemblyFiles Include="$(OutputPath)*.dll" />
+  </ItemGroup>
+  <Error Condition="'@(AssemblyFiles)' == ''"
+         Text="Signing was requested, but no assemblies were found in '$(OutputPath)'." />
+  <Exec Command="signtool sign /f cert.pfx &quot;%(AssemblyFiles.Identity)&quot;" />
+</Target>
+```
+
+The cheap version writer intentionally checks the value each build: `Version` can change through
+global properties without any project-file timestamp changing. A project-file-only `Inputs`
+declaration would incorrectly reuse stale content. For expensive generation, model value changes
+with a stable input fingerprint as in [AP-11's example](antipatterns/incremental-build-inputs-outputs.md).
+
+Preserve original target order, supported platforms, required tools, and copy semantics.
+`SkipUnchangedFiles` is appropriate only when its timestamp/size heuristic satisfies the contract.
+Register the copied destinations in `FileWrites` before MSBuild records them for a subsequent
+`Clean`. Hooking `CopyLicense` after `CopyFilesToOutputDirectory` does this even for unchanged
+copies; registering them in an `AfterTargets="Build"` target would be too late.
+Discover the assemblies inside the signing target, after the build has produced them, rather
+than with an evaluation-time glob. This retains the original output-directory DLL selection.
+
+## AP-11: Untracked artifact-producing targets
+
+**Smell:** expensive file generation runs on every no-change build because its inputs/outputs are
+not modeled, or skips despite a relevant change.
+
+**Impact:** repeated work or stale outputs. Inputs must cover actual files and relevant property,
+configuration, generator, and import changes.
+
+See [incremental-build-inputs-outputs.md](antipatterns/incremental-build-inputs-outputs.md) for a
+correctness-oriented example, and [incremental-build](incremental-build.md) for full diagnosis.
+Cheap validation, orchestration, and item-discovery targets may legitimately run without
+file-based outputs; do not invent a stamp to suppress necessary work.
+
+## AP-12: Defaults defined after their consumers
+
+**Smell:** a default is set in a late import after another file already used it.
+
+**Impact:** consumers observe an empty or unintended earlier value.
+
+```xml
+<!-- custom.props: an early, overridable default. -->
+<PropertyGroup>
+  <MyToolVersion Condition="'$(MyToolVersion)' == ''">2.0</MyToolVersion>
+</PropertyGroup>
+
+<!-- custom.targets: execution using that setting. -->
+<Target Name="RunMyTool">
+  <Exec Command="mytool --version $(MyToolVersion)" />
+</Target>
+```
+
+`.props` normally carries early defaults; `.targets` normally carries later build logic.
+Timing matters more than the suffix: a value depending on a project-defined property must not
+move earlier than that property exists. See AP-21 in
+[additional anti-patterns](antipatterns/additional-antipatterns.md).
+
+## AP-13: Missing guards on optional imports
+
+**Smell:** an optional developer/environment override is imported unconditionally.
+
+**Impact:** a fresh checkout fails because a file that is optional by contract is absent.
+
+```xml
+<!-- Guard an optional override. -->
+<Import Project="$(RepoRoot)eng\local.props"
+        Condition="Exists('$(RepoRoot)eng\local.props')" />
+```
+
+**Required imports must fail when missing.** Do not add an existence guard to hide a missing SDK,
+required build file, or broken package contract.
+
+**NuGet forwarders need a packed-layout check.** Files in `build`/`buildTransitive` can import
+paths that do not exist in source but are created by `.nuspec` mappings, `PackagePath` metadata,
+or SDK pack conventions. First inspect the effective `NuspecFile`, `NuspecBasePath`, and
+`NuspecProperties`, including imports and global-property overrides. Follow the configured
+nuspec even outside the project tree and resolve its mappings with those settings. Only when
+no custom nuspec is configured, inspect nearby `.nuspec` files in the project and its immediate
+parent as a bounded fallback. Inspect the project's packaging items too; do not search unrelated
+ancestors or treat an unavailable configured nuspec as proof of a broken import.
+
+Only flag the target if it is absent from both applicable source and projected package layouts.
+See [source tree vs packed layout](extension-points.md#source-tree-vs-packed-layout).
+For per-TFM forwarders, derive the matched folder from the file's own location rather than the
+consumer's `TargetFramework`; see the [forwarding chain](extension-points.md#forwarding-chain).
+
+## AP-14: Backslashes where path normalization does not apply
+
+**Smell:** Windows separators in a path intended to reach a non-MSBuild consumer on another OS.
+
+**Correctness issue:** raw shell strings, generated source/response files, or custom tasks that
+use OS APIs directly may interpret backslashes differently.
+
+**Not automatically a correctness issue:** `Import` paths, item globs, and file paths consumed by
+built-in tasks use MSBuild path handling. An ordinary backslash-style import is not, by itself,
+a Linux failure.
+
+```xml
+<!-- A raw Windows shell/tool path needs actual platform support and quoting. -->
+<Exec Command="$(MSBuildThisFileDirectory)tools\release\sign.exe $(OutputPath)" />
+
+<!-- MSBuild handles this import path. Do not report a defect solely for its separators. -->
+<Import Project="$(MSBuildThisFileDirectory)..\..\build\common.props" />
+```
+
+Trace the consumer before assigning severity. `MSBuildThisFileDirectory` already ends with a
+separator; use path functions when constructing paths rather than concatenating arbitrary strings.
+
+## AP-15: Unexpected property overrides across scopes
+
+**Smell:** a shared value is unexpectedly replaced by another unconditional assignment.
+
+**Impact:** last-write behavior is difficult to explain and can alter output paths or options.
+
+```xml
+<!-- Directory.Build.props: a default that permits an existing value. -->
+<PropertyGroup>
+  <OutputPath Condition="'$(OutputPath)' == ''">bin\custom\</OutputPath>
+</PropertyGroup>
+```
+
+Trace assignments and consumers first. A project overriding a repository default can be
+intentional, and command-line global properties have different override semantics. Do not add
+conditions everywhere or change path-defining properties too late for their SDK/NuGet consumers.
+
+For AP-16 through AP-23 and the quick-reference checklist, read
+[additional-antipatterns.md](antipatterns/additional-antipatterns.md).

package/package/corpus/skills/orleans/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Managed Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/orleans/NOTICE

@@ -0,0 +1,64 @@
+Microsoft Orleans
+Copyright (c) 2026 Managed Code
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/managedcode/dotnet-skills/blob/2d8fba176a33b9872d5de35ec71d9ec71112ee26/catalog/Frameworks/Orleans/skills/orleans/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Precedence line spells out the `[Alias]` scope from `.cratis/ai/rules/orleans.md` (grain interfaces and methods vs serializer records).
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line with the skill-specific safety, ownership or compatibility caveat.
+- Scope upstream general workflow advice to this skill's stated task; it does not govern unrelated tasks.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+references/grain-api.md:
+- Qualify activation liveness for KeepAlive timers.
+- Clarify the resource-optimized placement default from Orleans 9.2, random before.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/implementation.md:
+- Clarify the resource-optimized placement default from Orleans 9.2, random before.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/patterns.md:
+- Use the modern timer extension receiver and GrainTimerCreationOptions overload in the batching example.
+- Correct the batching timer callback to Func<CancellationToken, Task>.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/serialization-api.md:
+- Correct the persistence serialization default to provider-specific, including Redis.
+- Correct the default-serializer code comment to include Redis.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/anti-patterns.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/configuration-api.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/official-docs-index.md:
+- Remove the release-notes list; point links at the main branch and drop version labels.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/persistence-api.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/scheduling-and-services.md:
+- Remove release-notes link; point links at the main branch; describe the prerelease suffix without a version.
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/streaming-api.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/testing-patterns.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/grains.md:
+- Point links at the main branch and drop version labels.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/orleans/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: orleans
+description: 'Designs Microsoft Orleans systems from each primitive''s purpose and failure model: grains, digital twins, state versus databases, transactions, messaging, streams, timers, reminders, Durable Jobs, stateless workers, grain services, startup, and hosting. Use when a task needs an Orleans design decision: inspect version and topology, choose the primitive, implement, and validate. Not for other actor stacks, batch processing, relational-only CRUD, or advice without an Orleans decision.'
+license: MIT
+---
+
+<!-- Modified by Cratis from managedcode's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/managedcode/dotnet-skills (catalog/Frameworks/Orleans/skills/orleans/SKILL.md; see NOTICE) -->
+
+# Microsoft Orleans
+
+Use only within this skill's stated task; general workflow advice does not apply to unrelated tasks. Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ. `.cratis/ai/rules/orleans.md` forbids `[Alias]` on grain interfaces and grain methods (it is used only on `[GenerateSerializer]` state and definition records that must survive a rename) and forbids `ConfigureAwait(false)` in grain code; **cratis-orleans-jobs** owns recoverable jobs. DurableJobs/Journaling are experimental and are not interchangeable with Cratis.Orleans jobs.
+
+## Diagnostic Output Budget
+
+Keep native test progress and ANSI visible; use the detected runner's supported flags (`--progress on --ansi on` for MTP/TUnit), not MTP switches on VSTest. Keep console logs at `Warning` or higher and one concise final summary. Do not replay progress redraws, successful-test output, or Information/Debug/Trace logs into model context. On failure/crash, show only the failing test/resource, root error, and relevant stack frames; deduplicate and cap each diagnostic response at 80 lines / 8 KiB. Never dump entire console/host/browser logs, HTML, TRX, or crash artifacts. Keep necessary artifacts size-bounded outside context, link them, and inspect exact bounded excerpts. Preserve the runner exit code through capture/filtering; disclose truncation. Silence alone does not establish a hang.
+
+## Start With Purpose
+
+Do not begin with an Orleans API. First state:
+
+1. the business identity that owns the behavior;
+2. the invariant and what must survive activation or cluster failure;
+3. the required consistency, query shape, acknowledgement, durability, replay, fan-out, and timing.
+
+Then select the smallest Orleans primitive whose guarantees match those requirements. Reject Orleans when the problem is primarily shared-memory computation, a finite batch, relational querying, or global coordination with few independent entities.
+
+Inspect package versions for version-sensitive work. Orleans `10.3.1` ships `Microsoft.Orleans.DurableJobs*` and `Microsoft.Orleans.Journaling*` as `10.3.1-alpha.1`; treat them as experimental until that status changes.
+
+Orleans 10.3 makes Newtonsoft storage enforce the type allow-list, changes RPC telemetry keys, and requires custom grain-context activators to apply configurators before construction. Prefer generated/allowed types over permissive JSON and update affected tests, dashboards, and activators together. `10.3.1` services analyzer contract identities and documents placement hints.
+
+## Mental Model
+
+- A **grain** is a virtual actor with stable identity, behavior, and optional state, not a process, row, DTO, controller, or background job.
+- A **grain reference** is a location-transparent address. Getting a reference does not create a durable record or prove that an activation exists.
+- An **activation** is an ephemeral in-memory execution instance. Orleans creates, places, moves, deactivates, and recreates it. Never equate activation lifetime with entity lifetime.
+- A normal grain has at most one activation in the cluster by default and processes turns one at a time. This makes the grain a natural owner of per-identity invariants.
+- A **silo** hosts activations. Silos form a cluster; external clients or a co-hosted `IGrainFactory` call grains.
+- Calls are asynchronous messages even when they look like C# method calls. Network failure, timeout, serialization, retries, and duplicate side effects still matter.
+- A grain can model a **digital twin** when its identity and behavior map to a real or domain entity; that is a use case, not every grain's definition.
+- Orleans gives logical ownership and turn-based execution. It does not make external side effects transactional, turn arbitrary data into a queryable database, or provide exactly-once execution by default.
+
+## Workflow
+
+1. Inspect the solution, Orleans version, hosting topology, grain interfaces, providers, and tests.
+2. Identify domain identities and invariants. Prefer many independent, bounded entities over global coordinator grains.
+3. Choose state, communication, and time-based work from the tables below.
+4. Keep default non-reentrant scheduling and placement until a measured requirement justifies a change.
+5. Configure providers independently and test the failure model the design depends on.
+
+## Choose the State Owner
+
+| Primitive | Purpose | Choose it when | Do not use it as |
+|---|---|---|---|
+| Activation fields | Fast, temporary state for one activation | The value is derived, cached, disposable, or safe to rebuild after deactivation/failure | Durable truth |
+| `IPersistentState<T>` | Durable current state owned by one grain identity | The grain needs a bounded snapshot loaded on activation and explicitly written after commands | A general query database or cross-grain table |
+| External database/repository | Queryable, indexed, relational, bulk, shared, or externally owned data | The system needs joins, search, reporting, set-based updates, independent access, or an existing system of record | A replacement for grain ownership when serialized per-entity decisions are still required |
+| Grain plus database/read model | Separate command ownership from query/storage concerns | A grain owns invariants and a small control snapshot while a database owns large records, history, projections, or reporting | Two competing sources of truth without an explicit contract |
+| `JournaledGrain<TState,TEvent>` | Persist domain events and reconstruct state | Audit history, business-event replay, log consistency, or multi-cluster event-sourced replication is a requirement | A default persistence choice for ordinary CRUD state |
+| `Orleans.Journaling` durable states | Replay durable collection/value operations through a journal | The experimental 10.3 journaling model, durable collections, or durable completion state solves a measured need | Stable default persistence; it is distinct from `JournaledGrain` business event sourcing |
+| `ITransactionalState<T>` | ACID, serializable all-or-nothing changes across transactional grain state | A short operation must atomically update multiple grain-owned states and compensation is unacceptable | Long-running workflows or atomicity with arbitrary external systems |
+| Saga/process manager | Durable progress with compensation across steps and external systems | Work is long-running, spans services, waits for events, or cannot share one transaction | Instant atomic commit |
+
+### Grain State Versus a Database
+
+Use grain state for bounded current state and per-identity invariants. Use a database/read model for joins, search, reporting, bulk work, history, shared access, or an external system of record. When using both, define one authority per field and recovery rules.
+
+Never query or mutate another grain's persistence record behind the grain, or expose provider storage as the public query model merely because it uses SQL/Cosmos/Redis. Before using transactions, try one bounded grain owner; use a saga for external effects or long waits. Read [references/persistence-api.md](references/persistence-api.md) for the full boundary.
+
+## Choose Communication
+
+Prefer a direct call for completion to a known owner. Use streams for decoupled provider-backed delivery, response streams for one caller, and broadcast/observers/one-way calls only for loss-tolerant notifications. A timeout does not prove whether an external effect committed; retries require idempotency. Read [references/primitive-selection.md](references/primitive-selection.md) for the communication guarantees and execution choices.
+
+## Choose Time-Based and Background Work
+
+| Primitive | Purpose | Choose it when | Do not choose it when |
+|---|---|---|---|
+| `RegisterGrainTimer` | Periodic or one-shot work tied to the current activation | Work is frequent, local to an active grain, and safe to stop on deactivation or silo failure | The schedule must survive reactivation/restart |
+| Reminder | Durable recurring schedule definition associated with a grain identity | Low-frequency recurring work must wake the grain after deactivation or cluster restart | Every missed occurrence must be replayed, timing must be precise, or work is high-frequency |
+| Durable Job | Persistent one-time future delivery to a target grain with cancellation/retry metadata | A delayed command, expiry, notification, or workflow step must execute at least once around a due time | Recurring work, exactly-once side effects, or production work that cannot accept the current alpha package status |
+| `[StatelessWorker]` | Auto-scaled pool of local stateless grain activations | CPU/transform/routing/pre-aggregation work is not tied to one durable entity | Scheduling or durability; a stateless worker is not a job system |
+| `BackgroundService` | Continuous loop owned by each host process | A silo/web host must poll or consume an external source and forward work into grains | One global loop across replicas unless duplicates are safe or externally coordinated |
+| `IHostedService` | Host startup/shutdown action or simpler background component | Initialization or bounded host-lifetime work belongs to standard .NET hosting | Per-entity durable work |
+| Orleans startup task | Fail-fast hook at a specific silo startup stage | Legacy/framework integration truly requires Orleans lifecycle ordering | General background work; prefer `BackgroundService` or `IHostedService` |
+| Silo lifecycle participant | Ordered initialization/shutdown of an Orleans component | A provider or runtime service must start at an exact lifecycle stage | Business scheduling |
+| Grain service | Per-silo, cluster-partitioned runtime support service | Every silo hosts a long-lived service and responsibility for grains must be partitioned across silos | An ordinary domain entity, a singleton, or a durable job queue |
+| External scheduler/workflow engine | Scheduling/orchestration outside Orleans | Cross-system workflows, cron calendars, human steps, broad operational control, or mature production guarantees dominate | Per-grain work already solved by a stable Orleans primitive |
+
+### Timer, Reminder, or Durable Job
+
+Timer means “while this activation lives”; reminder means “wake this grain on a durable recurring schedule”; Durable Job means “invoke this target once around a future time, at least once.” Reminders persist definitions but miss ticks while the cluster is down. Durable Job handlers must be idempotent, and current `alpha.1` packages are an explicit architecture risk.
+
+`BackgroundService` means one loop per host replica, not one loop per cluster. Use a well-known grain or external lease/leader for one logical collector.
+
+Read [references/scheduling-and-services.md](references/scheduling-and-services.md) before implementing timers, reminders, Durable Jobs, hosted/startup tasks, silo lifecycle participants, or grain services.
+
+## Choose Execution and Scaling
+
+Use standard grains for stateful identities and stateless workers for fungible work. Apply narrow interleaving attributes only after auditing invariants across every `await`; grain turns do not make reentrant workflows race-free. Preserve default placement unless a measured locality or compatibility requirement justifies changing it. See [references/primitive-selection.md](references/primitive-selection.md) before changing scheduling or placement.
+
+## Hosting and Provider Boundaries
+
+Keep concerns separate: clustering discovers silos; the grain directory locates activations; grain/reminder/transaction/job storage persist different records; stream providers carry events while `PubSubStore` tracks subscriptions; serialization defines wire and persistence compatibility.
+
+In-memory clustering, storage, reminders, streams, Durable Jobs, and journaling are development/test choices unless loss is explicitly acceptable. Configure production providers, credentials, TLS/networking, server GC, graceful shutdown, and health/readiness for the deployment target. In Aspire, declare backing resources in AppHost and register the keyed clients expected by Orleans providers.
+
+## Contract and API Rules
+
+- Keep grain interfaces coarse-grained and asynchronous: `Task`, `Task<T>`, `ValueTask<T>`, or supported `IAsyncEnumerable<T>`.
+- Cancellation is cooperative, not proof that work did not finish.
+- Use `[GenerateSerializer]` and stable `[Id(N)]` values on messages/state. Use `[Alias]` for durable type identity and `[Immutable]` only for genuinely immutable values.
+- Never reuse removed field IDs; write state explicitly and propagate storage failures.
+- Bound external calls and use idempotency plus a saga/outbox when state writes and external effects must be reconciled.
+
+## Validate the Chosen Guarantees
+
+- Grain boundaries follow business identity and avoid hot global coordinators.
+- State is bounded, and the grain-state-versus-database choice is explicit.
+- Every time primitive matches activation, recurrence, durability, and delivery requirements.
+- Durable Job handlers/retried commands are idempotent; reminders tolerate missed ticks.
+- Broadcast channels, observers, and one-way calls carry only loss-tolerant signals.
+- Provider-backed tests prove delivery, ordering, replay, and failover claims.
+- Reentrancy tests cover state across `await`; transactions use transactional storage, `[Reentrant]`, and `PerformRead`/`PerformUpdate`.
+- Hosted services are reviewed for per-replica duplication.
+- Production uses persistent providers, multi-silo tests, and observability wherever the guarantee depends on them.
+
+## Load References
+
+Open only the references needed for the selected primitive:
+
+- [references/official-docs-index.md](references/official-docs-index.md) — official documentation map
+- [references/scheduling-and-services.md](references/scheduling-and-services.md) — scheduled/background/runtime work
+- [references/grains.md](references/grains.md) and [references/grain-api.md](references/grain-api.md) — grain design and APIs
+- [references/persistence-api.md](references/persistence-api.md) — state, databases, Journaling, event sourcing, transactions
+- [references/streaming-api.md](references/streaming-api.md) — streams, broadcast, observers, response streams
+- [references/serialization-api.md](references/serialization-api.md) — serialization and versioning
+- [references/hosting.md](references/hosting.md) and [references/configuration-api.md](references/configuration-api.md) — hosting, providers, operations
+- [references/implementation.md](references/implementation.md) and [references/testing-patterns.md](references/testing-patterns.md) — runtime and tests
+- [references/patterns.md](references/patterns.md), [references/anti-patterns.md](references/anti-patterns.md), and [references/examples.md](references/examples.md) — patterns and samples
+
+Prefer Learn for stable APIs. For Durable Jobs and `Orleans.Journaling`, use version-tagged package READMEs/public API because Learn does not yet cover them fully.