@spine-event-engine/server 2.0.0-snapshot.15 → 2.0.0-snapshot.16

package/dist/repository/repository.js

@@ -47,7 +47,7 @@ import { TransitionValidationError } from "./command-errors.js";
 import { MessageIds, PrimitiveIds } from "./primitive-id.js";
 import { ImplicitRequiredIds } from "../entity/implicit-required-id.js";
 /**
- * Describes an error raised when repository identity metadata cannot be constructed.
+ * Error raised when an Entity class and state schema cannot form a repository.
  */
 export class RepositoryIdentityError extends Error {
     // prettier-ignore
@@ -69,30 +69,17 @@ export class RepositoryIdentityError extends Error {
     }
 }
 /**
- * Repository identity and context-owned storage registration over one entity constructor and state schema.
+ * Configures storage and handlers for one Entity class.
  *
- * The class records the ownership facts bounded-context registration needs for
- * duplicate and conflict checks. Context assembly uses this metadata to attach
- * a repository to one built context and open state record storage. With
- * authentic explicit aggregate handler metadata, the built context can also
- * execute aggregate commands through repository-owned assignees and live
- * direct transactional handlers, persist the latest aggregate state plus a diagnostic event journal,
- * and hand already-stored events to the event bus. Aggregate and process-manager command
- * execution require `command.id` before routing or mutation so produced events
- * can carry a contract-valid command origin. With authentic projection
- * subscriber metadata, built contexts can also execute projection subscribers
- * and write changed projection state through the context-owned `Stand`. With
- * authentic process-manager metadata, built contexts can execute command
- * assignees, event reactors, and event-commanding handlers, storing changed
- * process-manager state through tenant-scoped Stand records with full Spine
- * Versions. The `events` option declares generated event schemas emitted by
- * aggregate and process-manager producer handlers. The repository surface still
- * does not expose direct entity lookup/storage APIs, inbox/delivery management,
- * caches, lifecycle monitors, or transport startup.
+ * Construction selects the Entity class, state schema, routing, and optional
+ * creation callback. A Bounded Context builder registers the repository. During
+ * context assembly, it opens record storage and installs handlers and Inbox
+ * targets. Aggregate handlers store state and a diagnostic event journal;
+ * Projection and Process Manager handlers store state in Stand. The `events`
+ * option lists generated event schemas that handlers may emit.
  *
- * @typeParam EntityType - A single concrete aggregate, projection, or process-manager constructor
- * with one concrete generated state schema. Broad constructor, constructor-union, broad-schema, and
- * schema-union bindings intentionally fail the public type constraint.
+ * @typeParam EntityType One concrete Aggregate, Projection, or Process Manager
+ * class with one generated state schema.
  */
 export class Repository {
     #entityType;
@@ -105,53 +92,18 @@ export class Repository {
      * @param options The entity constructor, state schema, and optional routing configuration.
      */
     constructor(options) {
-        if (!RepositoryIdentity.isRepositoryOptionsObject(options)) {
-            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", "Repository options must be a non-null object with an entity type class constructor " +
-                "extending Aggregate, Projection, or ProcessManager.");
-        }
-        const entityType = RepositoryIdentity.readEntityTypeOption(options);
-        const entityTypeDisplayName = RepositoryIdentity.entityTypeName(entityType);
-        if (typeof entityType !== "function" || !RepositoryIdentity.isClassConstructor(entityType)) {
-            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", `Repository entity type "${entityTypeDisplayName}" must be a class constructor ` +
-                "extending Aggregate, Projection, or ProcessManager.");
-        }
-        const entityFamily = RepositoryIdentity.resolveRepositoryEntityFamily(entityType);
-        if (entityFamily === undefined) {
-            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", `Repository entity type "${entityTypeDisplayName}" must extend Aggregate, Projection, or ProcessManager.`);
-        }
-        const schema = RepositoryIdentity.readRepositorySchemaOption(options, entityTypeDisplayName, entityFamily);
-        const metadata = RepositoryIdentity.describeRepositoryEntityMetadata(entityTypeDisplayName, entityFamily, schema);
-        if (metadata.kind !== entityFamily) {
-            throw new RepositoryIdentityError("ENTITY_SCHEMA_KIND_MISMATCH", `Repository entity type "${entityTypeDisplayName}" does not match ` +
-                "the supplied state schema.");
-        }
-        if (options.stateUpdateRouting !== undefined && entityFamily !== "projection") {
-            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", "State-update routing is supported only by Projection repositories.");
-        }
+        const { entityType, entityFamily, schema, metadata } = RepositoryIdentity.describeOptions(options);
         attachEntitySchema(entityType, schema);
         this.#entityType = entityType;
         this.#entityFamily = entityFamily;
         this.#metadata = metadata;
         this.#routing = RepositoryRoutes.createRepositoryRouting(this.#entityType, this.#entityFamily, this.#metadata, options.handlers, options.events ?? [], CommandRoutingInternals.snapshot(options.commandRouting), EventRoutingInternals.snapshot(options.eventRouting), StateUpdateRoutingInternals.snapshot(options.stateUpdateRouting), new StringifierRegistry(options.stringifierRegistry));
-        repositoryRoutings.set(this, this.#routing);
-        repositoryProducedEventSchemas.set(this, Object.freeze([...this.#routing.producedEventSchemas]));
-        repositoryHistoryConfigurations.set(this, RepositoryStorage.readHistoryConfiguration(options, this.#entityFamily));
-        repositorySnapshots.set(this, RepositoryIdentity.createRepositorySnapshot(this.#entityType, this.#entityFamily, this.#metadata));
-        repositoryDispatchers.set(this, RepositoryDispatch.createRepositoryDispatchers(this, this.#routing));
-        const entityInboxTarget = RepositoryDispatch.createEntityInboxTarget(this, this.#routing);
-        const projectionInboxTarget = RepositoryDispatch.createProjectionInboxTarget(this, this.#routing);
-        if (entityInboxTarget !== undefined) {
-            repositoryEntityInboxTargets.set(this, entityInboxTarget);
-        }
-        if (projectionInboxTarget !== undefined) {
-            repositoryProjectionInboxTargets.set(this, projectionInboxTarget);
-            repositoryProjectionDirect.set(this, RepositoryDispatch.createProjectionDirectDispatch(this, this.#routing));
-        }
+        RepositoryRegistration.install(this, options, this.#routing, entityType, entityFamily, metadata);
     }
     /**
-     * Returns the entity constructor owned by this repository identity.
+     * Returns the Entity class registered with this repository.
      *
-     * @returns The owned entity constructor.
+     * @returns The registered Entity class.
      */
     get entityType() {
         return this.#entityType;
@@ -167,7 +119,7 @@ export class Repository {
     /**
      * Returns the generated schema for this repository's entity state.
      *
-     * @returns The owned state schema.
+     * @returns The Entity state schema.
      */
     get stateSchema() {
         return this.#metadata.schema;
@@ -196,15 +148,15 @@ export class Repository {
         }
     }
     /**
-     * Returns descriptor-derived metadata for the owned entity state.
+     * Returns descriptor metadata for this repository's Entity state.
      *
-     * @returns A metadata view for the owned state.
+     * @returns Descriptor metadata for the Entity state.
      */
     get metadata() {
         return this.#metadata;
     }
     /**
-     * Returns the fully qualified Protobuf name of the owned entity state.
+     * Returns the fully qualified Protobuf name of the Entity state.
      *
      * @returns The state message type name.
      */
@@ -253,6 +205,7 @@ export class Repository {
     }
 }
 const repositorySnapshots = new WeakMap();
+const repositoryCreators = new WeakMap();
 const repositoryRoutings = new WeakMap();
 const repositoryProducedEventSchemas = new WeakMap();
 const repositoryDispatchers = new WeakMap();
@@ -264,6 +217,50 @@ const repositoryEntityHandles = new WeakMap();
 const entityStateHistoryCaches = new WeakMap();
 const repositoryHistoryConfigurations = new WeakMap();
 const repositoryDispatchGuards = new WeakMap();
+/**
+ * Installs repository routing, history, and callback state after identity validation.
+ */
+const RepositoryRegistration = {
+    /**
+     * Registers framework dispatch and application construction for one repository.
+     *
+     * @typeParam EntityType Concrete Entity class registered by the repository.
+     * @param repository Validated repository instance.
+     * @param options Registration options captured at construction.
+     * @param routing Resolved handler routes.
+     * @param entityType Validated Entity constructor.
+     * @param entityFamily Validated Entity family.
+     * @param metadata Validated descriptor metadata.
+     */
+    install(repository, options, routing, entityType, entityFamily, metadata) {
+        if (options.onCreate !== undefined) {
+            repositoryCreators.set(repository, options.onCreate);
+        }
+        repositoryRoutings.set(repository, routing);
+        repositoryProducedEventSchemas.set(repository, Object.freeze([...routing.producedEventSchemas]));
+        repositoryHistoryConfigurations.set(repository, RepositoryStorage.readHistoryConfiguration(options, entityFamily));
+        repositorySnapshots.set(repository, RepositoryIdentity.createRepositorySnapshot(entityType, entityFamily, metadata));
+        repositoryDispatchers.set(repository, RepositoryDispatch.createRepositoryDispatchers(repository, routing));
+        RepositoryRegistration.installTargets(repository, routing);
+    },
+    /**
+     * Registers durable Entity and direct Projection delivery targets.
+     *
+     * @param repository Repository receiving delivery targets.
+     * @param routing Resolved handler routes.
+     */
+    installTargets(repository, routing) {
+        const entityTarget = RepositoryDispatch.createEntityInboxTarget(repository, routing);
+        const projectionTarget = RepositoryDispatch.createProjectionInboxTarget(repository, routing);
+        if (entityTarget !== undefined)
+            repositoryEntityInboxTargets.set(repository, entityTarget);
+        if (projectionTarget === undefined)
+            return;
+        repositoryProjectionInboxTargets.set(repository, projectionTarget);
+        repositoryProjectionDirect.set(repository, RepositoryDispatch.createProjectionDirectDispatch(repository, routing));
+    },
+};
+Object.freeze(RepositoryRegistration);
 Object.freeze(Repository);
 /**
  * Exposes framework-only repository access for bounded-context assembly.
@@ -272,7 +269,7 @@ Object.freeze(Repository);
  */
 export const repositoryAccess = Object.freeze({
     /**
-     * Checks whether a value has registered repository identity metadata.
+     * Checks whether a value is a registered Repository.
      *
      * @param repository Value to inspect.
      * @returns Whether the value is a repository view.
@@ -281,7 +278,7 @@ export const repositoryAccess = Object.freeze({
         return repositorySnapshots.has(repository);
     },
     /**
-     * Copies a repository's immutable identity metadata.
+     * Copies the Entity class, state schema, and ID details of a Repository.
      *
      * @param repository Repository to inspect.
      * @returns A copy-safe identity snapshot.
@@ -419,6 +416,26 @@ export const repositoryAccess = Object.freeze({
     },
 });
 const inboxDedupMs = 30_000;
+/**
+ * Creates a repository Entity from framework options and an optional application constructor callback.
+ */
+const RepositoryCreation = {
+    /**
+     * Creates one Entity and rejects wrong-class or Promise results before handler execution.
+     *
+     * @param repository The registered constructor and callback.
+     * @param options Framework values for this new or restored instance.
+     * @returns The registered Entity instance.
+     */
+    create(repository, options) {
+        const onCreate = repositoryCreators.get(repository);
+        const entityType = repository.entityType;
+        const entity = onCreate === undefined ? new entityType(options) : onCreate(options);
+        if (entity instanceof entityType)
+            return entity;
+        throw new TypeError(`Repository onCreate must synchronously return a ${entityType.name} instance.`);
+    },
+};
 /**
  * Loads and persists Aggregate state within one tenant storage context.
  */
@@ -598,7 +615,6 @@ class AggregateExecutionSupport {
      * @returns The constructed Aggregate instance.
      */
     #instantiateAggregate(entityId, current) {
-        const entityType = this.#repository.entityType;
         const options = {
             id: entityId,
             schema: this.#repository.stateSchema,
@@ -608,7 +624,7 @@ class AggregateExecutionSupport {
         if (current !== undefined) {
             options.lifecycle = { archived: current.archived, deleted: current.deleted };
         }
-        return new entityType(options);
+        return RepositoryCreation.create(this.#repository, options);
     }
     /**
      * Creates generated initial state with its canonical identifier field set.
@@ -735,7 +751,7 @@ class AggregateCommandExecution {
         });
     }
     /**
-     * Invokes an assignee in a fenced Entity transaction with output validation.
+     * Invokes an assignee, validates its output, and checks delivery before the Entity transaction commits.
      *
      * @param entity Aggregate instance to mutate.
      * @param handler Assignee declaration to invoke.
@@ -966,11 +982,11 @@ class AggregateEventExecution {
         }
     }
     /**
-     * Applies a fenced Entity commit and raises transition rejection.
+     * Checks delivery immediately before the Entity transaction commits and raises transition rejection.
      *
      * @param entity Aggregate instance to commit.
      * @param producedEvents Whether reactors produced Events.
-     * @returns Completion after a successful fenced commit.
+     * @returns Completion after a successful commit.
      */
     async #commitEntity(entity, producedEvents) {
         const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, producedEvents));
@@ -1662,7 +1678,7 @@ class ProcessManagerCommandExecution {
         }
     }
     /**
-     * Invokes the Command handler in a fenced Entity transaction.
+     * Invokes a Command handler and checks delivery before the Entity transaction commits.
      *
      * @param entity Process Manager instance to mutate.
      * @param assignee Registered Command handler.
@@ -1968,11 +1984,11 @@ class ProcessManagerEventExecution {
         }
     }
     /**
-     * Applies a fenced Entity commit and raises transition rejection.
+     * Checks delivery immediately before the Entity transaction commits and raises transition rejection.
      *
      * @param entity Process Manager instance to commit.
      * @param producedEvents Whether handlers produced Events.
-     * @returns Completion after a successful fenced commit.
+     * @returns Completion after a successful commit.
      */
     async #commitEntity(entity, producedEvents) {
         const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, producedEvents));
@@ -2061,6 +2077,58 @@ class ProcessManagerEventExecution {
  * Internal repository identity operations.
  */
 const RepositoryIdentity = {
+    /**
+     * Validates constructor, family, and state metadata from repository options.
+     *
+     * @typeParam EntityType Concrete Entity constructor being registered.
+     * @param options Repository configuration to validate.
+     * @returns The validated Entity identity and descriptor metadata.
+     */
+    describeOptions(options) {
+        const entityType = RepositoryIdentity.requireEntityType(options);
+        const entityFamily = RepositoryIdentity.requireEntityFamily(entityType);
+        const displayName = RepositoryIdentity.entityTypeName(entityType);
+        const schema = RepositoryIdentity.readRepositorySchemaOption(options, displayName, entityFamily);
+        const metadata = RepositoryIdentity.describeRepositoryEntityMetadata(displayName, entityFamily, schema);
+        if (metadata.kind !== entityFamily) {
+            throw new RepositoryIdentityError("ENTITY_SCHEMA_KIND_MISMATCH", `Repository entity type "${displayName}" does not match the supplied state schema.`);
+        }
+        if (options.stateUpdateRouting !== undefined && entityFamily !== "projection") {
+            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", "State-update routing is supported only by Projection repositories.");
+        }
+        return { entityType, entityFamily, schema, metadata };
+    },
+    /**
+     * Validates and returns a readable Entity class constructor in repository options.
+     *
+     * @param options Repository configuration to inspect.
+     * @returns The supplied Entity constructor.
+     */
+    requireEntityType(options) {
+        if (!RepositoryIdentity.isRepositoryOptionsObject(options)) {
+            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", "Repository options must be a non-null object with an entity type class constructor " +
+                "extending Aggregate, Projection, or ProcessManager.");
+        }
+        const entityType = RepositoryIdentity.readEntityTypeOption(options);
+        if (typeof entityType !== "function" || !RepositoryIdentity.isClassConstructor(entityType)) {
+            throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", `Repository entity type "${RepositoryIdentity.entityTypeName(entityType)}" must be a class constructor ` +
+                "extending Aggregate, Projection, or ProcessManager.");
+        }
+        return entityType;
+    },
+    /**
+     * Validates and returns Aggregate, Projection, or Process Manager inheritance.
+     *
+     * @param entityType Validated class constructor.
+     * @returns Aggregate, Projection, or Process Manager.
+     */
+    requireEntityFamily(entityType) {
+        const family = RepositoryIdentity.resolveRepositoryEntityFamily(entityType);
+        if (family !== undefined)
+            return family;
+        throw new RepositoryIdentityError("UNSUPPORTED_ENTITY_TYPE", `Repository entity type "${RepositoryIdentity.entityTypeName(entityType)}" must extend ` +
+            "Aggregate, Projection, or ProcessManager.");
+    },
     /**
      * Creates a frozen identity snapshot from validated Entity metadata.
      *
@@ -2408,9 +2476,8 @@ const RepositoryEntities = {
      * @returns The Entity instance for one repository dispatch.
      */
     instantiate(repository, entityId, stored, resetDeleted) {
-        const entityType = repository.entityType;
         const fresh = stored === undefined || resetDeleted;
-        return new entityType({
+        return RepositoryCreation.create(repository, {
             id: entityId,
             schema: repository.stateSchema,
             state: fresh