@kaminos/webgpu-inference-kit 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @kaminos/webgpu-inference-kit
+
+Native WebGPU inference route substrate for Kaminos.
+
+Install:
+
+```sh
+npm install @kaminos/webgpu-inference-kit
+```
+
+Import:
+
+```js
+import {
+  createWebGpuRouteSchemaContract,
+  createWebGpuLocalRouteReceipt,
+  classifyWebGpuRouteReceiptEvidence,
+} from "@kaminos/webgpu-inference-kit";
+```
+
+This package starts with contracts, not kernels. Its first job is to make
+browser-local model routes prove what they actually ran before Kaminos treats
+their outputs as asset evidence.
+
+Current surface:
+
+- `createWebGpuLocalRouteReceipt(input)`: creates a
+  `kaminos.webgpu-route-receipt.v0` receipt for a `webgpu-local` route.
+- `createWebGpuRouteSchemaContract(input)`: exposes the kit-owned route
+  definition/request/result/receipt/runtime-profile/evidence-classification
+  schema strings as a compact contract object so route repos can run conformance
+  checks instead of manually mirroring hidden constants.
+- `createWebGpuRouteReceiptFromArtifacts(input)` plus
+  `createRouteReceiptArtifacts`, `createRouteReceiptInputArtifact`,
+  `finishAndValidateRouteProfile`, and validation helpers: shared route receipt
+  substrate used by MoGE, SHARP, Kimodo, and SF3D factories to preserve artifact
+  identity, backend identity, and staged profile requirements without duplicating
+  false-closure-prone boilerplate.
+- `validateRouteReceipt(receipt)`: validates requested/effective route identity,
+  backend/model/kernel identity, input/output artifact ids, timings, and
+  fallback status.
+- `assertAuthoritativeRouteReceipt(receipt)`: rejects fallback, cached,
+  partial, missing, or non-real outputs before they can masquerade as
+  authoritative Kaminos evidence.
+- `defineTensorManifest(input)` and `validateTensorManifest(manifest)`: normalize
+  and validate model tensor metadata, including dtype sizes and byte lengths.
+- `createWebGpuDeviceRequest(adapter, options)`: derives requested WebGPU
+  features and max adapter limits for model inference without silently capping
+  below the adapter's own reported capacity.
+- `requestBrowserWebGpuDevice(gpu, options)`: requests a browser WebGPU adapter
+  and device, then returns the effective device request and backend identity
+  that route receipts should preserve.
+- `createWebGpuBackendIdentity(input)` and
+  `validateWebGpuBackendIdentity(identity)`: preserve effective browser,
+  adapter, feature, limit, and timestamp-query identity for route receipts.
+- `createStagedSubmitProfile(input)`, `addStagedSubmitStage(profile, stage)`,
+  `finishStagedSubmitProfile(profile)`, and
+  `validateStagedSubmitProfile(profile)`: record staged-submit timing evidence
+  and reject timestamp-query timing unless it is validated against staged waits.
+- `createKernelProfileMetadata(input)` and
+  `createRouteKernelProfileMetadata(input)`: normalize shared kit version,
+  kernel profile, commit, required stage, and timing-source metadata for route
+  definitions and receipts while keeping route-specific semantics local.
+- `createWebGpuRuntimeProfileInput(input)`,
+  `createWebGpuRuntimeProfile(input)`, and
+  `validateWebGpuRuntimeProfile(profile)`: combine effective WebGPU backend
+  identity, kernel metadata, staged profile evidence, and evidence mode into a
+  single producer-side runtime profile object.
+- `createWebGpuRouteSchedulerProfile(input)` and
+  `validateWebGpuRouteSchedulerProfile(profile)`: preserve requested versus
+  effective WebGPU route scheduling, including throughput/cooperative mode,
+  route-specific phase chunk sizes, submitted-work waits, yield cadence, and
+  unsupported scheduler fields so a route cannot claim cooperative behavior
+  without effective telemetry.
+- `createWebGpuRouteBackpressureProfile(input)` and
+  `validateWebGpuRouteBackpressureProfile(profile)`: record route pressure
+  classification, warm/cache and memory-sharing posture, and frame-tail
+  evidence for visible-wait/furnace classification without turning internal
+  scheduler knobs into operator-facing controls.
+- `classifyWebGpuRouteReceiptEvidence(receipt)` and
+  `classifyWebGpuRouteWorkerResultEvidence(result)`: commoner-side receipt
+  classification helpers that distinguish authoritative live WebGPU evidence
+  from fallback, partial, cache/demo, stale, route-mismatch, and invalid
+  receipts, while surfacing scheduler verification and frame-tail fields when a
+  route provides them.
+- `createMogeDepthNormalRouteReceipt(input)`: first concrete `webgpu-local`
+  route receipt factory for `moge.depth-normal.webgpu-local.v0`.
+- `defineWebGpuRoute(input)`, `createWebGpuRouteRegistry(routes)`,
+  `createRouteInvocationRequest(route, input)`, `createRouteWorkerResult(route,
+  input)`, and their validators: define worker-executable routes, create
+  invocation envelopes, and validate route results before Wake/Pipeline consume
+  them as Kaminos evidence.
+- `createMogeDepthNormalRouteDefinition(input)`: first concrete route
+  definition for MoGE source-image to depth/normal/pointmap truth-layer output.
+- `createSharpImageToSplatRouteReceipt(input)`: concrete receipt factory for
+  `sharp.image-to-splat.webgpu-local.v0`, preserving source image, browser
+  WebGPU backend identity, PLY splat candidate, depth map, SHARP metadata, and
+  optional splat autocrop evidence.
+- `createSharpImageToSplatRouteDefinition(input)`: route definition aligned to
+  the native SHARP-WebGPU browser adapter surface used by Kaminos Pipeline:
+  source image in, splat candidate/depth/metadata out, with optional
+  `kaminos.splat-autocrop-evidence.v0` side evidence.
+- `createKimodoTextToMotionRouteReceipt(input)` and
+  `createKimodoTextToMotionRouteDefinition(input)`: browser WebGPU
+  text-to-motion route contract for Kimodo SOMA-RP-v1.1, preserving prompt
+  identity, SOMA77 joint output, motion sidecar output, optional filmstrip, and
+  staged text-embedding/DDIM/FK/output-capture timing.
+- `createSf3dImageToMeshRouteReceipt(input)` and
+  `createSf3dImageToMeshRouteDefinition(input)`: browser WebGPU image-to-mesh
+  route contract for Stable Fast 3D, preserving source image, GLB mesh, albedo
+  texture, normal map, optional OBJ, and DINOv2/two-stream/triplane/marching-tet
+  stage identity.
+
+Near-term extraction order:
+
+1. Route receipt and tensor manifest contracts. Done in the scaffold slice.
+2. WebGPU device/feature/profiling identity helpers. First pure contract helpers
+   are in place; browser adapters should wire into these next.
+3. MoGE depth/normal route receipt. First factory is in place and the MoGE
+   runtime emits this receipt from live inference.
+4. Browser route boundary. Route registry, invocation request, worker result,
+   browser device request, and MoGE route definition contracts are in place.
+5. SHARP image-to-splat route contract. First factory and route definition are
+   in place for the browser-native SHARP-WebGPU path; runtime emission remains
+   owned by SHARP/Pipeline adapter surfaces.
+6. Kimodo and SF3D route contracts. First factories and route definitions are
+   in place for browser-native text-to-motion and image-to-mesh routes; runtime
+   emission remains owned by those route repos and Kaminos motion/pipeline
+   consumers.
+7. MoGE schema mirror drift reduction. The kit exposes a schema contract object;
+   MoGE has a dev conformance test against that contract while the runtime still
+   avoids a brittle temporary worktree dependency.
+8. Shared route receipt helper. Artifact normalization, backend identity
+   validation, staged profile validation, and receipt construction now live in
+   one helper consumed by all four concrete route factories.
+9. Shared kernel/profile metadata helper. Kit version, kernel profile, commit,
+   required stage, and timing-source normalization now live in one helper
+   consumed by all four concrete route factories.
+10. Runtime profile and commoner receipt classification helpers. Producers can
+   normalize effective WebGPU runtime evidence, and downstream commoners can
+   classify receipts before treating outputs as live route evidence.
+11. Scheduler/backpressure contracts. Routes can now report throughput versus
+   cooperative scheduling, requested/effective phase chunking, unsupported
+   fields, visible-wait/furnace pressure, and frame-tail evidence without
+   implying browser GPU preemption that WebGPU does not provide.
+12. Pipeline, bind-group, uniform, and buffer caches from MoGE/SHARP.
+13. Shared kernels only when at least two real routes need them or a measured
+   kernel slice proves the extraction useful.
+
+Non-goals:
+
+- Generic ONNX import parity.
+- General LLM runtime competition.
+- Kaminos graph, scene, library, or promotion ownership.
+- Any route that hides fallback, stale output, fixture data, partial output, or
+  effective backend identity.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kaminos/webgpu-inference-kit",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Native WebGPU inference route substrate for Kaminos.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lyonsno/kaminos.git",
+    "directory": "webgpu-inference-kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node tests/receipt-contracts.mjs && node tests/tensor-manifest-contracts.mjs && node tests/gpu-environment-contracts.mjs && node tests/browser-device-context-contracts.mjs && node tests/staged-profile-contracts.mjs && node tests/kernel-profile-contracts.mjs && node tests/runtime-profile-contracts.mjs && node tests/scheduler-backpressure-contracts.mjs && node tests/route-schema-contracts.mjs && node tests/route-receipt-helper-contracts.mjs && node tests/route-receipt-consumer-contracts.mjs && node tests/moge-route-contracts.mjs && node tests/sharp-route-contracts.mjs && node tests/kimodo-route-contracts.mjs && node tests/sf3d-route-contracts.mjs && node tests/route-boundary-contracts.mjs"
+  }
+}

package/src/gpu-environment.js

@@ -0,0 +1,139 @@
+const LIMIT_KEYS = [
+  'maxBufferSize',
+  'maxStorageBufferBindingSize',
+  'maxComputeWorkgroupStorageSize',
+  'maxComputeInvocationsPerWorkgroup',
+  'maxComputeWorkgroupSizeX',
+  'maxComputeWorkgroupSizeY',
+];
+
+function featureList(features) {
+  if (!features) return [];
+  return Array.from(features).map(String).sort();
+}
+
+function hasFeature(features, name) {
+  return featureList(features).includes(name);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function copyLimits(limits = {}) {
+  const out = {};
+  for (const key of LIMIT_KEYS) {
+    if (Number.isFinite(limits[key])) out[key] = limits[key];
+  }
+  return out;
+}
+
+export function createWebGpuDeviceRequest(adapter, options = {}) {
+  if (!adapter || typeof adapter !== 'object') {
+    throw new Error('adapter must be an object');
+  }
+
+  const timestampPreference = options.timestampQuery || 'prefer';
+  const requiredFeatures = [];
+  let timestampQuery = 'disabled';
+
+  if (timestampPreference !== 'disable') {
+    if (hasFeature(adapter.features, 'timestamp-query')) {
+      requiredFeatures.push('timestamp-query');
+      timestampQuery = 'requested';
+    } else if (timestampPreference === 'require') {
+      throw new Error('timestamp-query required but not supported by adapter');
+    } else {
+      timestampQuery = 'unavailable';
+    }
+  }
+
+  return {
+    requiredFeatures,
+    requiredLimits: copyLimits(adapter.limits),
+    timestampQuery,
+  };
+}
+
+export function requestBrowserWebGpuDevice(gpu, options = {}) {
+  if (!gpu || typeof gpu.requestAdapter !== 'function') {
+    throw new Error('gpu.requestAdapter must be available');
+  }
+
+  return (async () => {
+    const adapter = await gpu.requestAdapter(options.adapterOptions || {});
+    if (!adapter) throw new Error('WebGPU adapter unavailable');
+
+    const deviceRequest = createWebGpuDeviceRequest(adapter, options);
+    const descriptor = {
+      requiredFeatures: deviceRequest.requiredFeatures,
+      requiredLimits: deviceRequest.requiredLimits,
+    };
+    if (isNonEmptyString(options.label)) descriptor.label = options.label;
+
+    const device = await adapter.requestDevice(descriptor);
+    const backendIdentity = createWebGpuBackendIdentity({
+      adapterName: options.adapterName || adapter.info?.description || adapter.info?.device || adapter.info?.vendor || 'unknown-webgpu-adapter',
+      browser: options.browser || globalThis.navigator?.userAgent || null,
+      requestedFeatures: deviceRequest.requiredFeatures,
+      effectiveFeatures: device?.features || deviceRequest.requiredFeatures,
+      limits: device?.limits || adapter.limits,
+      timestampQuery: deviceRequest.timestampQuery,
+    });
+
+    return {
+      adapter,
+      device,
+      deviceRequest,
+      backendIdentity,
+    };
+  })();
+}
+
+export function createWebGpuBackendIdentity(input) {
+  return {
+    kind: 'webgpu-local',
+    runtime: 'browser',
+    adapterName: input.adapterName || null,
+    browser: input.browser || null,
+    requestedFeatures: featureList(input.requestedFeatures),
+    features: featureList(input.effectiveFeatures || input.features),
+    limits: copyLimits(input.limits),
+    timestampQuery: input.timestampQuery || 'unavailable',
+  };
+}
+
+export function validateWebGpuBackendIdentity(identity) {
+  const errors = [];
+
+  if (!identity || typeof identity !== 'object') {
+    return { ok: false, errors: ['identity must be an object'] };
+  }
+  if (identity.kind !== 'webgpu-local') errors.push('kind must be webgpu-local');
+  if (identity.runtime !== 'browser') errors.push('runtime must be browser');
+  if (!isNonEmptyString(identity.adapterName)) errors.push('adapterName must be a non-empty string');
+  if (!Array.isArray(identity.features) || identity.features.length === 0) {
+    errors.push('features must be a non-empty array');
+  }
+  if (!identity.limits || typeof identity.limits !== 'object' || Object.keys(identity.limits).length === 0) {
+    errors.push('limits must be a non-empty object');
+  }
+
+  const timestampStates = new Set(['requested', 'available', 'unavailable', 'disabled']);
+  if (!timestampStates.has(identity.timestampQuery)) {
+    errors.push('timestampQuery has unsupported state');
+  }
+
+  if (identity.timestampQuery === 'requested') {
+    const requested = featureList(identity.requestedFeatures);
+    const effective = featureList(identity.features);
+    if (!requested.includes('timestamp-query')) {
+      errors.push('timestamp-query requested state must include timestamp-query in requestedFeatures');
+    }
+    if (!effective.includes('timestamp-query')) {
+      errors.push('timestamp-query requested state must include timestamp-query in features');
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/index.js

@@ -0,0 +1,106 @@
+export {
+  assertAuthoritativeRouteReceipt,
+  createWebGpuLocalRouteReceipt,
+  validateRouteReceipt,
+  WEBGPU_ROUTE_RECEIPT_SCHEMA,
+} from './route-receipt.js';
+
+export {
+  defineTensorManifest,
+  validateTensorManifest,
+} from './tensor-manifest.js';
+
+export {
+  createWebGpuBackendIdentity,
+  createWebGpuDeviceRequest,
+  requestBrowserWebGpuDevice,
+  validateWebGpuBackendIdentity,
+} from './gpu-environment.js';
+
+export {
+  addStagedSubmitStage,
+  createStagedSubmitProfile,
+  finishStagedSubmitProfile,
+  validateStagedSubmitProfile,
+} from './staged-profile.js';
+
+export {
+  createKernelProfileMetadata,
+  createRouteKernelProfileMetadata,
+  createRouteTimingMetadata,
+  validateKernelProfileMetadata,
+  validateRouteTimingMetadata,
+} from './kernel-profile.js';
+
+export {
+  createWebGpuRuntimeProfile,
+  createWebGpuRuntimeProfileInput,
+  validateWebGpuRuntimeProfile,
+  WEBGPU_RUNTIME_PROFILE_SCHEMA,
+} from './runtime-profile.js';
+
+export {
+  createWebGpuRouteBackpressureProfile,
+  createWebGpuRouteSchedulerProfile,
+  validateWebGpuRouteBackpressureProfile,
+  validateWebGpuRouteSchedulerProfile,
+  WEBGPU_ROUTE_BACKPRESSURE_SCHEMA,
+  WEBGPU_ROUTE_SCHEDULER_SCHEMA,
+} from './scheduler-backpressure.js';
+
+export {
+  classifyWebGpuRouteReceiptEvidence,
+  classifyWebGpuRouteWorkerResultEvidence,
+  WEBGPU_ROUTE_EVIDENCE_CLASSIFICATION_SCHEMA,
+} from './route-receipt-consumer.js';
+
+export {
+  MOGE_DEPTH_NORMAL_ROUTE_ID,
+  createMogeDepthNormalRouteDefinition,
+  createMogeDepthNormalRouteReceipt,
+} from './moge-route.js';
+
+export {
+  SHARP_IMAGE_TO_SPLAT_ROUTE_ID,
+  createSharpImageToSplatRouteDefinition,
+  createSharpImageToSplatRouteReceipt,
+} from './sharp-route.js';
+
+export {
+  KIMODO_TEXT_TO_MOTION_ROUTE_ID,
+  createKimodoTextToMotionRouteDefinition,
+  createKimodoTextToMotionRouteReceipt,
+} from './kimodo-route.js';
+
+export {
+  SF3D_IMAGE_TO_MESH_ROUTE_ID,
+  createSf3dImageToMeshRouteDefinition,
+  createSf3dImageToMeshRouteReceipt,
+} from './sf3d-route.js';
+
+export {
+  createWebGpuRouteSchemaContract,
+} from './route-schema-contract.js';
+
+export {
+  createRouteReceiptArtifacts,
+  createRouteReceiptInputArtifact,
+  createWebGpuRouteReceiptFromArtifacts,
+  finishAndValidateRouteProfile,
+  validateRouteReceiptArtifact,
+  validateRouteReceiptBackendIdentity,
+} from './route-receipt-helper.js';
+
+export {
+  assertAuthoritativeRouteWorkerResult,
+  createRouteInvocationRequest,
+  createRouteWorkerResult,
+  createWebGpuRouteRegistry,
+  defineWebGpuRoute,
+  validateRouteDefinition,
+  validateRouteInvocationRequest,
+  validateRouteWorkerResult,
+  WEBGPU_ROUTE_DEFINITION_SCHEMA,
+  WEBGPU_ROUTE_REQUEST_SCHEMA,
+  WEBGPU_ROUTE_RESULT_SCHEMA,
+} from './route-boundary.js';

package/src/kernel-profile.js

@@ -0,0 +1,101 @@
+const DEFAULT_KIT_VERSION = '0.0.0';
+const DEFAULT_TIMING_SOURCE = 'queue-submit-wait';
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function normalizeSource(input) {
+  return input && typeof input === 'object' ? input : {};
+}
+
+function stringOrDefault(value, fallback) {
+  return isNonEmptyString(value) ? value : fallback;
+}
+
+export function validateKernelProfileMetadata(kernel) {
+  const errors = [];
+
+  if (!kernel || typeof kernel !== 'object') {
+    return { ok: false, errors: ['kernel must be an object'] };
+  }
+
+  if (!isNonEmptyString(kernel.kitVersion)) errors.push('kernel.kitVersion must be a non-empty string');
+  if (!isNonEmptyString(kernel.profile)) errors.push('kernel.profile must be a non-empty string');
+  if (kernel.commit != null && typeof kernel.commit !== 'string') {
+    errors.push('kernel.commit must be a string or null');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function createKernelProfileMetadata(input = {}, options = {}) {
+  const source = normalizeSource(input);
+  const kernel = {
+    kitVersion: stringOrDefault(source.kitVersion, options.defaultKitVersion || DEFAULT_KIT_VERSION),
+    profile: stringOrDefault(source.profile, options.defaultProfile),
+    commit: source.commit || null,
+  };
+
+  if (options.requireProfile === true || options.validate === true) {
+    const result = validateKernelProfileMetadata(kernel);
+    if (!result.ok) throw new Error(result.errors.join('; '));
+  }
+
+  return kernel;
+}
+
+export function validateRouteTimingMetadata(timing) {
+  const errors = [];
+
+  if (!timing || typeof timing !== 'object') {
+    return { ok: false, errors: ['timing metadata must be an object'] };
+  }
+
+  if (!Array.isArray(timing.requiredStages) || timing.requiredStages.length === 0) {
+    errors.push('requiredStages must be a non-empty array');
+  } else {
+    timing.requiredStages.forEach((stage, index) => {
+      if (!isNonEmptyString(stage)) errors.push(`requiredStages[${index}] must be a non-empty string`);
+    });
+  }
+  if (!isNonEmptyString(timing.timingSource)) errors.push('timingSource must be a non-empty string');
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function createRouteTimingMetadata(input = {}, options = {}) {
+  const source = normalizeSource(input);
+  const requiredStages = Array.isArray(source.requiredStages)
+    ? source.requiredStages
+    : (Array.isArray(options.requiredStages) ? options.requiredStages : []);
+
+  const timing = {
+    requiredStages: [...requiredStages],
+    timingSource: stringOrDefault(source.timingSource, options.timingSource || DEFAULT_TIMING_SOURCE),
+  };
+
+  if (options.validate === true) {
+    const result = validateRouteTimingMetadata(timing);
+    if (!result.ok) throw new Error(result.errors.join('; '));
+  }
+
+  return timing;
+}
+
+export function createRouteKernelProfileMetadata(input = {}, options = {}) {
+  const source = normalizeSource(input);
+  return {
+    kernel: createKernelProfileMetadata(source.kernel, {
+      defaultKitVersion: options.defaultKitVersion,
+      defaultProfile: options.defaultProfile,
+      requireProfile: options.requireProfile,
+      validate: options.validateKernel,
+    }),
+    ...createRouteTimingMetadata(source, {
+      requiredStages: options.requiredStages,
+      timingSource: options.timingSource,
+      validate: options.validateTiming,
+    }),
+  };
+}

package/src/kimodo-route.js

@@ -0,0 +1,84 @@
+import { defineWebGpuRoute } from './route-boundary.js';
+import {
+  createKernelProfileMetadata,
+  createRouteKernelProfileMetadata,
+} from './kernel-profile.js';
+import {
+  createRouteReceiptArtifacts,
+  createRouteReceiptInputArtifact,
+  createWebGpuRouteReceiptFromArtifacts,
+} from './route-receipt-helper.js';
+
+export const KIMODO_TEXT_TO_MOTION_ROUTE_ID = 'kimodo.text-to-motion.webgpu-local.v0';
+const KIMODO_MODEL_ID = 'NVIDIA/Kimodo-SOMA-RP-v1.1';
+const DEFAULT_KERNEL_PROFILE = 'twostage-denoiser-ddim50-fk';
+const REQUIRED_STAGES = ['text-embedding', 'ddim-sampling', 'fk-decode', 'output-capture'];
+const OUTPUT_ROLES = [
+  { key: 'soma77Joints', role: 'soma77-joints', required: true },
+  { key: 'motionClip', role: 'motion-clip', required: true },
+  { key: 'filmstrip', role: 'filmstrip', required: false },
+];
+
+export function createKimodoTextToMotionRouteReceipt(input) {
+  if (!input || typeof input !== 'object') throw new Error('input must be an object');
+  if (!input.input?.artifactId || !input.input?.sha256) {
+    throw new Error('text prompt artifactId and sha256 are required');
+  }
+  if (!input.outputs?.soma77Joints) throw new Error('soma77Joints output is required');
+  if (!input.outputs?.motionClip) throw new Error('motionClip output is required');
+
+  return createWebGpuRouteReceiptFromArtifacts({
+    requestedRouteId: KIMODO_TEXT_TO_MOTION_ROUTE_ID,
+    effectiveRouteId: input.effectiveRouteId || KIMODO_TEXT_TO_MOTION_ROUTE_ID,
+    status: input.status || (input.fallbackReason ? 'fallback' : 'real'),
+    fallbackReason: input.fallbackReason || null,
+    backend: input.backend,
+    model: {
+      id: KIMODO_MODEL_ID,
+      revision: input.model?.revision,
+      weightsHash: input.model?.weightsHash,
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: createKernelProfileMetadata(input.kernel, { requireProfile: true }),
+    inputs: [
+      createRouteReceiptInputArtifact('text-prompt', input.input),
+    ],
+    outputs: createRouteReceiptArtifacts({ artifacts: input.outputs, roles: OUTPUT_ROLES }),
+    profile: input.profile,
+  });
+}
+
+export function createKimodoTextToMotionRouteDefinition(input = {}) {
+  const routeMetadata = createRouteKernelProfileMetadata(input, {
+    defaultProfile: DEFAULT_KERNEL_PROFILE,
+    requiredStages: REQUIRED_STAGES,
+    timingSource: 'adapter-phase-wall-clock',
+  });
+
+  return defineWebGpuRoute({
+    routeId: KIMODO_TEXT_TO_MOTION_ROUTE_ID,
+    backendKind: 'webgpu-local',
+    model: {
+      id: KIMODO_MODEL_ID,
+      revision: input.model?.revision || 'SOMA-RP-v1.1',
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: routeMetadata.kernel,
+    inputs: [
+      { role: 'text-prompt', required: true, artifactRequired: true, hashRequired: true },
+    ],
+    outputs: [
+      { role: 'soma77-joints', required: true, artifactRequired: true, hashRequired: true, shape: [90, 77, 3] },
+      { role: 'motion-clip', required: true, artifactRequired: true, hashRequired: true, shape: [1] },
+      { role: 'filmstrip', required: false, artifactRequired: true, hashRequired: true },
+    ],
+    requiredFeatures: input.requiredFeatures || [],
+    requiredStages: routeMetadata.requiredStages,
+    timingSource: routeMetadata.timingSource,
+    worker: input.worker || {
+      exportName: 'runKimodoTextToMotionRoute',
+      textEmbedding: 'external-llama3-8b',
+      motionFormat: 'kimodo-soma77-explicit-joints',
+    },
+  });
+}