@kaminos/webgpu-inference-kit 0.1.0

package/src/moge-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 MOGE_DEPTH_NORMAL_ROUTE_ID = 'moge.depth-normal.webgpu-local.v0';
+const MOGE_MODEL_ID = 'Ruicheng/moge-2-vitl-normal';
+const DEFAULT_KERNEL_PROFILE = 'conv-transpose2d-stride2';
+const REQUIRED_STAGES = ['backbone', 'decoder-heads', 'output-readback'];
+const OUTPUT_ROLES = [
+  { key: 'depth', role: 'depth', required: true },
+  { key: 'normal', role: 'normal', required: true },
+  { key: 'pointMap', role: 'pointmap', required: false },
+  { key: 'mask', role: 'mask', required: false },
+];
+
+export function createMogeDepthNormalRouteReceipt(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?.depth) throw new Error('depth output is required');
+  if (!input.outputs?.normal) throw new Error('normal output is required');
+
+  return createWebGpuRouteReceiptFromArtifacts({
+    requestedRouteId: MOGE_DEPTH_NORMAL_ROUTE_ID,
+    effectiveRouteId: input.effectiveRouteId || MOGE_DEPTH_NORMAL_ROUTE_ID,
+    status: input.status || (input.fallbackReason ? 'fallback' : 'real'),
+    fallbackReason: input.fallbackReason || null,
+    backend: input.backend,
+    model: {
+      id: MOGE_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 createMogeDepthNormalRouteDefinition(input = {}) {
+  const routeMetadata = createRouteKernelProfileMetadata(input, {
+    defaultProfile: DEFAULT_KERNEL_PROFILE,
+    requiredStages: REQUIRED_STAGES,
+    timingSource: 'queue-submit-wait',
+  });
+
+  return defineWebGpuRoute({
+    routeId: MOGE_DEPTH_NORMAL_ROUTE_ID,
+    backendKind: 'webgpu-local',
+    model: {
+      id: MOGE_MODEL_ID,
+      revision: input.model?.revision || 'local-vitl-normal',
+      dtype: input.model?.dtype || 'fp16',
+    },
+    kernel: routeMetadata.kernel,
+    inputs: [
+      { role: 'source-image', required: true, artifactRequired: true, hashRequired: true },
+    ],
+    outputs: [
+      { role: 'depth', required: true, artifactRequired: true, hashRequired: true, shape: [592, 592] },
+      { role: 'normal', required: true, artifactRequired: true, hashRequired: true, shape: [3, 592, 592] },
+      { role: 'pointmap', required: false, artifactRequired: true, hashRequired: true, shape: [3, 592, 592] },
+      { role: 'mask', required: false, artifactRequired: true, hashRequired: true, shape: [592, 592] },
+    ],
+    requiredFeatures: input.requiredFeatures || [],
+    requiredStages: routeMetadata.requiredStages,
+    timingSource: routeMetadata.timingSource,
+    worker: input.worker || {
+      exportName: 'runMogeDepthNormalRoute',
+    },
+  });
+}

package/src/route-boundary.js

@@ -0,0 +1,347 @@
+import { validateWebGpuBackendIdentity } from './gpu-environment.js';
+import {
+  assertAuthoritativeRouteReceipt,
+  validateRouteReceipt,
+} from './route-receipt.js';
+
+export const WEBGPU_ROUTE_DEFINITION_SCHEMA = 'kaminos.webgpu-route-definition.v0';
+export const WEBGPU_ROUTE_REQUEST_SCHEMA = 'kaminos.webgpu-route-request.v0';
+export const WEBGPU_ROUTE_RESULT_SCHEMA = 'kaminos.webgpu-route-result.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 requireString(errors, value, path) {
+  if (!isNonEmptyString(value)) errors.push(`${path} must be a non-empty string`);
+}
+
+function roleName(entry) {
+  return typeof entry === 'string' ? entry : entry?.role;
+}
+
+function normalizeRoles(entries = [], { defaultRequired = true } = {}) {
+  if (!Array.isArray(entries)) return [];
+
+  return entries.map(entry => {
+    if (typeof entry === 'string') {
+      return {
+        role: entry,
+        required: defaultRequired,
+        artifactRequired: true,
+        hashRequired: true,
+      };
+    }
+
+    return {
+      role: entry.role,
+      required: entry.required !== false,
+      artifactRequired: entry.artifactRequired !== false,
+      hashRequired: entry.hashRequired !== false,
+      shape: Array.isArray(entry.shape) ? [...entry.shape] : undefined,
+    };
+  });
+}
+
+function roleSet(roles) {
+  return new Set(roles.map(role => role.role));
+}
+
+function artifactArray(roles, artifacts = {}, { includeOptional = true, requireKnown = true } = {}) {
+  const byRole = Array.isArray(artifacts)
+    ? Object.fromEntries(artifacts.map(artifact => [artifact?.role, artifact]))
+    : artifacts;
+  const knownRoles = roleSet(roles);
+  const out = [];
+
+  for (const role of roles) {
+    const artifact = byRole?.[role.role];
+    if (!artifact) {
+      if (role.required || !includeOptional) {
+        out.push({ role: role.role });
+      }
+      continue;
+    }
+
+    out.push({
+      role: role.role,
+      artifactId: artifact.artifactId,
+      sha256: artifact.sha256,
+      shape: Array.isArray(artifact.shape) ? [...artifact.shape] : undefined,
+      status: artifact.status,
+    });
+  }
+
+  if (requireKnown && byRole && typeof byRole === 'object') {
+    for (const key of Object.keys(byRole)) {
+      if (!knownRoles.has(key)) {
+        out.push({ role: key, unknownRole: true, ...clone(byRole[key]) });
+      }
+    }
+  }
+
+  return out;
+}
+
+function requiredRoleNames(roles) {
+  return roles.filter(role => role.required !== false).map(role => role.role);
+}
+
+function optionalRoleNames(roles) {
+  return roles.filter(role => role.required === false).map(role => role.role);
+}
+
+function validateArtifacts(errors, artifacts, roles, path, { requireHash }) {
+  const knownRoles = roleSet(roles);
+  const artifactsByRole = new Map();
+
+  if (!Array.isArray(artifacts)) {
+    errors.push(`${path} must be an array`);
+    return;
+  }
+
+  artifacts.forEach((artifact, index) => {
+    const artifactPath = `${path}[${index}]`;
+    requireString(errors, artifact?.role, `${artifactPath}.role`);
+    if (isNonEmptyString(artifact?.role)) {
+      if (artifactsByRole.has(artifact.role)) errors.push(`${artifactPath}.role duplicates ${artifact.role}`);
+      artifactsByRole.set(artifact.role, artifact);
+      if (!knownRoles.has(artifact.role)) errors.push(`${artifactPath}.role is not defined by route`);
+    }
+    if (artifact?.unknownRole) errors.push(`${artifactPath}.role is not defined by route`);
+    requireString(errors, artifact?.artifactId, `${artifactPath}.artifactId`);
+    if (requireHash) requireString(errors, artifact?.sha256, `${artifactPath}.sha256`);
+    if (artifact?.shape != null && (!Array.isArray(artifact.shape) || !artifact.shape.every(Number.isInteger))) {
+      errors.push(`${artifactPath}.shape must be an integer array when present`);
+    }
+  });
+
+  for (const role of roles) {
+    if (role.required !== false && !artifactsByRole.has(role.role)) {
+      errors.push(`${path} missing required role ${role.role}`);
+    }
+  }
+}
+
+export function defineWebGpuRoute(input) {
+  if (!input || typeof input !== 'object') throw new Error('route input must be an object');
+
+  const inputRoles = normalizeRoles(input.inputs || input.inputRoles, { defaultRequired: true });
+  const outputRoles = normalizeRoles(input.outputs || input.outputRoles, { defaultRequired: true });
+
+  return {
+    schema: WEBGPU_ROUTE_DEFINITION_SCHEMA,
+    routeId: input.routeId,
+    backendKind: input.backendKind || 'webgpu-local',
+    model: clone(input.model),
+    kernel: clone(input.kernel),
+    inputRoles,
+    outputRoles,
+    requiredInputRoles: requiredRoleNames(inputRoles),
+    requiredOutputRoles: requiredRoleNames(outputRoles),
+    optionalOutputRoles: optionalRoleNames(outputRoles),
+    requiredFeatures: Array.isArray(input.requiredFeatures) ? [...input.requiredFeatures].map(String).sort() : [],
+    requiredStages: Array.isArray(input.requiredStages) ? [...input.requiredStages] : [],
+    timingSource: input.timingSource || 'queue-submit-wait',
+    worker: clone(input.worker || null),
+  };
+}
+
+export function validateRouteDefinition(route) {
+  const errors = [];
+
+  if (!route || typeof route !== 'object') {
+    return { ok: false, errors: ['route must be an object'] };
+  }
+
+  if (route.schema !== WEBGPU_ROUTE_DEFINITION_SCHEMA) errors.push(`schema must be ${WEBGPU_ROUTE_DEFINITION_SCHEMA}`);
+  requireString(errors, route.routeId, 'routeId');
+  if (route.backendKind !== 'webgpu-local') errors.push('backendKind must be webgpu-local');
+
+  if (!route.model || typeof route.model !== 'object') {
+    errors.push('model must be an object');
+  } else {
+    requireString(errors, route.model.id, 'model.id');
+  }
+
+  if (!route.kernel || typeof route.kernel !== 'object') {
+    errors.push('kernel must be an object');
+  } else {
+    requireString(errors, route.kernel.profile, 'kernel.profile');
+  }
+
+  if (!Array.isArray(route.inputRoles) || route.inputRoles.length === 0) {
+    errors.push('inputRoles must be a non-empty array');
+  } else {
+    route.inputRoles.forEach((role, index) => requireString(errors, role?.role, `inputRoles[${index}].role`));
+  }
+
+  if (!Array.isArray(route.outputRoles) || route.outputRoles.length === 0) {
+    errors.push('outputRoles must be a non-empty array');
+  } else {
+    route.outputRoles.forEach((role, index) => requireString(errors, role?.role, `outputRoles[${index}].role`));
+  }
+
+  if (!Array.isArray(route.requiredInputRoles) || route.requiredInputRoles.length === 0) {
+    errors.push('requiredInputRoles must be a non-empty array');
+  }
+  if (!Array.isArray(route.requiredOutputRoles) || route.requiredOutputRoles.length === 0) {
+    errors.push('requiredOutputRoles must be a non-empty array');
+  }
+  if (!isNonEmptyString(route.timingSource)) errors.push('timingSource must be a non-empty string');
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function createWebGpuRouteRegistry(initialRoutes = []) {
+  const routes = new Map();
+
+  function register(route) {
+    const result = validateRouteDefinition(route);
+    if (!result.ok) throw new Error(`invalid route definition: ${result.errors.join('; ')}`);
+    if (routes.has(route.routeId)) throw new Error(`duplicate route: ${route.routeId}`);
+    routes.set(route.routeId, route);
+    return route;
+  }
+
+  for (const route of initialRoutes) register(route);
+
+  return {
+    register,
+    has(routeId) {
+      return routes.has(routeId);
+    },
+    get(routeId) {
+      const route = routes.get(routeId);
+      if (!route) throw new Error(`unknown route: ${routeId}`);
+      return route;
+    },
+    list() {
+      return Array.from(routes.values());
+    },
+    createRequest(routeId, input) {
+      return createRouteInvocationRequest(this.get(routeId), input);
+    },
+  };
+}
+
+export function createRouteInvocationRequest(route, input) {
+  const result = validateRouteDefinition(route);
+  if (!result.ok) throw new Error(`invalid route definition: ${result.errors.join('; ')}`);
+  if (!input || typeof input !== 'object') throw new Error('route request input must be an object');
+  if (!isNonEmptyString(input.requestId)) throw new Error('requestId must be a non-empty string');
+
+  return {
+    schema: WEBGPU_ROUTE_REQUEST_SCHEMA,
+    requestId: input.requestId,
+    routeId: route.routeId,
+    backendKind: route.backendKind,
+    inputs: artifactArray(route.inputRoles, input.inputs, { includeOptional: false }),
+    outputs: artifactArray(route.outputRoles, input.outputs, { includeOptional: true }).map(output => ({
+      role: output.role,
+      artifactId: output.artifactId,
+      shape: output.shape,
+      unknownRole: output.unknownRole,
+    })),
+    routeConfig: clone(input.routeConfig || {}),
+    model: clone(route.model),
+    kernel: clone(route.kernel),
+    createdAt: input.createdAt || new Date().toISOString(),
+  };
+}
+
+export function validateRouteInvocationRequest(request, route) {
+  const errors = [];
+  const routeResult = validateRouteDefinition(route);
+  if (!routeResult.ok) errors.push(...routeResult.errors.map(error => `route.${error}`));
+
+  if (!request || typeof request !== 'object') {
+    return { ok: false, errors: ['request must be an object'] };
+  }
+  if (request.schema !== WEBGPU_ROUTE_REQUEST_SCHEMA) errors.push(`schema must be ${WEBGPU_ROUTE_REQUEST_SCHEMA}`);
+  requireString(errors, request.requestId, 'requestId');
+  if (request.routeId !== route?.routeId) errors.push('routeId must match route definition');
+  if (request.backendKind !== 'webgpu-local') errors.push('backendKind must be webgpu-local');
+
+  if (routeResult.ok) {
+    validateArtifacts(errors, request.inputs, route.inputRoles, 'inputs', { requireHash: true });
+    validateArtifacts(errors, request.outputs, route.outputRoles, 'outputs', { requireHash: false });
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function createRouteWorkerResult(route, input) {
+  if (!input || typeof input !== 'object') throw new Error('worker result input must be an object');
+  const request = input.request || {};
+  const receipt = input.receipt;
+
+  return {
+    schema: WEBGPU_ROUTE_RESULT_SCHEMA,
+    requestId: request.requestId,
+    routeId: route.routeId,
+    status: receipt?.status || 'unknown',
+    request: clone(request),
+    receipt: clone(receipt),
+    backend: clone(receipt?.backend),
+    outputs: clone(receipt?.outputs || []),
+    timings: clone(receipt?.timings),
+    createdAt: input.createdAt || new Date().toISOString(),
+  };
+}
+
+export function validateRouteWorkerResult(result, route) {
+  const errors = [];
+  const routeResult = validateRouteDefinition(route);
+  if (!routeResult.ok) errors.push(...routeResult.errors.map(error => `route.${error}`));
+
+  if (!result || typeof result !== 'object') {
+    return { ok: false, errors: ['result must be an object'] };
+  }
+
+  if (result.schema !== WEBGPU_ROUTE_RESULT_SCHEMA) errors.push(`schema must be ${WEBGPU_ROUTE_RESULT_SCHEMA}`);
+  requireString(errors, result.requestId, 'requestId');
+  if (result.routeId !== route?.routeId) errors.push('routeId must match route definition');
+
+  if (result.request != null) {
+    const requestResult = validateRouteInvocationRequest(result.request, route);
+    if (!requestResult.ok) errors.push(...requestResult.errors.map(error => `request.${error}`));
+  }
+
+  const receiptResult = validateRouteReceipt(result.receipt);
+  if (!receiptResult.ok) {
+    errors.push(...receiptResult.errors.map(error => `receipt.${error}`));
+  } else {
+    if (result.receipt.requestedRouteId !== route.routeId) {
+      errors.push('receipt.requestedRouteId must match route definition');
+    }
+    if (result.receipt.effectiveRouteId !== route.routeId) {
+      errors.push('receipt.effectiveRouteId must match route definition');
+    }
+  }
+
+  const backendResult = validateWebGpuBackendIdentity(result.backend);
+  if (!backendResult.ok) errors.push(...backendResult.errors.map(error => `backend.${error}`));
+
+  if (routeResult.ok && Array.isArray(result.outputs)) {
+    validateArtifacts(errors, result.outputs, route.outputRoles, 'outputs', { requireHash: true });
+  } else if (!Array.isArray(result.outputs)) {
+    errors.push('outputs must be an array');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function assertAuthoritativeRouteWorkerResult(result, route) {
+  const validation = validateRouteWorkerResult(result, route);
+  if (!validation.ok) {
+    throw new Error(`invalid route worker result: ${validation.errors.join('; ')}`);
+  }
+
+  assertAuthoritativeRouteReceipt(result.receipt);
+  return result;
+}

package/src/route-receipt-consumer.js

@@ -0,0 +1,160 @@
+import {
+  validateWebGpuBackendIdentity,
+} from './gpu-environment.js';
+import {
+  validateRouteReceipt,
+} from './route-receipt.js';
+import {
+  validateWebGpuRouteBackpressureProfile,
+  validateWebGpuRouteSchedulerProfile,
+} from './scheduler-backpressure.js';
+
+export const WEBGPU_ROUTE_EVIDENCE_CLASSIFICATION_SCHEMA = 'kaminos.webgpu-route-evidence-classification.v0';
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function parseTime(value) {
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function staleReason(receipt, options) {
+  if (!Number.isFinite(options.maxAgeMs)) return null;
+  const createdMs = parseTime(receipt.createdAt);
+  const nowMs = parseTime(options.now || new Date().toISOString());
+  if (createdMs == null) return 'createdAt is missing or invalid for freshness check';
+  if (nowMs == null) return 'now is invalid for freshness check';
+  return nowMs - createdMs > options.maxAgeMs ? `receipt is older than ${options.maxAgeMs}ms` : null;
+}
+
+function classifyNonRealStatus(status) {
+  if (status === 'fallback') return 'fallback';
+  if (status === 'cached') return 'cache';
+  if (status === 'cache') return 'cache';
+  if (status === 'demo') return 'demo';
+  if (status === 'fixture') return 'demo';
+  if (status === 'partial') return 'partial';
+  return 'non-real';
+}
+
+function outputClassification(outputs = []) {
+  if (!Array.isArray(outputs)) return null;
+  if (outputs.some(output => output?.status === 'partial')) return 'partial';
+  if (outputs.some(output => output?.status === 'cached' || output?.status === 'cache')) return 'cache';
+  if (outputs.some(output => output?.status === 'demo' || output?.status === 'fixture')) return 'demo';
+  if (outputs.some(output => output?.status !== 'real')) return 'non-real-output';
+  return null;
+}
+
+function baseClassification(receipt, options = {}) {
+  const reasons = [];
+  const receiptResult = validateRouteReceipt(receipt);
+  if (!receiptResult.ok) reasons.push(...receiptResult.errors);
+
+  const backendResult = validateWebGpuBackendIdentity(receipt?.backend);
+  if (!backendResult.ok) reasons.push(...backendResult.errors.map(error => `backend.${error}`));
+
+  if (receipt?.runtime?.scheduler) {
+    const schedulerResult = validateWebGpuRouteSchedulerProfile(receipt.runtime.scheduler);
+    if (!schedulerResult.ok) reasons.push(...schedulerResult.errors.map(error => `scheduler.${error}`));
+  }
+
+  if (receipt?.runtime?.backpressure) {
+    const backpressureResult = validateWebGpuRouteBackpressureProfile(receipt.runtime.backpressure);
+    if (!backpressureResult.ok) reasons.push(...backpressureResult.errors.map(error => `backpressure.${error}`));
+  }
+
+  if (reasons.length > 0) {
+    return { classification: 'invalid', authoritative: false, reasons };
+  }
+
+  if (isNonEmptyString(options.expectedRouteId) && receipt.effectiveRouteId !== options.expectedRouteId) {
+    return {
+      classification: 'route-mismatch',
+      authoritative: false,
+      reasons: [`effectiveRouteId ${receipt.effectiveRouteId} does not match expected ${options.expectedRouteId}`],
+    };
+  }
+
+  const stale = staleReason(receipt, options);
+  if (stale) {
+    return { classification: 'stale', authoritative: false, reasons: [stale] };
+  }
+
+  if (receipt.status !== 'real') {
+    return {
+      classification: classifyNonRealStatus(receipt.status),
+      authoritative: false,
+      reasons: [`receipt status is ${receipt.status}`],
+    };
+  }
+
+  if (receipt.fallbackReason) {
+    return {
+      classification: 'fallback',
+      authoritative: false,
+      reasons: [`fallback reason present: ${receipt.fallbackReason}`],
+    };
+  }
+
+  const outputStatus = outputClassification(receipt.outputs);
+  if (outputStatus) {
+    return {
+      classification: outputStatus,
+      authoritative: false,
+      reasons: [`one or more outputs are ${outputStatus}`],
+    };
+  }
+
+  return {
+    classification: 'authoritative-live-webgpu',
+    authoritative: true,
+    reasons: [],
+  };
+}
+
+export function classifyWebGpuRouteReceiptEvidence(receipt, options = {}) {
+  const base = baseClassification(receipt, options);
+  const scheduler = receipt?.runtime?.scheduler || null;
+  const backpressure = receipt?.runtime?.backpressure || null;
+  return {
+    schema: WEBGPU_ROUTE_EVIDENCE_CLASSIFICATION_SCHEMA,
+    classification: base.classification,
+    authoritative: base.authoritative,
+    reasons: base.reasons,
+    routeId: receipt?.effectiveRouteId || receipt?.requestedRouteId || null,
+    requestedRouteId: receipt?.requestedRouteId || null,
+    effectiveRouteId: receipt?.effectiveRouteId || null,
+    backendKind: receipt?.backend?.kind || null,
+    adapterName: receipt?.backend?.adapterName || null,
+    timingSource: receipt?.timings?.source || receipt?.timings?.profile?.timingSource || null,
+    totalMs: Number.isFinite(receipt?.timings?.totalMs) ? receipt.timings.totalMs : null,
+    schedulerVerificationState: scheduler?.verificationState || null,
+    schedulerMode: scheduler?.effectiveScheduler?.mode || scheduler?.requestedScheduler?.mode || null,
+    schedulerUnsupportedFields: Array.isArray(scheduler?.effectiveScheduler?.unsupportedFields)
+      ? [...scheduler.effectiveScheduler.unsupportedFields]
+      : [],
+    requestedBudget: backpressure?.requestedBudget || null,
+    effectiveBudget: backpressure?.effectiveBudget || null,
+    longFrameCount: Number.isInteger(backpressure?.frameTail?.longFrameCount)
+      ? backpressure.frameTail.longFrameCount
+      : null,
+    maxFrameGapMs: Number.isFinite(backpressure?.frameTail?.maxFrameGapMs)
+      ? backpressure.frameTail.maxFrameGapMs
+      : null,
+    outputRoles: Array.isArray(receipt?.outputs) ? receipt.outputs.map(output => output.role) : [],
+    createdAt: receipt?.createdAt || null,
+  };
+}
+
+export function classifyWebGpuRouteWorkerResultEvidence(result, options = {}) {
+  const classification = classifyWebGpuRouteReceiptEvidence(result?.receipt, options);
+  return {
+    ...classification,
+    requestId: result?.requestId || null,
+    resultRouteId: result?.routeId || null,
+    resultStatus: result?.status || null,
+  };
+}

package/src/route-receipt-helper.js

@@ -0,0 +1,86 @@
+import { validateWebGpuBackendIdentity } from './gpu-environment.js';
+import { createWebGpuLocalRouteReceipt } from './route-receipt.js';
+import { finishStagedSubmitProfile, validateStagedSubmitProfile } from './staged-profile.js';
+
+export function validateRouteReceiptArtifact(value, name) {
+  if (!value || typeof value !== 'object') throw new Error(`${name} output must be an object`);
+  if (typeof value.artifactId !== 'string' || value.artifactId.length === 0) {
+    throw new Error(`${name} output must include artifactId`);
+  }
+  if (typeof value.sha256 !== 'string' || value.sha256.length === 0) {
+    throw new Error(`${name} output must include sha256`);
+  }
+  if (!Array.isArray(value.shape) || value.shape.length === 0) {
+    throw new Error(`${name} output must include shape`);
+  }
+}
+
+export function createRouteReceiptInputArtifact(role, artifact) {
+  return {
+    role,
+    artifactId: artifact.artifactId,
+    sha256: artifact.sha256,
+    shape: Array.isArray(artifact.shape) ? [...artifact.shape] : undefined,
+  };
+}
+
+export function createRouteReceiptArtifacts({ artifacts, roles }) {
+  if (!artifacts || typeof artifacts !== 'object') throw new Error('artifacts must be an object');
+  if (!Array.isArray(roles) || roles.length === 0) throw new Error('roles must be a non-empty array');
+
+  const outputs = [];
+  for (const role of roles) {
+    const key = role.key;
+    const artifact = artifacts[key];
+    if (!artifact) {
+      if (role.required !== false) throw new Error(`${key} output is required`);
+      continue;
+    }
+
+    validateRouteReceiptArtifact(artifact, key);
+    outputs.push({
+      role: role.role,
+      artifactId: artifact.artifactId,
+      sha256: artifact.sha256,
+      shape: [...artifact.shape],
+      status: artifact.status || 'real',
+    });
+  }
+  return outputs;
+}
+
+export function finishAndValidateRouteProfile(profile) {
+  const finished = finishStagedSubmitProfile(profile);
+  const result = validateStagedSubmitProfile(finished);
+  if (!result.ok) throw new Error(`invalid staged profile: ${result.errors.join('; ')}`);
+  return finished;
+}
+
+export function validateRouteReceiptBackendIdentity(backend) {
+  const result = validateWebGpuBackendIdentity(backend);
+  if (!result.ok) throw new Error(`invalid WebGPU backend identity: ${result.errors.join('; ')}`);
+  return backend;
+}
+
+export function createWebGpuRouteReceiptFromArtifacts(input) {
+  validateRouteReceiptBackendIdentity(input.backend);
+  const profile = finishAndValidateRouteProfile(input.profile);
+
+  return createWebGpuLocalRouteReceipt({
+    requestedRouteId: input.requestedRouteId,
+    effectiveRouteId: input.effectiveRouteId || input.requestedRouteId,
+    status: input.status || (input.fallbackReason ? 'fallback' : 'real'),
+    fallbackReason: input.fallbackReason || null,
+    backend: input.backend,
+    model: input.model,
+    kernel: input.kernel,
+    inputs: input.inputs,
+    outputs: input.outputs,
+    timings: {
+      source: profile.timingSource,
+      totalMs: profile.totalMs,
+      stages: profile.stages,
+      profile,
+    },
+  });
+}