@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/projects/cyberia/instance-data.js

@@ -1,35 +1,43 @@
 /**
  * Shared Cyberia instance world-load / boot data assembly.
  *
- * Single source of truth for the payloads cyberia-server (Go) needs to boot an
- * instance and hot-reload it: full instance world (instance + maps + object
- * layers + simulation config + actions/quests), single map/object-layer
- * lookups, and the object-layer manifest.
+ * Single source of truth for the payloads the simulation server needs to boot
+ * and hot-reload an instance: the full world (instance + maps + object layers +
+ * simulation config + actions/quests), single map / object-layer lookups, and
+ * the object-layer manifest.
  *
- * Consumed by BOTH transports so they stay byte-for-byte equivalent:
- *  - gRPC `CyberiaDataService` (src/grpc/cyberia/grpc-server.js) — primary.
- *  - REST `/api/cyberia-instance/boot/*` — fallback when the engine gRPC
- *    server is not enabled for the deploy.
+ * Both boot transports adapt this module, so they stay equivalent:
+ *  - gRPC `CyberiaDataService` (src/grpc/cyberia/grpc-server.js), primary.
+ *  - REST `/api/cyberia-instance/boot/*`, fallback when gRPC is off.
  *
  * @module src/projects/cyberia/instance-data.js
  */
 
 import crypto from 'crypto';
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import {
+  collectInstanceItemIds,
+  collectSummonedItemIds,
+  selectInstanceSkills,
+} from '../../api/cyberia-instance/cyberia-instance-items.js';
 import { loggerFactory } from '../../server/ops/logger.js';
 import {
   CYBERIA_INSTANCE_CONF_DEFAULTS as FALLBACK_CONFIG_DEFAULTS,
   DEFAULT_DEAD_ITEM_ID,
+  resolveProgressionRules,
   ENTITY_TYPE_DEFAULTS,
+  resolveEntityInventory,
   DefaultCyberiaActions,
   DefaultCyberiaQuests,
+  DefaultSkillConfig,
 } from '../../api/cyberia-server-defaults/cyberia-server-defaults.js';
 import {
   DEFAULT_INSTANCE_CODE,
+  validateStats,
+  validateEntityLevel,
   DefaultCyberiaItems,
 } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { generateFallbackWorld } from '../../api/cyberia-instance/cyberia-fallback-world.js';
-import { getFallbackDefaultItems } from '../../api/cyberia-instance/cyberia-fallback-default-items.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -69,68 +77,26 @@ function getInstanceModels(context) {
   return bucket.models;
 }
 
-function normalizeEntityDefault(entityDefault = {}, canonical = {}) {
-  const defaultObjectLayers = entityDefault.defaultObjectLayers ?? canonical.defaultObjectLayers ?? [];
-  return {
+// The wire still carries inventory rows; the model no longer stores them. `defaultObjectLayers`
+// is derived here, once, from the discriminator lists — see resolveEntityInventory().
+function normalizeEntityDefault(entityDefault = {}, canonical = {}, itemTypes) {
+  const normalized = {
     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,
-    })),
+    inventoryItemsIds: [...(entityDefault.inventoryItemsIds ?? canonical.inventoryItemsIds ?? [])],
+    overrideItemsIdsState: [
+      ...(entityDefault.overrideItemsIdsState ?? canonical.overrideItemsIdsState ?? []),
+    ],
     behavior: entityDefault.behavior ?? canonical.behavior ?? '',
   };
+  return { ...normalized, defaultObjectLayers: resolveEntityInventory(normalized, { itemTypes }) };
 }
 
-// Merge instance-level itemIds flagged `defaultPlayerInventory` into the player
-// entityDefault's defaultObjectLayers so cyberia-server seeds them into every new
-// player's inventory (see handlers.go player spawn). Items are added inactive —
-// present in the inventory, not auto-equipped — so they never violate the
-// one-active-per-type equipment rule.
-//
-// Also **removes** items that are flagged `defaultPlayerInventory: false` from
-// the player's defaultObjectLayers. This ensures the instance's explicit intent
-// is honoured even when the conf's entityDefaults (e.g. from a backup/import)
-// baked those items into the player layer list.
-function applyInstanceDefaultPlayerInventory(config, instanceItemIds = []) {
-  const entries = instanceItemIds || [];
-
-  // ── 1. Remove items explicitly flagged as NOT default player inventory ─────
-  const removeIds = new Set(
-    entries.filter((entry) => entry && entry.defaultPlayerInventory === false && entry.id).map((entry) => entry.id),
-  );
-  if (removeIds.size > 0) {
-    for (const ed of config.entityDefaults || []) {
-      if (ed.defaultObjectLayers) {
-        ed.defaultObjectLayers = ed.defaultObjectLayers.filter((ol) => !removeIds.has(ol.itemId));
-      }
-    }
-  }
-
-  // ── 2. Add items flagged as default player inventory ──────────────────────
-  const addIds = entries.filter((entry) => entry && entry.defaultPlayerInventory && entry.id).map((entry) => entry.id);
-  if (addIds.length === 0) return config;
-
-  const playerDefault = (config.entityDefaults || []).find((d) => d.entityType === 'player');
-  if (!playerDefault) return config;
-
-  playerDefault.defaultObjectLayers = playerDefault.defaultObjectLayers || [];
-  const existing = new Set(playerDefault.defaultObjectLayers.map((ol) => ol.itemId));
-  for (const id of addIds) {
-    if (existing.has(id)) continue;
-    playerDefault.defaultObjectLayers.push({ itemId: id, active: false, quantity: 1 });
-    existing.add(id);
-  }
-  return config;
-}
-
-// Map CyberiaSkill collection docs to the proto skillConfig shape. The skill
-// collection is the authoritative own-model source: it carries full skill
-// metadata (summonedEntityItemId, name, description) that the instance-conf
-// skillConfig schema deliberately does not store.
+// Map CyberiaSkill documents to the proto skillConfig shape. The collection is the authoritative
+// source and carries the full metadata (summonedEntityItemId, name, description); the wire message
+// is built from the subset this instance runs, which nothing persists.
 function skillDocsToConfig(skillDocs = []) {
   return skillDocs
     .filter((d) => d && d.triggerItemId)
@@ -145,19 +111,16 @@ function skillDocsToConfig(skillDocs = []) {
     }));
 }
 
-// Load authoritative skill configs from the CyberiaSkill collection. Returns []
-// when the model is not loaded (api not mounted) or the collection is empty, so
-// callers transparently keep the conf / fallback skillConfig.
-async function loadSkillConfigDocs(models) {
+// Every skill definition the deployment knows. Which of them an instance runs is decided by
+// selectInstanceSkills against that instance's own content. Returns [] when the model is not
+// loaded (api not mounted), so callers fall back to the canonical definitions.
+async function loadSkillDocs(models) {
   if (!models.CyberiaSkill) return [];
   return await models.CyberiaSkill.find({}).lean();
 }
 
-// Map CyberiaEntityTypeDefault collection docs to the proto entityDefaults shape.
-// This collection is the authoritative own-model source for per-entity-type item
-// defaults (live/dead/drop + seed object layers). Resolution is by liveItemIds
-// membership, so every variant (e.g. each resource skin) must travel as its own
-// entry — never collapsed by entityType.
+// Map CyberiaEntityTypeDefault docs to the wire entityDefaults shape. Lookup is
+// by liveItemIds membership, so each variant travels as its own entry.
 function entityTypeDefaultDocsToConfig(docs = []) {
   return docs
     .filter((d) => d && d.entityType)
@@ -166,75 +129,56 @@ function entityTypeDefaultDocsToConfig(docs = []) {
       liveItemIds: [...(d.liveItemIds || [])],
       deadItemIds: [...(d.deadItemIds || [])],
       dropItemIds: [...(d.dropItemIds || [])],
-      defaultObjectLayers: (d.defaultObjectLayers || []).map((ol) => ({
-        itemId: ol.itemId,
-        active: !!ol.active,
-        quantity: ol.quantity || 0,
-      })),
+      inventoryItemsIds: [...(d.inventoryItemsIds || [])],
+      overrideItemsIdsState: [...(d.overrideItemsIdsState || [])],
       behavior: d.behavior || '',
     }));
 }
 
-// Load authoritative entity-type defaults from the CyberiaEntityTypeDefault
-// collection. Returns [] when the model is not mounted or empty, so callers
-// transparently keep the conf / canonical entityDefaults.
-async function loadEntityTypeDefaultDocs(models) {
+// Load the entity-type defaults THIS instance references. The conf names them by _id, so a
+// document reaches a world only when that world points at it — never because another instance
+// happens to share an item id with it, which is what used to drag foreign wiring into a build.
+async function loadEntityTypeDefaultDocs(models, conf) {
   if (!models.CyberiaEntityTypeDefault) return [];
-  return await models.CyberiaEntityTypeDefault.find({}).lean();
-}
-
-// Feed every live/dead/drop and default-object-layer item id from the collection
-// defaults into the atlas id set so the Go server resolves their sprites even
-// when the entity appears in no map (e.g. a new resource skin).
-function addEntityDefaultAtlasIds(entityDefaults, atlasItemIds) {
-  for (const d of entityDefaults || []) {
-    for (const id of d.liveItemIds || []) if (id) atlasItemIds.add(id);
-    for (const id of d.deadItemIds || []) if (id) atlasItemIds.add(id);
-    for (const id of d.dropItemIds || []) if (id) atlasItemIds.add(id);
-    for (const ol of d.defaultObjectLayers || []) if (ol.itemId) atlasItemIds.add(ol.itemId);
-  }
-}
-
-// Feed skill trigger items and every concrete summoned-entity id into the atlas
-// id set so the Go server resolves their sprites even when the entity appears in
-// no map. Runtime placeholders ('$active_skin', …) are excluded.
-function addSkillAtlasIds(skillDocs, atlasItemIds) {
-  for (const d of skillDocs || []) {
-    if (d.triggerItemId) atlasItemIds.add(d.triggerItemId);
-    for (const sk of d.skills || []) {
-      const id = sk.summonedEntityItemId;
-      if (id && !id.startsWith('$')) atlasItemIds.add(id);
-    }
-  }
+  const ids = (conf?.entityDefaults || []).map((id) => String(id?._id ?? id)).filter(Boolean);
+  if (ids.length === 0) return [];
+  const docs = await models.CyberiaEntityTypeDefault.find({ _id: { $in: ids } }).lean();
+  const byId = new Map(docs.map((doc) => [String(doc._id), doc]));
+  return ids.filter((id) => byId.has(id)).map((id) => byId.get(id));
 }
 
-function mergeEntityDefaults(entityDefaults = []) {
-  const merged = entityDefaults.map((entityDefault) => normalizeEntityDefault(entityDefault));
+// `itemTypes` lets the equipment rules settle a contested slot: which skin an entity wears when an
+// override names one. Without it every row keeps the state its list derives, which is the right
+// answer for a world whose object layers have not been read yet.
+function mergeEntityDefaults(entityDefaults = [], itemTypes) {
+  const merged = entityDefaults.map((entityDefault) => normalizeEntityDefault(entityDefault, {}, itemTypes));
   const coveredTypes = new Set(merged.map((entityDefault) => entityDefault.entityType));
   for (const canonical of ENTITY_TYPE_DEFAULTS) {
-    if (!coveredTypes.has(canonical.entityType)) merged.push(normalizeEntityDefault(canonical, canonical));
+    if (!coveredTypes.has(canonical.entityType)) merged.push(normalizeEntityDefault(canonical, canonical, itemTypes));
   }
   return merged;
 }
 
+/** itemId → item type, read from the ObjectLayer documents a world already loads for its atlases. */
+function itemTypesOf(objectLayerDocs = []) {
+  const types = {};
+  for (const doc of objectLayerDocs) {
+    const item = doc?.data?.item;
+    if (item?.id && item?.type) types[item.id] = item.type;
+  }
+  return types;
+}
+
 // ── Mongoose doc → wire message converters (proto camelCase shapes) ────────
 
 function toObjectLayerMsg(doc) {
   const d = doc.data || {};
   const item = d.item || {};
-  const stats = d.stats || {};
   const ledger = d.ledger || {};
   const render = d.render || {};
   return {
     mongoId: String(doc._id),
-    stats: {
-      effect: stats.effect || 0,
-      resistance: stats.resistance || 0,
-      agility: stats.agility || 0,
-      range: stats.range || 0,
-      intelligence: stats.intelligence || 0,
-      utility: stats.utility || 0,
-    },
+    stats: validateStats(d.stats),
     item: {
       id: item.id || '',
       type: item.type || '',
@@ -263,7 +207,7 @@ 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).
+  // CSS alpha is 0-1 float; the wire format 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) };
 }
@@ -272,6 +216,7 @@ function toEntityMsg(ent) {
   const rgba = parseRgba(ent.color);
   return {
     entityType: ent.entityType || 'floor',
+    level: ent.level === undefined ? 0 : validateEntityLevel(ent.level),
     initCellX: ent.initCellX || 0,
     initCellY: ent.initCellY || 0,
     dimX: ent.dimX || 1,
@@ -390,24 +335,23 @@ function toQuestMsg(q) {
  * Any field that is null/undefined in `gc` falls back to FALLBACK_CONFIG_DEFAULTS,
  * so partial DB documents always produce a fully playable config.
  */
+// A chance is a fraction of one. Anything else a conf carries is not a chance and resolves to
+// the default, the same way a partial progression curve inherits its missing fields.
+const chanceOf = (value, fallback) => (Number.isFinite(value) && value >= 0 && value <= 1 ? value : fallback);
+
 function toInstanceConfig(gc) {
   const fb = FALLBACK_CONFIG_DEFAULTS;
   if (!gc) return buildFallbackConfig();
 
-  // 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 the boot transports.
-  //
-  // 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 entityDefaults = mergeEntityDefaults(gcDefaults);
+  // STRICT BOUNDARY: this config is simulation only. Presentation values
+  // (palette, camera tunings, screen factors, devUi, interpolationMs,
+  // status-icon visuals, entityDefaults[].colorKey, cellSize, defaultObj*)
+  // reach the client through /api/cyberia-client-hints, never a boot transport.
+
+  // The conf carries references, not documents: the caller resolves them and overwrites this
+  // with the result. Canonical defaults alone are the correct answer for a world that
+  // references none, and for the fallback build that has no conf at all.
+  const entityDefaults = mergeEntityDefaults();
 
   return {
     tickRate: gc.tickRate ?? fb.tickRate,
@@ -425,12 +369,12 @@ function toInstanceConfig(gc) {
     playerBaseSpeed: gc.playerBaseSpeed ?? fb.playerBaseSpeed,
     playerBaseLifeRegenMin: gc.playerBaseLifeRegenMin ?? fb.playerBaseLifeRegenMin,
     playerBaseLifeRegenMax: gc.playerBaseLifeRegenMax ?? fb.playerBaseLifeRegenMax,
-    sumStatsLimit: gc.sumStatsLimit ?? fb.sumStatsLimit,
+    progressionRules: resolveProgressionRules(gc.progressionRules),
     maxActiveLayers: gc.maxActiveLayers ?? fb.maxActiveLayers,
     initialLifeFraction: gc.initialLifeFraction ?? fb.initialLifeFraction,
     respawnDurationMs: gc.respawnDurationMs ?? fb.respawnDurationMs,
     collisionLifeLoss: gc.collisionLifeLoss ?? fb.collisionLifeLoss,
-    // Economy — Fountain & Sink (nested, mirrors EconomyRules proto message).
+    // Economy — Fountain & Sink (nested EconomyRules message).
     economyRules: {
       botSpawnCoins: gc.economyRules?.botSpawnCoins ?? fb.economyRules.botSpawnCoins,
       playerSpawnCoins: gc.economyRules?.playerSpawnCoins ?? fb.economyRules.playerSpawnCoins,
@@ -441,31 +385,25 @@ function toInstanceConfig(gc) {
       portalFee: gc.economyRules?.portalFee ?? fb.economyRules.portalFee,
       craftingFeePercent: gc.economyRules?.craftingFeePercent ?? fb.economyRules.craftingFeePercent,
     },
-    lifeRegenChance: gc.lifeRegenChance ?? fb.lifeRegenChance,
-    maxChance: gc.maxChance ?? fb.maxChance,
+    lifeRegenChance: chanceOf(gc.lifeRegenChance, fb.lifeRegenChance),
+    maxChance: chanceOf(gc.maxChance, fb.maxChance),
     entityDefaults,
-    skillConfig: (gc.skillConfig && gc.skillConfig.length > 0 ? gc.skillConfig : fb.skillConfig).map((sc) => ({
-      triggerItemId: sc.triggerItemId || '',
-      skills: (sc.skills || []).map((sk) => ({
-        logicEventId: sk.logicEventId || '',
-        name: sk.name || '',
-        description: sk.description || '',
-        summonedEntityItemId: sk.summonedEntityItemId || '',
-      })),
-    })),
+    // Filled in by the caller from the skills this world's own content triggers; a conf stores
+    // none, so there is nothing here to fall back to.
+    skillConfig: [],
     skillRules: {
-      projectileSpawnChance: gc.skillRules?.projectileSpawnChance ?? fb.skillRules.projectileSpawnChance,
+      projectileSpawnChance: chanceOf(gc.skillRules?.projectileSpawnChance, fb.skillRules.projectileSpawnChance),
       projectileLifetimeMs: gc.skillRules?.projectileLifetimeMs ?? fb.skillRules.projectileLifetimeMs,
       projectileWidth: gc.skillRules?.projectileWidth ?? fb.skillRules.projectileWidth,
       projectileHeight: gc.skillRules?.projectileHeight ?? fb.skillRules.projectileHeight,
       projectileSpeedMultiplier: gc.skillRules?.projectileSpeedMultiplier ?? fb.skillRules.projectileSpeedMultiplier,
-      doppelgangerSpawnChance: gc.skillRules?.doppelgangerSpawnChance ?? fb.skillRules.doppelgangerSpawnChance,
+      doppelgangerSpawnChance: chanceOf(gc.skillRules?.doppelgangerSpawnChance, fb.skillRules.doppelgangerSpawnChance),
       doppelgangerLifetimeMs: gc.skillRules?.doppelgangerLifetimeMs ?? fb.skillRules.doppelgangerLifetimeMs,
       doppelgangerSpawnRadius: gc.skillRules?.doppelgangerSpawnRadius ?? fb.skillRules.doppelgangerSpawnRadius,
       doppelgangerInitialLifeFraction:
         gc.skillRules?.doppelgangerInitialLifeFraction ?? fb.skillRules.doppelgangerInitialLifeFraction,
     },
-    // Equipment rules — governs activation constraints (nested, mirrors EquipmentRules proto message).
+    // Equipment rules — activation constraints (nested EquipmentRules message).
     equipmentRules: {
       activeItemTypes: gc.equipmentRules?.activeItemTypes ?? fb.equipmentRules.activeItemTypes,
       onePerType: gc.equipmentRules?.onePerType ?? fb.equipmentRules.onePerType,
@@ -483,15 +421,6 @@ function buildFallbackConfig() {
   return JSON.parse(JSON.stringify(FALLBACK_CONFIG_DEFAULTS));
 }
 
-/**
- * Assembles the InstanceConfig for the procedural fallback world from code
- * defaults only — no own-model collection may override it — then applies the
- * fallback instance's default-player-inventory itemIds.
- */
-function buildFallbackInstanceConfig(fallbackConf, instanceItemIds) {
-  return applyInstanceDefaultPlayerInventory(toInstanceConfig(fallbackConf), instanceItemIds);
-}
-
 // ═══════════════════════════════════════════════════════════════════
 // Transport-agnostic fetchers — one per CyberiaDataService RPC
 // ═══════════════════════════════════════════════════════════════════
@@ -555,40 +484,31 @@ async function fetchFullInstance(models, requestedInstanceCode) {
   // ── Fallback: instance not found → return a multi-map procedural world ──
   if (!inst) {
     logger.info(`Instance "${instanceCode}" not found — returning fallback world.`);
-    const world = generateFallbackWorld({ itemIds: getFallbackDefaultItems() });
+    const world = generateFallbackWorld();
     const fallbackConf = buildFallbackConfig();
 
-    // Collect all objectLayerItemIds from the generated maps so the
-    // Go server can resolve atlases at startup.
+    // Collect every objectLayerItemId of the generated maps, so the atlases
+    // resolve at startup.
     const fallbackItemIds = new Set();
     for (const m of world.maps) {
       for (const e of m.entities || []) {
         for (const id of e.objectLayerItemIds || []) fallbackItemIds.add(id);
       }
     }
-    // Also include system OL items from entity defaults.
-    for (const d of fallbackConf.entityDefaults || []) {
+    // Also include system OL items from the canonical entity defaults — the fallback world
+    // references no collection document, so these are the defaults it actually runs on.
+    for (const d of ENTITY_TYPE_DEFAULTS) {
       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);
-      }
+      for (const id of d.inventoryItemsIds || []) fallbackItemIds.add(id);
     }
-    // Include every canonical item so the Go server can resolve the type
-    // of anything a player may pick up or equip (quest rewards like
-    // hatchet, alt weapons, etc.) — required for the one-per-type
-    // equipment rule, which silently no-ops when item type is unknown.
+    // Include every canonical item so the server knows the type of anything a
+    // player can pick up. The one-per-type rule no-ops on an unknown type.
     for (const it of DefaultCyberiaItems || []) {
       if (it?.item?.id) fallbackItemIds.add(it.item.id);
     }
 
-    // Instance-level itemIds (default-player-inventory) may not appear in
-    // any map entity — include them so their atlases resolve.
-    for (const entry of world.instance.itemIds || []) {
-      if (entry?.id) fallbackItemIds.add(entry.id);
-    }
-
     // The fallback world is fully self-contained: content config comes
     // exclusively from the canonical code defaults (cyberia-server-defaults
     // + SharedDefaultsCyberia). Own-model collections (CyberiaSkill,
@@ -599,19 +519,16 @@ async function fetchFullInstance(models, requestedInstanceCode) {
       ? await models.ObjectLayer.find({ 'data.item.id': { $in: [...fallbackItemIds] } }).lean()
       : [];
 
-    const fallbackConfig = buildFallbackInstanceConfig(fallbackConf, world.instance.itemIds);
+    const fallbackConfig = toInstanceConfig(fallbackConf);
+    // Same membership rule as a persisted world, over the canonical definitions: this path
+    // consults no collection, so DefaultSkillConfig is the only source of skills it has.
+    fallbackConfig.skillConfig = skillDocsToConfig(selectInstanceSkills(DefaultSkillConfig, fallbackItemIds));
 
     // Opaque version over everything mutable in this payload, mirroring the
     // persisted path below. A constant here would make hot reload a silent
     // no-op: WorldBuilder.ReloadWorld skips the rebuild — and therefore
-    // ApplyInstanceConfig — whenever the version is unchanged. The world
-    // geometry itself is deterministic (code defaults + seed), so the inputs
-    // that can actually differ are the staged default items and the
-    // ObjectLayer docs, which are the only things read from the DB here.
-    const fallbackVersionParts = ['fallback'];
-    for (const entry of world.instance.itemIds || []) {
-      fallbackVersionParts.push(`${entry.id}:${entry.defaultPlayerInventory ? 1 : 0}`);
-    }
+    // ApplyInstanceConfig when content and configuration are unchanged.
+    const fallbackVersionParts = ['fallback', JSON.stringify(fallbackConfig)];
     for (const doc of fallbackOlDocs) fallbackVersionParts.push(String(doc.sha256 || doc._id));
     const fallbackVersion = `fallback-${crypto
       .createHash('sha256')
@@ -633,8 +550,7 @@ async function fetchFullInstance(models, requestedInstanceCode) {
       objectLayers: fallbackOlDocs.map(toObjectLayerMsg),
       config: fallbackConfig,
       version: fallbackVersion,
-      // Mission content for the procedural fallback comes straight from
-      // the canonical defaults — no DB, fully self-contained.
+      // Mission content for the fallback comes from the code defaults, no DB.
       actions: DefaultCyberiaActions.map(toActionMsg),
       quests: DefaultCyberiaQuests.map(toQuestMsg),
     };
@@ -642,10 +558,8 @@ async function fetchFullInstance(models, requestedInstanceCode) {
 
   // ── Instance found — load maps + entity OLs + config default OLs ──────
   // `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.
+  // orphaned. The direct instanceCode lookup keeps every tuning field coming
+  // from the database instead of FALLBACK_CONFIG_DEFAULTS.
   let conf = inst.conf;
   if (!conf) {
     conf = await models.CyberiaInstanceConf.findOne({ instanceCode }).lean();
@@ -657,105 +571,112 @@ async function fetchFullInstance(models, requestedInstanceCode) {
   const mapCodes = inst.cyberiaMapCodes || [];
   const mapDocs = mapCodes.length ? await models.CyberiaMap.find({ code: { $in: mapCodes } }).lean() : [];
 
-  // Collect all item IDs referenced by map entities.
-  const itemIds = new Set();
-  for (const m of mapDocs) {
-    for (const e of m.entities || []) {
-      for (const id of e.objectLayerItemIds || []) itemIds.add(id);
-    }
-  }
-
-  // Instance-level itemIds (e.g. default-player-inventory items) may not
-  // appear in any map entity — include them so their atlases resolve.
-  // Tolerate legacy flat-string entries alongside the { id, … } shape.
-  for (const entry of inst.itemIds || []) {
-    const id = typeof entry === 'string' ? entry : entry?.id;
-    if (id) itemIds.add(id);
-  }
-
-  // Authoritative per-entity-type defaults come from the
-  // CyberiaEntityTypeDefault collection (own model); empty collection leaves
-  // the conf/canonical defaults in place.
-  const entityDefaultDocs = await loadEntityTypeDefaultDocs(models);
+  // Authoritative per-entity-type defaults are the documents this instance's conf references;
+  // referencing none leaves the canonical defaults in place.
+  const entityDefaultDocs = await loadEntityTypeDefaultDocs(models, conf);
   const entityDefaultsConfig = entityTypeDefaultDocsToConfig(entityDefaultDocs);
 
-  // Include system OL items from canonical ENTITY_TYPE_DEFAULTS, the DB conf,
-  // AND the collection so the Go server always caches every default atlas
-  // even when an entity (e.g. a new resource skin) appears in no map.
-  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);
-    }
-  }
+  // Mission content for this instance: actions and quests bound to its maps (by sourceMapCode).
+  // Delivered with the world so the Go server never opens a separate content channel, and never
+  // receives content from other instances' maps. Read before the item set because what a vendor
+  // sells and what a quest asks for are part of what this world owns.
+  const actionDocs =
+    mapCodes.length && models.CyberiaAction
+      ? await models.CyberiaAction.find({ sourceMapCode: { $in: mapCodes } }).lean()
+      : [];
+  const questDocs =
+    mapCodes.length && models.CyberiaQuest
+      ? await models.CyberiaQuest.find({ sourceMapCode: { $in: mapCodes } }).lean()
+      : [];
+
+  // Everything this world names, by the one rule the export and the editor's sync also use. The
+  // canonical defaults join the instance's own: every world runs on both, so an entity here can
+  // hold what they wire even when no map places it.
+  const owned = collectInstanceItemIds({
+    maps: mapDocs,
+    entityDefaults: [...entityDefaultsConfig, ...ENTITY_TYPE_DEFAULTS],
+    actions: actionDocs,
+    quests: questDocs,
+  });
+
+  const itemIds = new Set(owned);
   // The Go server falls back to this dead visual when a build declares
   // no deadItemIds — its atlas must resolve even when nothing references it.
   itemIds.add(DEFAULT_DEAD_ITEM_ID);
-  addEntityDefaultAtlasIds(entityDefaultsConfig, itemIds);
 
-  // Authoritative skills come from the CyberiaSkill collection (own model);
-  // resolve their atlases before the OL query so summoned entities render.
-  const skillDocs = await loadSkillConfigDocs(models);
-  addSkillAtlasIds(skillDocs, itemIds);
+  // The skills this world runs: the collection owns the definitions, and a trigger item the
+  // world never names is unreachable here. The canonical definitions stand in only for a
+  // deployment that never seeded the collection — never for a world that legitimately selects
+  // none of them, which would put back skills an operator deleted. What the selected skills
+  // summon needs an atlas, so those ids join the set before the ObjectLayer query.
+  const seededSkills = await loadSkillDocs(models);
+  const skillDocs = selectInstanceSkills(seededSkills.length ? seededSkills : DefaultSkillConfig, owned);
+  for (const summoned of collectSummonedItemIds(skillDocs)) itemIds.add(summoned);
 
   const olDocs = itemIds.size ? 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)];
+  // Opaque version over the updatedAt timestamps. The server compares it to
+  // skip a full world rebuild when nothing changed.
+  const versionParts = [String(inst.updatedAt || inst._id), JSON.stringify(toInstanceConfig(conf))];
   for (const m of mapDocs) versionParts.push(String(m.updatedAt || m._id));
   if (conf.updatedAt) versionParts.push(String(conf.updatedAt));
   // Skill edits live in their own collection — fold them in so a skill
   // change triggers a Go-side world rebuild instead of serving stale skills.
-  for (const sk of skillDocs) versionParts.push(String(sk.updatedAt || sk._id));
+  for (const sk of skillDocs) versionParts.push(String(sk.updatedAt || sk._id || sk.triggerItemId));
   // Entity-type-default edits live in their own collection too — fold them
   // in so adding/editing a default (e.g. a new resource) rebuilds the world.
   for (const ed of entityDefaultDocs) versionParts.push(String(ed.updatedAt || ed._id));
   const version = crypto.createHash('sha256').update(versionParts.join('|')).digest('hex');
 
-  // Mission content for this instance: actions and quests bound to its
-  // maps (by sourceMapCode). Delivered with the world so the Go server
-  // never opens a separate content channel, and never receives content from
-  // other instances' maps.
-  const actionDocs =
-    mapCodes.length && models.CyberiaAction
-      ? await models.CyberiaAction.find({ sourceMapCode: { $in: mapCodes } }).lean()
-      : [];
-  const questDocs =
-    mapCodes.length && models.CyberiaQuest
-      ? await models.CyberiaQuest.find({ sourceMapCode: { $in: mapCodes } }).lean()
-      : [];
-
   const baseConfig = toInstanceConfig(conf);
-  // Own-model entity defaults win over the conf's entityDefaults (overlaid on
-  // canonical via mergeEntityDefaults), so every collection variant — e.g.
-  // each resource skin — reaches the Go runtime keyed by liveItemIds. Applied
-  // BEFORE default-player-inventory so the player layer additions survive.
-  if (entityDefaultsConfig.length) baseConfig.entityDefaults = mergeEntityDefaults(entityDefaultsConfig);
-  const config = applyInstanceDefaultPlayerInventory(baseConfig, inst.itemIds);
-  // Own-model skills win over the conf's stripped skillConfig (which lacks
-  // summonedEntityItemId); empty collection leaves the conf/fallback as-is.
-  if (skillDocs.length) config.skillConfig = skillDocsToConfig(skillDocs);
+  // The referenced documents are the world's defaults, completed by the canonical set for every
+  // entity type they do not cover. Every variant — each resource skin, say — reaches the Go
+  // runtime keyed by liveItemIds. Applied BEFORE default-player-inventory so the player layer
+  // additions survive.
+  if (entityDefaultsConfig.length) {
+    baseConfig.entityDefaults = mergeEntityDefaults(entityDefaultsConfig, itemTypesOf(olDocs));
+  }
+  // The wire still carries a skillConfig; nothing stores one. It is exactly the skills selected
+  // above, so what the simulation runs and what the export writes come from one decision.
+  baseConfig.skillConfig = skillDocsToConfig(skillDocs);
 
   return {
     instance: toInstanceMsg(inst),
     maps: mapDocs.map(toMapMsg),
     objectLayers: olDocs.map(toObjectLayerMsg),
-    config,
+    config: baseConfig,
     version,
     actions: actionDocs.map(toActionMsg),
     quests: questDocs.map(toQuestMsg),
   };
 }
 
+/**
+ * Every ObjectLayer item id one instance runs on, as stored documents.
+ *
+ * Reads the world the same way the runtime does, so a tool never disagrees with the
+ * simulation about what a world owns. Ids the instance names but the collection does not
+ * hold are absent, because {@link fetchFullInstance} resolves the set against ObjectLayer.
+ *
+ * @param {object} models - Instance models, see {@link getInstanceModels}.
+ * @param {string} instanceCode - Instance code, must exist.
+ * @returns {Promise<string[]>} Item ids, no duplicates.
+ * @throws {Error} When no CyberiaInstance holds that code.
+ */
+async function fetchInstanceObjectLayerItemIds(models, instanceCode) {
+  const instance = await models.CyberiaInstance.findOne({ code: instanceCode }, { _id: 1 }).lean();
+  if (!instance) throw new Error(`CyberiaInstance "${instanceCode}" not found`);
+  const { objectLayers } = await fetchFullInstance(models, instanceCode);
+  return [...new Set(objectLayers.map((objectLayer) => objectLayer?.item?.id).filter(Boolean))];
+}
+
 export {
   buildCyberiaMmoInstanceEnv as buildInstanceEnv,
   buildCyberiaMmoInstanceEnv,
+  fetchInstanceObjectLayerItemIds,
   getInstanceModels,
+  itemTypesOf,
   normalizeEntityDefault,
-  applyInstanceDefaultPlayerInventory,
   skillDocsToConfig,
   entityTypeDefaultDocsToConfig,
   mergeEntityDefaults,
@@ -768,7 +689,6 @@ export {
   toQuestMsg,
   toInstanceConfig,
   buildFallbackConfig,
-  buildFallbackInstanceConfig,
   pingData,
   objectLayerQueryFilter,
   fetchObjectLayerBatch,