@cratis/chronicle 6.31.0 → 6.31.1

package/events/constraints/for_Constraints/against_a_kernel/when_appending_unique_values_concurrently.integration.spec.ts

@@ -0,0 +1,189 @@
+// 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 type { AppendResult } from '../../../../eventSequences/index.js';
+import type { IEventStore } from '../../../../IEventStore.js';
+import { eventType } from '../../../eventTypeDecorator.js';
+import { constraint } from '../../constraint.js';
+import type { IConstraint } from '../../IConstraint.js';
+import type { IConstraintBuilder } from '../../IConstraintBuilder.js';
+import { unique } from '../../unique.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;
+
+const constraintName = 'UniqueUserName';
+const constraintMessage = 'The user name is already taken';
+
+@eventType()
+class UserRegistered {
+    @field(String) userName = '';
+}
+
+@eventType()
+class UserRemoved {
+    @field(String) userName = '';
+}
+
+@eventType()
+@unique('OneAccountPerUser', 'The user already has an account')
+class AccountOpened {
+    @field(String) accountName = '';
+}
+
+@constraint(constraintName)
+class UniqueUserName implements IConstraint {
+    define(builder: IConstraintBuilder): void {
+        builder.unique(_ => _
+            .on(UserRegistered, e => e.userName)
+            .removedWith(UserRemoved)
+            .withMessage(constraintMessage));
+    }
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [UserRegistered, UserRemoved, AccountOpened],
+    readModels: [],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [UniqueUserName],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+const registered = (userName: string) => Object.assign(new UserRegistered(), { userName });
+const opened = (accountName: string) => Object.assign(new AccountOpened(), { accountName });
+const createClient = () => new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+    discoveryPatterns: [],
+    clientArtifactsProvider: artifacts
+}));
+
+function shouldHaveExactlyOneWinner(results: AppendResult[], name: string, message: string) {
+    results.filter(_ => _.isSuccess).length.should.equal(1);
+    const losers = results.filter(_ => !_.isSuccess);
+    losers.length.should.equal(results.length - 1);
+    for (const loser of losers) {
+        loser.constraintViolations.length.should.equal(1);
+        loser.constraintViolations[0].constraintId.should.equal(name);
+        loser.constraintViolations[0].message.should.equal(message);
+    }
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when appending unique values concurrently against a kernel', () => {
+    const storeName = `Unique${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    let first: ChronicleClient;
+    let second: ChronicleClient;
+    let store: IEventStore;
+    let otherClientStore: IEventStore;
+
+    beforeAll(async () => {
+        first = createClient();
+        second = createClient();
+        store = await first.getEventStore(storeName);
+        otherClientStore = await second.getEventStore(storeName);
+    });
+
+    afterAll(() => {
+        first?.dispose();
+        second?.dispose();
+    });
+
+    it('lets exactly one of two clients claim the same value on different event sources', async () => {
+        const results = await Promise.all([
+            store.eventLog.append(randomUUID(), registered('alice')),
+            otherClientStore.eventLog.append(randomUUID(), registered('alice'))
+        ]);
+        shouldHaveExactlyOneWinner(results, constraintName, constraintMessage);
+    });
+
+    it('lets exactly one of many parallel appends claim the same value', async () => {
+        const results = await Promise.all(Array.from({ length: 10 }, () => store.eventLog.append(randomUUID(), registered('bob'))));
+        shouldHaveExactlyOneWinner(results, constraintName, constraintMessage);
+    });
+
+    it('lets exactly one of two parallel appends open an account on the same event source', async () => {
+        const eventSourceId = randomUUID();
+        const results = await Promise.all([
+            store.eventLog.append(eventSourceId, opened('checking')),
+            otherClientStore.eventLog.append(eventSourceId, opened('savings'))
+        ]);
+        shouldHaveExactlyOneWinner(results, 'OneAccountPerUser', 'The user already has an account');
+    });
+
+    it('lets parallel appends open accounts on separate event sources', async () => {
+        const results = await Promise.all([
+            store.eventLog.append(randomUUID(), opened('checking')),
+            otherClientStore.eventLog.append(randomUUID(), opened('checking'))
+        ]);
+        results.every(_ => _.isSuccess).should.be.true;
+    });
+
+    it('lets the same value be claimed once in each namespace', async () => {
+        const [tenantA, tenantB] = await Promise.all([
+            first.getEventStore(storeName, `a${randomUUID().slice(0, 8)}`),
+            second.getEventStore(storeName, `b${randomUUID().slice(0, 8)}`)
+        ]);
+        const results = await Promise.all([
+            tenantA.eventLog.append(randomUUID(), registered('carol')),
+            tenantB.eventLog.append(randomUUID(), registered('carol'))
+        ]);
+        results.every(_ => _.isSuccess).should.be.true;
+    });
+
+    it('lets a released value be claimed again', async () => {
+        const owner = randomUUID();
+        (await store.eventLog.append(owner, registered('dave'))).isSuccess.should.be.true;
+        (await otherClientStore.eventLog.append(randomUUID(), registered('dave'))).isSuccess.should.be.false;
+
+        (await store.eventLog.append(owner, Object.assign(new UserRemoved(), { userName: 'dave' }))).isSuccess.should.be.true;
+
+        const results = await Promise.all([
+            store.eventLog.append(randomUUID(), registered('dave')),
+            otherClientStore.eventLog.append(randomUUID(), registered('dave'))
+        ]);
+        shouldHaveExactlyOneWinner(results, constraintName, constraintMessage);
+    });
+
+    it('commits no part of a batch that loses a race', async () => {
+        const batchSource = randomUUID();
+        const singleSource = randomUUID();
+        const [batch, single] = await Promise.all([
+            store.eventLog.appendMany([
+                { eventSourceId: batchSource, event: registered(`erin-${batchSource}`) },
+                { eventSourceId: batchSource, event: registered('erin') }
+            ]),
+            otherClientStore.eventLog.append(singleSource, registered('erin'))
+        ]);
+
+        const batchSucceeded = batch.every(_ => _.isSuccess);
+        batchSucceeded.should.not.equal(single.isSuccess);
+
+        const committed = await store.eventLog.getForEventSourceIdAndEventTypes(batchSource, [UserRegistered]);
+        committed.length.should.equal(batchSucceeded ? 2 : 0);
+    });
+
+    it('rejects a batch where two event sources claim the same value without committing any of it', async () => {
+        const firstSource = randomUUID();
+        const secondSource = randomUUID();
+        const results = await store.eventLog.appendMany([
+            { eventSourceId: firstSource, event: registered('frank') },
+            { eventSourceId: secondSource, event: registered('frank') }
+        ]);
+        results.some(_ => !_.isSuccess).should.be.true;
+        (await store.eventLog.getForEventSourceIdAndEventTypes(firstSource, [UserRegistered])).length.should.equal(0);
+        (await store.eventLog.getForEventSourceIdAndEventTypes(secondSource, [UserRegistered])).length.should.equal(0);
+        (await store.eventLog.append(randomUUID(), registered('frank'))).isSuccess.should.be.true;
+    });
+});

package/events/migrations/for_EventTypeMigrators/against_a_kernel/when_replaying_an_older_generation.integration.spec.ts

@@ -0,0 +1,156 @@
+// 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 type { AppendedEvent, EventContext } from '../../../../events/index.js';
+import { eventType } from '../../../../events/index.js';
+import type { IEventStore } from '../../../../IEventStore.js';
+import { fromEvent } from '../../../../projections/index.js';
+import { reactor } from '../../../../reactors/index.js';
+import { eventTypeMigration } from '../../eventTypeMigration.js';
+import type { IEventMigrationBuilder } from '../../IEventMigrationBuilder.js';
+import type { IEventTypeMigration } from '../../IEventTypeMigration.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;
+
+const eventTypeId = 'migration-replay-author-registered';
+
+@eventType(eventTypeId, 1)
+class AuthorRegisteredV1 {
+    @field(String) name = '';
+}
+
+@eventType(eventTypeId, 2)
+class AuthorRegistered {
+    @field(String) firstName = '';
+    @field(String) lastName = '';
+}
+
+@eventTypeMigration(AuthorRegistered, AuthorRegisteredV1)
+class AuthorRegisteredMigration implements IEventTypeMigration<AuthorRegistered, AuthorRegisteredV1> {
+    upcast(builder: IEventMigrationBuilder<AuthorRegistered, AuthorRegisteredV1>): void {
+        builder.properties(_ => _
+            .split('firstName', 'name', ' ', 0)
+            .split('lastName', 'name', ' ', 1));
+    }
+
+    downcast(builder: IEventMigrationBuilder<AuthorRegisteredV1, AuthorRegistered>): void {
+        builder.properties(_ => _.combine('name', ' ', 'firstName', 'lastName'));
+    }
+}
+
+// Projected by the kernel from the second generation.
+@fromEvent(AuthorRegistered)
+class Author {
+    @field(String) firstName = '';
+    @field(String) lastName = '';
+}
+
+const observed: { event: AuthorRegistered; context: EventContext }[] = [];
+
+@reactor('migration-replay-author-observer')
+class AuthorObserver {
+    authorRegistered(event: AuthorRegistered, context: EventContext): void {
+        observed.push({ event, context });
+    }
+}
+
+function artifactsWith(overrides: Partial<IClientArtifactsProvider>): IClientArtifactsProvider {
+    return {
+        eventTypes: [],
+        readModels: [],
+        reactors: [],
+        reducers: [],
+        seeders: [],
+        constraints: [],
+        projections: [],
+        webhooks: [],
+        eventTypeMigrations: [],
+        globalForHandlers: [],
+        ...overrides
+    };
+}
+
+function clientWith(artifacts: IClientArtifactsProvider): ChronicleClient {
+    return new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+        discoveryPatterns: [],
+        clientArtifactsProvider: artifacts
+    }));
+}
+
+async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs = 30_000): Promise<T> {
+    const deadline = Date.now() + timeoutMs;
+    let value = await read();
+    while (!accept(value)) {
+        if (Date.now() > deadline) throw new Error(`Timed out waiting for the kernel; last value: ${JSON.stringify(value, (_, v) => typeof v === 'bigint' ? v.toString() : v)}`);
+        await new Promise(resolve => setTimeout(resolve, 250));
+        value = await read();
+    }
+    return value;
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when replaying an older generation against a kernel', () => {
+    const eventStoreName = `MigrationReplay${randomUUID().replaceAll('-', '')}`;
+    const eventSourceId = randomUUID();
+    let firstGenerationClient: ChronicleClient;
+    let secondGenerationClient: ChronicleClient;
+    let appendedSequenceNumber: bigint;
+    let event: AppendedEvent;
+    let author: Author | null;
+    let observation: { event: AuthorRegistered; context: EventContext };
+    let missingMigrationError: unknown;
+
+    beforeAll(async () => {
+        // An application that only knows the first generation appends the event.
+        firstGenerationClient = clientWith(artifactsWith({ eventTypes: [AuthorRegisteredV1] }));
+        const firstGenerationStore = await firstGenerationClient.getEventStore(eventStoreName);
+        const appended = await firstGenerationStore.eventLog.append(eventSourceId, Object.assign(new AuthorRegisteredV1(), { name: 'Jane Doe' }));
+        appendedSequenceNumber = appended.sequenceNumber.value;
+        firstGenerationClient.dispose();
+
+        // A later version registers the second generation with a migration, a projection and a reactor that replay the history.
+        secondGenerationClient = clientWith(artifactsWith({
+            eventTypes: [AuthorRegisteredV1, AuthorRegistered],
+            eventTypeMigrations: [AuthorRegisteredMigration],
+            readModels: [Author],
+            reactors: [AuthorObserver]
+        }));
+        const store: IEventStore = await secondGenerationClient.getEventStore(eventStoreName);
+
+        event = await eventually(
+            async () => (await store.eventLog.getForEventSourceIdAndEventTypes(eventSourceId, [AuthorRegistered]))[0],
+            _ => (_?.content as AuthorRegistered | undefined)?.firstName === 'Jane');
+        author = await eventually(() => store.readModels.findInstanceById(Author, eventSourceId), _ => _ !== null && _.firstName !== '');
+        observation = await eventually(async () => observed.find(_ => _.context.eventSourceId === eventSourceId)!, _ => _ !== undefined);
+
+        // Registering a second generation without a migration from the first is rejected.
+        const missingMigrationClient = clientWith(artifactsWith({ eventTypes: [AuthorRegisteredV1, AuthorRegistered] }));
+        missingMigrationError = await missingMigrationClient.getEventStore(`MigrationReplayMissing${randomUUID().replaceAll('-', '')}`).catch((error: unknown) => error);
+        missingMigrationClient.dispose();
+    });
+
+    afterAll(() => {
+        firstGenerationClient?.dispose();
+        secondGenerationClient?.dispose();
+    });
+
+    it('should read the first name split from the first generation', () => (event.content as AuthorRegistered).firstName.should.equal('Jane'));
+    it('should read the last name split from the first generation', () => (event.content as AuthorRegistered).lastName.should.equal('Doe'));
+    it('should keep the event source of the appended event', () => event.context.eventSourceId.should.equal(eventSourceId));
+    it('should keep the sequence number of the appended event', () => event.context.sequenceNumber.should.equal(appendedSequenceNumber));
+    it('should project the migrated first name', () => author!.firstName.should.equal('Jane'));
+    it('should project the migrated last name', () => author!.lastName.should.equal('Doe'));
+    it('should replay the migrated first name to the reactor', () => observation.event.firstName.should.equal('Jane'));
+    it('should replay the migrated last name to the reactor', () => observation.event.lastName.should.equal('Doe'));
+    it('should replay the event source to the reactor', () => observation.context.eventSourceId.should.equal(eventSourceId));
+    it('should reject a second generation that has no migration', () => missingMigrationError.should.be.instanceOf(Error));
+});

package/jobs/for_Jobs/against_a_kernel/when_managing_a_replay_job.integration.spec.ts

@@ -0,0 +1,114 @@
+// 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 { JobStatus, JobStepStatus, type JobStepSummaryResponse, type JobSummaryResponse } from '@cratis/chronicle.contracts';
+import { field, Guid } from '@cratis/fundamentals';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import { fromContractsGuid } from '../../../connection/Guid.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import type { IEventStore } from '../../../IEventStore.js';
+import { fromEvent } from '../../../projections/index.js';
+import { JobId } from '../../JobId.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 ItemAdded {
+    @field(String) name = '';
+}
+
+@fromEvent(ItemAdded)
+class Item {
+    @field(String) name = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [ItemAdded],
+    readModels: [Item],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs = 20_000): Promise<T> {
+    const deadline = Date.now() + timeoutMs;
+    let value = await read();
+    while (!accept(value)) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        value = await read();
+    }
+    return value;
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when managing a replay job against a kernel', () => {
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let jobId: JobId;
+    let listed: JobSummaryResponse[];
+    let stopped: JobSummaryResponse | undefined;
+    let steps: JobStepSummaryResponse[];
+    let afterDelete: JobSummaryResponse | undefined;
+    let stopUnknownJob: unknown;
+    let deleteUnknownJob: unknown;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(`JobsEndToEnd${randomUUID().replaceAll('-', '')}`);
+
+        // Enough events that the replay is still running when it is stopped; a stopped job stays until deleted,
+        // where a completed one is removed and could not be listed reliably.
+        await store.eventLog.appendMany(Array.from({ length: 500 }, (_, index) => ({
+            eventSourceId: randomUUID(),
+            event: Object.assign(new ItemAdded(), { name: `Item ${index}` })
+        })));
+
+        jobId = await store.projections.replayForModel(Item);
+
+        // Stopping a job in the instant it starts leaves its step running forever, so wait until it is running.
+        await eventually(() => store.jobs.getJob(jobId), _ => _?.Status === JobStatus.JOB_STATUS_Running);
+        await store.jobs.stop(jobId);
+
+        listed = await store.jobs.getJobs();
+        stopped = await eventually(() => store.jobs.getJob(jobId), _ => _?.Status === JobStatus.JOB_STATUS_Stopped);
+        // The kernel updates step status asynchronously, after the job itself reports stopped.
+        steps = await eventually(
+            () => store.jobs.getJobSteps(jobId),
+            _ => _.length > 0 && _.every(step => step.Status === JobStepStatus.JOB_STEP_STATUS_Stopped),
+            30_000);
+
+        await store.jobs.delete(jobId);
+        afterDelete = await eventually(() => store.jobs.getJob(jobId), _ => _ === undefined);
+
+        stopUnknownJob = await store.jobs.stop(randomUUID()).catch((error: unknown) => error);
+        deleteUnknownJob = await store.jobs.delete(randomUUID()).catch((error: unknown) => error);
+    });
+
+    afterAll(() => client?.dispose());
+
+    it('should start a replay job', () => jobId.toString().should.not.equal(Guid.empty.toString()));
+    it('should list the job', () => listed.some(_ => fromContractsGuid(_.Id).toString() === jobId.toString()).should.be.true);
+    it('should report the job as a replay', () => stopped!.Type.should.equal('ReplayObserver'));
+    it('should report the job as stopped', () => stopped!.Status.should.equal(JobStatus.JOB_STATUS_Stopped));
+    it('should list the steps of the job', () => steps.length.should.be.greaterThan(0));
+    it('should report the steps as stopped', () => steps.every(_ => _.Status === JobStepStatus.JOB_STEP_STATUS_Stopped).should.be.true);
+    it('should no longer list the deleted job', () => (afterDelete === undefined).should.be.true);
+    it('should report stopping a job that does not exist', () => stopUnknownJob.should.be.instanceOf(Error));
+    it('should report deleting a job that does not exist', () => deleteUnknownJob.should.be.instanceOf(Error));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.31.0",
+    "version": "6.31.1",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",

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

@@ -0,0 +1,111 @@
+// 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 type { ChronicleConnection } from '../../../connection/index.js';
+import { eventType } from '../../../events/index.js';
+import type { IEventStore } from '../../../IEventStore.js';
+import { onceOnly } from '../../onceOnly.js';
+import { reactor } from '../../reactor.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 ThingHappened {
+    @field(String) name = '';
+}
+
+// The client constructs reactor instances; share sinks for assertions across that boundary.
+const onceOnlyInvocations: string[] = [];
+const replayableInvocations: string[] = [];
+
+@reactor()
+@onceOnly()
+class OnceOnlyReactor {
+    thingHappened(event: ThingHappened) { onceOnlyInvocations.push(event.name); }
+}
+
+@reactor()
+class ReplayableReactor {
+    thingHappened(event: ThingHappened) { replayableInvocations.push(event.name); }
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [ThingHappened],
+    readModels: [],
+    reactors: [OnceOnlyReactor, ReplayableReactor],
+    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, 250));
+    }
+}
+
+const isEmptyJobId = (jobId: string | undefined) => /^[0-]*$/.test(jobId ?? '');
+
+describe.skipIf(!connectionString && !process.env.CI)('when replaying reactors against a kernel', () => {
+    const storeName = `Replay${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let connection: ChronicleConnection;
+    let onceOnlyJobId: string | undefined;
+    let replayableJobId: string | undefined;
+
+    const replay = (observerId: string) => connection.observers.replay({
+        EventStore: storeName,
+        Namespace: 'Default',
+        ObserverId: observerId,
+        EventSequenceId: 'event-log'
+    });
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(storeName);
+        connection = (store as unknown as { _connection: ChronicleConnection })._connection;
+
+        (await store.eventLog.append(randomUUID(), Object.assign(new ThingHappened(), { name: 'first' }))).isSuccess.should.be.true;
+        await eventually(() => onceOnlyInvocations.length === 1 && replayableInvocations.length === 1);
+
+        onceOnlyJobId = (await replay('OnceOnlyReactor')).JobId;
+        replayableJobId = (await replay('ReplayableReactor')).JobId;
+        await eventually(() => replayableInvocations.length === 2);
+        await new Promise(resolve => setTimeout(resolve, 3_000));
+    });
+
+    afterAll(() => client?.dispose());
+
+    it('should replay a reactor that is not once-only', () => {
+        isEmptyJobId(replayableJobId).should.be.false;
+        replayableInvocations.should.deep.equal(['first', 'first']);
+    });
+
+    it('should not start a replay of a class-level once-only reactor', () => {
+        isEmptyJobId(onceOnlyJobId).should.be.true;
+    });
+
+    it('should not invoke a class-level once-only reactor again', () => {
+        onceOnlyInvocations.should.deep.equal(['first']);
+    });
+});

package/webhooks/for_Webhooks/against_a_kernel/when_registering_and_removing_a_webhook.integration.spec.ts

@@ -0,0 +1,88 @@
+// 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 type { WebhookDefinition } from '@cratis/chronicle.contracts';
+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 type { IEventStore } from '../../../IEventStore.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 OrderShipped {
+    @field(String) orderId = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [OrderShipped],
+    readModels: [],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boolean, timeoutMs = 20_000): Promise<T> {
+    const deadline = Date.now() + timeoutMs;
+    let value = await read();
+    while (!accept(value)) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 100));
+        value = await read();
+    }
+    return value;
+}
+
+describe.skipIf(!connectionString && !process.env.CI)('when registering and removing a webhook against a kernel', () => {
+    const webhookId = randomUUID();
+    const targetUrl = 'http://localhost:9/orders';
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let registered: WebhookDefinition | undefined;
+    let afterRemove: WebhookDefinition[];
+    let registerWithoutIdentifier: unknown;
+
+    const findRegistered = async () => (await store.webhooks.getWebhooks()).find(_ => _.Identifier === webhookId);
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(`WebhooksEndToEnd${randomUUID().replaceAll('-', '')}`);
+
+        await store.webhooks.register(webhookId, targetUrl, _ => _
+            .withEventType(OrderShipped)
+            .withHeader('X-Source', 'specs'));
+
+        // The kernel records the registration as events and builds its webhook list from them, so it shows up eventually.
+        registered = await eventually(findRegistered, _ => _ !== undefined);
+
+        await store.webhooks.remove(webhookId);
+        afterRemove = await eventually(() => store.webhooks.getWebhooks(), _ => !_.some(webhook => webhook.Identifier === webhookId));
+
+        registerWithoutIdentifier = await store.webhooks.register('', targetUrl, _ => _.withEventType(OrderShipped)).catch((error: unknown) => error);
+    });
+
+    afterAll(() => client?.dispose());
+
+    it('should list the webhook', () => registered!.Identifier.should.equal(webhookId));
+    it('should keep the target url', () => registered!.Target!.Url.should.equal(targetUrl));
+    it('should keep the header', () => registered!.Target!.Headers['X-Source'].should.equal('specs'));
+    it('should keep the event type', () => registered!.EventTypes.map(_ => _.Id).should.deep.equal(['OrderShipped']));
+    it('should no longer list the removed webhook', () => afterRemove.some(_ => _.Identifier === webhookId).should.be.false);
+    it('should report a registration the kernel rejects', () => registerWithoutIdentifier.should.be.instanceOf(Error));
+});