@spine-event-engine/server 2.0.0-snapshot.23 → 2.0.0-snapshot.25

package/dist/bus/event-bus.d.ts

@@ -1,164 +1,143 @@
 import { type MessageSchema } from "@spine-event-engine/core";
 import { type Event } from "@spine-event-engine/proto";
 import type { EventStore } from "@spine-event-engine/storage";
-import { type AgentSavedDispatchPlan } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
 import type { ILogLayer } from "loglayer";
+import type { ServerEnvironment } from "../server/server-environment.js";
 import type { EventDispatcher } from "./event-dispatcher.js";
 /**
- * Checks for framework System events, including Agent interaction events.
+ * Checks whether a schema defines a framework System Event, including Agent interactions.
  *
- * @param schema Event message descriptor to classify.
- * @returns Whether the schema is reserved for System events.
+ * @param schema Event payload schema.
+ * @returns Whether the Event belongs to the System bus.
  */
 export declare const isSystemEventSchema: (schema: MessageSchema) => boolean;
 interface EventBusAccess {
     /**
-     * Creates a bus without event storage.
+     * Binds this context bus's private runtime to its captured environment.
+     * @param eventBus Framework context bus.
+     * @param environment Exact environment containing the context.
+     */
+    bindEnvironment(eventBus: EventBus, environment: ServerEnvironment): void;
+    /**
+     * Sets receiving-context admission before Event storage or dispatch.
      *
-     * @param dispatchers Initial dispatchers to register.
-     * @returns The event bus without an event store.
+     * @param eventBus Context Event bus.
+     * @param onAdmit Checks current tenant membership.
      */
-    createForgettingBus(dispatchers?: Iterable<EventDispatcher>): EventBus;
+    setAdmission(eventBus: EventBus, onAdmit: (event: Event) => Promise<void>): void;
     /**
-     * Creates a System-event bus with optional storage.
+     * Creates a package-internal bus without an event store.
      *
-     * @param eventStore Optional event store for the System bus.
-     * @param dispatchers Initial dispatchers to register.
-     * @returns The System-event bus.
+     * @param dispatchers the initial dispatchers to register.
+     * @returns the assembled forgetting bus.
+     */
+    createForgettingBus(dispatchers?: Iterable<EventDispatcher>): EventBus;
+    /**
+     * Creates a System Event bus with optional persistent storage.
+     * @param eventStore Optional System Event store.
+     * @param dispatchers Initial recipients.
+     * @returns Configured System Event bus.
      */
     createSystemBus(eventStore: EventStore | undefined, dispatchers?: Iterable<EventDispatcher>): EventBus;
     /**
-     * Stores and dispatches an accepted event.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param event Event envelope to prepare or dispatch.
-     * @returns A promise for event storage and dispatch.
+     * Dispatches one already-stored Event without another append.
+     * @param eventBus Target bus.
+     * @param event Captured Event envelope.
+     * @returns Completion after recipient dispatch.
      */
     postStored(eventBus: EventBus, event: Event): Promise<void>;
     /**
-     * Stores and dispatches an event during follow-up work.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param event Event envelope to prepare or dispatch.
-     * @returns A promise for follow-up event storage and dispatch.
+     * Queues an already-stored Event as a trusted follow-up.
+     * @param eventBus Target bus.
+     * @param event Captured Event envelope.
+     * @returns Completion after recipient dispatch.
      */
     postStoredFollowUp(eventBus: EventBus, event: Event): Promise<void>;
     /**
-     * Posts an internal event during follow-up work.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param event Event envelope to prepare or dispatch.
-     * @returns A promise for follow-up event dispatch.
+     * Queues a produced Event after active bus work.
+     * @param eventBus Target bus.
+     * @param event Produced Event envelope.
+     * @returns Completion after recipient dispatch.
      */
     postFollowUp(eventBus: EventBus, event: Event): Promise<void>;
     /**
-     * Prepares a dispatch plan before persisting accepted output.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param event Event envelope to prepare or dispatch.
-     * @returns The exact saved recipient plan.
-     */
-    prepareSaved(eventBus: EventBus, event: Event): Promise<AgentSavedDispatchPlan>;
-    /**
-     * Posts a prepared dispatch after its Agent result is saved.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param event Event envelope to prepare or dispatch.
-     * @param plan Persisted recipient plan for this dispatch.
-     * @returns A promise for completion of the saved dispatch.
-     */
-    postSavedFollowUp(eventBus: EventBus, event: Event, plan: AgentSavedDispatchPlan): Promise<void>;
-    /**
-     * Executes work in the bus-wide exclusive sequence.
-     *
-     * @typeParam Result Result type returned by the serialized work.
-     * @param eventBus Event bus receiving this internal operation.
-     * @param work Work to serialize with other bus operations.
-     * @returns The result returned by the serialized work.
+     * Executes a callback in the Event queue.
+     * @typeParam Result Callback result.
+     * @param eventBus Target bus.
+     * @param work Serialized callback.
+     * @returns The callback result.
      */
     runExclusive<Result>(eventBus: EventBus, work: () => Result | Promise<Result>): Promise<Result>;
     /**
-     * Subscribes a callback to one event type.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param typeUrl Fully qualified event message type URL.
-     * @param subscriber Callback to invoke for matching events.
-     * @returns A handle for removing the subscription.
+     * Registers an in-process Event subscriber.
+     * @param eventBus Target bus.
+     * @param typeUrl Event payload type URL.
+     * @param subscriber Recipient to notify.
+     * @returns Subscription cancellation handle.
      */
     subscribe(eventBus: EventBus, typeUrl: string, subscriber: EventSubscriber): EventSubscription;
     /**
-     * Lists schemas registered for dispatch.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @returns The registered event message schemas.
+     * Lists registered Event payload schemas.
+     * @param eventBus Target bus.
+     * @returns Current schema list.
      */
     eventSchemas(eventBus: EventBus): readonly MessageSchema[];
     /**
-     * Registers event schemas for dispatch.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param schemas Event message schemas to register.
+     * Registers Event schemas for produced signals.
+     * @param eventBus Target bus.
+     * @param schemas Schemas to register.
      */
     registerSchemas(eventBus: EventBus, schemas: Iterable<MessageSchema>): void;
     /**
-     * Removes a dispatcher from the bus.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param dispatcher Dispatcher to register or inspect.
+     * Removes a dispatcher from this bus.
+     * @param eventBus Target bus.
+     * @param dispatcher Dispatcher to remove.
      */
     unregister(eventBus: EventBus, dispatcher: EventDispatcher): void;
     /**
-     * Finds a registered event schema by type URL.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param typeUrl Fully qualified event message type URL.
-     * @returns The matching schema, if registered.
+     * Finds a registered Event schema.
+     * @param eventBus Target bus.
+     * @param typeUrl Event payload type URL.
+     * @returns Matching schema when registered.
      */
     schema(eventBus: EventBus, typeUrl: string): MessageSchema | undefined;
     /**
-     * Stops accepting new external work.
-     *
-     * @param eventBus Event bus receiving this internal operation.
+     * Stops external Event intake before graceful drain.
+     * @param eventBus Target bus.
      */
     beginClose(eventBus: EventBus): void;
     /**
-     * Waits for accepted dispatches to settle.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @returns A promise that settles when accepted work drains.
+     * Waits for accepted Event work.
+     * @param eventBus Target bus.
+     * @returns Completion after the queue drains.
      */
     drain(eventBus: EventBus): Promise<void>;
     /**
-     * Completes the bus shutdown.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @returns A promise that settles when shutdown completes.
+     * Completes graceful Event-bus closure.
+     * @param eventBus Target bus.
+     * @returns Completion after closure.
      */
     finishClose(eventBus: EventBus): Promise<void>;
     /**
-     * Restores intake after an aborted shutdown.
-     *
-     * @param eventBus Event bus receiving this internal operation.
+     * Closes a partially assembled bus.
+     * @param eventBus Target bus.
      */
     abortClose(eventBus: EventBus): void;
     /**
-     * Returns the number of accepted dispatches still in progress.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @returns The number of accepted dispatches still in progress.
+     * Returns admitted Event work count for drain stability.
+     * @param eventBus Target bus.
+     * @returns Number of accepted work items.
      */
     acceptedWorkCount(eventBus: EventBus): number;
     /**
-     * Attaches the server logger to this bus.
-     *
-     * @param eventBus Event bus receiving this internal operation.
-     * @param logger Logger used for bus diagnostics.
+     * Sets the internal diagnostic sink.
+     * @param eventBus Target bus.
+     * @param logger Safe structured logger.
      */
     installLogger(eventBus: EventBus, logger: ILogLayer): void;
     /**
-     * Removes the server logger from this bus.
-     *
-     * @param eventBus Event bus receiving this internal operation.
+     * Clears the internal diagnostic sink.
+     * @param eventBus Target bus.
      */
     clearLogger(eventBus: EventBus): void;
 }
@@ -167,7 +146,7 @@ interface EventBusAccess {
  *
  * Public construction creates a domain-only bus that stores domain events and
  * rejects System schemas, dispatchers, and events. Internally assembled
- * forgetting and System buses own no `EventStore` unless explicitly given one.
+ * forgetting and System buses have no `EventStore` unless explicitly given one.
  * Events with no matching dispatcher resolve without dispatch. Events with no
  * registered schema reject deterministically before storage or dispatch.
  */
@@ -185,7 +164,7 @@ export declare class EventBus {
     /**
      * Registers an event dispatcher.
      *
-     * @typeParam Dispatcher Concrete Event dispatcher type returned to the caller.
+     * @typeParam Dispatcher Concrete recipient being registered.
      * @param dispatcher the dispatcher to register.
      * @returns the registered dispatcher.
      */
@@ -198,14 +177,13 @@ export declare class EventBus {
      */
     post(event: Event): Promise<void>;
     /**
-     * Stops accepting new event work, drains accepted work, and closes an owned event store.
+     * Stops accepting new event work, drains accepted work, and closes its event store.
      *
      * Close is idempotent and returns the same close outcome on repeated calls.
-     * Runtime and event-store close hooks are both attempted; failures reject as
-     * an `AggregateError`.
+     * Runtime and event-store close hooks are both awaited; failures reject as
+     * an `AggregateError` after both cleanup attempts.
      *
      * @returns A promise that settles after the event bus closes.
-     *
      */
     close(): Promise<void>;
 }

package/dist/bus/event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/bus/event-bus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/bus/event-bus.ts"],"names":[],"mappings":"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"}