@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/projects/cyberia/atlas-sprite-sheet-store.js

@@ -0,0 +1,391 @@
+/**
+ * Persistence for the atlas sprite sheet of one object layer item.
+ *
+ * Owns the AtlasSpriteSheet document, the File blobs it points at, and the
+ * IPFS pins of the atlas PNG and its metadata. Every writer — the REST service
+ * and the Cyberia CLI — goes through here, so one item key always resolves to
+ * one atlas.
+ *
+ * @module src/projects/cyberia/atlas-sprite-sheet-store.js
+ * @namespace CyberiaAtlasSpriteSheetStore
+ */
+
+import crypto from 'crypto';
+import { Types } from 'mongoose';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { createPinRecord } from '../../api/ipfs/ipfs.service.js';
+import { FileFactory } from '../../api/file/file.service.js';
+import { deleteOwnedFiles, documentFileIds, fileRefFields } from '../../api/file/file.ref.js';
+import { AtlasSpriteSheetGenerator, DEFAULT_ATLAS_UPSCALE_FACTOR } from './atlas-sprite-sheet-generator.js';
+import { IpfsClient } from './ipfs-client.js';
+
+const logger = loggerFactory(import.meta);
+
+/** The File-referencing fields of this model, read from the registry that owns that mapping. */
+export const ATLAS_FILE_FIELDS = fileRefFields('atlas-sprite-sheet');
+
+/**
+ * The File `name` an atlas render is written under, as {@link upsertRenderFile} spells it.
+ * A prune reads it to recognise a render whose atlas is already gone.
+ * @constant {RegExp}
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const ATLAS_RENDER_NAME = /-(atlas|minify|idle)\.png$/;
+
+/**
+ * MFS paths of the IPFS content an item key owns.
+ * @param {string} itemKey - Object layer item id.
+ * @returns {{ png: string, metadata: string }}
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+export const atlasMfsPaths = (itemKey) => ({
+  png: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
+  metadata: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
+});
+
+/**
+ * The File `_id` a render resolves through, derived from the item key, the render
+ * role and the bytes themselves.
+ *
+ * Content-addressed on purpose: identical bytes re-derive the same id, which makes
+ * a rerun a no-op instead of a churn of File documents. Changed bytes land on a new
+ * id, and the writer deletes the one it replaced.
+ *
+ * @param {string} itemKey - Object layer item id.
+ * @param {string} role - Render role: `atlas`, `minify` or `idle`.
+ * @param {string} md5 - Hex MD5 of the PNG bytes.
+ * @returns {import('mongoose').Types.ObjectId}
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const atlasFileId = (itemKey, role, md5) =>
+  new Types.ObjectId(crypto.createHash('sha256').update(`atlas:${itemKey}:${role}:${md5}`).digest('hex').slice(0, 24));
+
+/**
+ * Writes a PNG render to the File collection under its content-addressed id.
+ * Re-writing the same bytes returns the stored document untouched.
+ *
+ * @param {Object} File - Mongoose File model.
+ * @param {string} itemKey - Object layer item id.
+ * @param {string} role - Render role: `atlas`, `minify` or `idle`.
+ * @param {Buffer} buffer - PNG bytes.
+ * @returns {Promise<import('mongoose').Types.ObjectId>} The File id.
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const upsertRenderFile = async (File, itemKey, role, buffer) => {
+  const payload = FileFactory.create(buffer, `${itemKey}-${role}.png`);
+  const _id = atlasFileId(itemKey, role, payload.md5);
+  await File.updateOne({ _id }, { $setOnInsert: { ...payload, _id } }, { upsert: true });
+  return _id;
+};
+
+/**
+ * Writes the idle-preview still cut from a human-resolution render, or returns null
+ * for an atlas with no frame to cut.
+ *
+ * @param {Object} File - Mongoose File model.
+ * @param {string} itemKey - Object layer item id.
+ * @param {Buffer} buffer - PNG bytes of the human-resolution render.
+ * @param {Object} metadata - Atlas metadata describing that render's layout.
+ * @returns {Promise<import('mongoose').Types.ObjectId|null>}
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const upsertIdlePreview = async (File, itemKey, buffer, metadata) => {
+  const still = await AtlasSpriteSheetGenerator.idlePreviewFromAtlas(buffer, metadata);
+  return still ? await upsertRenderFile(File, itemKey, 'idle', still) : null;
+};
+
+/**
+ * Deletes the File documents an atlas no longer points at.
+ *
+ * @param {Object} File - Mongoose File model.
+ * @param {Array<import('mongoose').Types.ObjectId>} previousIds - File ids held before the write.
+ * @param {Array<import('mongoose').Types.ObjectId>} currentIds - File ids held after the write.
+ * @returns {Promise<void>}
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const deleteReplacedFiles = async (File, previousIds, currentIds) => {
+  const kept = new Set(currentIds.filter(Boolean).map(String));
+  const replaced = [...new Set(previousIds.filter(Boolean).map(String))].filter((id) => !kept.has(id));
+  if (replaced.length === 0) return;
+  await File.deleteMany({ _id: { $in: replaced } });
+  logger.info(`Removed ${replaced.length} replaced atlas File document(s)`);
+};
+
+/**
+ * Pins a payload to IPFS and records it in the registry. A failure is logged and
+ * yields an empty CID, so a missing IPFS node never blocks a write.
+ *
+ * @param {Object} params
+ * @param {function(): Promise<{cid: string}|null>} params.add - The IpfsClient call.
+ * @param {string} params.resourceType - Registry category.
+ * @param {string} params.mfsPath - MFS path of the payload.
+ * @param {Object} [params.options] - Router options ({ host, path }).
+ * @returns {Promise<string>} The CID, or an empty string.
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const pin = async ({ add, resourceType, mfsPath, options }) => {
+  try {
+    const result = await add();
+    if (!result) return '';
+    await createPinRecord({ cid: result.cid, resourceType, mfsPath, options });
+    logger.info(`Pinned ${resourceType} – CID: ${result.cid}`);
+    return result.cid;
+  } catch (error) {
+    logger.warn(`Failed to pin ${resourceType}: ${error.message}`);
+    return '';
+  }
+};
+
+/**
+ * Tells whether two atlas layouts place every frame at the same cell.
+ *
+ * @param {Object} left - Atlas metadata.
+ * @param {Object} right - Atlas metadata.
+ * @returns {boolean}
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+const sameLayout = (left, right) => {
+  if (left.atlasWidth !== right.atlasWidth || left.atlasHeight !== right.atlasHeight) return false;
+  const box = (frame) => (frame ? `${frame.x},${frame.y},${frame.width},${frame.height}` : '');
+  const directions = new Set([...Object.keys(left.frames ?? {}), ...Object.keys(right.frames ?? {})]);
+  for (const direction of directions) {
+    const leftFrames = left.frames?.[direction] ?? [];
+    const rightFrames = right.frames?.[direction] ?? [];
+    if (leftFrames.length !== rightFrames.length) return false;
+    for (let index = 0; index < leftFrames.length; index++) {
+      if (box(leftFrames[index]) !== box(rightFrames[index])) return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Atlas sprite sheet persistence, keyed by object layer item id.
+ * @class AtlasSpriteSheetStore
+ * @memberof CyberiaAtlasSpriteSheetStore
+ */
+export class AtlasSpriteSheetStore {
+  /**
+   * Generates both renders of an item's atlas and stores them.
+   *
+   * The write is keyed by `metadata.itemKey`, so a rerun updates the same
+   * document. Renders whose bytes did not change keep their File documents;
+   * renders that changed replace them and the old ones are deleted.
+   *
+   * @static
+   * @param {Object} params
+   * @param {string} params.itemKey - Object layer item id.
+   * @param {Object} params.objectLayerRenderFrames - Render frames, document or plain object.
+   * @param {number} [params.upscaleFactor=DEFAULT_ATLAS_UPSCALE_FACTOR] - Pixels per cell of the human-resolution render.
+   * @param {number} [params.maxAtlasDim=null] - Maximum atlas dimension, auto-calculated when null.
+   * @param {Object} [params.options] - Router options ({ host, path }) for model lookup.
+   * @returns {Promise<{atlasDoc: Object, metadata: Object, atlasCid: string, atlasMetadataCid: string}>}
+   *   `metadata` is the plain generated layout, free of the document wrapper a caller would have to unwrap.
+   * @memberof CyberiaAtlasSpriteSheetStore
+   */
+  static async persist({
+    itemKey,
+    objectLayerRenderFrames,
+    upscaleFactor = DEFAULT_ATLAS_UPSCALE_FACTOR,
+    maxAtlasDim = null,
+    options,
+  }) {
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    const File = DataBaseProviderService.getModel('File', options);
+
+    const { buffer, minifyBuffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+      objectLayerRenderFrames,
+      itemKey,
+      upscaleFactor,
+      maxAtlasDim,
+    );
+
+    const fileId = await upsertRenderFile(File, itemKey, 'atlas', buffer);
+    const minifyFileId = await upsertRenderFile(File, itemKey, 'minify', minifyBuffer);
+    const idlePreviewFileId = await upsertIdlePreview(File, itemKey, buffer, metadata);
+
+    const mfsPaths = atlasMfsPaths(itemKey);
+    const atlasCid = await pin({
+      add: () => IpfsClient.addBufferToIpfs(buffer, `${itemKey}_atlas_sprite_sheet.png`, mfsPaths.png),
+      resourceType: 'atlas-sprite-sheet',
+      mfsPath: mfsPaths.png,
+      options,
+    });
+    const atlasMetadataCid = await pin({
+      add: () => IpfsClient.addJsonToIpfs(metadata, `${itemKey}_atlas_sprite_sheet_metadata.json`, mfsPaths.metadata),
+      resourceType: 'atlas-metadata',
+      mfsPath: mfsPaths.metadata,
+      options,
+    });
+
+    let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+    const previousFileIds = atlasDoc ? ATLAS_FILE_FIELDS.map((field) => atlasDoc[field]) : [];
+
+    const renders = { fileId, minifyFileId, idlePreviewFileId };
+    if (atlasDoc) {
+      atlasDoc.set({ ...renders, cid: atlasCid, metadata });
+      await atlasDoc.save();
+    } else {
+      atlasDoc = await new AtlasSpriteSheet({ ...renders, cid: atlasCid, metadata }).save();
+    }
+
+    await deleteReplacedFiles(File, previousFileIds, Object.values(renders));
+
+    return { atlasDoc, metadata, atlasCid, atlasMetadataCid };
+  }
+
+  /**
+   * Removes atlases and everything they own: every File render they point at, and
+   * the documents themselves.
+   *
+   * The one place a caller deletes an atlas, because an atlas owns more than its
+   * document: a drop that took `fileId` and left `minifyFileId` behind is what put
+   * unreachable renders in the File collection. Rerunnable — a second call finds
+   * nothing and reports zeros.
+   *
+   * @static
+   * @param {Object} params
+   * @param {string[]} [params.itemKeys] - Item keys to purge.
+   * @param {Array<*>} [params.atlasIds] - Atlas document ids to purge, for a caller holding the link rather than the key.
+   * @param {boolean} [params.all=false] - Purge the whole collection, ignoring both selectors.
+   * @param {Object} [params.options] - Router options ({ host, path }) for model lookup.
+   * @returns {Promise<{atlases: number, files: number, cids: string[]}>} What was removed, and the CIDs the caller still has to unpin.
+   * @memberof CyberiaAtlasSpriteSheetStore
+   */
+  static async purge({ itemKeys = [], atlasIds = [], all = false, options }) {
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    const File = DataBaseProviderService.getModel('File', options);
+
+    const clauses = [];
+    if (itemKeys.length > 0) clauses.push({ 'metadata.itemKey': { $in: itemKeys } });
+    if (atlasIds.length > 0) clauses.push({ _id: { $in: atlasIds } });
+    if (!all && clauses.length === 0) return { atlases: 0, files: 0, cids: [] };
+    const selector = all ? {} : clauses.length === 1 ? clauses[0] : { $or: clauses };
+
+    const docs = await AtlasSpriteSheet.find(
+      selector,
+      Object.fromEntries([...ATLAS_FILE_FIELDS, 'cid'].map((field) => [field, 1])),
+    ).lean();
+    if (docs.length === 0) return { atlases: 0, files: 0, cids: [] };
+
+    const fileIds = documentFileIds(docs, ATLAS_FILE_FIELDS);
+    const cids = [...new Set(docs.map((doc) => doc.cid).filter(Boolean))];
+
+    // Documents first: the survivors this reads decide which renders are still
+    // reachable, so the ones being dropped must already be gone.
+    const { deletedCount } = await AtlasSpriteSheet.deleteMany({ _id: { $in: docs.map((doc) => doc._id) } });
+    const files = await deleteOwnedFiles({ File, Owner: AtlasSpriteSheet, fields: ATLAS_FILE_FIELDS, ids: fileIds });
+
+    return { atlases: deletedCount ?? 0, files, cids };
+  }
+
+  /**
+   * Deletes atlas renders no atlas document points at any more.
+   *
+   * The repair for what an earlier drop left behind: candidates are recognised by
+   * the name the writer gives a render, and a candidate a live atlas still holds
+   * is kept. Idempotent, and a no-op on a collection that never leaked.
+   *
+   * @static
+   * @param {Object} params
+   * @param {Object} [params.options] - Router options ({ host, path }) for model lookup.
+   * @returns {Promise<number>} How many orphaned renders were removed.
+   * @memberof CyberiaAtlasSpriteSheetStore
+   */
+  static async pruneOrphanRenders({ options } = {}) {
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    const File = DataBaseProviderService.getModel('File', options);
+
+    const candidates = await File.find({ name: { $regex: ATLAS_RENDER_NAME } }, { _id: 1 }).lean();
+    if (candidates.length === 0) return 0;
+
+    const removed = await deleteOwnedFiles({
+      File,
+      Owner: AtlasSpriteSheet,
+      fields: ATLAS_FILE_FIELDS,
+      ids: candidates.map((doc) => doc._id),
+    });
+    if (removed > 0) logger.info(`Removed ${removed} orphaned atlas File document(s)`);
+    return removed;
+  }
+
+  /**
+   * Refreshes only the minified render of a stored atlas.
+   *
+   * The layout must still match the stored metadata, because the client runtime
+   * pairs `GET /blob/:itemKey` with `GET /metadata/:itemKey`. A layout that moved
+   * means the render frames changed after the atlas was generated, so the item is
+   * reported as stale instead of written.
+   *
+   * @static
+   * @param {Object} params
+   * @param {string} params.itemKey - Object layer item id.
+   * @param {Object} params.objectLayerRenderFrames - Render frames, document or plain object.
+   * @param {Object} [params.options] - Router options ({ host, path }) for model lookup.
+   * @returns {Promise<{ status: 'updated'|'unchanged'|'missing'|'stale', minifyFileId?: import('mongoose').Types.ObjectId }>}
+   * @memberof CyberiaAtlasSpriteSheetStore
+   */
+  static async syncMinifyRender({ itemKey, objectLayerRenderFrames, options }) {
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    const File = DataBaseProviderService.getModel('File', options);
+
+    const atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+    if (!atlasDoc) return { status: 'missing' };
+
+    // Only the minified render is wanted here, so ask for no upscaled second render.
+    const { minifyBuffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
+      objectLayerRenderFrames,
+      itemKey,
+      1,
+    );
+
+    if (!sameLayout(metadata, atlasDoc.metadata.toObject ? atlasDoc.metadata.toObject() : atlasDoc.metadata)) {
+      return { status: 'stale' };
+    }
+
+    const previousId = atlasDoc.minifyFileId;
+    const minifyFileId = await upsertRenderFile(File, itemKey, 'minify', minifyBuffer);
+    if (previousId && String(previousId) === String(minifyFileId)) {
+      return { status: 'unchanged', minifyFileId };
+    }
+
+    await AtlasSpriteSheet.updateOne({ _id: atlasDoc._id }, { $set: { minifyFileId } });
+    await deleteReplacedFiles(File, [previousId], [minifyFileId]);
+
+    return { status: 'updated', minifyFileId };
+  }
+
+  /**
+   * Fills or refreshes the idle-preview still of a stored atlas from the render it already
+   * holds, so an atlas written before the still existed gains one without a regeneration.
+   *
+   * @static
+   * @param {Object} params
+   * @param {string} params.itemKey - Object layer item id.
+   * @param {Object} [params.options] - Router options ({ host, path }) for model lookup.
+   * @returns {Promise<{ status: 'updated'|'unchanged'|'missing', idlePreviewFileId?: import('mongoose').Types.ObjectId }>}
+   * @memberof CyberiaAtlasSpriteSheetStore
+   */
+  static async syncIdlePreview({ itemKey, options }) {
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+    const File = DataBaseProviderService.getModel('File', options);
+
+    const atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+    // Hydrated, not lean: a lean read hands back a BSON Binary the decoder cannot open.
+    const render = atlasDoc?.fileId ? await File.findById(atlasDoc.fileId) : null;
+    if (!render?.data) return { status: 'missing' };
+
+    const metadata = atlasDoc.metadata.toObject ? atlasDoc.metadata.toObject() : atlasDoc.metadata;
+    const previousId = atlasDoc.idlePreviewFileId;
+    const idlePreviewFileId = await upsertIdlePreview(File, itemKey, Buffer.from(render.data), metadata);
+    if (previousId && String(previousId) === String(idlePreviewFileId)) {
+      return { status: 'unchanged', idlePreviewFileId };
+    }
+
+    await AtlasSpriteSheet.updateOne({ _id: atlasDoc._id }, { $set: { idlePreviewFileId } });
+    await deleteReplacedFiles(File, [previousId], [idlePreviewFileId]);
+
+    return { status: 'updated', idlePreviewFileId };
+  }
+}

package/src/projects/cyberia/besu-genesis-generator.js

@@ -61,26 +61,17 @@ function derivePublicKey(privateKeyHex) {
  * (uncompressed, sans 04 prefix) public key bytes:
  *   `address = keccak256(pubKeyBytes)[12..31]`
  *
- * **Important:** Ethereum uses the *original* Keccak-256 (the pre-NIST
- * submission), NOT NIST SHA3-256.  NIST added different domain-separation
- * padding when standardising SHA-3, so `crypto.createHash('sha3-256')`
- * produces **wrong** addresses.  We use `ethers.keccak256` which bundles
- * a correct Keccak-256 implementation.
+ * Ethereum uses the original Keccak-256, not NIST SHA3-256. NIST added other
+ * domain-separation padding, so `crypto.createHash('sha3-256')` gives wrong
+ * addresses. `ethers.keccak256` carries a correct Keccak-256.
  *
  * @param {string} publicKeyHex - 128-char hex public key (no 0x prefix).
  * @returns {string} 40-char lowercase hex Ethereum address (no 0x prefix).
  * @memberof BesuGenesisGenerator
  */
 function publicKeyToAddress(publicKeyHex) {
-  // Ethereum addresses are derived using Keccak-256 (the original Keccak submission),
-  // NOT NIST SHA3-256.  NIST SHA3-256 added different domain-separation padding,
-  // so crypto.createHash('sha3-256') produces WRONG addresses.
-  //
-  // Node.js's OpenSSL does not expose the original Keccak-256, so we use ethers
-  // which bundles a correct implementation.
-  //
-  // ethersKeccak256 expects a 0x-prefixed hex string or Uint8Array and returns
-  // a 0x-prefixed 64-char hex hash.  The Ethereum address is the last 20 bytes.
+  // ethersKeccak256 takes 0x-prefixed hex or a Uint8Array and returns a
+  // 0x-prefixed 64-char hash. The address is its last 20 bytes.
   const hash = ethersKeccak256(Buffer.from(publicKeyHex, 'hex')); // 0x-prefixed 64-char hex
   return hash.slice(26); // skip '0x' + first 24 hex chars → last 40 hex chars (20 bytes)
 }

package/src/projects/cyberia/boot-contract-fixtures.js

@@ -0,0 +1,32 @@
+import { STAT_DEFAULTS } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+import { DefaultCyberiaActions, DefaultCyberiaQuests } from '../../api/cyberia-server-defaults/cyberia-server-defaults.js';
+import { toInstanceConfig, toMapMsg, toInstanceMsg, toObjectLayerMsg, toActionMsg, toQuestMsg } from './instance-data.js';
+
+export function buildBootContractArtifacts() {
+  const layer = toObjectLayerMsg({
+    _id: 'contract-layer', sha256: 'abc',
+    data: { stats: { ...STAT_DEFAULTS, effect: -100, resistance: 100 }, item: { id: 'sword', type: 'weapon' } },
+  });
+  const full = {
+    instance: toInstanceMsg({ _id: 'contract-instance', code: 'contract-test', cyberiaMapCodes: ['contract-map'] }),
+    maps: [toMapMsg({
+      _id: 'contract-map', code: 'contract-map', gridX: 16, gridY: 16,
+      entities: [{ entityType: 'bot', level: 7, objectLayerItemIds: ['sword'] }],
+    })],
+    objectLayers: [layer],
+    config: toInstanceConfig({}),
+    version: 'contract-fixture',
+    actions: DefaultCyberiaActions.slice(0, 1).map(toActionMsg),
+    quests: DefaultCyberiaQuests.slice(0, 1).map(toQuestMsg),
+  };
+  const payloads = {
+    boot_full_instance: full,
+    boot_object_layer: layer,
+    boot_manifest: { entries: [{ itemId: 'sword', sha256: 'abc' }] },
+    boot_ping: { serverTimeMs: 1000 },
+  };
+  return Object.fromEntries(Object.entries(payloads).map(([name, data]) => [
+    'cyberia-server/engine_client/testdata/' + name + '.json',
+    JSON.stringify({ status: 'success', data }, null, 2) + '\n',
+  ]));
+}

package/src/projects/cyberia/catalog-cyberia.js

@@ -39,11 +39,10 @@ export default {
   packageBin: { cyberia: 'bin/index.js', underpost: 'bin/index.js' },
   // Native-dependency pin list: versions stay reproducible across CI and production deploys.
   packageDependencies: {
-    'adm-zip': '^0.6.0',
     'maxrects-packer': '^2.7.3',
     pngjs: '^7.0.0',
     jimp: '^1.6.0',
-    sharp: '^0.35.3',
+    sharp: '^0.35.4',
     ethers: '~6.16.0',
   },
   packageScripts: {
@@ -73,6 +72,7 @@ export default {
     '/src/grpc/cyberia',
     '/src/client/ssr/views/CyberiaServerMetrics.js',
     '/src/client/ssr/views/Cyberia404.js',
+    '/test/unit/cyberia',
     '/test/integration/app/cyberia',
     '/src/projects/cyberia',
     '/src/runtime/cyberia-server',
@@ -102,6 +102,7 @@ export default {
     './src/runtime/cyberia-server',
     './src/runtime/cyberia-client',
     './src/runtime/engine-cyberia',
+    './test/unit/cyberia',
     './test/integration/app/cyberia',
     './src/client/public/cyberia-docs',
     './bin/cyberia.js',

package/src/projects/cyberia/gemini-client.js

@@ -5,9 +5,9 @@
  * Top-Down PCG saga generator. No streaming, no tool-calls — the saga
  * orchestration only needs one structured JSON payload per request.
  *
- * General purpose, but for now only the `:generateContent` endpoint is wired,
- * matching the Gemma model family (e.g. `gemma-4-26b-a4b-it`). Authentication
- * uses the `x-goog-api-key` header sourced from `GEMINI_API_KEY`.
+ * Only the `:generateContent` endpoint is wired, matching the Gemma model
+ * family (e.g. `gemma-4-26b-a4b-it`). Authentication uses the `x-goog-api-key`
+ * header from `GEMINI_API_KEY`.
  *
  * @module src/projects/cyberia/gemini-client.js
  * @namespace GeminiClient

package/src/projects/cyberia/generate-saga.js

@@ -1,3 +1,4 @@
+import { validateStats } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 /**
  * Top-Down Procedural Generation guided by LLMs (Semantic Reverse-Engineering).
  *
@@ -1089,9 +1090,10 @@ const STAGE_PROMPTS = {
     'STAGE: foundation. Return ONE JSON object: { "saga": {...}, "objectLayers": [...] }.',
     'saga: { code, name, description, mapCodes:[] }  (leave mapCodes an empty array).',
     'objectLayers[]: { stats:{ effect, resistance, agility, range, intelligence, utility },',
+    '- Stats are integer modifiers from -100 to +100. Zero is neutral. Level and XP belong to entities.',
     '  item:{ id, type, description, activable }, render:null }',
     '  item.type is one of: skin, breastplate, weapon, skill, coin, floor, obstacle, portal,',
-    '  foreground, resource; every stat is an integer 0..10 balanced to the lore.',
+    '  foreground, resource; every stat is an integer -100..+100, with 0 neutral.',
     'Produce 5-10 object-layer items including at least one "coin" currency item AND at least two',
     '"skin" items that represent NAMED NPC characters players can speak to (these back "talk" quests).',
   ].join('\n'),
@@ -1536,14 +1538,7 @@ function normalizeSagaPayload(raw, { theme }) {
   const objectLayers = asArray(raw.objectLayers).map((ol) => {
     const stats = ol.stats || {};
     return {
-      stats: {
-        effect: Number(stats.effect) || 0,
-        resistance: Number(stats.resistance) || 0,
-        agility: Number(stats.agility) || 0,
-        range: Number(stats.range) || 0,
-        intelligence: Number(stats.intelligence) || 0,
-        utility: Number(stats.utility) || 0,
-      },
+      stats: validateStats(stats),
       item: {
         id: slugify(ol.item?.id),
         type: ol.item?.type || 'skin',
@@ -1621,7 +1616,6 @@ function normalizeSagaPayload(raw, { theme }) {
     description: saga.description,
     tags: ['saga', 'generated'],
     cyberiaMapCodes: [...saga.mapCodes],
-    itemIds: saga.itemIds.map((id) => ({ id, defaultPlayerInventory: false })),
     portals: [],
     topologyMode: 'procedural',
   };
@@ -1687,7 +1681,6 @@ async function persistInstance({ instance, CyberiaInstance }) {
         description: instance.description,
         tags: instance.tags,
         cyberiaMapCodes: instance.cyberiaMapCodes,
-        itemIds: instance.itemIds,
         topologyMode: instance.topologyMode,
       },
       $setOnInsert: { code: instance.code, portals: instance.portals || [] },

package/src/projects/cyberia/hot-reload-trigger.js

@@ -1,24 +1,19 @@
 /**
- * Hot-reload trigger — engine-cyberia → cyberia-server control channel.
+ * Hot-reload trigger — the engine's control channel to a running game server.
  *
- * Asks a running cyberia-server to rebuild its world NOW instead of waiting
- * for its polling loop (ENGINE_GRPC_RELOAD_INTERVAL_SEC). Two transports, in
- * order:
+ * Asks the server to rebuild its world now instead of waiting for its polling
+ * loop. Two transports, in order:
  *
- *   1. gRPC  — cyberia-server's CyberiaControlService. Preferred.
- *   2. REST  — POST {baseUrl}/api/v1/hot-reload. Fallback when the control
- *              gRPC port is unreachable (not exposed, different network).
+ *   1. gRPC, the server's CyberiaControlService. Preferred.
+ *   2. REST, POST {baseUrl}/api/v1/hot-reload. Used when the control gRPC port
+ *      is unreachable.
  *
- * The gRPC control service is served with a JSON codec, so this client is
- * hand-rolled with makeUnaryRequest + JSON serializers — no .proto codegen on
- * either side. Keep SERVICE/METHOD in sync with cyberia-server/hotreload/grpc.go.
+ * The control service uses a JSON codec, so this client is hand-rolled with
+ * makeUnaryRequest and JSON serializers. There is no .proto codegen; SERVICE
+ * and METHOD must match the server's control service.
  *
- * AUTHORIZATION
- * -------------
- * Both transports carry CYBERIA_SERVER_API_KEY, the INTERNAL shared secret
- * between engine-cyberia and cyberia-server. It is read from the environment
- * here and never returned to a browser: the engine's REST endpoint is the only
- * public surface, and it is moderator/admin guarded.
+ * Both transports carry CYBERIA_SERVER_API_KEY, the internal shared secret. It
+ * is read from the environment and never returned to a browser.
  *
  * @module src/projects/cyberia/hot-reload-trigger.js
  */
@@ -49,11 +44,9 @@ const serverApiKey = () => process.env.CYBERIA_SERVER_API_KEY || '';
  * gRPC target. The gRPC host reuses the hostname with the control port, since
  * the control service listens on its own port.
  *
- * The URL sub-path is preserved as `basePath` ("", "/FOREST", "/TEST") and kept
- * on `restBaseUrl`: a path-based multi-instance proxy routes the REST trigger to
- * the right variant, and cyberia-server consumes that same base path natively.
- * Using `url.origin` alone would drop the sub-path and land every trigger on the
- * default (root) deployment.
+ * The URL sub-path is kept as `basePath` ("", "/FOREST", "/TEST") and stays on
+ * `restBaseUrl`. A path-based multi-instance proxy routes the REST trigger by
+ * it; `url.origin` alone would send every trigger to the root deployment.
  */
 const resolveTargets = (rawUrl, { grpcPort = DEFAULT_GRPC_PORT } = {}) => {
   const trimmed = String(rawUrl || '').trim();
@@ -133,11 +126,8 @@ const triggerHotReload = async ({
   const { restBaseUrl, grpcTarget, basePath } = resolveTargets(serverUrl, { grpcPort });
   const call = { apiKey, mode, instanceCode, timeoutMs };
 
-  // A path-based multi-instance proxy routes by URL sub-path, but a gRPC method
-  // path is fixed (/cyberia.CyberiaControlService/…) and can't carry the
-  // /FOREST prefix — a control call to hostname:port reaches the default
-  // variant. When the target names a variant sub-path, use the sub-path-aware
-  // REST transport directly instead of triggering the wrong world over gRPC.
+  // A gRPC method path is fixed and cannot carry the variant sub-path, so a
+  // control call would reach the default variant. Use REST for a sub-path target.
   if (basePath) {
     const result = await triggerViaRest({ ...call, restBaseUrl });
     logger.info(`hot reload via REST ${restBaseUrl}: ${result?.message}`);
@@ -149,8 +139,7 @@ const triggerHotReload = async ({
     logger.info(`hot reload via gRPC ${grpcTarget}: ${result?.message}`);
     return { transport: 'grpc', result };
   } catch (grpcError) {
-    // A rejected key is a real answer, not a transport failure — do not retry
-    // over REST, or a misconfigured key would be reported twice.
+    // A rejected key is an answer, not a transport failure. Do not retry.
     if (grpcError?.code === grpc.status.PERMISSION_DENIED) throw new Error(grpcError.details || grpcError.message);
     logger.warn(`hot reload gRPC (${grpcTarget}) unavailable: ${grpcError.message} — falling back to REST`);