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

20.0 KB
Raw Blame
/**
 * Music tracks — shared mutation logic (backend-agnostic).
 *
 * The file backend (file.js) and the PostgreSQL backend (db.js) both import the
 * sanitizer + record builders from here so the two backends can never drift.
 * This module has NO I/O — pure functions only. Mirrors `services/albums/
 * logic.js` with track-specific fields.
 *
 * A Track is a single song/recording — standalone or part of an album:
 *   - title         — track title
 *   - albumId       — FK to the owning album (`album-…`), or '' for a single
 *   - artistId      — FK to the performing artist (`artist-…`), or '' for none
 *   - artist        — denormalized artist name (renders before the artist syncs)
 *   - concept       — short creative brief captured by the stepped music designer
 *   - lyrics        — full lyrics (also the conditioning text for lyric-aware
 *                     generators like Ace-Step)
 *   - prompt        — the text/style prompt used (or to use) for generation
 *   - engine        — music-gen engine id the audio came from (e.g. 'acestep'),
 *                     or '' for an uploaded track
 *   - modelId       — model within that engine, or ''
 *   - durationSec   — clip length in seconds, or null
 *   - audioFilename — the music-library filename under data/music/ (the bytes),
 *                     or '' when no audio is attached yet — the ACTIVE render's
 *                     pointer; `engine`/`modelId`/`durationSec` mirror its metadata
 *   - renders       — the full render history (every generated/uploaded take), so
 *                     the studio can show each render as a card and re-select an
 *                     earlier one. Each entry is `{ id, audioFilename, prompt,
 *                     authoredPrompt, lyrics, instrumentalOnly, engine,
 *                     modelId, executionProfile, source, durationSec,
 *                     createdAt, codeProvenance? }`. `codeProvenance` (#9414) is
 *                     present only on a server-rendered code take: `{ language,
 *                     source, sourceHash, seed, runtimeVersion, policyVersion,
 *                     settings }`. `source` is the take's provenance when it
 *                     did not come from a local engine — `'upload'` (a plain
 *                     file), `'suno'` (audio exported from Suno and imported by
 *                     hand), `'youtube'` (the YouTube audio import) — or '' when
 *                     unrecorded (generated takes and pre-provenance renders). The
 *                     top-level `audioFilename`/`engine`/`modelId`/`durationSec`
 *                     point at whichever render is currently ACTIVE (selected).
 *   - chiptuneScore / chiptunePrompt — the LLM-composed looping 8-bit score
 *                     and the brief it was composed from (#2911), or null / ''
 *   - waveSketch / waveSketchPrompt — the Music Designer's LLM-painted
 *                     canvas (v2, lib/paintedCanvas.js, #8464) or a legacy v1
 *                     drawn sketch (lib/waveSketch.js), and the description it
 *                     came from (#8376), or null / ''
 *
 * Tracks are `db-primary` (PostgreSQL `tracks` table). The audio bytes live in
 * the shared music library (services/pipeline/musicLibrary.js, `data/music/`);
 * a track stores only the filename pointer. The storage layer is federation-
 * ready and federates across peers via the per-record peer-sync pipeline
 * (`record kind: track`, sync category: tracks). Audio bytes ride the asset
 * manifest as `music` assets.
 */

import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { sanitizeChiptuneScore } from '../../lib/chiptuneScore.js';
import { normalizeWaveSketch } from '../../lib/waveSketch.js';
import { isStr, trimTo } from '../../lib/textUtils.js';
import { promptAdditionsSchema } from '../../lib/modelInput.js';
import { TITLE_MAX, ALBUM_ID_MAX, ARTIST_ID_MAX, ARTIST_NAME_MAX, CONCEPT_MAX, LYRICS_MAX, PROMPT_MAX, ENGINE_MAX, MODEL_ID_MAX, EXECUTION_PROFILE_MAX, AUDIO_FILENAME_MAX, RENDER_ID_MAX, RENDER_SOURCE_MAX, RENDERS_MAX } from '../../lib/trackLimits.js';
export { TITLE_MAX, ALBUM_ID_MAX, ARTIST_ID_MAX, ARTIST_NAME_MAX, CONCEPT_MAX, LYRICS_MAX, PROMPT_MAX, ENGINE_MAX, MODEL_ID_MAX, EXECUTION_PROFILE_MAX, AUDIO_FILENAME_MAX, RENDER_ID_MAX, RENDER_SOURCE_MAX, RENDERS_MAX };

export const TRACK_ID_RE = /^track-[A-Za-z0-9-]{1,64}$/;

// Render provenance slug (see `source` above). A lowercase slug rather than a
// closed enum so a later import source is a value, not a sanitizer change; the
// routes that WRITE a source validate it against the sources they support.
const RENDER_SOURCE_RE = /^[a-z0-9-]{1,40}$/;
export const RENDER_SOURCES = Object.freeze({ UPLOAD: 'upload', SUNO: 'suno', YOUTUBE: 'youtube' });
// Cap the render history per track so a runaway generate loop can't grow the
// record unboundedly. Oldest renders fall off first (slice(-RENDERS_MAX)); the
// audio bytes stay in the shared library (they may be referenced elsewhere).
// A track clip's usable duration band — wide enough for a long-form generation,
// bounded so a garbage value can't poison the record.
export const DURATION_MIN_SEC = 1;
export const DURATION_MAX_SEC = 3600;

const RENDER_ID_RE = /^[A-Za-z0-9_-]{1,80}$/;

function sanitizeDuration(v) {
  if (typeof v !== 'number' || !Number.isFinite(v)) return null;
  const s = Math.round(v);
  if (s < DURATION_MIN_SEC || s > DURATION_MAX_SEC) return null;
  return s;
}

// Deterministic id for a render synthesized from a legacy single-pointer track
// (audio attached before the render-history field existed). The DB read path
// re-sanitizes on every read, so a fresh `randomUUID` here would mint a new id
// each read — derive a STABLE id from the audio filename instead (already unique
// per render: `music-gen-<uuid>.wav` for generated, the upload basename else).
function legacyRenderId(audioFilename) {
  const slug = String(audioFilename).replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 72);
  return `r-${slug}`.slice(0, RENDER_ID_MAX);
}

const CODE_SOURCE_MAX = 20000; // mirrors MUSIC_CODE_MAX (services/musicCode.js)
const CODE_LANGUAGE_RE = /^[a-z0-9]{1,20}$/;
const SHA256_RE = /^[0-9a-f]{64}$/;
const posInt = (v, max) => (Number.isInteger(v) && v >= 0 && v <= max ? v : null);

/**
 * A code-rendered take's reproducibility record (#9414): the language and exact
 * source that produced the audio, its SHA-256, the seed, the runtime that
 * rendered it and the render settings. Returns null unless the language and
 * source are usable, so a malformed value never half-persists.
 */
function sanitizeCodeProvenance(raw) {
  if (!raw || typeof raw !== 'object') return null;
  if (!isStr(raw.language) || !CODE_LANGUAGE_RE.test(raw.language)) return null;
  if (!isStr(raw.source) || !raw.source.trim() || raw.source.length > CODE_SOURCE_MAX) return null;
  const settings = raw.settings && typeof raw.settings === 'object' ? raw.settings : {};
  return {
    language: raw.language,
    source: raw.source,
    sourceHash: isStr(raw.sourceHash) && SHA256_RE.test(raw.sourceHash) ? raw.sourceHash : '',
    seed: posInt(raw.seed, 2 ** 31),
    runtimeVersion: trimTo(raw.runtimeVersion, 40),
    policyVersion: trimTo(String(raw.policyVersion ?? ''), 40),
    settings: {
      durationSec: posInt(settings.durationSec, DURATION_MAX_SEC),
      sampleRate: posInt(settings.sampleRate, 384000),
      channels: posInt(settings.channels, 64),
      tempoBpm: posInt(settings.tempoBpm, 1000),
    },
  };
}

/**
 * Normalize one render-history entry. Returns null for a non-object or an entry
 * without usable audio bytes (a render with no audioFilename is meaningless and
 * dropped — same drop-on-floor contract as sanitizeTrack). The id falls back to
 * a deterministic filename-derived id so re-sanitizing on read stays stable.
 */
export function sanitizeRender(raw) {
  if (!raw || typeof raw !== 'object') return null;
  const audioFilename = trackAudioFilename(raw.audioFilename);
  if (!audioFilename) return null;
  const id = isStr(raw.id) && RENDER_ID_RE.test(raw.id) ? raw.id : legacyRenderId(audioFilename);
  const codeProvenance = sanitizeCodeProvenance(raw.codeProvenance);
  const additions = promptAdditionsSchema.safeParse(raw.promptAdditions);
  const lyricAdditions = promptAdditionsSchema.safeParse(raw.lyricAdditions);
  const sentLyrics = typeof raw.sentLyrics === 'string' && raw.sentLyrics.length <= LYRICS_MAX + 1000
    ? { sentLyrics: raw.sentLyrics, ...(lyricAdditions.success && lyricAdditions.data ? { lyricAdditions: lyricAdditions.data } : {}) }
    : {};
  // Optional provenance on new local audio takes. Keep the exact caption,
  // including whitespace and the directive beyond the authored 8,000-char cap.
  const sent = typeof raw.sentPrompt === 'string' && raw.sentPrompt.length <= 20000
    ? { sentPrompt: raw.sentPrompt, ...(additions.success && additions.data ? { promptAdditions: additions.data } : {}) }
    : {};
  return {
    id,
    audioFilename,
    prompt: trimTo(raw.prompt, PROMPT_MAX),
    authoredPrompt: trimTo(raw.authoredPrompt, PROMPT_MAX),
    lyrics: isStr(raw.lyrics) ? raw.lyrics.slice(0, LYRICS_MAX) : '',
    // null means a legacy/uploaded render never recorded the choice. Preserve
    // that sentinel so remixing cannot infer vocal intent from empty lyrics.
    instrumentalOnly: typeof raw.instrumentalOnly === 'boolean' ? raw.instrumentalOnly : null,
    engine: trimTo(raw.engine, ENGINE_MAX),
    modelId: trimTo(raw.modelId, MODEL_ID_MAX),
    executionProfile: trimTo(raw.executionProfile, EXECUTION_PROFILE_MAX),
    source: isStr(raw.source) && RENDER_SOURCE_RE.test(raw.source) ? raw.source : '',
    durationSec: sanitizeDuration(raw.durationSec),
    createdAt: isStr(raw.createdAt) && raw.createdAt ? raw.createdAt : new Date().toISOString(),
    ...(codeProvenance ? { codeProvenance } : {}),
    ...sent,
    ...sentLyrics,
  };
}

// De-dup a render list by id (first wins) so a hand-edited record or a sync
// merge can't accumulate duplicate cards.
function dedupRenders(renders) {
  const seen = new Set();
  const out = [];
  for (const r of renders) {
    if (seen.has(r.id)) continue;
    seen.add(r.id);
    out.push(r);
  }
  return out;
}

/**
 * Normalize a raw track record into the canonical stored shape. Returns null for
 * a non-object or a record without a usable id/title (drop-on-floor contract).
 */
export function sanitizeTrack(raw) {
  if (!raw || typeof raw !== 'object') return null;
  if (!isStr(raw.id) || !raw.id) return null;
  const title = trimTo(raw.title, TITLE_MAX);
  if (!title) return null;
  const createdAt = isStr(raw.createdAt) ? raw.createdAt : new Date().toISOString();
  const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt : createdAt;
  const deleted = raw.deleted === true;
  const lyrics = isStr(raw.lyrics) ? raw.lyrics.slice(0, LYRICS_MAX) : '';
  const prompt = isStr(raw.prompt) ? raw.prompt.slice(0, PROMPT_MAX) : '';
  const engine = trimTo(raw.engine, ENGINE_MAX);
  const modelId = trimTo(raw.modelId, MODEL_ID_MAX);
  const durationSec = sanitizeDuration(raw.durationSec);
  // Empty string = no audio attached yet; never null so the shape is stable.
  const audioFilename = trimTo(raw.audioFilename, AUDIO_FILENAME_MAX);

  // Render history. Sanitize + de-dup + cap (newest kept). A legacy single-
  // pointer track (audio but no render array) is BACKFILLED with one synthesized
  // render from its top-level gen metadata — deterministic id + the track's own
  // createdAt, so re-sanitizing on every DB read stays stable (no drift, no new
  // id each read). New writes persist the backfilled array, healing the record.
  let renders = Array.isArray(raw.renders)
    ? dedupRenders(raw.renders.map(sanitizeRender).filter(Boolean)).slice(-RENDERS_MAX)
    : [];
  if (renders.length === 0 && audioFilename) {
    renders = [{
      id: legacyRenderId(audioFilename),
      audioFilename,
      prompt,
      authoredPrompt: prompt,
      lyrics,
      instrumentalOnly: null,
      engine,
      modelId,
      executionProfile: '',
      source: '',
      durationSec,
      createdAt,
    }];
  }

  return {
    id: raw.id,
    title,
    albumId: trimTo(raw.albumId, ALBUM_ID_MAX),
    artistId: trimTo(raw.artistId, ARTIST_ID_MAX),
    artist: trimTo(raw.artist, ARTIST_NAME_MAX),
    concept: isStr(raw.concept) ? raw.concept.slice(0, CONCEPT_MAX) : '',
    lyrics,
    prompt,
    engine,
    modelId,
    durationSec,
    audioFilename,
    renders,
    // Chiptune score (#2911): null = no score; an invalid stored/synced value
    // also normalizes to null (sentinel rule — absent and invalid collapse to
    // "no score", never to a half-valid object the renderer would trip on).
    chiptuneScore: sanitizeChiptuneScore(raw.chiptuneScore),
    chiptunePrompt: trimTo(raw.chiptunePrompt, PROMPT_MAX),
    // Drawn wave sketch (#8376): same sentinel rule — null = no drawing, and an
    // invalid stored/synced value normalizes to null rather than a sketch the
    // synth would trip on.
    waveSketch: normalizeWaveSketch(raw.waveSketch),
    waveSketchPrompt: trimTo(raw.waveSketchPrompt, PROMPT_MAX),
    createdAt,
    updatedAt,
    deleted,
    deletedAt: deleted && isStr(raw.deletedAt) && raw.deletedAt.trim() ? raw.deletedAt : null,
  };
}

/**
 * The bare music-library filename for a track's audio (already a basename), or
 * null when no audio is attached. Tracks store the filename directly (not a
 * URL), so this is mostly an existence/trim guard for the asset pipeline.
 */
export function trackAudioFilename(audioFilename) {
  const name = trimTo(audioFilename, AUDIO_FILENAME_MAX);
  if (!name) return null;
  // Defense-in-depth: never let a path-ish value through as an asset basename.
  if (name.includes('/') || name.includes('\\') || name.includes('..')) return null;
  return name;
}

/** Build a fresh track record from create input. */
export function buildTrackRecord(input, { id, now }) {
  return sanitizeTrack({
    id,
    title: input.title,
    albumId: input.albumId || '',
    artistId: input.artistId || '',
    artist: input.artist || '',
    concept: input.concept || '',
    lyrics: input.lyrics || '',
    prompt: input.prompt || '',
    engine: input.engine || '',
    modelId: input.modelId || '',
    durationSec: input.durationSec ?? null,
    audioFilename: input.audioFilename || '',
    renders: Array.isArray(input.renders) ? input.renders : [],
    createdAt: now,
    updatedAt: now,
    deleted: false,
    deletedAt: null,
  });
}

/**
 * Build a render-history entry from generation/upload metadata. The caller
 * supplies a unique `id` and `now` timestamp so this stays pure (no crypto/clock
 * I/O in logic.js). Returns null when there's no audio filename (sanitizeRender
 * contract).
 */
export function makeRender(input, { id, now } = {}) {
  return sanitizeRender({ ...input, id, createdAt: now });
}

/**
 * Compute the patch that makes `renderId` the ACTIVE render — copy its audio
 * pointer + gen metadata to the top level. Returns null if the render isn't in
 * the history. Deliberately does NOT touch the user-authored `prompt`/`lyrics`
 * (those are the editable source of the next generation, independent of which
 * past render is selected for playback).
 */
export function selectRenderPatch(current, renderId) {
  const r = (current?.renders || []).find((x) => x.id === renderId);
  if (!r) return null;
  return { audioFilename: r.audioFilename, engine: r.engine, modelId: r.modelId, durationSec: r.durationSec };
}

/**
 * Compute the patch that removes `renderId` from the history. When the removed
 * render was the active one, re-point the active fields at the newest remaining
 * render (or clear them when none remain). Returns null if the render isn't in
 * the history. The audio bytes are left in the shared library (may be shared).
 */
export function deleteRenderPatch(current, renderId) {
  const renders = current?.renders || [];
  const removed = renders.find((x) => x.id === renderId);
  if (!removed) return null;
  const next = renders.filter((x) => x.id !== renderId);
  const patch = { renders: next };
  if (removed.audioFilename === current.audioFilename) {
    // Re-point the active fields at the newest remaining take (reusing the same
    // mirror that selectRenderPatch applies), or clear them when none remain.
    const newest = next.length ? next[next.length - 1] : null;
    Object.assign(
      patch,
      newest
        ? selectRenderPatch({ renders: next }, newest.id)
        : { audioFilename: '', engine: '', modelId: '', durationSec: null },
    );
  }
  return patch;
}

// The user-authored fields a partial patch may overwrite. `id`, the LWW/
// tombstone trio, and `createdAt` are server-owned / structural. `renders` is
// server-managed (generate/upload/select/delete-render routes set it); the
// generic create/patch route schemas omit it so a client can't inject history.
const PATCHABLE = [
  'title', 'albumId', 'artistId', 'artist', 'concept', 'lyrics', 'prompt', 'engine', 'modelId', 'durationSec', 'audioFilename', 'renders',
  'chiptuneScore', 'chiptunePrompt', 'waveSketch', 'waveSketchPrompt',
];

/**
 * LWW merge decision for one incoming track record against the local copy.
 * Mirrors mergeAlbumRecord. Returns `{ next, inserted, remoteWins, changed }`.
 */
export function mergeTrackRecord(local, remoteRaw) {
  const remote = sanitizeTrack(remoteRaw);
  if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
  if (!local) return { next: remote, inserted: true, remoteWins: true, changed: true };
  const remoteWins = compareNewerWins(remote.updatedAt, local.updatedAt);
  let next = remoteWins ? remote : local;
  // Absent-vs-cleared (#2911, per the AGENTS.md merge convention): a payload
  // from a chiptune-unaware (≤v2) peer lacks the chiptune KEYS entirely, while
  // a v3 peer that intentionally cleared the score sends `chiptuneScore: null`
  // explicitly. Sanitizing collapses both to null, so gate on key presence in
  // the RAW payload — a winning key-absent remote must not erase the local
  // composition. (The sender-ahead direction is already version-gated; this
  // covers the accepted sender-behind direction.)
  if (remoteWins && next === remote) {
    const carry = {};
    if (!('concept' in remoteRaw) && local.concept) carry.concept = local.concept;
    if (!('chiptuneScore' in remoteRaw) && local.chiptuneScore) carry.chiptuneScore = local.chiptuneScore;
    if (!('chiptunePrompt' in remoteRaw) && local.chiptunePrompt) carry.chiptunePrompt = local.chiptunePrompt;
    // Same for the drawn wave sketch (#8376): a ≤v6 peer's payload lacks the keys.
    if (!('waveSketch' in remoteRaw) && local.waveSketch) carry.waveSketch = local.waveSketch;
    if (!('waveSketchPrompt' in remoteRaw) && local.waveSketchPrompt) carry.waveSketchPrompt = local.waveSketchPrompt;
    // A sender-behind peer may edit the track while omitting caption
    // provenance from its existing takes. Carry only matching take ids; never
    // resurrect a take that the incoming record deliberately deleted.
    const localTakes = new Map((local.renders || []).map((take) => [take.id, take]));
    carry.renders = remote.renders.map((take) => {
      const previous = localTakes.get(take.id);
      return {
        ...take,
        ...(!('sentPrompt' in take) && typeof previous?.sentPrompt === 'string'
          ? { sentPrompt: previous.sentPrompt, ...(previous.promptAdditions ? { promptAdditions: previous.promptAdditions } : {}) } : {}),
        ...(!('sentLyrics' in take) && typeof previous?.sentLyrics === 'string'
          ? { sentLyrics: previous.sentLyrics, ...(previous.lyricAdditions ? { lyricAdditions: previous.lyricAdditions } : {}) } : {}),
      };
    });
    next = { ...remote, ...carry };
  }
  const changed = JSON.stringify(next) !== JSON.stringify(local);
  return { next, inserted: false, remoteWins, changed };
}

/**
 * Apply a partial patch onto an existing record. Only keys PRESENT in `patch`
 * overwrite — absent preserves, present-empty clears (per AGENTS.md). Bumps
 * updatedAt.
 */
export function applyTrackPatch(current, patch = {}) {
  const next = { ...current };
  for (const key of PATCHABLE) {
    if (key in patch) next[key] = patch[key];
  }
  next.updatedAt = new Date().toISOString();
  return sanitizeTrack(next);
}