@underpostnet/cyberia 3.3.73 → 3.3.77

package/test/integration/app/cyberia/cyberia-instance-conf-coerce.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { CyberiaInstanceConfModel } from '../../../../src/api/cyberia-instance-conf/cyberia-instance-conf.model.js';
+import { CyberiaInstanceConfService } from '../../../../src/api/cyberia-instance-conf/cyberia-instance-conf.service.js';
+import { CYBERIA_INSTANCE_CONF_DEFAULTS } from '../../../../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
+
+const coerce = (conf) => CyberiaInstanceConfService.coerceToSchema(conf, CyberiaInstanceConfModel);
+
+// A backup written before the chance fields became fractions of one, as the exports on disk are.
+const legacy = { instanceCode: 'LEGACY', lifeRegenChance: 300, maxChance: 10000 };
+
+describe('instance conf import coercion', () => {
+  it('resets a value the schema rejects to its default and says so', async () => {
+    const { conf, resets } = await coerce(legacy);
+    expect(conf.lifeRegenChance).toBe(CYBERIA_INSTANCE_CONF_DEFAULTS.lifeRegenChance);
+    expect(conf.maxChance).toBe(CYBERIA_INSTANCE_CONF_DEFAULTS.maxChance);
+    expect(resets.map(({ path, from }) => [path, from])).toEqual([
+      ['lifeRegenChance', 300],
+      ['maxChance', 10000],
+    ]);
+  });
+
+  it('leaves every valid field exactly as it was', async () => {
+    const { conf, resets } = await coerce({ ...legacy, tickRate: 12, aoiRadius: 7 });
+    expect(conf.tickRate).toBe(12);
+    expect(conf.aoiRadius).toBe(7);
+    expect(conf.instanceCode).toBe('LEGACY');
+    expect(resets).toHaveLength(2);
+  });
+
+  it('is a no-op on a conf that already passes', async () => {
+    const { conf, resets } = await coerce({ instanceCode: 'CLEAN', lifeRegenChance: 0.2 });
+    expect(resets).toEqual([]);
+    expect(conf.lifeRegenChance).toBe(0.2);
+  });
+
+  it('resets a nested field through its dotted path', async () => {
+    const { conf, resets } = await coerce({ instanceCode: 'NESTED', skillRules: { projectileSpawnChance: 42 } });
+    expect(conf.skillRules.projectileSpawnChance).toBe(CYBERIA_INSTANCE_CONF_DEFAULTS.skillRules.projectileSpawnChance);
+    expect(resets[0].path).toBe('skillRules.projectileSpawnChance');
+  });
+
+  it('produces a document the model accepts, so import can never half-fail', async () => {
+    const { conf } = await coerce(legacy);
+    await expect(new CyberiaInstanceConfModel(conf).validate()).resolves.toBeUndefined();
+  });
+
+  it('converges: coercing its own output changes nothing', async () => {
+    const { conf } = await coerce(legacy);
+    const { conf: again, resets } = await coerce(conf);
+    expect(resets).toEqual([]);
+    expect(again).toEqual(conf);
+  });
+});

package/test/integration/app/cyberia/cyberia-instance-conf-defaults.test.js

@@ -25,7 +25,7 @@ const SCHEMA_FIELDS = [
   'playerBaseSpeed',
   'playerBaseLifeRegenMin',
   'playerBaseLifeRegenMax',
-  'sumStatsLimit',
+  'progressionRules',
   'maxActiveLayers',
   'initialLifeFraction',
   'respawnDurationMs',
@@ -35,7 +35,6 @@ const SCHEMA_FIELDS = [
   'maxChance',
   'entityDefaults',
   'statusIcons',
-  'skillConfig',
   'skillRules',
   'equipmentRules',
 ];
@@ -90,33 +89,28 @@ describe('fillInstanceConfDefaults', () => {
   });
 
   it('keeps a present non-empty array and does not merge defaults into it', () => {
-    const custom = [{ entityType: 'player', liveItemIds: ['anon'], deadItemIds: [], dropItemIds: [] }];
+    // entityDefaults holds CyberiaEntityTypeDefault references, never documents.
+    const custom = ['6a9d72430a55742d256c22d6', '6a9d72430a55742d256c22d7'];
     const out = fillInstanceConfDefaults({ entityDefaults: custom });
     expect(out.entityDefaults).to.deep.equal(custom);
   });
 
-  it('populates an empty skillConfig from defaults, normalised to schema shape (no `skills`)', () => {
-    for (const input of [{}, { skillConfig: [] }, { skillConfig: null }]) {
-      const out = fillInstanceConfDefaults(input);
-      expect(out.skillConfig.length, JSON.stringify(input)).to.be.greaterThan(0);
-      for (const entry of out.skillConfig) {
-        expect(entry).to.have.property('triggerItemId');
-        expect(entry).to.have.property('logicEventIds');
-        expect(entry).to.not.have.property('skills');
-      }
+  it('carries no skillConfig, because an instance never stores which skills it runs', () => {
+    // The CyberiaSkill collection owns the definitions; membership is derived from the content an
+    // instance names. A conf from before that still carrying the field has it dropped, so a stale
+    // list cannot reach the wire behind the derived one.
+    for (const input of [{}, { skillConfig: [] }, { skillConfig: [{ triggerItemId: 'hatchet' }] }]) {
+      expect(fillInstanceConfDefaults(input), JSON.stringify(input)).to.not.have.property('skillConfig');
     }
   });
 
-  it('keeps an author-set non-empty skillConfig verbatim', () => {
-    const custom = [{ triggerItemId: 'custom-weapon', logicEventIds: ['projectile'] }];
-    const out = fillInstanceConfDefaults({ skillConfig: custom });
-    expect(out.skillConfig).to.deep.equal(custom);
-  });
-
-  it('fills an empty config array (entityDefaults) from defaults', () => {
-    const out = fillInstanceConfDefaults({ entityDefaults: [] });
-    expect(out.entityDefaults.length).to.be.greaterThan(0);
-    expect(out.entityDefaults).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.entityDefaults);
+  it('leaves entityDefaults empty, because referencing none is a complete world', () => {
+    // A conf owns references, not defaults: naming no document means "add nothing to the
+    // canonical ENTITY_TYPE_DEFAULTS", which is what every fresh instance wants.
+    for (const input of [{}, { entityDefaults: [] }, { entityDefaults: null }]) {
+      expect(fillInstanceConfDefaults(input).entityDefaults, JSON.stringify(input)).to.deep.equal([]);
+    }
+    expect(CYBERIA_INSTANCE_CONF_DEFAULTS.entityDefaults).to.deep.equal([]);
   });
 
   it('preserves DB metadata (_id, instanceCode, timestamps)', () => {

package/test/integration/app/cyberia/cyberia-instance-items.test.js

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import {
+  collectInstanceItemIds,
+  collectSummonedItemIds,
+  isMaterialItemId,
+  selectInstanceSkills,
+} from '../../../../src/api/cyberia-instance/cyberia-instance-items.js';
+
+const SKILLS = [
+  { triggerItemId: 'atlas_pistol_mk2', skills: [{ summonedEntityItemId: 'atlas_pistol_mk2_bullet' }] },
+  { triggerItemId: 'hatchet', skills: [{ summonedEntityItemId: 'hatchet-skill' }] },
+  { triggerItemId: 'anon', skills: [{ summonedEntityItemId: '$active_skin' }] },
+];
+
+describe('what an instance names', () => {
+  it('reads the four sources and nothing else', () => {
+    const itemIds = collectInstanceItemIds({
+      maps: [{ entities: [{ objectLayerItemIds: ['purple', 'atlas_pistol_mk2'] }] }],
+      entityDefaults: [
+        { liveItemIds: ['wood-1'], deadItemIds: ['wood-extracted-1'], dropItemIds: ['wood-drop-1'], inventoryItemsIds: ['tim-knife'] },
+      ],
+      actions: [
+        {
+          shopItems: [{ itemId: 'hatchet', priceItemId: 'coin' }],
+          craftRecipes: [{ ingredients: [{ itemId: 'wood-1' }], outputItems: [{ itemId: 'plank' }] }],
+        },
+      ],
+      quests: [{ steps: [{ objectives: [{ itemId: 'kishins' }] }], rewards: [{ itemId: 'lain' }] }],
+    });
+    expect([...itemIds].sort()).toEqual([
+      'atlas_pistol_mk2',
+      'coin',
+      'hatchet',
+      'kishins',
+      'lain',
+      'plank',
+      'purple',
+      'tim-knife',
+      'wood-1',
+      'wood-drop-1',
+      'wood-extracted-1',
+    ]);
+  });
+
+  it('is empty for an instance with no content, and survives ragged documents', () => {
+    expect([...collectInstanceItemIds()]).toEqual([]);
+    expect([...collectInstanceItemIds({ maps: [null, {}], entityDefaults: [{}], actions: [{}], quests: [{}] })]).toEqual(
+      [],
+    );
+  });
+
+  it('leaves runtime placeholders out — they name no document', () => {
+    expect(isMaterialItemId('$active_skin')).toBe(false);
+    expect(isMaterialItemId('anon')).toBe(true);
+    expect([...collectInstanceItemIds({ quests: [{ rewards: [{ itemId: '$active_skin' }] }] })]).toEqual([]);
+  });
+});
+
+describe('which skills an instance runs', () => {
+  it('takes a skill whose trigger the world names, wherever it named it', () => {
+    // The reported case: no entity wears a hatchet, a quest asks for one, and the skill belongs.
+    const owned = collectInstanceItemIds({
+      maps: [{ entities: [{ objectLayerItemIds: ['anon'] }] }],
+      quests: [{ steps: [{ objectives: [{ itemId: 'hatchet' }] }] }],
+    });
+    expect(selectInstanceSkills(SKILLS, owned).map((skill) => skill.triggerItemId)).toEqual(['hatchet', 'anon']);
+  });
+
+  it('leaves out a skill nothing in the world triggers', () => {
+    expect(selectInstanceSkills(SKILLS, new Set(['purple']))).toEqual([]);
+    expect(selectInstanceSkills(SKILLS, new Set())).toEqual([]);
+  });
+
+  it('accepts a plain array of ids as well as a set', () => {
+    expect(selectInstanceSkills(SKILLS, ['coin', 'hatchet']).map((skill) => skill.triggerItemId)).toEqual(['hatchet']);
+  });
+
+  it('collects what the selected skills summon, minus the placeholders', () => {
+    // A summoned bullet needs an atlas; '$active_skin' is resolved by the simulation.
+    expect([...collectSummonedItemIds(SKILLS)].sort()).toEqual(['atlas_pistol_mk2_bullet', 'hatchet-skill']);
+    expect([...collectSummonedItemIds([])]).toEqual([]);
+  });
+
+  it('does not let a summoned item make its own skill belong', () => {
+    // Membership is decided before summons are folded in, so a world that merely draws a bullet
+    // does not thereby acquire the weapon skill that fires it.
+    const owned = new Set(['atlas_pistol_mk2_bullet']);
+    expect(selectInstanceSkills(SKILLS, owned)).toEqual([]);
+  });
+});

package/test/integration/app/cyberia/cyberia-load.test.js

@@ -14,8 +14,8 @@ import { setTimeout as sleep } from 'node:timers/promises';
 // so a fleet this size only fits an instance started for load — one running with
 // CYBERIA_DISABLE_CONNECTION_LIMITS=1, or with its per-IP admission limits raised
 // past CYBERIA_LOAD_CONNECTIONS. Pointed at an untuned instance the run is capped
-// by `DefaultMaxConnectionsPerIP` (cyberia-server/game/connection_guard.go) and
-// reports a refusal, so the target is named deliberately rather than defaulted to.
+// by the server's per-IP admission limit and reports a refusal, so the target is
+// named deliberately rather than defaulted to.
 // `underpost cyberia test` sets this, along with the fleet size and the duration.
 const WS_URL = process.env.CYBERIA_LOAD_WS_URL ?? '';
 const CONNECTIONS = Number(process.env.CYBERIA_LOAD_CONNECTIONS ?? 5);
@@ -62,8 +62,8 @@ const DISPERSAL_MARGIN_CELLS = 3;
 // lingers there sits in the crossfire of every joining player.
 const SPAWN_CLEARANCE_CELLS = 14;
 
-// Unit vectors for the supported directions, in the order of the Direction enum
-// in cyberia-server/game/types.go. NONE is excluded: a tap carries movement intent.
+// Unit vectors for the supported directions, in Direction enum order. NONE is
+// excluded: a tap carries movement intent.
 const DIRECTIONS = [
   [0, -1], // UP
   [1, -1], // UP_RIGHT
@@ -90,9 +90,8 @@ const clamp = (value, max) => (value < 0 ? 0 : value > max ? max : value);
 const randomDirection = () => DIRECTIONS[Math.floor(Math.random() * DIRECTIONS.length)];
 
 /**
- * Picks the supported direction closest to a vector. Same mapping the server
- * uses in `updateBotDirection` (cyberia-server/game/ai.go): the enum starts at
- * UP, so the angle index shifts by two quadrants.
+ * Picks the supported direction closest to a vector, the same mapping the
+ * server uses. The enum starts at UP, so the angle index shifts two quadrants.
  */
 function directionToward(dx, dy) {
   const index = (((Math.round(Math.atan2(dy, dx) / (Math.PI / 4)) + 2) % 8) + 8) % 8;

package/test/integration/app/cyberia/cyberia-map-audio-conf.test.js

@@ -0,0 +1,256 @@
+'use strict';
+
+import { expect } from 'chai';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { CyberiaAudioModel } from '../../../../src/api/cyberia-audio/cyberia-audio.model.js';
+import { CyberiaAudioService, readManifest } from '../../../../src/api/cyberia-audio/cyberia-audio.service.js';
+import { CyberiaMapAudioConfModel } from '../../../../src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.model.js';
+import {
+  mergeEventBindings,
+  parseEventAudioBinding,
+} from '../../../../src/api/cyberia-map-audio-conf/cyberia-map-audio-conf.service.js';
+
+// As the recorder writes it: `bus` is the `src/audio-module/<bus-id>/` directory of the module.
+const manifestFixture = (id) => ({
+  id,
+  bus: 'sfx',
+  tags: ['fixture'],
+  author: 'cyberia-audio',
+  version: '0.1.0',
+  duration: 0.42,
+  sampleRate: 44100,
+  channels: 1,
+  loop: false,
+  audio: `${id}.wav`,
+  defaults: { volume: 0.8 },
+  parameters: { volume: { min: 0, max: 1, integer: false } },
+});
+
+describe('parseEventAudioBinding', () => {
+  it('splits a <logic-event-id>:<audio-code> pair and trims both sides', () => {
+    expect(parseEventAudioBinding('combat:combat-theme')).to.deep.equal({
+      logicEventId: 'combat',
+      audioCode: 'combat-theme',
+    });
+    expect(parseEventAudioBinding(' boss : mystery ')).to.deep.equal({ logicEventId: 'boss', audioCode: 'mystery' });
+  });
+
+  it('splits on the first colon so an audio code may contain one', () => {
+    expect(parseEventAudioBinding('shoot:pack:laser')).to.deep.equal({ logicEventId: 'shoot', audioCode: 'pack:laser' });
+  });
+
+  it('rejects a value with an empty side or no separator', () => {
+    for (const bad of ['combat', ':combat', 'combat:', '', ' : ', undefined, null]) {
+      expect(() => parseEventAudioBinding(bad), `accepted: ${bad}`).to.throw(/<logic-event-id>:<audio-code>/);
+    }
+  });
+});
+
+describe('mergeEventBindings', () => {
+  const stored = [
+    { logicEventId: 'combat', audioCode: 'combat' },
+    { logicEventId: 'boss', audioCode: 'mystery' },
+  ];
+
+  it('replaces the events it names and keeps the rest', () => {
+    expect(mergeEventBindings(stored, [{ logicEventId: 'boss', audioCode: 'victory' }])).to.deep.equal([
+      { logicEventId: 'combat', audioCode: 'combat' },
+      { logicEventId: 'boss', audioCode: 'victory' },
+    ]);
+  });
+
+  it('appends an event the map does not carry yet', () => {
+    expect(mergeEventBindings(stored, [{ logicEventId: 'shoot', audioCode: 'shoot' }])).to.have.length(3);
+  });
+
+  it('preserves playback settings when only the asset reference changes', () => {
+    expect(mergeEventBindings(
+      [{ logicEventId: 'combat', audioCode: 'combat', settings: { bus: 'music', loop: true } }],
+      [{ logicEventId: 'combat', audioCode: 'boss' }],
+    )).to.deep.equal([
+      { logicEventId: 'combat', audioCode: 'boss', settings: { bus: 'music', loop: true } },
+    ]);
+  });
+
+  it('is a no-op with nothing incoming, and works from an empty map', () => {
+    expect(mergeEventBindings(stored, [])).to.deep.equal(stored);
+    expect(mergeEventBindings(undefined, [{ logicEventId: 'idle', audioCode: 'exploration' }])).to.deep.equal([
+      { logicEventId: 'idle', audioCode: 'exploration' },
+    ]);
+  });
+});
+
+describe('CyberiaAudio schema', () => {
+  it('is the asset and nothing else: code, file, manifest', () => {
+    expect(Object.keys(CyberiaAudioModel.schema.paths)).to.include.members(['code', 'fileId', 'manifest']);
+    // The asset carries no classification of its own; when it plays belongs to the binding.
+    expect(CyberiaAudioModel.schema.paths).to.not.have.property('type');
+    expect(CyberiaAudioModel.schema.paths).to.not.have.property('logicEventId');
+  });
+
+  it('identifies an asset by its code alone', () => {
+    const [fields, options] = CyberiaAudioModel.schema.indexes().find(([keys]) => keys.code);
+    expect(fields).to.deep.equal({ code: 1 });
+    expect(options.unique).to.equal(true);
+  });
+
+  it('records the bus a module was authored on, without constraining it', () => {
+    const asset = new CyberiaAudioModel({
+      code: 'combat',
+      manifest: readManifest(manifestFixture('combat'), 'combat.json'),
+    });
+    expect(asset.validateSync()).to.equal(undefined);
+    expect(asset.manifest.bus).to.equal('sfx');
+    // Any bus the package ships is stored as provenance; a map binding decides where an asset
+    // actually plays, so nothing here validates the value.
+    const ambient = new CyberiaAudioModel({
+      code: 'drone',
+      manifest: readManifest({ ...manifestFixture('drone'), bus: 'ambient' }, 'drone.json'),
+    });
+    expect(ambient.validateSync()).to.equal(undefined);
+    expect(ambient.manifest.bus).to.equal('ambient');
+    // The classification this model no longer carries cannot come back through the manifest.
+    expect(ambient.manifest.toObject()).to.not.have.property('type');
+  });
+});
+
+describe('CyberiaMapAudioConf schema', () => {
+  it('binds a logic event to an audio code, and nothing more', () => {
+    const doc = new CyberiaMapAudioConfModel({
+      mapCode: 'FOREST',
+      defaultMusic: 'exploration',
+      events: [
+        { logicEventId: 'combat', audioCode: 'combat' },
+        { logicEventId: 'shoot', audioCode: 'shoot', settings: { volume: 0.5 } },
+      ],
+    });
+    expect(doc.validateSync()).to.equal(undefined);
+    expect(Object.keys(doc.events[0].toObject())).to.deep.equal(['logicEventId', 'audioCode']);
+    // No classification is duplicated between the asset layer and the configuration layer.
+    expect(JSON.stringify(doc.toObject())).to.not.match(/"type":/);
+  });
+
+  it('keeps omitted overrides absent so map settings can be inherited', () => {
+    const doc = new CyberiaMapAudioConfModel({
+      mapCode: 'FOREST',
+      events: [{ logicEventId: 'combat', audioCode: 'combat' }, { logicEventId: 'shoot', audioCode: 'shoot', settings: { volume: 0.5 } }],
+    });
+    expect(doc.settings.toObject()).to.deep.equal({});
+    expect(doc.events[0].settings.toObject()).to.deep.equal({});
+    expect(doc.events[1].settings.volume).to.equal(0.5);
+  });
+
+  it('requires a map code, a logic event and the asset the event resolves to', () => {
+    expect(new CyberiaMapAudioConfModel({}).validateSync().errors).to.have.property('mapCode');
+    const missing = new CyberiaMapAudioConfModel({ mapCode: 'FOREST', events: [{}] }).validateSync().errors;
+    expect(missing).to.have.property('events.0.logicEventId');
+    expect(missing).to.have.property('events.0.audioCode');
+  });
+
+  it('resolves a logic event and the default music to asset codes', () => {
+    const doc = new CyberiaMapAudioConfModel({
+      mapCode: 'FOREST',
+      defaultMusic: 'exploration',
+      events: [
+        { logicEventId: 'combat', audioCode: 'combat' },
+        { logicEventId: 'boss', audioCode: 'mystery' },
+      ],
+    });
+    const resolve = (logicEventId) => doc.events.find((entry) => entry.logicEventId === logicEventId)?.audioCode;
+    expect(resolve('combat')).to.equal('combat');
+    expect(resolve('boss')).to.equal('mystery');
+    expect(resolve('unbound')).to.equal(undefined);
+    expect(doc.defaultMusic).to.equal('exploration');
+  });
+
+  it('lets one asset answer several logic events, on several maps', () => {
+    const forest = new CyberiaMapAudioConfModel({
+      mapCode: 'FOREST',
+      defaultMusic: 'mystery',
+      events: [
+        { logicEventId: 'boss', audioCode: 'mystery' },
+        { logicEventId: 'ambush', audioCode: 'mystery', settings: { volume: 0.4, crossfadeMs: 800 } },
+      ],
+    });
+    const cave = new CyberiaMapAudioConfModel({ mapCode: 'CAVE', events: [{ logicEventId: 'idle', audioCode: 'mystery' }] });
+    expect(forest.validateSync()).to.equal(undefined);
+    expect(cave.validateSync()).to.equal(undefined);
+    // The same asset, three contexts, one asset document: the binding carries the difference.
+    expect(forest.events[1].settings.crossfadeMs).to.equal(800);
+    expect(cave.events[0].settings.crossfadeMs).to.equal(undefined);
+  });
+
+  it('identifies a configuration by its map code alone', () => {
+    const [fields, options] = CyberiaMapAudioConfModel.schema.indexes().find(([keys]) => keys.mapCode);
+    expect(fields).to.deep.equal({ mapCode: 1 });
+    expect(options.unique).to.equal(true);
+  });
+});
+
+describe('readManifest', () => {
+  it("keeps the recorder's bus under the one name both sides use", () => {
+    expect(readManifest(manifestFixture('coin'), 'coin.json')).to.include({ id: 'coin', bus: 'sfx' });
+    expect(readManifest({ ...manifestFixture('combat'), bus: 'music' }, 'combat.json').bus).to.equal('music');
+  });
+
+  it('leaves the bus empty when the recorder wrote none', () => {
+    const { bus, ...bare } = manifestFixture('bare');
+    expect(readManifest(bare, 'bare.json').bus).to.equal('');
+  });
+
+  it('requires an asset identity, and nothing else', () => {
+    expect(() => readManifest({ bus: 'sfx' }, 'bad.json')).to.throw(/no id/);
+    expect(() => readManifest(null, 'bad.json')).to.throw(/Invalid audio manifest/);
+    expect(readManifest({ id: 'minimal' }, 'minimal.json')).to.deep.equal({ id: 'minimal', bus: '' });
+  });
+});
+
+describe('CyberiaAudioService.importRecords selection', () => {
+  let directory;
+
+  beforeEach(() => {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'cyberia-audio-records-'));
+  });
+  afterEach(() => fs.removeSync(directory));
+
+  const writePair = (id, { manifest = true } = {}) => {
+    fs.writeFileSync(path.join(directory, `${id}.wav`), Buffer.from('RIFF'));
+    if (manifest) fs.writeJsonSync(path.join(directory, `${id}.json`), manifestFixture(id));
+  };
+
+  it('skips a WAV that has no manifest beside it, reaching no database', async () => {
+    writePair('orphan', { manifest: false });
+    expect(await CyberiaAudioService.importRecords({ recordsPath: directory }, { host: 'x', path: '/' })).to.deep.equal(
+      [],
+    );
+  });
+
+  it('rejects a records directory that does not exist', async () => {
+    const missing = path.join(directory, 'nope');
+    let error;
+    await CyberiaAudioService.importRecords({ recordsPath: missing }, {}).catch((caught) => (error = caught));
+    expect(error).to.be.an('error');
+    expect(error.message).to.contain(missing);
+  });
+
+  it('rejects a requested code with no WAV in the directory', async () => {
+    writePair('coin');
+    let error;
+    await CyberiaAudioService.importRecords({ recordsPath: directory, codes: ['laser'] }, {}).catch(
+      (caught) => (error = caught),
+    );
+    expect(error).to.be.an('error');
+    expect(error.message).to.contain('No laser.wav found');
+  });
+
+  it('ignores non-WAV files and only considers requested codes', async () => {
+    writePair('coin');
+    writePair('shoot', { manifest: false });
+    fs.writeFileSync(path.join(directory, 'notes.txt'), 'ignored');
+    // 'coin' is filtered out, 'shoot' has no manifest: nothing is left to import,
+    // so the selection resolves without a provider being loaded.
+    expect(await CyberiaAudioService.importRecords({ recordsPath: directory, codes: ['shoot'] }, {})).to.deep.equal([]);
+  });
+});

package/test/integration/app/cyberia/cyberia-stats.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Command } from 'commander';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  STAT_TYPES, STAT_DEFAULTS, STAT_MODIFIER_MIN, STAT_MODIFIER_MAX,
+  STAT_EFFECTIVE_FLOORS, validateStats, generateRandomStats,
+} from '../../../../src/client/components/cyberia/SharedDefaultsCyberia.js';
+import { resolveProgressionRules } from '../../../../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
+import { generateMultiFrame, registerSemantic } from '../../../../src/projects/cyberia/semantic-layer-generator.js';
+import { ObjectLayerModel } from '../../../../src/api/object-layer/object-layer.model.js';
+import { CyberiaMapModel } from '../../../../src/api/cyberia-map/cyberia-map.model.js';
+import { CyberiaMapService } from '../../../../src/api/cyberia-map/cyberia-map.service.js';
+import { DataBaseProviderService } from '../../../../src/db/DataBaseProvider.js';
+import { CyberiaEntityModel } from '../../../../src/api/cyberia-entity/cyberia-entity.model.js';
+import { CyberiaInstanceConfModel } from '../../../../src/api/cyberia-instance-conf/cyberia-instance-conf.model.js';
+import { toObjectLayerMsg, toEntityMsg, toInstanceConfig } from '../../../../src/projects/cyberia/instance-data.js';
+import { generateStatContract, hasCyberiaSiblings } from '../../../../src/projects/cyberia/stat-contract-generator.js';
+import { registerStatCommands } from '../../../../src/projects/cyberia/stat-commands.js';
+
+const block = (value) => Object.fromEntries(STAT_TYPES.map((key) => [key, value]));
+const record = (stats) => ({ data: { stats, item: { id: 'signed', type: 'weapon' }, ledger: { type: 'OFF_CHAIN' } }, sha256: 'a'.repeat(64) });
+
+describe('Cyberia signed stat contract', () => {
+  it('defines ordered defaults and playable floors once', () => {
+    expect(STAT_TYPES).toEqual(['effect', 'resistance', 'agility', 'range', 'intelligence', 'utility']);
+    expect(validateStats({})).toEqual(STAT_DEFAULTS);
+    expect(Object.isFrozen(STAT_DEFAULTS)).toBe(true);
+    expect(STAT_EFFECTIVE_FLOORS.agility).toBeGreaterThan(-100);
+    expect(STAT_MODIFIER_MIN).toBe(-100);
+    expect(STAT_MODIFIER_MAX).toBe(100);
+  });
+
+  it.each([-100, 0, 100])('accepts %s in authoring, schema, and boot transport', async (value) => {
+    const stats = block(value);
+    expect(validateStats(stats)).toEqual(stats);
+    await new ObjectLayerModel(record(stats)).validate();
+    expect(toObjectLayerMsg(record(stats)).stats).toEqual(stats);
+  });
+
+  it.each([-101, 101, 0.5, Infinity, -Infinity, NaN, null, '2'])('rejects invalid values: %s', (value) => {
+    expect(() => validateStats({ effect: value })).toThrow();
+    expect(() => toObjectLayerMsg(record({ effect: value }))).toThrow();
+  });
+
+  it.each([-101, 101, 0.5, Infinity, NaN])('rejects %s in the database schema', async (value) => {
+    await expect(new ObjectLayerModel(record({ ...STAT_DEFAULTS, effect: value })).validate()).rejects.toThrow();
+  });
+
+  it('rejects XP and level inside item stats', () => {
+    expect(() => validateStats({ xp: 100 })).toThrow();
+    expect(() => validateStats({ level: 2 })).toThrow();
+  });
+
+  it('generates both boundaries and rejects invalid generator bounds', () => {
+    expect(generateRandomStats(undefined, undefined, () => 0)).toEqual(block(-100));
+    expect(generateRandomStats(undefined, undefined, () => 0.999999)).toEqual(block(100));
+    expect(generateRandomStats(0, 0)).toEqual(STAT_DEFAULTS);
+    expect(() => generateRandomStats(-101, 1)).toThrow();
+    expect(() => generateRandomStats(0, 101)).toThrow();
+    expect(() => generateRandomStats(1, -1)).toThrow();
+    expect(() => generateRandomStats(0, 10, () => 1)).toThrow();
+  });
+
+  it('keeps entity level separate from item ownership', async () => {
+    const entity = new CyberiaEntityModel({ entityType: 'bot', level: 25, objectLayerItemIds: ['signed'] });
+    await entity.validate();
+    expect(toEntityMsg(entity.toObject()).level).toBe(25);
+    await expect(new CyberiaEntityModel({ level: -1 }).validate()).rejects.toThrow();
+    const config = toInstanceConfig({});
+    expect(config.progressionRules.maxLevel).toBe(100);
+    expect(config).not.toHaveProperty('sumStatsLimit');
+    await expect(new CyberiaInstanceConfModel({ instanceCode: 'test', progressionRules: { maxLevel: -1 } }).validate()).rejects.toThrow();
+  });
+
+  it('resolves partial curves and rejects invalid progression configuration', () => {
+    const rules = resolveProgressionRules({ baseStats: { effect: 20 }, defaultBotLevel: 7 });
+    expect(rules.baseStats).toEqual({ ...resolveProgressionRules().baseStats, effect: 20 });
+    expect(toInstanceConfig({ progressionRules: { defaultBotLevel: 7 } }).progressionRules.defaultBotLevel).toBe(7);
+    for (const input of [
+      { maxLevel: 5, defaultBotLevel: 6 }, { xpPerLevel: 0 }, { xpPerLevel: '100' },
+      { baseStats: null }, { perLevelStats: [] }, { baseStats: { effect: -1 } },
+      { perLevelStats: { level: 1 } }, { unknown: 1 }, { maxAwardsPerWindow: 0 },
+    ]) expect(() => resolveProgressionRules(input)).toThrow();
+    for (const level of [0, -1, 65536, 1.5, null, '2']) expect(() => toEntityMsg({ level })).toThrow();
+  });
+
+  it('uses signed deterministic stats in the procedural pipeline', () => {
+    registerSemantic('stat-contract', { semanticTags: ['test'], paletteHints: [[0, 0, 0, 255]],
+      preferredShapes: {}, layers: {}, itemType: 'weapon' });
+    const options = { itemId: 'stat-contract-test', seed: 'signed-contract', frameCount: 1 };
+    const generated = generateMultiFrame(options).objectLayerData.data.stats;
+    expect(validateStats(generated)).toEqual(generated);
+    expect(generateMultiFrame(options).objectLayerData.data.stats).toEqual(generated);
+    expect(Object.values(generated).some((value) => value < 0)).toBe(true);
+    const samples = Array.from({ length: 8 }, (_, index) =>
+      Object.values(generateMultiFrame({ ...options, seed: 'signed-' + index }).objectLayerData.data.stats)).flat();
+    expect(samples.some((value) => value > 10)).toBe(true);
+  });
+
+  it('rejects invalid map levels before file cleanup', async () => {
+    const model = vi.spyOn(DataBaseProviderService, 'getModel').mockImplementation((name) => {
+      expect(name).toBe('CyberiaMap');
+      return CyberiaMapModel;
+    });
+    const lookup = vi.spyOn(CyberiaMapModel, 'findById').mockResolvedValue(new CyberiaMapModel({ code: 'level-test' }));
+    try {
+      await expect(CyberiaMapService.put({ params: { id: 'test' }, auth: { user: { role: 'admin' } },
+        body: { entities: [{ entityType: 'bot', level: -1 }] } }, {}, {})).rejects.toThrow();
+      expect(model).toHaveBeenCalledTimes(1);
+    } finally {
+      model.mockRestore();
+      lookup.mockRestore();
+    }
+  });
+
+  // cyberia-server and cyberia-client are gitignored siblings this repo does not contain (see
+  // .gitignore); a checkout that only has this repo's own tracked tree has nothing to check.
+  it.skipIf(!hasCyberiaSiblings())('matches generated Go and C contracts', async () => {
+    await generateStatContract({ check: true });
+  });
+});
+
+describe('Cyberia stats CLI', () => {
+  it('validates files and generates bounded random stats', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'cyberia-stats-test-'));
+    const output = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const run = async (...args) => {
+      const command = new Command().exitOverride();
+      registerStatCommands(command);
+      await command.parseAsync(args, { from: 'user' });
+    };
+    try {
+      const input = join(directory, 'input.json');
+      const source = JSON.stringify([record(block(-100))]);
+      await writeFile(input, source);
+      await run('stats', 'validate', input);
+      expect(JSON.parse(output.mock.calls.at(-1)[0])).toEqual({ valid: true, records: 1 });
+      await writeFile(input, JSON.stringify([record(block(101))]));
+      await expect(run('stats', 'validate', input)).rejects.toThrow();
+      await run('stats', 'random', '--min=-100', '--max=-100');
+      expect(JSON.parse(output.mock.calls.at(-1)[0])).toEqual(block(-100));
+      await expect(run('stats', 'random', '--min=-101')).rejects.toThrow();
+    } finally {
+      output.mockRestore();
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+});