@forgeax-extension/character-3d 0.1.2

package/server/tool-handlers.ts

@@ -0,0 +1,2193 @@
+import {
+  CAPABILITIES,
+  QUALITY_RUBRIC,
+  clampTargetPolycount,
+  generateMeshyTextMockResult,
+  makeCacheKey,
+  type MeshyTextMockArgs,
+  type ProviderResult,
+} from '../shared/catalog';
+import {
+  MESHY_FREE_RUN_ID,
+  MESHY_FREE_WALK_ID,
+  emptyQualityReport,
+  motionRefFromLegacy,
+  motionRefKey,
+  selectFiles,
+  type AssetSlot,
+  type Gen3DAssetManifest,
+  type GenerationMode,
+  type MotionRef,
+  type MotionSystem,
+  type MotionType,
+  type PlayableDeliverySnapshot,
+  type ProviderId,
+  type QualityDim,
+  type QualityReport,
+  type RigChain,
+} from '../shared/manifest';
+import { DEFAULT_WEIGHTS, weightedTotal } from '../shared/quality/heuristics';
+import { applyRodinPromptFlags, filterProviderParams } from '../shared/provider-params';
+import {
+  BUILTIN_PROFILE_PRESETS,
+  effectiveSlots,
+  findPreset,
+  gameProfileFromPreset,
+  type CharacterMotionOverride,
+  type GameMotionProfile,
+  type MotionMappingDraft,
+  type MotionMappingEntry,
+  type MotionSlotDef,
+  type PlaybackMode,
+  type RootMotionStrategy,
+} from '../shared/playable-profile';
+import { playableDeliveryLocalUrl } from '../shared/playable-preview-url';
+import { filterMotions, getMeshyCatalog, hunyuanV1Catalog, visviseCatalog, type MotionOption } from './motion-catalog';
+import type { AssetStorage, DerivedFileInput } from './asset-storage';
+import { PerGameAssetStore } from './per-game-store';
+import { engineImportStatus, importToEngine, type EngineImportResult, type EngineImportStatus } from './engine-import';
+import {
+  exportPlayableCharacter,
+  mappingFingerprint,
+  type ExportPlayableResult,
+} from './export-playable-character';
+import {
+  adoptPlayableCharacter,
+  inspectAdoptCandidate,
+  type AdoptCandidate,
+  type AdoptPlayableResult,
+  type AdoptSlotMapping,
+} from './adopt-playable-character';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, extname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateCacheFirst, persistGeneration, type PersistInput } from './generate';
+import * as cache from './cache';
+import { getCosEnv, getHunyuanEnv, getLitellmEnv, getMeshyEnv, getRodinEnv, getVisviseEnv, realProvidersEnabled } from './env';
+import { HUNYUAN_GATEWAY_MODELS, MESHY_GATEWAY_MODELS, RODIN_GATEWAY_MODELS, VISVISE_GATEWAY_MODELS } from './providers/gateway-models';
+import { readCredentials, writeCredentials } from './credentials-store';
+import { CosUploader, mimeForModelFormat } from './cos-uploader';
+import { uploadTransferArtifact } from './asset-upload';
+import {
+  HunyuanWorkflowProvider,
+  type HunyuanGenerateInput,
+  type ViewSlot,
+} from './providers/hunyuan-workflow';
+import { MeshyProvider, type MeshyGenerateInput } from './providers/meshy';
+import { RodinGatewayProvider, type RodinGatewayGenerateInput } from './providers/rodin-gateway';
+import { VisviseProvider, visviseInputFromFiltered, visviseInputUrl, type VisviseGenerateInput } from './providers/visvise';
+import { HunyuanRestProvider, type ModelFileOut } from './providers/hunyuan-rest';
+
+// Per-game storage adapter (ADR-0002). Assets live under the active game's
+// .forgeax/games/<slug>/assets/3d/{characters|meshes}/ tree; identity is the
+// game-relative assetPath. Same-origin preview URLs mirror the Studio server's
+// read-only /api/game-assets/:slug/* route (packages/server/src/main.ts).
+const perGameStore = new PerGameAssetStore();
+const storage: AssetStorage = perGameStore;
+
+// Every store-touching tool needs an active game. The host iframe injects
+// ?slug=<gameSlug>; the frontend threads it into each call. Reject early with a
+// clear code so the UI can render an empty/disabled state instead of writing to
+// a guessed path.
+function requireSlug(slug: string | undefined): string {
+  const s = slug?.trim();
+  if (!s) {
+    throw Object.assign(new Error('no active game (slug is required)'), { code: 'missing_game' });
+  }
+  return s;
+}
+
+function resolveSlot(slot: AssetSlot | undefined): AssetSlot {
+  return slot === 'characters' ? 'characters' : 'meshes';
+}
+
+// Default base name when the caller does not name the asset: derive from the
+// prompt (text) or fall back to provider+mode. The store sanitizes + de-dupes.
+function defaultName(provided: string | undefined, fallback: string): string {
+  const n = provided?.trim();
+  return n && n.length > 0 ? n : fallback;
+}
+
+interface ProviderStatusResult {
+  ok: true;
+  quotaSafe: boolean;
+  realProvidersEnabled: boolean;
+  generatedAt: string;
+  rubric: readonly string[];
+  capabilities: typeof CAPABILITIES;
+  providers: ProviderRuntimeStatus[];
+}
+
+type ProviderAvailability = 'configured' | 'available' | 'unavailable' | 'unknown';
+
+interface ProviderRuntimeStatus {
+  providerId: GenProvider;
+  providerName: string;
+  configured: boolean;
+  availability: ProviderAvailability;
+  selectable: boolean;
+  reason: string;
+  models: Record<string, string>;
+}
+
+const PROVIDER_MODELS: Record<GenProvider, Record<string, string>> = {
+  meshy: { ...MESHY_GATEWAY_MODELS, rig: MESHY_GATEWAY_MODELS.autoRig },
+  hunyuan_workflow: { ...HUNYUAN_GATEWAY_MODELS },
+  rodin: { generate: RODIN_GATEWAY_MODELS.generate },
+  visvise: { ...VISVISE_GATEWAY_MODELS },
+};
+
+function providerDisplayName(providerId: GenProvider): string {
+  if (providerId === 'meshy') return 'Meshy';
+  if (providerId === 'rodin') return 'Rodin';
+  if (providerId === 'visvise') return 'VISVISE';
+  return 'Hunyuan';
+}
+
+function providerEnvConfigured(providerId: GenProvider): boolean {
+  if (providerId === 'meshy') return getMeshyEnv() !== null;
+  if (providerId === 'rodin') return getRodinEnv() !== null;
+  if (providerId === 'visvise') return getVisviseEnv() !== null;
+  return getHunyuanEnv() !== null;
+}
+
+function providerRuntimeStatus(providerId: GenProvider): ProviderRuntimeStatus {
+  const realEnabled = realProvidersEnabled();
+  const litellm = getLitellmEnv();
+  const configured = providerEnvConfigured(providerId);
+  const providerName = providerDisplayName(providerId);
+  const selectable = providerId !== 'meshy';
+  const hiddenReason = 'UI hidden; code retained';
+  if (configured) {
+    const meshy = providerId === 'meshy' ? getMeshyEnv() : null;
+    return {
+      providerId,
+      providerName,
+      configured: true,
+      availability: 'configured',
+      selectable,
+      reason: selectable
+        ? meshy?.transport === 'direct'
+          ? 'Meshy is on the local recording path (operator key → api.meshy.ai).'
+          : 'Real provider calls are enabled and the LiteLLM gateway key is configured.'
+        : hiddenReason,
+      models: PROVIDER_MODELS[providerId],
+    };
+  }
+  if (!realEnabled && litellm) {
+    return {
+      providerId,
+      providerName,
+      configured: false,
+      availability: 'available',
+      selectable,
+      reason: selectable
+        ? 'LiteLLM gateway key is present; enable real providers to use it.'
+        : hiddenReason,
+      models: PROVIDER_MODELS[providerId],
+    };
+  }
+  return {
+    providerId,
+    providerName,
+    configured: false,
+    availability: realEnabled ? 'unknown' : 'unknown',
+    selectable,
+    reason: selectable
+      ? realEnabled
+        ? 'Real providers are enabled but no LiteLLM gateway key was found.'
+        : 'Mock mode is active; configure a LiteLLM gateway key before enabling real providers.'
+      : hiddenReason,
+    models: PROVIDER_MODELS[providerId],
+  };
+}
+
+function getProviderStatus(): ProviderStatusResult {
+  const realEnabled = realProvidersEnabled();
+  return {
+    ok: true,
+    quotaSafe: !realEnabled,
+    realProvidersEnabled: realEnabled,
+    generatedAt: new Date().toISOString(),
+    rubric: QUALITY_RUBRIC,
+    capabilities: CAPABILITIES,
+    providers: (['hunyuan_workflow', 'visvise', 'rodin', 'meshy'] as const).map(providerRuntimeStatus),
+  };
+}
+
+interface ListAssetsArgs {
+  slug?: string;
+  assetSlot?: AssetSlot;
+  provider?: ProviderId | 'all';
+}
+
+interface ListAssetsResult {
+  ok: true;
+  assets: Gen3DAssetManifest[];
+}
+
+async function listAssets(args: ListAssetsArgs = {}): Promise<ListAssetsResult> {
+  const slug = requireSlug(args.slug);
+  const provider = args.provider ?? 'all';
+  const all = await storage.listAssets(slug, args.assetSlot);
+  const assets = provider === 'all' ? all : all.filter((m) => m.provider === provider);
+  return { ok: true, assets };
+}
+
+interface DeleteAssetArgs {
+  slug?: string;
+  assetPath: string;
+}
+
+interface DeleteAssetResult {
+  ok: true;
+  assetPath: string;
+  tombstoned: boolean;
+}
+
+// Destructive: removes the main GLB + sidecar + same-basename sidefiles, then
+// tombstones its cacheKey so a deliberately deleted asset never resurrects from
+// a later cache hit (and never silently re-burns quota).
+async function deleteAsset(args: DeleteAssetArgs): Promise<DeleteAssetResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) {
+    throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  }
+  const { cacheKey } = await storage.deleteAsset(slug, assetPath);
+  if (cacheKey) await cache.tombstone(slug, cacheKey);
+  return { ok: true, assetPath, tombstoned: Boolean(cacheKey) };
+}
+
+interface GenerateMockArgs extends MeshyTextMockArgs {
+  slug?: string;
+  assetSlot?: AssetSlot;
+  assetName?: string;
+}
+
+interface GenerateMockResult {
+  ok: true;
+  quotaSafe: true;
+  cacheKey: string;
+  manifest: Gen3DAssetManifest;
+}
+
+async function generateMeshyTextMock(args: GenerateMockArgs): Promise<GenerateMockResult> {
+  const slug = requireSlug(args.slug);
+  const assetSlot = resolveSlot(args.assetSlot);
+  const { cacheKey, result } = generateMeshyTextMockResult(args);
+  const ctx: PersistInput = {
+    slug,
+    assetSlot,
+    assetName: defaultName(args.assetName, args.prompt),
+    cacheKey,
+  };
+  const manifest = await persistGeneration(result, storage, ctx);
+  return { ok: true, quotaSafe: true, cacheKey, manifest };
+}
+
+// Mode-based generation tools. Provider is a parameter; today the real
+// providers are Hunyuan workflow and Meshy. When real providers are not
+// configured, these fall back to the deterministic mock so the path stays
+// quota-safe by default.
+
+interface BaseGenArgs {
+  slug?: string;
+  assetSlot?: AssetSlot;
+  assetName?: string;
+  provider?: ProviderId;
+  enablePbr?: boolean;
+  enableFbxUrl?: boolean;
+  targetPolycount?: number;
+  providerParams?: Record<string, unknown>;
+}
+
+interface TextTo3DArgs extends BaseGenArgs {
+  prompt: string;
+}
+
+interface ImageTo3DArgs extends BaseGenArgs {
+  imageUrl: string;
+}
+
+interface ViewsTo3DArgs extends BaseGenArgs {
+  views: Partial<Record<ViewSlot, string>>;
+}
+
+interface GenerateResult {
+  ok: true;
+  cacheKey: string;
+  cacheHit: boolean;
+  usedMock: boolean;
+  manifest: Gen3DAssetManifest;
+}
+
+function mockFallback(provider: ProviderId, mode: GenerationMode, prompt: string | null): ProviderResult {
+  // Reuse the deterministic mock byte payloads regardless of provider/mode so
+  // the path works without quota. prompt may be null for image/views. The mock
+  // is tagged with the requested provider so the manifest reflects user intent.
+  const { result } = generateMeshyTextMockResult({ prompt: prompt ?? mode });
+  return { ...result, provider, mode, sourceJobId: null };
+}
+
+// Providers backing the mode tools today: Hunyuan workflow, Meshy, Rodin.
+// Default (and any unknown value) resolves to Hunyuan workflow for backward
+// compatibility. refine is Meshy-only and handled separately.
+type GenProvider = 'hunyuan_workflow' | 'meshy' | 'rodin' | 'visvise';
+
+function resolveProvider(provider: ProviderId | undefined): GenProvider {
+  if (provider === 'meshy') return 'meshy';
+  if (provider === 'rodin') return 'rodin';
+  if (provider === 'visvise') return 'visvise';
+  return 'hunyuan_workflow';
+}
+
+function providerNotConfigured(provider: GenProvider | 'hunyuan_rest', action: string): Error {
+  const providerLabel =
+    provider === 'meshy' ? 'Meshy'
+    : provider === 'rodin' ? 'Rodin'
+    : provider === 'visvise' ? 'VISVISE'
+    : 'Hunyuan';
+  const reason = 'GEN3D_ENABLE_REAL_PROVIDERS=1 but the LiteLLM 3D gateway key is not configured.';
+  return Object.assign(
+    new Error(`${providerLabel} real ${action} is not configured. ${reason}`),
+    { code: 'provider_not_configured', provider, action },
+  );
+}
+
+function resolvePolycount(target: number | undefined, provider: GenProvider): number {
+  if (target !== undefined) return clampTargetPolycount(target);
+  if (provider === 'meshy') return clampTargetPolycount(getMeshyEnv()?.defaultPolycount ?? 30000);
+  return clampTargetPolycount(getHunyuanEnv()?.defaultFaceCount ?? 30000);
+}
+
+function buildProviderParams(
+  provider: GenProvider,
+  mode: GenerationMode,
+  raw: Record<string, unknown> | undefined,
+): {
+  filtered: Record<string, string | number | boolean>;
+  cacheBits: Record<string, string | number | boolean>;
+} {
+  const filtered = filterProviderParams(provider, mode, raw);
+  const cacheBits: Record<string, string | number | boolean> = {};
+  for (const [k, v] of Object.entries(filtered)) cacheBits[`pp:${k}`] = v;
+  return { filtered, cacheBits };
+}
+
+// Provider-aware cache-first generation. Picks the real provider when its env is
+// configured, else falls back to the deterministic mock (quota-safe). The
+// cacheKey is computed by the caller (includes provider + assetSlot, excludes
+// assetName), so caches stay isolated per slot and a rename never re-burns
+// quota.
+// Provider inputs may be passed eagerly, or as a lazy async factory invoked
+// ONLY on a cache MISS and ONLY for the real-provider branch — so views-to-3d
+// can defer its studio-local→COS transfer until it's actually needed (never on a
+// cache hit, never on the mock path). See viewsTo3D.
+type GenInputs = {
+  hunyuan: HunyuanGenerateInput;
+  meshy: MeshyGenerateInput;
+  rodin: RodinGatewayGenerateInput;
+  visvise: VisviseGenerateInput;
+};
+
+async function runGeneration(
+  provider: GenProvider,
+  mode: GenerationMode,
+  ctx: PersistInput,
+  inputs: GenInputs | (() => Promise<GenInputs>),
+  mockPrompt: string | null,
+): Promise<GenerateResult> {
+  let usedMock = false;
+  const resolveInputs = (): Promise<GenInputs> =>
+    typeof inputs === 'function' ? inputs() : Promise.resolve(inputs);
+  const produce = async (): Promise<ProviderResult> => {
+    if (provider === 'meshy') {
+      const env = getMeshyEnv();
+      if (env) return new MeshyProvider({ env, slug: ctx.slug }).generate((await resolveInputs()).meshy);
+      if (realProvidersEnabled()) throw providerNotConfigured('meshy', mode);
+    } else if (provider === 'rodin') {
+      const env = getRodinEnv();
+      if (env) return new RodinGatewayProvider({ env, slug: ctx.slug }).generate((await resolveInputs()).rodin);
+      if (realProvidersEnabled()) throw providerNotConfigured('rodin', mode);
+    } else if (provider === 'visvise') {
+      const env = getVisviseEnv();
+      if (env) return new VisviseProvider({ env, slug: ctx.slug }).generate((await resolveInputs()).visvise);
+      if (realProvidersEnabled()) throw providerNotConfigured('visvise', mode);
+    } else {
+      const env = getHunyuanEnv();
+      if (env) return new HunyuanWorkflowProvider({ env, slug: ctx.slug }).generate((await resolveInputs()).hunyuan);
+      if (realProvidersEnabled()) throw providerNotConfigured('hunyuan_workflow', mode);
+    }
+    usedMock = true;
+    return mockFallback(provider, mode, mockPrompt);
+  };
+  const { manifest, cacheHit } = await generateCacheFirst(storage, ctx, produce);
+  return { ok: true, cacheKey: ctx.cacheKey, cacheHit, usedMock: cacheHit ? manifest.providerMode === 'mock' : usedMock, manifest };
+}
+
+/** Live Meshy / LiteLLM reject with HTTP 400 before any mesh is billed. */
+export const MESHY_TEXT_PROMPT_MAX = 800;
+
+export function assertMeshyTextPrompt(prompt: string): void {
+  if (prompt.length <= MESHY_TEXT_PROMPT_MAX) return;
+  throw Object.assign(
+    new Error(
+      `Meshy text prompt is ${prompt.length} characters; max is ${MESHY_TEXT_PROMPT_MAX}. Compress the same design spec and retry — do not switch vendor.`,
+    ),
+    { code: 'prompt_too_long', limit: MESHY_TEXT_PROMPT_MAX, length: prompt.length },
+  );
+}
+
+async function textTo3D(args: TextTo3DArgs): Promise<GenerateResult> {
+  const prompt = args.prompt.trim();
+  if (!prompt) throw Object.assign(new Error('prompt is required'), { code: 'invalid_prompt' });
+  const provider = resolveProvider(args.provider);
+  if (provider === 'meshy') assertMeshyTextPrompt(prompt);
+  const slug = requireSlug(args.slug);
+  const assetSlot = resolveSlot(args.assetSlot);
+  const faceCount = resolvePolycount(args.targetPolycount, provider);
+  const enablePbr = args.enablePbr ?? true;
+  const enableFbxUrl = args.enableFbxUrl ?? false;
+  const { filtered, cacheBits } = buildProviderParams(provider, 'text', args.providerParams);
+  const cacheKey = makeCacheKey(provider, 'text', {
+    assetSlot,
+    prompt,
+    faceCount,
+    enablePbr,
+    enableFbxUrl,
+    ...(provider === 'meshy' ? { shouldTexture: true, autoRefine: enablePbr } : {}),
+    ...cacheBits,
+  });
+  return runGeneration(
+    provider,
+    'text',
+    { slug, assetSlot, assetName: defaultName(args.assetName, prompt), faceCount, cacheKey },
+    {
+      hunyuan: { mode: 'text', prompt, faceCount, enablePbr, enableFbxUrl },
+      meshy: { mode: 'text', prompt, targetPolycount: faceCount, enablePbr, params: filtered },
+      rodin: { mode: 'text', prompt: applyRodinPromptFlags(prompt, filtered, 'text') },
+      visvise: visviseInputFromFiltered({ mode: 'text', prompt }, filtered),
+    },
+    prompt,
+  );
+}
+
+async function imageTo3D(args: ImageTo3DArgs): Promise<GenerateResult> {
+  const slug = requireSlug(args.slug);
+  const imageUrl = args.imageUrl.trim();
+  if (!imageUrl) throw Object.assign(new Error('imageUrl is required'), { code: 'invalid_image_url' });
+  const assetSlot = resolveSlot(args.assetSlot);
+  const provider = resolveProvider(args.provider);
+  const faceCount = resolvePolycount(args.targetPolycount, provider);
+  const enablePbr = args.enablePbr ?? true;
+  const enableFbxUrl = args.enableFbxUrl ?? false;
+  const { filtered, cacheBits } = buildProviderParams(provider, 'image', args.providerParams);
+  // cacheKey keys off the stable studio-local URL, never an ephemeral COS URL.
+  const cacheKey = makeCacheKey(provider, 'image', {
+    assetSlot,
+    imageUrl,
+    faceCount,
+    enablePbr,
+    enableFbxUrl,
+    ...(provider === 'meshy' ? { shouldTexture: true } : {}),
+    ...cacheBits,
+  });
+  const buildInputs = async (): Promise<GenInputs> => {
+    const reachable = await ensureProviderReachableUrl(imageUrl, slug);
+    const rodinPrompt = applyRodinPromptFlags('', filtered, 'image');
+    return {
+      hunyuan: { mode: 'image', imageUrl: reachable, faceCount, enablePbr, enableFbxUrl },
+      meshy: { mode: 'image', imageUrl: reachable, targetPolycount: faceCount, enablePbr, params: filtered },
+      rodin: {
+        mode: 'image',
+        imageUrl: reachable,
+        ...(rodinPrompt ? { prompt: rodinPrompt } : {}),
+      },
+      visvise: visviseInputFromFiltered({ mode: 'image', imageUrl: reachable }, filtered),
+    };
+  };
+  return runGeneration(
+    provider,
+    'image',
+    { slug, assetSlot, assetName: defaultName(args.assetName, `image-${provider}`), faceCount, cacheKey },
+    buildInputs,
+    null,
+  );
+}
+
+// ── T1 (ADR-0008 D-B): studio-local view URLs → COS transfer ────────────────
+// character:generate-turnaround returns studio-local image URLs — a relative
+// /api/wb/character/asset?path=… or a loopback host — that a URL-fetching
+// provider (Meshy/Hunyuan/Rodin) cannot reach. When a REAL provider will run we
+// server-side fetch those bytes and re-host them on COS, then feed the public
+// URL. Forge passes the turnaround url straight into views-to-3d (no schema
+// change, no multi-MB base64 over the LLM). Public URLs and the mock path are
+// untouched.
+// URL#hostname yields the bracketed form '[::1]' for IPv6 loopback, so the bare
+// '::1' would be dead — only the bracketed form can ever match.
+const STUDIO_LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '0.0.0.0']);
+
+const CHAT_IMAGE_EXT_MIME: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+/** Chat paste lands as an absolute file path (or file://). Not a Studio HTTP URL. */
+export function looksLikeAbsoluteFilesystemPath(ref: string): boolean {
+  const u = ref.trim();
+  if (!u) return false;
+  if (/^file:/i.test(u)) return true;
+  if (/^[a-zA-Z]:[\\/]/.test(u)) return true;
+  return u.startsWith('/') && !u.startsWith('/api/');
+}
+
+function projectRootFromEnv(): string {
+  return process.env.FORGEAX_PROJECT_ROOT ?? resolve(process.cwd(), '.forgeax-runtime');
+}
+
+function isSafePathSegment(s: string): boolean {
+  return Boolean(s) && !s.includes('/') && !s.includes('\\') && s !== '.' && s !== '..' && !s.includes('\0');
+}
+
+function safeUploadBasename(raw: string): string | null {
+  let name = raw.trim();
+  if (!name) return null;
+  try {
+    name = decodeURIComponent(name);
+  } catch {
+    // keep raw
+  }
+  name = basename(name);
+  if (!isSafePathSegment(name)) return null;
+  if (!CHAT_IMAGE_EXT_MIME[extname(name).toLowerCase()]) return null;
+  return name;
+}
+
+const SESSION_UPLOAD_API_RE = /^\/api\/sessions\/([^/?#]+)\/uploads\/([^/?#]+)/i;
+
+/** Bare chat-upload filename, or /api/sessions/<sid>/uploads/<file>. */
+export function parseChatUploadRef(ref: string): { sid?: string; fileName: string } | null {
+  const raw = ref.trim();
+  if (!raw) return null;
+  let pathname = raw;
+  if (/^https?:\/\//i.test(raw)) {
+    try {
+      pathname = new URL(raw).pathname;
+    } catch {
+      return null;
+    }
+  }
+  const api = pathname.match(SESSION_UPLOAD_API_RE);
+  if (api) {
+    const fileName = safeUploadBasename(api[2]);
+    if (!fileName || !isSafePathSegment(api[1])) return null;
+    return { sid: api[1], fileName };
+  }
+  if (raw.includes('/') || raw.includes('\\') || /^(?:https?|file|data|blob):/i.test(raw)) {
+    return null;
+  }
+  const fileName = safeUploadBasename(raw);
+  return fileName ? { fileName } : null;
+}
+
+/** Newest matching file under a game's session uploads directory. */
+export function resolveSessionUploadPath(
+  fileName: string,
+  slug: string,
+  sid?: string,
+): string | null {
+  const safeName = safeUploadBasename(fileName);
+  if (!safeName || !isSafePathSegment(slug) || (sid && !isSafePathSegment(sid))) return null;
+  const sessionsRoot = resolve(projectRootFromEnv(), '.forgeax', 'games', slug, 'sessions');
+  const candidates: string[] = [];
+  if (sid) {
+    candidates.push(resolve(sessionsRoot, sid, 'uploads', safeName));
+  } else {
+    let entries: string[] = [];
+    try {
+      entries = readdirSync(sessionsRoot);
+    } catch {
+      return null;
+    }
+    for (const entry of entries) {
+      if (!isSafePathSegment(entry)) continue;
+      candidates.push(resolve(sessionsRoot, entry, 'uploads', safeName));
+    }
+  }
+  let best: { path: string; mtime: number } | null = null;
+  for (const p of candidates) {
+    const rel = relative(sessionsRoot, p);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) continue;
+    try {
+      const st = statSync(p);
+      if (!st.isFile() || st.size === 0) continue;
+      if (!best || st.mtimeMs > best.mtime) best = { path: p, mtime: st.mtimeMs };
+    } catch {
+      // skip missing session dirs
+    }
+  }
+  return best?.path ?? null;
+}
+
+export function chatAttachmentImagePath(ref: string, slug?: string): string | null {
+  const raw = ref.trim();
+  if (!raw) return null;
+  if (looksLikeAbsoluteFilesystemPath(raw)) {
+    try {
+      return raw.startsWith('file:') ? fileURLToPath(raw) : raw;
+    } catch {
+      return null;
+    }
+  }
+  const parsed = parseChatUploadRef(raw);
+  if (!parsed || !slug) return null;
+  return resolveSessionUploadPath(parsed.fileName, slug, parsed.sid);
+}
+
+export function isStudioLocalImageUrl(url: string): boolean {
+  const u = url.trim();
+  if (!u) return false;
+  // data:/blob: are self-contained; file: and absolute FS paths are chat attachments.
+  if (/^(?:data|blob|file):/i.test(u) || u.startsWith('//')) return false;
+  if (!/^https?:\/\//i.test(u)) {
+    if (looksLikeAbsoluteFilesystemPath(u)) return false;
+    // Bare "shot.png" is a chat-upload name, not /api/... or a workbench relative path.
+    if (!u.includes('/')) return false;
+    return true;
+  }
+  try {
+    return STUDIO_LOCAL_HOSTS.has(new URL(u).hostname);
+  } catch {
+    return false;
+  }
+}
+
+// Studio hosts plugin handlers in-process; resolve relative URLs against its own
+// loopback origin (FORGEAX_SERVER_PORT, default 18900 — packages/server/main.ts).
+export function studioBaseUrl(): string {
+  return `http://127.0.0.1:${process.env.FORGEAX_SERVER_PORT ?? '18900'}`;
+}
+
+export interface ImageTransferDeps {
+  baseUrl: string;
+  fetchImpl: typeof fetch;
+  upload: (data: Uint8Array, mimetype: string) => Promise<string>;
+}
+
+// Fetch a studio-local image and re-host it on COS, returning the public URL.
+// Deps are injected so the transfer is unit-testable with zero network.
+export async function transferStudioLocalImage(url: string, deps: ImageTransferDeps): Promise<string> {
+  const abs = /^https?:\/\//i.test(url) ? url : `${deps.baseUrl}${url.startsWith('/') ? '' : '/'}${url}`;
+  const res = await deps.fetchImpl(abs);
+  if (!res.ok) {
+    throw Object.assign(new Error(`failed to fetch studio-local image (${res.status}): ${url}`), {
+      code: 'studio_local_fetch_failed',
+    });
+  }
+  const data = new Uint8Array(await res.arrayBuffer());
+  if (data.byteLength === 0) {
+    throw Object.assign(new Error(`studio-local image is empty: ${url}`), {
+      code: 'studio_local_fetch_failed',
+    });
+  }
+  const mimetype = res.headers.get('content-type')?.split(';')[0]?.trim() || 'image/png';
+  return deps.upload(data, mimetype);
+}
+
+/** Read a chat-attachment image from disk and re-host it. No LLM base64. */
+export async function transferChatAttachmentImage(
+  ref: string,
+  upload: ImageTransferDeps['upload'],
+): Promise<string> {
+  const path = chatAttachmentImagePath(ref);
+  if (!path || !isAbsolute(path)) {
+    throw Object.assign(new Error(`not a local image path: ${ref}`), { code: 'invalid_image_url' });
+  }
+  let st;
+  try {
+    st = statSync(path);
+  } catch {
+    throw Object.assign(new Error(`chat attachment image not found: ${path}`), { code: 'invalid_image_url' });
+  }
+  if (!st.isFile()) {
+    throw Object.assign(new Error(`chat attachment is not a file: ${path}`), { code: 'invalid_image_url' });
+  }
+  if (st.size === 0) {
+    throw Object.assign(new Error(`chat attachment image is empty: ${path}`), { code: 'invalid_image_url' });
+  }
+  if (st.size > MAX_UPLOAD_BYTES) {
+    throw Object.assign(
+      new Error(`chat attachment image too large: ${st.size} bytes (max ${MAX_UPLOAD_BYTES})`),
+      { code: 'image_too_large' },
+    );
+  }
+  const mime = CHAT_IMAGE_EXT_MIME[extname(path).toLowerCase()];
+  if (!mime) {
+    throw Object.assign(new Error(`unsupported chat attachment image type: ${path}`), { code: 'invalid_mimetype' });
+  }
+  const data = new Uint8Array(readFileSync(path));
+  return upload(data, mime);
+}
+
+// Re-host a studio-local URL or chat-attachment path on COS so a real provider
+// can fetch it; public URLs pass through. Fail loud when COS is missing.
+export async function ensureProviderReachableUrl(url: string, slug?: string): Promise<string> {
+  const filePath = chatAttachmentImagePath(url, slug);
+  if (filePath) {
+    if (!existsSync(filePath)) {
+      throw Object.assign(new Error(`chat attachment image not found: ${filePath}`), { code: 'invalid_image_url' });
+    }
+    return transferChatAttachmentImage(filePath, (data, mimetype) =>
+      uploadTransferArtifact(data, mimetype).then((r) => r.url),
+    );
+  }
+  const parsed = parseChatUploadRef(url);
+  if (parsed && !url.includes('/')) {
+    throw Object.assign(
+      new Error(`chat attachment image not found in game sessions: ${url}`),
+      { code: 'invalid_image_url' },
+    );
+  }
+  if (!isStudioLocalImageUrl(url)) return url;
+  return transferStudioLocalImage(url, {
+    baseUrl: studioBaseUrl(),
+    fetchImpl: globalThis.fetch,
+    upload: (data, mimetype) => uploadTransferArtifact(data, mimetype).then((r) => r.url),
+  });
+}
+
+export async function ensureProviderReachableUrls(
+  urls: Record<string, string>,
+  slug?: string,
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const [key, url] of Object.entries(urls)) {
+    out[key] = await ensureProviderReachableUrl(url, slug);
+  }
+  return out;
+}
+
+/** @deprecated Prefer ensureProviderReachableUrls — kept as a thin alias. */
+async function transferStudioLocalViews(
+  views: Record<string, string>,
+  slug?: string,
+): Promise<Record<string, string>> {
+  return ensureProviderReachableUrls(views, slug);
+}
+
+async function viewsTo3D(args: ViewsTo3DArgs): Promise<GenerateResult> {
+  const slug = requireSlug(args.slug);
+  const front = args.views?.front_image_url?.trim();
+  if (!front) {
+    throw Object.assign(new Error('views.front_image_url is required'), { code: 'invalid_views' });
+  }
+  const assetSlot = resolveSlot(args.assetSlot);
+  const provider = resolveProvider(args.provider);
+  if (provider === 'visvise') {
+    throw Object.assign(
+      new Error('visvise views is not on the LiteLLM catalog; use text or image'),
+      { code: 'views_not_supported' },
+    );
+  }
+  const faceCount = resolvePolycount(args.targetPolycount, provider);
+  const enablePbr = args.enablePbr ?? true;
+  const enableFbxUrl = args.enableFbxUrl ?? false;
+  const normalizedViews: Record<string, string> = {};
+  for (const [slot, url] of Object.entries(args.views)) {
+    if (url && url.trim()) normalizedViews[slot] = url.trim();
+  }
+  // cacheKey keys off the STABLE studio-local URLs, never the ephemeral COS
+  // presigned URL (which carries an expiring signature) — so an identical
+  // request still hits the cache and never re-burns quota.
+  const cacheKey = makeCacheKey(provider, 'views', {
+    assetSlot,
+    ...normalizedViews,
+    faceCount,
+    enablePbr,
+    enableFbxUrl,
+    ...(provider === 'meshy' ? { shouldTexture: true } : {}),
+    ...buildProviderParams(provider, 'views', args.providerParams).cacheBits,
+  });
+  // D-B (lazy): inputs are built ONLY on a cache MISS for the real-provider
+  // branch (runGeneration invokes this just before a real generate()), so the
+  // studio-local→COS transfer never runs on a cache hit or the mock path — no
+  // redundant fetch/upload, and a cached success can't be re-broken by a moved
+  // source image or changed COS config.
+  const buildInputs = async (): Promise<GenInputs> => {
+    const providerViews = await transferStudioLocalViews(normalizedViews, slug);
+    // Meshy multi-image takes an ordered URL array (front/back/left/right first),
+    // not Hunyuan's named view slots.
+    const meshyUrls = [
+      providerViews.front_image_url,
+      providerViews.back_image_url,
+      providerViews.left_image_url,
+      providerViews.right_image_url,
+    ].filter((u): u is string => Boolean(u));
+    const { filtered } = buildProviderParams(provider, 'views', args.providerParams);
+    const rodinPrompt = applyRodinPromptFlags('', filtered, 'views');
+    return {
+      hunyuan: {
+        mode: 'views',
+        views: providerViews as Partial<Record<ViewSlot, string>>,
+        faceCount,
+        enablePbr,
+        enableFbxUrl,
+      },
+      meshy: { mode: 'views', imageUrls: meshyUrls, targetPolycount: faceCount, enablePbr, params: filtered },
+      rodin: {
+        mode: 'views',
+        imageUrls: meshyUrls,
+        ...(rodinPrompt ? { prompt: rodinPrompt } : {}),
+      },
+      visvise: { mode: 'views' },
+    };
+  };
+  return runGeneration(
+    provider,
+    'views',
+    { slug, assetSlot, assetName: defaultName(args.assetName, `views-${provider}`), faceCount, cacheKey },
+    buildInputs,
+    null,
+  );
+}
+
+// Meshy-only second stage: add texture to a prior Meshy text `preview` task.
+// previewTaskId is the sourceJobId of a prior gen3d:text-to-3d (provider=meshy)
+// result. Produces a new durable manifest (mode='refine'). Quota-safe: falls
+// back to mock when Meshy is not configured.
+interface RefineMeshArgs {
+  slug?: string;
+  assetSlot?: AssetSlot;
+  assetName?: string;
+  previewTaskId: string;
+  texturePrompt?: string;
+  enablePbr?: boolean;
+}
+
+async function refineMesh(args: RefineMeshArgs): Promise<GenerateResult> {
+  const slug = requireSlug(args.slug);
+  const previewTaskId = args.previewTaskId?.trim();
+  if (!previewTaskId) {
+    throw Object.assign(new Error('previewTaskId is required'), { code: 'invalid_preview_task' });
+  }
+  const assetSlot = resolveSlot(args.assetSlot);
+  const enablePbr = args.enablePbr ?? true;
+  const texturePrompt = args.texturePrompt?.trim() || undefined;
+  const cacheKey = makeCacheKey('meshy', 'refine', {
+    assetSlot,
+    previewTaskId,
+    enablePbr,
+    texturePrompt: texturePrompt ?? '',
+  });
+  const ctx: PersistInput = {
+    slug,
+    assetSlot,
+    assetName: defaultName(args.assetName, `refine-${previewTaskId}`),
+    cacheKey,
+  };
+  let usedMock = false;
+  const produce = async (): Promise<ProviderResult> => {
+    const env = getMeshyEnv();
+    if (env) {
+      return new MeshyProvider({ env, slug }).generate({ mode: 'refine', previewTaskId, texturePrompt, enablePbr });
+    }
+    if (realProvidersEnabled()) throw providerNotConfigured('meshy', 'refine');
+    usedMock = true;
+    return mockFallback('meshy', 'refine', `refine:${previewTaskId}`);
+  };
+  const { manifest, cacheHit } = await generateCacheFirst(storage, ctx, produce);
+  return { ok: true, cacheKey, cacheHit, usedMock: cacheHit ? manifest.providerMode === 'mock' : usedMock, manifest };
+}
+
+// Hunyuan REST sub-capability: pose_standardization. This is an UPSTREAM
+// preprocessing tool (image → standardized portrait image), not 3D generation.
+// It does NOT produce a Gen3DAssetManifest. The output image is persisted as a
+// scratch (transfer) artifact under the game's .gen3d/tmp/ — never the asset
+// library (CONTEXT.md "临时/中转产物"). Quota-safe by default: with no real
+// provider configured it falls back to a deterministic mock image.
+
+interface PoseStandardizationArgs {
+  slug?: string;
+  imageUrl: string;
+  footnote?: string;
+  provider?: 'hunyuan_rest' | 'visvise';
+}
+
+interface PoseStandardizationResult {
+  ok: true;
+  usedMock: boolean;
+  sourceJobId: string | null;
+  // The standardized image as a scratch artifact (NOT an asset; no manifest).
+  // Use storageKey as the upstream input for a subsequent gen3d:image-to-3d.
+  storageKey: string;
+  bytes: number;
+  sha256: string;
+  localUrl: string | null;
+  sourceUrl: string | null;
+}
+
+async function poseStandardization(
+  args: PoseStandardizationArgs,
+): Promise<PoseStandardizationResult> {
+  const slug = requireSlug(args.slug);
+  const imageUrl = args.imageUrl?.trim();
+  if (!imageUrl) {
+    throw Object.assign(new Error('imageUrl is required'), { code: 'invalid_image_url' });
+  }
+  const footnote = args.footnote?.trim() || undefined;
+  const poseProvider = args.provider === 'visvise' ? 'visvise' : 'hunyuan_rest';
+
+  let imageData: Uint8Array;
+  let sourceJobId: string | null;
+  let sourceUrl: string | null;
+  let usedMock: boolean;
+
+  if (poseProvider === 'visvise') {
+    const visviseEnv = getVisviseEnv();
+    if (visviseEnv) {
+      const reachable = await ensureProviderReachableUrl(imageUrl, slug);
+      const result = await new VisviseProvider({ env: visviseEnv, slug }).pose({ inputModelUrl: reachable });
+      imageData = result.imageData;
+      sourceJobId = result.sourceJobId;
+      sourceUrl = result.sourceUrl;
+      usedMock = false;
+    } else {
+      if (realProvidersEnabled()) throw providerNotConfigured('visvise', 'pose-standardization');
+      const { result } = generateMeshyTextMockResult({ prompt: `pose-visvise:${imageUrl}` });
+      const preview = result.files.find((f) => f.role === 'preview_image');
+      imageData = preview?.data ?? new Uint8Array();
+      sourceJobId = null;
+      sourceUrl = null;
+      usedMock = true;
+    }
+  } else {
+  const env = getHunyuanEnv();
+
+  if (env) {
+    const reachable = await ensureProviderReachableUrl(imageUrl, slug);
+    const provider = new HunyuanRestProvider({ env, slug });
+    const result = await provider.poseStandardization({ imageUrl: reachable, footnote });
+    imageData = result.imageData;
+    sourceJobId = result.sourceJobId;
+    sourceUrl = result.sourceUrl;
+    usedMock = false;
+  } else {
+    if (realProvidersEnabled()) throw providerNotConfigured('hunyuan_rest', 'pose-standardization');
+    // Deterministic no-quota fallback: reuse the mock preview image bytes so the
+    // storage path runs without a network call.
+    const { result } = generateMeshyTextMockResult({ prompt: `pose:${imageUrl}` });
+    const preview = result.files.find((f) => f.role === 'preview_image');
+    imageData = preview?.data ?? new Uint8Array();
+    sourceJobId = null;
+    sourceUrl = null;
+    usedMock = true;
+  }
+  }
+
+  const stored = await storage.putScratch({ slug, data: imageData, format: 'png' });
+  return {
+    ok: true,
+    usedMock,
+    sourceJobId,
+    storageKey: stored.storageKey,
+    bytes: stored.bytes,
+    sha256: stored.sha256,
+    localUrl: stored.localUrl,
+    sourceUrl,
+  };
+}
+
+// Local image upload (transfer artifact, NOT an asset). Decodes a base64 image
+// and hosts it on COS so URL-fetching providers (Hunyuan/Meshy) can reach a
+// user's local file; the result URL is fed into image/views/pose tools. Rodin
+// takes bytes directly and does not need this. base64 rides the existing JSON
+// tools route (no extra server route); the decoded image is hard-capped at 8MB
+// so an oversized upload can't exhaust server memory.
+
+const MAX_UPLOAD_BYTES = 8 * 1024 * 1024;
+const ALLOWED_UPLOAD_MIMES = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/jpg',
+  'image/webp',
+  'image/gif',
+]);
+
+interface UploadImageArgs {
+  // Raw base64 (no data: prefix) of the image bytes.
+  base64: string;
+  mimetype: string;
+}
+
+interface UploadImageResult {
+  ok: true;
+  url: string;
+  bytes: number;
+  sha256: string;
+  expiresInSec: number;
+}
+
+function decodeBase64(raw: string): Uint8Array {
+  // Tolerate an accidental data: URL prefix the UI might pass.
+  const comma = raw.indexOf(',');
+  const b64 = raw.startsWith('data:') && comma !== -1 ? raw.slice(comma + 1) : raw;
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+
+async function uploadImage(args: UploadImageArgs): Promise<UploadImageResult> {
+  const mimetype = args.mimetype?.trim().toLowerCase();
+  if (!mimetype || !ALLOWED_UPLOAD_MIMES.has(mimetype)) {
+    throw Object.assign(new Error(`unsupported image mimetype ${JSON.stringify(args.mimetype)}`), {
+      code: 'invalid_mimetype',
+    });
+  }
+  if (!args.base64 || typeof args.base64 !== 'string') {
+    throw Object.assign(new Error('base64 image data is required'), { code: 'invalid_base64' });
+  }
+  const data = decodeBase64(args.base64);
+  if (data.byteLength === 0) {
+    throw Object.assign(new Error('decoded image is empty'), { code: 'invalid_base64' });
+  }
+  if (data.byteLength > MAX_UPLOAD_BYTES) {
+    throw Object.assign(
+      new Error(`image too large: ${data.byteLength} bytes (max ${MAX_UPLOAD_BYTES})`),
+      { code: 'image_too_large' },
+    );
+  }
+  const result = await uploadTransferArtifact(data, mimetype);
+  return { ok: true, ...result };
+}
+
+const MAX_VIDEO_BYTES = 100 * 1024 * 1024;
+const ALLOWED_VIDEO_MIMES = new Set(['video/mp4', 'video/webm']);
+
+interface UploadVideoArgs {
+  mimetype: string;
+}
+
+interface UploadVideoResult {
+  ok: true;
+  uploadUrl: string;
+  publicUrl: string;
+  expiresInSec: number;
+  maxBytes: number;
+}
+
+async function uploadVideo(args: UploadVideoArgs): Promise<UploadVideoResult> {
+  const mimetype = args.mimetype?.trim().toLowerCase();
+  if (!mimetype || !ALLOWED_VIDEO_MIMES.has(mimetype)) {
+    throw Object.assign(new Error(`unsupported video mimetype ${JSON.stringify(args.mimetype)}`), {
+      code: 'invalid_mimetype',
+    });
+  }
+  const env = getCosEnv();
+  if (!env) {
+    throw Object.assign(new Error('COS upload is not configured; paste a video URL instead'), {
+      code: 'cos_not_configured',
+    });
+  }
+  const signed = await new CosUploader(env).presignPut(mimetype);
+  return {
+    ok: true,
+    uploadUrl: signed.uploadUrl,
+    publicUrl: signed.publicUrl,
+    expiresInSec: signed.expiresInSec,
+    maxBytes: MAX_VIDEO_BYTES,
+  };
+}
+
+// ─── M13: rig / motion / low_poly (mock-first; ADR-0009) ────────────────────
+//
+// Core pipeline: textured high-poly GLB → auto-rig → apply-motion.
+// rig/motion append GLB (canonical) + FBX (motion transport) to the SAME mesh
+// asset and flip readiness; low_poly is an optional geometry/LOD side-branch.
+//
+// Provider dispatch (ADR-0009):
+//   • auto-rig auto = Hunyuan REST → VISVISE → mock. Meshy is explicit-only.
+//   • apply-motion follows the asset's recorded rig.rigProvider.
+//   • With neither configured, deterministic placeholder bytes exercise the
+//     storage path with zero quota (mock).
+// Meshy animation MUST be driven by Meshy's own rig_task_id (not an external
+// FBX), so apply-motion dispatches strictly by the asset's recorded rig system
+// (manifest.rig.rigProvider) and reads rig.rigTaskId. rig_task_id + signed URLs
+// expire ~3 days → rig_expired is reported unless autoReRig is set (PLAN §8-Q3).
+// exposedToAI stays false until operator real-machine verification (PLAN §5 P3).
+
+// Deterministic placeholder model bytes (GLB magic header). Stand-in so the
+// rig/motion/low_poly append + persist paths run end-to-end without quota.
+function mockModelBytes(seed: string): Uint8Array {
+  const header = new Uint8Array([0x67, 0x6c, 0x54, 0x46, 0x02, 0x00, 0x00, 0x00]);
+  const tail = new TextEncoder().encode(`mock-model:${seed}`);
+  const out = new Uint8Array(header.length + tail.length);
+  out.set(header, 0);
+  out.set(tail, header.length);
+  return out;
+}
+
+// Share an asset file (already on disk) as a public COS transfer URL so the
+// URL-fetching Hunyuan REST endpoint can read it. Returns null when COS is not
+// configured (caller then falls back to mock). The file is read from the store,
+// never assumed to be a reachable provider URL (ADR-0001).
+async function shareAssetFileUrl(
+  slug: string,
+  assetPath: string,
+  role: 'source_mesh' | 'rigged_model',
+  format: 'glb' | 'fbx',
+): Promise<string | null> {
+  const file = await storage.readAssetFile(slug, assetPath, role, format);
+  if (!file) {
+    throw Object.assign(
+      new Error(`asset has no ${role} ${format} file: ${assetPath}`),
+      { code: 'missing_input_file' },
+    );
+  }
+  try {
+    const { url } = await uploadTransferArtifact(file.data, mimeForModelFormat(format));
+    return url;
+  } catch (error) {
+    if ((error as { code?: unknown } | null)?.code === 'cos_not_configured') return null;
+    throw error;
+  }
+}
+
+interface AutoRigArgs {
+  slug?: string;
+  assetPath: string;
+  /** auto | meshy | hunyuan_rest | visvise — explicit force never falls back to the other route. */
+  rigProvider?: 'auto' | 'meshy' | 'hunyuan_rest' | 'visvise';
+  /**
+   * When true and the asset is already rigged: strip rigged_model + animated_model
+   * (+ custom.rig), then re-run the chosen route (burns fresh credits). Default
+   * false keeps the historical idempotent no-op.
+   */
+  force?: boolean;
+  /** Meshy-only: approximate character height (m). Omit → upstream default ~1.7. */
+  heightMeters?: number;
+}
+
+function parseHeightMeters(raw: number | undefined): number | undefined {
+  if (raw === undefined || !Number.isFinite(raw)) return undefined;
+  if (raw < 0.1 || raw > 5) {
+    throw Object.assign(new Error('heightMeters must be between 0.1 and 5'), {
+      code: 'invalid_height_meters',
+    });
+  }
+  return raw;
+}
+
+interface RigMotionResult {
+  ok: true;
+  usedMock: boolean;
+  assetPath: string;
+  manifest: Gen3DAssetManifest;
+}
+
+// A free walk/run clip bundled in a Meshy rig result (reserved ids, isFree).
+function freeMotionRef(category: 'walking' | 'running'): MotionRef {
+  return category === 'walking'
+    ? { system: 'meshy', id: MESHY_FREE_WALK_ID, label: '走路（免费）' }
+    : { system: 'meshy', id: MESHY_FREE_RUN_ID, label: '跑步（免费）' };
+}
+
+const HUMANOID_SKELETON = {
+  hasSkeleton: true,
+  skeletonProfile: 'humanoid' as const,
+  animationInputReady: true,
+};
+
+// Meshy credit costs per paid call (ADR-0006): rig ~5, animation ~3.
+export const MESHY_RIG_COST = 5;
+export const MESHY_ANIM_COST = 3;
+
+// Proactive balance pre-check before a paid Meshy rig/animation call (ADR-0006 /
+// ADR-0008 D-E). Meshy also rejects 402 → provider_insufficient_credits
+// reactively, but pre-checking lets the agent get a clear quote (needed vs
+// available) BEFORE any spend instead of discovering it mid-dispatch.
+export async function assertMeshyBalance(
+  provider: { getBalance(): Promise<number | null> },
+  needed: number,
+  op: string,
+): Promise<void> {
+  const balance = await provider.getBalance();
+  // Gateway has no balance endpoint — skip pre-check; 402 is handled reactively.
+  if (balance === null) return;
+  if (balance < needed) {
+    throw Object.assign(
+      new Error(`${op} needs ~${needed} Meshy credits but the balance is ${balance}; top up or skip the motion step`),
+      { code: 'provider_insufficient_credits', needed, balance },
+    );
+  }
+}
+
+// Meshy auto-rig: LiteLLM gateway requires `model_url` (input_task_id alone → HTTP 500
+// "Missing required parameter model_url"). Always COS-share the source GLB; optionally
+// also pass Meshy result task id. Then append rigged GLB+FBX + free walk/run clips.
+async function meshyRigAppend(
+  slug: string,
+  asset: Gen3DAssetManifest,
+  provider: MeshyProvider,
+  heightMeters?: number,
+): Promise<Gen3DAssetManifest> {
+  const modelUrl = await shareAssetFileUrl(slug, asset.assetPath, 'source_mesh', 'glb');
+  // Prefer the final textured mesh task (result), never the white-mesh preview.
+  const meshTaskId =
+    asset.meshyTaskRefs?.resultTaskId ??
+    (asset.provider === 'meshy' ? asset.sourceJobId : null);
+  const inputTaskId =
+    asset.provider === 'meshy' && meshTaskId && !meshTaskId.startsWith('mock') ? meshTaskId : undefined;
+  if (!modelUrl) {
+    throw Object.assign(
+      new Error('Meshy auto-rig needs COS configured to share model_url (gateway rejects input_task_id-only)'),
+      { code: 'cos_not_configured' },
+    );
+  }
+  const rig = await provider.rig({
+    modelUrl,
+    ...(inputTaskId ? { inputTaskId } : {}),
+    ...(heightMeters !== undefined ? { heightMeters } : {}),
+  });
+  const files: DerivedFileInput[] = [{ data: rig.glb, format: 'glb', role: 'rigged_model' }];
+  if (rig.fbx) files.push({ data: rig.fbx, format: 'fbx', role: 'rigged_model' });
+  for (const ba of rig.basicAnimations) {
+    const ref = freeMotionRef(ba.category);
+    files.push({ data: ba.glb, format: 'glb', role: 'animated_model', motionRef: ref });
+    if (ba.fbx) files.push({ data: ba.fbx, format: 'fbx', role: 'animated_model', motionRef: ref });
+  }
+  return storage.appendDerivedFiles({
+    slug,
+    assetPath: asset.assetPath,
+    files,
+    skeleton: HUMANOID_SKELETON,
+    rigChain: {
+      rigProvider: 'meshy',
+      rigTaskId: rig.sourceJobId,
+      rigType: rig.rigType,
+      rigExpiresAt: rig.expiresAt,
+    },
+  });
+}
+
+async function hunyuanRigAppend(
+  slug: string,
+  assetPath: string,
+  hunyuanEnv: NonNullable<ReturnType<typeof getHunyuanEnv>>,
+): Promise<Gen3DAssetManifest> {
+  const glbUrl = await shareAssetFileUrl(slug, assetPath, 'source_mesh', 'glb');
+  if (!glbUrl) {
+    throw Object.assign(new Error('auto-rig needs COS configured to share the input model URL'), {
+      code: 'cos_not_configured',
+    });
+  }
+  const files: ModelFileOut[] = (await new HunyuanRestProvider({ env: hunyuanEnv, slug }).autoRig({ glbUrl })).files;
+  const derived: DerivedFileInput[] = files.map((f) => ({ data: f.data, format: f.format, role: 'rigged_model' }));
+  return storage.appendDerivedFiles({
+    slug,
+    assetPath,
+    files: derived,
+    skeleton: HUMANOID_SKELETON,
+    rigChain: { rigProvider: 'hunyuan_rest', rigTaskId: null, rigType: null, rigExpiresAt: null },
+  });
+}
+
+async function visviseRigAppend(
+  slug: string,
+  asset: Gen3DAssetManifest,
+  visviseEnv: NonNullable<ReturnType<typeof getVisviseEnv>>,
+): Promise<Gen3DAssetManifest> {
+  const assetPath = asset.assetPath;
+  const inputModelUrl =
+    visviseInputUrl(asset.visviseRefs, 'rig') ??
+    (await shareAssetFileUrl(slug, assetPath, 'source_mesh', 'glb'));
+  if (!inputModelUrl) {
+    throw Object.assign(new Error('auto-rig needs a VISVISE mesh URL (or COS to share the local GLB)'), {
+      code: 'cos_not_configured',
+    });
+  }
+  const out = await new VisviseProvider({ env: visviseEnv, slug }).autoRig({ inputModelUrl });
+  const derived: DerivedFileInput[] = out.files.map((f) => ({ data: f.data, format: f.format, role: 'rigged_model' }));
+  return storage.appendDerivedFiles({
+    slug,
+    assetPath,
+    files: derived,
+    skeleton: HUMANOID_SKELETON,
+    rigChain: { rigProvider: 'visvise', rigTaskId: null, rigType: null, rigExpiresAt: null },
+    visviseRefs: {
+      meshUrl: asset.visviseRefs?.meshUrl ?? null,
+      rigUrl: out.sourceUrl,
+    },
+  });
+}
+
+function defaultAutoRigRoute(asset: Gen3DAssetManifest): 'hunyuan_rest' | 'visvise' {
+  if (asset.provider === 'visvise' || asset.provider === 'rodin') return 'visvise';
+  return 'hunyuan_rest';
+}
+
+// gen3d:auto-rig — append a rigged_model GLB (canonical) + FBX (motion transport)
+// to a textured mesh asset and set skeleton flags. Humanoid only (characters
+// slot, soft-gated in the UI/schema). Idempotent by default: if already rigged,
+// returns the existing manifest without burning quota. Pass force=true to strip
+// prior rig+motions and re-run (new credits; optional provider switch).
+// Dispatch (ADR-0009):
+//   rigProvider=auto           → Hunyuan if configured, else VISVISE, else mock
+//   explicit meshy|hunyuan_rest|visvise → that route; missing env → provider_not_configured
+async function autoRig(args: AutoRigArgs): Promise<RigMotionResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) {
+    throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  }
+  let existing = await storage.getAsset(slug, assetPath);
+  if (!existing) {
+    throw Object.assign(new Error(`asset not found: ${assetPath}`), { code: 'asset_not_found' });
+  }
+  // Idempotent: a verified rigged_model already present → return as-is unless force.
+  if (existing.readiness.rigged) {
+    if (!args.force) {
+      return { ok: true, usedMock: existing.providerMode === 'mock', assetPath, manifest: existing };
+    }
+    existing = await storage.clearRigAndMotions(slug, assetPath);
+  }
+
+  const route = args.rigProvider ?? 'auto';
+  const heightMeters = parseHeightMeters(args.heightMeters);
+  const meshyEnv = getMeshyEnv();
+  const hunyuanEnv = getHunyuanEnv();
+  const visviseEnv = getVisviseEnv();
+
+  if (route === 'meshy') {
+    if (!meshyEnv) throw providerNotConfigured('meshy', 'auto-rig');
+    const provider = new MeshyProvider({ env: meshyEnv, slug });
+    await assertMeshyBalance(provider, MESHY_RIG_COST, 'auto-rig');
+    const manifest = await meshyRigAppend(slug, existing, provider, heightMeters);
+    return { ok: true, usedMock: false, assetPath, manifest };
+  }
+
+  if (route === 'hunyuan_rest') {
+    if (!hunyuanEnv) throw providerNotConfigured('hunyuan_rest', 'auto-rig');
+    const manifest = await hunyuanRigAppend(slug, assetPath, hunyuanEnv);
+    return { ok: true, usedMock: false, assetPath, manifest };
+  }
+
+  if (route === 'visvise') {
+    if (!visviseEnv) throw providerNotConfigured('visvise', 'auto-rig');
+    const manifest = await visviseRigAppend(slug, existing, visviseEnv);
+    return { ok: true, usedMock: false, assetPath, manifest };
+  }
+
+  // auto: Hunyuan → VISVISE → mock. Meshy is no longer first (ADR-0009).
+  if (hunyuanEnv) {
+    const manifest = await hunyuanRigAppend(slug, assetPath, hunyuanEnv);
+    return { ok: true, usedMock: false, assetPath, manifest };
+  }
+  if (visviseEnv) {
+    const manifest = await visviseRigAppend(slug, existing, visviseEnv);
+    return { ok: true, usedMock: false, assetPath, manifest };
+  }
+
+  if (realProvidersEnabled()) throw providerNotConfigured('hunyuan_rest', 'auto-rig');
+
+  const mockRoute = defaultAutoRigRoute(existing);
+  const files: DerivedFileInput[] = [
+    { data: mockModelBytes(`rig-glb:${assetPath}`), format: 'glb', role: 'rigged_model' },
+    { data: mockModelBytes(`rig-fbx:${assetPath}`), format: 'fbx', role: 'rigged_model' },
+  ];
+  const manifest = await storage.appendDerivedFiles({
+    slug,
+    assetPath,
+    files,
+    skeleton: HUMANOID_SKELETON,
+    rigChain: { rigProvider: mockRoute, rigTaskId: `mock-rig:${assetPath}`, rigType: 'mock', rigExpiresAt: null },
+  });
+  return { ok: true, usedMock: true, assetPath, manifest };
+}
+
+interface ApplyMotionArgs {
+  slug?: string;
+  assetPath: string;
+  // Meshy path: the action_id from gen3d:list-motions (positive integer).
+  actionId?: number;
+  // Hunyuan dev path: the v1 fixed motion (int 9–16).
+  motionType?: number;
+  // VISVISE: text-motion prompt XOR video-motion URL.
+  prompt?: string;
+  videoUrl?: string;
+  // Optional display label (the UI passes the action name it showed); the
+  // catalog is not re-queried here. Falls back to "动作 <id>".
+  label?: string;
+  // When the Meshy rig task is stale (expired ~3 days, or mock), re-rig
+  // (+credits) instead of erroring with rig_expired. Default false (PLAN §8-Q3).
+  autoReRig?: boolean;
+}
+
+const VALID_MOTION_TYPES: readonly MotionType[] = [9, 10, 11, 12, 13, 14, 15, 16];
+
+function asMotionType(value: number | undefined): MotionType {
+  if (value === undefined || !VALID_MOTION_TYPES.includes(value as MotionType)) {
+    throw Object.assign(new Error(`motionType must be an int 9–16, got ${value}`), {
+      code: 'invalid_motion_type',
+    });
+  }
+  return value as MotionType;
+}
+
+// Real Meshy action ids are positive; reserved negatives are internal (bundled
+// free clips) and must not be requested directly through apply-motion.
+function asActionId(value: number | undefined): number {
+  if (value === undefined || !Number.isInteger(value) || value <= 0) {
+    throw Object.assign(new Error(`actionId must be a positive integer, got ${value}`), {
+      code: 'invalid_action_id',
+    });
+  }
+  return value;
+}
+
+// Has this exact motion already been applied? (idempotency, by structural key.)
+function hasMotion(asset: Gen3DAssetManifest, ref: MotionRef): boolean {
+  const key = motionRefKey(ref);
+  return selectFiles(asset.files, 'animated_model').some(
+    (f) => f.motionRef !== undefined && motionRefKey(f.motionRef) === key,
+  );
+}
+
+// A Meshy rig task is stale when it expired (~3 days) or was only mock-rigged —
+// either way it cannot drive a real /animations call.
+function meshyRigStale(rig: RigChain | undefined): boolean {
+  if (!rig || !rig.rigTaskId) return true;
+  if (rig.rigTaskId.startsWith('mock')) return true;
+  return rig.rigExpiresAt !== null && Date.now() > rig.rigExpiresAt;
+}
+
+// gen3d:apply-motion — append an animated_model GLB (canonical) + FBX for one
+// motion to a RIGGED asset, flipping readiness.animated. Dispatches strictly by
+// the asset's recorded rig system (ADR-0006 §8-Q4): Meshy uses rig.rigTaskId +
+// actionId; Hunyuan uses the rigged FBX + motionType. Multiple motions coexist;
+// idempotent per motion. Requires a prior auto-rig (else not_rigged).
+async function applyMotion(args: ApplyMotionArgs): Promise<RigMotionResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) {
+    throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  }
+  const existing = await storage.getAsset(slug, assetPath);
+  if (!existing) {
+    throw Object.assign(new Error(`asset not found: ${assetPath}`), { code: 'asset_not_found' });
+  }
+  if (!existing.readiness.rigged) {
+    throw Object.assign(new Error('asset is not rigged; run gen3d:auto-rig first'), {
+      code: 'not_rigged',
+    });
+  }
+
+  const rigProvider = existing.rig?.rigProvider ?? 'meshy';
+
+  if (rigProvider === 'visvise') {
+    const prompt = args.prompt?.trim();
+    const videoUrl = args.videoUrl?.trim();
+    if (!prompt && !videoUrl) {
+      throw Object.assign(new Error('VISVISE apply-motion requires prompt or videoUrl'), {
+        code: 'invalid_motion_input',
+      });
+    }
+    if (prompt && videoUrl) {
+      throw Object.assign(new Error('VISVISE apply-motion accepts prompt or videoUrl, not both'), {
+        code: 'invalid_motion_input',
+      });
+    }
+    const ref: MotionRef = prompt
+      ? { system: 'visvise', id: `text:${prompt}`, label: args.label?.trim() || prompt }
+      : { system: 'visvise', id: `video:${videoUrl}`, label: args.label?.trim() || 'video-motion' };
+    if (hasMotion(existing, ref)) {
+      return { ok: true, usedMock: existing.providerMode === 'mock', assetPath, manifest: existing };
+    }
+    const visviseEnv = getVisviseEnv();
+    let files: ModelFileOut[];
+    let usedMock: boolean;
+    if (visviseEnv) {
+      const inputModelUrl =
+        visviseInputUrl(existing.visviseRefs, 'motion') ??
+        (await shareAssetFileUrl(slug, assetPath, 'rigged_model', 'glb'));
+      if (!inputModelUrl) {
+        throw Object.assign(new Error('apply-motion needs a VISVISE rig URL (or COS to share the local GLB)'), {
+          code: 'cos_not_configured',
+        });
+      }
+      const provider = new VisviseProvider({ env: visviseEnv, slug });
+      const out = prompt
+        ? await provider.textMotion({ inputModelUrl, prompt })
+        : await provider.videoMotion({ inputModelUrl, videoUrl });
+      files = out.files;
+      usedMock = false;
+    } else {
+      if (realProvidersEnabled()) throw providerNotConfigured('visvise', 'apply-motion');
+      files = [
+        { format: 'glb', data: mockModelBytes(`motion-visvise-glb:${assetPath}:${ref.id}`) },
+        { format: 'fbx', data: mockModelBytes(`motion-visvise-fbx:${assetPath}:${ref.id}`) },
+      ];
+      usedMock = true;
+    }
+    const derived: DerivedFileInput[] = files.map((f) => ({
+      data: f.data,
+      format: f.format,
+      role: 'animated_model',
+      motionRef: ref,
+    }));
+    const manifest = await storage.appendDerivedFiles({ slug, assetPath, files: derived });
+    return { ok: true, usedMock, assetPath, manifest };
+  }
+
+  // ── Hunyuan dev path (internal): fixed motion int 9–16 via the rigged FBX. ──
+  if (rigProvider === 'hunyuan_rest') {
+    const motionType = asMotionType(args.motionType);
+    const ref = motionRefFromLegacy(motionType);
+    if (hasMotion(existing, ref)) {
+      return { ok: true, usedMock: existing.providerMode === 'mock', assetPath, manifest: existing };
+    }
+    const env = getHunyuanEnv();
+    let files: ModelFileOut[];
+    let usedMock: boolean;
+    if (env) {
+      const fbxUrl = await shareAssetFileUrl(slug, assetPath, 'rigged_model', 'fbx');
+      if (!fbxUrl) {
+        throw Object.assign(new Error('apply-motion needs COS configured to share the rigged FBX URL'), {
+          code: 'cos_not_configured',
+        });
+      }
+      files = (await new HunyuanRestProvider({ env, slug }).applyMotion({ fbxUrl, motionType })).files;
+      usedMock = false;
+    } else {
+      if (realProvidersEnabled()) throw providerNotConfigured('hunyuan_rest', 'apply-motion');
+      files = [
+        { format: 'glb', data: mockModelBytes(`motion-${motionType}-glb:${assetPath}`) },
+        { format: 'fbx', data: mockModelBytes(`motion-${motionType}-fbx:${assetPath}`) },
+      ];
+      usedMock = true;
+    }
+    const derived: DerivedFileInput[] = files.map((f) => ({
+      data: f.data,
+      format: f.format,
+      role: 'animated_model',
+      motionRef: ref,
+    }));
+    const manifest = await storage.appendDerivedFiles({ slug, assetPath, files: derived });
+    return { ok: true, usedMock, assetPath, manifest };
+  }
+
+  // ── Meshy public path (default): actionId via Meshy's own rig_task_id. ──
+  const actionId = asActionId(args.actionId);
+  const ref: MotionRef = { system: 'meshy', id: actionId, label: args.label?.trim() || `动作 ${actionId}` };
+  if (hasMotion(existing, ref)) {
+    return { ok: true, usedMock: existing.providerMode === 'mock', assetPath, manifest: existing };
+  }
+
+  const env = getMeshyEnv();
+  if (!env) {
+    if (realProvidersEnabled()) throw providerNotConfigured('meshy', 'apply-motion');
+    // Mock: no key → deterministic placeholder clip, zero quota.
+    const files: DerivedFileInput[] = [
+      { data: mockModelBytes(`motion-meshy-${actionId}-glb:${assetPath}`), format: 'glb', role: 'animated_model', motionRef: ref },
+      { data: mockModelBytes(`motion-meshy-${actionId}-fbx:${assetPath}`), format: 'fbx', role: 'animated_model', motionRef: ref },
+    ];
+    const manifest = await storage.appendDerivedFiles({ slug, assetPath, files });
+    return { ok: true, usedMock: true, assetPath, manifest };
+  }
+
+  // Real Meshy: the animation input is the rig task id, NOT a local FBX. If that
+  // task is stale, re-rig only when autoReRig is set; else report rig_expired so
+  // the caller decides (PLAN §8-Q3).
+  const provider = new MeshyProvider({ env, slug });
+  let asset = existing;
+  const willReRig = meshyRigStale(asset.rig);
+  if (willReRig && !args.autoReRig) {
+    throw Object.assign(
+      new Error('Meshy rig task expired (~3 days); re-run gen3d:auto-rig or pass autoReRig:true'),
+      { code: 'rig_expired' },
+    );
+  }
+  // Pre-check the total spend before any paid call: a re-rig adds the rig cost on
+  // top of the animation (ADR-0006 / ADR-0008 D-E).
+  await assertMeshyBalance(provider, (willReRig ? MESHY_RIG_COST : 0) + MESHY_ANIM_COST, 'apply-motion');
+  if (willReRig) {
+    asset = await meshyRigAppend(slug, asset, provider);
+  }
+  const rigTaskId = asset.rig?.rigTaskId;
+  if (!rigTaskId) {
+    throw Object.assign(new Error('asset has no Meshy rig task id; re-run gen3d:auto-rig'), {
+      code: 'rig_expired',
+    });
+  }
+  const out = await provider.animate({ rigTaskId, actionId });
+  const files: DerivedFileInput[] = [{ data: out.glb, format: 'glb', role: 'animated_model', motionRef: ref }];
+  if (out.fbx) files.push({ data: out.fbx, format: 'fbx', role: 'animated_model', motionRef: ref });
+  const manifest = await storage.appendDerivedFiles({ slug, assetPath, files });
+  return { ok: true, usedMock: false, assetPath, manifest };
+}
+
+// gen3d:list-motions — two-step motion discovery (PLAN §8-Q1b). Returns a
+// filtered slice of the motion catalog for the asset's rig system (Hunyuan →
+// the v1 fixed set; Meshy → the public catalog). Zero credits (a GET);
+// quota-safe mock sample when Meshy is not configured. The AI schema never
+// enumerates the ~680 actions — callers narrow via query/category/rigType.
+interface ListMotionsArgs {
+  slug?: string;
+  assetPath?: string;
+  query?: string;
+  category?: string;
+  rigType?: string;
+}
+
+interface ListMotionsResult {
+  ok: true;
+  usedMock: boolean;
+  system: MotionSystem;
+  total: number;
+  motions: MotionOption[];
+}
+
+async function listMotions(args: ListMotionsArgs = {}): Promise<ListMotionsResult> {
+  const slug = requireSlug(args.slug);
+  let system: MotionSystem = 'meshy';
+  const path = args.assetPath?.trim();
+  if (path) {
+    const asset = await storage.getAsset(slug, path);
+    if (asset?.rig?.rigProvider === 'hunyuan_rest') system = 'hunyuan_v1';
+    if (asset?.rig?.rigProvider === 'visvise') system = 'visvise';
+  }
+  const filter = { query: args.query, category: args.category, rigType: args.rigType };
+  if (system === 'hunyuan_v1') {
+    const motions = filterMotions(hunyuanV1Catalog(), filter);
+    return { ok: true, usedMock: false, system, total: motions.length, motions };
+  }
+  if (system === 'visvise') {
+    const motions = filterMotions(visviseCatalog(), filter);
+    return { ok: true, usedMock: false, system, total: motions.length, motions };
+  }
+  if (realProvidersEnabled() && !getMeshyEnv()) {
+    throw providerNotConfigured('meshy', 'list-motions');
+  }
+  const { usedMock, options } = await getMeshyCatalog(slug);
+  const motions = filterMotions(options, filter);
+  return { ok: true, usedMock, system: 'meshy', total: motions.length, motions };
+}
+
+interface RetopoLowpolyArgs {
+  slug?: string;
+  assetPath: string;
+  assetName?: string;
+  assetSlot?: AssetSlot;
+  polygonType?: 'triangle' | 'quadrilateral';
+  detailLevel?: 'high' | 'medium' | 'low';
+}
+
+// gen3d:retopo-lowpoly — OPTIONAL geometry/LOD side-branch (NOT a pre-rig step;
+// textures are NOT preserved). Produces a NEW derived low-poly GLB asset from a
+// high-poly source; the high-poly source is retained. cache-first + mock fallback.
+async function retopoLowpoly(args: RetopoLowpolyArgs): Promise<GenerateResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) {
+    throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  }
+  const source = await storage.getAsset(slug, assetPath);
+  if (!source) {
+    throw Object.assign(new Error(`asset not found: ${assetPath}`), { code: 'asset_not_found' });
+  }
+  const assetSlot = resolveSlot(args.assetSlot ?? source.assetSlot);
+  const polygonType = args.polygonType ?? 'quadrilateral';
+  const detailLevel = args.detailLevel ?? 'high';
+  const sourceHash = source.files.find((f) => f.role === 'source_mesh')?.sha256 ?? assetPath;
+  const cacheKey = makeCacheKey('hunyuan_rest', 'image', {
+    op: 'lowpoly',
+    assetSlot,
+    inputHash: sourceHash,
+    polygonType,
+    detailLevel,
+  });
+  const baseName = source.assetPath
+    .replace(/^assets\/3d\/[^/]+\//, '')
+    .replace(/\.glb$/, '');
+  const ctx: PersistInput = {
+    slug,
+    assetSlot,
+    assetName: defaultName(args.assetName, `${baseName}-lowpoly`),
+    cacheKey,
+    sourceInputAssetPaths: [assetPath],
+  };
+
+  let usedMock = false;
+  const produce = async (): Promise<ProviderResult> => {
+    const env = getHunyuanEnv();
+    if (env) {
+      const glbUrl = await shareAssetFileUrl(slug, assetPath, 'source_mesh', 'glb');
+      if (!glbUrl) {
+        throw Object.assign(
+          new Error('retopo-lowpoly needs COS configured to share the input model URL'),
+          { code: 'cos_not_configured' },
+        );
+      }
+      const out = await new HunyuanRestProvider({ env, slug }).lowPoly({
+        glbUrl,
+        polygonType,
+        detailLevel,
+      });
+      const files: ProviderResult['files'] = [
+        { role: 'source_mesh', format: 'glb', data: out.glb },
+      ];
+      if (out.previewImage) {
+        files.push({ role: 'preview_image', format: 'png', data: out.previewImage });
+      }
+      return {
+        provider: 'hunyuan_rest',
+        mode: 'image',
+        providerMode: 'real',
+        sourceJobId: out.sourceJobId,
+        prompt: source.prompt,
+        files,
+      };
+    }
+    if (realProvidersEnabled()) throw providerNotConfigured('hunyuan_rest', 'retopo-lowpoly');
+    usedMock = true;
+    return {
+      provider: 'hunyuan_rest',
+      mode: 'image',
+      providerMode: 'mock',
+      sourceJobId: null,
+      prompt: source.prompt,
+      files: [{ role: 'source_mesh', format: 'glb', data: mockModelBytes(`lowpoly:${assetPath}`) }],
+    };
+  };
+  const { manifest, cacheHit } = await generateCacheFirst(storage, ctx, produce);
+  return { ok: true, cacheKey, cacheHit, usedMock: cacheHit ? manifest.providerMode === 'mock' : usedMock, manifest };
+}
+
+// ─── Quality scoring (ADR-0004, P3) ─────────────────────────────────────────
+
+type DimKey = 'geometry' | 'topology' | 'texture' | 'pbr' | 'prompt_fidelity';
+
+interface ScoreQualityArgs {
+  slug?: string;
+  assetPath: string;
+  objective?: Partial<Record<'geometry' | 'topology' | 'texture' | 'pbr', number | null>>;
+  aiPass?: boolean;
+  manual?: Partial<Record<DimKey, number | null>> & { notes?: string };
+}
+
+interface ScoreQualityResult {
+  ok: true;
+  usedMock: boolean;
+  manifest: Gen3DAssetManifest;
+}
+
+function clampScore(v: number | null | undefined): number | null {
+  if (v === null || v === undefined || !Number.isFinite(v)) return null;
+  return Math.min(100, Math.max(0, Math.round(v)));
+}
+
+async function scoreQuality(args: ScoreQualityArgs): Promise<ScoreQualityResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) {
+    throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  }
+  const existing = await storage.getAsset(slug, assetPath);
+  if (!existing) {
+    throw Object.assign(new Error(`asset not found: ${assetPath}`), { code: 'asset_not_found' });
+  }
+
+  const report: QualityReport = emptyQualityReport();
+  const setDim = (key: DimKey, value: number | null, source: QualityDim['source']) => {
+    report[key] = { value: clampScore(value), source };
+  };
+
+  let hasObjective = false;
+  if (args.objective) {
+    for (const key of ['geometry', 'topology', 'texture', 'pbr'] as const) {
+      if (key in args.objective) {
+        setDim(key, args.objective[key] ?? null, 'auto');
+        hasObjective = true;
+      }
+    }
+  }
+
+  let usedMock = false;
+  if (args.aiPass) usedMock = true;
+
+  let hasManual = false;
+  if (args.manual) {
+    for (const key of ['geometry', 'topology', 'texture', 'pbr', 'prompt_fidelity'] as const) {
+      if (key in args.manual) {
+        setDim(key, args.manual[key] ?? null, 'manual');
+        hasManual = true;
+      }
+    }
+    if (typeof args.manual.notes === 'string') report.notes = args.manual.notes;
+    if (hasManual) report.rater = 'local';
+  }
+
+  report.method = hasManual && hasObjective ? 'mixed' : hasManual ? 'manual' : 'auto';
+  report.total = weightedTotal([
+    { value: report.geometry.value, weight: DEFAULT_WEIGHTS.geometry },
+    { value: report.topology.value, weight: DEFAULT_WEIGHTS.topology },
+    { value: report.texture.value, weight: DEFAULT_WEIGHTS.texture },
+    { value: report.pbr.value, weight: DEFAULT_WEIGHTS.pbr },
+    { value: report.prompt_fidelity.value, weight: DEFAULT_WEIGHTS.prompt_fidelity },
+  ]);
+  report.scoredAt = new Date().toISOString();
+
+  const manifest = await storage.updateAssetQuality(slug, assetPath, report);
+  return { ok: true, usedMock, manifest };
+}
+
+interface RenameAssetArgs {
+  slug?: string;
+  assetPath: string;
+  label: string | null;
+}
+
+async function renameAsset(args: RenameAssetArgs): Promise<{ ok: true; manifest: Gen3DAssetManifest }> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) {
+    throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  }
+  const manifest = await storage.updateAssetLabel(slug, assetPath, args.label ?? null);
+  return { ok: true, manifest };
+}
+
+// ─── Playable-character motion profile (R7, PLAN §4.1/§5.3) ─────────────────
+// Four-layer model: built-in preset → game default profile → character
+// override → motion mapping. Game profile is one file per game; override +
+// mapping live in the character's own gen3d sidecar (never the engine meta).
+
+async function requireCharacterAsset(slug: string, assetPath: string): Promise<Gen3DAssetManifest> {
+  const asset = await storage.getAsset(slug, assetPath);
+  if (!asset) {
+    throw Object.assign(new Error(`asset not found: ${assetPath}`), { code: 'asset_not_found' });
+  }
+  if (asset.assetSlot !== 'characters') {
+    throw Object.assign(new Error('this tool only applies to character assets'), {
+      code: 'not_a_character',
+    });
+  }
+  return asset;
+}
+
+interface GetPlayableProfileArgs {
+  slug?: string;
+  assetPath?: string;
+}
+
+interface GetPlayableProfileResult {
+  ok: true;
+  presets: typeof BUILTIN_PROFILE_PRESETS;
+  gameProfile: GameMotionProfile | null;
+  effectiveSlots: MotionSlotDef[];
+  override: CharacterMotionOverride | null;
+  mapping: MotionMappingDraft | null;
+  delivery: (PlayableDeliverySnapshot & { localUrl: string }) | null;
+  oneClickReady: boolean;
+  /** PROF3: game default drifted past what this character/delivery was based on. */
+  migrationNeeded: boolean;
+  /** ADOPT1: orphan merged.glb+meta exist and this source has no delivery yet. */
+  adoptCandidate: AdoptCandidate | null;
+}
+
+async function getPlayableProfile(args: GetPlayableProfileArgs): Promise<GetPlayableProfileResult> {
+  const slug = requireSlug(args.slug);
+  const gameProfile = await perGameStore.getGameMotionProfile(slug);
+  const assetPath = args.assetPath?.trim();
+
+  let override: CharacterMotionOverride | null = null;
+  let mapping: MotionMappingDraft | null = null;
+  let delivery: PlayableDeliverySnapshot | null = null;
+  let adoptCandidate: AdoptCandidate | null = null;
+  if (assetPath) {
+    await requireCharacterAsset(slug, assetPath);
+    const state = await perGameStore.getCharacterPlayableState(slug, assetPath);
+    override = state?.override ?? null;
+    mapping = state?.mapping ?? null;
+    delivery = state?.delivery ?? null;
+    adoptCandidate = await inspectAdoptCandidate(perGameStore, slug, assetPath);
+  }
+
+  const baseGameProfile = gameProfile ?? gameProfileFromPreset('basic-character-v1', new Date(0).toISOString());
+  const slots = effectiveSlots(baseGameProfile, override);
+  const profileId = override?.basedOnProfileId ?? baseGameProfile.profileId;
+  const profileVersion = override?.basedOnProfileVersion ?? baseGameProfile.profileVersion;
+  // PROF3: only a *persisted* game profile can drift. Virtual preset anchors
+  // always report v1 and must not alone trigger migration review.
+  const migrationNeeded = Boolean(
+    delivery &&
+      gameProfile &&
+      (override
+        ? override.basedOnProfileId !== gameProfile.profileId ||
+          override.basedOnProfileVersion !== gameProfile.profileVersion
+        : delivery.profileId !== gameProfile.profileId ||
+          delivery.profileVersion !== gameProfile.profileVersion),
+  );
+  const currentFingerprint =
+    mapping?.confirmed
+      ? mappingFingerprint(slots, mapping.mappings, profileId, profileVersion)
+      : null;
+  const deliveryResult = delivery
+    ? {
+        ...delivery,
+        localUrl: playableDeliveryLocalUrl(slug, delivery.modelPath),
+      }
+    : null;
+  return {
+    ok: true,
+    // Cloned, not the live module singleton — callers must not be able to
+    // mutate BUILTIN_PROFILE_PRESETS through the returned object. Slot arrays
+    // (matchKeywords) are cloned too, not just the slot objects themselves.
+    presets: BUILTIN_PROFILE_PRESETS.map((p) => ({
+      ...p,
+      slots: p.slots.map((s) => ({ ...s, matchKeywords: [...s.matchKeywords] })),
+    })),
+    gameProfile,
+    effectiveSlots: slots,
+    override,
+    mapping,
+    delivery: deliveryResult,
+    oneClickReady: Boolean(
+      delivery &&
+        !migrationNeeded &&
+        currentFingerprint &&
+        delivery.mappingFingerprint === currentFingerprint,
+    ),
+    migrationNeeded,
+    adoptCandidate,
+  };
+}
+
+interface SetPlayableProfileArgs {
+  slug?: string;
+  assetPath: string;
+  slots: MotionSlotDef[];
+  profileId?: string;
+  displayName?: string;
+  saveAsGameDefault?: boolean;
+}
+
+interface SetPlayableProfileResult {
+  ok: true;
+  gameProfile: GameMotionProfile;
+  override: CharacterMotionOverride;
+}
+
+const VALID_PLAYBACK_MODES: readonly PlaybackMode[] = ['loop', 'once', 'freeze_frame'];
+const VALID_ROOT_MOTIONS: readonly RootMotionStrategy[] = ['preserve', 'remove_xz', 'remove_xyz'];
+
+// The args schema declares speed/playbackMode/rootMotion constraints, but
+// nothing upstream enforces JSON-Schema constraints at runtime (no validator
+// lib in this pipeline). Mirrors the asMotionType/asActionId hand-validator
+// convention above.
+function validateMotionSlots(slots: unknown): MotionSlotDef[] {
+  if (!Array.isArray(slots) || slots.length === 0) {
+    throw Object.assign(new Error('slots must be a non-empty array'), { code: 'invalid_slots' });
+  }
+  for (const s of slots as MotionSlotDef[]) {
+    if (typeof s.speed !== 'number' || !(s.speed > 0)) {
+      throw Object.assign(new Error(`slot ${s.slotId}: speed must be > 0, got ${s.speed}`), {
+        code: 'invalid_slots',
+      });
+    }
+    if (!VALID_PLAYBACK_MODES.includes(s.playbackMode)) {
+      throw Object.assign(new Error(`slot ${s.slotId}: invalid playbackMode ${s.playbackMode}`), {
+        code: 'invalid_slots',
+      });
+    }
+    if (!VALID_ROOT_MOTIONS.includes(s.rootMotion)) {
+      throw Object.assign(new Error(`slot ${s.slotId}: invalid rootMotion ${s.rootMotion}`), {
+        code: 'invalid_slots',
+      });
+    }
+  }
+  return slots as MotionSlotDef[];
+}
+
+// PROF6: writing a character's slots ALWAYS records a character override (the
+// per-character source of truth). saveAsGameDefault is the opt-in extra step
+// that also bumps the shared game default profile — plain override saves never
+// touch it (PROF1: "单角色默认只改自己的覆盖"). PROF3 (migration review on
+// game-default drift) is enforced later, at export time (R9/R10) by comparing
+// basedOnProfileVersion, not here.
+async function setPlayableProfile(args: SetPlayableProfileArgs): Promise<SetPlayableProfileResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  validateMotionSlots(args.slots);
+  await requireCharacterAsset(slug, assetPath);
+
+  const now = new Date().toISOString();
+
+  let gameProfile: GameMotionProfile;
+  if (args.saveAsGameDefault) {
+    // Read-compute-write inside one lock acquisition: setGameMotionProfile's
+    // updateFn sees the CURRENT stored profile atomically, so two concurrent
+    // saveAsGameDefault calls can't both read the same profileVersion and
+    // silently clobber each other (lost-update).
+    gameProfile = await perGameStore.setGameMotionProfile(slug, (existing) => {
+      const presetFallback = findPreset(args.profileId ?? existing?.profileId ?? 'basic-character-v1');
+      return {
+        schemaVersion: 1,
+        profileId: args.profileId ?? existing?.profileId ?? 'basic-character-v1',
+        // Bump only when a stored profile already existed; the very first real
+        // save stays at version 1.
+        profileVersion: existing ? existing.profileVersion + 1 : 1,
+        displayName: args.displayName ?? existing?.displayName ?? presetFallback?.displayName ?? 'Custom',
+        slots: args.slots,
+        updatedAt: now,
+      };
+    });
+  } else {
+    // No saveAsGameDefault: the shared game default file must stay untouched
+    // (PROF1/PROF6). If nothing has ever been saved for real, fall back to an
+    // in-memory-only anchor (never persisted) purely so the override still has
+    // a basedOnProfileId/Version to record. NOTE for R10/PROF3: this virtual
+    // anchor always reports version 1 (same as a real first save would), so
+    // migration-review must not treat basedOnProfileVersion:1 alone as proof
+    // the override was based on an actually-persisted profile — compare
+    // basedOnProfileId too.
+    gameProfile =
+      (await perGameStore.getGameMotionProfile(slug)) ??
+      gameProfileFromPreset(args.profileId ?? 'basic-character-v1', now);
+  }
+
+  const override: CharacterMotionOverride = {
+    schemaVersion: 1,
+    slots: args.slots,
+    basedOnProfileId: gameProfile.profileId,
+    basedOnProfileVersion: gameProfile.profileVersion,
+    updatedAt: now,
+  };
+  await perGameStore.setCharacterPlayableOverride(slug, assetPath, override);
+
+  return { ok: true, gameProfile, override };
+}
+
+interface SetPlayableMotionMappingArgs {
+  slug?: string;
+  assetPath: string;
+  mappings: MotionMappingEntry[];
+  confirmed?: boolean;
+}
+
+interface SetPlayableMotionMappingResult {
+  ok: true;
+  mapping: MotionMappingDraft;
+}
+
+async function setPlayableMotionMapping(
+  args: SetPlayableMotionMappingArgs,
+): Promise<SetPlayableMotionMappingResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  if (!Array.isArray(args.mappings)) {
+    throw Object.assign(new Error('mappings must be an array'), { code: 'invalid_mappings' });
+  }
+  await requireCharacterAsset(slug, assetPath);
+
+  const mapping: MotionMappingDraft = {
+    schemaVersion: 1,
+    mappings: args.mappings,
+    confirmed: args.confirmed ?? false,
+    updatedAt: new Date().toISOString(),
+  };
+  await perGameStore.setCharacterMotionMapping(slug, assetPath, mapping);
+  return { ok: true, mapping };
+}
+
+interface EngineImportArgs {
+  slug?: string;
+  assetPath: string;
+}
+
+async function getEngineImportStatus(args: EngineImportArgs): Promise<EngineImportStatus> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  return engineImportStatus(perGameStore, slug, assetPath);
+}
+
+async function doImportToEngine(args: EngineImportArgs): Promise<EngineImportResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  return importToEngine(perGameStore, slug, assetPath);
+}
+
+
+async function doExportPlayableCharacter(args: {
+  slug?: string;
+  assetPath: string;
+  forceWizardConfirm?: boolean;
+}): Promise<ExportPlayableResult> {
+  const slug = requireSlug(args.slug);
+  const assetPath = args.assetPath?.trim();
+  if (!assetPath) throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+  await requireCharacterAsset(slug, assetPath);
+  return exportPlayableCharacter(perGameStore, {
+    slug,
+    assetPath,
+    forceWizardConfirm: args.forceWizardConfirm,
+  });
+}
+
+export const tools = {
+  'gen3d:provider-status': async () => getProviderStatus(),
+  'gen3d:list-assets': async (args: ListAssetsArgs = {}) => listAssets(args),
+  'gen3d:delete-asset': async (args: DeleteAssetArgs) => deleteAsset(args),
+  'gen3d:generate-meshy-text-mock': async (args: GenerateMockArgs) => generateMeshyTextMock(args),
+  'gen3d:text-to-3d': async (args: TextTo3DArgs) => textTo3D(args),
+  'gen3d:image-to-3d': async (args: ImageTo3DArgs) => imageTo3D(args),
+  'gen3d:views-to-3d': async (args: ViewsTo3DArgs) => viewsTo3D(args),
+  'gen3d:refine-mesh': async (args: RefineMeshArgs) => refineMesh(args),
+  'gen3d:pose-standardization': async (args: PoseStandardizationArgs) =>
+    poseStandardization(args),
+  'gen3d:upload-image': async (args: UploadImageArgs) => uploadImage(args),
+  'gen3d:upload-video': async (args: UploadVideoArgs) => uploadVideo(args),
+  'gen3d:auto-rig': async (args: AutoRigArgs) => autoRig(args),
+  'gen3d:apply-motion': async (args: ApplyMotionArgs) => applyMotion(args),
+  'gen3d:list-motions': async (args: ListMotionsArgs = {}) => listMotions(args),
+  'gen3d:retopo-lowpoly': async (args: RetopoLowpolyArgs) => retopoLowpoly(args),
+  'gen3d:score-quality': async (args: ScoreQualityArgs) => scoreQuality(args),
+  'gen3d:rename-asset': async (args: RenameAssetArgs) => renameAsset(args),
+  'gen3d:engine-import-status': async (args: EngineImportArgs) => getEngineImportStatus(args),
+  'gen3d:import-to-engine': async (args: EngineImportArgs) => doImportToEngine(args),
+  'gen3d:get-playable-profile': async (args: GetPlayableProfileArgs = {}) => getPlayableProfile(args),
+  'gen3d:set-playable-profile': async (args: SetPlayableProfileArgs) => setPlayableProfile(args),
+  'gen3d:set-playable-motion-mapping': async (args: SetPlayableMotionMappingArgs) =>
+    setPlayableMotionMapping(args),
+  'gen3d:export-playable-character': async (args: {
+    slug?: string;
+    assetPath: string;
+    forceWizardConfirm?: boolean;
+  }) => doExportPlayableCharacter(args),
+  'gen3d:adopt-playable-character': async (args: {
+    slug?: string;
+    assetPath: string;
+    slotMappings: AdoptSlotMapping[];
+    confirmed?: boolean;
+  }): Promise<AdoptPlayableResult> => {
+    const slug = requireSlug(args.slug);
+    const assetPath = args.assetPath?.trim();
+    if (!assetPath) throw Object.assign(new Error('assetPath is required'), { code: 'invalid_asset_path' });
+    await requireCharacterAsset(slug, assetPath);
+    return adoptPlayableCharacter(perGameStore, {
+      slug,
+      assetPath,
+      slotMappings: args.slotMappings ?? [],
+      confirmed: args.confirmed,
+    });
+  },
+  'gen3d:get-credentials': async () => readCredentials(),
+  'gen3d:set-credentials': async (args: Record<string, unknown> = {}) => writeCredentials(args),
+};
+
+export default tools;