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 — authoring the user-defined animation-track store (#3153).
*
* #3152 made the track registry a merge of compiled `walk` plus a JSON store, and
* #3136 made every track's generate/review/approve workflow generic — so a new
* animation type already needs no code. What it still needed was a way to *author*
* one: the store was a file the user had to hand-edit, which is not a feature so
* much as a documented workaround. This module is the write half of that store.
*
* **Why a module of its own, not writers on `animationTrackStore.js`.** That module
* is imported by `server/lib/validation.js` (which builds its sprite Zod ranges
* from the effective registry at module load), and `animationTrackStore.test.js`
* plus `animationTracks.test.js` pin how narrow its import graph is allowed to be —
* `validation.js` must not drag the native image graph into request validation.
* Refusing to delete a track that has authored work on disk means scanning every
* record, which reaches `records.js` and the workflow's on-disk layout, i.e. sharp.
* So reads stay in the leaf-ish store and writes live here, where the route layer
* (which already imports `atlas.js`) is the only consumer.
*
* **Five row fields are DERIVED from the id, never typed.** `assertAnimationTrackRows`
* refuses two rows claiming the same `contractFrameCountField`, `selectionKind`, or
* `setKind`, and those strings name on-disk files and publish-contract keys — asking
* a user to invent globally-unique `kind` discriminators is a trap with no upside,
* and a typo in one would surface as another track's finalized set satisfying this
* one's evidence check. The user types the id and the derivation is total. A derived
* value that DOES collide (id `directional-scanner` derives the seeded scanner's
* `reviewed-directional-scanner-selection`) is refused at save time by the same
* assert, naming the conflict — which is the point of validating the merged table
* here rather than discovering it at the next boot.
*
* `standaloneContract` is derived too, for the same reason: it is a cross-row
* invariant (`assertAnimationTrackRows` requires exactly one standalone track per
* record kind), so the only correct value depends on what else is in the table. A
* new row is the baseline exactly when none of the kinds it claims already has one
* — which is what makes "delete ambient, then add your own place loop" work. A row
* spanning a kind that has a baseline and one that doesn't has no valid answer, and
* the assert refuses it by naming the kind.
*
* **The writes are serialized and the cache is invalidated.** One `data/` file, one
* `createFileWriteQueue` tail, so a create landing while a delete is mid-flight
* cannot read a stale pre-image (the AGENTS.md rule for a service that owns a single
* JSON state file). Every mutation ends in `__resetAnimationTrackStore()` so the
* running server serves the table it just wrote instead of reporting success against
* a cache nothing dropped.
*
* **A mutation still reports `restartRequired`.** Per #3136/#3152's scope the
* registry itself is live after the cache reset, but `server/lib/validation.js`
* builds `spriteRuntimeContractSchema`'s per-track contract fields ONCE at module
* load — so a brand-new track's `<id>FrameCount` key is stripped by Zod until the
* process restarts. Saying so in the response is the difference between a documented
* boundary and a field that silently does nothing.
*/
import { atomicWrite, pathExists } from '../../lib/fileUtils.js';
import { createFileWriteQueue } from '../../lib/fileWriteQueue.js';
import { ServerError } from '../../lib/errorHandler.js';
import {
WALK_TRACK, AUTHORED_TRACK_FIELDS, assertAnimationTrackRows, deriveTrackFields,
} from './animationTracks.js';
import {
ANIMATION_TRACK_STORE_REL,
ANIMATION_TRACK_STORE_SCHEMA_VERSION,
animationTrackStorePath,
getEffectiveAnimationTracks,
__resetAnimationTrackStore,
} from './animationTrackStore.js';
import { recordsCarryingTrack } from './animationTrackWorkflow.js';
// One store file, so ONE tail — per AGENTS.md's "collapse the queue to a single
// tail per shared file". A per-id queue would let two different tracks' writes
// interleave on the same JSON and lose one of them.
const queueStoreWrite = createFileWriteQueue();
/** The stored (non-builtin) rows, in registration order. */
const storedRows = (tracks) => Object.values(tracks).filter((row) => !row.builtin);
/** The compiled-in rows (`walk`) — never mutable, always first in the merged table. */
const builtinRows = (tracks) => Object.values(tracks).filter((row) => row.builtin);
/**
* Run a registry call whose failure is a bare `Error`, as a 409 the form can show.
*
* Both the store's load and `assertAnimationTrackRows` throw plain Errors — correct
* for boot, where a loud crash naming the field is the whole point, but wrong on this
* surface: here it is a *response* to a request the user made about that very file,
* and an unrecognized error becomes an opaque 500 that says nothing about which row
* is broken. The registry's messages already name the field, the two claimants, or
* the record kind, so they are surfaced verbatim with an actionable status.
*/
function asConflict(fn) {
try {
return fn();
} catch (err) {
throw new ServerError(err.message, { status: 409, code: 'ANIMATION_TRACK_CONFLICT' });
}
}
/**
* The user-facing subset of a row, in the shape the CRUD surface accepts.
*
* Whitelisted from `AUTHORED_TRACK_FIELDS` rather than spread-minus-derived, so a
* round-trip through the editor can't carry an unknown key from a hand-edited store
* back into a saved row and have it silently persist — and so this list and the
* request schema's cannot drift (see that constant's header).
*/
const authoredFields = (row) => ({
id: row.id,
...Object.fromEntries(AUTHORED_TRACK_FIELDS.map((key) => (
[key, Array.isArray(row[key]) ? [...row[key]] : row[key]]
))),
});
/**
* Whether a row is its record kinds' publishable baseline: true only when NONE of
* the kinds it claims is already owned by another row in the SAME prospective table.
*
* `rows` is the whole post-mutation row set (not the pre-image), which is what makes
* a promotion work: deleting `place`'s baseline must let a surviving `place` track
* become one, and deriving against the table as it WAS would instead leave that kind
* with zero owners and 409 on a delete that should have succeeded.
*
* Order-dependent by design: within one table the earlier row wins a contested kind,
* matching the registry's `walk`-first registration order, so the answer is stable
* across installs rather than dependent on which row happened to be recomposed
* first.
*/
function withDerivedBaselines(rows, builtins) {
// Seed from the BUILTINS only: their claim is compiled in and fixed, while every
// stored row's answer is what this function decides below (a row arrives from
// `composeRow` with no `standaloneContract` at all).
const claimed = new Set();
for (const row of builtins) {
if (row.standaloneContract) for (const kind of row.kinds) claimed.add(kind);
}
return rows.map((row) => {
const standaloneContract = row.kinds.every((kind) => !claimed.has(kind));
if (standaloneContract) for (const kind of row.kinds) claimed.add(kind);
return { ...row, standaloneContract };
});
}
/**
* A stored row's PortOS-owned fields, minus `standaloneContract` (a cross-row answer
* `withDerivedBaselines` fills in once the whole table is known).
*
* `existing` is the row already on disk, and its presence is load-bearing: when
* there is one, the five discriminators are carried over VERBATIM rather than
* re-derived. A row whose `setKind` was hand-edited (or seeded under different
* wording — the shipped `scanner` row's `reviewed-directional-scanner-selection` is
* not what `deriveTrackFields('scanner')` produces) names files an approved set on
* this machine already carries, so re-deriving during an unrelated label edit would
* rename the artifact the atlas compiler re-verifies and silently orphan that set.
* Only a brand-new id derives them.
*/
const composeRow = (authored, existing = null) => ({
...authored,
...(existing ? {
contractFrameCountField: existing.contractFrameCountField,
contractFpsField: existing.contractFpsField,
selectionKind: existing.selectionKind,
setKind: existing.setKind,
finalErrorCode: existing.finalErrorCode,
} : deriveTrackFields(authored.id)),
builtin: false,
});
/**
* The prospective stored-row set for a mutation, with every row's discriminators
* preserved and every `standaloneContract` re-derived over the RESULT.
*
* `added` is a brand-new authored row, `replacement` swaps in for its own id, and
* `dropId` removes one — the three mutations expressed as one table rebuild, so
* baseline promotion/demotion is computed the same way whichever one ran.
*/
const nextStoredRows = (tracks, { added = null, replacement = null, dropId = null } = {}) => {
const kept = storedRows(tracks)
.filter((row) => row.id !== dropId)
.map((row) => composeRow(
replacement && row.id === replacement.id ? replacement : authoredFields(row),
row,
));
const rows = added ? [...kept, composeRow(added)] : kept;
return withDerivedBaselines(rows, builtinRows(tracks));
};
/**
* The effective table — every read on this surface goes through this rather than the
* store's getter, so a hand-broken store can't reach one path as a 409 and another
* as a 500.
*/
const effectiveTracksOrThrow = () => asConflict(getEffectiveAnimationTracks);
/**
* Every track the effective registry knows, built-in first.
*
* Returns the FULL rows (derived fields included), because the drawer shows the
* user which on-disk kinds and contract field their id produced — that is how a
* collision refusal below becomes actionable rather than mysterious.
*/
export function listAnimationTracks() {
return {
tracks: Object.values(effectiveTracksOrThrow()),
storePath: ANIMATION_TRACK_STORE_REL,
};
}
/**
* Persist a stored-row set, then drop the registry cache.
*
* The seed's `_comment` is deliberately NOT carried over: once the user has saved
* through the UI this file is theirs, and a note explaining which rows shipped as
* seed data stops being true the moment they edit one.
*/
async function writeStoredRows(rows) {
await atomicWrite(animationTrackStorePath(), {
schemaVersion: ANIMATION_TRACK_STORE_SCHEMA_VERSION,
tracks: rows,
});
__resetAnimationTrackStore();
}
/**
* Validate the prospective merged table (compiled `walk` plus these stored rows)
* through the SAME guard the store runs at load — so a row saved here can never be
* one that bricks the next boot. That is the difference between "refused at save time
* with a message naming the conflict" and a server that won't start.
*/
function assertTableValid(tracks, rows) {
const byId = [...builtinRows(tracks), ...rows].map((row) => [row.id, row]);
asConflict(() => assertAnimationTrackRows(Object.fromEntries(byId)));
}
/**
* Refuse a mutation to a built-in track by name.
*
* `walk` is the one mandatory baseline: its bounds feed the Zod schemas and its
* `setKind` gates every character compile, so editing or deleting it through a data
* edit would brick authoring with no code change to point at. The store's loader
* already refuses a row that shadows it; this is the same refusal at the surface
* where the user would otherwise get a 404 for a track they can plainly see.
*/
function refuseBuiltin(trackId, tracks) {
const row = tracks[trackId];
if (trackId === WALK_TRACK || (row && row.builtin)) {
throw new ServerError(
`'${trackId}' is a built-in animation type and cannot be edited or deleted`,
{ status: 409, code: 'BUILTIN_ANIMATION_TRACK' },
);
}
}
/** 409 for a built-in, 404 for a well-formed id that names no stored track. */
function requireStored(trackId, tracks) {
refuseBuiltin(trackId, tracks);
const row = tracks[trackId];
if (!row) {
throw new ServerError(
`Unknown animation type '${trackId}' — the registered types are: ${Object.keys(tracks).join(', ')}`,
{ status: 404, code: 'UNKNOWN_ANIMATION_TRACK' },
);
}
return row;
}
/**
* Refuse a mutation that would orphan authored work, listing the records.
*
* "In use" is any record carrying this track's finalized set OR a review selection
* with at least one approved direction — both are renders the user approved, both
* are keyed by the `setKind`/`selectionKind` strings a delete removes from the
* registry, and after either mutation the atlas compiler would find on-disk
* evidence for a track it no longer knows (or, on a directionality flip, would
* expect a different number of rows than the set was frozen with).
*
* No force flag, deliberately (#3153): a force-delete that silently drops approved
* renders is worse than a refusal the user can act on by reopening those sets
* first. The message names the records so that action is obvious.
*/
async function refuseIfInUse(trackId, action) {
const recordIds = await recordsCarryingTrack(trackId);
if (!recordIds.length) return;
throw new ServerError(
`Cannot ${action} '${trackId}' — ${recordIds.length} sprite${recordIds.length === 1 ? '' : 's'} `
+ `already ${recordIds.length === 1 ? 'carries' : 'carry'} approved ${trackId} work: ${recordIds.join(', ')}. `
+ 'Reopen or unlock those sets first.',
{ status: 409, code: 'ANIMATION_TRACK_IN_USE', context: { records: recordIds } },
);
}
// Every mutation answers with the fresh table plus the honest scope boundary, so
// the client never has to guess whether its write is live.
const mutationResult = () => ({ ...listAnimationTracks(), restartRequired: true });
/** Create one user-defined animation type. */
export function createAnimationTrack(input) {
return queueStoreWrite(async () => {
const tracks = effectiveTracksOrThrow();
if (tracks[input.id]) {
refuseBuiltin(input.id, tracks);
throw new ServerError(
`Animation type '${input.id}' already exists — edit it instead, or choose another id`,
{ status: 409, code: 'ANIMATION_TRACK_EXISTS' },
);
}
const rows = nextStoredRows(tracks, { added: input });
assertTableValid(tracks, rows);
await writeStoredRows(rows);
return mutationResult();
});
}
/**
* Update one user-defined animation type. `id` is immutable — renaming would have
* to migrate the on-disk `<trackId>/` directories, every run's `track` field and
* every manifest, so it is a delete-plus-create the user makes explicitly.
*
* A directionality FLIP on an in-use track is refused like a delete: the finalized
* set was frozen with a `directionOrder` derived from the old value and the
* compiler validates row counts against the new one, so the two would disagree
* about what is on disk. Every other field (label, bounds, prompt) is safe to
* retune with work already authored — the packer clamps into the new range.
*/
export function updateAnimationTrack(trackId, patch) {
return queueStoreWrite(async () => {
const tracks = effectiveTracksOrThrow();
const existing = authoredFields(requireStored(trackId, tracks));
const next = { ...existing, ...patch, id: trackId };
if (next.directional !== existing.directional) {
await refuseIfInUse(trackId, 'change the facing mode of');
}
const rows = nextStoredRows(tracks, { replacement: next });
assertTableValid(tracks, rows);
await writeStoredRows(rows);
return mutationResult();
});
}
/** Delete one user-defined animation type, refusing when work depends on it. */
export function deleteAnimationTrack(trackId) {
return queueStoreWrite(async () => {
const tracks = effectiveTracksOrThrow();
requireStored(trackId, tracks);
await refuseIfInUse(trackId, 'delete');
const rows = nextStoredRows(tracks, { dropId: trackId });
assertTableValid(tracks, rows);
await writeStoredRows(rows);
return mutationResult();
});
}
/**
* Whether this install has its own store file yet, and where the rows came from.
*
* Surfaced so the drawer can say "these are the shipped starter types" before the
* first save — a user who deletes one needs to know the file is about to become
* theirs and stop tracking the seed.
*/
export async function animationTrackStoreOrigin() {
return (await pathExists(animationTrackStorePath())) ? 'store' : 'seed';
}