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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Forge creation store — durable persistence + the text→3D data flywheel.
//
// /forge runs the real flux-schnell → TRELLIS pipeline (see api/forge.js) and
// hands back the Replicate delivery URL, which expires in ~1h. This module is
// the layer that makes a generator a *data engine*: it copies every generated
// mesh (and its reference image) into our own object storage so they're
// permanent, records the (prompt → image → mesh) pair, and captures the human
// verdict (kept / discarded / downloaded) — the labeled signal a future
// in-house model trains on.
//
// Every function is best-effort and fail-soft. /forge is auth-free and works on
// deployments without a database or object storage configured; when either is
// missing, these helpers no-op (return null/false/[]) and the endpoint falls
// back to returning the raw provider URL. Persistence is a bonus, never a gate.
import { createHash } from 'node:crypto';
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
import { sql, isDbUnavailableError } from './db.js';
import { databaseConfigured } from './env.js';
import { putObject, cdnUrl, deleteObject, keyFromPublicUrl, normalizeStoredUrl, objectStorageConfigured } from './r2.js';
import { recordDailyActivity, maybeAwardFirstCreation } from './streaks.js';
import { recordGenerationEvent } from './forge-events.js';
import { scoreGlbQuality } from './glb-quality.js';
import { stripFloorSlab } from './glb-floor-slab.js';
import { fitBbox } from './glb-bbox-fit.js';
import { compressGlb, deliveryCompressionOptions } from './glb-compress.js';
import { classifyModelCategory } from './forge-classify.js';
import { cleanupGlb } from './glb-cleanup.js';
import { derivePbrChannels } from './glb-pbr-derive.js';
import { fetchUpstream, fetchUpstreamPublic } from './upstream-fetch.js';
import { gradeSimReadiness } from './sim-readiness.js';
import { putGrade } from './sim-readiness-store.js';
import { dispatchWebhooks } from './webhook-dispatch.js';
import { autoCredentialForBytes } from './auto-provenance.js';
import { tripoModelVersion } from '../_providers/tripo.js';
import { validForgeDestination } from '../../src/shared/forge-destinations.js';
// Stable, non-secret salt so a leaked DB row can't be trivially reversed to the
// raw browser-local id. The id is anonymous to begin with; this is hygiene, not
// a security boundary.
const CLIENT_SALT = 'forge:v1';
// Generations larger than this are almost certainly a runaway TRELLIS output;
// refuse to copy them into our bucket rather than ingest an unbounded blob.
const MAX_GLB_BYTES = 64 * 1024 * 1024;
const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
// Forge persistence needs both a database (the creation rows) and object
// storage (durable copies). Detect from the raw env so a partially-configured
// deployment degrades to the stateless path instead of throwing on first use.
export function forgeStoreEnabled() {
return Boolean(databaseConfigured() && objectStorageConfigured());
}
// Hash a caller-supplied anonymous client id. Empty / missing ids collapse to a
// shared 'anon' bucket so the column is never null and gallery scoping is total.
export function hashClient(raw) {
const value = typeof raw === 'string' ? raw.trim() : '';
if (!value) return 'anon';
return createHash('sha256').update(`${CLIENT_SALT}:${value}`).digest('hex');
}
export function hashIp(ip) {
if (!ip) return null;
return createHash('sha256').update(`${CLIENT_SALT}:ip:${ip}`).digest('hex');
}
// Resolve the reference-view URLs a generation consumes down to the bucket keys
// of the user's own uploads (forge/uploads/..., written by api/forge-upload.js).
// Provider-hosted URLs (FLUX previews on a delivery CDN, pasted external links)
// resolve to null and are dropped: they are not ours to delete. Returns a
// deduplicated array, or null when nothing bucket-hosted is present, so the
// column stays null for the text-to-3D majority.
function sourceImageKeysFrom(urls) {
const keys = new Set();
for (const url of Array.isArray(urls) ? urls : []) {
const key = keyFromPublicUrl(url);
if (key && key.startsWith('forge/')) keys.add(key);
}
return keys.size ? [...keys].slice(0, 12) : null;
}
// Record a generation the moment it starts, so the prompt + reference image are
// retained even if the mesh step later fails. Returns the new creation id (used
// as the durable object key and the client-facing handle) or null when the
// store is unavailable.
export const MODEL_CATEGORIES = ['avatar', 'accessory', 'item', 'scene', 'creature', 'vehicle', 'other'];
export function validModelCategory(v) {
return typeof v === 'string' && MODEL_CATEGORIES.includes(v) ? v : null;
}
// x402 payment provenance, shaped for read-path spreads. Only rows created by
// the paid /api/x402/forge lane carry these; every other lane spreads nothing,
// so existing consumers see no new keys on non-x402 items.
function x402Provenance(r) {
if (!r?.x402_tx_sig && !r?.x402_payer) return {};
return {
x402: {
payer: r.x402_payer ?? null,
tx_sig: r.x402_tx_sig ?? null,
price_usdc: r.x402_price_atomic != null ? Number(r.x402_price_atomic) / 1e6 : null,
},
};
}
// Stamp the on-chain receipt onto a creation the paid x402 lane just recorded:
// who paid, the settle signature, and the price. Keyed the same way as every
// other store writer (replicate_job_id + client_key) so it can only touch the
// row its caller created. Best-effort: a miss is logged, never thrown.
export async function attachX402Provenance({ replicateJobId, clientKey, payer, txSig, priceAtomic }) {
if (!forgeStoreEnabled() || !replicateJobId || !clientKey) return false;
try {
const rows = await sql`
update forge_creations
set x402_payer = ${payer ?? null},
x402_tx_sig = ${txSig ?? null},
x402_price_atomic = ${Number.isFinite(Number(priceAtomic)) ? Number(priceAtomic) : null},
updated_at = now()
where replicate_job_id = ${replicateJobId} and client_key = ${clientKey}
returning id
`;
return rows.length > 0;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] attachX402Provenance skipped (db unavailable):', err?.message);
else console.error('[forge-store] attachX402Provenance failed:', err?.message);
return false;
}
}
// Request-scoped facts every row written during one request should carry.
//
// A single /api/forge request can insert a row from any of a dozen branches
// (primary submit, each failover hop, the cache-hit path, the sync lanes), and
// threading a new field through every one of them is how a field ends up set on
// nine branches and silently null on the tenth. The handler states the fact
// once, here, and createCreation reads it, so no branch can forget it.
const creationContext = new AsyncLocalStorage();
/**
* Run `fn` with request-scoped creation facts. `destination` is validated here,
* so callers pass the raw request value. `internal` marks platform-generated
* rows (catalog seeder, quality benchmark) so the funnel report can leave them out.
* @template T
* @param {{ destination?: unknown, internal?: boolean }} facts
* @param {() => T} fn
* @returns {T}
*/
export function runWithCreationContext({ destination, internal = false } = {}, fn) {
return creationContext.run(
{ destination: validForgeDestination(destination), internal: internal === true },
fn,
);
}
export async function createCreation({
clientKey,
ipHash,
prompt,
aspect,
previewImageUrl,
replicateJobId,
textToImageModel,
viewsRequested,
viewsUsed,
multiview,
backend,
tier,
path,
modelCategory,
userId,
// Every reference-view URL the generation consumes (multiview lanes pass the
// full list). Bucket-hosted ones (the user's own uploaded photos) are
// resolved to their object keys and remembered on the row so deleteCreation
// can erase the photos too. Defaults to the preview URL, which is the single
// reference view on every non-multiview lane, so callers that pass nothing
// still get their upload tracked.
sourceImageUrls = null,
// What the maker is building for (src/shared/forge-destinations.js). An
// explicit value wins; otherwise the request-scoped one the handler set.
destination,
// Platform-generated row (seeder, benchmark). Only failover successors pass
// it, to inherit the original's flag; a fresh submit takes it from the context.
internal,
}) {
if (!forgeStoreEnabled()) return null;
const id = randomUUID();
const ctx = creationContext.getStore();
const nextDestination = validForgeDestination(destination) ?? ctx?.destination ?? null;
const isInternal = typeof internal === 'boolean' ? internal : ctx?.internal === true;
// An explicit category (from the studio picker) always wins; otherwise infer
// it from the prompt so the model gets a real category at birth instead of
// defaulting to 'other' and leaving the category dimension dead.
const category = validModelCategory(modelCategory) ?? classifyModelCategory(prompt);
const sourceKeys = sourceImageKeysFrom(
Array.isArray(sourceImageUrls) && sourceImageUrls.length ? sourceImageUrls : [previewImageUrl],
);
try {
await sql`
insert into forge_creations
(id, client_key, ip_hash, prompt, aspect, preview_image_url,
replicate_job_id, text_to_image_model, views_requested, views_used,
multiview, backend, tier, path, status, outcome, model_category, user_id,
source_image_keys, destination, internal)
values
(${id}, ${clientKey}, ${ipHash ?? null}, ${prompt}, ${aspect ?? null},
${previewImageUrl ?? null}, ${replicateJobId ?? null},
${textToImageModel ?? null}, ${viewsRequested ?? null}, ${viewsUsed ?? null},
${typeof multiview === 'boolean' ? multiview : null}, ${backend ?? null},
${tier ?? null}, ${path ?? null}, 'generating', 'generated', ${category}, ${userId ?? null},
${sourceKeys ? JSON.stringify(sourceKeys) : null}, ${nextDestination}, ${isInternal})
`;
// Funnel start — counts attempts so the health rollup can show how many
// generations began vs. completed. Best-effort; never blocks the insert.
await recordGenerationEvent({ phase: 'start', backend, tier, path, source: 'create' });
return id;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] createCreation skipped (db unavailable):', err?.message);
else console.error('[forge-store] createCreation failed:', err?.message);
return null;
}
}
// Register a finished selfie/prompt reconstruction (api/_lib/reconstruct-
// finalize.js) as a first-class creation, so the Forge surfaces — showcase,
// recent feed, share/embed pages, leaderboards — see reconstructions the same
// way they see /forge generations. The row lands already 'done': the GLB is
// durably stored by the avatar pipeline before this is called, so there is no
// generating phase to track here.
//
// Privacy contract: `visibility` mirrors the avatar's setting. Public feeds
// only serve null/'public' rows (see the visibility predicates on the list
// readers below); 'unlisted' additionally resolves on the direct share read
// (getPublicCreation); 'private' rows exist for provenance and the owner's own
// stores only. The client_key is derived from the owner's user id — it never
// matches a browser's anonymous key, which keeps these rows out of every
// anonymous client gallery.
//
// Idempotent per job: keyed on replicate_job_id (the regen job id), so the
// poll/cron race that can double-drive finalize registers one row, not two.
export async function registerReconstructionCreation({
userId,
avatarId,
jobId,
provider,
prompt,
glbKey,
glbUrl,
sizeBytes,
visibility,
previewImageUrl = null,
}) {
if (!forgeStoreEnabled() || !userId || !avatarId || !jobId || !glbUrl) return null;
const vis = ['public', 'unlisted', 'private'].includes(visibility) ? visibility : 'private';
const promptLine = String(prompt || 'Selfie avatar').slice(0, 500);
try {
const existing = await sql`
select id from forge_creations where replicate_job_id = ${jobId} limit 1
`;
if (existing[0]) return existing[0].id;
const id = randomUUID();
await sql`
insert into forge_creations
(id, client_key, prompt, preview_image_url, replicate_job_id,
glb_key, glb_url, size_bytes, backend, path, status, outcome,
model_category, user_id, visibility, avatar_id)
values
(${id}, ${hashClient(`user:${userId}`)}, ${promptLine}, ${previewImageUrl},
${jobId}, ${glbKey ?? null}, ${glbUrl}, ${Number.isFinite(sizeBytes) ? sizeBytes : null},
${provider ?? null}, 'reconstruct', 'done', 'generated', 'avatar',
${userId}, ${vis}, ${avatarId})
`;
await recordGenerationEvent({ phase: 'done', backend: provider ?? 'unknown', path: 'reconstruct', source: 'reconstruct' });
return id;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] registerReconstructionCreation skipped (db unavailable):', err?.message);
else console.error('[forge-store] registerReconstructionCreation failed:', err?.message);
return null;
}
}
// Look up an in-flight creation by its TRELLIS prediction id, scoped to the
// requesting client so one browser can't poll another's job into existence.
export async function findByJob({ replicateJobId, clientKey }) {
if (!forgeStoreEnabled() || !replicateJobId) return null;
try {
const rows = await sql`
select id, status, glb_url, glb_key, prompt, preview_image_url,
views_requested, views_used, multiview, backend, tier, path, model_category,
user_id, created_at, destination, internal
from forge_creations
where replicate_job_id = ${replicateJobId} and client_key = ${clientKey}
limit 1
`;
return rows[0] ?? null;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] findByJob skipped (db unavailable):', err?.message);
else console.error('[forge-store] findByJob failed:', err?.message);
return null;
}
}
// clientKey-agnostic sibling of findByJob, for the one caller that cannot
// supply a clientKey: a provider webhook, which calls the server directly
// with no cookie/session context. Returns client_key on the row so the
// webhook handler can feed it straight into materializeCreation/markFailed,
// which stay scoped exactly as before: this never widens their privacy
// boundary, it only lets the webhook learn the scope it needs to use.
export async function findByJobAnyClient({ replicateJobId }) {
if (!forgeStoreEnabled() || !replicateJobId) return null;
try {
const rows = await sql`
select id, status, glb_url, glb_key, prompt, preview_image_url,
views_requested, views_used, multiview, backend, tier, path, model_category,
user_id, created_at, destination, internal, client_key
from forge_creations
where replicate_job_id = ${replicateJobId}
limit 1
`;
return rows[0] ?? null;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] findByJobAnyClient skipped (db unavailable):', err?.message);
else console.error('[forge-store] findByJobAnyClient failed:', err?.message);
return null;
}
}
// Idempotency claim for an inbound generation-provider webhook (Tripo), mirror
// of claimWebhookDelivery in print/fulfillment-queries.js: the insert IS the
// concurrency lock, so a retried delivery is a 200 no-op rather than a second
// materialize/markFailed call.
export async function claimForgeWebhookDelivery({ provider, deliveryId, jobId }) {
const rows = await sql`
insert into forge_webhook_deliveries (provider, delivery_id, job_id)
values (${provider}, ${deliveryId}, ${jobId ?? null})
on conflict (provider, delivery_id) do nothing
returning delivery_id
`;
return { fresh: rows.length > 0 };
}
// Drops a claim so the provider's retry of a delivery whose side effect failed
// runs again instead of being acknowledged as a duplicate.
export async function releaseForgeWebhookDelivery({ provider, deliveryId }) {
await sql`
delete from forge_webhook_deliveries
where provider = ${provider} and delivery_id = ${deliveryId}
`;
}
export async function markForgeWebhookApplied({ provider, deliveryId }) {
await sql`
update forge_webhook_deliveries
set applied = true
where provider = ${provider} and delivery_id = ${deliveryId}
`;
}
// Provider asset URLs are frequently short-lived (HuggingFace Spaces serve the
// mesh from an ephemeral gradio /tmp path; CDNs hiccup). Pull the bytes with a
// few quick retries so a transient network error or 5xx/429 — the dominant cause
// of "materializeCreation failed: 404/5xx" in the logs — doesn't permanently lose
// a generation. A hard 404/410 means the file is already gone, so retrying is
// pointless: fail fast on those and let the caller fall back to the provider URL.
const COPY_MAX_ATTEMPTS = 3;
// A provider delivery blob can be tens of MB; the deadline covers the whole
// body read, so it is sized for the 64 MB ceiling on a slow origin.
const COPY_TIMEOUT_MS = 120_000;
// Score, clean, derive PBR channels for, and (optionally) compress a freshly
// downloaded GLB before it lands in the bucket. Every step is pure, local, and
// best-effort: a failure never blocks delivery; it just means the response
// carries no quality signal, or ships the un-cleaned / uncompressed bytes.
// `compress` is one of COMPRESSION_MODES ('draco' | 'meshopt') or falsy to
// skip. `cleanup` runs the codec-independent geometry cleanup (glb-cleanup.js)
// that tames the workers' raw marching-cubes triangle soup; on by default for
// forge meshes. `derivePbr` runs the material completion pass
// (glb-pbr-derive.js) that turns an albedo-only lane output into a full PBR set
// (normal + packed occlusion/roughness/metallic + the class's measured
// extension layer); on by default, pass false to deliver the lane's own
// materials untouched.
async function scoreAndCompress(buf, { computeQuality, compress, cleanup = false, derivePbr = false, bbox = null, prompt = '', tier = '', materialClass = '' }) {
let quality = null;
let compression = null;
let cleaned = null;
let pbr = null;
let fit = null;
let outBuf = buf;
// Cleanup FIRST: a welded, de-duplicated, decimated mesh both renders better
// and compresses better than the raw soup, so the codec below operates on the
// cleaned geometry. Skips itself if it would grow the file (tiny meshes).
if (cleanup) {
try {
const r = await cleanupGlb(outBuf);
if (!r.grew) {
outBuf = r.buffer;
cleaned = {
tris_before: r.trisBefore,
tris_after: r.trisAfter,
verts_before: r.vertsBefore,
verts_after: r.vertsAfter,
input_bytes: r.inputBytes,
output_bytes: r.outputBytes,
simplified: r.simplified,
};
}
} catch (err) {
console.warn('[forge-store] geometry cleanup failed, delivering as-is:', err?.message);
}
// The reconstructors fuse a floor plate under a resting subject even from a
// clean cutout (glb-floor-slab.js). Cut it here, on geometry alone, so the
// fix never depends on a vision provider answering, and before scoring so
// the quality signal describes the model users actually receive.
try {
const r = await stripFloorSlab(outBuf);
if (r.stripped) {
outBuf = r.buffer;
cleaned = { ...(cleaned || {}), floor_slab_removed_tris: r.removedTriangles };
}
} catch (err) {
console.warn('[forge-store] floor slab strip failed, delivering as-is:', err?.message);
}
}
// Bbox fit SECOND, still before material completion: it rescales and
// recenters the whole mesh (glb-bbox-fit.js), which must happen after the
// floor-slab strip settles the final geometry (fitting around a slab that is
// about to be cut would waste the fit) and before PBR derivation measures or
// bakes anything resolution-dependent on the final scale.
if (bbox) {
try {
const r = await fitBbox(outBuf, bbox);
if (r.fitted) {
outBuf = r.buffer;
fit = { bbox, scale: r.scale };
}
} catch (err) {
console.warn('[forge-store] bbox fit failed, delivering at native scale:', err?.message);
}
}
// Material completion THIRD: it reads the albedo the lane baked and writes
// derived maps onto the geometry cleanup just settled, so it has to run after
// cleanup and before the codec pass (a Draco/meshopt-encoded buffer would
// have to be decoded again to touch its materials) and before quality
// scoring, so `no_materials` reflects what users actually receive.
if (derivePbr) {
try {
const r = await derivePbrChannels(outBuf, { prompt, tier, materialClass });
if (r.changed) {
outBuf = r.buffer;
pbr = {
input_bytes: r.inputBytes,
output_bytes: r.outputBytes,
materials_created: r.materialsCreated,
normals_filled: r.normalsFilled,
mime_types_fixed: r.mimeTypesFixed,
materials: r.materials,
};
}
} catch (err) {
console.warn('[forge-store] PBR derivation failed, delivering lane materials as-is:', err?.message);
}
}
if (computeQuality) {
try {
quality = scoreGlbQuality(outBuf);
} catch (err) {
console.warn('[forge-store] quality scoring failed:', err?.message);
}
}
if (compress) {
try {
const result = await compressGlb(outBuf, { mode: compress });
if (result.grew) {
compression = { mode: result.mode, skipped: true, reason: 'no_size_benefit' };
} else {
outBuf = result.buffer;
compression = {
mode: result.mode,
input_bytes: result.inputBytes,
output_bytes: result.outputBytes,
ratio: result.ratio,
};
}
} catch (err) {
console.warn(`[forge-store] compression (${compress}) failed, delivering uncompressed:`, err?.message);
compression = { mode: compress, skipped: true, reason: 'compression_failed' };
}
}
return { buf: outBuf, quality, compression, cleaned, pbr, fit };
}
// An upstream Content-Type ends up as the object's stored type, which the CDN
// then serves from the three.ws origin. Only ever store a media type: a
// provider (or a redirect chain that ends somewhere unexpected) answering with
// `text/html` or `image/svg+xml` must not get to decide that.
const STORABLE_TYPE_RE = /^(?:image\/(?:png|jpeg|webp|gif|avif)|model\/[\w.+-]+|video\/(?:mp4|webm)|audio\/[\w.+-]+|application\/(?:json|octet-stream))$/;
function mediaTypeOr(header, fallback) {
const type = String(header || '').split(';')[0].trim().toLowerCase();
return STORABLE_TYPE_RE.test(type) ? type : fallback;
}
async function copyToBucket({ sourceUrl, key, fallbackContentType, maxBytes, computeQuality = false, compress = null, cleanup = false, derivePbr = false, bbox = null, prompt = '', tier = '', materialClass = '', forceContentType = null, untrustedSource = false }) {
// fetchUpstream retries network errors and 408/425/429/5xx with jittered
// backoff and gives up immediately on 404/410 (the ephemeral asset has
// already expired; no retry can recover it), rejecting with an error that
// carries `status` so callers keep classifying it the same way.
// An untrusted source (a reference image the caller named) is fetched with
// every redirect hop SSRF-checked: the bytes land in a public bucket, so an
// unchecked hop would publish whatever an internal host answered.
const fetcher = untrustedSource ? fetchUpstreamPublic : fetchUpstream;
const resp = await fetcher(sourceUrl, {}, { timeoutMs: COPY_TIMEOUT_MS, attempts: COPY_MAX_ATTEMPTS, label: 'forge asset copy' });
let buf = Buffer.from(await resp.arrayBuffer());
if (buf.length > maxBytes) throw new Error(`asset too large: ${buf.length} bytes`);
// forceContentType wins over the upstream header: providers (Replicate
// et al.) often serve ephemeral output blobs as `application/octet-stream`
// or another generic type regardless of the actual bytes. Trusting that
// verbatim into R2's stored Content-Type is what made every homepage
// forge thumbnail fail Chrome's Opaque Response Blocking: the browser
// won't render a cross-origin <img> whose declared type isn't an image
// type. Callers that know the asset kind (e.g. the preview image, whose
// extension is already decided by imageExtFor) should force it.
const contentType = forceContentType || mediaTypeOr(resp.headers.get('content-type'), fallbackContentType);
let quality = null;
let compression = null;
let cleaned = null;
let pbr = null;
let fit = null;
if (computeQuality || compress || cleanup || derivePbr || bbox) {
const scored = await scoreAndCompress(buf, { computeQuality, compress, cleanup, derivePbr, bbox, prompt, tier, materialClass });
buf = scored.buf;
quality = scored.quality;
compression = scored.compression;
cleaned = scored.cleaned;
pbr = scored.pbr;
fit = scored.fit;
}
await putObject({ key, body: buf, contentType, metadata: { source: 'forge' } });
// `buffer` is the bytes actually stored, post-cleanup and post-compression, so
// a caller that hashes or grades them is describing the asset users receive
// rather than the provider's original, and does it without a second fetch.
// The URL handed back is the same-origin /cdn/ proxy, not the raw bucket
// domain: a browser <img>/<model-viewer> consumer of this field is exactly
// what Chrome's ORB blocked above, so every durable forge URL must be
// ORB-safe the same way avatar thumbnails already are (thumbnailUrl()).
return { bytes: buf.length, publicUrl: cdnUrl(key), quality, compression, cleaned, pbr, fit, buffer: buf };
}
function imageExtFor(url) {
const m = /\.(png|jpe?g|webp)(\?|$)/i.exec(url || '');
return m ? m[1].toLowerCase().replace('jpeg', 'jpg') : 'webp';
}
const IMAGE_CONTENT_TYPE_BY_EXT = { png: 'image/png', jpg: 'image/jpeg', webp: 'image/webp' };
function imageContentTypeFor(ext) {
return IMAGE_CONTENT_TYPE_BY_EXT[ext] || 'image/webp';
}
// Grade the delivered mesh for simulation readiness and cache the report by its
// content hash (api/_lib/sim-readiness-store.js). Every finished generation
// becomes a graded asset, which is what turns the free grade endpoint from an
// on-demand tool into a growing corpus: by the time anyone asks about one of our
// meshes, the answer is already a hash lookup.
//
// Deliberately fire-and-forget and fully wrapped. Grading is ~1.5 s of pure CPU
// against a generation that already took tens of seconds, but a user waiting on
// their model must never lose it to a grader bug or a database blip: any failure
// here leaves the creation ungraded and delivered, never failed.
function gradeDeliveredMesh({ buffer, creationId, sourceUrl }) {
if (!buffer?.length) return;
const started = Date.now();
Promise.resolve()
.then(() => gradeSimReadiness(buffer))
.then((report) =>
putGrade({
glbSha256: createHash('sha256').update(buffer).digest('hex'),
report,
sourceUrl,
creationId,
sizeBytes: buffer.length,
gradeMs: Date.now() - started,
}),
)
.catch((err) => console.warn('[forge-store] simulation-readiness grading failed:', err?.message));
}
// The web-delivery variant of a finished mesh: meshopt geometry plus WebP
// textures capped at 2048 px (api/_lib/glb-compress.js). On the six production
// forge outputs sampled on 2026-09-04 it cut 1.25-3.34 MB down to 0.11-0.67 MB,
// which on a phone over slow 4G is the difference between a mesh that arrives in
// seconds and one that does not arrive at all.
//
// Two deliberate choices:
//
// 1. It is a SECOND object, never a replacement. `glb_url` keeps exactly the
// bytes the caller's `output_format` asked for, so the download action hands
// back the full-resolution original and a third-party consumer with a bare
// GLTFLoader is never handed an EXT_meshopt_compression file it cannot
// decode. Our own viewers ask for `web_glb_url` and fall back on a decode
// failure.
// 2. It runs AFTER the row is flipped to 'done', fire-and-forget, exactly like
// gradeDeliveredMesh above. The pass costs 2-6 s of CPU; the person waiting
// on their generation must never wait on it, and must never lose a finished
// model because a compression bug or an instance recycle killed the request.
// A row whose variant never lands simply keeps `web_glb_url` null, and every
// reader treats null as "serve glb_url".
//
// Skips meshes already small enough that the pass cannot pay for itself.
const WEB_VARIANT_MIN_BYTES = 512 * 1024;
// Below this the variant is not worth a second object: keep storage honest.
const WEB_VARIANT_MIN_GAIN = 0.9;
export function buildWebVariant({ buffer, creationId, keyPrefix }) {
if (!buffer?.length || buffer.length < WEB_VARIANT_MIN_BYTES) return Promise.resolve(null);
const key = `${keyPrefix}.web.glb`;
return Promise.resolve()
.then(() => compressGlb(buffer, deliveryCompressionOptions()))
.then(async (result) => {
if (result.grew || result.outputBytes > buffer.length * WEB_VARIANT_MIN_GAIN) return null;
await putObject({
key,
body: result.buffer,
contentType: 'model/gltf-binary',
metadata: { source: 'forge-web-variant' },
});
await sql`
update forge_creations
set web_glb_key = ${key},
web_glb_url = ${cdnUrl(key)},
web_size_bytes = ${result.outputBytes},
updated_at = now()
where id = ${creationId}
`;
return { key, url: cdnUrl(key), bytes: result.outputBytes };
})
.catch((err) => {
console.warn('[forge-store] web delivery variant failed:', err?.message);
return null;
});
}
// The opt-in LOD chain variant: a real MSFT_lod GLB (packages/glb-tools's
// buildLodChain, meshoptimizer decimation) a real-time engine can switch levels
// from at runtime, built alongside the base mesh when the caller asks for it
// (forge-options.js's `lods` flag). Same reasoning as buildWebVariant above:
// a SECOND object (glb_url stays exactly the requested output_format), built
// fire-and-forget after the row is already 'done' so a slow or failed build
// never delays delivery of the mesh itself. lod_levels carries the per-level
// triangle/vertex counts so a reader never has to fetch and parse the GLB just
// to show the chain's shape.
export function buildLodVariant({ buffer, creationId, keyPrefix }) {
if (!buffer?.length) return Promise.resolve(null);
const key = `${keyPrefix}.lod.glb`;
return Promise.resolve()
.then(() => import('../../packages/glb-tools/src/lod.js'))
.then(({ buildLodChain }) => buildLodChain(buffer))
.then(async (chain) => {
const levels = chain.levels.map((l) => ({
name: l.name,
ratio: l.ratio,
triangleCount: l.triangleCount,
vertexCount: l.vertexCount,
}));
await putObject({
key,
body: chain.combined,
contentType: 'model/gltf-binary',
metadata: { source: 'forge-lod-variant' },
});
await sql`
update forge_creations
set lod_glb_key = ${key},
lod_glb_url = ${cdnUrl(key)},
lod_levels = ${JSON.stringify(levels)},
updated_at = now()
where id = ${creationId}
`;
return { key, url: cdnUrl(key), levels };
})
.catch((err) => {
console.warn('[forge-store] LOD chain variant failed:', err?.message);
return null;
});
}
// Copy a finished generation into durable storage and flip the row to 'done'.
// Copies the mesh (required) and the reference image (best-effort). Returns the
// durable { id, glbUrl, previewImageUrl, quality, compression } or null on any
// failure so the caller can fall back to the provider URL.
//
// Two additive, opt-in params:
// quality — when true, scores the mesh (glb-quality.js) and returns the
// signal in `quality`. Off by default so an existing caller's
// response shape and latency are unaffected.
// compress — 'draco' | 'meshopt' to deliver a geometry-compressed variant
// (glb-compress.js) instead of the raw provider bytes. Falls back
// to uncompressed on any compression failure — never blocks
// delivery. Omitted/null preserves today's uncompressed behavior.
// cleanup — run the codec-independent geometry cleanup (glb-cleanup.js:
// dedup/join/weld/simplify) on the delivered mesh. On by default:
// every forge mesh is raw marching-cubes output that benefits, and
// it's best-effort (any failure ships the original bytes). Pass
// false to deliver the provider geometry untouched.
// derivePbr - complete the material set (glb-pbr-derive.js): a derived normal
// map, a packed occlusion/roughness/metallic map, the material
// class's measured factors and its real-world extension layer. On
// by default, because every reconstruction lane bakes an albedo
// and stops (the free TRELLIS lanes ship no materials at all, so
// glTF's default fully-metallic material renders them as rough
// metal). Best-effort like the rest of the chain; pass false to
// deliver the lane's own materials untouched.
// lods - build and store a real MSFT_lod chain (buildLodVariant above).
// Off by default: it is real decimation work, worth its own opt-in
// exactly like forge-options.js documents. Fire-and-forget, same
// as the web-delivery variant it sits beside.
export async function materializeCreation({ replicateJobId, clientKey, glbUrl, quality = false, compress = null, cleanup = true, derivePbr = true, bbox = null, lods = false }) {
if (!forgeStoreEnabled() || !replicateJobId || !glbUrl) return null;
const existing = await findByJob({ replicateJobId, clientKey });
if (!existing) return null;
// Idempotent: a repeat poll after completion returns the durable copy.
if (existing.status === 'done' && existing.glb_url) {
return {
id: existing.id,
glbUrl: existing.glb_url,
previewImageUrl: existing.preview_image_url ?? null,
quality: null,
compression: null,
cleaned: null,
pbr: null,
fit: null,
};
}
const keyPrefix = `forge/${clientKey.slice(0, 12)}/${existing.id}`;
try {
const glb = await copyToBucket({
sourceUrl: glbUrl,
key: `${keyPrefix}.glb`,
fallbackContentType: 'model/gltf-binary',
maxBytes: MAX_GLB_BYTES,
computeQuality: quality,
compress,
cleanup,
derivePbr,
bbox,
// The row carries the words the material classifier reads and the tier
// that sets the derived maps' resolution, so no caller has to thread
// either through the poll path.
prompt: existing.prompt || '',
tier: existing.tier || '',
});
// Reference image is part of the training pair but never blocks the mesh.
let preview = { key: null, url: existing.preview_image_url ?? null };
if (existing.preview_image_url) {
try {
const ext = imageExtFor(existing.preview_image_url);
const copied = await copyToBucket({
sourceUrl: existing.preview_image_url,
key: `${keyPrefix}.${ext}`,
fallbackContentType: 'image/webp',
forceContentType: imageContentTypeFor(ext),
maxBytes: MAX_IMAGE_BYTES,
// preview_image_url can be the caller's own reference image URL.
untrustedSource: true,
});
preview = { key: `${keyPrefix}.${ext}`, url: copied.publicUrl };
} catch (imgErr) {
console.error('[forge-store] preview copy failed:', imgErr?.message);
}
}
await sql`
update forge_creations
set status = 'done',
glb_key = ${`${keyPrefix}.glb`},
glb_url = ${glb.publicUrl},
preview_key = ${preview.key},
preview_image_url = ${preview.url},
size_bytes = ${glb.bytes},
completed_at = coalesce(completed_at, now()),
updated_at = now()
where id = ${existing.id} and client_key = ${clientKey}
`;
// Terminal success — the one universal completion writer every lane (free
// HF, async Replicate poll, BYOK) flows through, so it's where the rolling
// success/latency counters are recorded. Latency is wall-clock from the row's
// created_at; null if the timestamp is unreadable rather than a bogus number.
const startedAt = existing.created_at ? Date.parse(existing.created_at) : NaN;
const latencyMs = Number.isFinite(startedAt) ? Date.now() - startedAt : null;
await recordGenerationEvent({
phase: 'done',
backend: existing.backend,
tier: existing.tier,
path: existing.path,
latencyMs,
source: 'materialize',
});
// Every delivered mesh gets a physics grade, cached by content hash.
gradeDeliveredMesh({ buffer: glb.buffer, creationId: existing.id, sourceUrl: glb.publicUrl });
// ...and a free, signed content credential by default (work order 079), no
// explicit anchor_provenance call required. Fire-and-forget like the grade
// above: a signing/storage hiccup here must never delay delivery.
autoCredentialForBytes({
buffer: glb.buffer,
assetId: existing.id,
creator: existing.user_id || existing.client_key || null,
prompt: existing.prompt || null,
model: existing.backend || null,
provider: existing.path || null,
}).catch(() => {});
// …and a phone-sized delivery variant. See buildWebVariant for why this is
// a second object and why it runs after the row is already 'done'.
buildWebVariant({ buffer: glb.buffer, creationId: existing.id, keyPrefix });
// …and, when the caller opted in, a real LOD chain. See buildLodVariant.
if (lods) buildLodVariant({ buffer: glb.buffer, creationId: existing.id, keyPrefix });
// A finished, signed-in creation is a qualifying streak action + the
// trigger for the "first creation" badge. Fire-and-forget — never blocks
// delivery of the model itself.
if (existing.user_id) {
recordDailyActivity(existing.user_id).catch(() => {});
maybeAwardFirstCreation(existing.user_id).catch(() => {});
// A generation submitted over the API outlives the request that started
// it, so an integrator's only completion signal is polling unless we push
// one. This is the single writer every lane finishes through, and the
// early return above makes it idempotent, so the event fires exactly once
// per job. Fire-and-forget, like every other side effect here: a slow or
// dead developer endpoint must never delay delivery of the model.
dispatchWebhooks({
userId: existing.user_id,
eventType: 'forge.completed',
data: {
id: existing.id,
status: 'done',
prompt: existing.prompt || null,
glb_url: glb.publicUrl,
preview_image_url: preview.url,
backend: existing.backend || null,
tier: existing.tier || null,
path: existing.path || null,
size_bytes: glb.bytes,
latency_ms: latencyMs,
},
}).catch(() => {});
}
return {
id: existing.id,
glbUrl: glb.publicUrl,
previewImageUrl: preview.url,
quality: glb.quality ?? null,
compression: glb.compression ?? null,
cleaned: glb.cleaned ?? null,
pbr: glb.pbr ?? null,
fit: glb.fit ?? null,
};
} catch (err) {
// A 404/410 means the provider's ephemeral asset (e.g. a HuggingFace Space's
// gradio /tmp mesh) expired before we could copy it — expected and fully
// handled here by returning null so the caller falls back to the provider
// URL. Log it at WARN so it doesn't flood the actionable-error view; genuine
// failures (storage write, oversize, 5xx after retries) stay at ERROR.
const recoverable = err?.status === 404 || err?.status === 410;
const log = recoverable ? console.warn : console.error;
log('[forge-store] materializeCreation failed:', err?.message);
return null;
}
}
// Attach a client-rendered poster to a creation that has no preview image.
// Geometry-first and sketch lanes never paint a flux reference image, so their
// gallery/showcase cards had nothing to show; the browser renders the actual
// mesh to a small webp and posts it here. Fill-only: a row that already has a
// preview (the flux reference image — part of the training pair) is never
// overwritten. Scoped to the owning client. Returns the durable URL or null.
export async function attachPoster({ id, clientKey, body, contentType, ext }) {
if (!forgeStoreEnabled() || !id || !body) return null;
try {
const rows = await sql`
select id, preview_image_url
from forge_creations
where id = ${id} and client_key = ${clientKey} and status = 'done'
limit 1
`;
const existing = rows[0];
if (!existing || existing.preview_image_url) return null;
const key = `forge/${clientKey.slice(0, 12)}/${id}-poster.${ext}`;
await putObject({ key, body, contentType, metadata: { source: 'forge-poster' } });
const url = cdnUrl(key);
const updated = await sql`
update forge_creations
set preview_key = ${key}, preview_image_url = ${url}, updated_at = now()
where id = ${id} and client_key = ${clientKey} and preview_image_url is null
returning id
`;
return updated.length > 0 ? url : null;
} catch (err) {
console.error('[forge-store] attachPoster failed:', err?.message);
return null;
}
}
export async function markFailed({ replicateJobId, clientKey, error }) {
if (!forgeStoreEnabled() || !replicateJobId) return;
try {
const rows = await sql`
update forge_creations
set status = 'failed', error = ${String(error || 'generation failed').slice(0, 500)},
completed_at = coalesce(completed_at, now()), updated_at = now()
where replicate_job_id = ${replicateJobId} and client_key = ${clientKey} and status != 'done'
returning backend, tier, path
`;
// Terminal failure — counted only when a row actually flipped to 'failed'
// (returning is empty when the job already completed or never existed), so a
// stray late poll can't inflate the failure rate.
const row = rows[0];
if (row) {
await recordGenerationEvent({
phase: 'failed',
backend: row.backend,
tier: row.tier,
path: row.path,
source: 'mark_failed',
});
}
} catch (err) {
console.error('[forge-store] markFailed failed:', err?.message);
}
}
/**
* Link a failed attempt to the successor row that re-ran it on another lane.
*
* Both failover paths already resubmit the original inputs and create a
* successor creation row; without this link the ledger shows only the failure,
* so the health sensor and the error report count a recovered attempt as a
* user-visible loss (see the migration 20260814200000_forge_failover_supersede
* for the production numbers that motivated it).
*
* Best-effort by design: the failover itself has already succeeded by the time
* this runs, and losing the annotation must never turn a recovered generation
* into a failed one.
*
* @param {{ replicateJobId: string, clientKey: string, successorId: string }} input
* @returns {Promise<boolean>} true when a row was annotated.
*/
export async function markSupersededBy({ replicateJobId, clientKey, successorId }) {
if (!forgeStoreEnabled() || !replicateJobId || !successorId) return false;
try {
const rows = await sql`
update forge_creations
set superseded_by = ${successorId}, updated_at = now()
where replicate_job_id = ${replicateJobId}
and client_key = ${clientKey}
and status = 'failed'
and superseded_by is null
returning id
`;
return rows.length > 0;
} catch (err) {
console.error('[forge-store] markSupersededBy failed:', err?.message);
return false;
}
}
// Permanently delete a creation: the stored mesh, the stored preview, every
// recorded source upload (the user's reference photos), and the row itself.
// Scoped to the owning client_key so one browser can never erase another's
// work. Bucket objects go first: if storage refuses, the row survives and the
// user can simply retry; deleting the row first would strand unreferenced
// bytes with no handle left to retry from. The row delete then cascades
// forge_votes and forge_comments; lineage children and forge_board_winners
// null their reference (see the migrations that created those FKs).
// Returns 'deleted' | 'not_found' | 'error' | 'unavailable'.
export async function deleteCreation({ id, clientKey }) {
if (!forgeStoreEnabled() || !id || !clientKey) return 'unavailable';
try {
const rows = await sql`
select id, glb_key, glb_url, preview_key, preview_image_url, source_image_keys
from forge_creations
where id = ${id} and client_key = ${clientKey}
limit 1
`;
const row = rows[0];
if (!row) return 'not_found';
// Every bucket object the row points at. URL-derived keys cover legacy
// rows written before the *_key columns existed, and a preview that still
// points at the raw upload because the durable copy failed. The forge/
// prefix guard keeps a corrupted row from ever deleting outside the
// forge namespace.
const keys = new Set();
for (const k of [row.glb_key, row.preview_key]) {
if (typeof k === 'string' && k.startsWith('forge/')) keys.add(k);
}
for (const u of [row.glb_url, row.preview_image_url]) {
const k = keyFromPublicUrl(u);
if (k && k.startsWith('forge/')) keys.add(k);
}
for (const k of Array.isArray(row.source_image_keys) ? row.source_image_keys : []) {
if (typeof k === 'string' && k.startsWith('forge/')) keys.add(k);
}
await Promise.all([...keys].map((key) => deleteObject(key)));
await sql`delete from forge_creations where id = ${id} and client_key = ${clientKey}`;
return 'deleted';
} catch (err) {
if (isDbUnavailableError(err)) {
console.warn('[forge-store] deleteCreation skipped (db unavailable):', err?.message);
return 'unavailable';
}
console.error('[forge-store] deleteCreation failed:', err?.message);
return 'error';
}
}
const VALID_OUTCOMES = new Set(['accepted', 'rejected', 'generated']);
// Capture the human verdict on a creation. Scoped to the owning client so a
// verdict can't be forged for someone else's row. Returns true on a real write.
export async function recordFeedback({ id, clientKey, outcome, downloaded, rating, note, destination }) {
if (!forgeStoreEnabled() || !id) return false;
const nextDestination = validForgeDestination(destination);
const nextOutcome = VALID_OUTCOMES.has(outcome) ? outcome : null;
const nextRating =
Number.isInteger(rating) && rating >= 1 && rating <= 5 ? rating : null;
const nextNote = typeof note === 'string' && note.trim() ? note.trim().slice(0, 500) : null;
const markDownloaded = downloaded === true;
// Nothing meaningful to record → don't touch the row.
if (!nextOutcome && nextRating === null && nextNote === null && !markDownloaded && !nextDestination) {
return false;
}
try {
const rows = await sql`
update forge_creations
set outcome = coalesce(${nextOutcome}, outcome),
rating = coalesce(${nextRating}, rating),
note = coalesce(${nextNote}, note),
downloaded = (downloaded or ${markDownloaded}),
destination = coalesce(${nextDestination}, destination),
feedback_at = now(),
updated_at = now()
where id = ${id} and client_key = ${clientKey}
returning id
`;
return rows.length > 0;
} catch (err) {
console.error('[forge-store] recordFeedback failed:', err?.message);
return false;
}
}
// Update the model_category on a forge creation. Scoped to the owning client.
export async function setForgeCategory({ id, clientKey, modelCategory }) {
if (!forgeStoreEnabled() || !id) return false;
const category = validModelCategory(modelCategory);
if (!category) return false;
try {
const rows = await sql`
update forge_creations
set model_category = ${category}, updated_at = now()
where id = ${id} and client_key = ${clientKey}
returning id
`;
return rows.length > 0;
} catch (err) {
console.error('[forge-store] setForgeCategory failed:', err?.message);
return false;
}
}
// Fetch a single durable creation by id, NOT scoped to any client. Powers the
// share flow: a recipient who didn't forge the model still gets to view it.
// Only returns finished, durably-stored rows — an in-flight or failed creation
// has no public artifact to show. Returns null when missing or store-disabled.
export async function getPublicCreation({ id, voterKey = null }) {
if (!forgeStoreEnabled() || !id) return null;
try {
const rows = await sql`
select fc.id, fc.prompt, fc.aspect, fc.glb_url, fc.web_glb_url, fc.web_size_bytes,
fc.preview_image_url, fc.outcome,
fc.views_used, fc.multiview, fc.backend, fc.tier, fc.path, fc.model_category, fc.created_at,
fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,
fc.vote_count, fc.size_bytes, fc.remixable, fc.remix_royalty_bps,
fc.parent_creation_id, fc.refine_instruction,
coalesce(fc.view_count, 0) as view_count,
(select count(*)::int from forge_creations c where c.parent_creation_id = fc.id) as remix_count,
exists(select 1 from forge_votes v
where v.creation_id = fc.id and v.voter_key = ${voterKey ?? ''}) as voted,
u.username as creator_username,
u.display_name as creator_display_name,
u.avatar_url as creator_avatar_url,
g.report as sim_readiness,
g.graded_at as sim_readiness_graded_at
from forge_creations fc
left join users u on u.id = fc.user_id and u.deleted_at is null
-- The physics grade for this creation's own bytes, written when the
-- generation was materialized. Joined here so the model page renders
-- the verdict without a second round trip and, more importantly,
-- without re-fetching the GLB just to recompute a hash it already has
-- a row for. Null is the honest answer for an older creation nobody
-- has graded yet, and the page has a state for that.
left join sim_readiness_grades g on g.creation_id = fc.id
where fc.id = ${id} and fc.status = 'done' and fc.glb_url is not null
and (fc.visibility is null or fc.visibility in ('public', 'unlisted'))
limit 1
`;
const r = rows[0];
if (!r) return null;
return {
id: r.id,
prompt: r.prompt,
aspect: r.aspect,
glb_url: normalizeStoredUrl(r.glb_url),
// The phone-sized delivery variant, or null when one was never built.
// Viewers prefer it and fall back to glb_url; downloads always use
// glb_url. See buildWebVariant.
web_glb_url: normalizeStoredUrl(r.web_glb_url) ?? null,
web_size_bytes: r.web_size_bytes ?? null,
preview_image_url: normalizeStoredUrl(r.preview_image_url),
outcome: r.outcome,
views_used: r.views_used ?? null,
multiview: r.multiview ?? null,
backend: r.backend ?? null,
tier: r.tier ?? null,
path: r.path ?? null,
model_category: r.model_category ?? 'other',
created_at: r.created_at,
vote_count: r.vote_count ?? 0,
voted: r.voted === true,
view_count: r.view_count ?? 0,
remix_count: r.remix_count ?? 0,
size_bytes: r.size_bytes ?? null,
remixable: r.remixable === true,
remix_royalty_bps: r.remix_royalty_bps ?? null,
parent_creation_id: r.parent_creation_id ?? null,
refine_instruction: r.refine_instruction ?? null,
// Real, opt-in attribution only — set when the model was forged while
// signed in. Never invented for anonymous generations.
creatorUsername: r.creator_username || null,
creatorDisplayName: r.creator_display_name || r.creator_username || null,
creatorAvatarUrl: r.creator_avatar_url || null,
simReadiness: r.sim_readiness ?? null,
simReadinessGradedAt: r.sim_readiness_graded_at ? new Date(r.sim_readiness_graded_at).toISOString() : null,
...x402Provenance(r),
};
} catch (err) {
console.error('[forge-store] getPublicCreation failed:', err?.message);
return null;
}
}
// Count a model-page impression. Fail-soft and fire-and-forget: the page read
// never blocks (or breaks) on the counter, and a miss is just an uncounted
// view. Distinct from views_requested/views_used (multiview camera counts).
export async function recordCreationView({ id }) {
if (!forgeStoreEnabled() || !id) return;
try {
await sql`
update forge_creations set view_count = coalesce(view_count, 0) + 1
where id = ${id} and status = 'done'
`;
} catch (err) {
console.error('[forge-store] recordCreationView failed:', err?.message);
}
}
// Suggested models for the detail page's sidebar: newest finished community
// models in the same category first, backfilled with fresh models from any
// category when the category is thin, never including the model itself.
// Card-shaped like listShowcase items (minus vote state, which is per-browser).
export async function listRelated({ id, category, limit = 6 }) {
if (!forgeStoreEnabled() || !id) return [];
const capped = Math.min(Math.max(Number(limit) || 6, 1), 12);
const cat = validModelCategory(category);
try {
const rows = await sql`
select id, prompt, glb_url, preview_image_url, model_category, backend,
vote_count, coalesce(view_count, 0) as view_count, created_at,
(model_category = ${cat ?? ''}) as same_category
from forge_creations
where status = 'done' and glb_url is not null and id != ${id}
and (visibility is null or visibility = 'public')
order by (model_category = ${cat ?? ''}) desc, created_at desc
limit ${capped}
`;
return rows.map((r) => ({
id: r.id,
prompt: r.prompt,
glb_url: normalizeStoredUrl(r.glb_url),
preview_image_url: normalizeStoredUrl(r.preview_image_url),
model_category: r.model_category ?? 'other',
backend: r.backend ?? null,
vote_count: r.vote_count ?? 0,
view_count: r.view_count ?? 0,
created_at: r.created_at,
}));
} catch (err) {
console.error('[forge-store] listRelated failed:', err?.message);
return [];
}
}
// Link an already-created creation to the one it was derived from, marking it as
// a refinement/remix in the lineage. Called AFTER the derived model is generated
// (the base row exists from createCreation), so the durable parent → child edge
// is written without touching the many-laned /api/forge submit path. Sets
// parent_creation_id + refine_instruction + lineage_index. Idempotent per row.
// Returns true on success, false when the store is unavailable or the row is
// missing / not owned by clientKey.
export async function linkRefinement({
creationId,
clientKey,
parentCreationId,
refineInstruction,
lineageIndex,
}) {
if (!forgeStoreEnabled() || !creationId || !parentCreationId) return false;
try {
const rows = await sql`
update forge_creations
set parent_creation_id = ${parentCreationId},
refine_instruction = ${refineInstruction ?? null},
lineage_index = ${typeof lineageIndex === 'number' ? lineageIndex : 1},
updated_at = now()
where id = ${creationId}
and (${clientKey}::text is null or client_key = ${clientKey})
and parent_creation_id is null
returning id
`;
return rows.length > 0;
} catch (err) {
console.error('[forge-store] linkRefinement failed:', err?.message);
return false;
}
}
// Return the full lineage thread rooted at rootCreationId: the root itself plus
// all descendants in lineage_index order. Fails soft (returns []) when the store
// is unavailable or the root doesn't exist. The caller reconstructs the tree
// structure using parent_creation_id + lineage_index.
export async function getLineage({ rootCreationId, clientKey }) {
if (!forgeStoreEnabled() || !rootCreationId) return [];
try {
// Recursive CTE: walk descendants of the root creation. Up to 50 versions
// per thread (a hard cap so a misbehaving recursive loop can't exhaust the
// connection pool). Rows are returned newest-first within each lineage_index
// so the latest refinement at each depth comes first.
const rows = await sql`
with recursive thread as (
select id, parent_creation_id, prompt, refine_instruction, lineage_index,
glb_url, preview_image_url, status, backend, created_at
from forge_creations
where id = ${rootCreationId}
and (${clientKey}::text is null or client_key = ${clientKey})
union all
select fc.id, fc.parent_creation_id, fc.prompt, fc.refine_instruction,
fc.lineage_index, fc.glb_url, fc.preview_image_url, fc.status,
fc.backend, fc.created_at
from forge_creations fc
join thread t on fc.parent_creation_id = t.id
)
select * from thread
order by lineage_index asc, created_at asc
limit 50
`;
return rows.map((r) => ({
id: r.id,
parent_creation_id: r.parent_creation_id,
prompt: r.prompt,
refine_instruction: r.refine_instruction,
lineage_index: r.lineage_index,
glb_url: normalizeStoredUrl(r.glb_url),
preview_image_url: normalizeStoredUrl(r.preview_image_url),
status: r.status,
backend: r.backend,
created_at: r.created_at,
}));
} catch (err) {
console.error('[forge-store] getLineage failed:', err?.message);
return [];
}
}
// Newest durable creations for one anonymous client — powers the gallery.
export async function listCreations({ clientKey, limit = 24 }) {
if (!forgeStoreEnabled()) return [];
const capped = Math.min(Math.max(Number(limit) || 24, 1), 48);
try {
const rows = await sql`
select id, prompt, aspect, glb_url, web_glb_url, preview_image_url, outcome, downloaded,
views_used, multiview, backend, tier, path, model_category, created_at
from forge_creations
where client_key = ${clientKey} and status = 'done' and glb_url is not null
order by created_at desc
limit ${capped}
`;
return rows.map((r) => ({
id: r.id,
prompt: r.prompt,
aspect: r.aspect,
glb_url: normalizeStoredUrl(r.glb_url),
web_glb_url: normalizeStoredUrl(r.web_glb_url) ?? null,
preview_image_url: normalizeStoredUrl(r.preview_image_url),
outcome: r.outcome,
downloaded: r.downloaded,
views_used: r.views_used ?? null,
multiview: r.multiview ?? null,
backend: r.backend ?? null,
tier: r.tier ?? null,
path: r.path ?? null,
// Not a stored column: Tripo's model version is a deployment-wide
// setting, read live the same way pollJob does, so the gallery card
// names exactly what produced the mesh without a schema change.
engine_version: r.backend === 'tripo' ? tripoModelVersion() : null,
model_category: r.model_category ?? 'other',
created_at: r.created_at,
}));
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] listCreations skipped (db unavailable):', err?.message);
else console.error('[forge-store] listCreations failed:', err?.message);
return [];
}
}
// A signed-in creator's finished, durably-stored models — powers the
// "Models" tab on their public portfolio (/u/:username). Scoped to user_id,
// not client_key, so it only ever surfaces creations made while logged in;
// anonymous forges (the majority) never attach to any profile. Cursor
// pagination by created_at mirrors listRemixable so the profile's "load
// more" can page through a prolific creator's full history.
export async function listCreationsByUser({ userId, limit = 24, before } = {}) {
if (!forgeStoreEnabled() || !userId) return [];
const capped = Math.min(Math.max(Number(limit) || 24, 1), 60);
try {
const rows = before
? await sql`
select id, prompt, glb_url, preview_image_url, model_category,
parent_creation_id, remixable, created_at
from forge_creations
where user_id = ${userId} and status = 'done' and glb_url is not null
and (visibility is null or visibility = 'public')
and created_at < ${before}
order by created_at desc
limit ${capped}
`
: await sql`
select id, prompt, glb_url, preview_image_url, model_category,
parent_creation_id, remixable, created_at
from forge_creations
where user_id = ${userId} and status = 'done' and glb_url is not null
and (visibility is null or visibility = 'public')
order by created_at desc
limit ${capped}
`;
return rows.map((r) => ({
id: r.id,
type: 'model',
prompt: r.prompt,
glbUrl: normalizeStoredUrl(r.glb_url),
webGlbUrl: normalizeStoredUrl(r.web_glb_url) ?? null,
previewImageUrl: normalizeStoredUrl(r.preview_image_url),
category: r.model_category ?? 'other',
isRemix: Boolean(r.parent_creation_id),
remixable: Boolean(r.remixable),
createdAt: r.created_at,
}));
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] listCreationsByUser skipped (db unavailable):', err?.message);
else console.error('[forge-store] listCreationsByUser failed:', err?.message);
return [];
}
}
// Count of a signed-in creator's finished, stored models — cheap stat-strip
// number, separate from the paginated list above.
export async function countCreationsByUser({ userId } = {}) {
if (!forgeStoreEnabled() || !userId) return 0;
try {
const [row] = await sql`
select count(*)::int as n
from forge_creations
where user_id = ${userId} and status = 'done' and glb_url is not null
and (visibility is null or visibility = 'public')
`;
return row?.n ?? 0;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] countCreationsByUser skipped (db unavailable):', err?.message);
else console.error('[forge-store] countCreationsByUser failed:', err?.message);
return 0;
}
}
// Newest durable creations across ALL clients — powers the public "Fresh from
// the Forge" showcase on /forge. Same public-artifact bar as the share flow
// (getPublicCreation): finished rows with a stored GLB only. Rows the creator
// explicitly discarded (outcome = 'rejected') are excluded — a model its own
// maker rated as bad is not showcase material. No client_key in the SELECT, so
// nothing identifying ever leaves the store.
//
// Two orderings, both over the same public-artifact set:
// • sort='fresh' (default) — visual-first, newest: the shop window. Rows with
// a preview image lead (geometry-first lanes paint none), recency breaks
// ties. This is the historical "Fresh from the Forge" strip.
// • sort='top' — the Forge-Off board: most community votes first, recency
// breaks ties, over the current Forge-Off week when window='week'. Served by
// idx_forge_creations_board.
// Every row now carries vote_count and, when a voterKey is supplied, a per-row
// `voted` flag so the UI can render the caller's own upvotes without a second
// round-trip. voterKey is the hashed browser id (hashClient); pass null for an
// anonymous read (voted is then false for every row).
export async function listShowcase({ limit = 12, voterKey = null, sort = 'fresh', window = 'all' } = {}) {
if (!forgeStoreEnabled()) return [];
const capped = Math.min(Math.max(Number(limit) || 12, 1), 24);
// Empty string never matches a real voter_key (hashClient collapses missing
// ids to 'anon', a non-empty hash), so an anonymous read yields voted=false.
const vk = typeof voterKey === 'string' && voterKey ? voterKey : '';
const top = sort === 'top';
const weekStart = top && window === 'week' ? forgeOffWeekStart().toISOString() : null;
try {
const rows = top
? await sql`
select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url,
fc.views_used, fc.multiview, fc.backend, fc.tier, fc.path,
fc.model_category, fc.created_at, fc.vote_count,
fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,
(v.voter_key is not null) as voted
from forge_creations fc
left join forge_votes v on v.creation_id = fc.id and v.voter_key = ${vk}
where fc.status = 'done' and fc.glb_url is not null
and (fc.outcome is null or fc.outcome != 'rejected')
and (fc.visibility is null or fc.visibility = 'public')
and (${weekStart}::timestamptz is null or fc.created_at >= ${weekStart}::timestamptz)
order by fc.vote_count desc, fc.created_at desc
limit ${capped}
`
: await sql`
select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url,
fc.views_used, fc.multiview, fc.backend, fc.tier, fc.path,
fc.model_category, fc.created_at, fc.vote_count,
fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,
(v.voter_key is not null) as voted
from forge_creations fc
left join forge_votes v on v.creation_id = fc.id and v.voter_key = ${vk}
where fc.status = 'done' and fc.glb_url is not null
and (fc.outcome is null or fc.outcome != 'rejected')
and (fc.visibility is null or fc.visibility = 'public')
order by (fc.preview_image_url is not null) desc, fc.created_at desc
limit ${capped}
`;
return rows.map((r) => ({
id: r.id,
prompt: r.prompt,
glb_url: normalizeStoredUrl(r.glb_url),
web_glb_url: normalizeStoredUrl(r.web_glb_url) ?? null,
preview_image_url: normalizeStoredUrl(r.preview_image_url),
views_used: r.views_used ?? null,
multiview: r.multiview ?? null,
backend: r.backend ?? null,
tier: r.tier ?? null,
path: r.path ?? null,
model_category: r.model_category ?? 'other',
created_at: r.created_at,
vote_count: Number(r.vote_count) || 0,
voted: Boolean(r.voted),
...x402Provenance(r),
}));
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] listShowcase skipped (db unavailable):', err?.message);
else console.error('[forge-store] listShowcase failed:', err?.message);
return [];
}
}
// Total finished community models with a stored GLB — the same public-artifact
// bar the showcase feed uses (rejected rows excluded). Powers the live "N models
// forged" social-proof count. Cheap COUNT(*), CDN-cached by its callers.
export async function countShowcase() {
if (!forgeStoreEnabled()) return 0;
try {
const [row] = await sql`
select count(*)::int as n
from forge_creations
where status = 'done' and glb_url is not null
and (outcome is null or outcome != 'rejected')
and (visibility is null or visibility = 'public')
`;
return row?.n ?? 0;
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] countShowcase skipped (db unavailable):', err?.message);
else console.error('[forge-store] countShowcase failed:', err?.message);
return 0;
}
}
// Monday 00:00:00 UTC of the Forge-Off week containing `ref` (default: now).
// The weekly ritual runs Monday→Monday UTC; the crowning cron writes one
// forge_board_winners row per completed week keyed by this Monday. Same idiom
// used for weekly windows elsewhere (api/permissions/[action].js).
export function forgeOffWeekStart(ref = new Date()) {
const d = new Date(ref);
const day = d.getUTCDay(); // 0=Sun
const diff = day === 0 ? -6 : 1 - day; // back to this week's Monday
d.setUTCDate(d.getUTCDate() + diff);
d.setUTCHours(0, 0, 0, 0);
return d;
}
// Cast an upvote for a creation from an anonymous browser. Idempotent: a second
// vote from the same voter_key is a no-op (the PRIMARY KEY makes it a conflict),
// so the button can be optimistic without creating duplicates. vote_count is
// recomputed from the authoritative forge_votes tally via a correlated
// subquery so the denormalized column can never drift (the Sketchfab showcase
// cron reads it). Returns { creationId, voteCount, voted:true } or null when the
// creation isn't a board-eligible public artifact / the store is unconfigured.
export async function castVote({ creationId, voterKey, ipHash = null }) {
if (!forgeStoreEnabled() || !creationId || !voterKey) return null;
try {
// Only public, finished, non-rejected creations are votable — the same
// bar the board and showcase render. Blocks votes on nonexistent or
// private/failed ids before any write.
const eligible = await sql`
select id from forge_creations
where id = ${creationId} and status = 'done' and glb_url is not null
and (outcome is null or outcome != 'rejected')
limit 1
`;
if (eligible.length === 0) return null;
await sql`
insert into forge_votes (creation_id, voter_key, ip_hash)
values (${creationId}, ${voterKey}, ${ipHash})
on conflict (creation_id, voter_key) do nothing
`;
const rows = await sql`
update forge_creations
set vote_count = (select count(*) from forge_votes where creation_id = ${creationId})
where id = ${creationId}
returning vote_count
`;
return { creationId, voteCount: Number(rows[0]?.vote_count) || 0, voted: true };
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] castVote skipped (db unavailable):', err?.message);
else console.error('[forge-store] castVote failed:', err?.message);
return null;
}
}
// Remove the caller's upvote (toggle off). No-op when they hadn't voted.
// Recomputes vote_count from the tally, same as castVote, and returns the fresh
// count with voted:false. Returns null only on an unconfigured store / db fault.
export async function removeVote({ creationId, voterKey }) {
if (!forgeStoreEnabled() || !creationId || !voterKey) return null;
try {
await sql`
delete from forge_votes
where creation_id = ${creationId} and voter_key = ${voterKey}
`;
const rows = await sql`
update forge_creations
set vote_count = (select count(*) from forge_votes where creation_id = ${creationId})
where id = ${creationId}
returning vote_count
`;
// No returned row → creation was pruned; report a zeroed, un-voted state.
return { creationId, voteCount: Number(rows[0]?.vote_count) || 0, voted: false };
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] removeVote skipped (db unavailable):', err?.message);
else console.error('[forge-store] removeVote failed:', err?.message);
return null;
}
}
// Newest durable creations across ALL clients, WITH creator attribution when
// the creator was signed in — powers the platform-wide activity feed
// (api/users/me/feed.js, scope=all) and /community. Same public-artifact bar
// as listShowcase (finished rows with a stored GLB, nothing rejected by its
// own maker), but left-joins users so a signed-in creator's forge shows up
// with a real profile link while an anonymous one (the majority) still
// appears with no identity attached rather than being excluded.
export async function listRecentCreations({ limit = 24, before } = {}) {
if (!forgeStoreEnabled()) return [];
const capped = Math.min(Math.max(Number(limit) || 24, 1), 60);
try {
const rows = before
? await sql`
select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url, fc.model_category,
fc.parent_creation_id, fc.created_at,
fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,
u.username, u.display_name, u.avatar_url
from forge_creations fc
left join users u on u.id = fc.user_id and u.deleted_at is null and u.username is not null
where fc.status = 'done' and fc.glb_url is not null
and (fc.outcome is null or fc.outcome != 'rejected')
and (fc.visibility is null or fc.visibility = 'public')
and fc.created_at < ${before}
order by fc.created_at desc
limit ${capped}`
: await sql`
select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url, fc.model_category,
fc.parent_creation_id, fc.created_at,
fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,
u.username, u.display_name, u.avatar_url
from forge_creations fc
left join users u on u.id = fc.user_id and u.deleted_at is null and u.username is not null
where fc.status = 'done' and fc.glb_url is not null
and (fc.outcome is null or fc.outcome != 'rejected')
and (fc.visibility is null or fc.visibility = 'public')
order by fc.created_at desc
limit ${capped}`;
return rows.map((r) => ({
id: r.id,
type: 'model',
prompt: r.prompt,
glbUrl: normalizeStoredUrl(r.glb_url),
previewImageUrl: normalizeStoredUrl(r.preview_image_url),
category: r.model_category ?? 'other',
isRemix: Boolean(r.parent_creation_id),
createdAt: r.created_at,
username: r.username || null,
displayName: r.display_name || null,
avatarUrl: r.avatar_url || null,
...x402Provenance(r),
}));
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] listRecentCreations skipped (db unavailable):', err?.message);
else console.error('[forge-store] listRecentCreations failed:', err?.message);
return [];
}
}
// ── Remix economy ────────────────────────────────────────────────────────────
//
// A creator opts a finished creation into the remix bazaar (setRemixable) with a
// license, a royalty rate, and a Solana payout wallet. Other agents browse the
// opted-in assets (listRemixable), inspect one's provenance + terms before
// remixing (getRemixSource), and — after a paid remix settles — the royalty
// settlement is recorded back onto the source (recordRemixSettlement). All of
// this lives on the SAME forge_creations rows the generator already writes; no
// parallel asset store. USDC is the settlement asset only — no other coin.
const REMIX_LICENSES = new Set(['remix-cc', 'remix-nc', 'remix-royalty', 'all-rights']);
// Opt a creation into (or out of) the remix bazaar and set its terms. Scoped to
// the owning client_key so one browser can't publish another's model. Only a
// done row with a stored GLB can be made remixable. Royalty bps is clamped at
// the DB check constraint (0–2000); we pre-clamp for a clean error path.
export async function setRemixable({ creationId, clientKey, remixable, royaltyBps, creatorWallet, license }) {
if (!forgeStoreEnabled() || !creationId || !clientKey) return null;
const bps = Math.max(0, Math.min(2000, Math.round(Number(royaltyBps ?? 1000)) || 0));
const lic = REMIX_LICENSES.has(license) ? license : null;
try {
const rows = await sql`
update forge_creations
set remixable = ${remixable !== false},
remix_royalty_bps = ${bps},
creator_wallet_solana = ${creatorWallet ?? null},
model_category = coalesce(model_category, 'other'),
updated_at = now()
where id = ${creationId}
and client_key = ${clientKey}
and status = 'done'
and glb_url is not null
returning id, remixable, remix_royalty_bps, creator_wallet_solana
`;
if (!rows.length) return null;
const r = rows[0];
return {
id: r.id,
remixable: r.remixable,
royaltyBps: r.remix_royalty_bps,
creatorWallet: r.creator_wallet_solana,
license: lic || 'remix-royalty',
};
} catch (err) {
console.error('[forge-store] setRemixable failed:', err?.message);
return null;
}
}
// Newest remixable creations across all creators — powers the remix feed /
// creator marketplace gallery (prompt 09). Only done rows with a stored GLB
// and remixable = true are surfaced.
//
// Three sort modes, matched to what can be paginated safely:
// - 'recent' (default): cursor by created_at (`before` = last item's ISO
// timestamp) — true infinite scroll, monotonic key.
// - 'royalty': highest creator royalty rate first. Non-monotonic across
// pages, so `before` is ignored — this returns a fixed top-N list (a
// leaderboard slice, same pattern trending/leaderboard surfaces use
// everywhere on the platform — they don't infinite-scroll either).
// - 'remixed': most-derived-from first (a live count of child creations),
// same fixed top-N behavior as 'royalty'.
// `q` does a case-insensitive substring match on the prompt; `category` filters
// to one of MODEL_CATEGORIES. Both are additive, backward-compatible with the
// original (limit, before)-only call shape.
export async function listRemixable({ limit = 24, before, category, q, sort } = {}) {
if (!forgeStoreEnabled()) return [];
const capped = Math.min(Math.max(Number(limit) || 24, 1), 48);
const sortMode = sort === 'royalty' || sort === 'remixed' ? sort : 'recent';
const cat = validModelCategory(category);
const search = typeof q === 'string' && q.trim() ? q.trim().slice(0, 120) : null;
const params = [];
const conds = [`p.remixable = true`, `p.status = 'done'`, `p.glb_url is not null`];
if (cat) {
params.push(cat);
conds.push(`p.model_category = $${params.length}`);
}
if (search) {
params.push(`%${search}%`);
conds.push(`p.prompt ilike $${params.length}`);
}
// The cursor only makes sense for the monotonic 'recent' sort.
if (sortMode === 'recent' && before) {
params.push(before);
conds.push(`p.created_at < $${params.length}`);
}
params.push(capped);
const limitParam = `$${params.length}`;
const orderBy =
sortMode === 'royalty'
? `p.remix_royalty_bps desc, p.created_at desc`
: sortMode === 'remixed'
? `remix_count desc, p.created_at desc`
: `p.created_at desc`;
try {
const rows = await sql(
`select p.id, p.prompt, p.glb_url, p.preview_image_url, p.remix_royalty_bps,
p.creator_wallet_solana, p.parent_creation_id, p.lineage_index,
p.backend, p.model_category, p.created_at,
coalesce(rc.remix_count, 0) as remix_count,
u.username as owner_username, u.display_name as owner_display_name, u.avatar_url as owner_avatar_url
from forge_creations p
left join (
select parent_creation_id, count(*) as remix_count
from forge_creations
where parent_creation_id is not null and status = 'done'
group by parent_creation_id
) rc on rc.parent_creation_id = p.id
left join users u on u.id = p.user_id and u.deleted_at is null
where ${conds.join(' and ')}
order by ${orderBy}
limit ${limitParam}`,
params,
);
return rows.map((r) => ({
id: r.id,
prompt: r.prompt,
glb_url: normalizeStoredUrl(r.glb_url),
preview_image_url: normalizeStoredUrl(r.preview_image_url),
royaltyBps: r.remix_royalty_bps ?? 0,
// Provenance + terms VISIBLE before remixing — but never leak the raw
// payout wallet in the public feed; only whether royalties can route.
royaltyPayable: Boolean(r.creator_wallet_solana),
isDerived: Boolean(r.parent_creation_id),
lineageIndex: r.lineage_index ?? 0,
remixCount: Number(r.remix_count) || 0,
backend: r.backend ?? null,
model_category: r.model_category ?? 'other',
created_at: r.created_at,
// Opt-in creator attribution — only when the model was made while
// signed in (same contract as listRecentCreations / creator-portfolio).
ownerUsername: r.owner_username || null,
ownerDisplayName: r.owner_display_name || null,
ownerAvatarUrl: r.owner_avatar_url || null,
}));
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] listRemixable skipped (db unavailable):', err?.message);
else console.error('[forge-store] listRemixable failed:', err?.message);
return [];
}
}
// The most-remixed published assets, platform-wide — the "trending" half of
// the creator marketplace leaderboard (prompt 09). Counts REAL child rows
// (finished derivatives whose parent_creation_id points at this asset), not a
// synthetic popularity score. A source that is no longer published as
// remixable can still appear (its remix history is a fact even if it was later
// unpublished) — the caller renders that as "no longer remixable".
export async function listMostRemixed({ limit = 10 } = {}) {
if (!forgeStoreEnabled()) return [];
const capped = Math.min(Math.max(Number(limit) || 10, 1), 24);
try {
const rows = await sql`
with remix_counts as (
select parent_creation_id, count(*) as remix_count
from forge_creations
where parent_creation_id is not null and status = 'done'
group by parent_creation_id
)
select p.id, p.prompt, p.glb_url, p.preview_image_url, p.remix_royalty_bps,
p.creator_wallet_solana, p.remixable, p.model_category, p.created_at,
rc.remix_count
from remix_counts rc
join forge_creations p on p.id = rc.parent_creation_id
where p.status = 'done' and p.glb_url is not null
order by rc.remix_count desc, p.created_at desc
limit ${capped}
`;
return rows.map((r) => ({
id: r.id,
prompt: r.prompt,
glb_url: normalizeStoredUrl(r.glb_url),
preview_image_url: normalizeStoredUrl(r.preview_image_url),
royaltyBps: r.remix_royalty_bps ?? 0,
royaltyPayable: Boolean(r.creator_wallet_solana),
remixable: Boolean(r.remixable),
remixCount: Number(r.remix_count) || 0,
model_category: r.model_category ?? 'other',
created_at: r.created_at,
}));
} catch (err) {
if (isDbUnavailableError(err)) console.warn('[forge-store] listMostRemixed skipped (db unavailable):', err?.message);
else console.error('[forge-store] listMostRemixed failed:', err?.message);
return [];
}
}
// Fetch one remixable source with the fields settlement needs: its GLB, the
// reference image to anchor the remix, the royalty rate, and the payout wallet.
// Includes the wallet (unlike the public feed) because the caller is the
// settlement path, not a browser. Returns null when missing or not remixable.
export async function getRemixSource({ creationId }) {
if (!forgeStoreEnabled() || !creationId) return null;
try {
const rows = await sql`
select id, client_key, user_id, prompt, glb_url, preview_image_url,
remixable, remix_royalty_bps, creator_wallet_solana,
parent_creation_id, lineage_index, aspect, created_at
from forge_creations
where id = ${creationId} and status = 'done' and glb_url is not null
limit 1
`;
if (!rows.length) return null;
const r = rows[0];
return {
id: r.id,
clientKey: r.client_key,
userId: r.user_id ?? null,
prompt: r.prompt,
glbUrl: r.glb_url,
previewImageUrl: r.preview_image_url,
remixable: r.remixable === true,
royaltyBps: r.remix_royalty_bps ?? 0,
creatorWallet: r.creator_wallet_solana,
parentCreationId: r.parent_creation_id,
lineageIndex: r.lineage_index ?? 0,
aspect: r.aspect,
createdAt: r.created_at,
};
} catch (err) {
console.error('[forge-store] getRemixSource failed:', err?.message);
return null;
}
}
// Record a completed royalty settlement on the SOURCE creation (the one that was
// remixed). Stored as JSONB carrying the on-chain tx, amount, and the remix that
// triggered it — the append-only provenance of income earned. Best-effort.
export async function recordRemixSettlement({ sourceCreationId, settlement }) {
if (!forgeStoreEnabled() || !sourceCreationId || !settlement) return false;
try {
await sql`
update forge_creations
set remix_settlement_ref = ${JSON.stringify(settlement)}::jsonb,
updated_at = now()
where id = ${sourceCreationId}
`;
return true;
} catch (err) {
console.error('[forge-store] recordRemixSettlement failed:', err?.message);
return false;
}
}