Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

154 KB
Raw Blame
/**
 * Forge: browser-facing text/image → 3D model generator + auto-rigger.
 *
 *   POST /api/forge   { prompt, aspect_ratio?, path?, tier?, backend? }  → text→3D
 *   POST /api/forge   { image_urls[], prompt?, path?, tier?, backend? }  → image→3D
 *   POST /api/forge   { image_urls[sketch], prompt, path: 'sketch' }     → sketch→3D
 *   POST /api/forge?action=rig  { glb_url }                              → auto-rig
 *   GET  /api/forge?job=<id>                                             → poll a job
 *   GET  /api/forge?catalog                                              → tier/backend/cost matrix
 *
 * Two request axes select how a mesh is produced (see api/_lib/forge-tiers.js):
 *   • path : "image" (image-intermediate: text→image→mesh via FLUX + TRELLIS,
 *             the fast default; or Hunyuan3D self-host), "geometry" (geometry-
 *             first: native text→mesh / image→mesh via Meshy or Tripo, no
 *             synthesized intermediate view, higher geometric ceiling), or
 *             "sketch" (a drawing + a prompt naming it → TripoSG-scribble,
 *             self-host; untextured geometry).
 *   • tier : draft | standard | high: the target polygon budget + texture
 *             richness. The high tier yields a visibly denser mesh.
 * Every job result reports the path + tier + backend that produced it.
 *
 * The geometry providers are BYOK: the caller supplies their own Meshy/Tripo key
 * (request header `x-forge-provider-key`, or the signed-in user's stored key).
 * Without one, the geometry path returns a designed `needs_key` state.
 *
 * Optional output controls (every field off by default, see
 * api/_lib/forge-options.js: an old request that never sends any of these
 * behaves exactly as before):
 *   • seed             : integer, reproducible generation on lanes that expose one.
 *   • output_format     : "glb" (default) | "glb-draco" | "glb-meshopt": a real
 *     post-generation @gltf-transform compression pass (api/_lib/glb-compress.js).
 *   • texture_size / target_polycount: poly-aware backends only (Hunyuan3D,
 *     Meshy, Tripo, Rodin, TripoSG); ignored (never 422s) on TRELLIS.
 *   • director: false  : SKIPS the IBM Granite "art director" prompt rewrite
 *     that otherwise runs before a text prompt synthesizes its reference image
 *     (the same director the free MCP tools use). On by default, because it
 *     fails soft to the raw prompt and rides the free-first LLM chain, so it
 *     can only help. Documented at /docs/3d-api.
 *   • force_regenerate: true: skip the result cache read for this call (the
 *     cache still gets refreshed with the new result).
 * A finished generation's metadata carries `quality` (api/_lib/glb-quality.js
 *: valid/flag/score/reasons) and, when compression was requested,
 * `compression` (mode + before/after byte counts). A flagged degenerate/low
 * result is retried once automatically on the lanes that complete inline
 * within one request (free NVIDIA NIM, HuggingFace Spaces, BYOK-sync).
 * Identical text→3D requests on a platform-keyed (never BYOK), non-high-tier
 * lane are served from a short-lived result cache (api/_lib/forge-cache.js)
 * instead of re-running the GPU pipeline; the response carries `cached: true`.
 *
 * This is the public, auth-free twin of the 3D Studio MCP server (api/mcp-3d.js).
 * No mock paths: if a selected backend isn't configured the endpoint returns a
 * clean 503/501 and the page renders a designed state, it never fabricates a
 * model.
 */

import { randomUUID } from 'node:crypto';
import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { textToImage, synthesizeTurnaroundViews } from './_mcp3d/text-to-image.js';
import { createRegenProvider } from './_providers/replicate.js';
import { createRegenProvider as createGcpProvider } from './_providers/gcp.js';
import { BYOK_PROVIDER_FACTORIES } from './_providers/byok-registry.js';
import { tripoModelVersion } from './_providers/tripo.js';
import {
	PATHS,
	DEFAULT_PATH,
	TIER_IDS,
	DEFAULT_TIER,
	BACKENDS,
	resolveTier,
	resolveBackendId,
	resolveBackendIdWithHealth,
	freeLaneCandidates,
	classifyForgeSubject,
	isSelfHostBackend,
	coldStartSecondsFor,
	estimateEtaSeconds,
	estimateCredits,
	preferFreeReconstruct,
	backendIsConfigured,
	laneAfterHfFailure,
	backendAcceptsInlineViews,
	buildCatalog,
	selfhostQualityForTier,
	MODLY_LANES,
	isSelfHostImageLane,
	selfHostLaneName,
	nextSelfHostImageLane,
	poseControlFor,
} from './_lib/forge-tiers.js';
import {
	laneHealthSnapshot,
	markLaneUnhealthy,
	hfLaneCooling,
	HF_LANE_COOLDOWN_SECONDS,
} from './_lib/forge-lane-health.js';
import { isInlineImageRef } from './_lib/image-persist.js';
import { resolveProviderKey, resolveProviderKeyWithSource } from './_lib/forge-provider-key.js';
import { validateForgeImage } from './_lib/forge-image-validate.js';
import { encodeJobToken, decodeJobToken } from './_lib/forge-job-token.js';
import {
	hashClient,
	hashIp,
	createCreation,
	runWithCreationContext,
	materializeCreation,
	markFailed,
	markSupersededBy,
	findByJob,
} from './_lib/forge-store.js';
import { isStorageInfrastructureError } from './_lib/r2.js';
import { normalizeTraceId, recordForgeProgress, readForgeProgress } from './_lib/forge-progress.js';
import { getSessionUser } from './_lib/auth.js';
import { constantTimeEquals } from './_lib/crypto.js';
import {
	forgeRequestHash,
	coalesceInFlight,
	registerInFlight,
	acquireBlockingSlot,
	providerSubmitAllowed,
	dailyPaidAllowed,
	SCALE_LIMITS,
} from './_lib/forge-scale.js';
import { env as _env } from './_lib/env.js';
import { verifyTierPass, TIERS } from './_lib/three-tier.js';
import { requireFeatureAccess } from './_lib/require-three.js';
import { resolveCompAccess, COMP_TIER } from './_lib/comp-access.js';
import { priceForAction } from './_lib/pricing/catalog.js';
import {
	assertForgePayment,
	redeemForgePayment,
	releaseForgePayment,
} from './_lib/forge-high-payment.js';
import {
	chargeCreditsForAction,
	quoteCreditsForAction,
	getCreditAccount,
	refundCredits,
} from './_lib/credits.js';
import { markProviderCooldown, providersInCooldown } from './_lib/provider-health.js';
import { acquireLock, releaseLock, cacheGet, cacheSet } from './_lib/cache.js';
import { sanitizeJobError } from './_lib/provider-job-error.js';
import { normalizeForgeOptions, providerReconstructParams, summarizeForgeOptions, poseDirective } from './_lib/forge-options.js';
import { bindJobToOptions, optionsForJob } from './_lib/forge-job-options.js';
import {
	forgeResultCacheKey,
	getCachedForgeResult,
	putCachedForgeResult,
	bindJobToCacheKey,
	cacheKeyForJob,
} from './_lib/forge-cache.js';
import { shouldRetryForQuality, shouldEscalateToVisionQA } from './_lib/glb-quality.js';
import {
	resolveLiveJob,
	bindJobSuccessor,
	pickRedispatchLane,
	retryBackendSuggestions,
	submitFailoverJob,
	MAX_FAILOVER_HOPS,
} from './_lib/forge-failover.js';
import {
	laneAllowedInTerritory,
	requestTerritory,
	isTencentLane,
} from './_lib/forge-territory.js';
import { decideSelfhostMissing } from './_lib/forge-selfhost-recovery.js';
import { directPrompt } from './_mcp-studio/forge-client.js';
import { meshDirectorFor, meshSubjectClass, resolveLogoPrompt } from './_lib/forge-director-prompts.js';

// Circuit-breaker key + window for the free NVIDIA NIM TRELLIS text→3D lane. The
// hosted NVCF gateway can degrade so a submit neither completes nor hands back a
// pollable id before our timeout: a single slow window otherwise makes every
// text prompt re-pay that full timeout before failing over to the reconstruct
// lane. A short cooldown (recorded on a health failure, checked before the lane
// runs) lets subsequent requests skip a degraded lane and go straight to a
// working one; it expires on its own so a recovered lane is retried promptly.
// Best-effort via the shared cache: a miss just means "not cooling".
export const NIM_TRELLIS_COOLDOWN_KEY = 'forge-nim-trellis';
// Sideline the free NIM lane after a failure. The cooldown exists to avoid
// re-paying the expensive submit-timeout HANG, so a socket timeout / unreachable
// host (no HTTP status came back) earns the full window. A fast gateway 5xx (a
// 504/503 the gateway returned promptly: a cold-start/capacity blip the
// in-provider retry already rode) only earns a short window, so a single transient
// 504 doesn't sideline the free lane for two minutes and dump every text prompt on
// the paid lane. See nimCooldownSeconds().
const NIM_FORGE_COOLDOWN_SECONDS = 120;
const NIM_FORGE_GATEWAY_COOLDOWN_SECONDS = 30;

// Honest cold-start signal for a self-host lane: true only when the liveness
// probe reached the worker but it answered slowly (a scale-to-zero container
// spinning up). Reuses the cached lane-health snapshot, so the common path pays
// no extra probe. Used to widen the ETA + flag `cold_start`, never to fabricate
// progress; the client's real polling still drives actual status.
//
// Module-level because BOTH ends of a job need it. It used to be a closure inside
// the submit handler, so only the submit response could say a worker was booting;
// a client that never saw that response (a coalesced job, a page resumed after a
// reload, a poll-time failover successor) was told "queued" with no explanation
// for a wait that is a container boot, not a stall.
async function laneColdStart(backendId) {
	if (!backendId || !isSelfHostBackend(backendId) || !coldStartSecondsFor(backendId)) return false;
	try {
		const snap = await laneHealthSnapshot([backendId]);
		const rec = snap.byId[backendId];
		return Boolean(rec && rec.status === 'ok' && rec.warm === false);
	} catch {
		return false;
	}
}

// The platform-keyed paid reconstruct lane (Replicate TRELLIS) recorded as down.
// Set only on an out-of-credit/billing failure: which won't self-heal until ops
// tops the account up, so the window is long (reason 'auth'). The NIM-cooldown
// router reads it to avoid skipping the free lane in favour of a dead paid lane.
const REPLICATE_PAID_COOLDOWN_KEY = 'forge-replicate-paid';
const REPLICATE_PAID_COOLDOWN_SECONDS = 300;

// Pick how long to cool the free NIM lane after a failure. A Retry-After hint
// (429) is honoured within bounds; an HTTP status that came back at all means the
// gateway answered (a fast fail) and earns the short window; no status means our
// socket timed out / the host was unreachable (the expensive hang) and earns the
// full window.
export function nimCooldownSeconds(err) {
	const retryAfter = Number(err?.retryAfter);
	if (Number.isFinite(retryAfter) && retryAfter > 0) {
		return Math.min(
			Math.max(Math.ceil(retryAfter), NIM_FORGE_GATEWAY_COOLDOWN_SECONDS),
			NIM_FORGE_COOLDOWN_SECONDS,
		);
	}
	if (typeof err?.providerStatus === 'number') return NIM_FORGE_GATEWAY_COOLDOWN_SECONDS;
	return NIM_FORGE_COOLDOWN_SECONDS;
}

// Holder perk (Lever 2): a presented, verified $THREE tier pass lifts the free
// generation ceiling by that tier's multiplier. The pass is pure-HMAC verifiable
// (no RPC/price feed), so this adds zero latency to the anonymous free lane. An
// absent or invalid pass simply leaves the multiplier at 1 (the base 60/h).
// A comped account (api/_lib/comp-access.js) gets the top multiplier without a
// pass. Its lookup is cookie-guarded, so the anonymous path stays query-free.
async function freeLaneMultiplier(req, body) {
	const token = req.headers?.['x-three-tier-pass'] || body?.tier_pass || null;
	let fromPass = 1;
	if (token) {
		const payload = verifyTierPass(token);
		const tier = payload ? TIERS.find((t) => t.level === payload.level) : null;
		fromPass = tier?.rateMultiplier || 1;
	}
	// A pass that actually lifts the ceiling short-circuits: the holder perk is
	// already proven and no lookup is worth doing. A Member-level (or absent) pass
	// lifts nothing, so fall through and let a comp answer instead.
	if (fromPass > 1) return fromPass;
	const { comped } = await resolveCompAccess(req);
	return comped ? COMP_TIER.rateMultiplier || 1 : fromPass;
}

// Returns true when the request carries the internal cron seed token, meaning
// the call comes from forge-seed-cron (server→server). These bypass the per-IP
// rate limit; they're metered by maxPending() in the cron instead.
function isInternalSeedRequest(req) {
	const token = req.headers['x-forge-seed'];
	if (!token) return false;
	const secret = _env.CRON_SECRET;
	return !!secret && constantTimeEquals(token, secret);
}

// The free NVIDIA NIM (TRELLIS) provider is loaded lazily and dynamically: it
// ships in T1.1, so importing it statically would couple this whole endpoint to
// a module that may not exist yet. Dynamic import keeps every other backend
// working in the meantime; a missing module or absent NVIDIA_API_KEY surfaces as
// a clean backend_unconfigured 501 at the dispatch sites below.
async function loadNvidiaProvider() {
	const mod = await import('./_providers/nvidia.js');
	return mod.createNvidiaProvider();
}

const VALID_ASPECT = new Set(['1:1', '4:3', '3:4', '16:9', '9:16']);

// Multi-view reconstruction accepts up to four calibrated views of one object
// (front / back / left / right / and two three-quarter angles). This matches the
// self-host TRELLIS worker's own fusion ceiling (run_multi_image accepts up to 6
// views, workers/model-trellis/main.py); capping lower than the worker just threw
// away calibrated coverage the reconstructor could have fused.
const MAX_VIEWS = 6;

// Guard for caller-supplied reference image / source GLB URLs. http(s) only,
// bounded length: we forward these to the reconstruction/rig provider, so we
// never accept data: URLs or unbounded strings.
const HTTP_URL_RE = /^https?:\/\/[^\s]+$/i;

// A Replicate prediction id is a lowercase base32-ish token. Constrain the
// poll parameter to that shape so we never forward arbitrary strings upstream.
const JOB_ID_RE = /^[a-z0-9]{16,64}$/;

// Stable anonymous handle for the browser making the request (/forge has no
// login). Used to scope durable creations + the gallery to one client without
// trusting any of its other input.
function clientKeyFrom(req) {
	const raw = req.headers['x-forge-client'];
	return hashClient(Array.isArray(raw) ? raw[0] : raw);
}

// /forge is auth-free and the overwhelming majority of calls are anonymous -
// but when a caller DOES carry a session cookie (the browser /create/studio
// flow while logged in), attach their user_id to the durable creation so it
// surfaces on their public portfolio (/u/:username → "Models" tab). Resolved
// at most once per request; failures (no db, bad cookie) degrade to null,
// never block generation.
async function sessionUserIdFromReq(req) {
	if (Object.prototype.hasOwnProperty.call(req, '__twxSessionUserId')) return req.__twxSessionUserId;
	try {
		const user = await getSessionUser(req);
		req.__twxSessionUserId = user?.id ?? null;
	} catch {
		req.__twxSessionUserId = null;
	}
	return req.__twxSessionUserId;
}

// Resolve the requested generation path + quality tier from the body, falling
// back to the existing fast defaults (image-intermediate, standard tier).
function parsePath(body) {
	const p = typeof body?.path === 'string' ? body.path.trim() : '';
	return PATHS.includes(p) ? p : DEFAULT_PATH;
}
function parseTier(body) {
	const t = typeof body?.tier === 'string' ? body.tier.trim() : '';
	return TIER_IDS.includes(t) ? t : DEFAULT_TIER;
}

// "needs a BYOK key": a designed, branchable state (mirrors rig_unconfigured)
// rather than a generic error, so the page can prompt for the key inline.
function needsKey(res, providerName) {
	const meta = BACKENDS[providerName];
	return json(res, 501, {
		error: 'needs_key',
		provider: providerName,
		message: `${meta?.label || providerName} needs your own API key. Add a ${meta?.byok || providerName} key to use it.`,
	});
}

// Normalize the caller's reference image input into an ordered, de-duplicated
// list of view URLs. Accepts the multi-view `image_urls: string[]` form and the
// legacy single `image_url: string` (backward compatible, a single string
// still works exactly as before). Empty/blank/duplicate entries are dropped.
function parseImageUrls(body) {
	let raw;
	if (Array.isArray(body?.image_urls)) raw = body.image_urls;
	else if (typeof body?.image_url === 'string') raw = [body.image_url];
	else raw = [];

	const seen = new Set();
	const out = [];
	for (const v of raw) {
		if (typeof v !== 'string') continue;
		const t = v.trim();
		if (!t || seen.has(t)) continue;
		seen.add(t);
		out.push(t);
	}
	return out;
}

function unconfigured(res) {
	return json(res, 503, {
		error: 'unconfigured',
		message:
			'Text-to-3D generation is not configured on this deployment. Set any one of NVIDIA_API_KEY or HF_TOKEN (free lanes) or REPLICATE_API_TOKEN (flux → TRELLIS) to enable it.',
	});
}

// Whether a thrown provider error means the upstream itself is unavailable -
// throttled, over-quota, unreachable, or 5xx: as opposed to a client/config
// fault. Both never-dead-end fallbacks (image→3D to the self-hosted Hunyuan3D
// worker, text→3D to the free NVIDIA NIM lane) degrade on exactly these so a
// generation rides out a transient upstream outage instead of failing the user.
function isUpstreamUnavailable(err) {
	return (
		err?.code === 'rate_limited' ||
		err?.providerStatus === 429 ||
		err?.code === 'provider_error' ||
		err?.code === 'provider_unreachable' ||
		(typeof err?.providerStatus === 'number' && err.providerStatus >= 500)
	);
}

// A leaked paid-account billing/credit message from the platform's OWN vendor
// (e.g. Replicate "You have insufficient credit to run this model… purchase
// credit") is internal infra state: surfacing it to the user is both useless
// (they can't fund our account) and a billing-state leak. Detect it so the
// boundary can answer with an honest, generic "temporarily unavailable" instead.
// BYOK callers are excluded at the call site: a credit message about THEIR OWN
// account is actionable, so it's surfaced verbatim.
function isPaidCreditFailure(err) {
	if (err?.providerStatus === 402) return true;
	const text = `${err?.message || ''} ${err?.providerDetail || ''}`.toLowerCase();
	return /insufficient credit|purchase credit|account\/billing|out of credit|not enough credit/.test(text);
}

// ── Realism modules (land concurrently; imported lazily + fail-open) ───────────
// Two dedicated modules sharpen the realism path without ever becoming a hard
// dependency of it:
//   • forge-reference-image.js: seeds text→3D reconstruction with a Vertex-Gemini
//     photoreal reference image (falls back to the standing text→image provider).
//   • forge-quality-gate.js   : scores a finished generation (vision QA) and
//     supplies the retry hint that drives a bounded auto-retry.
// Both are consumed through the lazy, fail-open shims below: an absent module (not
// yet deployed) or a down Vertex backend degrades to the standing behaviour, so
// the free/default lane never regresses and a delivered model is never blocked.
// These shims are the ONLY coupling forge.js has to those modules.

function readForgeEnv(name) {
	if (typeof process !== 'undefined' && process.env && process.env[name] != null && process.env[name] !== '') {
		return process.env[name];
	}
	return null;
}

// Photoreal reconstruction reference. Prefers the dedicated Vertex-Gemini module;
// falls back to the standing text→image provider (the FLUX/Imagen/NIM chain) when
// the module is absent or Vertex is unavailable. Returns { imageUrl, model } -
// exactly textToImage()'s shape: so the call site is a drop-in swap.
export async function seedReferenceImage({ prompt, aspect, seed, skipNim }) {
	if (readForgeEnv('FORGE_REFERENCE_IMAGE') !== 'off') {
		try {
			const mod = await import('./_lib/forge-reference-image.js');
			const fn =
				mod.generateReferenceImage ||
				mod.reconstructionReferenceImage ||
				mod.photorealReferenceImage ||
				(typeof mod.default === 'function' ? mod.default : null);
			if (typeof fn === 'function') {
				// Positional signature: (prompt, { aspectRatio, seed, skipNim }). The module
				// itself falls through to the standing text→image provider on a Vertex
				// failure, so a returned result already reflects the best available lane.
				const out = await fn(prompt, { aspectRatio: aspect, seed, skipNim });
				const imageUrl = out && (out.imageUrl || out.image_url || out.url);
				if (imageUrl) {
					return { imageUrl, model: out.model || 'vertex-reference', referenceModule: true };
				}
			}
		} catch (err) {
			// Module not landed yet, or both Vertex AND its internal fallthrough failed.
			// Make one more standing-provider attempt below so this path never dead-ends.
			console.warn(`[forge] reference-image module unavailable, using standing provider: ${err?.message || err}`);
		}
	}
	const synthesized = await textToImage(prompt, { aspectRatio: aspect, skipNim, seed });
	return { imageUrl: synthesized.imageUrl, model: synthesized.model, referenceModule: false };
}

// Quality-gate scope, env-tunable via FORGE_QUALITY_GATE so ops widen/disable
// with no code change:
//   'adaptive' (default): the paid `high` tier is always vision-scored, and the
//       FREE draft/standard lanes escalate to vision QA only when the cheap
//       deterministic scorer cannot vouch for the mesh (shouldEscalateToVisionQA).
//       This gives every lane a semantic quality floor while a clean, textured
//       draft still ships instantly with no vision latency.
//   'high': only the paid/realism ceiling is vision-scored; free lanes untouched.
//   'all' : vision-score every tier unconditionally (no cheap-signal shortcut).
//   'off' : no vision QA anywhere.
export function qualityGateScope() {
	const v = (readForgeEnv('FORGE_QUALITY_GATE') || 'adaptive').toLowerCase();
	return v === 'all' || v === 'off' || v === 'high' ? v : 'adaptive';
}
// Decide whether the vision-QA gate runs for this tier. In 'adaptive' scope the
// cheap deterministic quality signal (glb-quality.js, already computed for every
// delivered mesh) decides for the non-high lanes: a confidently-good mesh is
// trusted and skips vision; an ambiguous one escalates.
export function qualityGateAppliesTo(tierId, quality = undefined) {
	const s = qualityGateScope();
	if (s === 'off') return false;
	if (s === 'all') return true;
	if (tierId === 'high') return true;
	if (s === 'adaptive') return shouldEscalateToVisionQA(quality);
	return false; // 'high' scope, non-high tier
}
// Bounded retry cap: default 1, clamped 0..2 so a quality retry can never turn one
// generation into an unbounded credit/latency sink.
export function qualityGateMaxRetries() {
	const raw = readForgeEnv('FORGE_QUALITY_GATE_MAX_RETRIES');
	if (raw == null) return 1; // unset → default 1 (Number(null) is 0, so guard first)
	const n = Number(raw);
	if (!Number.isFinite(n)) return 1;
	return Math.max(0, Math.min(2, Math.floor(n)));
}

// Score a finished generation via the dedicated vision-QA module. Fail-open: an
// absent module or a vision outage returns a passing verdict, so scoring can never
// block or fail a delivered model. Returns the module's verdict object
// ({ score, pass, defects, suggested_retry_hint, ... }) or a skipped pass.
export async function scoreQualityGate({ glbUrl, prompt, tier, backend, referenceImageUrl }) {
	try {
		const mod = await import('./_lib/forge-quality-gate.js');
		const fn =
			mod.runQualityGate ||
			mod.scoreForgeQuality ||
			mod.scoreGeneration ||
			mod.qualityGateScore ||
			(typeof mod.default === 'function' ? mod.default : null);
		if (typeof fn === 'function') {
			// runQualityGate renders the delivered GLB itself and scores exactly one
			// view of it; it never throws (fail-open) and returns a verdict carrying
			// pass / score / defects / suggested_retry_hint / qa_available. Score the
			// OUTPUT model (glbUrl), never the input reference, so the gate judges what
			// was actually produced.
			const verdict = await fn({
				glbUrl,
				prompt: prompt || null,
				subject: null,
			});
			if (verdict && typeof verdict === 'object') return verdict;
		}
	} catch (err) {
		console.warn(`[forge] quality-gate scoring unavailable (fail-open pass): ${err?.message || err}`);
	}
	return { pass: true, skipped: true, qa_available: false };
}

// True only for an explicit failing verdict: a skipped/absent gate never retries.
export function qualityGateFailed(verdict) {
	return Boolean(verdict) && verdict.skipped !== true && verdict.pass === false;
}
// Numeric quality score used to keep the best result across retries. A passing
// verdict floors at 1; an explicit numeric score wins; a bare fail is 0.
function qualityScoreValue(verdict) {
	const n = Number(verdict?.score);
	if (Number.isFinite(n)) return n;
	if (verdict?.pass === true) return 1;
	return 0;
}

// Post-generation quality stage for the synchronous lanes: score the delivered
// model and, on a failing verdict, run a bounded best-of retry that keeps the
// higher-scoring result. `regenerate({ hint })` re-runs the SAME lane and returns
// { glbUrl, durable }; it is called at most qualityGateMaxRetries() times. When
// the module exposes its own auto-retry helper it owns the loop instead (it holds
// the hint interpretation); either way this is fail-open and never discards a
// delivered model for a worse one. Returns { durable, verdict, retried }.
async function qualityGateFinalize({ tierId, prompt, path, backend, referenceImageUrl, durable, regenerate }) {
	// In 'adaptive' scope the cheap deterministic signal on the delivered mesh
	// decides whether a free-lane generation is worth a vision pass: a clean,
	// textured draft is trusted and returns here with no added latency.
	if (!qualityGateAppliesTo(tierId, durable?.quality) || !durable?.glbUrl) {
		return { durable, verdict: null, retried: false };
	}
	let bestDurable = durable;
	let bestVerdict = await scoreQualityGate({ glbUrl: durable.glbUrl, prompt, tier: tierId, backend, referenceImageUrl });
	let bestScore = qualityScoreValue(bestVerdict);
	let retried = false;
	const maxRetries = qualityGateMaxRetries();

	// The module's buildRetryDirective owns the retry decision: it returns the next
	// adjusted directive ({ prompt, tier, path, attempt }) or null when a retry must
	// NOT happen (verdict passed, QA outage, or the cap is reached), so it enforces
	// both the hint (tightened prompt / negative guidance) and the cap. Absent module
	// falls back to the verdict's suggested_retry_hint under our own env cap.
	let buildDirective = null;
	try {
		const mod = await import('./_lib/forge-quality-gate.js');
		if (typeof mod.buildRetryDirective === 'function') buildDirective = mod.buildRetryDirective;
	} catch {
		// Module absent: the local hint path below drives the (bounded) retry.
	}

	let attempt = 0;
	while (attempt < maxRetries && typeof regenerate === 'function') {
		let directive;
		if (buildDirective) {
			directive = buildDirective(bestVerdict, { prompt, tier: tierId, path, attempt, maxRetries });
			if (!directive) break; // module says stop (passed / QA outage / cap reached)
		} else {
			if (!qualityGateFailed(bestVerdict)) break;
			directive = { prompt, hint: bestVerdict?.suggested_retry_hint || null };
		}
		attempt += 1;
		const retryPrompt = directive.prompt || prompt;
		let next;
		try {
			next = await regenerate({ prompt: retryPrompt, hint: directive.hint || bestVerdict?.suggested_retry_hint || null });
		} catch (err) {
			console.warn(`[forge] quality-gate retry regenerate failed, keeping best result: ${err?.message || err}`);
			break;
		}
		if (!next?.durable?.glbUrl) break;
		retried = true;
		const nextVerdict = await scoreQualityGate({ glbUrl: next.durable.glbUrl, prompt: retryPrompt, tier: tierId, backend, referenceImageUrl });
		const nextScore = qualityScoreValue(nextVerdict);
		// Keep the higher-scoring result; a passing verdict always wins and ends the loop.
		if (nextVerdict?.pass === true || nextScore > bestScore) {
			bestDurable = next.durable;
			bestVerdict = nextVerdict;
			bestScore = nextScore;
		}
		if (bestVerdict?.pass === true) break;
	}
	return { durable: bestDurable, verdict: bestVerdict, retried };
}

// Free NVIDIA NIM TRELLIS text→3D lane, extracted so it serves two callers:
//   1. the draft default (backendId === 'nvidia'), and
//   2. the never-dead-end fallback the paid image-intermediate TRELLIS lane
//      degrades to when Replicate is unreachable / over-quota (HTTP 429/5xx).
// Returns true once it has written a 200 response, or false when the lane is
// itself unavailable (so the caller can fall through to the next lane). Prompt
// is required: NVCF is text-only; photo submissions never reach here.
async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opts = null, cacheKey = null }) {
	// NVCF emits the mesh directly from text, no FLUX-synthesized reference
	// image exists for this lane, so a pose directive (if honorable at all,
	// see forge-tiers.js poseControlFor) has to be appended here rather than
	// relying on the image-intermediate injection in startJobWithBody.
	const poseText = opts?.pose && poseControlFor('nvidia') ? poseDirective(opts.pose) : null;
	const poseApplied = Boolean(poseText);
	const withPose = (p) => (poseText ? `${p}, ${poseText}` : p);
	let submitted;
	try {
		const nv = await loadNvidiaProvider();
		submitted = await nv.textTo3d({ prompt: withPose(prompt), tier, seed: opts?.seed ?? undefined });
	} catch (err) {
		// A timed-out / unreachable / throttled / 5xx NIM lane is degraded, cool it
		// down so the next request skips the submit-timeout gamble and fails over
		// fast. A 4xx (bad input / key) is not a lane-health fault, so it never cools.
		if (isUpstreamUnavailable(err)) {
			markProviderCooldown(NIM_TRELLIS_COOLDOWN_KEY, nimCooldownSeconds(err)).catch(() => {});
		}
		console.warn(`[forge] free NVIDIA NIM lane unavailable: ${err?.message || err}`);
		return false;
	}

	const backendId = 'nvidia';
	const provenance = {
		mode: 'text_to_3d',
		path,
		tier: tier.id,
		backend: backendId,
		prompt: prompt || null,
		preview_image_url: null,
		reference_image_urls: [],
		eta_seconds: estimateEtaSeconds({ backendId, tier }),
		estimated_credits: estimateCredits({ backendId, path, tier }),
	};

	const clientKey = clientKeyFrom(req);
	// Synchronous completion: NVCF already persisted the GLB to R2. Record a
	// finished creation (a synthetic handle lets materialize copy + flip it to
	// done) and return it so the client skips polling entirely.
	if (!submitted.taskId && submitted.resultGlbUrl) {
		const syntheticJob = randomUUID().replace(/-/g, '');
		const creationId = await createCreation({
			clientKey,
			userId: await sessionUserIdFromReq(req),
			ipHash: hashIp(ip),
			prompt,
			aspect,
			previewImageUrl: null,
			replicateJobId: syntheticJob,
			textToImageModel: null,
			viewsRequested: 0,
			viewsUsed: null,
			multiview: false,
			backend: backendId,
			tier: tier.id,
			path,
		});
		let durable = await materializeCreation({
			replicateJobId: syntheticJob,
			clientKey,
			userId: await sessionUserIdFromReq(req),
			glbUrl: submitted.resultGlbUrl,
			quality: true,
			compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
			derivePbr: opts?.derivePbr !== false,
			lods: opts?.lods === true,
			bbox: opts?.bbox ?? null,
		});

		// One auto-retry on a flagged low-quality/degenerate output (CLAUDE.md: no
		// silent mediocrity). Only worth attempting when the free NIM lane already
		// completed synchronously once: a second synchronous completion is the
		// common case, so this stays a bounded, in-request retry rather than a
		// background job. Best-effort: any retry failure just keeps the first result.
		let retried = false;
		if (shouldRetryForQuality(durable?.quality)) {
			try {
				const nv = await loadNvidiaProvider();
				const retry = await nv.textTo3d({ prompt: withPose(prompt), tier, seed: opts?.seed ?? undefined });
				if (!retry.taskId && retry.resultGlbUrl) {
					const retryJob = randomUUID().replace(/-/g, '');
					await createCreation({
						clientKey,
						userId: await sessionUserIdFromReq(req),
						ipHash: hashIp(ip),
						prompt,
						aspect,
						previewImageUrl: null,
						replicateJobId: retryJob,
						textToImageModel: null,
						viewsRequested: 0,
						viewsUsed: null,
						multiview: false,
						backend: backendId,
						tier: tier.id,
						path,
					});
					const retryDurable = await materializeCreation({
						replicateJobId: retryJob,
						clientKey,
						userId: await sessionUserIdFromReq(req),
						glbUrl: retry.resultGlbUrl,
						quality: true,
						compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
						derivePbr: opts?.derivePbr !== false,
						lods: opts?.lods === true,
						bbox: opts?.bbox ?? null,
					});
					if (retryDurable) {
						durable = retryDurable;
						retried = true;
					}
				}
			} catch (err) {
				console.warn(`[forge] quality auto-retry (nvidia) failed, keeping first result: ${err?.message || err}`);
			}
		}

		// Vision-QA quality gate (High/realism tier by default; env-tunable via
		// FORGE_QUALITY_GATE). Score the delivered model and, on a failing verdict,
		// run a bounded best-of retry on this same free lane keeping the higher-
		// scoring result. Dormant for draft/standard by default, so the free default
		// lane pays no extra latency. Fail-open end to end.
		const gated = await qualityGateFinalize({
			tierId: tier.id,
			prompt,
			path,
			backend: backendId,
			referenceImageUrl: null,
			durable,
			regenerate: async ({ prompt: retryPrompt } = {}) => {
				const useP = retryPrompt || prompt;
				const nvr = await loadNvidiaProvider();
				const r = await nvr.textTo3d({ prompt: withPose(useP), tier, seed: opts?.seed ?? undefined });
				if (r.taskId || !r.resultGlbUrl) return null;
				const rj = randomUUID().replace(/-/g, '');
				await createCreation({
					clientKey, userId: await sessionUserIdFromReq(req), ipHash: hashIp(ip),
					prompt: useP, aspect, previewImageUrl: null, replicateJobId: rj,
					textToImageModel: null, viewsRequested: 0, viewsUsed: null, multiview: false,
					backend: backendId, tier: tier.id, path,
				});
				const rd = await materializeCreation({
					replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),
					glbUrl: r.resultGlbUrl, quality: true,
					compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,
					derivePbr: opts?.derivePbr !== false,
					lods: opts?.lods === true,
					bbox: opts?.bbox ?? null,
				});
				return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;
			},
		});
		if (gated.durable) durable = gated.durable;
		if (gated.retried) retried = true;
		const qualityGate = gated.verdict;

		if (cacheKey && durable?.glbUrl) {
			await putCachedForgeResult(cacheKey, {
				glb_url: durable.glbUrl,
				backend: backendId,
				tier: tier.id,
				path,
				quality: durable.quality || null,
			});
		}

		json(res, 200, {
			job_id: null,
			creation_id: durable?.id ?? creationId,
			status: 'done',
			glb_url: durable?.glbUrl ?? submitted.resultGlbUrl,
			durable: Boolean(durable),
			quality: durable?.quality || null,
			quality_retried: retried,
			quality_gate: qualityGate || undefined,
			compression: durable?.compression || null,
			options: opts?.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,
			...provenance,
		});
		return true;
	}

	// Async: wrap the NVCF request id in a forge token so the poll routes back to
	// the NIM provider, and store it as the job handle.
	const token = encodeJobToken({
		provider: 'nvidia',
		kind: submitted.kind,
		taskId: submitted.taskId,
	});
	const creationId = await createCreation({
		clientKey,
		userId: await sessionUserIdFromReq(req),
		ipHash: hashIp(ip),
		prompt,
		aspect,
		previewImageUrl: null,
		replicateJobId: submitted.taskId,
		textToImageModel: null,
		viewsRequested: 0,
		viewsUsed: null,
		multiview: false,
		backend: backendId,
		tier: tier.id,
		path,
	});
	if (cacheKey) await bindJobToCacheKey(token, cacheKey);
	if (opts) await bindJobToOptions(token, opts);
	json(res, 200, {
		job_id: token,
		creation_id: creationId,
		status: 'queued',
		options: opts?.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,
		...provenance,
	});
	return true;
}

// The caller explicitly picked the free HuggingFace engine and it could not
// serve the request. The pick is honoured (never silently swapped), but this is
// a temporary capacity state, not a gateway fault: answer 503 with Retry-After,
// and name the configured engines that can take a fresh retry so the client can
// hop to one visibly instead of looping its countdown on the same dead Spaces.
// The lane always holds reference views by now (uploaded, or synthesized from
// the prompt), so the suggestions are scoped to image-capable lanes.
function hfLaneBusy(res, country = null) {
	const retryBackends = retryBackendSuggestions({ attempted: ['huggingface'], hasImage: true, country });
	res.setHeader('retry-after', '30');
	return json(res, 503, {
		error: 'provider_busy',
		backend: 'huggingface',
		message:
			'The free Hugging Face Spaces are out of GPU quota or warming up right now. Switch engines, or try again in a moment.',
		retry_after: 30,
		...(retryBackends.length ? { retryable: true, retry_backends: retryBackends } : {}),
	});
}

// Free Hugging Face Spaces image→3D lane (Hunyuan3D / TRELLIS / TripoSR on free
// GPU Spaces: the same provider the avatar reconstruction pipeline runs). The
// platform photo→3D default is the Replicate TRELLIS lane; when that account is
// over-quota or unreachable a photo upload would otherwise dead-end, because the
// free NVIDIA NIM fallback is text-only. This lane gives image mode the same
// "never dead-end" guarantee text mode already has: gated on HF_TOKEN, so it is
// a transparent no-op on deployments that don't set it. The provider blocks
// until the GLB is ready (Space queue + inference, within the 300s budget), so
// this returns status:'done' synchronously like the NVIDIA sync branch, no
// poll handle to route. Returns true once a 200 is written, false when the lane
// is unavailable so the caller can surface its own error.
// One-shot guard so the "HuggingFace lane not configured" notice is logged once
// per process instead of on every forge request (a static env condition).
let _hfUnconfiguredWarned = false;

async function runHfImageLane({
	req,
	res,
	ip,
	imageUrls,
	prompt,
	aspect,
	tier,
	path,
	// Text→3D feeds this lane a FLUX-synthesized reference view, so provenance must
	// be able to report text_to_3d (+ the synthesis model) rather than always
	// image_to_3d. Defaults keep the original image→3D behavior for callers that
	// pass user photos.
	mode = 'image_to_3d',
	previewImageUrl = null,
	textToImageModel = null,
	// The art-directed rewrite that painted `previewImageUrl`, when it differed
	// from the caller's raw prompt. Reported back verbatim so the client can show
	// what the model was actually asked for. Null on image→3D (nothing to rewrite).
	directedPrompt = null,
	opts = null,
	cacheKey = null,
	// Whether a requested pose was already baked into the reference image this
	// lane is reconstructing from (decided once in startJobWithBody, before any
	// lane failover reassigned the backend); false on the image→3D path and on
	// a pose-incapable backend (forge-tiers.js poseControlFor).
	poseApplied = false,
}) {
	// The Spaces chain runs Hunyuan3D, so the lane is closed to the EU, the UK,
	// South Korea and unknown countries. false means "could not serve" and every
	// caller already falls through to the next lane.
	if (!laneAllowedInTerritory('huggingface', requestTerritory(req))) return false;
	let provider;
	try {
		const mod = await import('./_providers/huggingface.js');
		provider = mod.createRegenProvider();
	} catch (err) {
		// HF_TOKEN absent or the Space chain is empty: the lane isn't available
		// on this deployment; fall through so the caller surfaces the real error.
		// A missing token is a STATIC deployment condition, not a per-request fault:
		// logging it on every forge call floods the function logs (it was the
		// single noisiest line). Warn once per process for the unconfigured case;
		// keep logging genuine transient init failures each time.
		if (err?.code === 'provider_unconfigured') {
			if (!_hfUnconfiguredWarned) {
				_hfUnconfiguredWarned = true;
				console.warn(`[forge] free HuggingFace image lane disabled (not configured): ${err?.message || err}`);
			}
		} else {
			console.warn(`[forge] free HuggingFace image lane unavailable: ${err?.message || err}`);
		}
		return false;
	}

	// The Space call BLOCKS this serverless worker for up to ~280s. Under an influx
	// that exhausts the Vercel worker pool and stalls /forge for everyone, so we cap
	// fleet-wide concurrent holds with a self-healing TTL lease. Over the cap the
	// lane reports "not served" (false) and the caller degrades, to the paid
	// reconstruct fallback on the free-first path, or a designed "free lane busy"
	// error on an explicit free pick: instead of piling onto an exhausted pool.
	// A chain-wide failure in the last few minutes paused the lane (see
	// HF_LANE_COOLDOWN_SECONDS): report "not served" at once instead of making
	// this caller wait out the same dead Spaces again.
	if (await hfLaneCooling()) return false;

	const slot = await acquireBlockingSlot('hf', {
		max: SCALE_LIMITS.hfConcurrent,
		ttlMs: SCALE_LIMITS.hfSlotTtlMs,
	});
	if (!slot.ok) {
		console.warn('[forge] free HuggingFace lane at concurrency cap; shedding this request');
		return false;
	}

	let resultGlbUrl;
	try {
		const submitted = await provider.submit({
			mode: 'reconstruct',
			sourceUrl: imageUrls[0],
			params: { images: imageUrls, prompt: prompt || undefined, seed: opts?.seed ?? undefined },
		});
		// submit() blocks and packs the finished GLB into extJobId; status() echoes
		// it back without re-hitting the Space.
		const finished = await provider.status(submitted.extJobId);
		resultGlbUrl = finished?.resultGlbUrl;
		if (!resultGlbUrl) throw new Error('HuggingFace returned no GLB');
	} catch (err) {
		console.warn(`[forge] free HuggingFace image lane failed: ${err?.message || err}`);
		await markLaneUnhealthy('huggingface', HF_LANE_COOLDOWN_SECONDS);
		return false;
	} finally {
		await slot.release();
	}

	const backendId = 'huggingface';
	const isImageMode = mode === 'image_to_3d';
	const preview = previewImageUrl || imageUrls[0];
	const clientKey = clientKeyFrom(req);
	const syntheticJob = randomUUID().replace(/-/g, '');
	const creationId = await createCreation({
		clientKey,
		userId: await sessionUserIdFromReq(req),
		ipHash: hashIp(ip),
		prompt: prompt || (isImageMode ? 'image-to-3d' : ''),
		aspect,
		previewImageUrl: preview,
		replicateJobId: syntheticJob,
		textToImageModel: isImageMode ? null : textToImageModel,
		viewsRequested: imageUrls.length,
		viewsUsed: imageUrls.length,
		multiview: imageUrls.length > 1,
		sourceImageUrls: imageUrls,
		backend: backendId,
		tier: tier.id,
		path,
	});
	// Best-effort copy to R2 so the model survives the Space's ephemeral file URL;
	// fail-soft to the raw HF url so the client still gets a model either way.
	const wantCompress = opts?.compression && opts.compression !== 'none' ? opts.compression : null;
	let durable = await materializeCreation({
		replicateJobId: syntheticJob,
		clientKey,
		userId: await sessionUserIdFromReq(req),
		glbUrl: resultGlbUrl,
		quality: true,
		compress: wantCompress,
		derivePbr: opts?.derivePbr !== false,
		lods: opts?.lods === true,
		bbox: opts?.bbox ?? null,
	});

	// One auto-retry on a flagged low-quality/degenerate output. Only attempted
	// when a concurrency slot is free right now: the HF lane is capacity-capped,
	// so a busy fleet keeps the first (flagged) result rather than starving
	// other callers of their turn on the free Spaces.
	let retried = false;
	if (shouldRetryForQuality(durable?.quality)) {
		const retrySlot = await acquireBlockingSlot('hf', { max: SCALE_LIMITS.hfConcurrent, ttlMs: SCALE_LIMITS.hfSlotTtlMs });
		if (retrySlot.ok) {
			try {
				const retrySubmitted = await provider.submit({
					mode: 'reconstruct',
					sourceUrl: imageUrls[0],
					params: { images: imageUrls, prompt: prompt || undefined, seed: opts?.seed ?? undefined },
				});
				const retryFinished = await provider.status(retrySubmitted.extJobId);
				if (retryFinished?.resultGlbUrl) {
					const retryJob = randomUUID().replace(/-/g, '');
					await createCreation({
						clientKey,
						userId: await sessionUserIdFromReq(req),
						ipHash: hashIp(ip),
						prompt: prompt || (isImageMode ? 'image-to-3d' : ''),
						aspect,
						previewImageUrl: preview,
						replicateJobId: retryJob,
						textToImageModel: isImageMode ? null : textToImageModel,
						viewsRequested: imageUrls.length,
						viewsUsed: imageUrls.length,
						multiview: imageUrls.length > 1,
						sourceImageUrls: imageUrls,
						backend: backendId,
						tier: tier.id,
						path,
					});
					const retryDurable = await materializeCreation({
						replicateJobId: retryJob,
						clientKey,
						userId: await sessionUserIdFromReq(req),
						glbUrl: retryFinished.resultGlbUrl,
						quality: true,
						compress: wantCompress,
						derivePbr: opts?.derivePbr !== false,
						lods: opts?.lods === true,
						bbox: opts?.bbox ?? null,
					});
					if (retryDurable) {
						durable = retryDurable;
						retried = true;
					}
				}
			} catch (err) {
				console.warn(`[forge] quality auto-retry (huggingface) failed, keeping first result: ${err?.message || err}`);
			} finally {
				await retrySlot.release();
			}
		}
	}

	// Vision-QA quality gate (High/realism tier by default; env-tunable). Bounded
	// best-of retry on this same free lane. Each retry must claim a free
	// concurrency slot first, so a busy fleet keeps the first result rather than
	// starving other callers. Fail-open end to end.
	const gated = await qualityGateFinalize({
		tierId: tier.id,
		prompt,
		path,
		backend: backendId,
		referenceImageUrl: preview,
		durable,
		regenerate: async ({ prompt: retryPrompt } = {}) => {
			const useP = retryPrompt || prompt;
			const rslot = await acquireBlockingSlot('hf', { max: SCALE_LIMITS.hfConcurrent, ttlMs: SCALE_LIMITS.hfSlotTtlMs });
			if (!rslot.ok) return null;
			try {
				const rs = await provider.submit({
					mode: 'reconstruct',
					sourceUrl: imageUrls[0],
					params: { images: imageUrls, prompt: useP || undefined, seed: opts?.seed ?? undefined },
				});
				const rf = await provider.status(rs.extJobId);
				if (!rf?.resultGlbUrl) return null;
				const rj = randomUUID().replace(/-/g, '');
				await createCreation({
					clientKey, userId: await sessionUserIdFromReq(req), ipHash: hashIp(ip),
					prompt: useP || (isImageMode ? 'image-to-3d' : ''), aspect,
					previewImageUrl: preview, replicateJobId: rj,
					textToImageModel: isImageMode ? null : textToImageModel,
					viewsRequested: imageUrls.length, viewsUsed: imageUrls.length,
					multiview: imageUrls.length > 1, sourceImageUrls: imageUrls, backend: backendId, tier: tier.id, path,
				});
				const rd = await materializeCreation({
					replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),
					glbUrl: rf.resultGlbUrl, quality: true, compress: wantCompress,
					derivePbr: opts?.derivePbr !== false,
					lods: opts?.lods === true,
					bbox: opts?.bbox ?? null,
				});
				return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;
			} finally {
				await rslot.release();
			}
		},
	});
	if (gated.durable) durable = gated.durable;
	if (gated.retried) retried = true;
	const qualityGate = gated.verdict;

	if (cacheKey && !isImageMode && durable?.glbUrl) {
		await putCachedForgeResult(cacheKey, {
			glb_url: durable.glbUrl,
			backend: backendId,
			tier: tier.id,
			path,
			quality: durable.quality || null,
		});
	}

	json(res, 200, {
		job_id: null,
		creation_id: durable?.id ?? creationId,
		status: 'done',
		glb_url: durable?.glbUrl ?? resultGlbUrl,
		durable: Boolean(durable),
		quality: durable?.quality || null,
		quality_retried: retried,
		quality_gate: qualityGate || undefined,
		compression: durable?.compression || null,
		options: opts?.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,
		mode,
		path,
		tier: tier.id,
		backend: backendId,
		prompt: prompt || null,
		directed_prompt: directedPrompt,
		preview_image_url: preview,
		reference_image_urls: isImageMode ? [imageUrls[0]] : [preview],
		text_to_image_model: isImageMode ? null : textToImageModel,
		eta_seconds: estimateEtaSeconds({ backendId, tier }),
		estimated_credits: estimateCredits({ backendId, path, tier }),
	});
	return true;
}

// Parse the request once, then run the whole submit inside a creation context so
// every row this request writes (primary submit, each failover hop, the sync and
// cache-hit branches) carries the caller's `destination` without each branch
// having to remember to pass it.
async function startJob(req, res) {
	const body = await readJson(req, 8_000).catch(() => null);
	return runWithCreationContext(
		{ destination: body?.destination, internal: isInternalSeedRequest(req) },
		() => startJobWithBody(req, res, body),
	);
}

async function startJobWithBody(req, res, body) {
	const ip = clientIp(req);

	// Two reconstruction modes share this path:
	//   • image→3D: a caller supplies one or more reference views (image_url or
	//     image_urls[]); we reconstruct directly and skip the text-to-image stage.
	//     With >1 view the provider fuses them (multi-view conditioning). An
	//     optional prompt may still guide the model where it accepts one.
	//   • text→3D: no images; we synthesize the reference image from the prompt
	//     with FLUX first, then reconstruct.
	let imageUrls = parseImageUrls(body);
	const isImageMode = imageUrls.length > 0;
	const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';

	// Optional, additive output controls (seed, output_format/compression,
	// texture_size, target_polycount): see _lib/forge-options.js. Every field is
	// off by default, so a request that never sends them behaves exactly as
	// before. An explicitly-present but invalid value is a 400 with an actionable
	// message; an absent field is never an error.
	const opts = normalizeForgeOptions(body);
	// True once a `pose` request actually reached a prompt that drives
	// generation (native text-to-geometry, or the synthesized reference image
	// for text→3D). Stays false for every image-mode request (the caller's own
	// photo already fixes the pose) and for a backend whose poseControl is
	// false (forge-tiers.js); summarizeForgeOptions echoes it as pose_applied
	// so a caller who asked for a pose can tell whether it actually took.
	let poseApplied = false;
	// Optional client-supplied trace id for the pre-submit progress channel. The
	// director pass and the reference-view synthesis both finish long before this
	// request can answer, so each records a crumb the page reads with a cheap poll
	// (GET ?progress=<id>) while this POST is still open. Absent id: no crumbs, and
	// the generation is byte-for-byte what it was before.
	const progressId = normalizeTraceId(body?.progress_id);
	if (opts.errors.length) {
		return json(res, 400, {
			error: 'invalid_options',
			errors: opts.errors,
			message: opts.errors.map((e) => e.message).join(' '),
		});
	}

	// Resolve the generation path + tier + backend BEFORE the rate check so the
	// limiter can be lane-aware. The free NVIDIA NIM lane (draft, no vendor spend)
	// gets a generous fail-open bucket; the paid Replicate/BYOK lanes keep the
	// tight critical 12/h ceiling that protects real money. Both still gate the
	// expensive work below (image moderation, FLUX, reconstruction).
	let path = parsePath(body);
	const tier = resolveTier(parseTier(body));
	// Subject class (organic / hard-surface / null) steers the High realism tier's
	// self-host lane order: Hunyuan3D-2.1 leads on people / creatures / detailed
	// organics, self-host TRELLIS leads on hard-surface / mechanical subjects. Pure
	// keyword heuristic on the prompt: zero latency, no LLM, and a no-op for every
	// tier below High (see freeLaneCandidates). An image submission with no guidance
	// prompt classifies to null and keeps the default order.
	const subjectClass = classifyForgeSubject(prompt);
	// Requester country, resolved from the edge geo header (never a body field).
	// Lanes that run a Tencent model are not routed for the EU, the UK, South
	// Korea or an unknown country (api/_lib/forge-territory.js).
	const country = requestTerritory(req);
	let backendId = resolveBackendId({ path, tier, backend: body?.backend, userImages: isImageMode, subjectClass, country });
	// Tracks whether the free NVIDIA NIM lane has already been attempted this
	// request, so the paid-lane fallback below never retries a lane that just
	// failed (draft already tries nvidia first; standard/high reach it only as a
	// last-resort fallback when Replicate is down).
	let nvidiaTried = false;
	// Set once the free NVIDIA NIM TRELLIS lane is known-degraded this request
	// (skipped on cooldown, or attempted and failed). The text→3D FLUX synthesis
	// below then skips the sibling NIM image lane too, so a degraded NVCF gateway
	// can't stack a second submit-timeout window on the same request.
	let nimGatewayDegraded = false;

	// Pay-per-use (Token Utility: consumption lever): set to { paymentId, refId,
	// settledAt, redeemed? } once a non-holder's settled $THREE payment is accepted
	// in lieu of holding. The payment is validated at the gate, claimed atomically
	// just before dispatch, and released if the generation fails before delivery.
	let paidHigh = null;

	// Prepaid-credit lane (pay_with:'credits'): set to { user, action, ref,
	// ledgerId?, chargedUsd? } once a signed-in user opts to spend their credit
	// balance instead of holding $THREE or paying per-call. Validated at the gate,
	// debited just before dispatch, refunded if the generation fails.
	let creditsCharge = null;

	// Fingerprint for in-flight request coalescing, set once the lane is resolved
	// below. Null disables coalescing (high tier, which is paid/gated per caller and
	// must never hand one payer's job to another).
	let requestHash = null;

	// The geometry path is BYOK-only: no free model does native text→geometry.
	// So when the caller didn't explicitly pick a backend and has no key for the
	// default geometry engine, transparently serve the free image lane (NVIDIA
	// NIM on draft, TRELLIS otherwise) instead of a dead "needs key" error. The
	// platform works with zero setup; Meshy/Tripo/Rodin stay fully selectable the
	// moment a key is present or a backend is explicitly chosen.
	const backendExplicit = Boolean(body?.backend && BACKENDS[body.backend]);
	// An explicitly named lane is honoured everywhere except where its model
	// licence excludes the requester's territory. Say so, and name the lane that
	// serves the same request there, instead of silently swapping the engine.
	if (backendExplicit && !laneAllowedInTerritory(body.backend, country)) {
		return json(res, 403, {
			error: 'region_restricted',
			backend: body.backend,
			message:
				'This engine is not available in your region because its model licence excludes it. Use the default engine, which is available everywhere.',
			retry_backends: retryBackendSuggestions({ hasImage: isImageMode, country }),
		});
	}
	if (path === 'geometry' && !backendExplicit) {
		const defaultByok = BACKENDS[backendId]?.byok;
		if (defaultByok) {
			const { key } = await resolveProviderKeyWithSource(req, body, defaultByok);
			if (!key) {
				path = 'image';
				backendId = resolveBackendId({ path, tier, userImages: isImageMode, subjectClass, country });
			}
		}
	}

	// Health-aware lane selection: when the caller didn't name a backend, consult a
	// cheap, cached liveness snapshot of the free lanes and skip any our probe (or a
	// recent submit failure) marks down: so a cold or unreachable self-host worker
	// is routed AROUND before submit, not failed-over after. Only the platform free
	// lanes (image/sketch) are candidates; geometry is BYOK and unaffected. Pure
	// best-effort: any snapshot error leaves the env-resolved backendId in place, so
	// a deployment with no telemetry behaves exactly as before. The snapshot is also
	// reused below to decide an honest cold-start ETA without a second probe.
	if (!backendExplicit && (path === 'image' || path === 'sketch')) {
		try {
			const candidates = freeLaneCandidates(path, tier.id, isImageMode, subjectClass, country);
			if (candidates.length) {
				const snap = await laneHealthSnapshot(candidates);
				const healthAware = resolveBackendIdWithHealth({
					path,
					tier,
					userImages: isImageMode,
					health: snap.statusMap,
					subjectClass,
					country,
				});
				if (BACKENDS[healthAware]) backendId = healthAware;
			}
		} catch (err) {
			console.warn(`[forge] lane-health routing skipped: ${err?.message || err}`);
		}
	}

	const coldStartFor = laneColdStart;

	// House-key billing/gate awareness, resolved once, for Tripo only (the one
	// backend with a house-key lane right now): the SAME priority order (inline,
	// then user session, then house env var) the BYOK dispatch below uses, so the
	// $THREE gate and the actual dispatch always agree on who is paying. An
	// inline or user key here always wins; this only flips true when the request
	// falls through to the platform's own key, in which case the resolved key is
	// cached here so the dispatch below doesn't re-run the session/DB lookup.
	let usingTripoHouseKey = false;
	let resolvedTripoKey = null;
	if (BACKENDS[backendId]?.byok === 'tripo' && BACKENDS[backendId]?.houseKeyEnv) {
		resolvedTripoKey = await resolveProviderKeyWithSource(req, body, 'tripo');
		usingTripoHouseKey = resolvedTripoKey.source === 'house';
	}

	// Content-addressed result cache (see _lib/forge-cache.js): a text→3D request
	// on a platform-keyed lane (never BYOK: that spends the caller's own account,
	// so it must never be replayed to a stranger) can be served instantly from a
	// prior identical generation instead of re-running the GPU pipeline. Captured
	// once, before any lane-failover churn reassigns `backendId` below, so the
	// same cache key is used to both look up and (on completion) store this
	// request's result: a failover to a different lane just means a miss, never
	// a wrong hit. `force_regenerate: true` skips the read (a fresh run is still
	// written back, keeping the cache warm). High tier is paid/gated per caller
	// and is never cached, matching the module's own privacy boundary.
	const cacheEligible = !isImageMode && tier.id !== 'high' && BACKENDS[backendId]?.byok === false;
	const forceRegenerate = body?.force_regenerate === true;
	const cacheKey = cacheEligible
		? forgeResultCacheKey({ path, tier, backend: backendId, prompt, options: opts })
		: null;
	if (cacheKey && !forceRegenerate) {
		const cached = await getCachedForgeResult(cacheKey);
		if (cached) {
			return json(res, 200, {
				job_id: null,
				creation_id: null,
				status: 'done',
				glb_url: cached.glb_url,
				durable: true,
				cached: true,
				cached_at: cached.cached_at,
				mode: 'text_to_3d',
				path: cached.path || path,
				tier: cached.tier || tier.id,
				backend: cached.backend || backendId,
				prompt: prompt || null,
				quality: cached.quality || null,
				// Cache lookup runs before any lane failover, so `backendId` here is
				// still the originally requested lane; a hit only exists because a
				// prior run with this exact (pose included) cache key already
				// generated it under that same lane.
				options: opts.hasOptions
					? summarizeForgeOptions(opts, { poseApplied: Boolean(opts.pose) && poseControlFor(backendId) })
					: undefined,
			});
		}
	}

	// $THREE hold-to-access gate (Token Utility v1): the High tier (200k poly +
	// PBR, textured) is the platform's premium quality tier. It now runs on a
	// free-for-us engine (HuggingFace Hunyuan3D) like every other tier, so this is
	// a pure monetization gate: we charge for higher quality, not to recover
	// vendor spend: reserved for holders (Bronze+, $25 hold) or a presented tier
	// pass, otherwise a hold-or-pay 402. BYOK backends are exempt (the caller pays
	// their own vendor key: key-gated, not hold-gated). Draft and Standard are
	// never gated, and internal cron seed jobs bypass it entirely.
	// requireFeatureAccess writes the 402 (three_hold_required) itself and returns
	// { ok:false }; on a holder it writes nothing and lets the job proceed.
	if (tier.id === 'high' && (BACKENDS[backendId]?.byok === false || usingTripoHouseKey) && !isInternalSeedRequest(req)) {
		// Consumption lever: a non-holder may present a settled $THREE payment
		// (payment_id + the client nonce it was bound to) to satisfy the gate per
		// generation instead of holding. Validate it read-only here; the single-use
		// claim is taken atomically just before dispatch (see paidHigh below). A
		// missing/invalid proof falls through to the normal hold-or-pay 402.
		const payWith = typeof body?.pay_with === 'string' ? body.pay_with.toLowerCase() : '';
		const paymentId = typeof body?.payment_id === 'string' ? body.payment_id.trim() : '';
		const refId = typeof body?.ref_id === 'string' ? body.ref_id.trim() : '';
		if (payWith === 'credits') {
			// Prepaid-credit lane: a signed-in user spends their balance instead of
			// holding $THREE or paying per-call. Affordability is checked here; the
			// single-use debit happens just before dispatch and is refunded if the
			// job fails (see creditsCharge in the try/finally below).
			const creditUser = await getSessionUser(req).catch(() => null);
			if (!creditUser) {
				return json(res, 401, {
					error: 'unauthorized',
					feature: 'forge.high',
					top_up_url: '/credits',
					message: 'Sign in to pay with credits.',
				});
			}
			let priceUsd;
			try {
				priceUsd = (await quoteCreditsForAction({ user: creditUser, action: 'forge.high' })).usd;
			} catch {
				priceUsd = Number(priceForAction('forge.high').usd) || 0;
			}
			const acct = await getCreditAccount(creditUser.id);
			if (acct.balanceUsd < priceUsd) {
				return json(res, 402, {
					error: 'insufficient_credits',
					feature: 'forge.high',
					price_usd: priceUsd,
					balance_usd: acct.balanceUsd,
					top_up_url: '/credits',
					message: `Generating a High model costs $${priceUsd.toFixed(2)} in credits, your balance is $${acct.balanceUsd.toFixed(2)}. Top up to continue.`,
				});
			}
			creditsCharge = { user: creditUser, action: 'forge.high', ref: refId || randomUUID() };
		} else if (paymentId && refId) {
			try {
				const proof = await assertForgePayment({ paymentId, refId });
				paidHigh = { paymentId, refId, settledAt: proof.payment.settledAt };
			} catch (err) {
				// A presented-but-invalid proof is a designed, recoverable state: the
				// client can pay again (pay_per_use) or hold. Carry the price so the UI
				// can re-offer Pay without another round-trip.
				let usd = null;
				try {
					usd = Number(priceForAction('forge.high').usd) || null;
				} catch {
					usd = null;
				}
				return json(res, err.status || 402, {
					error: err.code || 'payment_invalid',
					feature: 'forge.high',
					get_three_url: '/three-token',
					pay_per_use: usd ? { action: 'forge.high', usd } : null,
					message: err.message || 'That $THREE payment could not be verified.',
				});
			}
		} else {
			const gate = await requireFeatureAccess(req, res, 'forge.high', { body });
			if (!gate.ok) return; // 402 three_hold_required already sent
		}
	}

	const backendMeta = BACKENDS[backendId];
	const isFreeLane = backendMeta?.free === true;
	if (!isInternalSeedRequest(req)) {
		const rl = isFreeLane
			? await limits.mcp3dGenerateFreeTiered(ip, await freeLaneMultiplier(req, body))
			: await limits.mcp3dGenerate(ip);
		if (!rl.success) {
			return rateLimited(res, rl, 'Generation limit reached. Try again shortly.');
		}
		// Cost circuit breaker: a platform-wide hourly ceiling on PLATFORM-keyed paid
		// generation (the shared Replicate/self-host budget), on top of the per-IP cap
		// above. It stops the influx/abuse failure mode where many callers each stay
		// under their own cap but collectively drain spend. BYOK lanes spend the
		// caller's own key, so the platform-budget ceiling must never throttle them.
		// When it trips the free NVIDIA / HuggingFace lanes stay open, paid capacity
		// degrades, it never dead-ends.
		if (!isFreeLane && !backendMeta?.byok) {
			const globalRl = await limits.mcp3dGenerateGlobal();
			if (!globalRl.success) {
				return rateLimited(
					res,
					globalRl,
					'Paid 3D generation is at capacity right now: switch to a free engine (NVIDIA or Hugging Face), or try again shortly.',
				);
			}
			// Per-identity daily ceiling: closes the rotating-IP abuse path the per-IP
			// hourly cap and the global hourly cap leave open (one actor under every
			// per-request limit can still drain paid spend over a day). Keyed by the
			// forge client id. Free and BYOK lanes are never counted.
			const daily = await dailyPaidAllowed(clientKeyFrom(req), {
				limit: SCALE_LIMITS.paidDailyPerClient,
			});
			if (!daily.ok) {
				return json(res, 429, {
					error: 'daily_limit_reached',
					message:
						'You’ve reached today’s limit for paid generations. Free engines (NVIDIA, Hugging Face) stay open, or try again tomorrow.',
				});
			}
		}
	}

	if (isImageMode) {
		if (imageUrls.length > MAX_VIEWS) {
			return json(res, 400, {
				error: 'invalid_image_urls',
				message: `Provide between 1 and ${MAX_VIEWS} reference images.`,
			});
		}
		// Pixal3D's "Match my photo" lane fuses every view it is given, so its cap
		// is tighter than the generic MAX_VIEWS turnaround ceiling (4, not 6), and
		// its optional per-image labels must line up with the images they tag.
		if (backendId === 'pixal3d') {
			if (imageUrls.length > 4) {
				return json(res, 400, {
					error: 'invalid_image_urls',
					message: 'Match my photo accepts 1 to 4 reference images.',
				});
			}
			if (opts.viewLabels && opts.viewLabels.length !== imageUrls.length) {
				return json(res, 400, {
					error: 'invalid_view_labels',
					message: `view_labels must have exactly one entry per image (sent ${imageUrls.length} image(s) and ${opts.viewLabels.length} label(s)).`,
				});
			}
			if (opts.fillOtherSides && imageUrls.length !== 1) {
				return json(res, 400, {
					error: 'invalid_fill_other_sides',
					message: 'fill_other_sides needs exactly one reference image; send one photo and let the worker synthesize the other sides.',
				});
			}
		}
		// Validate every view at the boundary before any of them reach the model.
		for (const u of imageUrls) {
			if (!HTTP_URL_RE.test(u) || u.length > 2048) {
				return json(res, 400, {
					error: 'invalid_image_url',
					message: 'Each reference image must be an http(s) URL under 2048 characters.',
				});
			}
		}
		if (prompt.length > 1000) {
			return json(res, 400, {
				error: 'invalid_prompt',
				message: 'Optional guidance prompt must be 1000 characters or fewer.',
			});
		}

		// Vision pre-check (Consumer 1 of the shared vision helper): catch a photo
		// that can't be reconstructed BEFORE it burns a generation slot. Validates
		// the primary view only. Fail-open: a vision outage returns ok:true and we
		// proceed exactly as before (validateForgeImage owns that contract). The
		// user can override a verdict they disagree with via `skip_validation:true`
		// (e.g. a stylized reference our checker is too cautious about).
		// The sketch path is exempt: a line drawing is exactly what the photo
		// checker is trained to reject, and exactly what TripoSG-scribble wants.
		if (body?.skip_validation !== true && path !== 'sketch') {
			// The forge client key is a hashed client-supplied header, NOT an OAuth
			// client: it has no row in oauth_clients, so it must never land in the
			// FK-constrained usage_events.client_id (that fails the insert and the
			// whole spend event is silently dropped). Attribute it via meta instead.
			// Every view is checked in parallel, not just the primary: a bad
			// secondary angle (blurred, wrong subject, occluded) doesn't merely waste
			// a slot, it actively corrupts multi-view fusion by voting for geometry
			// that isn't there.
			const track = { meta: { forgeClient: clientKeyFrom(req) } };
			const checks = await Promise.all(imageUrls.map((u) => validateForgeImage(u, { track })));
			// The primary view is load-bearing: if it can't be reconstructed the whole
			// job can't, so reject with the one-click override as before.
			if (!checks[0].ok) {
				return json(res, 422, {
					error: 'image_not_usable',
					issue: checks[0].issue,
					message: checks[0].message,
					subject: checks[0].subject || null,
					// Surfaced so the UI can offer a one-click "generate anyway".
					override: { field: 'skip_validation', value: true },
				});
			}
			// Secondary views are additive coverage: drop any the checker flags
			// rather than fail the job or feed a corrupting view into fusion. The
			// primary always survives, so a single-photo upload is unaffected.
			const usable = imageUrls.filter((_, i) => i === 0 || checks[i].ok);
			if (usable.length < imageUrls.length) {
				console.warn(
					`[forge] pruned ${imageUrls.length - usable.length} unusable secondary view(s) before fusion; keeping ${usable.length}`,
				);
				imageUrls = usable;
			}
		}
	} else if (prompt.length < 3 || prompt.length > 1000) {
		return json(res, 400, {
			error: 'invalid_prompt',
			message:
				'Describe one subject in 3-1000 characters, or pass image_url / image_urls for image-to-3D.',
		});
	}
	const aspect = VALID_ASPECT.has(body?.aspect_ratio) ? body.aspect_ratio : '1:1';

	// Sketch→3D is single-view and prompt-conditioned: the drawing is the only
	// input image, and the prompt names what it depicts (TripoSG-scribble is a
	// text+scribble model: without the prompt it has nothing to disambiguate
	// rough strokes against).
	if (path === 'sketch') {
		if (!isImageMode) {
			return json(res, 400, {
				error: 'missing_sketch',
				message: 'Upload a drawing and pass it as image_urls[0] for sketch-to-3D.',
			});
		}
		if (imageUrls.length > 1) {
			return json(res, 400, {
				error: 'invalid_image_urls',
				message: 'Sketch-to-3D takes exactly one drawing.',
			});
		}
		if (prompt.length < 3) {
			return json(res, 400, {
				error: 'invalid_prompt',
				message: 'Say what the sketch depicts (3-1000 characters), the sketch model is prompt-conditioned.',
			});
		}
	}

	// path / tier / backendId were resolved above (the rate limiter is lane-aware).
	// An explicitly selected text-only backend can't serve a photo submission -
	// say so plainly rather than failing upstream with an opaque 422.
	if (isImageMode && BACKENDS[backendId]?.userImages === false) {
		return json(res, 422, {
			error: 'backend_text_only',
			backend: backendId,
			message:
				`${BACKENDS[backendId].label} generates from text prompts only, NVIDIA's hosted preview doesn't accept uploaded photos. ` +
				'Drop the backend field to use the default photo engine, or pick TRELLIS, Meshy, or Tripo.',
		});
	}

	try {
		// Pay-per-use: claim the settled $THREE payment now, immediately before any
		// provider work, so every cheap failure above (rate limit, moderation, bad
		// input) left the payment reusable. The atomic claim (payment_id PRIMARY KEY)
		// is the single-use source of truth: a concurrent retry of the same payment
		// loses the race and is told the payment is already used. If anything below
		// fails before a model is delivered, the finally releases the claim.
		if (paidHigh && !paidHigh.redeemed) {
			const claim = await redeemForgePayment({
				paymentId: paidHigh.paymentId,
				refId: paidHigh.refId,
				settledAt: paidHigh.settledAt,
			});
			if (!claim.redeemed) {
				return json(res, 409, {
					error: 'payment_already_used',
					feature: 'forge.high',
					get_three_url: '/three-token',
					message:
						'This payment has already been used for a generation. Pay again to generate another High model.',
				});
			}
			paidHigh.redeemed = true;
		}

		// Prepaid-credit charge: debit now, immediately before provider work, so
		// every cheap failure above left the balance untouched. Idempotent on the
		// client ref; the finally refunds it if the job fails before delivery.
		if (creditsCharge && !creditsCharge.ledgerId) {
			try {
				const charged = await chargeCreditsForAction({
					user: creditsCharge.user,
					action: creditsCharge.action,
					refType: 'forge',
					refId: creditsCharge.ref,
					idempotencyKey: `forge:credits:${creditsCharge.ref}`,
					meta: { tier: 'high' },
				});
				creditsCharge.ledgerId = charged.ledgerId;
				creditsCharge.chargedUsd = charged.chargedUsd;
			} catch (err) {
				if (err.code === 'insufficient_credits') {
					return json(res, 402, {
						error: 'insufficient_credits',
						feature: 'forge.high',
						available_usd: err.available_usd,
						required_usd: err.required_usd,
						top_up_url: '/credits',
						message: err.message,
					});
				}
				throw err;
			}
		}

		// ── Sketch path (TripoSG-scribble, self-host) ───────────────────────────
		// The drawing + prompt go straight to the TripoSG worker's scribble
		// pipeline. Geometry only: no synthesized intermediate view, no textures;
		// the result panel's Retexture/Stylize tools pick up from there.
		if (path === 'sketch') {
			let gcp;
			try {
				gcp = createGcpProvider();
			} catch {
				return json(res, 501, {
					error: 'backend_unconfigured',
					backend: backendId,
					message: 'Sketch-to-3D is not configured on this deployment.',
				});
			}

			const sketchUrl = imageUrls[0];
			let job;
			try {
				job = await gcp.submit({
					mode: 'sketch',
					sourceUrl: sketchUrl,
					params: {
						prompt,
						target_polycount: opts.targetPolycount ?? tier.polycount,
						tier: tier.id,
						path,
						seed: opts.seed ?? undefined,
					},
				});
			} catch (err) {
				if (err?.code === 'mode_unconfigured') {
					return json(res, 501, {
						error: 'backend_unconfigured',
						backend: backendId,
						message:
							'Sketch-to-3D is not configured on this deployment (GCP_TRIPOSG_URL is not set).',
					});
				}
				// The sketch model is conditioned on the drawing: no other lane can
				// serve it, so there is nothing to fail over to. Cool the worker so the
				// next request skips it while it recovers, and return a designed,
				// retryable state instead of a raw provider error.
				if (isUpstreamUnavailable(err)) {
					await markLaneUnhealthy('triposg');
					console.warn(`[forge] self-host sketch lane unavailable: ${err?.message || err}`);
					res.setHeader('retry-after', '20');
					return json(res, 503, {
						error: 'generation_unavailable',
						backend: backendId,
						message:
							'The sketch-to-3D worker is warming up or briefly unavailable. Try again in a moment.',
						retry_after: 20,
					});
				}
				throw err;
			}

			// Wrap the GCP job envelope in a forge token so polling routes back to
			// the GCP provider: same idiom as the Hunyuan3D lane.
			const token = encodeJobToken({ provider: 'gcp', kind: null, taskId: job.extJobId });
			const creationId = await createCreation({
				clientKey: clientKeyFrom(req),
				userId: await sessionUserIdFromReq(req),
				ipHash: hashIp(ip),
				prompt,
				aspect: null,
				previewImageUrl: sketchUrl,
				replicateJobId: job.extJobId,
				textToImageModel: null,
				viewsRequested: 1,
				viewsUsed: 1,
				multiview: false,
				backend: backendId,
				tier: tier.id,
				path,
			});
			await bindJobToOptions(token, opts);

			const sketchCold = await coldStartFor(backendId);
			return json(res, 200, {
				job_id: token,
				creation_id: creationId,
				status: 'queued',
				mode: 'sketch_to_3d',
				path,
				tier: tier.id,
				backend: backendId,
				prompt,
				preview_image_url: sketchUrl,
				reference_image_urls: [sketchUrl],
				cold_start: sketchCold,
				cold_start_seconds: sketchCold ? coldStartSecondsFor(backendId) : undefined,
				eta_seconds: estimateEtaSeconds({ backendId, tier, cold: sketchCold }),
				estimated_credits: estimateCredits({ backendId, path, tier }),
				options: opts.hasOptions ? summarizeForgeOptions(opts) : undefined,
			});
		}

		// ── BYOK geometry-style providers (Meshy / Tripo / Rodin / Stability) ────
		// A native 3D model emits mesh geometry directly: from the prompt
		// (text→geometry) or a single photo (image→3D): with no synthesized
		// intermediate view, so detail isn't capped by one image. These backends
		// have no platform key, except Tripo when TRIPO_API_KEY is set (the house
		// lane, resolved above into resolvedTripoKey/usingTripoHouseKey so this
		// reuses it instead of re-querying). Dispatch is a registry lookup on the
		// backend's `byok` name (Replicate BYOK is handled on the image-intermediate
		// path below: it speaks a different interface).
		const byokProvider = BACKENDS[backendId].byok;
		const byokFactory = BYOK_PROVIDER_FACTORIES[byokProvider];
		if (byokFactory) {
			const key =
				byokProvider === 'tripo' && resolvedTripoKey
					? resolvedTripoKey.key
					: await resolveProviderKey(req, body, byokProvider);
			if (!key) return needsKey(res, backendId);

			let gp;
			try {
				gp = byokFactory(key);
			} catch {
				return needsKey(res, backendId);
			}

			let submitted;
			let previewImageUrl = null;
			if (isImageMode) {
				// The native image→3D endpoints reconstruct from a single primary
				// view; multi-view fusion stays on the image/TRELLIS path. The
				// caller's own photo already fixes the subject's pose, so `pose` is
				// never applied here regardless of this backend's poseControl.
				previewImageUrl = imageUrls[0];
				submitted = await gp.imageTo3d({
					imageUrl: previewImageUrl,
					prompt: prompt || undefined,
					tier,
					targetPolycount: opts.targetPolycount ?? undefined,
				});
			} else if (typeof gp.textToGeometry === 'function') {
				const poseText = opts.pose && poseControlFor(backendId) ? poseDirective(opts.pose) : null;
				if (poseText) poseApplied = true;
				submitted = await gp.textToGeometry({
					prompt: poseText ? `${prompt}, ${poseText}` : prompt,
					tier,
					targetPolycount: opts.targetPolycount ?? undefined,
				});
			} else {
				// Image-only backend (e.g. Stable Fast 3D) asked to run text→3D.
				return json(res, 422, {
					error: 'backend_image_only',
					backend: backendId,
					message: `${BACKENDS[backendId].label} reconstructs from a reference image, attach one, or drop the backend to use a text→3D engine.`,
				});
			}

			const clientKey = clientKeyFrom(req);

			// Synchronous completion (Stable Fast 3D): the provider already persisted
			// the GLB to R2 and handed back a durable url: no task to poll. Record a
			// finished creation and return done so the client skips polling, exactly
			// like the NVIDIA NIM synchronous path.
			if (!submitted.taskId && submitted.resultGlbUrl) {
				const syntheticJob = randomUUID().replace(/-/g, '');
				const creationId = await createCreation({
					clientKey,
					userId: await sessionUserIdFromReq(req),
					ipHash: hashIp(ip),
					prompt: prompt || (isImageMode ? 'image-to-3d' : ''),
					aspect: isImageMode ? null : aspect,
					previewImageUrl,
					replicateJobId: syntheticJob,
					textToImageModel: null,
					viewsRequested: isImageMode ? imageUrls.length : 0,
					viewsUsed: isImageMode ? 1 : null,
					multiview: false,
					backend: backendId,
					tier: tier.id,
					path,
				});
				const durable = await materializeCreation({
					replicateJobId: syntheticJob,
					clientKey,
					userId: await sessionUserIdFromReq(req),
					glbUrl: submitted.resultGlbUrl,
					quality: true,
					compress: opts.compression !== 'none' ? opts.compression : null,
					derivePbr: opts.derivePbr !== false,
					lods: opts.lods === true,
					bbox: opts.bbox ?? null,
				});
				return json(res, 200, {
					job_id: null,
					creation_id: durable?.id ?? creationId,
					status: 'done',
					glb_url: durable?.glbUrl ?? submitted.resultGlbUrl,
					durable: Boolean(durable),
					quality: durable?.quality || null,
					compression: durable?.compression || null,
					options: opts.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,
					mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
					path,
					tier: tier.id,
					backend: backendId,
					engine_version: byokProvider === 'tripo' ? tripoModelVersion() : undefined,
					prompt: prompt || null,
					preview_image_url: previewImageUrl,
					reference_image_urls: isImageMode ? [imageUrls[0]] : [],
					eta_seconds: estimateEtaSeconds({ backendId, tier }),
					estimated_credits: estimateCredits({ backendId, path, tier }),
				});
			}

			const token = encodeJobToken({
				provider: byokProvider,
				kind: submitted.kind,
				taskId: submitted.taskId,
			});
			await bindJobToOptions(token, opts);

			// Store the upstream task id as the job handle so findByJob/materialize
			// resolve it on poll, exactly like the Replicate path.
			const creationId = await createCreation({
				clientKey,
				userId: await sessionUserIdFromReq(req),
				ipHash: hashIp(ip),
				prompt: prompt || (isImageMode ? 'image-to-3d' : ''),
				aspect: isImageMode ? null : aspect,
				previewImageUrl,
				replicateJobId: submitted.taskId,
				textToImageModel: null,
				viewsRequested: isImageMode ? imageUrls.length : 0,
				viewsUsed: isImageMode ? 1 : null,
				multiview: false,
				backend: backendId,
				tier: tier.id,
				path,
			});

			return json(res, 200, {
				job_id: token,
				creation_id: creationId,
				status: 'queued',
				mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
				path,
				tier: tier.id,
				backend: backendId,
				engine_version: byokProvider === 'tripo' ? tripoModelVersion() : undefined,
				prompt: prompt || null,
				preview_image_url: previewImageUrl,
				reference_image_urls: isImageMode ? [imageUrls[0]] : [],
				eta_seconds: estimateEtaSeconds({ backendId, tier }),
				estimated_credits: estimateCredits({ backendId, path, tier }),
			});
		}

			// ── Free NVIDIA NIM TRELLIS lane (platform-keyed; direct text→3D) ────────
			// TRELLIS on NIM emits the mesh natively from the prompt (no FLUX
			// intermediate view) and needs no BYOK key. It serves prompt submissions
			// on the image path as the free draft default; photo submissions never
			// resolve here (hosted preview is text-only: see the provider header).
			// The free NVIDIA NIM lane is a flaky synchronous upstream, NVCF can be
			// unreachable, accept the job but drop the request id, or finish with no
			// artifact, and a missing module/key throws on load. Per the free-first
			// "AI must never fail" policy none of these may surface as a dead 502: a
			// failure here transparently degrades to the platform image-intermediate
			// TRELLIS lane so the zero-setup free default still returns a model. Only
			// the unit cost changes, and only when NIM is down. Provenance reports the
			// lane that actually ran (trellis below), so the downgrade is never silent.
			if (backendId === 'nvidia') {
				nvidiaTried = true;
				// Skip the submit-timeout gamble when the lane is in a recent-failure
				// cooldown: go straight to the reconstruct lane instead of re-hanging.
				// BUT only when that reconstruct lane is a real destination: it free-firsts
				// to HuggingFace and then the paid Replicate account, so it's viable when HF
				// is configured OR the paid account isn't itself recorded out-of-credit. When
				// both are gone, skipping NIM would route straight into a dead paid lane and
				// 503 the user: so we ignore the cooldown and give the free lane a real shot.
				const cooldowns = await providersInCooldown([
					NIM_TRELLIS_COOLDOWN_KEY,
					REPLICATE_PAID_COOLDOWN_KEY,
				]);
				const trellisCooling = cooldowns.has(NIM_TRELLIS_COOLDOWN_KEY);
				const reconstructLaneViable =
					backendIsConfigured('huggingface') || !cooldowns.has(REPLICATE_PAID_COOLDOWN_KEY);
				if (trellisCooling && reconstructLaneViable) {
					console.warn('[forge] NVIDIA NIM TRELLIS lane in cooldown; routing to reconstruct lane');
					nimGatewayDegraded = true;
					backendId = 'trellis';
				} else if (await runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opts, cacheKey })) {
					return;
				} else {
					// nvidia failed → fall through to the image-intermediate TRELLIS path
					// below, which gives the prompt a second chance on Replicate. The NVCF
					// gateway is degraded, so the FLUX synthesis below skips its NIM lane too.
					nimGatewayDegraded = true;
					backendId = 'trellis';
				}
			}

			// ── Image-intermediate path (TRELLIS default, or Hunyuan3D self-host) ────
			// Hunyuan3D runs on its own Cloud Run worker (GCP_HUNYUAN3D_URL), never
			// the avatar pipeline controller, whose face pipeline fails every
			// non-face image with "no face detected".
			// Replicate BYOK runs the same reconstruction models on the caller's own
			// Replicate account: resolve their token up front (distinct from the
			// platform-keyed TRELLIS default).
			let byokReplicateKey = null;
			if (backendId === 'replicate_byok') {
				byokReplicateKey = await resolveProviderKey(req, body, 'replicate');
				if (!byokReplicateKey) return needsKey(res, backendId);
			}

			let provider;
			try {
				if (backendId === 'hunyuan3d') {
					// The gcp provider's `hunyuan` mode routes to GCP_HUNYUAN3D_URL
					// (workers/model-hunyuan3d, /infer + /tasks/:id); fail here only
					// so an unconfigured deployment gets the branchable 501 below.
					if (!process.env.GCP_HUNYUAN3D_URL) throw new Error('GCP_HUNYUAN3D_URL is not set');
					provider = createGcpProvider();
				} else if (backendId === 'replicate_byok') {
					provider = createRegenProvider({ apiToken: byokReplicateKey });
				} else if (backendId === 'huggingface') {
					// The free HF Spaces lane is driven by runHfImageLane() below, it
					// creates its own provider. We deliberately do NOT build a Replicate
					// client here: creating one would 503 on a deployment that has no
					// REPLICATE_API_TOKEN, breaking an explicitly-chosen free engine.
				} else if (isSelfHostImageLane(backendId)) {
					// Driven by the dedicated self-host image lane below, which builds
					// its own GCP provider. Same reasoning as huggingface, never build a
					// Replicate client here, or a deployment without REPLICATE_API_TOKEN
					// would 503 on an explicitly-chosen free self-hosted engine.
				} else {
					provider = createRegenProvider();
				}
			} catch {
				// A selected-but-unconfigured self-host backend gets a branchable 501;
				// the default TRELLIS path keeps its existing "not configured" 503.
				if (backendId === 'hunyuan3d') {
					return json(res, 501, {
						error: 'backend_unconfigured',
						backend: 'hunyuan3d',
						message: 'Hunyuan3D self-host is not configured on this deployment.',
					});
				}
				if (backendId === 'replicate_byok') return needsKey(res, backendId);
				// The default TRELLIS (Replicate) provider couldn't be built, no
				// REPLICATE_API_TOKEN. That alone is NOT "unconfigured" when the free
				// HuggingFace Spaces lane is live: a degraded-from-NVIDIA text prompt, or
				// a photo→3D request, must still reconstruct on the free lane rather than
				// dead-ending at a 503. Leave `provider` undefined and fall through, the
				// free-first HF block below serves it, and the `!provider` guard further
				// down raises a designed unavailable state only if every free lane is gone
				// too. Mirrors the self-host TRELLIS failover (provider = undefined) above.
				if (backendId === 'trellis' && backendIsConfigured('huggingface')) {
					provider = undefined;
				} else {
					return unconfigured(res);
				}
		}

		// In-flight coalescing: if an identical (path, tier, backend, prompt, images)
		// request is already generating, hand its job back instead of running the
		// whole FLUX→reconstruct pipeline a second time. Collapses double-clicks and
		// viral-prompt bursts to one generation that N clients poll. Skipped for high
		// tier (paid/gated per caller) so a payment is never shared across users.
		// `force_regenerate` has to skip the coalescing read as well as the result
		// cache read above, or it does not mean what it says: the in-flight record
		// outlives the generation it points at (TTL only, never cleared on success),
		// so within that window a "force a fresh run" submit was still handed the
		// previous job. That is what made the daily smoke test's force_regenerate
		// leg unable to prove generation was alive, and what stopped a user's Retry
		// from ever producing a different model. The hash is still COMPUTED so the
		// fresh job registers under it and later callers can coalesce onto this one.
		if (tier.id !== 'high') {
			requestHash = forgeRequestHash({
				path,
				tier: tier.id,
				backend: backendId,
				prompt,
				images: isImageMode ? imageUrls : null,
				options: opts,
			});
			const existing = forceRegenerate ? null : await coalesceInFlight(requestHash);
			if (existing) {
				return json(res, 200, {
					job_id: existing,
					status: 'queued',
					coalesced: true,
					mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
					path,
					tier: tier.id,
					backend: backendId,
					prompt: prompt || null,
					eta_seconds: estimateEtaSeconds({ backendId, tier }),
				});
			}
		}

		// Resolve the reference views: supplied directly (image→3D) or a single
		// view synthesized from the prompt (text→3D). `referenceImageUrl` is the
		// primary view: the durable preview + the synthesis target.
		let referenceImageUrl;
		// What we ECHO and STORE for the reference view, as opposed to what we send
		// the reconstructor. They differ in exactly one case: a storage outage makes
		// referenceImageUrl an inline data URI (see _lib/image-persist.js), which the
		// worker must receive and which must never reach the response body or the
		// forge_creations row, where a multi-megabyte base64 string would bloat every
		// poll payload and the database. Null there means "no durable preview", which
		// is the truth: nothing was parked.
		let reportableRefUrl = null;
		let textToImageModel;
		let views;
		// The prompt the art director actually handed to the reference painter, when
		// it differs from what the user typed. Surfaced on the response as
		// `directed_prompt` so /forge can show "what we actually asked the model"
		// instead of leaving the rewrite invisible. Null means the raw prompt was
		// used verbatim (director off, no rewrite, or the pass failed soft).
		let directedPrompt = null;
		if (isImageMode) {
			views = imageUrls;
			referenceImageUrl = imageUrls[0];
			reportableRefUrl = referenceImageUrl;
			textToImageModel = null;
		} else {
			// Granite art-director pass (on by default; pass director:false to skip):
			// rewrites the raw prompt into a richer, single-subject spec (form,
			// per-part PBR materials, photoreal-by-default cues, composition
			// constraints) before it drives the FLUX/Vertex reference image, the
			// same director the free MCP tools use. Fail-soft: any failure (chat
			// lane down, timeout) silently keeps the raw prompt, so running it by
			// default can only ever help, never break, a generation, and it rides
			// the free-first LLM chain, so it costs no GCP/vendor spend. This is the
			// single biggest lever on "does this look like a real photograph"
			// available before the reference image is even generated.
			let promptForReference = prompt;
			if (body?.director !== false) {
				// Known brand marks resolve deterministically before the LLM gets a
				// say: no model reliably knows a niche mark's geometry, and the
				// lexicon spec is already a tight single-subject description.
				const knownMark = resolveLogoPrompt(prompt);
				if (knownMark) {
					promptForReference = knownMark.prompt;
				} else {
					// Subject-classified briefing (person/animal/vehicle/food/architecture/
					// object) so the director reaches for the material/construction cues
					// that actually matter for THIS subject's failure mode.
					const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt).catch(
						() => null,
					);
					if (directed) promptForReference = directed;
				}
			}
			// Pose directive, appended AFTER the director rewrite so it survives
			// verbatim into the reference image. Baked into the synthesized image's
			// pixels, so it applies no matter which image-conditioned backend this
			// request ultimately lands on (including a later lane failover).
			if (opts.pose && poseControlFor(backendId)) {
				const poseText = poseDirective(opts.pose);
				if (poseText) {
					promptForReference = `${promptForReference}, ${poseText}`;
					poseApplied = true;
				}
			}
			// Report the rewrite only when it actually changed the brief, an
			// unchanged value means the model saw exactly what the user typed.
			if (promptForReference && promptForReference !== prompt) directedPrompt = promptForReference;
			// Milestone 1: the director pass is over. Crumb it before the (much
			// longer) image synthesis starts so the page can retire that stage and
			// show the real rewrite instead of holding it for the whole request.
			recordForgeProgress(progressId, 'directed', { directed_prompt: directedPrompt }).catch(() => {});
			// Seed the reconstruction reference from the dedicated Vertex-Gemini
			// photoreal module when it is live, so a text prompt reconstructs from the
			// most photoreal single view we can synthesize. Fail-open: an absent module
			// or a Vertex outage transparently falls back to the standing text→image
			// provider (FLUX/Imagen/NIM), so this path runs identically either way.
			const synthesized = await seedReferenceImage({
				prompt: promptForReference,
				aspect,
				skipNim: nimGatewayDegraded,
				seed: opts.seed ?? undefined,
			});
			referenceImageUrl = synthesized.imageUrl;
			textToImageModel = synthesized.model;
			views = [referenceImageUrl];
			reportableRefUrl = isInlineImageRef(referenceImageUrl) ? null : referenceImageUrl;
			// The reference view came back inline because object storage refused to
			// park it (see _lib/image-persist.js). Our own GPU workers decode a data
			// URI, so those lanes carry on untouched; a third-party reconstructor
			// fetches a URL and cannot, so it is refused here with the actual cause
			// rather than being handed a data URI it will reject opaquely. Before
			// this branch existed the storage error escaped raw, and every text→3D
			// caller was told to "check your secret access key and signing method".
			if (isInlineImageRef(referenceImageUrl) && !backendAcceptsInlineViews(backendId)) {
				return json(res, 503, {
					error: 'storage_unavailable',
					message:
						'Our image storage is not accepting writes right now, so this engine cannot be given the reference view. Try again on the free built-in engine, or retry shortly.',
					backend: backendId,
					retryable: true,
					retry_backends: retryBackendSuggestions({ attempted: [backendId], hasImage: false, country }).filter(
						backendAcceptsInlineViews,
					),
				});
			}
			// Milestone 2: the reference view exists. This is the one the user is
			// really waiting to see, and it is now minutes-fresh rather than
			// arriving with the job id at the end of the request.
			recordForgeProgress(progressId, 'reference', {
				preview_image_url: reportableRefUrl,
				text_to_image_model: textToImageModel,
			}).catch(() => {});
		}

		// Multi-view conditioning: rotate the primary view (the caller's uploaded
		// photo, or the synthesized reference for a text prompt) into side + back
		// turnaround views (Vertex Gemini edit lane) so the self-host TRELLIS
		// worker fuses real coverage instead of hallucinating the subject's unseen
		// sides. A single-photo upload used to skip this and shipped with a
		// smeared, hollowed-out back for exactly that reason; text prompts always
		// had it. Only the fusing lane benefits (every other reconstruct lane
		// conditions on the primary view alone), draft keeps its single-view
		// speed, and a caller who supplied multiple calibrated views keeps exactly
		// those. Best-effort: a failed view just means fewer views, never a
		// failed generation.
		// An inline reference view (storage outage) is skipped here on purpose: the
		// turnaround lane edits an image it fetches by URL, so it can only fail, and
		// paying a Vertex round trip to learn that would just slow the one path still
		// able to deliver a mesh. Single-view reconstruction still runs.
		if (
			backendId === 'trellis_selfhost' &&
			tier.id !== 'draft' &&
			views.length === 1 &&
			!isInlineImageRef(referenceImageUrl)
		) {
			const turnaround = await synthesizeTurnaroundViews(referenceImageUrl).catch(() => []);
			if (turnaround.length) views = [...views, ...turnaround];
		}
		// Milestone 3: every view the reconstructor will fuse now exists, so the
		// remaining wait is the GPU itself. Only crumbed when the lane actually
		// painted extra views, so a single-view lane never shows a stage it skipped.
		if (views.length > 1) {
			recordForgeProgress(progressId, 'views', { view_count: views.length }).catch(() => {});
		}
		// Milestone 4: every image the reconstructor needs is in the bucket and the
		// request is handing the job to a GPU lane. Everything after this point is
		// the engine's own queued/running reporting, which the page already polls.
		recordForgeProgress(progressId, 'submitting', {}).catch(() => {});

		// Explicitly chosen free HuggingFace lane. Unlike the trellis free-first
		// path below: which degrades to the paid Replicate lane when the free
		// Spaces are down: an explicit pick of the FREE engine must never silently
		// fall through to a paid lane: that would spend credits the user
		// deliberately opted out of. So we run the free Spaces and, if every one is
		// busy/down, return a designed error the UI can act on (retry / switch engine).
		//
		// Self-hosted TRELLIS image-to-3D lane (platform-keyed; native single-hop).
		// Our own Microsoft TRELLIS worker (workers/model-trellis) reconstructs a
		// textured mesh DIRECTLY from the primary reference view -- the user's photo,
		// or the FLUX-synthesized view for a text prompt -- with no vendor cost. This
		// is the native single-hop image-to-3D NVIDIA's hosted preview can't do (it
		// rejects user images); a self-deployed NIM accepts them. Async like the
		// sketch lane: returns a poll token that routes back through the gcp provider's
		// status(). Reached on an explicit pick OR as the preferred free image lane
		// (FREE_FALLBACK_FOR_PATH) when MODEL_TRELLIS_URL is configured.
		//
		// The Modly lanes (workers/modly: TripoSG, Hunyuan3D 2 Mini Turbo) ride the
		// same block. They are explicit picks or late free fallbacks, and when their
		// worker is down the request retries on TRELLIS.2, then TRELLIS v1.
		if (isSelfHostImageLane(backendId)) {
			let gcp;
			try {
				gcp = createGcpProvider();
			} catch {
				return json(res, 501, {
					error: 'backend_unconfigured',
					backend: backendId,
					message: `${selfHostLaneName(backendId)} is not configured on this deployment.`,
				});
			}

			let job;
			let selfHostTrellisFailed = false;
			// TRELLIS.2 leads; when it is unavailable the same request retries on the
			// TRELLIS v1 worker, which holds the same reference views. A Modly lane
			// retries on TRELLIS.2 first.
			for (;;) {
				try {
					job = await gcp.submit(MODLY_LANES.includes(backendId) ? {
						mode: backendId,
						sourceUrl: referenceImageUrl,
						params: {
							images: views,
							seed: opts.seed ?? undefined,
							// The worker maps the tier to its sampler budget and decimates
							// the mesh to this face count after a repair pass.
							tier: tier.id,
							target_polycount: opts.targetPolycount ?? tier.polycount,
						},
					} : backendId === 'trellis2' ? {
						mode: 'trellis2',
						sourceUrl: referenceImageUrl,
						params: {
							images: views,
							seed: opts.seed ?? undefined,
							// Voxel resolution: an explicit request value, else the worker maps
							// the tier (draft 512, standard and high 1024).
							resolution: opts.resolution ?? undefined,
							tier: tier.id,
							// Bake overrides. Absent, the resolution preset decides
							// (512: 2048 px and 300k faces, 1024 and 1536: 4096 px).
							texture_size: opts.textureSize ?? undefined,
							decimation_target: opts.targetPolycount ?? undefined,
						},
					} : backendId === 'pixal3d' ? {
						mode: 'pixal3d',
						sourceUrl: referenceImageUrl,
						params: {
							// Unlike every other lane above, Pixal3D actually fuses every view
							// in this array (up to 4) instead of reading the first one alone,
							// the whole point of the "Match my photo" lane. view_labels tags
							// each entry front/back/left/right; omitted, the worker infers the
							// front view from the camera estimator. fill_other_sides asks it to
							// synthesize the other three sides from a single photo instead.
							images: views,
							view_labels: opts.viewLabels ?? undefined,
							fill_other_sides: opts.fillOtherSides || undefined,
							seed: opts.seed ?? undefined,
							// Voxel resolution: an explicit request value (1024 or 1536), else
							// the worker maps the tier (draft/standard 1024, high/max 1536).
							resolution: opts.resolution ?? undefined,
							tier: tier.id,
							texture_size: opts.textureSize ?? undefined,
							decimation_target: opts.targetPolycount ?? undefined,
						},
					} : backendId === 'anigen' ? {
						mode: 'anigen',
						sourceUrl: referenceImageUrl,
						params: {
							// The worker reads only the first view; it predicts mesh, joint
							// skeleton and skin weights together, so the result needs no
							// separate rerig call.
							images: views,
							seed: opts.seed ?? undefined,
						},
					} : backendId === 'partcrafter' ? {
						mode: 'partcrafter',
						sourceUrl: referenceImageUrl,
						params: {
							// The worker reads only the first view; it decodes N named
							// part nodes in a single pass, ready for Restyle Studio's
							// per-part edit flow with no separate segmentation call.
							images: views,
							num_parts: opts.numParts ?? undefined,
							seed: opts.seed ?? undefined,
						},
					} : {
						mode: 'trellis',
						sourceUrl: referenceImageUrl,
						params: {
							images: views,
							seed: opts.seed ?? undefined,
							// Tier-scaled sampler/export budgets: this is where standard/high
							// actually buy more quality on our own GPU (steps, kept geometry,
							// texture resolution) instead of only a bigger advertised polycount.
							quality: selfhostQualityForTier(tier.id),
							// Background pre-matting via the worker's sibling rembg service
							// (RMBG-2/isnet). A busy background (the classroom behind the
							// subject) separates poorly in TRELLIS's internal cutout and bleeds
							// into the fused geometry; a clean alpha cutout of every view before
							// fusion removes that.
							//
							// This used to be gated to real user photos, on the reasoning that a
							// text→3D reference is "already synthesized on a plain background".
							// Measured on 2026-09-08, that premise is false: plain is not
							// transparent, and the reconstruction happily fuses the plain
							// backdrop in as geometry. Six text personas rendered through this
							// exact path produced a figure standing on a full-footprint slab of
							// reconstructed backdrop in four of six cases, twice losing the
							// figure entirely (bbox 0.966 x 0.01 x 1: a bare plane, no person).
							// Evidence: prompts/quality-bar/_generated/10/pass-2026-09-08/.
							// So text→3D gets the same cutout; draft stays fast (single view,
							// no matte). Worker-side it is best-effort either way: a rembg miss
							// falls back to the original image, never failing the generation.
							matte: tier.id !== 'draft',
						},
					});
				} catch (err) {
					if (err?.code === 'mode_unconfigured') {
						return json(res, 501, {
							error: 'backend_unconfigured',
							backend: backendId,
							message:
								`${selfHostLaneName(backendId)} is not configured on this deployment (the worker URL is not set).`,
						});
					}
					// A genuine config/input fault surfaces as-is. An upstream blip (the
					// worker is cold, restarting, throttled, or briefly unreachable) must
					// not fail a request another lane can serve: cool this lane so the next
					// request skips it, then fail over below to our other self-host worker
					// (Hunyuan3D) or the standing reconstruct chain (which free-firsts to HF
					// and only then the paid lane). We already hold the reference views, so
					// the next lane reconstructs from exactly the same input.
					if (!isUpstreamUnavailable(err)) throw err;
					await markLaneUnhealthy(backendId);
					console.warn(
						`[forge] self-host ${backendId} lane unavailable (${err?.providerStatus || err?.code}); failing over to the next image lane`,
					);
					const nextLane = nextSelfHostImageLane(backendId);
					if (nextLane) {
						backendId = nextLane;
						continue;
					}
					selfHostTrellisFailed = true;
				}
				break;
			}

			if (!selfHostTrellisFailed) {
				// Wrap the gcp job envelope in a forge token so polling routes back to the
				// gcp provider -- same idiom as the sketch and Hunyuan3D lanes.
				const token = encodeJobToken({ provider: 'gcp', kind: null, taskId: job.extJobId });
				const clientKey = clientKeyFrom(req);
				const creationId = await createCreation({
					clientKey,
					userId: await sessionUserIdFromReq(req),
					ipHash: hashIp(ip),
					prompt: prompt || (isImageMode ? 'image-to-3d' : ''),
					aspect: isImageMode ? null : aspect,
					previewImageUrl: reportableRefUrl,
					replicateJobId: job.extJobId,
					textToImageModel: isImageMode ? null : textToImageModel,
					viewsRequested: views.length,
					viewsUsed: job.viewsUsed ?? views.length,
					multiview: views.length > 1,
					sourceImageUrls: views,
					backend: backendId,
					tier: tier.id,
					path,
				});
				if (cacheKey) await bindJobToCacheKey(token, cacheKey);
				await bindJobToOptions(token, opts);

				const cold = await coldStartFor(backendId);
				return json(res, 200, {
					job_id: token,
					creation_id: creationId,
					status: 'queued',
					mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
					path,
					tier: tier.id,
					backend: backendId,
					prompt: prompt || null,
					directed_prompt: directedPrompt,
					preview_image_url: reportableRefUrl,
					reference_image_urls: views,
					text_to_image_model: isImageMode ? null : textToImageModel,
					cold_start: cold,
					cold_start_seconds: cold ? coldStartSecondsFor(backendId) : undefined,
					options: opts.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,
					eta_seconds: estimateEtaSeconds({ backendId, tier, cold }),
					estimated_credits: estimateCredits({ backendId, path, tier }),
				});
			}

			// Fail over from the down self-host TRELLIS worker. Prefer our other
			// self-host GPU lane (Hunyuan3D) when it's wired; otherwise hand off to the
			// standing reconstruct chain (backend 'trellis'), which free-firsts to the
			// HuggingFace Spaces lane and only then the paid Replicate account. Falls
			// through (no return) into the lane blocks below; provenance reports the
			// lane that actually runs, so the failover is never silent.
			if (
				process.env.GCP_HUNYUAN3D_URL &&
				process.env.GCP_RECONSTRUCTION_KEY &&
				laneAllowedInTerritory('hunyuan3d', country)
			) {
				backendId = 'hunyuan3d';
				provider = createGcpProvider();
			} else {
				backendId = 'trellis';
				try {
					provider = createRegenProvider();
				} catch {
					provider = undefined;
				}
			}
		}

		if (backendId === 'huggingface') {
			if (
				await runHfImageLane({
					req,
					res,
					ip,
					imageUrls: views,
					prompt,
					aspect,
					tier,
					path,
					mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
					previewImageUrl: reportableRefUrl,
					textToImageModel,
					directedPrompt,
					opts,
					cacheKey,
					poseApplied,
				})
			)
				return;
			// Failover instead of a dead end: see laneAfterHfFailure for why an
			// auto-routed request lands here while our own GPU worker is healthy.
			const nextLane = laneAfterHfFailure({ explicit: backendExplicit, userImages: isImageMode, country });
			if (nextLane === 'hunyuan3d') {
				console.warn('[forge] free HuggingFace lane could not serve this request; failing over to self-hosted Hunyuan3D');
				backendId = 'hunyuan3d';
				provider = createGcpProvider();
			} else if (nextLane === 'nvidia' && !nvidiaTried) {
				nvidiaTried = true;
				console.warn('[forge] free HuggingFace lane could not serve this request; failing over to free NVIDIA NIM');
				if (await runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opts, cacheKey })) return;
			}
			if (backendId === 'huggingface') {
				return hfLaneBusy(res, country);
			}
		}

		// Free-first: exhaust the free reconstruct lane (HuggingFace Spaces) BEFORE
		// the paid Replicate default, so a forge call never spends on, or dead-ends
		// against: the paid account while a free lane can serve it. We already hold
		// the reference views (uploaded, or FLUX-synthesized above), so the free lane
		// reconstructs from exactly what Replicate would have. Scoped to the default
		// trellis lane: an explicitly chosen Hunyuan3D / Replicate-BYOK backend is
		// honored as picked. When the free lane is unavailable (no HF_TOKEN) or it
		// fails, we fall through to Replicate, which keeps its own fallback chain.
		// Reversible via FORGE_PREFER_FREE=false. Provenance reports backend:huggingface
		// so the chosen lane is never silent.
		if (preferFreeReconstruct() && backendId === 'trellis') {
			if (
				await runHfImageLane({
					req,
					res,
					ip,
					imageUrls: views,
					prompt,
					aspect,
					tier,
					path,
					mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
					previewImageUrl: reportableRefUrl,
					textToImageModel,
					directedPrompt,
					opts,
					cacheKey,
					poseApplied,
				})
			)
				return;
		}

		// Only poly-aware backends (Hunyuan3D self-host) accept a target budget;
		// TRELLIS validates its input schema and would 422 on an unknown field, so
		// the tier rides along as the recorded provenance only. `seed` is a
		// recognized generation param across the TRELLIS family and Hunyuan3D
		// alike (survives stripInternal() and overrides the provider's own
		// default), so it's forwarded unconditionally, not gated on polyControl.
		const reconstructParams = { images: views, prompt: prompt || undefined };
		if (opts.seed !== null) reconstructParams.seed = opts.seed;
		if (BACKENDS[backendId].polyControl) {
			reconstructParams.target_polycount = opts.targetPolycount ?? tier.polycount;
			reconstructParams.tier = tier.id;
			reconstructParams.path = path;
			if (opts.textureSize) reconstructParams.texture_size = opts.textureSize;
		}

		let job;
		try {
			// A self-host failover landed here with no paid provider configured (no
			// REPLICATE_API_TOKEN) and the free HF lane above didn't serve the request
			//: there is no reconstruct lane left. Raise it as upstream-unavailable so
			// the catch below runs the remaining free fallbacks (Hunyuan3D → HF) and,
			// if those are gone too, surfaces a designed unavailable state.
			if (!provider) {
				throw Object.assign(new Error('no reconstruct lane configured'), {
					code: 'provider_unreachable',
					status: 502,
				});
			}
			// Per-provider submit throttle: shed platform Replicate bursts to the free
			// lane BEFORE they hit the account quota and turn into fleet-wide 429s. Only
			// the platform-keyed default lane is capped: BYOK lanes spend the caller's
			// own quota. Over-cap is thrown as upstream-unavailable so the existing
			// fallback chain (self-host Hunyuan3D → free HuggingFace) absorbs it.
			if (
				backendId === 'trellis' &&
				!(await providerSubmitAllowed('replicate', {
					limit: SCALE_LIMITS.replicateSubmitLimit,
					windowS: SCALE_LIMITS.replicateSubmitWindowS,
				}))
			) {
				console.warn('[forge] platform Replicate submit throttle hit; shedding to free lane');
				throw Object.assign(new Error('platform submit throttle'), {
					code: 'rate_limited',
					providerStatus: 429,
				});
			}
			job = await provider.submit({
				// The self-host Hunyuan3D worker speaks the standard /infer +
				// /tasks/:id task shape (gcp provider mode 'hunyuan'), not the
				// avatar controller's /reconstruct + /jobs/:id contract.
				mode: backendId === 'hunyuan3d' ? 'hunyuan' : 'reconstruct',
				sourceUrl: referenceImageUrl,
				params: reconstructParams,
			});
		} catch (submitErr) {
			// Free fallback chain when the default TRELLIS lane (Replicate) is
			// over-quota or unreachable. Covers two modes:
			//   • image→3D: user photos can't fall to the text NIM lane (it's
			//     text-only), so we need a reconstruct-capable fallback here.
			//   • text→3D via NVIDIA fallback: NIM failed first (nvidiaTried=true),
			//     TRELLIS was the second attempt; we already have a synthesized
			//     referenceImageUrl from textToImage(), so the same reconstruct
			//     fallbacks apply. Without this branch the outer catch re-checks
			//     nvidiaTried=true and skips NIM, leaving the user with a 429.
			// Scoped to the default trellis backend only: an explicitly chosen
			// Hunyuan3D / BYOK backend that fails surfaces its own error. Provenance
			// always reports the lane that actually ran so any downgrade is visible.
			const upstreamGone =
				backendId === 'trellis' &&
				isUpstreamUnavailable(submitErr) &&
				(isImageMode || referenceImageUrl != null);
			if (!upstreamGone) throw submitErr;

			const mode3d = isImageMode ? 'image→3D' : 'text→3D (via synthesized image)';

			// Fallback #1: self-hosted TRELLIS Cloud Run worker (workers/model-trellis),
			// when wired and not cooled. FREE_FALLBACK_FOR_PATH prefers it first among
			// the free image lanes, so this paid-lane failover walks the same order:
			// our own GPU (zero vendor cost) before any external free allocation. It
			// reconstructs single-hop from the referenceImageUrl we already hold.
			if (backendIsConfigured('trellis_selfhost')) {
				let selfHostUsable = true;
				try {
					const snap = await laneHealthSnapshot(['trellis_selfhost']);
					selfHostUsable = snap.byId.trellis_selfhost?.status !== 'down';
				} catch {
					// No telemetry → try the lane anyway; the submit catch below cools it.
				}
				if (selfHostUsable) {
					console.warn(
						`[forge] platform TRELLIS lane unavailable (${submitErr?.providerStatus || submitErr?.code}); degrading ${mode3d} to self-hosted TRELLIS`,
					);
					try {
						const gcp = createGcpProvider();
						job = await gcp.submit({
							mode: 'trellis',
							sourceUrl: referenceImageUrl,
							params: {
								images: views,
								seed: opts.seed ?? undefined,
								quality: selfhostQualityForTier(tier.id),
							},
						});
						backendId = 'trellis_selfhost';
						provider = gcp;
					} catch (selfErr) {
						// A config/input fault surfaces as-is; an upstream blip cools the
						// lane and falls through to the remaining reconstruct fallbacks.
						if (!isUpstreamUnavailable(selfErr)) throw selfErr;
						await markLaneUnhealthy('trellis_selfhost');
						console.warn(
							`[forge] self-host TRELLIS fallback unavailable (${selfErr?.providerStatus || selfErr?.code}); trying the next image lane`,
						);
					}
				}
			}

			// Fallback #2: self-hosted Hunyuan3D Cloud Run worker, when wired.
			const hunyuanUrl = process.env.GCP_HUNYUAN3D_URL;
			if (!job && hunyuanUrl && process.env.GCP_RECONSTRUCTION_KEY && laneAllowedInTerritory('hunyuan3d', country)) {
				console.warn(
					`[forge] platform TRELLIS lane unavailable (${submitErr?.providerStatus || submitErr?.code}); degrading ${mode3d} to self-hosted Hunyuan3D`,
				);
				backendId = 'hunyuan3d';
				provider = createGcpProvider();
				// Hunyuan3D is poly-aware: supply the tier budget the TRELLIS params omit.
				reconstructParams.target_polycount = opts.targetPolycount ?? tier.polycount;
				reconstructParams.tier = tier.id;
				reconstructParams.path = path;
				if (opts.textureSize) reconstructParams.texture_size = opts.textureSize;
				job = await provider.submit({
					mode: 'hunyuan',
					sourceUrl: referenceImageUrl,
					params: reconstructParams,
				});
			} else if (!job) {
				// Fallback #3: free Hugging Face Spaces image→3D (gated on HF_TOKEN).
				// It blocks and writes its own status:'done' response; if it does, the
				// request is complete. Otherwise fall through to surface the real error.
				// For text mode, views=[referenceImageUrl] (the FLUX-synthesized image).
				console.warn(
					`[forge] platform TRELLIS lane unavailable (${submitErr?.providerStatus || submitErr?.code}); trying free HuggingFace ${mode3d} lane`,
				);
				if (
					await runHfImageLane({
						req,
						res,
						ip,
						imageUrls: views,
						prompt,
						aspect,
						tier,
						path,
						mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
						previewImageUrl: reportableRefUrl,
						textToImageModel,
						directedPrompt,
						opts,
						cacheKey,
						poseApplied,
					})
				) {
					return;
				}
				throw submitErr;
			}
		}

		// How the job was actually conditioned. The provider reports back which
		// backend handled it and how many views it fused: these can differ from
		// what was requested when a single-view model is configured and we fall
		// back to the primary view. Surfaced so a downgrade is never silent.
		const viewsRequested = views.length;
		const viewsUsed = typeof job.viewsUsed === 'number' ? job.viewsUsed : viewsRequested;
		const multiview = Boolean(job.multiview);

		// TRELLIS returns a bare Replicate prediction id (kept as the job handle
		// for backward compatibility); the GCP/Hunyuan3D provider returns its own
		// opaque envelope, which we wrap in a forge token so polling routes back to
		// the GCP provider. Replicate BYOK uses the same bare id but a distinct
		// token tag so polling re-resolves the caller's key (not the platform one).
		// Either way the upstream id is what the store keys on.
		const jobHandle =
			backendId === 'hunyuan3d' || isSelfHostImageLane(backendId)
				? encodeJobToken({ provider: 'gcp', kind: null, taskId: job.extJobId })
				: backendId === 'replicate_byok'
					? encodeJobToken({ provider: 'replicate_byok', kind: null, taskId: job.extJobId })
					: job.extJobId;

		// Record the generation the moment it starts so the prompt + reference
		// image survive even if the mesh step later fails. Fail-soft: a missing
		// store just means no durable copy + no gallery entry for this run.
		const creationId = await createCreation({
			clientKey: clientKeyFrom(req),
			userId: await sessionUserIdFromReq(req),
			ipHash: hashIp(ip),
			prompt: prompt || (isImageMode ? 'image-to-3d' : ''),
			aspect,
			previewImageUrl: reportableRefUrl,
			replicateJobId: job.extJobId,
			textToImageModel,
			viewsRequested,
			viewsUsed,
			multiview,
			sourceImageUrls: views,
			backend: backendId,
			tier: tier.id,
			path,
		});

		// Publish this job as the canonical handle for its fingerprint so identical
		// requests in the next few minutes coalesce onto it instead of re-running the
		// GPU pipeline. First writer wins; best-effort (no-op without Redis).
		await registerInFlight(requestHash, jobHandle);
		// Cache-eligibility was fixed before any lane failover reassigned backendId;
		// a BYOK pick already disqualified it above, so it's always safe to bind
		// here for whichever platform lane actually ran.
		if (cacheKey) await bindJobToCacheKey(jobHandle, cacheKey);
		await bindJobToOptions(jobHandle, opts);

		// Honest cold-start: only a self-host worker reached cold widens the ETA
		// (a paid/external lane returns false). Covers the Hunyuan3D self-host
		// fallback this block serves after a self-host TRELLIS failover.
		const cold = await coldStartFor(backendId);
		return json(res, 200, {
			job_id: jobHandle,
			creation_id: creationId,
			status: 'queued',
			mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
			path,
			tier: tier.id,
			backend: backendId,
			prompt: prompt || null,
			directed_prompt: directedPrompt,
			preview_image_url: reportableRefUrl,
			reference_image_urls: views,
			views_requested: viewsRequested,
			views_used: viewsUsed,
			multiview,
			text_to_image_model: textToImageModel,
			cold_start: cold,
			cold_start_seconds: cold ? coldStartSecondsFor(backendId) : undefined,
			options: opts.hasOptions ? summarizeForgeOptions(opts, { poseApplied }) : undefined,
			eta_seconds: estimateEtaSeconds({ backendId, tier, cold }),
			estimated_credits: estimateCredits({ backendId, path, tier }),
		});
	} catch (err) {
		if (err?.code === 'unconfigured') return unconfigured(res);
		if (err?.code === 'invalid_key') {
			return json(res, 401, {
				error: 'invalid_key',
				message: err.message || 'The provider rejected this API key.',
			});
		}
		if (err?.code === 'insufficient_credits' && BACKENDS[backendId]?.byok && !usingTripoHouseKey) {
			// BYOK lane: the message names the CALLER'S own provider account, which
			// they can act on: surface it. The house-key Tripo lane and the platform's
			// own paid lane both fall through to the sanitized "temporarily
			// unavailable" state below, since it's the PLATFORM's account that's out
			// of credits, not the caller's: naming it here would be misleading.
			return json(res, 402, {
				error: 'insufficient_credits',
				message: err.message || 'The provider account is out of credits.',
			});
		}
		// Last-resort free fallback: when the paid image-intermediate TRELLIS lane
		// (Replicate) is throttled, over-quota, unreachable, OR out of credit, a text
		// prompt must never dead-end: degrade to the free NVIDIA NIM lane so the
		// default "type a prompt → get a model" flow always returns something. The
		// credit-exhaustion case matters most here: the failure is the paid FLUX
		// synthesis step (textToImage throws code:'billing'/402, which is NOT
		// upstream-unavailable), but the NIM TRELLIS lane is native text→mesh and
		// needs no FLUX intermediate at all: so a dry Replicate account should hand
		// the prompt to the healthy free lane rather than skip straight to the 503.
		// Honors the free-first "AI must never fail" policy; provenance reports
		// backend:nvidia so the downgrade is visible, not silent. Image uploads have
		// no free reconstruct fallback here (NVCF is text-only, the HF lane already
		// absorbed them above), so they fall through to the designed states below.
		// `nvidiaTried` guards against re-running a lane that already failed this
		// request (the draft nvidia→trellis→nvidia loop).
		if (
			(isUpstreamUnavailable(err) || isPaidCreditFailure(err)) &&
			!isImageMode &&
			!nvidiaTried &&
			prompt
		) {
			nvidiaTried = true;
			// Don't degrade to NIM when it's already in a recent-failure cooldown, that
			// would just re-pay the submit timeout on a lane we know is down right now.
			const trellisCooling = (await providersInCooldown([NIM_TRELLIS_COOLDOWN_KEY])).has(
				NIM_TRELLIS_COOLDOWN_KEY,
			);
			if (!trellisCooling) {
				console.warn(
					`[forge] paid TRELLIS lane unavailable (${err?.providerStatus || err?.code}); degrading text→3D to free NVIDIA NIM`,
				);
				try {
					if (await runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, opts, cacheKey })) return;
				} catch (fallbackErr) {
					console.warn(`[forge] NVIDIA NIM fallback also failed: ${fallbackErr?.message || fallbackErr}`);
				}
			}
		}

		// Upstream throttling is a transient 429, not a server fault, return it as
		// such with a retry hint so the page can show a "busy, try again" state.
		if (err?.code === 'rate_limited' || err?.providerStatus === 429) {
			const retryAfter = typeof err?.retryAfter === 'number' ? err.retryAfter : 10;
			res.setHeader('retry-after', String(retryAfter));
			// A `queued` throttle is our own rate gate pacing the request to the
			// upstream limit (not an upstream rejection): tell the user it's in line so
			// a retry reads as "your turn is coming up", not "the system is failing".
			const queued = Boolean(err?.queued);
			return json(res, 429, {
				error: 'rate_limited',
				queued,
				message: queued
					? `Your generation is queued behind a few others: retry in ~${retryAfter}s to pick it up.`
					: 'The 3D generator is busy right now. Try again in a few seconds.',
				retry_after: retryAfter,
			});
		}
		// Free lanes are exhausted and the only remaining lane was the platform's
		// PAID vendor account, which is out of credit. The vendor's raw "buy credit"
		// message is our internal billing state and is useless to the user, answer
		// with an honest, generic unavailable state instead of leaking it. (BYOK lanes
		// kept their actionable account message via the insufficient_credits branch.)
		if (!BACKENDS[backendId]?.byok && isPaidCreditFailure(err)) {
			const creditDetail = err?.providerDetail ? `: vendor: ${err.providerDetail}` : '';
			console.warn(
				`[forge] paid reconstruct lane out of credit and no free lane available: ${err?.message || err}${creditDetail}`,
			);
			// Record the paid lane as down (reason 'auth': a billing fault that won't
			// self-heal until ops tops the account up). The NIM-cooldown router reads this
			// so the next text prompt keeps the free NIM lane in play instead of skipping
			// it to route into this now-known-dead paid lane.
			markProviderCooldown(
				REPLICATE_PAID_COOLDOWN_KEY,
				REPLICATE_PAID_COOLDOWN_SECONDS,
				'auth',
			).catch(() => {});
			res.setHeader('retry-after', '30');
			return json(res, 503, {
				error: 'generation_unavailable',
				message: 'Free 3D generation is temporarily unavailable. Please try again shortly.',
				retry_after: 30,
			});
		}
		// Object storage rejected us (a rotated/whitespace-padded credential, or an
		// unreachable endpoint). Nothing about the prompt is wrong and no lane
		// failover can route around it: every lane has to park a reference image or
		// a finished mesh in the bucket. Answer with the designed unavailable state
		// instead of forwarding the store's raw signing complaint, which read as
		// "Check your secret access key" in the user's browser on 2026-09-07.
		if (isStorageInfrastructureError(err)) {
			console.error(`[forge] object storage rejected the generation: ${err?.message || err}`);
			res.setHeader('retry-after', '60');
			return json(res, 503, {
				error: 'storage_unavailable',
				message: '3D generation is temporarily unavailable while our asset storage recovers. Please try again shortly.',
				retry_after: 60,
			});
		}
		return json(res, 502, {
			error: 'generation_failed',
			message: err?.message || 'The generator could not start this job.',
		});
	} finally {
		// A claimed pay-per-use payment that did NOT deliver a model, any non-2xx
		// exit (validation 4xx, unconfigured 5xx, provider failure), is released so
		// the settled $THREE payment stays reusable on retry. A successful job (200)
		// keeps the claim, so one payment can never buy a second generation.
		if (paidHigh?.redeemed && res.statusCode >= 400) {
			await releaseForgePayment({ paymentId: paidHigh.paymentId }).catch(() => {});
		}
		// A charged prepaid generation that did NOT deliver (any non-2xx exit) is
		// refunded so credits are never spent on a failed job.
		if (creditsCharge?.ledgerId && creditsCharge.chargedUsd > 0 && res.statusCode >= 400) {
			await refundCredits({
				userId: creditsCharge.user.id,
				amountUsd: creditsCharge.chargedUsd,
				action: creditsCharge.action,
				refType: 'forge',
				refId: creditsCharge.ref,
				idempotencyKey: `forge:credits:refund:${creditsCharge.ledgerId}`,
				meta: { reason: 'generation_failed' },
			}).catch(() => {});
		}
	}
}

// Auto-rig an existing GLB mesh: skeleton + skin weights via the provider's
// `rerig` mode (VAST-AI UniRig by default). Takes a GLB URL, returns a job id
// that polls through the same GET ?job=<id> path: provider.status() is
// mode-agnostic, so the rigged GLB surfaces exactly like a reconstruction.
async function startRigJob(req, res) {
	const ip = clientIp(req);
	const rl = await limits.mcp3dGenerate(ip);
	if (!rl.success) {
		return rateLimited(res, rl, 'Rigging limit reached. Try again shortly.');
	}

	const body = await readJson(req, 8_000).catch(() => null);
	const glbUrl = typeof body?.glb_url === 'string' ? body.glb_url.trim() : '';
	if (!HTTP_URL_RE.test(glbUrl) || glbUrl.length > 2048) {
		return json(res, 400, {
			error: 'invalid_glb_url',
			message: 'glb_url must be an http(s) URL to a GLB mesh, under 2048 characters.',
		});
	}

	// Prefer the self-hosted GCP UniRig pipeline when it's configured, it supports
	// rerig out of the box via its /rig endpoint: and fall back to Replicate when
	// a REPLICATE_RERIG_MODEL is set. Mirrors the gcp-first resolution the MCP
	// studio path uses, so rigging works whenever ANY rerig-capable lane exists,
	// not only when the highest-precedence provider happens to be the rigger.
	let provider = null;
	let providerName = 'replicate';
	if (process.env.GCP_RECONSTRUCTION_KEY) {
		try {
			const gcp = createGcpProvider();
			if (gcp.supportsMode('rerig')) {
				provider = gcp;
				providerName = 'gcp';
			}
		} catch {
			// fall through to Replicate
		}
	}
	if (!provider) {
		try {
			const rep = createRegenProvider();
			if (rep.supportsMode('rerig')) {
				provider = rep;
				providerName = 'replicate';
			}
		} catch {
			return unconfigured(res);
		}
	}

	// Rigging stays dormant until a rerig lane is configured, surface a clean
	// 501 rather than a generic provider error so callers can branch on it.
	if (!provider) {
		return json(res, 501, {
			error: 'rig_unconfigured',
			message:
				'Auto-rigging is not configured on this deployment (set GCP_RECONSTRUCTION_URL + GCP_RECONSTRUCTION_KEY, or REPLICATE_RERIG_MODEL).',
		});
	}

	// Rigging runs on platform-paid GCP/Replicate capacity, so it needs the same
	// breakers as the paid reconstruction lanes (startJobWithBody): the per-IP cap
	// above is bypassed by rotating IPs, the global hourly ceiling and the
	// per-client daily ceiling are not.
	const globalRl = await limits.mcp3dGenerateGlobal();
	if (!globalRl.success) {
		return rateLimited(res, globalRl, 'Rigging is at capacity right now. Try again shortly.');
	}
	const daily = await dailyPaidAllowed(clientKeyFrom(req), {
		limit: SCALE_LIMITS.paidDailyPerClient,
	});
	if (!daily.ok) {
		return json(res, 429, {
			error: 'daily_limit_reached',
			message: 'You’ve reached today’s limit for paid generations. Try again tomorrow.',
		});
	}

	try {
		const job = await provider.submit({ mode: 'rerig', sourceUrl: glbUrl, params: {} });
		// GCP rig jobs poll through a token-encoded handle so /api/forge?action=status
		// routes back to the GCP worker; Replicate jobs use the bare prediction id.
		const jobToken =
			providerName === 'gcp'
				? encodeJobToken({ provider: 'gcp', kind: null, taskId: job.extJobId })
				: job.extJobId;
		const creationId = await createCreation({
			clientKey: clientKeyFrom(req),
			userId: await sessionUserIdFromReq(req),
			ipHash: hashIp(ip),
			prompt: 'auto-rig',
			aspect: null,
			previewImageUrl: null,
			replicateJobId: job.extJobId,
			textToImageModel: null,
		});
		return json(res, 200, {
			job_id: jobToken,
			creation_id: creationId,
			status: 'queued',
			mode: 'rig',
			source_glb_url: glbUrl,
			eta_seconds: typeof job.eta === 'number' ? job.eta : null,
		});
	} catch (err) {
		if (err?.code === 'mode_unconfigured') {
			return json(res, 501, { error: 'rig_unconfigured', message: err.message });
		}
		if (err?.code === 'rate_limited' || err?.providerStatus === 429) {
			res.setHeader('retry-after', '10');
			return json(res, 429, {
				error: 'rate_limited',
				message: 'The rigger is busy right now. Try again in a few seconds.',
				retry_after: 10,
			});
		}
		return json(res, 502, {
			error: 'rig_failed',
			message: err?.message || 'The rigger could not start this job.',
		});
	}
}

// ── NVCF poll robustness ─────────────────────────────────────────────────────
// NVCF pexec results are consume-once: the FIRST status GET that lands after
// completion receives the artifact and every later GET for that request id
// 404s. Two production consequences (53 of 134 nvidia jobs in one 36h window
// failed with "NVCF request not found or expired"):
//   1. Concurrent polls for the same job (overlapping browser timers, a second
//      tab, a retried request) race: one consumes the result, the other 404s
//      and flips the creation to failed even though the mesh exists.
//   2. A result that expires out of NVCF's retention window (throttled
//      background tab, closed laptop) is genuinely gone.
// Recovery below: single-flight the upstream poll per task id so only one
// request ever touches NVCF at a time; on a 404, first re-check the store for
// a completion a racing poll already materialized, then, because the prompt
// is recorded on the creation row: resubmit the SAME generation once and
// alias the old task id to the new one so the client's existing poll handle
// keeps working. The alias lives in the shared cache; the creation row keeps
// its original replicate_job_id, so findByJob/materializeCreation are untouched.
const NVCF_ALIAS_TTL_S = 3600;
const NVCF_POLL_LOCK_TTL_S = 70; // > provider poll timeout (60s) so a dead holder can't wedge the job

function nvcfAliasKey(taskId) {
	return `nvcf:alias:${taskId}`;
}

async function pollNvidiaStatus({ nv, upstreamId, clientKey }) {
	// A previous recovery may have resubmitted this job under a new NVCF id.
	const alias = await cacheGet(nvcfAliasKey(upstreamId)).catch(() => null);
	const taskId = typeof alias === 'string' && alias ? alias : upstreamId;

	// Single-flight across instances: whoever loses the race reports running and
	// lets the client's next poll pick up the winner's outcome from the store.
	const lockKey = `nvcf:poll-lock:${taskId}`;
	if (!(await acquireLock(lockKey, NVCF_POLL_LOCK_TTL_S))) {
		return { status: 'running' };
	}

	let result;
	try {
		result = await nv.status({ taskId });
	} finally {
		await releaseLock(lockKey);
	}
	if (result?.code !== 'nvcf_expired') return result;

	// The request id is dead. A racing poll may have already materialized the
	// creation: that's a success, not a failure.
	const row = await findByJob({ replicateJobId: upstreamId, clientKey });
	if (row?.status === 'done' && row.glb_url) {
		return { status: 'done', resultGlbUrl: row.glb_url };
	}

	// Genuinely lost (expired / consumed by an aborted socket). The never-dead-end
	// rule: regenerate server-side rather than surface a failure the user can only
	// answer by re-clicking Generate. Once per job: the resub lock outlives the
	// alias so a second expiry reports the failure honestly.
	if (!row?.prompt) return result;
	if (!(await acquireLock(`nvcf:resub:${upstreamId}`, NVCF_ALIAS_TTL_S))) {
		return { status: 'running' };
	}
	try {
		const tier = resolveTier(row.tier);
		const resub = await nv.textTo3d({ prompt: row.prompt, tier });
		if (!resub.taskId && resub.resultGlbUrl) {
			return { status: 'done', resultGlbUrl: resub.resultGlbUrl };
		}
		if (resub.taskId) {
			await cacheSet(nvcfAliasKey(upstreamId), resub.taskId, NVCF_ALIAS_TTL_S);
			console.warn(
				`[forge] NVCF request expired; resubmitted job under a new request id (creation ${row.id})`,
			);
			return { status: 'running' };
		}
	} catch (err) {
		console.warn(`[forge] NVCF expiry resubmit failed: ${err?.message || err}`);
	}
	return result;
}

// ── Self-host (GCP worker) poll recovery ─────────────────────────────────────
// A self-host /tasks/:id or /jobs/:id poll can 404 ("task not found on gcp
// service") when the durable task record isn't visible to the instance this
// poll reached: the post-submit cross-instance window (worker at high
// concurrency, no session affinity) or a completion write racing us. That was
// the platform's single largest failure class (410 of 425 trellis failures, all
// path='image'), and the router used to treat the FIRST 404 as terminal. The
// GCP twin of pollNvidiaStatus: never dead-end on a recoverable signal -
// re-check the store, grace a young job, and only surface failure once a missing
// task is genuinely orphaned, where the poll handler's lane failover takes over.
async function pollGcpStatus({ gcp, upstreamId, clientKey, createdAt }) {
	const result = await gcp.status(upstreamId);
	if (result?.code !== 'gcp_task_missing') return result;

	const row = await findByJob({ replicateJobId: upstreamId, clientKey }).catch(() => null);
	const ageMs = createdAt ? Date.now() - Date.parse(createdAt) : Infinity;
	const decision = decideSelfhostMissing({ code: result.code, row, ageMs });
	if (decision.action === 'done') {
		return { status: 'done', resultGlbUrl: decision.glbUrl };
	}
	if (decision.action === 'running') {
		return { status: 'running' };
	}
	return result; // genuinely orphaned → existing failover path acts on it
}

async function pollJob(req, res, jobId) {
	// A job handle is either a bare Replicate prediction id (legacy / image-
	// TRELLIS path) or a forge token encoding the geometry/GCP provider + the
	// upstream task id. Decode to learn which provider to poll.
	const token = decodeJobToken(jobId);
	if (!token && !JOB_ID_RE.test(jobId)) {
		return json(res, 400, { error: 'invalid_job', message: 'Malformed job id.' });
	}

	const rl = await limits.mcp3dStatus(clientIp(req));
	if (!rl.success) {
		return rateLimited(res, rl);
	}

	// A pipeline job token (POST /api/x402/pipeline) polls here too, but its record
	// is a multi-stage chain, not a single provider job. Hand it to the pipeline
	// engine, which advances the state machine one tick and returns per-stage
	// progress. Plain forge jobs (below) are unaffected.
	if (token?.provider === 'pipeline') {
		const { pollPipeline } = await import('./_lib/pipeline.js');
		return pollPipeline(res, token.taskId, jobId);
	}

	// Poll-time failover may have re-dispatched this generation onto another
	// lane during an earlier poll (see _lib/forge-failover.js). The client keeps
	// polling the ORIGINAL id; chase the successor chain to the live handle
	// before resolving which provider owns the job. No failover (the common
	// case) leaves everything as decoded above.
	const live = await resolveLiveJob(jobId);
	const liveHandle = live?.handle || jobId;
	const liveToken = live ? decodeJobToken(liveHandle) : token;

	const provider = liveToken?.provider || 'replicate';
	const upstreamId = liveToken?.taskId || liveHandle;
	const clientKey = clientKeyFrom(req);

	// How this job was conditioned (path + tier + backend + view count), recorded
	// at submit time. Surfaced on every poll so a caller that only polls still
	// learns the provenance. Fail-soft: absent when the store is off.
	const meta = await findByJob({ replicateJobId: upstreamId, clientKey });
	const metaFields = meta
		? {
				views_requested: meta.views_requested ?? null,
				views_used: meta.views_used ?? null,
				multiview: meta.multiview ?? null,
				backend: meta.backend ?? null,
				tier: meta.tier ?? null,
				path: meta.path ?? null,
				// Tripo's model version is a deployment-wide setting (TRIPO_MODEL_VERSION
				// or the provider's default), read live rather than stored per row: it
				// cannot drift between submit and poll within the same job's lifetime.
				engine_version: meta.backend === 'tripo' ? tripoModelVersion() : null,
				// The reference view this job reconstructs from. The submit response
				// already carries it, but a client that never saw that response -
				// a coalesced job, a resumed job after a reload, a poll-time failover
				// successor: otherwise has no way to learn it. Repeating it here lets
				// the generation timeline reveal the reference the moment it exists.
				preview_image_url: meta.preview_image_url ?? null,
			}
		: {};

	// Honest timing on every non-terminal poll: how long this job has actually
	// been alive, the lane's typical total, and what is left of it. /api/gpt-forge
	// has returned these since the ChatGPT surface needed them; /api/forge is the
	// endpoint every browser and MCP client polls and it returned neither, so each
	// caller either invented its own copy of the estimate or fell back to a static
	// "usually under a minute" line that nothing measured.
	//
	// eta_remaining_seconds is floored at 5 for the reason gpt-forge floors it: the
	// estimate is a typical duration, not a deadline, and a countdown that goes
	// negative reads as "stuck" for a job that is merely slower than average.
	const elapsedSeconds = meta?.created_at
		? Math.max(0, Math.round((Date.now() - Date.parse(meta.created_at)) / 1000))
		: null;
	const etaTotalSeconds = meta?.backend
		? estimateEtaSeconds({ backendId: meta.backend, tier: meta.tier })
		: null;
	const timingFields = {
		...(Number.isFinite(elapsedSeconds) ? { elapsed_seconds: elapsedSeconds } : {}),
		...(Number.isFinite(etaTotalSeconds) && etaTotalSeconds > 0
			? {
					eta_seconds: etaTotalSeconds,
					eta_remaining_seconds: Number.isFinite(elapsedSeconds)
						? Math.max(5, etaTotalSeconds - elapsedSeconds)
						: etaTotalSeconds,
				}
			: {}),
	};

	// Poll the provider that owns this job. BYOK providers re-resolve the key per
	// poll (the client resends it, or it loads from the session store).
	let result;
	try {
		if (BYOK_PROVIDER_FACTORIES[provider]) {
			const key = await resolveProviderKey(req, null, provider);
			if (!key) {
				return json(res, 200, {
					job_id: jobId,
					status: 'failed',
					error: 'Your API key is required to check this job. Re-enter it and retry.',
					...metaFields,
				});
			}
			const gp = BYOK_PROVIDER_FACTORIES[provider](key);
			result = await gp.status({ kind: liveToken.kind, taskId: upstreamId });
		} else if (provider === 'replicate_byok') {
			// Replicate BYOK polls the caller's own account (key name 'replicate').
			const key = await resolveProviderKey(req, null, 'replicate');
			if (!key) {
				return json(res, 200, {
					job_id: jobId,
					status: 'failed',
					error: 'Your API key is required to check this job. Re-enter it and retry.',
					...metaFields,
				});
			}
			let rep;
			try {
				rep = createRegenProvider({ apiToken: key });
			} catch {
				return unconfigured(res);
			}
			result = await rep.status(upstreamId);
		} else if (provider === 'nvidia') {
			let nv;
			try {
				nv = await loadNvidiaProvider();
			} catch {
				return json(res, 501, {
					error: 'backend_unconfigured',
					message: 'The free NVIDIA NIM 3D lane is not available on this deployment yet.',
				});
			}
			result = await pollNvidiaStatus({ nv, upstreamId, clientKey });
		} else if (provider === 'gcp') {
			// Serves every self-host lane (Hunyuan3D, TripoSG sketch), the job
			// envelope carries the worker URL it was submitted to.
			let gcp;
			try {
				gcp = createGcpProvider();
			} catch {
				return json(res, 501, {
					error: 'backend_unconfigured',
					message: 'Self-hosted generation is not configured on this deployment.',
				});
			}
			result = await pollGcpStatus({ gcp, upstreamId, clientKey, createdAt: meta?.created_at });
		} else {
			let rep;
			try {
				rep = createRegenProvider();
			} catch {
				return unconfigured(res);
			}
			// liveHandle, not jobId: a failover successor on the paid default lane
			// keeps Replicate's bare prediction id as its handle.
			result = await rep.status(liveHandle);
		}
	} catch {
		// A transient poll error shouldn't fail the job: report running so the
		// client's loop retries.
		return json(res, 200, { job_id: jobId, status: 'running', ...metaFields, ...timingFields });
	}

	if (result.status === 'done' && result.resultGlbUrl) {
		// The compression choice a caller requested at submit time (see
		// _lib/forge-job-options.js): this poll is a LATER, separate invocation
		// with no access to that original request body, so it was bound to the
		// job handle then and is looked up now. Absent when nothing non-default
		// was requested, or Redis is unavailable: both fail open to uncompressed.
		const boundOpts = await optionsForJob(jobId);
		// Copy the mesh into our own storage so the model is permanent (provider
		// delivery URLs expire) and serve the durable CDN url. Falls back to the
		// provider url where the store is unavailable. Always scored for quality
		// (glb-quality.js): free, deterministic, and the signal every lane's
		// completion should carry regardless of which provider produced it.
		const durable = await materializeCreation({
			replicateJobId: upstreamId,
			clientKey,
			userId: await sessionUserIdFromReq(req),
			glbUrl: result.resultGlbUrl,
			quality: true,
			compress: boundOpts?.compression || null,
			derivePbr: boundOpts?.derivePbr !== false,
			bbox: boundOpts?.bbox ?? null,
			lods: boundOpts?.lods === true,
		});
		// Populate the result cache this job was bound to at submit time (text→3D,
		// non-high-tier, platform-keyed lanes only: see forgeResultCacheKey). A
		// job with no binding (image mode, high tier, BYOK, or no options
		// requested) is a no-op here.
		const boundCacheKey = await cacheKeyForJob(jobId);
		if (boundCacheKey && durable?.glbUrl) {
			await putCachedForgeResult(boundCacheKey, {
				glb_url: durable.glbUrl,
				backend: meta?.backend || null,
				tier: meta?.tier || null,
				path: meta?.path || null,
				quality: durable.quality || null,
			});
		}
		// Post-generation vision-QA verdict for the async self-host lanes: the
		// High/MAX realism path (self-host TRELLIS / Hunyuan3D) completes here.
		// Tier-scoped (default High only) and fail-open, so draft/standard pay no
		// scoring latency and a vision outage never withholds the delivered model.
		// Surfaced so the client can show the score and offer a one-click regenerate
		// on a failing verdict.
		let qualityGate;
		if (durable?.glbUrl && qualityGateAppliesTo(meta?.tier)) {
			qualityGate = await scoreQualityGate({
				glbUrl: durable.glbUrl,
				prompt: meta?.prompt || null,
				tier: meta?.tier || null,
				backend: meta?.backend || null,
				referenceImageUrl: meta?.preview_image_url || null,
			});
		}
		return json(res, 200, {
			job_id: jobId,
			creation_id: durable?.id ?? meta?.id ?? null,
			status: 'done',
			glb_url: durable?.glbUrl ?? result.resultGlbUrl,
			durable: Boolean(durable),
			quality: durable?.quality || null,
			quality_gate: qualityGate || undefined,
			compression: durable?.compression || null,
			// AniGen's GLB already carries a skeleton and skin weights. Tell the
			// client so it can skip offering a separate rerig step.
			rigged: result.rigged || undefined,
			joint_count: result.jointCount ?? undefined,
			// PartCrafter / HoloPart / segment all hand back the same named-part
			// manifest shape, so Restyle Studio's part picker reads it the same
			// way regardless of which worker produced the mesh.
			parts: result.parts ?? undefined,
			part_count: result.partCount ?? undefined,
			parts_manifest_url: result.manifestUrl ?? undefined,
			...metaFields,
		});
	}
	if (result.status === 'failed') {
		// Persist the RAW provider error for operators, but never relay it: the
		// adapter strings can name the vendor ("meshy task not found"), its billing
		// state, a task id, an IP, or a leaked key. Mask to neutral copy on the wire.
		await markFailed({ replicateJobId: upstreamId, clientKey, error: result.error });

		// Cool the platform lane that actually failed so health-aware routing
		// steers new submits away immediately: the poll-time twin of the
		// submit-side cooldown. BYOK lanes are excluded (never auto-selected).
		const failedBackend = meta?.backend || null;
		const platformLaneFailed = Boolean(failedBackend && BACKENDS[failedBackend] && !BACKENDS[failedBackend].byok);
		if (platformLaneFailed) await markLaneUnhealthy(failedBackend);

		// Automatic redispatch (see _lib/forge-failover.js): recover the original
		// inputs from the creation row and continue the SAME job on the next
		// configured lane: the client keeps polling this id and sees
		// status:"running" with a new backend instead of a dead end. Scoped to
		// platform image-path jobs with a stored reference view; sketch stays on
		// its purpose-built lane and BYOK vendors are never silently swapped.
		const attempted = [...new Set([...(live?.attempted || []), failedBackend].filter(Boolean))];
		const hop = live?.hop || 0;
		const redispatchable =
			platformLaneFailed && hop < MAX_FAILOVER_HOPS && meta?.preview_image_url && meta?.path !== 'sketch';
		if (redispatchable) {
			const nextLane = await pickRedispatchLane({ attempted, country: requestTerritory(req) });
			if (nextLane) {
				try {
					const submitted = await submitFailoverJob({
						backend: nextLane,
						imageUrl: meta.preview_image_url,
						prompt: meta.prompt,
						tierId: meta.tier,
						path: meta.path,
					});
					// Provenance row for the successor so later polls resolve its meta
					// and the success path materializes into the store as usual. The
					// redispatch reconstructs from the primary stored view, so a
					// multi-view original degrades visibly (views_used: 1), never silently.
					const successorId = await createCreation({
						clientKey,
						userId: await sessionUserIdFromReq(req),
						ipHash: hashIp(clientIp(req)),
						prompt: meta.prompt,
						previewImageUrl: meta.preview_image_url,
						replicateJobId: submitted.extJobId,
						viewsRequested: 1,
						viewsUsed: 1,
						multiview: false,
						backend: nextLane,
						tier: meta.tier,
						path: meta.path,
						// A poll carries no request body, so the successor inherits what
						// the original submit said it was for.
						destination: meta.destination,
						internal: meta.internal === true,
					});
					// Report "running" ONLY once the successor is durably chaseable -
					// otherwise the client would poll a dead handle forever.
					const bound = await bindJobSuccessor(jobId, {
						handle: submitted.handle,
						backend: nextLane,
						hop: hop + 1,
						attempted,
					});
					if (bound) {
						// Link the failed attempt to the successor now that the chain is
						// durable, so the outcome ledger records a recovery rather than a
						// loss (the health sensor and npm run forge:errors both read it).
						if (successorId) {
							await markSupersededBy({ replicateJobId: upstreamId, clientKey, successorId });
						}
						console.warn(
							`[forge] job failed on ${failedBackend}; auto-failover #${hop + 1} → ${nextLane}`,
						);
						return json(res, 200, {
							job_id: jobId,
							status: 'running',
							...metaFields,
							...timingFields,
							backend: nextLane,
							failover_from: failedBackend,
						});
					}
				} catch (err) {
					console.warn(`[forge] poll-time failover redispatch failed: ${err?.message || err}`);
				}
			}
		}

		// Terminal: but never a bare dead end: name the configured lanes that can
		// still serve a fresh retry of this request, so a client can offer a
		// one-click engine switch instead of a bare error. Sketch keeps its single
		// purpose-built lane (reconstruct models do badly on drawings).
		const suggestions =
			meta?.path === 'sketch'
				? []
				: retryBackendSuggestions({ attempted, hasImage: Boolean(meta?.preview_image_url), country: requestTerritory(req) });
		return json(res, 200, {
			job_id: jobId,
			status: 'failed',
			error: sanitizeJobError(result.error) || '3D generation hit a snag, please try again.',
			...metaFields,
			...(suggestions.length ? { retryable: true, retry_backends: suggestions } : {}),
		});
	}
	// A job still QUEUED on a scale-to-zero self-host worker is waiting on a
	// container boot, and that is the one wait a client can explain instead of
	// showing a stalled bar. Resolved from the cached lane-health snapshot (one
	// probe per 20s per instance, shared across every concurrent poll), and only
	// while queued: a worker that answered "running" is up by definition, so the
	// flag clears on a real signal rather than on a timer.
	const pendingStatus = result.status || 'running';
	const cold = pendingStatus === 'queued' ? await laneColdStart(metaFields.backend) : false;
	return json(res, 200, {
		job_id: jobId,
		status: pendingStatus,
		...metaFields,
		...timingFields,
		...(cold
			? { cold_start: true, cold_start_seconds: coldStartSecondsFor(metaFields.backend) }
			: {}),
	});
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	if (!method(req, res, ['GET', 'POST'])) return;

	const url = new URL(req.url, 'http://localhost');

	if (req.method === 'POST') {
		// ?action=rig auto-rigs an existing GLB; the default POST reconstructs a
		// mesh from a prompt (text→3D) or a reference image (image→3D).
		if ((url.searchParams.get('action') || '').trim() === 'rig') {
			return startRigJob(req, res);
		}
		return startJob(req, res);
	}

	// ?catalog: the tier + backend + cost/time matrix the composer renders.
	// Public, no secrets; lets the UI communicate the time/cost trade-off and
	// which backends are live before the user commits. The payload only changes
	// on a redeploy (tiers/backends are static; `configured` reflects env
	// presence), so it is heavily CDN-cacheable: one of the hottest GETs on the
	// site (every /forge load), now served almost entirely from the edge instead
	// of recomputing per request. stale-while-revalidate keeps it instant even as
	// the cache refreshes in the background.
	if (url.searchParams.has('catalog')) {
		return json(res, 200, buildCatalog(), {
			'cache-control': 'public, max-age=60, s-maxage=600, stale-while-revalidate=86400',
		});
	}

	// ?health: live-probes every platform backend's upstream (auth + quota
	// gates, zero vendor spend) so the UI and uptime checks see what a
	// generation would actually hit, not just which env vars exist. Cached
	// briefly per instance; rate-limited like status polling.
	if (url.searchParams.has('health')) {
		const rl = await limits.mcp3dStatus(clientIp(req));
		if (!rl.success) return rateLimited(res, rl);
		const { probeForgeHealth } = await import('./_lib/forge-health.js');
		// The probe already memoizes per instance (60s TTL); a short edge cache
		// collapses an influx of identical health polls into one shared response
		// every ~30s instead of one origin probe per client. stale-while-revalidate
		// means a client never waits on a refresh: it sees the live status surface
		// update within ~30s while the CDN absorbs the load.
		return json(res, 200, await probeForgeHealth(), {
			'cache-control': 'public, max-age=15, s-maxage=30, stale-while-revalidate=120',
		});
	}

	// ?progress: the pre-submit crumbs for a trace id the caller passed on its own
	// still-open POST (see _lib/forge-progress.js). Answers instantly from the
	// shared cache, and an unknown trace is an empty list rather than an error:
	// polling ahead of the first milestone is the normal case, not a fault.
	if (url.searchParams.has('progress')) {
		const traceId = (url.searchParams.get('progress') || '').trim();
		if (!normalizeTraceId(traceId)) {
			return json(res, 400, {
				error: 'invalid_progress_id',
				message: 'Pass ?progress=<id> using the same id sent as progress_id on the POST.',
			});
		}
		const rl = await limits.mcp3dStatus(clientIp(req));
		if (!rl.success) return rateLimited(res, rl);
		return json(res, 200, { progress: await readForgeProgress(traceId) });
	}

	const jobId = (url.searchParams.get('job') || '').trim();
	if (!jobId) {
		return json(res, 400, { error: 'missing_job', message: 'Pass ?job=<id> to poll a job.' });
	}
	return pollJob(req, res, jobId);
});