@cratis/pi 7.28.0 → 7.28.1

package/package/corpus/rules/reactors.md

@@ -278,4 +278,34 @@ async Task Because() => await _scenario.Given.ForEventSource(_id).Events(new Inv
 [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.md) for the full `*Scenario` family.

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

@@ -160,6 +160,47 @@ async Task Because() => await _scenario.Given.ForEventSource(_id).Events(new Aut
 [Fact] async Task should_notify() => await _service.Received(1).Notify("Jane Austen");
 ```
 
+#### Read-model setup — Chronicle 19.46.0+
+
+In a class-based `ReactorScenario<TReactor>`, `Given` events invoke the reactor;
+they **do not materialize read models**, even `[Passive]` ones. For each
+read-model handler parameter, choose one setup before `Because()`:
+
+```csharp
+// Present-state specification: supply the instance the handler must receive.
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_author);
+
+// Separate absence specification: deliberately let an Author? parameter receive null.
+void Establish() => _scenario.Given.ForEventSourceId(_id).NoReadModel<Author>();
+```
+
+These are alternatives in **separate specification classes**, not two
+`Establish()` methods in one class. Both builders return
+`ReactorSourceGivenBuilder<TReactor>` for chaining; neither setup is async.
+Use the triggering event-source id by default, or the key returned by the
+reactor's `ICanResolveReadModelKey.Resolve` when implemented. An absence
+declaration is for that exact type and key and does not delete a seeded model.
+
+If a recognized read-model parameter resolves to `null` without declared absence,
+`Events(...)` throws `ReadModelNotSeededForReactorScenario` from
+`Cratis.Chronicle.Testing.Reactors`, even if the parameter is nullable. The
+message names the full type and missing key, explains `ReadModel(...)` and
+`NoReadModel<T>()`, and lists seeded keys for that type when any exist. Fix the
+fixture or its key; do not add `NoReadModel<T>()` just to silence missing setup.
+The guard applies to `EventStoreForTesting`; it does not alter production
+resolution or an explicitly supplied event store of another type.
+
+**Handler failures:** in Chronicle 19.46.0+, a synchronous handler throw surfaces
+its own exception, not `TargetInvocationException`, with its handler stack
+preserved. Use `await Catch.Exception(() => _scenario.Given.ForEventSource(_id).Events(...))`
+and assert the handler's exception type.
+
+**Occurrence time:** in Chronicle 19.46.0+, `EventContext.From(...)` uses
+`DateTimeOffset.UtcNow` when `occurred` is omitted (previously local `Now`).
+`ReactorScenario` builds its contexts through this helper, as do
+`EventContext.Empty` and `EmptyWithEventSourceId(...)`. Explicit occurrence times
+keep their supplied offset; the positional constructor has no such default.
+
 ## Out-of-process Chronicle integration specs (advanced)
 
 Reserve these for the host/transport boundary the scenario helpers can't reach. They test a complete slice — HTTP request → command → append → constraint → projection — against a real Chronicle store, and live under `when_<behavior>/` directly inside the slice folder (no `for_` folder; the "unit" is the whole slice).

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

@@ -30,6 +30,10 @@ This skill decides **when to add a scenario** and **what to cover**. The C# mech
 
 > 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.
 
+Reactor read-model setup and the `EventContext.From` UTC default below are
+verified separately at **Chronicle 19.46.0**, the minimum version for that
+guidance; see `cratis-chronicle-reactor/references/specifications.md` for sources.
+
 `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.
@@ -112,6 +116,15 @@ keep a scenario for that wiring and for appended-event behavior.
 | Automation or Translation — a reactor | `ReactorScenario<TReactor>` | `cratis-specifications-csharp` |
 | A host, transport, or real-infrastructure boundary | Out-of-process integration | `cratis-specifications-csharp` |
 
+For a class-based reactor scenario on **Chronicle 19.46.0+**, explicitly seed
+handler read-model parameters with `Given.ForEventSourceId(id).ReadModel(instance)`
+or declare intentional absence with `.NoReadModel<T>()`. An unseeded model throws
+`ReadModelNotSeededForReactorScenario` even if nullable; `Given` events do not
+build read models, including passive ones. Use the reactor's resolved key, not
+necessarily the trigger's source id. This is **not** the command-scenario event
+seeding described in Step 5. Read `cratis-chronicle-reactor` for the setup examples,
+exception diagnostics, synchronous handler throws and UTC context defaults.
+
 ## Step 3 — Cover every outcome of a State Change slice
 
 One specification class for **each** of:

package/package/corpus/skills/cratis-chronicle-reactor/SKILL.md

@@ -45,6 +45,11 @@ This skill is verified against these exact sources:
 | `Cratis.Chronicle` | `18.3.0` | `Cratis.Chronicle.Reactors`, `Cratis.Chronicle.Reactors.SideEffects`, `Cratis.Chronicle.EventSequences`, `Cratis.Chronicle.Events` |
 | `Cratis.Chronicle.CodeAnalysis` | `18.3.0` | `CHR0004`, `CHR0005`, `CHR0008`, `CHR0013`, `CHR0022`, `CHR0031`, `CHR0032` |
 
+Scenario read-model seeding/absence, synchronous handler exception propagation,
+and the `EventContext.From` UTC default are verified separately at **Chronicle
+19.46.0**; they require **19.46.0+**. See the source paths in
+[references/specifications.md](references/specifications.md).
+
 Reverify product sources before claiming support for another version.
 
 > **There is no `ReactorSideEffect` type.** It does not exist in Chronicle, in
@@ -363,7 +368,17 @@ when they serve that concern.
 
 Start with `Specification` plus a direct call for pure reactor decisions; add `ReactorScenario<TReactor>` only where invocation, dependency wiring or side effects contribute proof. Specify the contract, not only the happy path: field lineage, contract-authorized filtering, repeated delivery, and unrelated events.
 
-Read [references/specifications.md](references/specifications.md) when writing or reviewing reactor specifications.
+In Chronicle **19.46.0+**, a handler's unseeded read-model parameter throws
+`ReadModelNotSeededForReactorScenario`, even if nullable. Seed it through
+`Given.ForEventSourceId(id).ReadModel(instance)`, or declare intentional absence
+with `.NoReadModel<T>()`. Use the resolved read-model key; `Given` events do not
+build read models, including passive ones. A synchronous handler throw surfaces
+the handler's exception rather than a reflection wrapper, and the scenario's
+`EventContext.Occurred` defaults to UTC.
+
+Read [references/specifications.md](references/specifications.md) before writing
+or reviewing reactor specifications; it shows both setup alternatives and the
+scope of these scenario-only guards.
 
 ## Verify
 

package/package/corpus/skills/cratis-chronicle-reactor/references/specifications.md

@@ -1,3 +1,12 @@
+# Reactor specifications
+
+## Contents
+
+- Specifications
+- Read-model setup — Chronicle 19.46.0+
+- Exceptions and occurrence time — Chronicle 19.46.0+
+- Contract coverage
+
 ## Specifications
 
 Start with `Specification` plus a direct call for pure reactor decisions,
@@ -9,6 +18,82 @@ non-event side effects; for handlers that return events, assert the resulting
 appends through the scenario's event store. Cover the replay path separately
 when the reactor has `[OnceOnly]` or `[Replay]` handlers.
 
+## Read-model setup — Chronicle 19.46.0+
+
+Class-based `ReactorScenario<TReactor>` does not build read models from `Given`
+events, **including passive models**. Seed a pre-built instance in `Establish()`:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_order);
+async Task Because() => await _scenario.Given.ForEventSource(_id).Events(_orderPlaced);
+```
+
+For a **separate absence specification**, use this setup instead, so an `Order?`
+handler parameter deliberately receives `null`:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).NoReadModel<Order>();
+```
+
+The builders live in `Cratis.Chronicle.Testing.Reactors`. Exact signatures on
+`ReactorSourceGivenBuilder<TReactor>` (`where TReactor : class, IReactor`):
+
+```csharp
+public ReactorSourceGivenBuilder<TReactor> ReadModel<TReadModel>(TReadModel readModel)
+    where TReadModel : class;
+public ReactorSourceGivenBuilder<TReactor> NoReadModel<TReadModel>()
+    where TReadModel : class;
+public Task Events(params object[] events);
+```
+
+Both `Given.ForEventSource(EventSourceId)` and
+`Given.ForEventSourceId(EventSourceId)` return this builder. Seed or declare
+absence using the triggering source id by default, or the key returned by
+`ICanResolveReadModelKey.Resolve` when implemented. Declarations are shared
+across the scenario's builders, match the **exact type and key**, and do not
+remove a seeded instance. Do not declare absence to hide forgotten setup.
+
+If a recognized read-model parameter resolves to `null` without declared
+absence, `Events(...)` throws `ReadModelNotSeededForReactorScenario` from
+`Cratis.Chronicle.Testing.Reactors`, **even for nullable parameters**. Its message
+names the full read-model type and key, tells you to seed via `ReadModel(...)`
+or declare `NoReadModel<T>()`, and lists other seeded keys for that type when
+any exist. Check the key first if the fixture already seeds that type. This
+guard applies only when the scenario uses `EventStoreForTesting` (including an
+explicit instance); an explicitly supplied store of another type and production
+read-model resolution are unchanged.
+
+## Exceptions and occurrence time — Chronicle 19.46.0+
+
+`Events(...)` rethrows a synchronously throwing handler's **own exception**,
+unwrapping the `TargetInvocationException` previously surfaced by reflection,
+and preserves the handler stack. Capture with
+`await Catch.Exception(() => _scenario.Given.ForEventSource(_id).Events(_orderPlaced))`
+and assert the handler's exception type, not a reflection wrapper.
+
+`EventContext.From(...)` defaults omitted `occurred` to `DateTimeOffset.UtcNow`
+(previously `DateTimeOffset.Now`). `ReactorScenario` uses this helper, as do
+`EventContext.Empty` and `EmptyWithEventSourceId(...)`. Explicit timestamps keep
+their supplied offset; the positional constructor does not default `Occurred`.
+For deterministic time-dependent plain-call specs, supply a fixed occurrence
+time rather than asserting an exact current instant.
+
+Verified against **Chronicle tag `v19.46.0`**:
+
+- `Source/Clients/Testing/Reactors/ReactorSourceGivenBuilder.cs` and
+  `ReactorScenarioGivenBuilder.cs`: seeding, absence and builder signatures.
+- `Source/Clients/Testing/Reactors/ScenarioReactorMethodArgumentsResolver.cs` and
+  `ReadModelNotSeededForReactorScenario.cs`: guard scope, resolved key and message.
+- `Source/Clients/Testing/Reactors/ReactorScenario.cs`: synchronous exception
+  unwrapping and context creation.
+- `Source/Clients/DotNET/Events/EventContext.cs`: UTC default and explicit time.
+- `Source/Clients/Testing.Specs/Reactors/for_ReactorScenario/when_resolving_read_model_dependencies/`:
+  seeded, absent, nullable, passive, custom-key and explicit-store examples.
+- `Source/Clients/Testing.Specs/Reactors/for_ReactorScenario/when_a_reactor_handler_throws_synchronously.cs`
+  and `when_a_reactor_reads_the_occurrence_time.cs`: handler exception and UTC specs.
+
+## Contract coverage
+
 Specify the contract, not only the happy path:
 
 - **Field lineage.** For each returned command or event, a specification asserts

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -22,6 +22,11 @@ This skill is verified against these exact public releases:
 | `Cratis.Arc.Testing` | `22.16.0` | `CommandScenario<TCommand>` and `CommandResult` assertions |
 | `Cratis.Chronicle.Testing` | `18.3.0` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
 
+Reactor read-model seeding/absence, synchronous handler exceptions and the
+`EventContext.From` UTC default are verified separately at **Chronicle 19.46.0**
+and require **19.46.0+**; see the ReactorScenario section in
+[application-scenarios.md](references/application-scenarios.md).
+
 Generated-value scenario pinning is verified separately against
 `Cratis.Arc.Testing` **22.68.0** (introduced in **22.67.0**).
 
@@ -83,6 +88,14 @@ never produces a concurrency violation. `ShouldHaveConcurrencyViolations()`
 cannot pass for such an append and its negation passes vacuously — specify concurrency against the
 real kernel with an out-of-process integration specification instead.
 
+For a class-based `ReactorScenario<TReactor>` on **Chronicle 19.46.0+**, seed each
+handler read-model parameter with `Given.ForEventSourceId(id).ReadModel(instance)`
+or declare intentional absence with `.NoReadModel<T>()`; `Given` events do not
+build it, even if passive. Missing setup throws
+`ReadModelNotSeededForReactorScenario` even for a nullable parameter. Use the
+resolved read-model key. See the ReactorScenario reference for diagnostics,
+exception capture and UTC occurrence-time defaults.
+
 Specification projects are named `<Source>.Specs` and run on xUnit.
 
 ### Pin server-generated Handle values

package/package/corpus/skills/cratis-specifications-csharp/references/application-scenarios.md

@@ -262,6 +262,47 @@ async Task Because() =>
 Construct with an `IServiceProvider` of substituted collaborators and assert on
 those substitutes after `Given` fires the events.
 
+### Read-model parameters — Chronicle 19.46.0+
+
+`Given` events invoke the reactor; they **do not build read models**, including
+passive ones. In the present-state specification, seed a pre-built instance:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).ReadModel(_author);
+```
+
+In a **separate absence specification**, deliberately let an `Author?` handler
+parameter receive `null`:
+
+```csharp
+void Establish() => _scenario.Given.ForEventSourceId(_id).NoReadModel<Author>();
+```
+
+Both return `ReactorSourceGivenBuilder<TReactor>` for chaining, not a `Task`.
+Use the triggering source id by default or `ICanResolveReadModelKey.Resolve`'s
+key when implemented. Absence matches the exact type and key and does not remove
+a seeded instance. Missing setup throws `ReadModelNotSeededForReactorScenario`
+(`Cratis.Chronicle.Testing.Reactors`), **even for nullable parameters**. Its
+message names the type/key, explains both setups, and lists other seeded keys
+for that type when any exist. Fix the fixture/key rather than hiding missing
+setup with `NoReadModel<T>()`. This guard applies to `EventStoreForTesting`, not
+production resolution or an explicitly supplied store of another type.
+
+Also in **Chronicle 19.46.0+**, a synchronous handler throw surfaces its own
+exception, not reflection's `TargetInvocationException`, preserving the handler
+stack. Capture with `await Catch.Exception(() => _scenario.Given.ForEventSource(_id).Events(...))`
+and assert the handler's exception type.
+
+`EventContext.From(...)` defaults omitted `occurred` to `DateTimeOffset.UtcNow`,
+previously local `Now`. Scenario contexts, `EventContext.Empty` and
+`EmptyWithEventSourceId(...)` use this helper; explicit times retain their offset,
+and the positional constructor has no such default.
+
+Sources at **Chronicle tag `v19.46.0`**:
+`Source/Clients/Testing/Reactors/{ReactorScenario,ReactorSourceGivenBuilder,ScenarioReactorMethodArgumentsResolver,ReadModelNotSeededForReactorScenario}.cs`
+and `Source/Clients/DotNET/Events/EventContext.cs`. For exact signatures and
+source-backed examples, read `cratis-chronicle-reactor/references/specifications.md`.
+
 ## Application conventions
 
 - **Use a per-specification fixture value for anything under a shared uniqueness

package/package.json

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