@kaminos/webgpu-inference-kit 0.1.0

package/src/route-receipt.js

@@ -0,0 +1,147 @@
+export const WEBGPU_ROUTE_RECEIPT_SCHEMA = 'kaminos.webgpu-route-receipt.v0';
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isFiniteNonNegative(value) {
+  return Number.isFinite(value) && value >= 0;
+}
+
+function requireString(errors, value, path) {
+  if (!isNonEmptyString(value)) errors.push(`${path} must be a non-empty string`);
+}
+
+function requireArray(errors, value, path) {
+  if (!Array.isArray(value) || value.length === 0) {
+    errors.push(`${path} must be a non-empty array`);
+  }
+}
+
+export function createWebGpuLocalRouteReceipt(input) {
+  const status = input.status || (input.fallbackReason ? 'fallback' : 'real');
+  return {
+    schema: WEBGPU_ROUTE_RECEIPT_SCHEMA,
+    requestedRouteId: input.requestedRouteId,
+    effectiveRouteId: input.effectiveRouteId,
+    status,
+    fallbackReason: input.fallbackReason || null,
+    backend: clone(input.backend),
+    model: clone(input.model),
+    kernel: clone(input.kernel),
+    inputs: clone(input.inputs || []),
+    outputs: clone(input.outputs || []),
+    timings: clone(input.timings),
+    createdAt: input.createdAt || new Date().toISOString(),
+  };
+}
+
+export function validateRouteReceipt(receipt) {
+  const errors = [];
+
+  if (!receipt || typeof receipt !== 'object') {
+    return { ok: false, errors: ['receipt must be an object'] };
+  }
+
+  if (receipt.schema !== WEBGPU_ROUTE_RECEIPT_SCHEMA) {
+    errors.push(`schema must be ${WEBGPU_ROUTE_RECEIPT_SCHEMA}`);
+  }
+
+  requireString(errors, receipt.requestedRouteId, 'requestedRouteId');
+  requireString(errors, receipt.effectiveRouteId, 'effectiveRouteId');
+  requireString(errors, receipt.status, 'status');
+
+  if (!receipt.backend || typeof receipt.backend !== 'object') {
+    errors.push('backend must be an object');
+  } else {
+    if (receipt.backend.kind !== 'webgpu-local') {
+      errors.push('backend.kind must be webgpu-local');
+    }
+    requireString(errors, receipt.backend.runtime, 'backend.runtime');
+  }
+
+  if (!receipt.model || typeof receipt.model !== 'object') {
+    errors.push('model must be an object');
+  } else {
+    requireString(errors, receipt.model.id, 'model.id');
+    requireString(errors, receipt.model.revision, 'model.revision');
+    requireString(errors, receipt.model.weightsHash, 'model.weightsHash');
+    requireString(errors, receipt.model.dtype, 'model.dtype');
+  }
+
+  if (!receipt.kernel || typeof receipt.kernel !== 'object') {
+    errors.push('kernel must be an object');
+  } else {
+    requireString(errors, receipt.kernel.kitVersion, 'kernel.kitVersion');
+    requireString(errors, receipt.kernel.profile, 'kernel.profile');
+  }
+
+  requireArray(errors, receipt.inputs, 'inputs');
+  if (Array.isArray(receipt.inputs)) {
+    receipt.inputs.forEach((input, index) => {
+      requireString(errors, input?.role, `inputs[${index}].role`);
+      requireString(errors, input?.artifactId, `inputs[${index}].artifactId`);
+      requireString(errors, input?.sha256, `inputs[${index}].sha256`);
+    });
+  }
+
+  requireArray(errors, receipt.outputs, 'outputs');
+  if (Array.isArray(receipt.outputs)) {
+    receipt.outputs.forEach((output, index) => {
+      requireString(errors, output?.role, `outputs[${index}].role`);
+      requireString(errors, output?.artifactId, `outputs[${index}].artifactId`);
+      requireString(errors, output?.sha256, `outputs[${index}].sha256`);
+      requireString(errors, output?.status, `outputs[${index}].status`);
+      if (!Array.isArray(output?.shape) || output.shape.length === 0 || !output.shape.every(Number.isInteger)) {
+        errors.push(`outputs[${index}].shape must be a non-empty integer array`);
+      }
+    });
+  }
+
+  if (!receipt.timings || typeof receipt.timings !== 'object') {
+    errors.push('timings must be an object');
+  } else {
+    requireString(errors, receipt.timings.source, 'timings.source');
+    if (!isFiniteNonNegative(receipt.timings.totalMs)) {
+      errors.push('timings.totalMs must be a finite non-negative number');
+    }
+    if (receipt.timings.stages != null && !Array.isArray(receipt.timings.stages)) {
+      errors.push('timings.stages must be an array when present');
+    }
+  }
+
+  if (receipt.status === 'fallback' && !isNonEmptyString(receipt.fallbackReason)) {
+    errors.push('fallback receipts must include fallbackReason');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function assertAuthoritativeRouteReceipt(receipt) {
+  const result = validateRouteReceipt(receipt);
+  if (!result.ok) {
+    throw new Error(`invalid route receipt: ${result.errors.join('; ')}`);
+  }
+
+  if (receipt.status !== 'real') {
+    throw new Error(`not authoritative: receipt status is ${receipt.status}`);
+  }
+  if (receipt.fallbackReason) {
+    throw new Error(`not authoritative: fallback reason present (${receipt.fallbackReason})`);
+  }
+
+  for (const output of receipt.outputs) {
+    if (output.status === 'partial') {
+      throw new Error(`partial output is not authoritative: ${output.role}`);
+    }
+    if (output.status !== 'real') {
+      throw new Error(`output is not authoritative: ${output.role} status=${output.status}`);
+    }
+  }
+
+  return receipt;
+}

package/src/route-schema-contract.js

@@ -0,0 +1,29 @@
+import { WEBGPU_ROUTE_RECEIPT_SCHEMA } from './route-receipt.js';
+import { WEBGPU_ROUTE_EVIDENCE_CLASSIFICATION_SCHEMA } from './route-receipt-consumer.js';
+import { WEBGPU_RUNTIME_PROFILE_SCHEMA } from './runtime-profile.js';
+import {
+  WEBGPU_ROUTE_BACKPRESSURE_SCHEMA,
+  WEBGPU_ROUTE_SCHEDULER_SCHEMA,
+} from './scheduler-backpressure.js';
+import {
+  WEBGPU_ROUTE_DEFINITION_SCHEMA,
+  WEBGPU_ROUTE_REQUEST_SCHEMA,
+  WEBGPU_ROUTE_RESULT_SCHEMA,
+} from './route-boundary.js';
+
+export function createWebGpuRouteSchemaContract(input = {}) {
+  return {
+    schema: 'kaminos.webgpu-route-schema-contract.v0',
+    kitVersion: input.kitVersion || '0.0.0',
+    definitionSchema: WEBGPU_ROUTE_DEFINITION_SCHEMA,
+    requestSchema: WEBGPU_ROUTE_REQUEST_SCHEMA,
+    resultSchema: WEBGPU_ROUTE_RESULT_SCHEMA,
+    receiptSchema: WEBGPU_ROUTE_RECEIPT_SCHEMA,
+    runtimeProfileSchema: WEBGPU_RUNTIME_PROFILE_SCHEMA,
+    evidenceClassificationSchema: WEBGPU_ROUTE_EVIDENCE_CLASSIFICATION_SCHEMA,
+    schedulerSchema: WEBGPU_ROUTE_SCHEDULER_SCHEMA,
+    backpressureSchema: WEBGPU_ROUTE_BACKPRESSURE_SCHEMA,
+    authoritativeReceiptStatuses: ['real'],
+    nonAuthoritativeReceiptStatuses: ['fallback', 'partial', 'cached'],
+  };
+}

package/src/runtime-profile.js

@@ -0,0 +1,139 @@
+import {
+  createWebGpuBackendIdentity,
+  validateWebGpuBackendIdentity,
+} from './gpu-environment.js';
+import {
+  createKernelProfileMetadata,
+  createRouteTimingMetadata,
+  validateKernelProfileMetadata,
+  validateRouteTimingMetadata,
+} from './kernel-profile.js';
+import {
+  finishAndValidateRouteProfile,
+} from './route-receipt-helper.js';
+import {
+  validateStagedSubmitProfile,
+} from './staged-profile.js';
+
+export const WEBGPU_RUNTIME_PROFILE_SCHEMA = 'kaminos.webgpu-runtime-profile.v0';
+
+const EVIDENCE_MODES = new Set(['live', 'fallback', 'cache', 'demo', 'partial', 'unknown']);
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function createBackendIdentity(input) {
+  if (input?.kind === 'webgpu-local') return clone(input);
+  return createWebGpuBackendIdentity(input || {});
+}
+
+function createEvidence(input = {}) {
+  const mode = input.mode || 'live';
+  return {
+    mode,
+    source: input.source || 'browser-webgpu-route',
+    fallbackReason: input.fallbackReason || null,
+  };
+}
+
+function validateEvidence(errors, evidence) {
+  if (!evidence || typeof evidence !== 'object') {
+    errors.push('evidence must be an object');
+    return;
+  }
+  if (!EVIDENCE_MODES.has(evidence.mode)) errors.push('evidence.mode has unsupported state');
+  if (!isNonEmptyString(evidence.source)) errors.push('evidence.source must be a non-empty string');
+  if (evidence.mode === 'fallback' && !isNonEmptyString(evidence.fallbackReason)) {
+    errors.push('fallback evidence must include fallbackReason');
+  }
+}
+
+export function createWebGpuRuntimeProfileInput(input = {}) {
+  if (!input || typeof input !== 'object') throw new Error('runtime profile input must be an object');
+  if (!isNonEmptyString(input.routeId)) throw new Error('routeId must be a non-empty string');
+
+  const backend = createBackendIdentity(input.backend);
+  const backendResult = validateWebGpuBackendIdentity(backend);
+  if (!backendResult.ok) throw new Error(`invalid WebGPU backend identity: ${backendResult.errors.join('; ')}`);
+
+  const kernel = createKernelProfileMetadata(input.kernel, { requireProfile: true });
+  const profile = finishAndValidateRouteProfile(input.profile);
+  const evidence = createEvidence(input.evidence);
+
+  const errors = [];
+  validateEvidence(errors, evidence);
+  if (errors.length > 0) throw new Error(errors.join('; '));
+
+  return {
+    routeId: input.routeId,
+    runtimeLabel: input.runtimeLabel || 'browser-webgpu',
+    backend,
+    kernel,
+    profile,
+    evidence,
+  };
+}
+
+export function createWebGpuRuntimeProfile(input = {}) {
+  const runtimeInput = createWebGpuRuntimeProfileInput(input);
+  const timing = createRouteTimingMetadata({
+    requiredStages: Array.isArray(input.requiredStages) ? input.requiredStages : runtimeInput.profile.requiredStages,
+    timingSource: input.timingSource || runtimeInput.profile.timingSource,
+  }, { validate: true });
+
+  return {
+    schema: WEBGPU_RUNTIME_PROFILE_SCHEMA,
+    routeId: runtimeInput.routeId,
+    runtimeLabel: runtimeInput.runtimeLabel,
+    backend: runtimeInput.backend,
+    kernel: runtimeInput.kernel,
+    profile: runtimeInput.profile,
+    evidence: runtimeInput.evidence,
+    requiredStages: timing.requiredStages,
+    timingSource: timing.timingSource,
+    createdAt: input.createdAt || new Date().toISOString(),
+  };
+}
+
+export function validateWebGpuRuntimeProfile(runtimeProfile) {
+  const errors = [];
+
+  if (!runtimeProfile || typeof runtimeProfile !== 'object') {
+    return { ok: false, errors: ['runtimeProfile must be an object'] };
+  }
+
+  if (runtimeProfile.schema !== WEBGPU_RUNTIME_PROFILE_SCHEMA) {
+    errors.push(`schema must be ${WEBGPU_RUNTIME_PROFILE_SCHEMA}`);
+  }
+  if (!isNonEmptyString(runtimeProfile.routeId)) errors.push('routeId must be a non-empty string');
+  if (!isNonEmptyString(runtimeProfile.runtimeLabel)) errors.push('runtimeLabel must be a non-empty string');
+
+  const backendResult = validateWebGpuBackendIdentity(runtimeProfile.backend);
+  if (!backendResult.ok) errors.push(...backendResult.errors.map(error => `backend.${error}`));
+
+  const kernelResult = validateKernelProfileMetadata(runtimeProfile.kernel);
+  if (!kernelResult.ok) errors.push(...kernelResult.errors.map(error => `kernel.${error}`));
+
+  const profileResult = validateStagedSubmitProfile(runtimeProfile.profile);
+  if (!profileResult.ok) errors.push(...profileResult.errors.map(error => `profile.${error}`));
+
+  const timingResult = validateRouteTimingMetadata(runtimeProfile);
+  if (!timingResult.ok) errors.push(...timingResult.errors);
+
+  validateEvidence(errors, runtimeProfile.evidence);
+
+  if (
+    isNonEmptyString(runtimeProfile.timingSource)
+    && isNonEmptyString(runtimeProfile.profile?.timingSource)
+    && runtimeProfile.timingSource !== runtimeProfile.profile.timingSource
+  ) {
+    errors.push('timingSource must match profile.timingSource');
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/scheduler-backpressure.js

@@ -0,0 +1,221 @@
+export const WEBGPU_ROUTE_SCHEDULER_SCHEMA = 'kaminos.webgpu-route-scheduler.v0';
+export const WEBGPU_ROUTE_BACKPRESSURE_SCHEMA = 'kaminos.webgpu-route-backpressure.v0';
+
+const SCHEDULER_MODES = new Set(['throughput', 'cooperative']);
+const VERIFICATION_STATES = new Set(['verified', 'scheduler-unverified', 'unsupported']);
+const BUDGETS = new Set(['interactive', 'visible-wait', 'furnace', 'batch', 'unknown']);
+const MEMORY_EXCLUSIVITY = new Set(['shared', 'exclusive', 'unknown']);
+const WARM_CACHE_STATES = new Set(['cold', 'warm', 'hot', 'unknown']);
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isNonNegativeNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function normalizePhaseChunkSize(input = {}) {
+  const out = {};
+  if (!isPlainObject(input)) return out;
+  for (const [phase, chunkSize] of Object.entries(input)) {
+    out[phase] = chunkSize;
+  }
+  return out;
+}
+
+function normalizeScheduler(input = {}) {
+  return {
+    mode: input.mode || 'throughput',
+    yieldMs: input.yieldMs ?? 0,
+    waitForSubmittedWorkDone: Boolean(input.waitForSubmittedWorkDone),
+    phaseChunkSize: normalizePhaseChunkSize(input.phaseChunkSize),
+  };
+}
+
+function normalizeEffectiveScheduler(input = {}, requestedScheduler) {
+  const base = normalizeScheduler({
+    ...requestedScheduler,
+    ...input,
+    phaseChunkSize: input.phaseChunkSize ?? requestedScheduler.phaseChunkSize,
+  });
+  return {
+    ...base,
+    unsupportedFields: Array.isArray(input.unsupportedFields) ? [...input.unsupportedFields] : [],
+  };
+}
+
+function validateSchedulerShape(errors, scheduler, label) {
+  if (!isPlainObject(scheduler)) {
+    errors.push(`${label} must be an object`);
+    return;
+  }
+  if (!SCHEDULER_MODES.has(scheduler.mode)) {
+    errors.push(`${label}.mode must be throughput or cooperative`);
+  }
+  if (!isNonNegativeNumber(scheduler.yieldMs)) {
+    errors.push(`${label}.yieldMs must be a non-negative number`);
+  }
+  if (typeof scheduler.waitForSubmittedWorkDone !== 'boolean') {
+    errors.push(`${label}.waitForSubmittedWorkDone must be a boolean`);
+  }
+  if (!isPlainObject(scheduler.phaseChunkSize)) {
+    errors.push(`${label}.phaseChunkSize must be an object`);
+    return;
+  }
+  for (const [phase, chunkSize] of Object.entries(scheduler.phaseChunkSize)) {
+    if (!isNonEmptyString(phase)) errors.push(`${label}.phaseChunkSize contains an empty phase name`);
+    if (!Number.isInteger(chunkSize) || chunkSize < 1) {
+      errors.push(`${label}.phaseChunkSize.${phase} must be a positive integer`);
+    }
+  }
+}
+
+function missingUnsupportedField(effectiveScheduler, field) {
+  return !effectiveScheduler.unsupportedFields.includes(field)
+    && !effectiveScheduler.unsupportedFields.includes('phaseChunkSize');
+}
+
+export function createWebGpuRouteSchedulerProfile(input = {}) {
+  const requestedScheduler = normalizeScheduler(input.requestedScheduler || input);
+  const effectiveScheduler = normalizeEffectiveScheduler(
+    input.effectiveScheduler || {},
+    requestedScheduler,
+  );
+  const verificationState = input.verificationState
+    || (requestedScheduler.mode === 'cooperative' ? 'scheduler-unverified' : 'unsupported');
+
+  const profile = {
+    schema: WEBGPU_ROUTE_SCHEDULER_SCHEMA,
+    requestedScheduler,
+    effectiveScheduler,
+    verificationState,
+  };
+
+  const result = validateWebGpuRouteSchedulerProfile(profile);
+  if (!result.ok) throw new Error(result.errors.join('; '));
+  return profile;
+}
+
+export function validateWebGpuRouteSchedulerProfile(profile) {
+  const errors = [];
+  if (!isPlainObject(profile)) {
+    return { ok: false, errors: ['scheduler profile must be an object'] };
+  }
+  if (profile.schema !== WEBGPU_ROUTE_SCHEDULER_SCHEMA) {
+    errors.push(`schema must be ${WEBGPU_ROUTE_SCHEDULER_SCHEMA}`);
+  }
+  validateSchedulerShape(errors, profile.requestedScheduler, 'requestedScheduler');
+  validateSchedulerShape(errors, profile.effectiveScheduler, 'effectiveScheduler');
+
+  if (!Array.isArray(profile.effectiveScheduler?.unsupportedFields)) {
+    errors.push('effectiveScheduler.unsupportedFields must be an array');
+  } else {
+    for (const field of profile.effectiveScheduler.unsupportedFields) {
+      if (!isNonEmptyString(field)) errors.push('effectiveScheduler.unsupportedFields entries must be non-empty strings');
+    }
+  }
+
+  if (!VERIFICATION_STATES.has(profile.verificationState)) {
+    errors.push('verificationState must be verified, scheduler-unverified, or unsupported');
+  }
+
+  if (isPlainObject(profile.requestedScheduler) && isPlainObject(profile.effectiveScheduler)) {
+    for (const [phase, requestedChunk] of Object.entries(profile.requestedScheduler.phaseChunkSize || {})) {
+      const effectiveChunk = profile.effectiveScheduler.phaseChunkSize?.[phase];
+      const field = `phaseChunkSize.${phase}`;
+      if (effectiveChunk !== requestedChunk && missingUnsupportedField(profile.effectiveScheduler, field)) {
+        if (profile.verificationState === 'verified') {
+          errors.push(`verified scheduler cannot drop requested ${field}`);
+        } else {
+          errors.push(`effectiveScheduler must list unsupported ${field}`);
+        }
+      }
+    }
+  }
+
+  if (profile.verificationState === 'verified') {
+    if (profile.effectiveScheduler?.unsupportedFields?.length > 0) {
+      errors.push('verified scheduler cannot include unsupportedFields');
+    }
+    if (profile.requestedScheduler?.mode === 'cooperative' && profile.effectiveScheduler?.mode !== 'cooperative') {
+      errors.push('verified cooperative scheduler must have effectiveScheduler.mode cooperative');
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function normalizeFrameTail(input = {}) {
+  return {
+    sampleWindowMs: input.sampleWindowMs ?? 0,
+    longFrameCount: input.longFrameCount ?? 0,
+    maxFrameGapMs: input.maxFrameGapMs ?? 0,
+    p95FrameGapMs: input.p95FrameGapMs ?? null,
+    p99FrameGapMs: input.p99FrameGapMs ?? null,
+  };
+}
+
+export function createWebGpuRouteBackpressureProfile(input = {}) {
+  const profile = {
+    schema: WEBGPU_ROUTE_BACKPRESSURE_SCHEMA,
+    requestedBudget: input.requestedBudget || 'unknown',
+    effectiveBudget: input.effectiveBudget || input.requestedBudget || 'unknown',
+    memoryExclusivity: input.memoryExclusivity || 'unknown',
+    warmCacheState: input.warmCacheState || 'unknown',
+    frameTail: normalizeFrameTail(input.frameTail),
+  };
+  const result = validateWebGpuRouteBackpressureProfile(profile);
+  if (!result.ok) throw new Error(result.errors.join('; '));
+  return profile;
+}
+
+function validateOptionalFrameMs(errors, frameTail, field) {
+  if (frameTail[field] != null && !isNonNegativeNumber(frameTail[field])) {
+    errors.push(`frameTail.${field} must be null or a non-negative number`);
+  }
+}
+
+export function validateWebGpuRouteBackpressureProfile(profile) {
+  const errors = [];
+  if (!isPlainObject(profile)) {
+    return { ok: false, errors: ['backpressure profile must be an object'] };
+  }
+  if (profile.schema !== WEBGPU_ROUTE_BACKPRESSURE_SCHEMA) {
+    errors.push(`schema must be ${WEBGPU_ROUTE_BACKPRESSURE_SCHEMA}`);
+  }
+  if (!BUDGETS.has(profile.requestedBudget)) errors.push('requestedBudget has unsupported value');
+  if (!BUDGETS.has(profile.effectiveBudget)) errors.push('effectiveBudget has unsupported value');
+  if (!MEMORY_EXCLUSIVITY.has(profile.memoryExclusivity)) errors.push('memoryExclusivity has unsupported value');
+  if (!WARM_CACHE_STATES.has(profile.warmCacheState)) errors.push('warmCacheState has unsupported value');
+
+  if (!isPlainObject(profile.frameTail)) {
+    errors.push('frameTail must be an object');
+  } else {
+    if (!isNonNegativeNumber(profile.frameTail.sampleWindowMs)) {
+      errors.push('frameTail.sampleWindowMs must be a non-negative number');
+    }
+    if (!Number.isInteger(profile.frameTail.longFrameCount) || profile.frameTail.longFrameCount < 0) {
+      errors.push('frameTail.longFrameCount must be a non-negative integer');
+    }
+    if (!isNonNegativeNumber(profile.frameTail.maxFrameGapMs)) {
+      errors.push('frameTail.maxFrameGapMs must be a non-negative number');
+    }
+    validateOptionalFrameMs(errors, profile.frameTail, 'p95FrameGapMs');
+    validateOptionalFrameMs(errors, profile.frameTail, 'p99FrameGapMs');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function cloneWebGpuRouteSchedulerProfile(profile) {
+  return clone(profile);
+}

package/src/sf3d-route.js

@@ -0,0 +1,96 @@
+import { defineWebGpuRoute } from './route-boundary.js';
+import {
+  createKernelProfileMetadata,
+  createRouteKernelProfileMetadata,
+} from './kernel-profile.js';
+import {
+  createRouteReceiptArtifacts,
+  createRouteReceiptInputArtifact,
+  createWebGpuRouteReceiptFromArtifacts,
+} from './route-receipt-helper.js';
+
+export const SF3D_IMAGE_TO_MESH_ROUTE_ID = 'sf3d.image-to-mesh.webgpu-local.v0';
+const SF3D_MODEL_ID = 'stabilityai/stable-fast-3d';
+const DEFAULT_KERNEL_PROFILE = 'dinov2-two-stream-triplane-marching-tet-texture-bake';
+const REQUIRED_STAGES = [
+  'image-preprocess',
+  'dinov2-tokenizer',
+  'two-stream-backbone',
+  'triplane-decode',
+  'marching-tet',
+  'texture-bake',
+  'glb-export',
+];
+const OUTPUT_ROLES = [
+  { key: 'meshGlb', role: 'mesh-glb', required: true },
+  { key: 'albedoTexture', role: 'albedo-texture', required: true },
+  { key: 'normalMap', role: 'normal-map', required: true },
+  { key: 'meshObj', role: 'mesh-obj', required: false },
+];
+
+export function createSf3dImageToMeshRouteReceipt(input) {
+  if (!input || typeof input !== 'object') throw new Error('input must be an object');
+  if (!input.input?.artifactId || !input.input?.sha256) {
+    throw new Error('input image artifactId and sha256 are required');
+  }
+  if (!input.outputs?.meshGlb) throw new Error('meshGlb output is required');
+  if (!input.outputs?.albedoTexture) throw new Error('albedoTexture output is required');
+  if (!input.outputs?.normalMap) throw new Error('normalMap output is required');
+
+  return createWebGpuRouteReceiptFromArtifacts({
+    requestedRouteId: SF3D_IMAGE_TO_MESH_ROUTE_ID,
+    effectiveRouteId: input.effectiveRouteId || SF3D_IMAGE_TO_MESH_ROUTE_ID,
+    status: input.status || (input.fallbackReason ? 'fallback' : 'real'),
+    fallbackReason: input.fallbackReason || null,
+    backend: input.backend,
+    model: {
+      id: SF3D_MODEL_ID,
+      revision: input.model?.revision,
+      weightsHash: input.model?.weightsHash,
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: createKernelProfileMetadata(input.kernel, { requireProfile: true }),
+    inputs: [
+      createRouteReceiptInputArtifact('source-image', input.input),
+    ],
+    outputs: createRouteReceiptArtifacts({ artifacts: input.outputs, roles: OUTPUT_ROLES }),
+    profile: input.profile,
+  });
+}
+
+export function createSf3dImageToMeshRouteDefinition(input = {}) {
+  const routeMetadata = createRouteKernelProfileMetadata(input, {
+    defaultProfile: DEFAULT_KERNEL_PROFILE,
+    requiredStages: REQUIRED_STAGES,
+    timingSource: 'adapter-phase-wall-clock',
+  });
+
+  return defineWebGpuRoute({
+    routeId: SF3D_IMAGE_TO_MESH_ROUTE_ID,
+    backendKind: 'webgpu-local',
+    model: {
+      id: SF3D_MODEL_ID,
+      revision: input.model?.revision || 'stable-fast-3d',
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: routeMetadata.kernel,
+    inputs: [
+      { role: 'source-image', required: true, artifactRequired: true, hashRequired: true },
+    ],
+    outputs: [
+      { role: 'mesh-glb', required: true, artifactRequired: true, hashRequired: true, shape: [1] },
+      { role: 'albedo-texture', required: true, artifactRequired: true, hashRequired: true },
+      { role: 'normal-map', required: true, artifactRequired: true, hashRequired: true },
+      { role: 'mesh-obj', required: false, artifactRequired: true, hashRequired: true, shape: [1] },
+    ],
+    requiredFeatures: input.requiredFeatures || [],
+    requiredStages: routeMetadata.requiredStages,
+    timingSource: routeMetadata.timingSource,
+    worker: input.worker || {
+      exportName: 'runSf3dImageToMeshRoute',
+      meshFormat: 'glb',
+      textureBake: true,
+      normalMap: true,
+    },
+  });
+}