@underpostnet/cyberia 3.3.0 → 3.3.76

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

@@ -0,0 +1,61 @@
+/**
+ * One audio asset: what it is, never when it plays.
+ *
+ * The asset carries its identity (`code`), its bytes (`fileId`) and the manifest the recorder
+ * wrote beside them. It holds no classification of its own: whether a sound behaves as a bed, a
+ * one-shot or a transition is a property of the context that binds it — see
+ * cyberia-map-audio-conf — not of the asset, which the same map or several maps may reuse.
+ *
+ * @module src/api/cyberia-audio/cyberia-audio.model.js
+ * @namespace CyberiaAudioModelServer
+ */
+
+import { Schema, model } from 'mongoose';
+
+// https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
+
+// Mirrors the `<name-out>.json` manifest the cyberia-audio package writes beside every recorded
+// WAV. `defaults` and `parameters` are the asset's own parameter contract, so they stay
+// free-form: each asset owns its parameter names and ranges.
+const ManifestSchema = new Schema(
+  {
+    id: { type: String, required: true },
+    // The bus the module was authored on — `src/audio-module/<bus-id>/` in the cyberia-audio
+    // package, and the same vocabulary a binding's `settings.bus` selects. It is the asset's
+    // natural route, not a decision: a map binding chooses where an asset actually plays.
+    bus: { type: String, default: '', trim: true },
+    tags: [{ type: String }],
+    author: { type: String, required: true },
+    version: { type: String, required: true },
+    duration: { type: Number, required: true },
+    sampleRate: { type: Number },
+    channels: { type: Number },
+    loop: { type: Boolean, default: false },
+    audio: { type: String, default: '' },
+    defaults: { type: Schema.Types.Mixed, default: {} },
+    parameters: { type: Schema.Types.Mixed, default: {} },
+  },
+  { _id: false },
+);
+
+const CyberiaAudioSchema = new Schema(
+  {
+    // The asset's canonical identity across the platform: what a map binding, an import and an
+    // export all refer to. It is unique on its own, so a reference needs nothing beside it.
+    code: { type: String, required: true, trim: true },
+    fileId: { type: Schema.Types.ObjectId, ref: 'File' },
+    manifest: { type: ManifestSchema, required: true },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+// Declared here rather than as `index: true` on the field, so the unique index is defined once.
+CyberiaAudioSchema.index({ code: 1 }, { unique: true });
+
+const CyberiaAudioModel = model('CyberiaAudio', CyberiaAudioSchema);
+
+const ProviderSchema = CyberiaAudioSchema;
+
+export { CyberiaAudioSchema, CyberiaAudioModel, ProviderSchema };

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

@@ -0,0 +1,21 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
+import { CyberiaAudioController } from './cyberia-audio.controller.js';
+
+class CyberiaAudioRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    // Fully unguarded (matches prior behavior).
+    return registerCrudRoutes(express.Router(), CyberiaAudioController, options, {
+      writeGuards: [],
+      deleteAllGuards: [],
+    });
+  }
+}
+
+const ApiRouter = (options) => CyberiaAudioRouter.router(options);
+
+export { ApiRouter, CyberiaAudioRouter };

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

@@ -1,4 +1,4 @@
-import { controllerHandler, sendSuccess } from '../../server/middlewares.js';
+import { controllerHandler, sendSuccess } from '../../server/network/middlewares.js';
 import { CYBERIA_CLIENT_HINTS_DEFAULTS } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { resolveClientHints } from './cyberia-client-hints.service.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,44 +1,26 @@
 /**
  * @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';
-import { crossOriginMiddleware } from '../../server/middlewares.js';
+import { crossOriginMiddleware } from '../../server/network/middlewares.js';
 import { CyberiaClientHintsController } from './cyberia-client-hints.controller.js';
 
 class CyberiaClientHintsRouter {
@@ -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,27 +3,19 @@
  *
  * 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';
-import { loggerFactory } from '../../server/logger.js';
-import { resolveHostKeyContext } from '../../server/conf.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { resolveHostKeyContext } from '../../server/runtime/conf.js';
 import {
   buildClientHints,
   CYBERIA_CLIENT_HINTS_DEFAULTS,
@@ -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.controller.js

@@ -1,4 +1,4 @@
-import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { buildCrudController, serviceHandler } from '../../server/network/middlewares.js';
 import { CyberiaDialogueService } from './cyberia-dialogue.service.js';
 
 const CyberiaDialogueController = buildCrudController(CyberiaDialogueService, {

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

@@ -1,5 +1,5 @@
 import express from 'express';
-import { registerCrudRoutes } from '../../server/middlewares.js';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
 import { CyberiaDialogueController } from './cyberia-dialogue.controller.js';
 
 class CyberiaDialogueRouter {
@@ -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-dialogue/cyberia-dialogue.service.js

@@ -1,6 +1,6 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { loggerFactory } from '../../server/logger.js';
-import { DataQuery } from '../../server/data-query.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { DataQuery } from '../../server/storage/data-query.js';
 import { DefaultCyberiaDialogues } from '../cyberia-server-defaults/cyberia-server-defaults.js';
 
 const logger = loggerFactory(import.meta);

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

@@ -1,4 +1,4 @@
-import { buildCrudController } from '../../server/middlewares.js';
+import { buildCrudController } from '../../server/network/middlewares.js';
 import { CyberiaEntityService } from './cyberia-entity.service.js';
 
 const CyberiaEntityController = buildCrudController(CyberiaEntityService);

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.router.js

@@ -1,5 +1,5 @@
 import express from 'express';
-import { registerCrudRoutes } from '../../server/middlewares.js';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
 import { CyberiaEntityController } from './cyberia-entity.controller.js';
 
 class CyberiaEntityRouter {

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

@@ -1,6 +1,6 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { loggerFactory } from '../../server/logger.js';
-import { DataQuery } from '../../server/data-query.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { DataQuery } from '../../server/storage/data-query.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -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} */