@mxf-dev/core 2.0.5 → 3.0.0

package/src/events/ClientEventBus.ts

@@ -44,6 +44,10 @@ const logger = new Logger('warn', 'ClientEventBus', 'client');
 
 // Create a strict validator for client-side operations
 const validator = createStrictValidator('ClientEventBus');
+type SocketCallback = (event: string, ...args: unknown[]) => void;
+
+/** Bound process-global socket replay protection without a cleanup timer. */
+const MAX_INBOUND_EVENT_KEYS = 4096;
 
 /**
  * Interface for client-specific event bus functionality
@@ -56,6 +60,12 @@ export interface IClientEventBus extends BaseEventBusImplementation {
      */
     setClientSocket(socket: SocketLike): this;
 
+    /**
+     * Release the primary socket only when it is the expected socket. Named
+     * agent transports and listeners owned by other SDK services are retained.
+     */
+    clearClientSocket(socket?: SocketLike): this;
+
     /**
      * Set up socket event forwarding
      * @param socket Socket to use
@@ -90,6 +100,9 @@ export interface IClientEventBus extends BaseEventBusImplementation {
      */
     emitOn<K extends AnyEventName>(socketId: string, event: K, payload: PayloadOf<K>): void;
 
+    /** Whether the exact named socket used by emitOn() is connected. */
+    isRegisteredSocketConnected(socketId: string): boolean;
+
     /**
      * Disconnect the primary socket and unregister all sockets
      * @returns this (for chaining)
@@ -113,13 +126,21 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
     // Primary socket (set by setClientSocket, used by admin/SDK emit())
     private socket: SocketLike | null = null;
     // Listeners tracked for the primary socket's onAny handler
-    private socketListeners: Map<string, (...args: any[]) => void> = new Map();
+    private socketListeners: Map<string, SocketCallback> = new Map();
 
     // Socket registry: maps socketId (typically agentId) → socket instance
     // Agent sockets register here so they don't overwrite the primary admin socket
     private socketRegistry: Map<string, SocketLike> = new Map();
     // Listeners tracked for each registered socket's onAny handler
-    private socketListenersRegistry: Map<string, Map<string, (...args: any[]) => void>> = new Map();
+    private socketListenersRegistry: Map<string, Map<string, SocketCallback>> = new Map();
+
+    /**
+     * Socket.IO broadcasts one envelope to every local agent socket. All of
+     * those sockets feed this process-global bus, so remember exact envelopes
+     * and publish each one only once. Set iteration order supplies bounded FIFO
+     * eviction; raw/custom socket payloads without an eventId remain distinct.
+     */
+    private readonly inboundEventKeys = new Set<string>();
 
 
     /**
@@ -143,6 +164,11 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
             validator.assertHasFunction(socket, 'on');
             validator.assertHasFunction(socket, 'emit');
 
+            // Remove only the EventBus listeners from the previous primary
+            // socket. Other SDK lifecycle listeners and named agent sockets
+            // have independent owners and must survive a primary reconnect.
+            this.removePrimarySocketListeners();
+
             // Store the socket
             this.socket = socket;
 
@@ -157,6 +183,17 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
         return this;
     }
 
+    /** Release only the primary transport and the exact callbacks this bus owns. */
+    public clearClientSocket(socket?: SocketLike): this {
+        if (socket && this.socket !== socket) {
+            return this;
+        }
+
+        this.removePrimarySocketListeners();
+        this.socket = null;
+        return this;
+    }
+
     /**
      * Forward an emitted event to the primary socket.
      *
@@ -187,9 +224,6 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
             validator.assertHasFunction(socket, 'on');
             validator.assertHasFunction(socket, 'onAny');
             
-            // Remove previous listeners if any
-            this.removeAllSocketListeners();
-            
             // Catch every event with onAny (Socket.IO specific)
             if (socket.onAny) {
                 // Build a set of events that are handled specifically by MxfService.setupControlLoopSocketListeners()
@@ -201,7 +235,7 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
                     ...Object.values(OrparEvents)
                 ]);
 
-                const handleAnyEvent = (event: string, ...args: any[]) => {
+                const handleAnyEvent = (event: string, ...args: unknown[]): void => {
                     // Skip processing of some internal socket.io events
                     if (event.startsWith('$') || event === 'ping' || event === 'pong') {
                         return;
@@ -215,11 +249,7 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
 
                     const payload = args.length > 0 ? args[0] : {};
 
-                    // Forward to event bus
-                    this.eventSubject.next({
-                        type: event,
-                        payload
-                    });
+                    this.publishInboundEvent(event, payload);
                 };
 
                 socket.onAny(handleAnyEvent);
@@ -266,7 +296,7 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
                     ...Object.values(OrparEvents)
                 ]);
 
-                const handleAnyEvent = (event: string, ...args: any[]) => {
+                const handleAnyEvent = (event: string, ...args: unknown[]): void => {
                     // Skip internal socket.io events
                     if (event.startsWith('$') || event === 'ping' || event === 'pong') {
                         return;
@@ -276,7 +306,7 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
                         return;
                     }
                     const payload = args.length > 0 ? args[0] : {};
-                    this.eventSubject.next({ type: event, payload });
+                    this.publishInboundEvent(event, payload);
                 };
 
                 socket.onAny(handleAnyEvent);
@@ -310,14 +340,13 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
         }
 
         try {
-            // Remove onAny listener
-            if (socket.offAny) {
-                socket.offAny();
-            }
-
             // Remove individually tracked listeners
             const listeners = this.socketListenersRegistry.get(socketId);
             if (listeners) {
+                const anyListener = listeners.get('any');
+                if (socket.offAny && anyListener) {
+                    socket.offAny(anyListener);
+                }
                 for (const [event, listener] of listeners.entries()) {
                     if (event !== 'any') {
                         socket.off(event, listener);
@@ -384,6 +413,8 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
      * @returns this (for chaining)
      */
     public disconnect(): this {
+        this.inboundEventKeys.clear();
+
         // Unregister all sockets in the registry
         for (const socketId of Array.from(this.socketRegistry.keys())) {
             this.unregisterSocket(socketId);
@@ -414,42 +445,17 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
      * @returns this (for chaining)
      */
     public removeAllSocketListeners(): this {
-        // Clean up primary socket listeners
-        if (this.socket) {
-            try {
-                // Remove "any" listener if registered
-                if (this.socket.offAny && this.socketListeners.has('any')) {
-                    this.socket.offAny();
-                    this.socketListeners.delete('any');
-                }
-
-                // Remove individual event listeners
-                for (const [event, listener] of this.socketListeners.entries()) {
-                    if (event !== 'any') {
-                        this.socket.off(event, listener);
-                    }
-                }
-
-                // Clear listener map
-                this.socketListeners.clear();
-
-                // Use Socket.IO's removeAllListeners if available
-                if (this.socket.removeAllListeners) {
-                    this.socket.removeAllListeners();
-                }
-            } catch (error) {
-                logger.error('[ClientEventBus] Error removing primary socket listeners:', error instanceof Error ? error.message : String(error));
-            }
-        }
+        this.removePrimarySocketListeners();
 
         // Clean up registered sockets' listeners
         for (const [socketId, socket] of this.socketRegistry.entries()) {
             try {
-                if (socket.offAny) {
-                    socket.offAny();
-                }
                 const listeners = this.socketListenersRegistry.get(socketId);
                 if (listeners) {
+                    const anyListener = listeners.get('any');
+                    if (socket.offAny && anyListener) {
+                        socket.offAny(anyListener);
+                    }
                     for (const [event, listener] of listeners.entries()) {
                         if (event !== 'any') {
                             socket.off(event, listener);
@@ -465,6 +471,34 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
 
         return this;
     }
+
+    /** Remove only listeners installed by this bus on the primary socket. */
+    private removePrimarySocketListeners(): void {
+        if (!this.socket) {
+            this.socketListeners.clear();
+            return;
+        }
+
+        try {
+            const anyListener = this.socketListeners.get('any');
+            if (this.socket.offAny && anyListener) {
+                this.socket.offAny(anyListener);
+            }
+
+            for (const [event, listener] of this.socketListeners.entries()) {
+                if (event !== 'any') {
+                    this.socket.off(event, listener);
+                }
+            }
+
+            this.socketListeners.clear();
+        } catch (error) {
+            logger.error(
+                '[ClientEventBus] Error removing primary socket listeners:',
+                error instanceof Error ? error.message : String(error)
+            );
+        }
+    }
     
     /**
      * Remove all agent event listeners
@@ -482,5 +516,40 @@ export class ClientEventBus extends BaseEventBusImplementation implements IClien
     public isSocketConnected(): boolean {
         return !!this.socket && !!this.socket.connected;
     }
+
+    /**
+     * Check the exact named agent socket used by emitOn().
+     *
+     * Request/response services must not rely on emitOn()'s primary-socket
+     * fallback: when no transport is available that fallback only logs, which
+     * would leave an acknowledged request pending forever.
+     */
+    public isRegisteredSocketConnected(socketId: string): boolean {
+        validator.assertIsNonEmptyString(socketId);
+        return this.socketRegistry.get(socketId)?.connected === true;
+    }
+
+    /** Publish one exact typed socket envelope into the shared local bus. */
+    private publishInboundEvent(event: string, payload: unknown): void {
+        if (payload && typeof payload === 'object') {
+            const eventId = (payload as { eventId?: unknown }).eventId;
+            if (typeof eventId === 'string' && eventId.trim().length > 0) {
+                const eventKey = `${event}:${eventId}`;
+                if (this.inboundEventKeys.has(eventKey)) {
+                    return;
+                }
+
+                this.inboundEventKeys.add(eventKey);
+                if (this.inboundEventKeys.size > MAX_INBOUND_EVENT_KEYS) {
+                    const oldestKey = this.inboundEventKeys.values().next().value;
+                    if (typeof oldestKey === 'string') {
+                        this.inboundEventKeys.delete(oldestKey);
+                    }
+                }
+            }
+        }
+
+        this.eventSubject.next({ type: event, payload });
+    }
     
 }

package/src/events/EventBus.ts

@@ -30,7 +30,7 @@
  * - All events are processed through RxJS for local subscriptions
  */
 
-import { Subject } from 'rxjs';
+import { Subject, Subscription } from 'rxjs';
 import { EventMessage } from './EventBusBase.js';
 import { ClientEventBus, IClientEventBus } from './ClientEventBus.js';
 import { ServerEventBus, IServerEventBus } from './ServerEventBus.js';
@@ -85,6 +85,15 @@ export class EventBusImplementation {
      * This is primarily used for testing.
      */
     public reset(): void {
+        // A Subject completion disposes RxJS subscriptions, but it cannot
+        // detach Socket.IO callbacks registered outside RxJS. Release the
+        // exact transport listeners owned by the old buses before dropping
+        // their instances so a test reset/reinitialize cannot retain a dead
+        // bus through socket.onAny().
+        this.clientEventBus?.removeAllSocketListeners();
+        this.clientEventBus?.removeAllListeners();
+        this.serverEventBus?.cleanup();
+
         // Completing the Subject disposes every subscription both buses hold,
         // and their completion callbacks clear their registries.
         this.eventSubject.complete();
@@ -95,11 +104,32 @@ export class EventBusImplementation {
         this.serverEventBus = null;
     }
 
+    /**
+     * Drain async callbacks owned by either bus without instantiating a bus that
+     * was never used. Repeat across both buses because a settling server handler
+     * may synchronously publish work to the client bus (or vice versa).
+     */
+    public async drain(): Promise<void> {
+        for (;;) {
+            const buses = [this.serverEventBus, this.clientEventBus].filter(
+                (bus): bus is IServerEventBus | IClientEventBus => bus !== null
+            );
+            await Promise.all(buses.map(bus => bus.drain()));
+
+            const currentBuses = [this.serverEventBus, this.clientEventBus].filter(
+                (bus): bus is IServerEventBus | IClientEventBus => bus !== null
+            );
+            if (currentBuses.every(bus => bus.pendingHandlerCount() === 0)) {
+                return;
+            }
+        }
+    }
+
     /**
      * Log every event passing through the bus.
      * @returns A subscription that can be unsubscribed to stop debugging
      */
-    public debug() {
+    public debug(): Subscription {
         return this.eventSubject.subscribe(event => {
             logger.debug(`event '${event.type}': ${JSON.stringify(event.payload)}`);
         });

package/src/events/EventBusBase.ts

@@ -41,20 +41,25 @@ import { Logger } from '../utils/Logger.js';
  * rejection can kill the bus subscription or vanish silently. Errors are
  * logged loudly with the event name; the bus stays alive for other handlers.
  */
-export const invokeHandlerSafely = (
+export const invokeHandlerSafely = <T>(
     busLogger: Logger,
     eventName: unknown,
-    handler: (payload: any) => unknown,
-    payload: any
+    handler: (payload: T) => unknown,
+    payload: T,
+    trackAsyncWork?: (work: Promise<void>) => void
 ): void => {
     try {
         const result = handler(payload);
         if (result && typeof (result as Promise<unknown>).then === 'function') {
-            (result as Promise<unknown>).catch((error: unknown) => {
-                busLogger.error(
-                    `Async handler for '${String(eventName)}' rejected: ${error instanceof Error ? error.stack : String(error)}`
-                );
-            });
+            const work = Promise.resolve(result).then(
+                () => undefined,
+                (error: unknown): void => {
+                    busLogger.error(
+                        `Async handler for '${String(eventName)}' rejected: ${error instanceof Error ? error.stack : String(error)}`
+                    );
+                }
+            );
+            trackAsyncWork?.(work);
         }
     } catch (error) {
         busLogger.error(
@@ -76,7 +81,7 @@ export interface SocketLike {
     off: (event: string, listener?: (...args: any[]) => void) => any;
     emit: (event: string, ...args: any[]) => any;
     onAny?: (listener: (event: string, ...args: any[]) => void) => any;
-    offAny?: () => any;
+    offAny?: (listener?: (event: string, ...args: unknown[]) => void) => unknown;
     removeAllListeners?: () => any;
     disconnect?: () => void;
     data?: {
@@ -161,7 +166,13 @@ export interface EventBusBase {
      * @param event Event name
      * @param payload Event payload
      */
-    emit?(event: AnyEventName, payload: any): void;
+    emit?<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void;
+
+    /**
+     * Publish an event to local subscribers without forwarding it to the
+     * transport. Used when a socket event has already crossed the transport.
+     */
+    emitLocal<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void;
 
     /**
      * Check if an event has subscribers
@@ -190,6 +201,12 @@ export interface EventBusBase {
      * @returns this (for chaining)
      */
     removeAllListeners(event?: AnyEventName): this;
+
+    /** Wait for every async handler already accepted by this bus to settle. */
+    drain(): Promise<void>;
+
+    /** Number of accepted async handlers that have not settled yet. */
+    pendingHandlerCount(): number;
 }
 
 /**
@@ -232,7 +249,7 @@ export function isReservedEvent(event: string): boolean {
  * the wrapper (as an earlier version did) meant off() could never find the entry,
  * so the RxJS subscription was never disposed and the "one-shot" listener kept
  * firing on every later event. take(1) now disposes the subscription itself and
- * the completion callback clears the registry entry.
+ * the subscription teardown clears the registry entry.
  *
  * ## Emit contract
  *
@@ -258,7 +275,7 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
      * A handler may be registered more than once for the same event, so the
      * value is a list; off() disposes all of them.
      */
-    protected handlerSubscriptions: Map<string, Map<EventHandler<any>, Subscription[]>> = new Map();
+    protected handlerSubscriptions: Map<string, Map<EventHandler<never>, Subscription[]>> = new Map();
 
     /** event → number of live per-event subscribers. */
     protected subscriptionCountMap: Map<string, number> = new Map();
@@ -266,6 +283,9 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
     /** onAll() subscriptions, which are not tied to any single event name. */
     protected allEventSubscriptions: Set<Subscription> = new Set();
 
+    /** Async handler work accepted by this bus and still using server resources. */
+    private readonly pendingHandlerWork = new Set<Promise<void>>();
+
     private debugMode: boolean = false;
     private debugSubscription: Subscription | null = null;
 
@@ -319,6 +339,37 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
         }
     }
 
+    /**
+     * Deliver an event to this bus's local subscribers only.
+     *
+     * Socket ingress must use this path when adapting a received event for SDK
+     * subscribers. Calling emit()/emitOn() there sends the same event back over
+     * the socket and creates a transport echo loop for bidirectional names.
+     */
+    public emitLocal<K extends AnyEventName>(event: K, payload: PayloadOf<K>): void {
+        try {
+            validateEventName(event);
+
+            if (payload === undefined || payload === null) {
+                throw new Error(
+                    `Event '${String(event)}' was emitted locally with a ` +
+                    `${payload === null ? 'null' : 'undefined'} payload. ` +
+                    'Build the payload with a helper from EventPayloadSchema.'
+                );
+            }
+
+            this.validateEventPayload(String(event), payload);
+            this.eventSubject.next({ type: event, payload });
+        } catch (error) {
+            this.busLogger.error(
+                `Error emitting local event '${String(event)}': ` +
+                `${error instanceof Error ? error.message : String(error)}`
+            );
+            this.reportEmitFailure(event, error);
+            throw error;
+        }
+    }
+
     /**
      * Publish a properly-formed error event describing a failed emit.
      *
@@ -375,11 +426,17 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
             .subscribe({
                 // Isolate throws/rejections so one bad handler cannot kill the
                 // subscription or fail silently.
-                next: (payload) => invokeHandlerSafely(this.busLogger, event, handler, payload),
-                complete: () => this.forgetSubscription(event, handler, subscription)
+                next: (payload) => invokeHandlerSafely(
+                    this.busLogger,
+                    event,
+                    handler,
+                    payload,
+                    this.trackAsyncHandlerWork
+                )
             });
 
         this.registerHandler(event, handler, subscription);
+        subscription.add(() => this.forgetSubscription(event, handler, subscription));
 
         return subscription;
     }
@@ -388,7 +445,7 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
      * Subscribe to an event for exactly one delivery.
      *
      * take(1) disposes the RxJS subscription after the first event, and the
-     * completion callback removes it from the registry, so nothing is left
+     * subscription teardown removes it from the registry, so nothing is left
      * behind. off(event, handler) still works before the event arrives.
      *
      * @param event Event name
@@ -398,13 +455,6 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
     public once<K extends AnyEventName>(event: K, handler: EventHandler<PayloadOf<K>>): Subscription {
         validateEventName(event);
 
-        // The completion callback needs the Subscription, which only exists once
-        // subscribe() returns. With a plain Subject the source cannot emit during
-        // subscribe(), but this flag keeps the bookkeeping correct even if the
-        // Subject were ever swapped for a replaying one.
-        let registered = false;
-        let completedBeforeRegistration = false;
-
         const subscription: Subscription = this.eventSubject
             .pipe(
                 filter((e: EventMessage) => e.type === event),
@@ -412,22 +462,17 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
                 map((e: EventMessage) => e.payload)
             )
             .subscribe({
-                next: (payload) => invokeHandlerSafely(this.busLogger, event, handler, payload),
-                complete: () => {
-                    if (registered) {
-                        this.forgetSubscription(event, handler, subscription);
-                    } else {
-                        completedBeforeRegistration = true;
-                    }
-                }
+                next: (payload) => invokeHandlerSafely(
+                    this.busLogger,
+                    event,
+                    handler,
+                    payload,
+                    this.trackAsyncHandlerWork
+                )
             });
 
         this.registerHandler(event, handler, subscription);
-        registered = true;
-
-        if (completedBeforeRegistration) {
-            this.forgetSubscription(event, handler, subscription);
-        }
+        subscription.add(() => this.forgetSubscription(event, handler, subscription));
 
         return subscription;
     }
@@ -441,11 +486,18 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
     public onAll(listener: (eventType: string, payload: any) => void): Subscription {
         const subscription = this.eventSubject.subscribe({
             next: (e: EventMessage) =>
-                invokeHandlerSafely(this.busLogger, e.type, (payload) => listener(e.type, payload), e.payload)
+                invokeHandlerSafely(
+                    this.busLogger,
+                    e.type,
+                    (payload) => listener(e.type, payload),
+                    e.payload,
+                    this.trackAsyncHandlerWork
+                )
         });
 
         this.subscriptions.push(subscription);
         this.allEventSubscriptions.add(subscription);
+        subscription.add(() => this.forgetSubscriptionEverywhere(subscription));
 
         return subscription;
     }
@@ -472,6 +524,7 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
         } else {
             this.categorySubscriptions.set(category, [subscription]);
         }
+        subscription.add(() => this.forgetCategorySubscription(category, subscription));
 
         return subscription;
     }
@@ -528,7 +581,7 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
             return this;
         }
 
-        for (const subscription of categorySubs) {
+        for (const subscription of [...categorySubs]) {
             subscription.unsubscribe();
             this.forgetSubscriptionEverywhere(subscription);
         }
@@ -614,6 +667,22 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
         return this.allEventSubscriptions.size;
     }
 
+    /** Number of async callbacks which have not yet settled. */
+    public pendingHandlerCount(): number {
+        return this.pendingHandlerWork.size;
+    }
+
+    /**
+     * Wait for all accepted async callbacks, including callbacks accepted by a
+     * callback while the current batch is settling. Ingress must be stopped
+     * before calling this during process shutdown so the set eventually closes.
+     */
+    public async drain(): Promise<void> {
+        while (this.pendingHandlerWork.size > 0) {
+            await Promise.all([...this.pendingHandlerWork]);
+        }
+    }
+
     /**
      * Log every event passing through this bus at debug level.
      *
@@ -648,10 +717,18 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
     // Internal bookkeeping
     // ---------------------------------------------------------------------
 
+    /** Keep shutdown ownership of an async handler until it has settled. */
+    private readonly trackAsyncHandlerWork = (work: Promise<void>): void => {
+        this.pendingHandlerWork.add(work);
+        void work.then((): void => {
+            this.pendingHandlerWork.delete(work);
+        });
+    };
+
     /** Record a new per-event subscription across all three structures. */
     private registerHandler(
         event: AnyEventName,
-        handler: EventHandler<any>,
+        handler: EventHandler<never>,
         subscription: Subscription
     ): void {
         this.subscriptions.push(subscription);
@@ -679,7 +756,7 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
      */
     private forgetSubscription(
         event: AnyEventName,
-        handler: EventHandler<any>,
+        handler: EventHandler<never>,
         subscription: Subscription
     ): void {
         const eventHandlers = this.handlerSubscriptions.get(event);
@@ -728,6 +805,22 @@ export abstract class BaseEventBusImplementation implements EventBusBase {
         }
     }
 
+    /** Drop a subscription from one category without affecting other registrations. */
+    private forgetCategorySubscription(category: string, subscription: Subscription): void {
+        const categorySubs = this.categorySubscriptions.get(category);
+        if (!categorySubs) {
+            return;
+        }
+
+        const index = categorySubs.indexOf(subscription);
+        if (index !== -1) {
+            categorySubs.splice(index, 1);
+        }
+        if (categorySubs.length === 0) {
+            this.categorySubscriptions.delete(category);
+        }
+    }
+
     // ---------------------------------------------------------------------
     // Validation
     // ---------------------------------------------------------------------