@cratis/chronicle 6.52.1 → 6.53.1

package/projections/for_ProjectionDefinitionCompiler/against_a_kernel/when_subscribing_with_from_all_events.integration.spec.ts

@@ -65,8 +65,8 @@ class AllWithChildMappings {
     @field(Array, { genericArguments: [AllMappedChild] }) @childrenFrom(ChildAdded, 'childId') children: AllMappedChild[] = [];
 }
 
-// Without root all-event subscription, the shared All block needs a root From entry
-// for ChildAdded as well as the child's creating entry.
+// The root fromEvery mapping handles ChildAdded only because the root explicitly
+// subscribes to it; the child's All mapping belongs to the child independently.
 @fromEvent(Started)
 @fromEvent(ChildAdded)
 class ChildOnlyMappings {
@@ -81,20 +81,6 @@ const artifacts: IClientArtifactsProvider = {
     eventTypeMigrations: [], globalForHandlers: []
 };
 
-async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean): Promise<T> {
-    const deadline = Date.now() + 20_000;
-    let value = await read();
-    while (!accept(value)) {
-        if (Date.now() > deadline) {
-            const state = JSON.stringify(value, (_key, member: unknown) => typeof member === 'bigint' ? member.toString() : member);
-            throw new Error(`Timed out waiting for the projected state: ${state}`);
-        }
-        await new Promise(resolve => setTimeout(resolve, 100));
-        value = await read();
-    }
-    return value;
-}
-
 describe.skipIf(!connectionString && !process.env.CI)('when opting into fromAllEvents against a kernel', () => {
     const knownSource = randomUUID();
     const unrelatedSource = randomUUID();
@@ -111,25 +97,32 @@ describe.skipIf(!connectionString && !process.env.CI)('when opting into fromAllE
     let allAfterUnrelated: AllWithChildren | null;
     let restrictedAfterUnrelated: RestrictedWithChildren | null;
     let allChildMappingsAfterChild: AllWithChildMappings | null;
+    let allChildMappingsAfterUpdate: AllWithChildMappings | null;
     let childOnlyAfterChild: ChildOnlyMappings | null;
     let childOnlyAfterUnrelated: ChildOnlyMappings | null;
     let unrelatedChildOnly: ChildOnlyMappings | null;
 
-    async function append(source: string, event: object): Promise<bigint> {
+    async function append(source: string, event: object, waitForObservers = true): Promise<bigint> {
         const result = await store.eventLog.append(source, event);
         result.isSuccess.should.be.true;
+        if (waitForObservers) {
+            const completion = await result.waitForCompletion(20_000);
+            completion.isSuccess.should.equal(true, `Observer completion failed: ${JSON.stringify(completion.failedPartitions)}`);
+        }
         return result.sequenceNumber.value;
     }
 
     async function waitForObserver(observerId: string, sequenceNumber: bigint): Promise<void> {
         const connection = (store as unknown as { _connection: ChronicleConnection })._connection;
-        await eventually(() => connection.observers.getObserverInformation({
+        const observer = await connection.observers.getObserverInformation({
             EventStore: storeName,
             Namespace: 'Default',
             ObserverId: observerId,
             EventSequenceId: 'event-log'
-        }), observer => observer.IsSubscribed && observer.RunningState === ObserverRunningState.Active &&
-            observer.LastHandledEventSequenceNumber >= sequenceNumber);
+        }, { signal: AbortSignal.timeout(5_000) });
+        observer.IsSubscribed.should.equal(true, `${observerId} must be subscribed`);
+        observer.RunningState.should.equal(ObserverRunningState.Active);
+        (observer.LastHandledEventSequenceNumber >= sequenceNumber).should.equal(true, `${observerId} must have handled ${sequenceNumber}`);
     }
 
     beforeAll(async () => {
@@ -138,27 +131,33 @@ describe.skipIf(!connectionString && !process.env.CI)('when opting into fromAllE
         }));
         store = await client.getEventStore(storeName);
 
-        await append(knownSource, Object.assign(new Started(), { value: 'started' }));
-        allAfterStarted = await eventually(() => store.readModels.findInstanceById(AllWithChildren, knownSource), model => model?.lastValue === 'started');
-        await eventually(() => store.readModels.findInstanceById(RestrictedWithChildren, knownSource), model => model?.lastValue === 'started');
-        await append(knownSource, Object.assign(new ChildAdded(), { childId: 'child-one', value: 'child-value' }));
-        allAfterChild = await eventually(() => store.readModels.findInstanceById(AllWithChildren, knownSource), model => model?.children?.length === 1);
-        restrictedAfterChild = await eventually(() => store.readModels.findInstanceById(RestrictedWithChildren, knownSource), model => model?.children?.length === 1);
-        childOnlyAfterChild = await eventually(() => store.readModels.findInstanceById(ChildOnlyMappings, knownSource), model => model?.children?.length === 1);
-        allChildMappingsAfterChild = await eventually(() => store.readModels.findInstanceById(AllWithChildMappings, knownSource), model => model?.children?.length === 1);
-
-        await append(knownSource, Object.assign(new Unrelated(), { marker: 'no-value' }));
-        allAfterUnrelated = await eventually(() => store.readModels.findInstanceById(AllWithChildren, knownSource),
-            model => model !== null && model.lastValue === '');
-
-        await append(unrelatedSource, Object.assign(new Unrelated(), { marker: 'new-source' }));
-        allOnly = await eventually(() => store.readModels.findInstanceById(AllOnly, unrelatedSource), model => model !== null);
-        unrelatedAll = await eventually(() => store.readModels.findInstanceById(AllWithChildren, unrelatedSource), model => model !== null);
-        // A subscribed sentinel advances each restricted observer past both unrelated events.
-        // Progress on an all-event projection is not a barrier for another observer.
+        const startedSequenceNumber = await append(knownSource, Object.assign(new Started(), { value: 'started' }));
+        await waitForObserver('AllWithChildren', startedSequenceNumber);
+        allAfterStarted = await store.readModels.findInstanceById(AllWithChildren, knownSource);
+        const childSequenceNumber = await append(knownSource, Object.assign(new ChildAdded(), { childId: 'child-one', value: 'child-value' }));
+        for (const observerId of ['AllWithChildren', 'RestrictedWithChildren', 'ChildOnlyMappings', 'AllWithChildMappings']) {
+            await waitForObserver(observerId, childSequenceNumber);
+        }
+        allAfterChild = await store.readModels.findInstanceById(AllWithChildren, knownSource);
+        restrictedAfterChild = await store.readModels.findInstanceById(RestrictedWithChildren, knownSource);
+        childOnlyAfterChild = await store.readModels.findInstanceById(ChildOnlyMappings, knownSource);
+        allChildMappingsAfterChild = await store.readModels.findInstanceById(AllWithChildMappings, knownSource);
+
+        const updatedSequenceNumber = await append(knownSource, Object.assign(new ChildAdded(), { childId: 'child-one', value: 'updated-child-value' }));
+        await waitForObserver('AllWithChildMappings', updatedSequenceNumber);
+        allChildMappingsAfterUpdate = await store.readModels.findInstanceById(AllWithChildMappings, knownSource);
+
+        // This client's completion request carries only a global tail, so restricted
+        // observers cannot complete an unrelated append until a subscribed sentinel follows.
+        await append(knownSource, Object.assign(new Unrelated(), { marker: 'no-value' }), false);
+        await append(unrelatedSource, Object.assign(new Unrelated(), { marker: 'new-source' }), false);
         const sentinelSequenceNumber = await append(sentinelSource, Object.assign(new Started(), { value: 'sentinel' }));
-        await waitForObserver('RestrictedWithChildren', sentinelSequenceNumber);
-        await waitForObserver('ChildOnlyMappings', sentinelSequenceNumber);
+        for (const observerId of ['AllOnly', 'AllWithChildren', 'RestrictedWithChildren', 'ChildOnlyMappings']) {
+            await waitForObserver(observerId, sentinelSequenceNumber);
+        }
+        allAfterUnrelated = await store.readModels.findInstanceById(AllWithChildren, knownSource);
+        allOnly = await store.readModels.findInstanceById(AllOnly, unrelatedSource);
+        unrelatedAll = await store.readModels.findInstanceById(AllWithChildren, unrelatedSource);
         restrictedAfterUnrelated = await store.readModels.findInstanceById(RestrictedWithChildren, knownSource);
         unrelatedRestricted = await store.readModels.findInstanceById(RestrictedWithChildren, unrelatedSource);
         childOnlyAfterUnrelated = await store.readModels.findInstanceById(ChildOnlyMappings, knownSource);
@@ -173,10 +172,11 @@ describe.skipIf(!connectionString && !process.env.CI)('when opting into fromAllE
         (unrelatedRestricted === null).should.be.true;
     });
     it('should give the explicit all-event mapping precedence over fromEvery', () => allAfterStarted!.lastValue.should.equal('started'));
-    it('should apply the root all-event mapping to a child', () => {
+    it('should update the root on a child event without copying its mapping into the child', () => {
+        allAfterChild!.lastValue.should.equal('child-value');
         allAfterChild!.children.should.have.lengthOf(1);
         allAfterChild!.children[0].id.should.equal('child-one');
-        allAfterChild!.children[0].lastValue.should.equal('child-value');
+        allAfterChild!.children[0].lastValue.should.equal('');
     });
     it('should not propagate the deprecated restricted alias mapping to children', () => {
         restrictedAfterChild!.children.should.have.lengthOf(1);
@@ -186,17 +186,21 @@ describe.skipIf(!connectionString && !process.env.CI)('when opting into fromAllE
         allAfterUnrelated!.lastValue.should.equal('');
     });
     it('should leave the restricted alias unchanged on an unrelated event', () => restrictedAfterUnrelated!.lastValue.should.equal(restrictedAfterChild!.lastValue));
-    it('should apply a child-declared all-event mapping through the shared root All block', () => {
+    it('should apply a child-declared mapping on creation without changing an unmapped same-named root property', () => {
         allChildMappingsAfterChild!.children[0].lastValue.should.equal('child-value');
-        // The child event's key routes the all-event fallback to the child, not the root.
-        allChildMappingsAfterChild!.lastValue.should.equal('started');
+        allChildMappingsAfterChild!.source.should.equal(knownSource);
+        allChildMappingsAfterChild!.lastValue.should.equal('');
+    });
+    it('should update the existing child through its own All mapping on subsequent child events', () => {
+        allChildMappingsAfterUpdate!.children.should.have.lengthOf(1);
+        allChildMappingsAfterUpdate!.children[0].lastValue.should.equal('updated-child-value');
+        allChildMappingsAfterUpdate!.lastValue.should.equal('');
     });
     it('should keep the root subscription restricted when only the child declares fromAllEvents', () => {
         childOnlyAfterChild!.rootValue.should.equal('child-value');
         childOnlyAfterChild!.children[0].id.should.equal('child-one');
-        // The explicitly subscribed root From entry maps the root, not the child's shared values.
-        childOnlyAfterChild!.children[0].lastValue.should.equal('');
-        childOnlyAfterUnrelated!.rootValue.should.equal('child-value');
+        childOnlyAfterChild!.children[0].lastValue.should.equal('child-value');
+        childOnlyAfterUnrelated!.rootValue.should.equal('updated-child-value');
         (unrelatedChildOnly === null).should.be.true;
     });
 });

package/projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.spec.ts

@@ -116,13 +116,13 @@ describe('when compiling fromAllEvents on a child model', () => {
         (definition.SubscribesToAllEvents === undefined).should.be.true;
         ('SubscribesToAllEvents' in definition.Children.items).should.be.false;
     });
-    it('should collect the child mapping by bare name in the root All without subscribing to all events', () => {
+    it('should collect the mapping only in the owning child All with its full diagnostic path', () => {
         const { compiled, definition } = compileModelBound(Parent);
-        definition.All!.should.deep.equal({ Properties: { title: 'name' }, IncludeChildren: true, AutoMap: 0 });
-        definition.Children.items.All!.Properties.should.deep.equal({});
+        definition.All!.should.deep.equal({ Properties: {}, IncludeChildren: false, AutoMap: 0 });
+        definition.Children.items.All!.should.deep.equal({ Properties: { title: 'name' }, IncludeChildren: true, AutoMap: 0 });
         compiled.provenance.get(definition)!.should.include.deep.members([
-            { contractPath: 'All', declaration: '@fromAllEvents' },
-            { contractPath: 'All.Properties.title', declaration: '@fromAllEvents' }
+            { contractPath: 'Children.items.All', declaration: '@fromAllEvents' },
+            { contractPath: 'Children.items.All.Properties.title', declaration: '@fromAllEvents' }
         ]);
     });
     it('should emit the subscription only at the root when the parent opts in', () => {
@@ -131,17 +131,26 @@ describe('when compiling fromAllEvents on a child model', () => {
         const { definition } = compileModelBound(AllParent);
         definition.SubscribesToAllEvents.should.be.true;
         definition.All!.should.deep.equal({
-            Properties: { source: '$eventContext(EventSourceId)', title: 'name' }, IncludeChildren: true, AutoMap: 0
+            Properties: { source: '$eventContext(EventSourceId)' }, IncludeChildren: true, AutoMap: 0
         });
         ('SubscribesToAllEvents' in definition.Children.items).should.be.false;
     });
-    it('should share one bare-name mapping when a later child member shadows a root member', () => {
-        class AllParent extends Model { items: Child[] = []; }
-        fromAllEvents('rootName')(AllParent.prototype, 'title');
-        field(Array, { genericArguments: [Child] })(AllParent.prototype, 'items');
-        childrenFrom(Added, 'id')(AllParent.prototype, 'items');
-        compileModelBound(AllParent).definition.All!.Properties.should.deep.equal({ title: 'name' });
-    });
+    for (const childFirst of [true, false]) {
+        it(`should keep same-named root and child sources independent with child declared ${childFirst ? 'first' : 'last'}`, () => {
+            class AllParent { title = ''; items: Child[] = []; }
+            const declareChild = () => {
+                field(Array, { genericArguments: [Child] })(AllParent.prototype, 'items');
+                childrenFrom(Added, 'id')(AllParent.prototype, 'items');
+            };
+            if (childFirst) declareChild();
+            field(String)(AllParent.prototype, 'title');
+            fromAllEvents('rootName')(AllParent.prototype, 'title');
+            if (!childFirst) declareChild();
+            const { definition } = compileModelBound(AllParent);
+            definition.All!.Properties.should.deep.equal({ title: 'rootName' });
+            definition.Children.items.All!.Properties.should.deep.equal({ title: 'name' });
+        });
+    }
 });
 
 describe('when compiling fromAllEvents on nested and inherited child models', () => {
@@ -172,16 +181,35 @@ describe('when compiling fromAllEvents on nested and inherited child models', ()
     field(Detail)(Parent.prototype, 'detail');
     nested(Parent.prototype, 'detail');
 
-    it('should collect grandchild and nested mappings into the root without path prefixes or legacy child mappings', () => {
-        const { definition } = compileModelBound(Parent);
-        definition.All!.should.deep.equal({
-            Properties: { title: 'name', label: 'label', sequence: '$eventContext(SequenceNumber)' },
-            IncludeChildren: true, AutoMap: 0
-        });
+    it('should keep grandchild and nested mappings on their declaring levels including inherited fromEvery', () => {
+        const { compiled, definition } = compileModelBound(Parent);
+        definition.All!.should.deep.equal({ Properties: {}, IncludeChildren: false, AutoMap: 0 });
         (definition.SubscribesToAllEvents === undefined).should.be.true;
-        definition.Children.groups.Children.children.All!.Properties.should.deep.equal({});
-        definition.Children.groups.Children.children.Nested.detail.All!.Properties.should.deep.equal({});
-        definition.Nested.detail.All!.Properties.should.deep.equal({});
+        definition.Children.groups.All!.Properties.should.deep.equal({});
+        definition.Children.groups.Children.children.All!.Properties.should.deep.equal({ title: 'name', ignored: 'ignoredEvery' });
+        const detailMappings = { label: 'label', sequence: '$eventContext(SequenceNumber)' };
+        definition.Children.groups.Children.children.Nested.detail.All!.Properties.should.deep.equal(detailMappings);
+        definition.Nested.detail.All!.Properties.should.deep.equal(detailMappings);
+        compiled.provenance.get(definition)!.should.include.deep.members([
+            { contractPath: 'Children.groups.Children.children.All.Properties.ignored', declaration: '@fromEvery' },
+            { contractPath: 'Children.groups.Children.children.Nested.detail.All.Properties.sequence', declaration: '@fromAllEvents' },
+            { contractPath: 'Nested.detail.All.Properties.label', declaration: '@fromAllEvents' }
+        ]);
+    });
+    it('should keep a sibling fromEvery context mapping local without enabling IncludeChildren or the deprecated child alias', () => {
+        class RestrictedChild { id = ''; source = ''; ignored = ''; }
+        for (const property of ['id', 'source', 'ignored']) field(String)(RestrictedChild.prototype, property);
+        fromEvery(undefined, 'eventSourceId')(RestrictedChild.prototype, 'source');
+        fromAll('ignoredAlias')(RestrictedChild.prototype, 'ignored');
+        class RestrictedParent { items: RestrictedChild[] = []; }
+        field(Array, { genericArguments: [RestrictedChild] })(RestrictedParent.prototype, 'items');
+        childrenFrom(Added, 'id')(RestrictedParent.prototype, 'items');
+        const { definition } = compileModelBound(RestrictedParent);
+        definition.All!.should.deep.equal({ Properties: {}, IncludeChildren: false, AutoMap: 0 });
+        definition.Children.items.All!.should.deep.equal({
+            Properties: { source: '$eventContext(EventSourceId)' }, IncludeChildren: false, AutoMap: 0
+        });
+        compileModelBound(Parent).definition.Children.groups.Children.children.All!.Properties.title.should.equal('name');
     });
     it('should collect a nested-only mapping without widening the root subscription', () => {
         class NestedOnly { detail = new Detail(); }
@@ -189,9 +217,8 @@ describe('when compiling fromAllEvents on nested and inherited child models', ()
         field(Detail)(NestedOnly.prototype, 'detail');
         nested(NestedOnly.prototype, 'detail');
         const { definition } = compileModelBound(NestedOnly);
-        definition.All!.should.deep.equal({
-            Properties: { label: 'label', sequence: '$eventContext(SequenceNumber)' }, IncludeChildren: true, AutoMap: 0
-        });
+        definition.All!.should.deep.equal({ Properties: {}, IncludeChildren: false, AutoMap: 0 });
+        definition.Nested.detail.All!.Properties.should.deep.equal({ label: 'label', sequence: '$eventContext(SequenceNumber)' });
         (definition.SubscribesToAllEvents === undefined).should.be.true;
         ('SubscribesToAllEvents' in definition.Nested.detail).should.be.false;
     });

package/projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts

@@ -61,26 +61,66 @@ describe('when compiling standard fromAllEvents without explicit event subscript
         should(getFromAllEventsMetadata(Alias.prototype, 'title') === undefined).be.true;
     });
 
-    it('should collect standard child and nested mappings in the root All without widening the subscription', () => {
+    it('should collect standard child and nested mappings on their owning levels without widening the subscription', () => {
         @eventType('standard-from-all-events-child-added')
         class Added { @field(String) id = ''; }
-        class Detail { @field(String) @fromAllEvents(undefined, 'sequenceNumber') sequence = ''; }
+        class Detail {
+            @field(String) @fromAllEvents(undefined, 'sequenceNumber') sequence = '';
+            @field(String) @fromAllEvents() label = '';
+        }
         class Child {
             @field(String) id = '';
             @field(String) @fromAllEvents('name') title = '';
+            @field(String) @fromEvery('everyName') @fromAll('aliasName') restricted = '';
             @field(Detail) @nested detail = new Detail();
         }
         class Derived extends Child {}
-        class Parent {
+        class Sibling extends Child { @field(String) @fromAllEvents('siblingName') override title = ''; }
+        class Group {
             @field(Array, { genericArguments: [Derived] }) @childrenFrom(Added, 'id') items: Derived[] = [];
         }
-        const { definition } = compileModelBound(Parent);
-        should(definition.All).deep.equal({
-            Properties: { title: 'name', sequence: '$eventContext(SequenceNumber)' }, IncludeChildren: true, AutoMap: 0
-        });
+        class Parent {
+            @field(Array, { genericArguments: [Group] }) @childrenFrom(Added, 'id') groups: Group[] = [];
+            @field(Array, { genericArguments: [Sibling] }) @childrenFrom(Added, 'id') siblings: Sibling[] = [];
+            @field(Detail) @nested detail = new Detail();
+        }
+        const { compiled, definition } = compileModelBound(Parent);
+        should(definition.All).deep.equal({ Properties: {}, IncludeChildren: false, AutoMap: 0 });
         should(definition.SubscribesToAllEvents === undefined).be.true;
-        should(definition.Children.items.All!.Properties).deep.equal({});
-        should(definition.Children.items.Nested.detail.All!.Properties).deep.equal({});
+        should(definition.Children.groups.All!.Properties).deep.equal({});
+        should(definition.Children.groups.Children.items.All!.Properties).deep.equal({ title: 'name', restricted: 'everyName' });
+        should(definition.Children.siblings.All!.Properties).deep.equal({ title: 'siblingName', restricted: 'everyName' });
+        const detailMappings = { sequence: '$eventContext(SequenceNumber)', label: 'label' };
+        should(definition.Children.groups.Children.items.Nested.detail.All!.Properties).deep.equal(detailMappings);
+        should(definition.Nested.detail.All!.Properties).deep.equal(detailMappings);
+        should(compiled.provenance.get(definition)).include.deep.members([
+            { contractPath: 'Children.groups.Children.items.All.Properties.restricted', declaration: '@fromEvery' },
+            { contractPath: 'Children.groups.Children.items.Nested.detail.All.Properties.sequence', declaration: '@fromAllEvents' }
+        ]);
+    });
+
+    it('should preserve independent same-named root and child mappings in either property order', () => {
+        @eventType('standard-all-same-name-added')
+        class Added { @field(String) id = ''; }
+        class Child {
+            @field(String) id = '';
+            @field(String) @fromEvery('ignored') @fromAllEvents('childName') title = '';
+            @field(String) @fromAllEvents('childOther') @fromEvery('ignored') other = '';
+        }
+        class RootFirst {
+            @field(String) @fromAllEvents('rootName') title = '';
+            @field(Array, { genericArguments: [Child] }) @childrenFrom(Added, 'id') items: Child[] = [];
+        }
+        class ChildFirst {
+            @field(Array, { genericArguments: [Child] }) @childrenFrom(Added, 'id') items: Child[] = [];
+            @field(String) @fromAllEvents('rootName') title = '';
+        }
+        for (const type of [RootFirst, ChildFirst]) {
+            const { definition } = compileModelBound(type);
+            should(definition.All!.Properties).deep.equal({ title: 'rootName' });
+            should(definition.Children.items.All!.Properties).deep.equal({ title: 'childName', other: 'childOther' });
+            should(definition.SubscribesToAllEvents).be.true;
+        }
     });
 
     it('should reject all-event scenarios before replay with the standard decorator declaration', () => {

package/projections/modelBound/childrenAndNestedBuilder.ts

@@ -234,12 +234,14 @@ function discoverIdentifiedBy(childType: Function | undefined, eventKey: string
  * `@childrenFrom`/`@nested` properties the child/nested type itself declares.
  * @param definition - The children definition being populated.
  * @param childType - The resolved child/nested type, when available.
- * @param collectSharedMapping - Collects member mappings into the root's shared All definition.
+ * @param path - The contract path of this child or nested definition.
+ * @param collectSharedMapping - Collects member mappings into their owning All definition.
  */
 function populateFromType(
     definition: ChildrenDefinitionLike,
     childType: Function | undefined,
-    collectSharedMapping?: (prototype: object, property: string) => void
+    path: string,
+    collectSharedMapping?: (prototype: object, property: string, all: ChildrenDefinitionLike['All'], path: string) => void
 ): void {
     if (!childType) {
         return;
@@ -281,8 +283,7 @@ function populateFromType(
 
     const prototype = childType.prototype;
     const properties = TypeIntrospector.getTrackedProperties(childType);
-    // Like .NET, collect this type's members before descending into its children.
-    for (const property of properties) collectSharedMapping?.(prototype, property);
+    for (const property of properties) collectSharedMapping?.(prototype, property, definition.All, `${path}.All`);
     for (const property of properties) {
         applyPropertyMappings(prototype, property, fromByEventType);
 
@@ -307,11 +308,11 @@ function populateFromType(
 
         const childrenFromList = getChildrenFromMetadata(prototype, property);
         if (childrenFromList.length > 0) {
-            definition.Children[property] = buildChildrenEntry(childType, property, childrenFromList, collectSharedMapping);
+            definition.Children[property] = buildChildrenEntry(childType, property, childrenFromList, collectSharedMapping, `${path}.Children.${property}`);
         }
 
         if (isNested(prototype, property)) {
-            definition.Nested[property] = buildNestedEntry(childType, property, collectSharedMapping);
+            definition.Nested[property] = buildNestedEntry(childType, property, collectSharedMapping, `${path}.Nested.${property}`);
         }
     }
 
@@ -325,14 +326,16 @@ function populateFromType(
  * @param type - The class declaring the property.
  * @param property - The property name.
  * @param metadataList - The `@childrenFrom` metadata entries declared on the property (one per creating event type).
- * @param collectSharedMapping - Collects member mappings into the root's shared All definition.
+ * @param collectSharedMapping - Collects member mappings into their owning All definition.
+ * @param path - The contract path of this children definition.
  * @returns The wire-shaped children definition.
  */
 export function buildChildrenEntry(
     type: Function,
     property: string,
     metadataList: ChildrenFromMetadata[],
-    collectSharedMapping?: (prototype: object, property: string) => void
+    collectSharedMapping?: (prototype: object, property: string, all: ChildrenDefinitionLike['All'], path: string) => void,
+    path = `Children.${property}`
 ): ChildrenDefinitionLike {
     const childType = resolveChildElementType(type, property);
     const definition = createEmptyChildrenDefinition(type, childType);
@@ -352,7 +355,7 @@ export function buildChildrenEntry(
         });
     }
 
-    populateFromType(definition, childType, collectSharedMapping);
+    populateFromType(definition, childType, path, collectSharedMapping);
 
     // For non-aggregate-only creating events, populate an unmapped child identifier from
     // the creating event's key. IdentifiedBy selects the child property; it is not itself
@@ -395,13 +398,15 @@ export function buildChildrenEntry(
  * Builds the `ChildrenDefinition` for a `@nested` single-object property.
  * @param type - The class declaring the property.
  * @param property - The property name.
- * @param collectSharedMapping - Collects member mappings into the root's shared All definition.
+ * @param collectSharedMapping - Collects member mappings into their owning All definition.
+ * @param path - The contract path of this nested definition.
  * @returns The wire-shaped nested definition.
  */
 export function buildNestedEntry(
     type: Function,
     property: string,
-    collectSharedMapping?: (prototype: object, property: string) => void
+    collectSharedMapping?: (prototype: object, property: string, all: ChildrenDefinitionLike['All'], path: string) => void,
+    path = `Nested.${property}`
 ): ChildrenDefinitionLike {
     const nestedType = resolveNestedType(type, property);
     const definition = createEmptyChildrenDefinition(type, nestedType);
@@ -414,6 +419,6 @@ export function buildNestedEntry(
         definition.RemovedWith.push({ Key: eventType, Value: { Key: '$eventSourceId', ParentKey: '' } });
     }
 
-    populateFromType(definition, nestedType, collectSharedMapping);
+    populateFromType(definition, nestedType, path, collectSharedMapping);
     return definition;
 }

package/reactors/Reactors.startAtTail.spec.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactorMessage } from '@cratis/chronicle.contracts';
+import { describe, expect, it } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import type { IEventLog } from '../eventSequences/IEventLog.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { reactor } from './reactor.js';
+import { Reactors } from './Reactors.js';
+import { startAtTail } from './startAtTail.js';
+
+@eventType('start-at-tail-event')
+class SomethingHappened {
+    constructor(readonly value: string = '') {}
+}
+
+@reactor('starts-at-tail')
+@startAtTail()
+class StartsAtTail {
+    somethingHappened() {}
+}
+
+@reactor('starts-at-the-beginning')
+class StartsAtTheBeginning {
+    somethingHappened() {}
+}
+
+async function registrationOf(type: Function) {
+    const lifecycle = new ConnectionLifecycle();
+    let registration!: ReactorMessage;
+    let received!: () => void;
+    const registered = new Promise<void>(resolve => { received = resolve; });
+    async function* stream(queue: AsyncIterable<ReactorMessage>) {
+        registration = (await queue[Symbol.asyncIterator]().next()).value!;
+        received();
+        await new Promise(() => {});
+    }
+    const connection = { reactors: { observe: stream } } as unknown as ChronicleConnection;
+    const artifacts = { reactors: [type], eventTypes: [SomethingHappened] } as unknown as IClientArtifactsProvider;
+    const reactors = new Reactors(artifacts, connection, 'store', 'tenant', lifecycle, {} as IEventLog);
+    await reactors.register();
+    await registered;
+    reactors.dispose();
+    return registration.Content?.Value0?.Reactor;
+}
+
+describe('when registering a reactor marked to start at the tail', () => {
+    it('asks the kernel to begin at the tail', async () => {
+        expect((await registrationOf(StartsAtTail))?.StartAtTail).toBe(true);
+    });
+});
+
+describe('when registering a reactor that is not marked', () => {
+    it('does not ask the kernel to skip history', async () => {
+        expect((await registrationOf(StartsAtTheBeginning))?.StartAtTail).toBe(false);
+    });
+});

package/reactors/Reactors.ts

@@ -22,6 +22,7 @@ import { IReactors } from './IReactors.js';
 import { dispatchReactorSideEffects } from './ReactorSideEffects.js';
 import { getReactorMetadata } from './reactor.js';
 import { isOnceOnly } from './onceOnly.js';
+import { isStartAtTail } from './startAtTail.js';
 import { getReactorEventTypes, selectReactorHandler, invokeReactorHandler } from './ReactorDispatcher.js';
 import type { ReactorEventTypeEntry } from './ReactorDispatcher.js';
 import type { ReactorResultHandler } from './ReactorResultHandler.js';
@@ -277,6 +278,7 @@ export class Reactors implements IReactors {
                         })),
                         IsReplayable: !isOnceOnly(reactorType),
                         IsNotReplayable: isOnceOnly(reactorType),
+                        StartAtTail: isStartAtTail(reactorType),
                         GenerationDelivery: EventGenerationDelivery.Compatibility,
                         Tags: getTagsFor(reactorType).map(t => t.value),
                         Filters: {

package/reactors/for_Reactors/against_a_kernel/when_starting_at_the_tail.integration.spec.ts

@@ -0,0 +1,107 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import { reactor } from '../../reactor.js';
+import { startAtTail } from '../../startAtTail.js';
+
+chai.should();
+
+// Runs against a real Chronicle kernel; skipped locally unless the connection string is set (see vitest.integration.config.ts).
+// In CI it never skips, so a missing connection string or unreachable kernel fails instead of passing vacuously.
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class SomethingHappenedBeforeRegistration {
+    @field(String) name = '';
+}
+
+// The client constructs reactor instances; share sinks for assertions across that boundary.
+const fromTheTail: string[] = [];
+const fromTheBeginning: string[] = [];
+
+@reactor()
+@startAtTail()
+class TailReactor {
+    somethingHappenedBeforeRegistration(event: SomethingHappenedBeforeRegistration) { fromTheTail.push(event.name); }
+}
+
+// The control: the same registration without the marker catches up on all history.
+@reactor()
+class HistoryReactor {
+    somethingHappenedBeforeRegistration(event: SomethingHappenedBeforeRegistration) { fromTheBeginning.push(event.name); }
+}
+
+const artifactsWith = (reactors: Function[]): IClientArtifactsProvider => ({
+    eventTypes: [SomethingHappenedBeforeRegistration],
+    readModels: [],
+    reactors,
+    reducers: [],
+    seeders: [],
+    constraints: [],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+});
+
+async function eventually(accept: () => boolean, timeoutMs = 30_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (!accept()) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when registering a reactor marked to start at the tail against a kernel', () => {
+    const storeName = `StartAtTail${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const clients: ChronicleClient[] = [];
+
+    const newClient = (reactors: Function[]) => {
+        const client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifactsWith(reactors)
+        }));
+        clients.push(client);
+        return client;
+    };
+
+    beforeAll(async () => {
+        // History exists before either reactor has ever been registered.
+        const writer = await newClient([]).getEventStore(storeName);
+        for (const name of ['one', 'two', 'three']) {
+            const appended = await writer.eventLog.append(randomUUID(), Object.assign(new SomethingHappenedBeforeRegistration(), { name }));
+            appended.isSuccess.should.be.true;
+        }
+
+        const reader = await newClient([TailReactor, HistoryReactor]).getEventStore(storeName);
+
+        // The control proves the history was deliverable, so the tail reactor's silence is not vacuous.
+        await eventually(() => fromTheBeginning.length === 3);
+
+        const appended = await reader.eventLog.append(randomUUID(), Object.assign(new SomethingHappenedBeforeRegistration(), { name: 'after' }));
+        appended.isSuccess.should.be.true;
+        await eventually(() => fromTheTail.length === 1 && fromTheBeginning.length === 4);
+    });
+
+    afterAll(() => clients.forEach(client => client.dispose()));
+
+    it('should not deliver history that predates its registration', () => {
+        fromTheTail.should.not.include.members(['one', 'two', 'three']);
+    });
+
+    it('should deliver what is appended afterwards', () => {
+        fromTheTail.should.deep.equal(['after']);
+    });
+
+    it('should leave a reactor that is not marked to catch up on all history', () => {
+        // Each event has its own event source, so the kernel may deliver the partitions in any order.
+        [...fromTheBeginning].sort().should.deep.equal(['after', 'one', 'three', 'two']);
+    });
+});