@open-core/framework 0.2.8 → 0.3.0

package/dist/runtime/core/spatial.d.ts

@@ -0,0 +1,5 @@
+import { Vector3 } from '../../kernel/utils/vector3';
+export interface Spatial {
+    getPosition(): Vector3;
+    setPosition(v: Vector3): void;
+}

package/dist/runtime/core/spatial.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/core/world.d.ts

@@ -0,0 +1,13 @@
+import { BaseEntity, EntityId } from './entity';
+export declare class WorldContext {
+    private entities;
+    private readonly kindIndex;
+    add(entity: BaseEntity): void;
+    remove(id: EntityId): void;
+    get<T extends BaseEntity = BaseEntity>(id: EntityId): T | undefined;
+    find<T extends BaseEntity>(predicate: (e: BaseEntity) => e is T): T[];
+    find(predicate: (e: BaseEntity) => boolean): BaseEntity[];
+    all(): BaseEntity[];
+    size(): number;
+    sizeBy(kind: string): number;
+}

package/dist/runtime/core/world.js

@@ -0,0 +1,64 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorldContext = void 0;
+const tsyringe_1 = require("tsyringe");
+function getKind(id) {
+    const i = id.indexOf(':');
+    return i === -1 ? id : id.slice(0, i);
+}
+let WorldContext = class WorldContext {
+    constructor() {
+        this.entities = new Map();
+        this.kindIndex = new Map();
+    }
+    add(entity) {
+        var _a;
+        // If replacing, remove first to keep index consistent
+        const prev = this.entities.get(entity.id);
+        if (prev)
+            this.remove(entity.id);
+        this.entities.set(entity.id, entity);
+        const kind = getKind(entity.id);
+        this.kindIndex.set(kind, ((_a = this.kindIndex.get(kind)) !== null && _a !== void 0 ? _a : 0) + 1);
+    }
+    remove(id) {
+        const entity = this.entities.get(id);
+        if (!entity)
+            return;
+        const kind = getKind(id);
+        const n = this.kindIndex.get(kind);
+        if (n !== undefined) {
+            if (n <= 1)
+                this.kindIndex.delete(kind);
+            else
+                this.kindIndex.set(kind, n - 1);
+        }
+        this.entities.delete(id);
+    }
+    get(id) {
+        return this.entities.get(id);
+    }
+    find(predicate) {
+        return [...this.entities.values()].filter(predicate);
+    }
+    all() {
+        return [...this.entities.values()];
+    }
+    size() {
+        return this.entities.size;
+    }
+    sizeBy(kind) {
+        var _a;
+        return (_a = this.kindIndex.get(kind)) !== null && _a !== void 0 ? _a : 0;
+    }
+};
+exports.WorldContext = WorldContext;
+exports.WorldContext = WorldContext = __decorate([
+    (0, tsyringe_1.injectable)()
+], WorldContext);

package/dist/runtime/server/api.d.ts

@@ -0,0 +1,12 @@
+export { onFrameworkEvent } from './bus/internal-event.bus';
+export * from './configs';
+export * from './contracts/index';
+export { init } from './core';
+export * from './decorators';
+export * from './devmode';
+export * from './entities';
+export * from './runtime';
+export * from './services';
+export * from './setup';
+export * from './templates';
+export type * from './types/internal-events';

package/dist/runtime/server/api.js

@@ -0,0 +1,34 @@
+"use strict";
+// Framework modules
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = exports.onFrameworkEvent = void 0;
+var internal_event_bus_1 = require("./bus/internal-event.bus");
+Object.defineProperty(exports, "onFrameworkEvent", { enumerable: true, get: function () { return internal_event_bus_1.onFrameworkEvent; } });
+// Configs
+__exportStar(require("./configs"), exports);
+__exportStar(require("./contracts/index"), exports);
+var core_1 = require("./core");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return core_1.init; } });
+__exportStar(require("./decorators"), exports);
+// DevMode (development tools)
+__exportStar(require("./devmode"), exports);
+// Entities
+__exportStar(require("./entities"), exports);
+__exportStar(require("./runtime"), exports);
+__exportStar(require("./services"), exports);
+__exportStar(require("./setup"), exports);
+__exportStar(require("./templates"), exports);

package/dist/runtime/server/bootstrap.js

@@ -37,8 +37,7 @@ exports.initServer = initServer;
 const adapters_1 = require("../../adapters");
 const register_capabilities_1 = require("../../adapters/register-capabilities");
 const index_1 = require("../../kernel/di/index");
-const logger_1 = require("../../kernel/shared/logger");
-const bootstrap_validation_1 = require("./bootstrap.validation");
+const logger_1 = require("../../kernel/logger");
 const index_2 = require("./contracts/index");
 const controller_1 = require("./decorators/controller");
 const runtime_1 = require("./runtime");
@@ -49,22 +48,14 @@ const CORE_WAIT_TIMEOUT = 10000;
 function checkProviders(ctx) {
     if (ctx.mode === 'RESOURCE')
         return;
-    if (ctx.features.principal.enabled && ctx.features.principal.required) {
-        if (!index_1.di.isRegistered(index_2.PrincipalProviderContract)) {
+    if (ctx.features.principal.enabled) {
+        if (!index_1.GLOBAL_CONTAINER.isRegistered(index_2.PrincipalProviderContract)) {
             const errorMsg = 'No Principal Provider configured. ' +
                 "Please call 'Server.setPrincipalProvider(YourProvider)' before init(). This is required for authorization.";
             logger_1.loggers.bootstrap.fatal(errorMsg);
             throw new Error(`[OpenCore] CRITICAL: ${errorMsg}`);
         }
     }
-    if (ctx.features.auth.enabled && ctx.features.auth.required) {
-        if (!index_1.di.isRegistered(index_2.AuthProviderContract)) {
-            const errorMsg = 'No Authentication Provider configured. ' +
-                "Please call 'Server.setAuthProvider(YourProvider)' before init(). This is required for authentication.";
-            logger_1.loggers.bootstrap.fatal(errorMsg);
-            throw new Error(`[OpenCore] CRITICAL: ${errorMsg}`);
-        }
-    }
 }
 async function loadFrameworkControllers(ctx) {
     if (ctx.features.commands.enabled) {
@@ -89,6 +80,9 @@ async function loadFrameworkControllers(ctx) {
     if (ctx.features.players.enabled && ctx.features.players.export && ctx.features.exports.enabled) {
         await Promise.resolve().then(() => __importStar(require('./controllers/player-export.controller')));
     }
+    if (ctx.mode === 'CORE') {
+        await Promise.resolve().then(() => __importStar(require('./controllers/ready.controller')));
+    }
     if (ctx.features.principal.enabled &&
         ctx.features.principal.export &&
         ctx.features.exports.enabled) {
@@ -120,8 +114,9 @@ async function initServer(options) {
         mode: ctx.mode,
         scope: (0, runtime_1.getFrameworkModeScope)(ctx.mode),
     });
-    // Adapters
+    // Register platform-specific capabilities (adapters)
     await (0, register_capabilities_1.registerServerCapabilities)();
+    logger_1.loggers.bootstrap.debug('Platform capabilities registered');
     const dependenciesToWaitFor = [];
     if (ctx.mode === 'RESOURCE') {
         logger_1.loggers.bootstrap.info(`[WAIT] Standing by for Core '${ctx.coreResourceName}' to be ready...`);
@@ -140,89 +135,20 @@ async function initServer(options) {
         logger_1.loggers.bootstrap.info(`Core ready detected!`);
     }
     logger_1.loggers.bootstrap.debug('Dependencies resolved. Proceeding with system boot.');
+    // 1. Register Core Services (WorldContext, PlayerService, etc.)
     (0, services_register_1.registerServicesServer)(ctx);
     logger_1.loggers.bootstrap.debug('Core services registered');
+    // 2. Load Controllers (Framework & User controllers)
+    // This is where user services get registered if they are decorated with @injectable()
+    // and imported before init() or discovered here.
+    await loadFrameworkControllers(ctx);
+    logger_1.loggers.bootstrap.debug('Controllers loaded');
+    // 3. Register System Processors (Command, NetEvent, etc.)
+    // These processors check if contracts are already registered before applying defaults.
     (0, processors_register_1.registerSystemServer)(ctx);
     logger_1.loggers.bootstrap.debug('System processors registered');
     checkProviders(ctx);
-    // In RESOURCE mode, verify CORE exports are available before loading controllers
-    if (ctx.mode === 'RESOURCE') {
-        const needsCoreExports = ctx.features.players.provider === 'core' ||
-            ctx.features.commands.provider === 'core' ||
-            ctx.features.principal.provider === 'core' ||
-            ctx.features.auth.provider === 'core';
-        if (needsCoreExports) {
-            const { coreResourceName } = ctx;
-            logger_1.loggers.bootstrap.debug(`Verifying CORE exports availability`, {
-                coreResourceName,
-                globalExportsKeys: Object.keys(globalThis.exports || {}),
-            });
-            // Build list of required exports
-            const requiredExports = [];
-            if (ctx.features.commands.provider === 'core') {
-                requiredExports.push('registerCommand', 'executeCommand', 'getAllCommands');
-            }
-            if (ctx.features.players.provider === 'core') {
-                requiredExports.push('getPlayerId', 'getPlayerData', 'getAllPlayersData', 'getPlayerByAccountId', 'getPlayerCount', 'isPlayerOnline', 'getPlayerMeta', 'setPlayerMeta', 'getPlayerStates', 'hasPlayerState', 'addPlayerState', 'removePlayerState');
-            }
-            if (ctx.features.principal.provider === 'core') {
-                requiredExports.push('getPrincipal', 'getPrincipalByAccountId', 'refreshPrincipal', 'hasPermission', 'hasRank', 'hasAnyPermission', 'hasAllPermissions', 'getPermissions', 'getRank', 'getPrincipalName', 'getPrincipalMeta');
-            }
-            logger_1.loggers.bootstrap.debug(`Checking CORE exports`, {
-                coreResourceName,
-                requiredExports,
-            });
-            // Access exports directly using FiveM's global exports object
-            const globalExports = globalThis.exports;
-            if (!globalExports) {
-                throw new Error(`[OpenCore] FiveM 'exports' global not found. This should never happen in a FiveM environment.`);
-            }
-            const coreExports = globalExports[coreResourceName];
-            // Check each required export directly (can't use Object.keys on FiveM exports proxy)
-            const missingExports = [];
-            for (const exportName of requiredExports) {
-                try {
-                    const exportValue = coreExports === null || coreExports === void 0 ? void 0 : coreExports[exportName];
-                    if (typeof exportValue !== 'function') {
-                        missingExports.push(exportName);
-                        logger_1.loggers.bootstrap.warn(`Export '${exportName}' is not a function`, {
-                            exportName,
-                            type: typeof exportValue,
-                            value: exportValue,
-                        });
-                    }
-                }
-                catch (error) {
-                    missingExports.push(exportName);
-                    logger_1.loggers.bootstrap.warn(`Failed to access export '${exportName}'`, {
-                        exportName,
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                }
-            }
-            if (missingExports.length > 0) {
-                const errorMsg = `CORE resource '${coreResourceName}' is missing ${missingExports.length} required exports: ${missingExports.join(', ')}\n` +
-                    `\n` +
-                    `This usually means:\n` +
-                    `  1. The CORE resource failed to initialize properly\n` +
-                    `  2. The CORE resource doesn't have the 'exports' feature enabled\n` +
-                    `  3. The CORE resource doesn't have the required features enabled (commands: ${ctx.features.commands.provider === 'core'})\n` +
-                    `\n` +
-                    `Verify in '${coreResourceName}/src/server/server.ts':\n` +
-                    `  - mode: 'CORE'\n` +
-                    `  - features.exports.enabled: true\n` +
-                    `  - features.commands.enabled: true (if using commands)`;
-                logger_1.loggers.bootstrap.fatal(errorMsg);
-                throw new Error(`[OpenCore] ${errorMsg}`);
-            }
-        }
-    }
-    await loadFrameworkControllers(ctx);
-    if (ctx.features.database.enabled) {
-        (0, bootstrap_validation_1.registerDefaultBootstrapValidators)();
-        await (0, bootstrap_validation_1.runBootstrapValidatorsOrThrow)();
-    }
-    const scanner = index_1.di.resolve(index_1.MetadataScanner);
+    const scanner = index_1.GLOBAL_CONTAINER.resolve(index_1.MetadataScanner);
     scanner.scan((0, controller_1.getServerControllerRegistry)());
     // Initialize DevMode if enabled
     if ((_d = ctx.devMode) === null || _d === void 0 ? void 0 : _d.enabled) {
@@ -233,26 +159,56 @@ async function initServer(options) {
         runSessionRecovery();
     }
     logger_1.loggers.bootstrap.info('OpenCore Server initialized successfully');
-    if (ctx.mode === 'CORE' && index_1.di.isRegistered(adapters_1.IEngineEvents)) {
-        const engineInterface = index_1.di.resolve(adapters_1.IEngineEvents);
-        engineInterface.emit('core:ready');
+    if (ctx.mode === 'CORE' &&
+        index_1.GLOBAL_CONTAINER.isRegistered(adapters_1.IEngineEvents) &&
+        index_1.GLOBAL_CONTAINER.isRegistered(adapters_1.INetTransport)) {
+        const engineEvents = index_1.GLOBAL_CONTAINER.resolve(adapters_1.IEngineEvents); // server -> servers
+        const net = index_1.GLOBAL_CONTAINER.resolve(adapters_1.INetTransport); // server -> clients
+        engineEvents.emit('core:ready'); // Broadcast to all Servers resources
+        net.emitNet('core:ready', 'all'); // Broadcast to all Clients resources
+        logger_1.loggers.bootstrap.debug(`'core:ready' events emmited to all clients and all servers`);
     }
 }
 function createCoreDependency(coreName) {
     return new Promise((resolve, reject) => {
         let resolved = false;
-        const engineEvents = index_1.di.resolve(adapters_1.IEngineEvents);
+        const engineEvents = index_1.GLOBAL_CONTAINER.resolve(adapters_1.IEngineEvents);
         const cleanup = () => {
             resolved = true;
             clearTimeout(timeout);
+            clearInterval(pollingInterval);
+        };
+        // 1. Check if already ready via export (Polling)
+        const checkReady = () => {
+            var _a, _b;
+            if (resolved)
+                return;
+            try {
+                const globalExports = globalThis.exports;
+                const isReady = (_b = (_a = globalExports === null || globalExports === void 0 ? void 0 : globalExports[coreName]) === null || _a === void 0 ? void 0 : _a.isCoreReady) === null || _b === void 0 ? void 0 : _b.call(_a);
+                if (isReady === true) {
+                    logger_1.loggers.bootstrap.debug(`Core '${coreName}' detected as already ready via export.`);
+                    cleanup();
+                    resolve();
+                }
+            }
+            catch (_c) {
+                // Core might not be started yet, ignore
+            }
         };
+        const pollingInterval = setInterval(checkReady, 500);
+        checkReady(); // Initial check
+        // 2. Timeout protection
         const timeout = setTimeout(() => {
             if (!resolved) {
-                reject(new Error(`[OpenCore] Timeout waiting for CORE '${coreName}'. The Core did not emit 'core:ready' within ${CORE_WAIT_TIMEOUT}ms.`));
+                cleanup();
+                reject(new Error(`[OpenCore] Timeout waiting for CORE '${coreName}'. The Core did not emit 'core:ready' or expose 'isCoreReady' within ${CORE_WAIT_TIMEOUT}ms.`));
             }
         }, CORE_WAIT_TIMEOUT);
+        // 3. Listen for the event (for resources starting after/during CORE init)
         const onReady = () => {
             if (!resolved) {
+                logger_1.loggers.bootstrap.debug(`Core '${coreName}' detected via 'core:ready' event.`);
                 cleanup();
                 resolve();
             }
@@ -293,7 +249,7 @@ async function dependencyResolver(waitFor, onReady) {
  */
 function runSessionRecovery() {
     try {
-        const recoveryService = index_1.di.resolve(session_recovery_service_1.SessionRecoveryService);
+        const recoveryService = index_1.GLOBAL_CONTAINER.resolve(session_recovery_service_1.SessionRecoveryService);
         const stats = recoveryService.recoverSessions();
         if (stats.recovered > 0) {
             logger_1.loggers.bootstrap.info(`[SessionRecovery] Recovered ${stats.recovered} player session(s)`);
@@ -315,15 +271,14 @@ async function initDevMode(config) {
     const { StateInspectorService } = await Promise.resolve().then(() => __importStar(require('./devmode/state-inspector.service')));
     const { PlayerSimulatorService } = await Promise.resolve().then(() => __importStar(require('./devmode/player-simulator.service')));
     // Register DevMode services
-    index_1.di.registerSingleton(EventInterceptorService, EventInterceptorService);
-    index_1.di.registerSingleton(StateInspectorService, StateInspectorService);
-    index_1.di.registerSingleton(PlayerSimulatorService, PlayerSimulatorService);
-    index_1.di.registerSingleton(DevModeService, DevModeService);
+    index_1.GLOBAL_CONTAINER.registerSingleton(EventInterceptorService, EventInterceptorService);
+    index_1.GLOBAL_CONTAINER.registerSingleton(StateInspectorService, StateInspectorService);
+    index_1.GLOBAL_CONTAINER.registerSingleton(PlayerSimulatorService, PlayerSimulatorService);
+    index_1.GLOBAL_CONTAINER.registerSingleton(DevModeService, DevModeService);
     // Enable DevMode
-    const devModeService = index_1.di.resolve(DevModeService);
+    const devModeService = index_1.GLOBAL_CONTAINER.resolve(DevModeService);
     await devModeService.enable({
         enabled: true,
-        hotReload: config.hotReload,
         bridge: config.bridge,
         interceptor: config.interceptor,
         simulator: config.simulator,

package/dist/runtime/server/bus/internal-event.bus.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.onFrameworkEvent = onFrameworkEvent;
 exports.emitFrameworkEvent = emitFrameworkEvent;
-const logger_1 = require("../../../kernel/shared/logger");
+const logger_1 = require("../../../kernel/logger");
 const handlers = {};
 function onFrameworkEvent(event, handler) {
     let list = handlers[event];

package/dist/runtime/server/contracts/index.d.ts

@@ -1,6 +1,5 @@
-export * from './auth-provider.contract';
 export * from './player-persistence.contract';
-export * from './repository/index';
+export * from './security/command-error-observer.contract';
 export * from './security/net-event-security-observer.contract';
 export * from './security/permission.types';
 export * from './security/principal-provider.contract';

package/dist/runtime/server/contracts/index.js

@@ -15,10 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./auth-provider.contract"), exports);
+// Persistence
 __exportStar(require("./player-persistence.contract"), exports);
-// Repository
-__exportStar(require("./repository/index"), exports);
+__exportStar(require("./security/command-error-observer.contract"), exports);
 __exportStar(require("./security/net-event-security-observer.contract"), exports);
 __exportStar(require("./security/permission.types"), exports);
 __exportStar(require("./security/principal-provider.contract"), exports);

package/dist/runtime/server/contracts/player-persistence.contract.d.ts

@@ -36,24 +36,22 @@ export declare const DEFAULT_PERSISTENCE_CONFIG: PersistenceConfig;
  *   }
  *
  *   async onSessionLoad(player: Player): Promise<void> {
- *     const data = await this.db.single('SELECT * FROM players WHERE license = ?', [player.license])
- *     if (data) {
- *       player.setMeta('money', data.money)
- *       player.setMeta('job', data.job)
- *     }
- *   }
- *
- *   async onSessionSave(player: Player): Promise<void> {
- *     await this.db.execute(
- *       'UPDATE players SET money = ?, job = ? WHERE license = ?',
- *       [player.getMeta('money'), player.getMeta('job'), player.license]
- *     )
- *   }
- *
- *   async onAutoSave(player: Player): Promise<void> {
- *     // Can delegate to onSessionSave or implement lighter save logic
- *     await this.onSessionSave(player)
- *   }
+    // Example: fetch data from your own storage
+    // const data = await myStorage.find(player.license)
+    // if (data) {
+    //   player.setMeta('money', data.money)
+    // }
+  }
+
+  async onSessionSave(player: Player): Promise<void> {
+    // Example: save data to your own storage
+    // await myStorage.save(player.license, { money: player.getMeta('money') })
+  }
+
+  async onAutoSave(player: Player): Promise<void> {
+    // Can delegate to onSessionSave or implement lighter save logic
+    await this.onSessionSave(player)
+  }
  * }
  * ```
  */

package/dist/runtime/server/contracts/player-persistence.contract.js

@@ -26,24 +26,22 @@ exports.DEFAULT_PERSISTENCE_CONFIG = {
  *   }
  *
  *   async onSessionLoad(player: Player): Promise<void> {
- *     const data = await this.db.single('SELECT * FROM players WHERE license = ?', [player.license])
- *     if (data) {
- *       player.setMeta('money', data.money)
- *       player.setMeta('job', data.job)
- *     }
- *   }
- *
- *   async onSessionSave(player: Player): Promise<void> {
- *     await this.db.execute(
- *       'UPDATE players SET money = ?, job = ? WHERE license = ?',
- *       [player.getMeta('money'), player.getMeta('job'), player.license]
- *     )
- *   }
- *
- *   async onAutoSave(player: Player): Promise<void> {
- *     // Can delegate to onSessionSave or implement lighter save logic
- *     await this.onSessionSave(player)
- *   }
+    // Example: fetch data from your own storage
+    // const data = await myStorage.find(player.license)
+    // if (data) {
+    //   player.setMeta('money', data.money)
+    // }
+  }
+
+  async onSessionSave(player: Player): Promise<void> {
+    // Example: save data to your own storage
+    // await myStorage.save(player.license, { money: player.getMeta('money') })
+  }
+
+  async onAutoSave(player: Player): Promise<void> {
+    // Can delegate to onSessionSave or implement lighter save logic
+    await this.onSessionSave(player)
+  }
  * }
  * ```
  */

package/dist/runtime/server/contracts/security/command-error-observer.contract.d.ts

@@ -0,0 +1,73 @@
+import { AppError } from '../../../../kernel/error';
+import type { CommandMetadata } from '../../decorators/command';
+import type { Player } from '../../entities/player';
+import type { FeatureScope, FrameworkMode } from '../../runtime';
+/**
+ * High-level stage where a command error happened.
+ *
+ * @remarks
+ * Useful to drive decisions (e.g. show usage on validation errors).
+ */
+export type CommandErrorStage = 'dispatch' | 'auth' | 'security' | 'validation' | 'handler' | 'unknown';
+/**
+ * Public-facing command info intended for error reporting.
+ */
+export interface CommandErrorCommandInfo {
+    command: string;
+    description?: string;
+    usage?: string;
+    isPublic?: boolean;
+    methodName?: string;
+    expectsPlayer?: boolean;
+    paramNames?: string[];
+}
+/**
+ * Minimal player identity for error reporting.
+ */
+export interface CommandErrorPlayerInfo {
+    clientId: number;
+    accountId?: string;
+    name?: string;
+}
+/**
+ * Rich context emitted whenever command execution fails.
+ *
+ * @remarks
+ * The framework does not notify players directly. Consumers can implement
+ * {@link CommandErrorObserverContract} to decide how to report errors.
+ */
+export interface CommandErrorContext {
+    mode: FrameworkMode;
+    scope: FeatureScope;
+    stage: CommandErrorStage;
+    error: AppError;
+    commandName: string;
+    args: string[];
+    player: CommandErrorPlayerInfo;
+    /**
+     * Optional reference to the Player entity. Useful for custom
+     * (e.g. sending a chat message).
+     */
+    playerRef?: Player;
+    /**
+     * Best-effort command info (usage/description/etc.) to support.
+     */
+    command?: CommandErrorCommandInfo;
+    /**
+     * Raw metadata from the decorator, when available in the current runtime.
+     */
+    commandMeta?: CommandMetadata;
+    /**
+     * If the command is owned by a resource (remote command), indicates the owner.
+     */
+    ownerResourceName?: string;
+}
+/**
+ * Global observer contract for command execution errors.
+ */
+export declare abstract class CommandErrorObserverContract {
+    /**
+     * Called whenever command execution fails.
+     */
+    abstract onError(ctx: CommandErrorContext): Promise<void>;
+}

package/dist/runtime/server/contracts/security/command-error-observer.contract.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandErrorObserverContract = void 0;
+/**
+ * Global observer contract for command execution errors.
+ */
+class CommandErrorObserverContract {
+}
+exports.CommandErrorObserverContract = CommandErrorObserverContract;

package/dist/runtime/server/contracts/security/permission.types.d.ts

@@ -1,10 +1,10 @@
 /**
  * Represents the security identity of a user/player within the framework.
- * This interface bridges the gap between the Core framework and your specific database implementation.
+ * This interface bridges the gap between the Core framework and your specific implementation.
  */
 export interface Principal {
     /**
-     * Unique identifier for the user (e.g., database role ID).
+     * Unique identifier for the user (e.g., persistent role ID).
      */
     id: string;
     /**

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

@@ -1,17 +1,17 @@
-import { Server } from '../../../..';
+import { Server } from '../..';
 import { LinkedID } from '../../services/types/linked-id';
 import { Principal } from './permission.types';
 /**
  * **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 { ... }
  * ```
  */
 export declare abstract class PrincipalProviderContract {

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>;
 }