@cratis/pi 2.21.3 → 2.23.0

package/package/corpus/rules/orleans.md

@@ -10,41 +10,27 @@ paths:
 > **⚠️ APPLIES ONLY TO PROJECTS USING MICROSOFT ORLEANS**
 > If your project does not reference `Microsoft.Orleans` or any Orleans packages, **ignore this entire file**. These rules are irrelevant outside of Orleans contexts.
 
-These conventions apply to projects that use Microsoft Orleans for distributed grain-based actors.
+In the Cratis organization, Orleans is the Chronicle kernel's actor runtime (`Source/Kernel/`). These conventions describe how that kernel is shaped, verified against `Cratis/Chronicle` **v18.3.0**; follow them in any Cratis repository that hosts Orleans grains.
 
 ## General
 
-- Do **not** split Orleans grain interfaces into a separate project. Keep all grain types in the same project as their implementations.
-- Use localhost clustering for local development (`UseLocalhostClustering()`).
-- Do **not** add `[Alias]` attributes to grain interfaces or methods — rely on the default alias generated by Orleans.
+- Do **not** split grain interfaces into a separate project. Grain interfaces and their implementations live together in `Kernel/Core`; the `Contracts` project holds the gRPC contracts, not grain interfaces.
+- Clustering is chosen by the host, not the grain code: the server uses `UseLocalhostClustering(siloPort, gatewayPort, serviceId, clusterId)` for local development and the MongoDB storage integration switches on `UseMongoDBClustering` (`MongoDBMembershipStrategy.Multiple`) when clustering is enabled. A silo pointed at non-local shared storage while still on localhost clustering is logged as a **warning** at startup (each such node forms its own single-node cluster over the same data); `Cratis__Chronicle__Clustering__Type=MongoDB` on every node is what joins them.
+- Do **not** add `[Alias]` to grain interfaces or grain methods — rely on the default alias Orleans generates. `[Alias(nameof(Type))]` is used only on `[GenerateSerializer]` **state and definition records** in `Kernel/Concepts` (`ReadModelDefinition`, `IndexDefinition`, `ReadModelChangeContext`, `ProjectionFuture`), where a stable serialization alias must survive a rename.
 
-## Storage Providers
+## Grain storage providers
 
-- Centralize all storage provider names in a single `WellKnownStorageProviders` static class at the root of the project.
-- Reference provider names via the constants in `WellKnownStorageProviders` — never use magic strings.
-- Use `WellKnownStorageProviders.Default` as the name for the primary MongoDB-backed storage provider.
+- Storage provider names are constants in `WellKnownGrainStorageProviders` (`Kernel/Core`), **one name per concern** — 25 of them at v18.3.0 (`Namespaces`, `EventSequences`, `ObserverDefinitions`, `ObserverState`, `FailedPartitions`, `Jobs`, `JobSteps`, `Recommendations`, `Projections`, `ProjectionsManager`, `ProjectionFutures`, `Reactors`, `Reducers`, `ReducersManager`, `ReadModels`, `ReadModelsManager`, `ReadModelReplayManager`, `Constraints`, `EventStoreSubscriptionsManager`, `EventSeeding`, `Webhooks`, `WebhooksManager`, `DataProtectionKeys`, `PatchManager`, `System`). Reference a provider only through its constant — never a magic string, and there is no "default" provider.
+- Each concern has its own `IGrainStorage` implementation (`JobGrainStorageProvider`, `EventSequencesStorageProvider`, `NamespacesStateStorageProvider`, …) taking the kernel's `IStorage` abstraction — **not** a MongoDB collection. The storage backend (MongoDB, SQL, in-memory) is selected behind `IStorage`, so a grain storage provider never references a database driver.
+- Every provider is registered once, in `StorageProviderExtensions.AddStorageProviders(this ISiloBuilder)`, as a keyed singleton wrapped in `ResilientGrainStorage` (a Polly resilience pipeline configured from `Chronicle:ResilientStorage`). A new concern adds a constant, an `IGrainStorage` over `IStorage`, and one `AddKeyedSingleton(WellKnownGrainStorageProviders.<Name>, CreateResilientStorageFor<…>)` line there — nothing else.
+- Grains declare their state with `[PersistentState(nameof(<StateType>), WellKnownGrainStorageProviders.<Name>)]`.
 
 ```csharp
-public static class WellKnownStorageProviders
+public class JobGrainStorageProvider(IStorage storage) : IGrainStorage
 {
-    public const string Default = "MongoDbGrainStorage";
+    // ReadStateAsync / WriteStateAsync / ClearStateAsync over
+    // storage.GetEventStore(key.EventStore).GetNamespace(key.Namespace).Jobs
 }
-```
-
-- Annotate grains with `[StorageProvider(ProviderName = WellKnownStorageProviders.Default)]` when they need persistent state.
-
-## MongoDB Grain Storage
 
-- The `MongoDbGrainStorage<TState>` implementation accepts `IMongoCollection<TState>` as its only dependency — no additional plumbing is required.
-- Register it as a keyed singleton in the Orleans silo builder:
-
-```csharp
-builder.Host.UseOrleans(siloBuilder =>
-{
-    siloBuilder.UseLocalhostClustering();
-    siloBuilder.Services.AddKeyedSingleton<IGrainStorage>(
-        WellKnownStorageProviders.Default,
-        (sp, _) => new MongoDbGrainStorage<MyState>(
-            sp.GetRequiredService<IMongoCollection<MyState>>()));
-});
+services.AddKeyedSingleton(WellKnownGrainStorageProviders.Jobs, CreateResilientStorageFor<JobGrainStorageProvider>);
 ```

package/package/corpus/rules/react.md

@@ -8,7 +8,7 @@ paths:
 
 # React + Arc + Cratis Components
 
-The frontend is React + TypeScript in MVVM style, composed from **Cratis Components** on top of **Arc-generated proxies**. Cratis Components is PrimeReact-based; you reach PrimeReact almost exclusively through the Cratis wrappers. For component structure, styling, and icons see [components.md](./components.md); for dialogs see [dialogs.md](./dialogs.md). This rule covers MVVM, queries, and commands.
+The frontend is React + TypeScript in MVVM style, composed from **Cratis Components** on top of **Arc-generated proxies**. Cratis Components (4.x) owns its markup, styling contract and behavior — there is no vendor component library underneath to reach for; React Aria is an internal detail you never import. For component structure, styling, and icons see [components.md](./components.md); for dialogs see [dialogs.md](./dialogs.md). This rule covers MVVM, queries, and commands.
 
 ## The proxy boundary
 
@@ -81,7 +81,7 @@ Extract as soon as a component has **any** of: 3+ `useState`, any `useCallback`
 
 These are registered automatically by `withViewModel` and injected via the primary constructor. Concrete usage:
 
-- **`IMessenger`** — messages are plain classes; `_messenger.publish(new <Entity>Selected(id))` and `messenger.subscribe(<Entity>Selected, ({ id }) => ...)`. For scoped delivery, the messenger from `@cratis/arc/messaging` (distinct from `…mvvm/messaging`) resolves the nearest scope and falls back to root: `publish()` trickles **down** into nested scopes; bubbling **up** is opt-in with `{ bubble: true }`. Use the default `IMessenger` unless you genuinely need scoping.
+- **`IMessenger`** — messages are plain classes; `_messenger.publish(new <Entity>Selected(id))` and `messenger.subscribe(<Entity>Selected, ({ id }) => ...)`. For scoped delivery, the messenger from `@cratis/arc/messaging` (distinct from `…mvvm/messaging`) resolves the nearest scope and falls back to root: a `<MessengerScope>` trickles `publish()` **down** into nested scopes by default (`trickleDownToChildren`, default `true`) and bubbles **up** only when `bubbleToParent` is set (default `false`) — both are props on `MessengerScope` / properties on the messenger, not options on `publish()`. Use the default `IMessenger` unless you genuinely need scoping.
 - **`IDialogs`** — `await _dialogs.showConfirmation(title, message, DialogButtons.YesNo)` returns a `DialogResult`. For user-triggered dialogs that open React command dialogs, use `useDialog` in the component, not `IDialogs`.
 - **`IIdentityProvider`** — `await _identityProvider.getCurrent<TDetails>()`. Use the `useIdentity()` hook only in functional components without a view model.
 - **`ILocalStorage`** — `setItem(key, value)` / `getItem(key)`; **`IViewModelDetached.detached()`** runs on unmount (`detached() { this._subscription?.unsubscribe(); }`).
@@ -94,7 +94,7 @@ A typed proxy class is generated per query. Pick the hook:
 
 | Hook | When |
 |---|---|
-| `<Query>.use(args?, sorting?)` | standard — returns `[result]`, re-renders on change |
+| `<Query>.use(args?, sorting?)` | standard — returns `[result, perform, setSorting]`, re-renders on change |
 | `<Query>.useSuspense(...)` | suspense-aware — throws while loading; wrap in `<QueryBoundary>` |
 | `<Query>.when(condition).use(args)` | conditional — only fires when `condition` is true (don't wrap a hook in `if`) |
 | `<Query>.useWithPaging(pageSize, args?, sorting?)` | server-side paging (backend returns `IQueryable<T>`) |
@@ -106,12 +106,12 @@ A typed proxy class is generated per query. Pick the hook:
 
 | Hook | Returns |
 |---|---|
-| `<Query>.use(args?, sorting?)` | `[result, perform]` |
+| `<Query>.use(args?, sorting?)` | `[result, perform, setSorting]` |
 | `<Query>.useSuspense(...)` | `[result, perform, setSorting]` |
 | `<Query>.useWithPaging(pageSize, args?, sorting?)` | `[result, perform, setSorting, setPage, setPageSize]` |
 | `<Query>.useSuspenseWithPaging(pageSize, ...)` | `[result, perform, setSorting, setPage, setPageSize]` |
-| `<ObservableQuery>.use(...)` | `[result, setSorting]` — **no `perform`** |
-| `<ObservableQuery>.useChangeStream(args?, getKey?, sorting?, isEnabled?)` | `ChangeSet<T> { added, replaced, removed }` |
+| `<ObservableQuery>.use(...)` | `[result, setSorting]` for an enumerable query; `[result]` for a single-instance one — **no `perform`** |
+| `<ObservableQuery>.useChangeStream(args?, getKey?, sorting?)` | `ChangeSet<T> { added, replaced, removed }` |
 
 `result.paging` = `{ page, size, totalItems, totalPages }` (zero-based `page`). Read models returning `IQueryable<TReadModel>` get automatic server-side paging/sorting — use it whenever a list can grow.
 
@@ -141,7 +141,7 @@ Inside dialogs, use `CommandDialog` + CommandForm fields rather than driving the
 | `isValid` | validation failed — `validationResults` has per-field messages | render inline field errors |
 | `hasExceptions` | `Provide()`/`Handle()` threw — `exceptionMessages` carry diagnostics | generic error toast + log; never show stack traces |
 
-`CommandDialog` handles all of this automatically; the flags matter most when executing a command **outside** a dialog. `validate()` returns the same shape with `response == null` (handler did not run). `result.validationResults` is a `ValidationResult[]` of `{ property, message }` — render per-field UI from it, but **never branch on raw `.message` text**. `exceptionMessages`/`exceptionStackTrace` are for logging, never for users.
+`CommandDialog` handles all of this automatically; the flags matter most when executing a command **outside** a dialog. `validate()` returns the same shape with `response == null` (handler did not run). `result.validationResults` is a `ValidationResult[]` of `{ severity, message, members: string[], state, reason, reasonDetail? }` — `members` names the affected properties — render per-field UI from it, but **never branch on raw `.message` text**. `exceptionMessages`/`exceptionStackTrace` are for logging, never for users.
 
 Out-of-dialog execution branches in this order:
 
@@ -157,11 +157,11 @@ if (result.hasExceptions) { toast.error('Something went wrong'); console.error(r
 
 ### Command helpers
 
-- **`useCommandInstance(Command)`** — read the live reactive command instance for dependent fields (read it; never mutate — mutations go through field bindings).
+- **`useCommandInstance<TCommand>()`** — inside a `CommandForm`/`CommandDialog`, read the live reactive command instance from context for dependent fields (no argument; the type parameter is the command type) (read it; never mutate — mutations go through field bindings).
 - **`onBeforeExecute`** is a **transformer**: it receives the current values and **must return them** (mutated or not). It runs only on submit — never use it to seed required values (use `initialValues`).
 - **`initialValues`** = synchronous baseline (also drives change tracking); **`currentValues`** = reactive overlay for async/late-loading values (e.g. from a query).
 - **`asCommandFormField<P>(Component, opts)`** — wrap a custom input (rich text, address picker) so it participates in `CommandForm` with validation/error wiring.
-- **`CommandScope`** + `useCommandScope()` (`@cratis/arc.react/commands`) — aggregate state across multiple commands (and queries) on one screen; members tracked automatically (no `addCommand`); scopes nest (a child reports up to its parent); injectable as `ICommandScope` (nearest enclosing scope). Props: `setHasChanges`, `setIsPerforming`, `onBeforeExecute`, `onSuccess(cmd, result)`, `onFailed`, `onException`, `onUnauthorized`. `ICommandScope` members: `hasChanges`, `isPerforming`, `hasValidationFailures`, `hasExceptions`, `validationFailures`/`exceptions` (this scope), `aggregatedValidationFailures`/`aggregatedExceptions` (scope + children), `execute()` (runs only commands with changes), `revertChanges()`, `parent`.
+- **`CommandScope`** + `useCommandScope()` (`@cratis/arc.react/commands`) — aggregate state across multiple commands (and queries) on one screen; commands and queries rendered inside the scope register themselves (the `ICommandScope` API also exposes `addCommand`/`addQuery`/`addChildScope` for manual registration); scopes nest (a child reports up to its parent); injectable as `ICommandScope` (nearest enclosing scope). Props: `setHasChanges`, `setIsPerforming`, `onBeforeExecute`, `onSuccess(cmd, result)`, `onFailed`, `onException`, `onUnauthorized`. `ICommandScope` members: `hasChanges`, `isPerforming`, `hasValidationFailures`, `hasExceptions`, `validationFailures`/`exceptions` (this scope), `aggregatedValidationFailures`/`aggregatedExceptions` (scope + children), `execute()` (runs only commands with changes), `revertChanges()`, `parent`.
 
 ### `<Arc>` global configuration
 
@@ -175,7 +175,7 @@ Top-level provider for microservice name and API base path. Config props (with d
 | `queryConnectionCount` | `1` | hub connection slots |
 | `queryDirectMode` | `false` | direct per-query connection — dev use only |
 
-`QueryTransportMethod`/`ObservableQueryTransferMode` import from `@cratis/arc`; `Arc` from `@cratis/arc.react`. Reach `arc.reconnectQueries()` via `useContext(ArcContext)` and call it after login/logout to re-establish observable connections.
+`QueryTransportMethod` imports from `@cratis/arc/queries` and `ObservableQueryTransferMode` from `@cratis/arc`; `Arc` from `@cratis/arc.react`. Reach `arc.reconnectQueries()` via `useContext(ArcContext)` and call it after login/logout to re-establish observable connections.
 
 ## Composition
 
@@ -185,11 +185,11 @@ Top-level provider for microservice name and API base path. Config props (with d
 
 ## Styling default
 
-Default to **Cratis Components on PrimeReact theming/tokens** (`var(--surface-*)`, `var(--primary-color)`, `var(--text-color)`, `pt`/unstyled where needed) — see [components.md](./components.md). Tailwind is **not** the Cratis default (it's one supported unstyled path). Never hard-code hex/`rgb()` for chrome.
+Default to **Cratis Components with the `--cratis-*` tokens** (`var(--cratis-surface-*)`, `var(--cratis-primary-color)`, `var(--cratis-text-color)`; `pt`/`data-cratis-part` when you must reach a part) — see [components.md](./components.md). Tailwind is **not** the Cratis default: it is one supported way to *write* the CSS that maps a product's design onto those tokens. Never hard-code hex/`rgb()` for chrome.
 
 ## See also
 
-- [components.md](./components.md) — component structure, CSS, PrimeReact tokens, icons, Storybook.
+- [components.md](./components.md) — component structure, CSS, `--cratis-*` tokens and parts, icons, Storybook.
 - [dialogs.md](./dialogs.md) — `CommandDialog` / `Dialog` / `StepperCommandDialog` rules.
 - [frontend-quality.md](./frontend-quality.md) — engineering bar; [frontend-testing.md](./frontend-testing.md) — BDD specs.
 - [typescript.md](./typescript.md) — TS style.

package/package/corpus/rules/reactors.md

@@ -159,6 +159,23 @@ public Task<IEnumerable<EventForEventSourceId>> Handle(AnEvent @event, EventCont
 
 > **Chronicle version note:** reactor side-effect handling of `EventForEventSourceId` wrappers has shipped since Chronicle 15.35.
 
+### Return a command (Arc + Chronicle)
+
+When the follow-up belongs to **another slice**, return its `[Command]` instead of an event — the same idiom as returning events, applied to intent. Arc's Chronicle integration executes a returned command through the full pipeline (validation, authorization, `Handle()`) in its own service scope; a collection is executed in order when **every** element is a command (events and commands do not mix in one return). An unauthorized, invalid or throwing result is a **side-effect failure** — it fails the partition like a failed append, so it is never silently dropped.
+
+```csharp
+public class StockKeeping : IReactor
+{
+    [OnceOnly]
+    public Task<DecreaseStock> BookReserved(BookReserved @event, EventContext context) =>
+        Task.FromResult(new DecreaseStock(@event.Isbn, @event.Quantity));
+}
+```
+
+- **A reactor runs with no principal.** It is not an HTTP request, so a returned command gated by `[Roles]`/`[Authorize]` is denied. Opt in on the reactor **class** with `[ExecuteCommandsAsSystem("<role>", …)]` (`Cratis.Arc.Chronicle.Reactors`), naming only the roles its returned commands need. The attribute covers **returned** commands only.
+- Mark the handler `[OnceOnly]` — a replay would otherwise execute the command again. Replay exclusion is not exactly-once: recovery re-delivers, so the command itself must be safe to repeat.
+- The imperative alternative — inject `ICommandPipeline` and call `Execute(command)` — remains supported (see the **cratis-arc-command-execution** skill). It needs `[OnceOnly]` (`ARCCHR0006` warns otherwise), its `CommandResult` must be inspected (a denied or invalid result is otherwise discarded), and it needs its own execution context: `[ExecuteCommandsAsSystem]` does not apply to it.
+
 ## External event stores (outbox / inbox)
 
 Cross-service events route through Chronicle's outbox/inbox rather than a shared log:
@@ -176,11 +193,12 @@ The default is fire-and-forget. When a caller's correctness depends on all obser
 
 1. **Idempotent** — Reactors may be called more than once for the same event (e.g. during replay or recovery). Design accordingly. For a side effect that must **not** repeat on replay (emails, payments, external writes), mark the handler method `[OnceOnly]` — Chronicle then skips that handler for every event arriving as part of a **replay** (observer rewind, redaction, revision). That is the whole of it: `[OnceOnly]` is replay-exclusion, **not** exactly-once and **not** a per-event-source counter. Recovering a failed partition re-delivers the event as an ordinary observation, so the handler runs again — which is the point of a retry. When the side effect must survive that retry too, take a `ReactorDelivery` parameter alongside the attribute and keep a receipt under its identity, which is stable across the failure and the recovery.
 2. **Use event data directly** — Never query the read model back inside a reactor. The event contains all the information you need.
-3. **Return events instead of injecting IEventLog** — If the reactor needs to produce new events, return them directly as `Task<TEvent>`, `Task<EventForEventSourceId>`, or a collection thereof. For commands in other slices, inject `ICommandPipeline` and execute a command. Avoid injecting `IEventLog` directly into a reactor.
+3. **Return events and commands instead of injecting the plumbing** — If the reactor needs to produce new events, return them directly as `Task<TEvent>`, `Task<EventForEventSourceId>`, or a collection thereof. For intent in another slice, return the `[Command]` (Arc executes it; a denied or invalid result fails the partition) — or inject `ICommandPipeline` and inspect the result. Either way the handler is `[OnceOnly]`. Avoid injecting `IEventLog` directly into a reactor.
 4. **Single responsibility** — Each reactor class should have a focused purpose. Multiple handler methods in one reactor are fine if they serve the same automation concern.
 5. **Failure behavior** — If a reactor throws, *or* a returned side-effect event fails to append (constraint violation, concurrency violation, or error), the failing event-source partition pauses until the issue is resolved. Repeated failures can **quarantine** the observer: once `QuarantineOnFailedPartitionCount`/`QuarantineOnFailedPartitionPercentage` (under `Observers`) is crossed, the observer enters the `Quarantined` state — reminders cancelled, retries stopped, automatic recovery suppressed. **A quarantined observer does NOT auto-resume on reconnect** — an operator must call `ClearObserverQuarantine()`. A periodic watchdog (default 60s, `WatchdogInterval`) re-routes stuck/dead observers but does not rescue quarantined ones. Design for resilience.
 6. **Don't throw to validate malformed inbound events** — reactors are not data-quality validators; invalid payloads must be rejected at the command/append site. When a malformed cross-service fact reaches a consumer, throwing just to reject it pauses the partition and can quarantine the whole observer. Instead append a clear failure/dead-letter event (e.g. `ProvisioningFailed`) or surface it via the operational failure path, and skip partial side effects.
 7. **No state** — Reactors should be stateless. Inject dependencies via primary constructor, but do not store mutable state on the class.
+8. **An unattended, irreversible pass reads the log, not the sink — and carries a fuse.** A reactor that deletes, revokes, bills or notifies *because a read model says something is absent* is trusting a materialized sink that is only as current as its observer: a paused partition, a replay in progress or a lagging projection makes "absent" true of the sink and false of the world. Decide from a **`[Passive]`** read model (computed on demand from the events at the moment the reactor runs) or from the events themselves. And the code shape cannot tell an **empty subject set** ("nothing to consider" — fail-safe) from an **empty qualifying set** ("nothing survived the filter" — fail-destructive: every subject is about to be acted on), so an unattended pass states its expected population, refuses when the count is implausible, and caps how many subjects one run may touch — the same discipline as [guards-and-fuses.md](./guards-and-fuses.md), applied to a reactor.
 
 ## Slice Types That Use Reactors
 
@@ -207,18 +225,23 @@ public class ProjectRegisteredNotifier(INotificationService notifications) : IRe
 ### Translation Example
 
 ```csharp
-public class StockKeeping(IStockKeeper stockKeeper, ICommandPipeline commandPipeline) : IReactor
+[ExecuteCommandsAsSystem("inventory")]
+public class StockKeeping : IReactor
 {
     /// <summary>
-    /// Reacts to a book reservation by decreasing stock.
+    /// Reacts to a book reservation by decreasing stock in the inventory slice.
     /// </summary>
     /// <param name="event">The event.</param>
     /// <param name="context">The event context.</param>
-    public async Task BookReserved(BookReserved @event, EventContext context) =>
-        await commandPipeline.Execute(new DecreaseStock(@event.Isbn, await stockKeeper.GetStock(@event.Isbn)));
+    /// <returns>The command Arc executes as this reactor's side effect.</returns>
+    [OnceOnly]
+    public Task<DecreaseStock> BookReserved(BookReserved @event, EventContext context) =>
+        Task.FromResult(new DecreaseStock(@event.Isbn, @event.Quantity));
 }
 ```
 
+The command is returned, not executed: Arc runs it through validation and authorization under the roles the class opts into, and a rejected command fails the partition instead of vanishing. `[OnceOnly]` keeps a replay from decreasing stock twice.
+
 ## Testing Reactors
 
 Use `ReactorScenario<TReactor>` (from `Cratis.Chronicle.Testing.Reactors`) — construct it with an `IServiceProvider` of NSubstitute mocks, fire events through `Given`, and assert on the mocks:

package/package/corpus/rules/specs.scenarios.csharp.md

@@ -51,10 +51,10 @@ public class and_all_information_is_valid : Specification
 #endif
 ```
 
-- `CommandScenario<TCommand>` exposes `Services` (an `IServiceCollection`), `Context`, `Execute(command)`, and `Validate(command)` — and nothing else; everything else is configured through `Services` and asserted with extension methods.
+- `CommandScenario<TCommand>` exposes `Services` (an `IServiceCollection`), `Context`, `Execute(command[, ct])`, `Validate(command)`, `LastResult`, `Operations` and the operation assertions `ShouldHaveExecutedOperation<T>()` / `ShouldHaveCompensatedOperation<T>()` / `ShouldHaveNoOperationInvocations()`; with the Chronicle integration it also gains `Given`, `EventScenario`, `EventLog`, `EventSequence` and `AppendedEvents` as extension members. Everything else is configured through `Services` and asserted with extension methods.
 - **Event assertions are extension methods on the scenario** (from the Chronicle testing package), keyed by **command + event** type: `await _scenario.ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId)` or the `(eventSourceId, Func<TEvent,bool> predicate)` overload; plus `await _scenario.ShouldHaveTailSequenceNumber<TCommand>(...)`. They return `Task`, so the fact is `async Task`.
 - **`CommandResult` assertions** (Arc extensions): `ShouldBeSuccessful()`, `ShouldNotBeSuccessful()`, `ShouldBeValid()`, `ShouldHaveValidationErrors()`, `ShouldHaveValidationErrorFor(message)`, `ShouldBeAuthorized()`, `ShouldNotBeAuthorized()`, `ShouldHaveExceptions()`/`ShouldNotHaveExceptions()`.
-- **Seed prior state through `_scenario.Services`** — there is no `Given`/`Events` on `CommandScenario`. To populate the DCB read models the validator/`Provide()`/`Handle()` inject, substitute `IReadModels` and register it (`_scenario.Services.Replace(new ServiceDescriptor(typeof(IReadModels), mock))`, mocking `GetInstanceById(...)`) or register projections with `_scenario.Services.AddReadModels(...)`.
+- **Seed prior state through `_scenario.Given` or `_scenario.Services`.** `_scenario.Given.ForEventSource(id).Events(...)` materializes the seeded events into an **in-memory read-model dictionary** the harness answers keyed reads from — it never reaches the event log (see the false-greens list below). To populate the DCB read models the validator/`Provide()`/`Handle()` inject, substitute `IReadModels` and register it (`_scenario.Services.Replace(new ServiceDescriptor(typeof(IReadModels), mock))`, mocking `GetInstanceById(...)`) or register projections with `_scenario.Services.AddReadModels(...)`.
 - **Validator/`Provide()` dependencies:** register them in `_scenario.Services`; Arc testing discovers the concrete validator automatically. When several specs need different injected validator states, test rejected variants by instantiating the validator directly (per-scenario state can be order-sensitive under parallel xUnit).
 - **`Provide()`:** drive it through `CommandScenario` end-to-end; when the handler's decision is pure given provided data, also test `Handle(providedValue)` directly.
 
@@ -69,7 +69,21 @@ Every unhappy-path spec asserts **both**:
 
 `ShouldNotBeSuccessful()` alone can't tell a validation rejection from an unhandled exception. **Never assert on message strings** — they're presentation text. Authorization failures use `ShouldNotBeAuthorized()` (an unauthorized result has *no* validation errors, so `ShouldHaveValidationErrors()` would silently flip). To exercise a command that carries authorization attributes, register the identity the authorization evaluator reads into `_scenario.Services` (substitute the identity provider your app uses). **Adding `[Roles]` to an existing command breaks its happy-path AND validation-failure `.Execute()` specs** — an unauthorized result is not successful and carries no validation errors; switch those assertions to `ShouldNotBeAuthorized()`.
 
-`CommandResult` assertions (from `Cratis.Arc.Testing.Commands`; failures throw `CommandResultAssertionException`): `ShouldBeSuccessful()` (`isAuthorized && isValid && !hasExceptions`), `ShouldNotBeSuccessful()`, `ShouldBeValid()` (no validation errors — does *not* check authz/exceptions), `ShouldHaveValidationErrors()`, `ShouldHaveValidationErrorFor(message)`, `ShouldBeAuthorized()`, `ShouldNotBeAuthorized()`, `ShouldHaveExceptions()`.
+`CommandResult` assertions (from `Cratis.Arc.Testing.Commands`; failures throw `CommandResultAssertionException`): `ShouldBeSuccessful()` (`isAuthorized && isValid && !hasExceptions`), `ShouldNotBeSuccessful()`, `ShouldBeValid()` (no validation errors — does *not* check authz/exceptions), `ShouldHaveValidationErrors()`, `ShouldHaveValidationErrorFor(message)`, `ShouldHaveValidationErrorBecauseOf(ValidationResultReason)`, `ShouldHaveConstraintViolationFor(name)`, `ShouldBeAuthorized()`, `ShouldNotBeAuthorized()`, `ShouldHaveExceptions()`.
+
+#### False greens the harness lets through
+
+Each of these passes while proving nothing. They are the reason the two-assertion rule above exists.
+
+1. **A discarded assertion `Task`.** The `IEventSequence` assertions `ShouldHaveAppendedEvent`/`ShouldHaveTailSequenceNumber` (Chronicle Testing) are genuinely `async`: in a `void [Fact]` that does not `await` them the exception lands on a `Task` nobody observes and the spec passes regardless of behavior, while the compiler's `CS4014` stays silent outside an `async` method. (The same-named `CommandScenario` overloads in Arc's Chronicle.Testing throw synchronously and only *return* a completed `Task`, so those fail even when discarded — but you cannot tell the two apart at the call site.) Make the fact `async Task` and `await` every `Task`-returning `Should*`. Chronicle's analyzer **`CHR0039` (`NonAwaitedAssertion`)** reports any discarded `Task`/`ValueTask`-returning `Should*` call from a Cratis testing package (Chronicle's and Arc's alike).
+2. **A dependency the spec forgot to seed.** When a validator's constructor, `Provide()` or `Handle()` asks for a read model that does not exist for the command's key, the validator is never built and no rule runs — yet the command is rejected (one validation result, reason **`DependencyUnavailable`**, HTTP 400), so `ShouldNotBeSuccessful()` passes and keeps passing with the rule it is named after deleted. `ShouldHaveValidationErrors()` **refuses** a result whose only errors carry that reason and tells you to seed the read model — or, when that rejection *is* the behavior under spec, assert it deliberately with `ShouldHaveValidationErrorBecauseOf(ValidationResultReason.DependencyUnavailable)`. A missing *service* (not a read model) surfaces as an exception instead (`ShouldHaveExceptions()`), and `ShouldNotBeSuccessful()` alone cannot tell the two apart from a genuine rejection.
+3. **`.Validate()` authorizes first.** `Validate(command)` runs the command filters, and authorization filters are ordered before validation. A validate-only spec on a `[Roles]`/`[Authorize]` command with no identity registered is denied for authorization — the rule it is named after never ran. Register the identity, or assert `ShouldNotBeAuthorized()` and say so in the name.
+4. **Constraint preconditions go to the event log, not `CommandScenario.Given`.** `_scenario.Given.ForEventSource(id).Events(...)` on a `CommandScenario` seeds an **in-memory read-model materialization only**; nothing reaches the event log a `[Unique]`/`IConstraint` is enforced against, so a "second registration with the same name" spec passes because the first one was never appended. Seed constraint preconditions through **`EventScenario`**'s `Given`, and assert the violation by constraint **name** (`ShouldHaveConstraintViolationFor`) — the same helper exists on `CommandResult` and on `IAppendResult`.
+5. **`GetInstances<T>` is not harness-backed.** Under `CommandScenario` the read-model harness answers keyed reads (`GetInstanceById`) from its seeded dictionary and forwards `GetInstances<T>`/`GetSnapshotsById`/`Watch` to the real client, which is not there. Code under spec that enumerates a read model needs a fake lookup registered in `Services`, not `Given`.
+6. **One child is not a children spec.** `[ChildrenFrom<T>]` without `key:` identifies children by the **event source id**, so every child event on one stream upserts the same child and a one-child spec stays green with the key wrong. Drive **two** children with distinct keys and assert the count.
+7. **Independently derived expectations.** An expected value computed in the spec with the same expression as the code under spec agrees with it by construction. Write the expected literal.
+
+The `ReadModelScenario` and `EventScenario` equivalents of these live in the **cratis-chronicle-read-model-specifications** and **cratis-chronicle-event-specifications** skills.
 
 > **Validator-state order-sensitivity:** the command-scenario pipeline can cache enough state to make injected-validator branches order-sensitive when xUnit runs classes in parallel. Use `CommandScenario` for the valid path, test rejected state-variants by **instantiating the validator directly**, and — only for that validator-state case — put the command's specs in a **small xUnit `[Collection]`**. (This is distinct from the unique-value-collision rule below, where `[Collection]` is the *wrong* fix.)
 
@@ -151,6 +165,7 @@ public class and_name_already_exists(context context) : Given<context>(context)
 }
 ```
 
+- `ChronicleCollection` is a project-defined `[CollectionDefinition]` class over `ChronicleOutOfProcessFixture` (Chronicle ships the fixture, not the collection).
 - `ExecuteCommand<TCommand>(url, cmd)` returns `CommandResult<object>?`; `ExecuteCommand<TCommand, TResult>(url, cmd)` returns `CommandResult<TResult>?`.
 - Helpers: `Context.ShouldHaveTailSequenceNumber(n)` (First = 0), `Context.ShouldHaveAppendedEvent<TEvent>(seq, eventSourceId, validator)`.
 

package/package/corpus/rules/specs.typescript.md

@@ -40,7 +40,7 @@ for_EventsCommandResponseValueHandler/
 
 ## BDD Pattern with `given()` Helper
 
-The `given()` function is the TypeScript equivalent of the C# `Specification` base class. It instantiates a context class (the "given"), passes it to the test suite, and ensures setup runs before assertions. This keeps the Establish/Because/should pattern consistent across both stacks.
+The `given()` function is the TypeScript counterpart of the C# `Specification` base class. It instantiates a context class (the "given") **once when the `describe` is registered**, passes that instance to the suite callback, and leaves the per-behavior action to a `beforeEach` you write. Because the context is shared by every `it()` in the `describe`, keep one action per `describe` and let `it()` blocks only assert — that is what keeps Establish/Because/should consistent across both stacks.
 
 ```typescript
 import { an_events_command_response_value_handler } from '../given/an_events_command_response_value_handler';

package/package/corpus/rules/storybook.md

@@ -17,7 +17,7 @@ Good candidates: a presentational card/list-item/form-field with multiple visual
 
 ## Preview infrastructure (what you get for free)
 
-A configured `.storybook/preview` should wrap every story in `CratisComponentsProvider` (from `@cratis/components/Common`) and import `@cratis/components/styles` so PrimeReact-based components render correctly. With that in place:
+A configured `.storybook/preview` should wrap every story in `CratisComponentsProvider` (from `@cratis/components`) and import `@cratis/components/tokens`, `@cratis/components/styles` and (for the baseline look) `@cratis/components/theme` — the same three entries the app imports — so components render styled. With that in place:
 
 - **Auto prop tables** via `react-docgen-typescript` — a component's `interface` + per-prop JSDoc renders as a Docs prop table, and union props become `select` controls automatically. Keep a JSDoc comment on every prop. **`argTypes` is an override layer** (change control type, group under `table.category`, disable a control) — don't re-list every prop.
 - **Accessibility panel** (`@storybook/addon-a11y`) scans each story with axe-core. Treat new violations as defects.
@@ -67,7 +67,7 @@ export const Interactive: Story = {
 };
 ```
 
-- **Stateful only** — presentational atoms get no `play:`. Thin PrimeReact wrappers (overlay-portal components) are excluded — their behavior is the framework's.
+- **Stateful only** — presentational atoms get no `play:`. Components' own overlay components (dialogs, dropdowns, toasts) are excluded — their behavior is the library's, not yours.
 - Prefer role/structure queries over localized text. `play:` runs in the Interactions panel (documentation/QA); the enforced behavioral gate is the Vitest spec.
 
 ## Router-dependent components

package/package/corpus/rules/typescript.md

@@ -121,6 +121,7 @@ All identifiers, comments, JSDoc, and string literals must use **American Englis
 
 ## Folder Structure
 
+- **Never give a `.tsx` the same basename as a `.ts` in the same folder.** The Arc proxy generator emits `<Slice>.ts` beside the slice's C#; a component named `<Slice>.tsx` next to it is **silently dropped from the program**: for one basename TypeScript keeps only the `.ts`, so the component's type errors are never reported and `tsc -b` stays green while the file is broken (reproduced on TypeScript 6.0.3 and 7.0.2 with `include: ["src/**/*"]`). Name the component for what it renders (`Listing.tsx`, `RegisterAuthor.tsx`), never for the slice, and consider a repository spec that fails on any `.tsx` with a sibling `.ts` of the same name.
 - Do not prefix a file, component, type, or symbol with the name of its containing folder or the concept it belongs to. Instead, use folder structure to provide that context.
 - Favor functional folder structure over technical folder structure.
   - Group files by the feature or concept they belong to, not by their technical role.

package/package/corpus/rules/vertical-slices.md

@@ -17,12 +17,12 @@ This file is the reference for *what* goes in each part of a slice. Layout, slic
 ## Technical stack
 
 - .NET / C# (ASP.NET Core) — **Cratis Arc** for CQRS / model-bound commands and queries, **Cratis Chronicle** for event sourcing, MongoDB or EF Core for read models.
-- React + TypeScript (Vite) — Cratis Components (PrimeReact-based) + Arc-generated proxies, MVVM. Vitest + Mocha/Chai/Sinon for frontend specs.
+- React + TypeScript (Vite) — Cratis Components 4.x + Arc-generated proxies, MVVM. Vitest + Mocha/Chai/Sinon for frontend specs.
 - xUnit + Cratis.Specifications + NSubstitute for C# specs (the `*Scenario` family — see [specs.md](./specs.md)).
 
 ## Proxy generation — the build dependency
 
-A Debug `dotnet build` generates a typed TypeScript proxy per command and query next to the slice's `.cs` — Debug is the canonical trigger because it carries the fullest, most reliably-emitted PDB debug information the generator uses to place generated files. Until the backend compiles, **no proxy files exist** and frontend code cannot reference them. **Backend → build → frontend, always** — backend and frontend for the same slice cannot be done in parallel. When a subsequent Release build is only there to verify the app compiles in that configuration, skip proxy regeneration with `dotnet build -c Release -p:CratisProxiesOutputPath=` rather than letting it re-run the generator against a different compilation. Never edit a generated proxy (`// @generated by Cratis` header); fix the C# source and rebuild.
+A `dotnet build` with `CratisProxiesOutputPath` set generates a typed TypeScript proxy per command and query next to the slice's `.cs` — the generator target has **no configuration condition**; running it from the Debug build is the house convention (one configuration owns the generated files, so Release never rewrites them differently). The generator reads PDB sequence points only to name output files after their source file, and only when `CratisProxiesUseSourceFileAsOutputFile` is on; Arc's own remark says which types retain that information *can differ* between Debug and Release, which is one more reason to let a single configuration generate. Until the backend compiles, **no proxy files exist** and frontend code cannot reference them. **Backend → build → frontend, always** — backend and frontend for the same slice cannot be done in parallel. When a subsequent Release build is only there to verify the app compiles in that configuration, skip proxy regeneration with `dotnet build -c Release -p:CratisProxiesOutputPath=` rather than letting it re-run the generator against a different compilation. Never edit a generated proxy (`// @generated by Cratis` header); fix the C# source and rebuild.
 
 ## Model-bound — no controllers **[contract]**
 
@@ -116,7 +116,7 @@ Values render camel-cased; concepts unwrap to the value they hold; a value that
 
 ### `Provide()` — data for `Handle()` **[contract]**
 
-`Provide()` runs after authorization and validation, before `Handle()`. Its parameters resolve from DI (like `Handle()`'s); the command instance is `this`. Return one value, or a tuple (Arc binds tuple values to `Handle(...)` parameters by type). Each provided value must be consumed by a `Handle` parameter — an unused one is the **`ARC0005`** analyzer error. Use a **named record** when the provided values form a real domain/snapshot concept; a **tuple** when they are just separate inputs to event construction. It may be sync or async.
+`Provide()` runs after authorization and validation, before `Handle()`. Its parameters resolve from DI (like `Handle()`'s); the command instance is `this`. Return one value, or a tuple (Arc binds tuple values to `Handle(...)` parameters by type). Each provided value should be consumed by a `Handle` parameter — an unused one raises the **`ARC0005`** analyzer warning. Use a **named record** when the provided values form a real domain/snapshot concept; a **tuple** when they are just separate inputs to event construction. It may be sync or async.
 
 ```csharp
 [Command]
@@ -163,11 +163,13 @@ Three attributes scope an append broad→narrow, and each one *also* (only with
 
 Each attribute always tags the appended events (visible in `EventContext`). **Only when the command also carries `concurrency: true`** does each dimension join the server-side `ConcurrencyScope` (plus the event source id), with the optimistic strategy supplying the expected tail sequence number. A command **without** `concurrency: true` contributes no scope of its own, and the append falls to whatever concurrency strategy the event sequence is configured with — by default the optimistic one, scoped to the event source. So the attribute chooses *which dimensions* bound the check, not whether a check happens at all. Reach for it on high-contention state transitions where a stale read would let two commands both "win" — it narrows the boundary so appends that are genuinely independent stop colliding (concurrency failures surface on `CommandResult`/`AppendResult`). Adopt it deliberately per behavior, not as a blanket default.
 
-When the stream id is known only at runtime, implement `ICanProvideEventStreamId.GetEventStreamId()` instead of `[EventStreamId]`. ⚠️ Combining `ICanProvideEventStreamId` with a non-null `[EventStreamId]` attribute on the same command throws `AmbiguousEventStreamId` at startup — pick one (or set the attribute value to `null` to defer to the interface).
+When the stream id is known only at runtime, implement `ICanProvideEventStreamId.GetEventStreamId()` instead of `[EventStreamId]`. ⚠️ Combining `ICanProvideEventStreamId` with a non-null `[EventStreamId]` attribute on the same command throws `AmbiguousEventStreamId` when that command is executed (the check runs while Arc builds the command context, not at startup) — pick one (or set the attribute value to `null` to defer to the interface).
 
 ### Event-source id resolution order **[contract]**
 
-`ICanProvideEventSourceId.GetEventSourceId()` → a single `EventSourceId`/`EventSourceId<T>`-derived property → a `[Key]` property → else Arc/Chronicle generates one.
+`ICanProvideEventSourceId.GetEventSourceId()` first; otherwise the **first property, in declaration order, that qualifies** — an `EventSourceId`/`EventSourceId<T>`-derived property *or* a `[Key]`-marked one (there is no priority between those two kinds; Arc reports two qualifying properties as `ARCCHR0002` and tells you to implement the interface); otherwise Arc generates a new id. When `ICanProvideEventSourceId` is implemented and returns `null` (or throws), the result is `EventSourceId.Unspecified`, **not** a generated id.
+
+⚠️ **Two attributes are spelled `[Key]`.** Chronicle resolves the key from `Cratis.Chronicle.Keys.KeyAttribute`; `System.ComponentModel.DataAnnotations.KeyAttribute` compiles, reads identically, and does **nothing** in an application that uses Chronicle — every command gets a fresh generated event source id and every read model keyed by it resolves to nothing. Arc's analyzer **`ARCCHR0008`** reports the wrong one; if a `using` pulls in the DataAnnotations namespace, check which `[Key]` you have.
 
 ⚠️ **Injected read models resolve ONLY by the command's resolved event-source id** — not by the read-model type, and not by "the property that looks like its key." If the read model you need is keyed by a **different** value, direct injection silently hands you the **wrong** instance — or, when nothing exists for the command's id, `null` (or for a `[Passive]` projection a **default-valued** instance; see *Existence checks* below) — a correctness bug, not a compile error. The three failure shapes: (1) you need a *referenced other* entity (act on A, check B); (2) the command has **multiple** `EventSourceId<T>`-typed properties → ambiguous resolution (never rely on property order); (3) a create command whose id is generated inside `Handle()`. In all three, read by explicit key: `IReadModels.GetInstanceById<T>((EventSourceId)key)`.
 
@@ -197,6 +199,7 @@ Apply authorization attributes on the `[Command]` record or query method. **[con
 - **Never duplicate one fact as an aggregate event *plus* a per-item fanout.** If a command fans out per item (one `RequestSentToPartner` per partner), don't also emit an aggregate event carrying the whole list. Keep the fanout as the single source of truth and project any aggregate from it; pick per-item vs. single-with-list event from how consumers read it — never both.
 - **Command rejection normally appends no event.** Validation and business-rule rejections are command results, not facts. Add a rejection/failed event only when the business must audit or react to that failure later.
 - **One event name = one meaning.** Don't reuse a vague event for several domain facts; if facts can occur, be absent, or have consumers independently, split them into separate event types.
+- **Never persist clock-relative state.** "Overdue", "expired", "due in 3 days" are true *now* and false later, and a projection only moves when an event arrives — so a projected `IsOverdue` is wrong the moment the clock crosses the line with no event to flip it. Store the **deadline** (a `DateOnly`/`DateTimeOffset` the business supplied) and compute the comparison at the query or UI edge, refreshing when time alone changes the answer. Only when *crossing* the deadline is itself a business fact (a fee is charged, a reminder goes out) does a scheduled process append an event for it.
 
 ```csharp
 /// <summary>Emitted when an author is registered.</summary>
@@ -250,7 +253,7 @@ Ladder, first that fits: (1) direct read-model (DCB) injection — only when key
 
 ⚠️ **This is invisible when a status enum's `0` is a real state** ("the state every stream starts in"): absent becomes byte-identical to freshly-created, so a command reads never-invited as already-invited. **Renumbering the enum from `1` is not the fix** — the value is then dropped from the payload and deserializes back to CLR `0` on the client anyway. Carry an explicit existence flag instead: `[SetValue<FirstEvent>(true)] bool Exists`, one `[SetValue<T>]` per event that can be the first for the stream. That is exactly the `[SetValue<T>]`-driven `bool` exception the no-defaults convention above allows for. An explicit `NotSet`/`Unknown` zero member also works, but only because the property stays present and readable; the flag is the robust form. ⚠️ **A spec suite will not catch this** — `CommandScenario`'s read-model harness answers `null` for an unseeded event-source id, which matches production for every row above *except* the passive projection. Cover the absent case by seeding a default-valued instance explicitly, not only `null`.
 
-**Injected-parameter nullability is the required/optional switch:** a nullable `TReadModel?` parameter (on a validator, `Provide()`, or `Handle()`) gets `null` injected for a never-created/removed instance — check `is null`. A **non-nullable** `TReadModel` whose instance does not exist throws **`CannotResolveValidatorDependency`** (non-nullable = "required, must exist"). ⚠️ Both switches ride on the same resolution, so on a **`[Passive]` projection** neither fires for a never-created instance: the nullable parameter receives a default-valued object and the `is null` guard never runs, and the non-nullable one resolves happily. Check the existence flag there, not nullability. Type by-id accessors you write yourself as `Task<T?>` so callers get the compiler signal Chronicle's own signature withholds.
+**Injected-parameter nullability is the required/optional switch:** a nullable `TReadModel?` parameter (on a validator, `Provide()`, or `Handle()`) gets `null` injected for a never-created/removed instance — check `is null`. A **non-nullable** `TReadModel` whose instance does not exist is **rejected, not crashed**: Arc raises `ReadModelDoesNotExistForCommand`, which surfaces as a validation failure (HTTP 400) with reason `DependencyUnavailable` (non-nullable = "required, must exist"). The server-fault path (`CannotResolveCommandDependency` / `CannotResolveValidatorDependency`, HTTP 500) is reached only when the dependency is *not* a registered read model or no usable key was resolved — the exact contract is in the **cratis-arc-command** skill's `read-model-injection` reference. ⚠️ Both switches ride on the same resolution, so on a **`[Passive]` projection** neither fires for a never-created instance: the nullable parameter receives a default-valued object and the `is null` guard never runs, and the non-nullable one resolves happily. Check the existence flag there, not nullability. Type by-id accessors you write yourself as `Task<T?>` so callers get the compiler signal Chronicle's own signature withholds.
 
 ## Projections **[contract]**
 
@@ -286,7 +289,7 @@ public Task AuthorRegistered(AuthorRegistered @event, EventContext context) => .
 - **Signatures:** the first parameter is the event and drives dispatch; every parameter after it is resolved as a dependency — `EventContext`, a read model, a service, a `ReactorDelivery` — with no limit on how many. Return `Task`, `void`, or a synchronous side-effect return type. Prefer `Task`/async for real side effects, but sync returns are supported.
 - **[convention] `[OnceOnly]`** on any non-idempotent side effect (emails, payments, external writes) — replay re-fires otherwise. It covers **replay only**; a recovered failed partition still re-delivers, so guard that with a `ReactorDelivery` receipt.
 - **Side-effect events:** return them directly as event objects (single `TEvent`, `IEnumerable<object>`, or `Task<...>` thereof) — Chronicle appends them to the triggering event source. To target a different event source/stream, return `EventForEventSourceId(id, @event)` wrappers (the same cross-stream mechanism as a command — see [reactors.md](./reactors.md)); the wrapper is self-describing, so set the stream type, source type or `Subject` on it when you need full metadata control. Don't inject `IEventLog` for the normal path; reserve it for explicit append-result/wait/options/mixed-target workflows.
-- **Commands from a reactor:** inject `ICommandPipeline` and `Execute(command)` (scopeless overload) — runs the full validation/authorization/handler pipeline. Don't reach for `IEventLog` to change state in another slice.
+- **Commands from a reactor:** **return** the `[Command]` (or a collection of commands) from a `[OnceOnly]` handler — Arc executes it through the full validation/authorization/handler pipeline and a denied or invalid result fails the partition rather than disappearing. A reactor has no principal, so a `[Roles]`-gated command needs `[ExecuteCommandsAsSystem("<role>")]` on the reactor class. The imperative `ICommandPipeline.Execute(command)` remains available (`[OnceOnly]`, inspect the `CommandResult`, supply your own execution context — see the **cratis-arc-command-execution** skill). Don't reach for `IEventLog` to change state in another slice. Details and the analyzer: [reactors.md](./reactors.md).
 - **[convention] Stateless, idempotent, read state via Chronicle read models** (`GetInstanceById`), not `IMongoCollection<T>`. Don't throw to "validate" malformed inbound events — that pauses the partition and can quarantine the observer; record an explicit failure/dead-letter event instead.
 
 ## Compliance (PII)
@@ -305,13 +308,15 @@ public Task AuthorRegistered(AuthorRegistered @event, EventContext context) => .
 
 The compliance **subject** is the encryption-key identity. It is resolved first-match-wins:
 
-| Priority | Mechanism |
-| --- | --- |
-| 1 | `Subject` as the second tuple element returned from `Handle()` (computed in the handler) |
-| 2 | `ICanProvideSubject.GetSubject()` on the command |
-| 3 | a `Subject`-typed property on the command |
-| 4 | an `EventSourceId<T>` property (the typed identity is the subject — no attribute) |
-| 5 | `[Subject]` on a **non-`EventSourceId<T>`** property (Arc converts via `ToString()`) |
+| Priority | Mechanism | Resolved by |
+| --- | --- | --- |
+| 1 | `Subject` as a tuple element returned from `Handle()` (computed in the handler) | Arc |
+| 2 | `ICanProvideSubject.GetSubject()` on the command | Arc |
+| 3 | a `Subject`-typed property, or a `[Subject]`-marked property, on the **command** (any other type is converted with `ToString()`) | Arc |
+| 4 | a `[Subject]`-marked property on the **event** being appended | Chronicle client |
+| 5 | otherwise the **event source id** of the append — for a command, whatever its event-source-id resolution produced (`ICanProvideEventSourceId` → `EventSourceId<T>` property → `[Key]`) | Chronicle kernel |
+
+So a command whose identity is an `EventSourceId<T>` needs no attribute at all: with nothing marked, that identity is the subject. Mark `[Subject]` only when the person is *not* the stream — and never on the `EventSourceId<T>` itself (`CHR0026`).
 
 `ICanProvideSubject` lives in `Cratis.Chronicle.Events` (alongside `ICanProvideEventSourceId`/`ICanProvideEventStreamId`). `[Subject]` is *not* aggregate identity. A managed read-model document has **one** subject — never mix multiple people's PII in one document; split into person-scoped models.
 
@@ -327,7 +332,7 @@ Cross-slice access is **read-only and goes through Chronicle** — inject anothe
 
 ## Dialogs
 
-Frontend commands run through Cratis dialog wrappers — **never** import `Dialog` from `primereact/dialog`. Use `CommandDialog` (executes a command) or `Dialog` (data collection) from `@cratis/components`. See [dialogs.md](./dialogs.md).
+Frontend commands run through the Cratis dialogs — never a vendor or hand-rolled modal. Use `CommandDialog` (executes a command) from `@cratis/components/CommandDialog` or `Dialog` (data collection) from `@cratis/components/Dialogs`. See [dialogs.md](./dialogs.md).
 
 ## See also
 

package/package/corpus/rules/writing-correct-examples.md

@@ -16,6 +16,7 @@ For each framework type, attribute, method, prop, hook, or import in an example,
 - **C# / backend** — grep real usage in a reference application (e.g. Cratis **Studio**) and the product `Source/` trees of the Cratis repos checked out alongside this one (`Arc/Source`, `Chronicle/Source`). For extension methods, find the `public static … (this <Type> …)` signature and note **which type it extends**.
 - **React / Components** — the authoritative prop names are in the compiled type defs of the installed package (`node_modules/@cratis/components/dist/esm/**/*.d.ts`) or the `Components` source `dist`. Real usage: a reference app's `*.tsx`.
 - **Invented *domain* names are fine** (event/concept/command names like `AuthorRegistered`, `BookId`). Only **framework APIs** must be real. Never invent a framework interface, attribute, prop, method, or import path.
+- **Read the source at the version the reader runs, never at a checkout's `HEAD`.** A sibling clone's working tree is whatever someone last checked out; the package the reader installed is a tag. Read with `git show <tag>:<path>` and `git grep <pattern> <tag> -- <path>` — both work without touching the checkout, so a dirty or shared worktree is never a reason to skip the check. Name the repository and the tag in the claim ("`Arc v22.16.0`, `ParameterDependencyResolver.cs:44-62`") so the next reader can re-run it. Where the corpus states a version in a skill's *Verified product sources* table, that tag is the one to read; when a consumer's pin is newer, re-read at theirs. A release note is a reason to look, not evidence that a behavior changed or that a workaround can be retired — retire a workaround only after the original reproduction passes at the new tag.
 
 ## Complete and correct
 

package/package/corpus/skills/cratis-application-react-specifications/SKILL.md

@@ -57,7 +57,7 @@ Behavior that can regress without TypeScript catching it:
 - **Component rendering** only when the markup, a disabled state, or wrapper
   behavior is genuinely the point.
 
-Do **not** specify generated Cratis proxies, PrimeReact or framework internals,
+Do **not** specify generated Cratis proxies, Cratis Components or framework internals,
 CSS pixel-perfection, snapshots, or trivial presentational pass-throughs.
 
 ## View-model specification — the default shape
@@ -109,9 +109,9 @@ import React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { describe, beforeEach, it, vi } from 'vitest';
 
-vi.mock('primereact/dialog', () => ({
-    Dialog: (props: { footer?: React.ReactNode; children?: React.ReactNode }) =>
-        React.createElement('div', null, props.footer, props.children),
+vi.mock('@cratis/components/Dialogs', () => ({
+    Dialog: (props: { buttons?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', null, props.children, props.buttons),
 }));
 
 describe('when rendered while busy', () => {

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -19,11 +19,13 @@ This skill decides **which scenario** and **what to cover**. The C# mechanics
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Testing` | `22.10.4` | `CommandScenario<TCommand>` and the `CommandResult` assertions |
-| `Cratis.Arc.Chronicle.Testing` | `22.10.4` | `Given`, `EventLog`, `AppendedEvents` and the appended-event assertions on a command scenario |
-| `Cratis.Chronicle.Testing` | `16.45.2` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
+| `Cratis.Arc.Testing` | `22.16.0` | `CommandScenario<TCommand>` and the `CommandResult` assertions |
+| `Cratis.Arc.Chronicle.Testing` | `22.16.0` | `Given`, `EventLog`, `AppendedEvents` and the appended-event assertions on a command scenario |
+| `Cratis.Chronicle.Testing` | `18.3.0` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
 | `Cratis.Specifications.XUnit` | `4.x` | The `Specification` base and the `ShouldXxx` assertions |
 
+> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
+
 `Cratis.Testing` is the meta-package that brings `Cratis.Arc.Testing` and
 `Cratis.Arc.Chronicle.Testing` together. Reverify against the owning product
 repository before claiming support for another version.
@@ -109,9 +111,13 @@ public class and_name_is_unique : Specification
 #endif
 ```
 
-The scenario's own surface is `Services`, `Context`, `Execute(command)` and
-`Validate(command)` — `Validate` runs the filters without the handler.
-Everything else is an extension method.
+The scenario's own surface is `Services`, `Context`, `Execute(command[, ct])`,
+`Validate(command)` (runs the filters without the handler), `LastResult`,
+`Operations` and the three operation assertions
+(`ShouldHaveExecutedOperation<T>()`, `ShouldHaveCompensatedOperation<T>()`,
+`ShouldHaveNoOperationInvocations()`); it is `IDisposable`/`IAsyncDisposable`.
+Seeding (`Given`), the event log and the event assertions arrive as extension
+members from the Chronicle integration.
 
 ## Step 5 — Seed prior state through `Given`
 
@@ -186,8 +192,10 @@ keyed by **command and event type**. They return `Task`, so the fact is
 
 ⚠️ On a command scenario the second argument is a **predicate**
 (`Func<TEvent, bool>`), not an assertion callback. The `Action<TEvent>` validator
-overloads exist only on the `IEventSequence` extensions in
-`Cratis.Chronicle.Testing`, which is a different receiver.
+shape lives on other receivers — the `IEventSequence` extensions in
+`Cratis.Chronicle.Testing`, `AppendedEventWithResult.ShouldHaveEvent<TEvent>(Action<TEvent>?)`,
+and the `IChronicleSetupFixture` extension in `Cratis.Chronicle.XUnit.Integration`
+— never on `CommandScenario`.
 
 Sequence numbers are **zero-based**: the first event is `0`, and the tail after a
 single append is `0`, never `1`.

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/SKILL.md

@@ -15,10 +15,12 @@ told about them. Each has its own extension point.
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Arc.Core` | `22.10.4` | `Cratis.Arc.Identity`, `Cratis.Arc.Authorization`, `Cratis.Arc.Authentication`, `Cratis.Arc.Tenancy` |
-| `Cratis.Arc` | `22.10.4` | ASP.NET Core hosting, `AddMicrosoftIdentityPlatformIdentityAuthentication` |
-| `@cratis/arc` | `22.10.4` | `IdentityProvider`, `IIdentity` |
-| `@cratis/arc.react` | `22.10.4` | `IdentityProvider` component, `useIdentity`, `RequireRole` |
+| `Cratis.Arc.Core` | `22.16.0` | `Cratis.Arc.Identity`, `Cratis.Arc.Authorization`, `Cratis.Arc.Authentication`, `Cratis.Arc.Tenancy` |
+| `Cratis.Arc` | `22.16.0` | ASP.NET Core hosting, `AddMicrosoftIdentityPlatformIdentityAuthentication` |
+| `@cratis/arc` | `22.16.0` | `IdentityProvider`, `IIdentity` |
+| `@cratis/arc.react` | `22.16.0` | `IdentityProvider` component, `useIdentity`, `RequireRole` |
+
+> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
 
 Reverify before claiming support for another version.
 

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/authentication.md

@@ -1,6 +1,6 @@
 # Authentication
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.10.4`. Types are in
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.16.0`. Types are in
 `Cratis.Arc.Authentication` and `Cratis.Arc.Identity`.
 
 ## The contract

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/authorization.md

@@ -1,6 +1,6 @@
 # Authorization
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.10.4`. Everything below
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.16.0`. Everything below
 is in `Cratis.Arc.Authorization` unless stated.
 
 ## Default access differs by hosting model

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/frontend.md

@@ -1,6 +1,6 @@
 # Frontend identity
 
-Verified against `@cratis/arc` and `@cratis/arc.react` `22.10.4`.
+Verified against `@cratis/arc` and `@cratis/arc.react` `22.16.0`.
 
 ## `@cratis/arc/identity`
 

package/package/corpus/skills/cratis-arc-authentication-authorization-and-identity/references/local-development.md

@@ -1,6 +1,6 @@
 # Running with an identity locally
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.10.4`.
+Verified against `Cratis.Arc.Core` and `Cratis.Arc` `22.16.0`.
 
 ## What Arc does not give you