@open-core/framework 0.2.9 → 0.3.1

package/dist/runtime/server/contracts/security/principal-provider.contract.js

@@ -5,13 +5,13 @@ exports.PrincipalProviderContract = void 0;
  * **Authorization**
  *
  * This abstract class defines how the Security Layer retrieves user permissions.
- * The Framework does not know about your database (SQL, Mongo, JSON or API); it relies on
+ * The Framework does not know about your persistence layer (SQL, Mongo, JSON or API); it relies on
  * your implementation of this provider to resolve a `Principal`.
  *
  * @example
  * ```ts
  * // In your game resource:
- * class MyAuthProvider implements PrincipalProviderContract { ... }
+ * class MyPrincipal implements PrincipalProviderContract { ... }
  * ```
  */
 class PrincipalProviderContract {

package/dist/runtime/server/contracts/security/security-handler.contract.d.ts

@@ -1,5 +1,5 @@
-import { Server } from '../../../..';
-import { SecurityError } from '../../../../kernel/utils/error/security.error';
+import { SecurityError } from '../../../../kernel/error/security.error';
+import { Server } from '../../';
 export declare abstract class SecurityHandlerContract {
     abstract handleViolation(player: Server.Player, error: SecurityError): Promise<void>;
 }

package/dist/runtime/server/controllers/chat.controller.d.ts

@@ -1,4 +1,4 @@
-import { RGB } from '../../../kernel/utils';
+import { RGB } from '../../../kernel/utils/rgb';
 import { ChatService } from '../services/chat.service';
 import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
 export declare class ChatController {

package/dist/runtime/server/controllers/chat.controller.js

@@ -8,8 +8,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatController = void 0;
+const tsyringe_1 = require("tsyringe");
 const controller_1 = require("../decorators/controller");
 const export_1 = require("../decorators/export");
 const chat_service_1 = require("../services/chat.service");
@@ -57,6 +61,7 @@ __decorate([
 ], ChatController.prototype, "coreSendToGroupOfPlayers", null);
 exports.ChatController = ChatController = __decorate([
     (0, controller_1.Controller)(),
+    __param(1, (0, tsyringe_1.inject)(player_directory_port_1.PlayerDirectoryPort)),
     __metadata("design:paramtypes", [chat_service_1.ChatService,
         player_directory_port_1.PlayerDirectoryPort])
 ], ChatController);

package/dist/runtime/server/controllers/command-export.controller.d.ts

@@ -1,10 +1,11 @@
 import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
 import { Player } from '../entities';
 import { CommandExecutionPort, type CommandInfo } from '../services/ports/command-execution.port';
 import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
 import { PrincipalPort } from '../services/ports/principal.port';
 import { RateLimiterService } from '../services/rate-limiter.service';
-import { CommandRegistrationDto, CoreCommandsExports } from '../types/core-exports';
+import { CommandRegistrationDto, InternalCommandsExports } from '../types/core-exports';
 /**
  * Export controller for command system (CORE mode only).
  *
@@ -13,14 +14,22 @@ import { CommandRegistrationDto, CoreCommandsExports } from '../types/core-expor
  * Maintains a registry of both local and remote commands, delegating
  * remote command execution back to the owning resource via net events.
  */
-export declare class CommandExportController implements CoreCommandsExports {
+export declare class CommandExportController implements InternalCommandsExports {
     private commandService;
     private playerDirectory;
     private principalPort;
     private rateLimiter;
+    private readonly commandErrorObserver;
     private engineEvents;
     private remoteCommands;
-    constructor(commandService: CommandExecutionPort, playerDirectory: PlayerDirectoryPort, principalPort: PrincipalPort, rateLimiter: RateLimiterService, engineEvents: IEngineEvents);
+    constructor(commandService: CommandExecutionPort, playerDirectory: PlayerDirectoryPort, principalPort: PrincipalPort, rateLimiter: RateLimiterService, commandErrorObserver: CommandErrorObserverContract, engineEvents: IEngineEvents);
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break the command pipeline.
+     */
+    private safeObserve;
     /**
      * Receives command execution requests from clients.
      *

package/dist/runtime/server/controllers/command-export.controller.js

@@ -15,12 +15,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandExportController = void 0;
 const tsyringe_1 = require("tsyringe");
 const IEngineEvents_1 = require("../../../adapters/contracts/IEngineEvents");
-const logger_1 = require("../../../kernel/shared/logger");
-const utils_1 = require("../../../kernel/utils");
-const security_error_1 = require("../../../kernel/utils/error/security.error");
+const error_1 = require("../../../kernel/error");
+const logger_1 = require("../../../kernel/logger");
+const command_error_observer_contract_1 = require("../contracts/security/command-error-observer.contract");
 const decorators_1 = require("../decorators");
 const onNet_1 = require("../decorators/onNet");
 const entities_1 = require("../entities");
+const normalize_app_error_1 = require("../helpers/normalize-app-error");
+const runtime_1 = require("../runtime");
 const command_execution_port_1 = require("../services/ports/command-execution.port");
 const player_directory_port_1 = require("../services/ports/player-directory.port");
 const principal_port_1 = require("../services/ports/principal.port");
@@ -34,14 +36,29 @@ const rate_limiter_service_1 = require("../services/rate-limiter.service");
  * remote command execution back to the owning resource via net events.
  */
 let CommandExportController = class CommandExportController {
-    constructor(commandService, playerDirectory, principalPort, rateLimiter, engineEvents) {
+    constructor(commandService, playerDirectory, principalPort, rateLimiter, commandErrorObserver, engineEvents) {
         this.commandService = commandService;
         this.playerDirectory = playerDirectory;
         this.principalPort = principalPort;
         this.rateLimiter = rateLimiter;
+        this.commandErrorObserver = commandErrorObserver;
         this.engineEvents = engineEvents;
         this.remoteCommands = new Map();
     }
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break the command pipeline.
+     */
+    async safeObserve(ctx) {
+        try {
+            await this.commandErrorObserver.onError(ctx);
+        }
+        catch (e) {
+            logger_1.loggers.command.fatal(`Command error observer failed`, ctx, e);
+        }
+    }
     // ═══════════════════════════════════════════════════════════════
     // Network Event Handler (receives commands from clients)
     // ═══════════════════════════════════════════════════════════════
@@ -73,22 +90,60 @@ let CommandExportController = class CommandExportController {
             await this.executeCommand(player.clientID, command, args);
         }
         catch (error) {
-            if (error instanceof utils_1.AppError) {
-                if (error.code === 'GAME:BAD_REQUEST' || error.code === 'COMMAND:NOT_FOUND') {
-                    player.send(error.message, 'error');
-                }
-                else {
-                    player.send('An error occurred while executing the command', 'error');
+            const runtime = (0, runtime_1.getRuntimeContext)();
+            const remoteEntry = this.remoteCommands.get(command.toLowerCase());
+            const localMeta = this.commandService.getCommandMeta(command);
+            const appError = (0, normalize_app_error_1.normalizeToAppError)(error, 'server');
+            // If we have an error and it's not a remote command, try to find local meta
+            // to populate the error context properly for the observer.
+            const commandInfo = localMeta
+                ? {
+                    command: localMeta.command,
+                    description: localMeta.description,
+                    usage: localMeta.usage,
+                    isPublic: localMeta.isPublic,
+                    methodName: localMeta.methodName,
+                    expectsPlayer: localMeta.expectsPlayer,
+                    paramNames: localMeta.paramNames,
                 }
-                logger_1.loggers.command.error(`Execution failed: /${command}`, { playerId: player.clientID }, error);
-            }
-            else if (error instanceof security_error_1.SecurityError) {
-                player.send(error.message, 'error');
-                logger_1.loggers.command.warn(`Security error: /${command}`, {
-                    playerId: player.clientID,
-                    error: error.message,
-                });
-            }
+                : remoteEntry
+                    ? {
+                        command: remoteEntry.metadata.command,
+                        description: remoteEntry.metadata.description,
+                        usage: remoteEntry.metadata.usage,
+                        isPublic: remoteEntry.metadata.isPublic,
+                    }
+                    : undefined;
+            const stage = error instanceof error_1.SecurityError
+                ? 'security'
+                : appError.code === 'AUTH:UNAUTHORIZED'
+                    ? 'auth'
+                    : appError.code === 'GAME:BAD_REQUEST' || appError.code.startsWith('SCHEMA:')
+                        ? 'validation'
+                        : appError.code === 'COMMAND:NOT_FOUND'
+                            ? 'dispatch'
+                            : 'unknown';
+            await this.safeObserve({
+                mode: runtime.mode,
+                scope: runtime.mode === 'CORE'
+                    ? 'core'
+                    : runtime.mode === 'RESOURCE'
+                        ? 'resource'
+                        : 'standalone',
+                stage,
+                error: appError,
+                commandName: command,
+                args,
+                player: {
+                    clientId: player.clientID,
+                    accountId: player.accountID || player.clientID.toString(),
+                    name: player.name,
+                },
+                playerRef: player,
+                ownerResourceName: remoteEntry === null || remoteEntry === void 0 ? void 0 : remoteEntry.resourceName,
+                command: commandInfo,
+                commandMeta: localMeta,
+            });
         }
     }
     // ═══════════════════════════════════════════════════════════════
@@ -104,12 +159,22 @@ let CommandExportController = class CommandExportController {
      * Exported as: `exports[coreResourceName].registerCommand`
      */
     registerCommand(metadata) {
-        var _a;
         const commandKey = metadata.command.toLowerCase();
-        if (this.remoteCommands.has(commandKey)) {
+        const existing = this.remoteCommands.get(commandKey);
+        if (existing) {
+            // Allow re-registration from the same resource (hot-reload scenario)
+            if (existing.resourceName === metadata.resourceName) {
+                logger_1.loggers.command.debug(`Re-registering command '${metadata.command}' from same resource (hot-reload)`, { command: metadata.command, resource: metadata.resourceName });
+                // Update the entry with new metadata
+                this.remoteCommands.set(commandKey, {
+                    metadata,
+                    resourceName: metadata.resourceName,
+                });
+                return;
+            }
             logger_1.loggers.command.warn(`Remote command '${metadata.command}' already registered`, {
                 command: metadata.command,
-                existingResource: (_a = this.remoteCommands.get(commandKey)) === null || _a === void 0 ? void 0 : _a.resourceName,
+                existingResource: existing.resourceName,
                 newResource: metadata.resourceName,
             });
             return;
@@ -133,7 +198,7 @@ let CommandExportController = class CommandExportController {
     async executeCommand(clientID, commandName, args) {
         const player = this.playerDirectory.getByClient(clientID);
         if (!player) {
-            throw new utils_1.AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${clientID}`, 'core');
+            throw new error_1.AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${clientID}`, 'core');
         }
         const commandKey = commandName.toLowerCase();
         const remoteEntry = this.remoteCommands.get(commandKey);
@@ -199,7 +264,7 @@ let CommandExportController = class CommandExportController {
                 if (onExceed === 'KICK') {
                     DropPlayer(player.clientID.toString(), errorMessage);
                 }
-                throw new security_error_1.SecurityError(onExceed || 'LOG', errorMessage, { clientID: player.clientID });
+                throw new error_1.SecurityError(onExceed || 'LOG', errorMessage, { clientID: player.clientID });
             }
         }
         // 3. Validate @RequiresState (player state)
@@ -208,14 +273,14 @@ let CommandExportController = class CommandExportController {
             if (has) {
                 for (const state of has) {
                     if (!player.hasState(state)) {
-                        throw new utils_1.AppError('GAME:INVALID_STATE', errorMessage || `Command requires state: ${state}`, 'core');
+                        throw new error_1.AppError('GAME:INVALID_STATE', errorMessage || `Command requires state: ${state}`, 'core');
                     }
                 }
             }
             if (missing) {
                 for (const state of missing) {
                     if (player.hasState(state)) {
-                        throw new utils_1.AppError('GAME:INVALID_STATE', errorMessage || `Command cannot be used in state: ${state}`, 'core');
+                        throw new error_1.AppError('GAME:INVALID_STATE', errorMessage || `Command cannot be used in state: ${state}`, 'core');
                     }
                 }
             }
@@ -249,12 +314,13 @@ __decorate([
     __metadata("design:returntype", Array)
 ], CommandExportController.prototype, "getAllCommands", null);
 exports.CommandExportController = CommandExportController = __decorate([
-    (0, tsyringe_1.injectable)(),
     (0, decorators_1.Controller)(),
-    __param(4, (0, tsyringe_1.inject)(IEngineEvents_1.IEngineEvents)),
+    __param(4, (0, tsyringe_1.inject)(command_error_observer_contract_1.CommandErrorObserverContract)),
+    __param(5, (0, tsyringe_1.inject)(IEngineEvents_1.IEngineEvents)),
     __metadata("design:paramtypes", [command_execution_port_1.CommandExecutionPort,
         player_directory_port_1.PlayerDirectoryPort,
         principal_port_1.PrincipalPort,
         rate_limiter_service_1.RateLimiterService,
+        command_error_observer_contract_1.CommandErrorObserverContract,
         IEngineEvents_1.IEngineEvents])
 ], CommandExportController);

package/dist/runtime/server/controllers/player-export.controller.d.ts

@@ -1,5 +1,5 @@
 import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
-import { CorePlayerExports, SerializedPlayerData } from '../types/core-exports';
+import { InternalPlayerExports, SerializedPlayerData } from '../types/core-exports';
 /**
  * Exports player directory functionality for RESOURCE mode access.
  *
@@ -10,7 +10,7 @@ import { CorePlayerExports, SerializedPlayerData } from '../types/core-exports';
  * - Read/write session metadata
  * - Manage player state flags
  */
-export declare class PlayerExportController implements CorePlayerExports {
+export declare class PlayerExportController implements InternalPlayerExports {
     private playerService;
     constructor(playerService: PlayerDirectoryPort);
     getPlayerId(clientID: number): string | undefined;

package/dist/runtime/server/controllers/player-export.controller.js

@@ -8,8 +8,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlayerExportController = void 0;
+const tsyringe_1 = require("tsyringe");
 const controller_1 = require("../decorators/controller");
 const export_1 = require("../decorators/export");
 const player_directory_port_1 = require("../services/ports/player-directory.port");
@@ -169,5 +173,6 @@ __decorate([
 ], PlayerExportController.prototype, "removePlayerState", null);
 exports.PlayerExportController = PlayerExportController = __decorate([
     (0, controller_1.Controller)(),
+    __param(0, (0, tsyringe_1.inject)(player_directory_port_1.PlayerDirectoryPort)),
     __metadata("design:paramtypes", [player_directory_port_1.PlayerDirectoryPort])
 ], PlayerExportController);

package/dist/runtime/server/controllers/principal-export.controller.js

@@ -14,7 +14,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrincipalExportController = void 0;
 const tsyringe_1 = require("tsyringe");
-const utils_1 = require("../../../kernel/utils");
+const app_error_1 = require("../../../kernel/error/app.error");
 const index_1 = require("../contracts/index");
 const export_1 = require("../decorators/export");
 const index_2 = require("../decorators/index");
@@ -188,29 +188,29 @@ let PrincipalExportController = class PrincipalExportController {
     async enforce(source, requirements) {
         const player = this.playerService.getByClient(source);
         if (!player) {
-            throw new utils_1.AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${source}`, 'core');
+            throw new app_error_1.AppError('GAME:PLAYER_NOT_FOUND', `Player not found: ${source}`, 'core');
         }
         if (requirements.rank !== undefined) {
             const principal = await this.principalProvider.getPrincipal(player);
             if (!principal) {
-                throw new utils_1.AppError('AUTH:UNAUTHORIZED', 'No principal found', 'core');
+                throw new app_error_1.AppError('AUTH:UNAUTHORIZED', 'No principal found', 'core');
             }
             if (principal.rank === undefined) {
-                throw new utils_1.AppError('GAME:NO_RANK_IN_PRINCIPAL', "You're trying to compare a Principal rank, but there's no defined rank!", 'core');
+                throw new app_error_1.AppError('GAME:NO_RANK_IN_PRINCIPAL', "You're trying to compare a Principal rank, but there's no defined rank!", 'core');
             }
             if (principal.rank < requirements.rank) {
-                throw new utils_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Requires minimum rank level ${requirements.rank}`, 'core');
+                throw new app_error_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Requires minimum rank level ${requirements.rank}`, 'core');
             }
         }
         if (requirements.permission) {
             const principal = await this.principalProvider.getPrincipal(player);
             if (!principal) {
-                throw new utils_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
+                throw new app_error_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
             }
             const hasPerm = principal.permissions.includes('*') ||
                 principal.permissions.includes(requirements.permission);
             if (!hasPerm) {
-                throw new utils_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
+                throw new app_error_1.AppError('AUTH:PERMISSION_DENIED', `Access Denied: Missing required permission '${requirements.permission}'`, 'core');
             }
         }
     }
@@ -290,6 +290,7 @@ __decorate([
 ], PrincipalExportController.prototype, "enforce", null);
 exports.PrincipalExportController = PrincipalExportController = __decorate([
     (0, index_2.Controller)(),
+    __param(0, (0, tsyringe_1.inject)(player_directory_port_1.PlayerDirectoryPort)),
     __param(1, (0, tsyringe_1.inject)(index_1.PrincipalProviderContract)),
     __metadata("design:paramtypes", [player_directory_port_1.PlayerDirectoryPort,
         index_1.PrincipalProviderContract])

package/dist/runtime/server/controllers/ready.controller.d.ts

@@ -0,0 +1,4 @@
+export declare class ReadyController {
+    private isReady;
+    isCoreReady(): boolean;
+}

package/dist/runtime/server/controllers/ready.controller.js

@@ -0,0 +1,32 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadyController = void 0;
+const controller_1 = require("../decorators/controller");
+const export_1 = require("../decorators/export");
+let ReadyController = class ReadyController {
+    constructor() {
+        this.isReady = true;
+    }
+    isCoreReady() {
+        return this.isReady;
+    }
+};
+exports.ReadyController = ReadyController;
+__decorate([
+    (0, export_1.Export)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Boolean)
+], ReadyController.prototype, "isCoreReady", null);
+exports.ReadyController = ReadyController = __decorate([
+    (0, controller_1.Controller)()
+], ReadyController);

package/dist/runtime/server/controllers/remote-command-execution.controller.d.ts

@@ -1,5 +1,6 @@
 import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
 import { IResourceInfo } from '../../../adapters/contracts/IResourceInfo';
+import { CommandErrorObserverContract } from '../contracts/security/command-error-observer.contract';
 import { CommandExecutionPort } from '../services/ports/command-execution.port';
 import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
 /**
@@ -21,9 +22,17 @@ import { PlayerDirectoryPort } from '../services/ports/player-directory.port';
 export declare class RemoteCommandExecutionController {
     private commandService;
     private playerDirectory;
+    private readonly commandErrorObserver;
     private engineEvents;
     private resourceInfo;
-    constructor(commandService: CommandExecutionPort, playerDirectory: PlayerDirectoryPort, engineEvents: IEngineEvents, resourceInfo: IResourceInfo);
+    constructor(commandService: CommandExecutionPort, playerDirectory: PlayerDirectoryPort, commandErrorObserver: CommandErrorObserverContract, engineEvents: IEngineEvents, resourceInfo: IResourceInfo);
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break command execution.
+     */
+    private safeObserve;
     /**
      * Registers the event handler for command execution from CORE.
      *

package/dist/runtime/server/controllers/remote-command-execution.controller.js

@@ -16,9 +16,11 @@ exports.RemoteCommandExecutionController = void 0;
 const tsyringe_1 = require("tsyringe");
 const IEngineEvents_1 = require("../../../adapters/contracts/IEngineEvents");
 const IResourceInfo_1 = require("../../../adapters/contracts/IResourceInfo");
-const kernel_1 = require("../../../kernel");
-const logger_1 = require("../../../kernel/shared/logger");
+const logger_1 = require("../../../kernel/logger");
+const command_error_observer_contract_1 = require("../contracts/security/command-error-observer.contract");
 const decorators_1 = require("../decorators");
+const normalize_app_error_1 = require("../helpers/normalize-app-error");
+const runtime_1 = require("../runtime");
 const command_execution_port_1 = require("../services/ports/command-execution.port");
 const player_directory_port_1 = require("../services/ports/player-directory.port");
 /**
@@ -38,13 +40,28 @@ const player_directory_port_1 = require("../services/ports/player-directory.port
  * Event registration happens in constructor via adapter layer.
  */
 let RemoteCommandExecutionController = class RemoteCommandExecutionController {
-    constructor(commandService, playerDirectory, engineEvents, resourceInfo) {
+    constructor(commandService, playerDirectory, commandErrorObserver, engineEvents, resourceInfo) {
         this.commandService = commandService;
         this.playerDirectory = playerDirectory;
+        this.commandErrorObserver = commandErrorObserver;
         this.engineEvents = engineEvents;
         this.resourceInfo = resourceInfo;
         this.registerEventHandler();
     }
+    /**
+     * Invokes the global {@link CommandErrorObserverContract} safely.
+     *
+     * @remarks
+     * Observers are user-land code; failures must never break command execution.
+     */
+    async safeObserve(ctx) {
+        try {
+            await this.commandErrorObserver.onError(ctx);
+        }
+        catch (e) {
+            logger_1.loggers.command.fatal(`Command error observer failed`, ctx, e);
+        }
+    }
     /**
      * Registers the event handler for command execution from CORE.
      *
@@ -68,6 +85,11 @@ let RemoteCommandExecutionController = class RemoteCommandExecutionController {
      * @param args - Command arguments
      */
     async handleCommandExecution(clientID, commandName, args) {
+        logger_1.loggers.command.debug(`Received command execution request`, {
+            command: commandName,
+            clientID,
+            args,
+        });
         const player = this.playerDirectory.getByClient(clientID);
         if (!player) {
             logger_1.loggers.command.warn(`Command execution failed: player not found`, {
@@ -76,29 +98,73 @@ let RemoteCommandExecutionController = class RemoteCommandExecutionController {
             });
             return;
         }
+        logger_1.loggers.command.debug(`Executing command for player`, {
+            command: commandName,
+            playerName: player.name,
+            clientID,
+        });
         try {
             await this.commandService.execute(player, commandName, args);
+            logger_1.loggers.command.debug(`Command executed successfully`, {
+                command: commandName,
+                clientID,
+            });
         }
         catch (error) {
-            if (error instanceof kernel_1.AppError) {
-                player.send(error.message);
-            }
-            logger_1.loggers.command.error(`Remote command execution failed`, {
-                command: commandName,
-                clientID: player.clientID,
-                error: error instanceof Error ? error.message : String(error),
+            // Do not notify the player here. Report through the global observer.
+            const runtime = (0, runtime_1.getRuntimeContext)();
+            const appError = (0, normalize_app_error_1.normalizeToAppError)(error, 'server');
+            const meta = this.commandService.getCommandMeta(commandName);
+            const stage = appError.code === 'GAME:BAD_REQUEST' || appError.code.startsWith('SCHEMA:')
+                ? 'validation'
+                : appError.code === 'COMMAND:NOT_FOUND'
+                    ? 'dispatch'
+                    : 'handler';
+            await this.safeObserve({
+                mode: runtime.mode,
+                scope: runtime.mode === 'CORE'
+                    ? 'core'
+                    : runtime.mode === 'RESOURCE'
+                        ? 'resource'
+                        : 'standalone',
+                stage,
+                error: appError,
+                commandName,
+                args,
+                player: {
+                    clientId: player.clientID,
+                    accountId: player.accountID,
+                    name: player.name,
+                },
+                playerRef: player,
+                command: meta
+                    ? {
+                        command: meta.command,
+                        description: meta.description,
+                        usage: meta.usage,
+                        isPublic: meta.isPublic,
+                        methodName: meta.methodName,
+                        expectsPlayer: meta.expectsPlayer,
+                        paramNames: meta.paramNames,
+                    }
+                    : undefined,
+                commandMeta: meta,
+                ownerResourceName: this.resourceInfo.getCurrentResourceName(),
             });
         }
     }
 };
 exports.RemoteCommandExecutionController = RemoteCommandExecutionController;
 exports.RemoteCommandExecutionController = RemoteCommandExecutionController = __decorate([
-    (0, tsyringe_1.injectable)(),
     (0, decorators_1.Controller)(),
-    __param(2, (0, tsyringe_1.inject)(IEngineEvents_1.IEngineEvents)),
-    __param(3, (0, tsyringe_1.inject)(IResourceInfo_1.IResourceInfo)),
+    __param(0, (0, tsyringe_1.inject)(command_execution_port_1.CommandExecutionPort)),
+    __param(1, (0, tsyringe_1.inject)(player_directory_port_1.PlayerDirectoryPort)),
+    __param(2, (0, tsyringe_1.inject)(command_error_observer_contract_1.CommandErrorObserverContract)),
+    __param(3, (0, tsyringe_1.inject)(IEngineEvents_1.IEngineEvents)),
+    __param(4, (0, tsyringe_1.inject)(IResourceInfo_1.IResourceInfo)),
     __metadata("design:paramtypes", [command_execution_port_1.CommandExecutionPort,
         player_directory_port_1.PlayerDirectoryPort,
+        command_error_observer_contract_1.CommandErrorObserverContract,
         IEngineEvents_1.IEngineEvents,
         IResourceInfo_1.IResourceInfo])
 ], RemoteCommandExecutionController);

package/dist/runtime/server/controllers/session.controller.d.ts

@@ -6,6 +6,6 @@ export declare class SessionController {
     private readonly playerDirectory;
     private readonly persistance;
     constructor(playerSessionLifecycle: PlayerSessionLifecyclePort, playerDirectory: PlayerDirectoryPort, persistance: PlayerPersistenceService);
-    onPlayerJoining(): Promise<void>;
-    onPlayerDropped(): Promise<void>;
+    onPlayerJoining(clientId: number, identifiers?: Record<string, string>): Promise<void>;
+    onPlayerDropped(clientId: number): Promise<void>;
 }