@cratis/chronicle 6.9.1 → 6.11.0

package/eventSequences/EventSequence.spec.ts

@@ -558,6 +558,81 @@ describe('EventSequence', () => {
             const options = waitForCompletion.mock.calls[0][1];
             expect(options.signal).toBeInstanceOf(AbortSignal);
         });
+
+        it('should clear the timeout after completion', async () => {
+            vi.useFakeTimers();
+            try {
+                const appendResult = await eventSequence.append('some-event-source', new SomethingHappened('a'));
+                await appendResult.waitForCompletion({ timeoutMs: 1000 });
+                expect(vi.getTimerCount()).toBe(0);
+            } finally {
+                vi.useRealTimers();
+            }
+        });
+    });
+
+    describe('when a caller cancels a completion wait', () => {
+        it('should reject a pre-aborted signal without starting the RPC or a timer', async () => {
+            const { eventSequence, waitForCompletion } = createEventSequence();
+            const appendResult = await eventSequence.append('some-event-source', new SomethingHappened('a'));
+            const controller = new AbortController();
+            const reason = new Error('already canceled');
+            controller.abort(reason);
+            vi.useFakeTimers();
+            try {
+                await expect(appendResult.waitForCompletion({ signal: controller.signal })).rejects.toBe(reason);
+                expect(waitForCompletion).not.toHaveBeenCalled();
+                expect(vi.getTimerCount()).toBe(0);
+            } finally {
+                vi.useRealTimers();
+            }
+        });
+
+        it('should abort the underlying RPC and reject with the caller reason', async () => {
+            const waitForCompletion = vi.fn().mockImplementation((_request, { signal }: { signal: AbortSignal }) =>
+                new Promise((_resolve, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true })));
+            const { eventSequence } = createEventSequence({}, { waitForCompletion });
+            const appendResult = await eventSequence.append('some-event-source', new SomethingHappened('a'));
+            const controller = new AbortController();
+            const reason = new Error('caller canceled');
+            const pending = appendResult.waitForCompletion({ timeoutMs: 1000, signal: controller.signal });
+            const signal = waitForCompletion.mock.calls[0][1].signal as AbortSignal;
+
+            controller.abort(reason);
+
+            await expect(pending).rejects.toBe(reason);
+            expect(signal.aborted).toBe(true);
+            expect(signal.reason).toBe(reason);
+        });
+
+        it('should clear the timeout when the caller aborts', async () => {
+            const waitForCompletion = vi.fn().mockImplementation((_request, { signal }: { signal: AbortSignal }) =>
+                new Promise((_resolve, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true })));
+            const { eventSequence } = createEventSequence({}, { waitForCompletion });
+            const appendResult = await eventSequence.append('some-event-source', new SomethingHappened('a'));
+            const controller = new AbortController();
+            vi.useFakeTimers();
+            try {
+                const pending = appendResult.waitForCompletion({ timeoutMs: 1000, signal: controller.signal });
+                expect(vi.getTimerCount()).toBe(1);
+                const reason = new Error('caller canceled');
+                controller.abort(reason);
+                await expect(pending).rejects.toBe(reason);
+                expect(vi.getTimerCount()).toBe(0);
+            } finally {
+                vi.useRealTimers();
+            }
+        });
+
+        it('should cancel the underlying RPC when the options timeout expires', async () => {
+            const waitForCompletion = vi.fn().mockImplementation((_request, { signal }: { signal: AbortSignal }) =>
+                new Promise((_resolve, reject) => signal.addEventListener('abort', () => reject(signal.reason), { once: true })));
+            const { eventSequence } = createEventSequence({}, { waitForCompletion });
+            const appendResult = await eventSequence.append('some-event-source', new SomethingHappened('a'));
+
+            await expect(appendResult.waitForCompletion({ timeoutMs: 5 })).rejects.toMatchObject({ name: 'TimeoutError' });
+            expect(waitForCompletion.mock.calls[0][1].signal.aborted).toBe(true);
+        });
     });
 
     describe('when waiting for completion and observers report a failed partition', () => {
@@ -577,7 +652,7 @@ describe('EventSequence', () => {
 
         it('should report failure with the failed partitions', async () => {
             const appendResult = await eventSequence.append('some-event-source', new SomethingHappened('a'));
-            const result = await appendResult.waitForCompletion();
+            const result = await appendResult.waitForCompletion({ timeoutMs: 1234 });
 
             expect(result.isSuccess).toBe(false);
             expect(result.failedPartitions).toHaveLength(1);

package/eventSequences/EventSequence.ts

@@ -29,6 +29,7 @@ import { EventSequenceId } from './EventSequenceId.js';
 import { EventSequenceNumber } from './EventSequenceNumber.js';
 import { TransactionalEventSequence } from './TransactionalEventSequence.js';
 import { WaitForCompletionResult } from './WaitForCompletionResult.js';
+import type { WaitForCompletionOptions } from './WaitForCompletionOptions.js';
 
 /** Default timeout for {@link AppendResult.waitForCompletion}, matching the C# client's default. */
 const DEFAULT_WAIT_FOR_COMPLETION_TIMEOUT_MS = 5000;
@@ -725,7 +726,7 @@ export class EventSequence implements IEventSequence {
             concurrencyViolation: mappedConcurrencyViolation,
             errors: mappedErrors,
             isSuccess,
-            waitForCompletion: (timeoutMs?: number) => this.waitForObserverCompletion(eventSequenceNumber, isSuccess, timeoutMs)
+            waitForCompletion: (options?: number | WaitForCompletionOptions) => this.waitForObserverCompletion(eventSequenceNumber, isSuccess, options)
         };
     }
 
@@ -736,25 +737,38 @@ export class EventSequence implements IEventSequence {
     private async waitForObserverCompletion(
         tailSequenceNumber: EventSequenceNumber,
         appendWasSuccessful: boolean,
-        timeoutMs = DEFAULT_WAIT_FOR_COMPLETION_TIMEOUT_MS
+        options: number | WaitForCompletionOptions = DEFAULT_WAIT_FOR_COMPLETION_TIMEOUT_MS
     ): Promise<WaitForCompletionResult> {
         if (!appendWasSuccessful) {
             return { isSuccess: true, failedPartitions: [] };
         }
 
-        const response = await this._connection.observers.waitForCompletion(
-            {
-                EventStore: this._eventStoreName,
-                Namespace: this._namespace,
-                EventSequenceId: this.id.value,
-                TailEventSequenceNumber: tailSequenceNumber.value
-            },
-            { signal: AbortSignal.timeout(timeoutMs) });
+        const timeoutMs = typeof options === 'number' ? options : options.timeoutMs ?? DEFAULT_WAIT_FOR_COMPLETION_TIMEOUT_MS;
+        const callerSignal = typeof options === 'number' ? undefined : options.signal;
+        if (callerSignal?.aborted) throw callerSignal.reason;
+
+        const controller = new AbortController();
+        const forwardAbort = () => controller.abort(callerSignal?.reason);
+        callerSignal?.addEventListener('abort', forwardAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError')), timeoutMs);
+        try {
+            const response = await this._connection.observers.waitForCompletion(
+                {
+                    EventStore: this._eventStoreName,
+                    Namespace: this._namespace,
+                    EventSequenceId: this.id.value,
+                    TailEventSequenceNumber: tailSequenceNumber.value
+                },
+                { signal: controller.signal });
 
-        return {
-            isSuccess: response.IsSuccess,
-            failedPartitions: (response.FailedPartitions ?? []).map(failedPartition => toClientFailedPartition(failedPartition))
-        };
+            return {
+                isSuccess: response.IsSuccess,
+                failedPartitions: (response.FailedPartitions ?? []).map(failedPartition => toClientFailedPartition(failedPartition))
+            };
+        } finally {
+            clearTimeout(timer);
+            callerSignal?.removeEventListener('abort', forwardAbort);
+        }
     }
 
     private toContractConcurrencyScope(scope?: ConcurrencyScope) {
@@ -776,12 +790,6 @@ export class EventSequence implements IEventSequence {
     }
 }
 
-/**
- * Converts a RFC 4122 Guid string into the protobuf Guid shape used by Chronicle contracts.
- * @param guid - The Guid to convert.
- * @returns The converted protobuf Guid with fixed64-safe hi/lo values.
- */
-
 /**
  * Converts an {@link Identity} into the CausedBy shape used by Chronicle contracts.
  * @param identity - The identity to convert.

package/eventSequences/WaitForCompletionOptions.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Options for waiting until observers complete an append. */
+export interface WaitForCompletionOptions {
+    /** Timeout in milliseconds. Defaults to 5000 (5 seconds). */
+    readonly timeoutMs?: number;
+
+    /** Cancels the underlying wait RPC when aborted. */
+    readonly signal?: AbortSignal;
+}

package/eventSequences/index.ts

@@ -14,6 +14,7 @@ export type { CompleteStreamResult } from './CompleteStreamResult.js';
 export type { ConcurrencyScope } from './ConcurrencyScope.js';
 export type { EventForEventSourceId } from './EventForEventSourceId.js';
 export type { WaitForCompletionResult } from './WaitForCompletionResult.js';
+export type { WaitForCompletionOptions } from './WaitForCompletionOptions.js';
 export type { IEventSequence } from './IEventSequence.js';
 export type { IEventLog } from './IEventLog.js';
 export type { ITransactionalEventSequence } from './ITransactionalEventSequence.js';

package/externalServices/ExternalServiceBuilder.ts

@@ -2,11 +2,11 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import {
-    ExternalServiceDefinition,
-    ExternalServiceEndpoint,
+    type ExternalServiceDefinition,
+    type ExternalServiceEndpoint,
     ExternalServiceEndpointType,
-    OneOfBasicAuthorizationBearerTokenAuthorizationOAuthAuthorization
-} from './ExternalServicesContracts.js';
+    type OneOfBasicAuthorizationBearerTokenAuthorizationOAuthAuthorization
+} from '@cratis/chronicle.contracts';
 import { IExternalServiceBuilder } from './IExternalServiceBuilder.js';
 
 /**

package/externalServices/ExternalServices.spec.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AddExternalServicesRequest, ExternalServiceEndpointType } from '@cratis/chronicle.contracts';
+import { describe, expect, it, vi } from 'vitest';
+import type { ChronicleConnection } from '../connection/index.js';
+import { ChronicleCallFailed } from '../connection/callResults.js';
+import type { IExternalServiceBuilder } from './IExternalServiceBuilder.js';
+import { ExternalServices } from './ExternalServices.js';
+
+function createServices(result = { IsAuthorized: true, ValidationResults: [], ExceptionMessages: [], AuthorizationFailureReason: '' }) {
+    const addExternalServices = vi.fn().mockResolvedValue(result);
+    const connection = { externalServices: { addExternalServices } } as unknown as ChronicleConnection;
+    return { services: new ExternalServices('my-event-store', connection), addExternalServices };
+}
+
+async function requestFor(configure: (builder: IExternalServiceBuilder) => void): Promise<AddExternalServicesRequest> {
+    const { services, addExternalServices } = createServices();
+    await services.register('Customers', configure);
+    expect(addExternalServices).toHaveBeenCalledTimes(1);
+    // Round-trip through the generated codec to assert the actual wire request, not just the in-memory object.
+    const request = AddExternalServicesRequest.fromPartial(addExternalServices.mock.calls[0][0]);
+    return AddExternalServicesRequest.decode(AddExternalServicesRequest.encode(request).finish());
+}
+
+describe('ExternalServices registration', () => {
+    it('sends an HTTP bearer endpoint with headers', async () => {
+        expect(await requestFor(builder => builder.http('https://example.com')
+            .withBearerToken('secret').withHeader('X-Tenant', 'acme').withHeader('X-Trace', 'enabled'))).toEqual({
+            EventStore: 'my-event-store',
+            ExternalServices: [{
+                Id: 'Customers', Name: 'Customers', Endpoint: {
+                    Type: ExternalServiceEndpointType.Http,
+                    Http: {
+                        Url: 'https://example.com', Headers: { 'X-Tenant': 'acme', 'X-Trace': 'enabled' },
+                        Authorization: { Value0: undefined, Value1: { Token: 'secret' }, Value2: undefined }
+                    },
+                    Database: undefined
+                }
+            }]
+        });
+    });
+
+    it('sends basic authorization', async () => {
+        const request = await requestFor(builder => builder.http('https://example.com').withBasicAuth('user', 'password'));
+        expect(request.ExternalServices[0].Endpoint?.Http?.Authorization).toEqual({
+            Value0: { Username: 'user', Password: 'password' }, Value1: undefined, Value2: undefined
+        });
+        expect(request.ExternalServices[0].Endpoint?.Http?.Headers).toEqual({});
+    });
+
+    it('sends OAuth authorization', async () => {
+        const request = await requestFor(builder => builder.http('https://example.com').withOAuth('https://auth', 'client', 'secret'));
+        expect(request.ExternalServices[0].Endpoint?.Http?.Authorization).toEqual({
+            Value0: undefined, Value1: undefined,
+            Value2: { Authority: 'https://auth', ClientId: 'client', ClientSecret: 'secret' }
+        });
+    });
+
+    it.each([
+        ['msSql', ExternalServiceEndpointType.MsSql, 1433],
+        ['postgreSql', ExternalServiceEndpointType.PostgreSql, 5432]
+    ] as const)('sends %s with a port and options', async (method, type, port) => {
+        const request = await requestFor(builder => builder[method]('db.example.com', 'customers', 'user', 'password', port)
+            .withOption('sslmode', 'require'));
+        expect(request.ExternalServices[0]).toEqual({
+            Id: 'Customers', Name: 'Customers', Endpoint: {
+                Type: type, Http: undefined,
+                Database: {
+                    Host: 'db.example.com', Port: port, Database: 'customers',
+                    Username: 'user', Password: 'password', Options: { sslmode: 'require' }
+                }
+            }
+        });
+    });
+
+    it('rejects a failed command result', async () => {
+        const { services } = createServices({
+            IsAuthorized: true, ValidationResults: [{ Message: 'invalid endpoint', Members: ['Endpoint'] }],
+            ExceptionMessages: [], AuthorizationFailureReason: ''
+        });
+        await expect(services.register('Customers', builder => builder.http('https://example.com')))
+            .rejects.toThrow(ChronicleCallFailed);
+        await expect(services.register('Customers', builder => builder.http('https://example.com')))
+            .rejects.toThrow(/register external service.*invalid endpoint/);
+    });
+});

package/externalServices/ExternalServices.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { ChronicleConnection } from '../connection/index.js';
+import { ensureCommandSuccess } from '../connection/callResults.js';
 import { ExternalServiceBuilder } from './ExternalServiceBuilder.js';
 import { IExternalServiceBuilder } from './IExternalServiceBuilder.js';
 import { IExternalServices } from './IExternalServices.js';
@@ -26,9 +27,10 @@ export class ExternalServices implements IExternalServices {
         configure(builder);
         const definition = builder.build(name, name);
 
-        await this._connection.externalServices.add({
+        const result = await this._connection.externalServices.addExternalServices({
             EventStore: this._eventStore,
             ExternalServices: [definition]
         });
+        ensureCommandSuccess('register external service', result);
     }
 }

package/for_ChronicleClient/connectionAuthentication.spec.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ChronicleClient } from '../ChronicleClient.js';
+import { ChronicleOptions } from '../ChronicleOptions.js';
+import { RejectedChronicleCredentials } from '../connection/RejectedChronicleCredentials.js';
+
+const transport = vi.hoisted(() => ({ connect: vi.fn(), resetChannel: vi.fn(), disconnect: vi.fn(), getVersionInfo: vi.fn(), allEventStores: vi.fn() }));
+vi.mock('../connection/ChronicleConnection.js', () => ({
+    ChronicleConnection: class {
+        connect = transport.connect;
+        resetChannel = transport.resetChannel;
+        disconnect = transport.disconnect;
+        server = { getVersionInfo: transport.getVersionInfo };
+        eventStores = { allEventStores: transport.allEventStores };
+    }
+}));
+vi.mock('../connection/KernelKeepAlive.js', () => ({ KernelKeepAlive: class { async start() {} } }));
+
+let client: ChronicleClient;
+beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    transport.connect.mockResolvedValue(undefined);
+    transport.resetChannel.mockResolvedValue(undefined);
+    transport.getVersionInfo.mockResolvedValue({});
+    transport.allEventStores.mockResolvedValue({ IsAuthorized: true, Data: [] });
+    client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { discoveryPatterns: [] }));
+});
+afterEach(() => { client.dispose(); vi.useRealTimers(); });
+
+describe('client authentication recovery', () => {
+    it('connects when an anonymous kernel accepts calls despite an unavailable token endpoint', async () => {
+        await expect(client.getEventStores()).resolves.toEqual([]);
+        expect(transport.connect).toHaveBeenCalledTimes(1);
+    });
+
+    it('preserves a typed terminal error when an established call enters withReconnect', async () => {
+        await client.getEventStores();
+        transport.allEventStores.mockRejectedValue(new RejectedChronicleCredentials('rejected'));
+        await expect(client.getEventStores()).rejects.toBeInstanceOf(RejectedChronicleCredentials);
+        await expect(client.getEventStores()).rejects.toThrow('rejected');
+        expect(transport.connect).toHaveBeenCalledTimes(1);
+    });
+
+    it('makes a terminal error on the retried call permanent', async () => {
+        await client.getEventStores();
+        const rejection = new RejectedChronicleCredentials('rejected after reconnect');
+        transport.allEventStores.mockRejectedValueOnce(Object.assign(new Error('unavailable'), { code: 14 }))
+            .mockRejectedValueOnce(rejection);
+        await expect(client.getEventStores()).rejects.toBe(rejection);
+        const calls = transport.allEventStores.mock.calls.length;
+        await expect(client.getEventStores()).rejects.toBe(rejection);
+        expect(transport.allEventStores).toHaveBeenCalledTimes(calls);
+    });
+
+    it('continues retrying a network outage until disposed', async () => {
+        transport.connect.mockRejectedValue(new Error('UNAVAILABLE: connection refused'));
+        const pending = client.getEventStores().then(() => undefined, error => error as Error);
+        await vi.advanceTimersByTimeAsync(4500);
+        expect(transport.connect.mock.calls.length).toBeGreaterThan(1);
+        client.dispose();
+        await vi.runAllTimersAsync();
+        expect((await pending).message).toMatch(/disposed/);
+    });
+});

package/index.ts

@@ -27,6 +27,7 @@ import * as confidentiality from './confidentiality/index.js';
 
 export { ChronicleClient } from './ChronicleClient.js';
 export { IncompatibleChronicleServer } from './connection/IncompatibleChronicleServer.js';
+export { RejectedChronicleCredentials } from './connection/RejectedChronicleCredentials.js';
 export type { IChronicleClient } from './IChronicleClient.js';
 export { ChronicleOptions } from './ChronicleOptions.js';
 export { EventStore } from './EventStore.js';

package/observation/observationDisposal.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import { ChronicleClient } from '../ChronicleClient.js';
+import { ChronicleOptions } from '../ChronicleOptions.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import type { EventStore } from '../EventStore.js';
+import type { IEventLog } from '../eventSequences/IEventLog.js';
+import { Reactors } from '../reactors/Reactors.js';
+import { reactor } from '../reactors/reactor.js';
+import { Reducers } from '../reducers/Reducers.js';
+import { reducer } from '../reducers/reducer.js';
+
+class ExampleReactor {}
+reactor('disposal-reactor')(ExampleReactor);
+class ExampleReducer {}
+reducer('disposal-reducer')(ExampleReducer);
+
+const artifacts = {
+    reactors: [ExampleReactor as Constructor], reducers: [ExampleReducer as Constructor],
+    eventTypes: [], readModels: []
+} as unknown as IClientArtifactsProvider;
+
+function stream() {
+    const signals: AbortSignal[] = [];
+    const observe = vi.fn((_queue: AsyncIterable<unknown>, options: { signal: AbortSignal }) => {
+        signals.push(options.signal);
+        return {
+            async *[Symbol.asyncIterator]() {
+                await new Promise<void>(resolve => options.signal.addEventListener('abort', () => resolve(), { once: true }));
+            }
+        };
+    });
+    return { observe, signals };
+}
+
+describe('observation disposal', () => {
+    it('aborts reactor and reducer streams even without a connected lifecycle and prevents re-observation', async () => {
+        const reactorStream = stream();
+        const reducerStream = stream();
+        const connection = {
+            reactors: { observe: reactorStream.observe }, reducers: { observe: reducerStream.observe },
+            readModels: { registerMany: vi.fn().mockResolvedValue({}) }
+        } as unknown as ChronicleConnection;
+        const lifecycle = new ConnectionLifecycle();
+        const reactors = new Reactors(artifacts, connection, 'store', 'Default', lifecycle, {} as IEventLog);
+        const reducers = new Reducers(artifacts, connection, 'store', 'Default', lifecycle, 'sink');
+        await reactors.register();
+        await reducers.register();
+        expect(reactorStream.observe).toHaveBeenCalledOnce();
+        expect(reducerStream.observe).toHaveBeenCalledOnce();
+
+        reactors.dispose();
+        reducers.dispose();
+        expect(reactorStream.signals[0].aborted).toBe(true);
+        expect(reducerStream.signals[0].aborted).toBe(true);
+        await reactors.register();
+        await reducers.register();
+        expect(reactorStream.observe).toHaveBeenCalledOnce();
+        expect(reducerStream.observe).toHaveBeenCalledOnce();
+    });
+
+    it('disposes cached store observations even when the lifecycle is not connected', () => {
+        const client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { discoveryPatterns: [] }));
+        const disposeObservations = vi.fn();
+        (client as unknown as { _stores: Map<string, EventStore> })._stores.set('store/Default', { disposeObservations } as unknown as EventStore);
+        client.dispose();
+        expect(disposeObservations).toHaveBeenCalledOnce();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.9.1",
+    "version": "6.11.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -170,6 +170,7 @@
         "@cratis/chronicle.contracts": "19.4.0",
         "@grpc/grpc-js": "^1.14.4",
         "@opentelemetry/api": "^1.9.1",
+        "glob": "^13.0.6",
         "nice-grpc": "^2.1.17",
         "nice-grpc-common": "^2.0.4",
         "reflect-metadata": "^0.2.2",

package/projections/Projections.childrenAndNested.spec.ts

@@ -167,6 +167,7 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
             const summary = definition.Nested.summary;
 
+            expect(summary.IdentifiedBy).toBe('*NotSet*');
             const updateEntry = summary.From.find(candidate => candidate.Key.Id === 'SummaryUpdated')!;
             expect(updateEntry.Value.Properties.total).toBe('total');
             expect(summary.RemovedWith.some(candidate => candidate.Key.Id === 'SummaryCleared')).toBe(true);
@@ -179,6 +180,7 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
             const note = definition.Nested.note;
 
+            expect(note.IdentifiedBy).toBe('*NotSet*');
             const updateEntry = note.From.find(candidate => candidate.Key.Id === 'NoteAdded')!;
             expect(updateEntry.Value.Properties.text).toBe('text');
             expect(note.RemovedWith.some(candidate => candidate.Key.Id === 'NoteCleared')).toBe(true);

package/projections/Projections.modelBoundCompleteness.spec.ts

@@ -12,7 +12,9 @@ import { eventLog, eventSequence } from './modelBound/eventSequence.js';
 import { fromAll } from './modelBound/fromAll.js';
 import { fromEvent } from './modelBound/fromEvent.js';
 import { noAutoMap } from './modelBound/noAutoMap.js';
+import { join } from './modelBound/join.js';
 import { setFrom } from './modelBound/setFrom.js';
+import { setValue } from './modelBound/setValue.js';
 import { Projections } from './Projections.js';
 
 // Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
@@ -112,6 +114,28 @@ setFrom(MbProjectNoted, 'note')(MbProjectNotes.prototype, 'note');
 clearWith(MbProjectNoteCleared)(MbProjectNotes.prototype, 'note');
 fromEvent(MbProjectNoted)(MbProjectNotes);
 
+class MbConstants {
+    active!: boolean;
+    status!: string;
+    total!: number;
+    started!: Date;
+    cleared!: string | null;
+    wrapped!: string;
+}
+setValue(MbProjectNoted, true)(MbConstants.prototype, 'active');
+setValue(MbProjectNoted, 'on-loan')(MbConstants.prototype, 'status');
+setValue(MbProjectNoted, 2.5)(MbConstants.prototype, 'total');
+setValue(MbProjectNoted, new Date('2025-01-02T03:04:05.006Z'))(MbConstants.prototype, 'started');
+setValue(MbProjectNoted, null)(MbConstants.prototype, 'cleared');
+setValue(MbProjectNoted, { value: 'wrapped' })(MbConstants.prototype, 'wrapped');
+fromEvent(MbProjectNoted, { constantKey: 'singleton' })(MbConstants);
+
+class MbJoinedNote {
+    id!: string;
+    note!: string;
+}
+join(MbProjectNoted)(MbJoinedNote.prototype, 'note');
+
 interface BuiltFromEntry {
     Key: { Id: string };
     Value: { Properties: Record<string, string>; Key: string; ParentKey: string };
@@ -121,6 +145,7 @@ interface BuiltDefinition {
     EventSequenceId: string;
     AutoMap: AutoMap;
     NoAutoMapProperties: string[];
+    Join: Array<{ Value: { On: string } }>;
     All: { Properties: Record<string, string> };
     From: BuiltFromEntry[];
 }
@@ -208,6 +233,28 @@ describe('Projections model-bound completeness', () => {
         });
     });
 
+    describe('when a property is set to a constant', () => {
+        it('should send value and null expressions for model-bound mappings', async () => {
+            const definition = await registerAndGetDefinition(MbConstants);
+            expect(findFromEntry(definition, 'MbProjectNoted').Value.Properties).toMatchObject({
+                active: '$value(true)',
+                status: '$value(on-loan)',
+                total: '$value(2.5)',
+                started: '$value(2025-01-02T03:04:05.006Z)',
+                cleared: '$null',
+                wrapped: '$value(wrapped)'
+            });
+            expect(findFromEntry(definition, 'MbProjectNoted').Value.Key).toBe('$value(singleton)');
+        });
+    });
+
+    describe('when a model-bound join has no explicit on property', () => {
+        it('should use the mapped property as the join path', async () => {
+            const definition = await registerAndGetDefinition(MbJoinedNote);
+            expect(definition.Join[0].Value.On).toBe('note');
+        });
+    });
+
     describe('when a root scalar property is cleared with an event', () => {
         it('should add a $null mapping for that property on the clearing event', async () => {
             const definition = await registerAndGetDefinition(MbProjectNotes);