@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/rules/react.md

@@ -0,0 +1,195 @@
+---
+applyTo: "**/*.tsx, **/Components/**/*.ts"
+profile: application
+paths:
+  - "**/*.tsx"
+  - "**/Components/**/*.ts"
+---
+
+# 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 proxy boundary
+
+`dotnet build` (Debug) generates a typed TypeScript proxy per command and query, emitted next to the slice's `.cs`. React imports those proxies and calls their static hooks. **Backend before frontend, always** — the proxies don't exist until the backend compiles. **Never edit a generated proxy** (`// @generated by Cratis` header) — fix the C# source and rebuild.
+
+## MVVM
+
+Move behavior out of the render function. Two accepted idioms:
+
+- **`withViewModel`** from `@cratis/arc.react.mvvm` — for command/query orchestration, long-lived UI state, and workflow components that benefit from observable class state.
+- **A tested pure state module/helper** — for deterministic page/form state that doesn't need MobX. The component stays rendering + event wiring; the module owns derived state, filtering/sorting, wizard steps, command-value derivation, and has BDD specs (see [frontend-testing.md](./frontend-testing.md)).
+
+Don't leave complex behavior inline. Trivial presentational leaf components need no view model.
+
+```ts
+import { injectable } from 'tsyringe';
+
+@injectable()
+export class <Entity>ListingViewModel {
+    selectedId: string | null = null;
+    select(id: string) { this.selectedId = id; }
+}
+```
+
+```tsx
+import { withViewModel } from '@cratis/arc.react.mvvm';
+
+export const Listing = withViewModel(<Entity>ListingViewModel, ({ viewModel }) => (
+    /* read viewModel state inside JSX; call viewModel methods */
+));
+```
+
+**View-model rules:**
+- Pure TypeScript classes — no JSX, never store React state, never call React hooks (`useIdentity`, `useNavigate`) inside one — inject the Cratis abstraction instead.
+- Fields are auto-observable (`makeAutoObservable` is applied by `withViewModel`); no `@observable` on plain assignments.
+- Inject services via the primary constructor (`@injectable` / tsyringe).
+- A non-trivial view model must be constructible directly in a spec and covered with BDD specs.
+
+### When to extract a view model
+
+Extract as soon as a component has **any** of: 3+ `useState`, any `useCallback` beyond a trivial inline handler, any `useEffect` that synchronizes state, derived values computed from other state (use a getter), or state shared via prop drilling.
+
+### MobX reactivity
+
+- **Dereference late** — read `viewModel.property` *inside* JSX; never destructure observables at the top of the component body (the captured value won't track changes).
+- **Computed getters** for derived state (auto-`computed`) — not `useMemo` in the component.
+- **`useCallback`/`useMemo` are unnecessary in `withViewModel` components** — the render is wrapped in `Observer`. Their presence signals state that belongs in the view model. (This does *not* apply to plain functional components using proxy hooks directly. A plain component reaching for `useCallback` to stabilize a handler is a signal that handler belongs in a view model or tested state module.)
+- **Observable arrays into raw children** — passing `viewModel.items` (an observable array) to a *raw non-observer* child needs `viewModel.items.slice()` to materialize a plain array. Uncommon in practice — prefer `DataTableForObservableQuery`, which handles reactivity internally.
+
+### Props / route / query params in view models
+
+| Need | Mechanism |
+|---|---|
+| Props that change after mount | implement `IHandleProps<TProps>` → `handleProps(props)` (called on initial mount **and** every props change) |
+| Props set once at mount | `@props readonly componentProps: TProps` |
+| Route params | `@params readonly routeParams: RouteParams` — put `@field` on each property |
+| Query-string params | `@queryParams` |
+
+`@field` on each route/query-param property is what makes Arc's JSON serializer convert the URL **strings** to the property's real type — **without `@field`, the values stay strings**.
+
+### Injectable abstractions (never touch browser/React globals in a view model)
+
+| Interface | Package | Replaces |
+|---|---|---|
+| `IMessenger` | `@cratis/arc.react.mvvm/messaging` | cross-component selection (list↔detail) — not React Context |
+| `IDialogs` | `@cratis/arc.react.mvvm/dialogs` | imperative confirmation/busy dialogs from a view model |
+| `IIdentityProvider` | `@cratis/arc/identity` | identity in a view model (not the `useIdentity` hook) |
+| `ILocalStorage`, `INavigation` | `@cratis/arc.react.mvvm/browser` | `localStorage`, URL navigation |
+| `IViewModelDetached` | `@cratis/arc.react.mvvm` | teardown (`detached()`) for subscriptions/timers |
+
+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.
+- **`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(); }`).
+
+**Decorator prerequisite:** `experimentalDecorators` + `emitDecoratorMetadata` + `reflect-metadata` must be wired (tsconfig + the build) for `@injectable`/`@props`/`@params`/`@field` to work — don't change them.
+
+## Queries
+
+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>.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>`) |
+| `<Query>.useSuspenseWithPaging(pageSize, ...)` | suspense + paging |
+| `<ObservableQuery>.use(...)` | live observable (`ISubject<T>` backend) pushed over SSE/WebSocket |
+| `<ObservableQuery>.useChangeStream(args?, getKey?, ...)` | item-level add/replace/remove deltas |
+
+**Return-tuple shapes** (load-bearing — the observable variants have no `perform`):
+
+| Hook | Returns |
+|---|---|
+| `<Query>.use(args?, sorting?)` | `[result, perform]` |
+| `<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 }` |
+
+`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.
+
+- **`useChangeStream` `getKey`:** without `getKey`, removed items can't be identified — everything shows up as `added`. `getKey` enables `replaced` detection. Change streams exist only on observable queries returning `IEnumerable<T>`.
+- **Conditional:** `<Query>.when(!!id).use({ id: id ?? '' })` — when `condition` is false no request/subscription is made and the hook returns `QueryResultWithState.empty()` (`hasData: false`, empty `data`); guard with `result.hasData`. `.when()` works with paging, suspense, and observable variants too.
+- **Suspense:** `useSuspense()` throws a promise while loading and a typed error on failure — it **must** render inside a `<QueryBoundary>` (combines `<Suspense>` + `QueryErrorBoundary`) or React surfaces the thrown promise as an unhandled rejection. `useSuspense()` **re-suspends** on `refresh()`/`setSorting()`/`setPage()` (the cache entry is cleared). `<QueryBoundary onError={({ isQueryFailed, isQueryUnauthorized, error, reset }) => ...}>` exposes the failure; `(error as QueryFailed).exceptionMessages` carries diagnostics. In test teardown clear the caches with `clearSuspenseQueryCache()` / `clearSuspenseObservableQueryCache()` (`@cratis/arc.react/queries`).
+- **`QueryScope`** + `useQueryScope()` (`@cratis/arc.react/queries`): `<QueryScope setIsPerforming={...}>` aggregates one `isPerforming` flag across the queries inside it — they register automatically (no manual add); scopes nest (inner registers with the nearest outer).
+
+## Commands
+
+A typed proxy class is generated per command. For programmatic execution:
+
+```tsx
+const [command, setCommandValues, clearCommandValues] = Command.use();   // 3-tuple
+command.someField = value;                  // or setCommandValues({ ... })
+const result = await command.execute();
+```
+
+Inside dialogs, use `CommandDialog` + CommandForm fields rather than driving the command by hand — see [dialogs.md](./dialogs.md).
+
+### Read `CommandResult` by the granular flag — not just `isSuccess`
+
+| Flag | Meaning | UX response |
+|---|---|---|
+| `isSuccess` | `isAuthorized && isValid && !hasExceptions` | happy path |
+| `isAuthorized` | `[Roles]`/policy rejected | redirect to login / "not allowed" |
+| `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.
+
+Out-of-dialog execution branches in this order:
+
+```tsx
+const result = await command.execute();
+if (!result.isAuthorized) { redirectToLogin(); return; }
+if (!result.isValid)      { /* validationResults → inline field errors */ return; }
+if (result.hasExceptions) { toast.error('Something went wrong'); console.error(result.exceptionMessages); return; }
+// happy path — refresh queries, close, etc.
+```
+
+`toastCommandResult(result, opts)` from `@cratis/components/Notifications` collapses this whole branch into one call (with a `<Toaster />` mounted) — success/not-authorized/validation/exception → the right toast, no stack traces shown.
+
+### Command helpers
+
+- **`useCommandInstance(Command)`** — read the live reactive command instance for dependent fields (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`.
+
+### `<Arc>` global configuration
+
+Top-level provider for microservice name and API base path. Config props (with defaults):
+
+| Prop | Default | Notes |
+|---|---|---|
+| `httpHeadersCallback` | — | returns `HeadersInit` merged into every request (bearer/tenant headers) |
+| `queryTransportMethod` | `ServerSentEvents` | SSE is capped at 4 connections on HTTP/1.1 |
+| `observableQueryTransferMode` | `Delta` | `Delta` = server ChangeSet/client diff; `Full` = all items as `added` |
+| `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.
+
+## Composition
+
+- Single responsibility — if you write a `// Section` comment inside a component, that section is its own component. Parent owns state; children receive props.
+- Single-file component → in the slice folder; multi-file → a folder named after the component with an `index.ts` re-export.
+- A `.tsx` belongs in the slice folder it implements — never one level up. A feature's pass-through layout renders only `<Outlet />`.
+
+## 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.
+
+## See also
+
+- [components.md](./components.md) — component structure, CSS, PrimeReact tokens, 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

@@ -0,0 +1,238 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+profile: application
+---
+
+# Reactor Instructions
+
+Reactors are the "if this then that" of event sourcing — they observe events and produce side effects. Unlike projections (which build state), reactors *do things*: send emails, trigger commands in other slices, call external APIs.
+
+## IReactor — Marker Interface
+
+`IReactor` is a **marker interface** with no methods to implement. Method dispatch is entirely by convention: the first parameter type of each public method determines which event it handles.
+
+```csharp
+public class ProjectRegisteredNotifier(INotificationService notifications) : IReactor
+{
+    /// <summary>
+    /// Reacts to <see cref="ProjectRegistered"/> events by sending a notification.
+    /// </summary>
+    /// <param name="event">The event.</param>
+    /// <param name="context">The event context.</param>
+    public async Task ProjectRegistered(ProjectRegistered @event, EventContext context) =>
+        await notifications.Notify($"Project '{@event.Name}' was registered.");
+}
+```
+
+## Method Signature
+
+```csharp
+public Task MethodName(TEvent @event, EventContext context)
+```
+
+- **First parameter** — the event type. This determines which events the method subscribes to.
+- **Second parameter onward** — dependencies, resolved when the method is invoked: `EventContext`, a read model, or a service. All are optional and there is no limit on how many; see [Taking Dependencies](#taking-dependencies). The analyzer constrains their *kind*, not their count — a primitive, value type or `string` after the first parameter is flagged because it cannot be resolved.
+- **Return type** — `Task` or `void`, or a side-effect type (`TEvent`, `EventForEventSourceId`, or an `IEnumerable<>` of either — or of `object` to mix them) returned directly (sync) or wrapped in `Task<...>` (async). Prefer `Task`/async for real side effects, but synchronous returns are fully supported — there is no "always async" requirement.
+- **Method name** — can be anything descriptive. The name is for readability, not dispatch.
+
+## Handling replay differently — `[Replay]`
+
+A reactor sees the same event twice for different reasons: as it happens, and again when its observer is replayed. When those call for different work, mark a second handler for the same event type with **`[Replay]`** and it takes over for the duration of the replay.
+
+```csharp
+public class OrderNotifications(INotificationService notifications) : IReactor
+{
+    public Task OrderPlaced(OrderPlaced @event) => notifications.Notify($"Order {@event.Number} placed.");
+
+    [Replay]
+    public Task OrderPlacedDuringReplay(OrderPlaced @event) => Task.CompletedTask;
+}
+```
+
+- With a `[Replay]` handler, **only** it runs during replay — the regular handler does not also run.
+- Without one, the regular handler runs during replay exactly as before, so this changes nothing for existing reactors.
+- An event type handled *only* by a `[Replay]` handler is still subscribed to.
+- Reach for **`[OnceOnly]`** instead when the side effect should simply not happen again; use `[Replay]` when replay needs to do something *different* rather than nothing.
+
+## Taking Dependencies
+
+Beyond the event and `EventContext`, a handler method can take any number of additional parameters as dependencies. Only the first parameter is fixed (it is the event that drives dispatch); every parameter after it is resolved when the method is invoked.
+
+```csharp
+public class OrderProcessing(IShippingService shipping) : IReactor
+{
+    public async Task OrderPlaced(OrderPlaced @event, EventContext context, Order order, IPricingService pricing)
+    {
+        // 'order' is the read model, resolved by Chronicle for this event's key.
+        // 'pricing' is resolved from the service provider.
+        await shipping.Schedule(order, pricing.PriceFor(order));
+    }
+}
+```
+
+How each parameter is resolved:
+
+- **`EventContext`** — receives the event context (position independent).
+- **A read model** — a type that has a reducer or a projection (declarative or model-bound). Chronicle resolves it directly — read models never go through the service provider. A **materialized** read model (the default, for projections and reducers alike) is read from its sink, so it is **eventually consistent** — as current as its observer. Mark it **`[Passive]`** when the reactor needs it **strongly consistent**: a passive read model has no sink, so Chronicle computes it on demand from the events at the point the reactor runs.
+- **Any other type** — resolved from the service provider (constructor injection on the reactor itself is still preferred for collaborators used by every method).
+
+### Resolving the read model key
+
+By default the read model is materialized using the `EventSourceId` from the event context. When the key differs from the event source — for example the event carries the id of a related entity — implement `ICanResolveReadModelKey` on the reactor:
+
+```csharp
+public class OrderProcessing : IReactor, ICanResolveReadModelKey
+{
+    public ReadModelKey Resolve(object @event, EventContext context) =>
+        ((OrderLineAdded)@event).OrderId;
+
+    public Task OrderLineAdded(OrderLineAdded @event, Order order)
+    {
+        // 'order' was materialized using OrderId rather than the triggering event's source id.
+        return Task.CompletedTask;
+    }
+}
+```
+
+The resolved key applies to every read model parameter across all of the reactor's handler methods.
+
+## Returning Side-Effect Events
+
+Instead of taking a dependency on `IEventLog`, reactor handler methods can return events that should be appended automatically. The default target is the event log; the EventSourceId defaults to the one from the triggering event.
+
+### Return a single event
+
+```csharp
+public Task<SomeEvent> Handle(AnEvent @event, EventContext context) =>
+    Task.FromResult(new SomeEvent(@event.Name));
+```
+
+### Return a collection of events
+
+```csharp
+public Task<IEnumerable<object>> Handle(AnEvent @event, EventContext context) =>
+    Task.FromResult<IEnumerable<object>>([new SomeEvent(), new AnotherEvent()]);
+```
+
+### Target a specific event source id via `EventForEventSourceId`
+
+Return an `EventForEventSourceId` to append to an explicit `EventSourceId` — for example a different entity than the one that triggered the reactor. It also carries the `EventStreamType`, `EventStreamId`, `EventSourceType`, `Subject`, `Occurred` time, `Tags` and `Causation` per event:
+
+```csharp
+public Task<EventForEventSourceId> Handle(AnEvent @event, EventContext context) =>
+    Task.FromResult(new EventForEventSourceId(@event.RelatedId, new SomeEvent(@event.Name))
+    {
+        EventStreamType = new EventStreamType("custom"), // optional
+        EventSourceType = new EventSourceType("order"),  // optional
+        Subject = new Subject(@event.RelatedId),         // optional
+    });
+```
+
+### Return events for multiple event source ids
+
+Return `IEnumerable<EventForEventSourceId>` to append to several event source ids in one transaction:
+
+```csharp
+public Task<IEnumerable<EventForEventSourceId>> Handle(AnEvent @event, EventContext context) =>
+    Task.FromResult<IEnumerable<EventForEventSourceId>>(
+    [
+        new(@event.RelatedId, new SomeEvent()),
+        new(@event.OtherId, new AnotherEvent())
+    ]);
+```
+
+> Reactor-level metadata (`ICanProvideEventSourceId`, `ICanProvideSubject`, `[EventStreamType]`, …) applies to bare `TEvent` returns. An `EventForEventSourceId` is self-describing, so its own values are used instead. You can mix bare events and `EventForEventSourceId` in a single `IEnumerable<object>` return — each is appended with its respective metadata, all in one transaction.
+
+### Cross-stream via `EventForEventSourceId`
+
+To append a side-effect event to a **different** event source, return `EventForEventSourceId(id, @event)` (single or `IEnumerable<EventForEventSourceId>`) — the same cross-stream wrapper a command `Handle()` uses. The wrapper is self-describing, so it is also where you set the event stream type and id, source type, `Subject`, occurred time, tags and causation; set only the ones you need and the rest take the append defaults.
+
+```csharp
+public Task<IEnumerable<EventForEventSourceId>> Handle(AnEvent @event, EventContext context) =>
+    Task.FromResult<IEnumerable<EventForEventSourceId>>(
+    [
+        new EventForEventSourceId(@event.RelatedId, new SomeEvent())
+    ]);
+```
+
+> **Chronicle version note:** reactor side-effect handling of `EventForEventSourceId` wrappers has shipped since Chronicle 15.35.
+
+## External event stores (outbox / inbox)
+
+Cross-service events route through Chronicle's outbox/inbox rather than a shared log:
+
+- The producing service appends its **public contract event** to `EventSequenceId.Outbox`.
+- The consuming observer listens to the implicit inbox sequence for the source store (`inbox-<source-store>`).
+- Chronicle creates/reuses the outbox→inbox subscription from the observer's `[EventStore]` metadata, or from `[EventStore]` on the event type/assembly. Put `[assembly: EventStore("<source-store>")]` in the contracts project when every event there originates from one service; use observer-level `[EventStore("<source-store>")]` to override.
+- An observer-level `[EventStore]` **cannot** be combined with `[EventSequence]`, `[EventLog]`, or `Reactor(eventSequence: ...)`.
+
+## Confirming downstream completion — `WaitForCompletion`
+
+The default is fire-and-forget. When a caller's correctness depends on all observers (projections, reducers, reactors) having processed an appended event before returning — integration tests, synchronous webhook surfaces — call `WaitForCompletion` (from `Cratis.Chronicle.Observation`) on the `AppendResult`/`AppendManyResult`. It returns an `AppendResultWaitForCompletionResult` carrying `IsSuccess` and `FailedPartitions` (the full set across all affected observers, not just the first to fail). Reach for it deliberately — not as a default.
+
+## Critical Rules
+
+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.
+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.
+
+## Slice Types That Use Reactors
+
+| Slice type | Pattern |
+|------------|---------|
+| **Automation** | Reacts to events, makes decisions, triggers side effects |
+| **Translation** | Adapts events from one slice/system by triggering commands in another |
+
+### Automation Example
+
+```csharp
+public class ProjectRegisteredNotifier(INotificationService notifications) : IReactor
+{
+    /// <summary>
+    /// Sends a notification when a project is registered.
+    /// </summary>
+    /// <param name="event">The event.</param>
+    /// <param name="context">The event context.</param>
+    public async Task ProjectRegistered(ProjectRegistered @event, EventContext context) =>
+        await notifications.Notify($"Project '{@event.Name}' was registered.");
+}
+```
+
+### Translation Example
+
+```csharp
+public class StockKeeping(IStockKeeper stockKeeper, ICommandPipeline commandPipeline) : IReactor
+{
+    /// <summary>
+    /// Reacts to a book reservation by decreasing stock.
+    /// </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)));
+}
+```
+
+## 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:
+
+```csharp
+void Establish()
+{
+    _notifications = Substitute.For<INotificationService>();
+    _scenario = new(new ServiceCollection().AddSingleton(_notifications).BuildServiceProvider());
+}
+
+async Task Because() => await _scenario.Given.ForEventSource(_id).Events(new ProjectRegistered("Acme"));
+
+[Fact] async Task should_notify() => await _notifications.Received(1).Notify("Project 'Acme' was registered.");
+```
+
+For reactors that return side-effect events, assert the resulting appends through the scenario's event store; for non-event side effects, assert on the mocked services (as above). See [specs.scenarios.csharp.md](./specs.scenarios.csharp.md) for the full `*Scenario` family.

package/package/corpus/rules/rtk.md

@@ -0,0 +1,37 @@
+---
+applyTo: "**/*"
+description: "Use when running any shell command, reading files, or searching code. Route every command rtk supports through rtk (a hook auto-rewrites Bash commands); call rtk read/grep/find directly because the built-in Read/Grep/Glob tools bypass that hook."
+---
+
+# Using rtk (Token-Optimized Commands)
+
+[rtk](https://github.com/rtk-ai/rtk) (Rust Token Killer) is a CLI proxy that filters and compresses command output *before it reaches the model* — typically **60–90% fewer tokens** on common dev commands, with no loss of the signal you actually need. The default in this corpus is to **run every command rtk supports through rtk**. The savings are real and compound across a session: build, test, lint, git, search, and file-read output are exactly the high-volume, low-signal outputs rtk trims.
+
+## How it works — let the hook do its job
+
+A `PreToolUse` hook **auto-rewrites Bash commands** to their `rtk` equivalent transparently and at zero token overhead (`git status` → `rtk git status`). For any supported command you do **nothing special** — run it normally and the hook wraps it.
+
+- **Never bypass it.** Don't disable the hook, and reserve `rtk proxy <cmd>` for the rare case where you genuinely need the raw, unfiltered output (e.g. debugging what a filter dropped).
+- **Audit coverage** with `rtk gain` (savings so far) and `rtk discover` (commands that slipped past rtk — missed opportunities to close).
+
+## What rtk supports (route these through rtk)
+
+- **Files** — `ls`, `tree`, `read`, `find`, `grep`, `diff`
+- **Git & GitHub** — `git status/log/diff/add/commit/push/pull`, `gh pr/issue/run …`
+- **Tests** — `dotnet test`, Jest, Vitest, Playwright, pytest, Go, Cargo, RSpec
+- **Build & lint** — `dotnet build`, `tsc`, ESLint, Biome, Prettier, Cargo Clippy, Ruff, golangci-lint, Rubocop
+- **Package managers** — pnpm/npm/yarn, pip, Bundler, Prisma
+- **Cloud & containers** — AWS CLI, Docker, Kubernetes, OpenShift
+
+In practice this means the Cratis **quality-gate commands** — `dotnet build`, `dotnet test`, `yarn lint`, `npx tsc -b`, `git`, `gh` — all flow through rtk automatically. Just run them.
+
+## The one gap — built-in tools bypass the hook
+
+The hook only sees **Bash** commands. Claude Code's built-in `Read`, `Grep`, and `Glob` tools (and the Copilot equivalents) do **not** pass through it, so they are **not** auto-rewritten — and those are some of the most token-heavy operations in a session.
+
+- For **bulk reads and broad searches** where output volume is large, call **`rtk read` / `rtk grep` / `rtk find`** from the terminal so the savings are captured. This is a deliberate override of the usual "prefer the built-in file tools" default.
+- Keep the **built-in** `Read`/`Grep`/`Glob` for **small, targeted reads** and when you need exact line references for an edit — rtk filters output, so it serves exploration and volume, not the precise content an `Edit` must match verbatim.
+
+## Availability
+
+This assumes the `rtk` binary is installed and the hook configured (`rtk init -g`). If `rtk` is **not** on `PATH`, ignore this rule and use the normal tools — never block work on rtk being present.

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

@@ -0,0 +1,139 @@
+---
+applyTo: "**/for_*/**/*.cs, **/when_*/**/*.cs"
+paths:
+  - "**/for_*/**/*.cs"
+  - "**/when_*/**/*.cs"
+---
+
+# How to Write C# Specs
+
+Extends the base [specs.md](./specs.md) (folder structure, naming, philosophy) with C#-specific conventions. This file is the **universal foundation** used in **both** profiles — the `Cratis.Specifications` pattern (`Establish → Because → should_`) with NSubstitute.
+
+> **Which spec surface?**
+> - **Framework / library code** (Chronicle kernel, Arc pipeline, source generators, Fundamentals): the `Specification` base + NSubstitute in this file is the dominant mode — unit-test the classes under test in isolation. Reach for a `*Scenario` helper (in [specs.scenarios.csharp.md](./specs.scenarios.csharp.md)) **only** when testing the very engine your repo provides — Arc → `CommandScenario`, Chronicle → the event/projection/reactor scenarios. The **write-specs** skill is application-oriented, not for general framework specs.
+> - **Event-sourced applications on Cratis** (commands, projections, reducers, reactors, constraints): use this base **plus** the in-process scenario family — see **[specs.scenarios.csharp.md](./specs.scenarios.csharp.md)** (`profile: application`) and the **write-specs** skill.
+
+`Cratis.Specifications` keeps the approach of Machine.Specifications (MSpec): `Establish → Because → should_` maps to "Given → When → Then" and keeps each spec focused on *one setup, one action, one set of assertions*.
+
+## Frameworks
+
+- [xUnit](https://xunit.net/) for execution.
+- [Cratis.Specifications](https://github.com/Cratis/Specifications) for BDD specification by example — the `Specification` base class discovers `Establish`/`Because`/`Destroy` by convention (no attributes).
+- [NSubstitute](https://nsubstitute.github.io/) for mocking collaborators.
+- Spec projects are named `<Source>.Specs`.
+
+## BDD pattern
+
+`Establish` sets up the world, `Because` performs the single action under test, `should_*` facts verify individual outcomes. Any method can be `async Task`.
+
+```csharp
+public class when_combining_parts : Specification
+{
+    object[] _parts;
+    string _result;
+
+    void Establish() => _parts = ["First", "Second", "Third"];
+    void Because() => _result = KeyHelper.Combine(_parts);
+
+    [Fact] void should_combine_all_parts() => _result.ShouldEqual("First+Second+Third");
+}
+```
+
+| Method | Purpose | Notes |
+|---|---|---|
+| `void Establish()` | setup, before `Because()` | each class in the chain has its own, run base-first — never call `base.Establish()` |
+| `void Because()` | the single action under test | only in concrete spec files, never in a reusable context |
+| `[Fact] void should_*()` | one assertion per fact | use the `ShouldXxx()` extension methods |
+| `void Destroy()` | teardown after each test | |
+
+## Reusable layered contexts
+
+Layered contexts (`all_dependencies → a_<sut> → when_*`) capture shared setup base-first: the base mocks dependencies, the next builds the system under test, each spec adds only what's unique.
+
+```csharp
+// given/all_dependencies.cs — mocks all deps
+public class all_dependencies : Specification
+{
+    protected IEventStore _eventStore;
+    void Establish() => _eventStore = Substitute.For<IEventStore>();
+}
+
+// given/a_reactor_handler.cs — builds the system under test
+public class a_reactor_handler : all_dependencies
+{
+    protected ReactorHandler _handler;
+    void Establish() => _handler = new(_eventStore);
+}
+```
+
+Put the action under test only in the concrete spec's `Because()`, never in a reusable context.
+
+## NSubstitute patterns
+
+```csharp
+_service.GetValue(Arg.Any<string>()).Returns("result");
+Arg.Is<Request>(r => r.Id == expectedId)            // matcher
+_service.Received(1).DoSomething(Arg.Any<string>()); // verify
+_service.DidNotReceive().DoSomethingElse(Arg.Any<int>());
+_handler.Handle(Arg.Any<CommandContext>()).Throws(new Exception("fail"));
+```
+
+Catch exceptions for a unit under test with `Catch.Exception`:
+
+```csharp
+async Task Because() => _error = await Catch.Exception(_sut.DoSomething);
+[Fact] void should_not_fail() => _error.ShouldBeNull();
+```
+
+## Assertion extension methods
+
+From `Cratis.Specifications`: `.ShouldEqual(expected)`, `.ShouldBeTrue()`, `.ShouldBeFalse()`, `.ShouldBeNull()`, `.ShouldNotBeNull()`, `.ShouldBeEmpty()`, `.ShouldNotBeEmpty()`, `.ShouldContain(item)`, `.ShouldNotContain(item)`, `.ShouldContainOnly(items)`, `.ShouldBeOfExactType<T>()`, `.ShouldBeGreaterThan(n)`, `.ShouldBeLessThan(n)`.
+
+## Conventions
+
+- Common usings come from `GlobalUsings.Specs.cs` (`Xunit`, `NSubstitute`, `Cratis.Specifications`, …) — don't duplicate them, and don't add a using for the system-under-test namespace.
+- **`using` ordering (SA1210/SA1211):** non-aliased namespaces first, then a blank line, then `using <alias> = …` aliases sorted by alias name. Alias a type whose short name collides with a namespace segment (CS0118) — `using RegisterAuthorCmd = …` style, with a domain-meaningful alias, never a technical `Command`/`Event`/`Component` suffix.
+- Single-statement assertion lambdas use expression-body form (RCS1021) — `[Fact] void should_x() => result.ShouldEqual(...)`, not a `{ … }` block. Don't break long `should_` lines; don't add blank lines between `should_` methods.
+- **Prefer a concept's sentinel over a raw empty primitive.** When a `ConceptAs<T>` / `EventSourceId<T>` value is expected — as an argument, a mock setup, or an assertion — use its `NotSet` (or `Empty` / `New()`) static rather than a `string.Empty` / `Guid.Empty` / `0` that implicitly converts. It states intent and survives a sentinel-value change (see [concepts.md](./concepts.md)). Reserve raw `string.Empty` for genuinely non-concept `string` values (e.g. asserting a decrypted-to-empty JSON payload).
+
+## Never sleep — await a fact, not a duration
+
+**A spec never waits on the clock for the system under test.** `Thread.Sleep`, a bare `Task.Delay`, or a `SpinWait` before an assertion makes the spec pass because the machine happened to be fast enough, and it silently writes today's latency into the suite: the next fix that shifts timing in the observer/projection core then breaks specs that have nothing to do with it. That coupling — not the bugs being fixed — is the single largest source of regressions in Chronicle, and it is why fixes there keep getting rolled back.
+
+Wait on a signal instead:
+
+| Waiting for | Await |
+|---|---|
+| observers to catch up with an append | `appendResult.WaitForCompletion()` |
+| client artifacts to be registered with the kernel | `eventStore.WaitForRegistration()` |
+| an observer's state or position | `WaitTillActive` / `WaitTillSubscribed` / `WaitTillReachesEventSequenceNumber` / `WaitForState` (reactors, reducers, projections) |
+| a job | the `JobsWaitHelpers` extensions |
+| anything with no helper yet | build the signal: a `SemaphoreSlim` (or `TaskCompletionSource`) released by the code that observes the event, awaited under a timeout — `Source/Clients/XUnit.Integration/EventAppendCollection.cs` is the shipped example, and it never polls |
+
+A **deadline** is not a sleep — every helper above takes a `timeout`, and a timeout is what turns a hang into a named failure. Sleeping *between* re-checks is: a poll loop is a completion signal you have not built yet, so add the signal rather than another `while` + `Task.Delay`.
+
+Three delays are not waits at all and stay allowed — say which one it is in a comment: a test double that is **slow on purpose** so the test can observe it mid-flight (`Task.Delay(HandleTime)`), an **infrastructure readiness backoff** between retries of a connect/start that can legitimately fail, and a `Task.Delay(1)` / `Task.Yield()` that **widens an interleaving window** in a concurrency spec.
+
+The sleeps that predate this rule are frozen per file in `.github/timing-coupling-baseline.txt`; `.github/workflows/timing-coupling-ratchet.yml` fails a pull request that raises any entry or adds a file. The numbers may only go down.
+
+## What NOT to spec
+
+Simple properties are compiler-verified. Save spec effort for business logic, coordination between dependencies, and complex transformations.
+
+```csharp
+// ❌ Do NOT spec these
+public string TableName => tableName;                         // returns constructor parameter
+public IEnumerable<Property> Properties => mapper.Properties; // simple delegation
+
+// ✅ Spec complex business logic
+public decimal TotalCost => Items.Sum(i => i.Cost * i.Quantity * (1 + i.TaxRate));
+```
+
+Also don't spec logging or trivial getters.
+
+## See also
+
+- [specs.md](./specs.md) — folder structure, naming, BDD philosophy (the base this extends).
+- [specs.scenarios.csharp.md](./specs.scenarios.csharp.md) — **application profile**: the in-process scenario family (`CommandScenario` / `EventScenario` / `ReadModelScenario` / `ReactorScenario`) + out-of-process Chronicle integration, for event-sourced apps.
+- [efcore.specs.md](./efcore.specs.md) — `DbContext` specs with SQLite in-memory.
+- [frontend-testing.md](./frontend-testing.md) — TypeScript/React application BDD specs.