@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/api/cyberia-instance-conf/cyberia-instance-conf.model.js

@@ -1,56 +1,19 @@
+import { STAT_TYPES, STAT_MODIFIER_MAX } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { Schema, model } from 'mongoose';
-import { CYBERIA_INSTANCE_CONF_DEFAULTS as D } from '../cyberia-server-defaults/cyberia-server-defaults.js';
+import { CYBERIA_INSTANCE_CONF_DEFAULTS as D, resolveProgressionRules, PROGRESSION_RULE_LIMITS } from '../cyberia-server-defaults/cyberia-server-defaults.js';
+
+const BaseStatsSchema = new Schema(Object.fromEntries(STAT_TYPES.map((key) => [key, {
+  type: Number, min: 0, max: STAT_MODIFIER_MAX, validate: Number.isInteger,
+}])), { _id: false, strict: 'throw' });
+const ProgressionRulesSchema = new Schema({
+  ...Object.fromEntries(Object.entries(PROGRESSION_RULE_LIMITS).map(([key, [min, max]]) => [key, {
+    type: Number, min, max, validate: Number.isInteger,
+  }])),
+  baseStats: BaseStatsSchema,
+  perLevelStats: BaseStatsSchema,
+}, { _id: false, strict: 'throw' });
+ProgressionRulesSchema.pre('validate', function () { resolveProgressionRules(this.toObject()); });
 
-// ObjectLayer inventory slot: itemId + whether it starts active + initial quantity.
-// Used by EntityDefaultSchema.defaultObjectLayers.
-const ObjectLayerSlotSchema = new Schema(
-  {
-    itemId: { type: String, required: true },
-    active: { type: Boolean, default: false },
-    quantity: { type: Number, default: 1 },
-  },
-  { _id: false },
-);
-
-// Per-entity-type simulation defaults. ONLY authoritative item-id wiring
-// lives here — presentation (palette, colour keys) is the client's
-// responsibility and travels through the CyberiaClientHints REST contract.
-const EntityDefaultSchema = new Schema(
-  {
-    // Entity category string (matches entity_type_str / bot Behavior in game engine)
-    entityType: { type: String, required: true },
-    // Default ObjectLayer item IDs when the entity is alive and carries no assigned items.
-    liveItemIds: { type: [String], default: [] },
-    // Default ObjectLayer item IDs for the dead / ghost / respawning state.
-    deadItemIds: { type: [String], default: [] },
-    // Resource-only inventory items granted on extraction/depletion.
-    // These are not auto-activated on the entity itself.
-    dropItemIds: { type: [String], default: [] },
-    // Full default ObjectLayer inventory for this entity type.
-    // Each entry specifies itemId, whether it starts active, and its initial quantity.
-    // The coin slot must always have active:false — coins are non-activable.
-    // When non-empty this supersedes liveItemIds for inventory initialization.
-    defaultObjectLayers: { type: [ObjectLayerSlotSchema], default: [] },
-    // Canonical entity behavior (SharedDefaultsCyberia.ENTITY_BEHAVIORS). Empty
-    // lets the runtime derive it (armed → hostile, else passive).
-    behavior: { type: String, default: '' },
-  },
-  { _id: false },
-);
-
-const SkillConfigEntrySchema = new Schema(
-  {
-    triggerItemId: { type: String, required: true },
-    logicEventIds: { type: [String], default: [] },
-  },
-  { _id: false },
-);
-
-// ── StatusIconEntrySchema ────────────────────────────────────────────────────
-// Numeric Entity Status Indicator (ESI) IDs. The Go server stamps one of
-// these u8 IDs on every entity in the AOI binary wire format. Visual
-// resolution (icon stem, border colour, bounce) is the C client's job and
-// arrives through the /api/cyberia-client-hints REST contract — NOT here.
 const StatusIconEntrySchema = new Schema(
   {
     id: { type: Number, required: true },
@@ -61,10 +24,9 @@ const StatusIconEntrySchema = new Schema(
 );
 
 // ── EconomyRulesSchema ───────────────────────────────────────────────────────
-// Mirrors the EconomyRules proto message and the economyRules sub-document in
-// cyberia-server-defaults.js.  All fields default from those canonical
-// values so a freshly created document is immediately playable.
-// See OFF_CHAIN_ECONOMY.md for the full Fountain & Sink architecture.
+// The EconomyRules message shape. Every field defaults from
+// cyberia-server-defaults.js, so a new document is playable at once.
+// See OFF_CHAIN_ECONOMY.md for the Fountain & Sink architecture.
 const EconomyRulesSchema = new Schema(
   {
     // ── Fountains ───────────────────────────────────────────────────────────
@@ -101,12 +63,12 @@ const EquipmentRulesSchema = new Schema(
 
 const SkillRulesSchema = new Schema(
   {
-    projectileSpawnChance: { type: Number, default: D.skillRules.projectileSpawnChance },
+    projectileSpawnChance: { type: Number, default: D.skillRules.projectileSpawnChance, min: 0, max: 1 },
     projectileLifetimeMs: { type: Number, default: D.skillRules.projectileLifetimeMs },
     projectileWidth: { type: Number, default: D.skillRules.projectileWidth },
     projectileHeight: { type: Number, default: D.skillRules.projectileHeight },
     projectileSpeedMultiplier: { type: Number, default: D.skillRules.projectileSpeedMultiplier },
-    doppelgangerSpawnChance: { type: Number, default: D.skillRules.doppelgangerSpawnChance },
+    doppelgangerSpawnChance: { type: Number, default: D.skillRules.doppelgangerSpawnChance, min: 0, max: 1 },
     doppelgangerLifetimeMs: { type: Number, default: D.skillRules.doppelgangerLifetimeMs },
     doppelgangerSpawnRadius: { type: Number, default: D.skillRules.doppelgangerSpawnRadius },
     doppelgangerInitialLifeFraction: { type: Number, default: D.skillRules.doppelgangerInitialLifeFraction },
@@ -115,12 +77,11 @@ const SkillRulesSchema = new Schema(
 );
 
 /**
- * Game server configuration for a Cyberia instance.
- * Separated from CyberiaInstance so the GUI never overwrites live server parameters
- * when editing instance identity / map-graph fields.
+ * Simulation configuration for a Cyberia instance. It is separate from
+ * CyberiaInstance so an edit to instance identity or map graph cannot
+ * overwrite live simulation parameters.
  *
- * Linked from CyberiaInstance.conf (ObjectId ref).
- * Looked up by instanceCode for CLI / gRPC use.
+ * Linked from CyberiaInstance.conf (ObjectId ref), looked up by instanceCode.
  */
 const CyberiaInstanceConfSchema = new Schema(
   {
@@ -151,7 +112,7 @@ const CyberiaInstanceConfSchema = new Schema(
     playerBaseSpeed: { type: Number, default: D.playerBaseSpeed },
     playerBaseLifeRegenMin: { type: Number, default: D.playerBaseLifeRegenMin },
     playerBaseLifeRegenMax: { type: Number, default: D.playerBaseLifeRegenMax },
-    sumStatsLimit: { type: Number, default: D.sumStatsLimit },
+    progressionRules: { type: ProgressionRulesSchema, default: D.progressionRules },
     maxActiveLayers: { type: Number, default: D.maxActiveLayers },
     initialLifeFraction: { type: Number, default: D.initialLifeFraction },
 
@@ -163,15 +124,26 @@ const CyberiaInstanceConfSchema = new Schema(
     // Fountain & Sink parameters. See EconomyRulesSchema and OFF_CHAIN_ECONOMY.md.
     economyRules: { type: EconomyRulesSchema },
 
-    // ── Regen ────────────────────────────────────────────────────────
-    lifeRegenChance: { type: Number, default: D.lifeRegenChance },
-    maxChance: { type: Number, default: D.maxChance },
-
-    // ── Entity type rendering defaults ───────────────────────────────
-    // Replaces flat fields: userDefaultItemId, botDefaultItemId, ghostItemId,
-    // coinItemId, defaultFloorItemId, weaponDefaultItemId.
-    // Each entry: { entityType, liveItemIds, deadItemIds, dropItemIds, colorKey }.
-    entityDefaults: { type: [EntityDefaultSchema], default: D.entityDefaults },
+    // ── Chances, as fractions of 1 ───────────────────────────────────
+    lifeRegenChance: { type: Number, default: D.lifeRegenChance, min: 0, max: 1 },
+    maxChance: { type: Number, default: D.maxChance, min: 0, max: 1 },
+
+    // ── Entity type defaults ─────────────────────────────────────────
+    // References into the CyberiaEntityTypeDefault collection, which owns the
+    // per-entity-type item wiring (live/dead/drop sets, seed inventory, behavior).
+    //
+    // A reference, never a copy. Embedding the documents here meant the same
+    // wiring existed twice — once in the collection, once inside every instance
+    // conf — and the two were reconciled by matching item ids, so two instances
+    // sharing a skin resolved into each other's defaults on import and export.
+    // An id names exactly one document, which is what makes that impossible.
+    //
+    // An empty list is not "no defaults": it means this instance adds nothing to
+    // the canonical ENTITY_TYPE_DEFAULTS, which every world resolves against.
+    entityDefaults: {
+      type: [{ type: Schema.Types.ObjectId, ref: 'CyberiaEntityTypeDefault' }],
+      default: D.entityDefaults,
+    },
 
     // ── Entity Status Indicators ────────────────────────────────────
     // Overhead icon mapping + per-status border colour.
@@ -179,9 +151,11 @@ const CyberiaInstanceConfSchema = new Schema(
     statusIcons: { type: [StatusIconEntrySchema], default: D.statusIcons },
 
     // ── Skill system ─────────────────────────────────────────────────
-    // Each entry maps a trigger item to an ordered list of logic handler keys.
-    // Spawning entities (e.g. projectiles) is handled inside the logic handler itself.
-    skillConfig: { type: [SkillConfigEntrySchema], default: [] },
+    // Which skills an instance runs is not stored: the CyberiaSkill collection owns the
+    // definitions, and an instance runs the ones whose trigger item its own content names.
+    // See collectInstanceItemIds / selectInstanceSkills (cyberia-instance-items.js). Storing
+    // the list here meant maintaining a second answer to that question, and the two disagreed —
+    // a trigger a quest asked for exported but never reached the simulation.
 
     // Numeric tuning parameters for each skill archetype.
     skillRules: { type: SkillRulesSchema },

package/src/api/cyberia-instance-conf/cyberia-instance-conf.service.js

@@ -1,11 +1,83 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/ops/logger.js';
 import { DataQuery } from '../../server/storage/data-query.js';
+import {
+  CYBERIA_INSTANCE_CONF_DEFAULTS,
+  fillInstanceConfDefaults,
+  resolveProgressionRules,
+} from '../cyberia-server-defaults/cyberia-server-defaults.js';
 
 const logger = loggerFactory(import.meta);
 
+const readPath = (object, path) => path.split('.').reduce((node, key) => (node == null ? undefined : node[key]), object);
+
+const writePath = (object, path, value) => {
+  const keys = path.split('.');
+  let node = object;
+  for (const key of keys.slice(0, -1)) {
+    if (node[key] == null || typeof node[key] !== 'object') node[key] = {};
+    node = node[key];
+  }
+  node[keys.at(-1)] = value;
+};
+
+/* The canonical default for a path, or for the nearest ancestor that has one: a value nested
+ * inside an array element has no default of its own, so the whole array falls back. */
+const defaultFor = (path) => {
+  const keys = path.split('.');
+  for (let depth = keys.length; depth > 0; depth--) {
+    const candidate = keys.slice(0, depth).join('.');
+    const value = readPath(CYBERIA_INSTANCE_CONF_DEFAULTS, candidate);
+    if (value !== undefined) return { path: candidate, value: structuredClone(value) };
+  }
+  return null;
+};
+
+const validationPaths = async (Model, conf) => {
+  try {
+    await new Model(conf).validate();
+    return [];
+  } catch (error) {
+    return Object.keys(error?.errors ?? {});
+  }
+};
+
 class CyberiaInstanceConfService {
+  /**
+   * Makes a conf whole and valid: fills every missing field, then resets every field the schema
+   * rejects to its canonical default.
+   *
+   * A backup written before a bound tightened, or edited by hand, must still round-trip: the
+   * world it describes is worth more than one stale number in it, and resetting that number is
+   * what an operator would do by hand. Each reset is logged by path so the decision is visible.
+   * A default the schema itself rejects is a code fault, not bad data, and still throws.
+   *
+   * @param {object} conf - Conf as read from a backup or from the database.
+   * @param {import('mongoose').Model} CyberiaInstanceConf - The model whose schema decides.
+   * @returns {Promise<{conf: object, resets: Array<{path: string, from: unknown, to: unknown}>}>}
+   */
+  static async coerceToSchema(conf, CyberiaInstanceConf) {
+    const out = fillInstanceConfDefaults(conf);
+    const resets = [];
+    // One pass resets the rejected paths; the second proves the defaults themselves pass.
+    for (let pass = 0; pass < 2; pass++) {
+      const failing = await validationPaths(CyberiaInstanceConf, out);
+      if (failing.length === 0) return { conf: out, resets };
+      if (pass === 1) throw new Error(`CyberiaInstanceConf defaults fail validation at: ${failing.join(', ')}`);
+      for (const path of failing) {
+        const fallback = defaultFor(path);
+        if (!fallback) throw new Error(`CyberiaInstanceConf has no default to reset "${path}" to`);
+        const from = readPath(out, fallback.path);
+        writePath(out, fallback.path, fallback.value);
+        resets.push({ path: fallback.path, from, to: fallback.value });
+        logger.warn(`CyberiaInstanceConf "${fallback.path}" reset to default`, { from, to: fallback.value });
+      }
+    }
+    return { conf: out, resets };
+  }
+
   static post = async (req, res, options) => {
+    if (Object.hasOwn(req.body, 'progressionRules')) req.body.progressionRules = resolveProgressionRules(req.body.progressionRules);
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
     const CyberiaInstanceConf =
       DataBaseProviderService.getModel("CyberiaInstanceConf", options);
@@ -29,10 +101,11 @@ class CyberiaInstanceConfService {
     return { data, total, page, totalPages };
   };
   static put = async (req, res, options) => {
+    if (Object.hasOwn(req.body, 'progressionRules')) req.body.progressionRules = resolveProgressionRules(req.body.progressionRules);
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */
     const CyberiaInstanceConf =
       DataBaseProviderService.getModel("CyberiaInstanceConf", options);
-    return await CyberiaInstanceConf.findByIdAndUpdate(req.params.id, req.body);
+    return await CyberiaInstanceConf.findByIdAndUpdate(req.params.id, req.body, { runValidators: true });
   };
   static delete = async (req, res, options) => {
     /** @type {import('./cyberia-instance-conf.model.js').CyberiaInstanceConfModel} */

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

@@ -28,7 +28,9 @@ class CyberiaMapService {
       return { codes };
     }
 
-    if (req.params.id) return await CyberiaMap.findById(req.params.id).populate(populateCreator);
+    // Maps are addressed by code, the key the engine navigates by.
+    if (req.params.id)
+      return await CyberiaMap.findOne(DataQuery.naturalKeyFilter('code', req.params.id)).populate(populateCreator);
 
     // Parse query parameters using DataQuery helper
     const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
@@ -48,6 +50,8 @@ class CyberiaMapService {
     if (!map) throw new Error('map not found');
     if (req.auth.user.role !== 'admin' && String(map.creator) !== String(req.auth.user._id))
       throw new Error('insufficient permission');
+    const candidate = new CyberiaMap({ ...map.toObject(), ...req.body });
+    await candidate.validate();
     const File = DataBaseProviderService.getModel("File", options);
     if (req.body.thumbnail && map.thumbnail && String(req.body.thumbnail) !== String(map.thumbnail)) {
       await File.findByIdAndDelete(map.thumbnail);
@@ -55,7 +59,7 @@ class CyberiaMapService {
     if (req.body.preview && map.preview && String(req.body.preview) !== String(map.preview)) {
       await File.findByIdAndDelete(map.preview);
     }
-    return await CyberiaMap.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
+    return await CyberiaMap.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after', runValidators: true });
   };
   static delete = async (req, res, options) => {
     /** @type {import('./cyberia-map.model.js').CyberiaMapModel} */

package/src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.controller.js

@@ -0,0 +1,31 @@
+import {
+  buildCrudController,
+  controllerHandler,
+  sendSuccess,
+  setCrossOriginHeaders,
+} from '../../server/network/middlewares.js';
+import { CyberiaMapAudioConfService } from './cyberia-map-audio-conf.service.js';
+
+const context = (options) => ({ host: options.host || 'default', path: options.path || '/' });
+
+const CyberiaMapAudioConfController = buildCrudController(CyberiaMapAudioConfService, {
+  // Read by map code: the browser client's own path into this API, so it carries the same
+  // public-read cross-origin policy the generated CRUD reads do.
+  getByMapCode: controllerHandler(
+    async (req, res, options) => {
+      setCrossOriginHeaders(req, res);
+      return sendSuccess(res, await CyberiaMapAudioConfService.getByMapCode(req.params.mapCode, context(options)));
+    },
+    { errorStatus: 500 },
+  ),
+  assign: controllerHandler(
+    async (req, res, options) =>
+      sendSuccess(
+        res,
+        await CyberiaMapAudioConfService.assign({ ...req.body, mapCode: req.params.mapCode }, context(options)),
+      ),
+    { errorStatus: 400 },
+  ),
+});
+
+export { CyberiaMapAudioConfController };

package/src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.model.js

@@ -0,0 +1,56 @@
+import { Schema, model } from 'mongoose';
+import { AUDIO_BUSES } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+
+// Omitted fields inherit client or map defaults.
+const AudioSettingsSchema = new Schema(
+  {
+    bus: { type: String, enum: AUDIO_BUSES },
+    volume: { type: Number, min: 0, max: 1 },
+    loop: { type: Boolean },
+    crossfadeMs: { type: Number, min: 0, max: 10000 },
+    pitch: { type: Number, min: 0.25, max: 4 },
+    pan: { type: Number, min: 0, max: 1 },
+    priority: { type: Number, min: 0, max: 255, validate: Number.isInteger },
+  },
+  { _id: false },
+);
+
+const EventAudioSchema = new Schema(
+  {
+    logicEventId: { type: String, required: true, trim: true },
+    audioCode: { type: String, required: true, trim: true },
+    settings: { type: AudioSettingsSchema, default: () => ({}) },
+  },
+  { _id: false },
+);
+
+const CyberiaMapAudioConfSchema = new Schema(
+  {
+    // CyberiaMap.code. One audio configuration per map.
+    mapCode: { type: String, required: true, trim: true },
+
+    // CyberiaAudio.code played while no event binding is active.
+    defaultMusic: { type: String, default: '', trim: true },
+
+    // Logic-event bindings, merged by logicEventId.
+    events: { type: [EventAudioSchema], default: [] },
+
+    // Map-wide defaults. A binding's own settings override these.
+    settings: { type: AudioSettingsSchema, default: () => ({}) },
+  },
+  { timestamps: true },
+);
+
+CyberiaMapAudioConfSchema.index({ mapCode: 1 }, { unique: true });
+
+const CyberiaMapAudioConfModel = model('CyberiaMapAudioConf', CyberiaMapAudioConfSchema);
+
+const ProviderSchema = CyberiaMapAudioConfSchema;
+
+export {
+  AudioSettingsSchema,
+  CyberiaMapAudioConfModel,
+  CyberiaMapAudioConfSchema,
+  EventAudioSchema,
+  ProviderSchema,
+};

package/src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.router.js

@@ -0,0 +1,33 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
+import { moderatorGuard } from '../../server/security/auth.js';
+import { CyberiaMapAudioConfController } from './cyberia-map-audio-conf.controller.js';
+
+class CyberiaMapAudioConfRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+
+    // Map-code routes are registered before the CRUD routes: the generic `/:id`
+    // handlers capture every single-segment path once they are mounted.
+    router.get(
+      '/map-code/:mapCode',
+      async (req, res) => await CyberiaMapAudioConfController.getByMapCode(req, res, options),
+    );
+    router.post(
+      '/map-code/:mapCode',
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaMapAudioConfController.assign(req, res, options),
+    );
+
+    return registerCrudRoutes(router, CyberiaMapAudioConfController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaMapAudioConfRouter.router(options);
+
+export { ApiRouter, CyberiaMapAudioConfRouter };

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

@@ -0,0 +1,189 @@
+/**
+ * @module src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.service.js
+ * @namespace CyberiaMapAudioConfServiceServer
+ */
+
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { DataQuery } from '../../server/storage/data-query.js';
+
+const logger = loggerFactory(import.meta);
+
+// Resolved per call, not per module: reading a configuration must not require the
+// caller to have loaded the cyberia-audio model it never touches.
+const getConfModel = (options) => DataBaseProviderService.getModel('CyberiaMapAudioConf', options);
+const getAudioModel = (options) => DataBaseProviderService.getModel('CyberiaAudio', options);
+
+/**
+ * Parses a `<logic-event-id>:<audio-code>` binding as accepted by the CLI's `--set-event` flag.
+ * The separator is the first colon, so an audio code may contain one.
+ *
+ * @param {string} value - Raw flag value.
+ * @returns {{logicEventId: string, audioCode: string}} Parsed binding.
+ * @throws {Error} When either side of the separator is empty.
+ */
+const parseEventAudioBinding = (value) => {
+  const separator = `${value ?? ''}`.indexOf(':');
+  const logicEventId = separator === -1 ? '' : `${value}`.slice(0, separator).trim();
+  const audioCode = separator === -1 ? '' : `${value}`.slice(separator + 1).trim();
+  if (!logicEventId || !audioCode) throw new Error(`Expected <logic-event-id>:<audio-code>, received "${value}"`);
+  return { logicEventId, audioCode };
+};
+
+/**
+ * Merges incoming bindings into the ones a map already carries, keyed by logic event.
+ *
+ * Naming an event replaces that binding and leaves the rest in place, so a CLI call configures
+ * what it mentions and nothing else.
+ *
+ * @param {Array<{logicEventId: string}>} current - Bindings already stored.
+ * @param {Array<{logicEventId: string}>} incoming - Bindings being assigned.
+ * @returns {Array<object>} The merged list, in stored-then-new order.
+ */
+const mergeEventBindings = (current = [], incoming = []) => {
+  const merged = [...current];
+  for (const binding of incoming) {
+    const index = merged.findIndex((entry) => entry.logicEventId === binding.logicEventId);
+    if (index === -1) merged.push(binding);
+    else {
+      const settings = binding.settings ?? merged[index].settings;
+      merged[index] = { ...binding, ...(settings ? { settings } : {}) };
+    }
+  }
+  return merged;
+};
+
+/** Accepts a bare asset code or an object carrying one. */
+const readAudioCode = (input) => {
+  if (input === null || input === undefined || input === '') return '';
+  const code = typeof input === 'string' ? input : input.audioCode ?? input.code;
+  if (!code) throw new Error('Missing audio asset code');
+  return `${code}`.trim();
+};
+
+class CyberiaMapAudioConfService {
+  /**
+   * Asserts that an imported cyberia-audio asset carries this code.
+   *
+   * The code is the whole reference a binding stores, so this is where referential integrity is
+   * enforced: an unimported asset is refused rather than written as a dangling name. Nothing is
+   * copied out of the asset — the binding needs no more of it than its identity.
+   *
+   * @param {string} audioCode - CyberiaAudio.code.
+   * @param {{host: string, path: string}} options - Provider context.
+   * @returns {Promise<string>} The same code, once it is known to resolve.
+   * @throws {Error} When no imported cyberia-audio document carries that code.
+   */
+  static assertAudioCode = async (audioCode, options) => {
+    const exists = await getAudioModel(options).exists({ code: audioCode });
+    if (!exists) {
+      throw new Error(`Unknown audio asset "${audioCode}" — import it first with: cyberia audio ${audioCode} --import`);
+    }
+    return audioCode;
+  };
+
+  /**
+   * Fetches the audio configuration of a single map.
+   * @param {string} mapCode - CyberiaMap code.
+   * @param {{host: string, path: string}} options - Provider context.
+   * @returns {Promise<object|null>} Configuration document, or null when the map has none.
+   */
+  static getByMapCode = async (mapCode, options) => {
+    return await getConfModel(options).findOne({ mapCode }).lean();
+  };
+
+  /**
+   * Bulk-assigns map audio rules, upserting the map's configuration document.
+   *
+   * Two callers with two intents share this: the CLI amends one binding at a time and must leave
+   * the others alone, while a seed states the whole configuration and must converge on it —
+   * otherwise a binding whose logic event was renamed or dropped lives on forever, and the client
+   * keeps asking for an asset nothing declares any more. `replaceEvents` is which of the two
+   * this call is.
+   *
+   * @param {Object} rules - Assignment payload.
+   * @param {string} rules.mapCode - Target CyberiaMap code.
+   * @param {string|null} [rules.defaultMusic] - Default music asset code, or '' / null to clear it.
+   * @param {Array<{logicEventId: string, audioCode: string, settings?: object}>} [rules.events] - Bindings.
+   * @param {boolean} [rules.replaceEvents=false] - Make `events` the map's complete binding set.
+   * @param {object} [rules.settings] - Map-wide volume/loop/crossfade defaults.
+   * @param {{host: string, path: string}} options - Provider context.
+   * @returns {Promise<object>} The updated configuration document.
+   */
+  static assign = async ({ mapCode, defaultMusic, events = [], replaceEvents = false, settings }, options) => {
+    if (!mapCode) throw new Error('mapCode is required to assign map audio rules');
+    const CyberiaMapAudioConf = getConfModel(options);
+
+    const bindings = await Promise.all(
+      events.map(async ({ logicEventId, settings: entrySettings, ...reference }) => {
+        if (!logicEventId) throw new Error(`Missing logicEventId for an audio binding on map "${mapCode}"`);
+        return {
+          logicEventId: `${logicEventId}`.trim(),
+          audioCode: await CyberiaMapAudioConfService.assertAudioCode(readAudioCode(reference), options),
+          ...(entrySettings ? { settings: entrySettings } : {}),
+        };
+      }),
+    );
+
+    const defaultMusicCode = defaultMusic === undefined ? undefined : readAudioCode(defaultMusic);
+    if (defaultMusicCode) await CyberiaMapAudioConfService.assertAudioCode(defaultMusicCode, options);
+
+    const conf = (await CyberiaMapAudioConf.findOne({ mapCode })) || new CyberiaMapAudioConf({ mapCode });
+
+    if (defaultMusicCode !== undefined) conf.defaultMusic = defaultMusicCode;
+    if (settings) conf.settings = { ...(conf.settings?.toObject?.() ?? conf.settings ?? {}), ...settings };
+
+    const dropped = replaceEvents
+      ? (conf.events ?? [])
+          .map(({ logicEventId }) => logicEventId)
+          .filter((logicEventId) => !bindings.some((binding) => binding.logicEventId === logicEventId))
+      : [];
+    if (replaceEvents) conf.events = bindings;
+    else if (bindings.length > 0) conf.events = mergeEventBindings(conf.events, bindings);
+
+    await conf.save();
+    logger.info(`Assigned map audio rules for "${mapCode}"`, {
+      defaultMusic: conf.defaultMusic || null,
+      events: conf.events.length,
+      ...(dropped.length > 0 ? { dropped } : {}),
+    });
+    return conf;
+  };
+
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-map-audio-conf.model.js').CyberiaMapAudioConfModel} */
+    const CyberiaMapAudioConf = DataBaseProviderService.getModel('CyberiaMapAudioConf', options);
+    return await new CyberiaMapAudioConf(req.body).save();
+  };
+
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-map-audio-conf.model.js').CyberiaMapAudioConfModel} */
+    const CyberiaMapAudioConf = DataBaseProviderService.getModel('CyberiaMapAudioConf', options);
+    if (req.params.id) return await CyberiaMapAudioConf.findById(req.params.id);
+
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaMapAudioConf.find(query).sort(sort).limit(limit).skip(skip),
+      CyberiaMapAudioConf.countDocuments(query),
+    ]);
+
+    const totalPages = Math.ceil(total / limit);
+    return { data, total, page, totalPages };
+  };
+
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-map-audio-conf.model.js').CyberiaMapAudioConfModel} */
+    const CyberiaMapAudioConf = DataBaseProviderService.getModel('CyberiaMapAudioConf', options);
+    return await CyberiaMapAudioConf.findByIdAndUpdate(req.params.id, req.body);
+  };
+
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-map-audio-conf.model.js').CyberiaMapAudioConfModel} */
+    const CyberiaMapAudioConf = DataBaseProviderService.getModel('CyberiaMapAudioConf', options);
+    if (req.params.id) return await CyberiaMapAudioConf.findByIdAndDelete(req.params.id);
+    else return await CyberiaMapAudioConf.deleteMany();
+  };
+}
+
+export { CyberiaMapAudioConfService, mergeEventBindings, parseEventAudioBinding };

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

@@ -9,10 +9,10 @@ class CyberiaQuestRouter {
    */
   static router(options) {
     const router = express.Router();
-    // Direct lookup by code — C client fetches quest metadata by code.
+    // Direct lookup of quest metadata by code.
     router.get(`/code/:code`, async (req, res) => await CyberiaQuestController.getByCode(req, res, options));
-    // Quest offers located by binding cell — C client resolves the Quest tab from
-    // here using the interacted entity's cell, decoupled from CyberiaAction.
+    // Quest offers by binding cell. The client resolves its Quest tab from the
+    // interacted entity's cell, with no CyberiaAction lookup.
     router.get(
       `/cell/:mapCode/:cellX/:cellY`,
       async (req, res) => await CyberiaQuestController.getByCell(req, res, options),

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

@@ -50,9 +50,9 @@ class CyberiaQuestService {
     if (!code) throw new Error('code parameter is required');
     const data = await CyberiaQuest.findOne({ code }).lean();
     if (data) return data;
-    // Fallback world delivers quests to the Go server via gRPC from the
-    // canonical defaults without persisting them. Serve those same defaults so
-    // the client can resolve metadata even when Mongo has no seeded quest.
+    // The fallback world serves quests from the canonical defaults and never
+    // persists them. Serve the same defaults, so the client resolves metadata
+    // with no seeded quest in Mongo.
     const fallback = DefaultCyberiaQuests.find((q) => q.code === code);
     if (fallback) return fallback;
     throw new Error(`No quest found for code: ${code}`);

package/src/api/cyberia-quest-progress/cyberia-quest-progress.model.js

@@ -4,7 +4,7 @@ import { Schema, model } from 'mongoose';
 
 const CyberiaQuestProgressSchema = new Schema(
   {
-    // Matches the Go relay server's player UUID
+    // Matches the simulation server's player UUID
     playerId: { type: String, required: true, trim: true },
     // References CyberiaQuest.code
     questCode: { type: String, required: true, trim: true },