@cratis/chronicle 6.35.0 → 6.37.0

package/testing/projections/ProjectionCapabilities.ts

@@ -8,6 +8,7 @@ import { eventContractPath } from '../../projections/eventContractPath.js';
 import type { ContractEventType, FromRecord, RemovedWithRecord } from '../../projections/declarative/ProjectionBuilderCore.js';
 import { getEventTypeMapKey, type ChildrenDefinitionLike } from '../../projections/modelBound/childrenAndNestedBuilder.js';
 import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import { ProjectionArithmetic } from './ProjectionArithmetic.js';
 import { ProjectionChildrenCapabilities } from './ProjectionChildrenCapabilities.js';
 import { UnsupportedProjectionOperation } from './UnsupportedProjectionOperation.js';
 
@@ -95,6 +96,19 @@ export class ProjectionCapabilities {
                 reject(eventContractPath('From', entry.Key), 'events subscribed through both From and RemovedWith require a kernel-backed test (ChronicleKernelScenario / live kernel)');
             }
         }
+        const accumulators = new Set(from.flatMap(entry => Object.entries(entry.Value.Properties ?? {})
+            .filter(([, expression]) => ProjectionArithmetic.isArithmetic(expression)).map(([property]) => property)));
+        if (accumulators.size && Object.keys(wire.Children as object ?? {}).length) {
+            reject('Children', 'root arithmetic combined with children requires a kernel-backed test');
+        }
+        for (const entry of from) {
+            for (const [property, expression] of Object.entries(entry.Value.Properties ?? {})) {
+                if (expression === '$null' && accumulators.has(property)) {
+                    reject(`${eventContractPath('From', entry.Key)}.Properties.${property}`,
+                        'clearing an arithmetic accumulator requires a kernel-backed test; the kernel rejects arithmetic on a present null');
+                }
+            }
+        }
         for (const entry of [...from, ...removedWith]) {
             const section = from.includes(entry as FromRecord) ? 'From' : 'RemovedWith';
             const path = eventContractPath(section, entry.Key);
@@ -105,10 +119,10 @@ export class ProjectionCapabilities {
             const properties = (entry as FromRecord).Value.Properties ?? {};
             for (const [property, expression] of Object.entries(properties)) {
                 const mappingPath = `${path}.Properties.${property}`;
-                this.checkMapping(schema!, eventSchema, property, expression, mappingPath, reject);
+                this.checkMapping(schema!, eventSchema, property, expression, mappingPath, reject, accumulators);
             }
-            if (wire.AutoMap !== AutoMap.Disabled) {
-                this.checkAutoMap(schema!, eventSchema, properties, wire.NoAutoMapProperties as string[] ?? [], path, reject);
+            if (wire.AutoMap !== AutoMap.Disabled && !ProjectionArithmetic.suppressesAutoMap(properties)) {
+                this.checkAutoMap(schema!, eventSchema, properties, wire.NoAutoMapProperties as string[] ?? [], path, reject, accumulators);
             }
         }
         ProjectionChildrenCapabilities.validate(wire.Children as Record<string, ChildrenDefinitionLike> ?? {}, {
@@ -121,20 +135,20 @@ export class ProjectionCapabilities {
 
     private static checkAutoMap(
         modelSchema: JsonSchema, eventSchema: JsonSchema, explicit: Record<string, string>, exclusions: string[],
-        path: string, reject: (path: string, reason: string) => never
+        path: string, reject: (path: string, reason: string) => never, accumulators: ReadonlySet<string>
     ): void {
         for (const [destination] of Object.entries(modelSchema.properties ?? {})) {
             if (Object.keys(explicit).some(name => name.toLowerCase() === destination.toLowerCase()) ||
                 exclusions.some(name => name.toLowerCase() === destination.toLowerCase())) continue;
             const candidates = Object.keys(eventSchema.properties ?? {}).filter(source => source.toLowerCase() === destination.toLowerCase());
             if (candidates.length > 1) reject(`${path}.AutoMap.${destination}`, `inferred AutoMap source is ambiguous: ${candidates.join(', ')}`);
-            if (candidates.length) this.checkMapping(modelSchema, eventSchema, destination, candidates[0], `${path}.AutoMap.${destination}`, reject);
+            if (candidates.length) this.checkMapping(modelSchema, eventSchema, destination, candidates[0], `${path}.AutoMap.${destination}`, reject, accumulators);
         }
     }
 
     private static checkMapping(
         modelSchema: JsonSchema, eventSchema: JsonSchema, destination: string, expression: string,
-        path: string, reject: (path: string, reason: string) => never
+        path: string, reject: (path: string, reason: string) => never, accumulators?: ReadonlySet<string>
     ): void {
         const fail = (reason: string): never => reject(path, `expression '${expression}': ${reason}`);
         const target = modelSchema.properties?.[destination]
@@ -184,9 +198,10 @@ export class ProjectionCapabilities {
             }
             return;
         }
-        const operation = /^(\$add|\$subtract)\(([^()]+)\)$/.exec(expression);
-        const arithmetic = operation || ['$count', '$increment', '$decrement'].includes(expression);
-        if (arithmetic) fail('arithmetic requires a kernel-backed test (ChronicleKernelScenario / live kernel)');
+        if (ProjectionArithmetic.isArithmetic(expression)) {
+            ProjectionArithmetic.validate(expression, target, eventSchema, fail);
+            return;
+        }
         if (/^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)*$/.test(expression)) {
             if (['true', 'True', 'false', 'False'].includes(expression)) {
                 fail('kernel resolves this expression as a boolean literal before event content');
@@ -195,6 +210,9 @@ export class ProjectionCapabilities {
             const source = this.propertyAt(eventSchema, expression);
             if (!source) return fail(`event property '${expression}' is absent from the participating event schema`);
             this.checkSchema(source, path, (_path, reason) => fail(reason));
+            if (accumulators?.has(destination) && !this.numeric(source)) {
+                fail('assigning non-numeric event properties to an arithmetic accumulator requires a kernel-backed test; missing values can clear it');
+            }
             if (!this.compatible(source, target)) {
                 fail(`source '${expression}' (${source.type}${source.format ? `/${source.format}` : ''}) to target '${destination}' (${target.type}${target.format ? `/${target.format}` : ''}) requires a kernel-backed test`);
             }

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

@@ -38,11 +38,11 @@ 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 }> = {
-    'aggregate-only-automap.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic requires a kernel-backed test' },
-    'arithmetic.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic requires a kernel-backed test' },
-    'rounded-integer-operand.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic requires a kernel-backed test' },
-    'int32-overflow.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic requires a kernel-backed test' },
-    'null-accumulator.json': { type: 'UnsupportedProjectionOperation', message: 'arithmetic requires a kernel-backed test' },
+    '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' },
+    'arithmetic-null-initial.json': { type: 'UnsupportedProjectionOperation', message: 'initial numeric value must be a JSON number' },
+    'null-accumulator.json': { type: 'UnsupportedProjectionOperation', message: 'clearing an arithmetic accumulator requires a kernel-backed test' },
     'concept-shaped-objects.json': { type: 'UnsupportedProjectionOperation', message: 'nested event property paths require a kernel-backed test' },
     'mapped-and-removed.json': { type: 'UnsupportedProjectionOperation', message: 'both From and RemovedWith require a kernel-backed test' },
     'mapped-id-key-wins.json': { type: 'UnsupportedProjectionOperation', message: 'identifier or case-insensitively colliding target mappings require a kernel-backed test' },
@@ -97,9 +97,12 @@ describe('when replaying committed kernel semantics fixtures', () => {
                         () => { throw new Error('Evaluator accepted a kernel-rejected mapping'); },
                         error => {
                             (error instanceof RangeError).should.be.true;
-                            (error as Error).message.should.include('not supported by integer/int32');
+                            (error as Error).message.should.include(input.expectedError!.type === 'System.OverflowException'
+                                ? 'outside the supported integer/int32 range' : 'not supported by integer/int32');
                         }
                     );
+                    processor.engineState.should.deep.equal(expected.engineState);
+                    processor.publicRead.should.deep.equal(expected.publicRead);
                 } else {
                     await processor.process(events.slice(0, step + 1));
                     processor.engineState.should.deep.equal(expected.engineState);

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -12,6 +12,7 @@ import type { JsonSchema } from '../../schemas/JsonSchema.js';
 import type { IReadModelProcessor } from '../IReadModelProcessor.js';
 import type { ReadModelState } from '../ReadModelState.js';
 import type { ScenarioEvent } from '../ScenarioEvent.js';
+import { ProjectionArithmetic } from './ProjectionArithmetic.js';
 import { ProjectionCapabilities } from './ProjectionCapabilities.js';
 import { ProjectionExpressionEvaluator } from './ProjectionExpressionEvaluator.js';
 import { ProjectionValueConverter } from './ProjectionValueConverter.js';
@@ -107,7 +108,8 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
             if (from) {
                 const explicit = { ...from.Value.Properties };
                 const excluded = (this._definition.NoAutoMapProperties ?? []);
-                const properties = this._definition.AutoMap !== AutoMap.Disabled ? this.withAutoMap(explicit, schema, this._schema, excluded) : explicit;
+                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);
             }
             if (child) this.applyChild(child, content, event, schema, state, binding);
@@ -168,8 +170,12 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
 
     private apply(properties: Record<string, string>, content: unknown, event: ScenarioEvent, target: JsonSchema, state: Record<string, unknown>): void {
         for (const [destination, expression] of Object.entries(properties)) {
-            const value = ProjectionExpressionEvaluator.value(expression, content, event.context, target.properties![destination]);
-            // The kernel compares old and new null values; null on an absent member is no change.
+            const arithmetic = ProjectionArithmetic.isArithmetic(expression);
+            const value = arithmetic
+                ? ProjectionArithmetic.value(expression, content, target.properties![destination], state[destination])
+                : ProjectionExpressionEvaluator.value(expression, content, event.context, target.properties![destination]);
+            // Zero arithmetic on an absent accumulator is no change, just like null on an absent scalar.
+            if (arithmetic && value === 0 && state[destination] === undefined) continue;
             if (value !== null || state[destination] !== undefined) state[destination] = value;
         }
     }

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

@@ -148,11 +148,11 @@ describe('when rejecting unsupported operations before any event is seeded', ()
     });
 
     for (const expression of ['$add(quantity)', '$subtract(quantity)', '$count', '$increment', '$decrement']) {
-        it(`should reject all arithmetic ${expression} before replay`, () => {
+        it(`should reject arithmetic ${expression} on non-numeric targets before replay`, () => {
             const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.total).toValue(0)));
-            definition.From[0].Value.Properties.total = expression;
+            definition.From[0].Value.Properties = { name: expression };
             (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
-                .with.property('message').that.includes('arithmetic requires a kernel-backed test (ChronicleKernelScenario / live kernel)');
+                .with.property('message').that.includes('arithmetic targets must be number/double or integer/int32');
         });
     }
 

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

@@ -0,0 +1,127 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { count } from '../../../projections/modelBound/count.js';
+import { increment } from '../../../projections/modelBound/increment.js';
+import { decrement } from '../../../projections/modelBound/decrement.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 { Removed } from './given/Removed.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+
+chai.should();
+
+describe('when validating arithmetic before replay', () => {
+    for (const expression of ['$add(quantity)', '$subtract(quantity)', '$count', '$increment', '$decrement']) {
+        it(`should admit ${expression} on number fields without seeding events`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+            definition.From[0].Value.Properties.total = expression;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+        });
+    }
+
+    for (const expression of ['$add(name)', '$subtract(name)', '$add(missing)', '$add(inner.quantity)', '$subtract($eventSourceId)', '$add($value(1))', '$add(true)', '$add()']) {
+        it(`should reject unproven arithmetic operands in ${expression} with the contract path`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.add(model => model.total).with(event => event.quantity)));
+            definition.From[0].Value.Properties.total = expression;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('From[capability-changed:1].Properties.total (.from().addFrom)').and.includes('arithmetic');
+        });
+    }
+
+    for (const operation of ['add', 'subtract']) {
+        for (const property of ['unit_price', '_unit_price']) {
+            it(`should reject $${operation}(${property}) with the kernel operand limitation before replay`, () => {
+                const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+                compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties![property] = { type: 'number' };
+                definition.From[0].Value.Properties.total = `$${operation}(${property})`;
+                (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                    .with.property('message').that.includes('From[capability-changed:1].Properties.total')
+                    .and.includes('kernel only permits an underscore as the first character')
+                    .and.includes('https://github.com/Cratis/Chronicle/issues/4491');
+            });
+        }
+        it(`should admit $${operation}(_quantity) with a leading underscore`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+            compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties!._quantity = { type: 'number' };
+            definition.From[0].Value.Properties.total = `$${operation}(_quantity)`;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+        });
+    }
+
+    for (const target of [{ type: 'integer', format: 'uint32' }, { type: ['number', 'null'] }, { type: 'string' }, { type: 'boolean' }]) {
+        it(`should reject an unproven ${JSON.stringify(target)} accumulator schema`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.increment(model => model.total)));
+            const schema = JSON.parse(compiled.readModels[0].Schema) as JsonSchema;
+            schema.properties!.total = target as JsonSchema;
+            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 source of [{ type: 'boolean' }, { type: 'object' }, { type: ['number', 'null'] }, { type: 'number', format: 'decimal' }, { type: 'integer', format: 'int64' }]) {
+        it(`should reject an unproven ${JSON.stringify(source)} operand schema`, () => {
+            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 = source as JsonSchema;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('arithmetic operands must have number/double');
+        });
+    }
+
+    it('should reject arithmetic on a protected operand', () => {
+        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.security = [{ metadataType: 'EncryptedSubject', details: '' }];
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('protected arithmetic operands');
+    });
+
+    it('should reject any declaration that can clear an accumulator before arithmetic', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.increment(model => model.total))
+            .from(Removed, from => from.set(model => model.total).toValue(0)));
+        definition.From[1].Value.Properties.total = '$null';
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[capability-removed:1].Properties.total').and.includes('clearing an arithmetic accumulator');
+    });
+
+    it('should reject a text assignment that can clear an arithmetic accumulator', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.total).to(event => event.name))
+            .from(Removed, from => from.increment(model => model.total)));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('assigning non-numeric event properties to an arithmetic accumulator');
+    });
+
+    it('should reject inferred text AutoMap that can clear an arithmetic accumulator', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed)
+            .from(Removed, from => from.increment(model => model.total)));
+        compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties!.total = { type: 'string' };
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('AutoMap.total').and.includes('assigning non-numeric event properties');
+    });
+
+    it('should reject root arithmetic combined with children without widening the child boundary', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.increment(model => model.total))
+            .children(model => model.labels, child => child.from(Removed)));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('root arithmetic combined with children');
+    });
+
+    for (const [name, decorate] of [['count', count], ['increment', increment], ['decrement', decrement]] as const) {
+        it(`should keep @${name} constant keys outside the supported source-id shape`, () => {
+            const { compiled, definition } = compileModelBound(model => decorate(Removed, 'all')(model.prototype, 'total'));
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(`(@${name})`).and.includes('only $eventSourceId keys');
+        });
+    }
+
+    it('should not validate suppressed AutoMap as an executed mapping', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.increment(model => model.total)));
+        const schema = JSON.parse(compiled.readModels[0].Schema) as JsonSchema;
+        schema.properties!.quantity = { type: 'number', format: 'decimal' };
+        compiled.readModels[0].Schema = JSON.stringify(schema);
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
+    });
+});

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

@@ -12,7 +12,7 @@ chai.should();
 
 describe('when validating the numeric capability matrix', () => {
     for (const format of ['int32', 'uint32']) {
-        it(`should accept a finite ${format} literal without admitting arithmetic`, () => {
+        it(`should accept a finite ${format} literal`, () => {
             const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from
                 .set(model => model.quantity).toValue(12)));
             const modelSchema = JSON.parse(compiled.readModels[0].Schema) as { properties: { quantity: { type: string; format?: string } } };
@@ -63,13 +63,12 @@ describe('when validating the numeric capability matrix', () => {
         });
     }
 
-    it('should reject a double event operand into an integer accumulator before replay', () => {
+    it('should admit fixture-backed rounding of a double event operand into an int32 accumulator', () => {
         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 = { type: 'integer', format: 'int32' };
         compiled.readModels[0].Schema = JSON.stringify(schema);
-        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
-            .with.property('message').that.includes('arithmetic requires a kernel-backed test');
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.not.throw();
     });
 
     it('should reject an int32 $value literal with a fractional spelling even if its value is integral', () => {
@@ -96,6 +95,6 @@ describe('when validating the numeric capability matrix', () => {
         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 requires a kernel-backed test');
+            .with.property('message').that.includes('arithmetic operands must have number/double');
     });
 });