@open-core/framework 1.0.6 → 1.0.8

package/README.md

@@ -227,34 +227,37 @@ Note: `pnpm test` does not run benchmarks.
 
 ## Benchmarks
 
-There are two benchmark suites:
-
-- Core benchmarks (Tinybench)
-- Load benchmarks (Vitest project `benchmark`)
+Benchmarks are split by value, so the default run focuses on framework features that matter for real servers.
 
 ```bash
-pnpm bench:core
+pnpm bench
+pnpm bench:value
+pnpm bench:gold
+pnpm bench:startup
+pnpm bench:diagnostic
+pnpm bench:soak
 pnpm bench:load
 pnpm bench:all
 ```
 
+- `bench` / `bench:value`: value-focused suite. Commands, net events, RPC, lifecycle, ticks, binary path, bootstrap.
+- `bench:gold`: hot-path load scenarios only.
+- `bench:startup`: startup and registration cost.
+- `bench:diagnostic`: internal and low-level synthetic benchmarks.
+- `bench:soak`: long-running stress scenario.
+
 ### Snapshot (latest local run)
 
-These values are a small extract from the latest local run (`1.0.0-beta.1`, Feb 26, 2026). Results vary by machine.
-
-- **Core**
-  - BinaryService - classify response type: `~18.25M ops/sec` (mean `~0.055μs`, p95 `~0.076μs`)
-  - EventInterceptor - getStatistics (1000 events): `~17.78M ops/sec` (mean `~0.056μs`)
-  - RuntimeConfig - resolve CORE mode: `~10.49M ops/sec` (mean `~0.095μs`)
-  - Decorators - define metadata (Command): `~6.92M ops/sec` (mean `~0.145μs`)
-  - EventBus - multiple event types: `~2.57M ops/sec` (mean `~0.390μs`)
-  - DI - resolve simple service: `~1.78M ops/sec` (mean `~0.560μs`)
-- **Load**
-  - Commands - 500 players (validated): `~4.78M ops/sec` (p95 `~0.008ms`)
-  - Pipeline - validated (500 players): `~4.79M ops/sec` (p95 `~0.024ms`)
-  - Pipeline - full (500 players): `~2.34M ops/sec` (p95 `~0.011ms`)
-  - RPC - schema generation complex (500 methods): `~705K ops/sec` (p95 `~0.335ms`)
-  - Commands - 500 players (concurrent): `~6.31K ops/sec` (p95 `~76.00ms`)
+Use `benchmark/reports/` as the source of truth. Results vary by machine and should be compared relatively, not treated as product guarantees.
+
+- Primary benchmark targets:
+  - full command execution
+  - full net event handling
+  - RPC processing
+  - player lifecycle churn
+  - tick budget impact
+  - bootstrap cost
+  - binary transport cost
 
 Full reports and methodology are available in benchmark/README.md.
 

package/dist/adapters/node/transport/node.events.d.ts

@@ -3,12 +3,14 @@ import { RuntimeContext } from '../../contracts/transport/context';
 type NodeTarget = number | number[] | 'all';
 export declare class NodeEvents extends EventsAPI<RuntimeContext> {
     private readonly emitter;
+    private readonly asyncHandlers;
     on<TArgs extends readonly unknown[]>(event: string, handler: (ctx: {
         clientId?: number;
         raw?: unknown;
     }, ...args: TArgs) => unknown): void;
     emit(event: string, targetOrArg?: NodeTarget | unknown, ...args: unknown[]): void;
     simulateClientEvent(event: string, clientId: number, ...args: unknown[]): void;
+    simulateClientEventAsync(event: string, clientId: number, ...args: unknown[]): Promise<void>;
     clearHandlers(): void;
 }
 export {};

package/dist/adapters/node/transport/node.events.js

@@ -3,7 +3,14 @@ import { EventsAPI } from '../../contracts/transport/events.api';
 import { loggers } from '../../../kernel/logger';
 export class NodeEvents extends EventsAPI {
     emitter = new EventEmitter();
+    asyncHandlers = new Map();
     on(event, handler) {
+        let handlers = this.asyncHandlers.get(event);
+        if (!handlers) {
+            handlers = new Set();
+            this.asyncHandlers.set(event, handlers);
+        }
+        handlers.add(handler);
         this.emitter.on(event, (ctx, ...args) => {
             void Promise.resolve(handler(ctx, ...args)).catch((err) => {
                 loggers.netEvent.error(`handler error for '${event}'`, {}, err);
@@ -32,7 +39,16 @@ export class NodeEvents extends EventsAPI {
     simulateClientEvent(event, clientId, ...args) {
         this.emitter.emit(event, { clientId, raw: clientId }, ...args);
     }
+    async simulateClientEventAsync(event, clientId, ...args) {
+        const handlers = this.asyncHandlers.get(event);
+        if (!handlers || handlers.size === 0) {
+            return;
+        }
+        const ctx = { clientId, raw: clientId };
+        await Promise.allSettled(Array.from(handlers, (handler) => Promise.resolve(handler(ctx, ...args))));
+    }
     clearHandlers() {
         this.emitter.removeAllListeners();
+        this.asyncHandlers.clear();
     }
 }

package/dist/runtime/server/bootstrap.js

@@ -5,11 +5,14 @@ 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 { configureFrameworkEventBridge } from './bus/internal-event.bus';
 import { PrincipalProviderContract } from './contracts/index';
 import { getServerBinaryServiceRegistry } from './decorators/binaryService';
 import { getServerControllerRegistry } from './decorators/controller';
+import { Players } from './ports/players.api-port';
 import { getFrameworkModeScope, setRuntimeContext, validateRuntimeOptions, } from './runtime';
 import { BinaryProcessManager } from './system/managers/binary-process.manager';
+import { PlayerPersistenceService } from './services/persistence.service';
 import { SessionRecoveryService } from './services/session-recovery.local';
 import { registerServicesServer } from './services/services.register';
 import { SYSTEM_EVENTS } from '../shared/types/system-types';
@@ -115,6 +118,13 @@ export async function initServer(options, plugins) {
     // 1. Register Core Services (WorldContext, PlayerService, etc.)
     registerServicesServer(ctx);
     loggers.bootstrap.debug('Core services registered');
+    configureFrameworkEventBridge({
+        mode: ctx.mode,
+        engineEvents: GLOBAL_CONTAINER.resolve(IEngineEvents),
+        players: GLOBAL_CONTAINER.isRegistered(Players)
+            ? GLOBAL_CONTAINER.resolve(Players)
+            : undefined,
+    });
     // 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.
@@ -131,6 +141,9 @@ export async function initServer(options, plugins) {
     registerSystemServer(ctx);
     loggers.bootstrap.debug('System processors registered');
     checkProviders(ctx);
+    if (ctx.features.sessionLifecycle.enabled && ctx.mode !== 'RESOURCE') {
+        GLOBAL_CONTAINER.resolve(PlayerPersistenceService).initialize();
+    }
     const scanner = GLOBAL_CONTAINER.resolve(MetadataScanner);
     scanner.scan(getServerControllerRegistry());
     const binaryServices = getServerBinaryServiceRegistry();

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

@@ -1,6 +1,15 @@
-import { FrameworkEventsMap } from '../types/framework-events.types';
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { type FrameworkMode } from '../runtime';
+import { Players } from '../ports/players.api-port';
+import { type FrameworkEventsMap } from '../types/framework-events.types';
 type InternalEventName = keyof FrameworkEventsMap;
 type InternalEventHandler<E extends InternalEventName> = (payload: FrameworkEventsMap[E]) => void;
+interface FrameworkEventBridgeConfig {
+    mode: FrameworkMode;
+    engineEvents?: IEngineEvents;
+    players?: Players;
+}
 export declare function onFrameworkEvent<E extends InternalEventName>(event: E, handler: InternalEventHandler<E>): () => void;
+export declare function configureFrameworkEventBridge(config: FrameworkEventBridgeConfig): void;
 export declare function emitFrameworkEvent<E extends InternalEventName>(event: E, payload: FrameworkEventsMap[E]): void;
 export {};

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

@@ -1,5 +1,10 @@
 import { loggers } from '../../../kernel/logger';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 const handlers = {};
+const bridgeListenerRegistrations = new WeakSet();
+let bridgeConfig = {
+    mode: 'STANDALONE',
+};
 export function onFrameworkEvent(event, handler) {
     let list = handlers[event];
     if (!list) {
@@ -13,7 +18,32 @@ export function onFrameworkEvent(event, handler) {
             list.splice(index, 1);
     };
 }
+export function configureFrameworkEventBridge(config) {
+    bridgeConfig = config;
+    if (config.mode !== 'RESOURCE' || !config.engineEvents)
+        return;
+    if (bridgeListenerRegistrations.has(config.engineEvents))
+        return;
+    config.engineEvents.on(SYSTEM_EVENTS.framework.dispatch, (envelope) => {
+        if (bridgeConfig.mode !== 'RESOURCE')
+            return;
+        dispatchTransportFrameworkEvent(envelope.event, envelope.payload);
+    });
+    bridgeListenerRegistrations.add(config.engineEvents);
+}
 export function emitFrameworkEvent(event, payload) {
+    dispatchLocalFrameworkEvent(event, payload);
+    if (bridgeConfig.mode !== 'CORE' || !bridgeConfig.engineEvents)
+        return;
+    const transportPayload = serializeFrameworkEvent(event, payload);
+    if (!transportPayload)
+        return;
+    bridgeConfig.engineEvents.emit(SYSTEM_EVENTS.framework.dispatch, {
+        event,
+        payload: transportPayload,
+    });
+}
+function dispatchLocalFrameworkEvent(event, payload) {
     const list = handlers[event];
     if (!list)
         return;
@@ -28,3 +58,68 @@ export function emitFrameworkEvent(event, payload) {
         }
     }
 }
+function dispatchTransportFrameworkEvent(event, payload) {
+    const hydrated = hydrateFrameworkEvent(event, payload);
+    if (!hydrated)
+        return;
+    dispatchLocalFrameworkEvent(event, hydrated);
+}
+function serializeFrameworkEvent(event, payload) {
+    switch (event) {
+        case 'internal:playerSessionCreated':
+        case 'internal:playerSessionDestroyed':
+            return payload;
+        case 'internal:playerFullyConnected': {
+            const fullyConnectedPayload = payload;
+            return {
+                clientId: fullyConnectedPayload.player.clientID,
+            };
+        }
+        case 'internal:playerSessionRecovered': {
+            const recoveredPayload = payload;
+            return {
+                clientId: recoveredPayload.clientId,
+                license: recoveredPayload.license,
+            };
+        }
+        default:
+            return null;
+    }
+}
+function hydrateFrameworkEvent(event, payload) {
+    switch (event) {
+        case 'internal:playerSessionCreated':
+        case 'internal:playerSessionDestroyed':
+            return payload;
+        case 'internal:playerFullyConnected': {
+            const fullyConnectedPayload = payload;
+            const player = bridgeConfig.players?.getByClient(fullyConnectedPayload.clientId);
+            if (!player) {
+                loggers.eventBus.warn('Skipping framework event: player not found during hydration', {
+                    event,
+                    clientId: fullyConnectedPayload.clientId,
+                });
+                return null;
+            }
+            return { player };
+        }
+        case 'internal:playerSessionRecovered': {
+            const recoveredPayload = payload;
+            const player = bridgeConfig.players?.getByClient(recoveredPayload.clientId);
+            if (!player) {
+                loggers.eventBus.warn('Skipping framework event: player not found during hydration', {
+                    event,
+                    clientId: recoveredPayload.clientId,
+                });
+                return null;
+            }
+            return {
+                clientId: recoveredPayload.clientId,
+                license: recoveredPayload.license,
+                player,
+            };
+        }
+        default:
+            return null;
+    }
+}

package/dist/runtime/server/decorators/onFrameworkEvent.d.ts

@@ -6,7 +6,23 @@ import { FrameworkEventsMap } from '../types/framework-events.types';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ * The handler receives the framework payload associated with the selected event from
+ * {@link FrameworkEventsMap}. Unlike {@link OnRuntimeEvent}, this payload is framework-defined
+ * and may include hydrated entities such as {@link Player}.
+ *
+ * Framework events are delivered:
+ * - locally in `STANDALONE`
+ * - locally inside `CORE`
+ * - from `CORE` to `RESOURCE` through the internal framework bridge
+ *
+ * For bridged events, the transport payload is serialized in `CORE` and then rehydrated in the
+ * receiving `RESOURCE`. That means handlers can keep using the same payload shape in every mode.
+ *
+ * Current built-in payloads:
+ * - `internal:playerSessionCreated`: `{ clientId, license }`
+ * - `internal:playerSessionDestroyed`: `{ clientId }`
+ * - `internal:playerFullyConnected`: `{ player }`
+ * - `internal:playerSessionRecovered`: `{ clientId, license, player }`
  *
  * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
  *
@@ -16,7 +32,7 @@ import { FrameworkEventsMap } from '../types/framework-events.types';
  * export class SystemController {
  *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
  *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
- *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *     console.log(`Player ${payload.player.clientID} connected`)
  *   }
  * }
  * ```

package/dist/runtime/server/decorators/onFrameworkEvent.js

@@ -6,7 +6,23 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ * The handler receives the framework payload associated with the selected event from
+ * {@link FrameworkEventsMap}. Unlike {@link OnRuntimeEvent}, this payload is framework-defined
+ * and may include hydrated entities such as {@link Player}.
+ *
+ * Framework events are delivered:
+ * - locally in `STANDALONE`
+ * - locally inside `CORE`
+ * - from `CORE` to `RESOURCE` through the internal framework bridge
+ *
+ * For bridged events, the transport payload is serialized in `CORE` and then rehydrated in the
+ * receiving `RESOURCE`. That means handlers can keep using the same payload shape in every mode.
+ *
+ * Current built-in payloads:
+ * - `internal:playerSessionCreated`: `{ clientId, license }`
+ * - `internal:playerSessionDestroyed`: `{ clientId }`
+ * - `internal:playerFullyConnected`: `{ player }`
+ * - `internal:playerSessionRecovered`: `{ clientId, license, player }`
  *
  * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
  *
@@ -16,7 +32,7 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * export class SystemController {
  *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
  *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
- *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *     console.log(`Player ${payload.player.clientID} connected`)
  *   }
  * }
  * ```

package/dist/runtime/server/decorators/onRuntimeEvent.d.ts

@@ -7,6 +7,19 @@ import type { RuntimeEventName } from '../../../adapters/contracts/runtime';
  * This decorator only stores metadata. During bootstrap, the framework scans controller
  * methods and binds handlers to runtime events.
  *
+ * The decorated method receives the raw runtime arguments emitted by the adapter for
+ * the selected event. OpenCore does not wrap these arguments into an object payload and
+ * does not automatically resolve a {@link Player} entity for you.
+ *
+ * Common server event signatures in the current runtime map:
+ * - `playerJoining`: `(clientId: number, identifiers?: Record<string, string>)`
+ * - `playerDropped`: `(clientId: number)`
+ * - `onServerResourceStop`: `(resourceName: string)`
+ * - `playerCommand`: runtime-specific raw arguments from the adapter
+ *
+ * If you need a framework-managed payload such as `{ player }`, use
+ * {@link OnFrameworkEvent} instead.
+ *
  * CitizenFX server event reference:
  * https://docs.fivem.net/docs/scripting-reference/events/server-events/
  *
@@ -17,8 +30,8 @@ import type { RuntimeEventName } from '../../../adapters/contracts/runtime';
  * @Server.Controller()
  * export class SessionController {
  *   @Server.OnRuntimeEvent('playerJoining')
- *   onPlayerJoining() {
- *     // ...
+ *   onPlayerJoining(clientId: number, identifiers?: Record<string, string>) {
+ *     // Raw runtime arguments
  *   }
  * }
  * ```

package/dist/runtime/server/decorators/onRuntimeEvent.js

@@ -7,6 +7,19 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * This decorator only stores metadata. During bootstrap, the framework scans controller
  * methods and binds handlers to runtime events.
  *
+ * The decorated method receives the raw runtime arguments emitted by the adapter for
+ * the selected event. OpenCore does not wrap these arguments into an object payload and
+ * does not automatically resolve a {@link Player} entity for you.
+ *
+ * Common server event signatures in the current runtime map:
+ * - `playerJoining`: `(clientId: number, identifiers?: Record<string, string>)`
+ * - `playerDropped`: `(clientId: number)`
+ * - `onServerResourceStop`: `(resourceName: string)`
+ * - `playerCommand`: runtime-specific raw arguments from the adapter
+ *
+ * If you need a framework-managed payload such as `{ player }`, use
+ * {@link OnFrameworkEvent} instead.
+ *
  * CitizenFX server event reference:
  * https://docs.fivem.net/docs/scripting-reference/events/server-events/
  *
@@ -17,8 +30,8 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * @Server.Controller()
  * export class SessionController {
  *   @Server.OnRuntimeEvent('playerJoining')
- *   onPlayerJoining() {
- *     // ...
+ *   onPlayerJoining(clientId: number, identifiers?: Record<string, string>) {
+ *     // Raw runtime arguments
  *   }
  * }
  * ```

package/dist/runtime/server/implementations/local/player.local.d.ts

@@ -24,13 +24,13 @@ export declare class LocalPlayerImplementation implements Players, PlayerSession
     private readonly world;
     private readonly playerInfo;
     private readonly playerServer;
-    private readonly playerLifecycle;
-    private readonly playerStateSync;
-    private readonly entityServer;
-    private readonly events;
-    private readonly platformContext;
+    private readonly playerLifecycle?;
+    private readonly playerStateSync?;
+    private readonly entityServer?;
+    private readonly events?;
+    private readonly platformContext?;
     private readonly playerAdapters;
-    constructor(world: WorldContext, playerInfo: IPlayerInfo, playerServer: IPlayerServer, playerLifecycle: IPlayerLifecycleServer, playerStateSync: IPlayerStateSyncServer, entityServer: IEntityServer, events: EventsAPI<'server'>, platformContext: IPlatformContext);
+    constructor(world: WorldContext, playerInfo: IPlayerInfo, playerServer: IPlayerServer, playerLifecycle?: IPlayerLifecycleServer | undefined, playerStateSync?: IPlayerStateSyncServer | undefined, entityServer?: IEntityServer | undefined, events?: EventsAPI<"server"> | undefined, platformContext?: IPlatformContext | undefined);
     private isPlayer;
     /**
      * Initializes a new player session for a connecting client.

package/dist/runtime/server/implementations/local/player.local.js

@@ -21,6 +21,37 @@ import { IPlayerServer } from '../../../../adapters/contracts/server/IPlayerServ
 import { loggers } from '../../../../kernel/logger';
 import { WorldContext } from '../../../core/world';
 import { createLocalServerPlayer } from '../../adapter/registry';
+class NoopPlayerLifecycleServer extends IPlayerLifecycleServer {
+    spawn() { }
+    teleport() { }
+    respawn() { }
+}
+class NoopPlayerStateSyncServer extends IPlayerStateSyncServer {
+    getHealth() {
+        return 200;
+    }
+    setHealth() { }
+    getArmor() {
+        return 0;
+    }
+    setArmor() { }
+}
+const DEFAULT_PLATFORM_CONTEXT = {
+    platformName: 'node',
+    displayName: 'Node.js',
+    identifierTypes: ['license'],
+    maxPlayers: undefined,
+    gameProfile: 'common',
+    defaultSpawnModel: 'mp_m_freemode_01',
+    defaultVehicleType: 'automobile',
+    enableServerVehicleCreation: true,
+};
+function isEntityServer(value) {
+    return (!!value && typeof value === 'object' && typeof value.getCoords === 'function');
+}
+function isEventsAPI(value) {
+    return (!!value && typeof value === 'object' && typeof value.on === 'function');
+}
 /**
  * Service responsible for managing the lifecycle of player sessions.
  * It acts as the central registry for all connected players, mapping FiveM client IDs
@@ -49,14 +80,54 @@ let LocalPlayerImplementation = class LocalPlayerImplementation {
         this.entityServer = entityServer;
         this.events = events;
         this.platformContext = platformContext;
-        const defaultSpawnModel = this.platformContext.defaultSpawnModel;
+        let resolvedPlayerLifecycle = this.playerLifecycle;
+        let resolvedPlayerStateSync = this.playerStateSync;
+        let resolvedEntityServer = this.entityServer;
+        let resolvedEvents = this.events;
+        // Backward compatibility for tests/benchmarks still using the old 5-arg constructor.
+        if (!resolvedEntityServer &&
+            isEntityServer(resolvedPlayerLifecycle) &&
+            isEventsAPI(resolvedPlayerStateSync)) {
+            resolvedEntityServer = resolvedPlayerLifecycle;
+            resolvedEvents = resolvedPlayerStateSync;
+            resolvedPlayerLifecycle = new NoopPlayerLifecycleServer();
+            resolvedPlayerStateSync = new NoopPlayerStateSyncServer();
+        }
+        resolvedPlayerLifecycle ??= new NoopPlayerLifecycleServer();
+        resolvedPlayerStateSync ??= new NoopPlayerStateSyncServer();
+        resolvedEntityServer ??= {
+            doesExist: () => true,
+            getCoords: () => ({ x: 0, y: 0, z: 0 }),
+            setCoords: () => { },
+            setPosition: () => { },
+            getHeading: () => 0,
+            setHeading: () => { },
+            getModel: () => 0,
+            delete: () => { },
+            setOrphanMode: () => { },
+            setDimension: () => { },
+            getDimension: () => 0,
+            getStateBag: () => ({
+                set: () => undefined,
+                get: () => undefined,
+            }),
+            getHealth: () => 200,
+            setHealth: () => { },
+            getArmor: () => 0,
+            setArmor: () => { },
+        };
+        resolvedEvents ??= {
+            on: () => { },
+            emit: () => { },
+        };
+        const defaultSpawnModel = (this.platformContext ?? DEFAULT_PLATFORM_CONTEXT).defaultSpawnModel;
         this.playerAdapters = {
             playerInfo: this.playerInfo,
             playerServer: this.playerServer,
-            playerLifecycle: this.playerLifecycle,
-            playerStateSync: this.playerStateSync,
-            entityServer: this.entityServer,
-            events: this.events,
+            playerLifecycle: resolvedPlayerLifecycle,
+            playerStateSync: resolvedPlayerStateSync,
+            entityServer: resolvedEntityServer,
+            events: resolvedEvents,
             defaultSpawnModel,
         };
     }

package/dist/runtime/server/types/framework-events.types.d.ts

@@ -1,19 +1,65 @@
 import { Player } from '../entities';
+/**
+ * Emitted when a player session is created in the framework session lifecycle.
+ */
 export interface PlayerSessionCreatedPayload {
     clientId: number;
     license: string | undefined;
 }
+/**
+ * Emitted when a player session is destroyed in the framework session lifecycle.
+ */
 export interface PlayerSessionDestroyedPayload {
     clientId: number;
 }
+/**
+ * Emitted when the framework considers the player fully connected and the runtime-specific
+ * {@link Player} entity can be consumed safely by application code.
+ */
 export interface PlayerFullyConnectedPayload {
     player: Player;
 }
+/**
+ * Emitted when the framework recreates a player session after resource restart recovery.
+ */
 export interface PlayerSessionRecoveredPayload {
     clientId: number;
     player: Player;
     license: string | undefined;
 }
+/**
+ * Serialized transport payload for `internal:playerFullyConnected` used across `CORE -> RESOURCE`.
+ */
+export interface PlayerFullyConnectedTransportPayload {
+    clientId: number;
+}
+/**
+ * Serialized transport payload for `internal:playerSessionRecovered` used across `CORE -> RESOURCE`.
+ */
+export interface PlayerSessionRecoveredTransportPayload {
+    clientId: number;
+    license: string | undefined;
+}
+/**
+ * Internal transport contract used by the framework bridge when delivering framework events
+ * between different server runtimes.
+ */
+export type FrameworkTransportEventsMap = {
+    'internal:playerSessionCreated': PlayerSessionCreatedPayload;
+    'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;
+    'internal:playerFullyConnected': PlayerFullyConnectedTransportPayload;
+    'internal:playerSessionRecovered': PlayerSessionRecoveredTransportPayload;
+};
+/**
+ * Envelope emitted through the internal framework bridge.
+ */
+export interface FrameworkEventEnvelope<E extends keyof FrameworkTransportEventsMap> {
+    event: E;
+    payload: FrameworkTransportEventsMap[E];
+}
+/**
+ * Public payload map consumed by {@link OnFrameworkEvent} and `onFrameworkEvent(...)`.
+ */
 export type FrameworkEventsMap = {
     'internal:playerSessionCreated': PlayerSessionCreatedPayload;
     'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;

package/dist/runtime/shared/types/system-types.d.ts

@@ -16,6 +16,9 @@ export declare const SYSTEM_EVENTS: {
     readonly command: {
         readonly execute: `opencore:${string}:${string}`;
     };
+    readonly framework: {
+        readonly dispatch: `opencore:${string}:${string}`;
+    };
     readonly spawner: {
         readonly spawn: `opencore:${string}:${string}`;
         readonly teleport: `opencore:${string}:${string}`;

package/dist/runtime/shared/types/system-types.js

@@ -17,6 +17,9 @@ export const SYSTEM_EVENTS = {
     command: {
         execute: systemEvent('command', 'execute'),
     },
+    framework: {
+        dispatch: systemEvent('framework', 'dispatch'),
+    },
     spawner: {
         spawn: systemEvent('spawner', 'spawn'),
         teleport: systemEvent('spawner', 'teleport'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Secure, event-driven TypeScript Framework & Runtime engine for CitizenFX (Cfx).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,9 +72,14 @@
     "test:unit": "npx vitest run --project unit",
     "test:integration": "npx vitest run --project integration",
     "test:coverage": "npx vitest run --coverage",
-    "bench": "npx tsx benchmark/index.ts",
-    "bench:core": "npx tsx benchmark/index.ts --core",
-    "bench:load": "npx vitest run --project benchmark",
+    "bench": "npx tsx benchmark/index.ts --value",
+    "bench:value": "npx tsx benchmark/index.ts --value",
+    "bench:gold": "BENCHMARK_SUITE=gold npx vitest run --project benchmark-gold",
+    "bench:startup": "npx tsx benchmark/index.ts --startup",
+    "bench:diagnostic": "npx tsx benchmark/index.ts --diagnostic",
+    "bench:soak": "BENCHMARK_SUITE=soak npx vitest run --project benchmark-soak",
+    "bench:core": "npx tsx benchmark/index.ts --diagnostic",
+    "bench:load": "npx vitest run --project benchmark-gold --project benchmark-startup",
     "bench:all": "npx tsx benchmark/index.ts --all",
     "validate": "pnpm check && pnpm typecheck && pnpm test",
     "lint-staged": "lint-staged",