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

78.3 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { mkdtempSync, rmSync, existsSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { makePathsProxy } from './mockPathsDataRoot.js';

let tempRoot;

// Mock PATHS.data so the factory writes into a temp dir per test. `tempRoot`
// is a `let` that beforeEach reassigns — the function form of dataRoot makes
// the Proxy re-read it on every PATHS access so each test sees its own dir.
vi.mock('./fileUtils.js', async () => {
  const actual = await vi.importActual('./fileUtils.js');
  return makePathsProxy(actual, { dataRoot: () => tempRoot });
});

const storyBible = await import('./storyBible.js');
const { createBibleStore } = await import('../services/bibleStore.js');
const {
  sanitizeCharacter,
  sanitizePlace,
  sanitizeObject,
  sanitizeBibleList,
  mergeExtractedBible,
  normalizeBibleName,
  normalizeSlugline,
  findBibleEntryByName,
  BIBLE_LIMITS,
  BIBLE_KIND,
  pruneStaleReferenceSheets,
  mergePreservedSheetPointers,
  stripCanonControlFields,
  CANON_CONTROL_FIELDS,
  SERVER_OWNED_CHARACTER_FIELDS,
  filterCanonForIssue,
  filterCanonListForIssue,
  isCanonEntryGatedForIssue,
  canonHasRevealGated,
  revealGatedCanonRows,
  characterIdentityPackReadiness,
  preserveLegacyCharacterFields,
} = storyBible;

const WORK_ID = 'wr-work-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';

describe('storyBible — sanitizeCharacter', () => {
  it('returns null when name is blank or input is not an object', () => {
    expect(sanitizeCharacter(null)).toBeNull();
    expect(sanitizeCharacter('string')).toBeNull();
    expect(sanitizeCharacter({ name: '' })).toBeNull();
    expect(sanitizeCharacter({ name: '   ' })).toBeNull();
  });

  it('lifts the legacy `description` alias into `physicalDescription` on read', () => {
    const out = sanitizeCharacter({ name: 'Aria', description: 'tall, dark hair' });
    expect(out.physicalDescription).toBe('tall, dark hair');
    expect(out).not.toHaveProperty('description');
  });

  it('prefers `physicalDescription` when both fields are present', () => {
    const out = sanitizeCharacter({ name: 'Aria', description: 'old', physicalDescription: 'new' });
    expect(out.physicalDescription).toBe('new');
  });

  it('preserves writers-room-shape rich fields', () => {
    const out = sanitizeCharacter({
      name: 'Marcus',
      aliases: ['Marc', 'Big M'],
      role: 'antagonist',
      physicalDescription: 'broad shoulders, scar',
      personality: 'taciturn',
      background: 'ex-military',
      notes: 'do not kill',
      evidence: ['ch1: enters bar'],
      missingFromProse: ['ever named'],
      firstAppearance: 'seg-003',
      source: 'ai',
    });
    expect(out.role).toBe('antagonist');
    expect(out.aliases).toEqual(['Marc', 'Big M']);
    expect(out.evidence).toEqual(['ch1: enters bar']);
    expect(out.firstAppearance).toBe('seg-003');
    expect(out.source).toBe('ai');
  });

  it('caps long fields and array sizes', () => {
    const long = 'x'.repeat(BIBLE_LIMITS.PHYSICAL_DESCRIPTION_MAX + 100);
    const tooMany = Array.from({ length: 30 }, (_, i) => `alias${i}`);
    const out = sanitizeCharacter({ name: 'A', physicalDescription: long, aliases: tooMany });
    expect(out.physicalDescription.length).toBe(BIBLE_LIMITS.PHYSICAL_DESCRIPTION_MAX);
    expect(out.aliases.length).toBe(BIBLE_LIMITS.ALIASES_PER_ENTRY_MAX);
  });

  it('generates an id with the requested prefix when missing, preserves explicit id', () => {
    const generated = sanitizeCharacter({ name: 'A' }, { idPrefix: 'chr-' });
    expect(generated.id).toMatch(/^chr-/);
    const preserved = sanitizeCharacter({ id: 'wr-char-existing', name: 'A' });
    expect(preserved.id).toBe('wr-char-existing');
  });

  // Character framework (CWQE Phase 10, #2175). All fields optional — a
  // pre-#2175 record has no framework keys, so the sanitizer must produce the
  // empty/legacy shape (absent vs empty rule) and a populated record must round
  // trip verbatim.
  describe('character framework (Ghost→Wound→Lie→Want→Need + arc type + sliders + secrets)', () => {
    it('produces the empty/legacy shape when the fields are absent', () => {
      const out = sanitizeCharacter({ name: 'Legacy' });
      expect(out.ghost).toBe('');
      expect(out.wound).toBe('');
      expect(out.lie).toBe('');
      expect(out.want).toBe('');
      expect(out.need).toBe('');
      expect(out.arcType).toBeNull();
      expect(out.sliders).toEqual({ proactivity: null, likability: null, competence: null });
      expect(out.secrets).toEqual([]);
    });

    it('round-trips a fully-authored framework', () => {
      const authored = {
        name: 'Vale',
        ghost: 'Watched her mentor die for a cause she now doubts.',
        wound: 'She cannot trust a cause bigger than herself.',
        lie: 'I only matter if I stay in control.',
        need: 'I matter whether or not I am in control.',
        want: 'To seize command of the resistance.',
        arcType: 'positive',
        sliders: { proactivity: 9, likability: 4, competence: 8 },
        secrets: ['She forged the founding charter.', 'She still writes to the dead mentor.'],
      };
      const out = sanitizeCharacter(authored);
      expect(out.ghost).toBe(authored.ghost);
      expect(out.wound).toBe(authored.wound);
      expect(out.lie).toBe(authored.lie);
      expect(out.need).toBe(authored.need);
      expect(out.want).toBe(authored.want);
      expect(out.arcType).toBe('positive');
      expect(out.sliders).toEqual({ proactivity: 9, likability: 4, competence: 8 });
      expect(out.secrets).toEqual(authored.secrets);
      // Re-sanitizing the output is stable (no drift on the second pass).
      expect(sanitizeCharacter(out)).toMatchObject({
        ghost: authored.ghost, lie: authored.lie, arcType: 'positive',
        sliders: { proactivity: 9, likability: 4, competence: 8 },
      });
    });

    it('collapses an unknown arc type and out-of-range / non-integer sliders to unset', () => {
      const out = sanitizeCharacter({
        name: 'X',
        arcType: 'redemption', // not one of positive/negative/flat
        sliders: { proactivity: 11, likability: 0, competence: 5.5 },
      });
      expect(out.arcType).toBeNull();
      // 11 > max, 0 < min, 5.5 non-integer — all collapse to null (unset).
      expect(out.sliders).toEqual({ proactivity: null, likability: null, competence: null });
    });

    it('accepts a numeric-string slider and normalizes it to an integer', () => {
      const out = sanitizeCharacter({ name: 'X', sliders: { proactivity: '7', likability: '', competence: 'nope' } });
      expect(out.sliders).toEqual({ proactivity: 7, likability: null, competence: null });
    });

    it('caps framework prose fields and the secrets list', () => {
      const long = 'g'.repeat(BIBLE_LIMITS.LIE_MAX + 100);
      const tooMany = Array.from({ length: BIBLE_LIMITS.SECRETS_PER_CHARACTER_MAX + 5 }, (_, i) => `secret ${i}`);
      const out = sanitizeCharacter({ name: 'X', lie: long, secrets: tooMany });
      expect(out.lie.length).toBe(BIBLE_LIMITS.LIE_MAX);
      expect(out.secrets.length).toBe(BIBLE_LIMITS.SECRETS_PER_CHARACTER_MAX);
    });
  });

  it('coerces invalid source to `user`', () => {
    expect(sanitizeCharacter({ name: 'A', source: 'evil' }).source).toBe('user');
  });

  it('drops empty / non-string aliases', () => {
    const out = sanitizeCharacter({ name: 'A', aliases: ['', '  ', null, 42, 'real'] });
    expect(out.aliases).toEqual(['real']);
  });

  // ---- Universe-as-Canon extras: prompt / tags / locked / source / sourceSeriesId ----

  it('accepts Universe-as-Canon extras: prompt + tags + sourceSeriesId', () => {
    const out = sanitizeCharacter({
      name: 'Alex',
      prompt: 'field lead detective, expressive face, short jacket',
      tags: ['protagonist', 'detective'],
      sourceSeriesId: 'ser-1234',
    });
    expect(out.prompt).toBe('field lead detective, expressive face, short jacket');
    expect(out.tags).toEqual(['protagonist', 'detective']);
    expect(out.sourceSeriesId).toBe('ser-1234');
  });

  it('persists locked: true and accepts the new source vocabulary', () => {
    const out = sanitizeCharacter({ name: 'Alex', locked: true, source: 'series-extract' });
    expect(out.locked).toBe(true);
    expect(out.source).toBe('series-extract');
  });

  it('preserves explicit true/false on locked and omits other shapes', () => {
    // applyCanonExtras now persists explicit `locked: false` so the
    // universe-builder lock-by-default contract can round-trip an unlock.
    // Anything else (truthy non-bool, missing) still collapses to absent so
    // writers-room callers that never set the flag stay on the legacy shape.
    expect(sanitizeCharacter({ name: 'A', locked: false }).locked).toBe(false);
    expect(sanitizeCharacter({ name: 'A', locked: 'yes' }).locked).toBeUndefined();
    expect(sanitizeCharacter({ name: 'A', locked: 1 }).locked).toBeUndefined();
    expect(sanitizeCharacter({ name: 'A' }).locked).toBeUndefined();
  });

  it('round-trips ingredientId through applyCanonExtras (set / unset / over-cap / non-string)', () => {
    // The catalog backfill stamps the catalog row id back onto the embedded
    // canon entry; the sanitizer must preserve a valid string, trim to cap,
    // and drop non-string / missing.
    const set = sanitizeCharacter({ name: 'A', ingredientId: 'cat-chr-bible-abcd1234' });
    expect(set.ingredientId).toBe('cat-chr-bible-abcd1234');

    const unset = sanitizeCharacter({ name: 'A' });
    expect(unset.ingredientId).toBeNull();

    const long = 'cat-chr-bible-' + 'a'.repeat(BIBLE_LIMITS.INGREDIENT_ID_MAX + 32);
    const trimmed = sanitizeCharacter({ name: 'A', ingredientId: long });
    expect(trimmed.ingredientId.length).toBe(BIBLE_LIMITS.INGREDIENT_ID_MAX);

    // Non-string falls back to null — the sanitizer treats anything outside
    // the contract as "no value" rather than coercing.
    expect(sanitizeCharacter({ name: 'A', ingredientId: 12345 }).ingredientId).toBeNull();
    expect(sanitizeCharacter({ name: 'A', ingredientId: { id: 'x' } }).ingredientId).toBeNull();

    // Symmetry: places + objects carry the same field through the same helper.
    expect(sanitizePlace({ name: 'P', ingredientId: 'cat-plc-bible-feed' }).ingredientId)
      .toBe('cat-plc-bible-feed');
  });

  it('caps tags + prompt + sourceSeriesId at their limits', () => {
    const longPrompt = 'p'.repeat(BIBLE_LIMITS.PROMPT_MAX + 50);
    const tooManyTags = Array.from({ length: BIBLE_LIMITS.TAGS_PER_ENTRY_MAX + 5 }, (_, i) => `tag-${i}`);
    const longSrc = 's'.repeat(BIBLE_LIMITS.SOURCE_SERIES_ID_MAX + 10);
    const out = sanitizeCharacter({
      name: 'A', prompt: longPrompt, tags: tooManyTags, sourceSeriesId: longSrc,
    });
    expect(out.prompt.length).toBe(BIBLE_LIMITS.PROMPT_MAX);
    expect(out.tags.length).toBe(BIBLE_LIMITS.TAGS_PER_ENTRY_MAX);
    expect(out.sourceSeriesId.length).toBe(BIBLE_LIMITS.SOURCE_SERIES_ID_MAX);
  });

  it('extras apply identically to settings + objects', () => {
    const s = sanitizePlace({ name: 'Bubble Room', tags: ['indoor'], prompt: 'pastel lab', locked: true });
    expect(s.tags).toEqual(['indoor']);
    expect(s.prompt).toBe('pastel lab');
    expect(s.locked).toBe(true);
    const o = sanitizeObject({ name: 'Ward Tape', tags: ['prop', 'recurring'], prompt: 'striped tape coil', source: 'manual' });
    expect(o.tags).toEqual(['prop', 'recurring']);
    expect(o.prompt).toBe('striped tape coil');
    expect(o.source).toBe('manual');
  });

  describe('primaryImageRef (Cluster A)', () => {
    it('returns null when not set', () => {
      const out = sanitizeCharacter({ name: 'A', imageRefs: ['a.png'] });
      expect(out.primaryImageRef).toBeNull();
    });

    it('persists a valid pointer that matches one of imageRefs[]', () => {
      const out = sanitizeCharacter({
        name: 'A',
        imageRefs: ['a.png', 'b.png'],
        primaryImageRef: 'b.png',
      });
      expect(out.primaryImageRef).toBe('b.png');
    });

    it('auto-clears a stale pointer when the target was removed from imageRefs[]', () => {
      const out = sanitizeCharacter({
        name: 'A',
        imageRefs: ['a.png'],
        primaryImageRef: 'ghost.png',
      });
      expect(out.primaryImageRef).toBeNull();
    });

    it('rejects non-string pointers without throwing', () => {
      const out = sanitizeCharacter({ name: 'A', imageRefs: ['a.png'], primaryImageRef: 123 });
      expect(out.primaryImageRef).toBeNull();
    });

    it('applies identically to settings and objects', () => {
      const s = sanitizePlace({
        name: 'Bar',
        imageRefs: ['plate.png'],
        primaryImageRef: 'plate.png',
      });
      expect(s.primaryImageRef).toBe('plate.png');
      const o = sanitizeObject({
        name: 'Watch',
        imageRefs: ['watch1.png', 'watch2.png'],
        primaryImageRef: 'watch2.png',
      });
      expect(o.primaryImageRef).toBe('watch2.png');
    });
  });

  describe('portable production package (#5378)', () => {
    it('keeps voice canon bounded and strips local artifact pointers', () => {
      const out = sanitizeCharacter({
        name: 'A',
        voiceCanon: {
          version: 2,
          description: 'warm low alto',
          defaultDelivery: 'measured',
          emotionalRange: ['guarded', 'wry'],
          avoid: ['announcer projection'],
          pronunciations: [{ term: 'Aster Vale', pronunciation: 'AS-ter vayl', profileId: 'local-only' }],
          sourcePolicy: 'designed',
          approved: true,
          providerId: 'not-portable',
          artifactPath: '/machine-local/voice.wav',
        },
      });
      expect(out.voiceCanon).toEqual({
        version: 2,
        description: 'warm low alto',
        defaultDelivery: 'measured',
        emotionalRange: ['guarded', 'wry'],
        avoid: ['announcer projection'],
        pronunciations: [{ term: 'Aster Vale', pronunciation: 'AS-ter vayl' }],
        sourcePolicy: 'designed',
        approved: true,
      });
      expect(out.voiceCanon).not.toHaveProperty('providerId');
      expect(out.voiceCanon).not.toHaveProperty('artifactPath');
    });

    it('keeps identity assets as unapproved candidates until explicit approval', () => {
      const out = sanitizeCharacter({
        name: 'A', imageRefs: ['neutral.png', 'profile.png', 'body.png'],
        identityPack: {
          assets: [
            { role: 'neutral', imageRef: 'neutral.png' },
            { role: 'profile', imageRef: 'profile.png', approved: true },
            { role: 'full-body', imageRef: 'body.png', approved: true },
            { role: 'neutral', imageRef: '/local/escape.png', approved: true },
          ],
          avoid: ['different eye color'],
        },
      });
      expect(out.identityPack).toEqual({
        assets: [
          { role: 'neutral', imageRef: 'neutral.png', approved: false },
          { role: 'profile', imageRef: 'profile.png', approved: true },
          { role: 'full-body', imageRef: 'body.png', approved: true },
        ],
        avoid: ['different eye color'],
      });
      expect(characterIdentityPackReadiness(out)).toMatchObject({
        status: 'missing', missing: ['neutral'], ambiguous: [],
      });
    });

    it('reports ready, missing, and ambiguous required identity roles', () => {
      const ready = { identityPack: { assets: [
        { role: 'neutral', imageRef: 'n.png', approved: true },
        { role: 'profile', imageRef: 'p.png', approved: true },
        { role: 'full-body', imageRef: 'b.png', approved: true },
      ] } };
      expect(characterIdentityPackReadiness(ready)).toMatchObject({ status: 'ready', missing: [], ambiguous: [] });
      const ambiguous = { identityPack: { assets: [
        ...ready.identityPack.assets,
        { role: 'profile', imageRef: 'p2.png', approved: true },
      ] } };
      expect(characterIdentityPackReadiness(ambiguous)).toMatchObject({ status: 'ambiguous', ambiguous: ['profile'] });
    });

    it('preserves packages from a pre-v10 peer but honors a v10 clear', () => {
      const local = [{
        id: 'chr-1', name: 'A',
        voiceCanon: { version: 2, approved: true },
        identityPack: { assets: [{ role: 'neutral', imageRef: 'n.png', approved: true }] },
      }];
      const remote = [{ id: 'chr-1', name: 'A from peer' }];
      expect(preserveLegacyCharacterFields(remote, local, 9)[0]).toMatchObject({
        name: 'A from peer',
        voiceCanon: local[0].voiceCanon,
        identityPack: local[0].identityPack,
      });
      expect(preserveLegacyCharacterFields(remote, local, 10)).toEqual(remote);
    });
  });

  describe('psychology profile (#6414)', () => {
    it('preserves a profile from a pre-v11 peer but honors a v11 clear', () => {
      const local = [{
        id: 'chr-1', name: 'A',
        psychology: { theoryOfControl: 'If I stay useful, nobody leaves.' },
      }];
      const remote = [{ id: 'chr-1', name: 'A from peer' }];
      // A peer whose sanitizer has no psychology slot omitted it because it
      // COULD NOT carry it — restoring is what stops its LWW write from
      // deleting a profile it never saw.
      expect(preserveLegacyCharacterFields(remote, local, 10)[0]).toMatchObject({
        name: 'A from peer',
        psychology: local[0].psychology,
      });
      // A v11-aware peer omitting it means the author cleared it.
      expect(preserveLegacyCharacterFields(remote, local, 11)).toEqual(remote);
    });

    it('restores ONLY the fields the sender could not represent', () => {
      const local = [{
        id: 'chr-1', name: 'A',
        voiceCanon: { version: 2, approved: true },
        psychology: { theoryOfControl: 'Only the work is safe.' },
      }];
      // A v10 sender understands voiceCanon (so its omission is a clear) but
      // not psychology (so its omission is a gap).
      const restored = preserveLegacyCharacterFields([{ id: 'chr-1', name: 'A' }], local, 10)[0];
      expect(restored.voiceCanon).toBeUndefined();
      expect(restored.psychology).toEqual(local[0].psychology);
    });
  });

  describe('wardrobes (Cluster A)', () => {
    it('defaults to an empty array when omitted', () => {
      const out = sanitizeCharacter({ name: 'A' });
      expect(out.wardrobes).toEqual([]);
    });

    it('sanitizes well-formed wardrobe entries + assigns ids', () => {
      const out = sanitizeCharacter({
        name: 'Don Carlos',
        wardrobes: [
          { name: 'Wedding', description: 'cream silk suit, gold pocket watch' },
          { name: 'Backalley', description: 'worn leather jacket, scuffed boots' },
        ],
      });
      expect(out.wardrobes).toHaveLength(2);
      expect(out.wardrobes[0].name).toBe('Wedding');
      expect(out.wardrobes[0].description).toBe('cream silk suit, gold pocket watch');
      expect(out.wardrobes[0].id).toMatch(/^wd-/);
      expect(out.wardrobes[0].id).not.toBe(out.wardrobes[1].id);
    });

    it('preserves caller-supplied ids (round-trip after a PATCH)', () => {
      const out = sanitizeCharacter({
        name: 'Aria',
        wardrobes: [{ id: 'wd-fixed-1', name: 'Tactical' }],
      });
      expect(out.wardrobes[0].id).toBe('wd-fixed-1');
    });

    it('drops entries with no name (the only required field)', () => {
      const out = sanitizeCharacter({
        name: 'Aria',
        wardrobes: [
          { description: 'no name on this one' },
          { name: 'Real Wardrobe', description: 'has a name' },
        ],
      });
      expect(out.wardrobes).toHaveLength(1);
      expect(out.wardrobes[0].name).toBe('Real Wardrobe');
    });

    it('caps the list at BIBLE_LIMITS.WARDROBES_PER_CHARACTER_MAX', () => {
      const tooMany = Array.from({ length: BIBLE_LIMITS.WARDROBES_PER_CHARACTER_MAX + 5 }, (_, i) => ({
        name: `Outfit ${i}`,
      }));
      const out = sanitizeCharacter({ name: 'A', wardrobes: tooMany });
      expect(out.wardrobes).toHaveLength(BIBLE_LIMITS.WARDROBES_PER_CHARACTER_MAX);
    });

    it('caps individual field lengths', () => {
      const out = sanitizeCharacter({
        name: 'A',
        wardrobes: [{
          name: 'n'.repeat(BIBLE_LIMITS.WARDROBE_NAME_MAX + 100),
          description: 'd'.repeat(BIBLE_LIMITS.WARDROBE_DESCRIPTION_MAX + 100),
        }],
      });
      expect(out.wardrobes[0].name.length).toBe(BIBLE_LIMITS.WARDROBE_NAME_MAX);
      expect(out.wardrobes[0].description.length).toBe(BIBLE_LIMITS.WARDROBE_DESCRIPTION_MAX);
    });

    it('coerces a non-array wardrobes field to an empty array', () => {
      const out = sanitizeCharacter({ name: 'A', wardrobes: 'not an array' });
      expect(out.wardrobes).toEqual([]);
    });
  });

  describe('relationshipLinks (#1287)', () => {
    it('defaults a missing relationshipLinks field to an empty array (legacy shape)', () => {
      expect(sanitizeCharacter({ name: 'A' }).relationshipLinks).toEqual([]);
    });

    it('coerces a non-array relationshipLinks field to an empty array', () => {
      expect(sanitizeCharacter({ name: 'A', relationshipLinks: 'nope' }).relationshipLinks).toEqual([]);
    });

    it('sanitizes a well-formed link + mints a rel- id when none supplied', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{ targetCharacterId: 'chr-bob', type: 'ally', description: 'old friends' }],
      });
      expect(out.relationshipLinks).toHaveLength(1);
      expect(out.relationshipLinks[0].id).toMatch(/^rel-/);
      expect(out.relationshipLinks[0].targetCharacterId).toBe('chr-bob');
      expect(out.relationshipLinks[0].type).toBe('ally');
      expect(out.relationshipLinks[0].description).toBe('old friends');
      expect(out.relationshipLinks[0].opposition).toBeUndefined();
    });

    it('preserves a supplied link id', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{ id: 'rel-fixed-1', targetCharacterId: 'chr-bob' }],
      });
      expect(out.relationshipLinks[0].id).toBe('rel-fixed-1');
    });

    it('drops a link with no targetCharacterId', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{ type: 'ally', description: 'dangling' }, { targetCharacterId: 'chr-bob' }],
      });
      expect(out.relationshipLinks).toHaveLength(1);
      expect(out.relationshipLinks[0].targetCharacterId).toBe('chr-bob');
    });

    it('coerces an unrecognized type to custom (keeps the link + its prose)', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{ targetCharacterId: 'chr-bob', type: 'frenemy', description: 'complicated' }],
      });
      expect(out.relationshipLinks[0].type).toBe('custom');
      expect(out.relationshipLinks[0].description).toBe('complicated');
    });

    it('defaults a missing type to custom', () => {
      const out = sanitizeCharacter({ name: 'A', relationshipLinks: [{ targetCharacterId: 'chr-bob' }] });
      expect(out.relationshipLinks[0].type).toBe('custom');
    });

    it('sanitizes opposition + coerces an unrecognized axis to custom', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{
          targetCharacterId: 'chr-bob',
          type: 'antagonist',
          opposition: { axis: 'cat/mouse', thisRole: 'hunter', targetRole: 'prey', note: 'will it flip?' },
        }],
      });
      const opp = out.relationshipLinks[0].opposition;
      expect(opp.axis).toBe('custom');
      expect(opp.thisRole).toBe('hunter');
      expect(opp.targetRole).toBe('prey');
      expect(opp.note).toBe('will it flip?');
    });

    it('keeps a recognized opposition axis verbatim', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{ targetCharacterId: 'chr-bob', opposition: { axis: 'hunter/prey' } }],
      });
      expect(out.relationshipLinks[0].opposition.axis).toBe('hunter/prey');
    });

    it('drops an opposition with no axis (collapses to absent)', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{ targetCharacterId: 'chr-bob', opposition: { thisRole: 'hunter' } }],
      });
      expect(out.relationshipLinks[0].opposition).toBeUndefined();
    });

    it('persists explicit locked true/false but drops a non-boolean', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [
          { targetCharacterId: 'b', locked: true },
          { targetCharacterId: 'c', locked: false },
          { targetCharacterId: 'd', locked: 'yes' },
        ],
      });
      expect(out.relationshipLinks[0].locked).toBe(true);
      expect(out.relationshipLinks[1].locked).toBe(false);
      expect(out.relationshipLinks[2].locked).toBeUndefined();
    });

    it('caps the list at RELATIONSHIP_LINKS_PER_CHARACTER_MAX', () => {
      const tooMany = Array.from(
        { length: BIBLE_LIMITS.RELATIONSHIP_LINKS_PER_CHARACTER_MAX + 5 },
        (_, i) => ({ targetCharacterId: `chr-${i}` }),
      );
      const out = sanitizeCharacter({ name: 'A', relationshipLinks: tooMany });
      expect(out.relationshipLinks).toHaveLength(BIBLE_LIMITS.RELATIONSHIP_LINKS_PER_CHARACTER_MAX);
    });

    it('clamps over-long description + opposition fields', () => {
      const out = sanitizeCharacter({
        name: 'A',
        relationshipLinks: [{
          targetCharacterId: 'chr-bob',
          description: 'x'.repeat(BIBLE_LIMITS.RELATIONSHIP_DESCRIPTION_MAX + 50),
          opposition: { axis: 'hunter/prey', note: 'y'.repeat(BIBLE_LIMITS.RELATIONSHIP_OPPOSITION_NOTE_MAX + 50) },
        }],
      });
      expect(out.relationshipLinks[0].description.length).toBe(BIBLE_LIMITS.RELATIONSHIP_DESCRIPTION_MAX);
      expect(out.relationshipLinks[0].opposition.note.length).toBe(BIBLE_LIMITS.RELATIONSHIP_OPPOSITION_NOTE_MAX);
    });
  });

  describe('attachments (#1288)', () => {
    it('defaults a missing attachments field to an empty array (legacy shape)', () => {
      expect(sanitizeObject({ name: 'Watch' }).attachments).toEqual([]);
    });

    it('coerces a non-array attachments field to an empty array', () => {
      expect(sanitizeObject({ name: 'Watch', attachments: 'nope' }).attachments).toEqual([]);
    });

    it('sanitizes a complete attachment and mints an att- id', () => {
      const out = sanitizeObject({
        name: 'Watch',
        attachments: [{ characterId: 'chr-mara', emotion: 'grief', significance: 'her father\'s', origin: 'inherited', role: 'memento' }],
      });
      expect(out.attachments).toHaveLength(1);
      expect(out.attachments[0].id).toMatch(/^att-/);
      expect(out.attachments[0].characterId).toBe('chr-mara');
      expect(out.attachments[0].emotion).toBe('grief');
      expect(out.attachments[0].significance).toBe('her father\'s');
      expect(out.attachments[0].origin).toBe('inherited');
      expect(out.attachments[0].role).toBe('memento');
    });

    it('preserves a provided id verbatim', () => {
      const out = sanitizeObject({ name: 'Watch', attachments: [{ id: 'att-fixed-1', characterId: 'chr-mara' }] });
      expect(out.attachments[0].id).toBe('att-fixed-1');
    });

    it('drops an attachment with no characterId (meaningless link)', () => {
      const out = sanitizeObject({
        name: 'Watch',
        attachments: [{ emotion: 'grief' }, { characterId: 'chr-mara' }],
      });
      expect(out.attachments).toHaveLength(1);
      expect(out.attachments[0].characterId).toBe('chr-mara');
    });

    it('coerces an unrecognized role to custom (keeps prose intact)', () => {
      const out = sanitizeObject({
        name: 'Watch',
        attachments: [{ characterId: 'chr-mara', role: 'heirloom', significance: 'matters' }],
      });
      expect(out.attachments[0].role).toBe('custom');
      expect(out.attachments[0].significance).toBe('matters');
    });

    it('defaults a missing role to custom', () => {
      const out = sanitizeObject({ name: 'Watch', attachments: [{ characterId: 'chr-mara' }] });
      expect(out.attachments[0].role).toBe('custom');
    });

    it('persists explicit locked true/false but drops a non-boolean', () => {
      const out = sanitizeObject({
        name: 'Watch',
        attachments: [
          { characterId: 'a', locked: true },
          { characterId: 'b', locked: false },
          { characterId: 'c', locked: 'yes' },
        ],
      });
      expect(out.attachments[0].locked).toBe(true);
      expect(out.attachments[1].locked).toBe(false);
      expect(out.attachments[2].locked).toBeUndefined();
    });

    it('caps the list at ATTACHMENTS_PER_OBJECT_MAX', () => {
      const tooMany = Array.from(
        { length: BIBLE_LIMITS.ATTACHMENTS_PER_OBJECT_MAX + 5 },
        (_, i) => ({ characterId: `chr-${i}` }),
      );
      const out = sanitizeObject({ name: 'Watch', attachments: tooMany });
      expect(out.attachments).toHaveLength(BIBLE_LIMITS.ATTACHMENTS_PER_OBJECT_MAX);
    });

    it('clamps over-long prose fields', () => {
      const out = sanitizeObject({
        name: 'Watch',
        attachments: [{
          characterId: 'chr-mara',
          significance: 'x'.repeat(BIBLE_LIMITS.ATTACHMENT_SIGNIFICANCE_MAX + 50),
          origin: 'y'.repeat(BIBLE_LIMITS.ATTACHMENT_ORIGIN_MAX + 50),
          emotion: 'z'.repeat(BIBLE_LIMITS.ATTACHMENT_EMOTION_MAX + 50),
        }],
      });
      expect(out.attachments[0].significance.length).toBe(BIBLE_LIMITS.ATTACHMENT_SIGNIFICANCE_MAX);
      expect(out.attachments[0].origin.length).toBe(BIBLE_LIMITS.ATTACHMENT_ORIGIN_MAX);
      expect(out.attachments[0].emotion.length).toBe(BIBLE_LIMITS.ATTACHMENT_EMOTION_MAX);
    });
  });

  describe('extended character fields (novelist + graphic-novelist depth)', () => {
    it('defaults every new string field to empty + every list field to []', () => {
      const out = sanitizeCharacter({ name: 'Bare' });
      // String defaults
      expect(out.pronouns).toBe('');
      expect(out.age).toBe('');
      expect(out.coreTheme).toBe('');
      expect(out.speechAccent).toBe('');
      expect(out.speechPattern).toBe('');
      expect(out.visualNotes).toBe('');
      expect(out.silhouetteNotes).toBe('');
      expect(out.postureNotes).toBe('');
      expect(out.specialTraits).toBe('');
      expect(out.visualIdentity).toBe('');
      expect(out.motivations).toBe('');
      expect(out.likes).toBe('');
      expect(out.dislikes).toBe('');
      expect(out.mannerisms).toBe('');
      expect(out.relationships).toBe('');
      expect(out.skills).toBe('');
      // List defaults
      expect(out.stats).toEqual([]);
      expect(out.colorPalette).toEqual([]);
      expect(out.props).toEqual([]);
      expect(out.expressions).toEqual([]);
      expect(out.handGestures).toEqual([]);
      // Operational
      expect(out.referenceSheetImageRef).toBeNull();
    });

    it('round-trips a fully-populated character', () => {
      const out = sanitizeCharacter({
        name: 'Vale',
        pronouns: 'she/her',
        age: '27',
        coreTheme: 'cartographer of grief',
        speechAccent: 'clipped Edinburgh',
        speechPattern: 'rarely contracts; nautical metaphors; ends statements as questions',
        visualNotes: 'layered streetwear',
        silhouetteNotes: 'compact upper body',
        postureNotes: 'slight forward lean',
        specialTraits: 'quick hands, restless energy',
        visualIdentity: 'urban utilitarian; analog tech feel',
        motivations: 'finish the map; protect her sister',
        likes: 'thunderstorms, fresh ink',
        dislikes: 'small talk, fluorescent light',
        mannerisms: 'touches the back of her neck when lying',
        relationships: 'estranged from her father; ride-or-die with Park',
        skills: 'conversational Mandarin, sleight-of-hand',
      });
      expect(out.pronouns).toBe('she/her');
      expect(out.age).toBe('27');
      expect(out.coreTheme).toBe('cartographer of grief');
      expect(out.skills).toBe('conversational Mandarin, sleight-of-hand');
      expect(out.speechPattern).toBe('rarely contracts; nautical metaphors; ends statements as questions');
    });

    it('caps every new string field at its BIBLE_LIMITS bound', () => {
      const longs = {
        pronouns: 'p'.repeat(BIBLE_LIMITS.PRONOUNS_MAX + 5),
        age: 'a'.repeat(BIBLE_LIMITS.AGE_MAX + 5),
        coreTheme: 't'.repeat(BIBLE_LIMITS.CORE_THEME_MAX + 50),
        motivations: 'm'.repeat(BIBLE_LIMITS.MOTIVATIONS_MAX + 50),
        skills: 's'.repeat(BIBLE_LIMITS.SKILLS_MAX + 50),
      };
      const out = sanitizeCharacter({ name: 'A', ...longs });
      expect(out.pronouns.length).toBe(BIBLE_LIMITS.PRONOUNS_MAX);
      expect(out.age.length).toBe(BIBLE_LIMITS.AGE_MAX);
      expect(out.coreTheme.length).toBe(BIBLE_LIMITS.CORE_THEME_MAX);
      expect(out.motivations.length).toBe(BIBLE_LIMITS.MOTIVATIONS_MAX);
      expect(out.skills.length).toBe(BIBLE_LIMITS.SKILLS_MAX);
    });

    it('keeps the open key/value stats list (non-human characters supported)', () => {
      const out = sanitizeCharacter({
        name: 'The Reach',
        stats: [
          { label: 'Form', value: 'translucent vapor' },
          { label: 'Eyes', value: 'none (echolocates)' },
          { label: 'Limbs', value: '6 segmented' },
        ],
      });
      expect(out.stats).toHaveLength(3);
      expect(out.stats[0]).toMatchObject({ label: 'Form', value: 'translucent vapor' });
      expect(out.stats[0].id).toMatch(/^stat-/);
      expect(out.stats[2].label).toBe('Limbs');
    });

    it('stats round-trip caller-supplied id and assign UUIDs to fresh rows', () => {
      const out = sanitizeCharacter({
        name: 'A',
        stats: [
          { label: 'Form', value: 'vapor' },
          { id: 'stat-fixed-1', label: 'Limbs', value: '6' },
        ],
      });
      expect(out.stats[0].id).toMatch(/^stat-/);
      expect(out.stats[1].id).toBe('stat-fixed-1');
    });

    it('drops stats entries missing a label, caps overall list', () => {
      const tooMany = Array.from({ length: BIBLE_LIMITS.STATS_PER_CHARACTER_MAX + 5 }, (_, i) => ({ label: `s${i}`, value: 'v' }));
      const out = sanitizeCharacter({
        name: 'A',
        stats: [
          { value: 'no label' },
          ...tooMany,
        ],
      });
      // Nameless entry dropped; list capped at the limit.
      expect(out.stats).toHaveLength(BIBLE_LIMITS.STATS_PER_CHARACTER_MAX);
      expect(out.stats[0]).toMatchObject({ label: 's0', value: 'v' });
    });

    it('color palette accepts hex + role; drops nameless rows', () => {
      const out = sanitizeCharacter({
        name: 'A',
        colorPalette: [
          { name: 'amber', hex: '#f59e0b', role: 'skin' },
          { name: 'olive', hex: '', role: '' },
          { role: 'no name' },
        ],
      });
      expect(out.colorPalette).toHaveLength(2);
      expect(out.colorPalette[0]).toMatchObject({ name: 'amber', hex: '#f59e0b', role: 'skin' });
      expect(out.colorPalette[0].id).toMatch(/^color-/);
      expect(out.colorPalette[1]).toMatchObject({ name: 'olive', hex: '', role: '' });
    });

    it('props get a UUID id and round-trip caller-supplied ids', () => {
      const out = sanitizeCharacter({
        name: 'A',
        props: [
          { name: 'Radio', purpose: 'comms', materials: 'plastic + alloy' },
          { id: 'prop-fixed-1', name: 'Compass' },
        ],
      });
      expect(out.props).toHaveLength(2);
      expect(out.props[0].id).toMatch(/^prop-/);
      expect(out.props[1].id).toBe('prop-fixed-1');
      expect(out.props[0].purpose).toBe('comms');
    });

    it('expressions + handGestures drop rows without a name', () => {
      const out = sanitizeCharacter({
        name: 'A',
        expressions: [
          { name: 'neutral', description: 'baseline' },
          { description: 'no name' },
        ],
        handGestures: [
          { description: 'no name' },
          { name: 'pointing', description: 'index out' },
        ],
      });
      expect(out.expressions).toHaveLength(1);
      expect(out.expressions[0].name).toBe('neutral');
      expect(out.expressions[0].id).toMatch(/^expr-/);
      expect(out.handGestures).toHaveLength(1);
      expect(out.handGestures[0].name).toBe('pointing');
      expect(out.handGestures[0].id).toMatch(/^gesture-/);
    });

    it('referenceSheetImageRef accepts a filename and trims it', () => {
      const out = sanitizeCharacter({ name: 'A', referenceSheetImageRef: '  universe-abc-character-sheet.png  ' });
      expect(out.referenceSheetImageRef).toBe('universe-abc-character-sheet.png');
    });

    it('referenceSheetImageRef collapses to null for non-string / blank', () => {
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: '' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: '   ' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: 123 }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A' }).referenceSheetImageRef).toBeNull();
    });

    it('referenceSheets map keeps valid variant entries and basename-validates each filename', () => {
      const out = sanitizeCharacter({
        name: 'A',
        referenceSheetImageRef: 'std.png',
        referenceSheets: {
          blueprint: '  blueprint.png  ',
          noir: 'noir.png',
        },
      });
      expect(out.referenceSheetImageRef).toBe('std.png');
      expect(out.referenceSheets).toEqual({ blueprint: 'blueprint.png', noir: 'noir.png' });
    });

    it('referenceSheets defaults to an empty object when absent / non-object / null', () => {
      expect(sanitizeCharacter({ name: 'A' }).referenceSheets).toEqual({});
      expect(sanitizeCharacter({ name: 'A', referenceSheets: null }).referenceSheets).toEqual({});
      expect(sanitizeCharacter({ name: 'A', referenceSheets: 'string' }).referenceSheets).toEqual({});
      expect(sanitizeCharacter({ name: 'A', referenceSheets: [] }).referenceSheets).toEqual({});
    });

    it('referenceSheets drops invalid variant ids (path traversal, uppercase, dot prefix, "standard" sentinel)', () => {
      const out = sanitizeCharacter({
        name: 'A',
        referenceSheets: {
          blueprint: 'ok.png',
          // Invalid keys: traversal, uppercase, dot prefix, the reserved
          // 'standard' sentinel (kept on the legacy field), empty string.
          '../escape': 'attack.png',
          'BadCase': 'foo.png',
          '.hidden': 'foo.png',
          'standard': 'should-stay-in-legacy-field.png',
          '': 'foo.png',
        },
      });
      expect(out.referenceSheets).toEqual({ blueprint: 'ok.png' });
    });

    it('referenceSheets drops entries whose filename fails basename validation', () => {
      const out = sanitizeCharacter({
        name: 'A',
        referenceSheets: {
          blueprint: '../escape.png',
          noir: 'foo/bar.png',
          steampunk: 'ok.png',
        },
      });
      expect(out.referenceSheets).toEqual({ steampunk: 'ok.png' });
    });

    it('REGRESSION: referenceSheetImageRef rejects path separators + traversal', () => {
      // Defense-in-depth against an LLM-extracted payload that bypassed
      // stripCanonControlFields. The runtime route serves /data/image-refs/<x>
      // — a value with separators or dot-prefix would 404 OR escape the dir.
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: '../etc/passwd' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: 'foo/bar.png' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: 'foo\\bar.png' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: '.' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: '..' }).referenceSheetImageRef).toBeNull();
      expect(sanitizeCharacter({ name: 'A', referenceSheetImageRef: '.hidden.png' }).referenceSheetImageRef).toBeNull();
    });
  });
});

describe('storyBible — canon control + server-owned field invariants', () => {
  // These constants are the single source of truth for "fields the LLM /
  // client shouldn't be the writer of". `stripCanonControlFields` reads
  // CANON_CONTROL_FIELDS; `updateUniverse`'s PATCH-preservation guard
  // reads SERVER_OWNED_CHARACTER_FIELDS. Pin both so a new operational
  // field added to one constant without updating the other (or its
  // consumer) gets caught.

  it('stripCanonControlFields drops every CANON_CONTROL_FIELD on an entry', () => {
    const entry = {
      id: 'c-1', createdAt: 'x', updatedAt: 'y',
      locked: true, sourceSeriesId: 'sr-1',
      imageRefs: ['a.png'], primaryImageRef: 'a.png',
      referenceSheetImageRef: 'sheet.png',
      // Non-control field — must survive.
      name: 'Vale', personality: 'alert',
    };
    const stripped = stripCanonControlFields(entry);
    for (const f of CANON_CONTROL_FIELDS) {
      expect(stripped).not.toHaveProperty(f);
    }
    expect(stripped.name).toBe('Vale');
    expect(stripped.personality).toBe('alert');
  });

  it('SERVER_OWNED_CHARACTER_FIELDS is a subset of CANON_CONTROL_FIELDS', () => {
    // The PATCH-preservation guard reads server-owned fields; the
    // strip-from-LLM guard reads control fields. Server-owned MUST be a
    // strict subset — otherwise a new server-owned field could appear
    // in literal PATCH bodies that bypass `stripCanonControlFields`.
    const ctrl = new Set(CANON_CONTROL_FIELDS);
    for (const f of SERVER_OWNED_CHARACTER_FIELDS) {
      expect(ctrl.has(f)).toBe(true);
    }
  });

  it('SERVER_OWNED_CHARACTER_FIELDS lists exactly the render-completion-stamped pointers', () => {
    // Pin the current set so a new server-owned addition is a deliberate
    // change (update both this test AND the corresponding render flow).
    expect([...SERVER_OWNED_CHARACTER_FIELDS]).toEqual([
      'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',
    ]);
  });
});

describe('storyBible — pruneStaleReferenceSheets', () => {
  // Lives outside the sanitizeCharacter describe because it does FS I/O
  // (intentionally outside the sanitizer's pure contract). It collapses any
  // character.referenceSheetImageRef whose underlying file is missing from
  // PATHS.imageRefs — what the universe-builder GET route surfaces to the UI.

  it('returns the input unchanged when nothing is stale', () => {
    // No character has a pointer → nothing to check, returns the same array.
    const list = [{ name: 'A' }, { name: 'B', referenceSheetImageRef: null }];
    const out = pruneStaleReferenceSheets(list);
    expect(out).toBe(list);
  });

  it('nulls out pointers whose file does not exist (without persisting back)', () => {
    const list = [
      { name: 'A', referenceSheetImageRef: 'definitely-not-on-disk.png' },
      { name: 'B' },
    ];
    const out = pruneStaleReferenceSheets(list);
    expect(out).not.toBe(list); // new array on change
    expect(out[0].referenceSheetImageRef).toBeNull();
    // Untouched character pass-through (same reference).
    expect(out[1]).toBe(list[1]);
    expect(out).toHaveLength(2);
  });

  it('passes through a non-array input', () => {
    expect(pruneStaleReferenceSheets(null)).toBeNull();
    expect(pruneStaleReferenceSheets(undefined)).toBeUndefined();
    expect(pruneStaleReferenceSheets('not array')).toBe('not array');
  });

  it('drops stale variant keys from referenceSheets without disturbing the rest of the map', () => {
    // Two variants, one resolvable on disk one not — the gone one must be
    // dropped but the still-resolvable entry must stay. The legacy field is
    // untouched in this fixture.
    const list = [{
      name: 'A',
      referenceSheets: {
        blueprint: 'gone-blueprint.png',
        // Pruner takes whatever's not on disk; this test doesn't care which
        // entries survive — only that the map is pruned per-key, not wholesale.
        steampunk: 'also-gone.png',
      },
    }];
    const out = pruneStaleReferenceSheets(list);
    expect(out).not.toBe(list);
    expect(out[0].referenceSheets).toEqual({});
    expect(out[0].name).toBe('A');
  });

  it('mergePreservedSheetPointers preserves legacy + map pointers from prev when files still resolve', () => {
    // Inject a fake FS check so the test is hermetic.
    const onDisk = new Set(['live-std.png', 'live-bp.png']);
    const checkExists = (name) => onDisk.has(name);

    // patch carries a stale legacy filename AND no map; prev has both.
    const prev = {
      id: 'c-1', name: 'Vex',
      referenceSheetImageRef: 'live-std.png',
      referenceSheets: { blueprint: 'live-bp.png' },
    };
    const patchOmits = { id: 'c-1', name: 'Vex' };
    const merged1 = mergePreservedSheetPointers(prev, patchOmits, checkExists);
    expect(merged1.referenceSheetImageRef).toBe('live-std.png');
    expect(merged1.referenceSheets).toEqual({ blueprint: 'live-bp.png' });

    // Map merge: prev's blueprint wins over the patch's stale blueprint; the
    // patch's other variant ('noir') flows through.
    const patchStale = {
      id: 'c-1', name: 'Vex',
      referenceSheetImageRef: 'old-std.png',
      referenceSheets: { blueprint: 'old-bp.png', noir: 'patch-noir.png' },
    };
    const merged2 = mergePreservedSheetPointers(prev, patchStale, checkExists);
    expect(merged2.referenceSheetImageRef).toBe('live-std.png');
    expect(merged2.referenceSheets).toEqual({ blueprint: 'live-bp.png', noir: 'patch-noir.png' });
  });

  it('mergePreservedSheetPointers falls through to the patch when prev pointer no longer resolves', () => {
    // GET-route pruner returns null when the file is gone; client PATCH
    // carries that null back. Preservation MUST not re-introduce the stale
    // pointer from cur — otherwise the UI 404s on the next render.
    const onDisk = new Set(); // nothing resolves
    const checkExists = (name) => onDisk.has(name);
    const prev = {
      id: 'c-1', name: 'A',
      referenceSheetImageRef: 'dead-std.png',
      referenceSheets: { blueprint: 'dead-bp.png' },
    };
    const patch = {
      id: 'c-1', name: 'A',
      referenceSheetImageRef: null,
      referenceSheets: {},
    };
    const merged = mergePreservedSheetPointers(prev, patch, checkExists);
    expect(merged.referenceSheetImageRef).toBeNull();
    expect(merged.referenceSheets).toEqual({});
  });

  it('mergePreservedSheetPointers is a pass-through when prev or patchChar is missing', () => {
    const checkExists = () => true;
    expect(mergePreservedSheetPointers(null, { id: 'c-1' }, checkExists)).toEqual({ id: 'c-1' });
    expect(mergePreservedSheetPointers({ id: 'c-1' }, null, checkExists)).toBeNull();
  });

  it('prunes legacy + map pointers together without blowing away unrelated fields', () => {
    const list = [{
      id: 'c-1', name: 'A', personality: 'alert',
      referenceSheetImageRef: 'gone-std.png',
      referenceSheets: { blueprint: 'gone-bp.png' },
    }];
    const out = pruneStaleReferenceSheets(list);
    expect(out[0].referenceSheetImageRef).toBeNull();
    expect(out[0].referenceSheets).toEqual({});
    expect(out[0].name).toBe('A');
    expect(out[0].personality).toBe('alert');
  });

  it('leaves an absent / empty referenceSheets untouched', () => {
    const list = [
      { name: 'A' }, // no map at all
      { name: 'B', referenceSheets: {} }, // empty map
    ];
    const out = pruneStaleReferenceSheets(list);
    expect(out).toBe(list);
  });
});

describe('storyBible — sanitizePlace', () => {
  it('requires either name or slugline', () => {
    expect(sanitizePlace({ description: 'x' })).toBeNull();
    expect(sanitizePlace({ name: 'A bar' }).name).toBe('A bar');
    expect(sanitizePlace({ slugline: 'INT. BAR — NIGHT' }).slugline).toBe('INT. BAR — NIGHT');
  });

  it('preserves all fields and caps lengths', () => {
    const out = sanitizePlace({
      slugline: 'INT. BAR — NIGHT',
      name: 'The Foundry',
      description: 'cramped chrome bar',
      palette: 'amber, neon-red',
      era: '2049',
      weather: 'persistent rain outside',
      recurringDetails: 'broken jukebox',
      notes: 'returns in arc 2',
      evidence: ['ch1: opens here'],
    });
    expect(out.slugline).toBe('INT. BAR — NIGHT');
    expect(out.palette).toBe('amber, neon-red');
    expect(out.evidence).toEqual(['ch1: opens here']);
  });

  describe('intExt + timeOfDay (Cluster A)', () => {
    it('persists valid enums', () => {
      const out = sanitizePlace({ name: 'Bar', intExt: 'INT', timeOfDay: 'night' });
      expect(out.intExt).toBe('INT');
      expect(out.timeOfDay).toBe('night');
    });

    it('normalizes case on both fields', () => {
      const out = sanitizePlace({ name: 'Bar', intExt: 'ext', timeOfDay: 'DUSK' });
      expect(out.intExt).toBe('EXT');
      expect(out.timeOfDay).toBe('dusk');
    });

    it('drops invalid enum values to null instead of throwing', () => {
      const out = sanitizePlace({ name: 'Bar', intExt: 'underwater', timeOfDay: 'midnight-snack' });
      expect(out.intExt).toBeNull();
      expect(out.timeOfDay).toBeNull();
    });

    it('treats missing/empty as null (legacy settings)', () => {
      const out = sanitizePlace({ name: 'Bar' });
      expect(out.intExt).toBeNull();
      expect(out.timeOfDay).toBeNull();
    });
  });
});

describe('storyBible — sanitizeObject', () => {
  it('requires name', () => {
    expect(sanitizeObject({ description: 'x' })).toBeNull();
  });

  it('preserves significance + aliases', () => {
    const out = sanitizeObject({ name: 'The Locket', aliases: ['locket'], description: 'silver, dented', significance: 'mother\'s' });
    expect(out.name).toBe('The Locket');
    expect(out.significance).toBe("mother's");
    expect(out.aliases).toEqual(['locket']);
  });
});

describe('storyBible — sanitizeBibleList', () => {
  it('drops malformed entries and caps to ENTRIES_PER_BIBLE_MAX', () => {
    const list = [
      { name: 'A' },
      { name: '' },               // dropped (blank name)
      null,                       // dropped (non-object)
      { name: 'B', description: 'tall' },
      ...Array.from({ length: BIBLE_LIMITS.ENTRIES_PER_BIBLE_MAX + 50 }, (_, i) => ({ name: `pad-${i}` })),
    ];
    const out = sanitizeBibleList(list, 'character');
    expect(out.length).toBe(BIBLE_LIMITS.ENTRIES_PER_BIBLE_MAX);
    expect(out[0].name).toBe('A');
    expect(out[1].name).toBe('B');
  });

  it('returns [] for non-array input or unknown kind', () => {
    expect(sanitizeBibleList(null, 'character')).toEqual([]);
    expect(sanitizeBibleList([{ name: 'A' }], 'noSuchKind')).toEqual([]);
  });
});

describe('storyBible — mergeExtractedBible (characters)', () => {
  const baseExisting = () => [
    sanitizeCharacter({ id: 'c1', name: 'Aria', physicalDescription: 'tall, dark hair', source: 'user' }),
  ];

  it('fills only blank user-editable fields on an existing entry, keeping non-blank user content', () => {
    const existing = baseExisting();
    const incoming = [
      { name: 'Aria', physicalDescription: 'short, redhead', personality: 'guarded', background: 'ex-bartender' },
    ];
    const merged = mergeExtractedBible(existing, incoming, 'character');
    const aria = merged.find((c) => c.name === 'Aria');
    expect(aria.physicalDescription).toBe('tall, dark hair'); // user wins
    expect(aria.personality).toBe('guarded'); // was blank → filled
    expect(aria.background).toBe('ex-bartender');
  });

  it('inserts new characters with source=ai', () => {
    const merged = mergeExtractedBible(baseExisting(), [{ name: 'Marcus', physicalDescription: 'broad shoulders' }], 'character');
    const marcus = merged.find((c) => c.name === 'Marcus');
    expect(marcus.source).toBe('ai');
    expect(marcus.physicalDescription).toBe('broad shoulders');
  });

  it('matches by alias on the incoming side and dedupes within a batch', () => {
    const existing = [sanitizeCharacter({ id: 'c1', name: 'Aria Reyes', aliases: ['Aria', 'The Bartender'], physicalDescription: 'tall' })];
    const merged = mergeExtractedBible(existing, [
      { name: 'Aria', personality: 'guarded' }, // matches alias
      { name: 'the bartender', background: 'ex-marine' }, // also matches alias
    ], 'character');
    expect(merged.length).toBe(1);
    expect(merged[0].personality).toBe('guarded');
    expect(merged[0].background).toBe('ex-marine');
  });

  it('refreshes prose-derived fields verbatim, including null firstAppearance', () => {
    const existing = [sanitizeCharacter({ id: 'c1', name: 'Aria', physicalDescription: 'tall', firstAppearance: 'seg-001', evidence: ['old'], missingFromProse: ['old gap'] })];
    const merged = mergeExtractedBible(existing, [{ name: 'Aria', firstAppearance: null, evidence: ['new'], missingFromProse: [] }], 'character');
    expect(merged[0].firstAppearance).toBeNull();
    expect(merged[0].evidence).toEqual(['new']);
    expect(merged[0].missingFromProse).toEqual([]);
  });

  it('backfills aliases on an entry that previously had none, then reindexes', () => {
    const existing = [sanitizeCharacter({ id: 'c1', name: 'Aria', physicalDescription: 'tall' })];
    const merged = mergeExtractedBible(existing, [
      { name: 'Aria', aliases: ['Reyes'] },
      { name: 'Reyes', personality: 'sharp' }, // should resolve to Aria via the just-backfilled alias
    ], 'character');
    expect(merged.length).toBe(1);
    expect(merged[0].aliases).toEqual(['Reyes']);
    expect(merged[0].personality).toBe('sharp');
  });

  it('skips malformed incoming rows', () => {
    const merged = mergeExtractedBible([], [null, { /* no name */ }, { name: 'A' }], 'character');
    expect(merged.length).toBe(1);
    expect(merged[0].name).toBe('A');
  });

  it('refuses inserts past ENTRIES_PER_BIBLE_MAX so merged data does not silently truncate on next read', () => {
    const existing = Array.from({ length: BIBLE_LIMITS.ENTRIES_PER_BIBLE_MAX }, (_, i) => sanitizeCharacter({ name: `seed-${i}` }));
    const incoming = Array.from({ length: 5 }, (_, i) => ({ name: `new-${i}` }));
    const merged = mergeExtractedBible(existing, incoming, 'character');
    expect(merged.length).toBe(BIBLE_LIMITS.ENTRIES_PER_BIBLE_MAX);
  });

  // ---- Universe-as-Canon lock-aware merge ----

  it('locked existing entry: skips field overwrites, appends new evidence (deduped)', () => {
    const existing = [sanitizeCharacter({
      id: 'c1', name: 'Alex', physicalDescription: 'jacket with bright piping',
      role: 'Field Lead', personality: 'calm menace', evidence: ['Issue 1 prose'],
      locked: true, source: 'series-extract',
    })];
    const merged = mergeExtractedBible(existing, [{
      name: 'Alex',
      physicalDescription: 'rewritten attempt',
      role: 'rewritten role',
      personality: 'rewritten',
      evidence: ['Issue 1 prose', 'Issue 3 prose'], // first is dupe, second is new
      firstAppearance: 'should-be-ignored',
    }], 'character');
    expect(merged.length).toBe(1);
    const alex = merged[0];
    // Narrative fields round-trip verbatim — locked entries are protected.
    expect(alex.physicalDescription).toBe('jacket with bright piping');
    expect(alex.role).toBe('Field Lead');
    expect(alex.personality).toBe('calm menace');
    expect(alex.firstAppearance).toBeNull();
    // Evidence accumulates: dedupe by case-insensitive trimmed string.
    expect(alex.evidence).toEqual(['Issue 1 prose', 'Issue 3 prose']);
    // Lock survives.
    expect(alex.locked).toBe(true);
  });

  it('autoLock option stamps locked: true + sourceSeriesId on new inserts', () => {
    const merged = mergeExtractedBible([], [{ name: 'Beta' }], 'character', {
      source: 'series-extract', autoLock: true, sourceSeriesId: 'ser-active',
    });
    expect(merged.length).toBe(1);
    expect(merged[0].locked).toBe(true);
    expect(merged[0].source).toBe('series-extract');
    expect(merged[0].sourceSeriesId).toBe('ser-active');
  });

  it('autoLock false (default) inserts unlocked entries — legacy behavior preserved', () => {
    const merged = mergeExtractedBible([], [{ name: 'Beta' }], 'character');
    expect(merged[0].locked).toBeUndefined();
    expect(merged[0].source).toBe('ai'); // legacy default
  });
});

describe('storyBible — mergeExtractedBible (places)', () => {
  it('matches by slugline, fills blank fields only', () => {
    const existing = [sanitizePlace({ id: 's1', slugline: 'INT. BAR — NIGHT', description: 'cramped chrome bar', palette: '', recurringDetails: '' })];
    const merged = mergeExtractedBible(existing, [
      { slugline: 'INT. BAR — NIGHT', description: 'overwrite attempt', palette: 'amber', recurringDetails: 'jukebox' },
    ], 'place');
    expect(merged[0].description).toBe('cramped chrome bar'); // user wins
    expect(merged[0].palette).toBe('amber');
    expect(merged[0].recurringDetails).toBe('jukebox');
  });

  it('matches with em-dash / hyphen drift on the slugline', () => {
    const existing = [sanitizePlace({ id: 's1', slugline: 'INT. BAR — NIGHT', description: 'cramped' })];
    const merged = mergeExtractedBible(existing, [{ slugline: 'INT BAR - NIGHT', recurringDetails: 'jukebox' }], 'place');
    expect(merged.length).toBe(1);
    expect(merged[0].recurringDetails).toBe('jukebox');
  });

  // Places can legitimately have an empty `name` (slugline is the primary
  // identifier). Sorting by `name` would float every slugline-only entry to
  // the top AND diverge from `writersRoom/places.js#listPlaces`'s
  // `slugline || name` order. Keep the merge sort kind-aware so the API is
  // consistent and callers don't observe an ordering flip after a merge.
  it('sorts places by slugline (or name as fallback), not by name alone', () => {
    const existing = [
      sanitizePlace({ id: 's1', slugline: 'INT. ZINC FOUNDRY — NIGHT' }),
      sanitizePlace({ id: 's2', name: 'Alpha Lab' }),                        // name-only
      sanitizePlace({ id: 's3', slugline: 'EXT. BEACH — DAWN' }),
    ];
    const merged = mergeExtractedBible(existing, [], 'place');
    // Keys (slugline || name) → 'alpha lab', 'ext. beach — dawn', 'int. zinc foundry — night'
    expect(merged.map((e) => e.slugline || e.name)).toEqual([
      'Alpha Lab',
      'EXT. BEACH — DAWN',
      'INT. ZINC FOUNDRY — NIGHT',
    ]);
  });

  it('character/object merges still sort by name (regression guard)', () => {
    const chars = [
      sanitizeCharacter({ id: 'c1', name: 'Zara', physicalDescription: 'tall' }),
      sanitizeCharacter({ id: 'c2', name: 'Alice', physicalDescription: 'short' }),
    ];
    const mergedChars = mergeExtractedBible(chars, [], 'character');
    expect(mergedChars.map((e) => e.name)).toEqual(['Alice', 'Zara']);

    const objs = [
      sanitizeObject({ id: 'o1', name: 'Zenith Coin' }),
      sanitizeObject({ id: 'o2', name: 'Amulet' }),
    ];
    const mergedObjs = mergeExtractedBible(objs, [], 'object');
    expect(mergedObjs.map((e) => e.name)).toEqual(['Amulet', 'Zenith Coin']);
  });
});

describe('storyBible — mergeExtractedBible (objects)', () => {
  it('fills description + significance only when blank', () => {
    const existing = [sanitizeObject({ id: 'o1', name: 'The Locket', description: 'silver dented', significance: '' })];
    const merged = mergeExtractedBible(existing, [{ name: 'The Locket', description: 'try overwrite', significance: 'mother\'s' }], 'object');
    expect(merged[0].description).toBe('silver dented');
    expect(merged[0].significance).toBe("mother's");
  });
});

describe('storyBible — helpers', () => {
  it('normalizeBibleName lowercases + trims', () => {
    expect(normalizeBibleName('  Aria Reyes  ')).toBe('aria reyes');
    expect(normalizeBibleName(null)).toBe('');
  });

  describe('findBibleEntryByName', () => {
    const list = [
      { id: 'a', name: 'Ashley', aliases: ['Ash', 'Ash-bot'] },
      { id: 'b', name: 'Crystalline Canyon' }, // no aliases array
      { id: 'c', name: 'Reyes', aliases: null }, // null aliases tolerated
      null, // null entry tolerated
    ];

    it('matches by case-insensitive name', () => {
      expect(findBibleEntryByName(list, 'ashley')?.id).toBe('a');
      expect(findBibleEntryByName(list, '  ASHLEY  ')?.id).toBe('a');
    });

    it('matches by alias when present', () => {
      expect(findBibleEntryByName(list, 'ash')?.id).toBe('a');
      expect(findBibleEntryByName(list, 'Ash-Bot')?.id).toBe('a');
    });

    it('returns undefined when no entry matches', () => {
      expect(findBibleEntryByName(list, 'Nobody')).toBeUndefined();
    });

    it('returns undefined for blank/missing needles', () => {
      expect(findBibleEntryByName(list, '')).toBeUndefined();
      expect(findBibleEntryByName(list, '   ')).toBeUndefined();
      expect(findBibleEntryByName(list, null)).toBeUndefined();
    });

    it('returns undefined for a non-array list', () => {
      expect(findBibleEntryByName(null, 'Ashley')).toBeUndefined();
      expect(findBibleEntryByName(undefined, 'Ashley')).toBeUndefined();
    });
  });
});

// ---------------------------------------------------------------------------
// createBibleStore — factory exercised through the three real per-kind
// configs (so we cover both the single-primary-field path and the multi-
// primary settings path). Each subgroup gets a fresh temp dir.
// ---------------------------------------------------------------------------

function characterStore() {
  return createBibleStore({
    kind: BIBLE_KIND.CHARACTER,
    idPrefix: 'wr-char-',
    dedupKey: (entry) => normalizeBibleName(entry?.name),
    primaryFields: ['name'],
    editableFields: ['aliases', 'role', 'physicalDescription'],
    requireOnCreate: (patch) => (String(patch?.name || '').trim() ? null : 'Character name required'),
    conflictMessage: ({ name }) => `A character named "${name}" already exists`,
    notFoundLabel: 'Character',
    invalidIdMessage: 'Invalid character id',
  });
}

function settingStore() {
  return createBibleStore({
    kind: BIBLE_KIND.PLACE,
    idPrefix: 'wr-place-',
    dedupKey: (entry) => normalizeSlugline(entry?.slugline || entry?.name || ''),
    primaryFields: ['slugline', 'name'],
    editableFields: ['description', 'palette'],
    requireOnCreate: (patch) => {
      const sl = String(patch?.slugline || '').trim();
      const nm = String(patch?.name || '').trim();
      return sl || nm ? null : 'Setting requires either a slugline or a name';
    },
    validateAfterUpdate: (next) => {
      if (!next.slugline && !next.name) {
        const err = new Error('Setting needs slugline or name');
        err.status = 400;
        throw err;
      }
    },
    conflictMessage: ({ slugline, name }) => `A setting matching "${slugline || name}" already exists`,
    notFoundLabel: 'Setting',
    invalidIdMessage: 'Invalid setting id',
  });
}

describe('storyBible — createBibleStore (single-primary-field kind)', () => {
  beforeEach(() => {
    tempRoot = mkdtempSync(join(tmpdir(), 'bible-factory-test-'));
  });
  afterEach(() => {
    if (tempRoot && existsSync(tempRoot)) rmSync(tempRoot, { recursive: true, force: true });
  });

  it('creates, lists, gets, updates, deletes', async () => {
    const store = characterStore();
    expect(await store.list(WORK_ID)).toEqual([]);

    const created = await store.create(WORK_ID, { name: 'Aria', role: 'protagonist' });
    expect(created.id).toMatch(/^wr-char-/);
    expect(created.name).toBe('Aria');
    expect(created.source).toBe('user');

    const listed = await store.list(WORK_ID);
    expect(listed).toHaveLength(1);

    const fetched = await store.get(WORK_ID, created.id);
    expect(fetched.id).toBe(created.id);

    const updated = await store.update(WORK_ID, created.id, { role: 'antagonist' });
    expect(updated.role).toBe('antagonist');

    const removed = await store.remove(WORK_ID, created.id);
    expect(removed).toEqual({ ok: true });
    expect(await store.list(WORK_ID)).toEqual([]);
  });

  it('rejects creation without the required identifier', async () => {
    const store = characterStore();
    await expect(store.create(WORK_ID, { name: '   ' })).rejects.toThrow(/name required/i);
  });

  it('rejects duplicate dedup keys at create time (case-insensitive)', async () => {
    const store = characterStore();
    await store.create(WORK_ID, { name: 'Aria' });
    await expect(store.create(WORK_ID, { name: 'aria' })).rejects.toThrow(/already exists/i);
  });

  it('rejects path-traversal-shaped work ids before any filesystem access', async () => {
    const store = characterStore();
    await expect(store.list('../../etc')).rejects.toThrow(/work id/i);
    await expect(store.create('../../etc', { name: 'X' })).rejects.toThrow(/work id/i);
    await expect(store.mergeExtracted('../../etc', [{ name: 'X' }])).rejects.toThrow(/work id/i);
  });

  it('rejects malformed entry ids on get/update/remove', async () => {
    const store = characterStore();
    await expect(store.get(WORK_ID, 'nope')).rejects.toThrow(/invalid character id/i);
    await expect(store.update(WORK_ID, 'nope', {})).rejects.toThrow(/invalid character id/i);
    await expect(store.remove(WORK_ID, 'nope')).rejects.toThrow(/invalid character id/i);
  });

  it('rejects blanking the primary identifier on update', async () => {
    const store = characterStore();
    const c = await store.create(WORK_ID, { name: 'Aria' });
    await expect(store.update(WORK_ID, c.id, { name: '' })).rejects.toThrow(/cannot be blank/i);
  });

  it('mergeExtracted inserts new entries and skips duplicates', async () => {
    const store = characterStore();
    const merged = await store.mergeExtracted(WORK_ID, [
      { name: 'Aria', role: 'protagonist' },
      { name: 'Voss', role: 'antagonist' },
    ]);
    expect(merged).toHaveLength(2);
    expect(merged.every((e) => e.source === 'ai')).toBe(true);
  });

  it('serializes overlapping edits and extraction on the same bible file', async () => {
    const store = characterStore();
    const existing = await store.create(WORK_ID, { name: 'Aria', role: 'protagonist' });

    const updatePromise = store.update(WORK_ID, existing.id, { role: 'antagonist' });
    const mergePromise = store.mergeExtracted(WORK_ID, [{ name: 'Voss', role: 'antagonist' }]);
    await Promise.all([updatePromise, mergePromise]);

    const entries = await store.list(WORK_ID);
    expect(entries.find((entry) => entry.id === existing.id)?.role).toBe('antagonist');
    expect(entries.some((entry) => entry.name === 'Voss')).toBe(true);
  });

  it('preserves concurrent updates to different entries in one bible file', async () => {
    const store = characterStore();
    const aria = await store.create(WORK_ID, { name: 'Aria', role: 'protagonist' });
    const voss = await store.create(WORK_ID, { name: 'Voss', role: 'supporting' });

    await Promise.all([
      store.update(WORK_ID, aria.id, { role: 'antagonist' }),
      store.update(WORK_ID, voss.id, { role: 'protagonist' }),
    ]);

    const entries = await store.list(WORK_ID);
    expect(entries.find((entry) => entry.id === aria.id)?.role).toBe('antagonist');
    expect(entries.find((entry) => entry.id === voss.id)?.role).toBe('protagonist');
  });

  it('allows writes for different works to proceed independently', async () => {
    const store = characterStore();
    const otherWorkId = 'wr-work-bbbbbbbb-cccc-dddd-eeee-ffffffffffff';
    const [aria, voss] = await Promise.all([
      store.create(WORK_ID, { name: 'Aria' }),
      store.create(otherWorkId, { name: 'Voss' }),
    ]);

    await Promise.all([
      store.update(WORK_ID, aria.id, { role: 'protagonist' }),
      store.update(otherWorkId, voss.id, { role: 'antagonist' }),
    ]);

    expect((await store.list(WORK_ID))[0].role).toBe('protagonist');
    expect((await store.list(otherWorkId))[0].role).toBe('antagonist');
  });
});

describe('storyBible — createBibleStore (multi-primary-field kind / settings)', () => {
  beforeEach(() => {
    tempRoot = mkdtempSync(join(tmpdir(), 'bible-factory-settings-test-'));
  });
  afterEach(() => {
    if (tempRoot && existsSync(tempRoot)) rmSync(tempRoot, { recursive: true, force: true });
  });

  it('accepts either slugline or name as the primary identifier at create', async () => {
    const store = settingStore();
    const a = await store.create(WORK_ID, { slugline: 'INT. KITCHEN — NIGHT', description: 'cozy' });
    expect(a.slugline).toBe('INT. KITCHEN — NIGHT');
    // Auto-fills name from slugline when name omitted.
    expect(a.name).toBe('INT. KITCHEN — NIGHT');

    const b = await store.create(WORK_ID, { name: 'The Atrium' });
    expect(b.name).toBe('The Atrium');
    expect(b.slugline).toBe('');
  });

  it('rejects creation when both slugline and name are blank', async () => {
    const store = settingStore();
    await expect(store.create(WORK_ID, {})).rejects.toThrow(/slugline or a name/i);
  });

  it('rejects an update that blanks both name and slugline (validateAfterUpdate)', async () => {
    const store = settingStore();
    const s = await store.create(WORK_ID, { name: 'The Atrium' });
    await expect(store.update(WORK_ID, s.id, { name: '' })).rejects.toThrow(/slugline or name/i);
  });

  it('rejects duplicate-slugline create after normalization', async () => {
    const store = settingStore();
    await store.create(WORK_ID, { slugline: 'INT. KITCHEN — NIGHT' });
    await expect(
      store.create(WORK_ID, { slugline: 'int. kitchen - night' }),
    ).rejects.toThrow(/already exists/i);
  });

  it('rejects an update that would collide with another entry on dedup key', async () => {
    const store = settingStore();
    const a = await store.create(WORK_ID, { slugline: 'INT. KITCHEN — NIGHT' });
    await store.create(WORK_ID, { slugline: 'EXT. ROOFTOP — DAWN' });
    await expect(
      store.update(WORK_ID, a.id, { slugline: 'EXT. ROOFTOP — DAWN' }),
    ).rejects.toThrow(/already exists/i);
  });
});

describe('BIBLE_LIMITS client mirror', () => {
  it('matches client/src/lib/bibleLimits.js verbatim', async () => {
    // The client mirror at `client/src/lib/bibleLimits.js` exists so the
    // CharacterDetailEditor's `max:` literals can't drift from the server
    // sanitizer caps. If this fails, update the client file to match.
    const clientMirror = await import('../../client/src/lib/bibleLimits.js');
    expect(clientMirror.BIBLE_LIMITS).toEqual(BIBLE_LIMITS);
  });
});
describe('storyBible — reveal-gated canon (#2178)', () => {
  describe('sanitizer field round-trip', () => {
    it('defaults reveal fields to null/absent on every kind (backward compat)', () => {
      const c = sanitizeCharacter({ name: 'Alex' });
      expect(c.revealIssue).toBeNull();
      expect(c.surfaceDescriptor).toBeNull();
      expect(c.spoiler).toBeUndefined();
      const p = sanitizePlace({ name: 'The Wing' });
      expect(p.revealIssue).toBeNull();
      expect(p.surfaceDescriptor).toBeNull();
      const o = sanitizeObject({ name: 'The Locket' });
      expect(o.revealIssue).toBeNull();
      expect(o.spoiler).toBeUndefined();
    });

    it('persists a valid revealIssue (number or numeric string) and rejects bad values', () => {
      expect(sanitizeCharacter({ name: 'A', revealIssue: 8 }).revealIssue).toBe(8);
      expect(sanitizeCharacter({ name: 'A', revealIssue: '8' }).revealIssue).toBe(8);
      expect(sanitizeCharacter({ name: 'A', revealIssue: 0 }).revealIssue).toBeNull();
      expect(sanitizeCharacter({ name: 'A', revealIssue: -3 }).revealIssue).toBeNull();
      expect(sanitizeCharacter({ name: 'A', revealIssue: 2.5 }).revealIssue).toBeNull();
      expect(sanitizeCharacter({ name: 'A', revealIssue: 'soon' }).revealIssue).toBeNull();
      expect(sanitizeCharacter({ name: 'A', revealIssue: BIBLE_LIMITS.REVEAL_ISSUE_MAX + 1 }).revealIssue).toBeNull();
    });

    it('persists explicit spoiler true/false and drops a non-boolean', () => {
      expect(sanitizeCharacter({ name: 'A', spoiler: true }).spoiler).toBe(true);
      expect(sanitizeCharacter({ name: 'A', spoiler: false }).spoiler).toBe(false);
      expect(sanitizeCharacter({ name: 'A', spoiler: 'yes' }).spoiler).toBeUndefined();
      expect(sanitizeCharacter({ name: 'A' }).spoiler).toBeUndefined();
    });

    it('caps surfaceDescriptor at its limit and collapses blank to null', () => {
      const long = 'x'.repeat(BIBLE_LIMITS.SURFACE_DESCRIPTOR_MAX + 100);
      expect(sanitizePlace({ name: 'A', surfaceDescriptor: long }).surfaceDescriptor.length)
        .toBe(BIBLE_LIMITS.SURFACE_DESCRIPTOR_MAX);
      expect(sanitizePlace({ name: 'A', surfaceDescriptor: '   ' }).surfaceDescriptor).toBeNull();
    });
  });

  describe('isCanonEntryGatedForIssue', () => {
    it('hard spoiler gates regardless of issue number', () => {
      expect(isCanonEntryGatedForIssue({ spoiler: true }, 1)).toBe(true);
      expect(isCanonEntryGatedForIssue({ spoiler: true }, 99)).toBe(true);
      expect(isCanonEntryGatedForIssue({ spoiler: true }, undefined)).toBe(true);
    });
    it('revealIssue gates only issues before it', () => {
      expect(isCanonEntryGatedForIssue({ revealIssue: 8 }, 2)).toBe(true);
      expect(isCanonEntryGatedForIssue({ revealIssue: 8 }, 8)).toBe(false);
      expect(isCanonEntryGatedForIssue({ revealIssue: 8 }, 9)).toBe(false);
    });
    it('an ungated entry is never gated', () => {
      expect(isCanonEntryGatedForIssue({ name: 'A' }, 1)).toBe(false);
      expect(isCanonEntryGatedForIssue(null, 1)).toBe(false);
    });
    it('a numeric reveal gate is not evaluable without an issue number', () => {
      expect(isCanonEntryGatedForIssue({ revealIssue: 8 }, undefined)).toBe(false);
      expect(isCanonEntryGatedForIssue({ revealIssue: 8 }, 'not-a-number')).toBe(false);
    });
  });

  describe('filterCanonListForIssue — surface substitution + drop', () => {
    it('passes ungated entries through untouched', () => {
      const list = [{ id: 'c1', name: 'Open', physicalDescription: 'tall' }];
      expect(filterCanonListForIssue(list, 'character', 1)).toEqual(list);
    });
    it('substitutes surfaceDescriptor for a gated entry and strips the secret', () => {
      const list = [{
        id: 'c1', name: 'Mara', role: 'suspect',
        physicalDescription: 'the arsonist who burned the mill',
        background: 'set the fire in Issue 8',
        revealIssue: 8,
        surfaceDescriptor: 'a quiet neighbor who keeps to herself',
      }];
      const out = filterCanonListForIssue(list, 'character', 2);
      expect(out).toHaveLength(1);
      expect(out[0].physicalDescription).toBe('a quiet neighbor who keeps to herself');
      expect(out[0].name).toBe('Mara');
      expect(out[0].role).toBe('suspect');
      expect(out[0].surfaced).toBe(true);
      // The secret fields are gone.
      expect(out[0].background).toBeUndefined();
    });
    it('drops a gated entry entirely when it has no surfaceDescriptor', () => {
      const list = [{ id: 'c1', name: 'Twist', description: 'the real killer', revealIssue: 8 }];
      expect(filterCanonListForIssue(list, 'object', 2)).toEqual([]);
    });
    it('substitutes the place description field for a gated place', () => {
      const list = [{
        id: 'p1', name: 'East Wing', slugline: 'INT. EAST WING',
        description: 'the wing where the heir is imprisoned',
        revealIssue: 5,
        surfaceDescriptor: 'the locked east wing nobody enters',
      }];
      const out = filterCanonListForIssue(list, 'place', 3);
      expect(out[0].description).toBe('the locked east wing nobody enters');
      expect(out[0].slugline).toBe('INT. EAST WING');
    });
    it('reveals the full entry at/after the reveal issue', () => {
      const list = [{ id: 'c1', name: 'Mara', physicalDescription: 'the arsonist', revealIssue: 8, surfaceDescriptor: 'a neighbor' }];
      expect(filterCanonListForIssue(list, 'character', 8)[0].physicalDescription).toBe('the arsonist');
    });
  });

  describe('filterCanonForIssue — whole bundle', () => {
    it('filters all three kinds and returns empty for a nullish canon', () => {
      expect(filterCanonForIssue(null, 1)).toEqual({ characters: [], places: [], objects: [] });
      const canon = {
        characters: [{ id: 'c', name: 'C', spoiler: true }],
        places: [{ id: 'p', name: 'P' }],
        objects: [{ id: 'o', name: 'O', revealIssue: 4, surfaceDescriptor: 'a plain box', description: 'the bomb' }],
      };
      const out = filterCanonForIssue(canon, 2);
      expect(out.characters).toEqual([]); // hard spoiler, no surface → dropped
      expect(out.places).toHaveLength(1); // ungated
      expect(out.objects[0].description).toBe('a plain box'); // surfaced
    });
  });

  describe('canonHasRevealGated + revealGatedCanonRows', () => {
    it('is false when nothing is gated, true when any entry is gated', () => {
      expect(canonHasRevealGated({ characters: [{ name: 'A' }] })).toBe(false);
      expect(canonHasRevealGated({ characters: [{ name: 'A', revealIssue: 3 }] })).toBe(true);
      expect(canonHasRevealGated({ objects: [{ name: 'O', spoiler: true }] })).toBe(true);
      expect(canonHasRevealGated(null)).toBe(false);
    });
    it('enumerates gated rows with kind/name/reveal/spoiler/fact', () => {
      const canon = {
        characters: [{ name: 'Mara', physicalDescription: 'arsonist', background: 'lit the fire', revealIssue: 8, surfaceDescriptor: 'a neighbor' }],
        objects: [{ name: 'Box', description: 'the bomb', spoiler: true }],
        places: [{ name: 'Plain Room' }],
      };
      const rows = revealGatedCanonRows(canon);
      expect(rows).toHaveLength(2);
      const mara = rows.find((r) => r.name === 'Mara');
      expect(mara.kind).toBe('character');
      expect(mara.revealIssue).toBe(8);
      expect(mara.spoiler).toBe(false);
      expect(mara.surfaceDescriptor).toBe('a neighbor');
      expect(mara.fact).toContain('arsonist');
      expect(mara.fact).toContain('lit the fire');
      const box = rows.find((r) => r.name === 'Box');
      expect(box.spoiler).toBe(true);
      expect(box.revealIssue).toBeNull();
    });
  });
});

// The durable render identity must survive canonical storage and stale client
// edits, while model-generated content cannot create or replace it.
it('round-trips server-owned sheet request identity and preserves it across stale edits', () => {
  const requestId = '11111111-1111-4111-8111-111111111111';
  const current = sanitizeCharacter({ id: 'character-1', name: 'Example', referenceSheetRequests: { standard: requestId, blueprint: requestId } });
  expect(current.referenceSheetRequests).toEqual({ standard: requestId, blueprint: requestId });
  const patched = mergePreservedSheetPointers(current, { ...current, name: 'Edited', referenceSheetRequests: {} }, () => false);
  expect(sanitizeCharacter(patched).referenceSheetRequests).toEqual(current.referenceSheetRequests);
  expect(stripCanonControlFields(current)).not.toHaveProperty('referenceSheetRequests');
});

it('preserves sheet request identity from pre-v13 peers but honors current peer supersession', () => {
  const local = [{ id: 'character-1', referenceSheetRequests: { standard: '11111111-1111-4111-8111-111111111111' } }];
  const legacy = [{ id: 'character-1', name: 'Peer edit', referenceSheetRequests: {} }];
  expect(preserveLegacyCharacterFields(legacy, local, 12)[0].referenceSheetRequests).toEqual(local[0].referenceSheetRequests);
  const newer = [{ id: 'character-1', referenceSheetRequests: { standard: '22222222-2222-4222-8222-222222222222' } }];
  expect(preserveLegacyCharacterFields(newer, local, 13)).toEqual(newer);
});