@cratis/pi 7.34.1 → 7.36.0

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

@@ -19,10 +19,6 @@ effects. If the answer is "populate a queryable model", it is not a reactor.
 | record data from an outside system or service as our own facts | an adapter at the boundary, often a reactor (**translation**) |
 | both a model and an effect | one projection *and* one reactor |
 
-A reactor is an **automation** when it answers one of our own events, whatever it
-causes. It is the adapter side of a **translation** only when its input is
-outside data that becomes our own facts.
-
 > **Model first.** If an accepted model under the model root covers this scope, or
 > the repository is opted in (the root, the folder holding the project's `.play` files, 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
@@ -42,20 +38,16 @@ This skill is verified against these exact sources:
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `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` |
+| `Cratis.Chronicle` | `19.50.1` | `Cratis.Chronicle.Reactors`, `Cratis.Chronicle.Reactors.SideEffects`, `Cratis.Chronicle.EventSequences`, `Cratis.Chronicle.Events` |
+| `Cratis.Chronicle.CodeAnalysis` | `19.50.1` | handler, side-effect and filter diagnostics, including CHR0054–CHR0056 |
 
-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).
+Scenario guards began in **19.46.0**, reverified at **19.50.0**;
+see [specifications](references/specifications.md).
 
 Reverify product sources before claiming support for another version.
 
-> **There is no `ReactorSideEffect` type.** It does not exist in Chronicle, in
-> any version. The real return types are listed below; the per-event metadata
-> control it was imagined to provide is what `EventForEventSourceId` actually
-> gives you. Never write it into code or an example.
+> **There is no `ReactorSideEffect` type.** Use the supported return types below;
+> `EventForEventSourceId` supplies per-event metadata.
 
 ## Write the reactor
 
@@ -85,8 +77,7 @@ and plays no part. When two methods claim the same event type, the winner is
 chosen by public before non-public, then more parameters before fewer, then
 ordinal name order — so do not rely on it; write one handler per event type.
 
-A handler takes **at least one** parameter. There is no upper limit. Everything
-after the first is resolved by type, position-independently:
+A handler takes at least one parameter. Further parameters resolve by type:
 
 | Parameter type | Resolved as |
 | --- | --- |
@@ -95,13 +86,10 @@ after the first is resolved by type, position-independently:
 | a type that has a projection or a reducer | that **read model**, materialized for this event |
 | anything else | from the service provider |
 
-An unresolvable parameter throws at invocation, and analyzer **CHR0004**
-(warning) flags it at build time: after the event, a reactor method may take the
-event context, a read model, or a service — not a primitive, a value type, or a
-string.
+An unresolvable parameter throws. CHR0004 warns against primitive, value-type
+or string dependencies after the event: use context, a read model or a service.
 
-The first parameter's type must carry `[EventType]`, or analyzer **CHR0005**
-(error) rejects it.
+The first parameter must carry `[EventType]` (CHR0005 error).
 
 ### Injecting a read model
 
@@ -121,17 +109,13 @@ public class <ReactorName> : IReactor, ICanResolveReadModelKey
 }
 ```
 
-The resolved key applies to every read-model parameter across all of the
-reactor's handlers.
+The resolved key applies to every read-model parameter on the reactor.
 
-A **materialized** read model is read from its sink, so it is eventually
-consistent — as current as its own observer. Mark the read model `[Passive]` when
-the reactor needs it strongly consistent: a passive model has no sink and is
-computed on demand at the point the reactor runs.
+Materialized models are as current as their observer. `[Passive]` computes
+on demand without a sink when the reactor needs a current read.
 
-Prefer the event's own data. Analyzer **CHR0032** (warning) rejects injecting a
-storage primitive such as `IMongoCollection<T>` directly — read keyed state
-through a read-model parameter or `IReadModels.GetInstanceById` instead.
+Prefer the event's own data. CHR0032 warns against injected storage primitives such as `IMongoCollection<T>`;
+read keyed state through read-model parameters or `IReadModels.GetInstanceById`.
 
 ## Return types
 
@@ -147,15 +131,18 @@ through a read-model parameter or `IReadModels.GetInstanceById` instead.
 A collection may **mix** bare events and `EventForEventSourceId` items; each is
 appended with its own metadata, all in one transaction.
 
-A custom side-effect type handled by your own `IReactorSideEffectHandler` is
-only recognised when returned as `Task<T>`.
+Arrays and lists of registered events or `EventForEventSourceId` are also valid
+synchronous returns. Custom `IReactorSideEffectHandler` implementations can
+claim synchronous types through `CanHandleReturnType(Type)`; they are not
+restricted to `Task<T>`. An unclaimed return value **fails the partition** with
+`UnhandledReactorReturnValue`, naming its type. CHR0054 flags an unsupported
+return type at build time. Source at v19.50.0: `Reactors/EventHandlerMethods.cs`,
+`Reactors/SideEffects/IReactorSideEffectHandler.cs`, `Reactors/UnhandledReactorReturnValue.cs`.
 
 ### Returning events instead of injecting `IEventLog`
 
-Return the events. Do not inject `Cratis.Chronicle.EventSequences.IEventLog` into
-a reactor. **This is a convention, not a framework contract** — no analyzer
-enforces it — but returning the events keeps the reactor free of the event store
-and keeps the append inside Chronicle's own transaction.
+Return events rather than inject `IEventLog`: **a convention, not an analyzer
+contract**. Returned appends stay inside Chronicle's transaction.
 
 ```csharp
 // One event, on the triggering event's own event source.
@@ -169,20 +156,12 @@ public Task<IEnumerable<object>> <MethodName>(<EventName> @event, EventContext c
 
 ### Targeting another event source
 
-`Cratis.Chronicle.EventSequences.EventForEventSourceId` is the cross-stream
-wrapper:
-
-```csharp
-public record EventForEventSourceId(EventSourceId EventSourceId, object Event, Causation? Causation = default)
-{
-    public Subject? Subject { get; init; }
-    public EventStreamType EventStreamType { get; init; }
-    public EventStreamId EventStreamId { get; init; }
-    public EventSourceType EventSourceType { get; init; }
-    public DateTimeOffset? Occurred { get; init; }
-    public IEnumerable<string> Tags { get; init; }
-}
-```
+`Cratis.Chronicle.EventSequences.EventForEventSourceId(eventSourceId, @event,
+causation)` is the cross-stream wrapper. Its init members include `Subject`,
+`Occurred`, `Tags`, `EventSource` (`Type?`) and `EventStream` (`string?`). Routing
+defaults are `EventStreamType.All`, `EventStreamId.Default` and
+`EventSourceType.Default`. Source: `EventSequences/EventForEventSourceId.cs`
+at v19.50.0.
 
 ```csharp
 public Task<IEnumerable<EventForEventSourceId>> <MethodName>(<EventName> @event, EventContext context) =>
@@ -193,8 +172,9 @@ public Task<IEnumerable<EventForEventSourceId>> <MethodName>(<EventName> @event,
     ]);
 ```
 
-It does **not** carry an event sequence id; side effects are appended to the
-event log.
+It also carries `IEnumerable<NamedTag> NamedTags` (snapshotted on assignment).
+It does **not** carry an
+event sequence id; side effects are appended to the event log.
 
 ### Where the metadata for a bare event comes from
 
@@ -223,8 +203,8 @@ a method** and means **replay exclusion**:
 **`[OnceOnly]` is not per-event-source deduplication.** There is no ledger of
 which events a handler has already seen. Recovering a failed partition
 re-delivers the event as an ordinary observation, and a `[OnceOnly]` handler runs
-again. Design the side effect to be idempotent regardless — an external
-idempotency key, an upsert, a conditional write.
+again. Catch-up and crash redelivery are not replay either; every ordinary
+matching event can run, even on the same source. Keep effects idempotent.
 
 Analyzer **CHR0022** (warning) requires `[OnceOnly]` on a handler that returns
 event side effects, because a replay would otherwise append duplicates.
@@ -255,6 +235,16 @@ public sealed class ReactorAttribute(string id = "", string? eventSequence = def
 **There is no `isActive` argument** — that belongs to `[Reducer]`. Without an
 explicit `id`, the reactor's identity is its full type name.
 
+Give side-effecting reactors a **stable explicit id**. Since 19.47.0 discovery
+warns on likely renames/moves: a new id catches up from the start and repeats
+side effects; `[OnceOnly]` does not prevent that. `ArtifactIdentityDrift = Fail`
+rejects Warning-level reactor/event-type findings with
+`ArtifactIdentityDriftDetected`; projection/reducer drift is Information.
+Inspect `RegistrationOutcome.IdentityDrift`. After stopping all subscriptions,
+`IEventStore.Observers.Remove` can remove an orphaned observer; it refuses while
+running or subscribed anywhere. This is an authorized operator action, not a
+rename cleanup to perform automatically.
+
 The source sequence resolves in this order: an `[EventStore]` attribute (which
 selects the inbox for that store), then `[EventSequence]`/`[EventLog]`, then
 `Reactor(eventSequence: ...)`, then the event store inferred from the handled
@@ -282,10 +272,16 @@ event there originates from one service.
 | `[FilterEventsByTag("<tag>")]` | **filters** by appended tag; repeatable, and any one match admits the event |
 | `[EventSourceType("<value>")]` | **filters** by the appended event source type |
 | `[EventStreamType("<value>")]` | **filters** by the appended event stream type |
+| `[FromEventSource<TSource>("<stream>")]` | **filters** by a declared event source and stream (`Cratis.Chronicle.EventSources`) |
 | `[EventStreamId("<value>")]` | **does not filter**; it is append metadata for side effects |
 | `[Tag]`, `[Tags]` | **label** the reactor; they never filter |
 
 Filter categories combine with AND; tags within the tag category combine with OR.
+Typed source filters work on reactors and reducers, not projections (CHR0041).
+CHR0055 flags unknown streams; CHR0056 flags routing that contradicts the filter.
+Filters survive catch-up, replay and failed-partition recovery.
+`WaitForCompletion` excludes nonmatching observers when the .NET client supplies
+its first appended sequence number.
 These correspond to metadata supplied at append time:
 
 ```csharp
@@ -302,38 +298,15 @@ selection, a reactor or a reducer is where it happens.
 
 ## Invoking a command from a reactor
 
-An automation that turns one area's events into another area's intent runs a
-command rather than appending directly (Screenplay `invokes`). With the Arc Chronicle integration the handler
-**returns** the command — the same shape as returning an event — and Arc executes
-it through validation and authorization; a denied, invalid or throwing result is a
-side-effect failure that fails the partition rather than being dropped:
-
-```csharp
-using Cratis.Arc.Chronicle.Reactors;
-
-[ExecuteCommandsAsSystem("<role the command requires>")]   // only when the command is [Roles]/[Authorize]-gated
-public class <ReactorName> : IReactor
-{
-    [OnceOnly]
-    public Task<<CommandName>> <MethodName>(<EventName> @event, EventContext context) =>
-        Task.FromResult(new <CommandName>(@event.<Property>));
-}
-```
-
-A reactor runs with **no principal**; `[ExecuteCommandsAsSystem]` (class-level,
-`Cratis.Arc.Chronicle.Reactors`) supplies one for the **returned** commands only.
-A collection return is executed as commands when every element is a command. A stable collection mixing registered events and commands (Arc 22.72.0+; Arc 22.68.0's handler needs every element to be a command) appends the events
-first as one batch, then runs the commands in order, with no transaction across them; a retry can
-repeat both. `[ExecuteCommandsAsSystem]` covers only the commands.
-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 form — inject `ICommandPipeline` (`Cratis.Arc.Commands`) and call
-`Execute(command)` — is still supported and is the subject of the
-**cratis-arc-command-execution** skill. It needs `[OnceOnly]` as well (`ARCCHR0006`
-warns), the `CommandResult` must be inspected, and `[ExecuteCommandsAsSystem]`
-does not cover it.
+An automation that turns another area's facts into intent runs a command
+(Screenplay `invokes`). For the Arc integration's return shapes, execution
+identity and imperative pipeline alternative, use **cratis-arc-command-execution**
+and **cratis-arc-command** rather than reimplementing command dispatch here.
+A reactor has no caller principal: choose the authorized identity explicitly.
+Keep `[OnceOnly]` and idempotency; a failed command must remain a visible
+partition failure. Inline operations can run again on reactor retry and do not
+replace durable delivery; see **cratis-arc-command-operation**.
+Mixed event-and-command returns and their ordering are owned by the Arc skills.
 
 ## Failure behavior
 
@@ -344,7 +317,10 @@ can **quarantine** the observer, which stops retries and suppresses automatic
 recovery. **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.
+redeploy; Kernel-owned reactors subscribe again at startup; automatic event-store
+subscription reconciliation does not end quarantine. Read
+[recovery](../cratis-chronicle-hosting/references/operations.md) for the
+v19.50.1 fail-closed lookup and observer-kind-specific quarantine rules.
 
 Do not throw to reject a malformed inbound event. A reactor is not a data-quality
 gate; invalid payloads belong at the command or append site. When a malformed
@@ -353,34 +329,38 @@ surface it through the operational failure path, and skip the partial side
 effect. Throwing just to reject it pauses the partition and can quarantine the
 whole observer.
 
+`RetryFailedPartitionFor<TReactor>(partition)` returns a bounded
+`ReactorPartitionRetryOutcome`. `ClearFailedPartitionQuarantineFor<TReactor>(partition,
+retryImmediately)` clears **one partition**, preserves attempt history and starts
+a fresh retry budget (`maxRetryAttempts`). Observer clear is not partition clear.
+Quarantine survives deactivation; watchdog ticks and replay/catch-up completion
+do not end it. Only an operator clear or fresh subscription does. Kernel alert
+incidents surface repeated failures; see **cratis-chronicle-hosting**.
+
+A returned append into a closed scope fails with `StreamClosed`, so the reactor
+must not blindly retry it forever. Model an authorized alternate fact/route or
+operator recovery; see **cratis-chronicle-event-constraints**.
+
 ### Domain failures must leave a visible state
 
-A recorded failure fact is not complete handling while the user-facing workflow still looks running. Give each terminal failure a reliable owner that moves the workflow to an explicit failed or retryable state; do not add a failure reactor when a state machine already owns the transition.
+A terminal failure needs an owner that moves the workflow out of "running".
+Do not add a failure reactor when a state machine already owns that transition.
 
 Read [references/domain-failures.md](references/domain-failures.md) when handling a domain failure event or deciding whether a failure needs its own reactor or watchdog.
 
 ## Keep the reactor stateless
 
-Inject collaborators through the primary constructor; hold no mutable state on
-the class. Analyzer **CHR0031** (warning) flags mutable reactor state. Keep each
-reactor focused on one automation concern; several handlers in one class are fine
-when they serve that concern.
+Inject through the primary constructor; hold no mutable state (CHR0031 warning).
+Keep one automation concern per reactor; several related handlers are fine.
 
 ## Specifications
 
 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.
 
-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.
+Read [specifications](references/specifications.md) before writing scenario
+specs: explicit read-model seeding/absence, stream-filtered seeds, produced-event
+destinations, per-run discovery and disposal. `Given` never builds read models,
+including passive ones; nullable parameters still need explicit absence.
 
 ## Verify
 
@@ -405,7 +385,7 @@ scope of these scenario-only guards.
 - No filter attribute is placed where it is inert.
 - The reactor holds no mutable state and injects no storage primitive.
 - The build is clean with no `CHR0004`, `CHR0005`, `CHR0008`, `CHR0013`,
-  `CHR0022`, `CHR0031`, or `CHR0032` outstanding, and the reactor
+  `CHR0022`, `CHR0031`, `CHR0032`, `CHR0054`, `CHR0055`, or `CHR0056` outstanding, and the reactor
   specifications pass.
 
 ## Lineage

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

@@ -3,6 +3,7 @@
 ## Contents
 
 - Specifications
+- Routing and produced events — Chronicle 19.50.0 verification
 - Read-model setup — Chronicle 19.46.0+
 - Exceptions and occurrence time — Chronicle 19.46.0+
 - Contract coverage
@@ -18,6 +19,24 @@ 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.
 
+## Routing and produced events — Chronicle 19.50.0 verification
+
+Scenarios implement `IDisposable`; dispose in `Destroy()`.
+`Given.ForEventSource(id).OnStream(eventSourceType, eventStreamType, eventStreamId).Events(...)`
+seeds routing for class-based and fluent reactors. Source/stream/typed definition
+filters are honored: unqualified seeds do not reach a handler filtered to a
+specific stream. Specify both a matching event and an excluded event.
+
+`ProducedEvents` records each `ProducedEvent` **with its destination**.
+`ShouldHaveProduced<TEvent>(eventSourceId)` checks routing; the
+`ShouldHaveProduced<TEvent>((produced, @event) => ...)` overload checks metadata
+and payload together. Do not assert only the payload when a cross-stream target
+is part of the contract. Per-run `Defaults(clientArtifactsProvider, serviceProvider,
+options)` supports `InMemoryClientArtifactsProvider` and `ExplicitArtifacts`;
+non-generic `ReactorScenario(reactorId, defaults)` exercises a runtime/fluent reactor.
+Sources: `Source/Clients/Testing/Reactors/` and `Source/Clients/Testing/Defaults.cs`
+at **v19.50.0**.
+
 ## Read-model setup — Chronicle 19.46.0+
 
 Class-based `ReactorScenario<TReactor>` does not build read models from `Given`
@@ -78,7 +97,7 @@ 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`**:
+Reverified against **Chronicle tag `v19.50.0`** (the guards began in 19.46.0):
 
 - `Source/Clients/Testing/Reactors/ReactorSourceGivenBuilder.cs` and
   `ReactorScenarioGivenBuilder.cs`: seeding, absence and builder signatures.

package/package/corpus/skills/cratis-chronicle-read-model/SKILL.md

@@ -24,8 +24,8 @@ This skill is verified against these exact sources:
 | Package | Version | Purpose |
 | --- | --- | --- |
 | `Cratis.Chronicle` | `18.3.0` | `Cratis.Chronicle.Events`, `Cratis.Chronicle.Keys`, `Cratis.Chronicle.ReadModels` |
-| `Cratis.Arc.Core` | `22.16.0` | `Cratis.Arc.Queries.ModelBound.ReadModelAttribute` and `PathAttribute` |
-| `Cratis.Arc.MongoDB` | `22.16.0` | the `Observe` family of `IMongoCollection<T>` extensions |
+| `Cratis.Arc.Core` | `22.75.0` | `Cratis.Arc.Queries.ModelBound.ReadModelAttribute` and `PathAttribute` |
+| `Cratis.Arc.MongoDB` | `22.75.0` | the `Observe` family of `IMongoCollection<T>` extensions |
 
 Reverify product sources before claiming support for another version. Confirm
 the exact Arc package version in the consuming project before citing one.

package/package/corpus/skills/cratis-chronicle-read-model/references/queries.md

@@ -11,9 +11,8 @@
 - Custom routes
 - Reading without a query surface
 
-Verified against `Cratis.Arc.Core` and `Cratis.Arc.MongoDB` as checked out
-alongside `Cratis.Chronicle` `18.3.0`. Confirm the exact Arc package version in
-the consuming project before citing one.
+Verified against `Cratis.Arc.Core` and `Cratis.Arc.MongoDB` **v22.75.0**.
+Chronicle projection behavior is owned by the Chronicle guidance.
 
 ## Where the pieces live
 
@@ -23,7 +22,8 @@ the consuming project before citing one.
 | `PathAttribute` (`[Path]`) | `Cratis.Arc.Queries.ModelBound` | `Cratis.Arc.Core` |
 | the `Observe` extensions | `MongoDB.Driver` | `Cratis.Arc.MongoDB` |
 
-`[ReadModel]` is a bare marker with **no constructor parameters**. `[Path]` takes
+`[ReadModel]` has no constructor parameters; its `RequireQueryAttribute = true`
+property opts into explicit endpoint discovery. `[Path]` takes
 one `string path` and targets a class or a method.
 
 The `Observe` extensions are deliberately declared in the `MongoDB.Driver`
@@ -32,8 +32,17 @@ Chronicle extensions — Chronicle declares no `Observe` on `IMongoCollection<T>
 
 ## Discovery rules
 
-Arc scans the read-model type for **static** methods, public and non-public
-alike. Instance methods are never discovered.
+Arc discovers **public static** methods; private and compiler-generated methods
+are never queries. Use `[ReadModel(RequireQueryAttribute = true)]` and `[Query]`
+on intended endpoints when the type also has folds (`Create`/`Reduce`) or public
+helpers. `[Query]` alone does not hide siblings. ARC0026 checks invalid/ambiguous
+query declarations; ARCCHR0019 warns about fold-like statics exposed by convention.
+A `CancellationToken` parameter is supplied by Arc, not a query argument/proxy
+input. Concept parameters are always caller-supplied, never DI. Invalid bool,
+overflow, concept or collection-element GET/QUERY arguments return HTTP 400.
+Minimal-API concepts serialize as primitives since 22.26.0.
+Sources at Arc v22.75.0: `Arc.Core/Queries/ModelBound/ReadModelAttribute.cs`,
+`QueryAttribute.cs`, and `Documentation/backend/csharp/chronicle/code-analysis/ARCCHR0019.md`.
 
 The declared return type is validated after unwrapping at most one `Task<>`:
 
@@ -94,27 +103,32 @@ Return `ISubject<...>` directly. Do **not** return `Task<ISubject<...>>`.
 ISubject<IEnumerable<TDocument>> Observe<TDocument>(
     this IMongoCollection<TDocument> collection,
     Expression<Func<TDocument, bool>>? filter,
-    FindOptions? options = null);
+    FindOptions? options = null,
+    bool ignoreQueryContext = false);
 
 ISubject<IEnumerable<TDocument>> Observe<TDocument>(
     this IMongoCollection<TDocument> collection,
     FilterDefinition<TDocument>? filter = null,
-    FindOptions? options = null);
+    FindOptions? options = null,
+    bool ignoreQueryContext = false);
 
 // single-valued
 ISubject<TDocument> ObserveSingle<TDocument>(
     this IMongoCollection<TDocument> collection,
     Expression<Func<TDocument, bool>>? filter,
-    FindOptions? options = null);
+    FindOptions? options = null,
+    bool ignoreQueryContext = false);
 
 ISubject<TDocument> ObserveSingle<TDocument>(
     this IMongoCollection<TDocument> collection,
     FilterDefinition<TDocument>? filter = null,
-    FindOptions? options = null);
+    FindOptions? options = null,
+    bool ignoreQueryContext = false);
 
 ISubject<TDocument> ObserveById<TDocument, TId>(
     this IMongoCollection<TDocument> collection,
-    TId id);
+    TId id,
+    bool ignoreQueryContext = false);
 ```
 
 Two details that catch people out:
@@ -129,17 +143,22 @@ Two details that catch people out:
 Also available in the same place: `FindById<T, TId>` and
 `FindByIdAsync<T, TId>`.
 
+Single-instance `ObserveSingle`/`ObserveById` (MongoDB and EF) emit `default`
+when absent, deleted or outside the filter, without ending the subscription.
+Guard React `result.hasData` and `result.isReady` before dereferencing data.
+
 ## Cost and composition
 
-The behavior below was checked against **Arc v22.49.0**
-([collection observation](https://github.com/Cratis/Arc/blob/v22.49.0/Documentation/backend/csharp/mongodb/observing-collections.md),
-[implementation](https://github.com/Cratis/Arc/blob/v22.49.0/Source/DotNET/MongoDB/MongoCollectionExtensions.cs)).
+The behavior below was checked against **Arc v22.75.0**
+([collection observation](https://github.com/Cratis/Arc/blob/v22.75.0/Documentation/backend/csharp/mongodb/observing-collections.md),
+[implementation](https://github.com/Cratis/Arc/blob/v22.75.0/Source/DotNET/MongoDB/MongoCollectionExtensions.cs)).
 Do not generalize it to every provider or custom observable.
 
 - Per-collection `Observe` reads an initial filtered set, retains it in memory,
   and applies change-stream updates. It does **not** re-query the entire
   collection for every event. Updates/replacements perform a keyed membership
-  lookup; paged removals can query to refill the page.
+  lookup for unpaged observations. Paged observations re-read the page and total
+  on every change; sort ties and unsorted pages use `_id`.
 - Collection emissions still construct a snapshot of the retained set. In-memory
   joins, sorting, mapping, and serialization downstream can be expensive even
   without a full database re-query. Measure retained rows, payload size, change
@@ -158,7 +177,7 @@ Do not generalize it to every provider or custom observable.
 - Prefer a purpose-built projected summary for frequently recomputed joins.
   Query-time composition is supported, not forbidden. Bound each input and define
   count, paging, missing-related-data, and subscription-disposal behavior.
-  In v22.49.0 auxiliary observations can use `ignoreQueryContext: true` so client
+  At v22.75.0 MongoDB and EF auxiliary observations can use `ignoreQueryContext: true` so client
   paging/counts belong to the primary source. That option reads **all matching
   auxiliary rows**; it is not a performance limit. Confirm version support before
   using it, and keep an explicit narrow filter.

package/package/corpus/skills/cratis-chronicle-read-model-specifications/SKILL.md

@@ -22,10 +22,10 @@ is no separate `When`: seeding the events is what makes the projection run.
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Chronicle.Testing` | `18.3.0` | `ReadModelScenario<TReadModel>` and its `Given` builder |
+| `Cratis.Chronicle.Testing` | `19.50.1` | `ReadModelScenario<TReadModel>` and its `Given` builder |
 | `Cratis.Specifications.XUnit` | `4.x` | The `Specification` base and the `ShouldXxx` assertions |
 
-> Re-verified at the versions above by **symbol and signature**: every type, attribute and member this skill names exists at that tag, and the public surface it describes is unchanged since the previous verification (Chronicle 16.45.x / Arc 22.10.4 — the Chronicle 16→18 client diff is converters, options and doc comments; no type was removed or renamed). Behavior claims were verified at the earlier tag unless a section says otherwise.
+Source: `Source/Clients/Testing/ReadModels/` at **Cratis/Chronicle v19.50.0**.
 
 ```bash
 dotnet add package Cratis.Chronicle.Testing
@@ -82,6 +82,12 @@ var scenario = new ReadModelScenario<CartSummary>(new CartSummary { ItemCount =
 Further constructors take a service provider, a `Defaults`, or both, alongside
 the initial state. Use the named-parameter form when you need only one of them:
 `new ReadModelScenario<T>(initialState: null, serviceProvider: services)`.
+Scenarios implement `IDisposable`; call `_scenario.Dispose()` in `Destroy()`.
+`WithProjection(Action<IProjectionBuilderFor<T>>)` supplies an inline projection
+and wins over discovery, **including a discovered reducer**. Per-run `Defaults`
+can take a client artifacts provider, service provider and options;
+`InMemoryClientArtifactsProvider` and `ChronicleOptions.ExplicitArtifacts` let a
+specification isolate registrations without global discovery.
 
 ## Step 2 — Seed the events
 
@@ -103,6 +109,12 @@ await scenario.Given.ForEventSource(anotherOrderId).Events(new OrderCreated("ord
 offers `.ReadModel(instance)` to pin a materialized instance for code that calls
 `IReadModels.GetInstanceById` rather than deriving it from events.
 
+For a filtered reducer, seed the routing metadata as well:
+`Given.ForEventSource(id).OnStream(eventSourceType, eventStreamType, eventStreamId).Events(...)`.
+`[EventSourceType]`, `[EventStreamType]` and `[FromEventSource<T>]` filters are honored;
+unrouted seeds no longer reach a handler for another stream. Child-before-parent
+writes are retried when the parent later arrives; decimal seeds retain exact values.
+
 Events are processed in the order supplied. Seed before asserting, and do not
 try to separate a "setup" `Given` from an "act" `Given` — for a read model they
 are the same phase.
@@ -131,7 +143,7 @@ specific reason in the skip message.
 
 ## Step 4 — Know what the scenario picked
 
-The scenario finds a handler for `TReadModel` in this order:
+Without an explicit `WithProjection`, the scenario finds a handler for `TReadModel` in this order:
 
 1. A **reducer** — a class implementing `IReducerFor<TReadModel>`.
 2. A **fluent projection** — a class implementing `IProjectionFor<TReadModel>`.

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

@@ -17,7 +17,7 @@ This skill is verified against this exact source:
 
 | Package | Version | Purpose |
 | --- | --- | --- |
-| `Cratis.Chronicle` | `18.3.0` | `Cratis.Chronicle.Reducers`, `Cratis.Chronicle.ReadModels`, `Cratis.Chronicle.Events` |
+| `Cratis.Chronicle` | `19.50.1` | `Cratis.Chronicle.Reducers`, `Cratis.Chronicle.ReadModels`, `Cratis.Chronicle.Events` |
 
 Reverify product sources before claiming support for another version.
 
@@ -98,6 +98,9 @@ The rules the invoker enforces:
   per event type** — do not write two handlers for the same event.
 - Return the complete next state. Never mutate `current` in place; use `with { }`.
 - The reducer must be **stateless**. Do not hold mutable state on the class.
+- A reducer with no dispatchable methods is not registered. Logs name skipped
+  reducer-like methods; CHR0006/CHR0007 flag them. CHR0051 checks nullable current
+  state, and CHR0057 rejects multiple `IReducerFor<T>` targets on one class.
 
 ### Returning null deletes the instance
 
@@ -136,14 +139,14 @@ read.
 
 ## Filtering which events reach the reducer
 
-Three attributes genuinely filter a reducer's input, and they correspond to
-metadata supplied at append time:
+These attributes genuinely filter a reducer's input, matching append metadata:
 
 | Attribute | Filters on |
 | --- | --- |
 | `[FilterEventsByTag("<tag>")]` | an appended tag; repeatable, and any one match admits the event |
 | `[EventSourceType("<value>")]` | the appended event source type |
 | `[EventStreamType("<value>")]` | the appended event stream type |
+| `[FromEventSource<TSource>("<stream>")]` | the source definition and declared stream (`Cratis.Chronicle.EventSources`) |
 
 `[Tag]` and `[Tags]` **label** the artifact; they do not filter. Note also that a
 **projection cannot be filtered at all** — its definition has no field for it.
@@ -163,6 +166,20 @@ await eventStore.EventLog.Append(
 
 Mind the parameter order on `Append`: `eventStreamType` comes before
 `eventStreamId`, which comes before `eventSourceType`.
+CHR0055 flags an unknown typed stream and CHR0056 contradictory routing.
+Filters remain effective during catch-up, replay and failed-partition recovery.
+
+## Definition changes replay
+
+The kernel classifies new definitions under `observers.definitionEvolution`:
+`Automatic` (default), `PartialOnly`, or `Manual`. Reducer method fingerprints
+make code changes visible even without subscription changes; assembly versions
+are ignored since 19.29.4 (that upgrade replays each reducer once). Changed
+implementation, keys or filters require full replay; adding event types permits
+partial replay only when history proves they follow all previously consumed
+events per source. Interleaved history requires full replay. Manual policies
+leave recommendations; they do not silently rebuild. Source at v19.50.0:
+`Documentation/hosting/configuration/observers.md`.
 
 ## Specifications
 
@@ -194,7 +211,9 @@ assert on the resulting instance there. Cover, at minimum:
 
 - The admission test is satisfied and the justification names the specific
   limitation.
-- The current-state parameter is nullable on every handler method.
+- The current-state parameter is nullable on every handler method (CHR0051).
+- Logs contain no skipped reducer-like method warning (CHR0006/CHR0007);
+  CHR0055–CHR0057 are clean.
 - No handler method has more than three parameters, and any third is
   `EventContext`.
 - Exactly one handler exists per event type.