@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/api/cyberia-audio/cyberia-audio.service.js

@@ -0,0 +1,220 @@
+import crypto from 'crypto';
+import fs from 'fs-extra';
+import nodePath from 'path';
+import { Types } from 'mongoose';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { FileCleanup } from '../file/file.service.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { DataQuery } from '../../server/storage/data-query.js';
+import { fileRefFields } from '../file/file.ref.js';
+
+const logger = loggerFactory(import.meta);
+
+const AUDIO_MIMETYPE = 'audio/wav';
+
+/** The File-referencing fields of this model, read from the registry that owns that mapping. */
+const FILE_FIELDS = fileRefFields('cyberia-audio');
+
+/**
+ * The generic File `_id` an asset's bytes resolve through, derived from the asset code and the
+ * bytes themselves.
+ *
+ * Content-addressed on purpose. The client fetches a WAV as `/api/file/blob/<fileId>` and caches
+ * it, so re-recording an asset under a stable id would serve the old sound from that cache
+ * forever. A changed render therefore lands on a new id — and the import deletes the one it
+ * replaced, so the change costs nothing. Identical bytes re-derive the same id, which is what
+ * makes re-importing an unchanged bank a no-op rather than a churn of File documents.
+ *
+ * The code is folded in so two assets that happen to render identical bytes still own separate
+ * File documents; sharing one would make deleting either orphan the other.
+ *
+ * @param {string} code - Asset code.
+ * @param {string} md5 - Hex MD5 of the WAV bytes.
+ * @returns {import('mongoose').Types.ObjectId}
+ */
+const audioFileId = (code, md5) =>
+  new Types.ObjectId(crypto.createHash('sha256').update(`cyberia-audio:${code}:${md5}`).digest('hex').slice(0, 24));
+
+/**
+ * Validates a `<name>.json` sidecar written by the cyberia-audio package, and reads it into the
+ * shape this platform stores.
+ *
+ * Identity is all the import requires: `id` becomes the asset's code, and the rest is the
+ * recorder's own metadata — including `bus`, the `src/audio-module/<bus-id>/` directory the
+ * module was authored on, which is the same bus vocabulary a map binding routes through.
+ *
+ * @param {object} manifest - Parsed manifest.
+ * @param {string} manifestPath - Source path, for error messages.
+ * @returns {object} The manifest as stored.
+ * @throws {Error} When the manifest carries no usable asset identity.
+ */
+const readManifest = (manifest, manifestPath) => {
+  if (!manifest || typeof manifest !== 'object') throw new Error(`Invalid audio manifest: ${manifestPath}`);
+  if (!manifest.id) throw new Error(`Audio manifest has no id: ${manifestPath}`);
+  const { bus = '', ...rest } = manifest;
+  return { ...rest, bus };
+};
+
+class CyberiaAudioService {
+  /**
+   * Imports one recorded `<name>.wav` + `<name>.json` pair, upserting both the backing
+   * File document and the CyberiaAudio document keyed by the asset's code.
+   *
+   * @param {{wavPath: string, manifestPath: string}} record - Absolute or cwd-relative artifact pair.
+   * @param {{host: string, path: string}} options - Provider context.
+   * @returns {Promise<object>} The upserted CyberiaAudio document.
+   */
+  static importRecord = async ({ wavPath, manifestPath }, options) => {
+    const CyberiaAudio = DataBaseProviderService.getModel('CyberiaAudio', options);
+    const File = DataBaseProviderService.getModel('file', options);
+
+    const manifest = readManifest(JSON.parse(await fs.readFile(manifestPath, 'utf8')), manifestPath);
+    const data = await fs.readFile(wavPath);
+    const md5 = crypto.createHash('md5').update(data).digest('hex');
+    const fileData = { name: `${manifest.id}.wav`, data, size: data.length, mimetype: AUDIO_MIMETYPE, md5 };
+
+    await new CyberiaAudio({ code: manifest.id, manifest }).validate();
+    if (
+      44 > data.length ||
+      data.length > 8 * 1024 * 1024 ||
+      data.toString('ascii', 0, 4) !== 'RIFF' ||
+      data.toString('ascii', 8, 12) !== 'WAVE' ||
+      data.readUInt32LE(4) !== data.length - 8
+    )
+      throw new Error(`Invalid WAV: ${wavPath}`);
+
+    const existing = await CyberiaAudio.findOne({ code: manifest.id });
+    // Derived from the bytes, so it is the same id on an unchanged re-import and a new one the
+    // moment the render changes. Writing the File first leaves the bytes reachable if the run is
+    // interrupted before the metadata upsert; the stale document is then dropped on the next run.
+    const fileId = audioFileId(manifest.id, md5);
+    await File.findOneAndUpdate(
+      { _id: fileId },
+      { $set: fileData },
+      { upsert: true, returnDocument: 'after', runValidators: true },
+    );
+
+    const doc = await CyberiaAudio.findOneAndUpdate(
+      { code: manifest.id },
+      { $set: { code: manifest.id, fileId, manifest } },
+      { upsert: true, returnDocument: 'after', runValidators: true },
+    );
+
+    // Only once the asset points at the new bytes: the superseded blob is unreferenced from here
+    // on, and leaving it behind is what orphans a File document.
+    if (existing) {
+      await FileCleanup.cleanupReplacedFiles({
+        oldDoc: existing,
+        newData: { fileId },
+        fileFields: FILE_FIELDS,
+        File,
+      });
+    }
+    return doc;
+  };
+
+  /**
+   * Deletes an asset and the File document holding its bytes.
+   *
+   * The asset is the only reference to that blob, so dropping one without the other is exactly
+   * what `underpost db clean-fs` would later have to sweep up.
+   *
+   * @param {Array<object>} assets - CyberiaAudio documents about to be removed.
+   * @param {{host: string, path: string}} options - Provider context.
+   * @returns {Promise<number>} Count of File documents deleted.
+   */
+  static deleteBackingFiles = async (assets, options) => {
+    const File = DataBaseProviderService.getModel('file', options);
+    let deleted = 0;
+    for (const asset of assets) {
+      const ids = await FileCleanup.deleteDocumentFiles({ doc: asset, fileFields: FILE_FIELDS, File });
+      deleted += ids.length;
+    }
+    return deleted;
+  };
+
+  /**
+   * Imports every valid `<name>.wav` + `<name>.json` pair found in a records directory.
+   * A WAV with no manifest beside it is skipped with a warning: the pair is the unit of import.
+   *
+   * @param {{recordsPath: string, codes?: Array<string>|null}} params - Source directory and optional code filter.
+   * @param {{host: string, path: string}} options - Provider context.
+   * @returns {Promise<Array<object>>} The upserted CyberiaAudio documents.
+   */
+  static importRecords = async ({ recordsPath, codes = null }, options) => {
+    if (!(await fs.pathExists(recordsPath))) throw new Error(`Records directory not found: ${recordsPath}`);
+
+    const stems = (await fs.readdir(recordsPath))
+      .filter((name) => name.toLowerCase().endsWith('.wav'))
+      .map((name) => nodePath.basename(name, nodePath.extname(name)))
+      .filter((stem) => !codes || codes.includes(stem))
+      .sort();
+
+    if (codes) {
+      for (const code of codes) if (!stems.includes(code)) throw new Error(`No ${code}.wav found in ${recordsPath}`);
+    }
+
+    const imported = [];
+    for (const stem of stems) {
+      const wavPath = nodePath.join(recordsPath, `${stem}.wav`);
+      const manifestPath = nodePath.join(recordsPath, `${stem}.json`);
+      if (!(await fs.pathExists(manifestPath))) {
+        logger.warn(`Skipping ${stem}.wav: no ${stem}.json manifest beside it`);
+        continue;
+      }
+      const doc = await CyberiaAudioService.importRecord({ wavPath, manifestPath }, options);
+      logger.info(`Imported ${doc.code}`, { _id: doc._id.toString(), fileId: doc.fileId.toString() });
+      imported.push(doc);
+    }
+    return imported;
+  };
+
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-audio.model.js').CyberiaAudioModel} */
+    const CyberiaAudio = DataBaseProviderService.getModel('CyberiaAudio', options);
+    return await new CyberiaAudio(req.body).save();
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-audio.model.js').CyberiaAudioModel} */
+    const CyberiaAudio = DataBaseProviderService.getModel('CyberiaAudio', options);
+    if (req.params.id) return await CyberiaAudio.findById(req.params.id);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaAudio.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaAudio.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-audio.model.js').CyberiaAudioModel} */
+    const CyberiaAudio = DataBaseProviderService.getModel('CyberiaAudio', options);
+    const File = DataBaseProviderService.getModel('file', options);
+    const existing = await CyberiaAudio.findById(req.params.id);
+    const updated = await CyberiaAudio.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
+    // Repointing an asset at other bytes leaves the previous blob referenced by nothing.
+    if (existing) {
+      await FileCleanup.cleanupReplacedFiles({
+        oldDoc: existing,
+        newData: req.body,
+        fileFields: FILE_FIELDS,
+        File,
+      });
+    }
+    return updated;
+  };
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-audio.model.js').CyberiaAudioModel} */
+    const CyberiaAudio = DataBaseProviderService.getModel('CyberiaAudio', options);
+    const assets = req.params.id ? await CyberiaAudio.find({ _id: req.params.id }) : await CyberiaAudio.find();
+    await CyberiaAudioService.deleteBackingFiles(assets, options);
+    if (req.params.id) return await CyberiaAudio.findByIdAndDelete(req.params.id);
+    return await CyberiaAudio.deleteMany();
+  };
+}
+
+export { CyberiaAudioService, audioFileId, readManifest };

package/src/api/cyberia-client-hints/cyberia-client-hints.controller.js

@@ -9,9 +9,7 @@ class CyberiaClientHintsController {
         host: options.host || 'default',
         path: options.path || '/',
       });
-      // Surface the resolution source as a non-authoritative header so
-      // operators can see whether the runtime fetched from the new
-      // collection, the compatibility read on instance-conf, the cache, or defaults.
+      // Diagnostic header: which source answered this request.
       res.setHeader('X-Cyberia-Hints-Source', source);
       return sendSuccess(res, data);
     },

package/src/api/cyberia-client-hints/cyberia-client-hints.model.js

@@ -1,15 +1,9 @@
 /**
- * Mongoose model for `CyberiaClientHints`.
+ * Mongoose model for `CyberiaClientHints`, the per-instance presentation
+ * overrides. Editor flows write it; the game client reads it over REST. The
+ * simulation never touches it.
  *
- * Dedicated collection for per-instance presentation overrides.
- *
- * Ownership:
- *   - Read by:  cyberia-client (via /api/cyberia-client-hints/:code), CMS UIs.
- *   - Written by: CMS / editor flows. The Cyberia simulation server
- *                 never reads or writes this collection.
- *   - Cacheable: yes — the service layer keeps an in-memory TTL cache.
- *
- * Schema scope: purely visual fields. Anything that influences simulation
+ * Schema scope: visual fields only. A field that changes the simulation
  * belongs in `CyberiaInstanceConf`.
  *
  * @module src/api/cyberia-client-hints/cyberia-client-hints.model.js
@@ -58,13 +52,10 @@ const EntityColorKeySchema = new Schema(
 
 const CyberiaClientHintsSchema = new Schema(
   {
-    // Instance code this hint set is scoped to. Matches CyberiaInstance.code
-    // and CyberiaInstanceConf.instanceCode. Indexed and unique to make the
-    // service-layer cache a 1-to-1 keyed lookup.
+    // Instance code, matching CyberiaInstance.code. Unique: one hint set per code.
     code: { type: String, required: true, unique: true, index: true },
 
-    // Optional palette overrides. Keys not present here fall back to the
-    // client's compile-time defaults.
+    // Palette overrides. An absent key keeps the client default.
     palette: { type: [PaletteEntrySchema], default: [] },
 
     // Optional per-entity-type color-key overrides.
@@ -73,8 +64,8 @@ const CyberiaClientHintsSchema = new Schema(
     // Optional status-icon visual overrides (id → iconId + borderColor).
     statusIcons: { type: [StatusIconHintSchema], default: [] },
 
-    // Camera, viewport, and cell-sizing tunings — null/undefined means
-    // "use the SharedDefaultsCyberia.RENDER_DEFAULTS value".
+    // Camera, viewport and cell-size tunings. null keeps the
+    // SharedDefaultsCyberia.RENDER_DEFAULTS value.
     cellSize: { type: Number, default: null },
     defaultObjWidth: { type: Number, default: null },
     defaultObjHeight: { type: Number, default: null },
@@ -85,8 +76,8 @@ const CyberiaClientHintsSchema = new Schema(
     interpolationMs: { type: Number, default: null },
     devUi: { type: Boolean, default: null },
 
-    // Main UI font: TTF file name under engine assets/fonts/ (null = built-in
-    // raylib font) and a uniform text-size multiplier.
+    // Main UI font: TTF file name under engine assets/fonts/ (null = client
+    // built-in font) and a uniform text-size multiplier.
     fontFamily: { type: String, default: null },
     fontFactorSize: { type: Number, default: null },
   },

package/src/api/cyberia-client-hints/cyberia-client-hints.router.js

@@ -1,40 +1,22 @@
 /**
  * @module src/api/cyberia-client-hints
  *
- * Client presentation hints — read-only REST endpoint.
+ * Client presentation hints — read-only REST endpoint, off the simulation path.
+ * It serves optional per-instance overrides of render policy: palette, camera
+ * defaults, status-icon visuals, interpolation window, dev-overlay flag.
  *
- * Purpose
- * -------
- * The cyberia-server (Go authoritative simulation) and the WS init payload
- * carry *only* simulation contracts. Client-render policy (palette, camera
- * defaults, status-icon visuals, interpolation window, dev-overlay flag)
- * lives off the simulation path entirely.
- *
- * This endpoint exposes optional per-instance overrides of those values.
- * The client is required to function with no calls to this endpoint at
- * all (it ships built-in defaults that match the canonical engine
- * defaults 1-to-1 — see cyberia-client/src/domain/presentation_defaults.h).
- *
- * Endpoint
- * --------
+ * Endpoints:
  *   GET /api/cyberia-client-hints/:instanceCode
  *     -> 200 { palette, entityColorKeys, statusIcons, cameraSmoothing,
  *              cameraZoom, defaultWidthScreenFactor,
  *              defaultHeightScreenFactor, interpolationMs, devUi }
- *     -> 404 if no instance with that code exists in the database — the
- *            client falls back to its built-in defaults on 404 (this is
- *            the normal path for stateless servers / fresh deployments).
- *
+ *     -> 404 when no instance carries that code. The client then uses its
+ *            own built-in defaults, the normal path for a fresh deployment.
  *   GET /api/cyberia-client-hints/
- *     -> 200 canonical defaults — same shape as above, no DB read.
+ *     -> 200 canonical defaults, same shape, no DB read.
  *
- * What it intentionally does NOT do
- * ---------------------------------
- *   - It does not touch gameplay state (no entity, map, economy, skill,
- *     equipment, or stat fields).
- *   - It is not consumed by cyberia-server; the Go process never calls
- *     this endpoint.
- *   - It is not authenticated. Presentation hints are not secret.
+ * Out of scope: gameplay state and authentication. Presentation hints hold no
+ * simulation field and no secret.
  */
 
 import express from 'express';
@@ -50,15 +32,11 @@ class CyberiaClientHintsRouter {
     const router = express.Router();
     router.use(crossOriginMiddleware);
 
-    // GET /:code -> resolved hints.
-    // Resolution order is documented in cyberia-client-hints.service.js:
-    //   1. In-memory TTL cache.
-    //   2. CyberiaClientHints collection (preferred).
-    //   3. Legacy presentation fields on CyberiaInstanceConf (back-compat).
-    //   4. Canonical client defaults (never cached so a later DB insert wins).
+    // GET /:code -> resolved hints. See the resolution order in
+    // cyberia-client-hints.service.js.
     router.get('/:code', async (req, res) => await CyberiaClientHintsController.getByCode(req, res, options));
 
-    // GET / -> canonical defaults. No DB read. Documentation/diagnostic.
+    // GET / -> canonical defaults. No DB read.
     router.get('/', async (req, res) => await CyberiaClientHintsController.getDefaults(req, res, options));
 
     return router;

package/src/api/cyberia-client-hints/cyberia-client-hints.service.js

@@ -3,22 +3,14 @@
  *
  * Read-only service layer for client presentation hints.
  *
- * Resolution order (highest priority first):
- *   1. CyberiaClientHints collection — the dedicated presentation-overrides
- *      collection. Always preferred when present.
- *   2. Compatibility read on CyberiaInstanceConf with the same `code` —
- *      covers instances seeded before CyberiaClientHints existed.
- *   3. Canonical compile-time defaults from
- *      SharedDefaultsCyberia.js. The C client bakes the
- *      same defaults at compile time, so this branch returns exactly the
- *      values the client already has.
+ * Resolution order, highest priority first:
+ *   1. CyberiaClientHints collection, the dedicated overrides collection.
+ *   2. Presentation fields on CyberiaInstanceConf with the same `code`.
+ *   3. Canonical defaults from SharedDefaultsCyberia.js, the same values the
+ *      client holds built in.
  *
- * Caching: in-memory TTL cache keyed by instance code. Read-only on the
- * hot path; cache writes happen on cache miss + DB hit. CMS writes that
- * mutate the underlying collection should call `clientHintsInvalidate(code)`.
- *
- * Output is a plain JSON-friendly object whose shape matches the C
- * client's compile-time layout.
+ * An in-memory TTL cache keyed by instance code serves the hot path. A write
+ * to either collection must call `clientHintsInvalidate(code)`.
  */
 
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
@@ -31,8 +23,7 @@ import {
 
 const logger = loggerFactory(import.meta);
 
-// TTL chosen long enough that bursty client fetches are absorbed, short
-// enough that an editor change shows up within ~30s without manual flush.
+// TTL absorbs bursty client fetches and still shows an editor change in ~30s.
 const CACHE_TTL_MS = 30_000;
 
 // One per instance code. value: { data, expiresAt }
@@ -56,9 +47,7 @@ function cacheSet(code, data) {
   cache.set(code, { data, expiresAt: now() + CACHE_TTL_MS });
 }
 
-/** Invalidate a cache entry. CMS write paths should call this after
- *  mutating either CyberiaClientHints or CyberiaInstanceConf for
- *  the given code. */
+/** Invalidate one cache entry, or the whole cache when `code` is empty. */
 export function clientHintsInvalidate(code) {
   if (code) {
     cache.delete(code);
@@ -107,7 +96,7 @@ export async function resolveClientHints(code, options = {}) {
     return { data: CYBERIA_CLIENT_HINTS_DEFAULTS, source: 'defaults' };
   }
 
-  // 1. Preferred — CyberiaClientHints collection (src/api/cyberia-client-hints/cyberia-client-hints.model.js).
+  // 1. Preferred source: the CyberiaClientHints collection.
   if (HintsModel && code) {
     const hint = await HintsModel.findOne({ code }).lean().catch(() => null);
     if (hint) {
@@ -117,9 +106,7 @@ export async function resolveClientHints(code, options = {}) {
     }
   }
 
-  // 2. Compatibility read — for instances seeded before CyberiaClientHints
-  //    existed, look up the same code in CyberiaInstanceConf and read its
-  //    presentation-shaped fields directly.
+  // 2. Instances that keep their presentation fields on CyberiaInstanceConf.
   if (ConfModel && code) {
     const fromConf =
       (await ConfModel.findOne({ code }).lean().catch(() => null)) ||
@@ -131,22 +118,18 @@ export async function resolveClientHints(code, options = {}) {
     }
   }
 
-  // 3. Any available CyberiaClientHints document — used when the requested
-  //    code has no record yet but another instance (e.g. the one the Go
-  //    server is currently running) does.  This avoids pure built-in
-  //    defaults in fresh environments where only a different code is seeded.
+  // 3. Any CyberiaClientHints document, when the requested code has none but
+  //    another instance does. Beats falling straight through to defaults.
   if (HintsModel) {
     const anyHint = await HintsModel.findOne({}).lean().catch(() => null);
     if (anyHint) {
       const merged = buildClientHints(anyHint);
-      // Cache under the requested code so subsequent requests are fast,
-      // but with a shorter TTL (5 s) so a proper seed wins quickly.
+      // Short TTL under the requested code so a later seed wins quickly.
       if (code) cache.set(code, { data: merged, expiresAt: now() + 5_000 });
       return { data: merged, source: 'presentation-hints-fallback' };
     }
   }
 
-  // 4. Canonical defaults. Not cached — we do not poison the cache with
-  //    a default that could mask a later DB insert.
+  // 4. Canonical defaults. Never cached, so a later DB insert wins.
   return { data: CYBERIA_CLIENT_HINTS_DEFAULTS, source: 'defaults' };
 }

package/src/api/cyberia-dialogue/cyberia-dialogue.model.js

@@ -8,7 +8,7 @@ import { Schema, model, Types } from 'mongoose';
  *
  * Schema fields:
  *   code    – primary grouping key, e.g. "default-lain" or "wason-intro".
- *             The C client fetches all lines for a given code in one request.
+ *             The client fetches every line of one code in a single request.
  *   order   – zero-based display sequence within the code group.
  *   speaker – display name shown above the dialogue line.
  *   text    – the dialogue line itself.

package/src/api/cyberia-dialogue/cyberia-dialogue.router.js

@@ -9,7 +9,7 @@ class CyberiaDialogueRouter {
    */
   static router(options) {
     const router = express.Router();
-    // Direct lookup by code — C client fetches dialogue by code (e.g. "default-lain")
+    // Direct lookup by code, e.g. "default-lain".
     router.get(`/code/:code`, async (req, res) => await CyberiaDialogueController.getByCode(req, res, options));
     return registerCrudRoutes(router, CyberiaDialogueController, options);
   }

package/src/api/cyberia-entity/cyberia-entity.model.js

@@ -1,9 +1,11 @@
 import { Schema, model, Types } from 'mongoose';
+import { ENTITY_LEVEL_MIN, ENTITY_LEVEL_MAX } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
 // https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
 
 const CyberiaEntitySchema = new Schema({
   entityType: { type: String, default: 'floor' },
+  level: { type: Number, min: ENTITY_LEVEL_MIN, max: ENTITY_LEVEL_MAX, validate: Number.isInteger },
   initCellX: { type: Number, default: 0 },
   initCellY: { type: Number, default: 0 },
   dimX: { type: Number, default: 1 },

package/src/api/cyberia-entity/cyberia-entity.service.js

@@ -29,7 +29,7 @@ class CyberiaEntityService {
   static put = async (req, res, options) => {
     /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
     const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
-    return await CyberiaEntity.findByIdAndUpdate(req.params.id, req.body);
+    return await CyberiaEntity.findByIdAndUpdate(req.params.id, req.body, { runValidators: true });
   };
   static delete = async (req, res, options) => {
     /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.controller.js

@@ -1,6 +1,12 @@
-import { buildCrudController } from '../../server/network/middlewares.js';
+import { buildCrudController, serviceHandler } from '../../server/network/middlewares.js';
 import { CyberiaEntityTypeDefaultService } from './cyberia-entity-type-default.service.js';
 
-const CyberiaEntityTypeDefaultController = buildCrudController(CyberiaEntityTypeDefaultService);
+const CyberiaEntityTypeDefaultController = buildCrudController(CyberiaEntityTypeDefaultService, {
+  // Which instances run on this default. The link is stored on CyberiaInstanceConf.entityDefaults,
+  // so reading it is an ordinary conf read; only the write needs a route of its own.
+  setInstances: serviceHandler(CyberiaEntityTypeDefaultService.setInstances),
+  // Point one instance's conf at every default its own map content needs.
+  sync: serviceHandler(CyberiaEntityTypeDefaultService.sync),
+});
 
 export { CyberiaEntityTypeDefaultController };

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.model.js

@@ -6,24 +6,27 @@ import { Schema, model } from 'mongoose';
 // item defaults that ship in cyberia-server-defaults.js (ENTITY_TYPE_DEFAULTS).
 // A document binds an entity category (entityType) to the item ids the runtime
 // rotates through by lifecycle state:
-//   liveItemIds          — ObjectLayer item ids while the entity is alive.
-//   deadItemIds          — ids swapped in on death / ghost state.
-//   dropItemIds          — ids granted to the killer on depletion (resources).
-//   defaultObjectLayers  — seed inventory rows ({ itemId, active, quantity }).
+//   liveItemIds       — ObjectLayer item ids while the entity is alive.
+//   deadItemIds       — ids swapped in on death / ghost state.
+//   dropItemIds       — ids granted to the killer on depletion (resources).
+//   inventoryItemsIds     — ids the entity carries but no lifecycle state activates.
+//   overrideItemsIdsState — per-id overrides of what the lists would otherwise derive.
 //
-// Resolution rule (authoritative): defaults are looked up by the entity's ACTIVE
-// itemId (usually the skin) — the system finds the document whose `liveItemIds`
-// contains that itemId, then applies the document's deadItemIds / dropItemIds /
-// defaultObjectLayers to drive what is shown as the entity's state changes.
+// The three lifecycle lists are discriminators, not separate inventories. The entity holds one
+// inventory — the union of all four lists — and the runtime activates the slots the context
+// calls for. An id's active flag and quantity follow from the list it belongs to, so neither is
+// stored per row — `overrideItemsIdsState` is the one exception, and it only ever adjusts an id
+// the lists already carry. See resolveEntityInventory() in cyberia-server-defaults.js.
 //
-// Resolution (subset matching): a document matches an entity when ALL of its
-// `liveItemIds` are present in the entity's active item ids, and the MOST SPECIFIC
-// match wins — the document requiring the largest item set. This lets the same
-// skin map to different defaults by its full active set, e.g.
+// Resolution: a document matches an entity when every one of its `liveItemIds`
+// is in the entity's active item ids. The most specific match wins, the document
+// that requires the largest item set. Its remaining lists then drive the entity
+// through its states. So one skin can map to different defaults by its full
+// active set, e.g.
 //   { bot, liveItemIds:[purple, atlas_pistol_mk2], behavior:hostile }
 //   { bot, liveItemIds:[purple],                    behavior:passive }
 // where a purple bot carrying the pistol is hostile and a bare purple bot is
-// passive. The Go simulation (game/entity_defaults.go) implements the same rule.
+// passive. The simulation applies the same rule.
 //
 // Invariants:
 //   - `entityType` is a label, not a unique key — a category appears in many
@@ -33,11 +36,18 @@ import { Schema, model } from 'mongoose';
 //     at different specificity levels). `liveItemIds` is indexed (non-unique
 //     multikey) only for fast membership lookups.
 
-const ObjectLayerDefaultSchema = new Schema(
+// Overrides what the lists derive for one carried id: `active` forces the spawn state (a skin the
+// equipment rules would otherwise leave inactive), `quantity` sizes a stack (a drop bundle).
+// Omitting `active` keeps the derived value; an id no list carries is ignored.
+const OverrideItemStateSchema = new Schema(
   {
-    itemId: { type: String, required: true, trim: true },
-    active: { type: Boolean, default: false },
-    quantity: { type: Number, default: 0 },
+    itemId: { type: String, trim: true },
+    active: { type: Boolean },
+    quantity: { type: Number, default: 1, min: 1 },
+    // Probability in [0,1] that this id actually scatters when the entity dies. Absent means 1 —
+    // the drop always happens, which is what every world did before this existed. Only meaningful
+    // for an id the build carries in `dropItemIds`; on any other row it is inert.
+    dropChance: { type: Number, min: 0, max: 1 },
   },
   { _id: false },
 );
@@ -48,11 +58,12 @@ const CyberiaEntityTypeDefaultSchema = new Schema(
     liveItemIds: { type: [{ type: String, trim: true }], index: true },
     deadItemIds: [{ type: String, trim: true }],
     dropItemIds: [{ type: String, trim: true }],
-    defaultObjectLayers: [ObjectLayerDefaultSchema],
+    inventoryItemsIds: [{ type: String, trim: true }],
+    overrideItemsIdsState: [OverrideItemStateSchema],
     // Canonical entity behavior bound to entities matched by liveItemIds (see
     // SharedDefaultsCyberia.ENTITY_BEHAVIORS). Empty = let the runtime derive it
-    // (armed → hostile, else passive). The Go simulation resolves this with the
-    // same liveItemIds matching used for the live/dead/drop sets.
+    // (armed → hostile, else passive). The simulation resolves it with the same
+    // liveItemIds match it uses for the live/dead/drop sets.
     behavior: { type: String, trim: true },
   },
   {

package/src/api/cyberia-entity-type-default/cyberia-entity-type-default.router.js

@@ -1,5 +1,6 @@
 import express from 'express';
 import { registerCrudRoutes } from '../../server/network/middlewares.js';
+import { moderatorGuard } from '../../server/security/auth.js';
 import { CyberiaEntityTypeDefaultController } from './cyberia-entity-type-default.controller.js';
 
 class CyberiaEntityTypeDefaultRouter {
@@ -8,7 +9,21 @@ class CyberiaEntityTypeDefaultRouter {
    * @returns {import('express').Router}
    */
   static router(options) {
-    return registerCrudRoutes(express.Router(), CyberiaEntityTypeDefaultController, options);
+    const router = express.Router();
+    // Custom actions first: the generic /:id routes below capture everything.
+    router.post(
+      `/sync-instance/:instanceCode`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaEntityTypeDefaultController.sync(req, res, options),
+    );
+    router.post(
+      `/:id/instances`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaEntityTypeDefaultController.setInstances(req, res, options),
+    );
+    return registerCrudRoutes(router, CyberiaEntityTypeDefaultController, options);
   }
 }