@cratis/chronicle 3.1.0 → 4.0.0

package/ChronicleClient.ts

@@ -6,6 +6,7 @@ import { diag } from '@opentelemetry/api';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleOptions } from './ChronicleOptions';
 import { ChronicleConnection } from './connection';
+import { ensureCommandSuccess, ensureQuerySuccess, firstQueryResult } from './connection/callResults';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle';
 import { KernelKeepAlive } from './connection/KernelKeepAlive';
 import { EventStore } from './EventStore';
@@ -131,7 +132,7 @@ export class ChronicleClient implements IChronicleClient {
                     this._logger.debug('Ensuring event store exists in kernel', {
                         eventStore: storeName.value
                     });
-                    await this._connection.eventStores.ensure({ Name: storeName.value });
+                    ensureCommandSuccess('ensure event store', await this._connection.eventStores.ensureEventStore({ Name: storeName.value }));
 
                     const created = new EventStore(storeName, namespaceName, this._connection, this._lifecycle, this.options.defaultSinkTypeId);
                     this._stores.set(key, created);
@@ -167,9 +168,9 @@ export class ChronicleClient implements IChronicleClient {
             try {
                 const response = await this.withReconnect('get_event_stores', async () => {
                     await this.ensureConnected();
-                    return this._connection.eventStores.getEventStores({});
+                    return firstQueryResult('get event stores', this._connection.eventStores.allEventStores({}));
                 });
-                const result = (response.items ?? []).map((name: string) => new EventStoreName(name));
+                const result = ensureQuerySuccess('get event stores', response).map((name: string) => new EventStoreName(name));
                 this._logger.verbose('Retrieved event stores from kernel', {
                     count: result.length
                 });

package/EventStore.ts

@@ -5,6 +5,7 @@ import { diag } from '@opentelemetry/api';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleConnection } from './connection';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle';
+import { ensureQuerySuccess, firstQueryResult } from './connection/callResults';
 import { EventLog } from './eventSequences/EventLog';
 import { EventSequence } from './eventSequences/EventSequence';
 import { EventSequenceId } from './eventSequences/EventSequenceId';
@@ -89,7 +90,7 @@ export class EventStore implements IEventStore {
         const artifacts = DefaultClientArtifactsProvider.default;
         this.eventTypes = new EventTypes(name.value, _connection, artifacts);
         this.constraints = new Constraints(name.value, _connection, artifacts);
-        this.projections = new Projections(name.value, _connection, artifacts, defaultSinkTypeId);
+        this.projections = new Projections(name.value, namespace.value, _connection, artifacts, defaultSinkTypeId);
         this.reactors = new Reactors(artifacts, _connection, name.value, namespace.value, lifecycle, this.eventLog);
         this.reducers = new Reducers(artifacts, _connection, name.value, namespace.value, lifecycle, defaultSinkTypeId);
         this.readModels = new ReadModels(name.value, namespace.value, _connection, artifacts, defaultSinkTypeId);
@@ -163,8 +164,8 @@ export class EventStore implements IEventStore {
         return ChronicleTracer.startActiveSpan('chronicle.event_store.get_namespaces', async span => {
             span.setAttribute('chronicle.event_store', this.name.value);
             try {
-                const response = await this._connection.namespaces.getNamespaces({ EventStore: this.name.value });
-                const result = (response.items ?? []).map((namespace: string) => new EventStoreNamespaceName(namespace));
+                const response = await firstQueryResult('get namespaces', this._connection.namespaces.allNamespaces({ EventStore: this.name.value }));
+                const result = ensureQuerySuccess('get namespaces', response).map((namespace: string) => new EventStoreNamespaceName(namespace));
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             } catch (error) {

package/README.md

@@ -1,38 +1,42 @@
 # Chronicle TypeScript Client
 
-A TypeScript-idiomatic client for [Cratis Chronicle](https://github.com/Cratis/Chronicle) — the open source event-sourcing kernel.
+**Event sourcing for TypeScript and Node.js — the idiomatic client for [Cratis Chronicle](https://github.com/Cratis/Chronicle).**
+
+[![npm](https://img.shields.io/npm/v/@cratis/chronicle?label=npm&logo=npm)](https://www.npmjs.com/package/@cratis/chronicle)
+[![Build](https://github.com/Cratis/Chronicle.TypeScript/actions/workflows/build.yml/badge.svg)](https://github.com/Cratis/Chronicle.TypeScript/actions/workflows/build.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Cratis/Chronicle.TypeScript/blob/main/LICENSE)
+[![Discord](https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&logoColor=white)](https://discord.gg/kt4AMpV8WV)
+
+Chronicle is an event-sourcing database and processing runtime with a first-class .NET SDK and additional TypeScript, Kotlin/Java (JVM), and Elixir clients — with a Python client coming soon — plus pluggable storage-provider implementations including MongoDB (default), PostgreSQL, SQL Server, and SQLite. This package is the **TypeScript client**.
 
 ## Overview
 
 `@cratis/chronicle` provides a clean, type-safe TypeScript API for interacting with the Chronicle Kernel. It builds on top of [`@cratis/chronicle.contracts`](https://www.npmjs.com/package/@cratis/chronicle.contracts) (the gRPC contracts package) and exposes idiomatic TypeScript constructs including:
 
-- **Decorators** — `@eventType`, `@eventTypeMigration`, `@readModel`, `@reactor`, `@reducer`, `@constraint`, `@projection`, and model-bound decorators such as `@fromEvent`
+- **Decorators** — `@eventType`, `@eventTypeMigration`, `@readModel`, `@reactor`, `@reducer`, `@seeder`, `@constraint`, `@projection`, and model-bound decorators such as `@fromEvent`
 - **Value objects** — `EventSequenceNumber`, `EventTypeId`, `EventStoreName`, etc.
 - **Fluent client** — `ChronicleClient` → `EventStore` → `EventLog` → `append()`
 
-## Structure
+Beyond appending and observing events, the client covers the full Chronicle surface:
 
-```
-Source/          ← @cratis/chronicle TypeScript library
-Documentation/   ← User-facing documentation
-Samples/
-  Console/       ← Plain Node.js console sample application
-```
+- **Transactions** — group appends into a unit of work with a single commit
+- **Jobs** — inspect and control long-running kernel jobs
+- **Webhooks** — push events to HTTP endpoints
+- **Compliance / PII** — classify event data and handle personally identifiable information
+- **OpenTelemetry** — built-in metrics and tracing instrumentation
 
-## Prerequisite: Chronicle Running
+## Installation
 
-You need a Chronicle Kernel available before running samples or application code.
+```bash
+npm install @cratis/chronicle reflect-metadata
+```
 
-The easiest local setup is the development Docker image:
+You need a Chronicle Kernel available. The easiest local setup is the development Docker image:
 
 ```bash
 docker run -p 35000:35000 cratis/chronicle:latest-development
 ```
 
-## Getting Started
-
-See [Documentation/getting-started.md](./Documentation/getting-started.md) for installation and usage instructions.
-
 ## Quick Example
 
 ```typescript
@@ -51,19 +55,27 @@ console.log(`Appended at sequence number ${result.sequenceNumber.value}`);
 client.dispose();
 ```
 
-## Building
+## Documentation
 
-```bash
-yarn install
-yarn workspace @cratis/chronicle compile
-```
+See the [getting started guide](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/getting-started.md) and the rest of the [documentation](https://github.com/Cratis/Chronicle.TypeScript/tree/main/Documentation) for installation and usage instructions, or visit [cratis.io](https://www.cratis.io/chronicle/).
 
-## Running the Console Sample
+## The Cratis ecosystem
 
-```bash
-yarn install
-yarn workspace @cratis/chronicle-test-console build
-yarn workspace @cratis/chronicle-test-console start
-```
+This package is part of [Cratis](https://www.cratis.io) — free, MIT-licensed tools for building event-sourced and CQRS applications.
+
+- **[Chronicle](https://github.com/Cratis/Chronicle)** — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. [Docs](https://www.cratis.io/chronicle/)
+- **Chronicle clients** — first-class [.NET SDK](https://github.com/Cratis/Chronicle), plus [TypeScript](https://github.com/Cratis/Chronicle.TypeScript), [Kotlin/Java](https://github.com/Cratis/Chronicle.Kotlin), and [Elixir](https://github.com/Cratis/Chronicle.Elixir); [Python](https://github.com/Cratis/Chronicle.Python) coming soon (pre-alpha). AI agents connect through the [Chronicle MCP server](https://github.com/Cratis/Chronicle.Mcp).
+- **[Arc](https://github.com/Cratis/Arc)** — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. [Docs](https://www.cratis.io/arc/)
+- **[Components](https://github.com/Cratis/Components)** — React components aligned with Arc patterns. [Docs](https://www.cratis.io/components/)
+- **[CLI](https://github.com/Cratis/cli) + Workbench** — inspect and diagnose Chronicle from the terminal or the browser. [Docs](https://www.cratis.io/cli/)
+- **[Samples](https://github.com/Cratis/Samples)** — runnable event sourcing and CQRS samples for the whole stack
+
+Everything Cratis publishes today is MIT licensed and free to use.
+
+---
+
+<div align="center">
+
+*Part of the [Cratis](https://www.cratis.io) platform · Licensed under the [MIT license](https://github.com/Cratis/Chronicle.TypeScript/blob/main/LICENSE)*
 
-Set the `CHRONICLE_CONNECTION` environment variable to override the default connection string (`chronicle://localhost:35000`).
+</div>

package/compliance/ComplianceContracts.ts

@@ -33,6 +33,16 @@ export interface DeleteEncryptionKeyRequest {
     Identifier: string;
 }
 
+/**
+ * Request to authorize a new encryption key for a PII encryption key identifier whose key was
+ * previously erased, so a later lawful lifecycle can protect their data again.
+ */
+export interface AllowNewEncryptionKeyRequest {
+    EventStore: string;
+    Namespace: string;
+    Identifier: string;
+}
+
 /**
  * An empty protobuf message.
  */
@@ -49,6 +59,7 @@ export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<
 export interface ComplianceClient<CallOptionsExt = {}> {
     release(request: DeepPartial<ReleaseRequest>, options?: CallOptions & CallOptionsExt): Promise<ReleaseResponse>;
     deleteEncryptionKey(request: DeepPartial<DeleteEncryptionKeyRequest>, options?: CallOptions & CallOptionsExt): Promise<Empty>;
+    allowNewEncryptionKey(request: DeepPartial<AllowNewEncryptionKeyRequest>, options?: CallOptions & CallOptionsExt): Promise<Empty>;
 }
 
 export const ReleaseRequest = {
@@ -181,6 +192,46 @@ export const DeleteEncryptionKeyRequest = {
     }
 };
 
+export const AllowNewEncryptionKeyRequest = {
+    encode(message: AllowNewEncryptionKeyRequest, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
+        if (message.EventStore !== '') {
+            writer.uint32(10).string(message.EventStore);
+        }
+        if (message.Namespace !== '') {
+            writer.uint32(18).string(message.Namespace);
+        }
+        if (message.Identifier !== '') {
+            writer.uint32(26).string(message.Identifier);
+        }
+        return writer;
+    },
+
+    decode(input: BinaryReader | Uint8Array, length?: number): AllowNewEncryptionKeyRequest {
+        const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+        const end = length === undefined ? reader.len : reader.pos + length;
+        const message: AllowNewEncryptionKeyRequest = { EventStore: '', Namespace: '', Identifier: '' };
+        while (reader.pos < end) {
+            const tag = reader.uint32();
+            switch (tag >>> 3) {
+                case 1: message.EventStore = reader.string(); continue;
+                case 2: message.Namespace = reader.string(); continue;
+                case 3: message.Identifier = reader.string(); continue;
+            }
+            if ((tag & 7) === 4 || tag === 0) break;
+            reader.skip(tag & 7);
+        }
+        return message;
+    },
+
+    fromPartial(object: DeepPartial<AllowNewEncryptionKeyRequest>): AllowNewEncryptionKeyRequest {
+        return {
+            EventStore: object.EventStore ?? '',
+            Namespace: object.Namespace ?? '',
+            Identifier: object.Identifier ?? ''
+        };
+    }
+};
+
 export const Empty = {
     encode(_: Empty, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
         return writer;
@@ -224,6 +275,14 @@ export const ComplianceDefinition = {
             responseType: Empty,
             responseStream: false as const,
             options: {}
+        },
+        allowNewEncryptionKey: {
+            name: 'AllowNewEncryptionKey',
+            requestType: AllowNewEncryptionKeyRequest,
+            requestStream: false as const,
+            responseType: Empty,
+            responseStream: false as const,
+            options: {}
         }
     }
 } as const;

package/compliance/IPIIManager.ts

@@ -14,4 +14,16 @@ export interface IPIIManager {
      * this operation cannot be undone.
      */
     deleteEncryptionKey(identifier: string): Promise<void>;
+
+    /**
+     * Authorizes a new encryption key for a PII encryption key identifier whose key was previously
+     * erased, so a later lawful lifecycle can protect their data again.
+     * @param identifier - The identifier of the encryption key to authorize a new key for.
+     * @remarks
+     * Erasing an identifier removes the key that exists now; it does not ban the identifier
+     * forever. This creates no key - it lets the next PII value written for the identifier
+     * provision a fresh, independent one, which can decrypt nothing written before the erasure.
+     * The erased key itself never comes back, whatever else happens.
+     */
+    allowNewEncryptionKeyFor(identifier: string): Promise<void>;
 }

package/compliance/PIIManager.spec.ts

@@ -0,0 +1,50 @@
+// 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 { ChronicleConnection } from '../connection';
+import { PIIManager } from './PIIManager';
+
+function createPIIManager() {
+    const deleteEncryptionKeyMock = vi.fn().mockResolvedValue(undefined);
+    const allowNewEncryptionKeyMock = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        compliance: {
+            deleteEncryptionKey: deleteEncryptionKeyMock,
+            allowNewEncryptionKey: allowNewEncryptionKeyMock
+        }
+    } as unknown as ChronicleConnection;
+
+    const manager = new PIIManager('test-store', 'test-namespace', connection);
+    return { manager, deleteEncryptionKeyMock, allowNewEncryptionKeyMock };
+}
+
+describe('PIIManager', () => {
+    describe('when deleting an encryption key', () => {
+        it('should call the compliance service with the event store, namespace, and identifier', async () => {
+            const { manager, deleteEncryptionKeyMock } = createPIIManager();
+
+            await manager.deleteEncryptionKey('some-subject');
+
+            expect(deleteEncryptionKeyMock).toHaveBeenCalledWith({
+                EventStore: 'test-store',
+                Namespace: 'test-namespace',
+                Identifier: 'some-subject'
+            });
+        });
+    });
+
+    describe('when allowing a new encryption key', () => {
+        it('should call the compliance service with the event store, namespace, and identifier', async () => {
+            const { manager, allowNewEncryptionKeyMock } = createPIIManager();
+
+            await manager.allowNewEncryptionKeyFor('some-subject');
+
+            expect(allowNewEncryptionKeyMock).toHaveBeenCalledWith({
+                EventStore: 'test-store',
+                Namespace: 'test-namespace',
+                Identifier: 'some-subject'
+            });
+        });
+    });
+});

package/compliance/PIIManager.ts

@@ -28,4 +28,13 @@ export class PIIManager implements IPIIManager {
             Identifier: identifier
         });
     }
+
+    /** @inheritdoc */
+    async allowNewEncryptionKeyFor(identifier: string): Promise<void> {
+        await this._connection.compliance.allowNewEncryptionKey({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            Identifier: identifier
+        });
+    }
 }

package/compliance/PIINotSupportedOnEventSourceId.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Error thrown when the {@link pii} decorator is applied to the `eventSourceId` property.
+ */
+export class PIINotSupportedOnEventSourceId extends Error {
+    /**
+     * Initializes a new instance of the {@link PIINotSupportedOnEventSourceId} class.
+     * @param typeName - The name of the type the decorator was applied to.
+     */
+    constructor(typeName: string) {
+        super(
+            `The @pii() decorator cannot be applied to 'eventSourceId' on '${typeName}' because it is the event ` +
+            'source identifier. Event source identifiers cannot be encrypted as they are required for event ' +
+            'correlation. If the identifier itself is sensitive, use a non-sensitive surrogate value as the event ' +
+            'source identifier and store the sensitive value in a separate property marked with @pii().'
+        );
+        this.name = 'PIINotSupportedOnEventSourceId';
+    }
+}

package/compliance/index.ts

@@ -4,6 +4,8 @@
 export { ComplianceMetadataType } from './ComplianceMetadataType';
 export type { ComplianceMetadata } from './ComplianceMetadata';
 export { pii, getPIIMetadata, hasPIIMetadata, getTypePIIMetadata, isPII } from './pii';
+export { subject, hasSubjectMetadata, getSubjectPropertyName } from './subject';
+export { PIINotSupportedOnEventSourceId } from './PIINotSupportedOnEventSourceId';
 export { ComplianceMetadataResolver } from './ComplianceMetadataResolver';
 export type { IPIIManager } from './IPIIManager';
 export { PIIManager } from './PIIManager';

package/compliance/pii.spec.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { describe, expect, it } from 'vitest';
+import { pii } from './pii';
+import { PIINotSupportedOnEventSourceId } from './PIINotSupportedOnEventSourceId';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+describe('pii', () => {
+    describe('when applied to the eventSourceId property', () => {
+        class SomeEvent {
+            eventSourceId = '';
+        }
+
+        it('should throw PIINotSupportedOnEventSourceId', () => {
+            expect(() => pii()(SomeEvent.prototype, 'eventSourceId')).toThrow(PIINotSupportedOnEventSourceId);
+        });
+
+        it('should describe why the property cannot be encrypted', () => {
+            expect(() => pii()(SomeEvent.prototype, 'eventSourceId')).toThrow(/event source identifier/);
+        });
+    });
+
+    describe('when applied to any other property', () => {
+        class SomeEvent {
+            eventSourceId = '';
+            name = '';
+        }
+
+        it('should not throw', () => {
+            expect(() => pii()(SomeEvent.prototype, 'name')).not.toThrow();
+        });
+    });
+});

package/compliance/pii.ts

@@ -4,8 +4,12 @@
 import 'reflect-metadata';
 import type { ComplianceMetadata } from './ComplianceMetadata';
 import { ComplianceMetadataType } from './ComplianceMetadataType';
+import { PIINotSupportedOnEventSourceId } from './PIINotSupportedOnEventSourceId';
 import { TypeIntrospector } from '../types';
 
+/** The property name this client uses everywhere for the event source identifier. */
+const EVENT_SOURCE_ID_PROPERTY = 'eventSourceId';
+
 /** Metadata key for PII decorator on properties. */
 const PII_PROPERTY_METADATA_KEY = 'chronicle:compliance:pii:property';
 
@@ -66,7 +70,18 @@ export function pii(details?: string): PropertyDecorator & ClassDecorator {
         // Property decorator usage
         if (propertyKey !== undefined) {
             const key = propertyKey.toString();
-            TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+            const declaringType = (target as { constructor: Function }).constructor;
+
+            // Encrypting the event source identifier would make its own decryption key
+            // unfindable - the identifier is required, in the clear, to correlate events and
+            // look up the key that protects everything else. Mirrors C#'s
+            // PIINotSupportedOnEventSourceId guard, which throws for the same reason when
+            // [PII] is applied to an EventSourceId/EventSourceId<T> type.
+            if (key === EVENT_SOURCE_ID_PROPERTY) {
+                throw new PIINotSupportedOnEventSourceId(declaringType.name);
+            }
+
+            TypeIntrospector.trackProperty(declaringType, key);
             const metadata: ComplianceMetadata = {
                 metadataType: ComplianceMetadataType.PII,
                 details: details ?? ''

package/compliance/subject.spec.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { describe, expect, it } from 'vitest';
+import { getSubjectPropertyName, hasSubjectMetadata, subject } from './subject';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+describe('subject', () => {
+    describe('when applied to a property', () => {
+        class SomeReadModel {
+            personId = '';
+            name = '';
+        }
+        subject()(SomeReadModel.prototype, 'personId');
+
+        it('should mark the decorated property with subject metadata', () => {
+            expect(hasSubjectMetadata(SomeReadModel.prototype, 'personId')).toBe(true);
+        });
+
+        it('should leave other properties without subject metadata', () => {
+            expect(hasSubjectMetadata(SomeReadModel.prototype, 'name')).toBe(false);
+        });
+
+        it('should record the decorated property name on the declaring type', () => {
+            expect(getSubjectPropertyName(SomeReadModel)).toBe('personId');
+        });
+    });
+
+    describe('when no property is decorated', () => {
+        class PlainReadModel {
+            id = '';
+        }
+
+        it('should not record a subject property on the declaring type', () => {
+            expect(getSubjectPropertyName(PlainReadModel)).toBeUndefined();
+        });
+
+        it('should report no subject metadata for its properties', () => {
+            expect(hasSubjectMetadata(PlainReadModel.prototype, 'id')).toBe(false);
+        });
+    });
+});

package/compliance/subject.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { TypeIntrospector } from '../types';
+
+/** Metadata key for the subject decorator on a property. */
+const SUBJECT_PROPERTY_METADATA_KEY = 'chronicle:compliance:subject:property';
+
+/** Metadata key for the name of the subject property recorded on the declaring type. */
+const SUBJECT_TYPE_METADATA_KEY = 'chronicle:compliance:subject:type';
+
+/**
+ * Decorator that marks a property as the compliance subject - the natural person whose Personal
+ * Identifiable Information (PII) a read model or event carries. The subject selects which
+ * encryption key protects that PII, and which key a manual release operation must use.
+ *
+ * Mirrors the .NET client's `SubjectAttribute`. When no property is decorated, resolvers fall
+ * back to the `id` property by convention, so read models that predate this decorator keep
+ * working unchanged.
+ *
+ * @returns A property decorator.
+ *
+ * @example
+ * ```typescript
+ * @readModel()
+ * class Employee {
+ *     @subject()
+ *     personId: string = '';
+ *
+ *     @pii('Employee social security number')
+ *     ssn: string = '';
+ * }
+ * ```
+ */
+export function subject(): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const key = propertyKey.toString();
+        const declaringType = (target as { constructor: Function }).constructor;
+
+        TypeIntrospector.trackProperty(declaringType, key);
+        Reflect.defineMetadata(SUBJECT_PROPERTY_METADATA_KEY, true, target, key);
+        Reflect.defineMetadata(SUBJECT_TYPE_METADATA_KEY, key, declaringType);
+    };
+}
+
+/**
+ * Checks whether a property has been decorated with @subject.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns True if the property has the @subject decorator; false otherwise.
+ */
+export function hasSubjectMetadata(target: object, propertyKey: string): boolean {
+    return Reflect.hasMetadata(SUBJECT_PROPERTY_METADATA_KEY, target, propertyKey);
+}
+
+/**
+ * Gets the name of the property decorated with @subject on a type, if any.
+ * @param type - The type constructor to inspect.
+ * @returns The decorated property name, or undefined when no property is decorated.
+ */
+export function getSubjectPropertyName(type: Function): string | undefined {
+    return Reflect.getMetadata(SUBJECT_TYPE_METADATA_KEY, type);
+}

package/connection/callResults.spec.ts

@@ -0,0 +1,90 @@
+// 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 } from 'vitest';
+import { ChronicleCallFailed, ensureCommandSuccess, ensureQuerySuccess, firstQueryResult, isCallSuccess } from './callResults';
+
+const successfulResult = {
+    ValidationResults: [],
+    ExceptionMessages: [],
+    AuthorizationFailureReason: ''
+};
+
+describe('callResults', () => {
+    describe('when checking a successful result', () => {
+        it('should report success', () => {
+            expect(isCallSuccess(successfulResult)).toBe(true);
+        });
+    });
+
+    describe('when checking a result with an authorization failure reason', () => {
+        it('should report failure', () => {
+            expect(isCallSuccess({ ...successfulResult, AuthorizationFailureReason: 'no access' })).toBe(false);
+        });
+    });
+
+    describe('when checking a result with validation results', () => {
+        it('should report failure', () => {
+            expect(isCallSuccess({ ...successfulResult, ValidationResults: [{ Message: 'invalid', Members: [] }] })).toBe(false);
+        });
+    });
+
+    describe('when checking a result with exception messages', () => {
+        it('should report failure', () => {
+            expect(isCallSuccess({ ...successfulResult, ExceptionMessages: ['boom'] })).toBe(false);
+        });
+    });
+
+    describe('when ensuring a successful command', () => {
+        it('should not throw', () => {
+            expect(() => ensureCommandSuccess('operation', successfulResult)).not.toThrow();
+        });
+    });
+
+    describe('when ensuring a failed command', () => {
+        it('should throw with the failure reasons', () => {
+            expect(() => ensureCommandSuccess('operation', { ...successfulResult, ExceptionMessages: ['boom'] }))
+                .toThrow(ChronicleCallFailed);
+            expect(() => ensureCommandSuccess('operation', { ...successfulResult, ExceptionMessages: ['boom'] }))
+                .toThrow(/operation.*boom/);
+        });
+    });
+
+    describe('when ensuring a successful query', () => {
+        it('should return the data', () => {
+            expect(ensureQuerySuccess('operation', { ...successfulResult, Data: ['a', 'b'] })).toEqual(['a', 'b']);
+        });
+    });
+
+    describe('when ensuring a failed query', () => {
+        it('should throw with the failure reasons', () => {
+            expect(() => ensureQuerySuccess('operation', { ...successfulResult, AuthorizationFailureReason: 'no access', Data: [] }))
+                .toThrow(/no access/);
+        });
+    });
+
+    describe('when taking the first result from a stream', () => {
+        it('should return the first item and cancel the stream', async () => {
+            let cleanedUp = false;
+            async function* stream() {
+                try {
+                    yield 'first';
+                    yield 'second';
+                } finally {
+                    cleanedUp = true;
+                }
+            }
+
+            const result = await firstQueryResult('operation', stream());
+            expect(result).toBe('first');
+            expect(cleanedUp).toBe(true);
+        });
+    });
+
+    describe('when taking the first result from an empty stream', () => {
+        it('should throw', async () => {
+            async function* stream() { /* produces nothing */ }
+            await expect(firstQueryResult('operation', stream())).rejects.toThrow(/completed without producing a result/);
+        });
+    });
+});