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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* 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' });
});
});