cyberia 3.2.5 → 3.2.12

package/src/db/mongo/MongooseDB.js

@@ -1,6 +1,6 @@
 import mongoose from 'mongoose';
-import { loggerFactory } from '../../server/logger.js';
 import { getCapVariableName } from '../../client/components/core/CommonJs.js';
+import { loggerFactory } from '../../server/logger.js';
 
 /**
  * Module for connecting to and loading models for a MongoDB database using Mongoose.
@@ -10,6 +10,32 @@ import { getCapVariableName } from '../../client/components/core/CommonJs.js';
 
 const logger = loggerFactory(import.meta);
 
+const MONGODB_SERVICE_NAME = 'mongodb-service';
+const MONGODB_STATEFULSET_NAME = 'mongodb';
+const MONGODB_DEFAULT_AUTH_SOURCE = 'admin';
+const MONGODB_DEFAULT_REPLICA_SET = 'rs0';
+const MONGODB_DEFAULT_REPLICA_COUNT = 3;
+
+/**
+ * Resolves MongoDB replica hosts from explicit input or StatefulSet defaults.
+ * @param {{hostList?: string, replicaCount?: number}} [options] - Host resolution options.
+ * @returns {Array<string>} Normalized host:port entries.
+ */
+const resolveMongoReplicaHosts = ({ hostList = '', replicaCount = MONGODB_DEFAULT_REPLICA_COUNT }) => {
+  if (hostList) {
+    return hostList
+      .split(',')
+      .map((host) => host.trim())
+      .filter(Boolean)
+      .map((host) => (host.includes(':') ? host : `${host}:27017`));
+  }
+
+  return Array.from(
+    { length: replicaCount },
+    (_, index) => `${MONGODB_STATEFULSET_NAME}-${index}.${MONGODB_SERVICE_NAME}:27017`,
+  );
+};
+
 /**
  * @class
  * @alias MongooseDBService
@@ -23,35 +49,109 @@ const logger = loggerFactory(import.meta);
  * 3. No built-in defaults — both `host` and `name` are required from the caller or environment.
  */
 class MongooseDBService {
+  /**
+   * Normalizes Mongo host inputs into plain host:port entries.
+   * @param {Array<string>|string} hosts - Host input as list or comma-separated string.
+   * @returns {Array<string>} Normalized host:port entries.
+   */
+  normalizeHosts(hosts) {
+    const hostEntries = Array.isArray(hosts) ? hosts : `${hosts || ''}`.split(',');
+
+    return hostEntries
+      .map((entry) => `${entry || ''}`.trim())
+      .filter(Boolean)
+      .map((entry) => entry.replace(/^mongodb:\/\//, '').replace(/\/.*$/, ''));
+  }
+
+  /**
+   * Normalizes connection config from object or legacy host/name signature.
+   * @param {object|string} configOrHost - Connection config object or host string.
+   * @param {string} [name] - Legacy DB name when using host string input.
+   * @returns {{authSource: string, dbName: string, directConnection: boolean, hosts: Array<string>, password: string, replicaSet: string, user: string}} Normalized config.
+   */
+  normalizeConfig(configOrHost, name) {
+    const config =
+      typeof configOrHost === 'object' && configOrHost !== null ? { ...configOrHost } : { host: configOrHost, name };
+
+    const rawHosts = config.host || process.env.DB_HOST;
+    const hosts = this.normalizeHosts(rawHosts);
+    const dbName = config.name || process.env.DB_NAME;
+
+    if (!hosts.length || !dbName) {
+      const missing = [!hosts.length && 'host (db.host|DB_HOST)', !dbName && 'name (db.name|DB_NAME)']
+        .filter(Boolean)
+        .join(', ');
+      throw new Error(`MongooseDBService.connect: missing required parameter(s): ${missing}`);
+    }
+
+    const user = config.user || process.env.DB_USER || '';
+    const password = config.password || process.env.DB_PASSWORD || '';
+    const directConnection = hosts.length === 1;
+    const replicaSet = directConnection
+      ? ''
+      : config.replicaSet || process.env.DB_REPLICA_SET || MONGODB_DEFAULT_REPLICA_SET;
+    const authSource = config.authSource || process.env.DB_AUTH_SOURCE || (user ? MONGODB_DEFAULT_AUTH_SOURCE : '');
+
+    return {
+      authSource,
+      dbName,
+      directConnection,
+      hosts,
+      password,
+      replicaSet,
+      user,
+    };
+  }
+
+  /**
+   * Builds a MongoDB URI from normalized config options.
+   * @param {object|string} configOrHost - Connection config object or host string.
+   * @param {string} [name] - Legacy DB name when using host string input.
+   * @returns {string} MongoDB connection URI.
+   */
+  buildUri(configOrHost, name) {
+    const config = this.normalizeConfig(configOrHost, name);
+    const credentials =
+      config.user && config.password
+        ? `${encodeURIComponent(config.user)}:${encodeURIComponent(config.password)}@`
+        : '';
+    const query = new URLSearchParams();
+
+    if (config.directConnection) query.set('directConnection', 'true');
+    else if (config.replicaSet) query.set('replicaSet', config.replicaSet);
+    if (config.authSource) query.set('authSource', config.authSource);
+
+    return `mongodb://${credentials}${config.hosts.join(',')}/${config.dbName}${query.size ? `?${query.toString()}` : ''}`;
+  }
+
   /**
    * Establishes a Mongoose connection to the specified MongoDB instance.
    *
    * @async
-   * @param {string} host - The MongoDB host URI (e.g., `'mongodb://localhost:27017'`).
-   *   Falls back to `process.env.DB_HOST` when not provided.
-   * @param {string} name - The database name.
-   *   Falls back to `process.env.DB_NAME` when not provided.
+   * @param {object|string} configOrHost - Either a db config object or a legacy host string.
+   * @param {string} [configOrHost.host] - Legacy single host or comma-separated host list.
+   * @param {string} [configOrHost.name] - The database name.
+   * @param {string} [configOrHost.replicaSet] - The MongoDB replica set name.
+   * @param {string} [configOrHost.authSource] - The authentication database.
+   * @param {string} [configOrHost.user] - The MongoDB username.
+   * @param {string} [configOrHost.password] - The MongoDB password.
+   * @param {string} [name] - Legacy database name when a host string is passed.
    * @returns {Promise<mongoose.Connection>} A promise that resolves to the established Mongoose connection object.
    * @throws {Error} If neither the argument nor the corresponding environment variable supplies a value.
    */
-  async connect(host, name) {
-    host = host || process.env.DB_HOST;
-    name = name || process.env.DB_NAME;
-
-    if (!host || !name) {
-      const missing = [!host && 'host (DB_HOST)', !name && 'name (DB_NAME)'].filter(Boolean).join(', ');
-      throw new Error(`MongooseDBService.connect: missing required parameter(s): ${missing}`);
-    }
-
-    const uri = `${host}/${name}`;
-    // logger.info('MongooseDB connect', { host, name, uri });
+  async connect(configOrHost, name) {
+    const uri = this.buildUri(configOrHost, name);
+    if (process.env.NODE_ENV === 'development') logger.info(`Connecting to MongoDB with URI`, uri);
     return await mongoose
       .createConnection(uri, {
+        autoIndex: process.env.NODE_ENV !== 'production',
+        heartbeatFrequencyMS: 10000,
+        maxPoolSize: 20,
+        minPoolSize: 2,
+        retryReads: true,
+        retryWrites: true,
         serverSelectionTimeoutMS: 5000,
-        // readPreference: 'primary',
-        // directConnection: true,
-        // useNewUrlParser: true,
-        // useUnifiedTopology: true,
+        socketTimeoutMS: 45000,
       })
       .asPromise();
   }
@@ -87,4 +187,12 @@ class MongooseDBService {
  */
 const MongooseDB = new MongooseDBService();
 
-export { MongooseDB, MongooseDBService as MongooseDBClass };
+export {
+  MongooseDB,
+  MongooseDBService as MongooseDBClass,
+  MONGODB_DEFAULT_REPLICA_COUNT,
+  MONGODB_DEFAULT_REPLICA_SET,
+  MONGODB_SERVICE_NAME,
+  MONGODB_STATEFULSET_NAME,
+  resolveMongoReplicaHosts,
+};

package/src/grpc/cyberia/grpc-server.js

@@ -10,15 +10,18 @@
 
 import * as grpc from '@grpc/grpc-js';
 import * as protoLoader from '@grpc/proto-loader';
+import crypto from 'crypto';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import {
   CYBERIA_INSTANCE_CONF_DEFAULTS as FALLBACK_CONFIG_DEFAULTS,
   ENTITY_TYPE_DEFAULTS,
-  STATUS_ICONS,
-} from '../../api/cyberia-instance-conf/cyberia-instance-conf.defaults.js';
+  // STATUS_ICONS deliberately not imported here — see toInstanceConfig.
+  // Server simulation only cares about the numeric u8 IDs (which travel on
+  // the AOI wire). Icon stems + border colours live in SharedDefaultsCyberia.
+} from '../../api/cyberia-server-defaults/cyberia-server-defaults.js';
 import { generateFallbackWorld } from '../../api/cyberia-instance/cyberia-fallback-world.js';
 
 const logger = loggerFactory(import.meta);
@@ -26,7 +29,7 @@ const logger = loggerFactory(import.meta);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const PROTO_PATH = path.resolve(__dirname, '../../../cyberia-server/proto/cyberia.proto');
+const PROTO_PATH = path.resolve(__dirname, '../../../cyberia-server/gen/proto/cyberia.proto');
 
 const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
   keepCase: false,
@@ -43,11 +46,101 @@ const proto = grpc.loadPackageDefinition(packageDefinition).cyberia;
 // ═══════════════════════════════════════════════════════════════════
 
 function getModels(dbKey) {
-  const bucket = DataBaseProvider.instance[dbKey];
-  if (!bucket || !bucket.mongoose || !bucket.mongoose.models) {
-    throw new Error(`DataBaseProvider not loaded for key "${dbKey}"`);
+  const bucket = DataBaseProviderService.getProvider(dbKey, 'mongoose');
+  if (!bucket || !bucket.models) {
+    throw new Error(`DataBaseProviderService not loaded for key "${dbKey}"`);
   }
-  return bucket.mongoose.models;
+  return bucket.models;
+}
+
+function countSharedItemIds(source = [], target = []) {
+  if (!Array.isArray(source) || source.length === 0 || !Array.isArray(target) || target.length === 0) {
+    return 0;
+  }
+  const targetSet = new Set(target.filter(Boolean));
+  let count = 0;
+  for (const itemId of source) {
+    if (targetSet.has(itemId)) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function normalizeEntityDefault(entityDefault = {}, canonical = {}) {
+  const defaultObjectLayers = entityDefault.defaultObjectLayers ?? canonical.defaultObjectLayers ?? [];
+  return {
+    entityType: entityDefault.entityType ?? canonical.entityType ?? '',
+    liveItemIds: [...(entityDefault.liveItemIds ?? canonical.liveItemIds ?? [])],
+    deadItemIds: [...(entityDefault.deadItemIds ?? canonical.deadItemIds ?? [])],
+    dropItemIds: [...(entityDefault.dropItemIds ?? canonical.dropItemIds ?? [])],
+    defaultObjectLayers: defaultObjectLayers.map((ol) => ({
+      itemId: ol.itemId || '',
+      active: !!ol.active,
+      quantity: ol.quantity || 0,
+    })),
+  };
+}
+
+function selectCanonicalEntityDefaultIndex(entityDefault, canonicalDefaults, usedIndexes) {
+  const pickBestIndex = (candidateIndexes) => {
+    let firstSameTypeIndex = -1;
+    let bestLiveOverlapIndex = -1;
+    let bestLiveOverlap = 0;
+    let bestLiveItemCount = Number.POSITIVE_INFINITY;
+
+    for (const index of candidateIndexes) {
+      const canonical = canonicalDefaults[index];
+      if (canonical.entityType !== entityDefault.entityType) {
+        continue;
+      }
+      if (firstSameTypeIndex === -1) {
+        firstSameTypeIndex = index;
+      }
+      const liveOverlap = countSharedItemIds(entityDefault.liveItemIds, canonical.liveItemIds);
+      if (
+        liveOverlap > 0 &&
+        (bestLiveOverlapIndex === -1 ||
+          liveOverlap > bestLiveOverlap ||
+          (liveOverlap === bestLiveOverlap && (canonical.liveItemIds?.length ?? 0) < bestLiveItemCount))
+      ) {
+        bestLiveOverlapIndex = index;
+        bestLiveOverlap = liveOverlap;
+        bestLiveItemCount = canonical.liveItemIds?.length ?? 0;
+      }
+    }
+
+    if (bestLiveOverlapIndex !== -1) {
+      return bestLiveOverlapIndex;
+    }
+    return firstSameTypeIndex;
+  };
+
+  const unusedCandidateIndexes = canonicalDefaults.map((_, index) => index).filter((index) => !usedIndexes.has(index));
+
+  const preferredIndex = pickBestIndex(unusedCandidateIndexes);
+  if (preferredIndex !== -1) {
+    return preferredIndex;
+  }
+  return pickBestIndex(canonicalDefaults.map((_, index) => index));
+}
+
+function mergeEntityDefaults(entityDefaults = []) {
+  const mergedDefaults = ENTITY_TYPE_DEFAULTS.map((canonical) => normalizeEntityDefault(canonical, canonical));
+  const usedCanonicalIndexes = new Set();
+
+  for (const entityDefault of entityDefaults) {
+    const canonicalIndex = selectCanonicalEntityDefaultIndex(entityDefault, ENTITY_TYPE_DEFAULTS, usedCanonicalIndexes);
+    if (canonicalIndex === -1) {
+      mergedDefaults.push(normalizeEntityDefault(entityDefault));
+      continue;
+    }
+
+    mergedDefaults[canonicalIndex] = normalizeEntityDefault(entityDefault, ENTITY_TYPE_DEFAULTS[canonicalIndex]);
+    usedCanonicalIndexes.add(canonicalIndex);
+  }
+
+  return mergedDefaults;
 }
 
 // ── Mongoose doc → protobuf message converters ───────────────────
@@ -58,13 +151,6 @@ function toObjectLayerMsg(doc) {
   const stats = d.stats || {};
   const ledger = d.ledger || {};
   const render = d.render || {};
-  const rf = doc.objectLayerRenderFramesId;
-  let frameDuration = 250;
-  let isStateless = false;
-  if (rf && typeof rf === 'object') {
-    if (rf.frame_duration != null) frameDuration = rf.frame_duration;
-    if (rf.is_stateless != null) isStateless = rf.is_stateless;
-  }
   return {
     mongoId: String(doc._id),
     stats: {
@@ -92,12 +178,24 @@ function toObjectLayerMsg(doc) {
     },
     sha256: doc.sha256 || '',
     cid: doc.cid || '',
-    frameDuration,
-    isStateless,
   };
 }
 
+/**
+ * Parse a CSS rgba() colour string into {r, g, b, a} integer components.
+ * Returns {r:0, g:0, b:0, a:0} (transparent) when the string is absent or malformed.
+ */
+function parseRgba(str) {
+  if (!str) return { r: 0, g: 0, b: 0, a: 0 };
+  const m = str.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+))?\s*\)/);
+  if (!m) return { r: 0, g: 0, b: 0, a: 0 };
+  // CSS alpha is 0-1 (float); proto uses 0-255 (int).
+  const cssAlpha = m[4] !== undefined ? parseFloat(m[4]) : 1;
+  return { r: Number(m[1]), g: Number(m[2]), b: Number(m[3]), a: Math.round(cssAlpha * 255) };
+}
+
 function toEntityMsg(ent) {
+  const rgba = parseRgba(ent.color);
   return {
     entityType: ent.entityType || 'floor',
     initCellX: ent.initCellX || 0,
@@ -111,6 +209,10 @@ function toEntityMsg(ent) {
     maxLife: ent.maxLife || 0,
     lifeRegen: ent.lifeRegen || 0,
     portalSubtype: ent.portalSubtype || '',
+    colorR: rgba.r,
+    colorG: rgba.g,
+    colorB: rgba.b,
+    colorA: rgba.a,
   };
 }
 
@@ -159,49 +261,24 @@ function toInstanceConfig(gc) {
   const fb = FALLBACK_CONFIG_DEFAULTS;
   if (!gc) return buildFallbackConfig();
 
-  const colors =
-    gc.colors && gc.colors.length > 0
-      ? gc.colors.map((c) => ({
-          key: c.key || '',
-          r: c.r ?? 0,
-          g: c.g ?? 0,
-          b: c.b ?? 0,
-          a: c.a ?? 255,
-        }))
-      : fb.colors.map((c) => ({ ...c }));
-
-  // Merge entity defaults: use canonical ENTITY_TYPE_DEFAULTS as base, overlay with
-  // any instance-specific overrides stored in gc.entityDefaults.
+  // STRICT BOUNDARY — this function produces the *simulation* config for
+  // cyberia-server only. Every presentation concern is excluded:
+  //
+  //   - palette (colors), camera tunings, screen factors, devUi,
+  //     interpolationMs, status-icon visuals, entityDefaults[].colorKey,
+  //     cellSize, defaultObj* — all of these reach the client through
+  //     /api/cyberia-client-hints, never through gRPC.
+  //
+  // The Go simulation does not need any of them to advance world state;
+  // the C/WASM cyberia-client owns its own render policy. See
+  // src/client/components/cyberia/SharedDefaultsCyberia.js.
+
   const gcDefaults = gc.entityDefaults && gc.entityDefaults.length > 0 ? gc.entityDefaults : [];
-  const gcDefaultsMap = Object.fromEntries(gcDefaults.map((d) => [d.entityType, d]));
-  const entityDefaults = ENTITY_TYPE_DEFAULTS.map((canonical) => {
-    const override = gcDefaultsMap[canonical.entityType] ?? {};
-    const dols = override.defaultObjectLayers ?? canonical.defaultObjectLayers ?? [];
-    return {
-      entityType: canonical.entityType,
-      liveItemIds: override.liveItemIds ?? canonical.liveItemIds,
-      deadItemIds: override.deadItemIds ?? canonical.deadItemIds,
-      colorKey: override.colorKey ?? canonical.colorKey,
-      defaultObjectLayers: dols.map((ol) => ({
-        itemId: ol.itemId || '',
-        active: !!ol.active,
-        quantity: ol.quantity || 0,
-      })),
-    };
-  });
+  const entityDefaults = mergeEntityDefaults(gcDefaults);
 
   return {
-    cellSize: gc.cellSize ?? fb.cellSize,
-    fps: gc.fps ?? fb.fps,
-    interpolationMs: gc.interpolationMs ?? fb.interpolationMs,
-    defaultObjWidth: gc.defaultObjWidth ?? fb.defaultObjWidth,
-    defaultObjHeight: gc.defaultObjHeight ?? fb.defaultObjHeight,
-    cameraSmoothing: gc.cameraSmoothing ?? fb.cameraSmoothing,
-    cameraZoom: gc.cameraZoom ?? fb.cameraZoom,
-    defaultWidthScreenFactor: gc.defaultWidthScreenFactor ?? fb.defaultWidthScreenFactor,
-    defaultHeightScreenFactor: gc.defaultHeightScreenFactor ?? fb.defaultHeightScreenFactor,
-    devUi: gc.devUi ?? fb.devUi,
-    colors,
+    tickRate: gc.tickRate ?? fb.tickRate,
+    snapshotRate: gc.snapshotRate ?? fb.snapshotRate,
     aoiRadius: gc.aoiRadius ?? fb.aoiRadius,
     portalHoldTimeMs: gc.portalHoldTimeMs ?? fb.portalHoldTimeMs,
     portalSpawnRadius: gc.portalSpawnRadius ?? fb.portalSpawnRadius,
@@ -233,9 +310,14 @@ function toInstanceConfig(gc) {
     lifeRegenChance: gc.lifeRegenChance ?? fb.lifeRegenChance,
     maxChance: gc.maxChance ?? fb.maxChance,
     entityDefaults,
-    skillConfig: (gc.skillConfig || []).map((sc) => ({
+    skillConfig: (gc.skillConfig && gc.skillConfig.length > 0 ? gc.skillConfig : fb.skillConfig).map((sc) => ({
       triggerItemId: sc.triggerItemId || '',
-      logicEventIds: sc.logicEventIds || [],
+      skills: (sc.skills || []).map((sk) => ({
+        logicEventId: sk.logicEventId || '',
+        name: sk.name || '',
+        description: sk.description || '',
+        summonedEntityItemId: sk.summonedEntityItemId || '',
+      })),
     })),
     skillRules: {
       projectileSpawnChance: gc.skillRules?.projectileSpawnChance ?? fb.skillRules.projectileSpawnChance,
@@ -255,23 +337,6 @@ function toInstanceConfig(gc) {
       onePerType: gc.equipmentRules?.onePerType ?? fb.equipmentRules.onePerType,
       requireSkin: gc.equipmentRules?.requireSkin ?? fb.equipmentRules.requireSkin,
     },
-    // Status icon mapping — u8 ID → icon filename stem + border colour.
-    // Border colours come from the frozen STATUS_ICONS constant (canonical
-    // source of truth).  DB entries may override iconId but borderColor is
-    // always canonical — the DB schema defaults are generic grey, not the
-    // actual per-status colours.
-    statusIcons: STATUS_ICONS.map((canon) => {
-      const dbEntry = (gc.statusIcons || []).find((s) => s.id === canon.id);
-      const bc = canon.borderColor || {};
-      return {
-        id: canon.id,
-        iconId: (dbEntry && dbEntry.iconId) || canon.iconId || '',
-        borderColorR: bc.r ?? 100,
-        borderColorG: bc.g ?? 100,
-        borderColorB: bc.b ?? 100,
-        borderColorA: bc.a ?? 200,
-      };
-    }),
   };
 }
 
@@ -302,10 +367,7 @@ function buildHandlers(dbKey) {
         if (call.request.itemTypeFilter) {
           filter['data.item.type'] = call.request.itemTypeFilter;
         }
-        const cursor = models.ObjectLayer.find(filter)
-          .populate('objectLayerRenderFramesId', { _id: 1, frame_duration: 1, is_stateless: 1 })
-          .lean()
-          .cursor();
+        const cursor = models.ObjectLayer.find(filter).lean().cursor();
         for await (const doc of cursor) {
           call.write(toObjectLayerMsg(doc));
         }
@@ -319,9 +381,7 @@ function buildHandlers(dbKey) {
     async getObjectLayer(call, callback) {
       try {
         const models = getModels(dbKey);
-        const doc = await models.ObjectLayer.findOne({ 'data.item.id': call.request.itemId })
-          .populate('objectLayerRenderFramesId', { _id: 1, frame_duration: 1, is_stateless: 1 })
-          .lean();
+        const doc = await models.ObjectLayer.findOne({ 'data.item.id': call.request.itemId }).lean();
         if (!doc)
           return callback({ code: grpc.status.NOT_FOUND, message: `ObjectLayer "${call.request.itemId}" not found` });
         callback(null, toObjectLayerMsg(doc));
@@ -344,7 +404,7 @@ function buildHandlers(dbKey) {
           models.GlobalMapCodeRegistry.findOneAndUpdate(
             { mapCode },
             { instanceCode, status: 'active' },
-            { upsert: true, new: true, timestamps: true },
+            { upsert: true, returnDocument: 'after', timestamps: true },
           ).catch((err) => logger.warn('getMapData registry update failed:', err.message));
         }
 
@@ -380,15 +440,14 @@ function buildHandlers(dbKey) {
           for (const d of fallbackConf.entityDefaults || []) {
             for (const id of d.liveItemIds || []) fallbackItemIds.add(id);
             for (const id of d.deadItemIds || []) fallbackItemIds.add(id);
+            for (const id of d.dropItemIds || []) fallbackItemIds.add(id);
             for (const ol of d.defaultObjectLayers || []) {
               if (ol.itemId) fallbackItemIds.add(ol.itemId);
             }
           }
 
           const fallbackOlDocs = fallbackItemIds.size
-            ? await models.ObjectLayer.find({ 'data.item.id': { $in: [...fallbackItemIds] } })
-                .populate('objectLayerRenderFramesId', { _id: 1, frame_duration: 1, is_stateless: 1 })
-                .lean()
+            ? await models.ObjectLayer.find({ 'data.item.id': { $in: [...fallbackItemIds] } }).lean()
             : [];
 
           callback(null, {
@@ -415,12 +474,27 @@ function buildHandlers(dbKey) {
             })),
             objectLayers: fallbackOlDocs.map(toObjectLayerMsg),
             config: toInstanceConfig(fallbackConf),
+            version: 'fallback',
           });
           return;
         }
 
         // ── Instance found — load maps + entity OLs + config default OLs ──────
-        const conf = inst.conf || {};
+        // `populate('conf')` returns null when the ObjectId ref is missing or
+        // orphaned (e.g. after a --conf import that preserved a stale _id).
+        // Fall back to a direct instanceCode lookup so aoiRadius and all other
+        // tuning fields are always read from the database, never silently
+        // replaced by FALLBACK_CONFIG_DEFAULTS.
+        let conf = inst.conf;
+        if (!conf) {
+          conf = await models.CyberiaInstanceConf.findOne({ instanceCode }).lean();
+          if (conf) {
+            logger.warn(
+              `getFullInstance: conf ref missing on instance "${instanceCode}" — resolved by instanceCode lookup`,
+            );
+          }
+        }
+        conf = conf || {};
         const mapCodes = inst.cyberiaMapCodes || [];
         const mapDocs = mapCodes.length ? await models.CyberiaMap.find({ code: { $in: mapCodes } }).lean() : [];
 
@@ -432,29 +506,35 @@ function buildHandlers(dbKey) {
           }
         }
 
-        // Also include "system" item IDs from the instance config so the
-        // Go server has their OL data cached without extra round trips:
-        // Include OL item IDs from entityDefaults so the Go server has all
-        // default atlas data cached at startup without needing extra round trips.
-        for (const d of conf.entityDefaults || []) {
+        // Include system OL items from BOTH canonical ENTITY_TYPE_DEFAULTS AND
+        // the DB conf so the Go server always caches all default atlases even if
+        // the DB doc has incomplete entityDefaults.
+        for (const d of [...ENTITY_TYPE_DEFAULTS, ...(conf.entityDefaults || [])]) {
           for (const id of d.liveItemIds || []) itemIds.add(id);
           for (const id of d.deadItemIds || []) itemIds.add(id);
+          for (const id of d.dropItemIds || []) itemIds.add(id);
           for (const ol of d.defaultObjectLayers || []) {
             if (ol.itemId) itemIds.add(ol.itemId);
           }
         }
 
         const olDocs = itemIds.size
-          ? await models.ObjectLayer.find({ 'data.item.id': { $in: [...itemIds] } })
-              .populate('objectLayerRenderFramesId', { _id: 1, frame_duration: 1, is_stateless: 1 })
-              .lean()
+          ? await models.ObjectLayer.find({ 'data.item.id': { $in: [...itemIds] } }).lean()
           : [];
 
+        // Opaque version string from updatedAt timestamps — the Go server
+        // compares this to skip full world rebuilds when nothing changed.
+        const versionParts = [String(inst.updatedAt || inst._id)];
+        for (const m of mapDocs) versionParts.push(String(m.updatedAt || m._id));
+        if (conf.updatedAt) versionParts.push(String(conf.updatedAt));
+        const version = crypto.createHash('sha256').update(versionParts.join('|')).digest('hex');
+
         callback(null, {
           instance: toInstanceMsg(inst),
           maps: mapDocs.map(toMapMsg),
           objectLayers: olDocs.map(toObjectLayerMsg),
           config: toInstanceConfig(conf),
+          version,
         });
       } catch (err) {
         logger.error('getFullInstance:', err);
@@ -481,16 +561,16 @@ function buildHandlers(dbKey) {
 // Server lifecycle
 // ═══════════════════════════════════════════════════════════════════
 
-const GrpcServer = {
-  _server: null,
+class GrpcServer {
+  static _server = null;
 
   /**
    * @param {Object} opts
-   * @param {string} opts.host  - DataBaseProvider host key
-   * @param {string} opts.path  - DataBaseProvider path key
+   * @param {string} opts.host  - DataBaseProviderService host key
+   * @param {string} opts.path  - DataBaseProviderService path key
    * @param {number} [opts.port=50051]
    */
-  async start({ host, path: dbPath, port = 50051 } = {}) {
+  static async start({ host, path: dbPath, port = 50051 } = {}) {
     const dbKey = `${host}${dbPath}`;
     const server = new grpc.Server({
       'grpc.max_send_message_length': 64 * 1024 * 1024,
@@ -513,9 +593,9 @@ const GrpcServer = {
         resolve(server);
       });
     });
-  },
+  }
 
-  async stop() {
+  static async stop() {
     if (!GrpcServer._server) return;
     return new Promise((resolve) => {
       GrpcServer._server.tryShutdown(() => {
@@ -524,7 +604,7 @@ const GrpcServer = {
         resolve();
       });
     });
-  },
-};
+  }
+}
 
 export { GrpcServer };

package/src/index.js

@@ -44,7 +44,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.5';
+  static version = 'v3.2.12';
 
   /**
    * Required Node.js major version