@cratis/pi 7.30.0 → 7.31.0

package/package/corpus/skills/cratis-chronicle-client-dotnet/SKILL.md

@@ -204,6 +204,20 @@ from `string` (`:158`) and a `Redacted` form for logging (`:152`).
 
 Read [references/hosting.md](references/hosting.md) when wiring Chronicle into a worker or ASP.NET Core host, or when `AddCratisChronicle` or a namespace resolver does not resolve.
 
+## Pin event generations for delivery
+
+`ChronicleOptions.EventGenerationDelivery` defaults to `Compatibility`. Opt in
+with `EventGenerationDelivery.Pinned` (`Cratis.Chronicle.Observation`) **before
+connecting**. Reactors and reducers then receive their handler's CLR event
+generation (Chronicle **19.41.0+**); typed materialized projections use each
+clause's declared CLR event generation (**19.48.0+**). These additions are
+verified separately against those release tags, not the baseline above.
+
+Read [references/pinned-generation-delivery.md](references/pinned-generation-delivery.md)
+for compiling standalone/host configuration, registration constraints, and the
+Compatibility-only surfaces. For migration, PDL pin persistence, and integration
+test requirements, use **cratis-chronicle-event-type-migration**.
+
 ## The client and the server check each other
 
 The client runs the server-side compatibility check automatically inside `Connect()`; a genuine mismatch throws `IncompatibleServerException`, while a transport error is logged and ignored by design.

package/package/corpus/skills/cratis-chronicle-client-dotnet/references/pinned-generation-delivery.md

@@ -0,0 +1,92 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Pin event generations before connecting
+
+Requires Chronicle **19.41.0+** for client reactors/reducers and **19.48.0+** for
+typed materialized projections. Upgrade every kernel silo before enabling the
+option. `Compatibility` remains the default; adding a generation alone does not
+opt consumers in.
+
+## Standalone client
+
+This configuration excerpt uses `Cratis.Chronicle` **19.48.0** and a running
+local development kernel. Keep the client alive for observation; supply logging
+and a service provider when the application's observers need them (see the main
+skill's standalone checklist).
+
+```csharp
+using Cratis.Chronicle;
+using Cratis.Chronicle.Connections;
+using Cratis.Chronicle.Observation;
+
+var options = new ChronicleOptions(ChronicleConnectionString.Development)
+{
+    EventGenerationDelivery = EventGenerationDelivery.Pinned
+};
+using var client = new ChronicleClient(options);
+var eventStore = await client.GetEventStore("People");
+```
+
+## Host integration
+
+`AddCratisChronicle` extends `IHostApplicationBuilder` (an `IHostBuilder`
+overload also exists), **not** `IServiceCollection`. Its `ChronicleClientOptions` inherits the delivery option.
+This worker-host configuration excerpt uses `Cratis.Chronicle` **19.48.0** and
+`Microsoft.Extensions.Hosting`; add the application's hosted worker and start
+the host as usual.
+
+```csharp
+using Cratis.Chronicle.Observation;
+using Microsoft.Extensions.Hosting;
+
+var builder = Host.CreateApplicationBuilder();
+builder.AddCratisChronicle(options =>
+{
+    options.EventStore = "People";
+    options.EventGenerationDelivery = EventGenerationDelivery.Pinned;
+});
+```
+
+## Scope and registration
+
+- Reactors and reducers pin the generation of the handler's CLR event type.
+  Typed materialized projections (fluent, model-bound, or explicitly registered)
+  pin each clause's declared CLR event generation. Live, catch-up, and replay
+  (and, for reactors and reducers, partition retry) use kernel generation
+  selection and schema-guided release.
+- Projection pins cover `From`, `Join`, children, nested objects, removals,
+  event-content keys, and parent keys. Stored join/parent-event lookups select
+  and release through the same boundary as incoming events.
+- **One generation per event identifier per observer/projection**, across every
+  handler or clause, including children and nested objects. Different
+  identifiers may pin different generations. Client validation throws
+  `Cratis.Chronicle.Observation.MultipleGenerationsOfEventTypeInObserver` for
+  conflicting pins; the kernel rejects them with
+  `ObserverPinsMultipleGenerationsOfEventType`. Kernel observer subscription
+  rejects an unregistered generation with
+  `EventTypeGenerationNotRegisteredForObserver`; projection schema resolution
+  can reject an unavailable pin with `PinnedEventTypeGenerationUnavailable`.
+- Immediate/passive and wildcard (`all`/`FromAll`) projections stay
+  `Compatibility` when built through the .NET client. A definition explicitly
+  submitted as both wildcard and `Pinned` is unsupported and rejected by the
+  kernel with `EventGenerationDeliveryNotSupported`; the option does not make
+  wildcard pinning work.
+- Ad-hoc queries/event reads are not opted in. Neither are webhooks, captures,
+  or event-store subscriptions. Do not generalize this option to every read
+  path, or to unreleased generation-delivery work.
+
+For delivery-time migration, persisted PDL pins, and testing limits, read
+[the migration reference](../../cratis-chronicle-event-type-migration/references/pinned-generations.md).
+
+## Product sources
+
+Verified at `Cratis/Chronicle` **v19.48.0**:
+`Source/Clients/DotNET/ChronicleOptions.cs`,
+`Observation/EventGenerationDelivery.cs`,
+`ChronicleHostApplicationBuilderExtensions.cs`,
+`Projections/ProjectionGenerationDeliveryValidation.cs`, and
+`Source/Kernel/Core/Projections/Engine/ProjectionFactory.cs`.
+The option and reactor/reducer validation also exist at **v19.41.0**.
+
+See [Chronicle's pinned observer delivery documentation](https://github.com/Cratis/Chronicle/blob/v19.48.0/Documentation/concepts/event-type-migrations.mdx#opt-in-to-pinned-observer-delivery).

package/package/corpus/skills/cratis-chronicle-event-type-migration/SKILL.md

@@ -51,8 +51,9 @@ public sealed class EventTypeAttribute(string id = "", uint generation = 1) : At
 
 `id` defaults to the CLR type name and `generation` starts at `1`. The attribute
 is not repeatable, so two generations are always two distinct CLR types.
-Chronicle routes a stored event through the migration chain before delivering it
-to observers:
+Chronicle chains adjacent migrations to produce another generation. This is a
+possible upcast path, **not a promise that every observer receives the latest
+generation**; delivery policy is described below:
 
 ```text
 Generation 1 (stored) -> Migration 1->2 -> Migration 2->3 -> Current (Generation 3)
@@ -212,6 +213,23 @@ Migrations are discovered by convention — nothing is registered. They are
 activated through the service provider, so a migration may take constructor
 dependencies.
 
+## Choose the generation an observer receives
+
+`Compatibility` remains the default. With
+`ChronicleOptions.EventGenerationDelivery = EventGenerationDelivery.Pinned`,
+reactors and reducers receive the generation of their handler's CLR event type
+(verified at **19.41.0**). Typed materialized projection clauses receive the
+generation they declare (verified at **19.48.0**), including joins, children,
+removals, and event-content keys on live, catch-up, and replay.
+
+Read [references/pinned-generations.md](references/pinned-generations.md) for
+missing-generation migration, release and revision behavior, registration
+rejections, persisted PDL pins, and testing limits. Configure the opt-in through
+**cratis-chronicle-client-dotnet**; do not invent generation-qualified Screenplay
+syntax. `ReadModelScenario` and `ReactorScenario` do **not** emulate the kernel's
+pinned-generation migration and release; prove delivery with real-client
+integration, not a scenario-only assertion.
+
 ## Do not model absence with a nullable property
 
 **CHR0012** (warning) flags a nullable property on an `[EventType]` record.
@@ -246,3 +264,7 @@ is expected, since the prior generation records history rather than new intent.
   outstanding.
 - Old-generation events replay into the current shape through the read-model
   specifications for the affected observers.
+- With `EventGenerationDelivery.Pinned`, real-client integration also verifies
+  old-generation events on live delivery, catch-up, and replay into each
+  observer's pinned generation; in-process read-model/reactor scenarios alone
+  do not prove kernel migration and release.

package/package/corpus/skills/cratis-chronicle-event-type-migration/references/pinned-generations.md

@@ -0,0 +1,114 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Migrations and pinned delivery
+
+## Contents
+
+- What a pinned consumer receives
+- PDL pins are resolved once, when saved
+- Verify delivery through a real client
+- Product sources
+
+Verified against Chronicle **v19.48.0**. Reactor/reducer opt-in shipped in
+**19.41.0**; typed materialized projection opt-in shipped in **19.48.0**.
+Configure `ChronicleOptions.EventGenerationDelivery` before connecting; see
+[standalone and host examples](../../cratis-chronicle-client-dotnet/references/pinned-generation-delivery.md).
+
+## What a pinned consumer receives
+
+The kernel selects the pinned generation's content and hash, and releases
+protected values using **that generation's schema**. A reactor or reducer pins
+its handler's CLR event generation. A typed materialized projection uses the
+CLR generation each clause declares, including joins, children, nested objects,
+removals, event-content keys, and parent keys. Incoming live, catch-up, and replay
+events and stored join/parent-event lookups use the same release boundary.
+
+`EventContext.EventType.Generation` is the delivered generation;
+`EventContext.AppendedGeneration` is the original append generation, or null for
+legacy events where it is unknown. Do not infer the append generation from the
+handler type.
+
+If the pinned generation's content is missing from storage, Chronicle releases
+the known appended generation (or the highest stored generation for legacy
+events), then runs the adjacent `EventTypeMigration` upcast/downcast chain to the
+pin **for this delivery only**. It neither persists that result nor caches
+plaintext. The delivered hash is `EventHash.NotSet` because no durable hash
+exists for that migrated content. Erased PII stays erased through migration.
+An unavailable registered pin or an unreachable migration target fails with
+`PinnedEventTypeGenerationUnavailable`, rather than silently substituting a
+schema.
+
+Revised events use their **latest revision**, migrating it to the pin when
+needed. The revision's stored hash is retained only when its generation already
+matches the pin; otherwise the delivered hash is `EventHash.NotSet`. SQL
+revisions from before this release cannot be distinguished from original
+content and retain existing generation-selection behavior until revised again.
+
+Every observer/projection may pin **only one generation per event identifier**
+across all handlers/clauses, including children and nested objects. Different
+identifiers may pin different generations. See the client reference for the
+client and kernel registration exception names. Changing a reactor/reducer's
+pin or delivery mode does not itself trigger replay; request replay when prior
+state needs rebuilding.
+
+## PDL pins are resolved once, when saved
+
+For a PDL definition saved with `GenerationDelivery = Pinned`, a bare reference
+such as `from PersonRegistered` resolves to the **highest registered generation
+at registration time**. The definition persists that resolved pin. Join and
+removal references, including children and nested references, follow the same
+rule.
+
+Registering a later generation does **not** advance an existing saved pin.
+Re-saving the declaration resolves bare names again against the generations
+registered at that time. Keep this distinction when deploying migrations: a
+saved declaration is not a moving "latest" subscription.
+
+PDL is owned by Screenplay and has **no generation-qualified event reference
+syntax**. Never invent `PersonRegistered+2` or `Event+N`. When an explicit pin is
+needed, use .NET fluent or model-bound builders with that generation's CLR event
+type: for example, a `From<TEvent>` clause or `[FromEvent<TEvent>]` whose
+`TEvent` carries the intended `[EventType]` or `[EventTypeGenerationFor<T>]`.
+Do not mix two generations of the same identifier in different clauses.
+
+Compatibility PDL retains bare-name generation **1** and identifier-only
+dispatch. Immediate/passive and wildcard projections remain Compatibility;
+ad-hoc queries are not opted in by this change. Do not use their results as
+proof of pinned delivery.
+
+## Verify delivery through a real client
+
+`ReadModelScenario` and `ReactorScenario` do **not** emulate kernel pinned
+migration and protected-value release. The projection scenario preserves a
+seeded event's generation, but that is not the kernel selecting or migrating
+stored content. A scenario that feeds the desired CLR type only proves local
+handling/mapping for that type.
+
+Keep local decision/mapping specifications, and add **real-client integration**
+against a matching kernel to prove generation delivery:
+
+- Register both generations and their adjacent migration; use one pin per
+  identifier. Assert that conflicting pins are rejected.
+- Append another generation and assert delivered content and
+  `EventContext.EventType.Generation` on reactors/reducers, plus projected state
+  for typed materialized projections. Check `AppendedGeneration` separately.
+- Cover live delivery, catch-up, and replay; exercise contributing joins,
+  children, removals, and event-content/parent keys when the projection uses
+  them. Include missing stored generations and protected values when relevant.
+- For saved PDL, verify that adding a generation preserves the old pin and that
+  re-saving resolves the bare reference anew.
+
+Kernel specs provide product-level proof; in-process application scenarios are
+not a replacement for real-client integration of this option.
+
+## Product sources
+
+`Source/Kernel/Core/Events/EventGenerationRelease.cs` selects stored content,
+releases with the selected schema, and migrates missing/revised generations.
+`Source/Kernel/Core/Projections/ProjectionGenerationDeliveryValidation.cs`
+validates all clauses; `Engine/DefinitionLanguage/ProjectionEventTypeReference.cs`
+resolves PDL bare names. `Source/Clients/Testing/ReadModels/ProjectionReadModelProcessor.cs`
+and `Reactors/ReactorScenario.cs` define the scenario boundary.
+
+See [Chronicle's event type migration documentation](https://github.com/Cratis/Chronicle/blob/v19.48.0/Documentation/concepts/event-type-migrations.mdx#opt-in-to-pinned-observer-delivery).

package/package.json

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