@cratis/pi 7.37.0 → 7.38.1

package/package/corpus/harnesses/copilot/instructions/reactors.instructions.md

@@ -0,0 +1,336 @@
+---
+applyTo: "**/*.cs"
+paths:
+  - "**/*.cs"
+profile: application
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# 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.
+
+**Model first:** when an accepted model under the model root covers this scope (or the repository is opted in: the root holds a committed `.play` file (`git ls-tree -r --name-only HEAD` lists a `.play` file there, narrowed to `-- <root>` when a root is configured) or the project explicitly set `mcpServers.screenplay.root` in `.cratis/ai.json`; master definition in `cratis-screenplay-modeling-lifecycle`), a reactor implements an automation that the model owns (`produces` / `invokes`); read the modeled slice first and keep the reactor to what the model leaves to code (gap-fill). Otherwise (not opted in) stay code-first: this file and the **cratis-chronicle-reactor** skill are the guide, and the entry-point session may propose a model at most once per session. A `.play` file outside the root, an untracked or uncommitted draft or an empty directory is not consent.
+
+## 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 InvoiceIssuedNotifier(INotificationService notifications) : IReactor
+{
+    /// <summary>
+    /// Reacts to <see cref="InvoiceIssued"/> events by sending a notification.
+    /// </summary>
+    /// <param name="event">The event.</param>
+    /// <param name="context">The event context.</param>
+    public async Task InvoiceIssued(InvoiceIssued @event, EventContext context) =>
+        await notifications.Notify($"Invoice '{@event.Number}' was issued.");
+}
+```
+
+## 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]`** when the side effect must not repeat **during replay**;
+  use `[Replay]` when replay needs different work. Neither suppresses ordinary
+  catch-up or recovery redelivery, nor limits runs per event source.
+
+## 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.
+
+### 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 RenewalBilling : IReactor
+{
+    [OnceOnly]
+    public Task<IssueRenewalInvoice> MembershipRenewed(MembershipRenewed @event, EventContext context) =>
+        Task.FromResult(new IssueRenewalInvoice(@event.MemberId, @event.Amount));
+}
+```
+
+- **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.
+- A reactor retry can execute the command's operations again; inline operations are not a substitute for reactor/outbox durability — see **cratis-arc-command-operation** (verified at Arc v22.48.1).
+- 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:
+
+- 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: ...)`.
+
+## Storage lookup failures are not absence
+
+At **Chronicle v19.50.1**, a failed next-event lookup leaves the observer's
+position unchanged. Routing defers delivery and the watchdog retries; only
+`NotFound` proves absence and permits fast-forward. The watchdog likewise does
+not advance on storage error. This fixes #4770, not every legacy delivery or
+completion limitation. Quarantined observers do not resume from this retry.
+Sources: `Source/Kernel/Core/Observation/States/Routing.cs` and
+`Observation/Observer.Watchdog.cs` at v19.50.1.
+
+## 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`. At Chronicle **v19.50.0**, it returns `AppendResultWaitForCompletionResult` with
+`IsSuccess`, `FailedPartitions`, `TimedOut` and `OutstandingObservers`. Inspect
+all of these: timeout returns `TimedOut = true`, not a successful completion.
+The optional `TimeSpan?` defaults to a 5-second server wait plus 200 ms client
+grace; `Timeout.InfiniteTimeSpan` disables both deadlines. Filtering excludes
+observers that do not consume the appended events when the client supplies the
+first sequence number. Source: `Source/Clients/DotNET/Observation/AppendResultWaitForCompletionExtensions.cs`.
+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 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. **Stable identity and single responsibility** — Give side-effecting reactors
+an explicit `[Reactor("stable-id")]`: full-type-name identity changes on a rename
+or move and catches up from the start, repeating side effects even with `[OnceOnly]`.
+Chronicle v19.50.0 discovery warns on likely drift; `ArtifactIdentityDrift = Fail`
+rejects Warning-level reactor/event-type drift (not Information-level read-model
+findings). 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 quarantine ends when an operator clears it (`ClearObserverQuarantine()`), or when the observer is subscribed again** — for an application observer that is when the client connects again, for example after a redeploy; Kernel-owned observers are subscribed again when the Kernel starts. 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.instructions.md), applied to a reactor.
+
+## Failure transitions **[convention]**
+
+A domain failure must produce a timely, observable workflow outcome rather than
+leave work looking active until a watchdog notices. Assign the transition to a
+reliable consumer: an existing state machine can be sufficient; do not add a
+redundant failure reactor when it already owns the event. Watchdogs cover missing
+signals, not ordinary handling of an already recorded failure. Specify the visible
+transition, repeated delivery, and stale failures from earlier attempts. Keep
+public reasons free of secrets. See **cratis-chronicle-reactor** for the distinction
+between domain failure and an observer's operational failure.
+
+## Slice Types That Use Reactors
+
+| Slice type | Pattern |
+|------------|---------|
+| **Automation** | Reacts to our own events, makes decisions, triggers side effects: an external call, a follow-up event (`produces`), or a follow-up command in another slice (`invokes`) |
+| **Translation** | Takes data from outside the model's own facts (an external system or another service) and records it as our own facts. A reactor is only its adapter code; a reactor that turns our own event into a follow-up event or command is an Automation |
+
+### Automation Example
+
+```csharp
+public class InvoiceIssuedNotifier(INotificationService notifications) : IReactor
+{
+    /// <summary>
+    /// Sends a notification when an invoice is issued.
+    /// </summary>
+    /// <param name="event">The event.</param>
+    /// <param name="context">The event context.</param>
+    public async Task InvoiceIssued(InvoiceIssued @event, EventContext context) =>
+        await notifications.Notify($"Invoice '{@event.Number}' was issued.");
+}
+```
+
+### Automation Example — Returning a Command
+
+```csharp
+[ExecuteCommandsAsSystem("invoicing")]
+public class RenewalBilling : IReactor
+{
+    /// <summary>
+    /// Reacts to a membership renewal by invoking the invoice issuing in the invoicing slice.
+    /// </summary>
+    /// <param name="event">The event.</param>
+    /// <param name="context">The event context.</param>
+    /// <returns>The command Arc executes as this reactor's side effect.</returns>
+    [OnceOnly]
+    public Task<IssueRenewalInvoice> MembershipRenewed(MembershipRenewed @event, EventContext context) =>
+        Task.FromResult(new IssueRenewalInvoice(@event.MemberId, @event.Amount));
+}
+```
+
+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 issuing the renewal invoice twice.
+
+## Contract checks for a reactor
+
+- **Field lineage:** every field of a returned command or event comes from the trigger event, an injected read model, or a mapping the contract states. Nothing is invented or defaulted.
+- **Contract-authorized filtering:** every condition that skips an event is stated in the contract; do not add a skip the contract does not name.
+- **Repeated delivery:** write a specification for the same event arriving again. Recovery re-delivers even with `[OnceOnly]`.
+
+## Testing Reactors
+
+Start with `Specification` plus a direct call for pure reactor decisions, passing the event and supplied values explicitly. Add `ReactorScenario<TReactor>` (from `Cratis.Chronicle.Testing.Reactors`) only where invocation, dependency wiring or side effects contribute proof — 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 InvoiceIssued("INV-1001"));
+
+[Fact] async Task should_notify_about_the_issued_invoice() => await _notifications.Received(1).Notify(Arg.Is<string>(_ => _.Contains("INV-1001")));
+```
+
+### Read-model dependencies in scenarios — Chronicle 19.46.0+
+
+`ReactorScenario<TReactor>` does **not** build read models from `Given` events,
+including `[Passive]` models. Seed the handler's read-model parameter explicitly
+before firing the trigger:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_order);
+async Task Because() => await _scenario.Given.ForEventSource(_id).Events(_orderPlaced);
+```
+
+In a separate absence specification, replace the seeding with
+`_scenario.Given.ForEventSourceId(_id).NoReadModel<Order>()` to deliberately pass
+`null` to an `Order?` parameter. Without either setup, resolution to `null` throws
+`ReadModelNotSeededForReactorScenario` (`Cratis.Chronicle.Testing.Reactors`), even
+for a nullable parameter. Its message names the type and missing key, suggests
+both setup methods, and lists other seeded keys for that type when any exist.
+Use the key from `ICanResolveReadModelKey.Resolve` for seeding or absence when
+implemented, not the triggering source id. `NoReadModel<T>()` does not remove a
+seeded instance. This guard applies to `EventStoreForTesting`, not an explicitly
+supplied store of another type; production read-model resolution is unchanged.
+
+Also in Chronicle 19.46.0+, `Events(...)` surfaces a synchronously throwing
+handler's own exception, preserving its stack, rather than the reflection
+`TargetInvocationException`. Capture it with `Catch.Exception` and assert the
+handler's exception type. `EventContext.From(...)` now defaults an omitted
+`occurred` to `DateTimeOffset.UtcNow`, not local `Now`; scenario contexts,
+`EventContext.Empty` and `EmptyWithEventSourceId(...)` use that helper. An
+explicit occurrence time is preserved, not normalized to UTC.
+
+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.instructions.md) for the full `*Scenario` family.

package/package/corpus/harnesses/copilot/instructions/rtk.instructions.md

@@ -0,0 +1,48 @@
+---
+applyTo: "**/*"
+description: "Use when running any shell command, reading files, or searching code. Route commands through rtk for human-readable output (a hook auto-rewrites Bash commands; prefix rtk yourself where it does not); use raw output when the result is parsed, compared exactly, or drives another operation."
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# 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. Where no hook is configured, prefix the command yourself — including each command in an `&&` chain: `rtk git add . && rtk git commit -m "msg"`.
+
+- **Audit coverage** with `rtk gain` (savings so far) and `rtk discover` (commands that slipped past rtk — missed opportunities to close).
+
+## When to use raw output instead
+
+rtk output is a summary for a reader. It is never evidence of exact file contents, paths, Git state, or command semantics, and a filter can drop the line you needed. Use the raw command — `rtk proxy <cmd>`, or the plain command where nothing rewrites it — whenever:
+
+- the output is parsed by a script, compared exactly, or fed to another command;
+- the output is the evidence for a claim about content, paths, or Git state;
+- the command's exit code or exact diagnostics decide what happens next (security checks, structured JSON, machine-readable diagnostics);
+- a wrapped command failed. Read the actual error and retry through `rtk proxy` before concluding the tool, path, or repository is missing.
+
+Do not add `rtk` to scripts, hooks, or CI steps that deliberately use native commands; their raw output is the point. Exit codes are never traded for token savings — see [`exit-codes-and-wrappers.md`](./exit-codes-and-wrappers.instructions.md).
+
+## 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/harnesses/copilot/instructions/specs.csharp.instructions.md

@@ -0,0 +1,147 @@
+---
+applyTo: "**/for_*/**/*.cs, **/when_*/**/*.cs"
+paths:
+  - "**/for_*/**/*.cs"
+  - "**/when_*/**/*.cs"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# How to Write C# Specs
+
+Extends the base [specs.md](./specs.instructions.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.instructions.md)) **only** when testing the very engine your repo provides — Arc → `CommandScenario`, Chronicle → the event/projection/reactor scenarios. The **cratis-application-slice-specifications** skill is application-oriented, not for general framework specs.
+> - **Event-sourced applications on Cratis** (commands, projections, reducers, reactors, constraints): use this base plus a direct call by default for pure decisions; add the in-process scenario family only where pipelines, validation, constraints, projections or wiring contribute proof — see **[specs.scenarios.csharp.md](./specs.scenarios.csharp.instructions.md)** (`profile: application`) and the **cratis-application-slice-specifications** 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/) **2.x** for execution (not v3).
+- Reference `Cratis.Specifications.XUnit` **4.1.1** for the `Specification` base, convention lifecycle and `ShouldXxx` assertions; the namespace remains `Cratis.Specifications`. Its `Cratis.Specifications` dependency supplies `Catch` and `SpecificationMethods`, not the base or assertions.
+- 4.x targets net8.0/net9.0/net10.0; net48 requires 3.x. `Cratis.Specifications.NUnit` is an alternative with `[Test]` and public test methods; xUnit remains the house default.
+- [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 fact by default | once per eligible class with shared lifecycle opt-in |
+
+Shared lifecycle is optional (4.1.0+): add `[assembly: Xunit.TestFramework("Cratis.Specifications.SpecificationTestFramework", "Cratis.Specifications.XUnit")]`. Eligible classes derive from `Specification`, have one public parameterless constructor, do not implement `IDisposable`, and contain only plain facts. Construction, Establish/Because and Destroy run once; all facts share the instance and must not mutate it. Initialization failure fails every fact. Other classes keep per-fact execution. Keep the stock lifecycle by default; details are in the **cratis-specifications-csharp** skill's shared-lifecycle reference.
+
+CRSPEC0001–CRSPEC0007 are warnings bundled in `.Specifications`, `.XUnit`, and `.NUnit` 4.0.0+. With warnings as errors, a non-`should_` fact, multiple specs per file (given contexts exempt), a fact on a given context, a `should_` without a test attribute, explicit base lifecycle calls, non-public specs with facts, or `Because` on a given context fail the build. Follow **cratis-specification-by-example**; do not suppress these diagnostics.
+
+## 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 the `Cratis.Specifications.XUnit` package (namespace `Cratis.Specifications`): `.ShouldEqual(expected)`, `.ShouldBeTrue()`, `.ShouldBeFalse()`, `.ShouldBeNull()`, `.ShouldNotBeNull()`, `.ShouldBeEmpty()`, `.ShouldNotBeEmpty()`, `.ShouldContain(item)`, `.ShouldNotContain(item)`, `.ShouldContainOnly(items)`, `.ShouldBeOfExactType<T>()`, `.ShouldBeGreaterThan(n)`, `.ShouldBeLessThan(n)`.
+
+Additional helpers include `ShouldNotEqual`, `ShouldBeSame`/`ShouldNotBeSame`, `ShouldMatch(Func<T, bool>)`, `ShouldBeInRange`, inclusive comparisons `ShouldBeGreaterThanOrEqual`/`ShouldBeLessThanOrEqual`, `ShouldContainSingleItem`, `ShouldEachConformTo`, ordered collection `ShouldEqual(IEnumerable<T>)`, collection `ShouldContain(Predicate<T>)`, `ShouldBeAssignableFrom<T>`, and string `ShouldContain(substring, StringComparison)`. `Catch.Exception` accepts `Action` or `Func<Task>`; `Catch.Exception<T>(Action)` catches only T.
+
+## 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.instructions.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.instructions.md) — folder structure, naming, BDD philosophy (the base this extends).
+- [specs.scenarios.csharp.md](./specs.scenarios.csharp.instructions.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.instructions.md) — `DbContext` specs with SQLite in-memory.
+- [frontend-testing.md](./frontend-testing.instructions.md) — TypeScript/React application BDD specs.