@cratis/chronicle 6.35.0 → 6.37.0

package/index.ts

@@ -9,6 +9,7 @@ import * as seeding from './seeding/index.js';
 import * as readModels from './readModels/index.js';
 import * as projections from './projections/index.js';
 import * as jobs from './jobs/index.js';
+import * as patterns from './patterns/index.js';
 import * as webhooks from './webhooks/index.js';
 import * as externalServices from './externalServices/index.js';
 import * as identities from './identities/index.js';
@@ -53,6 +54,7 @@ export * from './seeding/index.js';
 export * from './readModels/index.js';
 export * from './projections/index.js';
 export * from './jobs/index.js';
+export * from './patterns/index.js';
 export * from './webhooks/index.js';
 export * from './externalServices/index.js';
 export * from './identities/index.js';
@@ -78,6 +80,7 @@ export {
     readModels,
     projections,
     jobs,
+    patterns,
     webhooks,
     externalServices,
     identities,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.35.0",
+    "version": "6.37.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",
@@ -96,6 +96,11 @@
             "import": "./dist/projections/index.js",
             "default": "./dist/projections/index.js"
         },
+        "./patterns": {
+            "types": "./dist/patterns/index.d.ts",
+            "import": "./dist/patterns/index.js",
+            "default": "./dist/patterns/index.js"
+        },
         "./jobs": {
             "types": "./dist/jobs/index.d.ts",
             "import": "./dist/jobs/index.js",
@@ -168,7 +173,7 @@
         "clean": "rm -rf dist",
         "test": "vitest run",
         "test:integration": "vitest run --config vitest.integration.config.ts",
-        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/patterns/BehaviorPattern.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { FacetSet } from './FacetSet.js';
+
+/** Recurring behavior established by Chronicle, not a prediction invented by the client. */
+export interface BehaviorPattern {
+    /** Identity of the persisted pattern. */
+    readonly id: string;
+    /** Scope the behavior belongs to, typically a user. */
+    readonly groupingKey: string;
+    /** The pattern's context and, when present, its CommandType action. */
+    readonly facets: FacetSet;
+    /** How often the pattern holds when its context is present, from 0 to 1. */
+    readonly confidence: number;
+    /** Share of all observed events containing the pattern, from 0 to 1. */
+    readonly support: number;
+    /** Approximate occurrence count, preserving the wire's 64-bit precision. */
+    readonly occurrences: bigint;
+    /** Recency-weighted strength. */
+    readonly weight: number;
+    /** Number of facets the pattern constrains. */
+    readonly specificity: number;
+    /** First observed instant, absent if the server omitted it. */
+    readonly firstSeen: Date | undefined;
+    /** Last observed instant, absent if the server omitted it. */
+    readonly lastSeen: Date | undefined;
+}

package/patterns/DayOfWeek.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Day names used by Chronicle's Day facet, independent of the caller's locale. */
+export enum DayOfWeek {
+    Sunday = 'Sunday',
+    Monday = 'Monday',
+    Tuesday = 'Tuesday',
+    Wednesday = 'Wednesday',
+    Thursday = 'Thursday',
+    Friday = 'Friday',
+    Saturday = 'Saturday'
+}

package/patterns/FacetName.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Well-known contextual dimensions mined from an event's context. */
+export enum FacetName {
+    CommandType = 'CommandType',
+    InitiatorType = 'InitiatorType',
+    InitiatorId = 'InitiatorId',
+    OnBehalfOf = 'OnBehalfOf',
+    CausedByCommand = 'CausedByCommand',
+    CorrelationRootId = 'CorrelationRootId',
+    AggregateType = 'AggregateType',
+    Year = 'Year',
+    Month = 'Month',
+    Day = 'Day',
+    TimeBucket = 'TimeBucket'
+}

package/patterns/FacetSet.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * A partial context of facet names and values. Use {@link FacetName} for well-known names;
+ * other names are accepted, but the kernel discards facets outside its configured mining vocabulary rather than
+ * narrowing to nothing. An empty object constrains nothing. Empty values are omitted from queries.
+ */
+export type FacetSet = Readonly<Record<string, string>>;

package/patterns/IPatterns.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { BehaviorPattern } from './BehaviorPattern.js';
+import type { FacetSet } from './FacetSet.js';
+import type { PatternMoment } from './PatternMoment.js';
+import type { PatternQueryOptions } from './PatternQueryOptions.js';
+import type { PatternsAtOptions } from './PatternsAtOptions.js';
+
+/** Queries behavior established in this event store and namespace. Failed queries reject, not return an empty answer. */
+export interface IPatterns {
+    /**
+     * Finds patterns describing a context, ranked by specificity then confidence.
+     * @param scope - Required grouping key, typically a user identifier.
+     * @param context - Facets to match, including the action if it is already known.
+     * @param options - Optional query limits; defaults come from the server.
+     * @returns Matching patterns, or an empty array when nothing is established for this context.
+     */
+    getPatterns(scope: string, context: FacetSet, options?: PatternQueryOptions): Promise<BehaviorPattern[]>;
+
+    /**
+     * Finds what is usually done in a context, ranked by confidence, at most one answer per action.
+     * @param scope - Required grouping key, typically a user identifier.
+     * @param context - The known situation; answers name the action through their CommandType facet.
+     * @param options - Optional query limits; defaults come from the server.
+     * @returns Usual actions, or an empty array when nothing is established for this context.
+     */
+    getUsualActions(scope: string, context: FacetSet, options?: PatternQueryOptions): Promise<BehaviorPattern[]>;
+
+    /**
+     * Finds what a scope usually does at a moment through getUsualActions.
+     * @param scope - Required grouping key, typically a user identifier.
+     * @param moment - An instant and its own offset; defaults to now at the system's local offset.
+     * @param options - Additional context and query limits. Derived Day and TimeBucket always take precedence.
+     * @returns Usual actions, or an empty array when nothing is established for this moment.
+     * @throws {RangeError} If the moment is invalid.
+     */
+    getPatternsAt(scope: string, moment?: PatternMoment, options?: PatternsAtOptions): Promise<BehaviorPattern[]>;
+
+    /**
+     * Gets every pattern established for a scope, without query limits.
+     * @param scope - Required grouping key.
+     * @returns All patterns held for this scope.
+     */
+    getPatternsForScope(scope: string): Promise<BehaviorPattern[]>;
+
+    /**
+     * Lists scopes with established patterns in this event store and namespace.
+     * @returns The grouping keys of scopes holding patterns.
+     */
+    getScopes(): Promise<string[]>;
+}

package/patterns/PatternMoment.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * An instant with its own UTC offset, which a JavaScript Date alone cannot retain.
+ * The offset is fixed for this instant, not an IANA time zone or a daylight-saving rule.
+ */
+export interface PatternMoment {
+    /** The instant to ask about. Must be a valid Date. */
+    readonly instant: Date;
+    /** Minutes east of UTC, from -840 to 840 inclusive, in whole minutes. For example, +02:00 is 120. */
+    readonly offsetMinutes: number;
+}

package/patterns/PatternQueryOptions.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Optional limits on a pattern query; omitted values defer to the server's configuration. */
+export interface PatternQueryOptions {
+    /** Lowest confidence to return, from 0 to 1. Zero selects the server's configured threshold. */
+    readonly minimumConfidence?: number;
+    /** Maximum number of answers. Zero selects the server's configured default. */
+    readonly maximumResults?: number;
+}

package/patterns/Patterns.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 type { MatchingPatternsRequest } from '@cratis/chronicle.contracts';
+import type { ChronicleConnection } from '../connection/index.js';
+import { ensureQuerySuccess } from '../connection/callResults.js';
+import type { BehaviorPattern } from './BehaviorPattern.js';
+import { FacetName } from './FacetName.js';
+import type { FacetSet } from './FacetSet.js';
+import type { IPatterns } from './IPatterns.js';
+import type { PatternMoment } from './PatternMoment.js';
+import type { PatternQueryOptions } from './PatternQueryOptions.js';
+import type { PatternsAtOptions } from './PatternsAtOptions.js';
+import { toBehaviorPattern } from './toBehaviorPattern.js';
+import { toDayOfWeek } from './toDayOfWeek.js';
+import { toTimeBucket } from './toTimeBucket.js';
+
+/** Implements {@link IPatterns} using the connection's pattern service. */
+export class Patterns implements IPatterns {
+    /**
+     * Creates the pattern query surface for an event store namespace.
+     * @param _eventStore - Event store name.
+     * @param _namespace - Event store namespace.
+     * @param _connection - Chronicle connection.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection
+    ) {}
+
+    /** @inheritdoc */
+    async getPatterns(scope: string, context: FacetSet, options: PatternQueryOptions = {}): Promise<BehaviorPattern[]> {
+        const response = await this._connection.patterns.matchingPatterns(this.createRequest(scope, context, options));
+        return ensureQuerySuccess('get patterns', response).map(toBehaviorPattern);
+    }
+
+    /** @inheritdoc */
+    async getUsualActions(scope: string, context: FacetSet, options: PatternQueryOptions = {}): Promise<BehaviorPattern[]> {
+        const response = await this._connection.patterns.usualActions(this.createRequest(scope, context, options));
+        return ensureQuerySuccess('get usual actions', response).map(toBehaviorPattern);
+    }
+
+    /** @inheritdoc */
+    async getPatternsAt(scope: string, moment?: PatternMoment, options: PatternsAtOptions = {}): Promise<BehaviorPattern[]> {
+        if (!moment) {
+            const instant = new Date();
+            moment = { instant, offsetMinutes: -instant.getTimezoneOffset() };
+        }
+        const context: FacetSet = {
+            ...options.alsoConstraining,
+            [FacetName.Day]: toDayOfWeek(moment),
+            [FacetName.TimeBucket]: toTimeBucket(moment)
+        };
+        return this.getUsualActions(scope, context, options);
+    }
+
+    /** @inheritdoc */
+    async getPatternsForScope(scope: string): Promise<BehaviorPattern[]> {
+        const response = await this._connection.patterns.patternsForScope({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            GroupingKey: scope
+        });
+        return ensureQuerySuccess('get patterns for scope', response).map(toBehaviorPattern);
+    }
+
+    /** @inheritdoc */
+    async getScopes(): Promise<string[]> {
+        const response = await this._connection.patterns.allPatternScopes({
+            EventStore: this._eventStore,
+            Namespace: this._namespace
+        });
+        return ensureQuerySuccess('get pattern scopes', response).map(scope => scope.Id);
+    }
+
+    private createRequest(scope: string, context: FacetSet, options: PatternQueryOptions): MatchingPatternsRequest {
+        return {
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            GroupingKey: scope,
+            Context: Object.fromEntries(Object.entries(context).filter(([, value]) => value.length > 0)),
+            // Zero asks the server to use its configuration, rather than duplicating thresholds in the client.
+            MinimumConfidence: options.minimumConfidence ?? 0,
+            MaximumResults: options.maximumResults ?? 0
+        };
+    }
+}

package/patterns/PatternsAtOptions.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.
+
+import type { FacetSet } from './FacetSet.js';
+import type { PatternQueryOptions } from './PatternQueryOptions.js';
+
+/** Additional context and limits when asking about a moment. */
+export interface PatternsAtOptions extends PatternQueryOptions {
+    /** Additional facets. The moment's Day and TimeBucket replace any supplied values for those names. */
+    readonly alsoConstraining?: FacetSet;
+}

package/patterns/TimeBucket.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Parts of a day, using the same names and boundaries as Chronicle's pattern miner. */
+export enum TimeBucket {
+    /** 05:00 inclusive to 08:00 exclusive. */
+    EarlyMorning = 'EarlyMorning',
+    /** 08:00 inclusive to 11:00 exclusive. */
+    Morning = 'Morning',
+    /** 11:00 inclusive to 14:00 exclusive. */
+    Midday = 'Midday',
+    /** 14:00 inclusive to 17:00 exclusive. */
+    Afternoon = 'Afternoon',
+    /** 17:00 inclusive to 22:00 exclusive. */
+    Evening = 'Evening',
+    /** 22:00 inclusive to 05:00 exclusive, crossing midnight. */
+    Night = 'Night'
+}

package/patterns/for_PatternMoment/when_deriving_facets/with_invalid_moments.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { type PatternMoment, toDayOfWeek, toTimeBucket } from '../../index.js';
+
+chai.should();
+
+const invalidMoments: PatternMoment[] = [
+    { instant: new Date(NaN), offsetMinutes: 0 },
+    { instant: new Date(0), offsetMinutes: NaN },
+    { instant: new Date(0), offsetMinutes: Infinity },
+    { instant: new Date(0), offsetMinutes: 1.5 },
+    { instant: new Date(0), offsetMinutes: 841 },
+    { instant: new Date(0), offsetMinutes: -841 },
+    { instant: new Date(8_640_000_000_000_000), offsetMinutes: 60 }
+];
+
+for (const helper of [toDayOfWeek, toTimeBucket]) {
+    for (const moment of invalidMoments) {
+        describe(`when ${helper.name} receives ${moment.instant} at offset ${moment.offsetMinutes}`, () => {
+            let failure: unknown;
+            beforeEach(() => {
+                try { helper(moment); } catch (error) { failure = error; }
+            });
+            it('should reject rather than silently ask about a different context', () => {
+                (failure as Error).should.be.instanceOf(RangeError);
+            });
+        });
+    }
+}

package/patterns/for_Patterns/given/a_patterns_service.fixture.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.
+
+import { vi } from 'vitest';
+import { QueryResultIEnumerableBehaviorPatternDetailsResponse, QueryResultIEnumerablePatternScopeResponse } from '@cratis/chronicle.contracts';
+import type { PatternsClient } from '@cratis/chronicle.contracts';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { Patterns } from '../../Patterns.js';
+
+export class a_patterns_service {
+    response = QueryResultIEnumerableBehaviorPatternDetailsResponse.create({ IsAuthorized: true });
+    scopesResponse = QueryResultIEnumerablePatternScopeResponse.create({ IsAuthorized: true });
+    client = {
+        matchingPatterns: vi.fn<PatternsClient['matchingPatterns']>().mockImplementation(async () => this.response),
+        usualActions: vi.fn<PatternsClient['usualActions']>().mockImplementation(async () => this.response),
+        patternsForScope: vi.fn<PatternsClient['patternsForScope']>().mockImplementation(async () => this.response),
+        allPatternScopes: vi.fn<PatternsClient['allPatternScopes']>().mockImplementation(async () => this.scopesResponse),
+        allPatterns: vi.fn<PatternsClient['allPatterns']>()
+    } satisfies PatternsClient;
+    patterns = new Patterns('accounts', 'tenant-a', { patterns: this.client } as unknown as ChronicleConnection);
+}

package/patterns/for_Patterns/when_browsing/with_scopes.spec.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.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+chai.should();
+
+describe('when browsing established scopes', () => {
+    let context: a_patterns_service;
+    let result: string[];
+    beforeEach(async () => {
+        context = new a_patterns_service();
+        context.scopesResponse.Data = [{ Id: 'user-42', Name: 'A name', UserName: 'a-user' }];
+        result = await context.patterns.getScopes();
+    });
+    it('should return grouping keys rather than display names', () => result.should.deep.equal(['user-42']));
+    it('should stay within the event store namespace', () => {
+        context.client.allPatternScopes.mock.calls[0][0].should.deep.equal({ EventStore: 'accounts', Namespace: 'tenant-a' });
+    });
+});

package/patterns/for_Patterns/when_browsing/within_a_scope.spec.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { BehaviorPatternDetailsResponse } from '@cratis/chronicle.contracts';
+import type { BehaviorPattern } from '../../index.js';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+chai.should();
+
+describe('when browsing every pattern for a scope', () => {
+    let context: a_patterns_service;
+    let result: BehaviorPattern[];
+    beforeEach(async () => {
+        context = new a_patterns_service();
+        context.response.Data = [BehaviorPatternDetailsResponse.create({ Id: 'pattern-1', GroupingKey: 'user-42' })];
+        result = await context.patterns.getPatternsForScope('user-42');
+    });
+    it('should address the scope within the event store namespace without limits', () => {
+        context.client.patternsForScope.mock.calls[0][0].should.deep.equal({
+            EventStore: 'accounts', Namespace: 'tenant-a', GroupingKey: 'user-42'
+        });
+    });
+    it('should convert the established patterns', () => result[0].id.should.equal('pattern-1'));
+});

package/patterns/for_Patterns/when_querying/with_query_outcomes.spec.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { ChronicleCallFailed } from '../../../connection/callResults.js';
+import type { IPatterns } from '../../index.js';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+const should = chai.should();
+const queries: Record<string, (patterns: IPatterns) => Promise<unknown[]>> = {
+    matching: patterns => patterns.getPatterns('user-42', {}),
+    actions: patterns => patterns.getUsualActions('user-42', {}),
+    moment: patterns => patterns.getPatternsAt('user-42'),
+    scope: patterns => patterns.getPatternsForScope('user-42'),
+    scopes: patterns => patterns.getScopes()
+};
+
+for (const [name, query] of Object.entries(queries)) {
+    describe(`when querying ${name} with no established behavior`, () => {
+        let result: unknown[];
+        beforeEach(async () => result = await query(new a_patterns_service().patterns));
+        it('should return an empty answer without inventing behavior', () => result.should.deep.equal([]));
+    });
+
+    for (const failureKind of ['authorization', 'validation', 'exception', 'transport']) {
+        describe(`when querying ${name} with a ${failureKind} failure`, () => {
+            let failure: unknown;
+            const transportFailure = new Error('transport unavailable');
+            beforeEach(async () => {
+                const context = new a_patterns_service();
+                for (const response of [context.response, context.scopesResponse]) {
+                    if (failureKind === 'authorization') response.IsAuthorized = false;
+                    if (failureKind === 'validation') response.ValidationResults = [{ Severity: 3, Message: 'invalid context', Members: [] }];
+                    if (failureKind === 'exception') response.ExceptionMessages = ['query failed'];
+                }
+                if (failureKind === 'transport') {
+                    for (const client of Object.values(context.client)) client.mockRejectedValue(transportFailure);
+                }
+                try { await query(context.patterns); } catch (error) { failure = error; }
+            });
+            it('should reject instead of disguising failure as no behavior', () => {
+                if (failureKind === 'transport') should.equal(failure, transportFailure);
+                else (failure as Error).should.be.instanceOf(ChronicleCallFailed);
+            });
+        });
+    }
+}

package/patterns/for_Patterns/when_querying_a_context/with_established_patterns.spec.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { BehaviorPatternDetailsResponse } from '@cratis/chronicle.contracts';
+import type { BehaviorPattern } from '../../index.js';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+const should = chai.should();
+
+describe('when querying a context with established patterns', () => {
+    let result: BehaviorPattern[];
+    beforeEach(async () => {
+        const context = new a_patterns_service();
+        context.response.Data = [
+            BehaviorPatternDetailsResponse.create({
+                Id: 'pattern-1', GroupingKey: 'user-42', Facets: { Day: 'Monday', CommandType: 'RegisterInvoice' },
+                Confidence: 0.75, Support: 0.2, Occurrences: 9_007_199_254_740_993n, Weight: 3.5, Specificity: 2,
+                FirstSeen: { Value: '2026-01-05T09:00:00+02:00' }, LastSeen: { Value: '2026-01-12T09:00:00+02:00' }
+            }),
+            BehaviorPatternDetailsResponse.create({ Id: 'pattern-2', Confidence: 0.95 })
+        ];
+        result = await context.patterns.getPatterns('user-42', {});
+    });
+    it('should convert every response field without losing occurrence precision', () => {
+        result[0].should.deep.equal({
+            id: 'pattern-1', groupingKey: 'user-42', facets: { Day: 'Monday', CommandType: 'RegisterInvoice' },
+            confidence: 0.75, support: 0.2, occurrences: 9_007_199_254_740_993n, weight: 3.5, specificity: 2,
+            firstSeen: new Date('2026-01-05T07:00:00Z'), lastSeen: new Date('2026-01-12T07:00:00Z')
+        });
+    });
+    it('should preserve the server ranking', () => result.map(pattern => pattern.id).should.deep.equal(['pattern-1', 'pattern-2']));
+    it('should not invent a missing observation timestamp', () => should.equal(result[1].firstSeen, undefined));
+});

package/patterns/for_Patterns/when_querying_a_context/with_facets.spec.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { FacetName } from '../../index.js';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+chai.should();
+
+for (const method of ['getPatterns', 'getUsualActions'] as const) {
+    for (const limited of [false, true]) {
+        describe(`when ${method} queries facets ${limited ? 'with explicit limits' : 'with server defaults'}`, () => {
+            let context: a_patterns_service;
+            beforeEach(async () => {
+                context = new a_patterns_service();
+                await context.patterns[method]('user-42', {
+                    [FacetName.CommandType]: 'RegisterInvoice',
+                    [FacetName.AggregateType]: '',
+                    CustomFacet: 'custom-value'
+                }, limited ? { minimumConfidence: 0.75, maximumResults: 3 } : undefined);
+            });
+            it('should scope the query and omit unspecified facet values', () => {
+                const client = method === 'getPatterns' ? context.client.matchingPatterns : context.client.usualActions;
+                client.mock.calls[0][0].should.deep.equal({
+                    EventStore: 'accounts', Namespace: 'tenant-a', GroupingKey: 'user-42',
+                    Context: { CommandType: 'RegisterInvoice', CustomFacet: 'custom-value' },
+                    MinimumConfidence: limited ? 0.75 : 0, MaximumResults: limited ? 3 : 0
+                });
+            });
+        });
+    }
+}

package/patterns/for_Patterns/when_querying_at_a_moment/with_additional_facets.spec.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { DayOfWeek, FacetName, type FacetSet, TimeBucket } from '../../index.js';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+chai.should();
+
+describe('when querying at a moment with additional facets', () => {
+    let context: a_patterns_service;
+    const facets: FacetSet = Object.freeze({
+        [FacetName.AggregateType]: 'Invoice',
+        [FacetName.CommandType]: 'RegisterInvoice',
+        [FacetName.Day]: DayOfWeek.Friday,
+        [FacetName.TimeBucket]: TimeBucket.Evening,
+        CustomFacet: 'custom-value'
+    });
+    beforeEach(async () => {
+        context = new a_patterns_service();
+        await context.patterns.getPatternsAt('user-42', {
+            instant: new Date('2026-01-04T23:30:00Z'), offsetMinutes: 345
+        }, { alsoConstraining: facets, minimumConfidence: 0.8, maximumResults: 5 });
+    });
+    it('should ask about usual actions in the explicit offset day and bucket', () => {
+        context.client.usualActions.mock.calls[0][0].should.deep.equal({
+            EventStore: 'accounts', Namespace: 'tenant-a', GroupingKey: 'user-42',
+            Context: { ...facets, Day: DayOfWeek.Monday, TimeBucket: TimeBucket.EarlyMorning },
+            MinimumConfidence: 0.8, MaximumResults: 5
+        });
+    });
+    it('should not use the descriptive matching endpoint', () => context.client.matchingPatterns.mock.calls.should.have.lengthOf(0));
+    it('should leave the caller context unchanged', () => facets[FacetName.Day].should.equal(DayOfWeek.Friday));
+});

package/patterns/for_Patterns/when_querying_at_a_moment/with_an_invalid_moment.spec.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+chai.should();
+
+describe('when querying an invalid moment', () => {
+    let context: a_patterns_service;
+    let failure: unknown;
+    beforeEach(async () => {
+        context = new a_patterns_service();
+        try {
+            await context.patterns.getPatternsAt('user-42', { instant: new Date(NaN), offsetMinutes: 0 });
+        } catch (error) { failure = error; }
+    });
+    it('should reject the query', () => (failure as Error).should.be.instanceOf(RangeError));
+    it('should not send a misleading context to the kernel', () => context.client.usualActions.mock.calls.should.have.lengthOf(0));
+});

package/patterns/for_Patterns/when_querying_at_a_moment/without_a_moment.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 { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
+import { DayOfWeek, FacetName, TimeBucket } from '../../index.js';
+import { a_patterns_service } from '../given/a_patterns_service.fixture.js';
+
+chai.should();
+
+for (const withOptions of [false, true]) {
+    describe(`when querying now ${withOptions ? 'with additional facets' : 'with only a scope'}`, () => {
+        let context: a_patterns_service;
+        beforeEach(async () => {
+            vi.useFakeTimers({ toFake: ['Date'] });
+            vi.setSystemTime(new Date('2026-01-05T01:00:00Z'));
+            // Simulate a machine west of UTC regardless of the machine running the specs.
+            vi.spyOn(Date.prototype, 'getTimezoneOffset').mockReturnValue(240);
+            context = new a_patterns_service();
+            if (withOptions) {
+                await context.patterns.getPatternsAt('user-42', undefined, { alsoConstraining: { [FacetName.AggregateType]: 'Invoice' } });
+            } else {
+                await context.patterns.getPatternsAt('user-42');
+            }
+        });
+        afterEach(() => { vi.restoreAllMocks(); vi.useRealTimers(); });
+        it('should capture now at the local system offset with server default limits', () => {
+            context.client.usualActions.mock.calls[0][0].should.deep.equal({
+                EventStore: 'accounts', Namespace: 'tenant-a', GroupingKey: 'user-42',
+                Context: {
+                    ...(withOptions ? { AggregateType: 'Invoice' } : {}),
+                    Day: DayOfWeek.Sunday, TimeBucket: TimeBucket.Evening
+                },
+                MinimumConfidence: 0, MaximumResults: 0
+            });
+        });
+    });
+}