@cratis/chronicle 6.31.4 → 6.32.1

package/schemas/for_JsonSchemaGenerator/when_generating_children/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,143 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
+import { JsonSchemaGenerator } from '../../JsonSchemaGenerator.js';
+
+chai.should();
+
+class ItemAdded {
+    itemId = '';
+    name = '';
+}
+
+class Item {
+    id = '';
+    name = '';
+    quantity = 0;
+}
+
+class Order {
+    @childrenFrom(ItemAdded, { childType: Item, key: 'itemId' })
+    options: Item[] = [];
+
+    @childrenFrom(ItemAdded, Item)
+    positional: Item[] = [];
+
+    @childrenFrom(ItemAdded, { childType: Item, key: 'itemId' })
+    withoutInitializer!: Item[];
+
+    @field(Array, { genericArguments: [Item] })
+    @childrenFrom(ItemAdded, 'itemId')
+    fieldMetadata: Item[] = [];
+
+    @childrenFrom(ItemAdded, { key: 'itemId', identifiedBy: 'id' })
+    unknown: Item[] = [];
+
+    @field(Array, { genericArguments: [Item] })
+    unrelated: Item[] = [];
+}
+
+class DeclaredItem {
+    @field(String) id!: string;
+    @field(String) name!: string;
+}
+
+class DeclaredOrder {
+    @childrenFrom(ItemAdded, { childType: DeclaredItem, key: 'itemId' })
+    items!: DeclaredItem[];
+}
+
+class UnresolvedItem {
+    id!: string;
+    name!: string;
+}
+
+class PartiallyResolvedItem {
+    id = '';
+    name!: string;
+}
+
+class MissingIdentifierItem {
+    id!: string;
+    name = '';
+}
+
+class CustomIdentifierItem {
+    itemId = '';
+    name!: string;
+}
+
+class CapitalizedIdentifierItem {
+    Id = '';
+    name!: string;
+}
+
+class FallbackOrder {
+    @childrenFrom(ItemAdded, { childType: UnresolvedItem, key: 'itemId', identifiedBy: 'id' })
+    unresolved!: UnresolvedItem[];
+
+    @childrenFrom(ItemAdded, { childType: MissingIdentifierItem, key: 'itemId', identifiedBy: 'id' })
+    missingIdentifier!: MissingIdentifierItem[];
+
+    @childrenFrom(ItemAdded, { childType: PartiallyResolvedItem, key: 'itemId' })
+    partial!: PartiallyResolvedItem[];
+
+    @childrenFrom(ItemAdded, { childType: CustomIdentifierItem, key: 'itemId' })
+    custom!: CustomIdentifierItem[];
+
+    @childrenFrom(ItemAdded, { childType: CapitalizedIdentifierItem, key: 'itemId' })
+    capitalized!: CapitalizedIdentifierItem[];
+
+    @childrenFrom(ItemAdded, { childType: MissingIdentifierItem, key: 'itemId' })
+    undiscoverableIdentifier!: MissingIdentifierItem[];
+}
+
+const schema = JsonSchemaGenerator.generate(Order);
+
+describe('for JsonSchemaGenerator', () => {
+    describe('when generating children with legacy decorators without design metadata', () => {
+        for (const property of ['options', 'positional', 'withoutInitializer', 'fieldMetadata']) {
+            it(`should register typed items for ${property}`, () => {
+                chai.should().not.exist(Reflect.getMetadata('design:type', Order.prototype, property));
+                schema.properties![property].should.deep.equal({ type: 'array', items: JsonSchemaGenerator.generate(Item) });
+                schema.properties![property].items!.properties!.should.deep.equal({
+                    id: { type: 'string' }, name: { type: 'string' }, quantity: { type: 'number' }
+                });
+            });
+        }
+
+        it('should resolve child properties from explicit field metadata without initializers', () => {
+            JsonSchemaGenerator.generate(DeclaredOrder).properties!.items.items!.properties!.should.deep.equal({
+                id: { type: 'string' }, name: { type: 'string' }
+            });
+        });
+
+        it('should retain untyped items when the child type is unknown', () => {
+            schema.properties!.unknown.should.deep.equal({ type: 'array', items: { type: 'object' } });
+        });
+
+        it('should retain untyped items for child members declared only with definite assignment', () => {
+            JsonSchemaGenerator.generate(FallbackOrder).properties!.unresolved.should.deep.equal({ type: 'array', items: { type: 'object' } });
+        });
+
+        for (const property of ['missingIdentifier', 'undiscoverableIdentifier']) {
+            it(`should retain untyped items for ${property} despite a resolved non-identifier property`, () => {
+                JsonSchemaGenerator.generate(FallbackOrder).properties![property].should.deep.equal({ type: 'array', items: { type: 'object' } });
+            });
+        }
+
+        for (const [property, childType] of [['partial', PartiallyResolvedItem], ['custom', CustomIdentifierItem], ['capitalized', CapitalizedIdentifierItem]] as const) {
+            it(`should retain typed items for ${property} with a resolved identifier`, () => {
+                JsonSchemaGenerator.generate(FallbackOrder).properties![property].should.deep.equal({ type: 'array', items: JsonSchemaGenerator.generate(childType) });
+            });
+        }
+
+        it('should preserve legacy array schemas outside children collections', () => {
+            schema.properties!.unrelated.should.deep.equal({ type: 'array', items: { type: 'object' } });
+        });
+    });
+});

package/schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,66 @@
+// 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 { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
+import { JsonSchemaGenerator } from '../../JsonSchemaGenerator.js';
+
+chai.should();
+
+function should(value: unknown): ReturnType<typeof chai.expect> {
+    return (value as { should: ReturnType<typeof chai.expect> }).should;
+}
+
+class ItemAdded {
+    @field(String) itemId!: string;
+    @field(String) name!: string;
+}
+
+class Item {
+    @field(String) id!: string;
+    @field(String) name!: string;
+    @field(Number) quantity!: number;
+}
+
+class Order {
+    @field(Array)
+    @childrenFrom(ItemAdded, { childType: Item, key: 'itemId' })
+    options!: Item[];
+
+    @field(Array)
+    @childrenFrom(ItemAdded, Item)
+    positional!: Item[];
+
+    @childrenFrom(ItemAdded, { childType: Item, key: 'itemId' })
+    withoutField!: Item[];
+
+    @field(Array, { genericArguments: [Item] })
+    @childrenFrom(ItemAdded, 'itemId')
+    fieldMetadata!: Item[];
+}
+
+class UnknownOrder {
+    @field(Array)
+    @childrenFrom(ItemAdded, { key: 'itemId', identifiedBy: 'id' })
+    items!: Item[];
+}
+
+const schema = JsonSchemaGenerator.generate(Order);
+
+describe('for JsonSchemaGenerator', () => {
+    describe('when generating children with standard decorators', () => {
+        for (const property of ['options', 'positional', 'withoutField', 'fieldMetadata']) {
+            it(`should register typed items for ${property}`, () => {
+                should(schema.properties![property]).deep.equal({ type: 'array', items: JsonSchemaGenerator.generate(Item) });
+                should(schema.properties![property].items!.properties!).deep.equal({
+                    id: { type: 'string' }, name: { type: 'string' }, quantity: { type: 'number' }
+                });
+            });
+        }
+
+        it('should still reject an unresolved child type', () => {
+            should(() => JsonSchemaGenerator.generate(UnknownOrder)).throw(TypeError, 'Cannot determine the element type of UnknownOrder.items');
+        });
+    });
+});

package/testing/ConstraintScope.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventContext } from '../events/EventContext.js';
+import type { ConstraintScopeCapture } from '../events/constraints/ConstraintBuilder.js';
+
+/** Property indexes use the kernel's unescaped flattened key, not a tuple. */
+export function propertyScopeKey(scope: ConstraintScopeCapture, context: EventContext): string {
+    const parts: string[] = [];
+    if (scope.perEventSourceType) parts.push(`est:${context.eventSourceType}`);
+    if (scope.perEventStreamType) parts.push(`estt:${context.eventStreamType}`);
+    if (scope.perEventStreamId) parts.push(`esid:${context.eventStreamId}`);
+    return parts.join('|');
+}
+
+/** Event-type cycles compare selected dimensions exactly. Never flatten them like property keys. */
+export function eventTypeScopeKey(scope: ConstraintScopeCapture, context: EventContext): string {
+    return JSON.stringify([
+        scope.perEventSourceType ? context.eventSourceType : null,
+        scope.perEventStreamType ? context.eventStreamType : null,
+        scope.perEventStreamId ? context.eventStreamId : null
+    ]);
+}
+
+/** Keep definition names, scope keys and source IDs in separate map levels. */
+export function scopeIndex<T>(indexes: Map<string, Map<string, T>>, name: string, scope: string, create: () => T): T {
+    let scopes = indexes.get(name);
+    if (!scopes) { scopes = new Map<string, T>(); indexes.set(name, scopes); }
+    let index = scopes.get(scope);
+    if (index === undefined) { index = create(); scopes.set(scope, index); }
+    return index;
+}

package/testing/EventScenario.batches.spec.ts

@@ -138,8 +138,8 @@ describe('when appending batches against committed kernel fixtures', () => {
             expected: { sequences: string[]; routes: Array<{ source: string; sourceType: string; streamType: string; streamId: string }> };
         };
         const scenario = create();
-        // Explicit empty route values are outside the scenario's domain; omit only those fields here.
-        const supported = routeCases.filter(item => item.sourceType !== '' && item.streamType !== '' && item.streamId !== '');
+        // Scoped wire fixtures additionally prove ts-proto omission of explicit empty routes.
+        const supported = routeCases;
         const results = await scenario.appendMany(supported.map(item => ({ eventSourceId: item.source,
             event: new OracleEventRecorded(item.name, item.active), eventSourceType: item.sourceType,
             eventStreamType: item.streamType, eventStreamId: item.streamId })));
@@ -450,9 +450,6 @@ describe('when appending batches against committed kernel fixtures', () => {
             ['appendMany.correlationId', () => scenario.appendMany('B', [event()], { correlationId: 'bad-guid' })],
             ['appendMany.entry', () => scenario.appendMany([entry({ unknown: 'value' })])],
             ['appendMany.sourceType', () => scenario.appendMany([entry({ eventSourceType: 'bad source' })])],
-            ['appendMany.sourceType', () => scenario.appendMany([entry({ eventSourceType: '' })], { sourceType: 'Group' })],
-            ['appendMany.streamType', () => scenario.appendMany('B', [event()], { streamType: '' })],
-            ['appendMany.streamId', () => scenario.appendMany([entry({ eventStreamId: '' })], { streamId: 'stream1' })],
             ['appendMany.subject', () => scenario.appendMany([entry({ subject: '' })], { subject: 'shared' })],
             ['appendMany.streamType', () => scenario.appendMany([entry({ eventStreamType: 'bad stream' })])],
             ['appendMany.streamId', () => scenario.appendMany([entry({ eventStreamId: 'bad stream' })])],

package/testing/EventScenario.constraints.spec.ts

@@ -355,7 +355,7 @@ describe('fixture-backed unscoped constraints', () => {
         subject.results.length.should.equal(1);
     });
 
-    it('rejects scoped, composite and case-insensitive configurations and unsupported keys before mutation', async () => {
+    it('rejects malformed or overlapping configurations and unsupported keys before mutation', async () => {
         const scoped = (configure: (builder: IConstraintBuilder) => void) => {
             class InvalidConstraint implements IConstraint {
                 define(builder: IConstraintBuilder) { configure(builder); }
@@ -363,9 +363,6 @@ describe('fixture-backed unscoped constraints', () => {
             constraint('ScopedOrComposite')(InvalidConstraint);
             unsupported(() => new EventScenario({ artifacts: { eventTypes: types, constraints: [InvalidConstraint] } }), 'artifacts.constraints');
         };
-        scoped(builder => builder.perEventStreamId().unique(key => key.on(OracleKeyClaimed, event => event.key)));
-        scoped(builder => builder.perEventStreamType().unique(key => key.on(OracleKeyClaimed, event => event.key)));
-        scoped(builder => builder.perEventSourceType().unique(key => key.on(OracleKeyClaimed, event => event.key)));
         scoped(builder => builder.unique(key => key.on(OracleKeyClaimed, event => event.key, event => event.key)));
         scoped(builder => builder.perEventStreamId().unique(key => key.on(OracleKeyClaimed, event => event.key).ignoreCasing()));
         scoped(builder => builder.unique(key => key.on(OracleKeyClaimed, event => event.key))

package/testing/EventScenario.fixtures.spec.ts

@@ -59,7 +59,7 @@ const fixtures = readdirSync(directory).filter(name => name.endsWith('.json') &&
     !['batches.json', 'batch-omitted-routes.json', 'batch-rollback.json', 'builders.json', 'constraints.json', 'constraints-isolation.json', 'constraints-key-domain.json',
         'constraints-property-lifecycle.json', 'constraints-property-covered-removal.json', 'constraints-event-type-cycles.json',
         'constraints-event-type-siblings.json', 'constraints-composite.json',
-        'constraints-ignore-casing.json'].includes(name)).map(name => ({
+        'constraints-ignore-casing.json', 'constraints-scopes.json'].includes(name)).map(name => ({
     name, fixture: JSON.parse(readFileSync(new URL(name, directory), 'utf8')) as Fixture
 }));
 const artifacts = { eventTypes: [OracleEventRecorded, AlternateRecorded, BoundaryRecorded], constraints: [] };

package/testing/EventScenario.ts

@@ -96,9 +96,21 @@ export class EventScenario {
                         throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
                             'Every constrained event type must be in the selected catalog. Claiming and removal references must be complete.');
                     }
+                    const scoped = Object.values(capture.scope).some(Boolean);
+                    if (scoped && removedWith.some(id => {
+                        const type = eventTypes.find(type => getEventTypeFor(type).id.value === id);
+                        return type && Object.keys(getEventTypeMetadata(type)?.schema.properties ?? {}).length === 0;
+                    })) {
+                        throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
+                            'Scoped fieldless removal events are not fixture-backed.');
+                    }
                     for (const entry of capture.uniqueConstraint?.eventDefinitions ?? []) {
                         const type = eventTypes.find(type => getEventTypeFor(type).id.value === entry.eventTypeId)!;
                         const schemaTypes = entry.properties.map(property => getEventTypeMetadata(type)?.schema.properties?.[property]?.type ?? '');
+                        if (scoped && schemaTypes.some(schemaType => schemaType !== 'string')) {
+                            throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
+                                'Scoped property keys must be schema-backed strings.');
+                        }
                         if (entry.properties.length === 1 && !['string', 'boolean'].includes(schemaTypes[0])) {
                             throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
                                 'The constrained property must be a schema-backed string or boolean.');

package/testing/InProcessConstraints.ts

@@ -8,6 +8,7 @@ import type { ConstraintCapture } from '../events/constraints/ConstraintBuilder.
 import { resolveConstraintMessage } from '../events/constraints/Constraints.js';
 import type { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+import { eventTypeScopeKey, propertyScopeKey, scopeIndex } from './ConstraintScope.js';
 
 export type WireConstraintViolation = ContractsConstraintViolation;
 
@@ -49,7 +50,7 @@ function claimOf(name: string, unique: UniqueCapture, eventTypeId: string, conte
     return { key: keyHash(joined.replace(/[A-Z]/g, letter => String.fromCharCode(letter.charCodeAt(0) + 32))), parts };
 }
 
-/** Narrow, fixture-backed unscoped constraint validation over serialized event snapshots. */
+/** Narrow, fixture-backed constraint validation over serialized event snapshots. */
 export class InProcessConstraints {
     private readonly _constrainedProperties = new Map<string, Set<string>>();
     private readonly _removalTypes = new Set<string>();
@@ -62,11 +63,15 @@ export class InProcessConstraints {
             if (capture.uniqueConstraint && capture.uniqueEventType) {
                 throw this.unsupported(name, 'A definition with both constraint kinds is not fixture-backed.');
             }
-            if (capture.scope.perEventSourceType || capture.scope.perEventStreamType || capture.scope.perEventStreamId) {
-                throw this.unsupported(name, 'Scoped constraints are not fixture-backed.');
+            const scoped = Object.values(capture.scope).some(Boolean);
+            if (scoped && _definitions.size !== 1) {
+                throw this.unsupported(name, 'Scoped constraints alongside other definitions are not fixture-backed.');
             }
             if (capture.uniqueConstraint) {
                 const unique = capture.uniqueConstraint;
+                if (scoped && (unique.ignoreCasing || unique.eventDefinitions.some(entry => entry.properties.length !== 1))) {
+                    throw this.unsupported(name, 'Scoped composite or case-insensitive property keys are not fixture-backed.');
+                }
                 // constraints-composite.json installs one, two and three flat properties per event type.
                 // The kernel keys properties by path with ToDictionary, so duplicate paths are not a key shape.
                 if (unique.eventDefinitions.length === 0 || unique.eventDefinitions.some(entry =>
@@ -85,6 +90,10 @@ export class InProcessConstraints {
                     this._removalTypes.add(id);
                     this._propertyRemovalTypes.add(id);
                 }
+                if (scoped && unique.eventDefinitions.some(entry =>
+                    entry.eventTypeId === unique.removedWithEventTypeId || unique.removedWithEventTypeIds?.includes(entry.eventTypeId))) {
+                    throw this.unsupported(name, 'Scoped covered-and-removal property events are not fixture-backed.');
+                }
                 for (const entry of unique.eventDefinitions) {
                     const properties = this._constrainedProperties.get(entry.eventTypeId) ?? new Set<string>();
                     entry.properties.forEach(property => properties.add(property));
@@ -104,6 +113,9 @@ export class InProcessConstraints {
                     !(ids.length === 3 && removals.length === 3 && shared === 1)) {
                     throw this.unsupported(name, 'This unique event type set and removal combination is not fixture-backed.');
                 }
+                if (scoped && shared !== 0) {
+                    throw this.unsupported(name, 'Scoped covered-and-removal event cycles are not fixture-backed.');
+                }
                 // Each cycle fixture installs its definition alone; interaction with other definitions is unproven.
                 if (removals.length && _definitions.size !== 1) {
                     throw this.unsupported(name, 'Unique event cycles alongside other definitions are not fixture-backed.');
@@ -145,15 +157,16 @@ export class InProcessConstraints {
         const violations: WireConstraintViolation[] = [];
         // Durable ownership is one claim per source, not one entry per historical value.
         // Rebuild it from committed history; batch claims below remain independent and are never released.
-        const owners = new Map<string, Map<string, { key: string; sequence: string }>>();
+        const owners = new Map<string, Map<string, Map<string, { key: string; sequence: string }>>>();
         for (const [name, definition] of this._definitions) {
             if (!definition.uniqueConstraint) continue;
-            const claims = new Map<string, { key: string; sequence: string }>();
             const unique = definition.uniqueConstraint;
             const removals = new Set([unique.removedWithEventTypeId, ...(unique.removedWithEventTypeIds ?? [])]);
             for (const prior of history) {
                 const type = prior.eventType.id.value;
                 const source = prior.context.eventSourceId;
+                const claims = scopeIndex(owners, name, propertyScopeKey(definition.scope, prior.context),
+                    () => new Map<string, { key: string; sequence: string }>());
                 if (removals.has(type)) {
                     claims.delete(source);
                     continue;
@@ -166,10 +179,9 @@ export class InProcessConstraints {
                 claims.set(source, { key: claimOf(name, unique, type, prior.content)!.key,
                     sequence: prior.context.sequenceNumber.toString() });
             }
-            owners.set(name, claims);
         }
-        const stagedKeys = new Map<string, Map<string, string>>();
-        const stagedCycles = new Map<string, Map<string, 'open' | 'released'>>();
+        const stagedKeys = new Map<string, Map<string, Map<string, string>>>();
+        const stagedCycles = new Map<string, Map<string, Map<string, 'open' | 'released'>>>();
         for (const event of incoming) {
             const type = event.eventType.id.value;
             const source = event.context.eventSourceId;
@@ -178,8 +190,10 @@ export class InProcessConstraints {
                 const claim = definition.uniqueConstraint && claimOf(name, definition.uniqueConstraint, type, event.content);
                 if (claim) {
                     const key = claim.key;
-                    const existing = [...owners.get(name)!.entries()].find(([, claim]) => claim.key === key);
-                    const batchClaims = stagedKeys.get(name) ?? new Map<string, string>();
+                    const scope = propertyScopeKey(definition.scope, event.context);
+                    const durableClaims = owners.get(name)?.get(scope);
+                    const existing = [...(durableClaims?.entries() ?? [])].find(([, claim]) => claim.key === key);
+                    const batchClaims = scopeIndex(stagedKeys, name, scope, () => new Map<string, string>());
                     const batchOwner = batchClaims.get(key);
                     if (existing && existing[0] !== source || batchOwner !== undefined && batchOwner !== source) {
                         // One violation per declared property, in declared order, each with its own original value.
@@ -192,7 +206,6 @@ export class InProcessConstraints {
                         }
                     } else {
                         batchClaims.set(key, source);
-                        stagedKeys.set(name, batchClaims);
                     }
                 }
                 const uniqueType = definition.uniqueEventType;
@@ -200,14 +213,15 @@ export class InProcessConstraints {
                     const covered = uniqueType.eventTypeIds ?? [uniqueType.eventTypeId];
                     const removals = uniqueType.removedWithEventTypeIds ?? [];
                     // Durable answer: the earliest covered event after the latest removal for this source.
+                    const scope = eventTypeScopeKey(definition.scope, event.context);
                     let first: AppendedEvent | undefined;
                     for (const prior of history) {
-                        if (prior.context.eventSourceId !== source) continue;
+                        if (prior.context.eventSourceId !== source || eventTypeScopeKey(definition.scope, prior.context) !== scope) continue;
                         const priorType = prior.eventType.id.value;
                         if (removals.includes(priorType)) first = undefined;
                         else if (!first && covered.includes(priorType)) first = prior;
                     }
-                    const cycles = stagedCycles.get(name) ?? new Map<string, 'open' | 'released'>();
+                    const cycles = scopeIndex(stagedCycles, name, scope, () => new Map<string, 'open' | 'released'>());
                     const state = cycles.get(source);
                     // A cycle state recorded earlier in this append overrides durable history.
                     if (state === 'open' || state === undefined && first) {
@@ -219,7 +233,6 @@ export class InProcessConstraints {
                             Details: {} });
                     } else {
                         cycles.set(source, 'open');
-                        stagedCycles.set(name, cycles);
                     }
                 }
             }
@@ -228,9 +241,9 @@ export class InProcessConstraints {
             if (violations.length === violationCount) {
                 for (const [name, definition] of this._definitions) {
                     if (definition.uniqueEventType?.removedWithEventTypeIds?.includes(type)) {
-                        const cycles = stagedCycles.get(name) ?? new Map<string, 'open' | 'released'>();
+                        const cycles = scopeIndex(stagedCycles, name, eventTypeScopeKey(definition.scope, event.context),
+                            () => new Map<string, 'open' | 'released'>());
                         cycles.set(source, 'released');
-                        stagedCycles.set(name, cycles);
                     }
                 }
             }

package/testing/InProcessEventSequence.ts

@@ -169,12 +169,7 @@ export class InProcessEventSequence implements IEventSequence {
         try {
             if (!event || typeof event !== 'object') throw this.unsupported('append.event', this.id.value, 'Only registered event instances are supported.');
             if (!/^[A-Za-z0-9_-]+$/.test(eventSourceId)) throw this.unsupported('append.source', eventSourceId, 'Only simple source identifiers are fixture-backed.');
-            if (options && (Reflect.ownKeys(options).length || options.correlationId !== undefined || options.sourceType !== undefined ||
-                options.streamType !== undefined || options.streamId !== undefined || options.subject !== undefined ||
-                options.occurred !== undefined || options.eventSourceId !== undefined || options.concurrencyScope !== undefined ||
-                options.tags !== undefined || options.concurrencyScopes !== undefined)) {
-                throw this.unsupported('append.options', event.constructor.name, 'Append metadata, routing and concurrency are not fixture-backed.');
-            }
+            const route = this.singleAppendRoute(options, event.constructor.name);
             const metadata = this._catalog.get(event.constructor);
             if (!metadata) throw this.unsupported('append.event', event.constructor.name, 'Event is not in the selected, validated catalog.');
             let prepared: ReturnType<typeof prepareSingleAppend>;
@@ -212,7 +207,7 @@ export class InProcessEventSequence implements IEventSequence {
                 context: {
                     eventStore: this._store, namespace: this._namespace,
                     sequenceNumber: sequenceNumber.value, eventSourceId,
-                    eventSourceType: 'Default', eventStreamType: 'All', eventStreamId: 'Default',
+                    eventSourceType: route.sourceType, eventStreamType: route.streamType, eventStreamId: route.streamId,
                     subject: eventSourceId, hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
                     eventType: prepared.eventType, occurred, correlationId: prepared.correlationId.toString(),
                     causation: prepared.causationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
@@ -295,7 +290,8 @@ export class InProcessEventSequence implements IEventSequence {
                 const wire = eventsToAppend[index];
                 for (const [name, value] of Object.entries({ sourceType: wire.EventSourceType, streamType: wire.EventStreamType,
                     streamId: wire.EventStreamId, subject: wire.Subject })) {
-                    if (value !== undefined && (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value))) {
+                    const identifiers = name === 'subject' ? /^[A-Za-z0-9_-]+$/ : /^[A-Za-z0-9_-]*$/;
+                    if (value !== undefined && (typeof value !== 'string' || !identifiers.test(value))) {
                         throw this.unsupported(`appendMany.${name}`, String(value), 'Only simple metadata identifiers are fixture-backed.');
                     }
                 }
@@ -403,6 +399,26 @@ export class InProcessEventSequence implements IEventSequence {
         }
     }
 
+    private singleAppendRoute(options: AppendOptions | undefined, artifact: string): { sourceType: string; streamType: string; streamId: string } {
+        if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+            throw this.unsupported('append.options', artifact, 'Append options must be an object.');
+        }
+        if (options && (Reflect.ownKeys(options).some(key => !['sourceType', 'streamType', 'streamId'].includes(String(key))) ||
+            options.correlationId !== undefined || options.subject !== undefined || options.occurred !== undefined ||
+            options.eventSourceId !== undefined || options.concurrencyScope !== undefined || options.tags !== undefined ||
+            options.concurrencyScopes !== undefined)) {
+            throw this.unsupported('append.options', artifact, 'Only sourceType, streamType and streamId routing options are fixture-backed for single append.');
+        }
+        const route = { sourceType: options?.sourceType, streamType: options?.streamType, streamId: options?.streamId };
+        for (const [name, value] of Object.entries(route)) {
+            if (value !== undefined && (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value))) {
+                throw this.unsupported(`append.${name}`, String(value), 'Only simple routing identifiers or empty defaults are fixture-backed.');
+            }
+        }
+        // ts-proto omits empty strings; the append pipeline resolves omissions to these exact values.
+        return { sourceType: route.sourceType || 'Default', streamType: route.streamType || 'All', streamId: route.streamId || 'Default' };
+    }
+
     private validateBatchOptions(options?: AppendOptions): void {
         if (options === undefined) return;
         if (!options || typeof options !== 'object' || Array.isArray(options)) {

package/testing/ReadModelScenario.childrenFrom.spec.ts

@@ -1,11 +1,13 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { readFileSync } from 'node:fs';
 import { chai, describe, it } from 'vitest';
 import { eventType } from '../events/eventTypeDecorator.js';
 import { childrenFrom } from '../projections/modelBound/childrenFrom.js';
 import { fromEvent } from '../projections/modelBound/fromEvent.js';
 import { setFrom } from '../projections/modelBound/setFrom.js';
+import { JsonSchemaGenerator } from '../schemas/JsonSchemaGenerator.js';
 import { ReadModelScenario, UnsupportedProjectionOperation } from './index.js';
 
 chai.should();
@@ -27,6 +29,18 @@ class ScenarioOrder {
 childrenFrom(ScenarioItemAdded, { childType: ScenarioItem, key: 'itemId' })(ScenarioOrder.prototype, 'items');
 fromEvent(ScenarioItemAdded)(ScenarioOrder);
 
+class ScenarioKeyedItem {
+    itemId = '';
+    name = '';
+}
+
+class ScenarioKeyedOrder {
+    id = '';
+    items: ScenarioKeyedItem[] = [];
+}
+childrenFrom(ScenarioItemAdded, { childType: ScenarioKeyedItem, key: 'itemId' })(ScenarioKeyedOrder.prototype, 'items');
+fromEvent(ScenarioItemAdded)(ScenarioKeyedOrder);
+
 class ScenarioNamedItem {
     id = '';
     name = '';
@@ -40,17 +54,70 @@ class ScenarioNamedOrder {
 childrenFrom(ScenarioItemAdded, { childType: ScenarioNamedItem, key: 'itemId' })(ScenarioNamedOrder.prototype, 'items');
 fromEvent(ScenarioItemAdded)(ScenarioNamedOrder);
 
+class ScenarioUnknownOrder {
+    id = '';
+    items: ScenarioItem[] = [];
+}
+childrenFrom(ScenarioItemAdded, { key: 'itemId', identifiedBy: 'id' })(ScenarioUnknownOrder.prototype, 'items');
+fromEvent(ScenarioItemAdded)(ScenarioUnknownOrder);
+
+class ScenarioUnresolvedItem {
+    id!: string;
+    name!: string;
+}
+
+class ScenarioUnresolvedOrder {
+    id = '';
+    items: ScenarioUnresolvedItem[] = [];
+}
+childrenFrom(ScenarioItemAdded, { childType: ScenarioUnresolvedItem, key: 'itemId', identifiedBy: 'id' })(ScenarioUnresolvedOrder.prototype, 'items');
+fromEvent(ScenarioItemAdded)(ScenarioUnresolvedOrder);
+
 const artifacts = { eventTypes: [ScenarioItemAdded], reducers: [], projections: [] };
 
 describe('when a read model scenario evaluates keyed children from the options form', () => {
-    it('should add one child per key and update an existing child in place (children-untyped-items)', async () => {
+    it('should add one child per key and update an existing child in place (children-typed-items)', async () => {
         const scenario = new ReadModelScenario(ScenarioOrder, artifacts);
         scenario.given.forEventSource('order-1').events(
             new ScenarioItemAdded('a', 'first'), new ScenarioItemAdded('b', 'second'), new ScenarioItemAdded('a', 'again'));
         const order = await scenario.instanceForEventSourceId('order-1');
         order!.id.should.equal('order-1');
-        // The kernel's AutoMap is schema-driven, and legacy decorators register an untyped child item schema.
-        order!.items.map(item => ({ id: item.id, name: item.name })).should.deep.equal([{ id: 'a', name: '' }, { id: 'b', name: '' }]);
+        // The explicit child type registers a typed item schema, so AutoMap preserves the event's name.
+        order!.items.map(item => ({ id: item.id, name: item.name })).should.deep.equal([{ id: 'a', name: 'again' }, { id: 'b', name: 'second' }]);
+    });
+
+    it('should register the same typed items schema as the oracle fixture', () => {
+        const fixture = JSON.parse(readFileSync(new URL('./projections/fixtures/children-typed-items.json', import.meta.url), 'utf8'));
+        JsonSchemaGenerator.generate(ScenarioOrder).properties!.items.should.deep.equal(fixture.readModel.schema.properties.items);
+    });
+
+    it('should add and update typed legacy children whose discovered identifier equals the event key (children-identifier-equals-key)', async () => {
+        const fixture = JSON.parse(readFileSync(new URL('./projections/fixtures/children-identifier-equals-key.json', import.meta.url), 'utf8'));
+        JsonSchemaGenerator.generate(ScenarioKeyedOrder).properties!.items.should.deep.equal(fixture.readModel.schema.properties.items);
+        const scenario = new ReadModelScenario(ScenarioKeyedOrder, artifacts);
+        for (let step = 0; step < 3; step++) {
+            const { itemId, name } = fixture.events[step].content;
+            scenario.given.forEventSource('order-1').events(new ScenarioItemAdded(itemId, name));
+            const order = await scenario.instanceForEventSourceId('order-1');
+            order!.should.deep.equal(fixture.expected[step].publicRead['order-1']);
+        }
+    });
+
+    it('should retain only the identifier when the child type is unknown (children-untyped-items)', async () => {
+        const scenario = new ReadModelScenario(ScenarioUnknownOrder, artifacts);
+        scenario.given.forEventSource('order-1').events(new ScenarioItemAdded('a', 'first'));
+        const order = await scenario.instanceForEventSourceId('order-1');
+        order!.items.should.deep.equal([{ id: 'a' }]);
+    });
+
+    it('should retain only the identifier when the declared child members have no runtime types (children-untyped-items)', async () => {
+        const fixture = JSON.parse(readFileSync(new URL('./projections/fixtures/children-untyped-items.json', import.meta.url), 'utf8'));
+        JsonSchemaGenerator.generate(ScenarioUnresolvedOrder).properties!.items.should.deep.equal(fixture.readModel.schema.properties.items);
+        const scenario = new ReadModelScenario(ScenarioUnresolvedOrder, artifacts);
+        scenario.given.forEventSource('order-1').events(
+            new ScenarioItemAdded('a', 'first'), new ScenarioItemAdded('b', 'second'), new ScenarioItemAdded('a', 'again'));
+        const order = await scenario.instanceForEventSourceId('order-1');
+        order!.items.map(item => ({ id: item.id, name: item.name })).should.deep.equal([{ id: 'a', name: undefined }, { id: 'b', name: undefined }]);
     });
 
     it('should reject explicit child property mappings', () => {