@spine-event-engine/server 2.0.0-snapshot.2

package/dist/repository/command-errors.d.ts

@@ -0,0 +1,25 @@
+import type { ValidationError } from "@spine-event-engine/proto";
+/**
+ * Error raised when aggregate command execution rejects a state transition.
+ */
+export declare class TransitionValidationError extends Error {
+    /**
+     * Stable client-visible error type returned in `Ack.status.error.type`.
+     */
+    readonly type = "COMMAND_STATE_TRANSITION_VALIDATION_FAILED";
+    /**
+     * Stable client-visible error message returned in `Ack.status.error.message`.
+     */
+    readonly clientMessage = "Command state transition validation failed.";
+    /**
+     * Structured transition validation details from the entity transaction boundary.
+     */
+    readonly validationError: ValidationError;
+    /**
+     * Creates an aggregate transition validation error.
+     *
+     * @param validationError Structured details explaining the rejected transition.
+     */
+    constructor(validationError: ValidationError);
+}
+//# sourceMappingURL=command-errors.d.ts.map

package/dist/repository/command-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-errors.d.ts","sourceRoot":"","sources":["../../src/repository/command-errors.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAGlD;;OAEG;IACH,QAAQ,CAAC,IAAI,gDAAgD;IAE7D;;OAEG;IACH,QAAQ,CAAC,aAAa,iDAAiD;IAEvE;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;OAIG;gBACS,eAAe,EAAE,eAAe;CAM7C"}

package/dist/repository/command-errors.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Error raised when aggregate command execution rejects a state transition.
+ */
+export class TransitionValidationError extends Error {
+    // prettier-ignore
+    /**
+     * Stable client-visible error type returned in `Ack.status.error.type`.
+     */
+    type = "COMMAND_STATE_TRANSITION_VALIDATION_FAILED";
+    /**
+     * Stable client-visible error message returned in `Ack.status.error.message`.
+     */
+    clientMessage = "Command state transition validation failed.";
+    /**
+     * Structured transition validation details from the entity transaction boundary.
+     */
+    validationError;
+    /**
+     * Creates an aggregate transition validation error.
+     *
+     * @param validationError Structured details explaining the rejected transition.
+     */
+    constructor(validationError) {
+        super("Command state transition validation failed.");
+        this.name = "TransitionValidationError";
+        this.validationError = validationError;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=command-errors.js.map

package/dist/repository/command-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-errors.js","sourceRoot":"","sources":["../../src/repository/command-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;GAEG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,kBAAkB;IAElB;;OAEG;IACM,IAAI,GAAG,4CAA4C,CAAC;IAE7D;;OAEG;IACM,aAAa,GAAG,6CAA6C,CAAC;IAEvE;;OAEG;IACM,eAAe,CAAkB;IAE1C;;;;OAIG;IACH,YAAY,eAAgC;QAC1C,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/repository/command-routing.d.ts

@@ -0,0 +1,72 @@
+import type { MessageShape } from "@bufbuild/protobuf";
+import { type MessageInterface, type MessageSchema } from "@spine-event-engine/core";
+import type { CommandContext } from "@spine-event-engine/proto";
+import { type InterfaceRouteSchemas, type InterfaceRouteMessage, type RoutingDeclarationSnapshot, type RoutingDeclarationState } from "./routing-declarations.js";
+/**
+ * Calculates one Entity ID for a Command message.
+ *
+ * @typeParam Id Entity ID type owned by the receiving repository.
+ * @typeParam Schema Generated Command message schema.
+ * @param message Unpacked Command message.
+ * @param context Normalized Command context. When the signal omits its context,
+ *   the framework supplies the default generated `CommandContext` value.
+ * The route must be deterministic and side-effect-free. The framework invokes
+ * it once for each accepted admission, and durable replay uses the stored
+ * target instead of invoking it again.
+ *
+ * @returns Target Entity ID.
+ */
+export type CommandRoute<Id, Schema extends MessageSchema = MessageSchema> = (message: MessageShape<Schema>, context: CommandContext) => Id;
+type CommandRoutingState<Id> = RoutingDeclarationState<CommandRoute<Id>>;
+/**
+ * Mutable Command route declarations that repositories snapshot at construction.
+ *
+ * @typeParam Id Entity ID type owned by the receiving repository.
+ */
+export declare class CommandRouting<Id> {
+    /**
+     * Creates empty mutable Command route declarations.
+     */
+    private constructor();
+    /**
+     * Creates empty Command route declarations.
+     *
+     * @typeParam Id Entity ID type owned by the receiving repository.
+     * @returns Mutable Command route declarations.
+     */
+    static create<Id>(): CommandRouting<Id>;
+    /**
+     * Registers a route for one exact generated Command schema.
+     *
+     * @param schemaOrToken Generated Command schema.
+     * @param via Route that calculates the target Entity ID.
+     * @returns These mutable route declarations.
+     */
+    route<Schema extends MessageSchema>(schemaOrToken: Schema, via: CommandRoute<Id, Schema>): this;
+    /**
+     * Registers a route for a nominal Command message-interface token.
+     *
+     * @param schemaOrToken Generated Command message-interface token.
+     * @param via Route that calculates the target Entity ID.
+     * @returns These mutable route declarations.
+     */
+    route<TInterface extends object, Schemas extends InterfaceRouteSchemas>(schemaOrToken: MessageInterface<TInterface, Schemas>, via: (message: InterfaceRouteMessage<TInterface, Schemas>, context: CommandContext) => Id): this;
+    /**
+     * Replaces the declaration-first default Command route.
+     *
+     * @param via Route that calculates the target Entity ID.
+     * @returns These mutable route declarations.
+     */
+    replaceDefault(via: CommandRoute<Id>): this;
+}
+/**
+ * Internal access to Command-routing declaration state.
+ *
+ * @internal
+ */
+export declare const CommandRoutingInternals: Readonly<{
+    state<Id>(routing: CommandRouting<Id>): CommandRoutingState<Id>;
+    snapshot<Id>(routing: CommandRouting<Id> | undefined): RoutingDeclarationSnapshot<CommandRoute<Id>>;
+}>;
+export {};
+//# sourceMappingURL=command-routing.d.ts.map

package/dist/repository/command-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-routing.d.ts","sourceRoot":"","sources":["../../src/repository/command-routing.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC7B,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,CAAC,EAAE,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,IAAI,CAC3E,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,cAAc,KACpB,EAAE,CAAC;AAER,KAAK,mBAAmB,CAAC,EAAE,IAAI,uBAAuB,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC;AAIzE;;;;GAIG;AACH,qBAAa,cAAc,CAAC,EAAE;IAG5B;;OAEG;IACH,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,cAAc,CAAC,EAAE,CAAC;IAIvC;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,SAAS,aAAa,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,CAAC,EAAE,EAAE,MAAM,CAAC,GAAG,IAAI;IAE/F;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,SAAS,MAAM,EAAE,OAAO,SAAS,qBAAqB,EACpE,aAAa,EAAE,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,EACpD,GAAG,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,cAAc,KAAK,EAAE,GACxF,IAAI;IAwCP;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI;CAM5C;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC;IAC7C,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAChE,QAAQ,CAAC,EAAE,EACT,OAAO,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,SAAS,GACtC,0BAA0B,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC;CACjD,CAYC,CAAC"}

package/dist/repository/command-routing.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import {} from "@spine-event-engine/core";
+import { RoutingDeclarations, } from "./routing-declarations.js";
+const routingStates = new WeakMap();
+/**
+ * Mutable Command route declarations that repositories snapshot at construction.
+ *
+ * @typeParam Id Entity ID type owned by the receiving repository.
+ */
+export class CommandRouting {
+    // prettier-ignore
+    /**
+     * Creates empty mutable Command route declarations.
+     */
+    constructor() {
+        routingStates.set(this, RoutingDeclarations.create());
+    }
+    /**
+     * Creates empty Command route declarations.
+     *
+     * @typeParam Id Entity ID type owned by the receiving repository.
+     * @returns Mutable Command route declarations.
+     */
+    static create() {
+        return new CommandRouting();
+    }
+    /**
+     * Registers an exact generated Command-schema route or a nominal message-interface route.
+     *
+     * A schema route receives its exact message shape. An interface route receives
+     * {@link InterfaceRouteMessage}, the member-message union intersected with
+     * the declared interface. Routing selects an exact schema route first, then
+     * the first matching interface token in registration order, then the
+     * replacement/default route.
+     *
+     * Copied or malformed tokens fail during declaration. Every token member must
+     * be registered by the repository, or construction fails. The selected route
+     * runs once for an accepted admission; durable replay uses stored targets and
+     * does not run routing again.
+     *
+     * @param schemaOrToken Generated Command schema or nominal message-interface token.
+     * @param via Route that calculates the target Entity ID.
+     * @returns These mutable route declarations.
+     */
+    route(schemaOrToken, via) {
+        if (typeof via !== "function")
+            throw new TypeError("Command routing requires a route function.");
+        const state = CommandRoutingInternals.state(this);
+        if (RoutingDeclarations.isInterfaceTokenCandidate(schemaOrToken)) {
+            RoutingDeclarations.routeInterface(state, schemaOrToken, via, "Command routing");
+        }
+        else {
+            RoutingDeclarations.exact(state, schemaOrToken, via, "Command routing has a duplicate exact command route.");
+        }
+        return this;
+    }
+    /**
+     * Replaces the declaration-first default Command route.
+     *
+     * @param via Route that calculates the target Entity ID.
+     * @returns These mutable route declarations.
+     */
+    replaceDefault(via) {
+        if (typeof via !== "function")
+            throw new TypeError("Command routing requires a route function.");
+        RoutingDeclarations.default(CommandRoutingInternals.state(this), via);
+        return this;
+    }
+}
+/**
+ * Internal access to Command-routing declaration state.
+ *
+ * @internal
+ */
+export const CommandRoutingInternals = Object.freeze({
+    state(routing) {
+        return routingStates.get(routing);
+    },
+    snapshot(routing) {
+        if (routing === undefined) {
+            return RoutingDeclarations.snapshot(RoutingDeclarations.create());
+        }
+        return RoutingDeclarations.snapshot(CommandRoutingInternals.state(routing));
+    },
+});
+//# sourceMappingURL=command-routing.js.map

package/dist/repository/command-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-routing.js","sourceRoot":"","sources":["../../src/repository/command-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAA6C,MAAM,0BAA0B,CAAC;AAErF,OAAO,EACL,mBAAmB,GAKpB,MAAM,2BAA2B,CAAC;AAuBnC,MAAM,aAAa,GAAG,IAAI,OAAO,EAAwC,CAAC;AAE1E;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACzB,kBAAkB;IAElB;;OAEG;IACH;QACE,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,EAAoB,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,cAAc,EAAM,CAAC;IAClC,CAAC;IAuBD;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CACH,aAA8E,EAC9E,GAAqB;QAErB,IAAI,OAAO,GAAG,KAAK,UAAU;YAC3B,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,mBAAmB,CAAC,yBAAyB,CAAC,aAAa,CAAC,EAAE,CAAC;YACjE,mBAAmB,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC;QACnF,CAAC;aAAM,CAAC;YACN,mBAAmB,CAAC,KAAK,CACvB,KAAK,EACL,aAAa,EACb,GAAG,EACH,sDAAsD,CACvD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,GAAqB;QAClC,IAAI,OAAO,GAAG,KAAK,UAAU;YAC3B,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACpE,mBAAmB,CAAC,OAAO,CAAC,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAK/B,MAAM,CAAC,MAAM,CAAC;IACjB,KAAK,CAAK,OAA2B;QACnC,OAAO,aAAa,CAAC,GAAG,CAAC,OAAO,CAA4B,CAAC;IAC/D,CAAC;IACD,QAAQ,CACN,OAAuC;QAEvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,mBAAmB,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM,EAAoB,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,mBAAmB,CAAC,QAAQ,CAAC,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9E,CAAC;CACF,CAAC,CAAC"}

package/dist/repository/commit-fence.d.ts

@@ -0,0 +1,22 @@
+interface Commit {
+    readonly status: string;
+}
+type Guard = () => Promise<void>;
+/**
+ * Executes a delivery callback with a commit-time ownership guard.
+ *
+ * @param guard Verifies that the delivery worker still owns its shard.
+ * @param callback Performs the delivery work within the guarded scope.
+ * @returns The value produced by the delivery callback.
+ */
+export declare function withDeliveryCommitFence<T>(guard: Guard, callback: () => Promise<T>): Promise<T>;
+/**
+ * Verifies delivery ownership immediately before committing an Entity.
+ *
+ * @param entity Supplies the Entity whose transaction is committed.
+ * @param commit Commits the active Entity transaction synchronously.
+ * @returns The result produced by the Entity transaction commit.
+ */
+export declare function commitFenced<T extends Commit>(entity: object, commit: (entity: object) => T): Promise<T>;
+export {};
+//# sourceMappingURL=commit-fence.d.ts.map

package/dist/repository/commit-fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-fence.d.ts","sourceRoot":"","sources":["../../src/repository/commit-fence.ts"],"names":[],"mappings":"AAgBA,UAAU,MAAM;IACd,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACD,KAAK,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAIjC;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,EACjD,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/repository/commit-fence.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const fences = new AsyncLocalStorage();
+/**
+ * Executes a delivery callback with a commit-time ownership guard.
+ *
+ * @param guard Verifies that the delivery worker still owns its shard.
+ * @param callback Performs the delivery work within the guarded scope.
+ * @returns The value produced by the delivery callback.
+ */
+export async function withDeliveryCommitFence(guard, callback) {
+    return fences.run(guard, callback);
+}
+/**
+ * Verifies delivery ownership immediately before committing an Entity.
+ *
+ * @param entity Supplies the Entity whose transaction is committed.
+ * @param commit Commits the active Entity transaction synchronously.
+ * @returns The result produced by the Entity transaction commit.
+ */
+export async function commitFenced(entity, commit) {
+    await fences.getStore()?.();
+    return commit(entity);
+}
+//# sourceMappingURL=commit-fence.js.map

package/dist/repository/commit-fence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-fence.js","sourceRoot":"","sources":["../../src/repository/commit-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrD,MAAM,MAAM,GAAG,IAAI,iBAAiB,EAAS,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAY,EACZ,QAA0B;IAE1B,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,MAA6B;IAE7B,MAAM,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC5B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}

package/dist/repository/event-routing.d.ts

@@ -0,0 +1,71 @@
+import type { MessageShape } from "@bufbuild/protobuf";
+import { type MessageInterface, type MessageSchema } from "@spine-event-engine/core";
+import type { EventContext } from "@spine-event-engine/proto";
+import { type InterfaceRouteSchemas, type InterfaceRouteMessage, type RoutingDeclarationSnapshot, type RoutingDeclarationState } from "./routing-declarations.js";
+/**
+ * Calculates target Entity IDs for one Event admission.
+ *
+ * The route must be deterministic and side-effect-free. It runs once for an
+ * accepted admission; durable replay uses stored targets instead.
+ *
+ * @typeParam Id Entity ID type used by the receiving repository.
+ * @typeParam Schema Generated Event message schema.
+ * @param message Unpacked Event message.
+ * @param context Normalized Event context. When the signal omits its context,
+ *   the framework supplies the default generated `EventContext` value.
+ * @returns Up to 1,000 target Entity IDs. The framework validates the complete
+ *   result, copies and stable-deduplicates its IDs, and freezes the accepted
+ *   plan. An empty array deliberately suppresses delivery to this repository.
+ */
+export type EventRoute<Id, Schema extends MessageSchema = MessageSchema> = (message: MessageShape<Schema>, context: EventContext) => readonly Id[];
+type State<Id> = RoutingDeclarationState<EventRoute<Id>>;
+/**
+ * Mutable Event route declarations snapshotted by repository construction.
+ */
+export declare class EventRouting<Id> {
+    /**
+     * Creates empty mutable Event route declarations.
+     */
+    private constructor();
+    /**
+     * Creates empty Event route declarations.
+     *
+     * @typeParam Id Entity ID type used by the receiving repository.
+     * @returns Mutable Event route declarations.
+     */
+    static create<Id>(): EventRouting<Id>;
+    /**
+     * Registers a route for one exact generated Event schema.
+     *
+     * @param schemaOrToken Generated Event schema.
+     * @param via Route that calculates target Entity IDs.
+     * @returns These mutable route declarations.
+     */
+    route<Schema extends MessageSchema>(schemaOrToken: Schema, via: EventRoute<Id, Schema>): this;
+    /**
+     * Registers a route for a nominal Event message-interface token.
+     *
+     * @param schemaOrToken Generated Event message-interface token.
+     * @param via Route that calculates target Entity IDs.
+     * @returns These mutable route declarations.
+     */
+    route<TInterface extends object, Schemas extends InterfaceRouteSchemas>(schemaOrToken: MessageInterface<TInterface, Schemas>, via: (message: InterfaceRouteMessage<TInterface, Schemas>, context: EventContext) => readonly Id[]): this;
+    /**
+     * Replaces the producer-aware default Event route.
+     *
+     * @param via Route that calculates target Entity IDs.
+     * @returns These mutable route declarations.
+     */
+    replaceDefault(via: EventRoute<Id>): this;
+}
+/**
+ * Internal access to Event-routing declaration state.
+ *
+ * @internal
+ */
+export declare const EventRoutingInternals: Readonly<{
+    state<Id>(routing: EventRouting<Id>): State<Id>;
+    snapshot<Id>(routing: EventRouting<Id> | undefined): RoutingDeclarationSnapshot<EventRoute<Id>>;
+}>;
+export {};
+//# sourceMappingURL=event-routing.d.ts.map

package/dist/repository/event-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-routing.d.ts","sourceRoot":"","sources":["../../src/repository/event-routing.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC7B,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,EAAE,MAAM,SAAS,aAAa,GAAG,aAAa,IAAI,CACzE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,YAAY,KAClB,SAAS,EAAE,EAAE,CAAC;AAEnB,KAAK,KAAK,CAAC,EAAE,IAAI,uBAAuB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;AAGzD;;GAEG;AACH,qBAAa,YAAY,CAAC,EAAE;IAG1B;;OAEG;IACH,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,YAAY,CAAC,EAAE,CAAC;IAIrC;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,SAAS,aAAa,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,GAAG,IAAI;IAE7F;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,SAAS,MAAM,EAAE,OAAO,SAAS,qBAAqB,EACpE,aAAa,EAAE,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,EACpD,GAAG,EAAE,CACH,OAAO,EAAE,qBAAqB,CAAC,UAAU,EAAE,OAAO,CAAC,EACnD,OAAO,EAAE,YAAY,KAClB,SAAS,EAAE,EAAE,GACjB,IAAI;IAuCP;;;;;OAKG;IACH,cAAc,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI;CAK1C;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC;IAC3C,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,0BAA0B,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;CACjG,CAUC,CAAC"}

package/dist/repository/event-routing.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import {} from "@spine-event-engine/core";
+import { RoutingDeclarations, } from "./routing-declarations.js";
+const states = new WeakMap();
+/**
+ * Mutable Event route declarations snapshotted by repository construction.
+ */
+export class EventRouting {
+    // prettier-ignore
+    /**
+     * Creates empty mutable Event route declarations.
+     */
+    constructor() {
+        states.set(this, RoutingDeclarations.create());
+    }
+    /**
+     * Creates empty Event route declarations.
+     *
+     * @typeParam Id Entity ID type used by the receiving repository.
+     * @returns Mutable Event route declarations.
+     */
+    static create() {
+        return new EventRouting();
+    }
+    /**
+     * Registers an exact generated Event-schema route or a nominal message-interface route.
+     *
+     * A schema route receives its exact message shape. An interface route receives
+     * {@link InterfaceRouteMessage}, the member-message union intersected with
+     * the declared interface. Routing selects an exact schema route first, then
+     * the first matching interface token in registration order, then the
+     * replacement/default route.
+     *
+     * Copied or malformed tokens fail during declaration. Every token member must
+     * be registered by the repository, or construction fails. The selected route
+     * runs once for an accepted admission; durable replay uses stored targets and
+     * does not run routing again.
+     *
+     * @param schemaOrToken Generated Event schema or nominal message-interface token.
+     * @param via Route that calculates target Entity IDs.
+     * @returns These mutable route declarations.
+     */
+    route(schemaOrToken, via) {
+        if (typeof via !== "function")
+            throw new TypeError("Event routing requires a route function.");
+        const state = EventRoutingInternals.state(this);
+        if (RoutingDeclarations.isInterfaceTokenCandidate(schemaOrToken)) {
+            RoutingDeclarations.routeInterface(state, schemaOrToken, via, "Event routing");
+        }
+        else {
+            RoutingDeclarations.exact(state, schemaOrToken, via, "Event routing has a duplicate exact event route.");
+        }
+        return this;
+    }
+    /**
+     * Replaces the producer-aware default Event route.
+     *
+     * @param via Route that calculates target Entity IDs.
+     * @returns These mutable route declarations.
+     */
+    replaceDefault(via) {
+        if (typeof via !== "function")
+            throw new TypeError("Event routing requires a route function.");
+        RoutingDeclarations.default(EventRoutingInternals.state(this), via);
+        return this;
+    }
+}
+/**
+ * Internal access to Event-routing declaration state.
+ *
+ * @internal
+ */
+export const EventRoutingInternals = Object.freeze({
+    state(routing) {
+        return states.get(routing);
+    },
+    snapshot(routing) {
+        if (routing === undefined) {
+            return RoutingDeclarations.snapshot(RoutingDeclarations.create());
+        }
+        return RoutingDeclarations.snapshot(EventRoutingInternals.state(routing));
+    },
+});
+//# sourceMappingURL=event-routing.js.map

package/dist/repository/event-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-routing.js","sourceRoot":"","sources":["../../src/repository/event-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAA6C,MAAM,0BAA0B,CAAC;AAErF,OAAO,EACL,mBAAmB,GAKpB,MAAM,2BAA2B,CAAC;AAuBnC,MAAM,MAAM,GAAG,IAAI,OAAO,EAA0B,CAAC;AAErD;;GAEG;AACH,MAAM,OAAO,YAAY;IACvB,kBAAkB;IAElB;;OAEG;IACH;QACE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,EAAkB,CAAC,CAAC;IACjE,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,YAAY,EAAM,CAAC;IAChC,CAAC;IA0BD;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CACH,aAA8E,EAC9E,GAAmB;QAEnB,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;QAC/F,MAAM,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,mBAAmB,CAAC,yBAAyB,CAAC,aAAa,CAAC,EAAE,CAAC;YACjE,mBAAmB,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC;QACjF,CAAC;aAAM,CAAC;YACN,mBAAmB,CAAC,KAAK,CACvB,KAAK,EACL,aAAa,EACb,GAAG,EACH,kDAAkD,CACnD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,GAAmB;QAChC,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,MAAM,IAAI,SAAS,CAAC,0CAA0C,CAAC,CAAC;QAC/F,mBAAmB,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAG7B,MAAM,CAAC,MAAM,CAAC;IACjB,KAAK,CAAK,OAAyB;QACjC,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAc,CAAC;IAC1C,CAAC;IACD,QAAQ,CAAK,OAAqC;QAChD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,mBAAmB,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM,EAAkB,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,mBAAmB,CAAC,QAAQ,CAAC,qBAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5E,CAAC;CACF,CAAC,CAAC"}

package/dist/repository/primitive-id.d.ts

@@ -0,0 +1,86 @@
+import { type Any } from "@bufbuild/protobuf/wkt";
+/**
+ * Represents a scalar value that may identify an entity.
+ */
+export type PrimitiveId = string | number | bigint | boolean;
+/**
+ * Packs and reads scalar entity identifiers.
+ */
+export interface PrimitiveIdCodec {
+    /**
+     * Packs an identifier into a Protobuf `Any` value.
+     *
+     * @param id Identifier to pack.
+     * @returns Packed identifier.
+     */
+    pack(id: PrimitiveId): Any;
+    /**
+     * Reads a scalar identifier from an unknown value.
+     *
+     * @param value Value to inspect.
+     * @returns Scalar identifier, or `undefined` when the value is unsupported.
+     */
+    read(value: unknown): PrimitiveId | undefined;
+    /**
+     * Reads a finite scalar identifier from an unknown value.
+     *
+     * @param value Value to inspect.
+     * @returns Scalar identifier, or `undefined` when it is unsupported or non-finite.
+     */
+    readFinite(value: unknown): PrimitiveId | undefined;
+    /**
+     * Unpacks a scalar identifier from a Protobuf `Any` value.
+     *
+     * @param id Packed identifier to unpack.
+     * @returns Scalar identifier, or `undefined` when it is absent or unsupported.
+     */
+    unpack(id: Any | undefined): PrimitiveId | undefined;
+}
+/**
+ * Describes the type name and scalar value of a message-shaped identifier.
+ */
+export interface MessageId {
+    /**
+     * Declares the fully-qualified Protobuf message type name.
+     */
+    readonly $typeName: string;
+    /**
+     * Holds the scalar identifier value.
+     */
+    readonly value: PrimitiveId;
+}
+/**
+ * Reads and keys message-shaped entity identifiers.
+ */
+export interface MessageIdCodec {
+    /**
+     * Reads a message-shaped identifier from an unknown value.
+     *
+     * @param value Value to inspect.
+     * @returns Identifier, or `undefined` when the value is malformed.
+     */
+    read(value: unknown): MessageId | undefined;
+    /**
+     * Reads the scalar value from a message-shaped identifier.
+     *
+     * @param value Value to inspect.
+     * @returns Scalar identifier, or `undefined` when the value is malformed.
+     */
+    readValue(value: unknown): PrimitiveId | undefined;
+    /**
+     * Creates a stable storage key for a message-shaped identifier.
+     *
+     * @param id Identifier to encode.
+     * @returns Stable key that distinguishes message type and scalar value type.
+     */
+    key(id: MessageId): string;
+}
+/**
+ * Provides the default scalar identifier codec.
+ */
+export declare const PrimitiveIds: PrimitiveIdCodec;
+/**
+ * Provides the default message-shaped identifier codec.
+ */
+export declare const MessageIds: MessageIdCodec;
+//# sourceMappingURL=primitive-id.d.ts.map

package/dist/repository/primitive-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive-id.d.ts","sourceRoot":"","sources":["../../src/repository/primitive-id.ts"],"names":[],"mappings":"AAeA,OAAO,EAML,KAAK,GAAG,EACT,MAAM,wBAAwB,CAAC;AAIhC;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAG/B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,WAAW,GAAG,GAAG,CAAC;IAE3B;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IAE9C;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IAEpD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,GAAG,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IAGxB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAG7B;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IAE5C;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IAEnD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,gBAsCzB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,cAmBvB,CAAC"}