@cratis/pi 0.0.1

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

@@ -0,0 +1,344 @@
+---
+name: cratis-chronicle-reactor
+description: Implement a Chronicle IReactor - an automation that causes an external side effect, or a translation that appends follow-up events. Covers handler dispatch and parameter resolution, every supported return type, targeting another event source, replay handling with [OnceOnly] and [Replay], event filtering, failure and quarantine behavior, and the analyzer rules. Use for event-driven side effects; do not use to populate a read model.
+license: MIT
+---
+
+# Chronicle reactors
+
+A reactor observes events and **does things**: calls an external system, or
+appends follow-up events. A projection or reducer builds state; a reactor causes
+effects. If the answer is "populate a queryable model", it is not a reactor.
+
+| Need | Use |
+| --- | --- |
+| populate a queryable read model from events | a projection |
+| a current-state-plus-event transition | a reducer |
+| trigger a side effect outside the system | a reactor (**automation**) |
+| append follow-up events elsewhere in the system | a reactor (**translation**) |
+| both a model and an effect | one projection *and* one reactor |
+
+## Verified product sources
+
+This skill is verified against these exact sources:
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Chronicle` | `16.45.2` | `Cratis.Chronicle.Reactors`, `Cratis.Chronicle.Reactors.SideEffects`, `Cratis.Chronicle.EventSequences`, `Cratis.Chronicle.Events` |
+| `Cratis.Chronicle.CodeAnalysis` | `16.45.2` | `CHR0004`, `CHR0005`, `CHR0008`, `CHR0013`, `CHR0022`, `CHR0031`, `CHR0032` |
+
+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.
+
+## Write the reactor
+
+```csharp
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.Reactors;
+
+/// <summary>
+/// <what this automation does and why>.
+/// </summary>
+public class <ReactorName>(<IServiceType> <serviceName>) : IReactor
+{
+    /// <summary>Reacts to <see cref="<EventName>"/>.</summary>
+    public async Task <MethodName>(<EventName> @event, EventContext context) =>
+        await <serviceName>.<Operation>(@event.<Property>);
+}
+```
+
+`Cratis.Chronicle.Reactors.IReactor` is a **marker interface with no members**.
+Reactors are discovered by that interface — the `[Reactor]` attribute is optional
+and is not what makes a class a reactor. Generic types are not discovered.
+
+## Dispatch and parameters
+
+**Dispatch is by the first parameter's type.** The method name is for the reader
+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:
+
+| Parameter type | Resolved as |
+| --- | --- |
+| `EventContext` | the event context |
+| `ReactorDelivery` | reactor id, event store, namespace, event sequence, partition, sequence number |
+| 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.
+
+The first parameter's type must carry `[EventType]`, or analyzer **CHR0005**
+(error) rejects it.
+
+### Injecting a read model
+
+A read-model parameter is materialized using the event context's event-source id
+by default. When the model's key differs from the triggering event's source —
+the event carries a related entity's id — implement `ICanResolveReadModelKey` on
+the reactor:
+
+```csharp
+public class <ReactorName> : IReactor, ICanResolveReadModelKey
+{
+    public ReadModelKey Resolve(object @event, EventContext context) =>
+        ((<EventName>)@event).<RelatedIdProperty>;
+
+    public Task <MethodName>(<EventName> @event, <ReadModelName> <readModel>) =>
+        Task.CompletedTask;
+}
+```
+
+The resolved key applies to every read-model parameter across all of the
+reactor's handlers.
+
+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.
+
+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.
+
+## Return types
+
+| Return | Effect |
+| --- | --- |
+| `void`, `Task` | no side-effect append |
+| `TEvent`, `Task<TEvent>` | append one event, with reactor-level metadata |
+| `IEnumerable<object>`, `Task<IEnumerable<object>>` | append several, in one transaction |
+| `EventForEventSourceId`, `Task<...>` | append one event to an explicit event source |
+| `IEnumerable<EventForEventSourceId>`, `Task<...>` | append to several event sources, in one transaction |
+| `EventsWithConcurrencyScopes`, `Task<...>` | append with explicit concurrency scopes |
+
+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>`.
+
+### 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.
+
+```csharp
+// One event, on the triggering event's own event source.
+public Task<<ResultEvent>> <MethodName>(<EventName> @event, EventContext context) =>
+    Task.FromResult(new <ResultEvent>(@event.<Property>));
+
+// Several events on that same event source.
+public Task<IEnumerable<object>> <MethodName>(<EventName> @event, EventContext context) =>
+    Task.FromResult<IEnumerable<object>>([new <ResultEvent>(), new <OtherEvent>()]);
+```
+
+### 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; }
+}
+```
+
+```csharp
+public Task<IEnumerable<EventForEventSourceId>> <MethodName>(<EventName> @event, EventContext context) =>
+    Task.FromResult<IEnumerable<EventForEventSourceId>>(
+    [
+        new(@event.<RelatedId>, new <ResultEvent>(@event.<Property>)),
+        new(@event.<OtherId>, new <OtherEvent>()) { EventStreamType = new("<stream-type>") },
+    ]);
+```
+
+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
+
+For a **bare** event return, Chronicle resolves the append metadata from the
+reactor itself: the `[EventSourceType]`, `[EventStreamType]`, and
+`[EventStreamId]` attributes, and the `ICanProvideEventSourceId`,
+`ICanProvideEventStreamId`, and `ICanProvideSubject` interfaces (all in
+`Cratis.Chronicle.Events`, each with one method).
+
+An `EventForEventSourceId` is **self-describing** — reactor-level metadata is not
+applied to it. In a mixed collection, bare items get the reactor metadata and
+wrapper items keep their own.
+
+## Replay
+
+A reactor sees the same event twice for different reasons: when it happens, and
+again when its observer is replayed.
+
+`Cratis.Chronicle.Reactors.OnceOnlyAttribute` (`[OnceOnly]`) targets a **class or
+a method** and means **replay exclusion**:
+
+- on the class, the observer is marked not replayable and the replay never
+  starts;
+- on a method, that handler is skipped while the delivery is a replay.
+
+**`[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.
+
+Analyzer **CHR0022** (warning) requires `[OnceOnly]` on a handler that returns
+event side effects, because a replay would otherwise append duplicates.
+
+`Cratis.Chronicle.Reactors.ReplayAttribute` (`[Replay]`) is the other half, and
+targets a method only. Mark a **second** handler for the same event type with it
+when replay needs to do something *different* rather than nothing:
+
+```csharp
+public Task <MethodName>(<EventName> @event) => <serviceName>.<Operation>(@event.<Property>);
+
+[Replay]
+public Task <MethodName>DuringReplay(<EventName> @event) => Task.CompletedTask;
+```
+
+With a `[Replay]` handler present, only it runs during replay. Without one, the
+ordinary handler runs during replay as before. An event type handled *only* by a
+`[Replay]` handler is still subscribed to.
+
+## Identity and event sequence
+
+`Cratis.Chronicle.Reactors.ReactorAttribute` takes two optional arguments:
+
+```csharp
+public sealed class ReactorAttribute(string id = "", string? eventSequence = default) : Attribute
+```
+
+**There is no `isActive` argument** — that belongs to `[Reducer]`. Without an
+explicit `id`, the reactor's identity is its full type name.
+
+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
+event types, then the event log.
+
+**`[EventStore]` cannot be combined** with `[EventSequence]`, `[EventLog]`, or
+`Reactor(eventSequence: ...)` — analyzer **CHR0013** (error), and a runtime
+exception. All of a reactor's event types must come from one event store —
+analyzer **CHR0008** (error).
+
+### Cross-service events
+
+Cross-service facts route through the outbox and inbox rather than a shared log.
+The producer appends its public contract event to the outbox sequence; the
+consuming observer listens on the implicit inbox sequence for the source store.
+Chronicle creates or reuses that subscription from the observer's `[EventStore]`
+metadata, or from `[EventStore]` on the event type or its assembly. Put
+`[assembly: EventStore("<source-store>")]` in a contracts project when every
+event there originates from one service.
+
+## Filtering which events reach the reactor
+
+| Attribute | Effect |
+| --- | --- |
+| `[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 |
+| `[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.
+These correspond to metadata supplied at append time:
+
+```csharp
+await eventStore.EventLog.Append(
+    <eventSourceId>,
+    new <EventName>(<arguments>),
+    eventStreamType: "<stream-type>",
+    eventSourceType: "<source-type>",
+    tags: ["<tag>"]);
+```
+
+A **projection cannot be filtered at all** — if you need metadata-based
+selection, a reactor or a reducer is where it happens.
+
+## Translation via a command
+
+A translation that adapts one area's events into another's intent runs a command
+rather than appending directly. `ICommandPipeline` is an **Arc** type
+(`Cratis.Arc.Commands`), not a Chronicle one:
+
+```csharp
+using Cratis.Arc.Commands;
+
+public class <ReactorName>(ICommandPipeline commandPipeline) : IReactor
+{
+    public async Task <MethodName>(<EventName> @event, EventContext context) =>
+        await commandPipeline.Execute(new <CommandName>(@event.<Property>));
+}
+```
+
+## Failure behavior
+
+If a handler throws, or a returned side-effect event fails to append — a
+constraint violation, a concurrency violation, or an error — the failing
+event-source partition **pauses** until the cause is resolved. Repeated failures
+can **quarantine** the observer, which stops retries and suppresses automatic
+recovery. **A quarantined observer does not resume on reconnect**; an operator
+must clear the quarantine explicitly.
+
+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
+cross-service fact arrives, append a clear failure or dead-letter event, or
+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.
+
+## 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.
+
+## Specifications
+
+Drive events through the reactor scenario helper with a service provider of
+substitutes, and assert on those substitutes for 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.
+
+## Verify
+
+- The class implements `IReactor` and is not generic.
+- Every handler's first parameter is an `[EventType]` record, and there is one
+  handler per event type.
+- Every additional parameter resolves to the event context, `ReactorDelivery`, a
+  read model, or a service.
+- No handler returns or references `ReactorSideEffect`.
+- No `IEventLog` is injected; side-effect events are returned instead.
+- Handlers returning events carry `[OnceOnly]`.
+- Side effects are idempotent even with `[OnceOnly]`, because recovery
+  re-delivers.
+- `[EventStore]` is not combined with an explicit event sequence.
+- 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
+  specifications pass.

package/skills/cratis-chronicle-read-model/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

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

@@ -0,0 +1,193 @@
+---
+name: cratis-chronicle-read-model
+description: Create a Chronicle read model and its query surface - past-tense event types, the read-model record and its key, choosing a projection or a reducer to build it, snapshot versus observable queries, and reading an instance directly through IReadModels. Use when creating a read model from scratch; for changing how an existing model is populated use the projection or reducer skill instead.
+license: MIT
+---
+
+# Chronicle read models
+
+A read model is derived state built from events. The path is:
+
+```text
+event types -> read-model record -> a projection or a reducer -> a query surface
+```
+
+Chronicle owns the events, the projection or reducer, and the stored instance.
+The **query surface is Arc's**, and the two halves are separable: a read model
+that only exists to be read from inside the backend needs no query surface at
+all.
+
+## Verified product sources
+
+This skill is verified against these exact sources:
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Chronicle` | `16.45.2` | `Cratis.Chronicle.Events`, `Cratis.Chronicle.Keys`, `Cratis.Chronicle.ReadModels` |
+| `Cratis.Arc.Core` | current | `Cratis.Arc.Queries.ModelBound.ReadModelAttribute` and `PathAttribute` |
+| `Cratis.Arc.MongoDB` | current | 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.
+
+## Step 1 — Define the events
+
+Events are the source of truth. Each is a `record` carrying
+`Cratis.Chronicle.Events.EventTypeAttribute`, named as a past-tense fact.
+
+```csharp
+using Cratis.Chronicle.Events;
+
+/// <summary>Emitted when <description>.</summary>
+[EventType]
+public record <EntityName><PastTenseVerb>(<ConceptType> <PropertyName>);
+```
+
+- One clear purpose per event; do not mix concerns into one fact.
+- **Avoid nullable properties.** Analyzer `CHR0012` warns on them. Model an
+  optional fact as a separate event.
+- Prefer strongly typed concept properties over raw primitives.
+- An event never carries its own event-source id as a payload property — the id
+  is in the event context.
+- `[EventType]` takes `(string id = "", uint generation = 1)`. Pass neither for a
+  new event: the id defaults to the CLR type name and the generation to `1`.
+
+## Step 2 — Define the read-model record
+
+```csharp
+using Cratis.Chronicle.Keys;
+
+public record <ReadModelName>(
+    [property: Key] <IdType> Id,
+    <PropertyType> <PropertyName>);
+```
+
+- `Cratis.Chronicle.Keys.KeyAttribute` takes no arguments and targets a property
+  or a record constructor parameter, never the class.
+- When the model's identity **is** the event-source id, that is already the key
+  and `[Key]` adds nothing. Placing `[Key]` on an `EventSourceId<T>`-derived
+  value is flagged by analyzer `CHR0026`.
+- One read model per use case. Specialization beats a shared model reused across
+  conflicting scenarios.
+- Do not give read-model properties default values that could mask a projection
+  that was never wired.
+- Never name a property `_subject`, `__subject`, or `__subjects` — Chronicle
+  reserves those for compliance-subject tracking, and analyzer `CHR0035`
+  rejects them.
+- `Cratis.Chronicle.ReadModels.IndexAttribute` (`[Index]`) marks a property for
+  indexing in the sink.
+
+## Step 3 — Choose a projection or a reducer
+
+| | Projection | Reducer |
+| --- | --- | --- |
+| Shape | the model is mostly a mapping of event fields | the next state is a function of the current state |
+| Expressed as | model-bound attributes, or the fluent builder | C# control flow in a handler method |
+| Reach for it | first, and second | only after both projection forms fail |
+
+A reducer is a legitimate style when the transition genuinely depends on prior
+state — it is not a failure mode. It *is* a failure mode when it re-implements
+something an attribute already expresses. Work down the ladder: model-bound
+attributes, then the fluent builder, then a reducer.
+
+Both are discovered by convention. Nothing is registered.
+
+Use the projection skill for the attribute and builder surface, and the reducer
+skill for handler signatures and the nullable-current rule.
+
+## Step 4 — Add a query surface, if the model is read from outside
+
+Queries are **static** methods on the read-model record, discovered by Arc.
+Marking the record with `[ReadModel]` from `Cratis.Arc.Queries.ModelBound` is
+what gives it that surface.
+
+```csharp
+using System.Reactive.Subjects;
+using Cratis.Arc.Queries.ModelBound;
+using Cratis.Chronicle.Keys;
+using MongoDB.Driver;
+
+[ReadModel]
+public record <ReadModelName>([property: Key] <IdType> Id, <PropertyType> <PropertyName>)
+{
+    public static async Task<IEnumerable<<ReadModelName>>> All<PluralName>(
+        IMongoCollection<<ReadModelName>> collection) =>
+        await collection.Find(Builders<<ReadModelName>>.Filter.Empty).ToListAsync();
+
+    public static ISubject<IEnumerable<<ReadModelName>>> Observe<PluralName>(
+        IMongoCollection<<ReadModelName>> collection) =>
+        collection.Observe();
+}
+```
+
+The rules Arc's discovery actually enforces:
+
+- The method must be **static**. Instance methods are never discovered.
+- The declared return type, after unwrapping one `Task<>`, must be the read
+  model, an array of it, something assignable to `IEnumerable<T>` of it,
+  `IAsyncEnumerable<T>` of it, `ISubject<T>` of it, or `ISubject<>` of a
+  collection of it.
+- **The declared type must be `ISubject<...>`, never `Subject<...>` or
+  `BehaviorSubject<...>`.** The check matches the open generic definition
+  exactly, so a concrete subject type fails discovery silently. Construct a
+  concrete subject inside if you like; declare `ISubject<...>`.
+- Open generic methods are rejected.
+- Use `[Path("<route>")]` from `Cratis.Arc.Queries.ModelBound` for a custom
+  route. It targets the class or the method. It is Arc's attribute — do not
+  reach for ASP.NET's `[Route]`.
+
+Read [references/queries.md](references/queries.md) for the `Observe` family and
+the difference between snapshot and observable queries.
+
+## Step 5 — Or read the instance directly
+
+Inside the backend, read an instance through
+`Cratis.Chronicle.ReadModels.IReadModels`, reached from `IEventStore.ReadModels`:
+
+```csharp
+Task<TReadModel> GetInstanceById<TReadModel>(ReadModelKey key, ReadModelSessionId? sessionId = null);
+Task<object> GetInstanceById(Type readModelType, ReadModelKey key, ReadModelSessionId? sessionId = null);
+```
+
+`ReadModelKey` converts implicitly from `string`, `Guid`, and `EventSourceId`,
+so an id can be passed directly. **The declared return type is not nullable even
+though no instance may exist** — check the result before dereferencing it.
+
+Neighbouring members include `GetInstances<T>`, `GetSnapshotsById<T>`,
+`Watch<T>`, `Release<T>`, and `Register`. **There is no predicate or `IQueryable`
+surface on `IReadModels`** — filtered reads go through the sink, which is what
+the Arc query methods above do.
+
+### `[Passive]` when the read is a command-side decision
+
+`Cratis.Chronicle.ReadModels.PassiveAttribute` on the read-model type makes it
+passive: no sink, nothing materialized, and the instance is computed on demand
+from the events at the moment it is read. Reach for it when a decision needs the
+model **strongly consistent** rather than eventually consistent.
+
+`[Passive]` on its own does **not** make a read model a projection. It is
+deliberately excluded from the annotations that do; it changes how an existing
+projection is registered.
+
+## Step 6 — Build and verify
+
+Build, fix every error, then prove the behavior: drive the contributing events
+through the read-model specification for this model and assert the projected
+state. Seed each contributing stream with its own event source when the model
+spans streams.
+
+## Verify
+
+- Every event is a past-tense fact with one purpose and no nullable properties.
+- No event carries its own event-source id.
+- The read model has exactly one key, and no `[Key]` sits on an
+  `EventSourceId<T>` value.
+- No reserved compliance-subject property name is used.
+- Read-model properties carry no defaults that could hide unwired projection.
+- Query methods are `static` and declare `ISubject<...>` rather than a concrete
+  subject type.
+- A direct `GetInstanceById` result is checked for absence before use.
+- `[Passive]` is present only where a strongly consistent command-side read is
+  genuinely required.
+- The project builds clean and the read-model specifications pass against the
+  verified package versions.

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

@@ -0,0 +1,142 @@
+# Read-model queries
+
+Verified against `Cratis.Arc.Core` and `Cratis.Arc.MongoDB` as checked out
+alongside `Cratis.Chronicle` `16.45.2`. Confirm the exact Arc package version in
+the consuming project before citing one.
+
+## Where the pieces live
+
+| Type | Namespace | Package |
+| --- | --- | --- |
+| `ReadModelAttribute` (`[ReadModel]`) | `Cratis.Arc.Queries.ModelBound` | `Cratis.Arc.Core` |
+| `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
+one `string path` and targets a class or a method.
+
+The `Observe` extensions are deliberately declared in the `MongoDB.Driver`
+namespace so they resolve from an existing `using MongoDB.Driver;`. They are not
+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.
+
+The declared return type is validated after unwrapping at most one `Task<>`:
+
+| Accepted |
+| --- |
+| the read model type |
+| an array of it |
+| anything assignable to `IEnumerable<T>` of it |
+| `IAsyncEnumerable<T>` of it |
+| `ISubject<T>` of it |
+| `ISubject<T>` of a collection of it |
+
+Rejected: open generic methods, and **any concrete subject type**. The subject
+check matches `typeof(ISubject<>)` as an open generic definition, so a method
+declared as returning `Subject<T>` or `BehaviorSubject<T>` fails discovery
+without an error at the call site. Declare `ISubject<...>`; construct whatever
+you like inside.
+
+## Snapshot queries
+
+A snapshot query answers once with the current state.
+
+```csharp
+public static async Task<IEnumerable<<ReadModelName>>> All<PluralName>(
+    IMongoCollection<<ReadModelName>> collection) =>
+    await collection.Find(Builders<<ReadModelName>>.Filter.Empty).ToListAsync();
+
+public static async Task<<ReadModelName>?> <SingularName>ById(
+    <IdType> id,
+    IMongoCollection<<ReadModelName>> collection) =>
+    await collection.Find(model => model.Id == id).FirstOrDefaultAsync();
+```
+
+Name the method for what it returns — the name is the query's identity on the
+generated client surface.
+
+## Observable queries
+
+An observable query pushes updates as projected state lands.
+
+```csharp
+public static ISubject<IEnumerable<<ReadModelName>>> Observe<PluralName>(
+    IMongoCollection<<ReadModelName>> collection) =>
+    collection.Observe();
+
+public static ISubject<<ReadModelName>> Observe<SingularName>ById(
+    <IdType> id,
+    IMongoCollection<<ReadModelName>> collection) =>
+    collection.ObserveById<<ReadModelName>, <IdType>>(id);
+```
+
+Return `ISubject<...>` directly. Do **not** return `Task<ISubject<...>>`.
+
+## The `Observe` family — exact signatures
+
+```csharp
+// collection-valued
+ISubject<IEnumerable<TDocument>> Observe<TDocument>(
+    this IMongoCollection<TDocument> collection,
+    Expression<Func<TDocument, bool>>? filter,
+    FindOptions? options = null);
+
+ISubject<IEnumerable<TDocument>> Observe<TDocument>(
+    this IMongoCollection<TDocument> collection,
+    FilterDefinition<TDocument>? filter = null,
+    FindOptions? options = null);
+
+// single-valued
+ISubject<TDocument> ObserveSingle<TDocument>(
+    this IMongoCollection<TDocument> collection,
+    Expression<Func<TDocument, bool>>? filter,
+    FindOptions? options = null);
+
+ISubject<TDocument> ObserveSingle<TDocument>(
+    this IMongoCollection<TDocument> collection,
+    FilterDefinition<TDocument>? filter = null,
+    FindOptions? options = null);
+
+ISubject<TDocument> ObserveById<TDocument, TId>(
+    this IMongoCollection<TDocument> collection,
+    TId id);
+```
+
+Two details that catch people out:
+
+- **`Observe` always returns a collection**, even with an equality filter. For a
+  single document use `ObserveSingle` or `ObserveById`; a filtered `Observe`
+  declared as `ISubject<TDocument>` does not compile.
+- On the expression overload the `filter` parameter has **no default**. A bare
+  `collection.Observe()` therefore binds the `FilterDefinition<TDocument>?`
+  overload, which is the intended "everything" call.
+
+Also available in the same place: `FindById<T, TId>` and
+`FindByIdAsync<T, TId>`.
+
+## Custom routes
+
+```csharp
+[ReadModel]
+[Path("<resource-path>")]
+public record <ReadModelName>(...)
+{
+    [Path("<sub-path>")]
+    public static Task<IEnumerable<<ReadModelName>>> <QueryName>(...) => ...;
+}
+```
+
+`[Path]` is Arc's attribute and works at class or method level. ASP.NET's
+`[Route]` belongs to controller-based endpoints and is not the mechanism here.
+
+## Reading without a query surface
+
+When only backend code reads the model, skip `[ReadModel]` entirely and use
+`IEventStore.ReadModels.GetInstanceById<T>(key)`. Its declared return type is
+non-nullable even though no instance may exist, so test the result. There is no
+predicate or `IQueryable` surface on `IReadModels` — filtered reads belong on the
+sink, which is what the query methods above use.

package/skills/cratis-chronicle-read-model-specifications/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.