@underpostnet/cyberia 3.3.0 → 3.3.76

package/test/integration/app/cyberia/fallback-world-capture.test.js

@@ -0,0 +1,338 @@
+'use strict';
+
+import { expect } from 'chai';
+
+import { generateFallbackWorld } from '../../../../src/api/cyberia-instance/cyberia-fallback-world.js';
+import {
+  planFallbackCapture,
+  captureFallbackWorld,
+  captureMapCode,
+} from '../../../../src/api/cyberia-instance/cyberia-fallback-capture.js';
+import { fallbackAudioConfig } from '../../../../src/projects/cyberia/seed-audio.js';
+import {
+  DefaultCyberiaActions,
+  DefaultCyberiaQuests,
+  DefaultSkillConfig,
+  ENTITY_TYPE_DEFAULTS,
+} from '../../../../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
+
+const INSTANCE_CODE = 'CAPTURE-TEST';
+
+// ── Minimal in-memory stand-ins for the Mongoose models the capture writes ───
+// Only the query shapes cyberia-fallback-capture.js actually issues are
+// supported: equality filters, `$in`, `$nin` and `$regex` on `code`.
+
+const matchesValue = (docValue, expected) => {
+  if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+    if (expected.$in && !expected.$in.includes(docValue)) return false;
+    if (expected.$nin && expected.$nin.includes(docValue)) return false;
+    if (expected.$regex && !expected.$regex.test(String(docValue ?? ''))) return false;
+    return true;
+  }
+  if (Array.isArray(expected)) return JSON.stringify(docValue ?? []) === JSON.stringify(expected);
+  return docValue === expected;
+};
+
+const readPath = (doc, path) => path.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), doc);
+
+const matchesFilter = (doc, filter) =>
+  Object.entries(filter).every(([key, expected]) => matchesValue(readPath(doc, key), expected));
+
+class FakeModel {
+  constructor(docs = []) {
+    this.docs = docs.map((doc) => ({ ...doc }));
+    this.upserts = 0;
+    this.inserts = 0;
+  }
+  find(filter = {}) {
+    return { lean: async () => this.docs.filter((doc) => matchesFilter(doc, filter)) };
+  }
+  findOne(filter = {}) {
+    return { lean: async () => this.docs.find((doc) => matchesFilter(doc, filter)) || null };
+  }
+  async findOneAndUpdate(filter, update, options = {}) {
+    this.upserts++;
+    let doc = this.docs.find((entry) => matchesFilter(entry, filter));
+    if (!doc) {
+      if (!options.upsert) return null;
+      doc = { _id: `id-${this.docs.length + 1}`, ...filter, ...(update.$setOnInsert || {}) };
+      this.docs.push(doc);
+    }
+    Object.assign(doc, update.$set || {});
+    return doc;
+  }
+  async create(doc) {
+    this.inserts++;
+    this.docs.push({ _id: `id-${this.docs.length + 1}`, ...doc });
+    return doc;
+  }
+  async deleteMany(filter = {}) {
+    const kept = this.docs.filter((doc) => !matchesFilter(doc, filter));
+    const deletedCount = this.docs.length - kept.length;
+    this.docs = kept;
+    return { deletedCount };
+  }
+}
+
+// Every asset the fallback audio configuration binds, as `cyberia audio --import` would leave them.
+const AUDIO_CONFIG = fallbackAudioConfig();
+const importedAudioCodes = () => [
+  ...new Set([...AUDIO_CONFIG.events.map((e) => e.audioCode), ...AUDIO_CONFIG.maps.map((m) => m.defaultMusic)]),
+];
+
+const buildModels = ({ objectLayerItemIds = [], audioCodes = importedAudioCodes(), seeded = {} } = {}) => ({
+  CyberiaInstance: new FakeModel(seeded.instances),
+  CyberiaInstanceConf: new FakeModel(seeded.confs),
+  CyberiaMap: new FakeModel(seeded.maps),
+  CyberiaAction: new FakeModel(seeded.actions),
+  CyberiaQuest: new FakeModel(seeded.quests),
+  CyberiaSkill: new FakeModel(seeded.skills),
+  CyberiaEntityTypeDefault: new FakeModel(seeded.entityTypeDefaults),
+  CyberiaDialogue: new FakeModel(seeded.dialogues),
+  CyberiaMapAudioConf: new FakeModel(seeded.audioConfs),
+  CyberiaAudio: new FakeModel(audioCodes.map((code) => ({ code }))),
+  ObjectLayer: new FakeModel(objectLayerItemIds.map((id) => ({ data: { item: { id } } }))),
+});
+
+describe('planFallbackCapture', () => {
+  const world = generateFallbackWorld();
+  const plan = planFallbackCapture({ world, instanceCode: INSTANCE_CODE });
+
+  it('namespaces every map code under the instance code', () => {
+    expect(plan.maps.map((m) => m.code)).to.deep.equal(world.maps.map((m) => captureMapCode(m.code, INSTANCE_CODE)));
+    expect(plan.instance.cyberiaMapCodes).to.deep.equal(plan.maps.map((m) => m.code));
+    for (const code of plan.instance.cyberiaMapCodes) expect(code).to.not.include('fallback-map-');
+  });
+
+  it('rewrites portal edges and the player spawn onto the captured map codes', () => {
+    const captured = new Set(plan.instance.cyberiaMapCodes);
+    expect(plan.instance.portals.length).to.equal(world.instance.portals.length);
+    for (const portal of plan.instance.portals) {
+      expect(captured.has(portal.sourceMapCode), portal.sourceMapCode).to.equal(true);
+      expect(captured.has(portal.targetMapCode), portal.targetMapCode).to.equal(true);
+    }
+    expect(captured.has(plan.instance.playerSpawn.sourceMapCode)).to.equal(true);
+    expect(plan.instance.playerSpawn.sourceCellX).to.equal(world.instance.playerSpawn.sourceCellX);
+  });
+
+  it('carries every generated entity onto the captured maps', () => {
+    for (const [index, map] of plan.maps.entries()) {
+      expect(map.entities.length).to.equal(world.maps[index].entities.length);
+    }
+  });
+
+  it('keeps action and quest cross-references internally consistent', () => {
+    expect(plan.actions.length).to.equal(DefaultCyberiaActions.length);
+    expect(plan.quests.length).to.equal(DefaultCyberiaQuests.length);
+
+    const questCodes = new Set(plan.quests.map((q) => q.code));
+    const mapCodes = new Set(plan.instance.cyberiaMapCodes);
+
+    for (const action of plan.actions) {
+      expect(mapCodes.has(action.sourceMapCode), action.code).to.equal(true);
+      for (const entry of action.questDialogueCodes || []) {
+        expect(questCodes.has(entry.questCode), entry.questCode).to.equal(true);
+      }
+    }
+    for (const quest of plan.quests) {
+      expect(mapCodes.has(quest.sourceMapCode), quest.code).to.equal(true);
+      for (const code of [...(quest.prerequisiteCodes || []), ...(quest.unlocksQuestCodes || [])]) {
+        expect(questCodes.has(code), code).to.equal(true);
+      }
+    }
+  });
+
+  it('drops mission content bound to maps outside the captured world', () => {
+    const foreign = { code: 'foreign-action', sourceMapCode: 'some-other-map' };
+    const foreignQuest = { code: 'foreign-quest', sourceMapCode: 'some-other-map', steps: [] };
+    const out = planFallbackCapture({
+      world,
+      instanceCode: INSTANCE_CODE,
+      actions: [...DefaultCyberiaActions, foreign],
+      quests: [...DefaultCyberiaQuests, foreignQuest],
+    });
+    expect(out.skippedActionCodes).to.deep.equal(['foreign-action']);
+    expect(out.skippedQuestCodes).to.deep.equal(['foreign-quest']);
+    expect(out.actions.some((a) => a.code.endsWith('foreign-action'))).to.equal(false);
+  });
+
+  it('collects every item id the captured world places or names in a catalog', () => {
+    const itemIds = new Set(plan.itemIds);
+    for (const map of plan.maps) {
+      for (const entity of map.entities) {
+        for (const id of entity.objectLayerItemIds || []) expect(itemIds.has(id), id).to.equal(true);
+      }
+    }
+    // Assembler output: named only by a craft recipe, worn by no entity.
+    expect(itemIds.has('hatchet')).to.equal(true);
+    // Vendor stock and its price item.
+    expect(itemIds.has('tim-knife')).to.equal(true);
+    expect(itemIds.has('coin')).to.equal(true);
+    // Runtime placeholders never reach the atlas resolver.
+    expect(plan.itemIds.some((id) => id.startsWith('$'))).to.equal(false);
+  });
+
+  it('stamps the instance code onto a fully defaulted conf document', () => {
+    expect(plan.conf.instanceCode).to.equal(INSTANCE_CODE);
+    expect(plan.conf.tickRate).to.equal(world.config.tickRate);
+    // The captured conf references no entity-type default: the fallback world runs on the
+    // canonical set, and referencing nothing is what says so.
+    expect(plan.conf.entityDefaults).to.deep.equal([]);
+    expect(plan.conf.equipmentRules).to.be.an('object');
+  });
+
+  it('keeps the canonical codes verbatim under keepFallbackCodes', () => {
+    const kept = planFallbackCapture({ world, instanceCode: INSTANCE_CODE, keepFallbackCodes: true });
+    expect(kept.instance.cyberiaMapCodes).to.deep.equal(world.instance.cyberiaMapCodes);
+    expect(kept.actions.map((a) => a.code)).to.deep.equal(DefaultCyberiaActions.map((a) => a.code));
+    expect(kept.quests.map((q) => q.code)).to.deep.equal(DefaultCyberiaQuests.map((q) => q.code));
+    expect(kept.instance.code).to.equal(INSTANCE_CODE);
+  });
+
+  it('rejects an instance code or world it cannot capture', () => {
+    expect(() => planFallbackCapture({ world, instanceCode: '' })).to.throw(/instanceCode/);
+    expect(() => planFallbackCapture({ world: {}, instanceCode: INSTANCE_CODE })).to.throw(/invalid world/);
+  });
+});
+
+describe('captureFallbackWorld', () => {
+  const world = generateFallbackWorld();
+  const plan = planFallbackCapture({ world, instanceCode: INSTANCE_CODE });
+
+  const run = async (overrides = {}) => {
+    const models = buildModels({ objectLayerItemIds: plan.itemIds, ...overrides });
+    const result = await captureFallbackWorld({ models, world, instanceCode: INSTANCE_CODE });
+    return { models, result };
+  };
+
+  it('writes the instance, conf, maps and mission content', async () => {
+    const { models, result } = await run();
+
+    expect(models.CyberiaMap.docs.map((m) => m.code)).to.deep.equal(plan.maps.map((m) => m.code));
+    expect(models.CyberiaAction.docs.length).to.equal(plan.actions.length);
+    expect(models.CyberiaQuest.docs.length).to.equal(plan.quests.length);
+
+    const [instanceDoc] = models.CyberiaInstance.docs;
+    expect(instanceDoc.code).to.equal(INSTANCE_CODE);
+    expect(instanceDoc.status).to.equal('unlisted');
+    expect(instanceDoc.conf).to.equal(models.CyberiaInstanceConf.docs[0]._id);
+    expect(instanceDoc.cyberiaMapCodes).to.deep.equal(plan.instance.cyberiaMapCodes);
+    expect(models.CyberiaInstanceConf.docs[0].instanceCode).to.equal(INSTANCE_CODE);
+    expect(result.missingObjectLayerItemIds).to.deep.equal([]);
+  });
+
+  it('inserts the content defaults the in-memory world serves from code', async () => {
+    const { models, result } = await run();
+    expect(result.inserted.skills).to.equal(DefaultSkillConfig.length);
+    expect(result.inserted.entityTypeDefaults).to.equal(ENTITY_TYPE_DEFAULTS.length);
+    expect(result.inserted.dialogues).to.be.greaterThan(0);
+    expect(models.CyberiaSkill.docs.length).to.equal(DefaultSkillConfig.length);
+  });
+
+  it('never overwrites content defaults that already exist', async () => {
+    const edited = { triggerItemId: DefaultSkillConfig[0].triggerItemId, logicEventIds: [], skills: [] };
+    const { models, result } = await run({ seeded: { skills: [edited] } });
+    expect(result.inserted.skills).to.equal(DefaultSkillConfig.length - 1);
+    expect(models.CyberiaSkill.docs.find((d) => d.triggerItemId === edited.triggerItemId).skills).to.deep.equal([]);
+  });
+
+  it('is idempotent — a second capture converges on the same documents', async () => {
+    const models = buildModels({ objectLayerItemIds: plan.itemIds });
+    await captureFallbackWorld({ models, world, instanceCode: INSTANCE_CODE });
+    const first = JSON.stringify(models.CyberiaMap.docs);
+    const second = await captureFallbackWorld({ models, world, instanceCode: INSTANCE_CODE });
+
+    expect(models.CyberiaInstance.docs.length).to.equal(1);
+    expect(models.CyberiaMap.docs.length).to.equal(plan.maps.length);
+    expect(JSON.stringify(models.CyberiaMap.docs)).to.equal(first);
+    expect(second.inserted).to.deep.equal({ skills: 0, entityTypeDefaults: 0, dialogues: 0 });
+  });
+
+  it('prunes documents left in its own namespace by a wider previous capture', async () => {
+    const stale = { code: `${INSTANCE_CODE}-map-99` };
+    const foreign = { code: 'FOREST-A' };
+    const { models, result } = await run({ seeded: { maps: [stale, foreign] } });
+    expect(result.pruned.maps).to.equal(1);
+    expect(models.CyberiaMap.docs.some((m) => m.code === stale.code)).to.equal(false);
+    expect(models.CyberiaMap.docs.some((m) => m.code === foreign.code)).to.equal(true);
+  });
+
+  it('reports item ids that have no ObjectLayer instead of writing a broken backup', async () => {
+    const { result } = await run({ objectLayerItemIds: plan.itemIds.filter((id) => id !== 'coin') });
+    expect(result.missingObjectLayerItemIds).to.deep.equal(['coin']);
+  });
+});
+
+describe('captureFallbackWorld — audio configuration', () => {
+  const world = generateFallbackWorld();
+  const plan = planFallbackCapture({ world, instanceCode: INSTANCE_CODE });
+
+  const run = async (overrides = {}) => {
+    const models = buildModels({ objectLayerItemIds: plan.itemIds, ...overrides });
+    const result = await captureFallbackWorld({
+      models,
+      world,
+      instanceCode: INSTANCE_CODE,
+      keepFallbackCodes: !!overrides.keepFallbackCodes,
+    });
+    return { models, result };
+  };
+
+  it('writes one configuration per captured map, under the captured map code', async () => {
+    const { models, result } = await run();
+    // The client asks for audio by map code, so a namespaced capture needs its own documents.
+    expect(result.audio.audioConfs).to.equal(AUDIO_CONFIG.maps.length);
+    expect(models.CyberiaMapAudioConf.docs.map((d) => d.mapCode)).to.deep.equal(
+      AUDIO_CONFIG.maps.map((m) => captureMapCode(m.mapCode, INSTANCE_CODE)),
+    );
+    for (const doc of models.CyberiaMapAudioConf.docs) {
+      expect(doc.mapCode).to.not.include('fallback-map-');
+      expect(plan.instance.cyberiaMapCodes).to.include(doc.mapCode);
+      expect(doc.events.map((e) => e.logicEventId)).to.deep.equal(AUDIO_CONFIG.events.map((e) => e.logicEventId));
+      expect(doc.settings).to.deep.equal(AUDIO_CONFIG.settings);
+    }
+    expect(result.audio.missingAudioCodes).to.deep.equal([]);
+  });
+
+  it('binds a logic event to an audio code, carrying no asset of its own', async () => {
+    const { models } = await run();
+    const [doc] = models.CyberiaMapAudioConf.docs;
+    const projectile = doc.events.find((e) => e.logicEventId === 'projectile');
+    expect(projectile.audioCode).to.equal('shoot');
+    expect(projectile).to.not.have.property('audioId');
+    expect(doc.defaultMusic).to.equal(AUDIO_CONFIG.maps[0].defaultMusic);
+  });
+
+  it('leaves a code with no imported asset unbound, and reports it', async () => {
+    const { models, result } = await run({ audioCodes: importedAudioCodes().filter((code) => code !== 'shoot') });
+    expect(result.audio.missingAudioCodes).to.deep.equal(['shoot']);
+    for (const doc of models.CyberiaMapAudioConf.docs) {
+      expect(doc.events.some((e) => e.audioCode === 'shoot')).to.equal(false);
+    }
+  });
+
+  it('clears a default music the world has not imported', async () => {
+    const { models, result } = await run({ audioCodes: [] });
+    expect(result.audio.missingAudioCodes).to.deep.equal(importedAudioCodes().sort());
+    for (const doc of models.CyberiaMapAudioConf.docs) {
+      expect(doc.defaultMusic).to.equal('');
+      expect(doc.events).to.deep.equal([]);
+    }
+  });
+
+  it('writes the canonical map codes under keepFallbackCodes', async () => {
+    const { models } = await run({ keepFallbackCodes: true });
+    expect(models.CyberiaMapAudioConf.docs.map((d) => d.mapCode)).to.deep.equal(
+      AUDIO_CONFIG.maps.map((m) => m.mapCode),
+    );
+  });
+
+  it('is idempotent — a second capture converges on the same configuration', async () => {
+    const models = buildModels({ objectLayerItemIds: plan.itemIds });
+    await captureFallbackWorld({ models, world, instanceCode: INSTANCE_CODE });
+    const first = JSON.stringify(models.CyberiaMapAudioConf.docs);
+    await captureFallbackWorld({ models, world, instanceCode: INSTANCE_CODE });
+    expect(models.CyberiaMapAudioConf.docs.length).to.equal(AUDIO_CONFIG.maps.length);
+    expect(JSON.stringify(models.CyberiaMapAudioConf.docs)).to.equal(first);
+  });
+});

package/test/integration/app/cyberia/object-layer-item-id.test.js

@@ -0,0 +1,327 @@
+'use strict';
+
+import { expect } from 'chai';
+import { Types } from 'mongoose';
+import {
+  ObjectLayerSchema,
+  computeObjectLayerSha256,
+  mergeObjectLayerData,
+} from '../../../../src/api/object-layer/object-layer.model.js';
+
+const storedData = () => ({
+  stats: { effect: 5, resistance: 4, agility: 6, range: 2, intelligence: 0, utility: 1 },
+  item: { id: 'hatchet', type: 'weapon', description: 'a hatchet', activable: true },
+  ledger: { type: 'ERC1155', address: '0xabc', tokenId: '42' },
+  render: { cid: 'bafk-atlas', metadataCid: 'bafk-atlas-metadata' },
+});
+
+describe('object layer data merge', () => {
+  it('keeps the stored value when the writer sends null, undefined or empty string', () => {
+    const merged = mergeObjectLayerData(storedData(), {
+      render: { cid: null, metadataCid: '' },
+      ledger: { address: undefined },
+    });
+
+    expect(merged.render.cid).to.equal('bafk-atlas');
+    expect(merged.render.metadataCid).to.equal('bafk-atlas-metadata');
+    expect(merged.ledger.address).to.equal('0xabc');
+  });
+
+  it('prioritizes the last attribute that carries a value', () => {
+    const merged = mergeObjectLayerData(storedData(), {
+      item: { description: 'sharpened hatchet' },
+      render: { cid: 'bafk-new-atlas' },
+    });
+
+    expect(merged.item.description).to.equal('sharpened hatchet');
+    expect(merged.render.cid).to.equal('bafk-new-atlas');
+    expect(merged.render.metadataCid).to.equal('bafk-atlas-metadata');
+  });
+
+  it('treats false and 0 as real values, not as absent', () => {
+    const merged = mergeObjectLayerData(storedData(), {
+      item: { activable: false },
+      stats: { effect: 0 },
+    });
+
+    expect(merged.item.activable).to.equal(false);
+    expect(merged.stats.effect).to.equal(0);
+  });
+
+  it('preserves stored attributes the writer does not mention', () => {
+    const merged = mergeObjectLayerData(storedData(), { stats: { agility: 9 } });
+
+    expect(merged.stats).to.deep.equal({
+      effect: 5,
+      resistance: 4,
+      agility: 9,
+      range: 2,
+      intelligence: 0,
+      utility: 1,
+    });
+    expect(merged.ledger).to.deep.equal({ type: 'ERC1155', address: '0xabc', tokenId: '42' });
+  });
+
+  it('replaces ObjectIds and Dates atomically instead of merging their internals', () => {
+    const storedId = new Types.ObjectId();
+    const incomingId = new Types.ObjectId();
+
+    expect(
+      mergeObjectLayerData({ objectLayerRenderFramesId: storedId }, { objectLayerRenderFramesId: incomingId })
+        .objectLayerRenderFramesId,
+    ).to.equal(incomingId);
+    expect(
+      mergeObjectLayerData({ objectLayerRenderFramesId: storedId }, { objectLayerRenderFramesId: null })
+        .objectLayerRenderFramesId,
+    ).to.equal(storedId);
+    expect(mergeObjectLayerData({ at: new Date(0) }, { at: new Date(1) }).at.getTime()).to.equal(1);
+  });
+
+  it('seeds insert-only defaults under the payload, the way generate-saga does', () => {
+    const seeded = mergeObjectLayerData(
+      { cid: null, data: { ledger: { type: 'OFF_CHAIN', tokenId: '' }, render: {} } },
+      { data: { stats: { effect: 1 }, item: { id: 'amethyst-shard' } } },
+    );
+
+    expect(seeded.data.ledger).to.deep.equal({ type: 'OFF_CHAIN', tokenId: '' });
+    expect(seeded.data.item.id).to.equal('amethyst-shard');
+    expect(seeded.data.stats.effect).to.equal(1);
+  });
+
+  it('takes the incoming shape when nothing is stored yet', () => {
+    expect(mergeObjectLayerData(undefined, { render: { cid: null } })).to.deep.equal({ render: { cid: null } });
+  });
+});
+
+describe('object layer sha256', () => {
+  it('is deterministic regardless of key order', () => {
+    const a = { item: { id: 'hatchet' }, stats: { effect: 1 } };
+    const b = { stats: { effect: 1 }, item: { id: 'hatchet' } };
+
+    expect(computeObjectLayerSha256(a)).to.equal(computeObjectLayerSha256(b));
+    expect(computeObjectLayerSha256(a)).to.match(/^[a-f0-9]{64}$/);
+  });
+
+  it('is the single implementation shared with ObjectLayerEngine', async ({ skip }) => {
+    // object-layer.js pulls in pngjs/sharp/jimp, which external engine projects
+    // may not have installed; dynamic import keeps a missing optional
+    // dependency from aborting the runner's collection phase for the whole file.
+    let ObjectLayerEngine;
+    try {
+      ({ ObjectLayerEngine } = await import('../../../../src/projects/cyberia/object-layer.js'));
+    } catch (err) {
+      if (err.code === 'ERR_MODULE_NOT_FOUND') return skip();
+      throw err;
+    }
+
+    const data = storedData();
+    expect(ObjectLayerEngine.computeSha256(data)).to.equal(computeObjectLayerSha256(data));
+  });
+});
+
+describe('ObjectLayer schema item id contract', () => {
+  it('declares data.item.id as a unique index under a stable name', () => {
+    const itemIdIndex = ObjectLayerSchema.indexes().find(([fields]) => fields['data.item.id'] === 1);
+
+    expect(itemIdIndex, 'data.item.id index is declared').to.not.equal(undefined);
+    expect(itemIdIndex[1].name).to.equal('data.item.id_1');
+    expect(itemIdIndex[1].unique).to.equal(true);
+  });
+
+  it('exposes the statics that enforce one document per item id', () => {
+    for (const name of ['upsertByItemId', 'dedupeByItemId', 'ensureUniqueItemIdIndex']) {
+      expect(ObjectLayerSchema.statics[name], name).to.be.a('function');
+    }
+  });
+});
+
+// Stub model standing in for a bound Mongoose model, so the upsert contract is
+// exercised without a live MongoDB.
+const stubModel = (docs = []) => {
+  const state = { docs: [...docs], deletedIds: [], deletedFramesIds: [], created: null, updated: null };
+  const model = {
+    db: {
+      models: {
+        ObjectLayerRenderFrames: {
+          deleteMany: async ({ _id }) => state.deletedFramesIds.push(..._id.$in),
+        },
+      },
+    },
+    find: (query) => ({
+      sort: async () => state.docs.filter((doc) => doc.data.item.id === query['data.item.id']),
+    }),
+    deleteMany: async ({ _id }) => {
+      state.deletedIds.push(..._id.$in);
+      state.docs = state.docs.filter((doc) => !_id.$in.includes(doc._id));
+    },
+    create: async (payload) => {
+      state.created = payload;
+      return payload;
+    },
+    findByIdAndUpdate: async (_id, { $set }) => {
+      state.updated = { _id, $set };
+      return $set;
+    },
+  };
+  return { model, state };
+};
+
+const stubDoc = (doc) => ({ ...doc, toObject: () => JSON.parse(JSON.stringify(doc)) });
+
+const upsertByItemId = (model, ...args) => ObjectLayerSchema.statics.upsertByItemId.call(model, ...args);
+
+describe('ObjectLayer.upsertByItemId', () => {
+  it('rejects a payload without data.item.id', async () => {
+    const { model, state } = stubModel();
+
+    let error = null;
+    try {
+      await upsertByItemId(model, { data: { item: {} } });
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).to.not.equal(null);
+    expect(error.message).to.match(/requires data\.item\.id/);
+    expect(state.created).to.equal(null);
+  });
+
+  it('creates a new item with the sha256 computed over its data', async () => {
+    const { model, state } = stubModel();
+    const payload = { data: { item: { id: 'hatchet' }, stats: { effect: 1 } } };
+
+    await upsertByItemId(model, payload);
+
+    expect(state.created.sha256).to.equal(computeObjectLayerSha256(payload.data));
+  });
+
+  it('never lets a degraded import erase values already stored', async () => {
+    const { model, state } = stubModel([
+      stubDoc({
+        _id: 'a',
+        data: {
+          item: { id: 'hatchet', type: 'weapon', description: 'stored description', activable: true },
+          stats: { effect: 5 },
+          ledger: { type: 'ERC1155', address: '0xabc', tokenId: '42' },
+          render: { cid: 'bafk-atlas', metadataCid: 'bafk-atlas-metadata' },
+        },
+        cid: 'bafk-data',
+        objectLayerRenderFramesId: 'render-frames-old',
+      }),
+    ]);
+
+    // What the CLI stages when IPFS is unreachable: real ids, empty CIDs.
+    await upsertByItemId(model, {
+      data: {
+        item: { id: 'hatchet', type: 'weapon', description: '', activable: true },
+        stats: { effect: 7 },
+        ledger: { type: 'OFF_CHAIN' },
+        render: { cid: '', metadataCid: '' },
+      },
+      cid: '',
+      objectLayerRenderFramesId: 'render-frames-new',
+    });
+
+    const { _id, $set } = state.updated;
+    expect(_id).to.equal('a');
+    expect($set.data.render).to.deep.equal({ cid: 'bafk-atlas', metadataCid: 'bafk-atlas-metadata' });
+    expect($set.data.ledger.address).to.equal('0xabc');
+    expect($set.data.ledger.tokenId).to.equal('42');
+    expect($set.data.item.description).to.equal('stored description');
+    expect($set.cid).to.equal('bafk-data');
+    // …while everything the writer actually supplied still wins.
+    expect($set.data.ledger.type).to.equal('OFF_CHAIN');
+    expect($set.data.stats.effect).to.equal(7);
+    expect($set.objectLayerRenderFramesId).to.equal('render-frames-new');
+    expect($set.sha256).to.equal(computeObjectLayerSha256($set.data));
+  });
+
+  it('collapses pre-existing duplicates onto the oldest document', async () => {
+    const { model, state } = stubModel([
+      stubDoc({ _id: 'a', data: { item: { id: 'hatchet' } }, objectLayerRenderFramesId: 'rf-a' }),
+      stubDoc({ _id: 'b', data: { item: { id: 'hatchet' } }, objectLayerRenderFramesId: 'rf-b' }),
+      stubDoc({ _id: 'c', data: { item: { id: 'hatchet' } }, objectLayerRenderFramesId: 'rf-c' }),
+    ]);
+
+    await upsertByItemId(model, { data: { item: { id: 'hatchet' }, stats: { effect: 9 } } });
+
+    expect(state.deletedIds).to.deep.equal(['b', 'c']);
+    expect(state.deletedFramesIds).to.deep.equal(['rf-b', 'rf-c']);
+    expect(state.updated._id).to.equal('a');
+    expect(state.created).to.equal(null);
+  });
+
+  it('merges a backup restore onto the existing document instead of forking the item id', async () => {
+    // What `instance <code> --import` reads back from a backup: a full document
+    // carrying its own _id and sha256, for an item this database already holds
+    // under a different _id.
+    const { model, state } = stubModel([
+      stubDoc({
+        _id: 'live-id',
+        data: {
+          item: { id: 'biometric-masking-array', type: 'weapon', description: 'live description' },
+          stats: { effect: 3 },
+          ledger: { type: 'ERC1155', address: '0xabc', tokenId: '42' },
+          render: { cid: 'live-atlas', metadataCid: 'live-atlas-metadata' },
+        },
+        cid: 'live-data',
+      }),
+    ]);
+
+    await upsertByItemId(model, {
+      _id: 'backup-id',
+      sha256: 'stale-hash-from-the-backup',
+      data: {
+        item: { id: 'biometric-masking-array', type: 'weapon', description: '' },
+        stats: { effect: 8 },
+        ledger: { type: 'OFF_CHAIN' },
+        render: { cid: '', metadataCid: '' },
+      },
+      cid: '',
+      objectLayerRenderFramesId: 'restored-render-frames',
+    });
+
+    expect(state.created, 'no second document for the same item id').to.equal(null);
+    expect(state.updated._id).to.equal('live-id');
+    expect(state.updated.$set).to.not.have.property('_id');
+    expect(state.updated.$set.data.stats.effect).to.equal(8);
+    expect(state.updated.$set.objectLayerRenderFramesId).to.equal('restored-render-frames');
+    expect(state.updated.$set.data.item.description).to.equal('live description');
+    expect(state.updated.$set.data.render.cid).to.equal('live-atlas');
+    expect(state.updated.$set.cid).to.equal('live-data');
+    expect(state.updated.$set.sha256).to.equal(computeObjectLayerSha256(state.updated.$set.data));
+  });
+
+  it('preserves the backup _id when the item is genuinely new', async () => {
+    const { model, state } = stubModel();
+
+    await upsertByItemId(model, { _id: 'backup-id', data: { item: { id: 'fresh' }, stats: { effect: 1 } } });
+
+    expect(state.created._id).to.equal('backup-id');
+  });
+
+  it('applies setOnInsert only on create, so a saga rerun cannot downgrade an item', async () => {
+    const setOnInsert = { cid: null, data: { ledger: { type: 'OFF_CHAIN', tokenId: '' }, render: {} } };
+
+    const fresh = stubModel();
+    await upsertByItemId(fresh.model, { data: { item: { id: 'shard' }, stats: { effect: 1 } } }, { setOnInsert });
+    expect(fresh.state.created.data.ledger).to.deep.equal({ type: 'OFF_CHAIN', tokenId: '' });
+
+    const registered = stubModel([
+      stubDoc({
+        _id: 'a',
+        data: {
+          item: { id: 'shard' },
+          stats: { effect: 1 },
+          ledger: { type: 'ERC1155', address: '0xdead', tokenId: '7' },
+          render: { cid: 'bafk-atlas', metadataCid: 'bafk-atlas-metadata' },
+        },
+      }),
+    ]);
+    await upsertByItemId(registered.model, { data: { item: { id: 'shard' }, stats: { effect: 4 } } }, { setOnInsert });
+
+    expect(registered.state.updated.$set.data.ledger.type).to.equal('ERC1155');
+    expect(registered.state.updated.$set.data.render.cid).to.equal('bafk-atlas');
+    expect(registered.state.updated.$set.data.stats.effect).to.equal(4);
+  });
+});