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.

32.4 KB
Raw Blame
// Forge realism / quality gate - the vision-model half of "raise the floor".
//
// glb-quality.js (scoreGlbQuality) answers the CHEAP, deterministic question
// from the glTF JSON chunk alone: is this a valid, dense, textured mesh, or a
// degenerate blob? It cannot see what the mesh actually LOOKS like. This module
// answers the harder, product-facing question: does a render of this model read
// as a real photograph of a real subject, or as a plastic toy / melted blob /
// incomplete / duplicated mess a user should never be shown?
//
// It renders the GLB (or takes a render you already have), sends the image to
// Vertex Gemini vision (GCP-credit-funded, no third-party key) with a subject-
// aware photoreal rubric, and returns a structured verdict:
//   { pass, score, realism, completeness, defects, reason, suggested_retry_hint }.
//
// ── Fail-open, always ─────────────────────────────────────────────────────────
// Quality gating is a BOOST, never a hard gate. If Vertex is down, the render
// fails, the token can't be minted, or the model returns garbage, runQualityGate
// returns pass:true with qa_available:false and a "qa_unavailable" reason. A QA
// outage must never take down a working generation. The router treats a non-pass
// verdict as "try one adjusted regeneration"; it must treat qa_available:false as
// "ship what we have".
//
// ── Provider order ────────────────────────────────────────────────────────────
//   1. Vertex Gemini (gemini-2.5-flash) - the intended lane, bills GCP credits.
//   2. Platform vision chain (describeImageJson: free NVIDIA NIM VLMs) - used
//      when Vertex is unconfigured or errors, so the gate still functions off the
//      free lanes rather than silently disabling itself.
//   3. Neither available → fail-open pass with qa_available:false.
//
// Rung 1 is health-gated, which matters more than it sounds. A project-wide
// billing denial ("Lightning dunning decision is deny for project") makes Vertex
// answer 403 to every request until ops fixes billing, and without a breaker the
// gate spends attempt-0 of EVERY generation on a lane that cannot answer. The
// same circuit breaker the vision chain uses (provider-health) now covers this
// lane: an auth/billing fault parks Vertex for AUTH_COOLDOWN_SECONDS so the very
// next generation goes straight to the free non-GCP rungs, and the park expires
// on its own, so the lane recovers with no deploy the moment billing is
// restored. Measured on production 2026-09-09 under the live hold: 5 of 10
// calls fell open with no verdict while Vertex was re-probed on every call.
//
// ── The router seam ───────────────────────────────────────────────────────────
// The generation router (api/forge.js, owned by another agent) wires this in by:
//   const verdict = await runQualityGate({ glbUrl, prompt });
//   if (!verdict.pass && verdict.qa_available) {
//     const next = buildRetryDirective(verdict, { prompt, tier, path, attempt });
//     if (next) { /* regenerate once with next.prompt / next.tier / next.path */ }
//   }
// See the SEAM comment block at the end of this file for the copy-paste contract.

import { getGcpAccessToken } from './gcp-auth.js';
import { describeImageJson, visionConfigured, parseJsonLoose } from './vision.js';
import {
	AUTH_COOLDOWN_SECONDS,
	clearProviderCooldown,
	markProviderCooldown,
	providersInCooldown,
} from './provider-health.js';
import { renderAvatarScene, SCENE_PRESETS } from './avatar-render.js';
import { assertPublicHttpsUrl, SsrfError } from './ssrf.js';
import { fetchSafePublicUrlPinned, MaxBytesExceededError, SsrfBlockedError } from './ssrf-guard.js';

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

function intEnv(name, fallback) {
	const v = readEnv(name);
	const n = v == null || v === '' ? NaN : Number(v);
	return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
}

// Env-tunable knobs. Defaults chosen for the Forge lanes; a deployment can retune
// without a code change.
export const QUALITY_GATE_DEFAULTS = Object.freeze({
	// A verdict at or above this composite score passes the gate.
	passScore: intEnv('FORGE_QUALITY_PASS_SCORE', 60),
	// Hard cap on auto-retries per generation, so a persistently-bad prompt can
	// never burn unbounded GCP credit. attempt is 0-indexed, so 2 means the
	// original plus up to two adjusted regenerations.
	maxRetries: intEnv('FORGE_QUALITY_MAX_RETRIES', 2),
	// Vertex model + region. gemini-2.5-flash is vision-capable and serves on
	// us-central1 and global (both probed live).
	model: readEnv('VERTEX_QUALITY_MODEL') || 'gemini-2.5-flash',
	location: readEnv('GOOGLE_CLOUD_LOCATION_QUALITY') || readEnv('GOOGLE_CLOUD_LOCATION') || 'us-central1',
	// Render size for scoring. Small keeps image-token cost low while staying
	// legible enough for a realism call.
	renderSize: intEnv('FORGE_QUALITY_RENDER_SIZE', 640),
	// Per-call vision timeout.
	timeoutMs: intEnv('FORGE_QUALITY_TIMEOUT_MS', 25_000),
});

// Circuit-breaker key for the Vertex scoring rung. Namespaced away from the
// vision chain's own lanes so parking the quality gate's Vertex call never
// disables Vertex for a different consumer.
const VERTEX_QUALITY_LANE = 'forge-quality:vertex';
// Transient-failure park (timeout, 5xx, network blip). Matches the vision
// chain's lane cooldown so the two breakers behave the same way.
const VISION_FALLBACK_COOLDOWN_SECONDS = 45;

// ── Subject awareness ─────────────────────────────────────────────────────────
// The photoreal bar differs by subject: a person needs correct anatomy and skin;
// food needs appetizing surface and no plastic sheen; a vehicle needs panel gaps
// and real paint. Detecting the subject lets the rubric ask for the right cues
// and lets the retry hint steer regeneration toward them.
const SUBJECT_RULES = Object.freeze({
	person: {
		match: /\b(person|man|woman|boy|girl|human|character|warrior|knight|astronaut|soldier|king|queen|figure|portrait|avatar|face|guy|lady|ninja|wizard|hero)\b/i,
		cues: 'correct human anatomy and proportions, five fingers per hand, two eyes, symmetric face, realistic skin with pores (not plastic or waxy), one single complete body (no extra or fused limbs, no duplicated heads)',
	},
	animal: {
		match: /\b(cat|dog|horse|bird|dragon|lion|tiger|bear|wolf|fox|animal|creature|fish|snake|deer|rabbit|elephant|monster|beast)\b/i,
		cues: 'correct animal anatomy (right leg count, single head/tail), real fur/scale/feather texture, no melted or fused limbs',
	},
	food: {
		match: /\b(food|burger|pizza|cake|fruit|apple|bread|sushi|donut|coffee|drink|meal|dish|sandwich|ice cream|cookie|steak)\b/i,
		cues: 'appetizing photoreal surface, real food texture and translucency, no plastic sheen, no toy-like uniform color',
	},
	vehicle: {
		match: /\b(car|truck|vehicle|motorcycle|plane|aircraft|ship|boat|tank|bike|bus|train|rocket|helicopter)\b/i,
		cues: 'real paint with panel gaps and reflections, correct wheel/window/light placement, symmetric body, no warped or collapsed panels',
	},
	plant: {
		match: /\b(tree|plant|flower|bush|leaf|grass|cactus|fern|rose|palm|forest)\b/i,
		cues: 'natural organic branching and leaf texture, real botanical silhouette, no fused or repeating geometry',
	},
	building: {
		match: /\b(house|building|castle|tower|church|temple|bridge|structure|architecture|room|shop|store|hut|cabin)\b/i,
		cues: 'straight structural lines, real material texture (brick/wood/stone/glass), coherent architecture, no floating or collapsed sections',
	},
	object: {
		match: /.*/,
		cues: 'real PBR-looking materials (metal/wood/fabric/leather read as their true material, not flat plastic), complete single object, correct proportions, no melted or blobby geometry',
	},
});

// Resolve a subject category from an explicit hint or the prompt text. Falls back
// to the generic "object" bar, which every asset must at least clear.
export function subjectFromPrompt(prompt, hint = null) {
	if (hint && SUBJECT_RULES[hint]) return hint;
	const text = String(prompt || '');
	for (const key of ['person', 'animal', 'food', 'vehicle', 'plant', 'building']) {
		if (SUBJECT_RULES[key].match.test(text)) return key;
	}
	return 'object';
}

// Build the rubric prompt sent to the vision model. Subject-aware, and it demands
// a strict JSON reply so the parse is reliable (VLMs honor "reply ONLY JSON").
function rubricPrompt(subject, prompt) {
	const rule = SUBJECT_RULES[subject] || SUBJECT_RULES.object;
	const promptLine = prompt
		? `The model was generated from this request: "${String(prompt).slice(0, 400)}".`
		: 'No source prompt was provided.';
	return [
		'You are a quality inspector for an AI 3D-model generator (text-to-3D). You are shown a render of ONE generated 3D model.',
		promptLine,
		`This model is a ${subject}. For this subject, a good result shows: ${rule.cues}.`,
		'',
		'Your job is to RAISE THE FLOOR: catch and reject genuinely broken output while passing clean, complete, correctly-proportioned models. Photorealism is the aspiration, but do NOT hold generated 3D assets to the standard of a literal photograph. A clean, complete model of the correct subject is GOOD even if its materials look slightly matte or game-ready.',
		'',
		'IMPORTANT: the render uses fixed studio lighting on a plain gray backdrop, and the subject may look dark. Do NOT lower the score for the render\'s exposure, brightness, shadows, or background. If the geometry and proportions are correct and complete, that alone earns a passing score even when fine surface detail is hard to see.',
		'',
		'Score the OVERALL quality on this calibrated 0-100 scale:',
		'  85-100 = excellent: complete, clean, correct proportions, convincingly real materials.',
		'  65-84  = good: complete, correct subject and proportions, decent materials (may be slightly matte or low-detail). THIS IS A PASS.',
		'  45-64  = borderline: recognizable and mostly complete but noticeably coarse, or missing a requested part, or a plastic-toy look on something that should be real.',
		'  20-44  = poor: badly wrong proportions, largely incomplete, or unrecognizable as the intended subject.',
		'  0-19   = broken: a blob, melted or fused mass, duplicated parts, floating disconnected fragments, or an unrecognizable mess.',
		'Reserve scores under 30 for genuinely broken output. A complete, correctly-shaped object of the right subject should score 65 or higher.',
		'',
		'Reply with ONLY this JSON object and nothing else. Keep "reason" under 30 words and "retry_hint" under 15 words:',
		'{',
		'  "score": <int 0-100, overall quality on the calibrated scale above>,',
		'  "realism": <int 0-100, how photographic vs toy/plastic/CG the materials and shading look>,',
		'  "completeness": <int 0-100, how complete and single-subject the geometry is (100 = one whole subject, low = missing/partial/duplicated/fragmented)>,',
		'  "is_photoreal": <true|false>,',
		'  "subject_detected": "<what you actually see>",',
		'  "defects": [<zero or more short tags, ONLY for issues actually present, from: blob, melted, plastic, toy, incomplete, partial, holes, duplicated, fused, extra_limbs, floating_fragments, garbled_texture, untextured, wrong_proportions, low_detail>],',
		'  "reason": "<one concrete sentence on the main quality issue, or why it is good>",',
		'  "retry_hint": "<one short instruction to improve a regeneration, or empty string if it is already good>"',
		'}',
	].join('\n');
}

// Clamp a value into a 0-100 integer, or null when it is not a finite number.
function score100(v) {
	const n = Number(v);
	if (!Number.isFinite(n)) return null;
	return Math.max(0, Math.min(100, Math.round(n)));
}

// SSRF guard for a caller-supplied render or GLB URL: https (http only in dev),
// and the host is resolved on our side with every address checked against the
// private/loopback/metadata blocklist. A literal-only check let any DNS name
// that resolves inward straight through.
async function assertSafeUrl(rawUrl) {
	try {
		return await assertPublicHttpsUrl(rawUrl);
	} catch (e) {
		if (e instanceof SsrfError) {
			throw Object.assign(new Error('render URL is not a public https address'), { code: 'invalid_url' });
		}
		throw e;
	}
}

const MAX_RENDER_IMAGE_BYTES = 16 * 1024 * 1024;

// Fetch an image URL and return { imageBase64, mimeType }. The pinned guard
// connects only to the validated address, re-validates every redirect hop, and
// caps the body while streaming.
async function fetchImageBase64(rawUrl, timeoutMs) {
	await assertSafeUrl(rawUrl);
	let res;
	try {
		res = await fetchSafePublicUrlPinned(
			rawUrl,
			{ signal: AbortSignal.timeout(timeoutMs) },
			{ allowHttp: process.env.NODE_ENV !== 'production', maxBytes: MAX_RENDER_IMAGE_BYTES },
		);
	} catch (e) {
		if (e instanceof SsrfBlockedError) {
			throw Object.assign(new Error('render URL is not a public https address'), { code: 'invalid_url' });
		}
		if (e instanceof MaxBytesExceededError) throw new Error('render image exceeds 16 MB');
		throw e;
	}
	if (!res.ok) throw new Error(`render fetch ${res.status}`);
	const ct = (res.headers.get('content-type') || 'image/png').split(';')[0].trim();
	const buf = Buffer.from(await res.arrayBuffer());
	return { imageBase64: buf.toString('base64'), mimeType: ct.startsWith('image/') ? ct : 'image/png' };
}

// Render a GLB to a PNG and return { imageBase64, mimeType }. Uses the shared
// headless pipeline (avatar-render.js) with a full-body framing so the whole
// subject is judged, not a cropped portrait. A neutral mid-gray studio backdrop
// (not black) gives the vision model contrast against dark subjects - a dark GLB
// on a dark background reads as "underexposed" and skews the verdict. The
// pipeline's lighting is fixed, so the rubric explicitly tells the model to judge
// the mesh, not the render's exposure.
async function renderGlbBase64(glbUrl, size) {
	await assertSafeUrl(glbUrl);
	const { png } = await renderAvatarScene({
		glbUrl,
		width: size,
		height: size,
		background: '#6a6d75',
		scenePreset: SCENE_PRESETS['full-body'],
	});
	return { imageBase64: Buffer.from(png).toString('base64'), mimeType: 'image/png' };
}

// Resolve a GCP OAuth bearer token. Primary path is the shared service-account /
// metadata-server minter (production Cloud Run). As an additive fallback for
// environments where an ambient gcloud token is exported (local verification,
// CI shells), accept GOOGLE_ACCESS_TOKEN / GCLOUD_ACCESS_TOKEN. Never logged.
async function resolveGcpToken() {
	try {
		return await getGcpAccessToken();
	} catch (e) {
		const ambient = readEnv('GOOGLE_ACCESS_TOKEN') || readEnv('GCLOUD_ACCESS_TOKEN');
		if (ambient) return ambient.trim();
		throw e;
	}
}

// True when the Vertex Gemini lane can be attempted (GCP project configured).
export function vertexQualityConfigured() {
	return Boolean(readEnv('GOOGLE_CLOUD_PROJECT'));
}

// True when the gate can score at all - Vertex OR the free platform vision chain.
// Use to decide whether to bother rendering (a cheap pre-check the router can run).
export function qualityGateConfigured() {
	return vertexQualityConfigured() || visionConfigured();
}

// Score one render via Vertex Gemini. Returns { json, provider, model } or throws.
async function scoreViaVertex({ imageBase64, mimeType, prompt, subject, timeoutMs }) {
	const project = readEnv('GOOGLE_CLOUD_PROJECT');
	if (!project) throw Object.assign(new Error('GOOGLE_CLOUD_PROJECT unset'), { code: 'unconfigured' });
	const location = QUALITY_GATE_DEFAULTS.location;
	const model = QUALITY_GATE_DEFAULTS.model;
	const token = await resolveGcpToken();
	const host = location === 'global' ? 'https://aiplatform.googleapis.com' : `https://${location}-aiplatform.googleapis.com`;
	const endpoint = `${host}/v1/projects/${project}/locations/${location}/publishers/google/models/${model}:generateContent`;

	const body = {
		contents: [
			{
				role: 'user',
				parts: [
					{ text: rubricPrompt(subject, prompt) },
					{ inlineData: { mimeType, data: imageBase64 } },
				],
			},
		],
		// thinkingBudget:0 disables gemini-2.5 extended reasoning. It is essential
		// here: the thinking tokens count against maxOutputTokens but are NOT returned
		// as text, so on a complex render the model can burn the whole budget thinking
		// and hit MAX_TOKENS with the JSON reply truncated mid-object (finishReason
		// MAX_TOKENS at ~49 visible tokens). A deterministic scoring rubric needs no
		// chain-of-thought, so turning it off makes the reply complete, cheaper, and
		// faster. temperature:0 for a stable verdict; JSON mime for a clean parse.
		generationConfig: {
			temperature: 0,
			responseMimeType: 'application/json',
			maxOutputTokens: 800,
			thinkingConfig: { thinkingBudget: 0 },
		},
	};

	const res = await fetch(endpoint, {
		method: 'POST',
		headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
		body: JSON.stringify(body),
		signal: AbortSignal.timeout(timeoutMs),
	});
	if (!res.ok) {
		const text = await res.text().catch(() => '');
		throw Object.assign(new Error(`vertex ${res.status}: ${text.slice(0, 200)}`), { status: res.status });
	}
	const data = await res.json();
	const parts = data?.candidates?.[0]?.content?.parts || [];
	const text = parts.map((p) => p?.text || '').join('').trim();
	if (!text) {
		const reason = data?.candidates?.[0]?.finishReason;
		throw new Error(`vertex returned no text${reason ? ` (finishReason: ${reason})` : ''}`);
	}
	return { json: parseJsonLoose(text), provider: 'vertex', model: `vertex-ai/${model}` };
}

// The rung the gate asks first. Measured 2026-09-30 with this rubric on real
// turntable renders from production (a TRELLIS avatar and a catalog armchair):
// Workers AI's Llama 4 Scout returned the JSON verdict 8 times in 8, in 2.4 to
// 6.9 s, while the NIM 11B lane returned it 4 times in 8, in 8 to 20 s, and
// described the avatar in prose on all four tries. Asked first, that lane spent
// most of the gate's 29 s deadline and then failed, and the rungs behind it
// (free OpenRouter routes at 429, Vertex on a billing hold, OpenAI with billing
// inactive) could not answer either, so the gate failed open on 8 of 10
// production checks. Leading with the measured-reliable rung keeps the rest of
// the chain as its fallback, cooldowns included.
export const QUALITY_GATE_VISION_LEAD = Object.freeze(['cloudflare']);

// Score one render via the platform vision chain. Reuses describeImageJson so
// the JSON acceptance test and the spend ledger are inherited.
async function scoreViaPlatformVision({ imageBase64, mimeType, prompt, subject, timeoutMs, track }) {
	const out = await describeImageJson({
		lead: QUALITY_GATE_VISION_LEAD,
		prompt: rubricPrompt(subject, prompt),
		imageBase64,
		mimeType,
		maxTokens: 1536,
		timeoutMs,
		deadlineMs: timeoutMs + 4000,
		track: { ...(track || {}), tool: 'api/_lib/forge-quality-gate' },
	});
	return { json: out.json, provider: out.provider, model: out.model };
}

// The platform vision chain walks up to a dozen rungs and throws the LAST one's
// error, carrying the whole walk on `err.lanes`. Reporting only the message said
// "openai vision 429: billing_not_active" for every outage, which is the paid
// tail answering after every free rung had already lost for its own reason. The
// fail-open verdict is the one place an operator reads why the gate went blind,
// so it names every rung that was tried and how it lost.
export function describeVisionFailure(err) {
	const lanes = Array.isArray(err?.lanes) ? err.lanes : [];
	if (!lanes.length) return String(err?.message || err);
	return lanes
		.map((l) => {
			const who = l.model ? `${l.provider}/${l.model}` : l.provider;
			const detail = String(l.detail || '').replace(/\s+/g, ' ').trim().slice(0, 90);
			return `${who} ${l.status ?? 'no-status'}${detail ? ` ${detail}` : ''}`;
		})
		.join('; ');
}

// The structural-failure floor: below this completeness the mesh is broken
// (incomplete, duplicated, fragmented) regardless of a generous overall score, so
// it fails the gate. Env-tunable alongside the pass score.
const COMPLETENESS_FLOOR = intEnv('FORGE_QUALITY_COMPLETENESS_FLOOR', 40);

// Normalize a raw model reply into the public verdict shape and apply our pass
// decision. The decision trusts the recalibrated overall score (which already
// folds in structure and materials) plus a hard completeness floor that catches
// broken geometry even if the model was generous on the headline number. Defect
// tags are informational and drive the retry hint; a single over-eager tag does
// NOT by itself fail an otherwise-complete, well-scored model.
function normalizeVerdict(raw, { subject, provider, model, passScore, renderSource }) {
	const score = score100(raw?.score);
	const realism = score100(raw?.realism);
	const completeness = score100(raw?.completeness);
	const defects = Array.isArray(raw?.defects)
		? raw.defects.map((d) => String(d).toLowerCase().trim().replace(/\s+/g, '_')).filter(Boolean).slice(0, 12)
		: [];
	const hint = typeof raw?.retry_hint === 'string' ? raw.retry_hint.trim() : '';
	// Pass requires clearing the score threshold AND not being structurally broken
	// (completeness below the floor). A null score (unparseable field) means the
	// provider answered but malformed - fail closed to a retry rather than pass a
	// blind result; a total provider/render outage is handled upstream by fail-open.
	const structurallyBroken = completeness != null && completeness < COMPLETENESS_FLOOR;
	const pass = score != null && score >= passScore && !structurallyBroken;
	return {
		pass,
		score,
		realism,
		completeness,
		subject,
		subject_detected: typeof raw?.subject_detected === 'string' ? raw.subject_detected.slice(0, 120) : null,
		is_photoreal: raw?.is_photoreal === true,
		defects,
		reason: typeof raw?.reason === 'string' ? raw.reason.slice(0, 400) : (pass ? 'meets the realism bar' : 'below the realism bar'),
		suggested_retry_hint: hint || (pass ? null : 'increase realism and detail; render as a real photograph of the subject'),
		provider,
		model,
		qa_available: true,
		render_source: renderSource,
	};
}

// A fail-open pass verdict, returned whenever scoring cannot run. The router MUST
// ship this (qa_available:false) rather than retry - a QA outage is not a quality
// failure of the model.
function failOpen(reason, { subject = 'object', renderSource = 'none' } = {}) {
	return {
		pass: true,
		score: null,
		realism: null,
		completeness: null,
		subject,
		subject_detected: null,
		is_photoreal: null,
		defects: [],
		reason: `qa_unavailable: ${reason}`,
		suggested_retry_hint: null,
		provider: null,
		model: null,
		qa_available: false,
		render_source: renderSource,
	};
}

/**
 * Run the realism / quality gate on a generated model.
 *
 * Provide the GLB to render, or a render you already have. Exactly one image is
 * scored: a provided renderBase64, else a fetched renderUrl, else a fresh render
 * of glbUrl.
 *
 * @param {object} opts
 * @param {string} [opts.glbUrl]        public GLB URL to render + score
 * @param {string} [opts.renderUrl]     public image URL of an existing render
 * @param {string} [opts.renderBase64]  base64 (or data: URI) of an existing render
 * @param {string} [opts.mimeType]      mime for renderBase64 (default image/png)
 * @param {string} [opts.prompt]        the source generation prompt (steers rubric + retry)
 * @param {string} [opts.subject]       explicit subject category override
 * @param {number} [opts.passScore]     override the pass threshold
 * @param {object} [opts.track]         spend-ledger attribution passed to platform vision
 * @returns {Promise<object>} verdict (never throws - fail-open on any error)
 */
export async function runQualityGate({
	glbUrl = null,
	renderUrl = null,
	renderBase64 = null,
	mimeType = 'image/png',
	prompt = null,
	subject = null,
	passScore = QUALITY_GATE_DEFAULTS.passScore,
	track = null,
} = {}) {
	const subj = subjectFromPrompt(prompt, subject);

	if (!qualityGateConfigured()) {
		return failOpen('no vision provider configured (set GOOGLE_CLOUD_PROJECT for Vertex, or NVIDIA_API_KEY for the free lane)', { subject: subj });
	}

	// 1. Obtain exactly one image to score.
	let image;
	let renderSource;
	try {
		if (renderBase64) {
			const m = String(renderBase64).match(/^data:(image\/[a-z+]+);base64,(.*)$/i);
			image = { imageBase64: m ? m[2] : String(renderBase64).replace(/^data:[^,]*,/, ''), mimeType: m ? m[1].toLowerCase() : mimeType };
			renderSource = 'provided_base64';
		} else if (renderUrl) {
			image = await fetchImageBase64(renderUrl, QUALITY_GATE_DEFAULTS.timeoutMs);
			renderSource = 'provided_url';
		} else if (glbUrl) {
			image = await renderGlbBase64(glbUrl, QUALITY_GATE_DEFAULTS.renderSize);
			renderSource = 'rendered_glb';
		} else {
			return failOpen('no glbUrl, renderUrl, or renderBase64 supplied', { subject: subj });
		}
	} catch (e) {
		// A render / fetch failure is a QA outage, not a model failure - fail open.
		return failOpen(`could not obtain a render: ${e?.message || e}`, { subject: subj });
	}

	// 2. Score it. Vertex first, free platform vision as automatic backup.
	// Record EVERY rung's failure, not just the first. Keeping only the first
	// (this was `lastErr = lastErr || e`) meant that while Vertex sat behind a
	// project-wide billing denial, every QA outage reported that 403 and the
	// backup's own error was never written down anywhere. The outage then reads
	// as "Vertex is down" when the thing that actually decided the outcome was
	// the rung after it, which is the failure this chain exists to survive.
	let scored = null;
	const failures = [];
	if (vertexQualityConfigured()) {
		// Skip a lane already known to be refusing. Best-effort: an unreadable
		// cache reads as "not cooling", which is exactly the pre-breaker path.
		const cooling = await providersInCooldown([VERTEX_QUALITY_LANE]);
		if (cooling.has(VERTEX_QUALITY_LANE)) {
			failures.push(`vertex: skipped, lane cooling (${cooling.get(VERTEX_QUALITY_LANE)})`);
		} else {
			try {
				scored = await scoreViaVertex({ ...image, prompt, subject: subj, timeoutMs: QUALITY_GATE_DEFAULTS.timeoutMs });
				void clearProviderCooldown(VERTEX_QUALITY_LANE);
			} catch (e) {
				failures.push(`vertex: ${e?.message || e}`);
				// 401/402/403 is a key or billing fault: broken until ops acts, so
				// park it for the long window instead of re-probing every call. Any
				// other failure is treated as transient and parked briefly.
				const status = Number(e?.status);
				const authFault = status === 401 || status === 402 || status === 403;
				void markProviderCooldown(
					VERTEX_QUALITY_LANE,
					authFault ? AUTH_COOLDOWN_SECONDS : VISION_FALLBACK_COOLDOWN_SECONDS,
					authFault ? 'auth' : 'health',
				);
			}
		}
	}
	if (!scored && visionConfigured()) {
		try {
			scored = await scoreViaPlatformVision({ ...image, prompt, subject: subj, timeoutMs: QUALITY_GATE_DEFAULTS.timeoutMs, track });
		} catch (e) {
			failures.push(`platform-vision: ${describeVisionFailure(e)}`);
		}
	}
	if (!scored) {
		return failOpen(`scoring failed: ${failures.join(' | ') || 'no provider answered'}`, { subject: subj, renderSource });
	}

	// 3. Normalize + apply the threshold.
	return normalizeVerdict(scored.json, {
		subject: subj,
		provider: scored.provider,
		model: scored.model,
		passScore,
		renderSource,
	});
}

// ── Auto-retry directive ──────────────────────────────────────────────────────

const TIER_LADDER = ['draft', 'standard', 'high'];

function nextTier(tier) {
	const i = TIER_LADDER.indexOf(tier);
	if (i < 0) return 'standard';
	return TIER_LADDER[Math.min(i + 1, TIER_LADDER.length - 1)];
}

// Turn defect tags into a short negative-guidance clause the regeneration prompt
// can carry, plus a decision on whether to switch the generation path.
function guidanceFromDefects(defects) {
	const set = new Set(defects || []);
	const avoid = [];
	if (set.has('plastic') || set.has('toy')) avoid.push('plastic or toy-like materials');
	if (set.has('blob') || set.has('melted')) avoid.push('blobby or melted geometry');
	if (set.has('incomplete') || set.has('partial') || set.has('holes')) avoid.push('missing or incomplete parts');
	if (set.has('duplicated') || set.has('fused') || set.has('extra_limbs')) avoid.push('duplicated or fused parts');
	if (set.has('floating_fragments')) avoid.push('floating disconnected fragments');
	if (set.has('garbled_texture') || set.has('untextured')) avoid.push('smeared or missing textures');
	if (set.has('wrong_proportions')) avoid.push('wrong proportions');
	// A structural defect (blob/incomplete/duplicated) is best fought with more
	// geometric budget and the image path, which grounds the mesh in a reference.
	const structural = ['blob', 'melted', 'incomplete', 'partial', 'holes', 'duplicated', 'fused', 'extra_limbs', 'floating_fragments'];
	const wantsMoreGeometry = structural.some((d) => set.has(d));
	return { avoid, wantsMoreGeometry };
}

/**
 * Given a failed verdict and the directive that produced it, build a concrete
 * adjusted directive for ONE regeneration. Returns null when a retry should not
 * happen: the verdict passed, QA was unavailable (never retry on an outage), or
 * the retry cap is reached.
 *
 * @param {object} verdict  a runQualityGate() result
 * @param {object} base     { prompt, tier, path, attempt, maxRetries }
 *   attempt is 0-indexed (0 = the original generation). The returned directive
 *   carries attempt+1. Stop when attempt+1 > maxRetries.
 * @returns {object|null} { prompt, tier, path, attempt, reason } or null
 */
export function buildRetryDirective(verdict, base = {}) {
	if (!verdict || verdict.pass || verdict.qa_available === false) return null;
	const maxRetries = Number.isFinite(base.maxRetries) ? base.maxRetries : QUALITY_GATE_DEFAULTS.maxRetries;
	const attempt = Number.isFinite(base.attempt) ? base.attempt : 0;
	const nextAttempt = attempt + 1;
	if (nextAttempt > maxRetries) return null;

	const { avoid, wantsMoreGeometry } = guidanceFromDefects(verdict.defects);
	const basePrompt = String(base.prompt || '').trim();
	const hint = verdict.suggested_retry_hint ? ` ${verdict.suggested_retry_hint.trim()}` : '';
	const avoidClause = avoid.length ? ` Avoid: ${avoid.join(', ')}.` : '';
	// Append photoreal steering to the original prompt without discarding it, so
	// the subject stays intact while the realism bar is pushed.
	const prompt = `${basePrompt}, photorealistic, real photograph, high detail, accurate proportions, realistic PBR materials.${avoidClause}${hint}`.trim();

	const tier = wantsMoreGeometry ? nextTier(base.tier || 'standard') : (base.tier || 'standard');
	// Switch to the image path on a structural failure: a reference image grounds
	// the reconstruction and cuts blob/duplication failure modes. Leave a non-
	// structural (material-only) failure on its current path - a tighter prompt
	// alone usually fixes plastic/toy looks.
	const path = wantsMoreGeometry ? 'image' : (base.path || 'image');

	return {
		prompt,
		tier,
		path,
		attempt: nextAttempt,
		reason: `retry ${nextAttempt}/${maxRetries}: ${verdict.reason || 'below realism bar'}`,
	};
}

// ── ROUTER SEAM (copy-paste contract for api/forge.js, owned by another agent) ──
//
// After a generation produces { glb_url } and BEFORE returning it to the user,
// the router can gate + auto-retry like this (fail-open by construction):
//
//   import { runQualityGate, buildRetryDirective, QUALITY_GATE_DEFAULTS } from './_lib/forge-quality-gate.js';
//
//   let directive = { prompt, tier, path, attempt: 0, maxRetries: QUALITY_GATE_DEFAULTS.maxRetries };
//   let result = await generateOnce(directive);              // existing generation call
//   let verdict = await runQualityGate({ glbUrl: result.glb_url, prompt: directive.prompt });
//
//   while (!verdict.pass && verdict.qa_available) {
//     const next = buildRetryDirective(verdict, directive);  // null when cap reached
//     if (!next) break;
//     directive = next;
//     result = await generateOnce(directive);                // regenerate with adjusted directive
//     verdict = await runQualityGate({ glbUrl: result.glb_url, prompt: directive.prompt });
//   }
//   // Ship `result` regardless. Attach `verdict` to creation metadata for observability.
//   // verdict.qa_available === false  → QA outage, ship as-is, do NOT retry.
//   // verdict.pass === false && cap hit → best effort shipped; the verdict explains why.