@cratis/chronicle 6.17.0 → 6.19.0

package/projections/declarative/FromBuilder.ts

@@ -171,6 +171,14 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
     }
 
     /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+    ): this;
     addChild<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,
         eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
@@ -184,7 +192,7 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
 
         this.entry.children.push(probe.usedAsBuilder
-            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty, usingParentKey: probe.usingParentKeyProperty }
             : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
         return this;
     }

package/projections/declarative/IAddChildBuilder.ts

@@ -22,4 +22,18 @@ export interface IAddChildBuilder<TChildModel, TEvent> {
      * @returns This builder for fluent chaining.
      */
     usingKey(eventPropertyAccessor: PropertyAccessor<TEvent>): IAddChildBuilder<TChildModel, TEvent>;
+
+    /**
+     * Specifies an event context property used as the key when adding a child.
+     * @param contextPropertyName - Property path on EventContext, using TypeScript casing.
+     * @returns This builder for fluent chaining.
+     */
+    usingKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent>;
+
+    /**
+     * Specifies an event context property used as the parent key when adding a child.
+     * @param contextPropertyName - Property path on EventContext, using TypeScript casing.
+     * @returns This builder for fluent chaining.
+     */
+    usingParentKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent>;
 }

package/projections/declarative/IReadModelPropertiesBuilder.ts

@@ -107,7 +107,24 @@ export interface IReadModelPropertiesBuilder<TReadModel, TEvent, TBuilder> {
     count(readModelPropertyAccessor: PropertyAccessor<TReadModel>): TBuilder;
 
     /**
-     * Adds a child model from the event to a collection property on the read model.
+     * Adds a child model configured through a child builder to a collection on the read model.
+     * Event members remain available while TypeScript resolves the two function-shaped overloads.
+     * @param targetPropertyAccessor - Accessor for the collection property on the read model.
+     * @param builderCallback - Callback configuring the child identifier and keys.
+     * @returns This builder for fluent chaining.
+     */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): TBuilder;
+
+    /**
+     * Adds a child model directly from an event property to a collection on the read model.
+     * @param targetPropertyAccessor - Accessor for the collection property on the read model.
+     * @param eventPropertyAccessor - Accessor for the event property holding the child value.
+     * @returns This builder for fluent chaining.
+     */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): TBuilder;
+
+    /**
+     * Retains support for arbitrary read model accessors and explicitly selected child types.
      * @param targetPropertyAccessor - Accessor for the collection property on the read model.
      * @param eventPropertyAccessorOrBuilderCallback - Either a direct event property accessor or a builder callback.
      * @returns This builder for fluent chaining.

package/projections/declarative/JoinBuilder.ts

@@ -170,6 +170,14 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
     }
 
     /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+    ): this;
     addChild<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,
         eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
@@ -183,7 +191,7 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
         (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
 
         this.entry.children.push(probe.usedAsBuilder
-            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty, usingParentKey: probe.usingParentKeyProperty }
             : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
         return this;
     }

package/projections/declarative/ProjectionBuilderCore.ts

@@ -256,7 +256,7 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
                 Key: eventType,
                 Value: {
                     Key: child.usingKey ?? '$eventSourceId',
-                    ParentKey: '$eventSourceId',
+                    ParentKey: child.usingParentKey ?? '$eventSourceId',
                     Properties: {}
                 }
             });

package/projections/declarative/addChildCompatibility.standard.spec.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { FromBuilder } from './FromBuilder.js';
+import { IAddChildBuilder } from './IAddChildBuilder.js';
+import { IReadModelPropertiesBuilder } from './IReadModelPropertiesBuilder.js';
+import { JoinBuilder } from './JoinBuilder.js';
+import { ProjectionBuilderFor } from './ProjectionBuilderFor.js';
+
+class Line {
+    id = '';
+}
+
+class Base {
+    id = '';
+}
+
+class Derived extends Base {
+    derivedId = '';
+}
+
+class LineAdded {
+    line = new Line();
+}
+eventType()(LineAdded);
+
+class Order {
+    id = '';
+    lines: Line[] = [];
+    nullableLines: Line[] | null = null;
+    bases: Base[] = [];
+}
+
+// This checks the shared public interface independently of either concrete builder.
+function acceptOriginalCallSites(builder: IReadModelPropertiesBuilder<Order, LineAdded, unknown>): void {
+    builder.addChild<Line>(model => model.nullableLines, event => event.line);
+    builder.addChild(model => model.nullableLines, child => child.identifiedBy(item => item.id));
+    builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+    builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child
+        .identifiedBy(item => item.derivedId)
+        .usingKeyFromContext('sequenceNumber'));
+    builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+}
+
+describe('addChild source compatibility', () => {
+    it('should accept nullable targets and explicitly narrower child types on the shared interface', () => {
+        const builder: IReadModelPropertiesBuilder<Order, LineAdded, unknown> = new FromBuilder<Order, LineAdded>();
+        acceptOriginalCallSites(builder);
+    });
+
+    it('should accept the original call shapes on the concrete from builder', () => {
+        const builder = new FromBuilder<Order, LineAdded>();
+        builder.addChild<Line>(model => model.nullableLines, event => event.line);
+        builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child.identifiedBy(item => item.derivedId));
+        builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+        builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+        expect(builder.entry.children).toHaveLength(4);
+    });
+
+    it('should accept the original call shapes on the concrete join builder', () => {
+        const builder = new JoinBuilder<Order, LineAdded>();
+        builder.addChild<Line>(model => model.nullableLines, event => event.line);
+        builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child.identifiedBy(item => item.derivedId));
+        builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+        builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+        expect(builder.entry.children).toHaveLength(4);
+    });
+
+    it('should contextually type the unannotated builder callback in the documentation example', () => {
+        const projection = new ProjectionBuilderFor<Order>();
+        projection.from(LineAdded, from => from
+            .addChild(model => model.lines, child => child
+                .identifiedBy(item => item.id)
+                .usingKeyFromContext('sequenceNumber')
+                .usingParentKeyFromContext('eventSourceId')));
+        expect(projection.build('order', 'Order').Children).toHaveProperty('lines');
+    });
+});

package/projections/eventContextExpressions.spec.ts

@@ -182,6 +182,24 @@ describe('event context expressions', () => {
             .From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
     });
 
+    it('should use context properties as addChild keys in a from clause', () => {
+        const child = declarative(builder => builder.from(Recorded, from => from.addChild<Child>(model => model.children, added => added
+            .identifiedBy(model => model.happened)
+            .usingKeyFromContext('sequenceNumber')
+            .usingParentKeyFromContext('eventSourceId'))));
+        child.Children.children.From[0].Value.Key.should.equal('$eventContext(SequenceNumber)');
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
+    });
+
+    it('should use context properties as addChild keys in a join clause', () => {
+        const child = declarative(builder => builder.join(Recorded, join => join.on(model => model.occurred)
+            .addChild<Child>(model => model.children, added => added
+                .usingKeyFromContext('eventSourceId')
+                .usingParentKeyFromContext('sequenceNumber'))));
+        child.Children.children.From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(SequenceNumber)');
+    });
+
     it('should use a context property as a from parent key', () => {
         declarative(builder => builder.from(Recorded, from => from.usingParentKeyFromContext('eventSourceId')))
             .From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
@@ -255,6 +273,8 @@ describe('event context expressions', () => {
         const mappings = [
             (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.usingKeyFromContext('missingKey')),
             (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.usingParentKeyFromContext('missingParent')),
+            (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.addChild<Child>(model => model.children, child => child.usingKeyFromContext('missingChildKey'))),
+            (builder: ProjectionBuilderFor<Model>) => builder.join(Recorded, join => join.on(model => model.occurred).addChild<Child>(model => model.children, child => child.usingParentKeyFromContext('missingChildParent'))),
             (builder: ProjectionBuilderFor<Model>) => builder.join(Recorded, join => join.on(model => model.occurred).usingKeyFromContext('missingJoinKey')),
             (builder: ProjectionBuilderFor<Model>) => builder.removedWith(Removed, removed => removed.usingKeyFromContext('missingRemovalKey'))
         ];

package/projections/modelBound/childrenAndNestedBuilder.ts

@@ -48,6 +48,8 @@ export interface ChildrenDefinitionLike {
     NoAutoMapProperties: string[];
 }
 
+const aggregateExpressions = ['$count', '$increment', '$decrement', '$add', '$subtract'];
+
 /**
  * Resolves the contract event type for a decorated event constructor.
  * @param eventTypeConstructor - The event class constructor.
@@ -209,23 +211,20 @@ export function resolveNestedType(type: Function, property: string): Function |
 
 /**
  * Discovers the child model property used to identify instances, by convention: a property
- * named `id` (case-insensitive), matching the C# client's fallback once no `[Key]` attribute
- * is present (TypeScript has no `[Key]` decorator equivalent).
+ * named `id` (case-insensitive), or a property matching the event key when no id is found.
+ * TypeScript has no `[Key]` decorator equivalent.
  * @param childType - The child/nested model type, when resolvable.
+ * @param eventKey - The configured event key, when present.
  * @returns The discovered property name, or undefined when no convention match is found.
  */
-function discoverIdentifiedBy(childType: Function | undefined): string | undefined {
+function discoverIdentifiedBy(childType: Function | undefined, eventKey: string | undefined): string | undefined {
     if (!childType) {
         return undefined;
     }
 
-    for (const name of TypeIntrospector.getMembers(childType).keys()) {
-        if (name.toLowerCase() === 'id') {
-            return name;
-        }
-    }
-
-    return undefined;
+    const members = [...TypeIntrospector.getMembers(childType).keys()];
+    return members.find(name => name.toLowerCase() === 'id') ??
+        (eventKey !== undefined ? members.find(name => name.toLowerCase() === eventKey.toLowerCase()) : undefined);
 }
 
 /**
@@ -325,7 +324,7 @@ export function buildChildrenEntry(type: Function, property: string, metadataLis
     const definition = createEmptyChildrenDefinition(type, childType);
 
     const explicitIdentifiedBy = metadataList.find(metadata => metadata.identifiedBy)?.identifiedBy;
-    definition.IdentifiedBy = explicitIdentifiedBy ?? discoverIdentifiedBy(childType) ?? '$eventSourceId';
+    definition.IdentifiedBy = explicitIdentifiedBy ?? discoverIdentifiedBy(childType, metadataList[0]?.key) ?? '$eventSourceId';
 
     for (const metadata of metadataList) {
         const eventType = toContractEventType(metadata.eventType);
@@ -340,6 +339,41 @@ export function buildChildrenEntry(type: Function, property: string, metadataLis
     }
 
     populateFromType(definition, childType);
+
+    // For non-aggregate-only creating events, populate an unmapped child identifier from
+    // the creating event's key. IdentifiedBy selects the child property; it is not itself
+    // a property mapping. TypeScript has no [Key] decorator, so an explicit identifiedBy
+    // plays the same role as a discovered id for this default.
+    const identifier = definition.IdentifiedBy;
+    if (definition.AutoMap === AutoMap.Enabled && identifier !== '$eventSourceId') {
+        const prototype = childType?.prototype;
+        const hasExplicitMapping = prototype !== undefined && (
+            getSetFromMetadata(prototype, identifier).length > 0 ||
+            getSetFromContextMetadata(prototype, identifier).length > 0 ||
+            getSetValueMetadata(prototype, identifier).length > 0 ||
+            getAddFromMetadata(prototype, identifier).length > 0 ||
+            getSubtractFromMetadata(prototype, identifier).length > 0);
+        if (!hasExplicitMapping) {
+            for (const metadata of metadataList) {
+                const entry = definition.From.find(candidate => getEventTypeMapKey(candidate.Key) === getEventTypeMapKey(toContractEventType(metadata.eventType)))!;
+                const mappings = Object.values(entry.Value.Properties);
+                // Preserve the kernel's aggregate-only AutoMap exemption: Changeset.AddChild already
+                // initializes the child identifier from the resolved key before applying property mappers.
+                if (mappings.length > 0 && mappings.every(expression =>
+                    aggregateExpressions.some(aggregate => expression.startsWith(aggregate)))) {
+                    continue;
+                }
+                // Child property mappings may replace the creating key (for example, a constant-key count).
+                const key = entry.Value.Key;
+                // When an event property is also the identifier, AutoMap can fill it directly.
+                if (key.toLowerCase() !== identifier.toLowerCase() && !(identifier in entry.Value.Properties)) {
+                    entry.Value.Properties[identifier] = key === '$eventSourceId'
+                        ? eventContextPropertyExpression('eventSourceId')
+                        : key;
+                }
+            }
+        }
+    }
     return definition;
 }
 

package/testing/IReadModelProcessor.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReadModelState } from './ReadModelState.js';
+import type { ScenarioEvent } from './ScenarioEvent.js';
+
+/** Replays the complete serialized scenario history for independent event sources. */
+export interface IReadModelProcessor<TReadModel extends object> {
+    process(events: readonly ScenarioEvent[]): Promise<Map<string, ReadModelState<TReadModel>>>;
+}

package/testing/ReadModelScenario.spec.ts

@@ -2,18 +2,26 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { describe, expect, it } from 'vitest';
-import { ConceptAs, field } from '@cratis/fundamentals';
+import { ConceptAs, field, Guid } from '@cratis/fundamentals';
 import type { Constructor } from '@cratis/fundamentals';
+import { pii } from '../compliance/pii.js';
 import { eventType } from '../events/eventTypeDecorator.js';
 import type { EventContext } from '../events/EventContext.js';
 import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { setFrom } from '../projections/modelBound/setFrom.js';
+import { setFromContext } from '../projections/modelBound/setFromContext.js';
+import { removedWith } from '../projections/modelBound/removedWith.js';
+import type { IProjectionBuilderFor } from '../projections/declarative/IProjectionBuilderFor.js';
+import type { IProjectionFor } from '../projections/declarative/IProjectionFor.js';
 import { projection } from '../projections/declarative/projection.js';
 import { reducer } from '../reducers/reducer.js';
-import { ReadModelScenario, ReadModelScenarioGivenBuilder } from './index.js';
+import { readModel } from '../readModels/readModel.js';
+import { ReadModelScenario, ReadModelScenarioGivenBuilder, UnsupportedProjectionOperation } from './index.js';
 import { readModelScenarioExample } from './ReadModelScenario.example.js';
 
 class ItemAdded {
-    constructor(readonly amount: number) {}
+    @field(Number) amount: number;
+    constructor(amount: number) { this.amount = amount; }
 }
 eventType('scenario-item-added')(ItemAdded);
 class ItemRemoved {}
@@ -177,15 +185,153 @@ describe('ReadModelScenario', () => {
         await expect(scenario.instance).rejects.toThrow('FailingReducer');
     });
 
-    it('rejects model-bound and declarative projections rather than silently returning null', () => {
-        class ProjectedState {}
+    it('replays a compiled model-bound projection and recreates it after removal', async () => {
+        class ProjectedState {
+            @field(String) id = '';
+            @field(Number) count = 0;
+        }
         fromEvent(ItemAdded)(ProjectedState);
-        expect(() => new ReadModelScenario(ProjectedState, artifacts)).toThrow('not supported yet; use a kernel-backed test');
+        setFrom(ItemAdded, 'amount')(ProjectedState.prototype, 'count');
+        removedWith(ItemRemoved)(ProjectedState);
+        const scenario = new ReadModelScenario(ProjectedState, artifacts);
+        scenario.given.forEventSource('A').events(new ItemAdded(3), new ItemRemoved());
+        expect(await scenario.instanceForEventSourceId('A')).toBeNull();
+        expect(await scenario.wasDeletedForEventSourceId('A')).toBe(true);
+        scenario.given.forEventSource('A').events(new UnrelatedEvent(), new ItemAdded(7));
+        expect(await scenario.instance).toMatchObject({ count: 7 });
+        expect(await scenario.wasDeletedForEventSourceId('A')).toBe(false);
+    });
 
-        class FluentState {}
-        class FluentProjection {}
+    it('discovers a property-only model-bound read model without an artifact catalog', async () => {
+        class PropertyOnlyState { @field(String) id = ''; @field(Number) count = 0; }
+        setFrom(ItemAdded, 'amount')(PropertyOnlyState.prototype, 'count');
+        const scenario = new ReadModelScenario(PropertyOnlyState);
+        scenario.given.forEventSource('A').events(new ItemAdded(5));
+        expect(await scenario.instance).toMatchObject({ count: 5 });
+    });
+
+    it('defaults a projection Subject mapping to the event source when the seed has no subject', async () => {
+        class SubjectState { @field(String) id = ''; @field(String) subject = ''; }
+        fromEvent(ItemAdded)(SubjectState);
+        setFromContext(ItemAdded, 'subject')(SubjectState.prototype, 'subject');
+        const scenario = new ReadModelScenario(SubjectState, artifacts);
+        scenario.given.forEventSource('source-a').events(new ItemAdded(1));
+        expect(await scenario.instance).toMatchObject({ subject: 'source-a' });
+    });
+
+    it('defaults a projection Hash and CausedBy mapping to kernel sentinels when the seed omits them', async () => {
+        class ContextDefaults { @field(String) id = ''; @field(String) hash = ''; @field(String) causedByName = ''; }
+        setFromContext(ItemAdded, 'hash')(ContextDefaults.prototype, 'hash');
+        setFromContext(ItemAdded, 'causedBy.name')(ContextDefaults.prototype, 'causedByName');
+        const scenario = new ReadModelScenario(ContextDefaults, artifacts);
+        scenario.given.forEventSource('A').events(new ItemAdded(1));
+        expect(await scenario.instance).toMatchObject({ hash: '', causedByName: '[Not Set]' });
+    });
+
+    it('rejects a seeded generation different from the subscribed generation before mapping', async () => {
+        class LaterItemAdded { @field(Number) oldAmount = 42; }
+        eventType('scenario-item-added', 2)(LaterItemAdded);
+        class GenerationState { @field(String) id = ''; @field(Number) count = 0; }
+        fromEvent(ItemAdded)(GenerationState);
+        setFrom(ItemAdded, 'amount')(GenerationState.prototype, 'count');
+        const scenario = new ReadModelScenario(GenerationState, { ...artifacts, eventTypes: [...artifacts.eventTypes, LaterItemAdded] });
+        scenario.given.forEventSource('source-a').events(new LaterItemAdded());
+        await expect(scenario.instance).rejects.toThrow(UnsupportedProjectionOperation);
+        await expect(scenario.instance).rejects.toThrow(/GenerationState.*From\[scenario-item-added:1\].*seeded event generation 2/);
+    });
+
+    it('rejects a seeded generation different from a removal subscription', async () => {
+        class LaterItemRemoved {}
+        eventType('scenario-item-removed', 2)(LaterItemRemoved);
+        class GenerationState { @field(String) id = ''; @field(Number) count = 0; }
+        fromEvent(ItemAdded)(GenerationState);
+        removedWith(ItemRemoved)(GenerationState);
+        const scenario = new ReadModelScenario(GenerationState, { ...artifacts, eventTypes: [...artifacts.eventTypes, LaterItemRemoved] });
+        scenario.given.forEventSource('source-a').events(new LaterItemRemoved());
+        await expect(scenario.wasDeletedForEventSourceId('source-a')).rejects.toThrow(/RemovedWith\[scenario-item-removed:1\].*seeded event generation 2/);
+    });
+
+    it('selects a declarative projection using its final compiled contract', async () => {
+        class FluentState { @field(String) id = ''; @field(Number) count = 0; }
+        class FluentProjection implements IProjectionFor<FluentState> {
+            define(builder: IProjectionBuilderFor<FluentState>): void {
+                builder.from(ItemAdded, from => from.set(model => model.count).to(event => event.amount));
+            }
+        }
         projection('scenario-fluent-projection', FluentState)(FluentProjection);
-        expect(() => new ReadModelScenario(FluentState, { ...artifacts, projections: [FluentProjection] }))
-            .toThrow('not supported yet; use a kernel-backed test');
+        const scenario = new ReadModelScenario(FluentState, { ...artifacts, projections: [FluentProjection] });
+        scenario.given.forEventSource('A').events(new ItemAdded(8));
+        expect(await scenario.instance).toMatchObject({ count: 8 });
+    });
+
+    it('does not infer an unbound projection against an incomplete isolated read-model catalog', () => {
+        class AmbiguousState { @field(Number) count = 0; }
+        class AlsoMatching { @field(Number) count = 0; }
+        readModel()(AmbiguousState);
+        readModel()(AlsoMatching);
+        class UnboundProjection implements IProjectionFor<AmbiguousState> {
+            define(builder: IProjectionBuilderFor<AmbiguousState>): void {
+                builder.from(ItemAdded, from => from.set(model => model.count).to(event => event.amount));
+            }
+        }
+        projection('unbound-scenario-projection')(UnboundProjection);
+        expect(() => new ReadModelScenario(AmbiguousState, { ...artifacts, projections: [UnboundProjection] }))
+            .toThrow('No reducer or projection');
+        expect(() => new ReadModelScenario(AmbiguousState, {
+            ...artifacts, projections: [UnboundProjection], readModels: [AmbiguousState, AlsoMatching]
+        })).toThrow('found 0');
+    });
+
+    it('includes the read-model name and original error when projection replay fails', async () => {
+        class NumericState { @field(Guid) id!: Guid; }
+        fromEvent(ItemAdded)(NumericState);
+        const scenario = new ReadModelScenario(NumericState, artifacts);
+        scenario.given.forEventSource('01').events(new ItemAdded(1));
+        await expect(scenario.instance).rejects.toMatchObject({
+            message: expect.stringContaining('NumericState'),
+            cause: expect.objectContaining({ message: expect.stringContaining('Projection GUID value') })
+        });
+    });
+
+    it('rejects a protected identifier before any events are seeded', () => {
+        class ProtectedState { @field(String) id = ''; }
+        pii()(ProtectedState.prototype, 'id');
+        fromEvent(ItemAdded)(ProtectedState);
+        expect(() => new ReadModelScenario(ProtectedState, artifacts))
+            .toThrow(/ReadModel.Schema.id.*protected fields require a kernel-backed test/);
+    });
+
+    it('rejects unsupported mappings before replay even when no events are seeded', () => {
+        class CustomKeyState { @field(String) id = ''; @field(Number) count = 0; }
+        fromEvent(ItemAdded, { key: 'amount' })(CustomKeyState);
+        expect(() => new ReadModelScenario(CustomKeyState, artifacts)).toThrow('only $eventSourceId keys are supported');
+    });
+
+    it('rejects noncanonical GUID source IDs instead of merging independent histories', async () => {
+        class NumericState { @field(Guid) id!: Guid; }
+        fromEvent(ItemAdded)(NumericState);
+        const scenario = new ReadModelScenario(NumericState, artifacts);
+        scenario.given.forEventSource('01').events(new ItemAdded(1));
+        await expect(scenario.instance).rejects.toThrow('Projection GUID value');
+    });
+
+    it('keeps reducer precedence when a projection also applies', async () => {
+        class DualState { @field(Number) count = 0; }
+        class DualReducer { itemAdded(event: ItemAdded): DualState { return { count: event.amount }; } }
+        reducer('scenario-dual-reducer', undefined, DualState)(DualReducer);
+        fromEvent(ItemAdded)(DualState);
+        const scenario = new ReadModelScenario(DualState, { ...artifacts, reducers: [DualReducer] });
+        scenario.given.forEventSource('A').events(new ItemAdded(4));
+        expect(await scenario.instance).toEqual({ count: 4 });
+    });
+
+    it('rejects multiple applicable projections before replay', () => {
+        class FluentState { @field(Number) count = 0; }
+        class FirstProjection implements IProjectionFor<FluentState> { define(): void {} }
+        class SecondProjection implements IProjectionFor<FluentState> { define(): void {} }
+        projection('first-projection', FluentState)(FirstProjection);
+        projection('second-projection', FluentState)(SecondProjection);
+        expect(() => new ReadModelScenario(FluentState, { ...artifacts, projections: [FirstProjection, SecondProjection] }))
+            .toThrow('Multiple projections found');
     });
 });