@underpostnet/cyberia 3.3.0 → 3.3.76

package/test/unit/coverage-artifact.test.js

@@ -0,0 +1,221 @@
+'use strict';
+
+/**
+ * @module coverage-artifact.test
+ * @description Covers the coverage report as a build artifact: where a run leaves it, where an
+ * assembled deploy artifact carries it, and the guard that keeps a workload container from
+ * writing the runtime status contract while a test runner is what is executing.
+ *
+ * Uses 'chai' for assertions.
+ */
+
+import { expect } from 'chai';
+import fs from 'fs-extra';
+import {
+  COVERAGE_BUNDLE_DIRECTORY,
+  bundleCoverageReports,
+  coverageReportCandidates,
+  coverageReportCommand,
+  coverageReportsFactory,
+  coverageUnavailablePage,
+  deployCoverageReports,
+  resolveCoverageReportPath,
+} from '../../src/server/build/coverage.js';
+import { EXECUTION_PROFILE_ENV_KEY } from '../../src/server/build/execution.js';
+import { isTestRuntime, runtimeStatusWritable } from '../../src/server/runtime/runtime-status.js';
+
+describe('coverage report declaration', () => {
+  it('reads each declared report with its label defaulting to the id', () => {
+    expect(coverageReportsFactory({ coverage: [{ id: 'engine', suite: 'unit' }] })).to.deep.equal([
+      { id: 'engine', label: 'engine', suite: 'unit', path: undefined },
+    ]);
+  });
+
+  it('declares nothing for a deploy without coverage', () => {
+    expect(coverageReportsFactory({})).to.deep.equal([]);
+    expect(coverageReportsFactory(undefined)).to.deep.equal([]);
+  });
+
+  it('rejects an entry without exactly one source, a non-slug id, or a repeated id', () => {
+    expect(() => coverageReportsFactory({ coverage: [{ id: 'x' }] })).to.throw("exactly one of 'suite' or 'path'");
+    expect(() => coverageReportsFactory({ coverage: [{ id: 'x', suite: 'unit', path: './' }] })).to.throw(
+      'exactly one',
+    );
+    expect(() => coverageReportsFactory({ coverage: [{ id: 'Bad Id', suite: 'unit' }] })).to.throw('slug');
+    expect(() =>
+      coverageReportsFactory({
+        coverage: [
+          { id: 'x', suite: 'unit' },
+          { id: 'x', suite: 'app' },
+        ],
+      }),
+    ).to.throw('declared twice');
+  });
+
+  it("collects a deploy's reports across routes once each", () => {
+    const route = { docs: { coverage: [{ id: 'engine', suite: 'unit' }] } };
+    const confServer = { 'a.test': { '/': route, '/store': route }, 'b.test': { '/': {} } };
+    expect(deployCoverageReports(confServer).map(({ id }) => id)).to.deep.equal(['engine']);
+  });
+
+  it('refuses one id declared with two sources', () => {
+    const confServer = {
+      'a.test': {
+        '/': { docs: { coverage: [{ id: 'engine', suite: 'unit' }] } },
+        '/store': { docs: { coverage: [{ id: 'engine', suite: 'app' }] } },
+      },
+    };
+    expect(() => deployCoverageReports(confServer)).to.throw('two different sources');
+  });
+
+  it('names the command that produces each kind of report', () => {
+    expect(coverageReportCommand({ suite: 'unit,infra,app' })).to.equal('node bin test unit,infra,app');
+    expect(coverageReportCommand({ path: './hardhat/' })).to.equal('npm run coverage --prefix ./hardhat');
+  });
+});
+
+describe('coverage report resolution', () => {
+  let fixturePath;
+  let cwd;
+
+  // The bundled candidate is cwd-relative, and a published deploy artifact (the tree a
+  // downstream CI runs this suite in) carries real reports under it; resolve against the
+  // fixture, never the tree.
+  beforeEach(() => {
+    fixturePath = fs.mkdtempSync('/tmp/engine-coverage-artifact-');
+    cwd = process.cwd();
+    process.chdir(fixturePath);
+  });
+
+  afterEach(() => {
+    process.chdir(cwd);
+    fs.removeSync(fixturePath);
+  });
+
+  it("looks for a suite's own run output first and the bundled artifact last", () => {
+    expect(coverageReportCandidates({ id: 'engine', suite: 'unit,infra,app' })).to.deep.equal([
+      'coverage/unit-infra-app',
+      `${COVERAGE_BUNDLE_DIRECTORY}/engine`,
+    ]);
+  });
+
+  it("looks through an external tree's report layouts before the bundled artifact", () => {
+    expect(coverageReportCandidates({ id: 'hardhat', path: '/src/' })).to.deep.equal([
+      '/src/coverage/html',
+      '/src/coverage/lcov-report',
+      '/src/coverage',
+      `${COVERAGE_BUNDLE_DIRECTORY}/hardhat`,
+    ]);
+  });
+
+  it('ignores a coverage directory that carries no HTML index', () => {
+    fs.outputFileSync(`${fixturePath}/coverage/lcov.info`, 'TN:\n');
+    expect(resolveCoverageReportPath({ id: 'x', path: fixturePath })).to.equal(undefined);
+  });
+
+  it('resolves the report of the selection the deploy names, not the last run made', () => {
+    fs.outputFileSync(`${fixturePath}/coverage/unit-infra-app-cyberia/index.html`, '<!doctype html>');
+    fs.outputFileSync(`${fixturePath}/coverage/cyberia/index.html`, '<!doctype html>');
+    expect(resolveCoverageReportPath({ id: 'x', suite: 'cyberia' })).to.equal('coverage/cyberia');
+    expect(resolveCoverageReportPath({ id: 'x', suite: 'unit,infra,app' })).to.equal(undefined);
+  });
+
+  it('falls back to the report a deploy artifact already carries', () => {
+    fs.outputFileSync(`${fixturePath}/${COVERAGE_BUNDLE_DIRECTORY}/hardhat/index.html`, '<!doctype html>');
+    expect(resolveCoverageReportPath({ id: 'hardhat', path: `${fixturePath}/hardhat` })).to.equal(
+      `${COVERAGE_BUNDLE_DIRECTORY}/hardhat`,
+    );
+  });
+});
+
+describe('coverage bundling into a deploy artifact', () => {
+  let fixturePath;
+  let cwd;
+
+  // The bundled candidate is cwd-relative, and a published deploy artifact (the tree a
+  // downstream CI runs this suite in) carries real reports under it; resolve against the
+  // fixture, never the tree.
+  beforeEach(() => {
+    fixturePath = fs.mkdtempSync('/tmp/engine-coverage-artifact-');
+    cwd = process.cwd();
+    process.chdir(fixturePath);
+  });
+
+  afterEach(() => {
+    process.chdir(cwd);
+    fs.removeSync(fixturePath);
+  });
+
+  it('carries each report into the artifact under its own id', () => {
+    fs.outputFileSync(`${fixturePath}/hardhat/coverage/html/index.html`, '<!doctype html><title>report</title>');
+    fs.outputFileSync(`${fixturePath}/hardhat/coverage/html/base.css`, 'body {}');
+
+    const [result] = bundleCoverageReports(
+      [{ id: 'hardhat', path: `${fixturePath}/hardhat` }],
+      `${fixturePath}/template`,
+    );
+
+    expect(result.bundled).to.equal(true);
+    expect(result.to).to.equal(`${fixturePath}/template/${COVERAGE_BUNDLE_DIRECTORY}/hardhat`);
+    expect(fs.readFileSync(`${result.to}/index.html`, 'utf8')).to.include('report');
+    expect(fs.existsSync(`${result.to}/base.css`)).to.equal(true);
+  });
+
+  it('replaces a previously bundled report rather than merging into it', () => {
+    fs.outputFileSync(`${fixturePath}/template/${COVERAGE_BUNDLE_DIRECTORY}/hardhat/stale.html`, 'stale');
+    fs.outputFileSync(`${fixturePath}/hardhat/coverage/index.html`, '<!doctype html><title>fresh</title>');
+
+    const [{ to }] = bundleCoverageReports(
+      [{ id: 'hardhat', path: `${fixturePath}/hardhat` }],
+      `${fixturePath}/template`,
+    );
+
+    expect(fs.existsSync(`${to}/stale.html`)).to.equal(false);
+    expect(fs.readFileSync(`${to}/index.html`, 'utf8')).to.include('fresh');
+  });
+
+  it('reports what was not bundled without creating its directory', () => {
+    const [result] = bundleCoverageReports(
+      [{ id: 'hardhat', path: `${fixturePath}/hardhat` }],
+      `${fixturePath}/template`,
+    );
+
+    expect(result).to.deep.equal({
+      id: 'hardhat',
+      bundled: false,
+      to: `${fixturePath}/template/${COVERAGE_BUNDLE_DIRECTORY}/hardhat`,
+    });
+    expect(fs.existsSync(result.to)).to.equal(false);
+  });
+
+  it('renders a static unavailable page naming the report and the run that produces it', () => {
+    const page = coverageUnavailablePage({ id: 'engine', suite: 'unit,infra,app' });
+    expect(page).to.include('Coverage report unavailable');
+    expect(page).to.include('node bin test unit,infra,app');
+    expect(page).to.include(`${COVERAGE_BUNDLE_DIRECTORY}/engine`);
+    expect(page).not.to.include('<script');
+  });
+});
+
+// Regression: a suite run inside a pod latched `container-status=error` on every expected
+// non-zero exit, and the CD monitor failed the rollout on a deployment that was healthy.
+describe('runtime status contract writability', () => {
+  it('recognizes a test runner as the executing context', () => {
+    expect(isTestRuntime()).to.equal(true);
+  });
+
+  it('refuses to write the contract from under a test runner', () => {
+    expect(runtimeStatusWritable()).to.equal(false);
+  });
+
+  it('refuses to write the contract under a non-live execution profile', () => {
+    const previous = process.env[EXECUTION_PROFILE_ENV_KEY];
+    try {
+      process.env[EXECUTION_PROFILE_ENV_KEY] = 'HERMETIC_BUILD';
+      expect(runtimeStatusWritable()).to.equal(false);
+    } finally {
+      if (previous === undefined) delete process.env[EXECUTION_PROFILE_ENV_KEY];
+      else process.env[EXECUTION_PROFILE_ENV_KEY] = previous;
+    }
+  });
+});

package/test/{crypto.test.js → unit/crypto.test.js}

@@ -9,7 +9,7 @@
 import { expect } from 'chai';
 
 // Import the cryptographic classes from the Canvas's refactored module
-import { SymmetricCrypto, AsymmetricCrypto } from '../src/server/crypto.js';
+import { SymmetricCrypto, AsymmetricCrypto } from '../../src/server/security/crypto.js';
 
 // Define a common plaintext message for testing
 const plaintext = 'This is a secret message for testing cryptographic operations.';

package/test/unit/cyberia/instance-backup.test.js

@@ -0,0 +1,183 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// The restore path only routes documents; the collections are in-memory stand-ins, IPFS is
+// unreachable, and the static frame writer is a no-op, so what is asserted is the routing.
+const models = {};
+vi.mock('../../../src/db/DataBaseProvider.js', () => ({
+  DataBaseProviderService: { getModel: (name) => models[name] },
+}));
+vi.mock('../../../src/api/ipfs/ipfs.service.js', () => ({ createPinRecord: async () => ({}) }));
+vi.mock('../../../src/projects/cyberia/ipfs-client.js', () => ({ IpfsClient: { addToIpfs: async () => null } }));
+vi.mock('../../../src/projects/cyberia/object-layer.js', () => ({
+  ObjectLayerEngine: { writeStaticFrameAssets: async () => [], computeAndSaveFinalSha256: async () => ({}) },
+}));
+// The generator pulls in jimp, a cyberia product dependency the engine runner does not install;
+// every store method that would reach it is spied out below, so only the constant is needed.
+vi.mock('../../../src/projects/cyberia/atlas-sprite-sheet-generator.js', () => ({
+  AtlasSpriteSheetGenerator: {},
+  DEFAULT_ATLAS_UPSCALE_FACTOR: 20,
+}));
+
+const { AtlasSpriteSheetStore } = await import('../../../src/projects/cyberia/atlas-sprite-sheet-store.js');
+const { atlasBackupFileKey, readObjectLayerBackup, restoreObjectLayerBackup } =
+  await import('../../../src/projects/cyberia/instance-backup.js');
+
+/** A collection that remembers what was created and hands the last upsert back as the live document. */
+const collection = () => {
+  const created = [];
+  let live = null;
+  const query = (value) => Object.assign(Promise.resolve(value), { populate: () => Promise.resolve(value) });
+  return {
+    created,
+    deleteOne: async () => ({ deletedCount: 0 }),
+    create: async (doc) => (created.push(doc), doc),
+    findByItemId: () => query(live),
+    upsertByItemId: async (doc) => {
+      live = { ...doc, markModified() {}, save: async () => live };
+      return live;
+    },
+    get live() {
+      return live;
+    },
+  };
+};
+
+let backupDir;
+const write = (rel, value) => writeFile(join(backupDir, rel), Buffer.isBuffer(value) ? value : JSON.stringify(value));
+
+beforeAll(async () => {
+  backupDir = await mkdtemp(join(tmpdir(), 'cyberia-backup-'));
+  for (const dir of ['object-layers', 'render-frames', 'atlas-sprite-sheets', 'files', 'ipfs/content']) {
+    await mkdir(join(backupDir, dir), { recursive: true });
+  }
+  await write('object-layers/hatchet.json', {
+    _id: 'ol1',
+    cid: 'cid-data',
+    objectLayerRenderFramesId: 'rf1',
+    atlasSpriteSheetId: 'at1',
+    data: { item: { id: 'hatchet', type: 'weapon' }, render: { cid: 'cid-png', metadataCid: 'cid-meta' } },
+  });
+  await write('render-frames/hatchet.json', { _id: 'rf1', frames: {}, colors: [], frame_duration: 100 });
+  await write('atlas-sprite-sheets/hatchet.json', {
+    _id: 'at1',
+    fileId: 'f-full',
+    minifyFileId: 'f-min',
+    idlePreviewFileId: 'f-idle',
+    cid: 'cid-png',
+  });
+  // Files are matched on _id, never on name: one is misnamed on purpose, one is a bystander.
+  await write('files/whatever.json', {
+    _id: 'f-full',
+    name: 'hatchet-atlas.png',
+    data: { $base64: Buffer.from('PNG').toString('base64') },
+  });
+  await write('files/atlas-minify-hatchet.json', {
+    _id: 'f-min',
+    name: 'hatchet-minify.png',
+    data: { type: 'Buffer', data: [1, 2, 3] },
+  });
+  await write('files/atlas-idle-hatchet.json', { _id: 'f-idle', name: 'hatchet-idle.png', data: { $base64: 'AA==' } });
+  await write('files/atlas-sword.json', { _id: 'f-other', name: 'sword-atlas.png', data: { $base64: 'AA==' } });
+  await write('ipfs/content/cid-data.bin', Buffer.from('data'));
+  await write('ipfs/content/cid-png.bin', Buffer.from('png'));
+  // cid-meta has no payload on purpose.
+});
+
+afterAll(() => rm(backupDir, { recursive: true, force: true }));
+
+describe('reading one object layer out of an instance backup', () => {
+  it('gathers the object layer and every document it references', () => {
+    const backup = readObjectLayerBackup({ backupDir, itemId: 'hatchet' });
+    expect(backup.objectLayer.data.item.id).toBe('hatchet');
+    expect(backup.renderFrames._id).toBe('rf1');
+    expect(backup.atlas._id).toBe('at1');
+  });
+
+  it('resolves the atlas render Files by _id and leaves other Files alone', () => {
+    const { files } = readObjectLayerBackup({ backupDir, itemId: 'hatchet' });
+    expect(files.map((f) => f._id).sort()).toEqual(['f-full', 'f-idle', 'f-min']);
+  });
+
+  it('names each exported render after its atlas field', () => {
+    expect(atlasBackupFileKey('fileId', 'hatchet')).toBe('atlas-hatchet');
+    expect(atlasBackupFileKey('minifyFileId', 'hatchet')).toBe('atlas-minify-hatchet');
+    expect(atlasBackupFileKey('idlePreviewFileId', 'hatchet')).toBe('atlas-idle-hatchet');
+  });
+
+  it('decodes both File byte encodings the export can write', () => {
+    const { files } = readObjectLayerBackup({ backupDir, itemId: 'hatchet' });
+    const byId = Object.fromEntries(files.map((f) => [f._id, f.data]));
+    expect(Buffer.isBuffer(byId['f-full']) && byId['f-full'].toString()).toBe('PNG');
+    expect(Buffer.isBuffer(byId['f-min']) && [...byId['f-min']]).toEqual([1, 2, 3]);
+  });
+
+  it('collects only the payloads the backup actually carries', () => {
+    const { payloads } = readObjectLayerBackup({ backupDir, itemId: 'hatchet' });
+    expect([...payloads.keys()].sort()).toEqual(['cid-data', 'cid-png']);
+    expect(payloads.get('cid-png').toString()).toBe('png');
+  });
+
+  it('names the backup and item when the item is missing', () => {
+    expect(() => readObjectLayerBackup({ backupDir, itemId: 'ghost' })).toThrow(/no object layer 'ghost'/);
+  });
+
+  it('tolerates an item with no atlas or render frames yet', async () => {
+    await write('object-layers/bare.json', { _id: 'ol2', data: { item: { id: 'bare', type: 'floor' } } });
+    const backup = readObjectLayerBackup({ backupDir, itemId: 'bare' });
+    expect(backup.atlas).toBeNull();
+    expect(backup.renderFrames).toBeNull();
+    expect(backup.files).toEqual([]);
+    expect(backup.payloads.size).toBe(0);
+  });
+});
+
+describe('restoring one object layer from an instance backup', () => {
+  let persist;
+  let idle;
+
+  beforeEach(() => {
+    for (const name of ['ObjectLayer', 'ObjectLayerRenderFrames', 'AtlasSpriteSheet', 'File'])
+      models[name] = collection();
+    persist = vi.spyOn(AtlasSpriteSheetStore, 'persist').mockResolvedValue({
+      atlasDoc: { _id: 'at-rebuilt' },
+      atlasCid: 'cid-rebuilt-png',
+      atlasMetadataCid: 'cid-rebuilt-meta',
+    });
+    idle = vi.spyOn(AtlasSpriteSheetStore, 'syncIdlePreview').mockResolvedValue({ status: 'unchanged' });
+    vi.spyOn(AtlasSpriteSheetStore, 'pruneOrphanRenders').mockResolvedValue(0);
+  });
+
+  afterAll(() => vi.restoreAllMocks());
+
+  it('keeps the atlas the backup carries when it holds its minified render', async () => {
+    await restoreObjectLayerBackup({ backupDir, itemId: 'hatchet', options: {} });
+    expect(models.AtlasSpriteSheet.created[0].minifyFileId).toBe('f-min');
+    expect(persist).not.toHaveBeenCalled();
+    expect(idle).toHaveBeenCalledWith({ itemKey: 'hatchet', options: {} });
+    expect(models.ObjectLayer.live.data.render).toEqual({ cid: 'cid-png', metadataCid: 'cid-meta' });
+  });
+
+  // Regression: a backup written before the minified render existed restored an atlas the
+  // blob route could not serve, and the client runtime got a 500 for every entity wearing it.
+  it('rebuilds the atlas a backup restores without its minified render and relinks the item', async () => {
+    await write('object-layers/relic.json', {
+      _id: 'ol3',
+      objectLayerRenderFramesId: 'rf3',
+      atlasSpriteSheetId: 'at3',
+      data: { item: { id: 'relic', type: 'skin' }, render: { cid: 'cid-old-png', metadataCid: 'cid-old-meta' } },
+    });
+    const frames = { _id: 'rf3', frames: { down_idle: [] }, colors: [], frame_duration: 100 };
+    await write('render-frames/relic.json', frames);
+    await write('atlas-sprite-sheets/relic.json', { _id: 'at3', fileId: 'f-relic', minifyFileId: null });
+
+    await restoreObjectLayerBackup({ backupDir, itemId: 'relic', options: {} });
+
+    expect(persist).toHaveBeenCalledWith({ itemKey: 'relic', objectLayerRenderFrames: frames, options: {} });
+    const { live } = models.ObjectLayer;
+    expect(live.atlasSpriteSheetId).toBe('at-rebuilt');
+    expect(live.data.render).toEqual({ cid: 'cid-rebuilt-png', metadataCid: 'cid-rebuilt-meta' });
+  });
+});

package/test/unit/cyberia/instance-object-layer-items.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { fetchInstanceObjectLayerItemIds } from '../../../src/projects/cyberia/instance-data.js';
+
+const lean = (value) => ({ lean: async () => value, populate: () => lean(value) });
+
+const buildModels = ({ instance, maps = [], storedItemIds = [] }) => ({
+  CyberiaInstance: { findOne: () => lean(instance) },
+  CyberiaInstanceConf: { findOne: () => lean({ instanceCode: instance?.code, entityDefaults: [] }) },
+  CyberiaMap: { find: () => lean(maps) },
+  CyberiaEntityTypeDefault: { find: () => lean([]) },
+  CyberiaAction: { find: () => lean([]) },
+  CyberiaQuest: { find: () => lean([]) },
+  CyberiaSkill: { find: () => lean([]) },
+  ObjectLayer: {
+    find: (filter) => {
+      const wanted = new Set(filter['data.item.id'].$in);
+      return lean(storedItemIds.filter((id) => wanted.has(id)).map((id) => ({ _id: id, data: { item: { id } } })));
+    },
+  },
+});
+
+describe('instance object layer item ids', () => {
+  it('collects the item ids the instance maps place, limited to stored documents', async () => {
+    const models = buildModels({
+      instance: { _id: 'i1', code: 'FOREST', cyberiaMapCodes: ['forest-1'] },
+      maps: [
+        {
+          code: 'forest-1',
+          entities: [{ objectLayerItemIds: ['anon', 'hatchet'] }, { objectLayerItemIds: ['hatchet', '$runtime'] }],
+        },
+      ],
+      storedItemIds: ['anon', 'hatchet', 'unrelated'],
+    });
+    const itemIds = await fetchInstanceObjectLayerItemIds(models, 'FOREST');
+    expect(itemIds).toContain('anon');
+    expect(itemIds).toContain('hatchet');
+    expect(itemIds).not.toContain('unrelated');
+    expect(itemIds).not.toContain('$runtime');
+    expect(new Set(itemIds).size).toBe(itemIds.length);
+  });
+
+  it('fails on an unknown instance code instead of returning the fallback world', async () => {
+    const models = buildModels({ instance: null });
+    await expect(fetchInstanceObjectLayerItemIds(models, 'GHOST')).rejects.toThrow('"GHOST" not found');
+  });
+});

package/test/unit/cyberia/publish-workflow.test.js

@@ -0,0 +1,22 @@
+import { expect } from 'chai';
+import fs from 'fs-extra';
+// Named import: js-yaml's ESM build exports no default.
+import { load } from 'js-yaml';
+
+describe('the cyberia publish workflow', () => {
+  it('rewrites the published manifest after the install and before every publish', () => {
+    // The rewrite is the publish step's alone: a checkout that installed the published shape
+    // would run the engine source against a second engine in node_modules.
+    const workflow = load(fs.readFileSync('./.github/workflows/publish.cyberia.ci.yml', 'utf8'));
+
+    for (const [job, { steps }] of Object.entries(workflow.jobs)) {
+      const commands = steps.map(({ run }) => `${run ?? ''}`);
+      const restore = commands.findIndex((command) => command.includes('publishedProductPackageJson'));
+      const install = commands.findIndex((command) => command.trim().startsWith('npm ci'));
+      const publish = commands.findIndex((command) => command.includes('npm publish'));
+
+      expect(restore, `${job}: restores the published manifest`).to.be.greaterThan(install);
+      expect(restore, `${job}: restores it before publishing`).to.be.lessThan(publish);
+    }
+  });
+});

package/test/unit/cyberia/stat-balance.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { balanceStats, resolveStatBounds, statPolicyActive } from '../../../src/projects/cyberia/stat-balance.js';
+import {
+  STAT_TYPE_BOUNDS,
+  STAT_TYPES,
+  statBoundsForType,
+} from '../../../src/client/components/cyberia/SharedDefaultsCyberia.js';
+
+const wild = { effect: 60, resistance: -40, agility: 3, range: 25, intelligence: 9, utility: -2 };
+const lcg = (seed) => () => (seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0) / 4294967296;
+
+describe('stat balancing policy', () => {
+  it('is inert without normalize or random', () => {
+    expect(statPolicyActive({})).toBe(false);
+    expect(balanceStats({ stats: wild, itemType: 'weapon' })).toEqual(wild);
+  });
+
+  it('clamps into the semantic bounds of the item type', () => {
+    expect(balanceStats({ stats: wild, itemType: 'weapon', policy: { normalize: true } })).toEqual({
+      effect: 20,
+      resistance: -10,
+      agility: 3,
+      range: 10,
+      intelligence: 5,
+      utility: 0,
+    });
+    expect(balanceStats({ stats: wild, itemType: 'skin', policy: { normalize: true } })).toEqual({
+      effect: 1,
+      resistance: 0,
+      agility: 3,
+      range: 0,
+      intelligence: 2,
+      utility: 0,
+    });
+  });
+
+  it('keeps the contract bounds for a type without semantic bounds', () => {
+    expect(statBoundsForType('unknown')).toEqual(Object.fromEntries(STAT_TYPES.map((key) => [key, [-100, 100]])));
+    expect(balanceStats({ stats: wild, itemType: 'unknown', policy: { normalize: true } })).toEqual(wild);
+  });
+
+  it('is idempotent and deterministic', () => {
+    const once = balanceStats({ stats: wild, itemType: 'weapon', policy: { normalize: true } });
+    expect(balanceStats({ stats: once, itemType: 'weapon', policy: { normalize: true } })).toEqual(once);
+    const policy = { normalize: true, random: true, min: 0, max: 8 };
+    const first = balanceStats({ stats: wild, itemType: 'weapon', policy, random: lcg(7) });
+    expect(balanceStats({ stats: wild, itemType: 'weapon', policy, random: lcg(7) })).toEqual(first);
+    for (const key of STAT_TYPES) {
+      const [lo, hi] = resolveStatBounds('weapon', policy)[key];
+      expect(first[key]).toBeGreaterThanOrEqual(lo);
+      expect(first[key]).toBeLessThanOrEqual(hi);
+    }
+  });
+
+  it('lets min and max narrow the semantic range and pins a request outside it', () => {
+    expect(resolveStatBounds('weapon', { normalize: true, min: 12, max: 30 }).effect).toEqual([12, 20]);
+    expect(resolveStatBounds('weapon', { normalize: true, min: 50 }).effect).toEqual([20, 20]);
+    expect(resolveStatBounds('weapon', { normalize: true, max: -50 }).resistance).toEqual([-10, -10]);
+    expect(resolveStatBounds('weapon', { min: -20, max: 20 }).effect).toEqual([-20, 20]);
+    expect(() => resolveStatBounds('weapon', { min: 5, max: 1 })).toThrow('minimum');
+    expect(() => resolveStatBounds('weapon', { min: -101 })).toThrow();
+  });
+
+  it('declares every semantic bound inside the contract and in order', () => {
+    for (const bounds of Object.values(STAT_TYPE_BOUNDS)) {
+      for (const [lo, hi] of Object.values(bounds)) expect(lo <= hi && lo >= -100 && hi <= 100).toBe(true);
+    }
+  });
+});

package/test/unit/deploy-env-resolution.test.js

@@ -0,0 +1,38 @@
+'use strict';
+
+import { expect } from 'chai';
+import { deployEnvFactory } from '../../src/server/runtime/environment.js';
+
+describe('deploy environment resolution', () => {
+  const originalNodeEnv = process.env.NODE_ENV;
+
+  afterEach(() => {
+    if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = originalNodeEnv;
+  });
+
+  it('prefers an explicit --env over every other signal', () => {
+    process.env.NODE_ENV = 'development';
+    expect(deployEnvFactory({ env: 'production', dev: true }, 'test')).to.equal('production');
+    expect(deployEnvFactory({ env: '  staging  ' })).to.equal('staging');
+  });
+
+  it('treats --dev as the development shorthand', () => {
+    expect(deployEnvFactory({ dev: true })).to.equal('development');
+    expect(deployEnvFactory({ dev: true }, 'test')).to.equal('development');
+  });
+
+  it('falls back to the caller-supplied default, never to ambient NODE_ENV', () => {
+    process.env.NODE_ENV = 'development';
+    expect(deployEnvFactory({})).to.equal('production');
+    expect(deployEnvFactory()).to.equal('production');
+    expect(deployEnvFactory({ env: '' }, 'test')).to.equal('test');
+  });
+
+  it('lets a caller opt into the ambient environment by passing it as the fallback', () => {
+    process.env.NODE_ENV = 'production';
+    expect(deployEnvFactory({}, process.env.NODE_ENV || 'development')).to.equal('production');
+    delete process.env.NODE_ENV;
+    expect(deployEnvFactory({}, process.env.NODE_ENV || 'development')).to.equal('development');
+  });
+});