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

69.3 KB
Raw Blame
import { spriteEvents } from './events.js';
/**
 * Reference workflow orchestration (#2896): generate → candidates → lock,
 * against the file record backend + a tmpdir asset tree. The media-job queue
 * and image-gen dispatcher are mocked — this suite covers the workflow
 * contracts (prompt/tag/param shaping, manifest lifecycle, immutability
 * 409s, dynamic chroma-key selection at lock).
 */

import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest';
import { mkdtempSync, rmSync, readFileSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { createHash } from 'crypto';
import sharp from 'sharp';
import { mkdir, writeFile, readFile } from 'fs/promises';
import { writeCandidatePng, placeCandidate as placeCandidateFixture, expectCarriesCorrection } from './spriteTestFixtures.js';

const TEST_ROOT = mkdtempSync(join(tmpdir(), 'sprite-reference-test-'));
const manifestWrites = [];
const localImageModels = [
  { id: 'dev', hardwareCompatibility: { state: 'available' } },
  { id: 'flux-dev-4bit', hardwareCompatibility: { state: 'available' } },
  { id: 'record-incompatible', hardwareCompatibility: { state: 'unavailable' } },
];

// MUTATE actual.PATHS (don't replace the object): fileUtils' internal
// resolvers (resolveImageInputPath / resolveSpriteImageInput) close over the
// module-level PATHS reference, and the initImagePath assertion below needs
// them to see the test roots.
vi.mock('../../lib/fileUtils.js', async (importOriginal) => {
  const actual = await importOriginal();
  Object.assign(actual.PATHS, {
    data: TEST_ROOT,
    sprites: join(TEST_ROOT, 'sprites'),
    images: join(TEST_ROOT, 'images'),
  });
  return {
    ...actual,
    atomicWrite: async (path, ...args) => {
      if (path.endsWith('-reference-set-v1.json')) manifestWrites.push(path);
      return actual.atomicWrite(path, ...args);
    },
  };
});

const enqueueJob = vi.fn(() => ({ jobId: 'job-1234567890', position: 0, status: 'queued' }));
vi.mock('../mediaJobQueue/index.js', () => ({
  enqueueJob: (...args) => enqueueJob(...args),
  mediaJobEvents: { on: () => {}, off: () => {} },
}));

vi.mock('../../lib/imageCleanDefaults.js', () => ({
  resolveImageCleaners: () => ({ cleanC2PA: false, denoise: false }),
}));
vi.mock('../../lib/mediaModels.js', async (importOriginal) => ({
  ...(await importOriginal()),
  getImageModels: () => localImageModels,
}));

const settings = {
  imageGen: {
    mode: 'codex',
    codex: { enabled: true, codexPath: '/usr/local/bin/codex', model: 'gpt-5.6-luna', effort: 'low' },
    grok: { enabled: true, grokPath: '/usr/local/bin/grok', aspectRatio: '1:1' },
    // Enabled so the edit-incapable-backend suite (#3331) can ask for it; the
    // saved `mode` is still codex, so no other test's resolution changes.
    agy: { enabled: true, agyPath: '/usr/local/bin/agy', model: 'gemini-3.5-flash-low' },
    local: { pythonPath: '/usr/bin/python3', modelId: 'flux-dev-4bit' },
  },
};
vi.mock('../settings.js', () => ({ getSettings: async () => settings }));

const records = await import('./records.js');
const {
  getReferenceSet, startReferenceGeneration, attachReferenceCandidate, lockReference, patchSpriteRecord,
  unlockReferenceAnchor, unlockReferenceMain, unlockReferenceTurnaround,
  listReferenceSources, listSpriteThumbnails, forkSprite,
  requireCharacter, requireAnimatable,
} = await import('./reference.js');

let seq = 0;
const newId = () => `hero-${++seq}`;

async function createCharacter(id, input = {}) {
  return records.createRecord({ kind: 'character', name: 'Hero', ...input }, id);
}

const placeCandidate = (recordId, target, name, opts) => placeCandidateFixture(TEST_ROOT, recordId, target, name, opts);

async function lockTurnaround(recordId) {
  const rel = await placeCandidate(recordId, 'turnaround', 'turnaround-candidate-01.png');
  return lockReference(recordId, { target: 'turnaround', candidate: rel });
}

// Walks the turnaround-first order (#2979): the sheet freezes the key, then the
// main descends from it. Anchor tests start from here.
async function lockMain(recordId) {
  await lockTurnaround(recordId);
  const rel = await placeCandidate(recordId, 'main', 'walk-south-candidate-01.png');
  return lockReference(recordId, { target: 'main', candidate: rel });
}

const DIRECTIONS = ['south', 'south-east', 'east', 'north-east', 'north', 'north-west', 'west', 'south-west'];

// Write a pre-#2979 manifest verbatim to disk — main-first, schemaVersion 1, no
// turnaround block. `lockedMain` produces what an install upgraded from phase 2
// actually holds (the frozen PNG + a locked mainReference + the key it froze),
// which is the ONLY v1 shape that survives upgradeManifestShape; the unlocked
// variant is a mid-workflow draft, which normalizes to v2 on read.
//
// These are written straight to disk rather than locked through lockReference,
// because that path would normalize the draft to v2 first and so could never
// reproduce a genuine v1-with-locked-main.
async function writeLegacyManifest(recordId, { lockedMain = false } = {}) {
  const dir = join(TEST_ROOT, 'sprites', recordId, 'reference');
  await mkdir(dir, { recursive: true });
  const mainPath = `reference/${recordId}-walk-south-v1.png`;
  if (lockedMain) await writeCandidatePng(join(TEST_ROOT, 'sprites', recordId, mainPath));
  await writeFile(join(dir, `${recordId}-reference-set-v1.json`), JSON.stringify({
    schemaVersion: 1,
    manifestId: `${recordId}-reference-set-v1`,
    status: lockedMain ? 'in-progress' : 'needs-main-reference',
    characterFamily: recordId,
    chromaKey: lockedMain ? '#FF00FF' : null,
    ...(lockedMain ? { chromaKeyAutoSelected: true } : {}),
    mainReference: {
      path: lockedMain ? mainPath : null,
      role: 'immutable-root',
      background: 'chroma-key',
      locked: lockedMain,
      ...(lockedMain ? { lockedFrom: 'reference/candidates/walk-south-candidate-01.png', lockedAt: '2026-01-01T00:00:00.000Z' } : {}),
    },
    anchors: DIRECTIONS.map((direction) => ({
      id: `walk-${direction}`,
      kind: 'walk-anchor',
      direction,
      status: lockedMain && direction === 'south' ? 'locked' : 'pending',
      ...(lockedMain && direction === 'south' ? { path: mainPath } : {}),
    })),
  }));
  if (lockedMain) await records.updateRecord(recordId, { chromaKey: '#FF00FF', status: 'reference' });
}

const legacyLockedMain = (recordId) => writeLegacyManifest(recordId, { lockedMain: true });

beforeEach(() => {
  enqueueJob.mockClear();
  rmSync(join(TEST_ROOT, 'sprite-records.json'), { force: true });
});
afterAll(() => rmSync(TEST_ROOT, { recursive: true, force: true }));

describe('the animation gates (#3017)', () => {
  // The gates used to be one literal `kind !== 'character'` test. They are now
  // two registry reads with different questions: "may this record carry the
  // WALK track" (the gait-shaped reference/walk workflow) and "may it carry ANY
  // track" (compiling and publishing an atlas). Walk is character-only, so both
  // refuse exactly what they always did — what changed is that adding a row
  // listing `place` unlocks the second gate with no edit to this file's target.
  it('404s an unknown record from either gate', async () => {
    await expect(requireCharacter('nope-1')).rejects.toMatchObject({ code: 'NOT_FOUND' });
    await expect(requireAnimatable('nope-2')).rejects.toMatchObject({ code: 'NOT_FOUND' });
  });

  it('admits a character through both gates', async () => {
    const id = newId();
    await createCharacter(id);
    await expect(requireCharacter(id)).resolves.toMatchObject({ id, kind: 'character' });
    await expect(requireAnimatable(id)).resolves.toMatchObject({ id, kind: 'character' });
  });

  it('admits a place record for ambient work while retaining the character-only walk gate', async () => {
    await records.createRecord({ kind: 'place', name: 'Grove' }, 'grove');
    // The walk gate keeps its historical code, so existing callers matching on
    // NOT_A_CHARACTER are unaffected.
    await expect(requireCharacter('grove')).rejects.toMatchObject({ code: 'NOT_A_CHARACTER' });
    await expect(requireAnimatable('grove')).resolves.toMatchObject({ id: 'grove', kind: 'place' });
  });
});

describe('startReferenceGeneration', () => {
  // Pins the entire queue contract across target planners and backend routes;
  // the payload digest detects any serialized field or prompt wording drift.
  it('preserves queued payloads and manifest writes for every target and backend', async () => {
    const contracts = {};
    for (const mode of ['local', 'codex', 'agy', 'grok']) {
      for (const target of ['turnaround', 'ambient-main', 'main', 'east']) {
        const id = newId();
        if (target === 'ambient-main') {
          await records.createRecord({ kind: 'place', name: 'Hero' }, id);
        } else {
          await createCharacter(id);
        }
        if (target === 'main') await lockTurnaround(id);
        if (target === 'east') await lockMain(id);
        const run = async (designPrompt) => {
          enqueueJob.mockClear();
          manifestWrites.length = 0;
          await startReferenceGeneration(id, {
            target: target === 'ambient-main' ? 'main' : target,
            mode, designPrompt, correctionPrompt: '  repair the hem  ',
          });
          const job = enqueueJob.mock.calls[0][0];
          if (mode === 'codex') {
            expect(job.params.modelIsShippedDefault).toBe(false);
          }
          // Normalize native paths BEFORE JSON escapes Windows backslashes.
          // Only fixture-rooted paths change; prompts and other payload bytes
          // retain their exact snapshot contract.
          const normalized = JSON.stringify(job, (_key, value) => {
            if (typeof value !== 'string') return value;
            const stable = value.startsWith(TEST_ROOT)
              ? '<test-root>' + value.slice(TEST_ROOT.length).replaceAll('\\', '/')
              : value;
            return stable.replaceAll(id, '<record>');
          });
          return {
            payloadSHA256: createHash('sha256').update(normalized).digest('hex'),
            manifestWrites: manifestWrites.length,
          };
        };
        contracts[mode + '/' + target] = await run('example design');
        if (target === 'main') contracts[mode + '/main-reroll'] = await run(undefined);
      }
    }
    expect(contracts).toMatchInlineSnapshot(`
      {
        "agy/ambient-main": {
          "manifestWrites": 1,
          "payloadSHA256": "618f006a1923f147257030bae9aed0e892b410dd99864c6651b66c3a6e13c0d7",
        },
        "agy/east": {
          "manifestWrites": 0,
          "payloadSHA256": "663174cc78679ce571095b2d7ff363b5d5c025173a8d49c10afc24fe3fd24bcb",
        },
        "agy/main": {
          "manifestWrites": 1,
          "payloadSHA256": "19eadde44bc1333da317b56d5817b31124e5c5985147e20bc369105fef881a74",
        },
        "agy/main-reroll": {
          "manifestWrites": 0,
          "payloadSHA256": "9582217d0025d10f254571114dfa232bec7b8cc4a2e55aad41234b3d8c53b828",
        },
        "agy/turnaround": {
          "manifestWrites": 1,
          "payloadSHA256": "d06be938985f946942bc4c5f37a8ef5a5eb9d5c010a55195ecab2530b4b22e45",
        },
        "codex/ambient-main": {
          "manifestWrites": 1,
          "payloadSHA256": "eb5a0e7f9cb43a944944ec4bad178b9fa0b503829cb3466b02bf9b1346ff079a",
        },
        "codex/east": {
          "manifestWrites": 0,
          "payloadSHA256": "9e27f6c9f891a54c48966b603319a3f762efab7ef2dab26106015f4f6bc796c4",
        },
        "codex/main": {
          "manifestWrites": 1,
          "payloadSHA256": "831738c9a5253ac4cb70d51bf48abaf93e4a1d4c60104182c4cd82c54387b744",
        },
        "codex/main-reroll": {
          "manifestWrites": 0,
          "payloadSHA256": "80c1772f7fdabe48107d938a60875b91f5d90b74e42de68bac462d6dcd619a7e",
        },
        "codex/turnaround": {
          "manifestWrites": 1,
          "payloadSHA256": "cf90b056abeae15d14a0cd9da60c654b1d4b4810b75989c6c0183232e038f840",
        },
        "grok/ambient-main": {
          "manifestWrites": 1,
          "payloadSHA256": "696eb01070645ad71b91654275004782ec12e94a53d9404dd6fef633cbe86a9d",
        },
        "grok/east": {
          "manifestWrites": 0,
          "payloadSHA256": "7b022a6ac38c48e984b04e9dc2fdf6228a2690a7c0296b107be72afe4b539089",
        },
        "grok/main": {
          "manifestWrites": 1,
          "payloadSHA256": "180dc044dd6c4ca6396181bd2ef23f9bccb23e374170369fd2dd072e6d44e7e2",
        },
        "grok/main-reroll": {
          "manifestWrites": 0,
          "payloadSHA256": "7547bf855275eb89e35830b2fa88d10672ab8a478b54d393434ca1499380fbc4",
        },
        "grok/turnaround": {
          "manifestWrites": 1,
          "payloadSHA256": "8da78c2e920e50bfc161c3e7f236bed531581ac5005220818a69f15e94aeafd7",
        },
        "local/ambient-main": {
          "manifestWrites": 1,
          "payloadSHA256": "3655b224dc8e5b084b0a3a97410394badf0c411838470d3c191b9f7ef499a508",
        },
        "local/east": {
          "manifestWrites": 0,
          "payloadSHA256": "01c6c651ce1dbe0108044ec268aa4aa75cc364faa14d9c366c266d067e5bc037",
        },
        "local/main": {
          "manifestWrites": 1,
          "payloadSHA256": "652c79b1af5ced63055aed1ca002730b30e889e76ddaace9086fc82d5a798a39",
        },
        "local/main-reroll": {
          "manifestWrites": 0,
          "payloadSHA256": "4c828a15f8eca717a498f90b2a0469e3ca2a5eb9c18019805c947a9c6037e7d8",
        },
        "local/turnaround": {
          "manifestWrites": 1,
          "payloadSHA256": "02aa273d1b41b9a29809e5e62ead21587be57aaca11fc04a8b57e31b42e40afe",
        },
      }
    `);
  });

  it('404s an unknown record and queues a props main reference for the ambient workflow', async () => {
    await expect(startReferenceGeneration('nope', { target: 'main', designPrompt: 'x' }))
      .rejects.toMatchObject({ code: 'NOT_FOUND' });
    await records.createRecord({ kind: 'props', name: 'Crates' }, 'crates');
    await expect(startReferenceGeneration('crates', { target: 'main', designPrompt: 'x' }))
      .resolves.toMatchObject({ jobId: 'job-1234567890', target: 'main', anchorId: 'main' });
    expect(enqueueJob.mock.calls[0][0].params.prompt).toContain('at-rest state');
  });

  it('requires a design prompt or upload for the turnaround target', async () => {
    const id = newId();
    await createCharacter(id);
    await expect(startReferenceGeneration(id, { target: 'turnaround' }))
      .rejects.toMatchObject({ code: 'DESIGN_INPUT_REQUIRED' });
  });

  it('queues a turnaround render with the sprite tag and seeds the manifest', async () => {
    const id = newId();
    await createCharacter(id);
    const result = await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'a wiry ranger' });
    expect(result).toMatchObject({ jobId: 'job-1234567890', mode: 'codex', target: 'turnaround', anchorId: 'turnaround' });

    const call = enqueueJob.mock.calls[0][0];
    expect(call.kind).toBe('image');
    expect(call.params.mode).toBe('codex');
    expect(call.params.model).toBe('gpt-5.6-luna');
    expect(call.params).toMatchObject({ width: 1024, height: 1024 });
    expect(call.params.prompt).toContain('named Hero');
    expect(call.params.prompt).toContain('a wiry ranger');
    expect(call.params.prompt).toContain('magenta (#FF00FF)');
    // The panels, in order, and the constraint the sheet exists to enforce.
    expect(call.params.prompt).toContain('1) facing the viewer (front)');
    expect(call.params.prompt).toContain('3) facing directly away from the viewer');
    expect(call.params.prompt).toContain('SAME anatomical side');
    expect(call.params.spriteRef).toMatchObject({
      recordId: id, target: 'turnaround', anchorId: 'turnaround', chromaKey: '#FF00FF',
      // Provenance records the model the provider will actually run, not
      // null on the default path.
      model: 'gpt-5.6-luna',
    });

    const { manifest } = await getReferenceSet(id);
    expect(manifest.schemaVersion).toBe(2);
    expect(manifest.status).toBe('needs-turnaround');
    expect(manifest.anchors).toHaveLength(8);
    expect(manifest.designPrompt).toBe('a wiry ranger');
  });

  it('persists an uploaded design reference with a server-derived extension and records it in the tag provenance', async () => {
    const id = newId();
    await createCharacter(id);
    const tmp = join(TEST_ROOT, 'upload-tmp.png');
    await writeCandidatePng(tmp);
    await startReferenceGeneration(id, { target: 'turnaround' }, { tempPath: tmp, originalname: 'concept.svg', ext: '.png' });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.spriteRef.designReferencePath).toMatch(/^reference\/uploads\/.+design-reference\.png$/);
    expect(call.params.initImagePath).toContain(join('reference', 'uploads'));
    expect(call.params.initImageStrength).toBe(0.65);
  });

  it('maps an image/webp design upload to .webp regardless of the client filename', async () => {
    const id = newId();
    await createCharacter(id);
    const tmp = join(TEST_ROOT, 'upload-tmp.webp');
    await writeCandidatePng(tmp);
    await startReferenceGeneration(id, { target: 'turnaround' }, { tempPath: tmp, originalname: 'payload.html', ext: '.webp' });
    expect(enqueueJob.mock.calls[0][0].params.spriteRef.designReferencePath)
      .toMatch(/^reference\/uploads\/.+design-reference\.webp$/);
  });

  it('refuses the main and anchors before the turnaround is locked, and south always', async () => {
    const id = newId();
    await createCharacter(id);
    await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'x' });
    await expect(startReferenceGeneration(id, { target: 'main', designPrompt: 'x' }))
      .rejects.toMatchObject({ code: 'TURNAROUND_NOT_LOCKED', status: 409 });
    await expect(startReferenceGeneration(id, { target: 'east' }))
      .rejects.toMatchObject({ code: 'TURNAROUND_NOT_LOCKED', status: 409 });
    // 'south' is not a valid anchor target at all (schema also blocks it).
    await expect(startReferenceGeneration(id, { target: 'south' }))
      .rejects.toMatchObject({ code: 'INVALID_TARGET' });
  });

  it('refuses anchors between the turnaround lock and the main lock', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    await expect(startReferenceGeneration(id, { target: 'east' }))
      .rejects.toMatchObject({ code: 'MAIN_NOT_LOCKED', status: 409 });
  });

  it('derives the main from the locked turnaround via i2i', async () => {
    const id = newId();
    await createCharacter(id);
    await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'a wiry ranger' });
    enqueueJob.mockClear();
    await lockTurnaround(id);
    const result = await startReferenceGeneration(id, { target: 'main' });
    expect(result.anchorId).toBe('walk-south');
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.initImagePath).toContain(`${id}-turnaround-v1.png`);
    expect(call.params.initImageStrength).toBe(0.8);
    expect(call.params).toMatchObject({ width: 1024, height: 1024 });
    expect(call.params.prompt).toContain('turnaround model sheet');
    expect(call.params.prompt).toContain('facing the viewer (front)');
    // The design prompt persists from the turnaround step — the main render
    // still describes the character even though the body carried no prompt.
    expect(call.params.prompt).toContain('a wiry ranger');
  });

  it('400s a seed image sent with the main target once the sheet is locked', async () => {
    // The sheet IS the seed there, so a supplied one would be silently dropped
    // (the route allows an upload for `main` because a legacy record takes one).
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    const galleryName = 'fork-seed.png';
    await writeCandidatePng(join(TEST_ROOT, 'images', galleryName));
    await expect(startReferenceGeneration(id, { target: 'main', initImageGalleryFile: galleryName }))
      .rejects.toMatchObject({ code: 'SEED_NOT_APPLICABLE', status: 400 });
    const tmp = join(TEST_ROOT, 'main-seed-tmp.png');
    await writeCandidatePng(tmp);
    await expect(startReferenceGeneration(id, { target: 'main' }, { tempPath: tmp, originalname: 'concept.png' }))
      .rejects.toMatchObject({ code: 'SEED_NOT_APPLICABLE', status: 400 });
  });

  it('normalizes an unlocked legacy manifest to turnaround-first on read (#2996)', async () => {
    // A v1 draft has frozen nothing, so moving it onto the current standard
    // costs the user nothing — and it means no reachable main generate can
    // observe the old main-first flow.
    const id = newId();
    await createCharacter(id);
    await writeLegacyManifest(id); // schemaVersion 1, nothing locked
    const { manifest } = await getReferenceSet(id);
    expect(manifest.schemaVersion).toBe(2);
    expect(manifest.status).toBe('needs-turnaround');
    expect(manifest.turnaround).toMatchObject({ locked: false, role: 'identity-root' });
    await expect(startReferenceGeneration(id, { target: 'main', designPrompt: 'x' }))
      .rejects.toMatchObject({ code: 'TURNAROUND_NOT_LOCKED', status: 409 });
  });

  it('never normalizes — or rewrites — a legacy manifest holding a locked main', async () => {
    const id = newId();
    await createCharacter(id);
    await legacyLockedMain(id);
    const abs = join(TEST_ROOT, 'sprites', id, 'reference', `${id}-reference-set-v1.json`);
    const before = await readFile(abs, 'utf8');

    const { manifest } = await getReferenceSet(id);
    expect(manifest.schemaVersion).toBe(1);
    expect(manifest.turnaround).toBeUndefined();
    expect(manifest.chromaKey).toBe('#FF00FF');
    // Locked evidence is never rewritten as a side effect of a read.
    expect(await readFile(abs, 'utf8')).toBe(before);

    // …nor through a WRITE path: the backfill's generate saves the manifest, so
    // this is where an over-eager upgrade would actually land on disk.
    await startReferenceGeneration(id, { target: 'turnaround' });
    const afterWrite = JSON.parse(await readFile(abs, 'utf8'));
    expect(afterWrite.schemaVersion).toBe(1);
    expect(afterWrite.turnaround).toBeUndefined();
    expect(afterWrite.mainReference.locked).toBe(true);
    expect(afterWrite.chromaKey).toBe('#FF00FF');
  });

  it('derives anchors from the locked turnaround via i2i with the selected key in the prompt', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    enqueueJob.mockClear();
    const result = await startReferenceGeneration(id, { target: 'east' });
    expect(result.anchorId).toBe('walk-east');
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.initImagePath).toContain(`${id}-turnaround-v1.png`);
    expect(call.params.prompt).toContain('turnaround model sheet');
    expect(call.params.prompt).toContain('not multiple figures and not panels');
    // The queue's providers re-validate initImagePath through the approved
    // image-input roots — a sprite path must survive that gate or the i2i
    // silently degrades to text-to-image (identity drift).
    const { resolveImageInputPath } = await import('../../lib/fileUtils.js');
    expect(resolveImageInputPath(call.params.initImagePath)).toBe(call.params.initImagePath);
    expect(call.params.initImageStrength).toBe(0.8);
    expect(call.params.prompt).toContain('strict right-facing side profile');
    expect(call.params.prompt).toContain('magenta (#FF00FF)'); // green char kept magenta
  });

  it('threads a correction prompt into the anchor prompt and provenance tag', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    await startReferenceGeneration(id, { target: 'north-east', correctionPrompt: '  no pocket on the right sleeve  ' });
    const call = enqueueJob.mock.calls[0][0];
    expectCarriesCorrection(expect, call.params.prompt, 'no pocket on the right sleeve');
    // Trimmed and carried on the tag so the completion hook's sidecar records it.
    expect(call.params.spriteRef.correctionPrompt).toBe('no pocket on the right sleeve');
  });

  it('re-processes a specific turnaround candidate as the i2i seed with a correction', async () => {
    const id = newId();
    await createCharacter(id);
    const candidate = await placeCandidate(id, 'turnaround', 'turnaround-candidate-01.png');
    await startReferenceGeneration(id, {
      target: 'turnaround',
      initImageCandidate: candidate,
      correctionPrompt: 'add the missing pocket to the right sleeve',
    });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.initImagePath).toBe(join(TEST_ROOT, 'sprites', id, candidate));
    expect(call.params.initImageStrength).toBe(0.65);
    expectCarriesCorrection(expect, call.params.prompt, 'add the missing pocket to the right sleeve');
    expect(call.params.spriteRef).toMatchObject({
      designReferencePath: candidate,
      correctionPrompt: 'add the missing pocket to the right sleeve',
    });
  });

  it('rejects a non-turnaround candidate as a turnaround seed', async () => {
    const id = newId();
    await createCharacter(id);
    const candidate = await placeCandidate(id, 'east', 'walk-east-candidate-01.png');
    await expect(startReferenceGeneration(id, {
      target: 'turnaround', initImageCandidate: candidate,
    })).rejects.toMatchObject({ code: 'CANDIDATE_TARGET_MISMATCH', status: 400 });
  });

  it('threads a correction prompt into the main-reference derive and its tag (#3134)', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    enqueueJob.mockClear();
    await startReferenceGeneration(id, { target: 'main', correctionPrompt: '  the cloak hem is cut off  ' });
    const call = enqueueJob.mock.calls[0][0];
    expectCarriesCorrection(expect, call.params.prompt, 'the cloak hem is cut off');
    expect(call.params.spriteRef.correctionPrompt).toBe('the cloak hem is cut off');
  });

  it('leaves a blank main-reference correction byte-identical to a blind re-roll (#3134)', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    enqueueJob.mockClear();
    await startReferenceGeneration(id, { target: 'main' });
    const blind = enqueueJob.mock.calls[0][0].params.prompt;
    enqueueJob.mockClear();
    await startReferenceGeneration(id, { target: 'main', correctionPrompt: '   ' });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.prompt).toBe(blind);
    expect(call.params.spriteRef).not.toHaveProperty('correctionPrompt');
  });

  it('applies a correction alongside the ambient main\'s full-replace design prompt (#3134)', async () => {
    const id = 'grove-correction';
    await records.createRecord({ kind: 'place', name: 'Old Grove' }, id);
    enqueueJob.mockClear();
    await startReferenceGeneration(id, {
      target: 'main', designPrompt: 'a willow by a pond', correctionPrompt: '  the trunk leans too far right  ',
    });
    const call = enqueueJob.mock.calls[0][0];
    // Both inputs land: designPrompt replaces the design, the correction is additive.
    expect(call.params.prompt).toContain('Design: a willow by a pond');
    expectCarriesCorrection(expect, call.params.prompt, 'the trunk leans too far right');
    expect(call.params.spriteRef.correctionPrompt).toBe('the trunk leans too far right');

    enqueueJob.mockClear();
    await startReferenceGeneration(id, { target: 'main', designPrompt: 'a willow by a pond', correctionPrompt: '  ' });
    const blank = enqueueJob.mock.calls[0][0];
    expect(blank.params.prompt).not.toContain('Required fix');
    expect(blank.params.spriteRef).not.toHaveProperty('correctionPrompt');
  });

  it('omits the correction from the tag when blank', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    await startReferenceGeneration(id, { target: 'east', correctionPrompt: '   ' });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.prompt).not.toContain('Required fix');
    expect(call.params.spriteRef).not.toHaveProperty('correctionPrompt');
  });

  it('409s generation for a locked target', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    await expect(startReferenceGeneration(id, { target: 'main', designPrompt: 'x' }))
      .rejects.toMatchObject({ code: 'REFERENCE_LOCKED', status: 409 });

    const rel = await placeCandidate(id, 'east', 'walk-east-candidate-01.png');
    await lockReference(id, { target: 'east', candidate: rel });
    await expect(startReferenceGeneration(id, { target: 'east' }))
      .rejects.toMatchObject({ code: 'REFERENCE_LOCKED', status: 409 });
  });
});

describe('attachReferenceCandidate', () => {
  it('copies the render into candidates/ with a numbered name and sidecar', async () => {
    const id = newId();
    await createCharacter(id);
    await mkdir(join(TEST_ROOT, 'images'), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'images', 'render-1.png'));

    const ctx = {
      recordId: id, target: 'main', direction: 'south', anchorId: 'walk-south',
      chromaKey: '#FF00FF', mode: 'codex', model: 'm', jobId: 'j1',
      designPrompt: 'a ranger', filename: 'render-1.png',
    };
    // The notification must follow BOTH the asset and its provenance sidecar.
    const persisted = [];
    const onChanged = ({ recordId }) => {
      if (recordId === id) persisted.push(JSON.parse(readFileSync(
        join(TEST_ROOT, 'sprites', id, 'reference/candidates/walk-south-candidate-01.generation.json'), 'utf8',
      )));
    };
    spriteEvents.on('changed', onChanged);
    let first;
    try {
      first = await attachReferenceCandidate(ctx);
    } finally {
      spriteEvents.off('changed', onChanged);
    }
    expect(persisted).toHaveLength(1);
    expect(persisted[0].candidatePath).toBe(first.candidatePath);
    expect(first.candidatePath).toBe('reference/candidates/walk-south-candidate-01.png');
    const second = await attachReferenceCandidate(ctx);
    expect(second.candidatePath).toBe('reference/candidates/walk-south-candidate-02.png');

    const sidecar = JSON.parse(await readFile(
      join(TEST_ROOT, 'sprites', id, 'reference', 'candidates', 'walk-south-candidate-01.generation.json'), 'utf8',
    ));
    expect(sidecar).toMatchObject({
      kind: 'sprite-reference-generation', characterId: id, target: 'main',
      anchorId: 'walk-south', chromaKey: '#FF00FF', jobId: 'j1', designPrompt: 'a ranger',
    });
    expect(sidecar.model).toBe('m'); // tag model when the job carries none
    expect(sidecar.candidateSha256).toMatch(/^[0-9a-f]{64}$/);

    const { candidates } = await getReferenceSet(id);
    expect(candidates).toHaveLength(2);
    expect(candidates[0].target).toBe('main');
  });

  it('prefers the completed job\'s live model over the tag (Edit & Retry provenance)', async () => {
    const id = newId();
    await createCharacter(id);
    await mkdir(join(TEST_ROOT, 'images'), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'images', 'render-2.png'));
    await attachReferenceCandidate({
      recordId: id, target: 'main', direction: 'south', anchorId: 'walk-south',
      chromaKey: '#FF00FF', mode: 'codex', model: 'stale-tag-model', jobId: 'j2',
      filename: 'render-2.png', job: { params: { model: 'retried-model' } },
    });
    const sidecar = JSON.parse(await readFile(
      join(TEST_ROOT, 'sprites', id, 'reference', 'candidates', 'walk-south-candidate-01.generation.json'), 'utf8',
    ));
    expect(sidecar.model).toBe('retried-model');
  });

  it('reads a federated render\'s provenance through to the wire request', async () => {
    // A routed job blanks `params.prompt` and nulls `params.modelId` so a build
    // rolled back past `remoteMedia` fails closed (#4683) — reading them
    // directly would record a sidecar with no provenance at all.
    const id = newId();
    await createCharacter(id);
    await mkdir(join(TEST_ROOT, 'images'), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'images', 'render-remote.png'));
    await attachReferenceCandidate({
      recordId: id, target: 'main', direction: 'south', anchorId: 'walk-south',
      chromaKey: '#FF00FF', jobId: 'j-remote', filename: 'render-remote.png',
      job: {
        params: {
          prompt: '',
          modelId: null,
          remoteMedia: {
            wireVersion: 1,
            peerId: '00000000-0000-4000-8000-0000000004f1',
            request: { kind: 'image', engine: 'local', modelId: 'dev', prompt: 'a sprite facing south' },
          },
        },
      },
    });
    const sidecar = JSON.parse(await readFile(
      join(TEST_ROOT, 'sprites', id, 'reference', 'candidates', 'walk-south-candidate-01.generation.json'), 'utf8',
    ));
    expect(sidecar.model).toBe('dev');
    expect(sidecar.prompt).toBe('a sprite facing south');
  });

  it('records an anchor correction prompt in the sidecar as provenance', async () => {
    const id = newId();
    await createCharacter(id);
    await mkdir(join(TEST_ROOT, 'images'), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'images', 'render-3.png'));
    await attachReferenceCandidate({
      recordId: id, target: 'north-east', direction: 'north-east', anchorId: 'walk-north-east',
      chromaKey: '#FF00FF', mode: 'codex', model: 'm', jobId: 'j3',
      correctionPrompt: 'no pocket on the right sleeve', filename: 'render-3.png',
    });
    const sidecar = JSON.parse(await readFile(
      join(TEST_ROOT, 'sprites', id, 'reference', 'candidates', 'walk-north-east-candidate-01.generation.json'), 'utf8',
    ));
    expect(sidecar.correctionPrompt).toBe('no pocket on the right sleeve');
  });

  it('omits correctionPrompt from the sidecar when absent', async () => {
    const id = newId();
    await createCharacter(id);
    await mkdir(join(TEST_ROOT, 'images'), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'images', 'render-4.png'));
    await attachReferenceCandidate({
      recordId: id, target: 'east', direction: 'east', anchorId: 'walk-east',
      chromaKey: '#FF00FF', mode: 'codex', model: 'm', jobId: 'j4', filename: 'render-4.png',
    });
    const sidecar = JSON.parse(await readFile(
      join(TEST_ROOT, 'sprites', id, 'reference', 'candidates', 'walk-east-candidate-01.generation.json'), 'utf8',
    ));
    expect(sidecar).not.toHaveProperty('correctionPrompt');
  });

  it('returns null when the gallery file is gone', async () => {
    const id = newId();
    await createCharacter(id);
    expect(await attachReferenceCandidate({
      recordId: id, target: 'main', anchorId: 'walk-south', filename: 'vanished.png',
    })).toBeNull();
  });
});

describe('lockReference — turnaround (#2979)', () => {
  it('locks the sheet: freezes the key off its holistic palette and advances the status', async () => {
    const id = newId();
    await createCharacter(id);
    const result = await lockTurnaround(id);

    expect(result.manifest.turnaround.locked).toBe(true);
    expect(result.manifest.turnaround.path).toBe(`reference/${id}-turnaround-v1.png`);
    expect(result.manifest.turnaround.sha256).toMatch(/^[0-9a-f]{64}$/);
    expect(result.manifest.turnaround.role).toBe('identity-root');
    expect(result.manifest.turnaround.views).toEqual(['south', 'east', 'north', 'west']);
    // The sheet, not the main, is what chooses the canonical key now.
    expect(result.manifest.chromaKey).toBe('#FF00FF'); // green char → magenta kept
    expect(result.manifest.chromaKeyAutoSelected).toBe(true);
    expect(result.manifest.status).toBe('needs-main-reference');
    expect(result.manifest.mainReference.locked).toBe(false);

    const record = await records.getRecord(id);
    expect(record.chromaKey).toBe('#FF00FF');
    expect(record.status).toBe('reference');
  });

  it('re-keys the sheet without reframing it to a single-figure square', async () => {
    const id = newId();
    await createCharacter(id, { chromaKey: '#0000FF' }); // pin, so lock re-keys
    const rel = await placeCandidate(id, 'turnaround', 'turnaround-candidate-01.png');
    await lockReference(id, { target: 'turnaround', candidate: rel });
    // The fixture candidate is 64×64; normalizeFromAnalysis would rebuild it
    // around the 10×30 figure bbox. recompositeOnKey must leave it alone.
    const meta = await sharp(join(TEST_ROOT, 'sprites', id, `reference/${id}-turnaround-v1.png`)).metadata();
    expect([meta.width, meta.height]).toEqual([64, 64]);
  });

  it('409s a clip-risk sheet lock until accepted', async () => {
    const id = newId();
    await createCharacter(id);
    // A magenta-ish character on the magenta generation key: near-key detail is
    // already masked away, so locking it is lossy.
    const rel = await placeCandidate(id, 'turnaround', 'turnaround-candidate-01.png', {
      fg: { r: 255, g: 80, b: 230 }, // pink outfit near the magenta key
    });
    await expect(lockReference(id, { target: 'turnaround', candidate: rel }))
      .rejects.toMatchObject({ status: 409, code: 'CHROMA_CLIP_RISK' });
    const accepted = await lockReference(id, { target: 'turnaround', candidate: rel, acceptClipRisk: true });
    expect(accepted.manifest.turnaround.locked).toBe(true);
  });

  it('409s a relock and enforces the candidate filename prefix', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    const second = await placeCandidate(id, 'turnaround', 'turnaround-candidate-02.png');
    await expect(lockReference(id, { target: 'turnaround', candidate: second }))
      .rejects.toMatchObject({ status: 409, code: 'REFERENCE_LOCKED' });

    const other = newId();
    await createCharacter(other);
    const mismatched = await placeCandidate(other, 'turnaround', 'walk-east-candidate-01.png');
    await expect(lockReference(other, { target: 'turnaround', candidate: mismatched }))
      .rejects.toMatchObject({ status: 400, code: 'CANDIDATE_TARGET_MISMATCH' });
  });

  it('does not reselect the key when the main lock already froze one (legacy backfill)', async () => {
    const id = newId();
    await createCharacter(id);
    await legacyLockedMain(id);
    const before = await getReferenceSet(id);
    expect(before.manifest.schemaVersion).toBe(1);
    expect(before.manifest.chromaKey).toBe('#FF00FF');
    const recordBefore = await records.getRecord(id);

    const result = await lockTurnaround(id);
    expect(result.manifest.turnaround.locked).toBe(true);
    // Key stays exactly as the main lock froze it, and the legacy manifest is
    // NOT silently upgraded to the turnaround-first schema.
    expect(result.manifest.chromaKey).toBe('#FF00FF');
    expect(result.manifest.schemaVersion).toBe(1);
    // A backfill has nothing to say about the record — the main lock set it.
    const recordAfter = await records.getRecord(id);
    expect(recordAfter.chromaKey).toBe(recordBefore.chromaKey);
    expect(recordAfter.status).toBe(recordBefore.status);
  });

  it('unblocks anchor derivation on a legacy record once the sheet is backfilled', async () => {
    const id = newId();
    await createCharacter(id);
    await legacyLockedMain(id);
    await expect(startReferenceGeneration(id, { target: 'east' }))
      .rejects.toMatchObject({ code: 'TURNAROUND_NOT_LOCKED', status: 409 });
    await lockTurnaround(id);
    enqueueJob.mockClear();
    await startReferenceGeneration(id, { target: 'east' });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.initImagePath).toContain(`${id}-turnaround-v1.png`);
    expect(call.params.prompt).toContain('turnaround model sheet');
  });

  it('freezes the key against a post-turnaround repin', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    await expect(patchSpriteRecord(id, { chromaKey: '#00FF00' }))
      .rejects.toMatchObject({ status: 409, code: 'CHROMA_KEY_LOCKED' });
  });

  it('groups a sidecarless turnaround candidate under its own target', async () => {
    const id = newId();
    await createCharacter(id);
    const candDir = join(TEST_ROOT, 'sprites', id, 'reference', 'candidates');
    await mkdir(candDir, { recursive: true });
    await writeCandidatePng(join(candDir, 'turnaround-candidate-01.png')); // no sidecar
    const { candidates } = await getReferenceSet(id);
    expect(candidates.find((c) => c.path.endsWith('turnaround-candidate-01.png')).target).toBe('turnaround');
  });
});

describe('lockReference', () => {
  it('does not reselect the key when the sheet already froze one', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    // A magenta-ish main would auto-select AWAY from magenta if the main lock
    // still ran selection — it must inherit the sheet's frozen key instead.
    const rel = await placeCandidate(id, 'main', 'walk-south-candidate-01.png', {
      fg: { r: 255, g: 80, b: 230 },
    });
    const result = await lockReference(id, { target: 'main', candidate: rel, acceptClipRisk: true });
    expect(result.manifest.chromaKey).toBe('#FF00FF');
    expect(result.manifest.mainReference.clipWarning).toMatch(/generation key #FF00FF/);
  });

  it('locks the main: normalizes, auto-selects the chroma key, freezes the manifest + record', async () => {
    const id = newId();
    await createCharacter(id);
    const result = await lockMain(id);

    expect(result.manifest.mainReference.locked).toBe(true);
    expect(result.manifest.mainReference.path).toBe(`reference/${id}-walk-south-v1.png`);
    expect(result.manifest.mainReference.sha256).toMatch(/^[0-9a-f]{64}$/);
    expect(result.manifest.chromaKey).toBe('#FF00FF'); // green char → magenta kept
    expect(result.manifest.chromaKeyAutoSelected).toBe(true);
    expect(result.manifest.status).toBe('in-progress');
    const south = result.manifest.anchors.find((a) => a.id === 'walk-south');
    expect(south.status).toBe('locked');

    const record = await records.getRecord(id);
    expect(record.chromaKey).toBe('#FF00FF');
    expect(record.status).toBe('reference');
  });

  it('409s a clip-risk main lock until accepted, then selects away from the clashing key', async () => {
    const id = newId();
    await createCharacter(id);
    const rel = await placeCandidate(id, 'main', 'walk-south-candidate-01.png', {
      fg: { r: 255, g: 80, b: 230 }, // pink/magenta outfit near the magenta key
    });
    // The freeze is irreversible — a clip-risk lock must be refused until
    // the user explicitly locks through it.
    await expect(lockReference(id, { target: 'main', candidate: rel }))
      .rejects.toMatchObject({ status: 409, code: 'CHROMA_CLIP_RISK' });
    let manifest = (await getReferenceSet(id)).manifest;
    expect(manifest?.mainReference?.locked ?? false).toBe(false);

    const result = await lockReference(id, { target: 'main', candidate: rel, acceptClipRisk: true });
    expect(result.manifest.mainReference.locked).toBe(true);
    expect(result.manifest.chromaKey).not.toBe('#FF00FF');
    const record = await records.getRecord(id);
    expect(record.chromaKey).toBe(result.manifest.chromaKey);
    // The accepted risk stays visible on the manifest.
    expect(result.manifest.chromaKeyWarning).toMatch(/generation key #FF00FF/);
  });

  it('honors a legacy lowercase pinned key at lock time (phase-1 records)', async () => {
    const id = newId();
    await createCharacter(id);
    await records.updateRecord(id, { chromaKey: '#0000ff' }); // phase-1 stored any-case hex
    const result = await lockMain(id);
    expect(result.manifest.chromaKey).toBe('#0000FF');
    expect(result.manifest.chromaKeyAutoSelected).toBe(false);
  });

  it('409s a lock whose PINNED key collides with the surviving palette', async () => {
    const id = newId();
    await createCharacter(id);
    // Leaf-green clothing (hue ~138 after quantization) + user pins the
    // green key (hue 120): compositing onto green would make runtime keying
    // eat the clothing.
    await records.updateRecord(id, { chromaKey: '#00FF00' });
    const rel = await placeCandidate(id, 'main', 'walk-south-candidate-01.png', {
      fg: { r: 40, g: 200, b: 80 }, // green clothing on the magenta gen key
    });
    await expect(lockReference(id, { target: 'main', candidate: rel }))
      .rejects.toMatchObject({ status: 409, code: 'CHROMA_CLIP_RISK' });
    const accepted = await lockReference(id, { target: 'main', candidate: rel, acceptClipRisk: true });
    expect(accepted.manifest.chromaKey).toBe('#00FF00');
    expect(accepted.manifest.chromaKeyWarning).toMatch(/selected key #00FF00/);
  });

  it('gates anchor locks on clip risk against the canonical key', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id); // teal char → magenta key
    // This facing reveals a pink feature near the magenta generation key.
    const rel = await placeCandidate(id, 'east', 'walk-east-candidate-01.png', {
      fg: { r: 255, g: 80, b: 230 },
    });
    await expect(lockReference(id, { target: 'east', candidate: rel }))
      .rejects.toMatchObject({ status: 409, code: 'CHROMA_CLIP_RISK' });
    const accepted = await lockReference(id, { target: 'east', candidate: rel, acceptClipRisk: true });
    const east = accepted.manifest.anchors.find((a) => a.id === 'walk-east');
    expect(east.status).toBe('locked');
    expect(east.clipWarning).toMatch(/generation key #FF00FF/);
  });

  it('threads the saved local model into local-mode renders and provenance', async () => {
    const id = newId();
    await createCharacter(id);
    await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'x', mode: 'local' });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.mode).toBe('local');
    expect(call.params.modelId).toBe('flux-dev-4bit');
    expect(call.params.spriteRef.model).toBe('flux-dev-4bit');
  });

  it('falls through an incompatible record pin to the compatible install pin', async () => {
    const id = newId();
    await createCharacter(id, { imageMode: 'local', imageModelId: 'record-incompatible' });

    await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'example design' });

    const { params } = enqueueJob.mock.calls[0][0];
    expect(params.modelId).toBe('flux-dev-4bit');
    expect(params.spriteRef.model).toBe('flux-dev-4bit');
  });

  it('rebases legacy repo-root manifest paths from a phase-1 import', async () => {
    const id = newId();
    await createCharacter(id);
    const refDir = join(TEST_ROOT, 'sprites', id, 'reference');
    await mkdir(refDir, { recursive: true });
    await writeCandidatePng(join(refDir, `${id}-walk-south-v1.png`));
    await writeFile(join(refDir, `${id}-reference-set-v1.json`), JSON.stringify({
      schemaVersion: 1,
      status: 'in-progress',
      chromaKey: '#FF00FF',
      mainReference: { path: `art-source/sprites/${id}/reference/${id}-walk-south-v1.png`, locked: true },
      anchors: [
        { id: 'walk-south', direction: 'south', status: 'locked', path: `art-source/sprites/${id}/reference/${id}-walk-south-v1.png` },
        { id: 'walk-east', direction: 'east', status: 'pending', source: 'derive-from-main' },
      ],
    }));

    const { manifest } = await getReferenceSet(id);
    expect(manifest.mainReference.path).toBe(`reference/${id}-walk-south-v1.png`);
    expect(manifest.anchors[0].path).toBe(`reference/${id}-walk-south-v1.png`);

    // An imported record is main-first with no sheet, so anchors are gated on
    // the backfill — which must resolve the REBASED main as its i2i init.
    await expect(startReferenceGeneration(id, { target: 'east' }))
      .rejects.toMatchObject({ code: 'TURNAROUND_NOT_LOCKED', status: 409 });
    const result = await startReferenceGeneration(id, { target: 'turnaround' });
    expect(result.anchorId).toBe('turnaround');
    expect(enqueueJob.mock.calls[0][0].params.initImagePath).toBe(join(TEST_ROOT, 'sprites', id, `reference/${id}-walk-south-v1.png`));
  });

  it('respects a user-pinned key instead of auto-selecting', async () => {
    const id = newId();
    await createCharacter(id);
    await records.updateRecord(id, { chromaKey: '#0000FF' });
    const result = await lockMain(id);
    expect(result.manifest.chromaKey).toBe('#0000FF');
    expect(result.manifest.chromaKeyAutoSelected).toBe(false);
  });

  it('409s a relock and enforces candidate/target agreement', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    const rel = await placeCandidate(id, 'main', 'walk-south-candidate-02.png');
    await expect(lockReference(id, { target: 'main', candidate: rel }))
      .rejects.toMatchObject({ code: 'REFERENCE_LOCKED', status: 409 });

    const eastRel = await placeCandidate(id, 'east', 'walk-east-candidate-01.png');
    await expect(lockReference(id, { target: 'west', candidate: eastRel }))
      .rejects.toMatchObject({ code: 'CANDIDATE_TARGET_MISMATCH' });
  });

  it('refuses a sidecarless candidate whose filename does not match the target', async () => {
    const id = newId();
    await createCharacter(id);
    // Crash between PNG copy and sidecar write: PNG exists, no provenance.
    const candDir = join(TEST_ROOT, 'sprites', id, 'reference', 'candidates');
    await mkdir(candDir, { recursive: true });
    await writeCandidatePng(join(candDir, 'walk-east-candidate-01.png'));
    await expect(lockReference(id, { target: 'main', candidate: 'reference/candidates/walk-east-candidate-01.png' }))
      .rejects.toMatchObject({ code: 'CANDIDATE_TARGET_MISMATCH' });
    // And the reference-set view infers its target from the filename so the
    // client can't group it under main.
    const { candidates } = await getReferenceSet(id);
    expect(candidates[0].target).toBe('east');
  });

  it('refuses candidates outside reference/candidates/ and traversal paths', async () => {
    const id = newId();
    await createCharacter(id);
    await expect(lockReference(id, { target: 'main', candidate: 'runtime/sneaky.png' }))
      .rejects.toMatchObject({ code: 'INVALID_CANDIDATE' });
    await expect(lockReference(id, { target: 'main', candidate: 'reference/candidates/../../../escape.png' }))
      .rejects.toMatchObject({ code: 'INVALID_ASSET_PATH' });
  });

  it('patchSpriteRecord allows a key change pre-lock and 409s it post-lock', async () => {
    const id = newId();
    await createCharacter(id);
    const patched = await patchSpriteRecord(id, { chromaKey: '#0000FF' });
    expect(patched.chromaKey).toBe('#0000FF');
    await patchSpriteRecord(id, { chromaKey: null }); // back to auto so lockMain selects
    await lockMain(id);
    await expect(patchSpriteRecord(id, { chromaKey: '#00FF00' }))
      .rejects.toMatchObject({ status: 409, code: 'CHROMA_KEY_LOCKED' });
    // Non-key fields stay patchable after lock.
    const notes = await patchSpriteRecord(id, { notes: 'still editable' });
    expect(notes.notes).toBe('still editable');
  });

  it('refuses to recreate a character over a tombstoned id', async () => {
    const id = newId();
    await records.createCharacter({ id, name: 'Hero' });
    await records.deleteRecord(id);
    await expect(records.createCharacter({ id, name: 'Hero' }))
      .rejects.toMatchObject({ status: 409, code: 'ID_TOMBSTONED' });
  });

  it('never overwrites an existing versioned artifact (crash-recovery lands on v2)', async () => {
    const id = newId();
    await createCharacter(id);
    // Simulate a crash that wrote v1 but never updated the manifest.
    const refDir = join(TEST_ROOT, 'sprites', id, 'reference');
    await mkdir(refDir, { recursive: true });
    await writeFile(join(refDir, `${id}-walk-south-v1.png`), 'stale-bytes');
    const result = await lockMain(id);
    expect(result.manifest.mainReference.path).toBe(`reference/${id}-walk-south-v2.png`);
    expect(await readFile(join(refDir, `${id}-walk-south-v1.png`), 'utf8')).toBe('stale-bytes');
  });

  it('reopens one anchor, preserves v1, derives from the turnaround, and locks the replacement as v2', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    const firstCandidate = await placeCandidate(id, 'east', 'walk-east-candidate-01.png');
    const firstLock = await lockReference(id, { target: 'east', candidate: firstCandidate });
    const firstAnchor = firstLock.manifest.anchors.find((a) => a.direction === 'east');
    const firstBytes = await readFile(join(TEST_ROOT, 'sprites', id, firstAnchor.path));

    const reopened = await unlockReferenceAnchor(id, { direction: 'east' });
    const pending = reopened.manifest.anchors.find((a) => a.direction === 'east');
    expect(pending).toMatchObject({ status: 'pending', source: 'derive-from-turnaround' });
    // loadManifest normalizes every anchor with a `path` key, so the cleared
    // manifest pointer reads back as undefined rather than an absent property.
    expect(pending.path).toBeUndefined();
    expect(pending).not.toHaveProperty('sha256');
    expect(reopened.manifest.status).toBe('in-progress');
    expect(await readFile(join(TEST_ROOT, 'sprites', id, firstAnchor.path))).toEqual(firstBytes);
    expect((await records.getRecord(id)).status).toBe('reference');

    await startReferenceGeneration(id, { target: 'east' });
    expect(enqueueJob.mock.calls[0][0].params.initImagePath).toBe(
      join(TEST_ROOT, 'sprites', id, reopened.manifest.turnaround.path),
    );

    const secondCandidate = await placeCandidate(id, 'east', 'walk-east-candidate-02.png');
    const secondLock = await lockReference(id, { target: 'east', candidate: secondCandidate });
    expect(secondLock.manifest.anchors.find((a) => a.direction === 'east').path)
      .toBe(`reference/${id}-walk-east-v2.png`);
    expect(await readFile(join(TEST_ROOT, 'sprites', id, firstAnchor.path))).toEqual(firstBytes);
  });

  it('refuses to reopen south or an anchor that is already pending', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    await expect(unlockReferenceAnchor(id, { direction: 'south' }))
      .rejects.toMatchObject({ status: 400, code: 'INVALID_TARGET' });
    await expect(unlockReferenceAnchor(id, { direction: 'east' }))
      .rejects.toMatchObject({ status: 409, code: 'ANCHOR_NOT_LOCKED' });
  });

  it('reopens the main and south anchor while retaining the turnaround and other anchors', async () => {
    const id = newId();
    await createCharacter(id);
    const first = await lockMain(id);
    const eastCandidate = await placeCandidate(id, 'east', 'walk-east-candidate-01.png');
    const withEast = await lockReference(id, { target: 'east', candidate: eastCandidate });
    const oldMainPath = first.manifest.mainReference.path;
    const oldEastPath = withEast.manifest.anchors.find((anchor) => anchor.direction === 'east').path;

    const reopened = await unlockReferenceMain(id);
    expect(reopened.manifest).toMatchObject({
      status: 'needs-main-reference',
      turnaround: { locked: true },
      mainReference: { locked: false, path: null },
    });
    expect(reopened.manifest.anchors.find((anchor) => anchor.direction === 'south'))
      .toMatchObject({ status: 'pending', source: 'main-reference' });
    expect(reopened.manifest.anchors.find((anchor) => anchor.direction === 'east'))
      .toMatchObject({ status: 'locked', path: oldEastPath });
    expect(await readFile(join(TEST_ROOT, 'sprites', id, oldMainPath))).toBeTruthy();

    await startReferenceGeneration(id, { target: 'main' });
    const replacement = await placeCandidate(id, 'main', 'walk-south-candidate-02.png');
    const relocked = await lockReference(id, { target: 'main', candidate: replacement });
    expect(relocked.manifest.mainReference.path).toBe(`reference/${id}-walk-south-v2.png`);
  });

  it('refuses to reopen a main reference without a locked turnaround', async () => {
    const id = newId();
    await createCharacter(id);
    await expect(unlockReferenceMain(id))
      .rejects.toMatchObject({ status: 409, code: 'TURNAROUND_NOT_LOCKED' });
  });

  it('reopens the full turnaround chain, preserves v1 evidence, and relocks the sheet as v2', async () => {
    const id = newId();
    await createCharacter(id);
    const first = await lockMain(id);
    const eastCandidate = await placeCandidate(id, 'east', 'walk-east-candidate-01.png');
    const withEast = await lockReference(id, { target: 'east', candidate: eastCandidate });
    const oldPaths = [
      withEast.manifest.turnaround.path,
      first.manifest.mainReference.path,
      withEast.manifest.anchors.find((anchor) => anchor.direction === 'east').path,
    ];
    const oldBytes = await Promise.all(oldPaths.map(
      (path) => readFile(join(TEST_ROOT, 'sprites', id, path)),
    ));

    const reopened = await unlockReferenceTurnaround(id);
    expect(reopened.manifest).toMatchObject({
      status: 'needs-turnaround',
      chromaKey: null,
      turnaround: { locked: false, path: null },
      mainReference: { locked: false, path: null },
    });
    expect(reopened.manifest.anchors).toHaveLength(8);
    expect(reopened.manifest.anchors.every((anchor) => anchor.status === 'pending')).toBe(true);
    expect((await records.getRecord(id))).toMatchObject({ status: 'reference', chromaKey: null });
    for (let i = 0; i < oldPaths.length; i++) {
      expect(await readFile(join(TEST_ROOT, 'sprites', id, oldPaths[i]))).toEqual(oldBytes[i]);
    }

    const replacement = await placeCandidate(id, 'turnaround', 'turnaround-candidate-02.png');
    const relocked = await lockReference(id, { target: 'turnaround', candidate: replacement });
    expect(relocked.manifest.turnaround.path).toBe(`reference/${id}-turnaround-v2.png`);
  });

  it('preserves an explicitly pinned chroma key when reopening the turnaround', async () => {
    const id = newId();
    await createCharacter(id);
    await records.updateRecord(id, { chromaKey: '#0000FF' });
    await lockMain(id);

    const reopened = await unlockReferenceTurnaround(id);
    expect(reopened.manifest.chromaKey).toBeNull();
    expect((await records.getRecord(id)).chromaKey).toBe('#0000FF');
  });

  it('refuses to reopen a turnaround that is not locked', async () => {
    const id = newId();
    await createCharacter(id);
    await expect(unlockReferenceTurnaround(id))
      .rejects.toMatchObject({ status: 409, code: 'TURNAROUND_NOT_LOCKED' });
  });

  it('completes the set when the last anchor locks', async () => {
    const id = newId();
    await createCharacter(id);
    await lockMain(id);
    const { ANCHOR_DIRECTIONS } = await import('./prompts.js');
    for (const direction of ANCHOR_DIRECTIONS) {
      const rel = await placeCandidate(id, direction, `walk-${direction}-candidate-01.png`);
      await lockReference(id, { target: direction, candidate: rel });
    }
    const { manifest } = await getReferenceSet(id);
    expect(manifest.status).toBe('complete');
    expect(manifest.anchors.every((a) => a.status === 'locked')).toBe(true);
    const record = await records.getRecord(id);
    expect(record.status).toBe('reference-complete');
  });
});

describe('turnaround i2i seed sources', () => {
  it('seeds the turnaround from a gallery image (initImageGalleryFile)', async () => {
    const id = newId();
    await createCharacter(id);
    // resolveGalleryImage resolves a basename under PATHS.images (the test root).
    const galleryName = 'render-history-pick.png';
    await writeCandidatePng(join(TEST_ROOT, 'images', galleryName));
    await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'red coat', initImageGalleryFile: galleryName });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.initImagePath).toBe(join(TEST_ROOT, 'images', galleryName));
    expect(call.params.initImageStrength).toBe(0.65);
    expect(call.params.spriteRef.designReferencePath).toBe(`gallery:${galleryName}`);
  });

  it('400s a gallery pick that is not in the gallery', async () => {
    const id = newId();
    await createCharacter(id);
    await expect(startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'x', initImageGalleryFile: 'ghost.png' }))
      .rejects.toMatchObject({ code: 'INIT_IMAGE_NOT_FOUND', status: 400 });
  });

  it('seeds from another sprite\'s locked turnaround, preferring the sheet over its main', async () => {
    const source = newId();
    await createCharacter(source);
    await lockMain(source); // locks the sheet AND the main
    const dest = newId();
    await createCharacter(dest);
    enqueueJob.mockClear();
    await startReferenceGeneration(dest, { target: 'turnaround', designPrompt: 'now with a hat', initImageSpriteId: source });
    const call = enqueueJob.mock.calls[0][0];
    // The sheet carries every side, so a derive inherits accessory placement.
    expect(call.params.initImagePath).toBe(join(TEST_ROOT, 'sprites', source, `reference/${source}-turnaround-v1.png`));
    expect(call.params.spriteRef.designReferencePath).toBe(`sprite:${source}/reference/${source}-turnaround-v1.png`);
  });

  it('falls back to a legacy source\'s locked main when it has no sheet', async () => {
    const source = newId();
    await createCharacter(source);
    await legacyLockedMain(source);
    const dest = newId();
    await createCharacter(dest);
    enqueueJob.mockClear();
    await startReferenceGeneration(dest, { target: 'turnaround', designPrompt: 'x', initImageSpriteId: source });
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.initImagePath).toBe(join(TEST_ROOT, 'sprites', source, `reference/${source}-walk-south-v1.png`));
  });

  it('400s seeding from a source with no locked reference', async () => {
    const source = newId();
    await createCharacter(source); // never locked
    const dest = newId();
    await createCharacter(dest);
    await expect(startReferenceGeneration(dest, { target: 'turnaround', designPrompt: 'x', initImageSpriteId: source }))
      .rejects.toMatchObject({ code: 'SOURCE_REFERENCE_MISSING', status: 400 });
  });
});

describe('listReferenceSources', () => {
  it('returns characters with a locked reference, preferring the turnaround sheet', async () => {
    const locked = newId();
    await createCharacter(locked, { name: 'Locked One' });
    await lockMain(locked);
    const legacy = newId();
    await createCharacter(legacy, { name: 'Legacy One' });
    await legacyLockedMain(legacy);
    const draft = newId();
    await createCharacter(draft, { name: 'Draft One' }); // nothing locked
    const sources = await listReferenceSources();
    const ids = sources.map((s) => s.id);
    expect(ids).toContain(locked);
    expect(ids).toContain(legacy);
    expect(ids).not.toContain(draft);
    const entry = sources.find((s) => s.id === locked);
    expect(entry).toMatchObject({ id: locked, name: 'Locked One', kind: 'character' });
    expect(entry.path).toContain(`${locked}-turnaround-v1.png`);
    expect(entry.turnaroundPath).toContain(`${locked}-turnaround-v1.png`);
    // A legacy source is still seedable — it just has no sheet to advertise.
    const legacyEntry = sources.find((s) => s.id === legacy);
    expect(legacyEntry.path).toContain(`${legacy}-walk-south-v1.png`);
    expect(legacyEntry.turnaroundPath).toBeNull();
  });
});

describe('listSpriteThumbnails', () => {
  it('uses a locked character main, an on-disk asset for other kinds, and omits imageless records', async () => {
    // Character with a locked main → its canonical main-reference path (no
    // asset scan needed).
    const hero = newId();
    await createCharacter(hero, { name: 'Hero One' });
    await lockMain(hero);

    // A place with an on-disk previewable image → that asset.
    const place = 'saloon-thumb';
    await records.createRecord({ kind: 'place', name: 'Saloon' }, place);
    await mkdir(join(TEST_ROOT, 'sprites', place), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'sprites', place, 'establishing.png'));

    // A character with NO locked main but an asset → falls back to the asset.
    const drafted = newId();
    await createCharacter(drafted, { name: 'Draft Two' });
    await mkdir(join(TEST_ROOT, 'sprites', drafted), { recursive: true });
    await writeCandidatePng(join(TEST_ROOT, 'sprites', drafted, 'sketch.png'));

    // An object with no image at all → omitted entirely.
    const empty = 'crate-thumb';
    await records.createRecord({ kind: 'object', name: 'Crate' }, empty);

    const thumbs = await listSpriteThumbnails();
    const byId = Object.fromEntries(thumbs.map((t) => [t.id, t.path]));

    expect(byId[hero]).toContain(`${hero}-walk-south-v1.png`);
    expect(byId[place]).toBe('establishing.png');
    expect(byId[drafted]).toBe('sketch.png');
    expect(byId).not.toHaveProperty(empty);
  });
});

/**
 * #3331 — the seeded reference paths (main, anchors, forks) are all i2i, so
 * they used to be closed to agy. Its `generate_image` tool takes input images
 * through `ImagePaths`, so every queueable backend can now run them: neither an
 * explicit request-level pick nor a record pin is diverted.
 */
describe('input-image backends on the seeded reference paths (#3331)', () => {
  it('runs an explicitly requested agy render on a seeded (i2i) target', async () => {
    const id = newId();
    await createCharacter(id);
    await lockTurnaround(id);
    enqueueJob.mockClear();
    // The main always derives from the locked sheet, so this render is i2i.
    const { mode } = await startReferenceGeneration(id, { target: 'main', mode: 'agy' });
    expect(mode).toBe('agy');
    expect(enqueueJob.mock.calls.at(-1)[0].params.mode).toBe('agy');
    // The seed still rides along — the backend consumes it as its input image.
    expect(enqueueJob.mock.calls.at(-1)[0].params.initImagePath).toBeTruthy();
  });

  it('runs an explicitly requested agy render for a from-scratch turnaround', async () => {
    const id = newId();
    await createCharacter(id);
    const result = await startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'a wiry ranger', mode: 'agy' });
    expect(result.mode).toBe('agy');
    expect(enqueueJob.mock.calls.at(-1)[0].params.mode).toBe('agy');
  });

  it('honors a record PIN on a seeded render instead of diverting it', async () => {
    const id = newId();
    await createCharacter(id, { imageMode: 'agy' });
    await lockTurnaround(id);
    enqueueJob.mockClear();
    const { mode } = await startReferenceGeneration(id, { target: 'main' });
    expect(mode).toBe('agy');
    expect(enqueueJob.mock.calls.at(-1)[0].params.mode).toBe('agy');
  });
});

describe('forkSprite', () => {
  it('creates a new character and queues its turnaround seeded from the source sheet', async () => {
    const source = newId();
    await createCharacter(source, { name: 'Origin' });
    await lockMain(source);
    enqueueJob.mockClear();
    const { record, jobId, target } = await forkSprite(source, {
      name: 'Origin Fork',
      designPrompt: 'wearing a red coat',
      model: 'openai/gpt-image-1',
    });
    // A fork enters the same turnaround-first workflow every new character does.
    expect(target).toBe('turnaround');
    expect(jobId).toBe('job-1234567890');
    expect(record.kind).toBe('character');
    expect(record.name).toBe('Origin Fork');
    expect(record.imageModelId).toBe('openai/gpt-image-1');
    // The new record exists and the render was seeded from the source's ref.
    expect(await records.getRecord(record.id)).toBeTruthy();
    const call = enqueueJob.mock.calls[0][0];
    expect(call.params.spriteRef.recordId).toBe(record.id);
    expect(call.params.initImagePath).toBe(join(TEST_ROOT, 'sprites', source, `reference/${source}-turnaround-v1.png`));
  });

  it('forks onto agy, seeding the render from the source reference', async () => {
    const source = newId();
    await createCharacter(source, { name: 'Origin' });
    await lockMain(source);
    enqueueJob.mockClear();
    // A fork ALWAYS seeds from the source reference, which used to close agy
    // out of the fork picker entirely (#3331). Its ImagePaths parameter takes
    // that seed, so the fork runs and the chosen backend is persisted as the
    // new record's render pin.
    const { record } = await forkSprite(source, { name: 'Agy Fork', designPrompt: 'x', mode: 'agy' });
    expect(record.imageMode).toBe('agy');
    expect(enqueueJob.mock.calls.at(-1)[0].params.mode).toBe('agy');
    expect(enqueueJob.mock.calls.at(-1)[0].params.initImagePath).toBeTruthy();
  });

  it('400s forking a source with no locked main and creates no orphan record', async () => {
    const source = newId();
    await createCharacter(source);
    const before = (await records.listRecords()).length;
    await expect(forkSprite(source, { name: 'Bad Fork', designPrompt: 'x' }))
      .rejects.toMatchObject({ code: 'SOURCE_REFERENCE_MISSING', status: 400 });
    // The invariant this test names: the source is resolved BEFORE the record is
    // created, so a rejected fork leaves no orphan character behind.
    expect((await records.listRecords()).length).toBe(before);
  });
});

describe('unreadable reference manifest', () => {
  it('refuses generation on a damaged manifest and retries after repair', async () => {
    const id = newId();
    await createCharacter(id);
    const dir = join(TEST_ROOT, 'sprites', id, 'reference');
    await mkdir(dir, { recursive: true });
    const path = join(dir, `${id}-reference-set-v1.json`);
    await writeFile(path, '{');
    await expect(startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'a ranger' })).rejects.toThrow(/Unreadable/);
    expect(await readFile(path, 'utf8')).toBe('{');
    await writeFile(path, JSON.stringify({ schemaVersion: 2, characterId: id, anchors: [], turnaround: { locked: false }, mainReference: { locked: false } }));
    await expect(startReferenceGeneration(id, { target: 'turnaround', designPrompt: 'a ranger' })).resolves.toMatchObject({ target: 'turnaround' });
  });
});


it('keeps catalog projections available when one reference manifest is unreadable', async () => {
  const damaged = newId();
  await createCharacter(damaged);
  const dir = join(TEST_ROOT, 'sprites', damaged, 'reference');
  await mkdir(dir, { recursive: true });
  const path = join(dir, `${damaged}-reference-set-v1.json`);
  await writeFile(path, '{');
  await expect(listReferenceSources()).resolves.toEqual([]);
  await expect(listSpriteThumbnails()).resolves.toEqual([]);
  expect(await readFile(path, 'utf8')).toBe('{');
});