@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.2

package/dist/runtime/server/bootstrap.js

@@ -0,0 +1,318 @@
+import { IEngineEvents, IPlatformContext } from '../../adapters';
+import { IExports } from '../../adapters/contracts/IExports';
+import { EventsAPI } from '../../adapters/contracts/transport/events.api';
+import { GLOBAL_CONTAINER, MetadataScanner } from '../../kernel/di/index';
+import { getLogLevel, LogLevelLabels, loggers } from '../../kernel/logger';
+import { createNodeServerAdapter } from './adapter/node-server-adapter';
+import { installServerAdapter } from './adapter/registry';
+import { PrincipalProviderContract } from './contracts/index';
+import { getServerBinaryServiceRegistry } from './decorators/binaryService';
+import { getServerControllerRegistry } from './decorators/controller';
+import { getFrameworkModeScope, setRuntimeContext, validateRuntimeOptions, } from './runtime';
+import { BinaryProcessManager } from './system/managers/binary-process.manager';
+import { SessionRecoveryService } from './services/session-recovery.local';
+import { registerServicesServer } from './services/services.register';
+import { METADATA_KEYS } from './system/metadata-server.keys';
+import { registerSystemServer } from './system/processors.register';
+const CORE_WAIT_TIMEOUT = 10000;
+function checkProviders(ctx) {
+    if (ctx.mode === 'RESOURCE')
+        return;
+    if (ctx.features.principal.enabled) {
+        if (!GLOBAL_CONTAINER.isRegistered(PrincipalProviderContract)) {
+            const errorMsg = 'No Principal Provider configured. ' +
+                "Please call 'Server.setPrincipalProvider(YourProvider)' before init(). This is required for authorization.";
+            loggers.bootstrap.fatal(errorMsg);
+            throw new Error(`[OpenCore] CRITICAL: ${errorMsg}`);
+        }
+    }
+}
+async function loadFrameworkControllers(ctx) {
+    if (ctx.features.commands.enabled) {
+        if (ctx.mode === 'RESOURCE') {
+            // RESOURCE mode: only load the controller that receives delegated commands from CORE
+            await import('./controllers/remote-command-execution.controller');
+        }
+        else {
+            // CORE/STANDALONE mode: load the unified command controller
+            // This handles both network events and exports in a single controller
+            await import('./controllers/command-export.controller');
+        }
+    }
+    if (ctx.features.chat.enabled && ctx.features.chat.export && ctx.features.exports.enabled) {
+        if (ctx.mode !== 'RESOURCE') {
+            await import('./controllers/chat.controller');
+        }
+    }
+    if (ctx.features.sessionLifecycle.enabled && ctx.mode !== 'RESOURCE') {
+        await import('./controllers/session.controller');
+    }
+    if (ctx.features.players.enabled && ctx.features.players.export && ctx.features.exports.enabled) {
+        await import('./controllers/player-export.controller');
+    }
+    if (ctx.features.chat.enabled && ctx.features.exports.enabled && ctx.mode === 'CORE') {
+        await import('./controllers/channel.controller');
+    }
+    if (ctx.mode === 'CORE') {
+        await import('./controllers/ready.controller');
+    }
+    if (ctx.features.principal.enabled &&
+        ctx.features.principal.export &&
+        ctx.features.exports.enabled) {
+        await import('./controllers/principal-export.controller');
+    }
+}
+/**
+ * Bootstraps the OpenCore Server Application Context.
+ *
+ * This is the primary entry point for the server-side framework. It orchestrates the
+ * initialization of the Dependency Injection (DI) container and establishes the
+ * bridge between the low-level FiveM runtime and the OpenCore architecture.
+ *
+ * **Initialization Lifecycle:**
+ * 1. **Infrastructure Registration:** Registers core infrastructure services (`PlayerService`, `CommandService`, `HttpService`) as Singletons in the IoC container.
+ * 2. **Reflection & Discovery:** Scans all decorated classes (Controllers, Services) to extract metadata defined by `@Command`, `@OnNet`, etc.
+ * 3. **Runtime Binding:** Binds the discovered metadata to actual FiveM natives (e.g., `RegisterCommand`, `onNet`, `exports`).
+ * 4. **Session Management:** Activates the player session tracking system.
+ *
+ * @returns A promise that resolves when the Core is fully initialized and ready to process events.
+ */
+export async function initServer(options, plugins) {
+    validateRuntimeOptions(options);
+    setRuntimeContext(options);
+    const ctx = options;
+    loggers.bootstrap.info('Initializing OpenCore Server...');
+    loggers.bootstrap.debug('Runtime configuration', {
+        mode: ctx.mode,
+        scope: getFrameworkModeScope(ctx.mode),
+    });
+    // Register platform-specific capabilities through the selected server adapter.
+    await installServerAdapter(options.adapter ?? createNodeServerAdapter());
+    const platformContext = GLOBAL_CONTAINER.resolve(IPlatformContext);
+    loggers.bootstrap.debug('Loading server Adapter ', {
+        adapter: options.adapter?.name ?? 'node',
+        game: platformContext.gameProfile,
+    });
+    const dependenciesToWaitFor = [];
+    if (ctx.mode === 'RESOURCE') {
+        loggers.bootstrap.info(`[WAIT] Standing by for Core '${ctx.coreResourceName}' to be ready...`);
+        dependenciesToWaitFor.push(createCoreDependency(ctx.coreResourceName));
+    }
+    if (options.onDependency?.waitFor) {
+        const userDeps = Array.isArray(options.onDependency.waitFor)
+            ? options.onDependency.waitFor
+            : [options.onDependency.waitFor];
+        dependenciesToWaitFor.push(...userDeps);
+    }
+    if (dependenciesToWaitFor.length > 0 || options.onDependency?.onReady) {
+        await dependencyResolver(dependenciesToWaitFor, options.onDependency?.onReady);
+    }
+    if (ctx.mode === 'RESOURCE') {
+        loggers.bootstrap.info(`Core ready detected!`);
+    }
+    loggers.bootstrap.debug('Dependencies resolved. Proceeding with system boot.');
+    // 1. Register Core Services (WorldContext, PlayerService, etc.)
+    registerServicesServer(ctx);
+    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);
+    loggers.bootstrap.debug('Frameworks Controllers loaded');
+    await tryImportAutoLoad();
+    loggers.bootstrap.debug('User Controllers loaded');
+    if (plugins) {
+        await plugins.registry.startAll(plugins.context);
+        loggers.bootstrap.debug('Server plugins started');
+    }
+    // 3. Register System Processors (Command, NetEvent, etc.)
+    // These processors check if contracts are already registered before applying defaults.
+    registerSystemServer(ctx);
+    loggers.bootstrap.debug('System processors registered');
+    checkProviders(ctx);
+    const scanner = GLOBAL_CONTAINER.resolve(MetadataScanner);
+    scanner.scan(getServerControllerRegistry());
+    const binaryServices = getServerBinaryServiceRegistry();
+    for (const serviceClass of binaryServices) {
+        const metadata = Reflect.getMetadata(METADATA_KEYS.BINARY_SERVICE, serviceClass);
+        if (!metadata)
+            continue;
+        const manager = GLOBAL_CONTAINER.resolve(BinaryProcessManager);
+        try {
+            manager.register(metadata, metadata.serviceClass);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            loggers.bootstrap.error(`[BinaryService] Failed to register ${metadata.name}`, {
+                error: message,
+            });
+        }
+    }
+    // Initialize DevMode if enabled
+    if (ctx.devMode?.enabled) {
+        await initDevMode(ctx.devMode);
+    }
+    // Run session recovery if enabled (recovers sessions for players already connected)
+    if (ctx.features.sessionLifecycle.enabled && ctx.features.sessionLifecycle.recoveryOnRestart) {
+        runSessionRecovery();
+    }
+    loggers.bootstrap.info('OpenCore Server initialized successfully');
+    if (ctx.mode === 'CORE' &&
+        GLOBAL_CONTAINER.isRegistered(IEngineEvents) &&
+        GLOBAL_CONTAINER.isRegistered(EventsAPI)) {
+        const engineEvents = GLOBAL_CONTAINER.resolve(IEngineEvents);
+        const events = GLOBAL_CONTAINER.resolve(EventsAPI);
+        // 1. Broadast to resources already running
+        engineEvents.emit('core:ready');
+        events.emit('core:ready', 'all');
+        // 2. Listen for 'core:request-ready' for resources starting late (hot-reload)
+        engineEvents.on('core:request-ready', () => {
+            engineEvents.emit('core:ready');
+        });
+        loggers.bootstrap.info(`'core:ready' logic initialized and broadcasted`);
+    }
+    const logLevelLabel = LogLevelLabels[getLogLevel()];
+    loggers.bootstrap.info(`LogLevel Setted: ${logLevelLabel}`);
+}
+function createCoreDependency(coreName) {
+    loggers.bootstrap.debug(`Setting up detection mechanisms for Core '${coreName}'...`);
+    return new Promise((resolve, reject) => {
+        let resolved = false;
+        let pollingInterval;
+        let timeout;
+        const engineEvents = GLOBAL_CONTAINER.resolve(IEngineEvents);
+        const cleanup = () => {
+            resolved = true;
+            if (timeout)
+                clearTimeout(timeout);
+            if (pollingInterval)
+                clearInterval(pollingInterval);
+        };
+        // 1. Register listener FIRST (before any requests)
+        const exportsService = GLOBAL_CONTAINER.resolve(IExports);
+        const onReady = () => {
+            if (!resolved) {
+                loggers.bootstrap.debug(`Core '${coreName}' detected via 'core:ready' event!`);
+                cleanup();
+                resolve();
+            }
+        };
+        engineEvents.on('core:ready', onReady);
+        loggers.bootstrap.debug(`Listening for 'core:ready' event from Core`);
+        // 2. Check if already ready via export (Polling)
+        const checkReady = () => {
+            if (resolved)
+                return;
+            try {
+                const isReady = exportsService
+                    .getResource(coreName)
+                    ?.isCoreReady?.();
+                loggers.bootstrap.debug(`Polling isCoreReady export: ${isReady}`);
+                if (isReady === true) {
+                    loggers.bootstrap.debug(`Core '${coreName}' detected via isCoreReady export!`);
+                    cleanup();
+                    resolve();
+                }
+            }
+            catch (e) {
+                loggers.bootstrap.debug(`Export check failed: ${e}`);
+            }
+        };
+        pollingInterval = setInterval(checkReady, 500);
+        checkReady(); // Initial check
+        // 3. Request status (for hot-reload cases where Core is already up)
+        // This is sent AFTER registering the listener so we can receive the response
+        if (!resolved) {
+            loggers.bootstrap.debug(`Requesting Core status via 'core:request-ready' event`);
+            engineEvents.emit('core:request-ready');
+        }
+        // 4. Timeout protection
+        timeout = setTimeout(() => {
+            if (!resolved) {
+                loggers.bootstrap.warn(`Timeout waiting for Core '${coreName}' after ${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);
+    });
+}
+async function dependencyResolver(waitFor, onReady) {
+    if (waitFor) {
+        const dependencyPromises = Array.isArray(waitFor) ? waitFor : [waitFor];
+        try {
+            await Promise.all(dependencyPromises);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            loggers.bootstrap.fatal(`Failed to resolve startup dependencies`, { error: msg });
+            throw new Error(`[OpenCore] Startup aborted: ${msg}`);
+        }
+    }
+    if (onReady) {
+        try {
+            await onReady();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            loggers.bootstrap.fatal('Failed to execute onReady hook', { error: msg });
+            throw new Error(`[OpenCore] onReady hook failed: ${msg}`);
+        }
+    }
+}
+async function tryImportAutoLoad() {
+    try {
+        await import('./.opencore/autoload.server.controllers');
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('Cannot find module')) {
+            loggers.bootstrap.warn(`[Bootstrap] No server controllers autoload file found, skipping.`);
+            return;
+        }
+        throw err;
+    }
+}
+/**
+ * Runs session recovery to restore sessions for players already connected.
+ *
+ * @remarks
+ * This is useful during development when hot-reloading resources.
+ * Players remain connected to FiveM but lose their sessions when the resource restarts.
+ * This function detects these orphaned players and recreates their sessions.
+ */
+function runSessionRecovery() {
+    try {
+        const recoveryService = GLOBAL_CONTAINER.resolve(SessionRecoveryService);
+        const stats = recoveryService.recoverSessions();
+        if (stats.recovered > 0) {
+            loggers.bootstrap.info(`[SessionRecovery] Recovered ${stats.recovered} player session(s)`);
+        }
+    }
+    catch (error) {
+        loggers.bootstrap.warn('[SessionRecovery] Failed to run session recovery', {
+            error: error.message,
+        });
+    }
+}
+/**
+ * Initializes the DevMode subsystem.
+ * This is loaded dynamically to avoid bundling dev tools in production.
+ */
+async function initDevMode(config) {
+    const { DevModeService } = await import('./devmode/dev-mode.service');
+    const { EventInterceptorService } = await import('./devmode/event-interceptor.service');
+    const { StateInspectorService } = await import('./devmode/state-inspector.service');
+    const { PlayerSimulatorService } = await import('./devmode/player-simulator.service');
+    // Register DevMode services
+    GLOBAL_CONTAINER.registerSingleton(EventInterceptorService, EventInterceptorService);
+    GLOBAL_CONTAINER.registerSingleton(StateInspectorService, StateInspectorService);
+    GLOBAL_CONTAINER.registerSingleton(PlayerSimulatorService, PlayerSimulatorService);
+    GLOBAL_CONTAINER.registerSingleton(DevModeService, DevModeService);
+    // Enable DevMode
+    const devModeService = GLOBAL_CONTAINER.resolve(DevModeService);
+    await devModeService.enable({
+        enabled: true,
+        bridge: config.bridge,
+        interceptor: config.interceptor,
+        simulator: config.simulator,
+    });
+}

package/dist/runtime/server/bus/internal-event.bus.d.ts

@@ -0,0 +1,6 @@
+import { FrameworkEventsMap } from '../types/framework-events.types';
+type InternalEventName = keyof FrameworkEventsMap;
+type InternalEventHandler<E extends InternalEventName> = (payload: FrameworkEventsMap[E]) => void;
+export declare function onFrameworkEvent<E extends InternalEventName>(event: E, handler: InternalEventHandler<E>): () => void;
+export declare function emitFrameworkEvent<E extends InternalEventName>(event: E, payload: FrameworkEventsMap[E]): void;
+export {};

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

@@ -0,0 +1,30 @@
+import { loggers } from '../../../kernel/logger';
+const handlers = {};
+export function onFrameworkEvent(event, handler) {
+    let list = handlers[event];
+    if (!list) {
+        list = [];
+        handlers[event] = list;
+    }
+    list.push(handler);
+    return () => {
+        const index = list.indexOf(handler);
+        if (index !== -1)
+            list.splice(index, 1);
+    };
+}
+export function emitFrameworkEvent(event, payload) {
+    const list = handlers[event];
+    if (!list)
+        return;
+    for (const handler of list) {
+        try {
+            handler(payload);
+        }
+        catch (error) {
+            loggers.eventBus.error(`Handler error for event`, {
+                event,
+            }, error);
+        }
+    }
+}

package/dist/runtime/server/bus/library-event.bus.d.ts

@@ -0,0 +1,5 @@
+import { LibraryEventEnvelope, LibraryEventId } from '../../core/library/types';
+type LibraryEventHandler = (event: LibraryEventEnvelope) => void | Promise<void>;
+export declare function onLibraryEvent(eventId: LibraryEventId, handler: LibraryEventHandler): () => void;
+export declare function emitLibraryEvent(eventId: LibraryEventId, event: LibraryEventEnvelope): void;
+export {};

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

@@ -0,0 +1,27 @@
+import { loggers } from '../../../kernel/logger';
+const handlers = new Map();
+export function onLibraryEvent(eventId, handler) {
+    const eventHandlers = handlers.get(eventId) ?? new Set();
+    eventHandlers.add(handler);
+    handlers.set(eventId, eventHandlers);
+    return () => {
+        const current = handlers.get(eventId);
+        if (!current)
+            return;
+        current.delete(handler);
+        if (current.size === 0)
+            handlers.delete(eventId);
+    };
+}
+export function emitLibraryEvent(eventId, event) {
+    const eventHandlers = handlers.get(eventId);
+    if (!eventHandlers || eventHandlers.size === 0)
+        return;
+    for (const handler of [...eventHandlers]) {
+        Promise.resolve(handler(event)).catch((error) => {
+            loggers.eventBus.error(`Handler error in library event`, {
+                eventId,
+            }, error);
+        });
+    }
+}

package/dist/runtime/server/concepts/channel.d.ts

@@ -0,0 +1,29 @@
+import { Player } from '../entities/player';
+import { ChannelMetadata, ChannelSubscription, ChannelType } from '../types/channel.types';
+export declare class Channel {
+    readonly id: string;
+    readonly metadata: ChannelMetadata;
+    private readonly maxSubscribers?;
+    private subscribers;
+    constructor(id: string, metadata: ChannelMetadata, maxSubscribers?: number | undefined);
+    subscribe(player: Player, subscriptionMetadata?: Record<string, unknown>): boolean;
+    unsubscribe(player: Player): boolean;
+    isSubscribed(player: Player): boolean;
+    getSubscribers(): Player[];
+    getSubscriberCount(): number;
+    getSubscription(player: Player): ChannelSubscription | undefined;
+    clear(): void;
+    get type(): ChannelType;
+    get isPersistent(): boolean;
+    toJSON(): {
+        id: string;
+        metadata: ChannelMetadata;
+        subscriberCount: number;
+        subscribers: {
+            clientID: number;
+            name: string;
+            subscribedAt: number;
+        }[];
+    };
+    private debugLog;
+}

package/dist/runtime/server/concepts/channel.js

@@ -0,0 +1,70 @@
+import { loggers } from '../../../kernel/logger';
+export class Channel {
+    id;
+    metadata;
+    maxSubscribers;
+    subscribers = new Map();
+    constructor(id, metadata, maxSubscribers) {
+        this.id = id;
+        this.metadata = metadata;
+        this.maxSubscribers = maxSubscribers;
+    }
+    subscribe(player, subscriptionMetadata) {
+        if (this.maxSubscribers && this.subscribers.size >= this.maxSubscribers) {
+            this.debugLog('It has already reached its subscriber limit');
+            return false;
+        }
+        if (this.subscribers.has(player.clientID)) {
+            this.debugLog('already subscribed');
+            return false;
+        }
+        this.subscribers.set(player.clientID, {
+            player,
+            subscribedAt: Date.now(),
+            metadata: subscriptionMetadata,
+        });
+        this.debugLog(`player ${player.id} has subscribed to channel ${this.id}`);
+        return true;
+    }
+    unsubscribe(player) {
+        this.debugLog(`player ${player.id} has unsubscribed from channel ${this.id}`);
+        return this.subscribers.delete(player.clientID);
+    }
+    isSubscribed(player) {
+        this.debugLog(`player ${player.id} already subscribed to channel ${this.id}`);
+        return this.subscribers.has(player.clientID);
+    }
+    getSubscribers() {
+        return Array.from(this.subscribers.values()).map((sub) => sub.player);
+    }
+    getSubscriberCount() {
+        return this.subscribers.size;
+    }
+    getSubscription(player) {
+        return this.subscribers.get(player.clientID);
+    }
+    clear() {
+        this.subscribers.clear();
+    }
+    get type() {
+        return this.metadata.type;
+    }
+    get isPersistent() {
+        return this.metadata.persistent ?? false;
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            metadata: this.metadata,
+            subscriberCount: this.subscribers.size,
+            subscribers: Array.from(this.subscribers.values()).map((sub) => ({
+                clientID: sub.player.clientID,
+                name: sub.player.name,
+                subscribedAt: sub.subscribedAt,
+            })),
+        };
+    }
+    debugLog(msg) {
+        loggers.api.debug(`ChannelService: ${msg}`);
+    }
+}

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

@@ -0,0 +1,6 @@
+export * from './player-persistence.contract';
+export * from './security/command-error-observer.contract';
+export * from './security/net-event-security-observer.contract';
+export * from '../types/principal.type';
+export * from './security/principal-provider.contract';
+export * from './security/security-handler.contract';

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

@@ -0,0 +1,8 @@
+// Security
+// Persistence
+export * from './player-persistence.contract';
+export * from './security/command-error-observer.contract';
+export * from './security/net-event-security-observer.contract';
+export * from '../types/principal.type';
+export * from './security/principal-provider.contract';
+export * from './security/security-handler.contract';

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

@@ -0,0 +1,84 @@
+import { Player } from '../entities';
+/**
+ * Configuration for player data persistence behavior.
+ */
+export interface PersistenceConfig {
+    /**
+     * Whether automatic saving is enabled.
+     * When true, player data will be saved periodically.
+     */
+    autoSaveEnabled: boolean;
+    /**
+     * Interval in milliseconds between auto-saves.
+     * @default 300000 (5 minutes)
+     */
+    autoSaveIntervalMs: number;
+}
+/**
+ * Default persistence configuration values.
+ */
+export declare const DEFAULT_PERSISTENCE_CONFIG: PersistenceConfig;
+/**
+ * Player Persistence Contract
+ *
+ * Abstract base class for implementing player data persistence.
+ * Implement this contract to define how player data is loaded, saved,
+ * and automatically persisted during their session.
+ *
+ * @example
+ * ```typescript
+ * import { PlayerPersistenceContract, PersistenceConfig } from '@open-core/framework/server'
+ *
+ * class MyPersistenceProvider extends PlayerPersistenceContract {
+ *   readonly config: PersistenceConfig = {
+ *     autoSaveEnabled: true,
+ *     autoSaveIntervalMs: 300000, // 5 minutes
+ *   }
+ *
+ *   async onSessionLoad(player: Player): Promise<void> {
+    // 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)
+  }
+ * }
+ * ```
+ */
+export declare abstract class PlayerPersistenceContract {
+    /**
+     * Persistence configuration for this provider.
+     */
+    abstract readonly config: PersistenceConfig;
+    /**
+     * Called when a player session is created (after playerJoining).
+     * Load saved data from persistent storage and attach to the player.
+     *
+     * @param player - The player whose data should be loaded
+     */
+    abstract onSessionLoad(player: Player): Promise<void>;
+    /**
+     * Called when a player disconnects (before session destroy).
+     * Save player data to persistent storage.
+     *
+     * @param player - The player whose data should be saved
+     */
+    abstract onSessionSave(player: Player): Promise<void>;
+    /**
+     * Called periodically if autoSave is enabled.
+     * Can implement lighter save logic or delegate to onSessionSave.
+     *
+     * @param player - The player whose data should be auto-saved
+     */
+    abstract onAutoSave(player: Player): Promise<void>;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Default persistence configuration values.
+ */
+export const DEFAULT_PERSISTENCE_CONFIG = {
+    autoSaveEnabled: true,
+    autoSaveIntervalMs: 300000, // 5 minutes
+};
+/**
+ * Player Persistence Contract
+ *
+ * Abstract base class for implementing player data persistence.
+ * Implement this contract to define how player data is loaded, saved,
+ * and automatically persisted during their session.
+ *
+ * @example
+ * ```typescript
+ * import { PlayerPersistenceContract, PersistenceConfig } from '@open-core/framework/server'
+ *
+ * class MyPersistenceProvider extends PlayerPersistenceContract {
+ *   readonly config: PersistenceConfig = {
+ *     autoSaveEnabled: true,
+ *     autoSaveIntervalMs: 300000, // 5 minutes
+ *   }
+ *
+ *   async onSessionLoad(player: Player): Promise<void> {
+    // 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)
+  }
+ * }
+ * ```
+ */
+export class PlayerPersistenceContract {
+}