@cratis/chronicle 6.36.0 → 6.38.0

package/testing/for_ReadModelScenario/when_evaluating_joins/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { join } from '../../../projections/modelBound/join.js';
+import { noAutoMap } from '../../../projections/modelBound/noAutoMap.js';
+import { removedWith } from '../../../projections/modelBound/removedWith.js';
+import { ReadModelScenario } from '../../ReadModelScenario.js';
+
+chai.should();
+
+@eventType('legacy-join-placed')
+class Placed {
+    @field(String) customerId: string;
+    constructor(customerId: string) { this.customerId = customerId; }
+}
+@eventType('legacy-join-named')
+class Named {
+    @field(String) name: string;
+    @field(String) city = 'Oslo';
+    @field(String) ignored = 'excluded';
+    constructor(name: string) { this.name = name; }
+}
+@eventType('legacy-join-removed')
+class Removed {}
+@fromEvent(Placed)
+@removedWith(Removed)
+class Order {
+    @field(String) id = '';
+    @field(String) customerId = '';
+    @field(String) @join(Named, 'customerId', 'name') customerName = '';
+    @field(String) name = '';
+    @field(String) city = '';
+    @field(String) @noAutoMap ignored = '';
+}
+const artifacts = { eventTypes: [Placed, Named, Removed], readModels: [Order], reducers: [], projections: [] };
+
+describe('when evaluating joins with legacy model-bound decorators', () => {
+    it('should backfill and automap joined values without mapping an explicitly consumed source twice', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('customer').events(new Named('before'));
+        scenario.given.forEventSource('A').events(new Placed('customer'));
+        const result = (await scenario.instance)!;
+        result.customerName.should.equal('before');
+        result.city.should.equal('Oslo');
+        (result.name === undefined).should.be.true;
+        (result.ignored === undefined).should.be.true;
+    });
+
+    it('should update existing roots and recreate a removed root from the latest joined history', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('A').events(new Placed('customer'));
+        scenario.given.forEventSource('B').events(new Placed('customer'));
+        scenario.given.forEventSource('customer').events(new Named('first'));
+        (await scenario.instanceForEventSourceId('A'))!.customerName.should.equal('first');
+        scenario.given.forEventSource('A').events(new Removed());
+        scenario.given.forEventSource('customer').events(new Named('second'));
+        (await scenario.wasDeletedForEventSourceId('A')).should.be.true;
+        (await scenario.instanceForEventSourceId('B'))!.customerName.should.equal('second');
+        scenario.given.forEventSource('A').events(new Placed('customer'));
+        (await scenario.instanceForEventSourceId('A'))!.customerName.should.equal('second');
+        (await scenario.wasDeletedForEventSourceId('A')).should.be.false;
+    });
+});

package/testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { join } from '../../../projections/modelBound/join.js';
+import { noAutoMap } from '../../../projections/modelBound/noAutoMap.js';
+import { ReadModelScenario } from '../../ReadModelScenario.js';
+import { UnsupportedProjectionOperation } from '../../projections/UnsupportedProjectionOperation.js';
+
+chai.should();
+
+@eventType('standard-join-placed')
+class Placed {
+    @field(String) customerId: string;
+    constructor(customerId: string) { this.customerId = customerId; }
+}
+@eventType('standard-join-named')
+class Named {
+    @field(String) name: string;
+    @field(String) city = 'Oslo';
+    @field(String) ignored = 'excluded';
+    constructor(name: string) { this.name = name; }
+}
+@fromEvent(Placed)
+class Order {
+    @field(String) id = '';
+    @field(String) customerId = '';
+    @field(String) @join(Named, 'customerId', 'name') customerName = '';
+    @field(String) name = '';
+    @field(String) city = '';
+    @field(String) @noAutoMap ignored = '';
+}
+const artifacts = { eventTypes: [Placed, Named], readModels: [Order], reducers: [], projections: [] };
+
+// joins-automap.json captures foreign-key AutoMap, consumed-source exclusion and join AutoMap.
+describe('when evaluating joins with standard model-bound decorators', () => {
+    it('should backfill through the automapped foreign key and avoid mapping an explicitly consumed source twice', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('customer').events(new Named('before'));
+        scenario.given.forEventSource('A').events(new Placed('customer'));
+        const result = (await scenario.instance)!;
+        result.customerName.should.equal('before');
+        result.city.should.equal('Oslo');
+        (result.name === undefined).should.be.true;
+        (result.ignored === undefined).should.be.true;
+    });
+
+    it('should fan out subsequent join events to all matching roots', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('A').events(new Placed('customer'));
+        scenario.given.forEventSource('B').events(new Placed('customer'));
+        scenario.given.forEventSource('customer').events(new Named('after'));
+        (await scenario.instanceForEventSourceId('A'))!.customerName.should.equal('after');
+        (await scenario.instanceForEventSourceId('B'))!.customerName.should.equal('after');
+    });
+
+    it('should reject an identifier join during scenario construction', () => {
+        @fromEvent(Placed)
+        class Unsupported {
+            @field(String) id = '';
+            @field(String) @join(Named, 'id', 'name') customerName = '';
+        }
+        (() => new ReadModelScenario(Unsupported, { ...artifacts, readModels: [Unsupported] })).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('Join[standard-join-named:1].On (@join)').and.includes('direct non-identifier');
+    });
+});

package/testing/projections/ProjectionCapabilities.ts

@@ -10,6 +10,7 @@ import { getEventTypeMapKey, type ChildrenDefinitionLike } from '../../projectio
 import type { JsonSchema } from '../../schemas/JsonSchema.js';
 import { ProjectionArithmetic } from './ProjectionArithmetic.js';
 import { ProjectionChildrenCapabilities } from './ProjectionChildrenCapabilities.js';
+import { ProjectionJoinsCapabilities } from './ProjectionJoinsCapabilities.js';
 import { UnsupportedProjectionOperation } from './UnsupportedProjectionOperation.js';
 
 /** Validates *all* subscribed operations against the bounded scenario subset, before replay. */
@@ -25,6 +26,7 @@ export class ProjectionCapabilities {
         const reject = (path: string, reason: string, fallback?: string) : never => {
             const source = compiled.provenance.get(definition)?.find(entry => entry.contractPath.startsWith('From['))?.declaration ?? '.from';
             const declaration = compiled.provenance.get(definition)?.find(entry => entry.contractPath === path)?.declaration
+                ?? compiled.provenance.get(definition)?.find(entry => entry.contractPath.startsWith('Join[') && path.startsWith(`${entry.contractPath}.`))?.declaration
                 ?? fallback ?? (path.includes('.AutoMap.') ? `${source} (AutoMap)`
                     : path.startsWith('InitialModelState') ? '.withInitialValues'
                         : path.startsWith('ReadModel') ? source : 'contract');
@@ -38,11 +40,11 @@ export class ProjectionCapabilities {
         if (wire.IsActive === false) reject('IsActive', 'passive projections require a kernel-backed test');
         if (wire.SubscribesToAllEvents === true) reject('SubscribesToAllEvents', 'subscribe-to-all projections require a kernel-backed test');
         if (wire.EventSequenceId !== EventSequenceId.eventLog.value) reject('EventSequenceId', 'non-default event sequences require a kernel-backed test');
-        for (const section of ['Join', 'Nested', 'RemovedWithJoin'] as const) {
+        for (const section of ['Nested', 'RemovedWithJoin'] as const) {
             const value = wire[section];
             const paths = Array.isArray(value) ? value.map((entry: { Key: ContractEventType }) => eventContractPath(section, entry.Key))
                 : Object.keys(value as Record<string, unknown> ?? {}).map(property => `${section}.${property}`);
-            if (paths.length) reject(paths[0], `${section === 'Nested' ? 'nested projections' : section === 'Join' ? 'joins' : 'removedWithJoin'} require a kernel-backed test`);
+            if (paths.length) reject(paths[0], `${section === 'Nested' ? 'nested projections' : 'removedWithJoin'} require a kernel-backed test`);
         }
         if ((wire.FromEvery as unknown[] | undefined)?.length) reject('FromEvery', 'derivative projections require a kernel-backed test');
         if (wire.FromEventProperty) reject('FromEventProperty', 'event-property subscriptions require a kernel-backed test');
@@ -89,6 +91,12 @@ export class ProjectionCapabilities {
             const event = catalog.get(getEventTypeMapKey(eventType)) ?? reject(path, 'participating event schema is unavailable');
             return event.schema;
         };
+        ProjectionJoinsCapabilities.validate(definition, {
+            schema: schema!, requireEventSchema, reject,
+            checkProtection: (eventSchema, path) => this.checkProtection(eventSchema, path, reject),
+            checkMapping: (modelSchema, eventSchema, destination, expression, path) =>
+                this.checkMapping(modelSchema, eventSchema, destination, expression, path, reject)
+        });
         const from = wire.From as FromRecord[] ?? [];
         const removedWith = wire.RemovedWith as RemovedWithRecord[] ?? [];
         for (const entry of from) {

package/testing/projections/ProjectionChildrenCapabilities.ts

@@ -49,7 +49,7 @@ export class ProjectionChildrenCapabilities {
             const declaration = context.declarationFor(base);
             const reject = (path: string, reason: string): never => context.reject(path, reason, declaration);
             const wire = child as unknown as Record<string, unknown>;
-            if ((child.Join ?? []).length) reject(`${base}.Join`, 'joins require a kernel-backed test');
+            if ((child.Join ?? []).length) reject(`${base}.Join`, 'joins inside children require a kernel-backed test');
             if (Object.keys(child.Children ?? {}).length) reject(`${base}.Children`, `nested children collections ${kernelBacked}`);
             if (Object.keys(child.Nested ?? {}).length) reject(`${base}.Nested`, `nested projections inside children ${kernelBacked}`);
             if ((child.RemovedWithJoin ?? []).length) reject(`${base}.RemovedWithJoin`, `removedWithJoin inside children ${kernelBacked}`);

package/testing/projections/ProjectionJoinRecord.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 { AutoMap } from '@cratis/chronicle.contracts';
+import type { JoinRecord } from '../../projections/declarative/ProjectionBuilderCore.js';
+
+/** A compiled join entry, including the contract's optional per-join AutoMap override. */
+export interface ProjectionJoinRecord extends JoinRecord {
+    Value: JoinRecord['Value'] & { AutoMap?: AutoMap };
+}

package/testing/projections/ProjectionJoinValidationContext.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ContractEventType } from '../../projections/declarative/ProjectionBuilderCore.js';
+import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import type { CheckMapping, RejectOperation } from './ProjectionChildrenCapabilities.js';
+
+/** Schema checks shared with the root projection capability validator. */
+export interface ProjectionJoinValidationContext {
+    readonly schema: JsonSchema;
+    readonly requireEventSchema: (eventType: ContractEventType, path: string) => JsonSchema;
+    readonly checkMapping: CheckMapping;
+    readonly checkProtection: (schema: JsonSchema, path: string) => void;
+    readonly reject: RejectOperation;
+}

package/testing/projections/ProjectionJoins.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AutoMap, type ProjectionDefinition } from '@cratis/chronicle.contracts';
+import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import type { ProjectionJoinRecord } from './ProjectionJoinRecord.js';
+
+/** The kernel's join AutoMap differs from From: explicitly consumed sources are not mapped again. */
+export class ProjectionJoins {
+    /** Builds the effective root join mappings, including inherited settings and exclusions. */
+    static properties(definition: ProjectionDefinition, eventSchema: JsonSchema, modelSchema: JsonSchema): Record<string, string> {
+        const join = (definition.Join[0] as ProjectionJoinRecord).Value;
+        const properties = { ...join.Properties };
+        const autoMap = (join.AutoMap ?? AutoMap.Inherit) === AutoMap.Inherit ? definition.AutoMap : join.AutoMap;
+        if (autoMap === AutoMap.Disabled) return properties;
+        const destinations = new Set(Object.keys(properties).map(name => name.toLowerCase()));
+        const sources = new Set(Object.values(properties).map(name => name.toLowerCase()));
+        const exclusions = new Set((definition.NoAutoMapProperties ?? []).map(name => name.toLowerCase()));
+        for (const source of Object.keys(eventSchema.properties ?? {})) {
+            if (destinations.has(source.toLowerCase()) || sources.has(source.toLowerCase())) continue;
+            const destination = Object.keys(modelSchema.properties ?? {}).find(name => name.toLowerCase() === source.toLowerCase());
+            if (destination && !exclusions.has(destination.toLowerCase())) {
+                properties[destination] = source;
+                destinations.add(destination.toLowerCase());
+                sources.add(source.toLowerCase());
+            }
+        }
+        return properties;
+    }
+}

package/testing/projections/ProjectionJoinsCapabilities.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AutoMap, type ProjectionDefinition } from '@cratis/chronicle.contracts';
+import { eventContractPath } from '../../projections/eventContractPath.js';
+import type { FromRecord, RemovedWithRecord } from '../../projections/declarative/ProjectionBuilderCore.js';
+import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import { ProjectionArithmetic } from './ProjectionArithmetic.js';
+import type { ProjectionJoinRecord } from './ProjectionJoinRecord.js';
+import type { ProjectionJoinValidationContext } from './ProjectionJoinValidationContext.js';
+import { ProjectionJoins } from './ProjectionJoins.js';
+
+/** The string-only, single root join proven by the joins-* packaged-kernel fixtures. */
+export class ProjectionJoinsCapabilities {
+    /** Rejects unproven join shapes before any history is replayed. */
+    static validate(definition: ProjectionDefinition, context: ProjectionJoinValidationContext): void {
+        const joins = definition.Join as ProjectionJoinRecord[] ?? [];
+        if (!joins.length) return;
+        const { schema, reject, requireEventSchema, checkMapping } = context;
+        const join = joins[0];
+        const path = eventContractPath('Join', join.Key);
+        if (joins.length !== 1) reject(path, 'multiple join subscriptions require a kernel-backed test');
+        if (Object.keys(definition.Children ?? {}).length) reject(path, 'root joins combined with children require a kernel-backed test');
+        const from = definition.From as FromRecord[] ?? [];
+        if ([...from, ...joins].some(entry => Object.values(entry.Value.Properties ?? {}).some(ProjectionArithmetic.isArithmetic))) {
+            reject(path, 'joins combined with arithmetic require a kernel-backed test');
+        }
+        if (Object.keys(JSON.parse(definition.InitialModelState || '{}') as object).length) {
+            reject('InitialModelState', 'joins with initial model state require a kernel-backed test');
+        }
+        if (join.Value.Key !== '$eventSourceId') reject(`${path}.Key`, 'join keys other than $eventSourceId require a kernel-backed test; the kernel ignores custom root join keys');
+        if (!join.Value.On || join.Value.On === 'id' || !/^[A-Za-z_]\w*$/.test(join.Value.On) || !schema.properties?.[join.Value.On]) {
+            reject(`${path}.On`, 'joins require a direct non-identifier read-model property; other join targets require a kernel-backed test');
+        }
+        for (const [property, member] of Object.entries(schema.properties ?? {})) {
+            if (!this.plainString(member)) reject(`ReadModel.Schema.${property}`, 'joins currently require plain string read-model properties; other schemas require a kernel-backed test');
+        }
+        if ([...from, ...(definition.RemovedWith as RemovedWithRecord[] ?? [])].some(entry => entry.Key.Id === join.Key.Id)) {
+            reject(path, 'events shared between Join and From or RemovedWith require a kernel-backed test');
+        }
+        const joinSchema = requireEventSchema(join.Key, path);
+        context.checkProtection(joinSchema, `${path}.EventSchema`);
+        if (![AutoMap.Inherit, AutoMap.Enabled, AutoMap.Disabled].includes(join.Value.AutoMap ?? AutoMap.Inherit)) {
+            reject(`${path}.AutoMap`, 'unknown join AutoMap settings require a kernel-backed test');
+        }
+        for (const [index, name] of Object.keys(joinSchema.properties ?? {}).entries()) {
+            if (Object.keys(joinSchema.properties ?? {}).slice(index + 1).some(other => other.toLowerCase() === name.toLowerCase())) {
+                reject(path, 'case-insensitively colliding join event properties require a kernel-backed test');
+            }
+        }
+        const mappings = ProjectionJoins.properties(definition, joinSchema, schema);
+        if (!Object.keys(mappings).length) reject(path, 'joins without effective property mappings require a kernel-backed test');
+        for (const [property, expression] of Object.entries(mappings)) {
+            const mappingPath = `${path}.${Object.hasOwn(join.Value.Properties ?? {}, property) ? 'Properties' : 'AutoMap'}.${property}`;
+            if (property === join.Value.On) reject(mappingPath, 'a join cannot map its own join target in scenarios; this requires a kernel-backed test');
+            this.checkStringMapping(joinSchema, expression, mappingPath, context);
+            checkMapping(schema, joinSchema, property, expression, mappingPath);
+        }
+        let hasJoinTarget = false;
+        for (const entry of from) {
+            const fromPath = eventContractPath('From', entry.Key);
+            const eventSchema = requireEventSchema(entry.Key, fromPath);
+            const properties = { ...entry.Value.Properties };
+            if (definition.AutoMap !== AutoMap.Disabled) {
+                for (const source of Object.keys(eventSchema.properties ?? {})) {
+                    const destination = Object.keys(schema.properties ?? {}).find(name => name.toLowerCase() === source.toLowerCase());
+                    if (destination && !Object.keys(properties).some(name => name.toLowerCase() === destination.toLowerCase()) &&
+                        !(definition.NoAutoMapProperties ?? []).some(name => name.toLowerCase() === destination.toLowerCase())) properties[destination] = source;
+                }
+            }
+            hasJoinTarget ||= Object.hasOwn(properties, join.Value.On);
+            for (const [property, expression] of Object.entries(properties)) {
+                const mappingPath = `${fromPath}.${Object.hasOwn(entry.Value.Properties ?? {}, property) ? 'Properties' : 'AutoMap'}.${property}`;
+                if (Object.hasOwn(mappings, property)) reject(mappingPath, 'From and Join mapping the same property requires a kernel-backed test');
+                this.checkStringMapping(eventSchema, expression, mappingPath, context);
+            }
+        }
+        if (!hasJoinTarget) reject(`${path}.On`, 'joins require a From mapping for the join target; join-only projections require a kernel-backed test');
+    }
+
+    private static checkStringMapping(eventSchema: JsonSchema, expression: string, path: string, context: ProjectionJoinValidationContext): void {
+        if (!/^[A-Za-z_]\w*$/.test(expression) || !this.plainString(eventSchema.properties?.[expression])) {
+            context.reject(path, 'joins support direct plain string event-property mappings only; context, constants and other expressions require a kernel-backed test');
+        }
+    }
+
+    private static plainString(schema: JsonSchema | undefined): boolean {
+        return schema?.type === 'string' && !schema.format;
+    }
+}

package/testing/projections/ProjectionReadModelProcessor.fixtures.spec.ts

@@ -38,6 +38,8 @@ const allFixtures = readdirSync(directory).filter(name => name.endsWith('.json')
     .map(name => ({ name, fixture: JSON.parse(readFileSync(new URL(name, directory), 'utf8')) as Fixture }));
 const fixtures = allFixtures.filter(({ fixture }) => fixture.kind === 'kernelSemantics');
 const guardErrors: Record<string, { type: string; message: string }> = {
+    'joins-custom-key.json': { type: 'UnsupportedProjectionOperation', message: 'join keys other than $eventSourceId' },
+    'joins-initial-state.json': { type: 'UnsupportedProjectionOperation', message: 'joins with initial model state' },
     'arithmetic-string-operand.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic operands must have number/double' },
     'arithmetic-nonnumeric-operand.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic operands must have number/double' },
     'arithmetic-uint32-overflow.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic targets must be number/double or integer/int32' },

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -15,6 +15,8 @@ import type { ScenarioEvent } from '../ScenarioEvent.js';
 import { ProjectionArithmetic } from './ProjectionArithmetic.js';
 import { ProjectionCapabilities } from './ProjectionCapabilities.js';
 import { ProjectionExpressionEvaluator } from './ProjectionExpressionEvaluator.js';
+import { ProjectionJoins } from './ProjectionJoins.js';
+import type { ProjectionJoinRecord } from './ProjectionJoinRecord.js';
 import { ProjectionValueConverter } from './ProjectionValueConverter.js';
 import { UnsupportedProjectionOperation } from './UnsupportedProjectionOperation.js';
 
@@ -32,6 +34,8 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
     private readonly _initial: Record<string, unknown>;
     private readonly _from: ReadonlyMap<string, FromRecord>;
     private readonly _removed: ReadonlySet<string>;
+    private readonly _join: ProjectionJoinRecord | undefined;
+    private readonly _joinProperties: Record<string, string>;
     private readonly _children: ReadonlyMap<string, ChildBinding>;
     private readonly _eventSchemas: ReadonlyMap<string, JsonSchema>;
     private readonly _bindings: ReadonlyMap<string, { generation: number; path: string; declaration: string }>;
@@ -52,6 +56,11 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
             const path = eventContractPath(section, entry.Key);
             return [entry.Key.Id, { generation: entry.Key.Generation, path, declaration: declarationFor(path) ?? 'contract' }] as const;
         });
+        this._join = _definition.Join?.[0] as ProjectionJoinRecord | undefined;
+        if (this._join) {
+            const path = eventContractPath('Join', this._join.Key);
+            bindings.push([this._join.Key.Id, { generation: this._join.Key.Generation, path, declaration: declarationFor(path) ?? 'contract' }]);
+        }
         const children = new Map<string, ChildBinding>();
         for (const [property, child] of Object.entries(wire.Children ?? {})) {
             const items = this._schema.properties![property].items!;
@@ -68,6 +77,7 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
         this._bindings = new Map(bindings);
         this._eventSchemas = new Map([...(compiled.eventSchemas.get(_definition) ?? new Map()).values()]
             .map(entry => [entry.eventType.Id, entry.schema]));
+        this._joinProperties = this._join ? ProjectionJoins.properties(_definition, this._eventSchemas.get(this._join.Key.Id)!, this._schema) : {};
     }
 
     /** A snapshot of the production-style in-memory sink, for kernel conformance fixtures. */
@@ -78,17 +88,34 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
     async process(events: readonly ScenarioEvent[]): Promise<Map<string, ReadModelState<TReadModel>>> {
         const states = new Map<string, ReadModelState<TReadModel>>();
         const engine: Record<string, Record<string, unknown>> = Object.create(null);
+        // Replay-local event-sequence lookup. Removal deletes a root, never its joined source history.
+        const joinedEvents = new Map<string, { event: ScenarioEvent; content: unknown }>();
         for (const event of events) {
             const typeId = event.context.eventType.id.value;
             const from = this._from.get(typeId);
             const removed = this._removed.has(typeId);
             const child = this._children.get(typeId);
-            if (!from && !removed && !child) continue;
+            const joining = this._join?.Key.Id === typeId;
+            if (!from && !removed && !child && !joining) continue;
             const binding = this._bindings.get(typeId)!;
             if (event.context.eventType.generation.value !== binding.generation) {
                 throw new UnsupportedProjectionOperation(String(this._definition.ReadModel), binding.path, binding.declaration,
                     `seeded event generation ${event.context.eventType.generation.value} differs from subscribed generation ${binding.generation}; multi-generation history requires a kernel-backed test`);
             }
+            if (joining) {
+                const content = ProjectionValueConverter.eventContent(event.content, this._eventSchemas.get(typeId)!);
+                joinedEvents.set(event.sourceId, { event, content });
+                // SetInitialState skips join events: changes are computed against an empty state.
+                // Consequently a missing/null string produces no change, even on a populated row.
+                const changes: Record<string, unknown> = Object.create(null);
+                this.apply(this._joinProperties, content, event, this._schema, changes);
+                for (const [key, state] of Object.entries(engine)) {
+                    if (state[this._join!.Value.On] !== event.sourceId) continue;
+                    Object.assign(state, changes);
+                    states.set(key, { instance: this.materialize(state), deleted: false });
+                }
+                continue;
+            }
             const key = this.keyFor(event.sourceId);
             if (removed) {
                 delete engine[key];
@@ -111,6 +138,12 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
                 const properties = this._definition.AutoMap !== AutoMap.Disabled && !ProjectionArithmetic.suppressesAutoMap(explicit)
                     ? this.withAutoMap(explicit, schema, this._schema, excluded) : explicit;
                 this.apply(properties, content, event, this._schema, state);
+                // ResolveJoin is wired only to From clauses that map the join target (including AutoMap).
+                if (this._join && Object.hasOwn(properties, this._join.Value.On)) {
+                    const onValue = state[this._join.Value.On];
+                    const joined = typeof onValue === 'string' ? joinedEvents.get(onValue) : undefined;
+                    if (joined) this.apply(this._joinProperties, joined.content, joined.event, this._schema, state);
+                }
             }
             if (child) this.applyChild(child, content, event, schema, state, binding);
             // InMemorySink.ApplyChanges always restores lowercase id after applying mappings.

package/testing/projections/for_ProjectionCapabilities/when_rejecting_unsupported_children_operations.spec.ts

@@ -73,7 +73,7 @@ describe('when rejecting unsupported children operations before any event is see
     });
 
     const cases: Array<{ name: string; change: (child: ChildrenDefinitionLike, wire: Wire) => void; path: string; reason: string }> = [
-        { name: 'a join inside children', change: child => { child.Join = [{}]; }, path: 'Children.labels.Join', reason: 'joins require a kernel-backed test' },
+        { name: 'a join inside children', change: child => { child.Join = [{}]; }, path: 'Children.labels.Join', reason: 'joins inside children require a kernel-backed test' },
         { name: 'nested children collections', change: child => { child.Children = { inner: child }; }, path: 'Children.labels.Children', reason: 'nested children collections' },
         { name: 'nested projections inside children', change: child => { child.Nested = { inner: child }; }, path: 'Children.labels.Nested', reason: 'nested projections inside children' },
         { name: 'removedWithJoin inside children', change: child => { child.RemovedWithJoin = [child.RemovedWithJoin[0] ?? { Key: child.From[0].Key, Value: { Key: '' } }]; }, path: 'Children.labels.RemovedWithJoin', reason: 'removedWithJoin inside children' },

package/testing/projections/for_ProjectionCapabilities/when_rejecting_unsupported_operations.spec.ts

@@ -30,7 +30,7 @@ chai.should();
 describe('when rejecting unsupported operations before any event is seeded', () => {
     const modelBound = [
         { name: 'nested', configure: (model: Function) => nested(model.prototype, 'name'), path: 'Nested.name (@nested)', reason: 'nested projections' },
-        { name: 'join', configure: (model: Function) => join(Removed, 'name')(model.prototype, 'name'), path: 'Join[capability-removed:1] (@join)', reason: 'joins' },
+        { name: 'join on identifier', configure: (model: Function) => join(Removed, 'id')(model.prototype, 'name'), path: 'Join[capability-removed:1].On (@join)', reason: 'direct non-identifier' },
         { name: 'removedWithJoin', configure: (model: Function) => removedWithJoin(Removed)(model), path: 'RemovedWithJoin[capability-removed:1] (@removedWithJoin)', reason: 'removedWithJoin' },
         { name: 'fromEvery', configure: (model: Function) => fromEvery('name')(model.prototype, 'name'), path: 'All (@fromEvery)', reason: 'fromEvery/all' },
         { name: 'fromAll', configure: (model: Function) => fromAll('name')(model.prototype, 'name'), path: 'All (@fromAll)', reason: 'fromEvery/all' },
@@ -74,7 +74,7 @@ describe('when rejecting unsupported operations before any event is seeded', ()
         { name: 'context parent key', define: builder => { builder.from(Changed, from => from.usingParentKeyFromContext('eventSourceId')); }, path: 'From[capability-changed:1].ParentKey (.from().usingParentKeyFromContext)' },
         { name: 'composite key', define: builder => { builder.from(Changed, from => from.usingCompositeKey<{ name: string }>(key => key.set(target => target.name, event => event.name))); }, path: 'From[capability-changed:1].Key (.from().usingCompositeKey)' },
         { name: 'parent key', define: builder => { builder.from(Changed, from => from.usingParentKey(event => event.name)); }, path: 'From[capability-changed:1].ParentKey (.from().usingParentKey)' },
-        { name: 'join', define: builder => { builder.from(Changed).join(Removed, join => join.on(model => model.id)); }, path: 'Join[capability-removed:1] (.join)' },
+        { name: 'join on identifier', define: builder => { builder.from(Changed).join(Removed, join => join.on(model => model.id)); }, path: 'Join[capability-removed:1].On (.join)' },
         { name: 'nested', define: builder => { builder.from(Changed).nested(model => model.details, child => child.clearWith(Removed)); }, path: 'Nested.details (.nested)' },
         { name: 'removedWithJoin', define: builder => { builder.from(Changed).removedWithJoin(Removed); }, path: 'RemovedWithJoin[capability-removed:1] (.removedWithJoin)' },
         { name: 'removal key', define: builder => { builder.from(Removed).removedWith(Changed, removal => removal.usingKey(event => event.name)); }, path: 'RemovedWith[capability-changed:1].Key (.removedWith)' },

package/testing/projections/for_ProjectionCapabilities/when_validating_joins.spec.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { AutoMap, ReadModelObserverType, type ProjectionDefinition } from '@cratis/chronicle.contracts';
+import { chai, describe, it } from 'vitest';
+import { EventType } from '../../../events/EventType.js';
+import type { EventContext } from '../../../events/EventContext.js';
+import { buildReadModelDefinition } from '../../../readModels/buildReadModelDefinition.js';
+import type { CompiledProjectionDefinitions } from '../../../projections/CompiledProjectionDefinitions.js';
+import type { JsonSchema } from '../../../schemas/JsonSchema.js';
+import { ProjectionReadModelProcessor } from '../ProjectionReadModelProcessor.js';
+import { UnsupportedProjectionOperation } from '../UnsupportedProjectionOperation.js';
+
+chai.should();
+declare global {
+    interface Object { should: Chai.Assertion; }
+}
+
+function fixture() {
+    return JSON.parse(readFileSync(new URL('../fixtures/joins-lifecycle.json', import.meta.url), 'utf8')) as {
+        wireDefinition: Omit<ProjectionDefinition, 'Join' | 'From' | 'RemovedWith' | 'All'> & {
+            All: NonNullable<ProjectionDefinition['All']>;
+            Join: { Key: NonNullable<ProjectionDefinition['Join'][number]['Key']>; Value: NonNullable<ProjectionDefinition['Join'][number]['Value']> }[];
+            From: { Key: NonNullable<ProjectionDefinition['From'][number]['Key']>; Value: NonNullable<ProjectionDefinition['From'][number]['Value']> }[];
+            RemovedWith: { Key: NonNullable<ProjectionDefinition['RemovedWith'][number]['Key']>; Value: NonNullable<ProjectionDefinition['RemovedWith'][number]['Value']> }[];
+        };
+        readModel: { schema: JsonSchema };
+        eventSchemas: { eventType: { Id: string; Generation: number }; schema: JsonSchema }[];
+    };
+}
+
+function create(value: ReturnType<typeof fixture>) {
+    const definition = value.wireDefinition;
+    const compiled: CompiledProjectionDefinitions = {
+        definitions: [definition],
+        readModels: [buildReadModelDefinition({ identifier: definition.ReadModel, schema: JSON.stringify(value.readModel.schema),
+            sinkTypeId: 'test', observerType: ReadModelObserverType.Projection, observerIdentifier: definition.Identifier })],
+        provenance: new Map([[definition, [{ contractPath: 'Join[CustomerNamed:1]', declaration: '.join' }]]]),
+        eventSchemas: new Map([[definition, new Map(value.eventSchemas.map(entry => [`${entry.eventType.Id}:${entry.eventType.Generation}:0`,
+            { eventType: { ...entry.eventType, Tombstone: false }, schema: entry.schema }]))]])
+    };
+    return new ProjectionReadModelProcessor(class Order {}, compiled, definition);
+}
+
+describe('when validating joins before replay', () => {
+    it('should accept the captured root join without replaying any events', () => {
+        (() => create(fixture())).should.not.throw();
+    });
+
+    for (const key of ['name', '$value(customer)', '$eventContext(EventSourceId)', '$context.eventSourceId', '']) {
+        it(`should reject the unproven join key ${key}`, () => {
+            const value = fixture();
+            value.wireDefinition.Join[0].Value.Key = key;
+            (() => create(value)).should.throw(UnsupportedProjectionOperation).with.property('message')
+                .that.includes('Join[CustomerNamed:1].Key (.join)').and.includes('join keys other than $eventSourceId');
+        });
+    }
+
+    const cases: { name: string; change: (value: ReturnType<typeof fixture>) => void; reason: string }[] = [
+        { name: 'empty joins', change: value => { value.wireDefinition.Join[0].Value.Properties = {}; }, reason: 'joins without effective property mappings' },
+        { name: 'unknown join AutoMap', change: value => { value.wireDefinition.Join[0].Value.AutoMap = 99 as AutoMap; }, reason: 'unknown join AutoMap settings' },
+        { name: 'unmapped protected join fields', change: value => { value.eventSchemas[1].schema.properties!.ignored.security = [{ metadataType: 'EncryptedSubject', details: '' }]; }, reason: 'protected fields' },
+        { name: 'multiple joins', change: value => value.wireDefinition.Join.push(structuredClone(value.wireDefinition.Join[0])), reason: 'multiple join subscriptions' },
+        { name: 'join-only projections', change: value => { value.wireDefinition.From = []; }, reason: 'joins require a From mapping' },
+        { name: 'initial values', change: value => { value.wireDefinition.InitialModelState = '{"title":"seed"}'; }, reason: 'joins with initial model state' },
+        { name: 'identifier joins', change: value => { value.wireDefinition.Join[0].Value.On = 'id'; }, reason: 'direct non-identifier' },
+        { name: 'nested joins', change: value => { value.wireDefinition.Join[0].Value.On = 'customer.id'; }, reason: 'direct non-identifier' },
+        { name: 'unknown join targets', change: value => { value.wireDefinition.Join[0].Value.On = 'missing'; }, reason: 'direct non-identifier' },
+        { name: 'GUID roots', change: value => { value.readModel.schema.properties!.id.format = 'guid'; }, reason: 'plain string read-model properties' },
+        { name: 'numeric targets', change: value => { value.readModel.schema.properties!.customerName = { type: 'number' }; }, reason: 'plain string read-model properties' },
+        { name: 'numeric sources', change: value => { value.eventSchemas[1].schema.properties!.name = { type: 'number' }; }, reason: 'direct plain string event-property mappings' },
+        { name: 'nullable targets', change: value => { value.readModel.schema.properties!.customerName.type = ['string', 'null'] as unknown as JsonSchema['type']; }, reason: 'plain string read-model properties' },
+        { name: 'case-colliding sources', change: value => { value.eventSchemas[1].schema.properties!.Name = { type: 'string' }; }, reason: 'colliding join event properties' },
+        { name: 'protected sources', change: value => { value.eventSchemas[1].schema.properties!.name.security = [{ metadataType: 'EncryptedSubject', details: '' }]; }, reason: 'protected fields' },
+        { name: 'overlapping From and Join events', change: value => { value.wireDefinition.Join[0].Key = value.wireDefinition.From[0].Key; }, reason: 'events shared between Join' },
+        { name: 'overlapping removal and Join events', change: value => { value.wireDefinition.Join[0].Key = value.wireDefinition.RemovedWith[0].Key; }, reason: 'events shared between Join' },
+        { name: 'overlapping target mappings', change: value => { value.wireDefinition.From[0].Value.Properties.customerName = 'title'; }, reason: 'From and Join mapping the same property' },
+        { name: 'overlapping AutoMap targets', change: value => { value.wireDefinition.AutoMap = AutoMap.Enabled; value.eventSchemas[0].schema.properties!.customerName = { type: 'string' }; }, reason: 'From and Join mapping the same property' },
+        { name: 'join target mutation', change: value => { value.wireDefinition.Join[0].Value.Properties.customerId = 'name'; }, reason: 'cannot map its own join target' },
+        { name: 'root arithmetic', change: value => { value.wireDefinition.From[0].Value.Properties.title = '$count'; }, reason: 'joins combined with arithmetic' },
+        { name: 'join arithmetic', change: value => { value.wireDefinition.Join[0].Value.Properties.customerName = '$add(amount)'; }, reason: 'joins combined with arithmetic' },
+        { name: 'removedWithJoin', change: value => { value.wireDefinition.RemovedWithJoin = [{ Key: value.wireDefinition.Join[0].Key, Value: { Key: '$eventSourceId' } }]; }, reason: 'removedWithJoin require' },
+        { name: 'children combined with joins', change: value => { value.wireDefinition.Children = { items: {} as ProjectionDefinition['Children'][string] }; }, reason: 'root joins combined with children' },
+        { name: 'fromEvery combined with joins', change: value => { value.wireDefinition.All.Properties.title = 'title'; }, reason: 'fromEvery/all' },
+        { name: 'constant root keys', change: value => { value.wireDefinition.From[0].Value.Key = '$value(all)'; }, reason: 'only $eventSourceId keys' },
+        { name: 'root parent keys', change: value => { value.wireDefinition.From[0].Value.ParentKey = 'title'; }, reason: 'parent keys require' }
+    ];
+    for (const testCase of cases) {
+        it(`should reject ${testCase.name} without history`, () => {
+            const value = fixture();
+            testCase.change(value);
+            (() => create(value)).should.throw(UnsupportedProjectionOperation).with.property('message').that.includes(testCase.reason);
+        });
+    }
+
+    it('should reject a seeded join event from another generation even before a root exists', async () => {
+        const processor = create(fixture());
+        await processor.process([{ sourceId: 'customer', content: { name: 'unsupported' }, context: {
+            eventType: EventType.parse('CustomerNamed+2'), sequenceNumber: 0n, eventSourceId: 'customer'
+        } as EventContext }]).then(
+            () => { throw new Error('Expected rejection'); },
+            error => {
+                (error as Error).should.be.instanceOf(UnsupportedProjectionOperation);
+                (error as Error).message.should.include('Join[CustomerNamed:1] (.join)').and.include('seeded event generation 2');
+            }
+        );
+    });
+
+    for (const expression of ['$eventSourceId', '$eventContext(Subject)', '$value(fixed)', '$null', 'nested.name', 'missing']) {
+        it(`should reject unproven join mapping ${expression}`, () => {
+            const value = fixture();
+            value.wireDefinition.Join[0].Value.Properties.customerName = expression;
+            (() => create(value)).should.throw(UnsupportedProjectionOperation).with.property('message')
+                .that.includes('Join[CustomerNamed:1].Properties.customerName (.join)').and.includes('direct plain string');
+        });
+    }
+});