@cratis/chronicle 6.16.1 → 6.18.0

package/testing/projections/for_ProjectionCapabilities/when_compiling_capability_evidence.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 { chai, describe, it } from 'vitest';
+import { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
+import { entersOn } from '../../../projections/modelBound/entersOn.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { variantOf } from '../../../projections/modelBound/variantOf.js';
+import { getEventTypeJsonSchemaFor } from '../../../events/eventTypeDecorator.js';
+import { ProjectionDefinitionCompiler } from '../../../projections/ProjectionDefinitionCompiler.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { Changed } from './given/Changed.js';
+import { Removed } from './given/Removed.js';
+import { Model } from './given/Model.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+
+chai.should();
+
+describe('when compiling capability evidence', () => {
+    it('should retain model-bound variant declarations before joins and sibling removal obscure them', () => {
+        class Identity {}
+        class First extends Model {}
+        class Second extends Model {}
+        fromEvent(Changed)(First);
+        fromEvent(Removed)(Second);
+        variantOf(Identity, 'id')(First);
+        variantOf(Identity, 'id')(Second);
+        entersOn(Changed)(First);
+        entersOn(Removed)(Second);
+        const artifacts: IClientArtifactsProvider = {
+            readModels: [First, Second], projections: [], eventTypes: [Changed, Removed], globalForHandlers: [],
+            reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+        };
+        const compiled = new ProjectionDefinitionCompiler(artifacts, 'test-sink').compile([], [First, Second]);
+        const first = compiled.definitions[0];
+        compiled.provenance.get(first)!.should.deep.include({ contractPath: 'Variant', declaration: '@variantOf' });
+        compiled.provenance.get(first)!.should.deep.include({ contractPath: 'EntersOn[capability-changed:1]', declaration: '@entersOn' });
+        compiled.eventSchemas.get(first)!.has('capability-removed:1:0').should.be.true;
+        (first.RemovedWith?.length ?? 0).should.equal(1);
+    });
+
+    it('should retain declarative variant provenance before update-only joins replace From', () => {
+        class Identity {}
+        const { compiled, definition } = compileDeclarative(builder => builder
+            .variantOf(Identity, model => model.id).entersOn(Changed).from(Changed).from(Removed));
+        compiled.provenance.get(definition)!.should.deep.include({ contractPath: 'Variant', declaration: '.variantOf' });
+        compiled.provenance.get(definition)!.should.deep.include({ contractPath: 'From[capability-removed:1]', declaration: '.from' });
+        (definition.Join?.length ?? 0).should.equal(1);
+        compiled.eventSchemas.get(definition)!.has('capability-removed:1:0').should.be.true;
+    });
+
+    it('should catalog child events even though no root From entry refers to them', () => {
+        const { compiled, definition } = compileModelBound(model => childrenFrom(Removed)(model.prototype, 'name'));
+        compiled.eventSchemas.get(definition)!.has('capability-removed:1:0').should.be.true;
+        compiled.provenance.get(definition)!.should.deep.include({ contractPath: 'Children.name', declaration: '@childrenFrom' });
+    });
+
+    it('should isolate event schemas from later compiles and registration metadata', () => {
+        const first = compileModelBound();
+        const second = compileModelBound();
+        const firstSchema = first.compiled.eventSchemas.get(first.definition)!.get('capability-changed:1:0')!.schema;
+        const secondSchema = second.compiled.eventSchemas.get(second.definition)!.get('capability-changed:1:0')!.schema;
+        firstSchema.properties!.name.type = 'boolean';
+        secondSchema.properties!.name.type.should.equal('string');
+        getEventTypeJsonSchemaFor(Changed).properties!.name.type.should.equal('string');
+    });
+});

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

@@ -0,0 +1,230 @@
+// 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 type { IProjectionBuilderFor } from '../../../projections/declarative/IProjectionBuilderFor.js';
+import { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
+import { entersOn } from '../../../projections/modelBound/entersOn.js';
+import { eventSequence } from '../../../projections/modelBound/eventSequence.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { fromAll } from '../../../projections/modelBound/fromAll.js';
+import { fromEvery } from '../../../projections/modelBound/fromEvery.js';
+import { join } from '../../../projections/modelBound/join.js';
+import { nested } from '../../../projections/modelBound/nested.js';
+import { addFrom } from '../../../projections/modelBound/addFrom.js';
+import { passive } from '../../../projections/modelBound/passive.js';
+import { removedWithJoin } from '../../../projections/modelBound/removedWithJoin.js';
+import { removedWith } from '../../../projections/modelBound/removedWith.js';
+import { variantOf } from '../../../projections/modelBound/variantOf.js';
+import { ProjectionCapabilities } from '../ProjectionCapabilities.js';
+import { UnsupportedProjectionOperation } from '../UnsupportedProjectionOperation.js';
+import { Changed } from './given/Changed.js';
+import { Removed } from './given/Removed.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+import { Model } from './given/Model.js';
+
+chai.should();
+
+describe('when rejecting unsupported operations before any event is seeded', () => {
+    const modelBound = [
+        { name: 'children', configure: (model: Function) => childrenFrom(Removed)(model.prototype, 'name'), path: 'Children.name (@childrenFrom)', reason: 'children projections' },
+        { 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: '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' },
+        { name: 'passive', configure: (model: Function) => passive(model), path: 'IsActive (@passive)', reason: 'passive projections' },
+        { name: 'event sequence', configure: (model: Function) => eventSequence('custom')(model), path: 'EventSequenceId (@eventSequence)', reason: 'non-default event sequences' },
+        { name: 'custom key', configure: (model: Function) => fromEvent(Removed, { key: 'name' })(model), path: 'From[capability-removed:1].Key (@fromEvent)', reason: 'only $eventSourceId' },
+        { name: 'constant key', configure: (model: Function) => fromEvent(Removed, { constantKey: 'fixed' })(model), path: 'From[capability-removed:1].Key (@fromEvent)', reason: 'only $eventSourceId' },
+        { name: 'parent key', configure: (model: Function) => fromEvent(Removed, { parentKey: 'name' })(model), path: 'From[capability-removed:1].ParentKey (@fromEvent)', reason: 'parent keys' },
+        { name: 'removal key', configure: (model: Function) => removedWith(Removed, 'name')(model), path: 'RemovedWith[capability-removed:1].Key (@removedWith)', reason: 'only $eventSourceId' },
+        { name: 'removal parent key', configure: (model: Function) => removedWith(Removed, undefined, 'parent')(model), path: 'RemovedWith[capability-removed:1].ParentKey (@removedWith)', reason: 'parent keys' }
+    ];
+    for (const testCase of modelBound) {
+        it(`should reject model-bound ${testCase.name} with declaration and path`, () => {
+            const { compiled, definition } = compileModelBound(testCase.configure);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(testCase.path).and.includes(testCase.reason);
+        });
+    }
+
+    it('should reject model-bound variants even before cross-wired removal is visible', () => {
+        class Identity {}
+        const { compiled, definition } = compileModelBound(model => {
+            variantOf(Identity, 'id')(model);
+            entersOn(Changed)(model);
+        });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation,
+            'Candidate, Variant (@variantOf): variants require a kernel-backed test');
+    });
+
+    it('should reject declarative variants with their original declaration', () => {
+        class Identity {}
+        const { compiled, definition } = compileDeclarative(builder => builder.variantOf(Identity, model => model.id).entersOn(Changed).from(Changed));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation,
+            'Candidate, Variant (.variantOf): variants require a kernel-backed test');
+    });
+
+    const declarative: Array<{ name: string; define: (builder: IProjectionBuilderFor<Model>) => void; path: string }> = [
+        { name: 'custom key', define: builder => { builder.from(Changed, from => from.usingKey(event => event.name)); }, path: 'From[capability-changed:1].Key (.from().usingKey)' },
+        { name: 'constant key', define: builder => { builder.from(Changed, from => from.usingConstantKey('fixed')); }, path: 'From[capability-changed:1].Key (.from().usingConstantKey)' },
+        { name: 'context key', define: builder => { builder.from(Changed, from => from.usingKeyFromContext('eventSourceId')); }, path: 'From[capability-changed:1].Key (.from().usingKeyFromContext)' },
+        { 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: 'children', define: builder => { builder.from(Changed).children(model => model.labels, child => child.from(Removed)); }, path: 'Children.labels (.children)' },
+        { 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(Changed).removedWith(Changed, removal => removal.usingKey(event => event.name)); }, path: 'RemovedWith[capability-changed:1].Key (.removedWith)' },
+        { name: 'fromEvery', define: builder => { builder.from(Changed).fromEvery(all => all.set(model => model.name).toEventSourceId()); }, path: 'All (.fromEvery)' },
+        { name: 'empty fromEvery', define: builder => { builder.from(Changed).fromEvery(all => all.excludeChildProjections()); }, path: 'All (.fromEvery)' },
+        { name: 'passive', define: builder => { builder.from(Changed).passive(); }, path: 'IsActive (.passive)' },
+        { name: 'event sequence', define: builder => { builder.from(Changed).fromEventSequence('custom'); }, path: 'EventSequenceId (.fromEventSequence)' }
+    ];
+    for (const testCase of declarative) {
+        it(`should reject declarative ${testCase.name} with declaration and path`, () => {
+            const { compiled, definition } = compileDeclarative(testCase.define);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(testCase.path);
+        });
+    }
+
+    it('should reject the same event-type id with multiple declared generations', () => {
+        class NewGeneration { name!: string; }
+        field(String)(NewGeneration.prototype, 'name');
+        eventType('capability-changed', 2)(NewGeneration);
+        const { compiled, definition } = compileModelBound(model => fromEvent(NewGeneration)(model), [NewGeneration]);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation,
+            'multiple generations of the same event-type id');
+    });
+
+    it('should reject a literal legacy $context. wire expression as unknown with its declaration', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.state).toEventContextProperty('eventType')));
+        definition.From[0].Value.Properties.state = '$context.eventType';
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('(.from().setFromContext)')
+                .and.includes("expression '$context.eventType'").and.includes('$eventContext(...)');
+    });
+
+    it('should reject a client-emitted derived context function at the phase-one boundary', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from =>
+            from.set(model => model.state).toEventContextProperty('occurred.week()')));
+        definition.From[0].Value.Properties.state.should.equal('$eventContext(Occurred.Week())');
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('(.from().setFromContext)')
+                .and.includes("expression '$eventContext(Occurred.Week())': derived event-context functions require a kernel-backed test");
+    });
+
+    for (const expression of [
+        '$eventContext(Occurred.Date)', '$eventContext(EventSourceId.Part)', '$eventContext(CausedBy.Unknown)',
+        '$eventContext(CausedBy.OnBehalfOf.UserName)', '$eventContext(Causation.Type)', '$eventContext(Tags.Name)',
+        '$eventContext(Occurred.ISOWeek())', '$eventContext(Occurred1)', '$eventContext(_Occurred)',
+        '$eventContext(occurred)'
+    ]) {
+        it(`should reject unsupported event-context expression ${expression}`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.state).to(event => event.name)));
+            definition.From[0].Value.Properties.state = expression;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(`expression '${expression}'`);
+        });
+    }
+
+    it('should reject multiple generations on a declarative projection', () => {
+        class NewGeneration { name!: string; }
+        field(String)(NewGeneration.prototype, 'name');
+        eventType('capability-changed', 2)(NewGeneration);
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed).from(NewGeneration), [NewGeneration]);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation,
+            'multiple generations of the same event-type id');
+    });
+
+    for (const format of ['float', 'decimal', 'duration', 'int64']) {
+        it(`should reject ${format} arithmetic rather than approximate the kernel`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.add(model => model.total).with(event => event.quantity)));
+            const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { total: { type: string; format?: string } } };
+            schema.properties.total.format = format;
+            compiled.readModels[0].Schema = JSON.stringify(schema);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('From[capability-changed:1].Properties.total');
+        });
+    }
+
+    for (const format of ['float', 'decimal', 'duration', 'int64']) {
+        it(`should reject model-bound ${format} arithmetic`, () => {
+            const { compiled, definition } = compileModelBound(model => addFrom(Changed, 'quantity')(model.prototype, 'total'));
+            const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { total: { format?: string } } };
+            schema.properties.total.format = format;
+            compiled.readModels[0].Schema = JSON.stringify(schema);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('(@addFrom)').and.includes("expression '$add(quantity)'");
+        });
+    }
+
+    it('should reject an inferred AutoMap target with an unsupported format', () => {
+        const { compiled, definition } = compileModelBound();
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { quantity: { format?: string } } };
+        schema.properties.quantity.format = 'float';
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[capability-changed:1].AutoMap.quantity');
+    });
+
+    it('should reject declarative inferred AutoMap with its real source declaration', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { quantity: { format?: string } } };
+        schema.properties.quantity.format = 'float';
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[capability-changed:1].AutoMap.quantity (.from (AutoMap))');
+    });
+
+    it('should validate AutoMap against every participating event, including the second source', () => {
+        class Second { state!: string; }
+        field(String)(Second.prototype, 'state');
+        eventType('second-source')(Second);
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed).from(Second), [Second]);
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { state: { format?: string } } };
+        schema.properties.state.format = 'float';
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[second-source:1].AutoMap.state (.from (AutoMap))');
+    });
+
+    it('should reject ambiguous AutoMap sources that differ only by case', () => {
+        class Ambiguous { name!: string; Name!: string; }
+        field(String)(Ambiguous.prototype, 'name');
+        field(String)(Ambiguous.prototype, 'Name');
+        eventType('ambiguous-source')(Ambiguous);
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Ambiguous), [Ambiguous]);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[ambiguous-source:1].AutoMap.name (.from (AutoMap))').and.includes('name, Name');
+    });
+
+    it('should reject identifiers with unsupported schemas', () => {
+        const { compiled, definition } = compileModelBound();
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { id: { type: string } } };
+        schema.properties.id.type = 'boolean';
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('ReadModel.Schema.id (@fromEvent)');
+    });
+
+    it('should reject dynamically addressed destinations and unsupported expressions', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.setThisValue().to(event => event.name)));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[capability-changed:1].Properties.$this');
+    });
+
+    it('should reject participating event types missing from discovered registration artifacts', () => {
+        class Undiscovered {}
+        eventType()(Undiscovered);
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Undiscovered));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[').and.includes('(.from)').and.includes('participating event schema is unavailable');
+    });
+});

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

@@ -0,0 +1,73 @@
+// 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 { chai, describe, it } from 'vitest';
+import { ProjectionCapabilities } from '../ProjectionCapabilities.js';
+import { UnsupportedProjectionOperation } from '../UnsupportedProjectionOperation.js';
+import { Changed } from './given/Changed.js';
+import { compileDeclarative } from './given/compile.js';
+
+chai.should();
+
+describe('when validating the numeric capability matrix', () => {
+    for (const format of ['int32', 'uint32']) {
+        it(`should accept ${format} arithmetic with a matching event operand and literal`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from
+                .add(model => model.total).with(event => event.quantity)
+                .set(model => model.quantity).toValue(12)));
+            const modelSchema = JSON.parse(compiled.readModels[0].Schema) as { properties: { total: { type: string; format?: string }; quantity: { type: string; format?: string } } };
+            modelSchema.properties.total = { type: 'integer', format };
+            modelSchema.properties.quantity = { type: 'integer', format };
+            compiled.readModels[0].Schema = JSON.stringify(modelSchema);
+            const eventSchema = compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema;
+            eventSchema.properties!.quantity = { type: 'integer', format };
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+        });
+    }
+
+    it('should accept GUID identifiers and finite double arithmetic', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.add(model => model.total).with(event => event.quantity)));
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { id: { type: string; format?: string }; total: { format?: string } } };
+        schema.properties.id.format = 'guid';
+        schema.properties.total.format = 'double';
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    it('should accept numeric identifiers with a declared number schema', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { id: { type: string } } };
+        schema.properties.id.type = 'number';
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    for (const value of [12.5, 2147483648, 9007199254740992]) {
+        it(`should reject an int32 $value literal outside the integer range (${value})`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.total).toValue(value)));
+            const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { total: { type: string; format?: string } } };
+            schema.properties.total = { type: 'integer', format: 'int32' };
+            compiled.readModels[0].Schema = JSON.stringify(schema);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('$value numeric literal is outside');
+        });
+    }
+
+    it('should reject an overflowing initial integer value', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed)
+            .withInitialValues(() => ({ id: '', name: '', quantity: 0, total: 2147483648, state: '', labels: [], details: {} })));
+        const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { total: { type: string; format?: string } } };
+        schema.properties.total = { type: 'integer', format: 'int32' };
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('InitialModelState.total (.withInitialValues)');
+    });
+
+    it('should reject unsafe int64 operands instead of losing precision', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.add(model => model.total).with(event => event.quantity)));
+        compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties!.quantity.format = 'int64';
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('arithmetic operand requires a supported numeric event schema');
+    });
+});

package/testing/projections/for_ProjectionCapabilities/when_validating_schema_boundaries.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 'reflect-metadata';
+import { ConceptAs, field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { setFrom } from '../../../projections/modelBound/setFrom.js';
+import { JsonSchemaGenerator } from '../../../schemas/JsonSchemaGenerator.js';
+import type { JsonSchema } from '../../../schemas/JsonSchema.js';
+import { ProjectionCapabilities } from '../ProjectionCapabilities.js';
+import { UnsupportedProjectionOperation } from '../UnsupportedProjectionOperation.js';
+import { Changed } from './given/Changed.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+
+chai.should();
+
+class Timestamp extends ConceptAs<Date> { static readonly valueType = Date; }
+class Details { created!: Date; }
+class Dated { created!: Date; timestamp!: Timestamp; details!: Details; }
+field(Date)(Details.prototype, 'created');
+field(Date)(Dated.prototype, 'created');
+field(Timestamp)(Dated.prototype, 'timestamp');
+field(Details)(Dated.prototype, 'details');
+
+function setModelSchema(compiled: ReturnType<typeof compileDeclarative>['compiled'], change: (properties: Record<string, JsonSchema>) => void): void {
+    const schema = JSON.parse(compiled.readModels[0].Schema) as JsonSchema;
+    change(schema.properties!);
+    compiled.readModels[0].Schema = JSON.stringify(schema);
+}
+
+describe('when validating schema-bound projection operations', () => {
+    it('should accept generated date, date concept, and nested date formats for pass-through and initial values', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from
+            .set(model => model.name).to(event => event.name)
+            .set(model => model.state).to(event => event.name)
+            .set(model => model.details).to(event => event.details))
+            .withInitialValues(() => ({ id: '', name: '', quantity: 0, total: 0, state: new Date('2026-01-01') as unknown as string,
+                labels: [], details: { created: new Date('2026-01-01') } })));
+        const dates = JsonSchemaGenerator.generate(Dated).properties!;
+        setModelSchema(compiled, properties => {
+            properties.name = dates.created;
+            properties.state = dates.timestamp;
+            properties.details = dates.details;
+        });
+        const event = compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema;
+        event.properties!.name = dates.created;
+        event.properties!.details = dates.details;
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    it('should accept model-bound date pass-through and date AutoMap', () => {
+        const { compiled, definition } = compileModelBound(model => setFrom(Changed, 'name')(model.prototype, 'state'));
+        const date = JsonSchemaGenerator.generate(Dated).properties!.created;
+        setModelSchema(compiled, properties => { properties.name = date; properties.state = date; });
+        compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties!.name = date;
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    it('should accept $null for a date destination', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.state).toValue(null)));
+        setModelSchema(compiled, properties => { properties.state = { type: 'string', format: 'date-time' }; });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    for (const expression of ['$value(2026-01-01T00:00:00.000Z)', '$increment', '$add(quantity)']) {
+        it(`should reject ${expression} against a date destination`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.state).to(event => event.name)));
+            setModelSchema(compiled, properties => { properties.state = { type: 'string', format: 'date-time' }; });
+            definition.From[0].Value.Properties.state = expression;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(`expression '${expression}'`);
+        });
+    }
+
+    it('should use a string key when neither id nor Id exists', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+        setModelSchema(compiled, properties => { delete properties.id; });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    it('should use Id when id is absent, but prefer id when both exist', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+        setModelSchema(compiled, properties => { properties.Id = { type: 'string' }; delete properties.id; });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+        setModelSchema(compiled, properties => { properties.id = { type: 'boolean' }; });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation, 'ReadModel.Schema.id');
+    });
+
+    it('should not treat ID as the kernel identifier', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+        setModelSchema(compiled, properties => { delete properties.id; properties.ID = { type: 'boolean' }; });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    it('should skip AutoMap validation for arithmetic-only events', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.add(model => model.total).with(event => event.quantity)));
+        setModelSchema(compiled, properties => { properties.name.format = 'float'; });
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    for (const [expression, destination, reason] of [
+        ['$value(maybe)', 'state', '$value boolean literal'],
+        ['$value(not-a-guid)', 'state', '$value GUID literal'],
+        ['$value(text)', 'details', '$value object/array literals'],
+        ['$value(text)', 'labels', '$value object/array literals']
+    ]) {
+        it(`should reject invalid ${expression} for ${destination} (${reason})`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+            setModelSchema(compiled, properties => {
+                if (reason.includes('boolean')) properties.state = { type: 'boolean' };
+                if (reason.includes('GUID')) properties.state = { type: 'string', format: 'guid' };
+            });
+            definition.From[0].Value.Properties[destination] = expression;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(reason).and.includes(`expression '${expression}'`);
+        });
+    }
+});

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

@@ -0,0 +1,103 @@
+// 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 { chai, describe, it } from 'vitest';
+import { addFrom } from '../../../projections/modelBound/addFrom.js';
+import { clearWith } from '../../../projections/modelBound/clearWith.js';
+import { count } from '../../../projections/modelBound/count.js';
+import { decrement } from '../../../projections/modelBound/decrement.js';
+import { increment } from '../../../projections/modelBound/increment.js';
+import { noAutoMap } from '../../../projections/modelBound/noAutoMap.js';
+import { removedWith } from '../../../projections/modelBound/removedWith.js';
+import { setFrom } from '../../../projections/modelBound/setFrom.js';
+import { setFromContext } from '../../../projections/modelBound/setFromContext.js';
+import { setValue } from '../../../projections/modelBound/setValue.js';
+import { subtractFrom } from '../../../projections/modelBound/subtractFrom.js';
+import { ProjectionCapabilities } from '../ProjectionCapabilities.js';
+import { Changed } from './given/Changed.js';
+import { Removed } from './given/Removed.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+
+chai.should();
+
+describe('when validating the phase-one projection subset', () => {
+    const modelBound = [
+        { name: 'root From and schema-inferred AutoMap', configure: () => {} },
+        { name: 'setFrom and event source identity', configure: (model: Function) => setFrom(Changed, 'name')(model.prototype, 'name') },
+        { name: 'setFromContext maps eventType without needing it in the event schema', configure: (model: Function) => setFromContext(Changed, 'eventType')(model.prototype, 'state') },
+        { name: 'setFromContext maps the event source identity', configure: (model: Function) => setFromContext(Changed, 'eventSourceId')(model.prototype, 'state') },
+        { name: 'setFromContext maps a nested identity member', configure: (model: Function) => setFromContext(Changed, 'causedBy.subject')(model.prototype, 'state') },
+        { name: 'constant text', configure: (model: Function) => setValue(Changed, 'ready')(model.prototype, 'state') },
+        { name: 'scalar clearing', configure: (model: Function) => clearWith(Removed)(model.prototype, 'state') },
+        { name: 'addition', configure: (model: Function) => addFrom(Changed, 'quantity')(model.prototype, 'total') },
+        { name: 'subtraction', configure: (model: Function) => subtractFrom(Changed, 'quantity')(model.prototype, 'total') },
+        { name: 'count', configure: (model: Function) => count(Changed)(model.prototype, 'total') },
+        { name: 'increment', configure: (model: Function) => increment(Changed)(model.prototype, 'total') },
+        { name: 'decrement', configure: (model: Function) => decrement(Changed)(model.prototype, 'total') },
+        { name: 'root removal', configure: (model: Function) => removedWith(Removed)(model) },
+        { name: 'AutoMap exclusions', configure: (model: Function) => noAutoMap(model.prototype, 'quantity') }
+    ];
+    for (const testCase of modelBound) {
+        it(`should accept model-bound ${testCase.name} before any events are seeded`, () => {
+            const { compiled, definition } = compileModelBound(testCase.configure);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+        });
+    }
+
+    it('should accept declarative multiple root sources, explicit mappings, constants, arithmetic, and removal', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder
+            .from(Changed, from => from.set(model => model.name).to(event => event.name)
+                .set(model => model.id).toEventSourceId()
+                .set(model => model.state).toValue('ready')
+                .add(model => model.total).with(event => event.quantity)
+                .subtract(model => model.total).with(event => event.quantity)
+                .increment(model => model.total).decrement(model => model.total).count(model => model.total))
+            .from(Removed).removedWith(Removed).withInitialValues(() => ({ id: '', name: '', quantity: 0, total: 0, state: 'new', labels: [], details: {} })));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    for (const [property, expression] of [
+        ['sequenceNumber', '$eventContext(SequenceNumber)'],
+        ['eventSourceId', '$eventContext(EventSourceId)'],
+        ['eventStore', '$eventContext(EventStore)'],
+        ['namespace', '$eventContext(Namespace)'],
+        ['eventSourceType', '$eventContext(EventSourceType)'],
+        ['eventStreamType', '$eventContext(EventStreamType)'],
+        ['eventStreamId', '$eventContext(EventStreamId)'],
+        ['subject', '$eventContext(Subject)'],
+        ['hash', '$eventContext(Hash)'],
+        ['causedBy', '$eventContext(CausedBy)'],
+        ['observationState', '$eventContext(ObservationState)'],
+        ['eventType', '$eventContext(EventType)'],
+        ['occurred', '$eventContext(Occurred)'],
+        ['correlationId', '$eventContext(CorrelationId)'],
+        ['causation', '$eventContext(Causation)'],
+        ['tags', '$eventContext(Tags)'],
+        ['causedBy.subject', '$eventContext(CausedBy.Subject)'],
+        ['causedBy.name', '$eventContext(CausedBy.Name)'],
+        ['causedBy.userName', '$eventContext(CausedBy.UserName)'],
+        ['causedBy.onBehalfOf', '$eventContext(CausedBy.OnBehalfOf)']
+    ]) {
+        it(`should accept the client's emitted context expression ${expression}`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from =>
+                from.set(model => model.state).toEventContextProperty(property)));
+            definition.From[0].Value.Properties.state.should.equal(expression);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+        });
+    }
+
+    it('should accept declarative null clearing and an explicit null initial accumulator', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder
+            .from(Changed, from => from.set(model => model.state).toValue(null).count(model => model.total))
+            .withInitialValues(() => ({ id: '', name: '', quantity: 0, total: null as unknown as number, state: '', labels: [], details: {} })));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+
+    it('should accept an ordinary object or array value without mistaking it for a child projection', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from
+            .set(model => model.labels).to(event => event.labels)
+            .set(model => model.details).to(event => event.details)));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+});