@cratis/pi 2.26.0 → 2.27.0

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

@@ -1,6 +1,6 @@
 ---
 name: cratis-chronicle-projection
-description: Add Chronicle projection behavior to an existing read model - model-bound attributes first, the fluent IProjectionFor<T> builder when they cannot express the shape. Covers AutoMap, keys, children and nested types, counters, event-sequence selection, and the startup-crash traps. Use when populating a read model from events; do not use to create the read model and its query surface, and do not reach for a reducer before exhausting these options.
+description: Add Chronicle projection behavior to an existing read model - model-bound attributes first, the fluent IProjectionFor<T> builder when they cannot express the shape. Covers AutoMap, keys, children and nested types, counters, event-sequence selection, variants ([VariantOf<T>]/.VariantOf<T>() and [EntersOn<T>]/.EntersOn<T>()) for an entity with mutually exclusive lifecycle shapes such as a work item that is a backlog entry then a pull request then closed, and the startup-crash traps. Use when populating a read model from events; do not use to create the read model and its query surface, and do not reach for a reducer before exhausting these options.
 license: MIT
 ---
 
@@ -104,6 +104,64 @@ query edge. Chronicle's analyzer **`CHR0042` (`JoinOverridesLocalWrite`)** repor
 the overlap; suppress it only when the join is deliberately keeping that property
 fresh.
 
+## Variants — mutually exclusive shapes for one entity's lifecycle
+
+Some entities do not have one shape for their whole lifetime — a work item is a
+backlog entry until a pull request exists for it, then it is a pull request
+until it merges. Modeling that as one read model with a `Status` property and
+an ever-growing set of nullable columns makes every query filter on state
+before it can trust a field. **Variants** let you declare several mutually
+exclusive read models for the same logical entity instead — entering one
+variant automatically removes the entity from every other variant in the
+group, so at any point an entity exists in exactly one of them. Reach for
+variants only when the shapes genuinely diverge; a single read model with a
+`Status` flag is still right when every stage shares almost all its
+properties.
+
+> Variants require `Cratis.Chronicle` `19.1.0` or later — newer than this
+> skill's `18.3.0` baseline. Reverify before claiming support.
+
+Both approaches use the identity type only to anchor the group — it does not
+need to be a read model itself, and does not need a common CLR base type with
+any of the variants.
+
+**Model-bound:** `[VariantOf<TIdentity>]` on each variant type, `[EntersOn<TEvent>]`
+naming the event that activates it, and an optional `[GlobalFor<TIdentity>]` type
+carrying mappings shared across every variant.
+
+```csharp
+[VariantOf<WorkItem>]
+[EntersOn<IssueCreated>]
+public record BacklogItem([property: Key] Guid Id, string Title);
+
+[VariantOf<WorkItem>]
+[EntersOn<PullRequestCreated>]
+public record PullRequestItem([property: Key] Guid Id, [property: SetFrom<PullRequestCreated>] string PullRequestUrl);
+```
+
+**Fluent:** `.VariantOf<TIdentity>(keyAccessor)` and `.EntersOn<TEvent>()` are
+members of `IProjectionBuilderFor<TReadModel>` itself — there is no
+`[GlobalFor<T>]` equivalent, so a shared mapping is declared with `.From<TEvent>()`
+on each variant's builder.
+
+```csharp
+public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
+    .VariantOf<WorkItem>(_ => _.Id)
+    .EntersOn<PullRequestCreated>();
+```
+
+Only the entering event can create or resurrect a variant. Every other event a
+variant handles — declared exactly like an ordinary `.From<TEvent>()` /
+`[SetFrom<T>]` mapping — is automatically reclassified into an update-only
+join, so an out-of-order or replayed event can never resurrect a variant the
+entity has since left. A variant that declares no entering event at all throws
+`VariantMustDeclareEntersOnEvent` at startup.
+
+Read [references/variants.md](references/variants.md) for the complete group
+declaration, the update-only reclassification in full, `[GlobalFor<T>]` rules
+and its declaration-error trap, and best practices for picking an identity
+type.
+
 ## Selecting the source
 
 Class-level `[EventSequence("<name>")]`, `[EventLog]`, or `[EventStore("<name>")]`
@@ -146,6 +204,10 @@ or a reactor rather than annotating the projection.
 - **Chaining after `AutoMap()`/`NoAutoMap()`.** Those two return the base builder
   interface, so `.NotRewindable()`, `.Passive()`, `.ContainerName()`, and
   `.FromEventSequence()` will not compile after them. Put them last.
+- **A variant with no `[EntersOn<T>]` / `.EntersOn<T>()`.** Throws
+  `VariantMustDeclareEntersOnEvent` at startup — a variant that could never be
+  entered could never be written to at all. See
+  [references/variants.md](references/variants.md).
 
 ## `[FromAll]` versus `[FromEvery]`
 
@@ -177,5 +239,7 @@ projection spans streams.
 - `ConstantKey` is written as a property initializer.
 - The same event does not carry class-level `[FromEvent<T>]` on both a parent and
   a nested or child type.
+- Every variant group has at least one `[EntersOn<T>]` / `.EntersOn<T>()` per
+  variant, and every `[GlobalFor<T>]` member exists on every variant it targets.
 - The project builds clean and the read-model specifications pass against the
   verified package version.

package/package/corpus/skills/cratis-chronicle-projection/references/fluent-builder.md

@@ -21,15 +21,26 @@ member that Chronicle does not read. Use
 `[Projection(id: "<id>", eventSequence: "<name>")]` when the identity or source
 sequence must be explicit.
 
-## `IProjectionBuilderFor<TReadModel>` — its own four members
+## `IProjectionBuilderFor<TReadModel>` — its own members
 
 ```csharp
 IProjectionBuilderFor<TReadModel> FromEventSequence(EventSequenceId eventSequenceId);
 IProjectionBuilderFor<TReadModel> ContainerName(string containerName);
 IProjectionBuilderFor<TReadModel> NotRewindable();
 IProjectionBuilderFor<TReadModel> Passive();
+IProjectionBuilderFor<TReadModel> VariantOf<TIdentity>(Expression<Func<TReadModel, object?>> keyAccessor);
+IProjectionBuilderFor<TReadModel> EntersOn<TEvent>();
 ```
 
+`VariantOf<TIdentity>` and `EntersOn<TEvent>` require `Cratis.Chronicle`
+`19.1.0` or later — newer than this file's `18.3.0` baseline. See
+[variants.md](variants.md) for the full mechanics: the identity type anchors a
+group of mutually exclusive read models, only the event named in `EntersOn`
+can create or resurrect the variant, and every other `.From<TEvent>()` on the
+same builder is automatically reclassified into an update-only join. There is
+no fluent equivalent of the model-bound `[GlobalFor<T>]` shared handler — a
+mapping shared across variants is repeated on each variant's builder.
+
 ## Inherited from `IProjectionBuilder<TReadModel, TBuilder>`
 
 ```csharp

package/package/corpus/skills/cratis-chronicle-projection/references/model-bound-attributes.md

@@ -70,6 +70,19 @@ Setting it routes every matching event into a single aggregating document at
 that key. That is a different mechanism from the fluent builder's
 `UsingConstantKey("<key>")`, even though the effect is similar.
 
+## Variants
+
+| Attribute | Arity | Parameters | Targets |
+| --- | --- | --- | --- |
+| `[VariantOf<TIdentity>]` | `<TIdentity>` | none | class, struct; single |
+| `[EntersOn<T>]` | `<T>` | `(string? key = default)` | class, struct; repeatable |
+| `[GlobalFor<TIdentity>]` | `<TIdentity>` | none | class, struct; single |
+
+Requires `Cratis.Chronicle` `19.1.0` or later. See
+[variants.md](variants.md) for the full mechanics, the update-only
+reclassification of non-entering events, and the `VariantMustDeclareEntersOnEvent`
+startup trap.
+
 ## Relationships
 
 | Attribute | Arity | Parameters | Targets |

package/package/corpus/skills/cratis-chronicle-projection/references/variants.md

@@ -0,0 +1,182 @@
+# Variants — mutually exclusive read models for one entity
+
+Verified against `Cratis.Chronicle` `19.1.0` (first version carrying this
+feature; the skill's own baseline in `SKILL.md` is `18.3.0` — variants need at
+least `19.1.0`).
+
+Reach for variants when a single logical entity has genuinely different shapes
+across its lifecycle — a work item that is a backlog entry, then a pull
+request, then closed — and modeling it as one read model would mean a `Status`
+column plus an ever-growing set of properties that are only meaningful in one
+stage. A single read model with a `Status` flag is still correct when the
+stages differ only by a flag or two; reach for variants only when the shapes
+themselves diverge. See `choosing-a-read-model-style` in the Chronicle docs for
+the wider decision.
+
+Each variant is an ordinary projection — model-bound or fluent — with its own
+shape. Entering one variant automatically removes the entity from every other
+variant in the same group, so at any point an entity exists in exactly one
+variant. There is no CLR relationship required between the variants or the
+identity type; the identity type's only job is to anchor the group.
+
+## Declaring a group — model-bound
+
+```csharp
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.Keys;
+using Cratis.Chronicle.Projections.ModelBound;
+
+[EventType]
+public record IssueCreated(string Title);
+
+[EventType]
+public record PullRequestCreated(string PullRequestUrl);
+
+// Anchors the group. Does not need to be a read model itself, and does not
+// need a common CLR base type with any of the variants.
+public class WorkItem;
+
+[VariantOf<WorkItem>]
+[EntersOn<IssueCreated>]
+public record BacklogItem([property: Key] Guid Id, string Title);
+
+[VariantOf<WorkItem>]
+[EntersOn<PullRequestCreated>]
+public record PullRequestItem([property: Key] Guid Id, [property: SetFrom<PullRequestCreated>] string PullRequestUrl);
+```
+
+`[VariantOf<TIdentity>]` targets a class or struct, is not repeatable, and
+lives in `Cratis.Chronicle.Projections.ModelBound`. `TIdentity` is what groups
+variants — every type marked `[VariantOf<WorkItem>]` is mutually exclusive with
+every other. `[EntersOn<TEvent>]` targets a class or struct, **is repeatable**
+(a variant can be entered by more than one event type), and takes an optional
+`key` constructor argument naming the event property that identifies the
+instance — it defaults to the event source id.
+
+When `IssueCreated` is processed, a `BacklogItem` is created. When
+`PullRequestCreated` is processed for the same entity, `PullRequestItem` is
+created **and `BacklogItem` is removed automatically** — no `[RemovedWith<T>]`
+needed, the group handles it. Variants do not have to be entered in order: if
+`PullRequestCreated` arrives for an entity that was never a `BacklogItem`,
+`PullRequestItem` is still created.
+
+## Declaring a group — fluent (`IProjectionFor<T>`)
+
+```csharp
+using Cratis.Chronicle.Projections;
+
+// Anchors the group, same rules as above.
+public class WorkItem;
+
+public record BacklogItem(Guid Id, string Title);
+public record PullRequestItem(Guid Id, string PullRequestUrl);
+
+public class BacklogItemProjection : IProjectionFor<BacklogItem>
+{
+    public void Define(IProjectionBuilderFor<BacklogItem> builder) => builder
+        .VariantOf<WorkItem>(_ => _.Id)
+        .EntersOn<IssueCreated>();
+}
+
+public class PullRequestItemProjection : IProjectionFor<PullRequestItem>
+{
+    public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
+        .VariantOf<WorkItem>(_ => _.Id)
+        .EntersOn<PullRequestCreated>();
+}
+```
+
+`VariantOf<TIdentity>(Expression<Func<TReadModel, object?>> keyAccessor)` and
+`EntersOn<TEvent>()` are members of `IProjectionBuilderFor<TReadModel>` itself
+(`Cratis.Chronicle.Projections`), alongside `FromEventSequence`,
+`ContainerName`, `NotRewindable`, and `Passive`. Unlike the model-bound
+attribute, the fluent `VariantOf` call takes the key accessor explicitly —
+there is no separate `[Key]` to infer it from. AutoMap still applies exactly as
+for any other fluent projection.
+
+## Only the entering event can create a variant
+
+Every other `.From<TEvent>()` (fluent) or `[SetFrom<T>]` (model-bound) the
+variant declares works exactly as it would on an ordinary projection — with one
+difference: because the event is not the one named in `[EntersOn<T>]` /
+`.EntersOn<T>()`, Chronicle automatically reclassifies that mapping into an
+**update-only join** on the variant's own key before the definition reaches the
+projection engine. It can update an already-active instance; it can never
+create or resurrect one.
+
+```csharp
+// Model-bound
+[VariantOf<WorkItem>]
+[EntersOn<PullRequestCreated>]
+public record PullRequestItem(
+    [property: Key] Guid Id,
+    [property: SetFrom<PullRequestCreated>] string PullRequestUrl,
+    [property: SetFrom<BuildCompleted>] string BuildStatus); // update-only: BuildCompleted is not the entering event
+
+// Fluent
+public class PullRequestItemProjection : IProjectionFor<PullRequestItem>
+{
+    public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
+        .VariantOf<WorkItem>(_ => _.Id)
+        .EntersOn<PullRequestCreated>()
+        .From<BuildCompleted>(); // update-only, same reason
+}
+```
+
+**Why this matters:** without the reclassification, an out-of-order or
+replayed `BuildCompleted` could resurrect a `PullRequestItem` for an entity
+that has since moved to another variant — or one that was never a pull request
+at all. Declaring `[EntersOn<T>]` / `.EntersOn<T>()` is what makes that
+structurally impossible; you do not have to reason about event ordering
+yourself.
+
+## Sharing handlers across variants
+
+**Model-bound** has a dedicated mechanism: `[GlobalFor<TIdentity>]` on a type
+carrying the shared mappings as ordinary members. Every mapping is merged into
+every variant of `TIdentity`:
+
+```csharp
+[EventType]
+public record TitleChanged(string Title);
+
+[GlobalFor<WorkItem>]
+public record WorkItemSharedHandlers([property: SetFrom<TitleChanged>] string Title);
+```
+
+Every variant in the group **must** have the member a shared mapping targets —
+a variant missing it is a declaration error caught when the projection is
+discovered, not a silently skipped mapping at runtime. A shared handler is
+always update-only, exactly like any non-entering event, so it is safe to
+share across variants that enter at different times: it can never create or
+resurrect one on its own.
+
+**Fluent has no equivalent of `[GlobalFor<T>]`.** Each `IProjectionFor<T>` is
+its own class producing its own definition, so a mapping every variant needs is
+declared with `.From<TEvent>()` on each variant's builder individually. If that
+repetition becomes a maintenance concern, that is itself a reason to reach for
+model-bound projections for that group instead.
+
+## Startup-crash trap
+
+**A variant with no `[EntersOn<T>]` / `.EntersOn<T>()` throws
+`VariantMustDeclareEntersOnEvent` at startup.** A variant that could never be
+entered could never be created — and because every other handler on a variant
+is update-only, it would silently never be written to at all, so Chronicle
+refuses to start rather than let that pass silently.
+
+## Best practices
+
+1. **Pick an identity type that means something on its own** — not a marker
+   interface with no purpose beyond grouping. It is the type every variant (and
+   every shared handler) points back to.
+2. **Give every variant only the properties that stage of the entity actually
+   has.** A property every stage needs is either a `[GlobalFor<T>]` handler
+   (model-bound) or repeated on each variant's builder (fluent) — never a
+   reason to fall back to one shared shape with nullable columns.
+3. **Reach for variants only when the shapes genuinely diverge.** A single read
+   model with a `Status` property is still correct when every stage shares
+   almost all of its properties and differs only in a flag or two.
+4. **Each variant is its own collection; there is no query that spans a whole
+   group.** A caller that needs "this entity, whichever stage it's in" queries
+   each variant explicitly rather than assuming a single combined collection.

package/package.json

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