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

42.6 KB
Raw Blame
/**
 * Sprites — runtime atlas compiler (issue #2898, phase 4).
 *
 * Compiles the immutable runtime sprite-sheet from a finalized eight-direction
 * walk set: an (idle + N walk phases)-column × 8-row grid (× S/SE/E/
 * NE/N/NW/W/SW) of fixed-size cells, each frame scaled once per direction and
 * translated so it anchors on the pivot x and its sole lands exactly on the
 * pivot ground line. Placement is anchored on the TORSO, not the silhouette
 * centre, and shared across a direction's cells — a walk frame carries the
 * packer's pivot through the scale, the idle anchor measures its own (#3021) —
 * so a swinging limb cannot slide the character and idle→walk does not pop.
 * N (the walk frame count) is read from the approved
 * run manifests — every direction must share it — so the atlas width tracks the
 * authored count (historically 8; variable per #sprite-walk-variable-frames).
 * Ports the source pipeline's
 * `runtime_publish.py` compile stage; all math preserves Python semantics
 * (banker's rounding via pyRound, exclusive-bbox bounds) so cell placement
 * matches the production atlases the importer brought over.
 *
 * Every input is revalidated before any pixel work: walk-set kind/status/
 * direction order, the selection + per-direction run-manifest sha256s, every
 * packaged frame's sha256, and the locked reference set's anchor sha256s. A
 * failed hash means the evidence chain is broken — compile refuses rather
 * than compiling from tampered bytes.
 *
 * Output is immutable-by-version under data/sprites/<id>/runtime/vN/
 * (a differing byte-write to an existing version path is refused), with a
 * mutable current.json pointer. Recompiling the same finalized set is
 * idempotent: identical bytes → the existing version is returned untouched.
 */

import { join } from 'path';
import { readdir, readFile } from 'fs/promises';
import sharp from 'sharp';
import {
  atomicWrite, ensureDir, pathExists, readJSONFile, tryReadFile,
} from '../../lib/fileUtils.js';
import { ServerError } from '../../lib/errorHandler.js';
import {
  spriteDir, resolveSpriteAssetPath, RUNTIME_POINTER_REL, RUNTIME_PUBLICATIONS_REL,
  isSourcePipelinePath,
} from './paths.js';
import { requireAnimatable, loadManifest } from './reference.js';
import { SPRITE_DIRECTIONS } from './prompts.js';
import { keyChannelSplit } from './chromaKey.js';
import {
  WALK_PHASES, WALK_FPS,
  pyRound, pyRoundTo, median, premultipliedResize, decodeTransparentSpriteSource,
  despillKeyFrame,
  alphaBbox, robustBottomRow, rootX, rootBandForManifest, ROBUST_BASELINE_MIN_PIXELS, compositeOnto, sha256Buffer,
} from './walkPostprocess.js';
import { ATLAS_IDLE_COLUMN } from './walkBounds.js';
import {
  WALK_TRACK, SCANNER_TRACK, AMBIENT_TRACK,
  tracksForKind, primaryTrackForKind,
} from './animationTracks.js';
// #3152 — the DEFAULT registry table is the EFFECTIVE one (compiled `walk` + the
// user-defined store), not the compiled constant. Load-bearing now that #3158 made
// this compiler fully generic: it walks `tracksForKind` to find every track a
// record may carry, so with a compiled-only default a `place` record would resolve
// NO primary track (ambient is a stored row) and every ambient compile would fail
// with "has no animation track to compile". `animationTracks` stays an explicit
// parameter — still the injection seam the multi-track tests use.
import { getEffectiveAnimationTracks } from './animationTrackStore.js';
import {
  buildAtlasGrid, resolveTrackUniformity, compiledGridUpToDate, trackDirections,
} from './atlasGrid.js';
import {
  withWalkWriteTail, walkSetRelPath, importedWalkDirections, resolveChromaKey,
} from './walk.js';
import { trackSetRelPath } from './animationTrackWorkflow.js';
import { verifyPackagedFrames } from './walkFrames.js';
import { getRecord } from './records.js';

// Player atlas contract (source pipeline runtime_publish.py): 96px cells,
// pivot (48,88) — silhouette centered on x=48, feet on the y=88 ground line —
// content bounded to 86×74 so nothing touches a cell edge.
//
// The runtime grid is `idle` followed by one variable-length column span per
// animation track, in registry-registration order (#3016). Each track's length
// is read from its approved run manifests, not hardcoded, so the atlas width
// grows and shrinks with what was actually authored — and two tracks may
// legally differ in length, which is what makes a four-frame action beside a
// twelve-frame walk expressible. The span math lives in the sharp-free
// atlasGrid.js so the compiler that WRITES the grid and the sidecar that
// DESCRIBES it (atlasLayout.js) share one definition.
//
// ATLAS_COLUMNS remains the historical walk-only 8-frame layout, used as the
// default/fallback.
//
// A trailing `scanner` column used to follow the walk phases — a verbatim copy
// of the idle cell that no consumer ever sampled (#2986). It is no longer
// compiled: an action animation is its own named track, not a column bolted
// onto the walk cycle. Imported/legacy atlases and manifests that still carry
// the column keep loading and displaying unchanged — this is a write-side
// change only.
export const ATLAS_COLUMNS = buildAtlasGrid([{ id: WALK_TRACK, frameCount: WALK_PHASES.length }]).columns;

// A track whose historical run manifests predate the frameRate field falls back
// to the rate its frames were extracted at, not to the track's authoring
// default — so an older set compiles to exactly the atlas it always did. Keyed
// by track so a new track states its own answer (or omits it and takes its
// registry default) instead of adding a branch here.
const LEGACY_MANIFEST_FPS = { [WALK_TRACK]: WALK_FPS };
export const DEFAULT_ATLAS_GEOMETRY = {
  cellSize: 96,
  pivot: [48, 88],
  targetMaxHeight: 74,
  targetMaxWidth: 86,
};

// Silhouette-visibility alpha thresholds (exclusive bbox at alpha > N).
// Walk frames measure at 8; the idle anchor measures at 64 so chroma-key
// recovery noise can't inflate the character and shrink its scale.
const ALPHA_THRESHOLD = 8;
const SILHOUETTE_ALPHA_THRESHOLD = 64;
// Post-resize alpha snap (Python premultiplied_resize's ALPHA_NOISE_FLOOR).
const ALPHA_NOISE_FLOOR = 2;
// Compiled idle height must match the walk row's median height within two
// logical (96px-contract) pixels. Scale the rounding tolerance with source
// density so a 2×/3× compile applies the same visual standard.
const IDLE_HEIGHT_TOLERANCE = 2;

const RUNTIME_DIR = 'runtime';
const atlasStem = (recordId) => `${recordId}-animation-atlas`;

const compileError = (message, code = 'ATLAS_COMPILE_INVALID') =>
  new ServerError(message, { status: 422, code });

/**
 * The minimum opaque-pixel count a row needs to read as the sole rather than a
 * stray speck, at a given resize factor. A cell is typically upscaled from the
 * packer's frame, and the resize smears one source pixel across ~`scale` of
 * them — so a fixed count would let an upscaled speck masquerade as a sole.
 */
const cellMinRun = (scale) => Math.max(ROBUST_BASELINE_MIN_PIXELS, Math.ceil(ROBUST_BASELINE_MIN_PIXELS * scale));

/**
 * `robust` measures height to the SOLE rather than to the lowest lit pixel
 * (#3021). It matters here and not only at placement time: these dimensions set
 * the direction's scale, so a single speck below the feet made one frame read
 * taller, shrank the scale for the whole direction, and pushed the compiled idle
 * height off the walk median it is asserted against. Off for the idle anchor,
 * which is measured at the silhouette threshold on a raw reference.
 */
function occupiedDimensions(frame, threshold, label, robust = false) {
  const bounds = alphaBbox(frame, threshold);
  if (!bounds) throw compileError(`${label} has no visible pixels`);
  const bottom = robust ? robustBottomRow(frame, threshold) : bounds.bottom;
  return { width: bounds.right - bounds.left, height: bottom - bounds.top };
}

/**
 * Scale a source frame once and measure what placement needs from it: the bbox
 * the cell-edge guards test, and the sole the ground line is pinned to.
 * Placement itself is `placeCell` — the two are split because a direction's x is
 * SHARED, so every frame has to be measured before any of them can be placed.
 */
async function scaleForCell(source, scale, label) {
  const width = Math.max(1, pyRound(source.width * scale));
  const height = Math.max(1, pyRound(source.height * scale));
  const scaled = await premultipliedResize(source, width, height);
  // Python's premultiplied_resize snaps sub-noise alpha after re-straightening.
  for (let i = 3; i < scaled.data.length; i += 4) {
    if (scaled.data[i] <= ALPHA_NOISE_FLOOR) {
      scaled.data[i - 3] = 0; scaled.data[i - 2] = 0; scaled.data[i - 1] = 0; scaled.data[i] = 0;
    }
  }
  const bounds = alphaBbox(scaled, ALPHA_THRESHOLD);
  if (!bounds) throw compileError(`${label} has no visible pixels after scaling`);
  // The SOLE, not the lowest lit pixel — vertical placement keys on this.
  // Pinning the raw bbox bottom is what let a sub-sole speck set the ground line
  // and bob the body (#3021), and fixing it only in the packer would have been
  // undone right here: the packer would place the sole at its baseline, leaving
  // the speck lower, and this stage would pin the SPECK to the ground line,
  // landing the body exactly where it started.
  //
  // Measured on `scaled`, in the same space the ground-line assertion re-measures
  // — but with the pixel threshold scaled to match. These cells are upscaled
  // ~2.5x, and a lanczos upscale smears a single stray pixel into a blob several
  // pixels wide, wide enough to clear a fixed threshold and be mistaken for a
  // sole. Scaling the threshold keeps "a speck is a speck" true at any cell size.
  const baseline = robustBottomRow(scaled, ALPHA_THRESHOLD, cellMinRun(scale));
  return { scaled, bounds, baseline };
}

/**
 * Translate an already-scaled frame into a cell at the given x, with its sole on
 * the pivot ground line — translation-only placement, refusing any content that
 * touches a cell edge.
 */
function placeCell(scaled, bounds, baseline, pasteX, label, geometry, scale) {
  const { cellSize, pivot } = geometry;
  const pasteY = pivot[1] - (baseline - 1);
  if (pasteX + bounds.left <= 0 || pasteY + bounds.top <= 0) {
    throw compileError(`${label} touches the top or left runtime cell edge`);
  }
  if (pasteX + bounds.right >= cellSize || pasteY + bounds.bottom >= cellSize) {
    throw compileError(`${label} touches the right or bottom runtime cell edge`);
  }
  const cell = { data: Buffer.alloc(cellSize * cellSize * 4), width: cellSize, height: cellSize };
  compositeOnto(cell, scaled, pasteX, pasteY);
  // Port-faithful belt-and-braces: re-measure the composed cell and verify the
  // feet really sit on the ground line (runtime_publish.py does the same final
  // _bounds check rather than trusting the placement math). Measured by the same
  // robust rule that positioned it — asserting on the raw bbox would fail for
  // any frame carrying a speck below the sole, which is precisely the case this
  // is meant to tolerate.
  const final = alphaBbox(cell, ALPHA_THRESHOLD);
  if (!final || robustBottomRow(cell, ALPHA_THRESHOLD, cellMinRun(scale)) - 1 !== pivot[1]) {
    throw compileError(`${label} misses the runtime ground line y=${pivot[1]}`);
  }
  return {
    cell,
    meta: {
      scale: pyRoundTo(scale, 8),
      translation: [pasteX, pasteY],
      occupiedBounds: {
        left: final.left,
        top: final.top,
        width: final.right - final.left,
        height: final.bottom - final.top,
      },
    },
  };
}

/**
 * The shared x every cell of one direction is placed at, and the correction (if
 * any) needed to keep the whole row inside its cells.
 *
 * Anchoring on the packer's torso pivot rather than each cell's own silhouette
 * centre is what preserves registration through compile (#3021) — but it also
 * moves content off-centre by however far the torso sits from the silhouette
 * middle, which for a wide sprite can be enough to touch a cell edge and turn a
 * previously-successful compile into a hard 422. So the row is shifted back as a
 * WHOLE when that happens: relative registration between frames is preserved
 * exactly (the point of the fix), and only the row's absolute offset gives way.
 * Per-frame correction would reintroduce the very drift being removed.
 */
function sharedRowPasteX(anchoredX, boundsList, geometry) {
  const { cellSize } = geometry;
  const minLeft = Math.min(...boundsList.map((b) => anchoredX + b.left));
  const maxRight = Math.max(...boundsList.map((b) => anchoredX + b.right));
  if (minLeft <= 0) return anchoredX + (1 - minLeft);
  if (maxRight >= cellSize) return anchoredX - (maxRight - cellSize + 1);
  return anchoredX;
}

/**
 * Revalidate every registered track's evidence chain: finalized set →
 * selection → run manifests → packaged frame bytes, plus the locked reference
 * source. Returns everything the compiler consumes.
 */
export async function validateForCompile(recordId, animationTracks = getEffectiveAnimationTracks()) {
  return validateForCompileWithTracks(recordId, animationTracks);
}

async function validateForCompileWithTracks(recordId, animationTracks) {
  const record = await getRecord(recordId);
  const primary = primaryTrackForKind(record?.kind, animationTracks);
  const registryRows = tracksForKind(record?.kind, animationTracks);
  if (!primary || !registryRows.length) {
    throw compileError(`Sprite kind '${String(record?.kind)}' has no animation track to compile`);
  }

  // Every hashed input is read exactly once: verify the bytes in memory and
  // hand those same bytes to the compiler, so the pixels compiled are
  // provably the pixels verified (no re-read between check and use). Paths
  // come from server-owned manifests but still route through the record-dir
  // confinement gate (resolveSpriteAssetPath) per the paths.js contract.
  const readVerified = async (relPath, expectedSha, label) => {
    const bytes = await readFile(resolveSpriteAssetPath(recordId, relPath)).catch(() => null);
    if (!bytes || sha256Buffer(bytes) !== expectedSha) {
      throw compileError(`${label} no longer matches its recorded sha256`);
    }
    return bytes;
  };

  const dir = spriteDir(recordId);
  const loaded = {};
  for (const row of registryRows) {
    const setPath = row.id === WALK_TRACK ? walkSetRelPath(recordId) : trackSetRelPath(row.id, recordId);
    // eslint-disable-next-line no-await-in-loop -- registry order is the compiled span order
    const setBytes = await readFile(join(dir, setPath)).catch(() => null);
    if (!setBytes) {
      if (row.id !== primary.id) continue;
      if (row.id === WALK_TRACK) {
        throw compileError('No finalized walk set — approve all 8 directions first', 'WALK_SET_REQUIRED');
      }
      if (row.id === AMBIENT_TRACK) {
        throw compileError('No finalized ambient loop — approve its single row first', 'AMBIENT_SET_REQUIRED');
      }
      throw compileError(`No finalized ${row.label.toLowerCase()} set`, 'TRACK_SET_REQUIRED');
    }
    let set;
    try {
      set = JSON.parse(setBytes);
    } catch {
      throw compileError(`${row.label} set manifest is unreadable`);
    }
    const directions = trackDirections(row.id, SPRITE_DIRECTIONS, animationTracks);
    const trackMatches = row.id === WALK_TRACK ? (!set.track || set.track === row.id) : set.track === row.id;
    if (set.kind !== row.setKind || !trackMatches || set.status !== 'final' || set.characterId !== recordId
      || JSON.stringify(set.directionOrder) !== JSON.stringify(directions)) {
      throw compileError(`${row.label} set manifest is not a finalized ${row.directional ? 'directional' : 'single-row'} set`);
    }
    if (row.id === WALK_TRACK) {
      const stale = importedWalkDirections(set);
      if (stale.length || isSourcePipelinePath(set.selectionPath)) {
        const which = stale.length ? `${stale.join(', ')} ${stale.length === 1 ? 'is' : 'are'}` : 'This walk set is';
        throw new ServerError(
          `${which} still packaged by the source pipeline, whose per-frame images were not imported — PortOS cannot compile from them. `
          + 'Reopen each such direction and reprocess it from its imported clip to re-derive the frames here, then compile. '
          + 'A direction with no imported clip cannot be re-derived at all — re-import the character to bring its clips across. '
          + 'The imported runtime atlases remain available in the asset library.',
          { status: 409, code: 'LEGACY_IMPORTED_WALK_SET' },
        );
      }
    }
    // eslint-disable-next-line no-await-in-loop -- validate each set before its run graph
    await readVerified(set.selectionPath, set.selectionSha256, `${row.label} selection file`);
    loaded[row.id] = {
      id: row.id,
      definition: row,
      set,
      setPath,
      setSha256: sha256Buffer(setBytes),
      directions,
    };
  }

  const referenceManifest = await loadManifest(recordId);
  const chromaKey = resolveChromaKey({ manifest: referenceManifest, record });
  if (!chromaKey) throw compileError('Reference manifest has no frozen chroma key');
  const anchors = {};
  let mainReference = null;
  if (primary.directional) {
    if (!referenceManifest || referenceManifest.status !== 'complete') {
      throw compileError('Reference set is not complete — all 8 anchors must be locked', 'REFERENCE_INCOMPLETE');
    }
    for (const direction of SPRITE_DIRECTIONS) {
      const anchor = (referenceManifest.anchors || []).find((item) => item.direction === direction);
      if (!anchor || anchor.status !== 'locked' || !anchor.path) {
        throw compileError(`Anchor for ${direction} is not locked`);
      }
      // eslint-disable-next-line no-await-in-loop -- read-once evidence verification
      const bytes = await readVerified(anchor.path, anchor.sha256, `Anchor for ${direction}`);
      anchors[direction] = { ...anchor, bytes };
    }
  } else {
    const main = referenceManifest?.mainReference;
    if (!main?.locked || !main.path || !main.sha256) {
      throw compileError('Main reference is not locked', 'REFERENCE_INCOMPLETE');
    }
    mainReference = {
      ...main,
      bytes: await readVerified(main.path, main.sha256, 'Locked main reference'),
    };
  }

  // Two passes per track: agree on shape using the small manifests first, then
  // read and hash every frame. A malformed row therefore fails before the
  // expensive pixel graph is loaded.
  for (const row of registryRows) {
    const track = loaded[row.id];
    if (!track) continue;
    const pendingRuns = {};
    const rows = [];
    for (const direction of track.directions) {
      const entry = track.set.directions?.[direction];
      if (!entry || entry.status !== 'approved') {
        throw compileError(`${row.label} direction ${direction} is not approved`);
      }
      // eslint-disable-next-line no-await-in-loop -- evidence chain is ordered per facing
      const manifestBytes = await readVerified(
        entry.runManifest,
        entry.runManifestSha256,
        `${row.label} run manifest for ${direction}`,
      );
      let manifest;
      try {
        manifest = JSON.parse(manifestBytes);
      } catch {
        manifest = null;
      }
      const manifestTrackMatches = row.id === WALK_TRACK
        ? (!manifest?.track || manifest.track === row.id)
        : manifest?.track === row.id;
      if (!manifest || !manifestTrackMatches || manifest.direction !== direction) {
        throw compileError(`${row.label} run manifest for ${direction} is unreadable or mislabeled`);
      }
      pendingRuns[direction] = { entry, manifest };
      rows.push({
        direction,
        frameCount: (manifest.frames || []).length,
        declaredFrameCount: manifest.frameCount,
        fps: manifest.frameRate,
      });
    }
    const uniform = resolveTrackUniformity(row.id, rows, {
      tracks: animationTracks,
      error: compileError,
      defaultFps: LEGACY_MANIFEST_FPS[row.id],
      expectedRows: track.directions.length,
    });
    const runs = {};
    for (const direction of track.directions) {
      const { entry, manifest } = pendingRuns[direction];
      // eslint-disable-next-line no-await-in-loop -- read-once frame verification
      const { frameBytes } = await verifyPackagedFrames(recordId, manifest, {
        bytes: true,
        track: row.id,
        tracks: animationTracks,
      });
      runs[direction] = {
        runId: entry.runId,
        manifestPath: entry.runManifest,
        manifest,
        frameBytes,
      };
    }
    loaded[row.id] = {
      ...track,
      rows,
      runs,
      frameCount: uniform.frameCount,
      fps: uniform.fps,
    };
  }

  const walk = loaded[WALK_TRACK];
  const scanner = loaded[SCANNER_TRACK];
  const ambient = loaded[AMBIENT_TRACK];
  return {
    primaryTrackId: primary.id,
    referenceManifest,
    chromaKey,
    anchors,
    mainReference,
    tracks: loaded,
    // Legacy views remain additive compatibility fields for existing runtime
    // pointers and consumers. The generic compiler itself reads `tracks`.
    walkSet: walk?.set || null,
    walkSetPath: walk?.setPath || null,
    walkSetSha256: walk?.setSha256 || null,
    scannerSet: scanner?.set || null,
    scannerSetPath: scanner?.setPath || null,
    scannerSetSha256: scanner?.setSha256 || null,
    ambientSet: ambient?.set || null,
    ambientSetPath: ambient?.setPath || null,
    ambientSetSha256: ambient?.setSha256 || null,
    walkFrameCount: walk?.frameCount ?? null,
    walkFps: walk?.fps ?? null,
    scannerFrameCount: scanner?.frameCount ?? null,
    ambientFrameCount: ambient?.frameCount ?? null,
  };
}

async function prepareTrackCells(track, direction, validated, geometry, split) {
  const run = track.runs[direction];
  const sources = [];
  for (const bytes of run.frameBytes) {
    // eslint-disable-next-line no-await-in-loop -- sharp transforms preserve frame order
    sources.push(await decodeTransparentSpriteSource(bytes, split, validated.chromaKey));
  }
  const dims = sources.map((source, index) => occupiedDimensions(
    source,
    ALPHA_THRESHOLD,
    `${direction}-${run.manifest.frames[index].phase}`,
    true,
  ));
  const scale = Math.min(
    geometry.targetMaxHeight / Math.max(...dims.map((dim) => dim.height)),
    geometry.targetMaxWidth / Math.max(...dims.map((dim) => dim.width)),
  );
  const pivotX = Number(run.manifest.alignment?.targetPivot?.[0]);
  const sourcePivotX = Number.isFinite(pivotX)
    ? pivotX
    : (Number(run.manifest.alignment?.cellSize) || sources[0].width) / 2;
  const scaled = [];
  for (let index = 0; index < sources.length; index++) {
    // eslint-disable-next-line no-await-in-loop -- frame order is the atlas order
    scaled.push(await scaleForCell(
      sources[index],
      scale,
      `${direction}-${run.manifest.frames[index].phase}`,
    ));
  }
  const pasteX = sharedRowPasteX(
    pyRound(geometry.pivot[0] - sourcePivotX * scale),
    scaled.map((item) => item.bounds),
    geometry,
  );
  const cells = scaled.map((item, index) => {
    const frame = run.manifest.frames[index];
    const normalized = placeCell(
      item.scaled,
      item.bounds,
      item.baseline,
      pasteX,
      `${direction}-${frame.phase}`,
      geometry,
      scale,
    );
    return {
      column: frame.phase,
      track: track.id,
      frameIndex: index,
      ...normalized,
      sourcePath: frame.path,
      sourceSha256: frame.sha256,
    };
  });
  return { track, run, dims, scale, cells };
}

async function compileTrackRow(direction, validated, geometry) {
  const split = keyChannelSplit(validated.chromaKey);
  const prepared = [];
  for (const track of Object.values(validated.tracks)) {
    if (!track.runs[direction]) continue;
    // eslint-disable-next-line no-await-in-loop -- preserve registry and cell order
    prepared.push(await prepareTrackCells(track, direction, validated, geometry, split));
  }
  const primary = prepared.find((item) => item.track.id === validated.primaryTrackId) || prepared[0];
  if (!primary) throw compileError(`No animation track occupies atlas row ${direction}`);

  const source = validated.anchors[direction] || validated.mainReference;
  const sourcePolicy = validated.anchors[direction]
    ? 'locked-directional-reference-anchor'
    : 'locked-main-reference';
  const idleLabel = `${direction}-idle`;
  const idleSource = await decodeTransparentSpriteSource(source.bytes, split, validated.chromaKey);
  const idleDims = occupiedDimensions(idleSource, SILHOUETTE_ALPHA_THRESHOLD, idleLabel);
  const desiredIdleHeight = median(primary.dims.map((dim) => dim.height)) * primary.scale;
  const idleScale = Math.min(desiredIdleHeight / idleDims.height, geometry.targetMaxWidth / idleDims.width);
  const idleScaled = await scaleForCell(idleSource, idleScale, idleLabel);
  const idlePasteX = validated.anchors[direction]
    ? pyRound(
      geometry.pivot[0]
      - rootX(
        idleScaled.scaled,
        alphaBbox(idleScaled.scaled, SILHOUETTE_ALPHA_THRESHOLD) || idleScaled.bounds,
        rootBandForManifest(primary.run.manifest),
      ),
    )
    : pyRound((geometry.cellSize - idleScaled.scaled.width) / 2);
  const idle = placeCell(
    idleScaled.scaled,
    idleScaled.bounds,
    idleScaled.baseline,
    sharedRowPasteX(idlePasteX, [idleScaled.bounds], geometry),
    idleLabel,
    geometry,
    idleScale,
  );
  const idleHeightTolerance = Math.max(
    IDLE_HEIGHT_TOLERANCE,
    IDLE_HEIGHT_TOLERANCE * (geometry.cellSize / DEFAULT_ATLAS_GEOMETRY.cellSize),
  );
  if (validated.anchors[direction]
    && Math.abs(idle.meta.occupiedBounds.height - desiredIdleHeight) > idleHeightTolerance) {
    throw compileError(
      `${direction} idle height ${idle.meta.occupiedBounds.height} misses the animation median ${pyRoundTo(desiredIdleHeight, 2)}`,
    );
  }
  const cells = [{
    column: ATLAS_IDLE_COLUMN,
    track: ATLAS_IDLE_COLUMN,
    frameIndex: 0,
    ...idle,
    sourcePath: source.path,
    sourceSha256: source.sha256,
    policy: sourcePolicy,
  }, ...prepared.flatMap((item) => item.cells)];
  const trackScales = Object.fromEntries(
    prepared.map((item) => [item.track.id, pyRoundTo(item.scale, 8)]),
  );
  return {
    direction,
    runId: primary.run.runId,
    runManifestPath: primary.run.manifestPath,
    walkDirectionScale: trackScales[WALK_TRACK],
    trackScales,
    idleScale: pyRoundTo(idleScale, 8),
    idlePolicy: sourcePolicy,
    cells,
  };
}

async function nextAtlasVersion(runtimeAbs, stem) {
  let entries = [];
  try {
    entries = await readdir(runtimeAbs, { withFileTypes: true });
  } catch {
    return 1;
  }
  const pattern = /^v(\d+)$/;
  let max = 0;
  for (const entry of entries) {
    const match = entry.isDirectory() && entry.name.match(pattern);
    if (!match) continue;
    const version = Number(match[1]);
    if (version > max && await pathExists(join(runtimeAbs, entry.name, `${stem}-v${version}.png`))) {
      max = version;
    }
  }
  return max + 1;
}

/** Refuse to overwrite an immutable artifact with differing bytes. */
async function writeImmutable(absPath, buffer) {
  const existing = await tryReadFile(absPath, null);
  if (existing !== null) {
    if (!existing.equals(buffer)) {
      throw new ServerError(`Immutable runtime output differs: ${absPath}`, { status: 409, code: 'IMMUTABLE_CONFLICT' });
    }
    return;
  }
  await atomicWrite(absPath, buffer);
}

function mergeGeometry(override = {}) {
  const geometry = { ...DEFAULT_ATLAS_GEOMETRY, ...override };
  if (geometry.targetMaxWidth >= geometry.cellSize || geometry.targetMaxHeight >= geometry.cellSize) {
    throw new ServerError('Atlas geometry target bounds must fit inside the cell', { status: 400, code: 'INVALID_GEOMETRY' });
  }
  return geometry;
}

/**
 * Compile (idempotently) the runtime atlas for a finalized walk set. Returns
 * `{ created, version, atlasPath, atlasSha256, manifestPath, geometry }` —
 * `created: false` when the current pointer already covers identical bytes.
 * Runs inside the record's walk write tail; callers already inside the tail
 * use compileAtlasInTail.
 */
export function compileAtlas(recordId, options = {}) {
  return withWalkWriteTail(recordId, () => compileAtlasInTail(recordId, options));
}

const trackSetSha256s = (validated) => Object.fromEntries(
  Object.values(validated.tracks).map((track) => [track.id, track.setSha256]),
);

const persistedTrackSetSha256s = (persisted) => {
  if (persisted?.trackSetSha256s && typeof persisted.trackSetSha256s === 'object'
    && !Array.isArray(persisted.trackSetSha256s)) {
    return persisted.trackSetSha256s;
  }
  return {
    ...(persisted?.walkSetSha256 ? { [WALK_TRACK]: persisted.walkSetSha256 } : {}),
    ...(persisted?.scannerSetSha256 ? { [SCANNER_TRACK]: persisted.scannerSetSha256 } : {}),
    ...(persisted?.ambientSetSha256 ? { [AMBIENT_TRACK]: persisted.ambientSetSha256 } : {}),
  };
};

const trackSetsUpToDate = (persisted, validated) => {
  const current = persistedTrackSetSha256s(persisted);
  const expected = trackSetSha256s(validated);
  const ids = new Set([...Object.keys(current), ...Object.keys(expected)]);
  return [...ids].every((id) => current[id] === expected[id]);
};

const trackFrameCountFields = (validated, animationTracks) => Object.fromEntries(
  Object.values(animationTracks).flatMap((definition) => {
    const frameCount = validated.tracks[definition.id]?.frameCount;
    return Number.isInteger(frameCount) ? [[definition.contractFrameCountField, frameCount]] : [];
  }),
);

const trackFrameCountsUpToDate = (geometry, fields) => Object.entries(fields)
  .every(([field, frameCount]) => geometry?.[field] === frameCount);

export async function compileAtlasInTail(recordId, {
  geometry: geometryOverride,
  tracks: animationTracks = getEffectiveAnimationTracks(),
} = {}) {
  // The track-presence gate (#3017), not a literal kind check: a record may
  // compile an atlas when its kind carries at least one registered animation
  // track. Walk is character-only, so this refuses exactly what it always did —
  // but registering a non-directional ambient track that lists `place`/`object`
  // unlocks those records here with no edit to this line.
  await requireAnimatable(recordId);
  const geometry = mergeGeometry(geometryOverride);
  const validated = await validateForCompile(recordId, animationTracks);
  const frameCountFields = trackFrameCountFields(validated, animationTracks);
  const dir = spriteDir(recordId);

  // Columns/width follow the set's actual per-track frame counts, not the
  // historical 8 — and `tracks` names each track's `{ start, count }` span, so
  // the grid, the manifest geometry and the published sidecar can never
  // disagree about where a track's columns are.
  const trackSpecs = Object.values(validated.tracks).map((track) => ({
    id: track.id,
    frameCount: track.frameCount,
  }));
  const { columns, tracks } = buildAtlasGrid(trackSpecs, animationTracks);

  // Pre-pixel idempotency: the compile is deterministic, so unchanged track
  // sets + identical geometry mean identical bytes by construction —
  // skip the whole pixel pipeline. The evidence chain was still revalidated
  // above; the post-encode sha comparison below stays as the fallback for a
  // pointer whose geometry fields predate a shape change.
  // `compiledGridUpToDate` compares the GRID, not just the cell metrics: a
  // grid-shape change (#2986 dropping the trailing scanner column) leaves every
  // cell metric identical, and a track-SET change can leave even the column
  // count identical, so both the column list and the track spans are part of
  // the comparison (#3016). A pointer predating either field is described the
  // legacy way rather than treated as a mismatch, so upgrading an install
  // doesn't condemn every existing atlas to recompile its pixels forever.
  // Both idempotent early-returns require the pointed-at atlas file to still
  // exist — otherwise a deleted runtime/vN PNG would loop forever ("recompile"
  // → pointer returned untouched → still missing); falling through re-writes
  // the same version (nextAtlasVersion only counts versions whose PNG exists).
  const current = await readJSONFile(join(dir, RUNTIME_POINTER_REL), null, { strict: true });
  const currentAtlasOnDisk = current ? await pathExists(join(dir, current.atlasPath)) : false;
  if (
    current
    && currentAtlasOnDisk
    && trackSetsUpToDate(current, validated)
    && compiledGridUpToDate(current.geometry, { ...geometry, columns, tracks })
    && trackFrameCountsUpToDate(current.geometry, frameCountFields)
  ) {
    return { ...current, created: false };
  }

  // Each row emits its idle reference plus every registered track occupying
  // that facing. Cells carry their track and frame index into the compositor,
  // so variable-width and single-row spans land exactly where the grid says.
  const rowCount = Math.max(...Object.values(validated.tracks).map((track) => track.directions.length));
  const rows = await Promise.all(
    SPRITE_DIRECTIONS.slice(0, rowCount).map((direction) => compileTrackRow(direction, validated, geometry)),
  );

  // Resolve one cell's place in the grid from its track's span, once, and stamp
  // the answer on the cell so the manifest below reports where the pixels
  // actually went instead of re-deriving it. Deriving the index positionally
  // (its order within the row) was correct only while every track was
  // full-width and full-height; it would silently misplace a shorter or
  // single-row track rather than reporting the mismatch.
  const placeInGrid = (cell, r) => {
    const span = tracks[cell.track];
    if (!span) throw compileError(`Compiled cell references unknown atlas track '${cell.track}'`);
    // A non-directional track owns row 0 only; the rest of its span stays as
    // the zero-filled canvas left it — transparent, which PNG compresses to
    // near nothing. A cell compiled outside its track's rows would overwrite
    // pixels the sidecar promises are empty, so refuse rather than composite.
    if (r >= span.rows) {
      throw compileError(`Track '${cell.track}' occupies ${span.rows} atlas row(s) but a cell was compiled for ${SPRITE_DIRECTIONS[r]} (row ${r})`);
    }
    if (!Number.isInteger(cell.frameIndex) || cell.frameIndex < 0 || cell.frameIndex >= span.count) {
      throw compileError(`Track '${cell.track}' frame ${cell.frameIndex} is outside its ${span.count}-column span`);
    }
    const index = span.start + cell.frameIndex;
    if (columns[index] !== cell.column) {
      throw compileError(`Track '${cell.track}' frame ${cell.frameIndex} is column "${columns[index]}" in the grid but the cell is labeled "${cell.column}"`);
    }
    cell.columnIndex = index;
    return index;
  };

  const { cellSize } = geometry;
  const atlasWidth = cellSize * columns.length;
  const atlasHeight = cellSize * SPRITE_DIRECTIONS.length;
  const atlas = { data: Buffer.alloc(atlasWidth * atlasHeight * 4), width: atlasWidth, height: atlasHeight };
  for (let r = 0; r < rows.length; r++) {
    for (const cell of rows[r].cells) {
      compositeOnto(atlas, cell.cell, placeInGrid(cell, r) * cellSize, r * cellSize);
    }
  }
  const atlasBuffer = await sharp(atlas.data, { raw: { width: atlasWidth, height: atlasHeight, channels: 4 } })
    .png()
    .toBuffer();
  const atlasSha256 = sha256Buffer(atlasBuffer);

  if (current && currentAtlasOnDisk && trackSetsUpToDate(current, validated)
    && current.atlasSha256 === atlasSha256
    && trackFrameCountsUpToDate(current.geometry, frameCountFields)) {
    return { ...current, created: false };
  }

  const stem = atlasStem(recordId);
  const runtimeAbs = join(dir, RUNTIME_DIR);
  let version = await nextAtlasVersion(runtimeAbs, stem);
  // Never adopt a PNG-missing slot whose surviving manifest vouches for
  // DIFFERENT bytes — writing there would land a PNG its own manifest
  // contradicts and then 409 on the manifest write, poisoning the version
  // dir. Advance until the slot is empty or its manifest matches these bytes
  // (the re-materialize case).
  for (;;) {
    const survivor = await readJSONFile(join(runtimeAbs, `v${version}`, `${stem}-v${version}-manifest.json`), null, { strict: true });
    if (!survivor || (
      survivor.atlasSha256 === atlasSha256
      && trackFrameCountsUpToDate(survivor.geometry, frameCountFields)
    )) break;
    version += 1;
  }
  const versionRel = `${RUNTIME_DIR}/v${version}`;
  const atlasRel = `${versionRel}/${stem}-v${version}.png`;
  const manifestRel = `${versionRel}/${stem}-v${version}-manifest.json`;
  await ensureDir(join(dir, versionRel));
  await writeImmutable(join(dir, atlasRel), atlasBuffer);

  // Self-heal: when re-writing a version whose PNG was deleted, the version's
  // manifest usually survives — reuse it verbatim when it vouches for these
  // exact atlas bytes, since a freshly-built one would differ only in
  // createdAt and trip the immutable-write refusal.
  const manifestAbs = join(dir, manifestRel);
  const survivingManifest = await readJSONFile(manifestAbs, null, { strict: true });
  if (
    survivingManifest?.atlasSha256 === atlasSha256
    && trackFrameCountsUpToDate(survivingManifest.geometry, frameCountFields)
  ) {
    const survivingBuffer = await readFile(manifestAbs);
    const pointer = {
      schemaVersion: 1,
      kind: 'runtime-atlas-selection',
      characterId: recordId,
      version,
      atlasPath: atlasRel,
      atlasSha256,
      manifestPath: manifestRel,
      manifestSha256: sha256Buffer(survivingBuffer),
      ...(validated.walkSet ? { walkSetSha256: validated.walkSetSha256 } : {}),
      ...(survivingManifest.scannerSetSha256 ? { scannerSetSha256: survivingManifest.scannerSetSha256 } : {}),
      ...(survivingManifest.ambientSetSha256 ? { ambientSetSha256: survivingManifest.ambientSetSha256 } : {}),
      trackSetSha256s: persistedTrackSetSha256s(survivingManifest),
      geometry: survivingManifest.geometry,
      compiledAt: survivingManifest.createdAt,
    };
    await atomicWrite(join(dir, RUNTIME_POINTER_REL), pointer);
    console.log(`🧩 sprite atlas re-materialized for ${recordId} → v${version}`);
    return { ...pointer, created: true };
  }

  const manifest = {
    schemaVersion: 1,
    // The two named `kind`s are HISTORICAL spellings, kept so a recompile of a
    // record that was compiled before #3158 writes the same discriminator it always
    // did. They are matched on `primaryTrackId` rather than derived from it, which
    // means a user who deletes the seeded `ambient` row and authors their own
    // place-baseline track (#3152) gets the generic third spelling — correct for a
    // genuinely new track, and the same reason the two legacy names can't simply be
    // computed from the id: nothing else on disk records which name a record's
    // earlier atlases used.
    kind: validated.primaryTrackId === AMBIENT_TRACK
      ? 'reviewed-ambient-set-runtime-atlas'
      : validated.primaryTrackId === WALK_TRACK
        ? 'reviewed-walk-set-runtime-atlas'
        : 'reviewed-animation-set-runtime-atlas',
    characterId: recordId,
    version,
    createdAt: new Date().toISOString(),
    chromaKey: validated.chromaKey,
    compilerPath: 'server/services/sprites/atlas.js',
    ...(validated.walkSet ? {
      walkSetPath: validated.walkSetPath,
      walkSetSha256: validated.walkSetSha256,
    } : {}),
    ...(validated.scannerSet ? {
      scannerSetPath: validated.scannerSetPath,
      scannerSetSha256: validated.scannerSetSha256,
    } : {}),
    ...(validated.ambientSet ? {
      ambientSetPath: validated.ambientSetPath,
      ambientSetSha256: validated.ambientSetSha256,
    } : {}),
    trackSets: Object.fromEntries(
      Object.values(validated.tracks).map((track) => [
        track.id,
        { setPath: track.setPath, setSha256: track.setSha256 },
      ]),
    ),
    trackSetSha256s: trackSetSha256s(validated),
    atlasPath: atlasRel,
    atlasSha256,
    geometry: {
      columns,
      // Each track's `{ start, count }` column span (#3016). Additive: readers
      // that predate it (and every atlas compiled before it) fall back to the
      // legacy column-name derivation in atlasGrid.deriveTracks, so no migration
      // is needed and imported/pre-#2986 grids keep describing themselves.
      tracks,
      directionOrder: SPRITE_DIRECTIONS,
      rows: SPRITE_DIRECTIONS.length,
      cellSize,
      pivot: geometry.pivot,
      targetMaxHeight: geometry.targetMaxHeight,
      targetMaxWidth: geometry.targetMaxWidth,
      widthPx: atlasWidth,
      heightPx: atlasHeight,
      // Runtime playback metadata: the external game reads these to animate the
      // walk row at the authored speed over the right number of columns.
      walkFrameCount: validated.walkFrameCount,
      walkFps: validated.walkFps,
      // Match every compiled track to the convenience field its registry row
      // declares. The duplicate walk assignment preserves the existing field
      // position, while seeded scanner/ambient rows keep their wire names.
      ...frameCountFields,
    },
    directions: rows.map((row) => ({
      direction: row.direction,
      runId: row.runId,
      runManifestPath: row.runManifestPath,
      walkDirectionScale: row.walkDirectionScale,
      trackScales: row.trackScales,
      idleScale: row.idleScale,
      idlePolicy: row.idlePolicy,
      // The index the compositor stamped on, so the manifest cannot claim a
      // cell sits somewhere other than where its pixels actually landed.
      cells: row.cells.map((cell) => ({
        column: cell.column,
        columnIndex: cell.columnIndex,
        translation: cell.meta.translation,
        scale: cell.meta.scale,
        occupiedBounds: cell.meta.occupiedBounds,
        sourcePath: cell.sourcePath,
        sourceSha256: cell.sourceSha256,
        ...(cell.policy ? { policy: cell.policy } : {}),
      })),
    })),
  };
  const manifestBuffer = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
  await writeImmutable(manifestAbs, manifestBuffer);

  const pointer = {
    schemaVersion: 1,
    kind: 'runtime-atlas-selection',
    characterId: recordId,
    version,
    atlasPath: atlasRel,
    atlasSha256,
    manifestPath: manifestRel,
    manifestSha256: sha256Buffer(manifestBuffer),
    ...(validated.walkSet ? { walkSetSha256: validated.walkSetSha256 } : {}),
    ...(validated.scannerSet ? { scannerSetSha256: validated.scannerSetSha256 } : {}),
    ...(validated.ambientSet ? { ambientSetSha256: validated.ambientSetSha256 } : {}),
    trackSetSha256s: trackSetSha256s(validated),
    geometry: manifest.geometry,
    compiledAt: manifest.createdAt,
  };
  await atomicWrite(join(dir, RUNTIME_POINTER_REL), pointer);
  console.log(`🧩 sprite atlas compiled for ${recordId} → v${version}`);
  return { ...pointer, created: true };
}

/** Atlas view for the detail endpoint: current pointer + publish history. */
export async function getAtlasState(recordId) {
  const dir = spriteDir(recordId);
  const [current, publications] = await Promise.all([
    readJSONFile(join(dir, RUNTIME_POINTER_REL), null, { strict: true }),
    readJSONFile(join(dir, RUNTIME_PUBLICATIONS_REL), [], { strict: true }),
  ]);
  return { current, publications: [...publications].reverse() };
}