Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

147 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach, afterAll } from "vitest";
import { mkdtempSync, rmSync, mkdirSync } from "fs";
import { writeFile, mkdir } from "fs/promises";
import { tmpdir } from "os";
import { join } from "path";
import { mockNoPeerSync, mockNoPeers } from "../lib/mockPathsDataRoot.js";
import { BIBLE_LIMITS } from "../lib/bibleLimits.js";

// Real per-suite tmpdir backing the universes/ layout. Each test wipes the
// tree in beforeEach. The fileUtils mock below overrides PATHS.data so the
// universeBuilder + collectionStore land here instead of the real ./data.
const TEST_DATA_ROOT = mkdtempSync(join(tmpdir(), "universe-builder-test-"));
const writeCounter = vi.hoisted(() => ({ baseHash: 0 }));
const baseHashEvictionSequence = vi.hoisted(() => ({ enabled: false, tail: Promise.resolve() }));

// Per-test reference-sheet "what exists on disk" — keys are filenames the
// referenceSheetImageRef preservation guard / pruner asks about. Default
// behavior is "non-empty filename resolves" so existing tests using fake
// names like 'sheet-B.png' still pass; the stale-prune test overrides
// resolveImageRef to return null for the stale filename.
const refSheetFilesByName = new Map();

vi.mock("../lib/fileUtils.js", async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    // Override PATHS.data to point at the test tmpdir; everything else
    // (atomicWrite, readJSONFile, ensureDir, etc.) uses the real impl so
    // collectionStore's readdir/stat/rm operate against a real fs tree.
    PATHS: { ...actual.PATHS, data: TEST_DATA_ROOT },
    atomicWrite: async (path, data) => {
      if (typeof path === 'string' && path.endsWith('sync_base_hashes.json')) writeCounter.baseHash += 1;
      return actual.atomicWrite(path, data);
    },
    // mustExist: true → return a non-null path when the filename either
    // appears in refSheetFilesByName or has no explicit "missing" entry.
    // Tests opt into "this file is gone" by calling
    // refSheetFilesByName.set('foo.png', null).
    resolveImageRef: vi.fn((ref) => {
      if (typeof ref !== 'string' || !ref) return null;
      if (refSheetFilesByName.has(ref)) return refSheetFilesByName.get(ref);
      return `/mock/refs/${ref}`;
    }),
  };
});

vi.mock("../lib/conflictJournal.js", async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    deleteSyncBaseHash: async (...args) => {
      if (!baseHashEvictionSequence.enabled) return actual.deleteSyncBaseHash(...args);
      const previous = baseHashEvictionSequence.tail;
      let release;
      baseHashEvictionSequence.tail = new Promise((resolve) => { release = resolve; });
      await previous;
      try {
        return await actual.deleteSyncBaseHash(...args);
      } finally {
        release();
      }
    },
  };
});

// Stub instances.js so createUniverse's fire-and-forget autoSubscribeRecordToAllPeers
// doesn't fan out to real peers. getPeers reads the live peer registry through a
// dataPath closure that resolves to the REAL PATHS once the post-return microtask
// runs outside this file's fileUtils mock window — so without this stub, creating a
// non-ephemeral fixture (e.g. "Moebius SciFi") initial-pushes it across the
// federation and the receiving instance persists it into the real data/universes/.
// Mirrors the same guard in importer.test.js and writersRoom/promoteToPipeline.test.js.
vi.mock("./instances.js", () => mockNoPeers());
vi.mock('./sharing/peerSync.js', () => mockNoPeerSync());

// Pre-seed state into the new per-record layout. Mirrors what migration 034
// produces — each universe lands in `universes/<id>/index.json` and the
// cross-record `runs[]` lives in `universes/index.json` under `config.runs`.
async function seedState({ universes = [], runs = [] } = {}) {
  const universesDir = join(TEST_DATA_ROOT, "universes");
  await mkdir(universesDir, { recursive: true });
  for (const u of universes) {
    const recDir = join(universesDir, u.id);
    await mkdir(recDir, { recursive: true });
    await writeFile(join(recDir, "index.json"), JSON.stringify(u, null, 2));
  }
  await writeFile(join(universesDir, "index.json"), JSON.stringify({
    schemaVersion: 5,
    type: "universes",
    updatedAt: new Date().toISOString(),
    config: { runs },
  }, null, 2));
}

afterAll(() => {
  rmSync(TEST_DATA_ROOT, { recursive: true, force: true });
});

let uuidCounter = 0;
// Pad to satisfy UNIVERSE_ID_RE / collectionStore's idPattern (8-80 chars).
// Tests still get a predictable, monotonically increasing id sequence.
const mockUuid = (n) => `uuid-${String(n).padStart(8, '0')}`;
vi.mock("crypto", async () => {
  const actual = await vi.importActual("crypto");
  return { ...actual, randomUUID: () => mockUuid(++uuidCounter) };
});

const svc = await import("./universeBuilder.js");
const cj = await import("../lib/conflictJournal.js");
const { recordEvents, registerSubscriptionAdapter, __resetSubscriptionAdapter } = await import("./sharing/recordEvents.js");

// Default universe with non-empty influences. Override `influences` for tests
// that need isolation from the seed tokens.
//
// The seed uses `outfits` (a custom category) rather than the legacy default
// `characters` bucket — the latter was retired in schema v4 and any variations
// under it get folded into universe.characters[] (canon) on sanitize. Using a
// custom name keeps the 2-bucket / 3-variation scenario these tests rely on.
const seedWorld = async (overrides = {}) =>
  svc.createUniverse({
    name: "Moebius SciFi",
    starterPrompt: "moebius and scavengers reign meets prophet",
    influences: {
      embrace: ["moebius linework", "scavengers reign palette"],
      avoid: ["blurry", "lowres"],
    },
    categories: {
      landscapes: {
        variations: [
          { label: "Crystal Canyon", prompt: "crystalline canyon, alien sun" },
          { label: "Sand Sea", prompt: "endless sand sea, dunes" },
        ],
      },
      outfits: {
        variations: [
          {
            label: "Scavenger",
            prompt: "lone scavenger figure, weathered cloak",
          },
        ],
      },
    },
    ...overrides,
  });

describe("universeBuilder service", () => {
  beforeEach(() => {
    // Wipe the test tmpdir between tests so each starts with an empty
    // universes/ tree.
    rmSync(TEST_DATA_ROOT, { recursive: true, force: true });
    mkdirSync(TEST_DATA_ROOT, { recursive: true });
    cj.__resetBaseHashCacheForTests();
    writeCounter.baseHash = 0;
    baseHashEvictionSequence.enabled = false;
    baseHashEvictionSequence.tail = Promise.resolve();
    uuidCounter = 0;
    refSheetFilesByName.clear();
  });

  // A test that registers a subscription-adapter double must not leak it into
  // later tests even when its assertions fail mid-body.
  afterEach(() => {
    __resetSubscriptionAdapter();
  });

  it("listUniverses returns [] for fresh state", async () => {
    expect(await svc.listUniverses()).toEqual([]);
  });


  it("lists compact names and index summaries without losing legacy canon counts", async () => {
    await seedState({ universes: [
      { id: 'u-live', name: 'Live', schemaVersion: 4, createdAt: '2026-01-02T00:00:00.000Z',
        logline: 'A city', starterPrompt: 'Treatment '.repeat(1000), styleImageRefs: ['old.png', 'latest.png'],
        characters: [{ id: 'c1', name: 'Ada' }], places: [{ id: 'p1', name: 'Port' }] },
      { id: 'u-legacy', name: 'Legacy', schemaVersion: 3, createdAt: '2026-01-01T00:00:00.000Z',
        categories: { characters: { variations: [{ id: 'v1', label: 'Scout', prompt: 'A scout' }] } } },
      { id: 'u-deleted', name: 'Deleted', deleted: true },
    ] });
    const full = await svc.listUniverses();
    expect(await svc.listUniverseNames()).toEqual(full.map(({ id, name }) => ({ id, name })));
    const summaries = await svc.listUniverseSummaries();
    expect(summaries).toEqual(full.map((u) => ({
      id: u.id, name: u.name, logline: u.logline, starterPrompt: u.starterPrompt.slice(0, svc.LOGLINE_MAX).trim(),
      origin: u.origin, createdAt: u.createdAt, updatedAt: u.updatedAt,
      factual: u.factual === true,
      canonCount: u.characters.length + u.places.length + u.objects.length,
      styleImageRef: u.styleImageRefs.at(-1) || null,
    })));
    expect(summaries.find((u) => u.id === 'u-legacy').canonCount).toBe(1);
    expect(summaries[0].styleImageRef).toBe('latest.png');
    expect(summaries[0].starterPrompt).toHaveLength(svc.LOGLINE_MAX - 1);
    expect(full[0].starterPrompt.length).toBeGreaterThan(svc.LOGLINE_MAX);
  });

  describe("listUniverseStyles", () => {
    it("projects to style tokens only — no categories / canon / sheets", async () => {
      const w = await seedWorld();
      const styles = await svc.listUniverseStyles();
      expect(styles).toEqual([{
        id: w.id,
        name: "Moebius SciFi",
        influences: {
          embrace: ["moebius linework", "scavengers reign palette"],
          avoid: ["blurry", "lowres"],
        },
      }]);
    });

    it("drops universes with no style tokens — selecting one would be a no-op", async () => {
      await svc.createUniverse({ name: "Blank Slate" });
      expect(await svc.listUniverseStyles()).toEqual([]);
    });

    it("folds the legacy v2 prose stylePrompt/negativePrompt into the token lists", async () => {
      // A pre-v3 record (or one synced from an older peer) carries prose
      // instead of chips — sanitizeTemplate splits it on read, so the
      // projection must too or those universes look style-less.
      await seedState({
        universes: [{
          id: "legacy-1",
          name: "Legacy World",
          stylePrompt: "ink wash, muted palette",
          negativePrompt: "blurry",
        }],
      });
      expect(await svc.listUniverseStyles()).toEqual([{
        id: "legacy-1",
        name: "Legacy World",
        influences: { embrace: ["ink wash", "muted palette"], avoid: ["blurry"] },
      }]);
    });
  });

  it("createUniverse persists with sanitized categories + kind tags", async () => {
    const w = await seedWorld();
    expect(w.id).toBe(mockUuid(1));
    expect(w.name).toBe("Moebius SciFi");
    // All default categories materialized even when only one was provided,
    // each tagged with its canon trunk via the WORLD_CATEGORY_DEFAULT_KINDS map.
    for (const c of svc.WORLD_CATEGORIES) {
      expect(w.categories[c]).toBeDefined();
      expect(Array.isArray(w.categories[c].variations)).toBe(true);
      expect(svc.CATEGORY_KINDS).toContain(w.categories[c].kind);
    }
    expect(w.categories.landscapes.variations).toHaveLength(2);
    expect(w.categories.landscapes.kind).toBe("places");
    expect(w.categories.vehicles.kind).toBe("objects");
    expect(w.categories.environments.variations).toHaveLength(0);
    // Custom (un-defaulted) bucket falls to 'other'.
    expect(w.categories.outfits.kind).toBe("other");
    expect(w.categories.outfits.variations).toHaveLength(1);
  });

  it("createUniverse preserves custom universe-building categories", async () => {
    const w = await seedWorld({
      categories: {
        "Clothing Styles": {
          variations: [
            {
              label: "Rib-Cage Nomads",
              prompt: "reference sheet, layered sailcloth, bone toggles",
            },
          ],
        },
        factions: {
          variations: [
            {
              label: "Wake Jackals",
              prompt: "spare raider kit, patched pressure masks",
            },
          ],
        },
      },
    });
    expect(w.categories.clothing_styles.variations).toEqual([
      {
        id: expect.stringMatching(/^var-/),
        label: "Rib-Cage Nomads",
        prompt: "reference sheet, layered sailcloth, bone toggles",
        imageRefs: [],
        // Variations now lock-by-default — see sanitizeVariation in
        // services/universeBuilder.js for the contract.
        locked: true,
      },
    ]);
    expect(w.categories.factions.variations).toHaveLength(1);
    expect(w.categories.landscapes.variations).toHaveLength(0);
  });

  it("createUniverse persists composite sheet prompts separately from categories", async () => {
    const w = await seedWorld({
      compositeSheets: [
        {
          label: "Gas-Giant Drifters costume sheet",
          prompt:
            "Create a clean illustrated costume reference sheet with five figures, materials swatches, fasteners, accessories, and color palette strip.",
        },
      ],
    });
    expect(w.compositeSheets).toEqual([
      {
        id: expect.stringMatching(/^sheet-/),
        kind: "reference_sheet",
        label: "Gas-Giant Drifters costume sheet",
        prompt:
          "Create a clean illustrated costume reference sheet with five figures, materials swatches, fasteners, accessories, and color palette strip.",
        imageRefs: [],
        // Composite sheets lock-by-default — see sanitizeCompositeSheet.
        locked: true,
      },
    ]);
  });

  it("createUniverse persists universe pitch poster prompts separately from categories", async () => {
    const w = await seedWorld({
      compositeSheets: [
        {
          kind: "world_pitch_poster",
          label: "Universe summary concept pitch poster",
          prompt:
            "Create a cinematic universe summary concept pitch poster with hero panorama, inset environments, cultures, creatures, visual language, color palette, materials, light atmosphere, and theme icons.",
        },
      ],
    });
    expect(w.compositeSheets).toEqual([
      {
        id: expect.stringMatching(/^sheet-/),
        kind: "world_pitch_poster",
        label: "Universe summary concept pitch poster",
        prompt:
          "Create a cinematic universe summary concept pitch poster with hero panorama, inset environments, cultures, creatures, visual language, color palette, materials, light atmosphere, and theme icons.",
        imageRefs: [],
        // Composite sheets lock-by-default — see sanitizeCompositeSheet.
        locked: true,
      },
    ]);
  });

  it("createUniverse rejects empty name", async () => {
    await expect(svc.createUniverse({ name: "" })).rejects.toThrow(
      /name is required/,
    );
  });

  it("createUniverse persists narrative bible fields (logline / premise / styleNotes)", async () => {
    const w = await seedWorld({
      logline: "A foundry city goes silent, and the only survivor is a child.",
      premise:
        "Long-form premise paragraph about the setting, conflict, stakes, and tone.",
      styleNotes:
        "Moebius linework, oil-on-canvas grain, contemplative pacing, sparse dialogue.",
    });
    expect(w.logline).toBe(
      "A foundry city goes silent, and the only survivor is a child.",
    );
    expect(w.premise).toBe(
      "Long-form premise paragraph about the setting, conflict, stakes, and tone.",
    );
    expect(w.styleNotes).toBe(
      "Moebius linework, oil-on-canvas grain, contemplative pacing, sparse dialogue.",
    );
  });

  it("updateUniverse patches narrative bible fields independently of categories", async () => {
    const w = await seedWorld({ logline: "original logline" });
    const patched = await svc.updateUniverse(w.id, {
      logline: "new logline",
      premise: "new premise",
      styleNotes: "new style notes",
    });
    expect(patched.logline).toBe("new logline");
    expect(patched.premise).toBe("new premise");
    expect(patched.styleNotes).toBe("new style notes");
    // Untouched (existing) data preserved.
    expect(patched.categories.landscapes.variations).toHaveLength(2);
    expect(patched.influences.embrace).toEqual(w.influences.embrace);
    expect(patched.influences.avoid).toEqual(w.influences.avoid);
  });

  it("updateUniverse with { replaceCategories } swaps the whole categories map (drops live-only categories)", async () => {
    const w = await seedWorld(); // seeds `landscapes` (2 vars) + custom `outfits` (1 var)
    expect(w.categories.outfits).toBeTruthy();
    // Default PATCH unions per-key — the live-only `outfits` survives.
    const unioned = await svc.updateUniverse(w.id, {
      categories: { landscapes: { variations: [{ label: "New", prompt: "p" }] } },
    });
    expect(unioned.categories.outfits).toBeTruthy();
    // With replaceCategories the patch's map replaces wholesale — `outfits` is dropped.
    const replaced = await svc.updateUniverse(
      w.id,
      { categories: { landscapes: { variations: [{ label: "New2", prompt: "p2" }] } } },
      { replaceCategories: true },
    );
    expect(replaced.categories.outfits).toBeUndefined();
    expect(replaced.categories.landscapes.variations).toHaveLength(1);
  });

  it("bumps updatedAt on a canon entry whose content changed, leaves an untouched entry's timestamp", async () => {
    // Two canon characters; edit only the first's content. The edited entry's
    // updatedAt must advance (so the canon→catalog projection's LWW clock is
    // truthful and the edit reaches the catalog row); the untouched entry keeps
    // its timestamp (no spurious projection churn).
    const w = await svc.createUniverse({
      name: "CanonClock",
      characters: [
        { name: "Ada", physicalDescription: "tall" },
        { name: "Bee", physicalDescription: "short" },
      ],
    });
    const [ada0, bee0] = w.characters;
    expect(ada0?.updatedAt).toBeTruthy();

    // Patch only Ada's description via the mutator form (the `{ ...e, ...patch }`
    // shape that previously preserved the stale updatedAt).
    const patched = await svc.updateUniverse(w.id, (cur) => ({
      characters: cur.characters.map((c) =>
        c.id === ada0.id ? { ...c, physicalDescription: "towering" } : c,
      ),
    }));

    const ada1 = patched.characters.find((c) => c.id === ada0.id);
    const bee1 = patched.characters.find((c) => c.id === bee0.id);
    expect(ada1.physicalDescription).toBe("towering");
    // Edited entry's clock advanced…
    expect(new Date(ada1.updatedAt).getTime()).toBeGreaterThan(new Date(ada0.updatedAt).getTime());
    // …untouched entry's clock unchanged.
    expect(bee1.updatedAt).toBe(bee0.updatedAt);
  });

  it("persists styleImageRefs (base style-probe renders); dedupes on create + patches wholesale", async () => {
    const w = await svc.createUniverse({ name: "Probe", styleImageRefs: ["a.png", "a.png", "b.png"] });
    expect(w.styleImageRefs).toEqual(["a.png", "b.png"]); // dedupe via sanitizeEntryImageRefs
    const patched = await svc.updateUniverse(w.id, { styleImageRefs: ["a.png", "b.png", "c.png"] });
    expect(patched.styleImageRefs).toEqual(["a.png", "b.png", "c.png"]);
    const fresh = await svc.getUniverse(w.id);
    expect(fresh.styleImageRefs).toEqual(["a.png", "b.png", "c.png"]);
  });

  it("defaults styleImageRefs to [] when absent", async () => {
    const w = await svc.createUniverse({ name: "NoProbe" });
    expect(w.styleImageRefs).toEqual([]);
  });

  it("persists analyzed style references and patches the list wholesale", async () => {
    const reference = {
      id: "style-ref-example",
      title: "Dust-lit ink wash",
      prompt: "Granular ink wash, muted ochre, weathered silhouettes",
      imageRefs: ["reference.png"],
      createdAt: "2026-01-01T00:00:00.000Z",
    };
    const w = await svc.createUniverse({
      name: "Reference Bible",
      styleReferences: [reference, { ...reference, id: "style-ref-duplicate" }],
    });
    expect(w.styleReferences).toHaveLength(2);
    expect(w.styleReferences[0]).toEqual(reference);

    const patched = await svc.updateUniverse(w.id, { styleReferences: [reference] });
    expect(patched.styleReferences).toEqual([reference]);
    expect((await svc.getUniverse(w.id)).styleReferences).toEqual([reference]);
  });

  it("addStyleReference appends inside the queued mutator so concurrent adds compose (#3109)", async () => {
    const refFor = (n) => ({
      id: `style-ref-${n}`,
      title: `Ref ${n}`,
      prompt: `Prompt ${n}`,
      imageRefs: [`ref-${n}.png`],
      createdAt: "2026-01-01T00:00:00.000Z",
    });
    const w = await svc.createUniverse({ name: "Delta Adds" });

    // Fired without awaiting the first — the record write queue serializes
    // them and each reads the freshest persisted list, so neither is lost.
    // A wholesale-replace PATCH pair built from the same base would drop one.
    await Promise.all([
      svc.addStyleReference(w.id, refFor(1)),
      svc.addStyleReference(w.id, refFor(2)),
    ]);
    const fresh = await svc.getUniverse(w.id);
    expect(fresh.styleReferences.map((r) => r.id).sort()).toEqual([
      "style-ref-1",
      "style-ref-2",
    ]);
  });

  it("addStyleReference writes adopted style guidance in the SAME queued write", async () => {
    const w = await svc.createUniverse({ name: "Adopt", influences: { embrace: ["old"], avoid: [] } });
    const updated = await svc.addStyleReference(w.id, {
      id: "style-ref-adopt",
      title: "Ink wash",
      prompt: "Granular ink wash",
      imageRefs: ["adopt.png"],
    }, {
      adopt: { styleNotes: "Tactile and muted", influences: { embrace: ["ink wash"], avoid: ["gloss"] } },
    });
    expect(updated.styleReferences).toHaveLength(1);
    expect(updated.styleNotes).toBe("Tactile and muted");
    expect(updated.influences).toEqual({ embrace: ["ink wash"], avoid: ["gloss"] });
    // Persisted together — the pair can't half-land.
    const fresh = await svc.getUniverse(w.id);
    expect(fresh.styleNotes).toBe("Tactile and muted");
    expect(fresh.styleReferences).toHaveLength(1);
  });

  it("adoptStyleGuide writes the proposed guide with no reference attached (#4188 Phase 4)", async () => {
    const w = await svc.createUniverse({ name: "Adopt Guide", influences: { embrace: ["old"], avoid: [] } });
    const updated = await svc.adoptStyleGuide(w.id, {
      styleNotes: "Board-synthesized prose",
      influences: { embrace: ["ink wash"], avoid: ["gloss"] },
    });
    expect(updated.styleNotes).toBe("Board-synthesized prose");
    expect(updated.influences).toEqual({ embrace: ["ink wash"], avoid: ["gloss"] });
    const fresh = await svc.getUniverse(w.id);
    expect(fresh.styleNotes).toBe("Board-synthesized prose");
    expect(fresh.styleReferences ?? []).toHaveLength(0);
  });

  it("adoptStyleGuide re-checks locks against the freshest persisted record", async () => {
    const w = await svc.createUniverse({
      name: "Adopt Locked",
      styleNotes: "Locked prose",
      influences: { embrace: ["keep me"], avoid: ["old bad"] },
      locked: { styleNotes: true, influencesEmbrace: true },
    });
    const updated = await svc.adoptStyleGuide(w.id, {
      styleNotes: "Should not land",
      influences: { embrace: ["should not land"], avoid: ["new bad"] },
    });
    // Locked fields keep the persisted values; the unlocked avoid list adopts.
    expect(updated.styleNotes).toBe("Locked prose");
    expect(updated.influences.embrace).toEqual(["keep me"]);
    expect(updated.influences.avoid).toEqual(["new bad"]);
  });

  it("addStyleReference is idempotent on a re-sent id and rejects an invalid reference", async () => {
    const reference = {
      id: "style-ref-once",
      title: "Once",
      prompt: "Prompt",
      imageRefs: ["once.png"],
    };
    const w = await svc.createUniverse({ name: "Idempotent" });
    await svc.addStyleReference(w.id, reference);
    // A retried request / double-click is a no-op, not a duplicate.
    const again = await svc.addStyleReference(w.id, reference);
    expect(again.styleReferences).toHaveLength(1);
    await expect(svc.addStyleReference(w.id, { title: "No prompt", imageRefs: ["x.png"] }))
      .rejects.toThrow(/Invalid style reference/);
  });

  it("addStyleReference enforces the cap against the PERSISTED list", async () => {
    const w = await svc.createUniverse({
      name: "At Cap",
      styleReferences: Array.from({ length: svc.STYLE_REFERENCES_MAX }, (_, i) => ({
        id: `style-ref-${i}`,
        title: `Ref ${i}`,
        prompt: `Prompt ${i}`,
        imageRefs: [`ref-${i}.png`],
      })),
    });
    expect(w.styleReferences).toHaveLength(svc.STYLE_REFERENCES_MAX);
    await expect(svc.addStyleReference(w.id, {
      id: "style-ref-overflow",
      title: "Overflow",
      prompt: "Prompt",
      imageRefs: ["overflow.png"],
    })).rejects.toThrow(/up to 20 art references/);
  });

  it("style-reference deltas leave canon untouched (so the projection opt-out is sound)", async () => {
    // Guard for `touchesCanon: false`: these deltas skip the per-entry
    // canon→catalog projection the mutator path normally runs, which is only
    // sound because their patch carries no canon key. If either ever starts
    // writing one, this fails and the opt-out has to go.
    const w = await svc.createUniverse({
      name: "Canon Untouched",
      characters: [{ name: "Jean", physicalDescription: "tall" }],
    });
    const before = (await svc.getUniverse(w.id)).characters;
    expect(before).toHaveLength(1);

    const reference = { id: "style-ref-x", title: "X", prompt: "x", imageRefs: ["x.png"] };
    const added = await svc.addStyleReference(w.id, reference);
    expect(added.characters).toEqual(before);
    const removed = await svc.removeStyleReference(w.id, reference.id);
    expect(removed.characters).toEqual(before);
  });

  it("removeStyleReference drops one by id and no-ops on an id that is already gone", async () => {
    const refA = { id: "style-ref-a", title: "A", prompt: "a", imageRefs: ["a.png"] };
    const refB = { id: "style-ref-b", title: "B", prompt: "b", imageRefs: ["b.png"] };
    const w = await svc.createUniverse({ name: "Delta Removes", styleReferences: [refA, refB] });

    // Concurrent removals: each filters the freshest list, so both land — the
    // case a pair of wholesale-replace PATCHes needed client-side queuing for.
    await Promise.all([
      svc.removeStyleReference(w.id, refA.id),
      svc.removeStyleReference(w.id, refB.id),
    ]);
    expect((await svc.getUniverse(w.id)).styleReferences).toEqual([]);

    // Already gone (a duplicate delete, or one that raced the image-delete
    // purge) resolves with the unchanged record instead of throwing.
    const noop = await svc.removeStyleReference(w.id, refA.id);
    expect(noop.styleReferences).toEqual([]);
  });

  it("drops invalid style references and defaults the field to an empty list", async () => {
    const w = await svc.createUniverse({
      name: "Reference Validation",
      styleReferences: [
        { title: "Missing prompt", imageRefs: ["reference.png"] },
        { title: "Missing image", prompt: "Prompt", imageRefs: [] },
        { title: "Traversal", prompt: "Prompt", imageRefs: ["../secret.png"] },
      ],
    });
    expect(w.styleReferences).toEqual([]);
  });

  it("createUniverse trims bible fields to their max length", async () => {
    const w = await seedWorld({
      logline: "x".repeat(svc.LOGLINE_MAX + 50),
      premise: "y".repeat(svc.PREMISE_MAX + 50),
      styleNotes: "z".repeat(svc.STYLE_NOTES_MAX + 50),
    });
    expect(w.logline).toHaveLength(svc.LOGLINE_MAX);
    expect(w.premise).toHaveLength(svc.PREMISE_MAX);
    expect(w.styleNotes).toHaveLength(svc.STYLE_NOTES_MAX);
  });

  // Starter idea is intentionally uncapped at the legacy 4000-char limit —
  // the cap was raised to 200,000 (a sanity ceiling, not an artificial
  // brevity constraint). These tests pin the new boundary so a future
  // refactor can't silently regress to the old 4k limit.
  it("createUniverse preserves a starterPrompt well beyond the legacy 4000-char limit", async () => {
    const longPrompt = "a".repeat(50_000);
    const w = await seedWorld({ starterPrompt: longPrompt });
    expect(w.starterPrompt).toHaveLength(50_000);
    expect(w.starterPrompt).toBe(longPrompt);
  });

  it("createUniverse trims a starterPrompt exceeding STARTER_PROMPT_MAX (200k)", async () => {
    const w = await seedWorld({
      starterPrompt: "b".repeat(svc.STARTER_PROMPT_MAX + 5_000),
    });
    expect(w.starterPrompt).toHaveLength(svc.STARTER_PROMPT_MAX);
  });

  it("STARTER_PROMPT_MAX is at least the documented 200k ceiling", async () => {
    // Guard against accidental regression to the legacy 4k cap.
    expect(svc.STARTER_PROMPT_MAX).toBeGreaterThanOrEqual(200_000);
  });

  it("updateUniverse merges partial patches", async () => {
    const w = await seedWorld();
    const patched = await svc.updateUniverse(w.id, {
      name: "Renamed",
      // Legacy stale-client shape: prose stylePrompt gets split into chips and
      // appended to influences.embrace by the sanitizer's v2 → v3 migration.
      stylePrompt: "new style",
    });
    expect(patched.name).toBe("Renamed");
    // The legacy prose was absorbed as a single token at the tail of embrace.
    expect(patched.influences.embrace).toEqual([
      ...w.influences.embrace,
      "new style",
    ]);
    // The legacy field is no longer stored on the record.
    expect(patched.stylePrompt).toBeUndefined();
    // Untouched fields preserved.
    expect(patched.starterPrompt).toBe(w.starterPrompt);
    expect(patched.categories.landscapes.variations).toHaveLength(2);
  });

  it("updateUniverse throws NOT_FOUND for unknown id", async () => {
    await expect(
      svc.updateUniverse("no-such", { name: "X" }),
    ).rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
  });

  it("updateUniverse accepts a mutator(latest) callback that runs inside the queue", async () => {
    const w = await seedWorld({ logline: "before" });
    const mutator = vi.fn(async (latest) => {
      expect(latest.id).toBe(w.id);
      return { logline: `${latest.logline} → after` };
    });
    const patched = await svc.updateUniverse(w.id, mutator);
    expect(mutator).toHaveBeenCalledTimes(1);
    expect(patched.logline).toBe("before → after");
  });

  it("updateUniverse short-circuits with no write when the mutator returns null", async () => {
    const w = await seedWorld();
    const beforeUpdatedAt = w.updatedAt;
    const patched = await svc.updateUniverse(w.id, async () => null);
    // No write happened: updatedAt unchanged, no rename cascade fired.
    expect(patched.updatedAt).toBe(beforeUpdatedAt);
    expect(patched.id).toBe(w.id);
  });

  it("updateUniverse mutator that throws propagates without writing", async () => {
    const w = await seedWorld({ logline: "untouched" });
    await expect(
      svc.updateUniverse(w.id, async () => { throw new Error("mutator boom"); }),
    ).rejects.toThrow("mutator boom");
    const fresh = await svc.getUniverse(w.id);
    expect(fresh.logline).toBe("untouched");
  });

  it("updateUniverse mutator returning a non-object value throws ERR_VALIDATION", async () => {
    const w = await seedWorld();
    await expect(
      svc.updateUniverse(w.id, async () => "not-an-object"),
    ).rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    // Arrays are `typeof 'object'` but would silently no-op the categories
    // merge — reject them explicitly.
    await expect(
      svc.updateUniverse(w.id, async () => []),
    ).rejects.toMatchObject({ code: svc.ERR_VALIDATION });
  });

  it("updateUniverse mutator sees concurrent writes that landed before it ran (queued)", async () => {
    const w = await seedWorld({ logline: "v0" });
    // Two updates issued in parallel against the same record. The queue
    // serializes them: the mutator sees the result of the first write.
    const [first, second] = await Promise.all([
      svc.updateUniverse(w.id, { logline: "v1" }),
      svc.updateUniverse(w.id, async (latest) => ({
        logline: `${latest.logline}+v2`,
      })),
    ]);
    expect(first.logline).toBe("v1");
    expect(second.logline).toBe("v1+v2");
  });

  it("updateUniverse cascades a name change onto the linked media collection", async () => {
    const collections = await import("./mediaCollections.js");
    const w = await seedWorld();
    // Seed a linked collection. The render route uses
    // findOrCreateUniverseCollection (universeId-first); we use the
    // name-first helper here only because the resulting record is
    // shape-identical and avoids dragging in the production route's
    // dependencies for this rename-cascade-focused test.
    await collections.findOrCreateCollectionByName({
      name: collections.universeCollectionNameFor(w.name),
      universeId: w.id,
    });
    await svc.updateUniverse(w.id, { name: "Renamed Universe" });
    const linked = await collections.findCollectionByUniverseId(w.id);
    expect(linked?.name).toBe("Universe: Renamed Universe");
  });

  it("updateUniverse rename succeeds even when no linked collection exists", async () => {
    const w = await seedWorld();
    const patched = await svc.updateUniverse(w.id, { name: "Solo Rename" });
    expect(patched.name).toBe("Solo Rename");
  });

  it("updateUniverse preserves server-owned referenceSheetImageRef across character PATCHes", async () => {
    // Multi-tab race: tab B finished a newer sheet render (server pointer is
    // 'sheet-B.png'), tab A PATCH-saves with a character body it loaded
    // BEFORE the render landed (still carrying the previous 'sheet-A.png',
    // or null). Without server-side preservation the older PATCH would
    // clobber the newer server pointer and the UI would 404 on the stale
    // filename. The render-completion handler bypasses this preservation
    // path because it writes referenceSheetImageRef inside its own
    // updateUniverse mutator from the latest record state.
    const w = await seedWorld();
    // Simulate the render-completion stamp via an in-queue mutator (same
    // path the real onSheetComplete uses).
    await svc.updateUniverse(w.id, (latest) => {
      const next = [...(latest.characters || []), {
        id: "c-1", name: "Vale", referenceSheetImageRef: "sheet-B.png",
        referenceSheetRequests: { standard: "11111111-1111-4111-8111-111111111111" },
      }];
      return { characters: next };
    });
    // Client PATCH that round-trips a stale body — sheet pointer is the
    // OLD value (or null). Server should keep 'sheet-B.png' regardless.
    const afterClientPatch = await svc.updateUniverse(w.id, {
      characters: [{ id: "c-1", name: "Vale", referenceSheetImageRef: "sheet-A.png" }],
    });
    const char = afterClientPatch.characters.find((c) => c.id === "c-1");
    expect(char?.referenceSheetImageRef).toBe("sheet-B.png");

    // Same invariant when client PATCHes with the field omitted entirely.
    const afterOmitPatch = await svc.updateUniverse(w.id, {
      characters: [{ id: "c-1", name: "Vale" }],
    });
    const charOmit = afterOmitPatch.characters.find((c) => c.id === "c-1");
    expect(charOmit?.referenceSheetImageRef).toBe("sheet-B.png");
    expect(charOmit?.referenceSheetRequests).toEqual({ standard: "11111111-1111-4111-8111-111111111111" });

    // Mutator path (the render-completion handler) IS trusted to update
    // referenceSheetImageRef — it constructs the patch from the latest
    // record. Preservation must NOT run against mutator output, or the
    // newly-stamped filename gets clobbered back to the old value.
    const afterRenderStamp = await svc.updateUniverse(w.id, (latest) => {
      const next = (latest.characters || []).map((c) =>
        c.id === "c-1" ? { ...c, referenceSheetImageRef: "sheet-C.png" } : c,
      );
      return { characters: next };
    });
    const charAfterStamp = afterRenderStamp.characters.find((c) => c.id === "c-1");
    expect(charAfterStamp?.referenceSheetImageRef).toBe("sheet-C.png");
  });

  it("updateUniverse preserves canon entry imageRefs across a stale whole-array PATCH (#1395)", async () => {
    // The collection hook appends section-local / batch renders onto a canon
    // entry's imageRefs[] via appendEntryImageRef (mutator form). A literal
    // whole-array PATCH (inline canon edit / add / lock) that round-trips a
    // character list the client loaded BEFORE the render landed must not
    // clobber the freshly-appended filename.
    const w = await seedWorld({
      characters: [{ id: "c-ref", name: "Ref", physicalDescription: "a face" }],
    });
    // Durable append — the hook's path (mutator form, bypasses preservation).
    await svc.appendEntryImageRef(w.id, { kind: "canon", kindKey: "characters", id: "c-ref" }, "render-1.png");

    // Stale client PATCH: round-trips the character WITHOUT the new ref.
    const afterStale = await svc.updateUniverse(w.id, {
      characters: [{ id: "c-ref", name: "Ref (renamed)", physicalDescription: "a face", imageRefs: [] }],
    });
    const refChar = afterStale.characters.find((c) => c.id === "c-ref");
    expect(refChar?.imageRefs).toEqual(["render-1.png"]); // preserved
    expect(refChar?.name).toBe("Ref (renamed)");          // other edits still apply

    // Mutator path stays trusted — a subsequent append lands normally.
    await svc.appendEntryImageRef(w.id, { kind: "canon", kindKey: "characters", id: "c-ref" }, "render-2.png");
    const afterSecond = await svc.getUniverse(w.id);
    const refChar2 = afterSecond.characters.find((c) => c.id === "c-ref");
    expect(refChar2?.imageRefs).toEqual(["render-1.png", "render-2.png"]);
  });

  it("updateUniverse preservation skips when cur's referenceSheetImageRef no longer resolves on disk", async () => {
    // GET /:id runs pruneStaleReferenceSheets, returning null when the
    // underlying file is gone. Client PATCHes carry the pruned null. The
    // preservation guard MUST honor that null by skipping preservation —
    // otherwise the stale filename comes back from cur and the UI 404s
    // again. resolveImageRef returning null is the "file missing" signal.
    const w = await seedWorld();
    // Stamp a sheet (mutator path is trusted).
    await svc.updateUniverse(w.id, (latest) => {
      const next = [...(latest.characters || []), {
        id: "c-stale", name: "Stale", referenceSheetImageRef: "sheet-DEAD.png",
      }];
      return { characters: next };
    });
    // Mark that filename as missing for the resolveImageRef mock.
    refSheetFilesByName.set("sheet-DEAD.png", null);
    // Client PATCH that carries the pruned null (matching what GET would
    // surface after pruneStaleReferenceSheets ran). Preservation should
    // detect the stale cur value and skip, so the null wins.
    const after = await svc.updateUniverse(w.id, {
      characters: [{ id: "c-stale", name: "Stale", referenceSheetImageRef: null }],
    });
    const stale = after.characters.find((c) => c.id === "c-stale");
    expect(stale?.referenceSheetImageRef).toBeNull();
    // Clean up the per-test FS shim so later tests start clean.
    refSheetFilesByName.delete("sheet-DEAD.png");
  });

  it("updateUniverse preserves server-owned referenceSheets[<variant>] map across literal PATCHes", async () => {
    // Same multi-tab race, but for the map-stored variants (blueprint, etc.).
    // A render-completion mutator stamps `referenceSheets.blueprint`; a stale
    // client PATCH that round-trips a body with the field omitted (or with
    // an older snapshot) must NOT lose the freshly-stamped variant. Per-key
    // preservation means a separately-rendered legacy 'standard' sheet
    // survives even when only blueprint is in the map.
    const w = await seedWorld();
    await svc.updateUniverse(w.id, (latest) => ({
      characters: [...(latest.characters || []), {
        id: "c-map", name: "Vex",
        referenceSheetImageRef: "sheet-STD.png",
        referenceSheets: { blueprint: "sheet-BP.png" },
      }],
    }));
    // PATCH that omits referenceSheets entirely — guard must preserve both
    // the legacy 'standard' field AND the blueprint map slot.
    const afterOmit = await svc.updateUniverse(w.id, {
      characters: [{ id: "c-map", name: "Vex" }],
    });
    const c1 = afterOmit.characters.find((c) => c.id === "c-map");
    expect(c1?.referenceSheetImageRef).toBe("sheet-STD.png");
    expect(c1?.referenceSheets).toEqual({ blueprint: "sheet-BP.png" });

    // PATCH that carries an older map (a different variant set or stale
    // filename). Cur's still-resolvable entries override the patch's same
    // keys; the patch's other keys flow through.
    const afterStale = await svc.updateUniverse(w.id, {
      characters: [{ id: "c-map", name: "Vex", referenceSheets: { blueprint: "sheet-OLD.png", noir: "sheet-NOIR.png" } }],
    });
    const c2 = afterStale.characters.find((c) => c.id === "c-map");
    expect(c2?.referenceSheets.blueprint).toBe("sheet-BP.png"); // cur wins (resolves)
    expect(c2?.referenceSheets.noir).toBe("sheet-NOIR.png"); // patch-only key flows through
  });

  it("updateUniverse persists null for stale referenceSheetImageRef on the write path, not just GET", async () => {
    // Reviewer-found bug: the GET-route pruner nulled the response but the
    // on-disk record kept the stale filename, so a later PATCH that omitted
    // `characters` (e.g. rename) merged from cur and returned the stale value.
    // The write-time prune in updateUniverse fixes this — any PATCH catches
    // the on-disk record up.
    const w = await seedWorld();
    await svc.updateUniverse(w.id, (latest) => ({
      characters: [...(latest.characters || []), {
        id: "c-rename", name: "Anchor", referenceSheetImageRef: "sheet-RENAME.png",
      }],
    }));
    refSheetFilesByName.set("sheet-RENAME.png", null);
    // PATCH that does NOT include `characters` — only renames the universe.
    const renamed = await svc.updateUniverse(w.id, { name: "Renamed" });
    const char = renamed.characters.find((c) => c.id === "c-rename");
    expect(char?.referenceSheetImageRef).toBeNull();
    // And a follow-up GET sees the same null — disk is now consistent.
    const reread = await svc.getUniverse(w.id);
    const charReread = reread.characters.find((c) => c.id === "c-rename");
    expect(charReread?.referenceSheetImageRef).toBeNull();
    refSheetFilesByName.delete("sheet-RENAME.png");
  });

  it("deleteUniverse removes the universe and its runs", async () => {
    const w = await seedWorld();
    await svc.recordRun({
      id: "run-1",
      universeId: w.id,
      collectionId: "col-1",
      jobIds: ["j1"],
      promptCount: 3,
    });
    expect(await svc.listRuns(w.id)).toHaveLength(1);
    await svc.deleteUniverse(w.id);
    expect(await svc.listUniverses()).toEqual([]);
    expect(await svc.listRuns(w.id)).toEqual([]);
  });

  it("deleteUniverse is BLOCKED while live series reference it (hierarchy invariant)", async () => {
    const seriesSvc = await import("./pipeline/series.js");
    const w = await seedWorld();
    const ser = await seriesSvc.createSeries({ name: "Child Arc", universeId: w.id });

    // Block: the universe still has a live child series.
    await expect(svc.deleteUniverse(w.id)).rejects.toMatchObject({
      code: svc.ERR_HAS_LIVE_SERIES,
      blockingSeries: [{ id: ser.id, name: "Child Arc" }],
    });
    // Universe is untouched.
    expect(await svc.listUniverses()).toHaveLength(1);

    // Once the child is gone, the delete succeeds.
    await seriesSvc.deleteSeries(ser.id);
    await expect(svc.deleteUniverse(w.id)).resolves.toMatchObject({ id: w.id });
    expect(await svc.listUniverses()).toEqual([]);
  });

  it("deleteUniverse unlinks linked media collections (releases the rename-lock)", async () => {
    const collections = await import("./mediaCollections.js");
    const w = await seedWorld();
    // Seed a linked collection (see rename-cascade test above for why we
    // use the name-first helper here even though production routes through
    // findOrCreateUniverseCollection).
    const linked = await collections.findOrCreateCollectionByName({
      name: collections.universeCollectionNameFor(w.name),
      universeId: w.id,
    });
    expect(linked.universeId).toBe(w.id);
    await svc.deleteUniverse(w.id);
    // Collection survives — the user may still want the renders.
    const fresh = await collections.getCollection(linked.id);
    // …but the `universeId` is cleared so the rename-lock no longer applies.
    expect(fresh.universeId).toBeNull();
    await expect(
      collections.updateCollection(fresh.id, { name: "User-Renamed" }),
    ).resolves.toMatchObject({ name: "User-Renamed" });
  });

  describe("soft-delete (tombstones for peer sync)", () => {
    it("deleteUniverse soft-deletes (record stays on disk with deleted=true)", async () => {
      const w = await seedWorld();
      await svc.deleteUniverse(w.id);
      // listUniverses hides it.
      expect(await svc.listUniverses()).toEqual([]);
      // includeDeleted exposes the tombstone with deletedAt + bumped updatedAt.
      const all = await svc.listUniverses({ includeDeleted: true });
      expect(all).toHaveLength(1);
      expect(all[0]).toMatchObject({ id: w.id, deleted: true });
      expect(all[0].deletedAt).toBeTruthy();
      expect(all[0].updatedAt).toBe(all[0].deletedAt);
    });

    it("countUniverses excludes tombstones and agrees with listUniverses().length", async () => {
      // countUniverses is the cheap tally the character skill registry reads instead
      // of materializing every record + the run history (#2729). Pin it against
      // listUniverses so the two can never disagree — the specific bug a naive
      // listIds().length would introduce is counting tombstones, since listIds()
      // returns live + ephemeral + tombstones and leaves filtering to the service.
      expect(await svc.countUniverses()).toBe(0);

      const live = await seedWorld();
      const doomed = await seedWorld({ name: "Doomed World" });
      expect(await svc.countUniverses()).toBe(2);
      expect(await svc.countUniverses()).toBe((await svc.listUniverses()).length);

      await svc.deleteUniverse(doomed.id);
      // The tombstone is still ON DISK (soft delete) — listIds() would still see it.
      expect(await svc.listUniverses({ includeDeleted: true })).toHaveLength(2);
      // ...but it must NOT be counted.
      expect(await svc.countUniverses()).toBe(1);
      expect(await svc.countUniverses()).toBe((await svc.listUniverses()).length);
      expect((await svc.listUniverses()).map((u) => u.id)).toEqual([live.id]);

      // includeDeleted mirrors listUniverses's own option, tombstones and all.
      expect(await svc.countUniverses({ includeDeleted: true }))
        .toBe((await svc.listUniverses({ includeDeleted: true })).length);
    });

    it("listUniverseStyles excludes tombstones", async () => {
      const live = await seedWorld();
      const doomed = await seedWorld({ name: "Doomed World" });
      expect((await svc.listUniverseStyles()).map((u) => u.id).sort())
        .toEqual([live.id, doomed.id].sort());

      await svc.deleteUniverse(doomed.id);
      expect((await svc.listUniverseStyles()).map((u) => u.id)).toEqual([live.id]);
    });

    it("getUniverse returns 404 for tombstoned, includeDeleted exposes it", async () => {
      const w = await seedWorld();
      await svc.deleteUniverse(w.id);
      await expect(svc.getUniverse(w.id)).rejects.toMatchObject({ code: "NOT_FOUND" });
      const tombstone = await svc.getUniverse(w.id, { includeDeleted: true });
      expect(tombstone).toMatchObject({ id: w.id, deleted: true });
    });

    it("updateUniverse on a tombstoned record throws 404 (no zombie edits)", async () => {
      const w = await seedWorld();
      await svc.deleteUniverse(w.id);
      await expect(svc.updateUniverse(w.id, { name: "Zombie" })).rejects.toMatchObject({
        code: "NOT_FOUND",
      });
    });

    it("deleteUniverse on an already-tombstoned record throws 404", async () => {
      const w = await seedWorld();
      await svc.deleteUniverse(w.id);
      await expect(svc.deleteUniverse(w.id)).rejects.toMatchObject({ code: "NOT_FOUND" });
    });

    it("insertUniverseWithId overwrites a tombstoned record (re-import undeletes)", async () => {
      const id = "550e8400-e29b-41d4-a716-44665544abcd";
      await svc.insertUniverseWithId({ id, name: "First" });
      await svc.deleteUniverse(id);
      const restored = await svc.insertUniverseWithId({ id, name: "Restored" });
      expect(restored).toMatchObject({ id, name: "Restored", deleted: false });
      // listUniverses shows it (no longer hidden).
      expect((await svc.listUniverses()).map((u) => u.id)).toContain(id);
    });

    it("insertUniverseWithId resurrection fires emitRecordUpdated + autoSubscribeRecordToAllPeers", async () => {
      const id = "550e8400-e29b-41d4-a716-44665544abcf";
      await svc.insertUniverseWithId({ id, name: "ToResurrect" });
      await svc.deleteUniverse(id);

      const emitSpy = vi.spyOn(recordEvents, "emit");
      // The auto-subscribe flows through the recordEvents subscription
      // adapter (peerSync registers the real impl at boot) — register a
      // test double to observe the call.
      const subscribeSpy = vi.fn().mockResolvedValue([]);
      registerSubscriptionAdapter({ autoSubscribeRecordToAllPeers: subscribeSpy });

      await svc.insertUniverseWithId({ id, name: "Resurrected" });
      // Allow the fire-and-forget adapter call to settle.
      await new Promise((r) => setTimeout(r, 0));

      expect(emitSpy).toHaveBeenCalledWith("updated", { recordKind: "universe", recordId: id });
      expect(subscribeSpy).toHaveBeenCalledWith("universe", id);

      emitSpy.mockRestore();
    });

    it("insertUniverseWithId fresh insert does NOT fire emitRecordUpdated", async () => {
      const id = "550e8400-e29b-41d4-a716-44665544abd0";
      const emitSpy = vi.spyOn(recordEvents, "emit");

      await svc.insertUniverseWithId({ id, name: "Fresh" });

      expect(emitSpy).not.toHaveBeenCalledWith("updated", { recordKind: "universe", recordId: id });
      emitSpy.mockRestore();
    });

    it("insertUniverseWithId still rejects DUPLICATE on a LIVE record", async () => {
      const id = "550e8400-e29b-41d4-a716-44665544abce";
      await svc.insertUniverseWithId({ id, name: "First" });
      await expect(
        svc.insertUniverseWithId({ id, name: "Second" }),
      ).rejects.toMatchObject({ code: svc.ERR_DUPLICATE });
    });

    describe("mergeUniversesFromSync", () => {
      it("skips a peer record with an invalid id without aborting the batch", async () => {
        const good = await seedWorld();
        const editTs = new Date(Date.now() + 60_000).toISOString();
        // A malformed-id record (slash → outside the store allowlist) sits
        // BEFORE a valid edit in the same batch. The bad one must be skipped,
        // not throw and drop the valid edit after it.
        const r = await svc.mergeUniversesFromSync([
          { id: "bad/id", name: "Evil", updatedAt: editTs },
          { ...good, name: "Edited", updatedAt: editTs },
        ]);
        expect(r.applied).toBe(true);
        expect(r.count).toBe(1); // only the valid record applied
        expect((await svc.getUniverse(good.id)).name).toBe("Edited");
        await expect(svc.getUniverse("bad/id", { includeDeleted: true }))
          .rejects.toMatchObject({ code: "NOT_FOUND" });
      });

      it("applies an inbound soft-delete from a peer", async () => {
        const w = await seedWorld();
        const tombstoneTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync([{
          ...w,
          deleted: true,
          deletedAt: tombstoneTs,
          updatedAt: tombstoneTs,
        }]);
        expect(r).toEqual({ applied: true, count: 1 });
        await expect(svc.getUniverse(w.id)).rejects.toMatchObject({ code: "NOT_FOUND" });
        const tombstone = await svc.getUniverse(w.id, { includeDeleted: true });
        expect(tombstone.deleted).toBe(true);
      });

      it("LWW: an inbound edit with later updatedAt wins over a local tombstone", async () => {
        const w = await seedWorld();
        await svc.deleteUniverse(w.id);
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync([{
          ...w,
          name: "Edited After Delete",
          deleted: false,
          deletedAt: null,
          updatedAt: editTs,
        }]);
        expect(r.applied).toBe(true);
        // Edit wins — record is live again with the new name.
        const live = await svc.getUniverse(w.id);
        expect(live).toMatchObject({ name: "Edited After Delete", deleted: false });
      });

      it("LWW: an inbound tombstone with later updatedAt wins over a local edit", async () => {
        const w = await seedWorld();
        const tombstoneTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync([{
          ...w,
          deleted: true,
          deletedAt: tombstoneTs,
          updatedAt: tombstoneTs,
        }]);
        expect(r.applied).toBe(true);
        await expect(svc.getUniverse(w.id)).rejects.toMatchObject({ code: "NOT_FOUND" });
      });

      it("delete transition via sync drops orphan runs (mirrors local-delete contract)", async () => {
        const w = await seedWorld();
        await svc.recordRun({
          id: "run-sync-1",
          universeId: w.id,
          collectionId: "col-x",
          jobIds: ["j1"],
          promptCount: 1,
        });
        expect(await svc.listRuns(w.id)).toHaveLength(1);
        const tombstoneTs = new Date(Date.now() + 60_000).toISOString();
        await svc.mergeUniversesFromSync([{
          ...w,
          deleted: true,
          deletedAt: tombstoneTs,
          updatedAt: tombstoneTs,
        }]);
        expect(await svc.listRuns(w.id)).toEqual([]);
      });

      it("inbound tombstone for a NEVER-SEEN universe is accepted without firing the cascade (no orphan teardown for nothing)", async () => {
        // Regression: the no-local branch previously included tombstones in
        // `transitionedToDeleted`, firing `emitRecordDeleted` + the orphan
        // cascade for a record we never had. Now the no-local branch accepts
        // the record silently — the cascade only fires on real local
        // transitions (deleted=false → deleted=true).
        const ghostId = "550e8400-0000-0000-0000-000000000999";
        const ts = new Date().toISOString();
        const r = await svc.mergeUniversesFromSync([{
          id: ghostId,
          name: "Ghost",
          deleted: true,
          deletedAt: ts,
          updatedAt: ts,
        }]);
        expect(r).toEqual({ applied: true, count: 1 });
        // Tombstone is on disk via includeDeleted.
        const all = await svc.listUniverses({ includeDeleted: true });
        expect(all.find((u) => u.id === ghostId)).toMatchObject({ deleted: true });
      });

      it("delete transition via sync runs cascade — unlinks media collections", async () => {
        const collections = await import("./mediaCollections.js");
        const w = await seedWorld();
        const linked = await collections.findOrCreateCollectionByName({
          name: collections.universeCollectionNameFor(w.name),
          universeId: w.id,
        });
        expect(linked.universeId).toBe(w.id);
        const tombstoneTs = new Date(Date.now() + 60_000).toISOString();
        await svc.mergeUniversesFromSync([{
          ...w,
          deleted: true,
          deletedAt: tombstoneTs,
          updatedAt: tombstoneTs,
        }]);
        const fresh = await collections.getCollection(linked.id);
        expect(fresh.universeId).toBeNull();
      });

      it("local-ephemeral universes are IMMUNE to inbound merges (peer edits + tombstones both refused)", async () => {
        // The user marks a universe ephemeral to fork it private. A peer
        // that still has the pre-ephemeral version (or has a reverse
        // subscription) must not be able to overwrite local content or
        // trigger an orphan cascade by deleting their copy.
        const w = await seedWorld();
        await svc.updateUniverse(w.id, { ephemeral: true });
        const localBefore = await svc.getUniverse(w.id);
        // Inbound edit with NEWER updatedAt — would normally win via LWW.
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const editResult = await svc.mergeUniversesFromSync([{
          ...w,
          name: "Should Not Land",
          updatedAt: editTs,
        }]);
        expect(editResult.applied).toBe(false);
        const localAfterEdit = await svc.getUniverse(w.id);
        expect(localAfterEdit.name).toBe(localBefore.name);
        expect(localAfterEdit.ephemeral).toBe(true);
        // Inbound tombstone with NEWER updatedAt — would normally tombstone.
        const tombstoneTs = new Date(Date.now() + 120_000).toISOString();
        const deleteResult = await svc.mergeUniversesFromSync([{
          ...w,
          deleted: true,
          deletedAt: tombstoneTs,
          updatedAt: tombstoneTs,
        }]);
        expect(deleteResult.applied).toBe(false);
        const stillLive = await svc.getUniverse(w.id);
        expect(stillLive.deleted).toBeFalsy();
      });

      it("strips inbound `ephemeral` field — peers cannot plant a 'dark' record on the receiver", async () => {
        // The wire never carries `ephemeral`, but a buggy / older / non-
        // conformant peer (or the share-bucket importer's mutator-form
        // path) could ship a record with `ephemeral: true`. The receiver
        // must NOT honor that — it's a local-only marker by contract.
        const ghostId = "550e8400-0000-0000-0000-000000000aaa";
        const ts = new Date().toISOString();
        await svc.mergeUniversesFromSync([{
          id: ghostId,
          name: "Inbound Poison",
          ephemeral: true, // attempt to plant a dark record
          updatedAt: ts,
        }]);
        const inbound = await svc.getUniverse(ghostId);
        expect(inbound.name).toBe("Inbound Poison");
        // Receiver scrubs the field — record is normal-syncable.
        expect(inbound.ephemeral).toBeUndefined();
      });

      it("preserves local styleImageRefs across a remote-wins LWW edit (wire-local probe renders)", async () => {
        // styleImageRefs is stripped from the wire, so an inbound payload never
        // carries it. Without the receive-side restore, sanitizeTemplate would
        // default the missing field to [] and a remote-wins LWW write would
        // clobber this peer's locally-rendered probe images. The local value
        // is authoritative — a peer's edit to OTHER fields must not wipe it.
        const w = await seedWorld();
        await svc.updateUniverse(w.id, { styleImageRefs: ["probe-1.png", "probe-2.png"] });
        const localBefore = await svc.getUniverse(w.id);
        expect(localBefore.styleImageRefs).toEqual(["probe-1.png", "probe-2.png"]);
        // Inbound edit (newer updatedAt, no styleImageRefs — wire-stripped) wins LWW.
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync([{
          ...w,
          name: "Remote Edited Name",
          styleImageRefs: undefined, // mirror the wire form (field absent)
          updatedAt: editTs,
        }]);
        expect(r.applied).toBe(true);
        const after = await svc.getUniverse(w.id);
        // Remote name landed…
        expect(after.name).toBe("Remote Edited Name");
        // …but local probe renders survived.
        expect(after.styleImageRefs).toEqual(["probe-1.png", "probe-2.png"]);
      });

      it("preserves the local render pin across a remote-wins LWW edit (#3231 Phase 3)", async () => {
        // imageMode/imageModelId are wire-local like styleImageRefs — a peer's
        // edit to other fields must not clear this machine's pinned backend.
        const w = await seedWorld();
        await svc.updateUniverse(w.id, { imageMode: "agy", imageModelId: "gemini-3.6-flash-low" });
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync([{
          ...w,
          name: "Remote Edited Name",
          updatedAt: editTs,
        }]);
        expect(r.applied).toBe(true);
        const after = await svc.getUniverse(w.id);
        expect(after.name).toBe("Remote Edited Name");
        expect(after.imageMode).toBe("agy");
        expect(after.imageModelId).toBe("gemini-3.6-flash-low");
      });

      it("preserves the local moodBoardId when a pre-v9/no-meta sender's edit wins LWW (#4188)", async () => {
        // A behind sender passes the version gate (only AHEAD rejects), and
        // its moodBoardId-unaware sanitizer omitted the field — that omission
        // must not read as a clear.
        const w = await seedWorld();
        await svc.updateUniverse(w.id, { moodBoardId: "mb-local" });
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync([
          { ...w, name: "Remote Edited Name", updatedAt: editTs },
        ]); // no senderSchemaVersions — legacy/no-meta sender
        expect(r.applied).toBe(true);
        const after = await svc.getUniverse(w.id);
        expect(after.name).toBe("Remote Edited Name");
        expect(after.moodBoardId).toBe("mb-local");
      });

      it("honors a v9-aware sender's omitted moodBoardId as an explicit clear (#4188)", async () => {
        const w = await seedWorld();
        await svc.updateUniverse(w.id, { moodBoardId: "mb-local" });
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync(
          [{ ...w, name: "Remote Cleared", updatedAt: editTs }],
          { senderSchemaVersions: { universes: 9 } },
        );
        expect(r.applied).toBe(true);
        const after = await svc.getUniverse(w.id);
        expect("moodBoardId" in after).toBe(false);
      });

      it("applies a v9-aware sender's moodBoardId over the local link (#4188)", async () => {
        const w = await seedWorld();
        await svc.updateUniverse(w.id, { moodBoardId: "mb-local" });
        const editTs = new Date(Date.now() + 60_000).toISOString();
        const r = await svc.mergeUniversesFromSync(
          [{ ...w, moodBoardId: "mb-remote", updatedAt: editTs }],
          { senderSchemaVersions: { universes: 9 } },
        );
        expect(r.applied).toBe(true);
        const after = await svc.getUniverse(w.id);
        expect(after.moodBoardId).toBe("mb-remote");
      });

      it('preserves production canon when a pre-v10 sender wins an unrelated edit (#5378)', async () => {
        const w = await seedWorld();
        await svc.updateUniverse(w.id, {
          characters: [{
            id: 'chr-1', name: 'A', imageRefs: ['neutral.png', 'profile.png', 'body.png'],
            voiceCanon: { version: 1, description: 'warm low alto', approved: true },
            identityPack: { assets: [{ role: 'neutral', imageRef: 'neutral.png', approved: true }] },
          }],
        });
        const local = await svc.getUniverse(w.id);
        const r = await svc.mergeUniversesFromSync(
          [{ ...local, name: 'Old peer rename', characters: [{ id: 'chr-1', name: 'A', imageRefs: ['neutral.png', 'profile.png', 'body.png'] }], updatedAt: new Date(Date.now() + 60_000).toISOString() }],
          { senderSchemaVersions: { universes: 9 } },
        );
        expect(r.applied).toBe(true);
        const after = await svc.getUniverse(w.id);
        expect(after.characters[0].voiceCanon).toMatchObject({ description: 'warm low alto', approved: true });
        expect(after.characters[0].identityPack.assets).toEqual([{ role: 'neutral', imageRef: 'neutral.png', approved: true }]);
      });

      // Additive fields a behind sender's sanitizer strips (#8414). Each case
      // seeds the field locally, then merges a newer remote that lacks it —
      // from a sender one version behind the field (omission = "no slot",
      // must preserve) and from a sender AT the field's version (omission =
      // the author's clear, must apply).
      const styleReference = {
        id: 'style-ref-example', title: 'Dust-lit ink wash', prompt: 'Granular ink wash',
        imageRefs: ['reference.png'], createdAt: '2026-01-01T00:00:00.000Z',
      };
      const withoutField = (list, field) => list.map(({ [field]: _omit, ...rest }) => rest);
      const legacyFieldCases = [
        {
          field: 'factual', since: 12,
          patch: { factual: true },
          strip: ({ factual: _omit, ...rest }) => rest,
          read: (u) => u.factual,
          kept: true, cleared: undefined,
        },
        {
          field: 'styleReferences', since: 8,
          patch: { styleReferences: [styleReference] },
          strip: (u) => ({ ...u, styleReferences: [] }),
          read: (u) => u.styleReferences,
          kept: [styleReference], cleared: [],
        },
        {
          field: 'character relationshipLinks', since: 6,
          patch: {
            characters: [
              { id: 'chr-1', name: 'A', relationshipLinks: [{ id: 'rel-1', targetCharacterId: 'chr-2', type: 'custom', description: 'rivals' }] },
              { id: 'chr-2', name: 'B' },
            ],
          },
          strip: (u) => ({ ...u, characters: withoutField(u.characters, 'relationshipLinks') }),
          read: (u) => u.characters.find((c) => c.id === 'chr-1').relationshipLinks.map((l) => l.id),
          kept: ['rel-1'], cleared: [],
        },
        {
          field: 'object attachments', since: 7,
          patch: {
            characters: [{ id: 'chr-1', name: 'A' }],
            objects: [{ id: 'obj-1', name: 'Brass Lamp', attachments: [{ id: 'att-1', characterId: 'chr-1', role: 'custom', emotion: 'dread' }] }],
          },
          strip: (u) => ({ ...u, objects: withoutField(u.objects, 'attachments') }),
          read: (u) => u.objects.find((o) => o.id === 'obj-1').attachments.map((a) => a.id),
          kept: ['att-1'], cleared: [],
        },
      ];

      it.each(legacyFieldCases)('preserves $field from a behind sender but honors an at-version clear (#8414)', async ({ since, patch, strip, read, kept, cleared }) => {
        for (const [senderVersion, expected] of [[since - 1, kept], [since, cleared]]) {
          const w = await seedWorld();
          await svc.updateUniverse(w.id, patch);
          const local = await svc.getUniverse(w.id);
          expect(read(local)).toEqual(kept);
          const r = await svc.mergeUniversesFromSync(
            [{ ...strip(local), name: 'Peer rename', updatedAt: new Date(Date.now() + 60_000).toISOString() }],
            { senderSchemaVersions: { universes: senderVersion } },
          );
          expect(r.applied).toBe(true);
          const after = await svc.getUniverse(w.id);
          expect(after.name).toBe('Peer rename');
          expect(read(after)).toEqual(expected);
        }
      });
    });

    describe("pruneTombstonedUniverses", () => {
      it("removes tombstones older than the cutoff and leaves newer ones + live records", async () => {
        const live = await seedWorld();
        const oldTombstone = await seedWorld();
        const oldTombstone2 = await seedWorld();
        const newTombstone = await seedWorld();
        await svc.deleteUniverse(oldTombstone.id);
        await svc.deleteUniverse(oldTombstone2.id);
        await svc.deleteUniverse(newTombstone.id);
        // Backdate both old tombstones' deletedAt directly via merge.
        const oldDeletedAt = new Date(Date.now() - 100_000).toISOString();
        const mergeUpdatedAt = new Date(Date.now() + 10_000).toISOString();
        await svc.mergeUniversesFromSync([
          {
            ...(await svc.getUniverse(oldTombstone.id, { includeDeleted: true })),
            deletedAt: oldDeletedAt,
            updatedAt: mergeUpdatedAt,
          },
          {
            ...(await svc.getUniverse(oldTombstone2.id, { includeDeleted: true })),
            deletedAt: oldDeletedAt,
            updatedAt: mergeUpdatedAt,
          },
        ]);
        await cj.setSyncBaseHash('universe', oldTombstone.id, 'hash-old-a');
        await cj.setSyncBaseHash('universe', oldTombstone2.id, 'hash-old-b');
        await cj.flushBaseHashes();
        writeCounter.baseHash = 0;
        // Serialize the eviction calls without sleeping. Without the batch,
        // each call would finish its own side-store write before the next one.
        baseHashEvictionSequence.enabled = true;

        // Cutoff = now - 50s — old (100s ago) is past, new (just now) is not.
        const cutoff = Date.now() - 50_000;
        const result = await svc.pruneTombstonedUniverses(cutoff);
        expect(result.pruned).toBe(2);
        expect(writeCounter.baseHash).toBe(1);
        const remaining = await svc.listUniverses({ includeDeleted: true });
        const ids = remaining.map((u) => u.id);
        expect(ids).toContain(live.id);
        expect(ids).toContain(newTombstone.id);
        expect(ids).not.toContain(oldTombstone.id);
        expect(ids).not.toContain(oldTombstone2.id);
        cj.__resetBaseHashCacheForTests();
        expect(await cj.getSyncBaseHash('universe', oldTombstone.id)).toBeNull();
        expect(await cj.getSyncBaseHash('universe', oldTombstone2.id)).toBeNull();
      });

      it("keeps tombstones with unparseable deletedAt (conservative)", async () => {
        const w = await seedWorld();
        await svc.deleteUniverse(w.id);
        // Corrupt the deletedAt via merge — this can happen if a peer ships
        // a malformed record. We refuse to prune anything we can't time-stamp.
        await svc.mergeUniversesFromSync([{
          ...(await svc.getUniverse(w.id, { includeDeleted: true })),
          deletedAt: 'not-a-date',
          updatedAt: new Date(Date.now() + 10_000).toISOString(),
        }]);
        const result = await svc.pruneTombstonedUniverses(Date.now() + 60_000_000);
        expect(result.pruned).toBe(0);
        const remaining = await svc.listUniverses({ includeDeleted: true });
        expect(remaining.find((u) => u.id === w.id)).toBeTruthy();
      });

      it("returns { pruned: 0 } for a non-finite cutoff (defensive)", async () => {
        expect(await svc.pruneTombstonedUniverses(NaN)).toEqual({ pruned: 0 });
        expect(await svc.pruneTombstonedUniverses(Infinity)).toEqual({ pruned: 0 });
        expect(await svc.pruneTombstonedUniverses('not-a-number')).toEqual({ pruned: 0 });
      });

      it("rescues a record un-deleted between the id-only candidate scan and the queued delete (race safety, #6851)", async () => {
        // The candidate scan now comes from listTombstoneIdsBefore (a store
        // projection) instead of an out-of-queue listRaw()+filter, but the
        // race it must still lose to is the same one pruneTombstonedUniverses
        // has always guarded against: a concurrent sync un-deleting the record
        // between that scan and the per-id queued re-check.
        const w = await seedWorld();
        await svc.deleteUniverse(w.id);
        const oldDeletedAt = new Date(Date.now() - 100_000).toISOString();
        await svc.mergeUniversesFromSync([{
          ...(await svc.getUniverse(w.id, { includeDeleted: true })),
          deletedAt: oldDeletedAt,
          updatedAt: new Date(Date.now() + 10_000).toISOString(),
        }]);
        const cutoff = Date.now() - 50_000;

        // Hold the record's per-id write queue open BEFORE calling prune, so
        // prune's own queueRecordWrite(w.id, recheck) — issued only after its
        // async candidate scan resolves — is forced to queue BEHIND this held
        // task. Writes directly through the facade (not mergeUniversesFromSync,
        // which would itself re-enter queueRecordWrite for the same id and
        // deadlock against the very task it's called from).
        const s = svc.store();
        let releaseHold;
        const holdGate = new Promise((resolve) => { releaseHold = resolve; });
        const held = s.queueRecordWrite(w.id, async () => {
          await holdGate;
          const current = await s.loadOne(w.id);
          await s.writeRecord(w.id, {
            ...current,
            deleted: false,
            deletedAt: null,
            updatedAt: new Date(Date.now() + 20_000).toISOString(),
          });
        });

        const prunePromise = svc.pruneTombstonedUniverses(cutoff);
        releaseHold();
        await held;
        const result = await prunePromise;

        expect(result.pruned).toBe(0);
        const remaining = await svc.listUniverses({ includeDeleted: true });
        const rescued = remaining.find((u) => u.id === w.id);
        expect(rescued?.deleted).toBe(false);
      });
    });
  });

  describe("synthesizeCanonPrompt", () => {
    it("hand-authored prompt wins over field synthesis", () => {
      expect(svc.synthesizeCanonPrompt("characters", {
        name: "Mira",
        prompt: "custom prompt",
        physicalDescription: "weathered scavenger",
      })).toBe("custom prompt");
    });

    it("synthesizes from identifier + RICH descriptor for characters", () => {
      expect(svc.synthesizeCanonPrompt("characters", {
        name: "Mira",
        physicalDescription: "weathered scavenger",
        role: "protagonist",
      })).toBe("Mira — weathered scavenger. protagonist");
    });

    it("synthesizes from identifier + RICH descriptor for settings (capitalized prefixes)", () => {
      expect(svc.synthesizeCanonPrompt("places", {
        name: "Foundry City",
        description: "vast smelting works",
        palette: "rust + bone",
        era: "post-collapse",
        weather: "ash haze",
        recurringDetails: "broken statue at center",
      })).toBe("Foundry City — vast smelting works. Palette: rust + bone. Era: post-collapse. Weather: ash haze. broken statue at center");
    });

    it("falls back to slugline as identifier for settings without name", () => {
      expect(svc.synthesizeCanonPrompt("places", {
        slugline: "INT. FOUNDRY — DAY",
        description: "ore furnace",
      })).toBe("INT. FOUNDRY — DAY — ore furnace");
    });

    it("returns identifier alone when no descriptive fields are set", () => {
      expect(svc.synthesizeCanonPrompt("characters", { name: "Mira" })).toBe("Mira");
    });

    it("returns empty string for null entry", () => {
      expect(svc.synthesizeCanonPrompt("characters", null)).toBe("");
    });
  });

  describe("buildUniverseStyleContext", () => {
    const universe = {
      logline: "A foundry city goes silent.",
      premise: "post-collapse industrial sprawl",
      styleNotes: "moebius linework, ash palette",
      influences: { embrace: ["moebius linework", "cel-shading"], avoid: ["blurry"] },
    };

    it("returns '' for null universe", () => {
      expect(svc.buildUniverseStyleContext(null)).toBe("");
    });

    it("returns '' when no fields populate", () => {
      expect(svc.buildUniverseStyleContext({})).toBe("");
    });

    it("default options render bare `# Universe context` header with logline + styleNotes + embrace", () => {
      expect(svc.buildUniverseStyleContext(universe))
        .toBe("\n# Universe context\nLOGLINE: A foundry city goes silent.\n\nSTYLE NOTES: moebius linework, ash palette\n\nEMBRACE INFLUENCES: moebius linework, cel-shading\n");
    });

    it("headerSuffix appears after `Universe context — `", () => {
      const out = svc.buildUniverseStyleContext(
        { logline: "X" },
        { headerSuffix: "keep the new canon entry consistent with this established setting" },
      );
      expect(out).toBe("\n# Universe context — keep the new canon entry consistent with this established setting\nLOGLINE: X\n");
    });

    it("includePremise inserts PREMISE between LOGLINE and STYLE NOTES", () => {
      const out = svc.buildUniverseStyleContext(universe, { includePremise: true });
      expect(out.indexOf("LOGLINE:")).toBeLessThan(out.indexOf("PREMISE:"));
      expect(out.indexOf("PREMISE:")).toBeLessThan(out.indexOf("STYLE NOTES:"));
      expect(out).toContain("PREMISE: post-collapse industrial sprawl");
    });

    it("includeEmbrace:false suppresses the embrace line", () => {
      const out = svc.buildUniverseStyleContext(universe, { includeEmbrace: false });
      expect(out).not.toContain("EMBRACE INFLUENCES:");
      expect(out).toContain("LOGLINE:");
      expect(out).toContain("STYLE NOTES:");
    });

    it("escape:true collapses embedded newlines in styleNotes/logline", () => {
      const out = svc.buildUniverseStyleContext(
        { logline: "line1\nline2", styleNotes: "para1\n\npara2" },
        { escape: true },
      );
      expect(out).toContain("LOGLINE: line1 line2");
      expect(out).toContain("STYLE NOTES: para1 para2");
    });

    it("escape:false (default) preserves embedded newlines verbatim", () => {
      const out = svc.buildUniverseStyleContext({ logline: "line1\nline2" });
      expect(out).toContain("LOGLINE: line1\nline2");
    });

    it("returns '' when only premise is set but includePremise is false (the default)", () => {
      expect(svc.buildUniverseStyleContext({ premise: "p" })).toBe("");
    });

    it("expand-variations call shape (includePremise + includeEmbrace:false + headerSuffix) renders only logline/premise/styleNotes", () => {
      const out = svc.buildUniverseStyleContext(
        { logline: "L", premise: "P", styleNotes: "S", influences: { embrace: ["should-not-appear"] } },
        {
          includePremise: true,
          includeEmbrace: false,
          headerSuffix: "keep new variations consistent with this established setting",
        },
      );
      expect(out).toBe("\n# Universe context — keep new variations consistent with this established setting\nLOGLINE: L\n\nPREMISE: P\n\nSTYLE NOTES: S\n");
    });
  });

  describe("compilePrompts", () => {
    it("returns one prompt per variation across selected categories with style prefix", async () => {
      const w = await seedWorld();
      const compiled = svc.compilePrompts(w);
      // 2 landscapes + 1 outfit = 3 (other categories empty)
      expect(compiled).toHaveLength(3);
      // Style prefix uses `. ` separator (composeStyledPrompt convention,
      // shared with the scenePrompt composer in the client).
      expect(compiled[0].prompt).toBe(
        "moebius linework, scavengers reign palette. crystalline canyon, alien sun",
      );
      expect(compiled[0].category).toBe("landscapes");
      expect(compiled[0].label).toBe("Crystal Canyon");
      expect(compiled[0].negativePrompt).toBe("blurry, lowres");
    });

    it("includes custom categories by default", async () => {
      const w = await seedWorld({
        categories: {
          colonies: {
            variations: [
              {
                label: "Canopy Symbiotes",
                prompt:
                  "leaf-fiber clothing reference sheet, sap resin closures",
              },
            ],
          },
        },
      });
      const compiled = svc.compilePrompts(w);
      expect(compiled).toHaveLength(1);
      expect(compiled[0]).toMatchObject({
        category: "colonies",
        label: "Canopy Symbiotes",
      });
    });

    it("respects batchPerVariation", async () => {
      const w = await seedWorld();
      const compiled = svc.compilePrompts(w, { batchPerVariation: 3 });
      expect(compiled).toHaveLength(9); // 3 variations × 3 batch
      expect(compiled.filter((c) => c.label === "Crystal Canyon")).toHaveLength(
        3,
      );
    });

    it("selection: array filters by label (case-insensitive)", async () => {
      const w = await seedWorld();
      const compiled = svc.compilePrompts(w, {
        selection: { landscapes: ["crystal canyon"], outfits: "all" },
      });
      // 1 landscape (filtered) + 1 outfit (all) = 2
      expect(compiled).toHaveLength(2);
      expect(compiled.map((c) => c.label).sort()).toEqual([
        "Crystal Canyon",
        "Scavenger",
      ]);
    });

    it("selection: missing key skips category", async () => {
      const w = await seedWorld();
      const compiled = svc.compilePrompts(w, {
        selection: { landscapes: "all" },
      });
      expect(compiled).toHaveLength(2);
      expect(compiled.every((c) => c.category === "landscapes")).toBe(true);
    });

    it("selection supports custom category keys", async () => {
      const w = await seedWorld({
        categories: {
          raider_clans: {
            variations: [
              {
                label: "Wake Jackals",
                prompt: "clean scavenger raider outfit board",
              },
              {
                label: "Hull Vultures",
                prompt: "pressure-ring pirate boarding gear",
              },
            ],
          },
        },
      });
      const compiled = svc.compilePrompts(w, {
        selection: { raider_clans: ["wake jackals"] },
      });
      expect(compiled).toHaveLength(1);
      expect(compiled[0].label).toBe("Wake Jackals");
    });

    it("layers per-batch overrides on top of universe influences", async () => {
      const w = await seedWorld();
      const compiled = svc.compilePrompts(w, {
        selection: { landscapes: ["crystal canyon"] },
        extraStyle: "high contrast",
        extraNegative: "low quality",
        stylePresetPrompt: "noir cinematography",
        stylePresetNegative: "color photo",
      });
      expect(compiled).toHaveLength(1);
      // Baseline + preset + extra are comma-joined into the stylePreset prefix
      // and composeStyledPrompt sticks ". " between style and variation.
      expect(compiled[0].prompt).toBe(
        "moebius linework, scavengers reign palette, noir cinematography, high contrast. crystalline canyon, alien sun",
      );
      // Negative parts are comma-joined; composeStyledPrompt also adds a comma
      // when the user negative is non-empty, but here userNegative is empty so
      // we just see baseline + preset + extra.
      expect(compiled[0].negativePrompt).toBe(
        "blurry, lowres, color photo, low quality",
      );
      // Each block PortOS folds around the variation is listed; the batch's
      // own negative is the user's text, so it is not (#11317).
      expect(compiled[0].promptAdditions).toEqual([
        { id: "universe-style", label: "Universe style", text: "moebius linework, scavengers reign palette" },
        { id: "style-preset", label: "Style preset", text: "noir cinematography" },
        { id: "extra-style", label: "Batch extra style", text: "high contrast" },
        { id: "universe-avoid", label: "Universe avoid (negative prompt)", text: "blurry, lowres" },
        { id: "style-preset-negatives", label: "Style preset negatives", text: "color photo" },
      ]);
    });

    it("override fields default to baseline influences when omitted", async () => {
      const w = await seedWorld();
      const compiled = svc.compilePrompts(w, {
        selection: { landscapes: ["crystal canyon"] },
      });
      expect(compiled[0].prompt).toBe(
        "moebius linework, scavengers reign palette. crystalline canyon, alien sun",
      );
      expect(compiled[0].negativePrompt).toBe("blurry, lowres");
    });

    it("clamps batchPerVariation to 1..20", async () => {
      const w = await seedWorld();
      // 0 → 1
      expect(svc.compilePrompts(w, { batchPerVariation: 0 })).toHaveLength(3);
      // 100 → 20
      const big = svc.compilePrompts(w, { batchPerVariation: 100 });
      expect(big).toHaveLength(60); // 3 × 20
    });

    it("can compile composite sheets without atomic variations", async () => {
      const w = await seedWorld({
        categories: {},
        compositeSheets: [
          {
            label: "Canopy Symbiotes sheet",
            prompt:
              "clean costume reference sheet, lineup, materials, fasteners, palette",
          },
          {
            label: "Gas-Giant Drifters sheet",
            prompt:
              "clean costume reference sheet, pressure collars, clips, palette",
          },
        ],
      });
      const compiled = svc.compilePrompts(w, { promptMode: "sheets" });
      expect(compiled).toHaveLength(2);
      expect(compiled[0]).toMatchObject({
        category: "composite_sheets",
        label: "Canopy Symbiotes sheet",
        prompt:
          "moebius linework, scavengers reign palette. clean costume reference sheet, lineup, materials, fasteners, palette",
      });
    });

    it("tags universe pitch poster prompts separately from reference sheets", async () => {
      const w = await seedWorld({
        categories: {},
        compositeSheets: [
          {
            kind: "world_pitch_poster",
            label: "Universe pitch poster",
            prompt:
              "cinematic universe summary pitch poster, hero panorama, inset cultures, palette, themes",
          },
        ],
      });
      const compiled = svc.compilePrompts(w, { promptMode: "sheets" });
      expect(compiled).toHaveLength(1);
      expect(compiled[0]).toMatchObject({
        category: "world_pitch_posters",
        label: "Universe pitch poster",
      });
    });

    it("can compile atomic variations and composite sheets together", async () => {
      const w = await seedWorld({
        compositeSheets: [
          {
            label: "Gas-Giant Drifters sheet",
            prompt:
              "clean costume reference sheet, pressure collars, clips, palette",
          },
        ],
      });
      const compiled = svc.compilePrompts(w, { promptMode: "all" });
      expect(compiled).toHaveLength(4); // 3 atomic variations + 1 composite
      expect(compiled.map((p) => p.category)).toContain("composite_sheets");
    });

    describe("canon", () => {
      // Compile canon directly off a draft (createUniverse doesn't accept canon —
      // it lands via the canon-extract / refine path or the expand auto-save).
      // The synthesis path doesn't touch persistence, so a literal world shape
      // is enough.
      const canonWorld = () => ({
        influences: {
          embrace: ["moebius linework"],
          avoid: ["blurry"],
        },
        characters: [
          {
            name: "Mira",
            physicalDescription: "weathered scavenger, dust mask, copper goggles",
            role: "protagonist",
          },
          { name: "Vex", physicalDescription: "tall, scarred, plate-armor smith" },
        ],
        places: [
          {
            name: "Foundry City",
            slugline: "EXT. FOUNDRY CITY — DAY",
            description: "vast smelting works at the canyon rim",
            palette: "rust + bone",
          },
        ],
        objects: [
          { name: "Brass Compass", description: "always points away from home" },
        ],
      });

      it("synthesizes canon prompts from name + descriptive fields with style prefix", () => {
        const w = canonWorld();
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: "all", places: "all", objects: "all" },
        });
        // 2 characters + 1 setting + 1 object = 4
        expect(compiled).toHaveLength(4);
        const mira = compiled.find((c) => c.label === "Mira");
        expect(mira.category).toBe("canon:characters");
        expect(mira.prompt).toBe(
          "moebius linework. Mira — weathered scavenger, dust mask, copper goggles. protagonist",
        );
        expect(mira.negativePrompt).toBe("blurry");
        const place = compiled.find((c) => c.label === "Foundry City");
        expect(place.category).toBe("canon:places");
        expect(place.prompt).toContain("Foundry City");
        expect(place.prompt).toContain("Palette: rust + bone");
      });

      it("canonSelection: missing trunk skips it", () => {
        const w = canonWorld();
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { places: "all" },
        });
        expect(compiled).toHaveLength(1);
        expect(compiled[0].category).toBe("canon:places");
      });

      it("canonSelection: array filters by name (case-insensitive)", () => {
        const w = canonWorld();
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: ["mira"] },
        });
        expect(compiled).toHaveLength(1);
        expect(compiled[0].label).toBe("Mira");
      });

      it("synthesizes a settings prompt from slugline-only entries (no name)", () => {
        // The bible sanitizer accepts a setting whose only identifier is a
        // slugline (name field empty). synthesizeCanonPrompt must fall back
        // to slugline as the identifier seed so such entries don't silently
        // synthesize to '' and get skipped at render time.
        const w = canonWorld();
        w.places.push({
          // No name — only a slugline identifier + description.
          slugline: "INT. OLD ARCHIVE — NIGHT",
          description: "lantern-lit shelves of ledgers",
        });
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { places: "all" },
        });
        // Two settings now: the named Foundry City + the slugline-only Archive.
        expect(compiled).toHaveLength(2);
        const archive = compiled.find((c) => c.label === "INT. OLD ARCHIVE — NIGHT");
        expect(archive).toBeTruthy();
        expect(archive.prompt).toContain("INT. OLD ARCHIVE — NIGHT");
        expect(archive.prompt).toContain("lantern-lit shelves of ledgers");
      });

      it("canonSelection: settings also matches by slugline", () => {
        const w = canonWorld();
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { places: ["EXT. FOUNDRY CITY — DAY"] },
        });
        expect(compiled).toHaveLength(1);
        expect(compiled[0].label).toBe("Foundry City");
      });

      it("canonSelection: slugline matching is settings-only (characters/objects ignore stray slugline)", () => {
        // A stray `slugline` on a character or object should NOT participate
        // in canon-selection matching — slugline is part of the settings
        // schema only. This guards against accidental cross-trunk selection
        // when an upstream tool mis-tags an entry.
        const w = {
          ...canonWorld(),
          characters: [
            {
              name: "Ghost",
              slugline: "should-not-match-on-character",
              physicalDescription: "spectral",
            },
          ],
          objects: [
            {
              name: "Shard",
              slugline: "should-not-match-on-object",
              description: "humming crystal",
            },
          ],
        };
        const charsCompiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: ["should-not-match-on-character"] },
        });
        expect(charsCompiled).toHaveLength(0);
        const objsCompiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { objects: ["should-not-match-on-object"] },
        });
        expect(objsCompiled).toHaveLength(0);
        // Sanity — name still matches.
        const nameMatched = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: ["Ghost"], objects: ["Shard"] },
        });
        expect(nameMatched).toHaveLength(2);
      });

      it("entry.prompt wins over synthesized fields", () => {
        const w = {
          ...canonWorld(),
          characters: [
            {
              name: "Mira",
              physicalDescription: "ignored",
              prompt: "explicit hand-authored prompt",
            },
          ],
        };
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: "all" },
        });
        expect(compiled).toHaveLength(1);
        expect(compiled[0].prompt).toBe(
          "moebius linework. explicit hand-authored prompt",
        );
      });

      it("skips entries with no name and no descriptive content", () => {
        const w = { ...canonWorld(), characters: [{}, { name: "Mira" }] };
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: "all" },
        });
        expect(compiled).toHaveLength(1);
        expect(compiled[0].label).toBe("Mira");
      });

      it("promptMode=all compiles variations + sheets + canon together", async () => {
        const w = await seedWorld({
          compositeSheets: [
            { label: "Sheet", prompt: "clean reference sheet" },
          ],
        });
        // Layer canon directly onto the persisted world for this scenario.
        w.characters = [
          { name: "Mira", physicalDescription: "weathered scavenger" },
        ];
        const compiled = svc.compilePrompts(w, {
          promptMode: "all",
          canonSelection: { characters: "all" },
        });
        // 3 variations + 1 sheet + 1 canon = 5
        expect(compiled).toHaveLength(5);
        expect(compiled.map((c) => c.category)).toContain("canon:characters");
      });

      it("respects batchPerVariation for canon", () => {
        const w = canonWorld();
        const compiled = svc.compilePrompts(w, {
          promptMode: "canon",
          canonSelection: { characters: ["mira"] },
          batchPerVariation: 3,
        });
        expect(compiled).toHaveLength(3);
        expect(compiled.every((c) => c.label === "Mira")).toBe(true);
      });

      it("canon promptMode without canonSelection produces no prompts", () => {
        const w = canonWorld();
        const compiled = svc.compilePrompts(w, { promptMode: "canon" });
        expect(compiled).toEqual([]);
      });
    });
  });

  describe("influences", () => {
    // These tests probe the per-list sanitizer in isolation, so they override
    // seedWorld's default influences with their own to keep the assertions
    // focused on the input under test (the default influences would otherwise
    // round-trip alongside and confuse the expected output).
    it("round-trips embrace + avoid lists through createUniverse", async () => {
      const w = await seedWorld({
        influences: {
          embrace: ["Moebius", "cel-shading"],
          avoid: ["Ghibli painterly", "neon cyberpunk"],
        },
      });
      expect(w.influences.embrace).toEqual(["Moebius", "cel-shading"]);
      expect(w.influences.avoid).toEqual([
        "Ghibli painterly",
        "neon cyberpunk",
      ]);
    });

    it("dedupes influences case-insensitively, trims, drops empties + invalid types", async () => {
      const w = await seedWorld({
        influences: {
          embrace: ["Moebius", "moebius", "  cel-shading  ", "", 42, null],
          avoid: ["Ghibli", "ghibli"],
        },
      });
      expect(w.influences.embrace).toEqual(["Moebius", "cel-shading"]);
      expect(w.influences.avoid).toEqual(["Ghibli"]);
    });

    it("defaults to empty lists when influences is missing or invalid", async () => {
      // seedWorld seeds non-empty influences by default — override with empty
      // lists so this test isolates the missing/invalid branch.
      const w = await seedWorld({ influences: { embrace: [], avoid: [] } });
      expect(w.influences).toEqual({ embrace: [], avoid: [] });
      const w2 = await seedWorld({
        name: "second",
        influences: "not-an-object",
      });
      expect(w2.influences).toEqual({ embrace: [], avoid: [] });
    });

    it("caps influence lists at INFLUENCES_PER_LIST_MAX", async () => {
      const tooMany = Array.from(
        { length: svc.INFLUENCES_PER_LIST_MAX + 12 },
        (_, i) => `ref-${i}`,
      );
      const w = await seedWorld({
        influences: { embrace: tooMany, avoid: [] },
      });
      expect(w.influences.embrace).toHaveLength(svc.INFLUENCES_PER_LIST_MAX);
    });

    it("updateUniverse replaces influence lists wholesale (does not merge)", async () => {
      const w = await seedWorld({
        influences: { embrace: ["A", "B"], avoid: ["X"] },
      });
      const patched = await svc.updateUniverse(w.id, {
        influences: { embrace: ["C"] },
      });
      // Wholesale replace: avoid is gone because the patch didn't carry it.
      expect(patched.influences.embrace).toEqual(["C"]);
      expect(patched.influences.avoid).toEqual([]);
    });

    it("compilePrompts joins embrace verbatim into prompt + avoid into negative", async () => {
      const w = await seedWorld({
        influences: {
          embrace: ["Moebius", "cel-shading", "ink", "dust palette"],
          avoid: ["ghibli painterly", "lowres"],
        },
      });
      const compiled = svc.compilePrompts(w, {
        selection: { landscapes: ["Crystal Canyon"] },
      });
      expect(compiled).toHaveLength(1);
      // Embrace tokens land verbatim as the style prefix, joined with the
      // variation prompt via composeStyledPrompt's `. ` separator.
      expect(compiled[0].prompt).toBe(
        "Moebius, cel-shading, ink, dust palette. crystalline canyon, alien sun",
      );
      // Avoid tokens become the negative prompt verbatim.
      expect(compiled[0].negativePrompt).toBe("ghibli painterly, lowres");
    });

    it("compilePrompts absorbs legacy prose stylePrompt/negativePrompt into the chip lists", async () => {
      const w = await seedWorld({
        // Stale v2-shaped payload — prose tokens migrate into the chip lists
        // alongside any pre-existing influences and dedupe case-insensitively.
        stylePrompt: "cel-shading, ink, dust palette",
        negativePrompt: "lowres",
        influences: {
          embrace: ["Moebius", "cel-shading"],
          avoid: ["ghibli painterly", "lowres"],
        },
      });
      const compiled = svc.compilePrompts(w, {
        selection: { landscapes: ["Crystal Canyon"] },
      });
      expect(compiled).toHaveLength(1);
      // Chip tokens stay at the front (preserve user ordering); prose tokens
      // land at the tail. "cel-shading" / "lowres" dedupe at the sanitizer.
      expect(compiled[0].prompt).toBe(
        "Moebius, cel-shading, ink, dust palette. crystalline canyon, alien sun",
      );
      expect((compiled[0].prompt.match(/cel-shading/g) || []).length).toBe(1);
      expect(compiled[0].negativePrompt).toBe("ghibli painterly, lowres");
      expect((compiled[0].negativePrompt.match(/lowres/g) || []).length).toBe(1);
    });
  });

  describe("per-item locks", () => {
    it("defaults variations to locked + preserves explicit lock state", async () => {
      // Variations now lock-by-default: an entry with no `locked` field
      // reads as locked, and explicit `false` survives the round-trip so
      // a user-unlock isn't silently re-locked on the next read.
      const w = await seedWorld({
        categories: {
          landscapes: {
            variations: [
              { label: "Pinned canyon", prompt: "pinned canyon prompt", locked: true },
              { label: "Open canyon", prompt: "open canyon prompt" },
              { label: "Hand-unlocked", prompt: "hand unlocked prompt", locked: false },
            ],
          },
        },
      });
      const vs = w.categories.landscapes.variations;
      expect(vs.find((v) => v.label === "Pinned canyon").locked).toBe(true);
      expect(vs.find((v) => v.label === "Open canyon").locked).toBe(true);
      expect(vs.find((v) => v.label === "Hand-unlocked").locked).toBe(false);
    });

    it("coerces non-boolean `locked` values to the locked-by-default state", async () => {
      // Anything other than `false` collapses to the default (true); only
      // explicit `false` records an unlock.
      const w = await seedWorld({
        categories: {
          landscapes: {
            variations: [
              { label: "A", prompt: "a", locked: false },
              { label: "B", prompt: "b", locked: "yes" },
              { label: "C", prompt: "c", locked: 1 },
            ],
          },
        },
      });
      const labels = Object.fromEntries(
        w.categories.landscapes.variations.map((v) => [v.label, v.locked]),
      );
      expect(labels.A).toBe(false);
      expect(labels.B).toBe(true);
      expect(labels.C).toBe(true);
    });

    it("defaults composite sheets to locked + preserves explicit lock state", async () => {
      const w = await seedWorld({
        compositeSheets: [
          {
            label: "Pinned poster",
            prompt: "pinned poster prompt long enough",
            kind: "world_pitch_poster",
            locked: true,
          },
          { label: "Open sheet", prompt: "open sheet prompt long enough" },
          { label: "Unlocked sheet", prompt: "unlocked sheet prompt long enough", locked: false },
        ],
      });
      expect(
        w.compositeSheets.find((s) => s.label === "Pinned poster").locked,
      ).toBe(true);
      expect(
        w.compositeSheets.find((s) => s.label === "Open sheet").locked,
      ).toBe(true);
      expect(
        w.compositeSheets.find((s) => s.label === "Unlocked sheet").locked,
      ).toBe(false);
    });
  });

  describe("setVariationsLockAll", () => {
    const seedTwoBuckets = () =>
      seedWorld({
        categories: {
          landscapes: {
            variations: [
              { label: "A", prompt: "a" },
              { label: "B", prompt: "b", locked: false },
            ],
          },
          outfits: {
            variations: [
              { label: "X", prompt: "x" },
              { label: "Y", prompt: "y" },
            ],
          },
        },
      });

    it("scopes total + changed counts to a single bucket when categoryKey is set", async () => {
      // Regression guard: previously `total += variations.length` ran before
      // the categoryKey filter, so a single-bucket call over-reported the
      // denominator as every variation universe-wide.
      const w = await seedTwoBuckets();
      const res = await svc.setVariationsLockAll(w.id, {
        categoryKey: "landscapes",
        locked: false,
      });
      expect(res.total).toBe(2); // only landscapes' variations counted
      expect(res.changed).toBe(1); // only "A" flipped (true → false); "B" already false
      const reread = (await svc.listUniverses())[0];
      expect(reread.categories.landscapes.variations.every((v) => v.locked === false)).toBe(true);
      // Other bucket untouched.
      expect(reread.categories.outfits.variations.every((v) => v.locked === true)).toBe(true);
    });

    it("universe-wide path locks every variation across every bucket", async () => {
      const w = await seedTwoBuckets();
      // First, unlock everything explicitly so the test's "lock all" call has
      // real work to do (sanitizer defaults new variations to locked).
      await svc.setVariationsLockAll(w.id, { locked: false });
      const res = await svc.setVariationsLockAll(w.id, { locked: true });
      expect(res.total).toBe(4); // 2 landscapes + 2 outfits
      expect(res.changed).toBe(4);
      const reread = (await svc.listUniverses())[0];
      for (const bucket of Object.values(reread.categories)) {
        expect(bucket.variations.every((v) => v.locked === true)).toBe(true);
      }
    });

    it("includeSheets: true also flips composite sheets in the same call (only when no categoryKey)", async () => {
      const w = await seedWorld({
        compositeSheets: [
          { label: "Cover board", prompt: "cover board prompt long enough" },
        ],
      });
      await svc.setVariationsLockAll(w.id, { locked: false, includeSheets: true });
      const reread = (await svc.listUniverses())[0];
      expect(reread.compositeSheets[0].locked).toBe(false);
    });

    it("ignores includeSheets when a categoryKey is set (single-bucket scope is strict)", async () => {
      const w = await seedWorld({
        compositeSheets: [
          { label: "Cover board", prompt: "cover board prompt long enough" },
        ],
      });
      await svc.setVariationsLockAll(w.id, {
        categoryKey: "landscapes",
        locked: false,
        includeSheets: true,
      });
      const reread = (await svc.listUniverses())[0];
      expect(reread.compositeSheets[0].locked).toBe(true); // still locked
    });
  });

  describe("locked", () => {
    it("round-trips a sparse lock map and replaces wholesale on patch", async () => {
      const w = await seedWorld({
        locked: { logline: true, influencesEmbrace: true },
      });
      expect(w.locked).toEqual({ logline: true, influencesEmbrace: true });
      const patched = await svc.updateUniverse(w.id, {
        locked: { styleNotes: true },
      });
      expect(patched.locked).toEqual({ styleNotes: true });
    });

    it("ignores non-true / unknown lock keys", async () => {
      const w = await seedWorld({
        locked: { logline: false, bogus: true, premise: true },
      });
      expect(w.locked).toEqual({ premise: true });
    });

    it("migrates legacy `locked.influences: true` into per-list locks", async () => {
      // Prior schema combined embrace + avoid into one `influences` lock. The
      // sanitizer now splits it into two so existing on-disk universes keep working
      // without a data migration step.
      const w = await seedWorld({ locked: { influences: true, premise: true } });
      expect(w.locked).toEqual({
        premise: true,
        influencesEmbrace: true,
        influencesAvoid: true,
      });
    });
  });

  describe("categories→canon backfill", () => {
    it("upgrades v4 to v5 without re-folding exploratory categories into canon", () => {
      const w = svc.sanitizeTemplate({
        id: "world-v4",
        name: "Already backfilled",
        schemaVersion: 4,
        categories: {
          landscapes: { kind: "places", variations: [{ label: "New Vista", prompt: "exploratory" }] },
        },
        characters: [],
        places: [],
        objects: [],
      });
      expect(w.schemaVersion).toBe(svc.CURRENT_SCHEMA_VERSION);
      expect(w.places).toEqual([]);
      expect(w.styleReferences).toEqual([]);
    });

    it("backfills canon arrays from categories on first read + stamps the current schema version", async () => {
      await seedState({
        universes: [
          {
            id: "w-v1", name: "Legacy",
            starterPrompt: "old", stylePrompt: "", negativePrompt: "",
            categories: {
              characters: { variations: [{ label: "Alex", prompt: "field lead detective" }] },
              landscapes: { variations: [{ label: "Crystal Canyon", prompt: "canyon, alien sun", locked: true }] },
              environments: { variations: [{ label: "Bubble Room", prompt: "pastel lab" }] },
              vehicles: { variations: [{ label: "Rover", prompt: "dust-streaked rover" }] },
              structures: { variations: [{ label: "Monolith", prompt: "black monolith" }] },
              factions: { variations: [{ label: "Rebels", prompt: "scarred faction icon" }] }, // custom key → object tagged 'factions'
            },
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      const list = await svc.listUniverses();
      const w = list[0];
      expect(w.schemaVersion).toBe(svc.CURRENT_SCHEMA_VERSION);
      // Characters
      const alex = w.characters.find((c) => c.name === "Alex");
      expect(alex).toBeTruthy();
      expect(alex.prompt).toBe("field lead detective");
      expect(alex.tags).toEqual([]);
      expect(alex.source).toBe("universe-expand");
      // Places — landscape + environment
      const canyon = w.places.find((s) => s.name === "Crystal Canyon");
      expect(canyon.tags).toEqual(["landscape"]);
      expect(canyon.locked).toBe(true); // variation lock carries through
      expect(canyon.slugline).toBe("Crystal Canyon"); // places need slugline
      const bubble = w.places.find((s) => s.name === "Bubble Room");
      expect(bubble.tags).toEqual(["environment"]);
      // Objects — vehicle + structure + custom 'factions'
      const rover = w.objects.find((o) => o.name === "Rover");
      expect(rover.tags).toEqual(["vehicle"]);
      const monolith = w.objects.find((o) => o.name === "Monolith");
      expect(monolith.tags).toEqual(["structure"]);
      const rebels = w.objects.find((o) => o.name === "Rebels");
      expect(rebels.tags).toEqual(["factions"]); // unknown category key → object catch-all
    });

    it("backfill is idempotent — re-reading an already-migrated universe does not duplicate canon", async () => {
      await seedState({
        universes: [
          {
            id: "w-v1", name: "Legacy",
            starterPrompt: "old", stylePrompt: "", negativePrompt: "",
            categories: {
              characters: { variations: [{ label: "Alex", prompt: "detective" }] },
            },
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      // First read triggers backfill + persist.
      const first = (await svc.listUniverses())[0];
      expect(first.characters.length).toBe(1);
      // Second read — current schemaVersion already on disk, backfill skipped.
      const second = (await svc.listUniverses())[0];
      expect(second.characters.length).toBe(1);
      // Third read post-rename: a user-renamed entry must not be clobbered by
      // re-running backfill (the schemaVersion guard prevents the re-insert).
      const renamed = { ...second, characters: second.characters.map((c) => ({ ...c, name: "Alex Smith" })) };
      await seedState({ universes: [renamed], runs: [] });
      const third = (await svc.listUniverses())[0];
      expect(third.characters.length).toBe(1);
      expect(third.characters[0].name).toBe("Alex Smith");
    });

    it("backfill does not overwrite a pre-existing canon entry sharing a variation label", async () => {
      await seedState({
        universes: [
          {
            id: "w-mixed", name: "Mixed",
            starterPrompt: "", stylePrompt: "", negativePrompt: "",
            categories: {
              characters: { variations: [{ label: "Alex", prompt: "from variation" }] },
            },
            // Hand-authored canon entry whose name collides with the variation
            // label. Backfill must NOT overwrite — the canon entry's richer
            // metadata wins.
            characters: [{
              id: "chr-existing", name: "Alex",
              role: "Hand-authored role",
              physicalDescription: "hand-authored description",
              source: "manual",
            }],
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      const w = (await svc.listUniverses())[0];
      // Still exactly one Alex (no duplicate).
      const alexes = w.characters.filter((c) => c.name === "Alex");
      expect(alexes.length).toBe(1);
      // Hand-authored fields preserved; the variation's prompt didn't bleed in.
      expect(alexes[0].role).toBe("Hand-authored role");
      expect(alexes[0].source).toBe("manual");
    });
  });

  describe("category kind (schema v4)", () => {
    it("assigns built-in default kinds (landscapes/environments/structures→settings, vehicles→objects)", async () => {
      const w = await seedWorld();
      expect(w.categories.landscapes.kind).toBe("places");
      expect(w.categories.environments.kind).toBe("places");
      expect(w.categories.structures.kind).toBe("places");
      expect(w.categories.vehicles.kind).toBe("objects");
    });

    it("defaults custom (non-built-in) buckets to 'other'", async () => {
      const w = await seedWorld({
        categories: {
          factions: { variations: [{ label: "Rebels", prompt: "x" }] },
          colonies: { variations: [{ label: "Tycho", prompt: "y" }] },
        },
      });
      expect(w.categories.factions.kind).toBe("other");
      expect(w.categories.colonies.kind).toBe("other");
    });

    it("honors an explicit valid `kind` from the input over the built-in default", async () => {
      const w = await seedWorld({
        categories: {
          landscapes: { kind: "objects", variations: [] },
          factions: { kind: "characters", variations: [{ label: "Iron Reach", prompt: "z" }] },
        },
      });
      expect(w.categories.landscapes.kind).toBe("objects"); // override beats default
      expect(w.categories.factions.kind).toBe("characters");
    });

    it("falls back to default when explicit `kind` is invalid", async () => {
      const w = await seedWorld({
        categories: {
          landscapes: { kind: "not-a-kind", variations: [] },
          vehicles: { kind: 42, variations: [] },
          colonies: { kind: null, variations: [{ label: "Tycho", prompt: "x" }] },
        },
      });
      expect(w.categories.landscapes.kind).toBe("places"); // built-in default
      expect(w.categories.vehicles.kind).toBe("objects"); // built-in default
      expect(w.categories.colonies.kind).toBe("other"); // custom fallback
    });

    it("drops the legacy default `characters` bucket and folds variations into canon", async () => {
      const w = await seedWorld({
        categories: {
          // Mimic a v3 client (or post-migration tab) accidentally sending the
          // retired bucket — sanitize folds it into canon.characters[] and
          // drops the bucket entirely.
          characters: {
            variations: [
              { label: "Ash", prompt: "young survivor with iron rebar" },
              { label: "Roan", prompt: "weathered scavenger" },
            ],
          },
        },
      });
      expect(w.categories.characters).toBeUndefined();
      const ash = w.characters.find((c) => c.name === "Ash");
      const roan = w.characters.find((c) => c.name === "Roan");
      expect(ash).toBeDefined();
      expect(ash.prompt).toBe("young survivor with iron rebar");
      expect(roan).toBeDefined();
    });

    it("WORLD_CATEGORIES no longer includes `characters`", () => {
      expect(svc.WORLD_CATEGORIES).not.toContain("characters");
      expect(svc.WORLD_CATEGORIES).toEqual(
        expect.arrayContaining(["landscapes", "environments", "structures", "vehicles"]),
      );
    });

    it("kind round-trips through update", async () => {
      const w = await seedWorld({
        categories: { factions: { variations: [{ label: "Iron Reach", prompt: "x" }] } },
      });
      const patched = await svc.updateUniverse(w.id, {
        categories: { factions: { kind: "characters", variations: [{ label: "Iron Reach", prompt: "x" }] } },
      });
      expect(patched.categories.factions.kind).toBe("characters");
    });
  });

  describe("factual flag (#7616)", () => {
    it("persists `factual` only when true, leaving a fiction universe byte-identical", async () => {
      const base = {
        id: "w-factual", name: "Example Universe",
        schemaVersion: svc.CURRENT_SCHEMA_VERSION, createdAt: "2024-01-01T00:00:00Z",
      };
      // The regression this catches: persisting `factual: false` would add a key
      // to EVERY existing universe's record, changing the wire checksum that
      // peer sync and the conflict journal both hash — so every untouched world
      // would look edited on the next sync.
      const fiction = svc.sanitizeTemplate(base);
      expect("factual" in fiction).toBe(false);
      expect(JSON.stringify(svc.sanitizeTemplate({ ...base, factual: false })))
        .toBe(JSON.stringify(fiction));
      expect(svc.sanitizeTemplate({ ...base, factual: true }).factual).toBe(true);
    });

    it("round-trips the flag through create and PATCH, and `false` clears it", async () => {
      const u = await svc.createUniverse({ name: "Reality", factual: true });
      expect(u.factual).toBe(true);
      expect((await svc.getUniverse(u.id)).factual).toBe(true);

      const cleared = await svc.updateUniverse(u.id, { factual: false });
      expect("factual" in cleared).toBe(false);
      expect(await svc.updateUniverse(u.id, { factual: true })).toMatchObject({ factual: true });
    });
  });

  describe("entry ids + render history", () => {
    it("sanitizeTemplate mints stable ids for variations + composite sheets", async () => {
      const u = await svc.createUniverse({
        name: "Avatars",
        categories: {
          landscapes: { variations: [{ label: "L1", prompt: "p1" }] },
        },
        compositeSheets: [{ kind: "reference_sheet", label: "S1", prompt: "sp" }],
      });
      const v = u.categories.landscapes.variations[0];
      expect(v.id).toMatch(/^var-/);
      expect(v.imageRefs).toEqual([]);
      const sheet = u.compositeSheets[0];
      expect(sheet.id).toMatch(/^sheet-/);
      expect(sheet.imageRefs).toEqual([]);
    });

    it("sanitizeTemplate round-trips existing variation + sheet ids verbatim", async () => {
      await seedState({
        universes: [
          {
            id: "w1",
            name: "X",
            schemaVersion: svc.CURRENT_SCHEMA_VERSION,
            categories: {
              landscapes: {
                kind: "places",
                variations: [{ id: "var-keep-me", label: "V1", prompt: "p1" }],
              },
            },
            compositeSheets: [{ id: "sheet-keep-me", kind: "reference_sheet", label: "S1", prompt: "sp" }],
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      const list = await svc.listUniverses();
      expect(list[0].categories.landscapes.variations[0].id).toBe("var-keep-me");
      expect(list[0].compositeSheets[0].id).toBe("sheet-keep-me");
    });

    it("legacy universe (no variation ids on disk) gets unstable in-memory ids until persisted, then stable after a write", async () => {
      // Plant a pre-PR universe shape with no variation/sheet ids. Reads
      // through readState() mint fresh UUIDs each call because the migration
      // is not persisted there (race-safety against concurrent writers — see
      // readState() docstring). After a no-op updateUniverse() forces a write,
      // ids land on disk and every subsequent read returns the same ones.
      await seedState({
        universes: [
          {
            id: "legacy-universe",
            name: "Legacy",
            schemaVersion: svc.CURRENT_SCHEMA_VERSION,
            categories: {
              landscapes: { kind: "places", variations: [{ label: "L1", prompt: "p1" }] },
            },
            compositeSheets: [],
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      const a = await svc.getUniverse("legacy-universe");
      const b = await svc.getUniverse("legacy-universe");
      expect(a.categories.landscapes.variations[0].id).not.toBe(b.categories.landscapes.variations[0].id);
      // No-op mutator persists the in-memory sanitized shape (the render
      // route uses this to lock in entryRef.id before queueing jobs).
      const persisted = await svc.updateUniverse("legacy-universe", () => ({}));
      const variationIdPersisted = persisted.categories.landscapes.variations[0].id;
      const c = await svc.getUniverse("legacy-universe");
      expect(c.categories.landscapes.variations[0].id).toBe(variationIdPersisted);
      // appendEntryImageRef against the persisted id now succeeds.
      await svc.appendEntryImageRef("legacy-universe", { kind: "variation", categoryKey: "landscapes", id: variationIdPersisted }, "after-persist.png");
      const d = await svc.getUniverse("legacy-universe");
      expect(d.categories.landscapes.variations[0].imageRefs).toEqual(["after-persist.png"]);
    });

    it("needsEntryIdPersist returns true only when raw-disk variations or sheets lack ids", async () => {
      // Mixed fixture: one universe has ids on disk, the other doesn't.
      // The render route uses this helper to skip the no-op write when the
      // universe is already migrated — so already-upgraded records don't
      // bump updatedAt (which would interfere with LWW sync + spuriously
      // emit recordUpdated on every render).
      await seedState({
        universes: [
          {
            id: "fresh",
            name: "Fresh",
            schemaVersion: svc.CURRENT_SCHEMA_VERSION,
            categories: {
              landscapes: { kind: "places", variations: [{ id: "var-on-disk", label: "L", prompt: "p" }] },
            },
            compositeSheets: [{ id: "sheet-on-disk", kind: "reference_sheet", label: "S", prompt: "sp" }],
            createdAt: "2024-01-01T00:00:00Z",
          },
          {
            id: "legacy",
            name: "Legacy",
            schemaVersion: svc.CURRENT_SCHEMA_VERSION,
            categories: {
              landscapes: { kind: "places", variations: [{ label: "L", prompt: "p" }] },
            },
            compositeSheets: [],
            createdAt: "2024-01-01T00:00:00Z",
          },
          {
            id: "legacy-sheet",
            name: "LegacySheet",
            schemaVersion: svc.CURRENT_SCHEMA_VERSION,
            categories: {},
            compositeSheets: [{ kind: "reference_sheet", label: "S", prompt: "sp" }],
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      expect(await svc.needsEntryIdPersist("fresh")).toBe(false);
      expect(await svc.needsEntryIdPersist("legacy")).toBe(true);
      expect(await svc.needsEntryIdPersist("legacy-sheet")).toBe(true);
      expect(await svc.needsEntryIdPersist("does-not-exist")).toBe(false);
    });

    it("appendEntryImageRef appends to a variation's imageRefs by id", async () => {
      const u = await svc.createUniverse({
        name: "Bucket",
        categories: { landscapes: { variations: [{ label: "L1", prompt: "p1" }] } },
      });
      const variationId = u.categories.landscapes.variations[0].id;
      await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "rendered-1.png");
      await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "rendered-2.png");
      const updated = await svc.getUniverse(u.id);
      expect(updated.categories.landscapes.variations[0].imageRefs).toEqual(["rendered-1.png", "rendered-2.png"]);
    });

    it("appendEntryImageRef rejects pathy filenames up-front (no queued write)", async () => {
      // A renderer that ever returns a path-laden filename should be
      // rejected at the helper boundary — letting it through would trigger
      // a no-op write (sanitizer strips it later) and pointlessly bump
      // updatedAt + emit recordUpdated.
      const u = await svc.createUniverse({
        name: "PathReject",
        categories: { landscapes: { variations: [{ label: "L1", prompt: "p1" }] } },
      });
      const variationId = u.categories.landscapes.variations[0].id;
      const before = (await svc.getUniverse(u.id)).updatedAt;
      const result1 = await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "../escape.png");
      const result2 = await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "sub/file.png");
      const result3 = await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "..\\windows.png");
      expect(result1).toBe(null);
      expect(result2).toBe(null);
      expect(result3).toBe(null);
      const after = (await svc.getUniverse(u.id)).updatedAt;
      expect(after).toBe(before);
    });

    it("appendEntryImageRef dedupes a same-filename repeat render", async () => {
      const u = await svc.createUniverse({
        name: "Dedupe",
        compositeSheets: [{ kind: "reference_sheet", label: "S1", prompt: "sp" }],
      });
      const sheetId = u.compositeSheets[0].id;
      await svc.appendEntryImageRef(u.id, { kind: "sheet", id: sheetId }, "x.png");
      await svc.appendEntryImageRef(u.id, { kind: "sheet", id: sheetId }, "x.png");
      const updated = await svc.getUniverse(u.id);
      expect(updated.compositeSheets[0].imageRefs).toEqual(["x.png"]);
    });

    it("appendEntryImageRef appends to a canon entry's imageRefs by id", async () => {
      const u = await svc.createUniverse({
        name: "Canon",
        places: [{ id: "set-abc", name: "Library" }],
      });
      await svc.appendEntryImageRef(u.id, { kind: "canon", kindKey: "places", id: "set-abc" }, "place-render.png");
      const updated = await svc.getUniverse(u.id);
      expect(updated.places[0].imageRefs).toContain("place-render.png");
    });

    it("appendEntryImageRef is a no-op when entry id no longer exists", async () => {
      const u = await svc.createUniverse({ name: "Gone" });
      const result = await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: "var-missing" }, "x.png");
      // The mutator returns null → updateUniverse skips the write and resolves
      // with the unchanged record. Either shape is fine; we just want no throw.
      expect(result).toBeTruthy();
    });

    it("stale literal-object PATCH does not clobber server-stamped imageRefs (variations)", async () => {
      const u = await svc.createUniverse({
        name: "Stale",
        categories: { landscapes: { variations: [{ label: "L1", prompt: "p1" }] } },
      });
      const variationId = u.categories.landscapes.variations[0].id;
      // Server stamps a render history while the client is editing.
      await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "fresh.png");
      // Client (loaded BEFORE the render landed) PATCHes a label edit with
      // an empty imageRefs list. The stale-guard must preserve the freshly
      // appended filename.
      await svc.updateUniverse(u.id, {
        categories: {
          landscapes: {
            kind: "places",
            variations: [{ id: variationId, label: "L1 renamed", prompt: "p1", imageRefs: [] }],
          },
        },
      });
      const final = await svc.getUniverse(u.id);
      const v = final.categories.landscapes.variations[0];
      expect(v.label).toBe("L1 renamed");
      expect(v.imageRefs).toEqual(["fresh.png"]);
    });

    it("stale literal-object PATCH does not clobber server-stamped imageRefs (composite sheets)", async () => {
      const u = await svc.createUniverse({
        name: "StaleSheet",
        compositeSheets: [{ kind: "reference_sheet", label: "S1", prompt: "sp" }],
      });
      const sheetId = u.compositeSheets[0].id;
      await svc.appendEntryImageRef(u.id, { kind: "sheet", id: sheetId }, "sheet.png");
      await svc.updateUniverse(u.id, {
        compositeSheets: [{ id: sheetId, kind: "reference_sheet", label: "S1 renamed", prompt: "sp" }],
      });
      const final = await svc.getUniverse(u.id);
      expect(final.compositeSheets[0].label).toBe("S1 renamed");
      expect(final.compositeSheets[0].imageRefs).toEqual(["sheet.png"]);
    });

    it("stale at-cap PATCH detects rotation via tail mismatch (variations)", async () => {
      // Seed a variation whose imageRefs is already at the cap. A server-side
      // append rotates the list (drops oldest, pushes newest) — lengths stay
      // equal, so the stale-PATCH guard must compare the tail element, not
      // just the length.
      const cap = svc.IMAGE_REFS_PER_ENTRY_MAX;
      const capRefs = Array.from({ length: cap }, (_, i) => `r${i}.png`);
      const u = await svc.createUniverse({
        name: "Capped",
        categories: { landscapes: { variations: [{ label: "L1", prompt: "p1", imageRefs: capRefs }] } },
      });
      const variationId = u.categories.landscapes.variations[0].id;
      // Server appends a new render — list rotates (r0.png drops off, fresh.png appended).
      await svc.appendEntryImageRef(u.id, { kind: "variation", categoryKey: "landscapes", id: variationId }, "fresh.png");
      // Stale client (loaded BEFORE the rotation) PATCHes with the
      // pre-rotation list — same length, but tail is r{cap-1}.png instead of
      // fresh.png. Without the tail check, the stale list would clobber the
      // server-stamped fresh.png.
      await svc.updateUniverse(u.id, {
        categories: {
          landscapes: {
            kind: "places",
            variations: [{ id: variationId, label: "L1 renamed", prompt: "p1", imageRefs: capRefs }],
          },
        },
      });
      const final = await svc.getUniverse(u.id);
      const v = final.categories.landscapes.variations[0];
      expect(v.label).toBe("L1 renamed");
      // Tail should still be fresh.png (the server-stamped newest), not the
      // pre-rotation r{cap-1}.png from the stale patch.
      expect(v.imageRefs[v.imageRefs.length - 1]).toBe("fresh.png");
    });

    it("compilePrompts stamps entryRef on each compiled prompt", () => {
      const universe = {
        id: "w1",
        influences: { embrace: [], avoid: [] },
        categories: {
          landscapes: { kind: "places", variations: [{ id: "var-1", label: "L1", prompt: "p1" }] },
        },
        compositeSheets: [{ id: "sheet-1", kind: "reference_sheet", label: "S1", prompt: "sp" }],
        characters: [],
        places: [{ id: "set-abc", name: "Library" }],
        objects: [],
      };
      const variationCompiled = svc.compilePrompts(universe, { promptMode: "variations" });
      expect(variationCompiled).toHaveLength(1);
      expect(variationCompiled[0].entryRef).toEqual({ kind: "variation", categoryKey: "landscapes", id: "var-1" });

      const sheetCompiled = svc.compilePrompts(universe, { promptMode: "sheets" });
      expect(sheetCompiled).toHaveLength(1);
      expect(sheetCompiled[0].entryRef).toEqual({ kind: "sheet", id: "sheet-1" });

      const canonCompiled = svc.compilePrompts(universe, {
        promptMode: "canon",
        canonSelection: { places: "all" },
      });
      expect(canonCompiled).toHaveLength(1);
      expect(canonCompiled[0].entryRef).toEqual({ kind: "canon", kindKey: "places", id: "set-abc" });
    });

    it("imageRefs basename guard rejects path-separator filenames", async () => {
      await seedState({
        universes: [
          {
            id: "w1",
            name: "Guard",
            schemaVersion: svc.CURRENT_SCHEMA_VERSION,
            categories: {
              landscapes: {
                kind: "places",
                variations: [{ id: "var-1", label: "L", prompt: "p", imageRefs: ["../escape.png", "normal.png", "/abs/path.png", "..\\windows.png", "sub\\dir.png", "ok.png"] }],
              },
            },
            compositeSheets: [],
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      const list = await svc.listUniverses();
      expect(list[0].categories.landscapes.variations[0].imageRefs).toEqual(["normal.png", "ok.png"]);
    });
  });

  describe("sanitizers", () => {
    it("drops malformed variations on read", async () => {
      // Manually plant invalid state — sanitizeTemplate strips it on read.
      await seedState({
        universes: [
          {
            id: "w1",
            name: "X",
            starterPrompt: "",
            stylePrompt: "",
            negativePrompt: "",
            categories: {
              landscapes: {
                variations: [
                  { label: "Good", prompt: "good prompt" },
                  { label: "", prompt: "no label" },
                  { label: "No prompt", prompt: "" },
                  null,
                ],
              },
            },
            createdAt: "2024-01-01T00:00:00Z",
          },
        ],
        runs: [],
      });
      const list = await svc.listUniverses();
      expect(list[0].categories.landscapes.variations).toHaveLength(1);
      expect(list[0].categories.landscapes.variations[0].label).toBe("Good");
    });
  });

  describe("moodBoardId (linked mood board, #4188)", () => {
    it("persists through create and is absent when never set", async () => {
      const linked = await svc.createUniverse({ name: "Linked", moodBoardId: "mb-abc123" });
      expect(linked.moodBoardId).toBe("mb-abc123");
      const bare = await svc.createUniverse({ name: "Bare" });
      expect("moodBoardId" in bare).toBe(false);
    });

    it("PATCH sets, preserves-on-absent, and clears on ''/null", async () => {
      const w = await svc.createUniverse({ name: "W" });
      const set = await svc.updateUniverse(w.id, { moodBoardId: "mb-1" });
      expect(set.moodBoardId).toBe("mb-1");
      // A patch that doesn't carry the key preserves the link.
      const untouched = await svc.updateUniverse(w.id, { logline: "still linked" });
      expect(untouched.moodBoardId).toBe("mb-1");
      // Key-present with '' clears — the field drops back to absent.
      const cleared = await svc.updateUniverse(w.id, { moodBoardId: "" });
      expect("moodBoardId" in cleared).toBe(false);
      const setAgain = await svc.updateUniverse(w.id, { moodBoardId: "mb-2" });
      expect(setAgain.moodBoardId).toBe("mb-2");
      const nulled = await svc.updateUniverse(w.id, { moodBoardId: null });
      expect("moodBoardId" in nulled).toBe(false);
    });

    it("sanitizes a non-string value to absent on read", async () => {
      await seedState({
        universes: [{ id: "w-mb", name: "X", moodBoardId: 42, createdAt: "2024-01-01T00:00:00Z" }],
        runs: [],
      });
      const list = await svc.listUniverses();
      expect("moodBoardId" in list[0]).toBe(false);
    });
  });

  describe("insertUniverseWithId", () => {
    it("preserves the caller-supplied id", async () => {
      const u = await svc.insertUniverseWithId({
        id: "550e8400-e29b-41d4-a716-446655440000",
        name: "Imported Universe",
      });
      expect(u.id).toBe("550e8400-e29b-41d4-a716-446655440000");
      expect(u.name).toBe("Imported Universe");
    });

    it("rejects malformed id", async () => {
      await expect(svc.insertUniverseWithId({ id: "bad id with spaces", name: "X" }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
      await expect(svc.insertUniverseWithId({ name: "X" }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    });

    it("rejects duplicate id", async () => {
      const id = "550e8400-e29b-41d4-a716-446655440001";
      await svc.insertUniverseWithId({ id, name: "First" });
      await expect(svc.insertUniverseWithId({ id, name: "Second" }))
        .rejects.toMatchObject({ code: svc.ERR_DUPLICATE });
    });

    it("requires a name", async () => {
      await expect(svc.insertUniverseWithId({ id: "550e8400-e29b-41d4-a716-446655440002" }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    });
  });

  // Regression for "Async PATCH races on shared records — serialize writes
  // server-side" (AGENTS.md). Each updateUniverse() now goes through a
  // file-level write tail so a stale snapshot can't clobber a sibling write.
  describe("write serialization", () => {
    it("concurrent updates to the same universe preserve every field", async () => {
      const u = await svc.createUniverse({ name: "Race" });
      // Five concurrent PATCHes, each touching a different scalar field.
      // Without the queue, every call reads the same pre-PATCH snapshot and
      // the last writeState wins — only one field would survive.
      await Promise.all([
        svc.updateUniverse(u.id, { logline: "L1" }),
        svc.updateUniverse(u.id, { premise: "P1" }),
        svc.updateUniverse(u.id, { styleNotes: "S1" }),
        svc.updateUniverse(u.id, { starterPrompt: "SP1" }),
        svc.updateUniverse(u.id, { name: "N1" }),
      ]);
      const final = await svc.getUniverse(u.id);
      expect(final.logline).toBe("L1");
      expect(final.premise).toBe("P1");
      expect(final.styleNotes).toBe("S1");
      expect(final.starterPrompt).toBe("SP1");
      expect(final.name).toBe("N1");
    });

    it("concurrent updates to DIFFERENT universes preserve every field", async () => {
      // Per AGENTS.md: a Map<id, Promise> is NOT enough — both universes
      // share the same JSON file, so writes to different ids can still race.
      // The single file-level tail covers this.
      const a = await svc.createUniverse({ name: "A" });
      const b = await svc.createUniverse({ name: "B" });
      await Promise.all([
        svc.updateUniverse(a.id, { logline: "A-line", premise: "A-premise" }),
        svc.updateUniverse(b.id, { logline: "B-line", premise: "B-premise" }),
      ]);
      const fa = await svc.getUniverse(a.id);
      const fb = await svc.getUniverse(b.id);
      expect(fa.logline).toBe("A-line");
      expect(fa.premise).toBe("A-premise");
      expect(fb.logline).toBe("B-line");
      expect(fb.premise).toBe("B-premise");
    });

    it("a rejecting write does not poison the queue", async () => {
      // Force the rejection from INSIDE the queue (after the writeState would
      // run) so this actually pins poison-recovery rather than passing through
      // a fail-before-queue path. The first call's ERR_NOT_FOUND fires inside
      // the queued closure (the universe-id lookup happens after `readState`).
      const u = await svc.createUniverse({ name: "PoisonTest" });
      const results = await Promise.allSettled([
        svc.updateUniverse("nonexistent-universe", { logline: "X" }),
        svc.updateUniverse(u.id, { logline: "ok" }),
      ]);
      expect(results[0].status).toBe("rejected");
      expect(results[0].reason?.code).toBe(svc.ERR_NOT_FOUND);
      expect(results[1].status).toBe("fulfilled");
      const final = await svc.getUniverse(u.id);
      expect(final.logline).toBe("ok");
    });

    it("concurrent recordRun + updateUniverse don't clobber each other", async () => {
      const u = await svc.createUniverse({ name: "RunRace" });
      await Promise.all([
        svc.updateUniverse(u.id, { logline: "L" }),
        svc.recordRun({ id: "run-1", universeId: u.id, promptCount: 5 }),
        svc.updateUniverse(u.id, { premise: "P" }),
        svc.recordRun({ id: "run-2", universeId: u.id, promptCount: 7 }),
      ]);
      const final = await svc.getUniverse(u.id);
      const runs = await svc.listRuns(u.id);
      expect(final.logline).toBe("L");
      expect(final.premise).toBe("P");
      expect(runs).toHaveLength(2);
      expect(runs.map((r) => r.id).sort()).toEqual(["run-1", "run-2"]);
    });
  });

  // The slot map is in-process state; without these wirings entries persist
  // until the Node process restarts even after the character/universe is gone.
  describe("pending sheet slot cleanup", () => {
    it("updateUniverse clears slots for characters dropped from the PATCH", async () => {
      const slot = await import("./universeCharacterSheetSlot.js");
      const u = await svc.createUniverse({ name: "SlotPatchTest" });
      // Plant two characters via mutator (trusted path).
      await svc.updateUniverse(u.id, () => ({
        characters: [
          { id: "c-keep", name: "Keep" },
          { id: "c-drop", name: "Drop" },
        ],
      }));
      // Simulate two in-flight renders.
      slot.claimPendingSheetSlot(u.id, "c-keep", "job-keep");
      slot.claimPendingSheetSlot(u.id, "c-drop", "job-drop");
      // Drop one character via PATCH.
      await svc.updateUniverse(u.id, {
        characters: [{ id: "c-keep", name: "Keep" }],
      });
      // Slot for the dropped character is released; the survivor's slot
      // is untouched.
      expect(slot.getPendingSheetSlot(u.id, "c-drop")).toBeUndefined();
      expect(slot.getPendingSheetSlot(u.id, "c-keep")).toBe("job-keep");
      // teardown
      slot.clearPendingSheetSlotsForUniverse(u.id);
    });

    it("updateUniverse leaves slots intact when the PATCH does not remove characters", async () => {
      const slot = await import("./universeCharacterSheetSlot.js");
      const u = await svc.createUniverse({ name: "SlotIdempotentTest" });
      await svc.updateUniverse(u.id, () => ({
        characters: [{ id: "c-1", name: "One" }],
      }));
      slot.claimPendingSheetSlot(u.id, "c-1", "job-1");
      // PATCH that adds a sibling character — the original's slot must
      // survive.
      await svc.updateUniverse(u.id, {
        characters: [
          { id: "c-1", name: "One" },
          { id: "c-2", name: "Two" },
        ],
      });
      expect(slot.getPendingSheetSlot(u.id, "c-1")).toBe("job-1");
      // PATCH that touches an unrelated scalar must not disturb either.
      await svc.updateUniverse(u.id, { logline: "irrelevant" });
      expect(slot.getPendingSheetSlot(u.id, "c-1")).toBe("job-1");
      slot.clearPendingSheetSlotsForUniverse(u.id);
    });

    it("deleteUniverse releases every slot keyed by the universe", async () => {
      const slot = await import("./universeCharacterSheetSlot.js");
      const u1 = await svc.createUniverse({ name: "SlotDeleteA" });
      const u2 = await svc.createUniverse({ name: "SlotDeleteB" });
      slot.claimPendingSheetSlot(u1.id, "char-1", "job-a1");
      slot.claimPendingSheetSlot(u1.id, "char-2", "job-a2");
      slot.claimPendingSheetSlot(u2.id, "char-1", "job-b1");
      await svc.deleteUniverse(u1.id);
      expect(slot.getPendingSheetSlot(u1.id, "char-1")).toBeUndefined();
      expect(slot.getPendingSheetSlot(u1.id, "char-2")).toBeUndefined();
      // Sibling universe's slot survives.
      expect(slot.getPendingSheetSlot(u2.id, "char-1")).toBe("job-b1");
      slot.clearPendingSheetSlotsForUniverse(u2.id);
    });
  });

  // ---------------------------------------------------------------------------
  // Character psychology profile (#6414)
  // ---------------------------------------------------------------------------
  //
  // The public boundary is create → getUniverse → updateUniverse, which is what
  // the Cast tab actually drives. These cases pin the contract that makes the
  // field safe to ship into installs that already hold characters: it is
  // absent until authored, it never rewrites the legacy framework fields, a
  // partial PATCH cannot wipe the leaves it omits, and an explicit clear works.
  describe("character psychology (#6414)", () => {
    const fullProfile = () => ({
      theoryOfControl: "If I stay useful, nobody leaves.",
      strategy: "Absorbs everyone else's work and never asks for anything back.",
      protectiveBenefit: "Keeps her from ever testing whether she'd be kept anyway.",
      presentCost: "Exhaustion, and a crew who never learns to carry its own weight.",
      testingPressure: "A job she physically cannot do alone.",
      candidateChange: "Asking for help before the failure, not after.",
      drives: {
        survival: { desire: "a berth she cannot be put out of", fear: "being turned out" },
        connection: { desire: "to be kept", fear: "being easy to replace" },
        status: { desire: "to be the one the crew counts on", fear: "being read as surplus" },
      },
    });

    it("round-trips a full profile through create → load → patch, and stays ABSENT until authored", async () => {
      const w = await svc.createUniverse({
        name: "Example Universe",
        characters: [
          { name: "Nera Vost", psychology: fullProfile() },
          { name: "Unassessed Sib" },
        ],
      });
      const loaded = await svc.getUniverse(w.id);
      const nera = loaded.characters.find((c) => c.name === "Nera Vost");
      const sib = loaded.characters.find((c) => c.name === "Unassessed Sib");

      expect(nera.psychology).toEqual({ ...fullProfile(), assessment: null, assessmentNote: "" });
      // A character nobody assessed carries no key at all — legacy records stay
      // byte-identical rather than gaining an empty husk that reads as filled.
      expect("psychology" in sib).toBe(false);

      const patched = await svc.updateUniverse(w.id, (cur) => ({
        characters: cur.characters.map((c) => (c.id === nera.id
          ? { ...c, psychology: { ...c.psychology, presentCost: "A crew that never grows up." } }
          : c)),
      }));
      const repatched = patched.characters.find((c) => c.id === nera.id);
      expect(repatched.psychology.presentCost).toBe("A crew that never grows up.");
      expect(repatched.psychology.theoryOfControl).toBe(fullProfile().theoryOfControl);
      expect(repatched.psychology.drives.status.fear).toBe("being read as surplus");
    });

    it("preserves an existing Lie verbatim when a psychology profile is added", async () => {
      const lie = "I only matter if I win.";
      const w = await svc.createUniverse({
        name: "Example Universe",
        characters: [{ name: "Nera Vost", lie, want: "the salvage contract", need: "to be kept anyway" }],
      });
      const [character] = w.characters;
      const patched = await svc.updateUniverse(w.id, (cur) => ({
        characters: cur.characters.map((c) => (c.id === character.id ? { ...c, psychology: fullProfile() } : c)),
      }));
      const next = patched.characters.find((c) => c.id === character.id);
      // The Lie is a judgment ABOUT a belief and the theory of control is the
      // operating rule — related, never the same statement, never overwritten.
      expect(next.lie).toBe(lie);
      expect(next.want).toBe("the salvage contract");
      expect(next.need).toBe("to be kept anyway");
      expect(next.psychology.theoryOfControl).toBe(fullProfile().theoryOfControl);
      expect(next.psychology.theoryOfControl).not.toBe(lie);
    });

    it("a PATCH that omits nested leaves clears only what it omitted — the caller sends the whole object", async () => {
      // The universe canon PATCH is a whole-list write, so a nested field is
      // replaced by the object the caller sends. That is exactly why the editor
      // spreads the persisted profile before committing; assert the contract so
      // a future caller that forgets is caught by a failing test, not by data
      // loss on a writer's machine.
      const w = await svc.createUniverse({
        name: "Example Universe",
        characters: [{ name: "Nera Vost", psychology: fullProfile() }],
      });
      const [character] = w.characters;
      const patched = await svc.updateUniverse(w.id, (cur) => ({
        characters: cur.characters.map((c) => (c.id === character.id
          ? { ...c, psychology: { theoryOfControl: "Only the work is safe." } }
          : c)),
      }));
      const next = patched.characters.find((c) => c.id === character.id);
      expect(next.psychology.theoryOfControl).toBe("Only the work is safe.");
      expect(next.psychology.strategy).toBe("");
      expect(next.psychology.drives.survival).toEqual({ desire: "", fear: "" });
    });

    it("clears the profile on an explicit null and on an all-blank object", async () => {
      const w = await svc.createUniverse({
        name: "Example Universe",
        characters: [
          { name: "Nera Vost", psychology: fullProfile() },
          { name: "Sole Ryn", psychology: fullProfile() },
        ],
      });
      const [nera, ryn] = w.characters;
      const patched = await svc.updateUniverse(w.id, (cur) => ({
        characters: cur.characters.map((c) => {
          if (c.id === nera.id) return { ...c, psychology: null };
          if (c.id === ryn.id) return { ...c, psychology: { theoryOfControl: "   ", drives: {} } };
          return c;
        }),
      }));
      for (const id of [nera.id, ryn.id]) {
        const next = patched.characters.find((c) => c.id === id);
        expect("psychology" in next).toBe(false);
      }
    });

    it("records an explicit unknown / not-applicable ruling, and drops an unrecognized one", async () => {
      const w = await svc.createUniverse({
        name: "Example Universe",
        characters: [
          {
            name: "The Choir",
            psychology: {
              assessment: "not-applicable",
              assessmentNote: "A distributed swarm with no single interior to read a control theory from.",
            },
          },
          { name: "Bad Enum", psychology: { assessment: "definitely", theoryOfControl: "keep moving" } },
        ],
      });
      const choir = w.characters.find((c) => c.name === "The Choir");
      const badEnum = w.characters.find((c) => c.name === "Bad Enum");
      expect(choir.psychology.assessment).toBe("not-applicable");
      expect(choir.psychology.assessmentNote).toMatch(/distributed swarm/);
      expect(choir.psychology.theoryOfControl).toBe("");
      // An unrecognized ruling collapses to null rather than persisting a token
      // no consumer knows how to read — the rest of the profile survives.
      expect(badEnum.psychology.assessment).toBeNull();
      expect(badEnum.psychology.theoryOfControl).toBe("keep moving");
    });

    it("bounds every leaf and refuses a malformed nested shape", async () => {
      const w = await svc.createUniverse({
        name: "Example Universe",
        characters: [{
          name: "Nera Vost",
          psychology: {
            theoryOfControl: "x".repeat(BIBLE_LIMITS.THEORY_OF_CONTROL_MAX + 500),
            strategy: 42,
            drives: [{ desire: "not an object map" }],
          },
        }],
      });
      const [character] = w.characters;
      expect(character.psychology.theoryOfControl).toHaveLength(BIBLE_LIMITS.THEORY_OF_CONTROL_MAX);
      expect(character.psychology.strategy).toBe("");
      // A non-object `drives` still materializes the three empty axes rather
      // than persisting an array a reader would index by number.
      expect(Object.keys(character.psychology.drives)).toEqual(["survival", "connection", "status"]);
      expect(character.psychology.drives.connection).toEqual({ desire: "", fear: "" });
    });
  });
});