@dcl/sdk 7.29.1-36863326504.commit-aa54c50 → 7.30.0

package/src/network/server/index.ts

@@ -1,341 +0,0 @@
-import {
-  IEngine,
-  Entity,
-  CrdtMessageType,
-  CrdtMessageBody,
-  ProcessMessageResultType,
-  ComponentType,
-  PutNetworkComponentOperation
-} from '@dcl/ecs'
-import * as components from '@dcl/ecs/dist/components'
-import { ReadWriteByteBuffer } from '@dcl/ecs/dist/serialization/ByteBuffer'
-import { CommsMessage } from '../binary-message-bus'
-import { chunkCrdtMessages } from '../chunking'
-import * as utils from './utils'
-import { AUTH_SERVER_PEER_ID, DEBUG_NETWORK_MESSAGES } from '../message-bus-sync'
-import { type BinaryMessageBus } from '../binary-message-bus'
-import {
-  LastWriteWinElementSetComponentDefinition,
-  GrowOnlyValueSetComponentDefinition,
-  ComponentDefinition,
-  InternalBaseComponent
-} from '@dcl/ecs/dist/engine/component'
-
-export const LIVEKIT_MAX_SIZE = 12
-
-export interface ServerValidationConfig {
-  engine: IEngine
-  binaryMessageBus: ReturnType<typeof BinaryMessageBus>
-}
-
-export function createServerValidator(config: ServerValidationConfig) {
-  const { engine, binaryMessageBus } = config
-
-  // Initialize components for network operations and transform fixing
-  const NetworkEntity = components.NetworkEntity(engine)
-  const CreatedBy = components.CreatedBy(engine)
-  const NetworkParent = components.NetworkParent(engine)
-
-  // Type guard to check if component supports corrections (both LWW and GrowOnlySet)
-  function supportsCorrections<T>(
-    component: ComponentDefinition<T>
-  ): component is LastWriteWinElementSetComponentDefinition<T> | GrowOnlyValueSetComponentDefinition<T> {
-    return (
-      (component.componentType === ComponentType.LastWriteWinElementSet ||
-        component.componentType === ComponentType.GrowOnlyValueSet) &&
-      'getCrdtState' in component
-    )
-  }
-
-  function findExistingNetworkEntity(message: utils.NetworkMessage): Entity | null {
-    // Look for existing network entity mapping (don't create new ones)
-    for (const [entityId, networkData] of engine.getEntitiesWith(NetworkEntity)) {
-      if (networkData.networkId === message.networkId && networkData.entityId === message.entityId) {
-        return entityId
-      }
-    }
-    // Return null if not found
-    return null
-  }
-
-  /**
-   * What a message can be judged on before an entity is spent mapping it. Anything
-   * needing the local entity — the CRDT dry run, the scene's own validator — still
-   * happens in validateMessagePermissions afterwards.
-   */
-  function peerMessageIsEligible(message: utils.NetworkMessage): boolean {
-    if (!('componentId' in message)) return true
-
-    const definition = engine.getComponentOrNull(message.componentId)
-    if (!definition) return false
-
-    if ('data' in message) {
-      try {
-        definition.schema.deserialize(new ReadWriteByteBuffer(message.data))
-      } catch {
-        return false
-      }
-    }
-
-    return true
-  }
-
-  function findOrCreateNetworkEntity(message: utils.NetworkMessage, sender: string, isServer: boolean): Entity {
-    // Look for existing network entity mapping first
-    const existingEntity = findExistingNetworkEntity(message)
-
-    if (existingEntity) {
-      return existingEntity
-    }
-
-    // Create new entity and network mapping
-    const newEntityId = engine.addEntity()
-    NetworkEntity.createOrReplace(newEntityId, {
-      networkId: message.networkId,
-      entityId: message.entityId
-    })
-
-    if (isServer) {
-      CreatedBy.createOrReplace(newEntityId, { address: sender })
-    }
-
-    DEBUG_NETWORK_MESSAGES() &&
-      console.log(`[DEBUG] Created new entity ${newEntityId} for network ${message.networkId}:${message.entityId}`)
-    return newEntityId
-  }
-
-  function convertNetworkToRegularMessage(
-    networkMessage: utils.NetworkMessage,
-    localEntityId: Entity,
-    forceCorrections = false
-  ): (CrdtMessageBody & { messageBuffer: Uint8Array }) | null {
-    const buffer = new ReadWriteByteBuffer()
-
-    try {
-      // Use the well-tested networkMessageToLocal utility with transform fixing for Unity
-      const message = utils.networkMessageToLocal(
-        networkMessage,
-        localEntityId,
-        buffer,
-        NetworkParent,
-        forceCorrections
-      )
-      return { ...message, messageBuffer: buffer.toBinary() }
-    } catch (error) {
-      DEBUG_NETWORK_MESSAGES() && console.error('Error converting network message:', error)
-      return null
-    }
-  }
-
-  function validateMessagePermissions(message: utils.RegularMessage, sender: string, _localEntityId: Entity): boolean {
-    // Basic checks
-    if (!sender || sender === AUTH_SERVER_PEER_ID) {
-      return false // Server shouldn't send messages to itself
-    }
-
-    if (message.type === CrdtMessageType.DELETE_ENTITY) {
-      // TODO: how to handle this case ?
-    }
-
-    if (message.type === CrdtMessageType.PUT_COMPONENT || message.type === CrdtMessageType.DELETE_COMPONENT) {
-      const component = engine.getComponentOrNull(message.componentId) as InternalBaseComponent<unknown> | null
-      if (!component) return false
-
-      let value: unknown = null
-      if ('data' in message) {
-        try {
-          value = component.schema.deserialize(new ReadWriteByteBuffer(message.data))
-        } catch {
-          return false
-        }
-      }
-
-      const dryRunCRDT = component.__dry_run_updateFromCrdt(message)
-      const validCRDT = [
-        ProcessMessageResultType.StateUpdatedData,
-        ProcessMessageResultType.StateUpdatedTimestamp,
-        ProcessMessageResultType.EntityDeleted
-      ].includes(dryRunCRDT)
-      const createdBy = CreatedBy.getOrNull(message.entityId)
-      const validMessage =
-        validCRDT &&
-        component.__run_validateBeforeChange(message.entityId, value, sender, createdBy?.address ?? AUTH_SERVER_PEER_ID)
-
-      return !!validMessage
-    }
-
-    // For now, basic validation - in the future this will check component sync permissions
-    // TODO: Check if sender owns the entity
-    // TODO: Check component sync mode ('all' | 'owner' | 'server')
-    // TODO: Run component custom validation
-    return true
-  }
-
-  function broadcastBatchedMessages(messages: utils.NetworkMessage[], excludeSender: string) {
-    if (messages.length === 0) return
-
-    // Build the complete buffer with all messages
-    const networkBuffer = new ReadWriteByteBuffer()
-    for (const message of messages) {
-      // Skip oversized messages upfront
-      if (message.messageBuffer.byteLength / 1024 > LIVEKIT_MAX_SIZE) {
-        console.error(
-          `Message too large (${message.messageBuffer.byteLength} bytes), skipping message from ${excludeSender}`
-        )
-        continue
-      }
-      networkBuffer.writeBuffer(message.messageBuffer, false)
-    }
-
-    // Use the chunking function to split into proper chunks
-    const chunks = chunkCrdtMessages(networkBuffer.toBinary(), LIVEKIT_MAX_SIZE)
-
-    for (const chunk of chunks) {
-      binaryMessageBus.emit(CommsMessage.CRDT, chunk)
-    }
-    DEBUG_NETWORK_MESSAGES() &&
-      console.log(`Total: ${messages.length} messages in ${chunks.length} chunks from ${excludeSender}`)
-  }
-
-  function sendCorrectionToSender(networkMessage: utils.NetworkMessage, sender: string, localEntityId: Entity) {
-    try {
-      // Only handle component messages (PUT/DELETE), not entity deletion
-      if (networkMessage.type === CrdtMessageType.DELETE_ENTITY_NETWORK) {
-        DEBUG_NETWORK_MESSAGES() && console.log('[AUTHORITATIVE] Cannot send authoritative message for entity deletion')
-        return
-      }
-
-      // Safe to access componentId and timestamp now
-      const component = engine.getComponent(networkMessage.componentId)
-
-      // Only proceed if component supports authoritative messages (LWW or GrowOnlySet)
-      if (!supportsCorrections(component)) {
-        DEBUG_NETWORK_MESSAGES() && console.log('[AUTHORITATIVE] Component does not support authoritative messages')
-        return
-      }
-
-      const serverCRDTState = component.getCrdtState(localEntityId)
-
-      if (serverCRDTState) {
-        // Create authoritative message using PUT_COMPONENT_NETWORK
-        // Each client will convert this to AUTHORITATIVE_PUT_COMPONENT with proper entity mapping
-        const correctionBuffer = new ReadWriteByteBuffer()
-        PutNetworkComponentOperation.write(
-          networkMessage.entityId, // Use original network entity ID
-          serverCRDTState.timestamp,
-          networkMessage.componentId,
-          networkMessage.networkId,
-          serverCRDTState.data,
-          correctionBuffer
-        )
-        // Send authoritative message directly to the sender
-        binaryMessageBus.emit(CommsMessage.CRDT_AUTHORITATIVE, correctionBuffer.toBinary(), [sender])
-
-        DEBUG_NETWORK_MESSAGES() &&
-          console.log(
-            `[AUTHORITATIVE] Sent authoritative message to ${sender} for entity ${localEntityId} component ${networkMessage.componentId} with timestamp ${networkMessage.timestamp}`
-          )
-      }
-    } catch (error) {
-      DEBUG_NETWORK_MESSAGES() && console.error('Error sending correction:', error)
-    }
-  }
-
-  return {
-    findExistingNetworkEntity,
-    // transform Network messages to CRDT Common Messages.
-    processClientMessages: function processClientMessages(value: Uint8Array, sender: string, forceCorrections = false) {
-      // console.log(`[CLIENT] Processing message from ${sender}, ${value.length} bytes`)
-
-      // Collect all regular messages in a single buffer for batched application
-      const combinedBuffer = new ReadWriteByteBuffer()
-
-      // Clients process network messages from server and convert them to regular messages
-      for (const message of utils.readMessages(value)) {
-        // Only process network messages in client message handler
-        if (utils.isNetworkMessage(message)) {
-          const networkMessage = message as utils.NetworkMessage
-
-          // Find or create network entity mapping
-          const localEntityId = findOrCreateNetworkEntity(networkMessage, sender, false)
-
-          // Convert network message to regular message or correction message
-          const regularMessage = convertNetworkToRegularMessage(networkMessage, localEntityId, forceCorrections)
-
-          if (regularMessage?.messageBuffer.byteLength) {
-            combinedBuffer.writeBuffer(regularMessage.messageBuffer, false)
-          }
-        }
-      }
-      return combinedBuffer.toBinary()
-    },
-    // Sever Code: process message, handle permissions, and broadcast if needed.
-    processServerMessages: function processServerMessages(value: Uint8Array, sender: string) {
-      // console.log(`[SERVER] Processing message from ${sender}, ${value.length} bytes`)
-
-      // Collect all valid messages for batched broadcasting
-      const messagesToBroadcast: utils.NetworkMessage[] = []
-      const regularMessagesBuffer = new ReadWriteByteBuffer()
-
-      for (const message of utils.readMessages(value)) {
-        try {
-          // Only process network messages in server message handler
-          if (utils.isNetworkMessage(message)) {
-            const networkMessage = message as utils.NetworkMessage
-
-            // 0. Refuse what is already unusable before an entity is spent on it. A peer
-            // sending unique (networkId, entityId) pairs it knows will be refused would
-            // otherwise drain the range one refusal at a time. A pair already mapped takes
-            // the normal path, so its sender still gets the correction it is owed.
-            if (findExistingNetworkEntity(networkMessage) === null && !peerMessageIsEligible(networkMessage)) {
-              continue
-            }
-
-            // 1. Find or create network entity mapping
-            const localEntityId = findOrCreateNetworkEntity(networkMessage, sender, true)
-
-            // 2. Convert network message to regular message and collect for local application
-            const regularMessage = convertNetworkToRegularMessage(networkMessage, localEntityId)
-
-            // 3. Basic permission validation.
-            if (!regularMessage || !validateMessagePermissions(regularMessage as any, sender, localEntityId)) {
-              // Send correction back to sender with server's authoritative state
-              sendCorrectionToSender(networkMessage, sender, localEntityId)
-              continue
-            }
-
-            // 4. Collect valid message for batched broadcasting
-            messagesToBroadcast.push(networkMessage)
-
-            if (regularMessage?.messageBuffer.byteLength) {
-              regularMessagesBuffer.writeBuffer(regularMessage.messageBuffer, false)
-            }
-          }
-        } catch (error) {
-          DEBUG_NETWORK_MESSAGES() && console.error('Error processing server message:', error)
-        }
-      }
-      // Batch broadcast all valid messages together
-      broadcastBatchedMessages(messagesToBroadcast, sender)
-      return regularMessagesBuffer.toBinary()
-    },
-    // engine changes that needs to be broadcasted.
-    convertRegularToNetworkMessage: function convertRegularToNetworkMessage(regularMessage: Uint8Array): Uint8Array[] {
-      const groupedBuffer = new ReadWriteByteBuffer()
-
-      // First pass: Convert all regular messages to network format and group them into one big buffer
-      for (const message of utils.readMessages(regularMessage)) {
-        // Only convert regular messages that have network data
-        const networkData = NetworkEntity.getOrNull(message.entityId)
-
-        if (networkData && !utils.isNetworkMessage(message)) {
-          utils.localMessageToNetwork(message, networkData, groupedBuffer)
-        }
-      }
-
-      // Second pass: Use the new chunking function that respects message boundaries
-      const totalData = groupedBuffer.toBinary()
-      return chunkCrdtMessages(totalData, LIVEKIT_MAX_SIZE)
-    }
-  }
-}

package/src/network/server/utils.ts

@@ -1,189 +0,0 @@
-import { Entity } from '@dcl/ecs/dist/engine'
-import { CrdtMessageProtocol, NetworkParent } from '@dcl/ecs'
-import { ReceiveMessage } from '@dcl/ecs/dist/runtime/types'
-import { ReceiveNetworkMessage } from '@dcl/ecs/dist/systems/crdt/types'
-import { ByteBuffer, ReadWriteByteBuffer } from '@dcl/ecs/dist/serialization/ByteBuffer'
-import { AuthoritativePutComponentOperation, PutComponentOperation } from '@dcl/ecs/dist/serialization/crdt'
-import {
-  CrdtMessage,
-  CrdtMessageBody,
-  CrdtMessageHeader,
-  CrdtMessageType,
-  DeleteComponentMessage,
-  DeleteComponentNetworkMessage,
-  DeleteEntityMessage,
-  DeleteEntityNetworkMessage,
-  PutComponentMessage,
-  AuthoritativePutComponentMessage,
-  PutNetworkComponentMessage
-} from '@dcl/ecs/dist/serialization/crdt/types'
-import { DeleteComponent } from '@dcl/ecs/dist/serialization/crdt/deleteComponent'
-import { DeleteEntity } from '@dcl/ecs/dist/serialization/crdt/deleteEntity'
-import { INetowrkEntityType } from '@dcl/ecs/dist/components/types'
-import { PutNetworkComponentOperation } from '@dcl/ecs/dist/serialization/crdt/network/putComponentNetwork'
-import { DeleteComponentNetwork } from '@dcl/ecs/dist/serialization/crdt/network/deleteComponentNetwork'
-import { DeleteEntityNetwork } from '@dcl/ecs/dist/serialization/crdt/network/deleteEntityNetwork'
-import { TransformSchema, COMPONENT_ID as TransformComponentId } from '@dcl/ecs/dist/components/manual/Transform'
-
-export type NetworkMessage = (
-  | PutNetworkComponentMessage
-  | DeleteComponentNetworkMessage
-  | DeleteEntityNetworkMessage
-) & { messageBuffer: Uint8Array }
-
-export type RegularMessage = (
-  | PutComponentMessage
-  | AuthoritativePutComponentMessage
-  | DeleteComponentMessage
-  | DeleteEntityMessage
-) & {
-  messageBuffer: Uint8Array
-}
-export function readMessages(data: Uint8Array): (NetworkMessage | RegularMessage)[] {
-  const buffer = new ReadWriteByteBuffer(data)
-  const messages: (NetworkMessage | RegularMessage)[] = []
-  let header: CrdtMessageHeader | null
-  while ((header = CrdtMessageProtocol.getHeader(buffer))) {
-    const offset = buffer.currentReadOffset()
-    let message: CrdtMessage | undefined = undefined
-
-    // Network messages
-    if (header.type === CrdtMessageType.DELETE_COMPONENT_NETWORK) {
-      message = DeleteComponentNetwork.read(buffer)!
-    } else if (header.type === CrdtMessageType.PUT_COMPONENT_NETWORK) {
-      message = PutNetworkComponentOperation.read(buffer)!
-    } else if (header.type === CrdtMessageType.DELETE_ENTITY_NETWORK) {
-      message = DeleteEntityNetwork.read(buffer)!
-    }
-    // Regular messages
-    else if (header.type === CrdtMessageType.PUT_COMPONENT) {
-      message = PutComponentOperation.read(buffer)!
-    } else if (header.type === CrdtMessageType.AUTHORITATIVE_PUT_COMPONENT) {
-      message = AuthoritativePutComponentOperation.read(buffer)!
-    } else if (header.type === CrdtMessageType.DELETE_COMPONENT) {
-      message = DeleteComponent.read(buffer)!
-    } else if (header.type === CrdtMessageType.DELETE_ENTITY) {
-      message = DeleteEntity.read(buffer)!
-    } else {
-      // consume unknown messages
-      buffer.incrementReadOffset(header.length)
-    }
-
-    if (message) {
-      messages.push({
-        ...message,
-        messageBuffer: buffer.buffer().subarray(offset, buffer.currentReadOffset())
-      })
-    }
-  }
-  return messages
-}
-
-export function isNetworkMessage(message: ReceiveMessage): message is ReceiveNetworkMessage {
-  return [
-    CrdtMessageType.DELETE_COMPONENT_NETWORK,
-    CrdtMessageType.DELETE_ENTITY_NETWORK,
-    CrdtMessageType.PUT_COMPONENT_NETWORK
-  ].includes(message.type)
-}
-
-export function networkMessageToLocal(
-  message: ReceiveNetworkMessage,
-  localEntityId: Entity,
-  destinationBuffer: ByteBuffer,
-  // Optional network parent component for transform fixing
-  networkParentComponent?: typeof NetworkParent,
-  // Force corrections - converts PUT_COMPONENT_NETWORK to authoritative_PUT_COMPONENT
-  forceCorrections = false
-): CrdtMessageBody {
-  if (message.type === CrdtMessageType.PUT_COMPONENT_NETWORK) {
-    let messageData = message.data
-
-    // Fix transform parent if needed for Unity/engine processing
-    if (message.componentId === TransformComponentId && networkParentComponent) {
-      const parentNetwork = networkParentComponent.getOrNull(localEntityId)
-      messageData = fixTransformParent(message, parentNetwork?.entityId)
-    }
-    if (forceCorrections) {
-      // Use AUTHORITATIVE_PUT_COMPONENT for forced state updates
-      AuthoritativePutComponentOperation.write(
-        localEntityId,
-        message.timestamp,
-        message.componentId,
-        messageData,
-        destinationBuffer
-      )
-      return {
-        type: CrdtMessageType.AUTHORITATIVE_PUT_COMPONENT,
-        componentId: message.componentId,
-        timestamp: message.timestamp,
-        data: messageData,
-        entityId: localEntityId
-      }
-    } else {
-      // Normal PUT_COMPONENT conversion
-      PutComponentOperation.write(localEntityId, message.timestamp, message.componentId, messageData, destinationBuffer)
-      return {
-        type: CrdtMessageType.PUT_COMPONENT,
-        componentId: message.componentId,
-        timestamp: message.timestamp,
-        data: messageData,
-        entityId: localEntityId
-      }
-    }
-  } else if (message.type === CrdtMessageType.DELETE_COMPONENT_NETWORK) {
-    DeleteComponent.write(localEntityId, message.componentId, message.timestamp, destinationBuffer)
-    return {
-      type: CrdtMessageType.DELETE_COMPONENT,
-      componentId: message.componentId,
-      timestamp: message.timestamp,
-      entityId: localEntityId
-    }
-  } else if (message.type === CrdtMessageType.DELETE_ENTITY_NETWORK) {
-    DeleteEntity.write(localEntityId, destinationBuffer)
-    return {
-      type: CrdtMessageType.DELETE_ENTITY,
-      entityId: localEntityId
-    }
-  }
-  throw 1
-}
-
-export function localMessageToNetwork(
-  message: ReceiveMessage,
-  network: INetowrkEntityType,
-  destinationBuffer: ByteBuffer
-) {
-  if (message.type === CrdtMessageType.PUT_COMPONENT) {
-    PutNetworkComponentOperation.write(
-      network.entityId,
-      message.timestamp,
-      message.componentId,
-      network.networkId,
-      message.data,
-      destinationBuffer
-    )
-  } else if (message.type === CrdtMessageType.DELETE_COMPONENT) {
-    DeleteComponentNetwork.write(
-      network.entityId,
-      message.componentId,
-      message.timestamp,
-      network.networkId,
-      destinationBuffer
-    )
-  } else if (message.type === CrdtMessageType.DELETE_ENTITY) {
-    DeleteEntityNetwork.write(network.entityId, network.networkId, destinationBuffer)
-  }
-}
-
-export function fixTransformParent(message: ReceiveMessage, parent?: Entity): Uint8Array {
-  const buffer = new ReadWriteByteBuffer()
-  const transform = 'data' in message && TransformSchema.deserialize(new ReadWriteByteBuffer(message.data))
-
-  if (!transform) throw new Error('Invalid parent transform')
-
-  // Generate new transform raw data with the parent
-  const newTransform = { ...transform, parent }
-  TransformSchema.serialize(newTransform, buffer)
-  return buffer.toBinary()
-}

package/src/server/env-var.ts

@@ -1,36 +0,0 @@
-import { getStorageServerUrl } from './storage-url'
-import { assertIsServer, wrapSignedFetch } from './utils'
-
-const MODULE_NAME = 'EnvVar'
-
-/**
- * EnvVar provides methods to fetch environment variables from the
- * Server Side Storage service. This module only works when running
- * on server-side scenes.
- */
-export const EnvVar = {
-  /**
-   * Fetches a specific environment variable by key as plain text.
-   *
-   * @param key - The name of the environment variable to fetch
-   * @returns A promise that resolves to the plain text value, or empty string if not found
-   * @throws Error if not running on a server-side scene
-   */
-  async get(key: string): Promise<string> {
-    assertIsServer(MODULE_NAME)
-
-    const baseUrl = await getStorageServerUrl()
-    const url = `${baseUrl}/env/${encodeURIComponent(key)}`
-
-    const [error, data] = await wrapSignedFetch<{ value: string }>({
-      url
-    })
-
-    if (error) {
-      console.error(`Failed to fetch environment variable '${key}': ${error}`)
-      return ''
-    }
-
-    return data?.value ?? ''
-  }
-}

package/src/server/index.ts

@@ -1,12 +0,0 @@
-export { EnvVar } from './env-var'
-export {
-  Storage,
-  IStorage,
-  ISceneStorage,
-  IPlayerStorage,
-  GetOptions,
-  GetValuesOptions,
-  GetValuesResult,
-  SetOptions,
-  StorageOptions
-} from './storage'

package/src/server/storage/constants.ts

@@ -1,112 +0,0 @@
-export const MODULE_NAME = 'Storage'
-
-/**
- * Options for getValues pagination and filtering.
- */
-export interface GetValuesOptions {
-  prefix?: string
-  limit?: number
-  offset?: number
-}
-
-/**
- * Result of getValues with pagination metadata.
- */
-export interface GetValuesResult {
-  /** Key-value entries for the current page. */
-  data: Array<{ key: string; value: unknown }>
-  pagination: {
-    offset: number
-    total: number
-  }
-}
-
-/**
- * Per-call options for Storage get().
- */
-export interface GetOptions {
-  /**
-   * When true, bypasses the read cache and forces a network read (the result
-   * still refreshes the cache). Concurrent gets for the same key still share
-   * one in-flight request. Default: false.
-   */
-  fresh?: boolean
-}
-
-/**
- * Per-call options for Storage set().
- */
-export interface SetOptions {
-  /**
-   * When true, skips the network write if the serialized value matches the
-   * last value known to be stored for this key (from a previous successful
-   * set(), get() or getValues()). Overrides the configured default. Default: true.
-   */
-  skipIfUnchanged?: boolean
-}
-
-/**
- * Module-wide configuration for Storage, applied to both scene-scoped and
- * player-scoped storage via Storage.configure().
- */
-export interface StorageOptions {
-  /**
-   * Default for set()'s skipIfUnchanged when not passed per call. A skip only
-   * suppresses a proven no-op: the exact serialized value was confirmed stored
-   * by a previous network round-trip within cacheMaxAgeMs. Default: true.
-   */
-  skipIfUnchanged?: boolean
-  /**
-   * When true, get() serves values from the local cache within cacheMaxAgeMs,
-   * including confirmed "not found" results, without a network request.
-   * Out-of-band writers (e.g. CLI storage commands) may not be visible for up
-   * to cacheMaxAgeMs; pass { fresh: true } per call to force a network read.
-   * Default: true.
-   */
-  cacheReads?: boolean
-  /**
-   * Max cache entries per scope (scene / player) before oldest entries are
-   * evicted. Entries hold the serialized value body, so memory scales with
-   * value size — this bounds entry count, not bytes. Infinity removes the bound.
-   * Default: 512.
-   */
-  cacheMaxEntries?: number
-  /**
-   * Max age of a cache entry in milliseconds, bounding both read-cache
-   * staleness and write-dedup trust; older entries are treated as unknown.
-   * The default is deliberately short so out-of-band writers (CLI storage
-   * commands, dashboards) become visible within a minute, while still
-   * absorbing hot per-frame reads. Infinity never expires. Default: 60000 (1 minute).
-   */
-  cacheMaxAgeMs?: number
-}
-
-/**
- * Fully-resolved storage configuration shared by scene and player storage.
- * @internal
- */
-export interface StorageConfigState {
-  skipIfUnchanged: boolean
-  cacheReads: boolean
-  cacheMaxEntries: number
-  cacheMaxAgeMs: number
-}
-
-/**
- * Default values for the resolved storage configuration.
- * @internal
- */
-export const DEFAULT_STORAGE_CONFIG: Readonly<StorageConfigState> = {
-  skipIfUnchanged: true,
-  cacheReads: true,
-  cacheMaxEntries: 512,
-  cacheMaxAgeMs: 60 * 1000
-}
-
-/**
- * Creates a mutable config object, later mutated by Storage.configure().
- * @internal
- */
-export function createStorageConfig(overrides?: StorageOptions): StorageConfigState {
-  return { ...DEFAULT_STORAGE_CONFIG, ...overrides }
-}