@cratis/pi 0.0.1

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

@@ -0,0 +1,162 @@
+---
+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.
+license: MIT
+---
+
+# Chronicle projections
+
+A projection consumes **events** and produces read-model state. It is pure: no
+side effects, and it never reads another read model. Prefer model-bound
+attributes on the read model; fall back to the fluent builder only when the
+attributes cannot express the shape; reach for a reducer only after both fail.
+
+## Verified product sources
+
+This skill is verified against this exact source:
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Chronicle` | `16.45.2` | `Cratis.Chronicle.Projections`, `Cratis.Chronicle.Projections.ModelBound`, `Cratis.Chronicle.Keys`, `Cratis.Chronicle.EventSequences` |
+
+Reverify product sources before claiming support for another version.
+
+> `[ReadModel]` and `[Path]` are **Arc** types (`Cratis.Arc.Queries.ModelBound`),
+> not Chronicle types. A Chronicle read model that exists only as a projection
+> target needs no `[ReadModel]` at all — that attribute is what gives it an Arc
+> query surface.
+
+## Model-bound projections — the default
+
+Put the projection on the read model with attributes. No separate class.
+
+```csharp
+using Cratis.Chronicle.Keys;
+using Cratis.Chronicle.Projections.ModelBound;
+
+[FromEvent<<EventName>>]
+public record <ReadModelName>(
+    [property: Key] <IdType> Id,
+    <PropertyType> <PropertyName>);
+```
+
+Matching property names map automatically. **AutoMap is on by default** — both
+for model-bound types and for the fluent builder — so never call `.AutoMap()`
+except inside a scope where you disabled it.
+
+`[Key]` is `Cratis.Chronicle.Keys.KeyAttribute`. It has no arguments and targets
+a property or a record constructor parameter, never the class.
+
+Read [references/model-bound-attributes.md](references/model-bound-attributes.md)
+for the complete attribute list with exact arities, parameter names, and valid
+targets. Two things there are worth knowing before you write anything:
+
+- `[Nested]`, `[FromAll]`, and `[FromEvery]` are **non-generic**.
+- `ConstantKey` on `[Count<T>]`, `[Increment<T>]`, `[Decrement<T>]`, and
+  `[FromEvent<T>]` is an **object-initializer property**, never a constructor
+  argument: `[Count<TEvent>(ConstantKey = "<key>")]`.
+
+## Fluent projections — the fallback
+
+Use `Cratis.Chronicle.Projections.IProjectionFor<TReadModel>` when the attributes
+cannot express the shape — for example when two events feed one child collection
+through different key properties.
+
+```csharp
+using Cratis.Chronicle.Projections;
+
+public class <ReadModelName>Projection : IProjectionFor<<ReadModelName>>
+{
+    public void Define(IProjectionBuilderFor<<ReadModelName>> builder) =>
+        builder
+            .From<<EventName>>(from => from.UsingKey(@event => @event.<KeyProperty>))
+            .RemovedWith<<RemovalEventName>>();
+}
+```
+
+`Define` returns `void`. **There is no `Identifier` or `ProjectionId` member on
+the interface** — do not add one. Use `[Projection(id: "<id>")]` when the
+identity must be explicit.
+
+Read [references/fluent-builder.md](references/fluent-builder.md) for the real
+member list. The trap that costs the most time: **`UsingKey`, `UsingParentKey`,
+`UsingCompositeKey`, and `UsingConstantKey` are not on the projection builder.**
+They live on the per-event builder that `From<TEvent>` hands to your callback.
+
+## Joins are on events, never on read models
+
+Both `[Join<T>]` and the fluent `Join<TEvent>` take an **event** type. Joining on
+a read model type is not supported and is not what the API means. If a read model
+needs a field that only another read model has, the model is missing an event —
+fix the event model rather than cross-reading at runtime.
+
+## Selecting the source
+
+Class-level `[EventSequence("<name>")]`, `[EventLog]`, or `[EventStore("<name>")]`
+choose where a model-bound projection reads from.
+
+> **`[FromEventSequence]` no longer exists.** It was removed. The replacement on a
+> model-bound read model is `[EventSequence("<name>")]` or `[EventLog]`. The
+> fluent builder still has a `FromEventSequence(EventSequenceId)` **method** —
+> that one is alive; do not confuse the two.
+
+## Projections cannot filter by appended metadata
+
+Chronicle correlates appended metadata in two different ways:
+
+- **Projections** select their input through event types, joins, and event
+  sequence configuration — and nothing else. A projection's definition has **no
+  field for a filter at all**.
+- **Reducers and reactors** can additionally filter by appended tag, event source
+  type, and event stream type, using `[FilterEventsByTag]`, `[EventSourceType]`,
+  and `[EventStreamType]`.
+
+`[Tag]` and `[Tags]` on a projection or read model label the artifact; they never
+filter. If you need metadata-based selection, pair the projection with a reducer
+or a reactor rather than annotating the projection.
+
+## Startup-crash traps
+
+- **Duplicate class-level `[FromEvent<T>]`.** Declaring `[FromEvent<T>]` with no
+  `key:` on **both** a parent and a nested or child type for the **same** event
+  throws a duplicate-key exception at startup. Keep `[FromEvent<T>]` on the
+  nested type only, or switch the nested type to property-level `[SetFrom<T>]`.
+- **Duplicate `[SetFromContext<T>]`.** Two properties with
+  `[SetFromContext<SameEvent>]` on one read model crash at startup. Merge them,
+  or use `[FromEvery]`.
+- **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.
+
+## `[FromAll]` versus `[FromEvery]`
+
+- `[FromAll]` subscribes to **every** event type in the system. It is for audit
+  and log models; pair it with `[NotRewindable]`. It targets a **property only**,
+  so it cannot go on a record positional parameter.
+- `[FromEvery]` captures across the events the model **already** declares through
+  its `[FromEvent<T>]` attributes — for example to stamp `EventContext` data. It
+  subscribes to nothing new.
+
+Their two optional arguments are in **opposite order**: `[FromAll(contextProperty,
+property)]` and `[FromEvery(property, contextProperty)]`. Name them.
+
+## After creating
+
+Build. Fix every error before completing. Then 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 setup when the
+projection spans streams.
+
+## Verify
+
+- Model-bound attributes were exhausted before the fluent builder, and the
+  fluent builder before any reducer.
+- `.AutoMap()` is called only inside a `.NoAutoMap()` scope.
+- Every join is on an event type.
+- No `[FromEventSequence]` attribute appears anywhere.
+- No projection carries a filter attribute expecting it to filter.
+- `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.
+- The project builds clean and the read-model specifications pass against the
+  verified package version.

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

@@ -0,0 +1,126 @@
+# The fluent projection builder
+
+Verified against `Cratis.Chronicle` `16.45.2`, namespace
+`Cratis.Chronicle.Projections`.
+
+## The interfaces
+
+```csharp
+public interface IProjection;
+
+public interface IProjectionFor<TReadModel> : IProjection
+    where TReadModel : class
+{
+    void Define(IProjectionBuilderFor<TReadModel> builder);
+}
+```
+
+`IProjection` is an empty marker. `Define` returns `void`. **The interface has
+no `Identifier` or `ProjectionId` member** — declaring one adds a plain class
+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
+
+```csharp
+IProjectionBuilderFor<TReadModel> FromEventSequence(EventSequenceId eventSequenceId);
+IProjectionBuilderFor<TReadModel> ContainerName(string containerName);
+IProjectionBuilderFor<TReadModel> NotRewindable();
+IProjectionBuilderFor<TReadModel> Passive();
+```
+
+## Inherited from `IProjectionBuilder<TReadModel, TBuilder>`
+
+```csharp
+IProjectionBuilder<TReadModel, TBuilder> AutoMap();     // returns the BASE interface
+IProjectionBuilder<TReadModel, TBuilder> NoAutoMap();   // returns the BASE interface
+
+TBuilder WithInitialValues(Func<TReadModel> initialValueProviderCallback);
+TBuilder From<TEvent>(Action<IFromBuilder<TReadModel, TEvent>>? builderCallback = default);
+TBuilder Join<TEvent>(Action<IJoinBuilder<TReadModel, TEvent>>? builderCallback = default);
+TBuilder FromEvery(Action<IFromEveryBuilder<TReadModel>> builderCallback);   // callback required
+TBuilder FromAll(Action<IFromAllBuilder<TReadModel>> builderCallback);       // callback required
+TBuilder RemovedWith<TEvent>(Action<RemovedWithBuilder<TReadModel, TEvent>>? builderCallback = default);
+TBuilder RemovedWithJoin<TEvent>(Action<RemovedWithJoinBuilder<TReadModel, TEvent>>? builderCallback = default);
+TBuilder Children<TChildModel>(
+    Expression<Func<TReadModel, IEnumerable<TChildModel>>> targetProperty,
+    Action<IChildrenBuilder<TReadModel, TChildModel>> builderCallback);
+TBuilder Nested<TNestedModel>(
+    Expression<Func<TReadModel, TNestedModel?>> targetProperty,
+    Action<INestedBuilder<TReadModel, TNestedModel>> builderCallback);
+```
+
+**`AutoMap()` and `NoAutoMap()` return the base interface, not `TBuilder`.**
+Chaining `.NotRewindable()`, `.Passive()`, `.ContainerName()`, or
+`.FromEventSequence()` after either of them does not compile. Put them last.
+
+`RemovedWith` and `RemovedWithJoin` hand you the **concrete**
+`RemovedWithBuilder<,>` and `RemovedWithJoinBuilder<,>` classes, not interfaces.
+
+## Keys live on the per-event builder
+
+`From<TEvent>` hands the callback an `IFromBuilder<TReadModel, TEvent>`, which
+derives from `IReadModelPropertiesBuilder<TReadModel, TEvent, TBuilder>`. That
+is where every key method lives:
+
+```csharp
+TBuilder UsingKey<TProperty>(Expression<Func<TEvent, TProperty>> keyAccessor);
+TBuilder UsingKeyFromContext<TProperty>(Expression<Func<EventContext, TProperty>> keyAccessor);
+TBuilder UsingParentKey<TProperty>(Expression<Func<TEvent, TProperty>> keyAccessor);
+TBuilder UsingParentKeyFromContext<TProperty>(Expression<Func<EventContext, TProperty>> keyAccessor);
+TBuilder UsingCompositeKey<TKeyType>(Action<ICompositeKeyBuilder<TKeyType, TEvent>> builderCallback);
+TBuilder UsingParentCompositeKey<TKeyType>(Action<ICompositeKeyBuilder<TKeyType, TEvent>> builderCallback);
+TBuilder UsingConstantKey(string value);
+TBuilder UsingConstantParentKey(string value);
+```
+
+The same interface carries the value operations:
+
+```csharp
+TBuilder Increment<TProperty>(...);
+TBuilder Decrement<TProperty>(...);
+TBuilder Add<TProperty>(...);
+TBuilder Subtract<TProperty>(...);
+TBuilder Count<TProperty>(...);
+TBuilder AddChild<TChildModel>(...);
+ISetBuilder<...> Set(PropertyPath propertyPath);
+ISetBuilder<...> Set<TProperty>(Expression<Func<TReadModel, TProperty>> propertyExpression);
+TBuilder SetThisValue();
+TBuilder Clear<TProperty>(...);   // default implementation throws unless the builder overrides it
+```
+
+## `Set(...).To(...)`
+
+```csharp
+// ISetBuilder<TReadModel, TEvent, TParentBuilder>
+TParentBuilder To(PropertyPath propertyPath);
+TParentBuilder ToEventSourceId();
+
+// ISetBuilder<TReadModel, TEvent, TProperty, TParentBuilder>
+TParentBuilder ToValue(TProperty value);
+TParentBuilder To(Expression<Func<TEvent, TProperty>> eventPropertyAccessor);
+TParentBuilder ToEventContextProperty(Expression<Func<EventContext, object>> eventContextPropertyAccessor);
+```
+
+## When the fluent form is the only option
+
+The clearest case is a child collection fed by events that carry **different key
+properties**, which the single-key model-bound `[ChildrenFrom<T>]` cannot state:
+
+```csharp
+public void Define(IProjectionBuilderFor<<ReadModelName>> builder) =>
+    builder
+        .From<<AssignedEvent>>(from => from.UsingKey(@event => @event.<KeyA>))
+        .From<<UpdatedEvent>>(from => from.UsingKey(@event => @event.<KeyB>));
+```
+
+Also reach for it for joins across several events, composite keys, initial
+values, and conditional setters the attributes do not express.
+
+## AutoMap default
+
+`ProjectionBuilderFor` is constructed with AutoMap enabled, and the model-bound
+builder sets it to enabled unless `[NoAutoMap]` is present on the read model.
+Children and nested builders are created with an inherit setting, so they follow
+the enclosing scope.

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

@@ -0,0 +1,118 @@
+# Model-bound projection attributes
+
+Verified against `Cratis.Chronicle` `16.45.2`.
+
+Unless noted, every attribute below lives in
+`Cratis.Chronicle.Projections.ModelBound`. Generic arity is stated exactly:
+`<T>` means one generic parameter naming the event type; "non-generic" means the
+attribute takes no generic parameter at all.
+
+## Namespaces that are not `Projections.ModelBound`
+
+| Attribute | Namespace |
+| --- | --- |
+| `[Key]` | `Cratis.Chronicle.Keys` |
+| `[Index]` | `Cratis.Chronicle.ReadModels` |
+| `[Passive]` | `Cratis.Chronicle.ReadModels` |
+| `[NoAutoMap]` | `Cratis.Chronicle.Projections` |
+| `[Projection]` | `Cratis.Chronicle.Projections` |
+| `[EventSequence]`, `[EventLog]` | `Cratis.Chronicle.EventSequences` |
+| `[EventStore]` | `Cratis.Chronicle.Events` |
+
+`[ReadModel]` and `[Path]` are **Arc** types in `Cratis.Arc.Queries.ModelBound`.
+
+## Source and shape
+
+| Attribute | Arity | Parameters | Targets |
+| --- | --- | --- | --- |
+| `[FromEvent<T>]` | `<T>` | `(string? key = default, string? parentKey = default)`, plus `ConstantKey { get; init; }` | class, struct; repeatable |
+| `[RemovedWith<T>]` | `<T>` | `(string? key = default, string? parentKey = default)` | class, struct, property, parameter; repeatable |
+| `[RemovedWithJoin<T>]` | `<T>` | `(string? key = default)` | property, parameter; repeatable |
+| `[Nested]` | non-generic | none | property, parameter; single |
+| `[FromAll]` | non-generic | `(string? contextProperty = default, string? property = default)` | **property only**; single |
+| `[FromEvery]` | non-generic | `(string? property = default, string? contextProperty = default)` | property, parameter; single |
+| `[NoAutoMap]` | non-generic | none | class, struct, property, parameter; inherited |
+| `[NotRewindable]` | non-generic | none | class, struct; single |
+| `[Passive]` | non-generic | none | class, struct; single |
+| `[Key]` | non-generic | none | property, parameter |
+| `[Index]` | non-generic | none | property, parameter |
+
+Note that `[FromAll]` and `[FromEvery]` take their two optional arguments in
+**opposite order**. Always pass them by name.
+
+## Setting values
+
+| Attribute | Arity | Parameters | Targets |
+| --- | --- | --- | --- |
+| `[SetFrom<T>]` | `<T>` | `(string? eventPropertyName = default)` | property, parameter; repeatable |
+| `[SetValue<T>]` | `<T>` | `(object? value)` — **required**; pass `null` to clear | property, parameter; repeatable |
+| `[SetFromContext<T>]` | `<T>` | `(string? contextPropertyName = default)` | property, parameter; repeatable |
+| `[AddFrom<T>]` | `<T>` | `(string? eventPropertyName = default)` | property, parameter; repeatable |
+| `[SubtractFrom<T>]` | `<T>` | `(string? eventPropertyName = default)` | property, parameter; repeatable |
+| `[ClearWith<T>]` | `<T>` | **none** | class, property, parameter; repeatable |
+
+## Counters
+
+| Attribute | Arity | Parameters | Targets |
+| --- | --- | --- | --- |
+| `[Count<T>]` | `<T>` | none; `ConstantKey { get; init; }` | property, parameter; repeatable |
+| `[Increment<T>]` | `<T>` | none; `ConstantKey { get; init; }` | property, parameter; repeatable |
+| `[Decrement<T>]` | `<T>` | none; `ConstantKey { get; init; }` | property, parameter; repeatable |
+
+`ConstantKey` is an **object-initializer property**, never a constructor
+argument:
+
+```csharp
+[Count<<EventName>>(ConstantKey = "<key>")]
+```
+
+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.
+
+## Relationships
+
+| Attribute | Arity | Parameters | Targets |
+| --- | --- | --- | --- |
+| `[ChildrenFrom<T>]` | `<T>` | `(string? key = default, string? identifiedBy = default, string? parentKey = default)` — three parameters, `identifiedBy` in the middle | property, parameter; repeatable |
+| `[Join<T>]` | `<T>` | `(string? on = default, string? eventPropertyName = default)` | property, parameter; repeatable |
+
+`[Join<T>]` joins on an **event**. Joining on a read model is not supported.
+
+## Source selection
+
+| Attribute | Parameters | Targets |
+| --- | --- | --- |
+| `[EventSequence("<name>")]` | `(string sequence)`; exposes `Sequence` | class |
+| `[EventLog]` | none; equivalent to `[EventSequence]` for the event log | class |
+| `[EventStore("<name>")]` | `(string eventStore)` | class, assembly; single |
+
+**`[FromEventSequence]` was removed and does not exist.** The fluent builder's
+`FromEventSequence(EventSequenceId)` method is unrelated and still present.
+
+## Labels, not filters
+
+| Attribute | Namespace | Parameters | Effect on a projection |
+| --- | --- | --- | --- |
+| `[Tag]` | `Cratis.Chronicle` | `(params string[] tags)`; repeatable | label only |
+| `[Tags]` | `Cratis.Chronicle` | `(params string[] tags)`; repeatable | label only |
+
+A projection's definition carries `Tags` but has **no filter field at all**.
+`[FilterEventsByTag]`, `[EventSourceType]`, and `[EventStreamType]` only filter
+for reducers and reactors.
+
+## What makes a type a model-bound projection
+
+Chronicle treats a type as a model-bound projection when the class, its primary
+constructor parameters, or its public instance properties carry an
+`[EventSequence]` attribute or any projection annotation — **except
+`[Passive]`**, which is deliberately excluded. `[Passive]` on its own therefore
+does not make a read model a projection; it changes how an existing projection
+is registered.
+
+## AutoMap
+
+AutoMap is enabled by default for both model-bound types and the fluent builder.
+`[NoAutoMap]` disables it, is inherited, and applies at class, struct, property,
+or parameter level. Child and nested builders inherit the enclosing setting.
+Call `.AutoMap()` only to re-enable inside a scope you disabled.

package/skills/cratis-chronicle-reactor/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.