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

14.3 KB
Raw Blame
/**
 * Character rigging — auto-skin orchestration and the publication contract.
 *
 * Phase 1 (`runtime.js` / `readiness.js`) answers whether this host can run Blender at
 * all. This module is what actually rigs a generated mesh, and — more to the point —
 * what refuses to publish one that did not measure up. The gate itself is a pure
 * reducer in `autoSkinReport.js`; everything here is the plumbing around it.
 *
 * ## The publication contract
 *
 * A rig produces two files that are only meaningful as a PAIR: the GLB, and the JSON
 * report carrying the GLB's SHA-256. Both are written into a staging directory inside
 * the record's own render dir and then moved into place, and the ORDER and the MOVE
 * are both load-bearing:
 *
 *  - **GLB first, report last.** The report is the commit marker. A consumer treats
 *    the pair as usable only when the report exists AND its digest matches the GLB on
 *    disk, so a run interrupted between the two moves is *detectable* rather than
 *    silently loaded as a finished rig.
 *  - **No-replace moves.** `moveWithoutReplace` (`server/lib/noReplaceMove.js`) uses
 *    `link(2)`, which fails atomically on an existing destination. A name collision is
 *    an error, never an overwrite — and on a filesystem that cannot express that, the
 *    publish fails cleanly instead of degrading to a racy `rename`.
 *  - **Nothing published is mutated afterward.** Each run gets its own `rig/<rigId>/`
 *    directory, so a re-rig is a new directory rather than a rewrite of the last one.
 *    The single exception is the rollback below, which unlinks a GLB whose report never
 *    landed — that pair was never publishable in the first place.
 *  - **The source `model.glb` is never touched**, the same rule `sourceKeying.js`
 *    follows for the shared gallery file. The worker opens it read-only and exports to
 *    the staging dir.
 *
 * Child-process boundary outside the request lifecycle, so the worker's outcomes flow
 * through a resolved promise and a thrown `ServerError` at the orchestration layer —
 * never a throw from inside a spawn callback (AGENTS.md).
 */

import { randomUUID } from 'node:crypto';
import { basename, join } from 'node:path';
import { rm, stat } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { ServerError } from '../../lib/errorHandler.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { atomicWrite, ensureDir, PATHS, readJSONFile, sha256File } from '../../lib/fileUtils.js';
import { moveWithoutReplace } from '../../lib/noReplaceMove.js';
import {
  AUTO_SKIN_REPORT_VERSION,
  describeAutoSkinFailure,
  reduceAutoSkinGate,
  resolveAutoSkinThresholds,
  summarizeAutoSkin,
  thresholdsForWorker,
} from './autoSkinReport.js';
import { requireRiggingInterpreter } from './readiness.js';
import { buildHumanoidArmatureSpec } from './skeletonMapping.js';
import { runRiggingWorker } from './workerProcess.js';
import { getModel, mutateModel } from '../imageTo3d/db.js';

/** Per-record directory holding every rig run's published pair. */
export const RIG_DIR_NAME = 'rig';
/** Scratch root inside `rig/`. Excluded from backups — see `services/backup.js`. */
export const RIG_STAGING_DIR_NAME = '.staging';
export const RIGGED_GLB_NAME = 'character.rigged.glb';
export const RIG_REPORT_NAME = 'character.rig.json';

const WORKER_SCRIPT = fileURLToPath(new URL('./autoSkinWorker.py', import.meta.url));

/**
 * Every path one rig run touches, derived from the record id and the run id alone —
 * pure, so the publication tests can point it at a real temp dir.
 *
 * @param {{recordDir: string, rigId: string}} opts
 */
export function rigRunPaths({ recordDir, rigId }) {
  const rigRoot = join(recordDir, RIG_DIR_NAME);
  const publishDir = join(rigRoot, rigId);
  const stageDir = join(rigRoot, RIG_STAGING_DIR_NAME, rigId);
  return {
    rigRoot,
    publishDir,
    stageDir,
    inputGlb: join(recordDir, 'model.glb'),
    stagedGlb: join(stageDir, RIGGED_GLB_NAME),
    stagedReport: join(stageDir, RIG_REPORT_NAME),
    workerReport: join(stageDir, 'worker-report.json'),
    jobFile: join(stageDir, 'job.json'),
    publishedGlb: join(publishDir, RIGGED_GLB_NAME),
    publishedReport: join(publishDir, RIG_REPORT_NAME),
  };
}

/** The served URL for a published rig (static-mounted under `/data`). */
export const riggedAssetUrl = (modelId, rigId) => `/data/image-to-3d/${modelId}/${RIG_DIR_NAME}/${rigId}/${RIGGED_GLB_NAME}`;

/**
 * Publish the staged pair. GLB first, report last, neither replacing anything.
 *
 * The report is finalized HERE rather than by the worker, because the digest can only
 * be taken once the bytes the worker will actually publish are final — a worker-written
 * digest would describe a file the worker could still have rewritten.
 *
 * If the report move fails after the GLB landed, the GLB is unlinked: that pair was
 * never publishable, and leaving a half-pair behind would block the retry with a
 * permanent collision on a file no reader will ever accept.
 *
 * @param {{paths: object, report: object}} opts
 * @returns {Promise<{glbPath: string, reportPath: string, sha256: string, bytes: number}>}
 */
export async function publishRigArtifacts({ paths, report }) {
  const [sha256, info] = await Promise.all([sha256File(paths.stagedGlb), stat(paths.stagedGlb)]);
  await atomicWrite(paths.stagedReport, JSON.stringify({
    ...report,
    report_version: AUTO_SKIN_REPORT_VERSION,
    // Named from the path actually being published, not from a constant: the retarget
    // lane publishes a differently-named GLB through this same helper, and the reader
    // below resolves the artifact from this key rather than guessing a filename.
    output_file: basename(paths.publishedGlb),
    output_bytes: info.size,
    output_sha256: sha256,
  }, null, 2));

  await ensureDir(paths.publishDir);
  await moveWithoutReplace(paths.stagedGlb, paths.publishedGlb);
  await moveWithoutReplace(paths.stagedReport, paths.publishedReport).catch(async (error) => {
    await rm(paths.publishedGlb, { force: true }).catch(() => {});
    throw error;
  });
  return { glbPath: paths.publishedGlb, reportPath: paths.publishedReport, sha256, bytes: info.size };
}

/**
 * Read a published rig, refusing anything that is not a matched pair.
 *
 * This is the consumer half of the contract: a report without its GLB, a GLB without
 * its report, or a digest that disagrees are all `{ ok: false }` with a named reason —
 * never a partially-loaded rig. Callers must not fall back to "well, the GLB is there".
 *
 * @param {{publishDir: string}} opts
 * @returns {Promise<{ok: boolean, reason?: string, report?: object, glbPath?: string}>}
 */
export async function readRiggedArtifact({ publishDir }) {
  const report = await readJSONFile(join(publishDir, RIG_REPORT_NAME), null, { logError: false });
  if (!report || typeof report.output_sha256 !== 'string') return { ok: false, reason: 'missing-report' };
  // The report names its own artifact, so one reader serves both the auto-skin and the
  // retarget lane. `basename` because the report is a file on disk: a report carrying a
  // traversing `output_file` must resolve inside the publish dir or not at all.
  const glbPath = join(publishDir, basename(String(report.output_file || RIGGED_GLB_NAME)));
  const exists = await stat(glbPath).then((info) => info.isFile(), () => false);
  if (!exists) return { ok: false, reason: 'missing-glb' };
  const digest = await sha256File(glbPath);
  if (digest !== report.output_sha256) return { ok: false, reason: 'digest-mismatch' };
  return { ok: true, report, glbPath };
}

const rigError = (message, code, extra = {}) => new ServerError(message, { status: 422, code, ...extra });

/**
 * Rig one mesh: stage, spawn, gate, publish. Every path is injectable so the whole
 * contract is exercisable against a real temp dir and a fake worker.
 *
 * @param {{modelId: string, recordDir: string, skeletonHint?: string, overrides?: object,
 *          readiness?: object, python?: string|null, spawnImpl?: Function, rigId?: string,
 *          timeoutMs?: number, verify?: Function}} opts
 * @returns {Promise<{rigId: string, assetPath: string, reportPath: string, sha256: string,
 *   bytes: number, summary: object, report: object}>}
 */
export async function runAutoSkin({
  modelId,
  recordDir,
  skeletonHint = 'mixamo',
  overrides = {},
  readiness,
  python,
  spawnImpl,
  rigId = `rig-${randomUUID()}`,
  timeoutMs,
  verify = readRiggedArtifact,
}) {
  const interpreter = await requireRiggingInterpreter({ readiness, python });

  const thresholds = resolveAutoSkinThresholds(overrides);
  const paths = rigRunPaths({ recordDir, rigId });
  const sourceExists = await stat(paths.inputGlb).then((info) => info.isFile(), () => false);
  if (!sourceExists) throw rigError('This model has no rendered mesh to rig yet.', 'RIGGING_NO_SOURCE_MESH');

  await ensureDir(paths.stageDir);
  try {
    await atomicWrite(paths.jobFile, JSON.stringify({
      input_glb: paths.inputGlb,
      output_glb: paths.stagedGlb,
      report_path: paths.workerReport,
      thresholds: thresholdsForWorker(thresholds),
      armature: buildHumanoidArmatureSpec({ skeletonHint }),
    }, null, 2));

    const { code, tail } = await runRiggingWorker({
      python: interpreter, script: WORKER_SCRIPT, jobFile: paths.jobFile, spawnImpl, timeoutMs,
    });
    const report = await readJSONFile(paths.workerReport, null, { logError: false });

    // A non-zero exit with a readable report is the EXPECTED gate failure: the worker
    // measured, refused, and said why. Prefer that measured answer over the exit code.
    const gate = report ? reduceAutoSkinGate(report, thresholds) : null;
    if (gate && !gate.ok) {
      throw rigError(describeAutoSkinFailure(gate.reason, gate.metrics), 'RIGGING_GATE_FAILED', {
        context: { reason: gate.reason, metrics: gate.metrics },
      });
    }
    if (code !== 0 || !report) {
      throw rigError(
        `The rigging worker exited ${code} without a usable report.${tail ? ` Last output: ${tail.slice(-400)}` : ''}`,
        'RIGGING_WORKER_FAILED',
      );
    }
    const staged = await stat(paths.stagedGlb).then((info) => info.isFile(), () => false);
    if (!staged) throw rigError('The rigging worker reported success but exported no mesh.', 'RIGGING_NO_OUTPUT');

    const published = await publishRigArtifacts({ paths, report });
    // Read the pair back through the same reader every consumer uses, before recording
    // the rig as ready. A publish that does not verify is exactly the interrupted state
    // this contract exists to make detectable — it must not be reported as a finished
    // rig just because both moves returned.
    const verified = await verify({ publishDir: paths.publishDir });
    if (!verified.ok) {
      throw rigError(`The rig published but did not verify (${verified.reason}).`, 'RIGGING_PUBLISH_UNVERIFIED');
    }
    console.log(`🦴 Rigged ${modelId} as ${rigId}: ${gate.metrics.boneCount} bones, `
      + `${gate.metrics.verticesAfterWeld} vertices, ${gate.metrics.nearestBoneCompleted} filled by nearest bone`);
    return {
      rigId,
      assetPath: riggedAssetUrl(modelId, rigId),
      reportPath: published.reportPath,
      sha256: published.sha256,
      bytes: published.bytes,
      summary: summarizeAutoSkin(gate.metrics),
      report,
    };
  } finally {
    // Scratch only — the published pair lives in a sibling directory, so a failed run
    // leaves nothing behind and a successful one leaves only what it published.
    await rm(paths.stageDir, { recursive: true, force: true }).catch(() => {});
  }
}

// One rig per record at a time. A double-click would otherwise put two Blender
// processes on the same mesh — a re-entrancy guard, not a multi-actor lock
// (AGENTS.md single-user trust model).
const rigsInFlight = new Set();

/**
 * Rig a stored image-to-3D record and persist the result on it. The record's `rig`
 * field is the user-visible evidence: on success the published pair plus the measured
 * summary, on failure the reason and the sentence naming the number that failed.
 *
 * @param {string} modelId
 * @param {{skeletonHint?: string, weldDistance?: number, unweightedCeiling?: number}} [options]
 * @param {object} [deps] Injectable seams (`run`, `now`) for tests.
 * @returns {Promise<object>} The updated record.
 */
export async function rigImageTo3dModel(modelId, options = {}, { run = runAutoSkin, now = () => new Date().toISOString() } = {}) {
  const model = await getModel(modelId);
  if (!model) throw new ServerError('Image-to-3D model not found', { status: 404, code: 'NOT_FOUND' });
  if (model.status !== 'ready' || !model.assetPath) {
    throw rigError('Render this model before rigging it.', 'RIGGING_NO_SOURCE_MESH');
  }
  if (rigsInFlight.has(modelId)) {
    throw new ServerError('This model is already being rigged.', { status: 409, code: 'RIGGING_IN_FLIGHT' });
  }

  rigsInFlight.add(modelId);
  const startedAt = now();
  await mutateModel(modelId, (current) => ({ ...current, rig: { ...(current.rig || {}), status: 'rigging', startedAt, error: null, reason: null } }));
  try {
    const result = await run({
      modelId,
      recordDir: join(PATHS.imageTo3d, modelId),
      skeletonHint: options.skeletonHint,
      overrides: options,
    });
    // The verified pair already sits in its own `rig/<rigId>/` directory and is
    // never replaced, so the row that first names it takes a backup lease (#9982):
    // a cut either follows the commit, with the pair on disk to copy, or precedes
    // it, and the dumped row still says `rigging`.
    return await withBackupAssetPublication(() => mutateModel(modelId, (current) => ({
      ...current,
      rig: {
        status: 'ready',
        rigId: result.rigId,
        assetPath: result.assetPath,
        sha256: result.sha256,
        bytes: result.bytes,
        summary: result.summary,
        skeletonHint: options.skeletonHint || 'mixamo',
        error: null,
        reason: null,
        startedAt,
        completedAt: now(),
      },
    })));
  } catch (error) {
    await mutateModel(modelId, (current) => ({
      ...current,
      rig: {
        ...(current.rig || {}),
        status: 'failed',
        error: String(error?.message || error).slice(0, 2_000),
        reason: error?.context?.reason || error?.code || null,
        metrics: error?.context?.metrics || null,
        startedAt,
        completedAt: now(),
      },
    })).catch(() => {});
    throw error;
  } finally {
    rigsInFlight.delete(modelId);
  }
}