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
/**
* Sprites — publish the compiled runtime atlas into a managed app's repo
* (issue #2898, phase 4).
*
* The game consumes sprites from its own tree; PortOS owns provenance. A
* per-record `publishBinding` ({ appId, atlasDestPath, portraitDestPath?,
* presentationIdleDestPath?, codeBinding? }) names
* the managed app and the repo-relative destination. Publishing compiles the
* atlas (idempotently), path-anchors the destination under the app's
* repoPath, and atomically replaces the file — refusing when the destination
* bytes no longer match the previous publish (something else changed the
* game's atlas; clobbering it silently would destroy that change).
*
* The optional codeBinding is a verify-or-rewrite guard over the game source
* file that references the atlas: the binding's resourcePath must appear in
* the file exactly requiredOccurrenceCount times. When a previous publish
* recorded a different resourcePath (a destination move), the old string is
* rewritten to the new one — occurrence-count guarded, refusing on any
* drift. Engine sidecars (e.g. Godot .png.import) are the game repo's
* concern and are never touched.
*
* The optional runtimeContract (#2982) is the reverse direction: the app
* declares the grid it was built against ({ walkFrameCount?, ambientFrameCount?,
* cellSize, columnCount }) and a publish whose compiled geometry disagrees is refused
* instead of silently shifting every column the game reads. Alongside the PNG,
* publish writes a `<atlas-stem>.layout.json` sidecar describing the grid
* PortOS actually produced, so the app can resolve columns by name rather than
* by memory. An absent contract publishes unchecked, exactly as before.
*
* Publishes serialize on a per-app queue (the appDeployer per-app-lock
* posture) nested inside the record's walk write tail.
*/
import { dirname, join, resolve } from 'path';
import { mkdir, readFile, realpath, stat } from 'fs/promises';
import {
atomicWrite, isPathInsideDir, readJSONFile, safeJSONParse, sha256File, pathExists,
} from '../../lib/fileUtils.js';
import { isPathAtOrInsideDir } from '../../lib/pathContainment.js';
import { isSymlinkFreeRepoPath } from '../../lib/repoPublishPath.js';
import { ServerError } from '../../lib/errorHandler.js';
import { createKeyCachedQueue } from '../../lib/createKeyCachedQueue.js';
import { getAppById } from '../apps.js';
import { isDeploying } from '../appDeployer.js';
import { spriteDir, RUNTIME_POINTER_REL, RUNTIME_PUBLICATIONS_REL } from './paths.js';
import { requireAnimatable } from './reference.js';
import { listRecords, updateRecord } from './records.js';
import { withWalkWriteTail } from './walk.js';
import { compileAtlasInTail } from './atlas.js';
import { sha256Buffer } from './walkPostprocess.js';
import { spriteRuntimeContractSchema } from '../../lib/validation.js';
import {
ATLAS_LAYOUT_KIND, buildAtlasLayout, layoutSidecarPath, runtimeContractMismatch,
} from './atlasLayout.js';
import { buildPresentationPortrait } from './presentationPortrait.js';
import {
buildPresentationIdle,
buildPresentationIdleLayout,
PRESENTATION_IDLE_LAYOUT_KIND,
presentationIdleSidecarPath,
} from './presentationIdle.js';
// Per-repo serialization: keyed by the real repoPath, so two app records pointing at the
// same checkout — or two characters publishing into one game — queue behind
// each other instead of interleaving writes to the same tree.
const repoPublishTail = createKeyCachedQueue();
const bindingError = (message, code) => new ServerError(message, { status: 400, code });
/**
* Anchor a repo-relative path under a managed app's repoPath, refusing
* absolute paths, traversal, the repo root itself, and symlink components.
* Missing tails are allowed only below a verified existing directory.
*/
async function anchorRepoPath(repoRoot, relPath, label) {
if (typeof relPath !== 'string' || !relPath || relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0')) {
throw bindingError(`${label} must be a repo-relative path`, 'INVALID_PUBLISH_PATH');
}
const abs = resolve(repoRoot, relPath);
if (abs === resolve(repoRoot) || !isPathInsideDir(repoRoot, abs)) {
throw bindingError(`${label} escapes the app repository: ${relPath}`, 'INVALID_PUBLISH_PATH');
}
if (!(await isSymlinkFreeRepoPath(repoRoot, abs, { leaf: 'file' }))) {
throw bindingError(`${label} must stay inside the app repository without symlinks: ${relPath}`, 'INVALID_PUBLISH_PATH');
}
return abs;
}
/**
* Resolve a binding's app and confirm its repoPath is a real directory.
* Shared by save-time validation (400) and publish time (409) so the two
* checks can't drift.
*/
async function requireAppRepo(appId, status) {
const app = await getAppById(appId);
if (!app) throw new ServerError(`Unknown app: ${appId}`, { status, code: 'UNKNOWN_APP' });
const repoStat = app.repoPath ? await stat(app.repoPath).catch(() => null) : null;
if (!repoStat?.isDirectory()) {
throw new ServerError(`App ${app.name || appId} has no accessible repoPath`, { status, code: 'APP_REPO_MISSING' });
}
return { app, repoRoot: await realpath(app.repoPath) };
}
/**
* Validate the optional runtimeContract — the grid the consuming app was built
* against (#2982). Shape and bounds come from the SAME Zod schema the route
* parses, so a non-route caller (importer, peer sync, a test) can't persist a
* contract the route would have rejected.
*
* A registry-declared standalone track count is required once a contract is
* present; `cellSize` and `columnCount` are optional extra
* assertions. The fields are NOT cross-checked against each other: what counts
* as a consistent column layout is the compiler's business and changes with the
* grid (#2986 drops the scanner column), so a stale count surfaces at publish
* with both numbers named rather than as an unexplained 400 at save.
*/
function validateRuntimeContract(runtimeContract) {
if (runtimeContract === undefined || runtimeContract === null) return null;
const parsed = spriteRuntimeContractSchema.safeParse(runtimeContract);
if (!parsed.success) {
const issue = parsed.error.issues?.[0];
const field = issue?.path?.length ? `runtimeContract.${issue.path.join('.')}` : 'runtimeContract';
throw bindingError(`${field}: ${issue?.message || 'invalid'}`, 'INVALID_RUNTIME_CONTRACT');
}
const { cellSize, columnCount, ...trackFrameCounts } = parsed.data;
return {
// The schema builds these keys from the track registry. Preserve the
// parsed sparse map wholesale so a newly registered track round-trips
// without another publish-service branch.
...trackFrameCounts,
cellSize: cellSize ?? null,
columnCount: columnCount ?? null,
};
}
/** Validate a publishBinding shape (null clears it). */
export async function validatePublishBinding(binding) {
if (binding === null) return null;
const {
appId, atlasDestPath, portraitDestPath, presentationIdleDestPath,
codeBinding, runtimeContract,
} = binding;
const { repoRoot } = await requireAppRepo(appId, 400);
await anchorRepoPath(repoRoot, atlasDestPath, 'atlasDestPath');
// The sidecar lands beside the atlas, so its path must anchor too — catch a
// destination whose sidecar would escape the repo at SAVE time, not mid-publish.
await anchorRepoPath(repoRoot, layoutSidecarPath(atlasDestPath), 'atlas layout sidecar');
if (portraitDestPath) {
await anchorRepoPath(repoRoot, portraitDestPath, 'portraitDestPath');
}
if (presentationIdleDestPath) {
await anchorRepoPath(repoRoot, presentationIdleDestPath, 'presentationIdleDestPath');
await anchorRepoPath(repoRoot, presentationIdleSidecarPath(presentationIdleDestPath), 'picker animation sidecar');
}
if (codeBinding) {
await anchorRepoPath(repoRoot, codeBinding.path, 'codeBinding.path');
if (typeof codeBinding.resourcePath !== 'string' || !codeBinding.resourcePath.trim()) {
throw bindingError('codeBinding.resourcePath is required', 'INVALID_CODE_BINDING');
}
}
return {
appId,
atlasDestPath,
...(portraitDestPath === undefined ? {} : { portraitDestPath }),
...(presentationIdleDestPath === undefined ? {} : { presentationIdleDestPath }),
codeBinding: codeBinding
? {
path: codeBinding.path,
resourcePath: codeBinding.resourcePath.trim(),
requiredOccurrenceCount: codeBinding.requiredOccurrenceCount ?? 1,
}
: null,
// `undefined` (key absent) is distinct from `null` (explicit clear) — see
// setPublishBinding, which carries an absent contract over from the stored
// binding so a client that predates the field can't silently wipe it.
runtimeContract: validateRuntimeContract(runtimeContract),
};
}
/**
* Persist a validated binding on the record. A binding that omits
* `runtimeContract` entirely INHERITS the stored one (absent ≠ empty): the
* publish form saves appId/dest/codeBinding only, and a form save must not
* silently drop the contract an app declared through the API. Pass
* `runtimeContract: null` to clear it, or `binding: null` to clear everything.
*
* The inheritance is scoped to the SAME app — a contract describes the grid one
* particular app was built against, so carrying it across a re-point would make
* every publish to the new app 409 against an expectation that app never
* declared (and, with no UI for the field, leave no way out).
*
* Gated on the record carrying an animation track (#3017), not on it being a
* character — publishing an atlas is about the atlas, and a record kind that
* gains a non-directional ambient track should be bindable and publishable
* without this gate being revisited. Walk is character-only today, so nothing
* that used to be accepted or refused here changes.
*/
export async function setPublishBinding(recordId, binding) {
const record = await requireAnimatable(recordId);
const stored = record.publishBinding;
const effective = binding ? { ...binding } : null;
if (effective && effective.appId === stored?.appId) {
// Validate inherited paths too: a symlink may have appeared since the
// previous save, even when an older client omits optional destinations.
for (const field of ['runtimeContract', 'portraitDestPath', 'presentationIdleDestPath']) {
if (effective[field] === undefined) effective[field] = stored[field] ?? null;
}
}
const validated = await validatePublishBinding(effective);
return updateRecord(recordId, { publishBinding: validated });
}
/**
* Reverse lookup (#2991): the sprite records whose `publishBinding.appId`
* targets the given app, with their repo-relative destination paths. This is
* the app-side view of the publish relationship — it makes "PortOS is the
* creative source for this app" legible from the app's own detail page, rather
* than a hidden per-record setting. Returns `[]` for an app nothing publishes
* into (and for a falsy appId). Publishing itself still resolves purely from
* the app's `repoPath`; this is display-only and never gates a publish.
*/
export async function listPublishBindingsForApp(appId) {
if (!appId) return [];
const records = await listRecords();
return records
.filter((r) => r?.publishBinding?.appId === appId)
.map((r) => ({
recordId: r.id,
name: r.name || r.id,
kind: r.kind || null,
atlasDestPath: r.publishBinding.atlasDestPath || null,
portraitDestPath: r.publishBinding.portraitDestPath || null,
presentationIdleDestPath: r.publishBinding.presentationIdleDestPath || null,
codeBindingPath: r.publishBinding.codeBinding?.path || null,
}));
}
const countOccurrences = (text, needle) => (needle ? text.split(needle).length - 1 : 0);
/**
* Verify (or occurrence-guarded-rewrite) the game-source code binding.
* Returns the publication's codeBinding summary; throws on drift.
*/
async function applyCodeBinding(repoRoot, codeBinding, previousResourcePath) {
const abs = await anchorRepoPath(repoRoot, codeBinding.path, 'codeBinding.path');
const required = codeBinding.requiredOccurrenceCount ?? 1;
const text = await readFile(abs, 'utf8').catch(() => null);
if (text === null) {
throw new ServerError(`Code binding file not found in app repo: ${codeBinding.path}`, { status: 409, code: 'CODE_BINDING_MISSING' });
}
const currentCount = countOccurrences(text, codeBinding.resourcePath);
if (currentCount === required) {
return { ...codeBinding, rewritten: false };
}
// Destination moved since the last publish: the file should still hold the
// previously-published resource path exactly N times — rewrite it.
if (previousResourcePath && previousResourcePath !== codeBinding.resourcePath) {
const previousCount = countOccurrences(text, previousResourcePath);
if (previousCount === required) {
await anchorRepoPath(repoRoot, codeBinding.path, 'codeBinding.path');
await atomicWrite(abs, text.split(previousResourcePath).join(codeBinding.resourcePath));
return { ...codeBinding, rewritten: true, previousResourcePath };
}
}
throw new ServerError(
`Code binding drifted: ${codeBinding.path} contains ${currentCount} occurrence(s) of the resource path (expected ${required})`,
{ status: 409, code: 'CODE_BINDING_DRIFTED' },
);
}
/**
* Compile (idempotently) and publish the runtime atlas into the bound
* managed app. Refuses without a binding, on a diverged destination, on an
* occupied destination PortOS never published (unless explicitly
* acknowledged), and on code-binding drift. Idempotent: a destination
* already holding the current atlas bytes records nothing and touches
* nothing.
*/
export function publishAtlas(recordId, options = {}) {
return withWalkWriteTail(recordId, () => publishAtlasImpl(recordId, options));
}
async function publishAtlasImpl(recordId, { acknowledgeOverwrite = false } = {}) {
const record = await requireAnimatable(recordId);
const binding = record.publishBinding;
if (!binding?.appId || !binding?.atlasDestPath) {
throw new ServerError('No publish binding configured — set the target app and atlas path first', { status: 409, code: 'PUBLISH_BINDING_REQUIRED' });
}
const { app, repoRoot } = await requireAppRepo(binding.appId, 409);
const dir = spriteDir(recordId);
// Reuse the current pointer's geometry so publish ships the atlas the user
// compiled and previewed — a bare default-geometry recompile would silently
// discard a custom-geometry compile and flip the pointer back to defaults.
const pointer = await readJSONFile(join(dir, RUNTIME_POINTER_REL), null, { strict: true });
const geometryOverride = pointer?.geometry
? {
cellSize: pointer.geometry.cellSize,
pivot: pointer.geometry.pivot,
targetMaxHeight: pointer.geometry.targetMaxHeight,
targetMaxWidth: pointer.geometry.targetMaxWidth,
}
: undefined;
const compiled = await compileAtlasInTail(recordId, { geometry: geometryOverride });
// Export contract (#2982). Everything below runs BEFORE the repo write lock,
// so a publish the bound app cannot consume leaves the game tree untouched.
// One geometry assertion serves both the contract compare and the sidecar.
const appLabel = app.name || binding.appId;
if (!Array.isArray(compiled.geometry?.columns)) {
throw new ServerError(
'The compiled atlas reports no column layout, so neither its export contract nor its layout sidecar can be resolved — recompile the atlas before publishing.',
{ status: 422, code: 'ATLAS_GEOMETRY_UNKNOWN' },
);
}
// No declared contract ⇒ unchanged, unchecked behavior.
const mismatch = runtimeContractMismatch(compiled.geometry, binding.runtimeContract, appLabel);
if (mismatch) throw new ServerError(mismatch, { status: 409, code: 'PUBLISH_CONTRACT_MISMATCH' });
// The sidecar describing the grid PortOS actually produced. Built here (pure,
// lock-free) so the same bytes serve both the write and the up-to-date
// comparison below. It carries no timestamp: identical geometry ⇒ identical
// bytes ⇒ a republish is a genuine no-op.
const layout = buildAtlasLayout({
characterId: recordId,
geometry: compiled.geometry,
atlasSha256: compiled.atlasSha256,
version: compiled.version,
atlasDestPath: binding.atlasDestPath,
});
const layoutBuffer = Buffer.from(`${JSON.stringify(layout, null, 2)}\n`);
const layoutSha256 = sha256Buffer(layoutBuffer);
const layoutDestPath = layoutSidecarPath(binding.atlasDestPath);
const portrait = binding.portraitDestPath
? await buildPresentationPortrait(recordId, record)
: null;
const presentationIdle = binding.presentationIdleDestPath
? await buildPresentationIdle(recordId)
: null;
const presentationIdleLayout = presentationIdle
? buildPresentationIdleLayout(presentationIdle, binding.presentationIdleDestPath)
: null;
const presentationIdleLayoutBuffer = presentationIdleLayout
? Buffer.from(`${JSON.stringify(presentationIdleLayout, null, 2)}\n`)
: null;
const presentationIdleLayoutSha256 = presentationIdleLayoutBuffer
? sha256Buffer(presentationIdleLayoutBuffer)
: null;
const presentationIdleLayoutDestPath = presentationIdle
? presentationIdleSidecarPath(binding.presentationIdleDestPath)
: null;
return repoPublishTail(resolve(repoRoot), async () => {
// Don't mutate a tree a deploy is currently building from — appDeployer
// keys its lock by repoPath, so honor it here (the reverse direction —
// deploy checking publishes — isn't needed; publishes are sub-second).
if (isDeploying(app.repoPath)) {
throw new ServerError(`App ${appLabel} is deploying — retry when the deploy finishes`, { status: 409, code: 'APP_DEPLOY_IN_PROGRESS' });
}
const destAbs = await anchorRepoPath(repoRoot, binding.atlasDestPath, 'atlasDestPath');
// The sidecar is repo-anchored and written inside this same per-repo tail
// as the PNG, so the pair is never interleaved with another publish into
// the same checkout.
const layoutAbs = await anchorRepoPath(repoRoot, layoutDestPath, 'atlas layout sidecar');
const portraitAbs = portrait
? await anchorRepoPath(repoRoot, binding.portraitDestPath, 'portraitDestPath')
: null;
const presentationIdleAbs = presentationIdle
? await anchorRepoPath(repoRoot, binding.presentationIdleDestPath, 'presentationIdleDestPath')
: null;
const presentationIdleLayoutAbs = presentationIdle
? await anchorRepoPath(repoRoot, presentationIdleLayoutDestPath, 'picker animation sidecar')
: null;
const destinations = [
[binding.atlasDestPath, 'atlasDestPath'],
[layoutDestPath, 'atlas layout sidecar'],
...(portrait ? [[binding.portraitDestPath, 'portraitDestPath']] : []),
...(presentationIdle ? [
[binding.presentationIdleDestPath, 'presentationIdleDestPath'],
[presentationIdleLayoutDestPath, 'picker animation sidecar'],
] : []),
...(binding.codeBinding ? [[binding.codeBinding.path, 'codeBinding.path']] : []),
];
const preflightDestinations = async () => {
for (const [path, label] of destinations) await anchorRepoPath(repoRoot, path, label);
};
// Media paths were checked above; check source before any app-file reads.
if (binding.codeBinding) await anchorRepoPath(repoRoot, binding.codeBinding.path, 'codeBinding.path');
// Repeat the complete preflight after creating output parents, before
// either branch can rewrite source.
const prepareDestinations = async () => {
for (const [path, label] of destinations) {
const abs = await anchorRepoPath(repoRoot, path, label);
await mkdir(dirname(abs), { recursive: true });
await anchorRepoPath(repoRoot, path, label);
}
await preflightDestinations();
};
const writeDestination = async (path, label, buffer) => {
const abs = await anchorRepoPath(repoRoot, path, label);
await atomicWrite(abs, buffer);
};
const existingLayout = await readFile(layoutAbs).catch(() => null);
const layoutUpToDate = Boolean(existingLayout?.equals(layoutBuffer));
// Occupied-destination guard, mirroring the atlas's: PortOS owns files it
// stamped with its own `kind`, and will regenerate one freely, but a JSON
// file it never wrote sitting at that path is somebody else's — replacing
// it needs the same explicit acknowledgment replacing a foreign atlas does.
// A malformed/non-JSON file counts as foreign too: a parse failure must
// not become a 500, and must not license an overwrite.
//
// Split from the write and asserted BEFORE applyCodeBinding, which mutates
// the game's source file — a refusal after that rewrite would leave the
// source pointing at an atlas this publish then declined to write.
const assertLayoutDestWritable = () => {
if (layoutUpToDate || acknowledgeOverwrite || !existingLayout) return;
if (safeJSONParse(existingLayout.toString('utf8'))?.kind !== ATLAS_LAYOUT_KIND) {
throw new ServerError(
`${layoutDestPath} already exists and was not written by PortOS — confirm the overwrite to replace it.`,
{ status: 409, code: 'PUBLISH_LAYOUT_OCCUPIED' },
);
}
};
// Write only when the content actually differs, so a republish that changes
// nothing stays a genuine no-op. Returns whether the repo was mutated — an
// atlas already at the destination but MISSING its sidecar still gets one,
// so the two can never be permanently out of step.
const writeLayoutSidecar = async () => {
if (layoutUpToDate) return false;
await writeDestination(layoutDestPath, 'atlas layout sidecar', layoutBuffer);
return true;
};
const atlasBuffer = await readFile(join(dir, compiled.atlasPath)).catch(() => null);
if (!atlasBuffer) {
throw new ServerError('Compiled atlas file is missing on disk — recompile before publishing', { status: 422, code: 'ATLAS_OUTPUT_MISSING' });
}
// The only path that writes outside data/ ships exactly the bytes the
// evidence chain vouched for — never a tampered runtime/vN file.
if (sha256Buffer(atlasBuffer) !== compiled.atlasSha256) {
throw new ServerError('Compiled atlas bytes no longer match their recorded sha256 — recompile before publishing', { status: 422, code: 'ATLAS_OUTPUT_TAMPERED' });
}
const publications = await readJSONFile(join(dir, RUNTIME_PUBLICATIONS_REL), [], { strict: true });
const previous = [...publications].reverse().find(
(p) => p.appId === binding.appId && p.atlasDestPath === binding.atlasDestPath,
);
// The code-binding baseline follows the FILE, not the destination — a
// destination move changes atlasDestPath, and the rewrite exists exactly
// for that case, so a dest-keyed lookup would never find the old
// resource path to rewrite from.
const previousForCode = binding.codeBinding
? [...publications].reverse().find(
(p) => p.appId === binding.appId && p.codeBinding?.path === binding.codeBinding.path,
)
: null;
const previousPortrait = portrait
? [...publications].reverse().find(
(p) => p.appId === binding.appId && p.portraitDestPath === binding.portraitDestPath,
)
: null;
const previousPresentationIdle = presentationIdle
? [...publications].reverse().find(
(p) => p.appId === binding.appId
&& p.presentationIdleDestPath === binding.presentationIdleDestPath,
)
: null;
const recordPublication = async (extra) => {
const publication = {
publishedAt: new Date().toISOString(),
characterId: recordId,
version: compiled.version,
atlasPath: compiled.atlasPath,
atlasSha256: compiled.atlasSha256,
appId: binding.appId,
appName: app.name || null,
atlasDestPath: binding.atlasDestPath,
portraitDestPath: binding.portraitDestPath || null,
portraitSha256: portrait?.sha256 || null,
portraitSourcePath: portrait?.sourcePath || null,
portraitSourceSha256: portrait?.sourceSha256 || null,
portraitSize: portrait?.size || null,
presentationIdleDestPath: binding.presentationIdleDestPath || null,
presentationIdleSha256: presentationIdle?.sha256 || null,
presentationIdleSourceManifestPath: presentationIdle?.sourceManifestPath || null,
presentationIdleSourceManifestSha256: presentationIdle?.sourceManifestSha256 || null,
presentationIdleSourceFrameSha256s: presentationIdle?.sourceFrameSha256s || null,
presentationIdleFrameCount: presentationIdle?.frameCount || null,
presentationIdleFrameRate: presentationIdle?.frameRate || null,
presentationIdleCellSize: presentationIdle?.cellSize || null,
presentationIdleLayoutDestPath,
presentationIdleLayoutSha256,
...extra,
};
publications.push(publication);
await atomicWrite(join(dir, RUNTIME_PUBLICATIONS_REL), publications);
return publication;
};
const portraitDestSha256 = portrait && await pathExists(portraitAbs)
? await sha256File(portraitAbs)
: null;
const portraitUpToDate = Boolean(portrait && portraitDestSha256 === portrait.sha256);
const assertPortraitDestWritable = () => {
if (!portrait || portraitUpToDate || acknowledgeOverwrite || portraitDestSha256 === null) return;
if (previousPortrait && portraitDestSha256 !== previousPortrait.portraitSha256) {
throw new ServerError(
'Destination portrait no longer matches the previous publish — it was changed outside PortOS. Resolve it in the game repo, then re-publish.',
{ status: 409, code: 'PUBLISH_PORTRAIT_DIVERGED' },
);
}
if (!previousPortrait) {
throw new ServerError(
'Destination already contains a portrait PortOS did not publish — confirm the overwrite to replace it.',
{ status: 409, code: 'PUBLISH_PORTRAIT_OCCUPIED' },
);
}
};
const writePortrait = async () => {
if (!portrait || portraitUpToDate) return false;
await writeDestination(binding.portraitDestPath, 'portraitDestPath', portrait.buffer);
return true;
};
const presentationIdleDestSha256 = presentationIdle && await pathExists(presentationIdleAbs)
? await sha256File(presentationIdleAbs)
: null;
const presentationIdleUpToDate = Boolean(
presentationIdle && presentationIdleDestSha256 === presentationIdle.sha256,
);
const assertPresentationIdleDestWritable = () => {
if (!presentationIdle
|| presentationIdleUpToDate
|| acknowledgeOverwrite
|| presentationIdleDestSha256 === null) return;
if (previousPresentationIdle
&& presentationIdleDestSha256 !== previousPresentationIdle.presentationIdleSha256) {
throw new ServerError(
'Destination picker animation no longer matches the previous publish — it was changed outside PortOS. Resolve it in the game repo, then re-publish.',
{ status: 409, code: 'PUBLISH_PRESENTATION_IDLE_DIVERGED' },
);
}
if (!previousPresentationIdle) {
throw new ServerError(
'Destination already contains a picker animation PortOS did not publish — confirm the overwrite to replace it.',
{ status: 409, code: 'PUBLISH_PRESENTATION_IDLE_OCCUPIED' },
);
}
};
const writePresentationIdle = async () => {
if (!presentationIdle || presentationIdleUpToDate) return false;
await writeDestination(binding.presentationIdleDestPath, 'presentationIdleDestPath', presentationIdle.buffer);
return true;
};
const existingPresentationIdleLayout = presentationIdle
? await readFile(presentationIdleLayoutAbs).catch(() => null)
: null;
const presentationIdleLayoutUpToDate = Boolean(
existingPresentationIdleLayout?.equals(presentationIdleLayoutBuffer),
);
const assertPresentationIdleLayoutWritable = () => {
if (!presentationIdle
|| presentationIdleLayoutUpToDate
|| acknowledgeOverwrite
|| !existingPresentationIdleLayout) return;
if (safeJSONParse(existingPresentationIdleLayout.toString('utf8'))?.kind
!== PRESENTATION_IDLE_LAYOUT_KIND) {
throw new ServerError(
`${presentationIdleLayoutDestPath} already exists and was not written by PortOS — confirm the overwrite to replace it.`,
{ status: 409, code: 'PUBLISH_PRESENTATION_IDLE_LAYOUT_OCCUPIED' },
);
}
};
const writePresentationIdleLayout = async () => {
if (!presentationIdle || presentationIdleLayoutUpToDate) return false;
await writeDestination(presentationIdleLayoutDestPath, 'picker animation sidecar', presentationIdleLayoutBuffer);
return true;
};
const destSha256 = (await pathExists(destAbs)) ? await sha256File(destAbs) : null;
if (destSha256 === compiled.atlasSha256) {
assertLayoutDestWritable();
assertPortraitDestWritable();
assertPresentationIdleDestWritable();
assertPresentationIdleLayoutWritable();
await prepareDestinations();
// Verify the code binding even on a no-op so drift never hides.
const codeBinding = binding.codeBinding
? await applyCodeBinding(repoRoot, binding.codeBinding, previousForCode?.codeBinding?.resourcePath)
: null;
// An up-to-date atlas can still be missing (or carrying a stale) layout
// sidecar — from a publish that predates it, or a hand-deleted file.
// Reconcile it here so the pair converges on the next publish.
const layoutWritten = await writeLayoutSidecar();
const portraitWritten = await writePortrait();
const presentationIdleLayoutWritten = await writePresentationIdleLayout();
const presentationIdleWritten = await writePresentationIdle();
// The destination already holds the current bytes, but three sub-cases
// still mutate durable state and must be recorded: a code-binding
// rewrite just changed the game's source, the sidecar was just written,
// and a first-ever publish finding its own bytes needs a history
// baseline (otherwise the next changed-atlas publish reads the dest as
// foreign and 409s OCCUPIED).
let publication = null;
if ((codeBinding?.rewritten
|| layoutWritten
|| portraitWritten
|| presentationIdleLayoutWritten
|| presentationIdleWritten
|| !previous
|| (portrait && !previousPortrait)
|| (presentationIdle && !previousPresentationIdle))) {
publication = await recordPublication({
destPreviousSha256: destSha256, codeBinding, layoutDestPath, layoutSha256, upToDateBaseline: true,
});
}
return {
published: false,
upToDate: true,
compiled,
codeBinding,
publication,
layoutWritten,
layoutDestPath,
portraitWritten,
presentationIdleWritten,
presentationIdleLayoutWritten,
};
}
if (previous && destSha256 !== null && destSha256 !== previous.atlasSha256) {
throw new ServerError(
'Destination atlas no longer matches the previous publish — it was changed outside PortOS. Resolve in the game repo, then re-publish.',
{ status: 409, code: 'PUBLISH_DEST_DIVERGED' },
);
}
// Never silently destroy bytes PortOS didn't write: a destination that
// already exists with no publication history needs an explicit overwrite
// acknowledgment from the caller.
if (!previous && destSha256 !== null && !acknowledgeOverwrite) {
throw new ServerError(
'Destination already contains an atlas PortOS did not publish — confirm the overwrite to replace it.',
{ status: 409, code: 'PUBLISH_DEST_OCCUPIED' },
);
}
// Verify/rewrite the code binding BEFORE replacing the atlas so a drifted
// binding aborts the publish with the game repo untouched — and assert the
// sidecar destination first, since that rewrite is itself a mutation.
assertLayoutDestWritable();
assertPortraitDestWritable();
assertPresentationIdleDestWritable();
assertPresentationIdleLayoutWritable();
await prepareDestinations();
const codeBinding = binding.codeBinding
? await applyCodeBinding(repoRoot, binding.codeBinding, previousForCode?.codeBinding?.resourcePath)
: null;
// Sidecar BEFORE the atlas. Either order has a crash window, but only this
// one fails loudly: the layout carries `sourceAtlasSha256`, so a sidecar
// that landed without its atlas is DETECTABLE by the consumer, whereas a
// new atlas under a stale/absent layout is exactly the silent column shift
// this whole contract exists to prevent.
const layoutWritten = await writeLayoutSidecar();
const portraitWritten = await writePortrait();
const presentationIdleLayoutWritten = await writePresentationIdleLayout();
const presentationIdleWritten = await writePresentationIdle();
await writeDestination(binding.atlasDestPath, 'atlasDestPath', atlasBuffer);
const publication = await recordPublication({
destPreviousSha256: destSha256, codeBinding, layoutDestPath, layoutSha256,
});
console.log(`🚚 sprite atlas v${compiled.version} published for ${recordId} → ${appLabel}:${binding.atlasDestPath}`);
return {
published: true,
publication,
compiled,
layoutWritten,
layoutDestPath,
portraitWritten,
presentationIdleWritten,
presentationIdleLayoutWritten,
};
});
}