@cratis/chronicle 6.18.0 → 6.20.0

package/testing/EventScenarioGiven.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventScenario } from './EventScenario.js';
+import { seedScenario } from './EventScenarioSeed.js';
+import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+/** Seeds exactly one event through the ordinary single-append pipeline. */
+export class EventScenarioGiven {
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string) {}
+    async events(...events: object[]): Promise<void> {
+        if (events.length !== 1) throw new UnsupportedEventSequenceOperation('given.events', this._id,
+            'Zero or multiple setup events are not supported in this increment; call events once per event.');
+        await seedScenario(this._scenario, this._id, events[0]);
+    }
+}

package/testing/EventScenarioGivenBuilder.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventScenario } from './EventScenario.js';
+import { EventScenarioGiven } from './EventScenarioGiven.js';
+
+/** Selects the source for setup events. */
+export class EventScenarioGivenBuilder {
+    constructor(private readonly _scenario: EventScenario) {}
+    forEventSource(id: string): EventScenarioGiven { return new EventScenarioGiven(this._scenario, id); }
+}

package/testing/EventScenarioOptions.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import type { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+
+/** Configuration captured once when constructing an event scenario. */
+export interface EventScenarioOptions {
+    /** An isolated catalog; omitting it discovers process-wide event and constraint artifacts. */
+    artifacts?: { eventTypes: Constructor[]; constraints?: Constructor[]; eventTypeMigrations?: Constructor[] };
+    /** Constraint discovery is the default. Explicitly disable it only for tests without constraints. */
+    constraints?: 'disabled';
+    /** Scenario-local identifiers; only the fixture-backed defaults are supported in this increment. */
+    eventStore?: string;
+    namespace?: string;
+    eventSequenceId?: EventSequenceId;
+    /** Deterministic sources for metadata otherwise provided by the environment. */
+    clock?: () => Date;
+    correlationId?: () => string;
+}

package/testing/EventScenarioSeed.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventScenario } from './EventScenario.js';
+
+const seeders = new WeakMap<EventScenario, (source: string, event: object) => Promise<void>>();
+
+/** Internal builder wiring; not exported by the testing package. */
+export function registerScenarioSeed(scenario: EventScenario, seed: (source: string, event: object) => Promise<void>): void {
+    seeders.set(scenario, seed);
+}
+
+export function seedScenario(scenario: EventScenario, source: string, event: object): Promise<void> {
+    const seed = seeders.get(scenario);
+    if (!seed) throw new Error('EventScenario setup requires a constructed scenario.');
+    return seed(source, event);
+}

package/testing/EventScenarioWhen.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { AppendResult } from '../eventSequences/AppendResult.js';
+import type { EventScenario } from './EventScenario.js';
+import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+/** A single act-phase append; the plural form is reserved for atomic batches. */
+export class EventScenarioWhen {
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string) {}
+    async event(event: object): Promise<AppendResult> { return this._scenario.append(this._id, event); }
+    async events(..._events: object[]): Promise<readonly AppendResult[]> {
+        throw new UnsupportedEventSequenceOperation('when.events/appendMany', this._id,
+            'Even a one-event plural action uses kernel batch semantics; batch fixtures are not included.');
+    }
+}

package/testing/EventScenarioWhenBuilder.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventScenario } from './EventScenario.js';
+import { EventScenarioWhen } from './EventScenarioWhen.js';
+
+/** Selects the source for an act-phase append. */
+export class EventScenarioWhenBuilder {
+    constructor(private readonly _scenario: EventScenario) {}
+    forEventSource(id: string): EventScenarioWhen { return new EventScenarioWhen(this._scenario, id); }
+}

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/InProcessEventSequence.ts

@@ -0,0 +1,275 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createHash } from 'node:crypto';
+import { EventObservationState } from '@cratis/chronicle.contracts';
+import type { Constructor } from '@cratis/fundamentals';
+import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getTagsFor } from '../events/tagDecorator.js';
+import type { AppendedEvent } from '../events/AppendedEvent.js';
+import { Tag } from '../events/Tag.js';
+import { EventType } from '../events/EventType.js';
+import { EventTypeId } from '../events/EventTypeId.js';
+import { EventTypeGeneration } from '../events/EventTypeGeneration.js';
+import { Identity } from '../identity/Identity.js';
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import type { AppendResult } from '../eventSequences/AppendResult.js';
+import type { AppendedEventWithResult } from '../eventSequences/AppendedEventWithResult.js';
+import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
+import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber.js';
+import type { IEventSequence } from '../eventSequences/IEventSequence.js';
+import type { ITransactionalEventSequence } from '../eventSequences/ITransactionalEventSequence.js';
+import type { CompleteStreamResult } from '../eventSequences/CompleteStreamResult.js';
+import { prepareSingleAppend } from '../eventSequences/prepareSingleAppend.js';
+import { toContractsGuid } from '../connection/Guid.js';
+import { getUniqueEventMetadata, getUniquePropertyMetadata } from '../events/constraints/unique.js';
+import { getRemovedConstraintNames } from '../events/constraints/removeConstraint.js';
+import type { EventScenarioOptions } from './EventScenarioOptions.js';
+import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+// JS trim() omits U+0085, which the kernel trims. Reject unproven non-ASCII whitespace and controls.
+const unprovenFilterCharacters = /[\u007f-\u009f]|(?=[^\x00-\x7f])\p{White_Space}/u;
+
+/** Fixture-backed, scenario-local single-append sequence; no kernel or observer scheduler is started. */
+export class InProcessEventSequence implements IEventSequence {
+    readonly id: EventSequenceId;
+    private readonly _catalog = new Map<Function, ReturnType<typeof getEventTypeMetadata>>();
+    private readonly _history: AppendedEvent[] = [];
+    private readonly _store: string;
+    private readonly _namespace: string;
+    private readonly _clock: () => Date;
+    private readonly _correlationId?: () => string;
+    private _setup = false;
+    private _allowSeedAppend = false;
+    private _busy = false;
+    private readonly _results: AppendResult[] = [];
+
+    constructor(options: EventScenarioOptions, eventTypes: Constructor[]) {
+        if (options.eventSequenceId && options.eventSequenceId.value !== EventSequenceId.eventLog.value) {
+            throw this.unsupported('options.eventSequenceId', options.eventSequenceId.value, 'Custom sequences are not fixture-backed.');
+        }
+        this.id = options.eventSequenceId ?? EventSequenceId.eventLog;
+        if (options.eventStore !== undefined && options.eventStore !== 'test-event-store') {
+            throw this.unsupported('options.eventStore', options.eventStore, 'Custom event stores are not fixture-backed.');
+        }
+        if (options.namespace !== undefined && options.namespace !== 'default') {
+            throw this.unsupported('options.namespace', options.namespace, 'Custom namespaces are not fixture-backed.');
+        }
+        this._store = options.eventStore ?? 'test-event-store';
+        this._namespace = options.namespace ?? 'default';
+        this._clock = options.clock ?? (() => new Date());
+        this._correlationId = options.correlationId;
+        const ids = new Set<string>();
+        for (const type of eventTypes) {
+            const metadata = getEventTypeMetadata(type);
+            if (!metadata) throw this.unsupported('artifacts.eventTypes', type.name, 'Event type has no @eventType metadata.');
+            const eventType = metadata.eventType;
+            if (!eventType.id.value.trim() || eventType.id.value !== eventType.id.value.trim() ||
+                unprovenFilterCharacters.test(eventType.id.value) || eventType.id.value.includes(',')) {
+                throw this.unsupported('artifacts.eventTypes.id', eventType.id.value, 'Comma-separated or padded event IDs have unproven filter behavior.');
+            }
+            if (ids.has(eventType.id.value)) throw this.unsupported('artifacts.eventTypes', type.name, 'Duplicate event ID or generation history.');
+            ids.add(eventType.id.value);
+            if (eventType.generation.value !== 1 || eventType.tombstone) {
+                throw this.unsupported('artifacts.eventTypes', type.name, 'Only generation 1, non-tombstone events are proven.');
+            }
+            if (options.constraints !== 'disabled' && (getUniqueEventMetadata(type) || getRemovedConstraintNames(type).length ||
+                [...metadata.members.keys()].some(key => getUniquePropertyMetadata(type, key)))) {
+                throw this.unsupported('artifacts.eventTypes.constraints', type.name, 'Constraint metadata is not supported in this increment.');
+            }
+            if (getTagsFor(type).length) throw this.unsupported('artifacts.eventTypes.tags', type.name, 'Tagged events are not fixture-backed.');
+            // Validate the complete schema, not only properties present on a particular event.
+            const schema = metadata.schema;
+            if (schema.type !== 'object' || schema.compliance?.length || schema.security?.length ||
+                schema.enum !== undefined || schema.items !== undefined || schema.format !== undefined ||
+                schema.additionalProperties !== false ||
+                schema.required?.length !== Object.keys(schema.properties ?? {}).length ||
+                !schema.properties || Object.keys(schema.properties).length === 0 ||
+                Object.entries(schema.properties).some(([key, property]) =>
+                    !/^[a-z][a-zA-Z0-9]*$/.test(key) || !['string', 'boolean'].includes(property.type ?? '') ||
+                    property.format !== undefined || property.compliance?.length || property.security?.length ||
+                    property.items !== undefined || property.properties !== undefined || property.enum !== undefined ||
+                    property.additionalProperties !== undefined)) {
+                throw this.unsupported('artifacts.eventTypes.schema', type.name, 'Only flat, unclassified string/boolean fields are fixture-backed.');
+            }
+            this._catalog.set(type, metadata);
+        }
+    }
+
+    get results(): readonly AppendResult[] { return Object.freeze([...this._results]); }
+    get appendedEvents(): readonly AppendedEvent[] { return Object.freeze(this._history.map(event => this.snapshot(event))); }
+
+    /** Seed through the same append path, without recording act-phase results. */
+    async seed(source: string, event: object): Promise<void> {
+        if (this._setup) throw this.unsupported('given.events', this.id.value, 'Overlapping setup calls are not fixture-backed.');
+        this._setup = true;
+        this._allowSeedAppend = true;
+        let pending: Promise<AppendResult>;
+        try { pending = this.append(source, event); }
+        finally { this._allowSeedAppend = false; }
+        try {
+            const result = await pending;
+            if (!result.isSuccess) throw new Error(`EventScenario given setup failed: ${JSON.stringify(result)}`);
+        } finally {
+            this._setup = false;
+        }
+    }
+
+    get transactional(): ITransactionalEventSequence { throw this.unsupported('transactional', this.id.value, 'Transactions require a kernel.'); }
+    get appendOperations(): AsyncIterable<AppendedEventWithResult[]> { throw this.unsupported('appendOperations', this.id.value, 'Append notifications are not fixture-backed.'); }
+
+    async append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult> {
+        if (this._busy || (this._setup && !this._allowSeedAppend)) {
+            throw this.unsupported('append', this.id.value, 'Overlapping calls do not have proven ordering.');
+        }
+        this._busy = true;
+        try {
+            if (!event || typeof event !== 'object') throw this.unsupported('append.event', this.id.value, 'Only registered event instances are supported.');
+            if (!/^[A-Za-z0-9_-]+$/.test(eventSourceId)) throw this.unsupported('append.source', eventSourceId, 'Only simple source identifiers are fixture-backed.');
+            if (options && (Reflect.ownKeys(options).length || options.correlationId !== undefined || options.sourceType !== undefined ||
+                options.streamType !== undefined || options.streamId !== undefined || options.subject !== undefined ||
+                options.occurred !== undefined || options.eventSourceId !== undefined || options.concurrencyScope !== undefined ||
+                options.tags !== undefined || options.concurrencyScopes !== undefined)) {
+                throw this.unsupported('append.options', event.constructor.name, 'Append metadata, routing and concurrency are not fixture-backed.');
+            }
+            const metadata = this._catalog.get(event.constructor);
+            if (!metadata) throw this.unsupported('append.event', event.constructor.name, 'Event is not in the selected, validated catalog.');
+            let prepared: ReturnType<typeof prepareSingleAppend>;
+            let content: Record<string, unknown>;
+            try {
+                prepared = prepareSingleAppend(event, this._correlationId ? { correlationId: this._correlationId() } : undefined);
+                content = JSON.parse(prepared.content) as Record<string, unknown>;
+            } catch (error) {
+                throw this.unsupported('append.serialization', event.constructor.name, `Payload or metadata could not be serialized: ${String(error)}.`);
+            }
+            try {
+                toContractsGuid(prepared.correlationId);
+                if (!/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(prepared.correlationId.toString())) throw new Error('Invalid correlation ID.');
+            } catch {
+                throw this.unsupported('append.correlationId', event.constructor.name, 'Correlation ID must be a valid GUID.');
+            }
+            if (prepared.identity !== Identity.system || prepared.causationChain.length !== 2 ||
+                Object.keys(prepared.causationChain[0].properties).length !== 0) {
+                throw this.unsupported('append.context', event.constructor.name, 'Ambient identity or causation metadata is not fixture-backed.');
+            }
+            const properties = metadata.schema.properties!;
+            if (!content || typeof content !== 'object' || Array.isArray(content) ||
+                Object.keys(content).length !== Object.keys(properties).length ||
+                Object.entries(properties).some(([key, property]) => typeof content[key] !== property.type ||
+                    (property.type === 'string' && !/^[\x20-\x21\x23-\x5b\x5d-\x7e\u00e9]*$/.test(content[key] as string)))) {
+                throw this.unsupported('append.content', event.constructor.name, 'Content differs from the flat scalar schema; null, missing and extra values are not proven.');
+            }
+            const occurred = this._clock();
+            // Date has millisecond precision; only the UTC year range representable by DateTimeOffset is supported.
+            if (!(occurred instanceof Date) || Number.isNaN(occurred.getTime()) ||
+                occurred.getUTCFullYear() < 1 || occurred.getUTCFullYear() > 9999) {
+                throw this.unsupported('append.clock', event.constructor.name, 'Clock must return a valid Date within UTC years 1–9999 (millisecond precision).');
+            }
+            const canonical = Object.fromEntries(Object.entries(content).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+            const hash = createHash('sha256').update(`${prepared.eventType.id.value}|${eventSourceId}|${JSON.stringify(canonical)}`).digest('base64');
+            const sequenceNumber = new EventSequenceNumber(BigInt(this._history.length));
+            const stored: AppendedEvent = {
+                eventType: prepared.eventType,
+                content,
+                context: {
+                    eventStore: this._store, namespace: this._namespace,
+                    sequenceNumber: sequenceNumber.value, eventSourceId,
+                    eventSourceType: 'Default', eventStreamType: 'All', eventStreamId: 'Default',
+                    subject: eventSourceId, hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
+                    eventType: prepared.eventType, occurred, correlationId: prepared.correlationId.toString(),
+                    causation: prepared.causationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
+                    tags: prepared.tags.map(tag => new Tag(tag))
+                }
+            };
+            this._history.push(this.snapshot(stored));
+            const result: AppendResult = Object.freeze({
+                sequenceNumber: Object.freeze(sequenceNumber), constraintViolations: Object.freeze([]), errors: Object.freeze([]), isSuccess: true,
+                waitForCompletion: async () => { throw this.unsupported('waitForCompletion', event.constructor.name, 'No observers run in process.'); }
+            });
+            if (!this._setup) this._results.push(result);
+            return result;
+        } finally {
+            // Keep the append in flight until its promise crosses an async boundary.
+            await Promise.resolve();
+            this._busy = false;
+        }
+    }
+
+    appendMany(_eventSourceId: string, _events: object[], _options?: AppendOptions): Promise<AppendResult[]>;
+    appendMany(_events: EventForEventSourceId[], _options?: AppendOptions): Promise<AppendResult[]>;
+    async appendMany(): Promise<AppendResult[]> {
+        throw this.unsupported('appendMany', this.id.value, 'Batch atomicity and result mapping require kernel fixtures.');
+    }
+
+    async getNextSequenceNumber(): Promise<EventSequenceNumber> { return new EventSequenceNumber(BigInt(this._history.length)); }
+
+    async getTailSequenceNumber(source?: string, sourceType?: string, streamType?: string, streamId?: string, types?: Constructor[]): Promise<EventSequenceNumber> {
+        if (sourceType !== undefined || streamType !== undefined || streamId !== undefined || types?.length) {
+            throw this.unsupported('getTailSequenceNumber.filters', this.id.value, 'Route and event-type tail filters are not fixture-backed.');
+        }
+        if (source !== undefined) this.validateReadSource('getTailSequenceNumber.source', source);
+        const last = source === undefined ? this._history.at(-1) : [...this._history].reverse().find(event => event.context.eventSourceId === source);
+        return last ? new EventSequenceNumber(last.context.sequenceNumber) : EventSequenceNumber.unset;
+    }
+
+    async getTailSequenceNumberForObserver(observer: Constructor): Promise<EventSequenceNumber> {
+        throw this.unsupported('getTailSequenceNumberForObserver', observer.name, 'Observer discovery is not fixture-backed.');
+    }
+
+    async hasEventsFor(source: string): Promise<boolean> {
+        this.validateReadSource('hasEventsFor.source', source);
+        return this._history.some(event => event.context.eventSourceId === source);
+    }
+
+    async getForEventSourceIdAndEventTypes(source: string, types: Constructor[], streamType?: string, streamId?: string, sourceType?: string): Promise<AppendedEvent[]> {
+        if (streamType !== undefined || streamId !== undefined || sourceType !== undefined || !types.length) {
+            throw this.unsupported('getForEventSourceIdAndEventTypes.filters', source, 'Only explicit event-type/source filtering is fixture-backed.');
+        }
+        this.validateReadSource('getForEventSourceIdAndEventTypes.source', source);
+        const ids = types.map(type => {
+            const metadata = this._catalog.get(type);
+            if (!metadata) throw this.unsupported('read.eventTypes', type.name, 'Event type is not in the selected catalog.');
+            return metadata.eventType.id.value;
+        });
+        return this._history.filter(event => event.context.eventSourceId === source && ids.includes(event.eventType.id.value)).map(event => this.snapshot(event));
+    }
+
+    async getFromSequenceNumber(sequence: EventSequenceNumber, source?: string, types?: Constructor[]): Promise<AppendedEvent[]> {
+        if (sequence.value < 0n || sequence.value > EventSequenceNumber.unset.value) {
+            throw this.unsupported('getFromSequenceNumber.sequenceNumber', sequence.value.toString(), 'Sequence numbers must fit unsigned 64-bit wire values.');
+        }
+        if (types?.length) throw this.unsupported('getFromSequenceNumber.filterEventTypes', this.id.value, 'Event-type filtering on sequence reads is not fixture-backed.');
+        if (source !== undefined) this.validateReadSource('getFromSequenceNumber.source', source);
+        return this._history.filter(event => event.context.sequenceNumber >= sequence.value &&
+            (source === undefined || event.context.eventSourceId === source)).map(event => this.snapshot(event));
+    }
+
+    async redact(): Promise<void> { throw this.unsupported('redact', this.id.value, 'Redaction requires kernel storage.'); }
+    async redactForEventSource(): Promise<void> { throw this.unsupported('redactForEventSource', this.id.value, 'Redaction requires kernel storage.'); }
+    async completeStream(): Promise<CompleteStreamResult> { throw this.unsupported('completeStream', this.id.value, 'Stream completion requires a kernel.'); }
+
+    private snapshot(event: AppendedEvent): AppendedEvent {
+        const eventType = new EventType(new EventTypeId(event.eventType.id.value),
+            new EventTypeGeneration(event.eventType.generation.value), event.eventType.tombstone);
+        const causedBy = event.context.causedBy;
+        return {
+            eventType,
+            content: JSON.parse(JSON.stringify(event.content)) as Record<string, unknown>,
+            context: { ...event.context, eventType, occurred: new Date(event.context.occurred),
+                causedBy: causedBy && new Identity(causedBy.subject, causedBy.name, causedBy.userName, causedBy.onBehalfOf),
+                causation: event.context.causation.map(item => ({ ...item, occurred: item.occurred && new Date(item.occurred), properties: { ...item.properties } })),
+                tags: event.context.tags.map(item => new Tag(item.value)) }
+        };
+    }
+
+    private validateReadSource(operation: string, source: string): void {
+        if (!source.trim() || source !== source.trim() || unprovenFilterCharacters.test(source)) {
+            throw this.unsupported(operation, source, 'Blank and padded source filters have unproven kernel normalization.');
+        }
+    }
+
+    private unsupported(operation: string, artifact: string, reason: string): UnsupportedEventSequenceOperation {
+        return new UnsupportedEventSequenceOperation(operation, artifact, reason);
+    }
+}

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');
     });
 });