@underpostnet/cyberia 3.3.0 → 3.3.76

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

@@ -17,9 +17,9 @@ import crypto from 'crypto';
 import fs from 'fs-extra';
 import path from 'path';
 import { keccak256 as ethersKeccak256 } from 'ethers';
-import { loggerFactory } from '../../server/logger.js';
-import { shellExec } from '../../server/process.js';
-import { crictlCommandFactory } from '../../server/cri.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { shellExec } from '../../server/runtime/process.js';
+import { crictlCommandFactory } from '../../server/ops/cri.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -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

@@ -2,7 +2,7 @@
  * Cyberia CLI content catalog.
  *
  * A per-deploy product catalog: pure data, loaded dynamically by deploy id via
- * {@link module:src/server/catalog} so the base build and template assembly never
+ * {@link module:src/server/build/catalog.js} so the base build and template assembly never
  * statically depend on it. Exports the uniform product-catalog shape:
  *
  *   - `sourceMoves`       — public `[src, dest]` pairs moved into the engine tree before a build.
@@ -13,12 +13,50 @@
  *   - `copies`            — `[src, dest]` pairs copied into the template during assembly (like moves but copied instead of moved).
  *   - `keywords`          — npm keywords for the standalone product CLI package.
  *   - `description`       — npm description for the standalone product CLI package.
+ *   - `packageName`       — npm name of the product package; the deploy id without `dd-` otherwise.
+ *   - `packageBin`        — bin map of the standalone product CLI.
+ *   - `packageDependencies` — runtime dependencies this product adds to the engine's.
+ *   - `packageScripts`    — npm scripts this product adds to the engine's.
+ *
+ * The `package*` fields are the single declaration of what this product's manifests carry:
+ * every generated manifest — the deploy's `engine-private/conf/<id>/package.json`, the product
+ * repository's, and the published instance copy — is built from them by
+ * {@link module:src/server/build/package.js}. Nothing else may name them.
  *
  * @module src/projects/cyberia/catalog-cyberia.js
  * @namespace CyberiaCatalog
  */
 
+const DEPLOY_ID = 'dd-cyberia';
+const DOCKER_COMPOSE_ID = 'cyberia';
+
+const dockerScript = (action, flags = '') =>
+  `node bin docker-compose --${action}${flags} --deploy-id ${DEPLOY_ID} --docker-compose-id ${DOCKER_COMPOSE_ID}`;
+
 export default {
+  packageName: 'cyberia',
+  // Pod bootstraps link this product checkout over the image CLI before continuing.
+  packageBin: { cyberia: 'bin/index.js', underpost: 'bin/index.js' },
+  // Native-dependency pin list: versions stay reproducible across CI and production deploys.
+  packageDependencies: {
+    'maxrects-packer': '^2.7.3',
+    pngjs: '^7.0.0',
+    jimp: '^1.6.0',
+    sharp: '^0.35.4',
+    ethers: '~6.16.0',
+  },
+  packageScripts: {
+    'docker:generate': dockerScript('generate'),
+    'docker:up': dockerScript('up'),
+    'docker:up:build': dockerScript('up', ' --build'),
+    'docker:down': dockerScript('down'),
+    'docker:down:volumes': dockerScript('down', ' --volumes'),
+    'docker:restart': dockerScript('restart'),
+    'docker:pull': dockerScript('pull'),
+    'docker:logs': dockerScript('logs'),
+    'docker:status': dockerScript('status'),
+    'docker:reset': dockerScript('reset'),
+  },
   sourceMoves: [],
   privateConfPaths: [
     /** INSTANCE_CODES */
@@ -26,6 +64,7 @@ export default {
     'cyberia-instances/amethyst-strata-expansion',
     'cyberia-sagas/amethyst-strata-expansion.json',
     'cyberia-instances/FOREST',
+    'cyberia-instances/TEST',
 
     /** INSTANCE_CODES */
   ],
@@ -33,8 +72,8 @@ export default {
     '/src/grpc/cyberia',
     '/src/client/ssr/views/CyberiaServerMetrics.js',
     '/src/client/ssr/views/Cyberia404.js',
-    '/test/cyberia-instance-conf-defaults.test.js',
-    '/test/shape-generator.test.js',
+    '/test/unit/cyberia',
+    '/test/integration/app/cyberia',
     '/src/projects/cyberia',
     '/src/runtime/cyberia-server',
     '/src/runtime/cyberia-client',
@@ -49,7 +88,13 @@ export default {
     '/.github/workflows/cyberia-client.cd.yml',
     '/.github/workflows/cyberia-server.cd.yml',
     '/.github/workflows/coverall.cyberia.ci.yml',
-    '/scripts/coverall-test-cyberia.sh',
+    '/bin/cyberia.js',
+    '/hardhat',
+    // The deploy scripts `run-workflow build-manifest` mirrors into each generated instance
+    // repository. The base template drops the whole `deploy/` tree, so the product CLI only has
+    // them if it packages them here.
+    '/deploy/cyberia-client',
+    '/deploy/cyberia-server',
   ],
   stripPaths: [
     './src/projects/cyberia',
@@ -57,14 +102,13 @@ export default {
     './src/runtime/cyberia-server',
     './src/runtime/cyberia-client',
     './src/runtime/engine-cyberia',
-    './test/cyberia-instance-conf-defaults.test.js',
-    './test/cyberia-load.test.js',
-    './test/object-layer-item-id.test.js',
-    './test/shape-generator.test.js',
+    './test/unit/cyberia',
+    './test/integration/app/cyberia',
     './src/client/public/cyberia-docs',
-    './scripts/coverall-test-cyberia.sh',
-    'bin/cyberia.js',
+    './bin/cyberia.js',
     './hardhat',
+    './deploy/cyberia-client',
+    './deploy/cyberia-server',
   ],
   moves: [],
   copies: [

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

@@ -5,16 +5,16 @@
  * 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
  */
 
 import axios from 'axios';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 

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).
  *
@@ -18,7 +19,7 @@ import fs from 'fs-extra';
 import nodePath from 'path';
 import crypto from 'crypto';
 import { GeminiClient } from './gemini-client.js';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -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 || [] },