@cratis/chronicle 6.18.0 → 6.19.0

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

@@ -0,0 +1,135 @@
+// 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 { readFileSync, readdirSync } from 'node:fs';
+import { chai, describe, it } from 'vitest';
+import { ReadModelObserverType, type ProjectionDefinition } from '@cratis/chronicle.contracts';
+import { EventType } from '../../events/EventType.js';
+import type { EventContext } from '../../events/EventContext.js';
+import { buildReadModelDefinition } from '../../readModels/buildReadModelDefinition.js';
+import type { CompiledProjectionDefinitions } from '../../projections/CompiledProjectionDefinitions.js';
+import type { ProjectionEventSchema } from '../../projections/ProjectionEventSchema.js';
+import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import type { ScenarioEvent } from '../ScenarioEvent.js';
+import { ProjectionReadModelProcessor } from './ProjectionReadModelProcessor.js';
+
+chai.should();
+
+type FixtureSchema = Omit<JsonSchema, 'type' | 'properties' | 'items' | 'additionalProperties'> & {
+    type?: JsonSchema['type'] | readonly ['string', 'null'];
+    properties?: Record<string, FixtureSchema>;
+    items?: FixtureSchema;
+    additionalProperties?: boolean | FixtureSchema;
+};
+
+interface Fixture {
+    kind: 'kernelSemantics' | 'oracleGuard';
+    wireDefinition: ProjectionDefinition;
+    readModel: { schema: FixtureSchema };
+    eventSchemas: Array<{ eventType: { Id: string; Generation: number }; schema: FixtureSchema }>;
+    events: Array<{ context: Record<string, unknown> & { eventType: { Id: string; Generation: number }; eventSourceId: string; sequenceNumber: string; occurred: string }; content: unknown; expectedError?: { type: string; message: string } }>;
+    expected: Array<{ sequenceNumber: string; engineState: Record<string, unknown>; publicRead: Record<string, unknown>; error?: { type: string; message: string } }>;
+}
+
+class OracleReadModel {}
+const directory = new URL('./fixtures/', import.meta.url);
+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' },
+    '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' },
+    'reject-protected-fields.json': { type: 'UnsupportedProjectionOperation', message: 'protected fields require a kernel-backed test' },
+    'reject-protected-identifier.json': { type: 'UnsupportedProjectionOperation', message: 'protected fields require a kernel-backed test' }
+};
+
+function setup(fixture: Fixture): { processor: ProjectionReadModelProcessor<OracleReadModel>; events: ScenarioEvent[] } {
+    const definition = fixture.wireDefinition;
+    const schemas = new Map<string, ProjectionEventSchema>(fixture.eventSchemas.map(entry => [
+        `${entry.eventType.Id}:${entry.eventType.Generation}:0`,
+        { eventType: { ...entry.eventType, Tombstone: false }, schema: entry.schema as JsonSchema }
+    ]));
+    const compiled: CompiledProjectionDefinitions = {
+        definitions: [definition],
+        readModels: [buildReadModelDefinition({ identifier: definition.ReadModel, schema: JSON.stringify(fixture.readModel.schema),
+            sinkTypeId: 'test', observerType: ReadModelObserverType.Projection, observerIdentifier: definition.Identifier })],
+        provenance: new Map([[definition, []]]), eventSchemas: new Map([[definition, schemas]])
+    };
+    const events: ScenarioEvent[] = fixture.events.map(({ context, content }) => ({
+        sourceId: context.eventSourceId, content,
+        context: {
+            ...context,
+            eventType: EventType.parse(`${context.eventType.Id}+${context.eventType.Generation}`),
+            sequenceNumber: BigInt(context.sequenceNumber), occurred: new Date(context.occurred),
+            causation: context.causation ?? [], tags: context.tags ?? [],
+            correlationId: context.correlationId ?? '00000000-0000-0000-0000-000000000000'
+        } as EventContext
+    }));
+    return { processor: new ProjectionReadModelProcessor(OracleReadModel, compiled, definition), events };
+}
+
+describe('when replaying committed kernel semantics fixtures', () => {
+    it('should run kernel fixtures and assert every oracle guard', () => {
+        fixtures.length.should.be.greaterThan(0);
+        allFixtures.filter(({ fixture }) => fixture.kind === 'oracleGuard').length.should.equal(Object.keys(guardErrors).length);
+        allFixtures.every(({ fixture }) => fixture.kind === 'kernelSemantics' || fixture.kind === 'oracleGuard').should.be.true;
+    });
+
+    for (const { name, fixture } of fixtures) {
+        it(`should match each engine and public read snapshot for ${name}`, async () => {
+            const { processor, events } = setup(fixture);
+            fixture.expected.length.should.equal(fixture.events.length);
+            for (let step = 0; step < events.length; step++) {
+                const expected = fixture.expected[step];
+                const input = fixture.events[step];
+                expected.sequenceNumber.should.equal(input.context.sequenceNumber);
+                if (input.expectedError) {
+                    expected.error!.should.deep.equal(input.expectedError);
+                    (step === events.length - 1).should.be.true;
+                    await processor.process(events.slice(0, step + 1)).then(
+                        () => { 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');
+                        }
+                    );
+                } else {
+                    await processor.process(events.slice(0, step + 1));
+                    processor.engineState.should.deep.equal(expected.engineState);
+                    processor.publicRead.should.deep.equal(expected.publicRead);
+                }
+            }
+        });
+    }
+
+    for (const { name, fixture } of allFixtures.filter(({ fixture }) => fixture.kind === 'oracleGuard')) {
+        it(`should reject the oracle guard ${name} rather than silently reproduce unproven behavior`, async () => {
+            const expected = guardErrors[name];
+            (expected !== undefined).should.be.true;
+            for (let index = 0; index < fixture.events.length; index++) {
+                const error = fixture.events[index].expectedError;
+                if (error) {
+                    fixture.expected[index].error!.should.deep.equal(error);
+                    (index === fixture.events.length - 1).should.be.true;
+                }
+            }
+            let actual: unknown;
+            try {
+                const { processor, events } = setup(fixture);
+                await processor.process(events);
+            } catch (error) {
+                actual = error;
+            }
+            (actual instanceof Error).should.be.true;
+            (actual as Error).name.should.equal(expected.type);
+            (actual as Error).message.should.include(expected.message);
+        });
+    }
+});

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -0,0 +1,147 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AutoMap, type ProjectionDefinition } from '@cratis/chronicle.contracts';
+import type { Constructor } from '@cratis/fundamentals';
+import type { CompiledProjectionDefinitions } from '../../projections/CompiledProjectionDefinitions.js';
+import { eventContractPath } from '../../projections/eventContractPath.js';
+import type { FromRecord, RemovedWithRecord } from '../../projections/declarative/ProjectionBuilderCore.js';
+import { deserializeReadModel } from '../../readModels/deserializeReadModel.js';
+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 { ProjectionCapabilities } from './ProjectionCapabilities.js';
+import { ProjectionExpressionEvaluator } from './ProjectionExpressionEvaluator.js';
+import { ProjectionValueConverter } from './ProjectionValueConverter.js';
+import { UnsupportedProjectionOperation } from './UnsupportedProjectionOperation.js';
+
+/** In-process interpreter of the validated, registered projection contract subset. */
+export class ProjectionReadModelProcessor<TReadModel extends object> implements IReadModelProcessor<TReadModel> {
+    private readonly _schema: JsonSchema;
+    private readonly _initial: Record<string, unknown>;
+    private readonly _from: ReadonlyMap<string, FromRecord>;
+    private readonly _removed: ReadonlySet<string>;
+    private readonly _eventSchemas: ReadonlyMap<string, JsonSchema>;
+    private readonly _bindings: ReadonlyMap<string, { generation: number; path: string; declaration: string }>;
+    private _engineState: Record<string, Record<string, unknown>> = {};
+    private _publicRead: Record<string, Record<string, unknown>> = {};
+
+    constructor(private readonly _model: Constructor<TReadModel>, compiled: CompiledProjectionDefinitions, private readonly _definition: ProjectionDefinition) {
+        ProjectionCapabilities.validate(compiled, _definition);
+        const registration = compiled.readModels.find(entry => entry.Type.Identifier === _definition.ReadModel)!;
+        this._schema = JSON.parse(registration.Schema) as JsonSchema;
+        this._initial = JSON.parse(_definition.InitialModelState || '{}') as Record<string, unknown>;
+        const wire = _definition as unknown as { From: FromRecord[]; RemovedWith: RemovedWithRecord[] };
+        this._from = new Map((wire.From ?? []).map(entry => [entry.Key.Id, entry]));
+        this._removed = new Set((wire.RemovedWith ?? []).map(entry => entry.Key.Id));
+        this._bindings = new Map([...(wire.From ?? []), ...(wire.RemovedWith ?? [])].map(entry => {
+            const section = (wire.From ?? []).includes(entry as FromRecord) ? 'From' : 'RemovedWith';
+            const path = eventContractPath(section, entry.Key);
+            const declaration = compiled.provenance.get(_definition)?.find(provenance => provenance.contractPath === path)?.declaration ?? 'contract';
+            return [entry.Key.Id, { generation: entry.Key.Generation, path, declaration }];
+        }));
+        this._eventSchemas = new Map([...(compiled.eventSchemas.get(_definition) ?? new Map()).values()]
+            .map(entry => [entry.eventType.Id, entry.schema]));
+    }
+
+    /** A snapshot of the production-style in-memory sink, for kernel conformance fixtures. */
+    get engineState(): Record<string, Record<string, unknown>> { return structuredClone(this._engineState); }
+    /** A schema-normalized keyed read, for kernel conformance fixtures. */
+    get publicRead(): Record<string, Record<string, unknown>> { return structuredClone(this._publicRead); }
+
+    async process(events: readonly ScenarioEvent[]): Promise<Map<string, ReadModelState<TReadModel>>> {
+        const states = new Map<string, ReadModelState<TReadModel>>();
+        const engine: Record<string, Record<string, unknown>> = Object.create(null);
+        for (const event of events) {
+            const typeId = event.context.eventType.id.value;
+            const from = this._from.get(typeId);
+            const removed = this._removed.has(typeId);
+            if (!from && !removed) continue;
+            const binding = this._bindings.get(typeId)!;
+            if (event.context.eventType.generation.value !== binding.generation) {
+                throw new UnsupportedProjectionOperation(String(this._definition.ReadModel), binding.path, binding.declaration,
+                    `seeded event generation ${event.context.eventType.generation.value} differs from subscribed generation ${binding.generation}; multi-generation history requires a kernel-backed test`);
+            }
+            // A root removal has the final say when an event is registered for both operations.
+            const key = this.keyFor(event.sourceId);
+            if (removed) {
+                delete engine[key];
+                states.set(event.sourceId, { instance: null, deleted: true });
+                continue;
+            }
+            if (!from) continue;
+            const state = engine[key] ?? this.initialState(key, event);
+            const properties = { ...from.Value.Properties };
+            const schema = this._eventSchemas.get(typeId);
+            const content = ProjectionValueConverter.eventContent(event.content, schema!);
+            if (this._definition.AutoMap !== AutoMap.Disabled && schema) {
+                const explicit = new Set(Object.keys(properties).map(name => name.toLowerCase()));
+                const excluded = new Set((this._definition.NoAutoMapProperties ?? []).map(name => name.toLowerCase()));
+                for (const source of Object.keys(schema.properties ?? {})) {
+                    const destination = Object.keys(this._schema.properties ?? {}).find(name => name.toLowerCase() === source.toLowerCase());
+                    if (destination && !explicit.has(destination.toLowerCase()) && !excluded.has(destination.toLowerCase())) {
+                        properties[destination] = source;
+                        explicit.add(destination.toLowerCase());
+                    }
+                }
+            }
+            for (const [destination, expression] of Object.entries(properties)) {
+                const target = this._schema.properties![destination];
+                const value = ProjectionExpressionEvaluator.value(expression, content, event.context, target);
+                // The kernel compares old and new null values; null on an absent member is no change.
+                if (value !== null || state[destination] !== undefined) state[destination] = value;
+            }
+            // InMemorySink.ApplyChanges always restores lowercase id after applying mappings.
+            state.id = ProjectionValueConverter.convert(key, this._schema.properties!.id);
+            engine[key] = state;
+            states.set(event.sourceId, { instance: this.materialize(state), deleted: false });
+        }
+        this._engineState = engine;
+        this._publicRead = Object.fromEntries(Object.entries(engine).map(([key, value]) => [key, this.normalize(value)]));
+        return states;
+    }
+
+    private keyFor(source: string): string {
+        const identifier = this._schema.properties!.id;
+        const canonical = String(ProjectionValueConverter.convert(source, identifier));
+        if (identifier.format === 'guid' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(source)) {
+            throw new RangeError(`Projection event source '${source}' is not a canonical GUID identifier.`);
+        }
+        if (canonical !== source) throw new RangeError(`Projection event source '${source}' is not a canonical ${identifier.type} identifier.`);
+        return canonical;
+    }
+
+    private initialState(key: string, event: ScenarioEvent): Record<string, unknown> {
+        const initial: Record<string, unknown> = Object.create(null);
+        if (Object.keys(this._initial).length) {
+            Object.assign(initial, ProjectionValueConverter.convert(structuredClone(this._initial), this._schema, false, false));
+        }
+        if (!Object.keys(this._initial).length) {
+            for (const [name, property] of Object.entries(this._schema.properties ?? {})) {
+                if (property.type === 'array') initial[name] = [];
+            }
+        }
+        initial.id = ProjectionValueConverter.convert(key, this._schema.properties!.id);
+        initial.__subject = event.context.subject ?? event.sourceId;
+        initial.__initialized = true;
+        return initial;
+    }
+
+    private normalize(state: Record<string, unknown>): Record<string, unknown> {
+        const result: Record<string, unknown> = Object.create(null);
+        for (const [name, schema] of Object.entries(this._schema.properties ?? {})) {
+            const value = state[name];
+            if (value !== undefined && value !== null) result[name] = value;
+            else {
+                const fallback = ProjectionValueConverter.defaultValue(schema);
+                if (fallback !== null && fallback !== undefined) result[name] = fallback;
+            }
+        }
+        return result;
+    }
+
+    private materialize(state: Record<string, unknown>): TReadModel {
+        return deserializeReadModel(this._model, JSON.stringify(this.normalize(state)));
+    }
+}

package/testing/projections/ProjectionValueConverter.spec.ts

@@ -0,0 +1,81 @@
+// 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, expect, it } from 'vitest';
+import { ProjectionValueConverter } from './ProjectionValueConverter.js';
+
+chai.should();
+
+describe('when converting schema-bound projection values', () => {
+    for (const type of ['number', 'integer'] as const) {
+        it(`should reject numeric text in a ${type} event field`, () => {
+            (() => ProjectionValueConverter.eventContent({ amount: '12' }, { type: 'object', properties: {
+                amount: { type, format: type === 'number' ? 'double' : 'int32' }
+            } })).should.throw('must be a JSON number');
+        });
+    }
+
+    for (const format of ['int32', 'uint32']) {
+        it(`should reject decimal-spelled text mapped into ${format} even when the number is integral`, () => {
+            (() => ProjectionValueConverter.convert('1.0', { type: 'integer', format })).should.throw(RangeError, `not supported by integer/${format}`);
+            (ProjectionValueConverter.convert('1', { type: 'integer', format }) as number).should.equal(1);
+        });
+    }
+
+    it('should reject invalid boolean text rather than materialize it as a string', () => {
+        (() => ProjectionValueConverter.convert('not-boolean', { type: 'boolean' })).should.throw(RangeError, 'requires a kernel-backed test');
+        (() => ProjectionValueConverter.eventContent({ flag: 'not-boolean' }, { type: 'object', properties: {
+            flag: { type: 'boolean' }
+        } })).should.throw(RangeError, 'requires a kernel-backed test');
+    });
+
+    it('should reject invalid GUID text at the expression boundary', () => {
+        (() => ProjectionValueConverter.convert('not-a-guid', { type: 'string', format: 'guid' })).should.throw(RangeError, 'requires a kernel-backed test');
+    });
+
+    it('should prefer exact-case event properties over case-insensitive fallbacks', () => {
+        const schema = { type: 'object', properties: { name: { type: 'string' }, Name: { type: 'string' } } };
+        const content = { Name: 'uppercase', name: 'lowercase' };
+        expect(ProjectionValueConverter.eventContent(content, schema)).toEqual({ name: 'lowercase', Name: 'uppercase' });
+        expect(ProjectionValueConverter.convert(content, schema)).toEqual({ name: 'lowercase', Name: 'uppercase' });
+        expect(ProjectionValueConverter.eventContent({ NAME: 'fallback' }, schema)).toEqual({ name: 'fallback', Name: 'fallback' });
+        expect(ProjectionValueConverter.eventContent({ Name: 'uppercase', name: null }, schema)).toEqual({ name: 'uppercase', Name: 'uppercase' });
+        expect(ProjectionValueConverter.eventContent({ name: null, Name: 'uppercase' }, schema)).toEqual({ Name: 'uppercase' });
+    });
+
+    for (const [field, property] of [
+        ['text', { type: 'string' }], ['nullableText', { type: ['string', 'null'] }],
+        ['identifier', { type: 'string', format: 'guid' }]
+    ] as const) {
+        for (const value of [5, { value: 'text' }]) {
+            it(`should reject a non-string ${field} event field`, () => {
+                (() => ProjectionValueConverter.eventContent({ [field]: value }, { type: 'object', properties: {
+                    [field]: property
+                } })).should.throw(RangeError, 'must be a JSON string');
+            });
+        }
+    }
+
+    it('should retain string coercion for expression values', () => {
+        (ProjectionValueConverter.convert(5n, { type: 'string' }) as string).should.equal('5');
+    });
+
+    it('should admit UTC date-time boundaries and reject years or calendar dates outside DateTime', () => {
+        const schema = { type: 'string', format: 'date-time' };
+        (ProjectionValueConverter.convert('0001-01-01T00:00:00Z', schema) as string).should.equal('0001-01-01T00:00:00Z');
+        (ProjectionValueConverter.convert('9999-12-31T23:59:59.999Z', schema) as string).should.equal('9999-12-31T23:59:59.999Z');
+        for (const value of ['+010000-01-01T00:00:00.000Z', '0000-01-01T00:00:00Z',
+            '2025-02-30T00:00:00Z', '9999-12-31T24:00:00Z', '2025-01-01T00:00:00+01:00']) {
+            (() => ProjectionValueConverter.convert(value, schema)).should.throw(RangeError, 'outside the supported DateTime range or UTC ISO format');
+        }
+    });
+
+    it('should accept numeric text in an unformatted TypeScript Number field', () => {
+        (ProjectionValueConverter.convert('1.0', { type: 'number' }) as number).should.equal(1);
+    });
+
+    it('should lowercase a GUID supplied as an expression literal', () => {
+        (ProjectionValueConverter.convert('ABCDEFAB-ABCD-ABCD-ABCD-ABCDEFABCDEF', { type: 'string', format: 'guid' }) as string)
+            .should.equal('abcdefab-abcd-abcd-abcd-abcdefabcdef');
+    });
+});

package/testing/projections/ProjectionValueConverter.ts

@@ -0,0 +1,113 @@
+// 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';
+
+/** Converts values only in the numeric and scalar schema subset admitted by ProjectionCapabilities. */
+export class ProjectionValueConverter {
+    /** Kernel JsonSchemaExtensions.GetDefaultValue: only nullable schemas have a null default. */
+    static defaultValue(schema: JsonSchema): unknown {
+        if (Array.isArray(schema.type) && schema.type.includes('null')) return null;
+        if (schema.format === 'guid') return '00000000-0000-0000-0000-000000000000';
+        if (schema.format === 'date-time') return '0001-01-01T00:00:00';
+        if (schema.type === 'number' || schema.type === 'integer') return 0;
+        if (schema.type === 'boolean') return false;
+        return undefined;
+    }
+
+    /** A null exact-case value falls through to the first case-insensitive property in JSON order. */
+    private static sourceKey(input: Record<string, unknown>, name: string): string | undefined {
+        return Object.hasOwn(input, name) && input[name] != null
+            ? name : Object.keys(input).find(key => key.toLowerCase() === name.toLowerCase());
+    }
+
+    /** The kernel deserializes event JSON against its registered schema before mapping. */
+    static eventContent(content: unknown, schema: JsonSchema): Record<string, unknown> {
+        const serialized = content !== null && typeof content === 'object' && !Array.isArray(content)
+            ? content as Record<string, unknown> : {};
+        const result: Record<string, unknown> = Object.create(null);
+        for (const [name, property] of Object.entries(schema.properties ?? {})) {
+            const source = this.sourceKey(serialized, name);
+            const value = source === undefined ? null : serialized[source];
+            if (value !== null && value !== undefined) result[name] = this.convert(value, property, true, false);
+            else {
+                const fallback = this.defaultValue(property);
+                if (fallback !== null && fallback !== undefined) result[name] = fallback;
+            }
+        }
+        return result;
+    }
+
+    static convert(value: unknown, schema: JsonSchema, eventContent = false, expression = true): unknown {
+        if (value == null) return null;
+        // Concept conversion belongs to expression evaluation, never schema-bound input deserialization.
+        if (expression && schema.type !== 'object' && schema.type !== 'array' &&
+            typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 1 && 'value' in value) {
+            return this.convert((value as Record<string, unknown>).value, schema, eventContent, expression);
+        }
+        if (schema.type === 'object' && typeof value === 'object' && !Array.isArray(value)) {
+            const input = value as Record<string, unknown>;
+            if (schema.additionalProperties || !schema.properties) return structuredClone(input);
+            const result: Record<string, unknown> = Object.create(null);
+            for (const [name, property] of Object.entries(schema.properties)) {
+                const source = this.sourceKey(input, name);
+                if (source !== undefined && input[source] != null) result[name] = this.convert(input[source], property, eventContent, false);
+                else {
+                    const fallback = this.defaultValue(property);
+                    if (fallback !== null && fallback !== undefined) result[name] = fallback;
+                }
+            }
+            return result;
+        }
+        if (schema.type === 'array' && Array.isArray(value)) {
+            return value.map(item => schema.items ? this.convert(item, schema.items, eventContent, false) : structuredClone(item));
+        }
+        if (schema.type === 'boolean') {
+            if (typeof value === 'boolean') return value;
+            if (!eventContent && typeof value === 'string' && /^(true|false)$/i.test(value)) return value.toLowerCase() === 'true';
+            throw new RangeError(`Projection boolean value '${String(value)}' requires a kernel-backed test (ChronicleKernelScenario / live kernel).`);
+        }
+        if (schema.type === 'number' || schema.type === 'integer') {
+            if (eventContent && typeof value !== 'number') {
+                throw new RangeError(`Projection event numeric value '${String(value)}' must be a JSON number.`);
+            }
+            if (typeof value !== 'number' && (typeof value !== 'string' ||
+                !(schema.type === 'integer' ? /^[+-]?\d+$/.test(value) : /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/.test(value)))) {
+                throw new RangeError(`Projection numeric value '${String(value)}' is not supported by ${schema.type}/${schema.format ?? 'double'}.`);
+            }
+            const number = typeof value === 'number' ? value : Number(value);
+            this.checkNumber(number, schema);
+            return number;
+        }
+        if (schema.format === 'date-time') {
+            if (value === '0001-01-01T00:00:00') return value; // Kernel default for a missing DateTime member.
+            // Bound the accepted subset to UTC ISO text with a four-digit year. Date.parse accepts
+            // years beyond DateTime.MaxValue, and silently normalizes some invalid calendar dates.
+            if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value) ||
+                +value.slice(0, 4) < 1 || !Number.isFinite(Date.parse(value)) ||
+                new Date(value).toISOString().slice(0, 19) !== value.slice(0, 19)) {
+                throw new RangeError(`Projection date-time value '${String(value)}' is outside the supported DateTime range or UTC ISO format.`);
+            }
+            return value;
+        }
+        if (eventContent && (schema.type === 'string' || (Array.isArray(schema.type) && schema.type[0] === 'string')) && typeof value !== 'string') {
+            throw new RangeError(`Projection event string value '${String(value)}' must be a JSON string.`);
+        }
+        if (schema.format === 'guid' && typeof value === 'string') {
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) {
+                throw new RangeError(`Projection GUID value '${value}' requires a kernel-backed test (ChronicleKernelScenario / live kernel).`);
+            }
+            return value.toLowerCase();
+        }
+        if (schema.type === 'string' && typeof value !== 'string') return String(value);
+        return value;
+    }
+
+    static checkNumber(number: number, schema: JsonSchema): void {
+        if (!Number.isFinite(number) || (schema.type === 'integer' && (!Number.isSafeInteger(number) ||
+            (schema.format === 'int32' && (number < -2147483648 || number > 2147483647)) ||
+            (schema.format === 'uint32' && (number < 0 || number > 4294967295))))) {
+            throw new RangeError(`Projection numeric value '${number}' is outside the supported ${schema.type}/${schema.format ?? 'double'} range.`);
+        }
+    }
+}

package/testing/projections/for_ProjectionCapabilities/given/Changed.ts

@@ -4,9 +4,7 @@
 import { field } from '@cratis/fundamentals';
 import { eventType } from '../../../../events/eventTypeDecorator.js';
 
-export class Changed { name!: string; quantity!: number; labels!: string[]; details!: object; }
+export class Changed { name!: string; quantity!: number; }
 field(String)(Changed.prototype, 'name');
 field(Number)(Changed.prototype, 'quantity');
-field(Array)(Changed.prototype, 'labels');
-field(Object)(Changed.prototype, 'details');
 eventType('capability-changed')(Changed);

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

@@ -80,7 +80,7 @@ describe('when rejecting unsupported operations before any event is seeded', ()
         { 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: 'removal key', define: builder => { builder.from(Removed).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)' },
@@ -103,6 +103,28 @@ describe('when rejecting unsupported operations before any event is seeded', ()
             'multiple generations of the same event-type id');
     });
 
+    it('should reject dotted event-content source paths before replay', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from =>
+            from.set(model => model.state).to(event => event.name)));
+        definition.From[0].Value.Properties.state = 'inner.value';
+        compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties!.inner = {
+            type: 'object', properties: { value: { type: 'string' } }
+        };
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[capability-changed:1].Properties.state')
+            .and.includes('nested event property paths require a kernel-backed test');
+    });
+
+    for (const expression of ['true', 'True', 'false', 'False']) {
+        it(`should reject reserved literal ${expression} as an event property mapping`, () => {
+            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;
+            compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties![expression] = { type: 'string' };
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes(`expression '${expression}'`).and.includes('boolean literal before event content');
+        });
+    }
+
     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';
@@ -111,6 +133,64 @@ describe('when rejecting unsupported operations before any event is seeded', ()
                 .and.includes("expression '$context.eventType'").and.includes('$eventContext(...)');
     });
 
+    for (const property of ['causedBy', 'causedBy.onBehalfOf', 'causation', 'tags', 'observationState', 'eventType']) {
+        it(`should reject unproven ${property} context mappings with provenance`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from =>
+                from.set(model => model.state).toEventContextProperty(property)));
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('From[capability-changed:1].Properties.state (.from().setFromContext)')
+                .and.includes('kernel-backed test');
+        });
+    }
+
+    it('should reject an event subscribed through both From and RemovedWith', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed).removedWith(Changed));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('From[capability-changed:1]')
+                .and.includes('both From and RemovedWith require a kernel-backed test');
+    });
+
+    for (const expression of ['$add(quantity)', '$subtract(quantity)', '$count', '$increment', '$decrement']) {
+        it(`should reject all arithmetic ${expression} 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;
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('arithmetic requires a kernel-backed test (ChronicleKernelScenario / live kernel)');
+        });
+    }
+
+    it('should reject explicit mappings into the sink-managed id', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.id).toEventSourceId()));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('identifier or case-insensitively colliding target mappings require a kernel-backed test');
+    });
+
+    it('should reject AutoMap into the sink-managed id', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed));
+        compiled.eventSchemas.get(definition)!.get('capability-changed:1:0')!.schema.properties!.id = { type: 'string' };
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('AutoMap.id').and.includes('identifier or case-insensitively colliding target mappings');
+    });
+
+    for (const target of [{ type: 'boolean' }, { type: 'integer', format: 'int32' }, { type: 'string', format: 'date-time' }]) {
+        it(`should reject $eventSourceId mapped into ${target.type}/${target.format ?? 'unformatted'}`, () => {
+            const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from => from.set(model => model.state).toEventSourceId()));
+            const schema = JSON.parse(compiled.readModels[0].Schema) as { properties: { state: typeof target } };
+            schema.properties.state = target;
+            compiled.readModels[0].Schema = JSON.stringify(schema);
+            (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                .with.property('message').that.includes('$eventSourceId requires a string or GUID target');
+        });
+    }
+
+    it('should reject raw Occurred until the kernel conversion is consistent', () => {
+        const { compiled, definition } = compileDeclarative(builder => builder.from(Changed, from =>
+            from.set(model => model.state).toEventContextProperty('occurred')));
+        (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('(.from().setFromContext)')
+                .and.includes('raw Occurred is converted inconsistently by the kernel');
+    });
+
     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()')));