@cratis/chronicle 6.37.0 → 6.39.0

package/testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,123 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field, Guid } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType, getEventTypeMetadata } from '../../../events/eventTypeDecorator.js';
+import { unique } from '../../../events/constraints/unique.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { setFrom } from '../../../projections/modelBound/setFrom.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { reducer } from '../../../reducers/reducer.js';
+import { fieldScenarioBehaviors } from './field_scenario_behaviors.fixture.js';
+
+class Identifier extends ConceptAs<Guid> { static readonly valueType = Guid; }
+class Amount extends ConceptAs<number> { static readonly valueType = Number; }
+class Occurred extends ConceptAs<Date> { static readonly valueType = Date; }
+
+const identifier = () => Guid.parse('abcdef01-abcd-abcd-abcd-abcdef012345');
+const occurred = () => new Date('2025-01-02T03:04:05.123Z');
+
+class Payload {
+    @field(Number) amount = 1.5;
+    @field(Guid) identifier = identifier();
+    @field(Date) occurred = occurred();
+}
+
+@eventType('FieldTypesRecorded')
+class FieldsRecorded {
+    @field(Number) amount = 1.5;
+    @field(Guid) identifier = identifier();
+    @field(Date) occurred = occurred();
+    @field(Amount) amountConcept = new Amount(1e-7);
+    @field(Identifier) identifierConcept = new Identifier(identifier());
+    @field(Occurred) occurredConcept = new Occurred(occurred());
+    @field(Payload) payload = new Payload();
+    @field(Object) arbitrary = { nested: { number: 9007199254740992 }, values: [true, 1.5] };
+}
+
+@reactor('FieldTypesReactor')
+class Echo {
+    fieldsRecorded(event: FieldsRecorded) { return Object.assign(new FieldsRecorded(), event); }
+}
+
+class StoredFields {}
+class StoreFields {
+    fieldsRecorded(event: FieldsRecorded) { return event; }
+}
+reducer('FieldTypesReducer', undefined, StoredFields)(StoreFields);
+
+@fromEvent(FieldsRecorded)
+class ScalarProjection {
+    @field(String) id = '';
+    @field(Number) amount = 0;
+    @field(Guid) identifier = Guid.empty;
+    @field(Date) occurred = new Date(0);
+}
+
+@fromEvent(FieldsRecorded)
+class ObjectProjection {
+    @field(String) id = '';
+    @field(Object) payload = {};
+}
+
+@fromEvent(FieldsRecorded)
+class HashProjection {
+    @field(String) id = '';
+    @field(String) @setFrom(FieldsRecorded, '$eventContext(Hash)') hash = '';
+}
+
+@eventType('OracleFieldGuid')
+class GuidClaimed {
+    @field(Guid) key = identifier();
+}
+@eventType('OracleFieldNumber')
+class NumberClaimed {
+    @field(Number) key = 1;
+}
+@eventType('OracleFieldDouble')
+class DoubleClaimed {
+    @field(Number) key = 1;
+}
+getEventTypeMetadata(DoubleClaimed)!.schema.properties!.key.format = 'double';
+@constraint('OracleFieldKey')
+class DoubleKey {
+    define(builder: IConstraintBuilder) { builder.unique(key => key.on(DoubleClaimed, event => event.key)); }
+}
+@constraint('OracleFieldKey')
+class GuidKey {
+    define(builder: IConstraintBuilder) { builder.unique(key => key.on(GuidClaimed, event => event.key)); }
+}
+@constraint('OracleFieldKey')
+class NumberKey {
+    define(builder: IConstraintBuilder) { builder.unique(key => key.on(NumberClaimed, event => event.key)); }
+}
+@eventType('ConceptGuidClaimed')
+class ConceptGuidClaimed {
+    @field(Identifier) @unique('ConceptGuidKey') key = new Identifier(identifier());
+}
+@eventType('ConceptNumberClaimed')
+class ConceptNumberClaimed {
+    @field(Amount) @unique('ConceptNumberKey') key = new Amount(42);
+}
+@eventType('DateClaimed')
+class DateClaimed {
+    @field(Date) @unique('DateKey') key = occurred();
+}
+@eventType('ConceptDateClaimed')
+class ConceptDateClaimed {
+    @field(Occurred) @unique('ConceptDateKey') key = new Occurred(occurred());
+}
+@eventType('ObjectClaimed')
+class ObjectClaimed {
+    @field(Object) @unique('ObjectKey') key = { amount: 1.5 };
+}
+
+describe('when appending field types with standard decorators', () => {
+    fieldScenarioBehaviors({ recorded: FieldsRecorded, reactor: Echo, model: StoredFields, reducer: StoreFields,
+        projection: ScalarProjection, objectProjection: ObjectProjection, hashProjection: HashProjection,
+        guid: GuidClaimed, number: NumberClaimed, guidConstraint: GuidKey, numberConstraint: NumberKey, guidConcept: ConceptGuidClaimed, numberConcept: ConceptNumberClaimed,
+        double: DoubleClaimed, doubleConstraint: DoubleKey, rejected: [DateClaimed, ConceptDateClaimed, ObjectClaimed] });
+});

package/testing/for_EventScenario/when_appending_field_types/with_unproven_schemas.legacy.spec.ts

@@ -0,0 +1,82 @@
+// 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, Guid } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { eventType, getEventTypeMetadata } from '../../../events/eventTypeDecorator.js';
+import { unique } from '../../../events/constraints/unique.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import type { JsonSchema } from '../../../schemas/JsonSchema.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+
+chai.should();
+
+for (const schema of [
+    { type: 'string', format: 'date' }, { type: 'string', format: 'date-time' },
+    { type: 'object' }, { type: 'integer', format: 'int64' }, { type: 'number', format: 'decimal' }
+] satisfies JsonSchema[]) {
+    describe(`when registering a ${schema.type}/${schema.format ?? 'unformatted'} constrained schema`, () => {
+        it('should reject the constraint without rejecting an unconstrained field', async () => {
+            class Recorded { @field(Object) @unique(`Unsupported${schema.type}${schema.format ?? ''}`) key: unknown = {}; }
+            eventType(`Unsupported${schema.type}${schema.format ?? ''}`)(Recorded);
+            getEventTypeMetadata(Recorded)!.schema.properties!.key = schema;
+            (() => new EventScenario({ artifacts: { eventTypes: [Recorded] } })).should.throw(UnsupportedEventSequenceOperation, 'artifacts.constraints');
+            const scenario = new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled' });
+            const event = new Recorded();
+            event.key = schema.type === 'string' ? '2025-01-02' : schema.type === 'object' ? { value: 42 } : 1.5;
+            if (schema.format === 'date-time') event.key = '2025-01-02T03:04:05.000Z';
+            if (schema.type === 'integer') event.key = 42;
+            (await scenario.append('A', event)).isSuccess.should.equal(true);
+        });
+    });
+}
+
+for (const mode of ['composite', 'scoped', 'ignoreCasing']) {
+    describe(`when registering a ${mode} Guid key without fixture evidence`, () => {
+        it('should reject instead of inheriting plain-string constraint support', () => {
+            class Recorded { @field(Guid) key = Guid.empty; @field(String) label = ''; }
+            eventType(`UnprovenGuid${mode}`)(Recorded);
+            class Definition {
+                define(builder: IConstraintBuilder) {
+                    if (mode === 'scoped') builder.perEventSourceType();
+                    builder.unique(key => {
+                        if (mode === 'composite') key.on(Recorded, event => event.key, event => event.label);
+                        else key.on(Recorded, event => event.key);
+                        if (mode === 'ignoreCasing') key.ignoreCasing();
+                    });
+                }
+            }
+            constraint(`UnprovenGuid${mode}`)(Definition);
+            (() => new EventScenario({ artifacts: { eventTypes: [Recorded], constraints: [Definition] } }))
+                .should.throw(UnsupportedEventSequenceOperation, 'artifacts.constraints');
+        });
+    });
+}
+
+for (const protection of ['compliance', 'security'] as const) {
+    describe(`when registering nested ${protection} metadata`, () => {
+        it('should reject before serializing an object payload', () => {
+            class Recorded { @field(Object) payload = {}; }
+            eventType(`Nested${protection}`)(Recorded);
+            getEventTypeMetadata(Recorded)!.schema.properties!.payload = {
+                type: 'object', properties: { nested: { type: 'string', [protection]: [{ metadataType: 'protected', details: '' }] } }
+            };
+            (() => new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled' }))
+                .should.throw(UnsupportedEventSequenceOperation, 'artifacts.eventTypes.schema');
+        });
+    });
+}
+
+describe('when registering a uuid constraint schema alias', () => {
+    it('should reject unproven constraint semantics but accept a valid unconstrained payload', async () => {
+        class Recorded { @field(Guid) @unique('UuidAlias') key: Guid | string = Guid.empty; }
+        eventType('UuidAlias')(Recorded);
+        getEventTypeMetadata(Recorded)!.schema.properties!.key.format = 'uuid';
+        (() => new EventScenario({ artifacts: { eventTypes: [Recorded] } }))
+            .should.throw(UnsupportedEventSequenceOperation, 'artifacts.constraints');
+        const scenario = new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled' });
+        (await scenario.append('A', new Recorded())).isSuccess.should.equal(true);
+    });
+});

package/testing/for_ReadModelScenario/when_evaluating_joins/with_a_fluent_projection.spec.ts

@@ -0,0 +1,111 @@
+// 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 type { IProjectionBuilderFor } from '../../../projections/declarative/IProjectionBuilderFor.js';
+import { projection } from '../../../projections/declarative/projection.js';
+import { EventScenario } from '../../EventScenario.js';
+import { ReadModelScenario } from '../../ReadModelScenario.js';
+
+chai.should();
+
+class OrderPlaced {
+    constructor(readonly customerId: string) {}
+}
+field(String)(OrderPlaced.prototype, 'customerId');
+eventType('fluent-join-order-placed')(OrderPlaced);
+class CustomerNamed {
+    constructor(readonly name: string) {}
+}
+field(String)(CustomerNamed.prototype, 'name');
+eventType('fluent-join-customer-named')(CustomerNamed);
+class OrderRemoved {}
+eventType('fluent-join-order-removed')(OrderRemoved);
+class Order {
+    id = '';
+    customerId = '';
+    customerName = '';
+}
+for (const property of ['id', 'customerId', 'customerName']) field(String)(Order.prototype, property);
+class OrderProjection {
+    define(builder: IProjectionBuilderFor<Order>): void {
+        builder.noAutoMap()
+            .from(OrderPlaced, from => from.set(model => model.customerId).to(event => event.customerId))
+            .join(CustomerNamed, join => join.on(model => model.customerId).set(model => model.customerName).to(event => event.name))
+            .removedWith(OrderRemoved);
+    }
+}
+projection('fluent-join-order', Order)(OrderProjection);
+const artifacts = { eventTypes: [OrderPlaced, CustomerNamed, OrderRemoved], projections: [OrderProjection], reducers: [] };
+
+// Every ordering/lifecycle below is also captured from the packaged engine in joins-lifecycle.json.
+describe('when evaluating a fluent root join', () => {
+    it('should store joined history without materializing a phantom row and backfill the latest prior event', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('customer').events(new CustomerNamed('first'), new CustomerNamed('latest'));
+        (await scenario.instance === null).should.be.true;
+        (await scenario.wasDeletedForEventSourceId('customer')).should.be.false;
+        scenario.given.forEventSource('A').events(new OrderPlaced('customer'));
+        (await scenario.instance)!.customerName.should.equal('latest');
+        (await scenario.instanceForEventSourceId('customer') === null).should.be.true;
+    });
+
+    it('should update every referencing root and leave other customers unchanged', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('A').events(new OrderPlaced('customer'));
+        scenario.given.forEventSource('B').events(new OrderPlaced('customer'));
+        scenario.given.forEventSource('C').events(new OrderPlaced('other'));
+        (await scenario.instanceForEventSourceId('A'))!.customerId.should.equal('customer');
+        scenario.given.forEventSource('customer').events(new CustomerNamed('name'));
+        (await scenario.instanceForEventSourceId('A'))!.customerName.should.equal('name');
+        (await scenario.instanceForEventSourceId('B'))!.customerName.should.equal('name');
+        ((await scenario.instanceForEventSourceId('C'))!.customerName === undefined).should.be.true;
+    });
+
+    it('should retain joined history across removal without resurrecting the removed root', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('A').events(new OrderPlaced('customer'), new OrderRemoved());
+        scenario.given.forEventSource('customer').events(new CustomerNamed('after removal'));
+        (await scenario.instance === null).should.be.true;
+        (await scenario.wasDeletedForEventSourceId('A')).should.be.true;
+        scenario.given.forEventSource('A').events(new OrderPlaced('customer'));
+        (await scenario.instance)!.customerName.should.equal('after removal');
+        (await scenario.wasDeletedForEventSourceId('A')).should.be.false;
+    });
+
+    it('should resolve a changed foreign key against its own latest history', async () => {
+        const scenario = new ReadModelScenario(Order, artifacts);
+        scenario.given.forEventSource('one').events(new CustomerNamed('first'));
+        scenario.given.forEventSource('two').events(new CustomerNamed('second'));
+        scenario.given.forEventSource('A').events(new OrderPlaced('one'));
+        (await scenario.instance)!.customerName.should.equal('first');
+        scenario.given.forEventSource('A').events(new OrderPlaced('two'));
+        scenario.given.forEventSource('one').events(new CustomerNamed('no longer joined'));
+        (await scenario.instance)!.customerName.should.equal('second');
+    });
+
+    it('should rebuild join history per replay and never share it across scenarios', async () => {
+        const first = new ReadModelScenario(Order, artifacts);
+        first.given.forEventSource('customer').events(new CustomerNamed('first'));
+        first.given.forEventSource('A').events(new OrderPlaced('customer'));
+        (await first.instance)!.customerName.should.equal('first');
+        first.given.forEventSource('customer').events(new CustomerNamed('second'));
+        (await first.instance)!.customerName.should.equal('second');
+        const second = new ReadModelScenario(Order, artifacts);
+        second.given.forEventSource('A').events(new OrderPlaced('customer'));
+        ((await second.instance)!.customerName === undefined).should.be.true;
+    });
+
+    it('should update the root keys when observing a committed event sequence', async () => {
+        const events = new EventScenario({ artifacts: { eventTypes: [OrderPlaced, CustomerNamed] }, constraints: 'disabled' });
+        const scenario = new ReadModelScenario(Order, artifacts).observe(events);
+        await events.append('A', new OrderPlaced('customer'));
+        await events.append('B', new OrderPlaced('customer'));
+        await events.append('customer', new CustomerNamed('joined'));
+        (await scenario.instanceForEventSourceId('A'))!.customerName.should.equal('joined');
+        (await scenario.instanceForEventSourceId('B'))!.customerName.should.equal('joined');
+        (await scenario.instanceForEventSourceId('customer') === null).should.be.true;
+    });
+});

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;
+    }
+}