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

45.0 KB
Raw Blame
/**
 * Publish-to-managed-app (#2898): binding validation (app existence, repo
 * anchoring, traversal refusal), atomic destination replace, diverged-
 * destination refusal, idempotent re-publish, occurrence-count-guarded code
 * binding verify/rewrite, and the publish history. The atlas compiler is
 * mocked (covered by atlas.test.js) — these tests own everything after it.
 *
 * Also covers the export contract (#2982): the optional runtimeContract's
 * shape validation, the publish-time geometry guard, and the layout.json
 * sidecar written beside the published PNG.
 */

import { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
import { mkdtempSync, rmSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { mkdir, writeFile, readFile, realpath, symlink, unlink } from 'fs/promises';
import { createHash } from 'crypto';
import sharp from 'sharp';
import { trackSpan as fullSpan } from './spriteTestFixtures.js';

const TEST_ROOT = mkdtempSync(join(tmpdir(), 'sprite-publish-test-'));
const APP_REPO = join(TEST_ROOT, 'game-repo');

const filesystemMocks = vi.hoisted(() => ({ afterMkdir: null }));
vi.mock('fs/promises', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    mkdir: async (...args) => {
      const result = await actual.mkdir(...args);
      await filesystemMocks.afterMkdir?.(args[0]);
      return result;
    },
  };
});

vi.mock('../../lib/fileUtils.js', async (importOriginal) => {
  const actual = await importOriginal();
  Object.assign(actual.PATHS, {
    data: TEST_ROOT,
    sprites: join(TEST_ROOT, 'sprites'),
  });
  return actual;
});

const OTHER_APP_REPO = join(TEST_ROOT, 'other-game-repo');
const APPS = {
  'game-app': { id: 'game-app', name: 'Example Game', repoPath: APP_REPO },
  'other-app': { id: 'other-app', name: 'Other Example Game', repoPath: OTHER_APP_REPO },
};
const getAppById = vi.fn(async (id) => APPS[id] || null);
vi.mock('../apps.js', () => ({ getAppById: (...args) => getAppById(...args) }));

const isDeploying = vi.fn(() => false);
vi.mock('../appDeployer.js', () => ({ isDeploying: (...args) => isDeploying(...args) }));

const compileAtlasInTail = vi.fn();
vi.mock('./atlas.js', () => ({
  compileAtlasInTail: (...args) => compileAtlasInTail(...args),
}));
const presentationIdleMocks = vi.hoisted(() => ({ buildPresentationIdle: vi.fn() }));
vi.mock('./presentationIdle.js', () => ({
  ...presentationIdleMocks,
  PRESENTATION_IDLE_LAYOUT_KIND: 'portos-presentation-animation-layout',
  presentationIdleSidecarPath: (path) => path.replace(/\.png$/, '.presentation.json'),
  buildPresentationIdleLayout: (idle, path) => ({
    kind: 'portos-presentation-animation-layout',
    imageFile: path.split('/').at(-1),
    imageSha256: idle.sha256,
    frameCount: idle.frameCount,
    frameRate: idle.frameRate,
    cellSize: idle.cellSize,
  }),
}));

const records = await import('./records.js');
const { setPublishBinding, publishAtlas, validatePublishBinding, listPublishBindingsForApp } = await import('./publish.js');
const { walkPhaseLabels } = await import('./walkBounds.js');

let seq = 0;
const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');

const { SPRITE_DIRECTIONS: DIRECTIONS } = await import('./prompts.js');


// The geometry block a real compile writes into the runtime pointer — the
// publish path reads it for the contract guard and the layout sidecar.
const atlasGeometry = (walkFrameCount = 8, overrides = {}) => ({
  columns: ['idle', ...walkPhaseLabels(walkFrameCount)],
  directionOrder: DIRECTIONS,
  rows: DIRECTIONS.length,
  cellSize: 96,
  walkFrameCount,
  walkFps: 12,
  ...overrides,
});
// A pre-#2986 / imported grid, which still carries the trailing scanner
// placeholder. Publishing one must still work and must describe it honestly.
const legacyAtlasGeometry = (walkFrameCount = 8, overrides = {}) =>
  atlasGeometry(walkFrameCount, {
    columns: ['idle', ...walkPhaseLabels(walkFrameCount), 'scanner'],
    ...overrides,
  });

const sidecarPath = (destPath) => destPath.replace(/\.png$/, '.layout.json');
const readSidecar = async (destPath) =>
  JSON.parse(await readFile(join(APP_REPO, sidecarPath(destPath)), 'utf8'));

async function characterWithAtlas(atlasBytes = 'atlas-png-bytes-v1', geometry = atlasGeometry()) {
  const id = `pub-char-${++seq}`;
  await records.createRecord({ kind: 'character', name: 'Publisher' }, id);
  const atlasRel = `runtime/v1/${id}-animation-atlas-v1.png`;
  const abs = join(TEST_ROOT, 'sprites', id, atlasRel);
  await mkdir(join(abs, '..'), { recursive: true });
  await writeFile(abs, atlasBytes);
  compileAtlasInTail.mockResolvedValue({
    created: false,
    version: 1,
    atlasPath: atlasRel,
    atlasSha256: sha256(Buffer.from(atlasBytes)),
    geometry,
  });
  return { id, atlasRel, atlasBytes };
}

const BINDING = { appId: 'game-app', atlasDestPath: 'assets/sprites/hero/hero-atlas.png' };

async function addLockedMainReference(id) {
  const referenceDir = join(TEST_ROOT, 'sprites', id, 'reference');
  await mkdir(referenceDir, { recursive: true });
  const width = 32;
  const height = 32;
  const pixels = Buffer.alloc(width * height * 3);
  for (let y = 0; y < height; y++) {
    for (let x = 0; x < width; x++) {
      const index = (y * width + x) * 3;
      const subject = x >= 10 && x < 22 && y >= 6 && y < 28;
      pixels[index] = subject ? 18 : 255;
      pixels[index + 1] = subject ? 84 : 0;
      pixels[index + 2] = subject ? 102 : 255;
    }
  }
  const sourcePath = `reference/${id}-walk-south-v1.png`;
  await sharp(pixels, { raw: { width, height, channels: 3 } })
    .png()
    .toFile(join(TEST_ROOT, 'sprites', id, sourcePath));
  await writeFile(
    join(referenceDir, `${id}-reference-set-v1.json`),
    JSON.stringify({
      schemaVersion: 2,
      chromaKey: '#FF00FF',
      mainReference: { path: sourcePath, locked: true },
      anchors: [],
    }),
  );
}

beforeEach(async () => {
  getAppById.mockClear();
  APPS['game-app'].repoPath = APP_REPO;
  filesystemMocks.afterMkdir = null;
  isDeploying.mockReset();
  isDeploying.mockReturnValue(false);
  compileAtlasInTail.mockReset();
  presentationIdleMocks.buildPresentationIdle.mockReset();
  rmSync(join(TEST_ROOT, 'sprite-records.json'), { force: true });
  rmSync(APP_REPO, { recursive: true, force: true });
  rmSync(OTHER_APP_REPO, { recursive: true, force: true });
  await mkdir(APP_REPO, { recursive: true });
  await mkdir(OTHER_APP_REPO, { recursive: true });
});
afterAll(() => rmSync(TEST_ROOT, { recursive: true, force: true }));

describe('validatePublishBinding / setPublishBinding', () => {
  it('persists a normalized binding on the record', async () => {
    const { id } = await characterWithAtlas();
    const updated = await setPublishBinding(id, {
      ...BINDING,
      codeBinding: { path: 'src/Hero.cs', resourcePath: 'res://assets/sprites/hero/hero-atlas.png' },
    });
    expect(updated.publishBinding).toEqual({
      appId: 'game-app',
      atlasDestPath: 'assets/sprites/hero/hero-atlas.png',
      codeBinding: {
        path: 'src/Hero.cs',
        resourcePath: 'res://assets/sprites/hero/hero-atlas.png',
        requiredOccurrenceCount: 1,
      },
      runtimeContract: null,
    });
  });

  it('clears with null', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    const cleared = await setPublishBinding(id, null);
    expect(cleared.publishBinding).toBeNull();
  });

  it('refuses an unknown app and a traversal destination', async () => {
    await expect(validatePublishBinding({ ...BINDING, appId: 'nope' }))
      .rejects.toMatchObject({ code: 'UNKNOWN_APP' });
    await expect(validatePublishBinding({ ...BINDING, atlasDestPath: '../outside.png' }))
      .rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    await expect(validatePublishBinding({ ...BINDING, atlasDestPath: '/abs/path.png' }))
      .rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    // Non-.png destinations die at the route's Zod schema (spritePublishBindingSchema).
  });

  it('validates the runtimeContract shape at save time', async () => {
    const { id } = await characterWithAtlas();
    const saved = await setPublishBinding(id, {
      ...BINDING,
      runtimeContract: {
        walkFrameCount: 8, scannerFrameCount: 4, cellSize: 96, columnCount: 9,
      },
    });
    expect(saved.publishBinding.runtimeContract).toEqual({
      walkFrameCount: 8, scannerFrameCount: 4, cellSize: 96, columnCount: 9,
    });

    const ambient = await setPublishBinding(id, {
      ...BINDING,
      runtimeContract: { ambientFrameCount: 3, cellSize: 96, columnCount: 4 },
    });
    expect(ambient.publishBinding.runtimeContract).toEqual({
      ambientFrameCount: 3, cellSize: 96, columnCount: 4,
    });

    for (const bad of [
      { walkFrameCount: 0 },
      { walkFrameCount: 99 },
      { walkFrameCount: 8.5 },
      { cellSize: 96 },
      { walkFrameCount: 8, cellSize: 'big' },
      { walkFrameCount: 8, columnCount: -1 },
    ]) {
      await expect(validatePublishBinding({ ...BINDING, runtimeContract: bad }))
        .rejects.toMatchObject({ status: 400, code: 'INVALID_RUNTIME_CONTRACT' });
    }
    await expect(validatePublishBinding({ ...BINDING, runtimeContract: [8] }))
      .rejects.toMatchObject({ status: 400, code: 'INVALID_RUNTIME_CONTRACT' });
  });

  it('inherits an omitted runtimeContract and clears it only on an explicit null', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, { ...BINDING, runtimeContract: { walkFrameCount: 8 } });

    // The publish form saves appId/dest/codeBinding only — an omitted key must
    // not silently wipe the contract the app declared through the API.
    const resaved = await setPublishBinding(id, { ...BINDING, atlasDestPath: 'assets/sprites/hero/moved.png' });
    expect(resaved.publishBinding.runtimeContract).toEqual({ walkFrameCount: 8, cellSize: null, columnCount: null });

    const cleared = await setPublishBinding(id, { ...BINDING, runtimeContract: null });
    expect(cleared.publishBinding.runtimeContract).toBeNull();
  });

  it('does not carry a contract across a re-point to a different app', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, { ...BINDING, runtimeContract: { walkFrameCount: 8 } });
    // The contract describes the grid ONE app was built against — holding a
    // different app to it would 409 every publish against an expectation it
    // never declared.
    const repointed = await setPublishBinding(id, { ...BINDING, appId: 'other-app' });
    expect(repointed.publishBinding.runtimeContract).toBeNull();
  });
});

describe('listPublishBindingsForApp (reverse lookup, #2991)', () => {
  it('lists exactly the records bound to the app, with destination paths', async () => {
    const a = await characterWithAtlas();
    const b = await characterWithAtlas();
    const other = await characterWithAtlas();
    await setPublishBinding(a.id, { appId: 'game-app', atlasDestPath: 'assets/sprites/a.png' });
    await setPublishBinding(b.id, {
      appId: 'game-app',
      atlasDestPath: 'assets/sprites/b.png',
      codeBinding: { path: 'src/B.cs', resourcePath: 'res://assets/sprites/b.png' },
    });
    // Bound to a DIFFERENT app — must not appear in game-app's lookup.
    await setPublishBinding(other.id, { appId: 'other-app', atlasDestPath: 'assets/sprites/o.png' });

    const bound = await listPublishBindingsForApp('game-app');
    expect(bound.map(x => x.recordId).sort()).toEqual([a.id, b.id].sort());
    const byId = Object.fromEntries(bound.map(x => [x.recordId, x]));
    expect(byId[a.id].atlasDestPath).toBe('assets/sprites/a.png');
    expect(byId[a.id].codeBindingPath).toBeNull();
    expect(byId[b.id].atlasDestPath).toBe('assets/sprites/b.png');
    expect(byId[b.id].codeBindingPath).toBe('src/B.cs');
  });

  it('is empty for an app nothing publishes into (and for a falsy id)', async () => {
    const c = await characterWithAtlas();
    await setPublishBinding(c.id, { appId: 'game-app', atlasDestPath: 'assets/sprites/c.png' });
    expect(await listPublishBindingsForApp('other-app')).toEqual([]);
    expect(await listPublishBindingsForApp(undefined)).toEqual([]);
  });
});

describe('publishAtlas', () => {
  it('refuses without a binding', async () => {
    const { id } = await characterWithAtlas();
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_BINDING_REQUIRED' });
  });

  it('atomically writes the atlas into the app repo and records the publication', async () => {
    const { id, atlasBytes } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    const result = await publishAtlas(id);

    expect(result.published).toBe(true);
    const destAbs = join(APP_REPO, BINDING.atlasDestPath);
    expect((await readFile(destAbs)).toString()).toBe(atlasBytes);
    expect(result.publication).toMatchObject({
      appId: 'game-app',
      appName: 'Example Game',
      atlasDestPath: BINDING.atlasDestPath,
      version: 1,
      destPreviousSha256: null,
      codeBinding: null,
    });
    const history = JSON.parse(
      await readFile(join(TEST_ROOT, 'sprites', id, 'runtime/publications.json'), 'utf8'),
    );
    expect(history).toHaveLength(1);
  });

  it('publishes a transparent 512px presentation portrait from the locked identity master', async () => {
    const { id } = await characterWithAtlas();
    await addLockedMainReference(id);
    const portraitDestPath = 'assets/portraits/hero.png';
    await setPublishBinding(id, { ...BINDING, portraitDestPath });

    const result = await publishAtlas(id);
    expect(result.portraitWritten).toBe(true);
    expect(result.publication).toMatchObject({
      portraitDestPath,
      portraitSize: 512,
      portraitSha256: expect.stringMatching(/^[0-9a-f]{64}$/),
      portraitSourcePath: `reference/${id}-walk-south-v1.png`,
    });
    const portraitAbs = join(APP_REPO, portraitDestPath);
    const metadata = await sharp(portraitAbs).metadata();
    expect(metadata).toMatchObject({ width: 512, height: 512, channels: 4 });
    const raw = await sharp(portraitAbs).ensureAlpha().raw().toBuffer();
    expect(raw[3]).toBe(0);
    const centerAlpha = raw[((256 * 512 + 256) * 4) + 3];
    expect(centerAlpha).toBe(255);
  });

  it('publishes a presentation-resolution picker idle strip with source provenance', async () => {
    const { id } = await characterWithAtlas();
    const presentationIdleDestPath = 'assets/presentation/hero-idle.png';
    const strip = await sharp({
      create: {
        width: 512 * 3,
        height: 512,
        channels: 4,
        background: { r: 20, g: 90, b: 110, alpha: 1 },
      },
    }).png().toBuffer();
    presentationIdleMocks.buildPresentationIdle.mockResolvedValue({
      buffer: strip,
      sha256: sha256(strip),
      sourceManifestPath: 'idle-loop/approved-run.json',
      sourceManifestSha256: 'a'.repeat(64),
      sourceFrameSha256s: ['b'.repeat(64), 'c'.repeat(64), 'd'.repeat(64)],
      frameCount: 3,
      frameRate: 6,
      cellSize: 512,
    });
    await setPublishBinding(id, { ...BINDING, presentationIdleDestPath });

    const result = await publishAtlas(id);
    expect(result.presentationIdleWritten).toBe(true);
    expect(result.publication).toMatchObject({
      presentationIdleDestPath,
      presentationIdleFrameCount: 3,
      presentationIdleFrameRate: 6,
      presentationIdleCellSize: 512,
      presentationIdleSourceManifestPath: 'idle-loop/approved-run.json',
      presentationIdleLayoutDestPath: 'assets/presentation/hero-idle.presentation.json',
    });
    expect(await readFile(join(APP_REPO, presentationIdleDestPath))).toEqual(strip);
    expect(JSON.parse(await readFile(
      join(APP_REPO, 'assets/presentation/hero-idle.presentation.json'),
      'utf8',
    ))).toMatchObject({
      kind: 'portos-presentation-animation-layout',
      frameCount: 3,
      cellSize: 512,
    });
  });

  it('resolves purely from repoPath — no dependency on registered processes/ports (#2991)', async () => {
    // The mocked app carries only { id, name, repoPath } — no processes, no
    // ports, portless. Publishing must still succeed: it targets the repo tree,
    // never a running/registered process.
    expect(APPS['game-app'].processes).toBeUndefined();
    expect(APPS['game-app'].uiPort).toBeUndefined();
    const { id, atlasBytes } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    const result = await publishAtlas(id);
    expect(result.published).toBe(true);
    expect((await readFile(join(APP_REPO, BINDING.atlasDestPath))).toString()).toBe(atlasBytes);
  });

  it('is idempotent when the destination already holds the current bytes', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await publishAtlas(id);
    const again = await publishAtlas(id);
    expect(again.published).toBe(false);
    expect(again.upToDate).toBe(true);
    const history = JSON.parse(
      await readFile(join(TEST_ROOT, 'sprites', id, 'runtime/publications.json'), 'utf8'),
    );
    expect(history).toHaveLength(1);
  });

  it('refuses a destination changed outside PortOS since the previous publish', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await publishAtlas(id);
    await writeFile(join(APP_REPO, BINDING.atlasDestPath), 'hand-edited-in-game-repo');
    // A NEW compiled atlas (different bytes) must refuse rather than clobber.
    const nextBytes = 'atlas-png-bytes-v2';
    const nextRel = `runtime/v2/${id}-animation-atlas-v2.png`;
    await mkdir(join(TEST_ROOT, 'sprites', id, 'runtime/v2'), { recursive: true });
    await writeFile(join(TEST_ROOT, 'sprites', id, nextRel), nextBytes);
    compileAtlasInTail.mockResolvedValue({
      created: true, version: 2, atlasPath: nextRel, atlasSha256: sha256(Buffer.from(nextBytes)), geometry: atlasGeometry(),
    });
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_DEST_DIVERGED' });
  });

  it('refuses an occupied destination it never published unless acknowledged', async () => {
    const { id, atlasBytes } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await mkdir(join(APP_REPO, 'assets/sprites/hero'), { recursive: true });
    await writeFile(join(APP_REPO, BINDING.atlasDestPath), 'hand-made-atlas-from-before-portos');

    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_DEST_OCCUPIED' });
    // Explicit acknowledgment replaces it and records the prior sha.
    const acked = await publishAtlas(id, { acknowledgeOverwrite: true });
    expect(acked.published).toBe(true);
    expect(acked.publication.destPreviousSha256).toBe(sha256(Buffer.from('hand-made-atlas-from-before-portos')));
    expect((await readFile(join(APP_REPO, BINDING.atlasDestPath))).toString()).toBe(atlasBytes);
  });

  it('refuses to publish while the app is deploying', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    isDeploying.mockReturnValue(true);
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'APP_DEPLOY_IN_PROGRESS' });
    expect(isDeploying).toHaveBeenCalledWith(APP_REPO);
  });

  it('verifies the code binding by occurrence count and refuses drift', async () => {
    const { id } = await characterWithAtlas();
    const resource = 'res://assets/sprites/hero/hero-atlas.png';
    await mkdir(join(APP_REPO, 'src'), { recursive: true });
    await writeFile(join(APP_REPO, 'src/Hero.cs'), `var atlas = load("${resource}");\n`);
    await setPublishBinding(id, {
      ...BINDING,
      codeBinding: { path: 'src/Hero.cs', resourcePath: resource },
    });
    const ok = await publishAtlas(id);
    expect(ok.published).toBe(true);
    expect(ok.publication.codeBinding).toMatchObject({ rewritten: false });

    // Drift: the resource path appears twice now.
    await writeFile(join(APP_REPO, 'src/Hero.cs'), `load("${resource}"); load("${resource}");\n`);
    const nextBytes = 'atlas-png-bytes-v2';
    const nextRel = `runtime/v2/${id}-animation-atlas-v2.png`;
    await mkdir(join(TEST_ROOT, 'sprites', id, 'runtime/v2'), { recursive: true });
    await writeFile(join(TEST_ROOT, 'sprites', id, nextRel), nextBytes);
    compileAtlasInTail.mockResolvedValue({
      created: true, version: 2, atlasPath: nextRel, atlasSha256: sha256(Buffer.from(nextBytes)), geometry: atlasGeometry(),
    });
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'CODE_BINDING_DRIFTED' });
    // The drifted binding aborted BEFORE the atlas was replaced.
    expect((await readFile(join(APP_REPO, BINDING.atlasDestPath))).toString()).toBe('atlas-png-bytes-v1');
  });

  it('rewrites the code binding on a real destination move (baseline follows the file, not the dest)', async () => {
    const { id } = await characterWithAtlas();
    const oldResource = 'res://assets/sprites/hero/old-name.png';
    const newResource = 'res://assets/sprites/hero/new-name.png';
    await mkdir(join(APP_REPO, 'src'), { recursive: true });
    await writeFile(join(APP_REPO, 'src/Hero.cs'), `var atlas = load("${oldResource}");\n`);

    await setPublishBinding(id, {
      appId: 'game-app',
      atlasDestPath: 'assets/sprites/hero/old-name.png',
      codeBinding: { path: 'src/Hero.cs', resourcePath: oldResource },
    });
    await publishAtlas(id);

    // Real move: atlasDestPath AND resourcePath both change. The code-binding
    // baseline must be found via the file (appId + codeBinding.path), because
    // no publication exists for the NEW destination yet.
    await setPublishBinding(id, {
      appId: 'game-app',
      atlasDestPath: 'assets/sprites/hero/new-name.png',
      codeBinding: { path: 'src/Hero.cs', resourcePath: newResource },
    });
    const result = await publishAtlas(id);
    expect(result.published).toBe(true);
    expect(result.publication.codeBinding).toMatchObject({ rewritten: true, previousResourcePath: oldResource });
    expect(await readFile(join(APP_REPO, 'src/Hero.cs'), 'utf8')).toContain(newResource);
  });

  it('records a publication when an up-to-date publish rewrites the code binding', async () => {
    const { id } = await characterWithAtlas();
    const oldResource = 'res://assets/sprites/hero/old-atlas.png';
    const newResource = 'res://assets/sprites/hero/hero-atlas.png';
    await mkdir(join(APP_REPO, 'src'), { recursive: true });
    await writeFile(join(APP_REPO, 'src/Hero.cs'), `var atlas = load("${oldResource}");\n`);
    await setPublishBinding(id, { ...BINDING, codeBinding: { path: 'src/Hero.cs', resourcePath: oldResource } });
    await publishAtlas(id);

    // Same dest bytes, new resource path → binding-only fix, but the game
    // source WAS mutated, so history must say so.
    await setPublishBinding(id, { ...BINDING, codeBinding: { path: 'src/Hero.cs', resourcePath: newResource } });
    const result = await publishAtlas(id);
    expect(result.published).toBe(false);
    expect(result.codeBinding).toMatchObject({ rewritten: true, previousResourcePath: oldResource });
    expect(result.publication).toMatchObject({ upToDateBaseline: true });
    const history = JSON.parse(await readFile(join(TEST_ROOT, 'sprites', id, 'runtime/publications.json'), 'utf8'));
    expect(history).toHaveLength(2);
    // The recorded baseline lets a THIRD publish see the current resource path.
    const third = await publishAtlas(id);
    expect(third.published).toBe(false);
    expect(third.codeBinding).toMatchObject({ rewritten: false });
  });

  it('seeds a history baseline when the first publish finds its own bytes already at the destination', async () => {
    const { id, atlasBytes } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await mkdir(join(APP_REPO, 'assets/sprites/hero'), { recursive: true });
    await writeFile(join(APP_REPO, BINDING.atlasDestPath), atlasBytes);

    const first = await publishAtlas(id);
    expect(first.upToDate).toBe(true);
    expect(first.publication).toMatchObject({ upToDateBaseline: true });

    // A later changed atlas now reads as DIVERGED-checkable, not OCCUPIED.
    const nextBytes = 'atlas-png-bytes-v2';
    const nextRel = `runtime/v2/${id}-animation-atlas-v2.png`;
    await mkdir(join(TEST_ROOT, 'sprites', id, 'runtime/v2'), { recursive: true });
    await writeFile(join(TEST_ROOT, 'sprites', id, nextRel), nextBytes);
    compileAtlasInTail.mockResolvedValue({
      created: true, version: 2, atlasPath: nextRel, atlasSha256: sha256(Buffer.from(nextBytes)), geometry: atlasGeometry(),
    });
    const second = await publishAtlas(id);
    expect(second.published).toBe(true);
  });

  it('reuses the current pointer geometry when compiling for publish', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);

    // No pointer yet → default geometry (undefined override).
    await publishAtlas(id);
    expect(compileAtlasInTail).toHaveBeenLastCalledWith(id, { geometry: undefined });

    // A pointer with custom geometry → publish compiles with exactly it.
    const geometry = { cellSize: 64, pivot: [32, 56], targetMaxHeight: 44, targetMaxWidth: 52 };
    await writeFile(
      join(TEST_ROOT, 'sprites', id, 'runtime/current.json'),
      JSON.stringify({ version: 1, atlasPath: `runtime/v1/${id}-animation-atlas-v1.png`, geometry }),
    );
    await publishAtlas(id);
    expect(compileAtlasInTail).toHaveBeenLastCalledWith(id, { geometry });
  });

  it('refuses to ship a tampered or missing compiled atlas file', async () => {
    const { id, atlasRel } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await writeFile(join(TEST_ROOT, 'sprites', id, atlasRel), 'tampered-after-compile');
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 422, code: 'ATLAS_OUTPUT_TAMPERED' });
    rmSync(join(TEST_ROOT, 'sprites', id, atlasRel));
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 422, code: 'ATLAS_OUTPUT_MISSING' });
    expect(await readFile(join(APP_REPO, BINDING.atlasDestPath)).catch(() => null)).toBeNull();
  });
});

describe('runtime contract guard (#2982)', () => {
  it('publishes when the compiled geometry matches the declared contract', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, {
      ...BINDING,
      runtimeContract: { walkFrameCount: 8, cellSize: 96, columnCount: 9 },
    });
    const result = await publishAtlas(id);
    expect(result.published).toBe(true);
  });

  it('refuses a frame-count mismatch with both counts named, leaving the repo untouched', async () => {
    const { id } = await characterWithAtlas('atlas-png-bytes-12f', atlasGeometry(12));
    await setPublishBinding(id, {
      ...BINDING,
      runtimeContract: { walkFrameCount: 8, cellSize: 96, columnCount: 9 },
    });
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_CONTRACT_MISMATCH' });
    await expect(publishAtlas(id)).rejects.toThrow(/12 walk cycle frames.*expects 8/s);
    await expect(publishAtlas(id)).rejects.toThrow(/Approve the walk cycle set at that frame count/);
    // Nothing landed in the game repo — not the atlas, not the sidecar.
    expect(await readFile(join(APP_REPO, BINDING.atlasDestPath)).catch(() => null)).toBeNull();
    expect(await readFile(join(APP_REPO, sidecarPath(BINDING.atlasDestPath))).catch(() => null)).toBeNull();
  });

  it('refuses a cell-size mismatch', async () => {
    const { id } = await characterWithAtlas('atlas-png-bytes-64px', atlasGeometry(8, { cellSize: 64 }));
    await setPublishBinding(id, { ...BINDING, runtimeContract: { walkFrameCount: 8, cellSize: 96 } });
    await expect(publishAtlas(id)).rejects.toThrow(/cells are 64px but Example Game expects 96px/);
  });

  it('publishes a non-8-frame atlas unchecked when no contract is declared', async () => {
    const { id } = await characterWithAtlas('atlas-png-bytes-12f', atlasGeometry(12));
    await setPublishBinding(id, BINDING);
    const result = await publishAtlas(id);
    expect(result.published).toBe(true);
    expect((await readSidecar(BINDING.atlasDestPath)).walkFrameCount).toBe(12);
  });
});

describe('layout sidecar (#2982)', () => {
  it('writes the sidecar beside the atlas with the column list the atlas actually has', async () => {
    const { id, atlasBytes } = await characterWithAtlas('atlas-png-bytes-12f', atlasGeometry(12));
    await setPublishBinding(id, BINDING);
    const result = await publishAtlas(id);

    const layout = await readSidecar(BINDING.atlasDestPath);
    expect(layout).toMatchObject({
      schemaVersion: 1,
      kind: 'portos-sprite-atlas-layout',
      characterId: id,
      atlasFile: 'hero-atlas.png',
      cellSize: 96,
      rows: 8,
      walkFrameCount: 12,
      columnCount: 13,
      previewFps: 12,
      sourceAtlasSha256: sha256(Buffer.from(atlasBytes)),
    });
    expect(layout.columns[0]).toBe('idle');
    // idle + 12 walk phases — the sidecar advertises no scanner span, because
    // the atlas beside it no longer has that column (#2986).
    expect(layout.columns).not.toContain('scanner');
    expect(layout.columns).toHaveLength(13);
    // Per-track spans so a future multi-frame track is additive, not a rewrite.
    expect(layout.tracks).toEqual({
      idle: fullSpan(0, 1),
      walk: fullSpan(1, 12),
    });
    // previewFps travels labeled as authoring-only — the app must not animate from it.
    expect(layout.previewFpsNote).toMatch(/Authoring metadata only/);
    expect(result.publication).toMatchObject({ layoutDestPath: 'assets/sprites/hero/hero-atlas.layout.json' });
  });

  it('still describes a pre-#2986 atlas that carries a scanner column', async () => {
    // Imported/legacy atlases keep publishing unchanged — the sidecar reports
    // the grid the PNG actually is, scanner span and all, rather than the shape
    // the current compiler would emit.
    const { id } = await characterWithAtlas('atlas-png-bytes-legacy', legacyAtlasGeometry(8));
    await setPublishBinding(id, BINDING);
    const result = await publishAtlas(id);

    expect(result.published).toBe(true);
    const layout = await readSidecar(BINDING.atlasDestPath);
    expect(layout.columnCount).toBe(10);
    expect(layout.walkFrameCount).toBe(8);
    expect(layout.tracks.scanner).toEqual(fullSpan(9, 1));
  });

  it('is a no-op on an unchanged republish but self-heals a deleted sidecar', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await publishAtlas(id);

    const again = await publishAtlas(id);
    expect(again.upToDate).toBe(true);
    expect(again.layoutWritten).toBe(false);
    let history = JSON.parse(await readFile(join(TEST_ROOT, 'sprites', id, 'runtime/publications.json'), 'utf8'));
    expect(history).toHaveLength(1);

    // The atlas is still current but its sidecar was deleted in the game repo —
    // the pair must converge rather than leave the atlas undescribed.
    rmSync(join(APP_REPO, sidecarPath(BINDING.atlasDestPath)));
    const healed = await publishAtlas(id);
    expect(healed.upToDate).toBe(true);
    expect(healed.layoutWritten).toBe(true);
    expect((await readSidecar(BINDING.atlasDestPath)).walkFrameCount).toBe(8);
    history = JSON.parse(await readFile(join(TEST_ROOT, 'sprites', id, 'runtime/publications.json'), 'utf8'));
    expect(history).toHaveLength(2);
  });

  it('rewrites the sidecar when the atlas changes', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await publishAtlas(id);
    expect((await readSidecar(BINDING.atlasDestPath)).walkFrameCount).toBe(8);

    const nextBytes = 'atlas-png-bytes-v2';
    const nextRel = `runtime/v2/${id}-animation-atlas-v2.png`;
    await mkdir(join(TEST_ROOT, 'sprites', id, 'runtime/v2'), { recursive: true });
    await writeFile(join(TEST_ROOT, 'sprites', id, nextRel), nextBytes);
    compileAtlasInTail.mockResolvedValue({
      created: true,
      version: 2,
      atlasPath: nextRel,
      atlasSha256: sha256(Buffer.from(nextBytes)),
      geometry: atlasGeometry(10),
    });
    const result = await publishAtlas(id);
    expect(result.published).toBe(true);
    expect(result.layoutWritten).toBe(true);
    const layout = await readSidecar(BINDING.atlasDestPath);
    expect(layout).toMatchObject({
      walkFrameCount: 10, columnCount: 11, atlasVersion: 2, sourceAtlasSha256: sha256(Buffer.from(nextBytes)),
    });
  });

  it('refuses to replace a sidecar PortOS did not write unless acknowledged', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    await mkdir(join(APP_REPO, 'assets/sprites/hero'), { recursive: true });
    await writeFile(join(APP_REPO, sidecarPath(BINDING.atlasDestPath)), '{"kind":"someone-elses-file"}');

    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_LAYOUT_OCCUPIED' });
    // The refusal aborts before the atlas lands.
    expect(await readFile(join(APP_REPO, BINDING.atlasDestPath)).catch(() => null)).toBeNull();

    const acked = await publishAtlas(id, { acknowledgeOverwrite: true });
    expect(acked.published).toBe(true);
    expect((await readSidecar(BINDING.atlasDestPath)).kind).toBe('portos-sprite-atlas-layout');
  });

  it('refuses an occupied sidecar BEFORE rewriting the game source', async () => {
    const { id } = await characterWithAtlas();
    const oldResource = 'res://assets/sprites/hero/old-name.png';
    const newResource = 'res://assets/sprites/hero/hero-atlas.png';
    await mkdir(join(APP_REPO, 'src'), { recursive: true });
    const sourceBefore = `var atlas = load("${oldResource}");\n`;
    await writeFile(join(APP_REPO, 'src/Hero.cs'), sourceBefore);
    // A pending code-binding REWRITE (the previous publish recorded the old
    // resource path) plus a foreign sidecar at the destination.
    await setPublishBinding(id, {
      appId: 'game-app',
      atlasDestPath: 'assets/sprites/hero/old-name.png',
      codeBinding: { path: 'src/Hero.cs', resourcePath: oldResource },
    });
    await publishAtlas(id);
    await setPublishBinding(id, { ...BINDING, codeBinding: { path: 'src/Hero.cs', resourcePath: newResource } });
    await writeFile(join(APP_REPO, sidecarPath(BINDING.atlasDestPath)), 'not even json');

    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_LAYOUT_OCCUPIED' });
    // The refusal must land before applyCodeBinding mutates the game source —
    // otherwise the source points at an atlas this publish declined to write.
    expect(await readFile(join(APP_REPO, 'src/Hero.cs'), 'utf8')).toBe(sourceBefore);
    expect(await readFile(join(APP_REPO, BINDING.atlasDestPath)).catch(() => null)).toBeNull();
  });

  it('refuses an occupied sidecar before rewriting the game source on the up-to-date path too', async () => {
    const { id, atlasBytes } = await characterWithAtlas();
    const oldResource = 'res://assets/sprites/hero/old-name.png';
    const newResource = 'res://assets/sprites/hero/hero-atlas.png';
    await mkdir(join(APP_REPO, 'src'), { recursive: true });
    const sourceBefore = `var atlas = load("${oldResource}");\n`;
    await writeFile(join(APP_REPO, 'src/Hero.cs'), sourceBefore);
    await setPublishBinding(id, {
      appId: 'game-app',
      atlasDestPath: 'assets/sprites/hero/old-name.png',
      codeBinding: { path: 'src/Hero.cs', resourcePath: oldResource },
    });
    await publishAtlas(id);

    // The NEW destination already holds the current atlas bytes, so the publish
    // takes the up-to-date branch — which still rewrites the game source, and
    // so must also refuse the foreign sidecar before doing it.
    await setPublishBinding(id, { ...BINDING, codeBinding: { path: 'src/Hero.cs', resourcePath: newResource } });
    await writeFile(join(APP_REPO, BINDING.atlasDestPath), atlasBytes);
    await writeFile(join(APP_REPO, sidecarPath(BINDING.atlasDestPath)), '{"kind":"someone-elses-file"}');

    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 409, code: 'PUBLISH_LAYOUT_OCCUPIED' });
    expect(await readFile(join(APP_REPO, 'src/Hero.cs'), 'utf8')).toBe(sourceBefore);
  });

  it('refuses to publish an atlas whose geometry carries no column layout', async () => {
    const { id } = await characterWithAtlas('atlas-png-bytes-nogeo', undefined);
    compileAtlasInTail.mockResolvedValue({
      created: false,
      version: 1,
      atlasPath: `runtime/v1/${id}-animation-atlas-v1.png`,
      atlasSha256: sha256(Buffer.from('atlas-png-bytes-nogeo')),
    });
    await setPublishBinding(id, BINDING);
    await expect(publishAtlas(id)).rejects.toMatchObject({ status: 422, code: 'ATLAS_GEOMETRY_UNKNOWN' });
    expect(await readFile(join(APP_REPO, BINDING.atlasDestPath)).catch(() => null)).toBeNull();
  });
});

describe('publication filesystem boundary', () => {
  const sourcePath = 'src/Hero.cs';
  const portraitDestPath = 'assets/portraits/hero.png';
  const presentationIdleDestPath = 'assets/picker/hero.png';
  const targets = [
    ['atlas', BINDING.atlasDestPath, {}],
    ['atlas sidecar', sidecarPath(BINDING.atlasDestPath), {}],
    ['portrait', portraitDestPath, { portraitDestPath }],
    ['picker animation', presentationIdleDestPath, { presentationIdleDestPath }],
    ['picker sidecar', presentationIdleDestPath.replace(/\.png$/, '.presentation.json'), { presentationIdleDestPath }],
    ['code binding', sourcePath, {}],
  ];

  // Each destination has its own read/write call site. Both branches can
  // rewrite source, so this security matrix pins preflight ordering for all.
  describe.each(['normal', 'up-to-date'])('%s publication', (branch) => {
    it.each(targets)('rejects a newly symlinked %s before any app-file rewrite', async (_label, target, extra) => {
      const { id, atlasBytes } = await characterWithAtlas();
      const oldResource = 'res://old-atlas.png';
      const newResource = 'res://new-atlas.png';
      const sourceBefore = `load("${oldResource}");\n`;
      await mkdir(join(APP_REPO, 'src'), { recursive: true });
      await writeFile(join(APP_REPO, sourcePath), sourceBefore);
      await setPublishBinding(id, {
        ...BINDING,
        atlasDestPath: 'assets/old-atlas.png',
        codeBinding: { path: sourcePath, resourcePath: oldResource },
      });
      await publishAtlas(id);
      const historyPath = join(TEST_ROOT, 'sprites', id, 'runtime/publications.json');
      const historyBefore = await readFile(historyPath);
      if (extra.portraitDestPath) await addLockedMainReference(id);
      const strip = Buffer.from('synthetic-picker-strip');
      presentationIdleMocks.buildPresentationIdle.mockResolvedValue({
        buffer: strip, sha256: sha256(strip), frameCount: 3, frameRate: 6, cellSize: 512,
      });
      const binding = {
        ...BINDING, ...extra,
        codeBinding: { path: sourcePath, resourcePath: newResource },
      };
      await setPublishBinding(id, binding);
      await mkdir(join(APP_REPO, 'assets/sprites/hero'), { recursive: true });
      if (branch === 'up-to-date') await writeFile(join(APP_REPO, BINDING.atlasDestPath), atlasBytes);

      const outsidePath = join(OTHER_APP_REPO, 'outside-target');
      const outsideBefore = target === sourcePath ? sourceBefore : atlasBytes;
      await writeFile(outsidePath, outsideBefore);
      await mkdir(join(APP_REPO, target, '..'), { recursive: true });
      await unlink(join(APP_REPO, target)).catch((err) => { if (err.code !== 'ENOENT') throw err; });
      await symlink(outsidePath, join(APP_REPO, target), 'file');

      // Save-time validation and use-time validation share the same refusal.
      await expect(validatePublishBinding(binding)).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
      await expect(publishAtlas(id, { acknowledgeOverwrite: true })).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
      expect(await readFile(outsidePath, 'utf8')).toBe(outsideBefore);
      expect(await readFile(join(APP_REPO, sourcePath), 'utf8')).toBe(sourceBefore);
      expect(await readFile(historyPath)).toEqual(historyBefore);
      expect(await readFile(join(APP_REPO, 'assets/old-atlas.png'), 'utf8')).toBe(atlasBytes);
      if (target !== sidecarPath(BINDING.atlasDestPath)) {
        await expect(readFile(join(APP_REPO, sidecarPath(BINDING.atlasDestPath)))).rejects.toMatchObject({ code: 'ENOENT' });
      }
    });
  });

  it('rejects an escaping parent introduced after saving a missing nested output path', async () => {
    const { id } = await characterWithAtlas();
    const binding = { ...BINDING, atlasDestPath: 'linked-assets/missing/nested/atlas.png' };
    await setPublishBinding(id, binding);
    await writeFile(join(OTHER_APP_REPO, 'sentinel'), 'outside-before');
    await symlink(OTHER_APP_REPO, join(APP_REPO, 'linked-assets'), 'junction');
    await expect(validatePublishBinding(binding)).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    await expect(publishAtlas(id)).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    expect(await readFile(join(OTHER_APP_REPO, 'sentinel'), 'utf8')).toBe('outside-before');
    await expect(readFile(join(OTHER_APP_REPO, 'missing/nested/atlas.png'))).rejects.toMatchObject({ code: 'ENOENT' });
  });

  it('refuses contained and dangling symlinks instead of treating them as ordinary destinations', async () => {
    await writeFile(join(APP_REPO, 'contained.png'), 'contained-before');
    for (const target of ['contained.png', 'missing.png']) {
      const link = join(APP_REPO, 'alias.png');
      await symlink(join(APP_REPO, target), link, 'file');
      await expect(validatePublishBinding({ ...BINDING, atlasDestPath: 'alias.png' })).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
      await unlink(link);
    }
    await mkdir(join(APP_REPO, 'contained-dir'));
    await symlink(join(APP_REPO, 'contained-dir'), join(APP_REPO, 'alias-dir'), 'junction');
    await expect(validatePublishBinding({ ...BINDING, atlasDestPath: 'alias-dir/missing/atlas.png' })).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    expect(await readFile(join(APP_REPO, 'contained.png'), 'utf8')).toBe('contained-before');
  });

  it('revalidates a completed output parent before rewriting source', async () => {
    const { id } = await characterWithAtlas();
    const sourceBefore = 'load("res://old.png");';
    await mkdir(join(APP_REPO, 'src'));
    await writeFile(join(APP_REPO, sourcePath), sourceBefore);
    await setPublishBinding(id, {
      ...BINDING, codeBinding: { path: sourcePath, resourcePath: 'res://old.png' },
    });
    await publishAtlas(id);
    const atlasDestPath = 'new-output/nested/atlas.png';
    await setPublishBinding(id, {
      ...BINDING, atlasDestPath,
      codeBinding: { path: sourcePath, resourcePath: 'res://new.png' },
    });
    await writeFile(join(OTHER_APP_REPO, 'atlas.png'), 'outside-before');
    const completedParent = join(await realpath(APP_REPO), 'new-output/nested');
    filesystemMocks.afterMkdir = async (path) => {
      if (path !== completedParent) return;
      filesystemMocks.afterMkdir = null;
      rmSync(path, { recursive: true });
      await symlink(OTHER_APP_REPO, path, 'junction');
    };
    await expect(publishAtlas(id)).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    expect(await readFile(join(APP_REPO, sourcePath), 'utf8')).toBe(sourceBefore);
    expect(await readFile(join(OTHER_APP_REPO, 'atlas.png'), 'utf8')).toBe('outside-before');
    await expect(readFile(join(OTHER_APP_REPO, 'atlas.layout.json'))).rejects.toMatchObject({ code: 'ENOENT' });
  });

  it('validates inherited optional destinations before saving an older-client binding', async () => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, { ...BINDING, portraitDestPath });
    await mkdir(join(APP_REPO, 'assets/portraits'), { recursive: true });
    const outsidePath = join(OTHER_APP_REPO, 'portrait.png');
    await writeFile(outsidePath, 'outside-before');
    await symlink(outsidePath, join(APP_REPO, portraitDestPath), 'file');
    await expect(setPublishBinding(id, BINDING)).rejects.toMatchObject({ code: 'INVALID_PUBLISH_PATH' });
    expect(await readFile(outsidePath, 'utf8')).toBe('outside-before');
  });

  it('publishes through a configured repository alias while creating contained output directories', async () => {
    const { id, atlasBytes } = await characterWithAtlas();
    const alias = join(TEST_ROOT, `repo-alias-${id}`);
    await symlink(APP_REPO, alias, 'junction');
    APPS['game-app'].repoPath = alias;
    await setPublishBinding(id, BINDING);
    const result = await publishAtlas(id);
    expect(result.published).toBe(true);
    expect(await readFile(join(APP_REPO, BINDING.atlasDestPath), 'utf8')).toBe(atlasBytes);
    expect((await readSidecar(BINDING.atlasDestPath)).kind).toBe('portos-sprite-atlas-layout');
    expect(isDeploying).toHaveBeenCalledWith(alias);
  });
});

describe('unreadable publication state', () => {
  it.each(['current.json', 'publications.json'])('refuses publication with damaged %s', async (name) => {
    const { id } = await characterWithAtlas();
    await setPublishBinding(id, BINDING);
    const path = join(TEST_ROOT, 'sprites', id, 'runtime', name);
    await writeFile(path, '{');
    await expect(publishAtlas(id)).rejects.toThrow(/Unreadable/);
    expect(await readFile(path, 'utf8')).toBe('{');
    await expect(readFile(join(APP_REPO, BINDING.atlasDestPath))).rejects.toMatchObject({ code: 'ENOENT' });
  });
});