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

10.7 KB
Raw Blame
/**
 * Universe Builder Render Orchestration
 *
 * Extracted from routes/universeBuilder/render.js POST /:id/render.
 * Owns the full render-job flow: settings validation, image-mode resolution,
 * compilePrompts, LoRA resolution, findOrCreateUniverseCollection,
 * registerUniverseBuilderRun, job enqueue loop, run record.
 *
 * The route handler becomes: validate → renderUniverseJobs → res.json.
 */

import { randomUUID } from 'crypto';
import * as svc from './universeBuilder.js';
import { assertMediaQueueRoom, enqueueJob, partialBatchAdmissionError } from './mediaJobQueue/index.js';
import { getSettings } from './settings.js';
import { findOrCreateUniverseCollection } from './mediaCollections.js';
import { buildUniverseRunTag } from './universeRunTag.js';
import { registerUniverseBuilderRun, shrinkUniverseBuilderRun } from './universeBuilderCollectionHook.js';
import { IMAGE_GEN_MODE, QUEUEABLE_IMAGE_MODES } from './imageGen/modes.js';
import { resolveRenderTargetConfig } from './imageGen/cloudProviderConfig.js';
import { resolveLocalImageModel } from './imageGen/prepareParams.js';
import { RENDER_TARGET, recordRenderPin } from '../lib/renderTargets.js';
import { resolveImageCleaners } from '../lib/imageCleanDefaults.js';
import { getStylePresetById } from '../lib/writersRoomStylePresets.js';
import { ServerError } from '../lib/errorHandler.js';

/**
 * Orchestrate a full Universe Builder render batch.
 *
 * @param {string} universeId - The universe id.
 * @param {object} body - Validated render request body (renderSchema shape).
 * @param {function} mapServiceError - Error mapper from the route.
 * @returns {Promise<object>} Response payload: { runId, collectionId, collectionName, promptCount, jobIds, entryJobs, mode }
 */
export async function renderUniverseJobs(universeId, body, mapServiceError) {
  const universe = await svc.getUniverse(universeId).catch((err) => { throw mapServiceError(err); });

  // Resolve a style preset (server-side authoritative list) so the embrace
  // tokens are deterministic for this render even if the client sent a stale
  // preset object. Unknown ids are ignored (server is the source of truth).
  const stylePreset = getStylePresetById(body.stylePresetId);
  // `negativePrompt` is the schema field; `extraNegative` is compilePrompts'
  // option name (avoids shadowing `negativePrompt` on each compiled item).
  const compiled = svc.compilePrompts(universe, {
    promptMode: body.promptMode,
    selection: body.selection,
    sheetSelection: body.sheetSelection,
    canonSelection: body.canonSelection,
    batchPerVariation: body.batchPerVariation,
    extraStyle: body.extraStyle,
    extraNegative: body.negativePrompt,
    stylePresetPrompt: stylePreset?.prompt,
    stylePresetNegative: stylePreset?.negativePrompt,
    stylePresetLabel: stylePreset?.label,
  });
  if (!compiled.length) {
    throw new ServerError('No prompts to render — add canon entries, variations, or composite sheets first', {
      status: 400, code: 'WORLD_BUILDER_EMPTY',
    });
  }

  const settings = await getSettings();
  // Render-target ladder (#3231): body.mode → the universe's persisted pin
  // (Phase 3) → the universe-bible pin in settings.renderDefaults → the
  // install default → external (rejected below). body.cloudModel wins over
  // the record's imageModelId pin the same way.
  const renderPin = recordRenderPin(universe);
  const { mode, cloud } = resolveRenderTargetConfig(settings, RENDER_TARGET.UNIVERSE_BIBLE, {
    mode: body.mode,
    model: body.cloudModel,
    recordMode: renderPin.mode,
    recordModel: renderPin.modelId,
    fallbackMode: IMAGE_GEN_MODE.EXTERNAL,
  });

  // Reject `external` mode upfront — batch rendering against a remote SD-API
  // would block this request for the entire batch, and we don't want to leave
  // an orphaned media collection behind when we discover this mid-loop below.
  if (!QUEUEABLE_IMAGE_MODES.includes(mode)) {
    throw new ServerError(
      'Batch render requires local, codex, or grok mode — switch image-gen mode in Settings → Image Gen',
      { status: 400, code: 'WORLD_BUILDER_EXTERNAL_UNSUPPORTED' },
    );
  }

  // Mirror the upfront validation /api/image-gen/generate does so a doomed
  // batch fails before any jobs land in the queue.
  if (cloud && !cloud.enabled) throw cloud.disabledError;
  const localModel = mode === IMAGE_GEN_MODE.LOCAL
    ? resolveLocalImageModel(settings, { modelId: body.modelId })
    : null;
  if (mode === IMAGE_GEN_MODE.LOCAL && !localModel.selectedModel) {
    throw new ServerError('No local image-gen models are registered.', {
      status: 400, code: 'IMAGE_GEN_UNKNOWN_MODEL',
    });
  }

  // Refuse a batch the media queue cannot hold (#8326) whole — before the
  // collection is provisioned or any render lands — rather than half-queue it.
  assertMediaQueueRoom(compiled.length);

  // Provision the collection up front so renders can be tagged as they
  // complete. The completion hook (universeBuilderCollectionHook) will add
  // each finished image's filename to this collection. Resolution is
  // universeId-first (not name-first) so a re-render finds the existing
  // linked bucket even if the universe was hand-renamed or another
  // universe happens to share the same display name. Name-only matching
  // would either fork the bucket on rename or hijack a foreign universe's
  // collection — the atomic helper rules out both.
  const collection = await findOrCreateUniverseCollection({
    universeId: universe.id,
    universeName: universe.name,
    description: `Universe Builder renders for "${universe.name}"`,
  });

  const runId = randomUUID();
  const jobIds = [];
  // Map cfgScale → guidance the same way /api/image-gen/generate does. The
  // mediaJobQueue calls imageGen/local.generateImage() directly (not the
  // dispatcher), so without this mapping the Universe Builder UI's CFG control
  // would silently no-op for local renders.
  const guidance = body.guidance ?? body.cfgScale;
  // Local image gen reads `loraFilenames` (basenames) + `loraScales` (parallel
  // array of numbers), not the `[{filename, scale}]` UI shape. Convert here so
  // every enqueued job actually applies the user's LoRA selection.
  const loraFilenames = Array.isArray(body.loras) && body.loras.length
    ? body.loras.map((l) => l.filename)
    : undefined;
  const loraScales = Array.isArray(body.loras) && body.loras.length
    ? body.loras.map((l) => l.scale)
    : undefined;
  const baseParams = {
    width: body.width,
    height: body.height,
    steps: body.steps,
    cfgScale: body.cfgScale,
    guidance,
    quantize: body.quantize,
    seed: body.seed,
    loraFilenames,
    loraScales,
  };

  // Parallel-indexed mapping from jobId → entryRef so the client can show a
  // per-entry pending loader (MediaJobThumb-style) on the variation / sheet /
  // canon row that owns this render. Only entries with a stable `id` carry an
  // entryRef in `compiled` (the sanitizer mints ids on every write now, so
  // legacy id-less records are the only gap).
  const entryJobs = [];
  // Register the run BEFORE enqueueing any jobs — the queue may dispatch and
  // emit `completed` synchronously for the first job, and without prior
  // registration the completion hook can't coalesce the run's
  // emitRecordUpdated calls. `compiled.length` is the authoritative expected
  // count (each compiled item produces exactly one job below).
  registerUniverseBuilderRun({ runId, universeId: universe.id, jobCount: compiled.length });
  const recordRun = () => svc.recordRun({
    id: runId,
    universeId: universe.id,
    collectionId: collection.id,
    jobIds,
    promptCount: compiled.length,
    createdAt: new Date().toISOString(),
  });
  for (const item of compiled) {
    const params = {
      ...baseParams,
      prompt: item.prompt,
      negativePrompt: item.negativePrompt || undefined,
      ...(item.promptAdditions?.length ? { promptAdditions: item.promptAdditions } : {}),
      // Tag every job so the completion hook can route the result back
      // into the run's collection without us having to thread additional
      // arguments through the queue. `entryRef` (when present — variations
      // and composite sheets gain it once the universe has been written
      // through the current sanitizer) lets the hook also append the
      // rendered filename to the source variation/sheet/canon entry's
      // `imageRefs[]` so the Universe Builder can show the latest render
      // as an avatar next to each item. The pre-resolved `collection` +
      // shared `runId` are passed so each per-item tag reuses them without
      // re-provisioning the collection.
      universeRun: await buildUniverseRunTag({
        universeId: universe.id,
        collection,
        runId,
        category: item.category,
        label: item.label,
        entryRef: item.entryRef,
      }),
    };
    // The queue dispatches directly to imageGen/{codex,local}.generateImage,
    // bypassing imageGen/index.js's dispatcher that resolves cleaners for
    // direct callers. Resolve here so the per-mode cleanC2PA + denoise
    // settings apply to Universe Builder batch renders the same way they
    // do for /api/image-gen/generate and pipeline renders.
    const { cleanC2PA, denoise } = resolveImageCleaners(undefined, settings, mode);
    const jobParams = cloud
      ? { ...cloud.jobParams, cleanC2PA, denoise, ...params }
      // mode === IMAGE_GEN_MODE.LOCAL (validated upfront).
      : { pythonPath: localModel.pythonPath, modelId: localModel.selectedModel.id, cleanC2PA, denoise, ...params };
    const queued = await enqueueJob({ kind: 'image', params: jobParams }).catch(async (err) => {
      // Refused part-way (another producer filled the queue after the
      // preflight): the rest will never be enqueued, so release them from the
      // run's pending count, keep a run record for the renders that DID land,
      // and say how many that was.
      shrinkUniverseBuilderRun(runId, compiled.length - jobIds.length);
      if (jobIds.length) await recordRun();
      throw partialBatchAdmissionError(err, { admitted: jobIds.length, total: compiled.length, noun: 'renders' });
    });
    jobIds.push(queued.jobId);
    if (item.entryRef) entryJobs.push({ jobId: queued.jobId, entryRef: item.entryRef });
  }

  const run = await recordRun();

  console.log(`🌍 Universe Builder render — universe=${universe.name} prompts=${compiled.length} mode=${mode} runId=${runId.slice(0, 8)}`);

  return {
    runId: run.id,
    collectionId: collection.id,
    collectionName: collection.name,
    promptCount: compiled.length,
    jobIds,
    // Per-entry mapping for client-side pending-state UI. Empty when the
    // batch only contains entries without stable ids (legacy fallback).
    entryJobs,
    mode,
  };
}