@cratis/pi 2.0.9 → 2.0.11

package/package/corpus/agents/code-reviewer.md

@@ -51,6 +51,7 @@ When checking unused code, references, or naming, use semantic navigation if the
 - [ ] No shared state between commands
 - [ ] No service locator (`IServiceProvider` not injected); `IInstancesOf<T>` (not `IEnumerable<T>`) for discovering implementations
 - [ ] No explicit singleton registration when `[Singleton]` attribute suffices
+- [ ] No `[Singleton]` takes a scoped dependency (event store and anything off it, MongoDB collection/database/client, `DbContext`, read model by key) — such a type is transient or scoped instead
 - [ ] Logging is in a separate `*Logging.cs` partial file with `[LoggerMessage]`
 
 ## C# Commands checklist

package/package/corpus/rules/csharp.md

@@ -133,11 +133,17 @@ The framework discovers and wires dependencies by convention. Explicit registrat
 - Systems with a convention of `IFoo → Foo` do not need to be registered explicitly.
 - Command/query `Handle()` method parameters are automatically resolved from DI by type.
 
-### Service lifetimes — `[Singleton]` is a narrow choice, not the default
+### Service lifetimes — anything taking a scoped dependency is scoped or transient, never a singleton
+
+**The rule, before any of the reasoning:**
+
+> **A type that takes a scoped dependency is itself scoped or transient. If you are reaching for `[Singleton]` on something that needs the event store, a database, or a read model, the answer is to not make it a singleton.**
+
+`[Singleton]` is the exception, not the default. It is for what is genuinely process-wide *and* holds nothing belonging to a tenant, a user, or a request. Everything else takes the convention (transient) or `[Scoped]`, and inherits the resolving scope — and therefore the right tenant — for free.
 
 **Assume every application you build is multi-tenant.** Not "design for it later" — assume it now, even when the deployment ships with a single tenant and no tenant resolution configured. A single-tenant application is a multi-tenant one with one tenant in it, and the code shape that serves both is the same shape. The code shape that serves only one has to be found and rewritten later, from the far side of a data migration, under production. The same reasoning applies to the signed-in user: an application always has one, and a service that remembers *which* one will eventually answer for the wrong person.
 
-That gives one rule with two faces:
+So the rule has a second face:
 
 > **A singleton may not depend on anything that belongs to a tenant, a user, or a request.**
 
@@ -155,9 +161,9 @@ A `[Singleton]` taking one of these is a **captive dependency**: the container h
 
 **It does not throw. It returns nothing.** A query against the wrong namespace hits a database that exists and is empty, so the caller gets an empty collection, a `null` read model, or a default-valued options object, and carries on. The application starts, the pages render, the build is green, and the configuration a tenant spent an afternoon entering is simply not there. It is also invisible while there is only one tenant — every symptom appears on the day a second one arrives.
 
-**What to use instead.** Default to the convention (transient), which inherits the resolving scope's tenant for free, or `[Scoped]` when a service must be shared within one request. Reserve `[Singleton]` for things that are genuinely process-wide and hold no tenant-, user-, or request-bound state: `IInstancesOf<T>` aggregators, HTTP client wrappers, `IOptions<T>` readers, pure computation, framework plumbing.
+**What to do instead — in this order.**
 
-When something must be a singleton and still needs data — a hosted service, a dispatcher, a poller — inject `IServiceScopeFactory` and open a scope per unit of work:
+**1. Drop `[Singleton]`.** This is the answer almost every time. Delete the attribute and let the type be transient by convention, or mark it `[Scoped]` when one request should share one instance. Nothing else changes: the constructor keeps the collaborator it wanted, and now gets the caller's tenant instead of the root scope's.
 
 ```csharp
 // ❌ Wrong — IEventStore is scoped; this captures the root scope's default namespace forever.
@@ -168,19 +174,35 @@ public class DigestSources(IEventStore eventStore) : IDigestSources
         eventStore.ReadModels.GetInstanceById<DigestConfiguration>(DigestId.Default);
 }
 
-// ✅ Right — a scope per call, so the collaborators bind to the caller's tenant.
-[Singleton]
-public class DigestSources(IServiceScopeFactory scopeFactory) : IDigestSources
+// ✅ Right — no attribute at all. Transient by convention, so it resolves in the caller's scope
+// and reads that caller's tenant. There was never a reason for this to be process-wide.
+public class DigestSources(IEventStore eventStore) : IDigestSources
+{
+    public Task<DigestConfiguration?> GetCurrent() =>
+        eventStore.ReadModels.GetInstanceById<DigestConfiguration>(DigestId.Default);
+}
+```
+
+**2. Only when the lifetime is forced on you, open a scope per unit of work.** A hosted service or `BackgroundService` is resolved once by the host, so it *is* a singleton whether or not you asked — and it runs with no request to inherit a scope from. That, and only that, is what `IServiceScopeFactory` is for:
+
+```csharp
+// ✅ Right for a hosted service — a scope per unit of work, so collaborators bind to a real scope.
+public class DigestDispatcher(IServiceScopeFactory scopeFactory) : BackgroundService
 {
-    public async Task<DigestConfiguration?> GetCurrent()
+    protected override async Task ExecuteAsync(CancellationToken cancellationToken)
     {
-        using var scope = scopeFactory.CreateScope();
-        var eventStore = scope.ServiceProvider.GetRequiredService<IEventStore>();
-        return await eventStore.ReadModels.GetInstanceById<DigestConfiguration>(DigestId.Default);
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            using var scope = scopeFactory.CreateScope();
+            var eventStore = scope.ServiceProvider.GetRequiredService<IEventStore>();
+            await Dispatch(eventStore, cancellationToken);
+        }
     }
 }
 ```
 
+⚠️ **`IServiceScopeFactory` is not a way to keep `[Singleton]` on a service that had no reason to be one.** It is more code, it hides the lifetime question behind a scope nobody asked for, and — because a scope with no request still resolves no tenant — it does not by itself make an off-request flow tenant-correct. Reaching for it first is how a codebase ends up with dozens of these — a sweep of a real application found several dozen singletons holding a scoped service, not one of which needed to be a singleton at all. If the type is not the host's own, the fix is the attribute, not the factory.
+
 `IChronicleClient` **is** singleton-safe, and is the right collaborator when a flow knows which namespace it means and has no scope to resolve one from — it names the event store and namespace explicitly: `await chronicleClient.GetEventStore("MyStore", tenantId.Value)`. Naming the namespace is a deliberate, readable statement that this code crosses a tenant boundary; capturing a scoped service is the same crossing made by accident.
 
 **The current user is not process-wide either.** Never keep the signed-in user, their principal, claims, roles, or anything derived from them in a singleton. The distinction that matters: *the accessor is fine, the value is not.* `IHttpContextAccessor` is itself a singleton and safe to inject; reading a value out of it once and keeping it is not. A current-user service may be a singleton only when every method reads through the accessor on each call and stores nothing. Anything that derives something per user and wants to keep it holds a cache **keyed by the user**, never a single field.
@@ -189,9 +211,21 @@ public class DigestSources(IServiceScopeFactory scopeFactory) : IDigestSources
 
 **Caching.** A process-wide cache of tenant data is the same bug wearing a performance justification. If a singleton caches, the tenant (and where relevant the user) is part of the key. The same holds for `static` fields: a `static` cache of anything tenant-scoped is shared by every tenant in the process.
 
-**Enforce it, do not remember it.** This failure is silent, so review will not reliably catch it. Add an architecture spec that reflects over the assembly, finds every `[Singleton]` whose constructor takes a scope-bound service, and asserts the set is empty. It is a few dozen lines, it runs on every build, and it is the only thing that keeps the rule true a year from now.
+**Enforce it, do not remember it.** This failure is silent, so review will not reliably catch it. Two gates, and an application wants both:
+
+**Turn .NET's own scope validation on in every environment, not just Development.** `ServiceProviderOptions.ValidateScopes` rejects resolving a scoped service from the root provider, and `ValidateOnBuild` walks every registration at startup so a captive dependency fails the host immediately rather than at whichever request first happens to need it. The host enables both in Development by default and **neither outside it** — which is exactly backwards for a failure whose whole character is that it stays quiet:
+
+```csharp
+builder.Host.UseDefaultServiceProvider(options =>
+{
+    options.ValidateScopes = true;
+    options.ValidateOnBuild = true;
+});
+```
+
+Enable it on an existing codebase in this order, or it will simply refuse to start: turn it on locally first, fix everything it names, and only then let it reach the deployed environments. Turning it on *before* the sweep converts a silent multi-tenant bug into a production outage, which is a worse trade, not a braver one.
 
-> .NET's own captive-dependency detection (`ServiceProviderOptions.ValidateScopes`, which Arc deliberately leaves on in Development) exists to catch exactly this. If a singleton in your codebase holds a scoped service and Development startup is not complaining, that path is not being exercised in Development — worth knowing on its own.
+**And add an architecture spec**, because validation only catches what a run actually resolves. Reflect over the assembly, find every `[Singleton]` whose constructor takes a scope-bound service, and assert the set is empty. It is a few dozen lines, it names every offender in one pass rather than one per restart, and it holds for the types no startup path touches.
 
 ### Discovering multiple implementations — use `IInstancesOf<T>`, never `IEnumerable<T>`
 

package/package/corpus/rules/general.md

@@ -258,7 +258,7 @@ Documentation-only changes use repository-supported non-release intent, ordinari
 | **Contributing to a Cratis framework repo** (framework profile) | `framework.md` |
 | Slice anatomy (commands, `Provide()`, validators, events, projections, read models, reactors, constraints, compliance, cross-slice) | `vertical-slices.md` |
 | C# / TypeScript style | `csharp.md`, `typescript.md` |
-| Service lifetimes — what a singleton may never hold (tenant, user, request state) | `csharp.md` |
+| Service lifetimes — why anything taking a scoped dependency is scoped or transient, never a singleton | `csharp.md` |
 | React + Arc + Cratis Components + MVVM + dialogs | `react.md`, `components.md`, `dialogs.md` |
 | Frontend engineering quality & testing | `frontend-quality.md`, `frontend-testing.md`, `storybook.md` |
 | Spec patterns — universal `Specification` base (both profiles) | `specs.md`, `specs.csharp.md`, `specs.typescript.md` |

package/package/corpus/rules/pull-requests.md

@@ -6,6 +6,8 @@ applyTo: "**/*"
 
 PR descriptions serve two purposes: they help reviewers understand the change *now*, and they become the release notes that users read *later*. Write them with both audiences in mind.
 
+**The description is the release note — it is published verbatim.** Write it as the note you want the person upgrading to read, in the repository template's sections. A generic development write-up (`## Summary`, `## Verification`, `## Testing`, a list of the files you touched, a description of how you arrived at the change) is not a release note, and shipping one makes the release history unreadable. The same applies wherever a release is produced by hand: release-notes text typed into a manual workflow run, or written straight into a published release, carries exactly the same shape and the same audience as a PR description. There is no path to a release whose notes are allowed to describe the work instead of the change.
+
 ## Description
 
 - Follow the repository's pull request template (`.github/pull_request_template.md`).

package/package/corpus/skills/cratis-code-review/SKILL.md

@@ -66,6 +66,10 @@ there is nothing to review under a red build.
 - No service locator: `IServiceProvider` is not injected. Implementation sets
   come from `IInstancesOf<T>`, never `IEnumerable<T>`.
 - No explicit singleton registration where `[Singleton]` suffices.
+- No `[Singleton]` takes a scoped dependency — the event store and anything off
+  it, a MongoDB collection/database/client, a `DbContext`, a read model by key.
+  Such a type is transient or scoped instead; `IServiceScopeFactory` is only for
+  a service the host itself resolves once.
 - Logging lives in a `*Logging.cs` partial with `[LoggerMessage]`, not inline in
   domain code.
 - No shared mutable state between commands.

package/package/corpus/skills/cratis-engineering-csharp-conventions/SKILL.md

@@ -100,10 +100,12 @@ Read the reference that covers the decision at hand rather than all three.
 
 ## The two rules most often got wrong
 
-**`[Singleton]` is a narrow choice, not the default.** A singleton may not
-depend on anything that belongs to a tenant, a user, or a request. Capturing a
-scoped collaborator does not throw — it silently binds to the root scope's
-default namespace forever and returns empty results. See
+**Anything taking a scoped dependency is scoped or transient, never a
+singleton.** A singleton may not depend on anything that belongs to a tenant, a
+user, or a request. Capturing a scoped collaborator does not throw — it silently
+binds to the root scope's default namespace forever and returns empty results.
+The fix is almost always to drop `[Singleton]`, not to reach for
+`IServiceScopeFactory`. See
 [exceptions-logging-and-di.md](references/exceptions-logging-and-di.md).
 
 **Use `IInstancesOf<T>`, never `IEnumerable<T>`, to enumerate implementations of
@@ -123,7 +125,9 @@ hand-registered, which defeats convention-based discovery.
   non-nullable annotation.
 - Every public type, method, property, and operator carries multiline XML
   documentation with `<param>` and `<returns>` where applicable.
-- No `[Singleton]` holds tenant-, user-, or request-bound state.
+- No `[Singleton]` takes a scoped dependency or holds tenant-, user-, or
+  request-bound state, and the host sets `ValidateScopes` and `ValidateOnBuild`
+  in every environment.
 - No `services.Add*<TInterface, TImplementation>()` registers a type that exists
   to be discovered by convention.
 - Text is American English.

package/package/corpus/skills/cratis-engineering-csharp-conventions/references/exceptions-logging-and-di.md

@@ -88,7 +88,18 @@ public class <ClassName>(IServiceProvider provider)
 }
 ```
 
-## Service lifetimes — `[Singleton]` is a narrow choice
+## Service lifetimes — anything taking a scoped dependency is scoped or transient
+
+**The rule, before any of the reasoning:**
+
+> **A type that takes a scoped dependency is itself scoped or transient. If you
+> are reaching for `[Singleton]` on something that needs the event store, a
+> database, or a read model, the answer is to not make it a singleton.**
+
+`[Singleton]` is the exception, not the default. It is for what is genuinely
+process-wide *and* holds nothing belonging to a tenant, a user, or a request.
+Everything else takes the convention (transient) or a scoped lifetime, and
+inherits the resolving scope — and therefore the right tenant — for free.
 
 **Assume every application is multi-tenant**, even when it ships with a single
 tenant and no tenant resolution configured. A single-tenant application is a
@@ -96,7 +107,7 @@ multi-tenant one with one tenant in it, and the code shape that serves both is
 the same. The shape that serves only one has to be found and rewritten later,
 from the far side of a data migration, in production.
 
-That gives one rule with two faces:
+So the rule has a second face:
 
 > **A singleton may not depend on anything that belongs to a tenant, a user, or
 > a request.**
@@ -124,16 +135,15 @@ on. The application starts, pages render, the build is green, and configuration
 a tenant spent an afternoon entering is simply absent. It is invisible while
 there is one tenant; every symptom appears the day a second arrives.
 
-**What to use instead.** Default to the convention (transient), which inherits
-the resolving scope's tenant for free, or a scoped lifetime when a service must
-be shared within one request. Reserve `[Singleton]` for what is genuinely
-process-wide and holds no tenant-, user-, or request-bound state: implementation
-aggregators, HTTP client wrappers, options readers, pure computation, framework
-plumbing.
+**What to do instead — in this order.**
 
-When something must be a singleton and still needs data — a hosted service, a
-dispatcher, a poller — inject `IServiceScopeFactory` and open a scope per unit
-of work:
+**1. Drop `[Singleton]`.** This is the answer almost every time. Delete the
+attribute and let the type be transient by convention, or mark it scoped when
+one request should share one instance. Nothing else changes: the constructor
+keeps the collaborator it wanted, and now gets the caller's tenant instead of
+the root scope's. Reserve `[Singleton]` for what is genuinely process-wide and
+holds no tenant-, user-, or request-bound state: implementation aggregators,
+HTTP client wrappers, options readers, pure computation, framework plumbing.
 
 ```csharp
 // Wrong — the scoped collaborator captures the root scope's default namespace forever
@@ -143,21 +153,41 @@ public class <ClassName>(<IScopedCollaboratorType> <collaborator>) : <IInterface
     public Task<<ResultType>?> <MethodName>() => <collaborator>.<Method>(<argument>);
 }
 
-// Right — a scope per call, so collaborators bind to the caller's tenant
-[Singleton]
-public class <ClassName>(IServiceScopeFactory scopeFactory) : <IInterfaceName>
+// Right — no attribute at all. Transient by convention, so it resolves in the
+// caller's scope and reads that caller's tenant.
+public class <ClassName>(<IScopedCollaboratorType> <collaborator>) : <IInterfaceName>
 {
-    public async Task<<ResultType>?> <MethodName>()
+    public Task<<ResultType>?> <MethodName>() => <collaborator>.<Method>(<argument>);
+}
+```
+
+**2. Only when the lifetime is forced on you, open a scope per unit of work.** A
+hosted or background service is resolved once by the host, so it *is* a
+singleton whether or not you asked — and it runs with no request to inherit a
+scope from. That, and only that, is what `IServiceScopeFactory` is for:
+
+```csharp
+// Right for a hosted service — a scope per unit of work
+public class <ClassName>(IServiceScopeFactory scopeFactory) : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken cancellationToken)
     {
         using var scope = scopeFactory.CreateScope();
         var <collaborator> = scope.ServiceProvider
             .GetRequiredService<<IScopedCollaboratorType>>();
 
-        return await <collaborator>.<Method>(<argument>);
+        await <collaborator>.<Method>(<argument>);
     }
 }
 ```
 
+`IServiceScopeFactory` is **not** a way to keep `[Singleton]` on a service that
+had no reason to be one. It is more code, it hides the lifetime question behind
+a scope nobody asked for, and — because a scope with no request still resolves
+no tenant — it does not by itself make an off-request flow tenant-correct.
+Reaching for it first is how a codebase ends up with dozens of these. If the
+type is not the host's own, the fix is the attribute, not the factory.
+
 A client that names its store and namespace explicitly **is** singleton-safe,
 and is the right collaborator when a flow knows which namespace it means and has
 no scope to resolve one from. Naming the namespace is a deliberate, readable
@@ -180,6 +210,36 @@ collaborators they call are not — a flow that reaches a tenant-blind singleton
 has left its namespace behind without saying so. Such a flow states its tenant
 explicitly rather than inheriting whatever the root scope happens to be.
 
+**Enforce it, do not remember it.** This failure is silent, so review will not
+reliably catch it. Two gates, and an application wants both.
+
+Turn .NET's own scope validation on in **every** environment, not just
+Development. `ValidateScopes` rejects resolving a scoped service from the root
+provider, and `ValidateOnBuild` walks every registration at startup so a captive
+dependency fails the host immediately rather than at whichever request first
+needs it. The host enables both in Development by default and neither outside
+it — which is backwards for a failure whose whole character is that it stays
+quiet:
+
+```csharp
+builder.Host.UseDefaultServiceProvider(options =>
+{
+    options.ValidateScopes = true;
+    options.ValidateOnBuild = true;
+});
+```
+
+Enable it on an existing codebase in this order, or it will simply refuse to
+start: turn it on locally first, fix everything it names, and only then let it
+reach the deployed environments. Turning it on before the sweep converts a
+silent multi-tenant bug into a production outage.
+
+And add an architecture specification, because validation only catches what a
+run actually resolves. Reflect over the assembly, find every `[Singleton]` whose
+constructor takes a scope-bound service, and assert the set is empty. It names
+every offender in one pass rather than one per restart, and it covers the types
+no startup path touches.
+
 ## Discovering implementations — `IInstancesOf<T>`, never `IEnumerable<T>`
 
 When a type needs every implementation of an abstraction — handlers, strategies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [