@cratis/chronicle 6.35.0 → 6.37.0

package/patterns/for_Patterns/when_querying_through_the_connection/after_resetting_the_channel.spec.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { createServer, type ServiceImplementation } from 'nice-grpc';
+import { ConnectionServiceDefinition, PatternsDefinition, type UsualActionsRequest } from '@cratis/chronicle.contracts';
+import { EventStore } from '../../../EventStore.js';
+import { EventStoreName } from '../../../EventStoreName.js';
+import { EventStoreNamespaceName } from '../../../EventStoreNamespaceName.js';
+import { ChronicleConnection } from '../../../connection/index.js';
+import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
+import { DayOfWeek, TimeBucket, type BehaviorPattern } from '../../index.js';
+
+chai.should();
+
+describe('when querying patterns through an event store after resetting its connection', () => {
+    let server: ReturnType<typeof createServer>;
+    let connection: ChronicleConnection;
+    let eventStore: EventStore;
+    let request: UsualActionsRequest;
+    let apiKey: string | undefined;
+    let result: BehaviorPattern[];
+    beforeEach(async () => {
+        server = createServer();
+        const unused = async () => { throw new Error('Unexpected RPC'); };
+        server.add(ConnectionServiceDefinition, {
+            ...Object.fromEntries(Object.keys(ConnectionServiceDefinition.methods).map(name => [name, unused])),
+            checkCompatibility: async () => ({ IsCompatible: true, Incompatibilities: [], ServerVersion: 'test' })
+        } as ServiceImplementation<typeof ConnectionServiceDefinition>);
+        server.add(PatternsDefinition, {
+            allPatterns: unused, allPatternScopes: unused, matchingPatterns: unused, patternsForScope: unused,
+            usualActions: async (received, context) => {
+                request = received;
+                apiKey = context.metadata.get('api-key');
+                return { IsAuthorized: true, Data: [{ Id: 'pattern-1', Occurrences: 9_007_199_254_740_993n }] };
+            }
+        });
+        const port = await server.listen('127.0.0.1:0');
+        connection = new ChronicleConnection({ connectionString: `chronicle://127.0.0.1:${port}?disableTls=true&apiKey=patterns-test` });
+        await connection.connect();
+        eventStore = new EventStore(new EventStoreName('accounts'), new EventStoreNamespaceName('tenant-a'), connection, new ConnectionLifecycle(), 'sink');
+        await connection.resetChannel();
+        result = await eventStore.patterns.getPatternsAt('user-42', { instant: new Date('2026-01-05T00:30:00Z'), offsetMinutes: -240 });
+    });
+    afterEach(async () => {
+        eventStore?.disposeObservations();
+        connection?.dispose();
+        await server?.shutdown();
+    });
+    it('should send the offset-derived context to the generated usual actions service', () => {
+        request.should.deep.equal({
+            EventStore: 'accounts', Namespace: 'tenant-a', GroupingKey: 'user-42',
+            Context: { Day: DayOfWeek.Sunday, TimeBucket: TimeBucket.Evening }, MinimumConfidence: 0, MaximumResults: 0
+        });
+    });
+    it('should use the connection authentication middleware', () => apiKey!.should.equal('patterns-test'));
+    it('should preserve occurrence precision across the actual wire codec', () => result[0].occurrences.should.equal(9_007_199_254_740_993n));
+});

package/patterns/for_toDayOfWeek/when_reading_the_day/at_an_offset.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { DayOfWeek, toDayOfWeek } from '../../index.js';
+
+chai.should();
+
+const cases: [string, number, DayOfWeek][] = [
+    ['2026-01-04T23:59:59.999Z', 0, DayOfWeek.Sunday],
+    ['2026-01-05T00:00:00.000Z', 0, DayOfWeek.Monday],
+    ['2026-01-06T12:00:00Z', 0, DayOfWeek.Tuesday],
+    ['2026-01-07T12:00:00Z', 0, DayOfWeek.Wednesday],
+    ['2026-01-08T12:00:00Z', 0, DayOfWeek.Thursday],
+    ['2026-01-09T12:00:00Z', 0, DayOfWeek.Friday],
+    ['2026-01-10T12:00:00Z', 0, DayOfWeek.Saturday],
+    ['2026-01-04T23:30:00Z', 120, DayOfWeek.Monday],
+    ['2026-01-05T00:30:00Z', -120, DayOfWeek.Sunday],
+    ['2025-12-31T23:30:00Z', 345, DayOfWeek.Thursday],
+    ['2026-01-01T00:30:00Z', -210, DayOfWeek.Wednesday],
+    ['2026-01-04T12:00:00Z', 840, DayOfWeek.Monday],
+    ['2026-01-05T12:00:00Z', -840, DayOfWeek.Sunday]
+];
+
+for (const [instant, offsetMinutes, expected] of cases) {
+    describe(`when reading the day of ${instant} at offset ${offsetMinutes}`, () => {
+        let result: DayOfWeek;
+        beforeEach(() => result = toDayOfWeek({ instant: new Date(instant), offsetMinutes }));
+        it('should name the day at the moment offset rather than UTC', () => result.should.equal(expected));
+    });
+}

package/patterns/for_toTimeBucket/when_bucketing/at_boundaries.spec.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { TimeBucket, toTimeBucket } from '../../index.js';
+
+chai.should();
+
+// Chronicle v19.26.2: TimeBucketExtensions.ToTimeBucket uses >= start and < end on the offset's hour.
+const boundaries: [string, TimeBucket][] = [
+    ['00:00:00.000', TimeBucket.Night],
+    ['04:59:59.999', TimeBucket.Night],
+    ['05:00:00.000', TimeBucket.EarlyMorning],
+    ['07:59:59.999', TimeBucket.EarlyMorning],
+    ['08:00:00.000', TimeBucket.Morning],
+    ['10:59:59.999', TimeBucket.Morning],
+    ['11:00:00.000', TimeBucket.Midday],
+    ['13:59:59.999', TimeBucket.Midday],
+    ['14:00:00.000', TimeBucket.Afternoon],
+    ['16:59:59.999', TimeBucket.Afternoon],
+    ['17:00:00.000', TimeBucket.Evening],
+    ['21:59:59.999', TimeBucket.Evening],
+    ['22:00:00.000', TimeBucket.Night],
+    ['23:59:59.999', TimeBucket.Night]
+];
+
+for (const offsetMinutes of [0, 330, -210, 345, -840, 840]) {
+    for (const [time, expected] of boundaries) {
+        describe(`when bucketing ${time} at offset ${offsetMinutes}`, () => {
+            let result: TimeBucket;
+            beforeEach(() => {
+                const wallClock = new Date(`2026-01-05T${time}Z`);
+                const instant = new Date(wallClock.getTime() - offsetMinutes * 60_000);
+                result = toTimeBucket({ instant, offsetMinutes });
+            });
+            it('should use the same inclusive and exclusive boundaries as the miner', () => result.should.equal(expected));
+        });
+    }
+}

package/patterns/index.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.
+
+export type { BehaviorPattern } from './BehaviorPattern.js';
+export { DayOfWeek } from './DayOfWeek.js';
+export { FacetName } from './FacetName.js';
+export type { FacetSet } from './FacetSet.js';
+export type { IPatterns } from './IPatterns.js';
+export type { PatternMoment } from './PatternMoment.js';
+export type { PatternQueryOptions } from './PatternQueryOptions.js';
+export { Patterns } from './Patterns.js';
+export type { PatternsAtOptions } from './PatternsAtOptions.js';
+export { TimeBucket } from './TimeBucket.js';
+export { toDayOfWeek } from './toDayOfWeek.js';
+export { toTimeBucket } from './toTimeBucket.js';

package/patterns/toBehaviorPattern.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { BehaviorPatternDetailsResponse } from '@cratis/chronicle.contracts';
+import type { BehaviorPattern } from './BehaviorPattern.js';
+
+/**
+ * Converts the wire representation without losing 64-bit occurrence counts or inventing missing timestamps.
+ * @param pattern - The pattern returned by the kernel.
+ * @returns The client representation.
+ */
+export function toBehaviorPattern(pattern: BehaviorPatternDetailsResponse): BehaviorPattern {
+    return {
+        id: pattern.Id,
+        groupingKey: pattern.GroupingKey,
+        facets: { ...pattern.Facets },
+        confidence: pattern.Confidence,
+        support: pattern.Support,
+        occurrences: pattern.Occurrences,
+        weight: pattern.Weight,
+        specificity: pattern.Specificity,
+        firstSeen: pattern.FirstSeen ? new Date(pattern.FirstSeen.Value) : undefined,
+        lastSeen: pattern.LastSeen ? new Date(pattern.LastSeen.Value) : undefined
+    };
+}

package/patterns/toDayOfWeek.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DayOfWeek } from './DayOfWeek.js';
+import type { PatternMoment } from './PatternMoment.js';
+import { toOffsetDate } from './toOffsetDate.js';
+
+const days = [DayOfWeek.Sunday, DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Wednesday,
+    DayOfWeek.Thursday, DayOfWeek.Friday, DayOfWeek.Saturday];
+
+/**
+ * Reads the day at a moment's own offset, using Chronicle's English day names.
+ * @param moment - The instant and the offset it occurred at.
+ * @returns The day of week used by the Day facet.
+ * @throws {RangeError} If the date or offset is invalid.
+ */
+export function toDayOfWeek(moment: PatternMoment): DayOfWeek {
+    return days[toOffsetDate(moment).getUTCDay()];
+}

package/patterns/toOffsetDate.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { PatternMoment } from './PatternMoment.js';
+
+/**
+ * Produces a date whose UTC fields represent the moment's wall-clock fields.
+ * Internal only: the shifted value must never be used as an actual instant.
+ * @param moment - An instant and its explicit offset.
+ * @returns The shifted date for reading UTC calendar fields.
+ */
+export function toOffsetDate(moment: PatternMoment): Date {
+    if (!Number.isInteger(moment.offsetMinutes) || Math.abs(moment.offsetMinutes) > 14 * 60) {
+        throw new RangeError('The moment offset must be a whole number of minutes between -840 and 840.');
+    }
+    const milliseconds = moment.instant.getTime();
+    const shifted = new Date(milliseconds + moment.offsetMinutes * 60_000);
+    if (!Number.isFinite(milliseconds) || !Number.isFinite(shifted.getTime())) {
+        throw new RangeError('The moment must represent a valid date at its offset.');
+    }
+    return shifted;
+}

package/patterns/toTimeBucket.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { PatternMoment } from './PatternMoment.js';
+import { TimeBucket } from './TimeBucket.js';
+import { toOffsetDate } from './toOffsetDate.js';
+
+/**
+ * Buckets a moment using its own offset, matching DateTimeOffset.ToTimeBucket() in Chronicle.
+ * @param moment - The instant and the offset it occurred at, not the machine's offset.
+ * @returns The time bucket, with inclusive starts and exclusive ends.
+ * @throws {RangeError} If the date or offset is invalid.
+ */
+export function toTimeBucket(moment: PatternMoment): TimeBucket {
+    const hour = toOffsetDate(moment).getUTCHours();
+    if (hour >= 5 && hour < 8) return TimeBucket.EarlyMorning;
+    if (hour >= 8 && hour < 11) return TimeBucket.Morning;
+    if (hour >= 11 && hour < 14) return TimeBucket.Midday;
+    if (hour >= 14 && hour < 17) return TimeBucket.Afternoon;
+    if (hour >= 17 && hour < 22) return TimeBucket.Evening;
+    return TimeBucket.Night;
+}

package/testing/ReactorScenario.spec.ts

@@ -187,6 +187,19 @@ describe('ReactorScenario live delivery', () => {
         scenario.results[0].completed.should.be.false;
     });
 
+    it('rejects behavior pattern queries through the default event store', async () => {
+        let error: unknown;
+        @reactor('pattern-rejection-reactor')
+        class PatternRejection {
+            registered(_event: Registered, _context: EventContext, services: ReactorServices) {
+                try { void services.eventStore.patterns; } catch (caught) { error = caught; }
+            }
+        }
+        const scenario = new ReactorScenario(PatternRejection, options);
+        await scenario.when.forEventSource('A').events(new Registered('first')).catch(() => undefined);
+        (error instanceof UnsupportedReactorOperation && String(error).includes('services.eventStore.patterns')).should.be.true;
+    });
+
     it('stops a multi-event delivery at the event whose handler swallowed an unsupported call', async () => {
         const invoked: string[] = [];
         @reactor('swallowed-in-batch-reactor')

package/testing/ReactorScenario.ts

@@ -131,7 +131,7 @@ export class ReactorScenario {
             namespace: new EventStoreNamespaceName(this._options.namespace ?? 'default'), eventLog: guardedLog, readModels };
         const unsupportedStoreProperties = new Set(['eventTypes', 'constraints', 'projections', 'reactors', 'reducers',
             'unitOfWorkManager', 'jobs', 'webhooks', 'subscriptions', 'seeding', 'externalServices', 'identities',
-            'pii', 'failedPartitions', 'observers']);
+            'pii', 'failedPartitions', 'observers', 'patterns']);
         return new Proxy(store, { get: (target, key) => {
             if (typeof key !== 'string') return undefined;
             if (Object.hasOwn(target, key)) return target[key as keyof typeof target];

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

@@ -0,0 +1,85 @@
+// 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 { ReadModelScenario } from '../../ReadModelScenario.js';
+import { UnsupportedProjectionOperation } from '../../projections/UnsupportedProjectionOperation.js';
+
+chai.should();
+
+class Changed {
+    constructor(readonly amount: number) {}
+}
+field(Number)(Changed.prototype, 'amount');
+eventType('fluent-arithmetic-changed')(Changed);
+class Removed {}
+eventType('fluent-arithmetic-removed')(Removed);
+class Totals {
+    id = '';
+    added = 0;
+    subtracted = 0;
+    counted = 0;
+    incremented = 0;
+    decremented = 0;
+}
+field(String)(Totals.prototype, 'id');
+for (const property of ['added', 'subtracted', 'counted', 'incremented', 'decremented']) field(Number)(Totals.prototype, property);
+class TotalsProjection {
+    define(builder: IProjectionBuilderFor<Totals>): void {
+        builder.noAutoMap().withInitialValues(() => ({ id: '', added: 10, subtracted: 10, counted: 0, incremented: 0, decremented: 0 }))
+            .from(Changed, from => from.add(model => model.added).with(event => event.amount)
+                .subtract(model => model.subtracted).with(event => event.amount)
+                .count(model => model.counted).increment(model => model.incremented).decrement(model => model.decremented))
+            .removedWith(Removed);
+    }
+}
+projection('fluent-arithmetic', Totals)(TotalsProjection);
+const artifacts = { eventTypes: [Changed, Removed], projections: [TotalsProjection], reducers: [] };
+
+describe('when evaluating arithmetic with a fluent projection', () => {
+    for (const operation of ['add', 'subtract'] as const) {
+        it(`should reject fluent ${operation} with a snake_case operand before any events are seeded`, () => {
+            class PriceChanged {
+                unit_price = 2;
+            }
+            field(Number)(PriceChanged.prototype, 'unit_price');
+            eventType(`fluent-arithmetic-snake-case-${operation}`)(PriceChanged);
+            class PriceTotals {
+                id = '';
+                total = 0;
+            }
+            field(String)(PriceTotals.prototype, 'id');
+            field(Number)(PriceTotals.prototype, 'total');
+            class PriceProjection {
+                define(builder: IProjectionBuilderFor<PriceTotals>): void {
+                    builder.from(PriceChanged, from => from[operation](model => model.total).with(event => event.unit_price));
+                }
+            }
+            projection(`fluent-arithmetic-snake-case-${operation}`, PriceTotals)(PriceProjection);
+            (() => new ReadModelScenario(PriceTotals, { eventTypes: [PriceChanged], projections: [PriceProjection], reducers: [] }))
+                .should.throw(UnsupportedProjectionOperation).with.property('message')
+                .that.includes('kernel only permits an underscore as the first character')
+                .and.includes('https://github.com/Cratis/Chronicle/issues/4491');
+        });
+    }
+
+    it('should apply all five property operations to initial values', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Changed(2.5), new Changed(-1));
+        const result = (await scenario.instance)!;
+        [result.added, result.subtracted, result.counted, result.incremented, result.decremented].should.deep.equal([11.5, 8.5, 2, 2, -2]);
+    });
+
+    it('should discard the accumulator on removal and reapply initial values on recreation', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Changed(3), new Removed());
+        (await scenario.wasDeletedForEventSourceId('A')).should.be.true;
+        scenario.given.forEventSource('A').events(new Changed(4));
+        const result = (await scenario.instance)!;
+        [result.added, result.counted].should.deep.equal([14, 1]);
+    });
+});

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

@@ -0,0 +1,91 @@
+// 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 { addFrom } from '../../../projections/modelBound/addFrom.js';
+import { subtractFrom } from '../../../projections/modelBound/subtractFrom.js';
+import { count } from '../../../projections/modelBound/count.js';
+import { increment } from '../../../projections/modelBound/increment.js';
+import { decrement } from '../../../projections/modelBound/decrement.js';
+import { setFrom } from '../../../projections/modelBound/setFrom.js';
+import { ReadModelScenario } from '../../ReadModelScenario.js';
+import { UnsupportedProjectionOperation } from '../../projections/UnsupportedProjectionOperation.js';
+
+chai.should();
+
+@eventType('legacy-arithmetic-added')
+class Added {
+    @field(Number) amount: number;
+    @field(String) title = 'not mapped';
+    constructor(amount: number) { this.amount = amount; }
+}
+@eventType('legacy-arithmetic-subtracted')
+class Subtracted {
+    @field(Number) amount: number;
+    constructor(amount: number) { this.amount = amount; }
+}
+@eventType('legacy-arithmetic-renamed')
+class Renamed {
+    @field(Number) amount = 1;
+    @field(String) caption = 'explicit';
+    @field(String) title = 'automapped';
+}
+class Totals {
+    @field(String) id = '';
+    @field(Number) @addFrom(Added, 'amount') @subtractFrom(Subtracted, 'amount') @addFrom(Renamed, 'amount') total = 0;
+    @field(Number) @addFrom(Added) @subtractFrom(Subtracted) amount = 0;
+    @field(Number) @count(Added) counted = 0;
+    @field(Number) @increment(Added) incremented = 0;
+    @field(Number) @decrement(Added) decremented = 0;
+    @field(String) @setFrom(Renamed, 'caption') label = '';
+    @field(String) title = '';
+}
+const artifacts = { eventTypes: [Added, Subtracted, Renamed], readModels: [Totals], reducers: [], projections: [] };
+
+// The same operations are captured in arithmetic.json, arithmetic-numeric-matrix.json and arithmetic-automap.json.
+describe('when evaluating arithmetic with legacy model-bound decorators', () => {
+    for (const [operation, decorate] of [['add', addFrom], ['subtract', subtractFrom]] as const) {
+        it(`should reject @${operation}From with a snake_case operand before any events are seeded`, () => {
+            @eventType(`legacy-arithmetic-snake-case-${operation}`)
+            class PriceChanged {
+                @field(Number) unit_price = 2;
+            }
+            class PriceTotals {
+                @field(String) id = '';
+                @field(Number) @decorate(PriceChanged, 'unit_price') total = 0;
+            }
+            (() => new ReadModelScenario(PriceTotals, { eventTypes: [PriceChanged], readModels: [PriceTotals], reducers: [], projections: [] }))
+                .should.throw(UnsupportedProjectionOperation).with.property('message')
+                .that.includes('kernel only permits an underscore as the first character')
+                .and.includes('https://github.com/Cratis/Chronicle/issues/4491');
+        });
+    }
+
+    it('should accumulate all five operations and default event property names', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Added(2.5), new Added(3), new Subtracted(1));
+        const result = (await scenario.instance)!;
+        [result.total, result.amount, result.counted, result.incremented, result.decremented].should.deep.equal([4.5, 4.5, 2, 2, -2]);
+    });
+
+    it('should replay additional seeds without counting the previous replay twice and keep sources independent', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Added(2));
+        (await scenario.instance)!.total.should.equal(2);
+        scenario.given.forEventSource('B').events(new Added(7));
+        scenario.given.forEventSource('A').events(new Added(3));
+        (await scenario.instanceForEventSourceId('A'))!.total.should.equal(5);
+        (await scenario.instanceForEventSourceId('B'))!.total.should.equal(7);
+    });
+
+    it('should suppress aggregate-only AutoMap and restore it for mixed mappings', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Added(2));
+        ((await scenario.instance)!.title === undefined).should.be.true;
+        scenario.given.forEventSource('A').events(new Renamed());
+        const result = (await scenario.instance)!;
+        [result.total, result.title, result.label].should.deep.equal([3, 'automapped', 'explicit']);
+    });
+});

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

@@ -0,0 +1,92 @@
+// 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, type Assertion } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { addFrom } from '../../../projections/modelBound/addFrom.js';
+import { subtractFrom } from '../../../projections/modelBound/subtractFrom.js';
+import { count } from '../../../projections/modelBound/count.js';
+import { increment } from '../../../projections/modelBound/increment.js';
+import { decrement } from '../../../projections/modelBound/decrement.js';
+import { setFrom } from '../../../projections/modelBound/setFrom.js';
+import { ReadModelScenario } from '../../ReadModelScenario.js';
+import { UnsupportedProjectionOperation } from '../../projections/UnsupportedProjectionOperation.js';
+
+chai.should();
+function should(value: unknown): Assertion { return (value as { should: Assertion }).should; }
+
+@eventType('standard-arithmetic-added')
+class Added {
+    @field(Number) amount: number;
+    @field(String) title = 'not mapped';
+    constructor(amount: number) { this.amount = amount; }
+}
+@eventType('standard-arithmetic-subtracted')
+class Subtracted {
+    @field(Number) amount: number;
+    constructor(amount: number) { this.amount = amount; }
+}
+@eventType('standard-arithmetic-renamed')
+class Renamed {
+    @field(Number) amount = 1;
+    @field(String) caption = 'explicit';
+    @field(String) title = 'automapped';
+}
+class Totals {
+    @field(String) id = '';
+    @field(Number) @addFrom(Added, 'amount') @subtractFrom(Subtracted, 'amount') @addFrom(Renamed, 'amount') total = 0;
+    @field(Number) @addFrom(Added) @subtractFrom(Subtracted) amount = 0;
+    @field(Number) @count(Added) counted = 0;
+    @field(Number) @increment(Added) incremented = 0;
+    @field(Number) @decrement(Added) decremented = 0;
+    @field(String) @setFrom(Renamed, 'caption') label = '';
+    @field(String) title = '';
+}
+const artifacts = { eventTypes: [Added, Subtracted, Renamed], readModels: [Totals], reducers: [], projections: [] };
+
+// The same operations are captured in arithmetic.json, arithmetic-numeric-matrix.json and arithmetic-automap.json.
+describe('when evaluating arithmetic with standard model-bound decorators', () => {
+    for (const [operation, decorate] of [['add', addFrom], ['subtract', subtractFrom]] as const) {
+        it(`should reject @${operation}From with a snake_case operand before any events are seeded`, () => {
+            @eventType(`standard-arithmetic-snake-case-${operation}`)
+            class PriceChanged {
+                @field(Number) unit_price = 2;
+            }
+            class PriceTotals {
+                @field(String) id = '';
+                @field(Number) @decorate(PriceChanged, 'unit_price') total = 0;
+            }
+            should(() => new ReadModelScenario(PriceTotals, { eventTypes: [PriceChanged], readModels: [PriceTotals], reducers: [], projections: [] }))
+                .throw(UnsupportedProjectionOperation).with.property('message')
+                .that.includes('kernel only permits an underscore as the first character')
+                .and.includes('https://github.com/Cratis/Chronicle/issues/4491');
+        });
+    }
+
+    it('should accumulate all five operations and default event property names', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Added(2.5), new Added(3), new Subtracted(1));
+        const result = (await scenario.instance)!;
+        should([result.total, result.amount, result.counted, result.incremented, result.decremented]).deep.equal([4.5, 4.5, 2, 2, -2]);
+    });
+
+    it('should replay additional seeds without counting the previous replay twice and keep sources independent', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Added(2));
+        should((await scenario.instance)!.total).equal(2);
+        scenario.given.forEventSource('B').events(new Added(7));
+        scenario.given.forEventSource('A').events(new Added(3));
+        should((await scenario.instanceForEventSourceId('A'))!.total).equal(5);
+        should((await scenario.instanceForEventSourceId('B'))!.total).equal(7);
+    });
+
+    it('should suppress aggregate-only AutoMap and restore it for mixed mappings', async () => {
+        const scenario = new ReadModelScenario(Totals, artifacts);
+        scenario.given.forEventSource('A').events(new Added(2));
+        should((await scenario.instance)!.title === undefined).be.true;
+        scenario.given.forEventSource('A').events(new Renamed());
+        const result = (await scenario.instance)!;
+        should([result.total, result.title, result.label]).deep.equal([3, 'automapped', 'explicit']);
+    });
+});

package/testing/projections/ProjectionArithmetic.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import { ProjectionExpressionEvaluator } from './ProjectionExpressionEvaluator.js';
+import { ProjectionValueConverter } from './ProjectionValueConverter.js';
+
+/** The root arithmetic subset captured by the packaged-kernel arithmetic fixtures. */
+export class ProjectionArithmetic {
+    static isArithmetic(expression: string): boolean {
+        return /^\$(?:add|subtract)\(/.test(expression) || ['$count', '$increment', '$decrement'].includes(expression);
+    }
+
+    /** The kernel suppresses AutoMap for a nonempty set of aggregate-only mappings. */
+    static suppressesAutoMap(properties: Record<string, string>): boolean {
+        const expressions = Object.values(properties);
+        return expressions.length > 0 && expressions.every(expression => this.isArithmetic(expression));
+    }
+
+    static validate(expression: string, target: JsonSchema, eventSchema: JsonSchema, fail: (reason: string) => never): void {
+        if (!((target.type === 'number' && (!target.format || target.format === 'double')) ||
+            (target.type === 'integer' && target.format === 'int32'))) {
+            fail('arithmetic targets must be number/double or integer/int32; other targets require a kernel-backed test');
+        }
+        if (['$count', '$increment', '$decrement'].includes(expression)) return;
+        const operand = /^\$(?:add|subtract)\(([^()]+)\)$/.exec(expression)?.[1];
+        if (operand?.slice(1).includes('_')) {
+            fail('the Chronicle 19.26.2 kernel only permits an underscore as the first character of an arithmetic operand; snake_case operands are unsupported (https://github.com/Cratis/Chronicle/issues/4491)');
+        }
+        // Direct-property subset of EventValueProviderRegularExpressions.Expression in Chronicle 19.26.2.
+        // AddExpressionResolver and SubtractExpressionResolver anchor that grammar; nested/$ operands remain unproven.
+        const source = /^\$(?:add|subtract)\(([A-Za-z_][A-Za-z0-9]*)\)$/.exec(expression)?.[1];
+        if (!source || ['true', 'True', 'false', 'False'].includes(source)) {
+            fail('arithmetic operands must be direct numeric event properties; nested paths, literals and context require a kernel-backed test');
+        }
+        const schema = eventSchema.properties?.[source!];
+        if (!schema) fail(`arithmetic event property '${source}' is absent from the participating event schema`);
+        if (schema!.compliance?.length || schema!.security?.length) fail('protected arithmetic operands require a kernel-backed test');
+        if (!((schema!.type === 'number' && (!schema!.format || schema!.format === 'double')) ||
+            (schema!.type === 'integer' && ['int32', 'uint32'].includes(schema!.format ?? '')))) {
+            fail('arithmetic operands must have number/double, integer/int32 or integer/uint32 schemas; non-numeric and other operands require a kernel-backed test');
+        }
+    }
+
+    static value(expression: string, content: unknown, target: JsonSchema, current: unknown): number {
+        const operation = /^\$(add|subtract)\(([^()]+)\)$/.exec(expression);
+        const operand = operation ? ProjectionExpressionEvaluator.pathValue(content, operation[2]) : 1;
+        // Absent accumulators start at zero, unlike explicitly cleared (null) accumulators.
+        if (current === null) throw new RangeError('Projection arithmetic cannot use a null accumulator.');
+        const previous = current === undefined ? 0 : this.number(current, target);
+        const amount = this.number(operand, target);
+        const result = operation?.[1] === 'subtract' || expression === '$decrement' ? previous - amount : previous + amount;
+        // Int32 arithmetic is unchecked in the kernel; operand conversion is checked and rounds ties to even.
+        if (target.format === 'int32') return result | 0;
+        ProjectionValueConverter.checkNumber(result, target);
+        return result;
+    }
+
+    private static number(value: unknown, target: JsonSchema): number {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new RangeError('Projection arithmetic requires finite numeric values.');
+        }
+        let number = value;
+        if (target.format === 'int32') {
+            const lower = Math.floor(value);
+            number = value - lower === 0.5 ? (lower % 2 === 0 ? lower : lower + 1) : Math.round(value);
+        }
+        ProjectionValueConverter.checkNumber(number, target);
+        return number;
+    }
+}