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
import { emitSpriteChanged } from './events.js';
/**
* The generic per-track animation workflow (#3136).
*
* `scanner.js` and `ambient.js` were two ~300-line copies of one control flow:
* load the track's review selection / finalized set / runs → require a locked
* source reference → prepare a chroma matte → start ONE user-requested Grok
* image-to-video render → package it deterministically → review → approve →
* freeze the set. Nothing about that sequence is scanner-shaped or ambient
* shaped; they differed only in facts the track registry now carries:
*
* - `directional` how many facings the track is authored across (and so
* how many must be approved before the set freezes) AND —
* derived from it via `sourceReferenceFor` — which locked
* image seeds the render: this facing's own anchor, or the
* one main reference. Derived rather than declared because
* only one pairing can work; a row that claimed the other
* would render one facing's clip for every row.
* - `selectionKind` / `setKind` / `finalErrorCode`
* the on-disk discriminators and the 409 code
*
* plus one prompt builder. So this module is that flow ONCE, parameterized by
* track id, and a new animation type is a registry row + a prompt — not a fourth
* copy of this file. Walk deliberately stays on its own service (`walk.js`): it
* carries reprocess, loop trims, per-direction reopen, source-frame extraction
* and set-level targets that no other track has, and folding those in would make
* this module the union of every track's features rather than their intersection.
*
* **On-disk compatibility is exact, not approximate.** Every path, `kind`
* string, run field, error code and message this writes is byte-identical to
* what the two clones wrote, because installs already hold approved scanner sets
* and ambient loops whose evidence chain the atlas compiler re-verifies by those
* exact strings. The clone collapse is a code change only.
*
* The render is reachable only through `startTrackGeneration` — a direct user
* action per the AI-provider policy. Everything after Grok writes the MP4 is
* deterministic local packing, review, approval, and atlas input; no boot path
* or read endpoint calls a provider.
*/
import { join } from 'path';
import { readdir } from 'fs/promises';
import { randomUUID } from 'crypto';
import { atomicWrite, ensureDir, pathExists, readJSONFile, sha256File, rmGuarded } from '../../lib/fileUtils.js';
import { ServerError } from '../../lib/errorHandler.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { executeTuiRun } from '../tuiPromptRunner.js';
import { GROK_TUI_ID } from '../../lib/grok.js';
import { resolveGrokDuration } from '../../lib/grokVideoClip.js';
import {
planLocalAnimationRender, enqueueLocalAnimationRender, localRenderManifest,
normalizeStaleAnimationRun,
} from './localAnimationRender.js';
import { getSettings } from '../settings.js';
import { getRecord, listRecords } from './records.js';
import { requireTrack, loadManifest } from './reference.js';
import { anchorIdForDirection } from './prompts.js';
import { buildTrackVideoPrompt } from './trackPrompts.js';
import { clampTrackFrameCount, clampTrackFps, sourceReferenceFor } from './animationTracks.js';
// #3152 — this workflow drives ANY row, so every registry lookup resolves against
// the effective table (compiled `walk` + the user-defined store); a user's own
// track reaches generate/approve through exactly this path with no new code.
import { effectiveTrack, getEffectiveAnimationTracks } from './animationTrackStore.js';
import { trackDirections } from './atlasGrid.js';
import {
spriteDir, resolveSpriteAssetPath, SOURCE_CLIP_NAME, runRelPath, RUN_RECORD_NAME,
} from './paths.js';
import { prepareWalkAnchorChromaInput, runWalkPostprocess } from './walkPostprocess.js';
import { verifyPackagedFrames } from './walkFrames.js';
import {
resolveChromaKey, withAnimationWriteTail, lockedAnchorFor, lockedMainFor,
GROK_TUI_IDLE_MS, GROK_TUI_TIMEOUT_MS, grokTuiProvider, buildGrokI2vTask,
resolveAnimationProvider, isLocalProviderRun, runCreatedAtMs,
} from './animationWorkflow.js';
/**
* The facings a track is authored across: every direction for a directional
* track, the single row 0 for a non-directional one.
*
* `trackDirections` (atlasGrid) is the ONE definition of that slice, shared with
* the compiler — which matters because the count decides both when a set freezes
* (and what `directionOrder` it writes) and how many rows the compiler will
* accept. Two derivations of one registry field is exactly the drift
* `trackDirections`'s own header says it exists to prevent.
*/
export const trackAuthoringDirections = (trackId) => trackDirections(trackId);
// The on-disk layout, per track. `<track>/` subdirectory and `-<track>-` infix,
// which is exactly what scanner.js and ambient.js each spelled for themselves.
const selectionRelPath = (trackId, id) => `${trackId}/${id}-${trackId}-selection-v1.json`;
export const trackSetRelPath = (trackId, id) => `${trackId}/${id}-${trackId}-set-v1.json`;
const setFinalError = (row) => new ServerError(
row.directional
? `${row.label} set is finalized — reopen it before generating or approving another ${row.label.toLowerCase()}`
: `${row.label} is finalized and immutable`,
{ status: 409, code: row.finalErrorCode },
);
const loadSelection = (trackId, recordId) =>
readJSONFile(join(spriteDir(recordId), selectionRelPath(trackId, recordId)), null);
const loadSet = (trackId, recordId) =>
readJSONFile(join(spriteDir(recordId), trackSetRelPath(trackId, recordId)), null);
const loadRun = (recordId, runId) =>
readJSONFile(join(spriteDir(recordId), runRelPath(runId), RUN_RECORD_NAME), null);
const seedSelection = (row, recordId) => ({
schemaVersion: 1,
kind: row.selectionKind,
track: row.id,
characterId: recordId,
status: 'in-progress',
directions: {},
});
async function saveRun(recordId, run) {
const dir = join(spriteDir(recordId), runRelPath(run.id));
await ensureDir(dir);
await atomicWrite(join(dir, RUN_RECORD_NAME), run);
emitSpriteChanged(recordId);
}
/**
* Every run on disk belonging to `trackId`, newest first.
*
* Stranded `rendering` runs are normalized to `error` at READ time — never
* persisted — by the same rule the walk lane uses. Without it a run whose render
* could no longer be resolved (its server died and the completion hook could not
* reach it) sits at `rendering` forever, and the in-flight guard below then
* refuses every regenerate for that facing with TRACK_RENDER_IN_PROGRESS — with
* no per-run delete and `reopenTrackDirection` only touching APPROVED runs, that
* is unrecoverable short of hand-editing the record. The walk lane always had
* this backstop; the track lane never did, and the local lane's multi-hour
* renders made the gap materially more reachable.
*/
async function trackRuns(trackId, recordId) {
const runsDir = join(spriteDir(recordId), 'runs');
const entries = await readdir(runsDir, { withFileTypes: true }).catch(() => []);
const runs = await Promise.all(entries.filter((entry) => entry.isDirectory()).map((entry) => (
readJSONFile(join(runsDir, entry.name, RUN_RECORD_NAME), null)
)));
return runs.filter((run) => run?.track === trackId)
.map((run) => normalizeStaleAnimationRun(run, staleRenderError(trackId)))
.sort((a, b) => runCreatedAtMs(b.createdAt) - runCreatedAtMs(a.createdAt));
}
/** The read-time message a stranded run carries, named for the track it is on. */
const staleRenderError = (trackId) => (
`The ${effectiveTrack(trackId).label.toLowerCase()} render was interrupted `
+ '(server restart or timeout) — regenerate to retry.'
);
/**
* The track's authoring state: `{ track, definition, selection, set, runs }`.
*
* `definition` is the registry row, shipped so the client renders the track's
* label, facing count, and bounds from data instead of mirroring them as
* component copy — that is what lets one component serve a track it has never
* heard of. `set` is the finalized-set key for every track; the old per-track
* spellings (`scannerSet`/`ambientSet`) went away with the clones.
*/
export async function getTrackState(trackId, recordId) {
const row = effectiveTrack(trackId);
const [selection, set, runs] = await Promise.all([
loadSelection(row.id, recordId), loadSet(row.id, recordId), trackRuns(row.id, recordId),
]);
return { track: row.id, definition: row, selection, set, runs };
}
/**
* Every record id carrying approved work for `trackId`, in library order (#3153).
*
* The evidence a delete or a directionality flip would orphan, as ONE question:
* either the finalized set (the frozen `setKind` artifact the atlas compiler
* re-verifies) or a review selection with at least one approved direction. Both
* are renders the user approved and both are keyed by the discriminator strings
* the mutation would remove from the registry — a set alone would miss a
* half-approved directional track, where seven approvals exist but the eighth
* hasn't frozen the set yet.
*
* Lives here rather than in the CRUD service because the on-disk layout
* (`<track>/<id>-<track>-{selection,set}-v1.json`) is this module's contract; a
* second reader spelling those filenames is exactly the drift the generic
* workflow collapsed.
*
* Deliberately tolerant of a record whose directory is unreadable: `loadSelection`
* and `loadSet` answer `null` for anything absent, so a record with no assets
* simply doesn't carry the track. It never invents a false positive that would
* block a legitimate delete.
*/
export async function recordsCarryingTrack(trackId) {
const records = await listRecords();
const carried = await Promise.all(records.map(async (record) => {
const [selection, set] = await Promise.all([
loadSelection(trackId, record.id), loadSet(trackId, record.id),
]);
const approved = Object.values(selection?.directions || {})
.some((entry) => entry?.status === 'approved');
return set || approved ? record.id : null;
}));
return carried.filter(Boolean);
}
/**
* Everything about the locked reference this track's render is seeded from — both
* when it exists and when it doesn't.
*
* ONE resolver so no caller ever branches on the source shape again. It returns
* the artifact's `label`, the error `code`s to use when it isn't locked or has
* vanished from disk, and — when it IS locked — its `path`/`sha256`/`inputName`.
* Returning the label and codes unconditionally is the point: the "lock it first"
* 409 and the "missing on disk" 500 both need to name the artifact the row asked
* for, and re-deriving that name at each throw site is how three of them ended up
* spelling the anchor's name three different ways.
*
* `locked` is the sentinel: absent means nothing is frozen yet, which is a
* different answer from "frozen but gone", handled by the caller's disk check.
*/
function trackSourceFor(row, manifest, direction) {
if (sourceReferenceFor(row.id, getEffectiveAnimationTracks()) === 'main') {
const main = lockedMainFor(manifest);
return {
label: 'main reference',
notLockedCode: 'MAIN_NOT_LOCKED',
missingCode: 'MAIN_REFERENCE_MISSING',
inputName: 'input-main-chroma.png',
locked: main ? { path: main.path, sha256: main.sha256 || null } : null,
};
}
const anchor = lockedAnchorFor(manifest, direction);
return {
label: `${anchorIdForDirection(direction)} anchor`,
notLockedCode: 'ANCHOR_NOT_LOCKED',
missingCode: 'ANCHOR_MISSING',
inputName: 'input-anchor-chroma.png',
locked: anchor ? { path: anchor.path, sha256: anchor.sha256 || null } : null,
};
}
/**
* The facing a request is for, resolved against the track's OWN facing list.
*
* A non-directional track occupies exactly its single row, so its facing is
* derived from the registry rather than accepted from the request — no
* user-supplied direction can drift from what the compiler will later expect.
*
* A directional track's facing must be one the TRACK has, not merely one the
* sprite grid has: the route's Zod enum accepts all eight facings, but
* `trackAuthoringDirections` is a per-track slice, so a future track with fewer
* facings would otherwise accept a render for a row it doesn't occupy — which
* would author a set the compiler refuses, after the render was already paid for.
*/
function resolveTrackDirection(row, requested) {
const authored = trackAuthoringDirections(row.id);
if (!row.directional) return authored[0];
if (!authored.includes(requested)) {
throw new ServerError(
`The ${row.id} track has no '${String(requested)}' facing — it is authored across: ${authored.join(', ')}`,
{ status: 400, code: 'TRACK_DIRECTION_INVALID' },
);
}
return requested;
}
/** The 409 for a render/approval whose source reference isn't frozen yet. */
const notLockedError = (source, row, verb) => new ServerError(
`Lock the ${source.label} before ${verb} its ${row.label.toLowerCase()}`,
{ status: 409, code: source.notLockedCode },
);
export function startTrackGeneration(trackId, recordId, body) {
return withAnimationWriteTail(recordId, () => startTrackGenerationImpl(trackId, recordId, body));
}
async function startTrackGenerationImpl(trackId, recordId, body) {
const row = effectiveTrack(trackId);
const [record, reference, existingSet, existingRuns] = await Promise.all([
requireTrack(recordId, row.id), loadManifest(recordId), loadSet(row.id, recordId), trackRuns(row.id, recordId),
]);
if (existingSet) throw setFinalError(row);
const direction = resolveTrackDirection(row, body.direction);
const source = trackSourceFor(row, reference, direction);
if (!source.locked) throw notLockedError(source, row, 'generating');
const chromaKey = resolveChromaKey({ manifest: reference, record });
if (!chromaKey) throw new ServerError('No frozen chroma key is available for this sprite', { status: 409, code: 'CHROMA_KEY_REQUIRED' });
// In-flight guard, per facing for a directional track and per record for a
// single-row one (where "another facing" doesn't exist).
const inFlight = existingRuns.some((run) => (
['rendering', 'postprocessing'].includes(run.status) && (!row.directional || run.direction === direction)
));
if (inFlight) {
throw new ServerError(
row.directional
? `A ${row.label.toLowerCase()} render for ${direction} is already in progress`
: `A ${row.label.toLowerCase()} render is already in progress`,
{ status: 409, code: 'TRACK_RENDER_IN_PROGRESS' },
);
}
const effectiveTracks = getEffectiveAnimationTracks();
const frameCount = clampTrackFrameCount(body.frameCount, row.id, effectiveTracks);
const fps = clampTrackFps(body.fps, row.id, effectiveTracks);
// Optional re-roll note (#3134) — blank leaves the prompt and the run record
// exactly as a blind regenerate would.
const correctionPrompt = typeof body.correctionPrompt === 'string' ? body.correctionPrompt.trim() : '';
// WHICH lane renders the clip (#4876) — same contract the walk lane uses, so a
// track never needs its own provider rules. Absent → grok.
const provider = resolveAnimationProvider(body.provider);
const duration = resolveGrokDuration(body.duration);
// Readiness first: an install with no runnable local model 409s here, before a
// run record exists.
const localPlan = provider === 'local'
? await planLocalAnimationRender({ durationSeconds: duration })
: null;
// Run ids stay in the clones' shapes: `<track>-<direction>-<uuid8>` for a
// directional track, `<track>-<uuid8>` for a single-row one.
const runId = row.directional
? `${row.id}-${direction}-${randomUUID().slice(0, 8)}`
: `${row.id}-${randomUUID().slice(0, 8)}`;
const runRel = runRelPath(runId);
const generatedAbs = join(spriteDir(recordId), runRel, 'generated');
await ensureDir(generatedAbs);
const sourceAbs = resolveSpriteAssetPath(recordId, source.locked.path);
if (!await pathExists(sourceAbs)) {
throw new ServerError(
`Locked ${source.label} file is missing on disk`,
{ status: 500, code: source.missingCode },
);
}
const inputAbs = join(generatedAbs, source.inputName);
const [{ preparation, sha256: inputSha256, canvas }, settings] = await Promise.all([
prepareWalkAnchorChromaInput(sourceAbs, inputAbs, chromaKey, localPlan?.chooseCanvas || null),
getSettings(),
]);
const videoAbs = join(generatedAbs, SOURCE_CLIP_NAME);
const prompt = buildTrackVideoPrompt(row.id, {
name: record.name, kind: record.kind, direction, chromaKey, correctionPrompt,
});
const run = {
schemaVersion: 1,
kind: 'grok-game-animation-frames-run',
track: row.id,
provider: GROK_TUI_ID,
status: 'rendering',
id: runId,
shellSession: runId,
characterId: recordId,
direction,
chromaKey,
duration,
frameCount,
fps,
// `anchorPath`/`anchorSha256` name the SOURCE reference whatever it was —
// the ambient clone already used these keys for the main reference, and the
// approve gate's staleness check reads them, so the spelling stays.
anchorPath: source.locked.path,
anchorSha256: source.locked.sha256 || await sha256File(sourceAbs),
animationInputPath: `${runRel}/generated/${source.inputName}`,
animationInputSha256: inputSha256,
animationInputPreparation: preparation,
...(correctionPrompt ? { correctionPrompt } : {}),
createdAt: new Date().toISOString(),
// Spread LAST so the local lane's provider/geometry provenance wins over the
// grok defaults above. A local render is a queued media job, not a PTY, so it
// carries `jobId` in place of an attachable `shellSession`.
...(localPlan ? { ...localRenderManifest(localPlan, canvas), shellSession: null } : {}),
};
await saveRun(recordId, run);
if (localPlan) {
// Queued after the record is durable, and never awaited here — the
// boot-registered completion hook stages the clip and runs the attach. See
// the walk lane's note: that is what survives a restart, which matters most
// on this lane because track runs have no wall-clock backstop at all.
// A refused admission (#8325) would otherwise leave the run at
// `rendering` with no job to finish it — and this lane's in-flight guard
// would then refuse every retry — so settle it as an error first.
const jobId = await enqueueLocalAnimationRender({
plan: localPlan, canvas, prompt, inputAbs, recordId, runId, track: row.id, direction,
}).catch(async (err) => {
Object.assign(run, { status: 'error', postprocessError: err.message, completedAt: new Date().toISOString() });
await saveRun(recordId, run);
throw err;
});
run.jobId = jobId;
await saveRun(recordId, run);
console.log(`📡 sprite ${row.id} local render started ${recordId}/${runId} (job ${jobId.slice(0, 8)}, ${localPlan.numFrames}f @ ${localPlan.fps}fps)`);
return row.directional
? { runId, direction, duration, provider: 'local', jobId }
: { runId, duration, provider: 'local', jobId };
}
runTrackTuiRender(row, recordId, {
runId,
direction,
generatedAbs,
videoAbs,
grokPath: settings.imageGen?.grok?.grokPath,
task: buildGrokI2vTask({ prompt, inputAbs, videoAbs, duration }),
}).catch((err) => console.error(`❌ sprite ${row.id} grok-tui render crashed ${recordId}/${runId}: ${err?.message || err}`));
console.log(`📡 sprite ${row.id} grok-tui render started ${recordId}/${runId}`);
return row.directional
? { runId, direction, duration, provider: 'grok', shellSession: runId }
: { runId, duration, provider: 'grok', shellSession: runId };
}
async function runTrackTuiRender(row, recordId, { runId, direction, generatedAbs, videoAbs, grokPath, task }) {
await executeTuiRun({
runId,
provider: grokTuiProvider(grokPath),
prompt: task,
workspacePath: generatedAbs,
idleMs: GROK_TUI_IDLE_MS,
timeout: GROK_TUI_TIMEOUT_MS,
label: row.directional ? `sprite ${row.id} ${recordId}/${direction}` : `sprite ${row.id} ${recordId}`,
}).catch((err) => console.error(`❌ sprite ${row.id} grok-tui run failed ${recordId}/${runId}: ${err?.message || err}`));
// Lease before the tail, as in the completion hook (#9982): the clip, its decoded
// frames and the run record naming them are one publication.
await withBackupAssetPublication(() => withAnimationWriteTail(
recordId, () => attachTrackTuiResult(row.id, recordId, runId, videoAbs),
));
}
export async function attachTrackTuiResult(trackId, recordId, runId, videoAbs) {
const row = effectiveTrack(trackId);
const run = await loadRun(recordId, runId);
if (!run || run.track !== row.id || await loadSet(row.id, recordId)) return;
const selection = await loadSelection(row.id, recordId);
if (selection?.directions?.[run.direction]?.runId === runId) return;
if (!await pathExists(videoAbs)) {
run.status = 'error';
run.postprocessError = isLocalProviderRun(run)
? `The local render produced no ${row.label.toLowerCase()} video — check the Render Queue for the failed job`
: `Grok finished without writing the ${row.label.toLowerCase()} video — check the shell session output`;
run.completedAt = new Date().toISOString();
await saveRun(recordId, run);
return;
}
run.status = 'postprocessing';
// Anchors the packaging staleness window (normalizeStaleAnimationRun). It MUST
// be measured from here rather than from `createdAt`: a local render can have
// been queued hours before packaging starts, so a createdAt-anchored window
// reports every healthy local run as interrupted the moment it begins to pack.
run.postprocessingStartedAt = new Date().toISOString();
run.sourceVideoPath = `${runRelPath(run.id)}/generated/${SOURCE_CLIP_NAME}`;
await saveRun(recordId, run);
await packageTrackRun(row, recordId, run);
await saveRun(recordId, run);
}
async function packageTrackRun(row, recordId, run) {
// Runs outside the request lifecycle (the TUI completion tail), so a throw
// here would take the process down rather than reaching error middleware —
// hence the try/catch, per the AGENTS.md boundary exception.
try {
const [reference, record] = await Promise.all([loadManifest(recordId), getRecord(recordId)]);
const source = trackSourceFor(row, reference, run.direction);
if (!source.locked) throw new Error(`No locked ${source.label} in the reference manifest`);
const chromaKey = resolveChromaKey({ manifest: reference, record, run });
if (!chromaKey) throw new Error(`No chroma key is available for the ${row.label.toLowerCase()} matte`);
const runRel = runRelPath(run.id);
const effectiveTracks = getEffectiveAnimationTracks();
const result = await runWalkPostprocess({
recordId,
track: row.id,
direction: run.direction,
chromaKey,
runAbs: join(spriteDir(recordId), runRel),
runRel,
anchorRel: source.locked.path,
anchorAbs: resolveSpriteAssetPath(recordId, source.locked.path),
videoAbs: resolveSpriteAssetPath(recordId, run.sourceVideoPath),
frameCount: clampTrackFrameCount(run.frameCount, row.id, effectiveTracks),
fps: clampTrackFps(run.fps, row.id, effectiveTracks),
});
run.frameCount = result.manifest.frameCount;
run.fps = result.manifest.frameRate;
run.status = 'candidate';
run.postprocessManifest = result.manifestPath;
run.stripPreview = result.stripPreview;
delete run.postprocessError;
} catch (err) {
run.status = 'error';
run.postprocessError = err.message;
console.error(`❌ sprite ${row.id} postprocess failed ${recordId}/${run.id}: ${err.message}`);
}
run.completedAt = new Date().toISOString();
}
export function approveTrackRun(trackId, recordId, args) {
return withAnimationWriteTail(recordId, () => approveTrackRunImpl(trackId, recordId, args));
}
async function approveTrackRunImpl(trackId, recordId, { direction: requested, runId }) {
const row = effectiveTrack(trackId);
await requireTrack(recordId, row.id);
if (await loadSet(row.id, recordId)) throw setFinalError(row);
const direction = resolveTrackDirection(row, requested);
const label = row.label.toLowerCase();
const run = await loadRun(recordId, runId);
if (!run || run.track !== row.id) throw new ServerError(`Unknown ${label} run: ${runId}`, { status: 404, code: 'RUN_NOT_FOUND' });
if (run.direction !== direction) throw new ServerError(`Run ${runId} animates '${run.direction}', not '${direction}'`, { status: 400, code: 'RUN_DIRECTION_MISMATCH' });
if (run.status !== 'candidate' || !run.postprocessManifest) throw new ServerError('Run has no packaged candidate to approve', { status: 409, code: 'RUN_NOT_CANDIDATE' });
const [reference, packaged] = await Promise.all([
loadManifest(recordId), readJSONFile(resolveSpriteAssetPath(recordId, run.postprocessManifest), null),
]);
const source = trackSourceFor(row, reference, direction);
if (!source.locked) throw notLockedError(source, row, 'approving');
if (run.anchorSha256) {
const currentSha256 = source.locked.sha256
|| await sha256File(resolveSpriteAssetPath(recordId, source.locked.path));
if (run.anchorSha256 !== currentSha256) {
throw new ServerError(
`This ${label} was rendered from an older ${source.label} — generate it again from the current reference`,
{ status: 409, code: 'RUN_ANCHOR_STALE' },
);
}
}
if (!packaged || packaged.track !== row.id || packaged.direction !== direction || packaged.characterId !== recordId
|| packaged.frameCount !== run.frameCount || packaged.frameRate !== run.fps) {
throw new ServerError(`Packaged ${label} manifest is missing or inconsistent`, { status: 409, code: 'RUN_MANIFEST_INVALID' });
}
const frameCheck = await verifyPackagedFrames(recordId, packaged, { track: row.id });
if (frameCheck.missing) throw new ServerError(
`${frameCheck.missing} of this ${label} run's ${frameCheck.total} packaged frames are missing on disk`,
{ status: 409, code: 'RUN_FRAMES_MISSING' },
);
const selection = (await loadSelection(row.id, recordId)) || seedSelection(row, recordId);
selection.directions[direction] = {
status: 'approved',
runId,
runPath: runRelPath(runId),
runManifest: run.postprocessManifest,
runManifestSha256: await sha256File(resolveSpriteAssetPath(recordId, run.postprocessManifest)),
approvedAt: new Date().toISOString(),
};
// How many facings must land before the set freezes is registry data, so a
// single-row track freezes on its first approval and a directional one on its
// eighth — the two clones' `allApproved` rules, unified.
const authoringDirections = trackAuthoringDirections(row.id);
const allApproved = authoringDirections.every((item) => selection.directions[item]?.status === 'approved');
selection.status = allApproved ? 'complete' : 'in-progress';
const selectionAbs = join(spriteDir(recordId), selectionRelPath(row.id, recordId));
await ensureDir(join(spriteDir(recordId), row.id));
await atomicWrite(selectionAbs, selection);
if (allApproved) {
await atomicWrite(join(spriteDir(recordId), trackSetRelPath(row.id, recordId)), {
schemaVersion: 1,
kind: row.setKind,
track: row.id,
characterId: recordId,
status: 'final',
directionOrder: authoringDirections,
selectionPath: selectionRelPath(row.id, recordId),
selectionSha256: await sha256File(selectionAbs),
directions: selection.directions,
finalizedAt: new Date().toISOString(),
});
console.log(`🏁 sprite ${row.id} set finalized for ${recordId}`);
}
return getTrackState(row.id, recordId);
}
/**
* Drop one facing's approval because the reference it was rendered from changed.
*
* Called from the reference-unlock paths in `walk.js`: a revised anchor or a
* regenerated turnaround must not leave a stale approved clip standing, since
* the atlas would then compile frames drawn from an image that no longer exists.
* Returns true when something was actually invalidated.
*/
export function invalidateTrackDirectionForAnchorRevision(trackId, recordId, { direction }) {
return withAnimationWriteTail(recordId, () => invalidateTrackDirectionImpl(trackId, recordId, direction));
}
/** Every facing of `trackId`, for a turnaround revision that resets them all. */
export function invalidateTrackForTurnaroundRevision(trackId, recordId) {
return withAnimationWriteTail(recordId, async () => {
const invalidated = [];
for (const direction of trackAuthoringDirections(trackId)) {
// eslint-disable-next-line no-await-in-loop -- ordered: each facing's selection write must settle before the next reads it
if (await invalidateTrackDirectionImpl(trackId, recordId, direction)) invalidated.push(direction);
}
return invalidated;
});
}
/**
* Deliberately reopen one approved facing (or the sole row of a non-directional
* track) so a user can replace a finalized motion without revising its identity
* source. Approved files remain on disk as superseded provenance.
*/
export function reopenTrackDirection(trackId, recordId, { direction: requested } = {}) {
return withAnimationWriteTail(recordId, async () => {
const row = effectiveTrack(trackId);
await requireTrack(recordId, row.id);
const direction = resolveTrackDirection(row, requested);
const reopened = await invalidateTrackDirectionImpl(
row.id,
recordId,
direction,
'manual-track-revision',
);
if (!reopened) {
throw new ServerError(
`${row.label} ${row.directional ? `${direction} ` : ''}has no approved render to reopen`,
{ status: 409, code: 'TRACK_NOT_APPROVED' },
);
}
return getTrackState(row.id, recordId);
});
}
async function invalidateTrackDirectionImpl(
trackId,
recordId,
direction,
supersededReason = 'directional-anchor-revised',
) {
const row = effectiveTrack(trackId);
const [finalizedSet, loaded] = await Promise.all([loadSet(row.id, recordId), loadSelection(row.id, recordId)]);
const approved = loaded?.directions?.[direction] || finalizedSet?.directions?.[direction];
if (approved?.status !== 'approved') return false;
const selection = loaded || { ...seedSelection(row, recordId), directions: { ...(finalizedSet?.directions || {}) } };
if (finalizedSet) await rmGuarded(join(spriteDir(recordId), trackSetRelPath(row.id, recordId)), { force: true });
delete selection.directions[direction];
selection.status = 'in-progress';
await ensureDir(join(spriteDir(recordId), row.id));
await atomicWrite(join(spriteDir(recordId), selectionRelPath(row.id, recordId)), selection);
const run = approved.runId ? await loadRun(recordId, approved.runId) : null;
if (run?.track === row.id) {
await saveRun(recordId, {
...run,
status: supersededReason === 'manual-track-revision' ? 'superseded' : 'superseded-anchor',
supersededAt: new Date().toISOString(),
supersededReason,
});
}
const reasonLabel = supersededReason === 'manual-track-revision' ? 'manual revision' : 'anchor revision';
console.log(`♻️ sprite ${row.id} direction ${recordId}/${direction} reopened after ${reasonLabel}`);
return true;
}