@kaminos/webgpu-inference-kit 0.1.2 → 0.1.4

package/README.md

@@ -31,7 +31,7 @@ import {
 - What route is being invoked, such as MoGE depth/normal or SHARP image-to-splat.
 - Which browser WebGPU adapter, device features, limits, and timestamp capabilities were actually available.
 - Which kernel/profile variant ran, and which stages are required for a useful runtime profile.
-- How a route was scheduled: throughput mode, cooperative/yield posture, phase chunk sizes, submitted-work waits, and unsupported scheduler fields.
+- How a route was scheduled: throughput mode, cooperative/yield posture, breathability spans, yield checkpoints, phase chunk sizes, submitted-work waits, and unsupported scheduler fields.
 - Which artifacts went in and out, so downstream consumers can join routes without losing identity.
 
 The immediate goal is practical composition inside Kaminos: MoGE can become a local geometry/depth route, SHARP can emit splat candidates, Kimodo can emit motion clips, SF3D can emit meshes, and pipeline/commoner code can consume those outputs through one route grammar. The longer-term opportunity is a browser-native inference runtime kit that makes future image generators, 3D generators, and possibly language-model routes easier to seat without rebuilding the same WebGPU plumbing from scratch.
@@ -46,7 +46,7 @@ So the intended stack is:
 
 1. **Route boundary:** define callable browser-local inference routes with stable input/output roles.
 2. **Runtime profile:** preserve adapter/device/kernel/stage identity for the run that actually happened.
-3. **Scheduler/backpressure profile:** expose whether the route is throughput-oriented, cooperative, furnace-class, warm, cached, or frame-tail-sensitive.
+3. **Scheduler/backpressure profile:** expose whether the route is throughput-oriented, cooperative, furnace-class, warm, cached, frame-tail-sensitive, and where it can honestly yield.
 4. **Receipt and classification:** reject stale, fallback, partial, mismatched, or invalid route output before another system treats it as authoritative.
 
 The fourth layer protects the first three. It should not swallow the whole story.
@@ -63,7 +63,7 @@ The fourth layer protects the first three. It should not swallow the whole story
 - `createStagedSubmitProfile(input)`, `addStagedSubmitStage(profile, stage)`, `finishStagedSubmitProfile(profile)`, and `validateStagedSubmitProfile(profile)`: describe staged queue-submit timing in a way that can be compared across routes.
 - `createKernelProfileMetadata(input)` and `createRouteKernelProfileMetadata(input)`: normalize kit version, kernel profile, commit, required stages, and timing-source metadata for route definitions and receipts.
 - `createWebGpuRuntimeProfileInput(input)`, `createWebGpuRuntimeProfile(input)`, and `validateWebGpuRuntimeProfile(profile)`: combine effective backend identity, kernel metadata, staged profile, and route mode into one producer-side runtime profile object.
-- `createWebGpuRouteSchedulerProfile(input)` and `validateWebGpuRouteSchedulerProfile(profile)`: preserve requested versus effective scheduling, including throughput/cooperative mode, route-specific phase chunk sizes, submitted-work waits, yield cadence, and unsupported fields.
+- `createWebGpuRouteSchedulerProfile(input)` and `validateWebGpuRouteSchedulerProfile(profile)`: preserve requested versus effective scheduling, including throughput/cooperative mode, route-specific phase chunk sizes, submitted-work waits, yield cadence, breathability spans, yieldable checkpoints, non-preemptible GPU-submit spans, and unsupported fields.
 - `createWebGpuRouteBackpressureProfile(input)` and `validateWebGpuRouteBackpressureProfile(profile)`: record visible-wait/furnace pressure, warm/cache posture, memory-sharing posture, and frame-tail impact.
 - `defineTensorManifest(input)` and `validateTensorManifest(manifest)`: normalize tensor metadata including dtype sizes and byte lengths.
 - `createWebGpuLocalRouteReceipt(input)`, `createWebGpuRouteReceiptFromArtifacts(input)`, `createRouteReceiptArtifacts(input)`, `finishAndValidateRouteProfile(input)`, `validateRouteReceipt(receipt)`, and `assertAuthoritativeRouteReceipt(receipt)`: shared receipt construction and validation helpers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaminos/webgpu-inference-kit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Composable browser WebGPU inference route contracts, runtime profiles, and scheduler envelopes.",

package/src/kernel-profile.js

@@ -1,4 +1,4 @@
-export const WEBGPU_INFERENCE_KIT_VERSION = '0.1.2';
+export const WEBGPU_INFERENCE_KIT_VERSION = '0.1.4';
 const DEFAULT_KIT_VERSION = WEBGPU_INFERENCE_KIT_VERSION;
 const DEFAULT_TIMING_SOURCE = 'queue-submit-wait';
 

package/src/kimodo-route.js

@@ -8,6 +8,10 @@ import {
   createRouteReceiptInputArtifact,
   createWebGpuRouteReceiptFromArtifacts,
 } from './route-receipt-helper.js';
+import {
+  createWebGpuRouteBackpressureProfile,
+  createWebGpuRouteSchedulerProfile,
+} from './scheduler-backpressure.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';
@@ -19,6 +23,100 @@ const OUTPUT_ROLES = [
   { key: 'filmstrip', role: 'filmstrip', required: false },
 ];
 
+function createDefaultKimodoScheduler() {
+  return createWebGpuRouteSchedulerProfile({
+    requestedScheduler: {
+      mode: 'cooperative',
+      yieldMs: 4,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {
+        'text-embedding': 1,
+        'ddim-sampling': 1,
+        'fk-decode': 1,
+        'output-capture': 1,
+      },
+    },
+    effectiveScheduler: {
+      mode: 'cooperative',
+      yieldMs: 4,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {
+        'text-embedding': 1,
+        'ddim-sampling': 1,
+        'fk-decode': 1,
+        'output-capture': 1,
+      },
+      unsupportedFields: [],
+    },
+    verificationState: 'scheduler-unverified',
+    breathability: {
+      spans: [
+        {
+          name: 'text-embedding',
+          stage: 'text-embedding',
+          kind: 'external-bound',
+          interruptible: false,
+          canYieldBefore: true,
+          canYieldAfter: true,
+        },
+        {
+          name: 'ddim-sampling-loop',
+          stage: 'ddim-sampling',
+          kind: 'gpu-submit-loop',
+          interruptible: false,
+          canYieldBefore: true,
+          canYieldAfter: true,
+          nonInterruptibleReason: 'Each diffusion step submit is non-preemptible; cooperative yielding occurs between steps.',
+          metadata: { checkpointCadence: 'per-diffusion-step' },
+        },
+        {
+          name: 'fk-decode',
+          stage: 'fk-decode',
+          kind: 'cpu-bound',
+          interruptible: true,
+          canYieldBefore: true,
+          canYieldAfter: true,
+        },
+        {
+          name: 'output-capture',
+          stage: 'output-capture',
+          kind: 'readback-bound',
+          interruptible: false,
+          canYieldBefore: true,
+          canYieldAfter: true,
+        },
+      ],
+      checkpoints: [
+        {
+          name: 'between-diffusion-steps',
+          kind: 'diffusion-step',
+          afterStage: 'ddim-sampling',
+          yieldable: true,
+          waitsForSubmittedWorkDone: true,
+          metadata: { cadence: 'per-step' },
+        },
+        {
+          name: 'after-output-capture',
+          kind: 'readback',
+          afterStage: 'output-capture',
+          yieldable: true,
+          waitsForSubmittedWorkDone: true,
+        },
+      ],
+      notes: 'Kimodo can expose useful cooperative pressure between diffusion steps; each submitted step remains non-preemptible.',
+    },
+  });
+}
+
+function createDefaultKimodoBackpressure() {
+  return createWebGpuRouteBackpressureProfile({
+    requestedBudget: 'visible-wait',
+    effectiveBudget: 'visible-wait',
+    memoryExclusivity: 'shared',
+    warmCacheState: 'unknown',
+  });
+}
+
 export function createKimodoTextToMotionRouteReceipt(input) {
   if (!input || typeof input !== 'object') throw new Error('input must be an object');
   if (!input.input?.artifactId || !input.input?.sha256) {
@@ -75,6 +173,8 @@ export function createKimodoTextToMotionRouteDefinition(input = {}) {
     requiredFeatures: input.requiredFeatures || [],
     requiredStages: routeMetadata.requiredStages,
     timingSource: routeMetadata.timingSource,
+    scheduler: input.scheduler || createDefaultKimodoScheduler(),
+    backpressure: input.backpressure || createDefaultKimodoBackpressure(),
     worker: input.worker || {
       exportName: 'runKimodoTextToMotionRoute',
       textEmbedding: 'external-llama3-8b',

package/src/moge-route.js

@@ -8,6 +8,10 @@ import {
   createRouteReceiptInputArtifact,
   createWebGpuRouteReceiptFromArtifacts,
 } from './route-receipt-helper.js';
+import {
+  createWebGpuRouteBackpressureProfile,
+  createWebGpuRouteSchedulerProfile,
+} from './scheduler-backpressure.js';
 
 export const MOGE_DEPTH_NORMAL_ROUTE_ID = 'moge.depth-normal.webgpu-local.v0';
 const MOGE_MODEL_ID = 'Ruicheng/moge-2-vitl-normal';
@@ -20,6 +24,80 @@ const OUTPUT_ROLES = [
   { key: 'mask', role: 'mask', required: false },
 ];
 
+function createDefaultMogeScheduler() {
+  return createWebGpuRouteSchedulerProfile({
+    requestedScheduler: {
+      mode: 'cooperative',
+      yieldMs: 4,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {
+        backbone: 1,
+        'decoder-heads': 1,
+        'output-readback': 1,
+      },
+    },
+    effectiveScheduler: {
+      mode: 'cooperative',
+      yieldMs: 4,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {
+        backbone: 1,
+        'decoder-heads': 1,
+        'output-readback': 1,
+      },
+      unsupportedFields: [],
+    },
+    verificationState: 'scheduler-unverified',
+    breathability: {
+      spans: [
+        {
+          name: 'backbone-submit',
+          stage: 'backbone',
+          kind: 'gpu-submit-bound',
+          interruptible: false,
+          canYieldBefore: true,
+          canYieldAfter: true,
+          nonInterruptibleReason: 'GPU command buffers cannot be preempted after submit',
+        },
+        {
+          name: 'decoder-heads-submit',
+          stage: 'decoder-heads',
+          kind: 'gpu-submit-bound',
+          interruptible: false,
+          canYieldBefore: true,
+          canYieldAfter: true,
+          nonInterruptibleReason: 'GPU command buffers cannot be preempted after submit',
+        },
+        {
+          name: 'output-readback',
+          stage: 'output-readback',
+          kind: 'readback-bound',
+          interruptible: false,
+          canYieldBefore: true,
+          canYieldAfter: true,
+        },
+      ],
+      checkpoints: REQUIRED_STAGES.map(stage => ({
+        name: `after-${stage}`,
+        kind: stage === 'output-readback' ? 'readback' : 'stage-boundary',
+        afterStage: stage,
+        yieldable: true,
+        waitsForSubmittedWorkDone: true,
+      })),
+      notes: 'MoGE can cooperate between staged submits and readback, not inside a submitted GPU pass.',
+    },
+  });
+}
+
+function createDefaultMogeBackpressure() {
+  return createWebGpuRouteBackpressureProfile({
+    requestedBudget: 'visible-wait',
+    effectiveBudget: 'visible-wait',
+    memoryExclusivity: 'shared',
+    warmCacheState: 'unknown',
+  });
+}
+
 export function createMogeDepthNormalRouteReceipt(input) {
   if (!input || typeof input !== 'object') throw new Error('input must be an object');
   if (!input.input?.artifactId || !input.input?.sha256) {
@@ -77,6 +155,8 @@ export function createMogeDepthNormalRouteDefinition(input = {}) {
     requiredFeatures: input.requiredFeatures || [],
     requiredStages: routeMetadata.requiredStages,
     timingSource: routeMetadata.timingSource,
+    scheduler: input.scheduler || createDefaultMogeScheduler(),
+    backpressure: input.backpressure || createDefaultMogeBackpressure(),
     worker: input.worker || {
       exportName: 'runMogeDepthNormalRoute',
     },

package/src/route-boundary.js

@@ -3,6 +3,10 @@ import {
   assertAuthoritativeRouteReceipt,
   validateRouteReceipt,
 } from './route-receipt.js';
+import {
+  validateWebGpuRouteBackpressureProfile,
+  validateWebGpuRouteSchedulerProfile,
+} from './scheduler-backpressure.js';
 
 export const WEBGPU_ROUTE_DEFINITION_SCHEMA = 'kaminos.webgpu-route-definition.v0';
 export const WEBGPU_ROUTE_REQUEST_SCHEMA = 'kaminos.webgpu-route-request.v0';
@@ -12,6 +16,18 @@ function clone(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
 }
 
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function deepEqual(a, b) {
+  return stableJson(a) === stableJson(b);
+}
+
 function isNonEmptyString(value) {
   return typeof value === 'string' && value.trim().length > 0;
 }
@@ -95,6 +111,49 @@ function optionalRoleNames(roles) {
   return roles.filter(role => role.required === false).map(role => role.role);
 }
 
+function routeTimingStageNames(timings = {}) {
+  const names = new Set();
+  const addStageName = stage => {
+    if (isNonEmptyString(stage)) names.add(stage);
+    if (isNonEmptyString(stage?.name)) names.add(stage.name);
+  };
+
+  if (Array.isArray(timings.stages)) {
+    timings.stages.forEach(addStageName);
+  }
+
+  const profile = timings.profile;
+  if (profile && typeof profile === 'object') {
+    if (Array.isArray(profile.stageNames)) {
+      profile.stageNames.forEach(addStageName);
+    }
+    if (Array.isArray(profile.stages)) {
+      profile.stages.forEach(addStageName);
+    }
+  }
+
+  return names;
+}
+
+function validateRouteTiming(errors, receipt, route) {
+  const timings = receipt?.timings;
+  if (!timings || !route) return;
+
+  if (isNonEmptyString(route.timingSource) && timings.source !== route.timingSource) {
+    errors.push(`receipt.timings.source must be ${route.timingSource}`);
+  }
+
+  const requiredStages = Array.isArray(route.requiredStages) ? route.requiredStages : [];
+  if (requiredStages.length === 0) return;
+
+  const stageNames = routeTimingStageNames(timings);
+  for (const stageName of requiredStages) {
+    if (!stageNames.has(stageName)) {
+      errors.push(`receipt.timings missing required stage ${stageName}`);
+    }
+  }
+}
+
 function validateArtifacts(errors, artifacts, roles, path, { requireHash }) {
   const knownRoles = roleSet(roles);
   const artifactsByRole = new Map();
@@ -147,6 +206,8 @@ export function defineWebGpuRoute(input) {
     requiredFeatures: Array.isArray(input.requiredFeatures) ? [...input.requiredFeatures].map(String).sort() : [],
     requiredStages: Array.isArray(input.requiredStages) ? [...input.requiredStages] : [],
     timingSource: input.timingSource || 'queue-submit-wait',
+    scheduler: clone(input.scheduler || null),
+    backpressure: clone(input.backpressure || null),
     worker: clone(input.worker || null),
   };
 }
@@ -194,6 +255,16 @@ export function validateRouteDefinition(route) {
   }
   if (!isNonEmptyString(route.timingSource)) errors.push('timingSource must be a non-empty string');
 
+  if (route.scheduler != null) {
+    const schedulerResult = validateWebGpuRouteSchedulerProfile(route.scheduler);
+    if (!schedulerResult.ok) errors.push(...schedulerResult.errors.map(error => `scheduler.${error}`));
+  }
+
+  if (route.backpressure != null) {
+    const backpressureResult = validateWebGpuRouteBackpressureProfile(route.backpressure);
+    if (!backpressureResult.ok) errors.push(...backpressureResult.errors.map(error => `backpressure.${error}`));
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -250,6 +321,8 @@ export function createRouteInvocationRequest(route, input) {
     routeConfig: clone(input.routeConfig || {}),
     model: clone(route.model),
     kernel: clone(route.kernel),
+    scheduler: clone(route.scheduler || null),
+    backpressure: clone(route.backpressure || null),
     createdAt: input.createdAt || new Date().toISOString(),
   };
 }
@@ -272,6 +345,30 @@ export function validateRouteInvocationRequest(request, route) {
     validateArtifacts(errors, request.outputs, route.outputRoles, 'outputs', { requireHash: false });
   }
 
+  if (request.scheduler != null) {
+    const schedulerResult = validateWebGpuRouteSchedulerProfile(request.scheduler);
+    if (!schedulerResult.ok) errors.push(...schedulerResult.errors.map(error => `scheduler.${error}`));
+  }
+  if (route?.scheduler != null) {
+    if (request.scheduler == null) {
+      errors.push('scheduler must match route definition');
+    } else if (!deepEqual(request.scheduler, route.scheduler)) {
+      errors.push('scheduler must match route definition');
+    }
+  }
+
+  if (request.backpressure != null) {
+    const backpressureResult = validateWebGpuRouteBackpressureProfile(request.backpressure);
+    if (!backpressureResult.ok) errors.push(...backpressureResult.errors.map(error => `backpressure.${error}`));
+  }
+  if (route?.backpressure != null) {
+    if (request.backpressure == null) {
+      errors.push('backpressure must match route definition');
+    } else if (!deepEqual(request.backpressure, route.backpressure)) {
+      errors.push('backpressure must match route definition');
+    }
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -322,6 +419,7 @@ export function validateRouteWorkerResult(result, route) {
     if (result.receipt.effectiveRouteId !== route.routeId) {
       errors.push('receipt.effectiveRouteId must match route definition');
     }
+    if (routeResult.ok) validateRouteTiming(errors, result.receipt, route);
   }
 
   const backendResult = validateWebGpuBackendIdentity(result.backend);

package/src/scheduler-backpressure.js

@@ -6,6 +6,24 @@ const VERIFICATION_STATES = new Set(['verified', 'scheduler-unverified', 'unsupp
 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']);
+const BREATHABILITY_SPAN_KINDS = new Set([
+  'gpu-submit-bound',
+  'gpu-submit-loop',
+  'readback-bound',
+  'js-yieldable',
+  'cpu-bound',
+  'external-bound',
+  'unknown',
+]);
+const BREATHABILITY_CHECKPOINT_KINDS = new Set([
+  'pre-submit',
+  'post-submit',
+  'stage-boundary',
+  'diffusion-step',
+  'readback',
+  'external-callback',
+  'unknown',
+]);
 
 function clone(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
@@ -53,6 +71,41 @@ function normalizeEffectiveScheduler(input = {}, requestedScheduler) {
   };
 }
 
+function normalizeBreathabilitySpan(input = {}) {
+  return {
+    name: input.name,
+    stage: input.stage || null,
+    kind: input.kind || 'unknown',
+    interruptible: Boolean(input.interruptible),
+    canYieldBefore: Boolean(input.canYieldBefore),
+    canYieldAfter: Boolean(input.canYieldAfter),
+    nonInterruptibleReason: input.nonInterruptibleReason || null,
+    metadata: isPlainObject(input.metadata) ? clone(input.metadata) : {},
+  };
+}
+
+function normalizeBreathabilityCheckpoint(input = {}) {
+  return {
+    name: input.name,
+    kind: input.kind || 'unknown',
+    beforeStage: input.beforeStage || null,
+    afterStage: input.afterStage || null,
+    yieldable: Boolean(input.yieldable),
+    waitsForSubmittedWorkDone: Boolean(input.waitsForSubmittedWorkDone),
+    metadata: isPlainObject(input.metadata) ? clone(input.metadata) : {},
+  };
+}
+
+function normalizeBreathability(input = {}) {
+  return {
+    spans: Array.isArray(input.spans) ? input.spans.map(normalizeBreathabilitySpan) : [],
+    checkpoints: Array.isArray(input.checkpoints)
+      ? input.checkpoints.map(normalizeBreathabilityCheckpoint)
+      : [],
+    notes: input.notes || null,
+  };
+}
+
 function validateSchedulerShape(errors, scheduler, label) {
   if (!isPlainObject(scheduler)) {
     errors.push(`${label} must be an object`);
@@ -79,6 +132,59 @@ function validateSchedulerShape(errors, scheduler, label) {
   }
 }
 
+function validateBreathability(errors, breathability) {
+  if (breathability == null) return;
+  if (!isPlainObject(breathability)) {
+    errors.push('breathability must be an object');
+    return;
+  }
+  if (!Array.isArray(breathability.spans)) {
+    errors.push('breathability.spans must be an array');
+  } else {
+    breathability.spans.forEach((span, index) => {
+      const path = `breathability.spans[${index}]`;
+      if (!isNonEmptyString(span?.name)) errors.push(`${path}.name must be a non-empty string`);
+      if (span?.stage != null && !isNonEmptyString(span.stage)) errors.push(`${path}.stage must be null or a non-empty string`);
+      if (!BREATHABILITY_SPAN_KINDS.has(span?.kind)) errors.push(`${path}.kind has unsupported value`);
+      if (typeof span?.interruptible !== 'boolean') errors.push(`${path}.interruptible must be a boolean`);
+      if (typeof span?.canYieldBefore !== 'boolean') errors.push(`${path}.canYieldBefore must be a boolean`);
+      if (typeof span?.canYieldAfter !== 'boolean') errors.push(`${path}.canYieldAfter must be a boolean`);
+      if (span?.nonInterruptibleReason != null && !isNonEmptyString(span.nonInterruptibleReason)) {
+        errors.push(`${path}.nonInterruptibleReason must be null or a non-empty string`);
+      }
+      if (!isPlainObject(span?.metadata)) errors.push(`${path}.metadata must be an object`);
+      if ((span?.kind === 'gpu-submit-bound' || span?.kind === 'gpu-submit-loop') && span.interruptible) {
+        errors.push(`${path}.${span.kind} cannot be interruptible after GPU submit`);
+      }
+    });
+  }
+
+  if (!Array.isArray(breathability.checkpoints)) {
+    errors.push('breathability.checkpoints must be an array');
+  } else {
+    breathability.checkpoints.forEach((checkpoint, index) => {
+      const path = `breathability.checkpoints[${index}]`;
+      if (!isNonEmptyString(checkpoint?.name)) errors.push(`${path}.name must be a non-empty string`);
+      if (!BREATHABILITY_CHECKPOINT_KINDS.has(checkpoint?.kind)) errors.push(`${path}.kind has unsupported value`);
+      if (checkpoint?.beforeStage != null && !isNonEmptyString(checkpoint.beforeStage)) {
+        errors.push(`${path}.beforeStage must be null or a non-empty string`);
+      }
+      if (checkpoint?.afterStage != null && !isNonEmptyString(checkpoint.afterStage)) {
+        errors.push(`${path}.afterStage must be null or a non-empty string`);
+      }
+      if (typeof checkpoint?.yieldable !== 'boolean') errors.push(`${path}.yieldable must be a boolean`);
+      if (typeof checkpoint?.waitsForSubmittedWorkDone !== 'boolean') {
+        errors.push(`${path}.waitsForSubmittedWorkDone must be a boolean`);
+      }
+      if (!isPlainObject(checkpoint?.metadata)) errors.push(`${path}.metadata must be an object`);
+    });
+  }
+
+  if (breathability.notes != null && !isNonEmptyString(breathability.notes)) {
+    errors.push('breathability.notes must be null or a non-empty string');
+  }
+}
+
 function missingUnsupportedField(effectiveScheduler, field) {
   return !effectiveScheduler.unsupportedFields.includes(field)
     && !effectiveScheduler.unsupportedFields.includes('phaseChunkSize');
@@ -98,6 +204,7 @@ export function createWebGpuRouteSchedulerProfile(input = {}) {
     requestedScheduler,
     effectiveScheduler,
     verificationState,
+    breathability: normalizeBreathability(input.breathability),
   };
 
   const result = validateWebGpuRouteSchedulerProfile(profile);
@@ -115,6 +222,7 @@ export function validateWebGpuRouteSchedulerProfile(profile) {
   }
   validateSchedulerShape(errors, profile.requestedScheduler, 'requestedScheduler');
   validateSchedulerShape(errors, profile.effectiveScheduler, 'effectiveScheduler');
+  validateBreathability(errors, profile.breathability);
 
   if (!Array.isArray(profile.effectiveScheduler?.unsupportedFields)) {
     errors.push('effectiveScheduler.unsupportedFields must be an array');

package/src/sf3d-route.js

@@ -8,6 +8,10 @@ import {
   createRouteReceiptInputArtifact,
   createWebGpuRouteReceiptFromArtifacts,
 } from './route-receipt-helper.js';
+import {
+  createWebGpuRouteBackpressureProfile,
+  createWebGpuRouteSchedulerProfile,
+} from './scheduler-backpressure.js';
 
 export const SF3D_IMAGE_TO_MESH_ROUTE_ID = 'sf3d.image-to-mesh.webgpu-local.v0';
 const SF3D_MODEL_ID = 'stabilityai/stable-fast-3d';
@@ -28,6 +32,55 @@ const OUTPUT_ROLES = [
   { key: 'meshObj', role: 'mesh-obj', required: false },
 ];
 
+function createDefaultSf3dScheduler() {
+  return createWebGpuRouteSchedulerProfile({
+    requestedScheduler: {
+      mode: 'throughput',
+      yieldMs: 0,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {},
+    },
+    effectiveScheduler: {
+      mode: 'throughput',
+      yieldMs: 0,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {},
+      unsupportedFields: [],
+    },
+    verificationState: 'scheduler-unverified',
+    breathability: {
+      spans: REQUIRED_STAGES.map(stage => ({
+        name: `${stage}-phase`,
+        stage,
+        kind: stage === 'glb-export' ? 'cpu-bound' : 'gpu-submit-bound',
+        interruptible: false,
+        canYieldBefore: true,
+        canYieldAfter: true,
+        nonInterruptibleReason: stage === 'glb-export'
+          ? null
+          : 'SF3D browser phases are treated as non-preemptible GPU work until finer receipts prove step boundaries.',
+      })),
+      checkpoints: REQUIRED_STAGES.map(stage => ({
+        name: `after-${stage}`,
+        kind: 'stage-boundary',
+        afterStage: stage,
+        yieldable: true,
+        waitsForSubmittedWorkDone: stage !== 'glb-export',
+      })),
+      notes: 'SF3D remains furnace-class until attention/triplane/marching phases expose finer cooperative boundaries.',
+    },
+  });
+}
+
+function createDefaultSf3dBackpressure() {
+  return createWebGpuRouteBackpressureProfile({
+    requestedBudget: 'visible-wait',
+    effectiveBudget: 'furnace',
+    memoryExclusivity: 'exclusive',
+    warmCacheState: 'unknown',
+  });
+}
+
 export function createSf3dImageToMeshRouteReceipt(input) {
   if (!input || typeof input !== 'object') throw new Error('input must be an object');
   if (!input.input?.artifactId || !input.input?.sha256) {
@@ -86,6 +139,8 @@ export function createSf3dImageToMeshRouteDefinition(input = {}) {
     requiredFeatures: input.requiredFeatures || [],
     requiredStages: routeMetadata.requiredStages,
     timingSource: routeMetadata.timingSource,
+    scheduler: input.scheduler || createDefaultSf3dScheduler(),
+    backpressure: input.backpressure || createDefaultSf3dBackpressure(),
     worker: input.worker || {
       exportName: 'runSf3dImageToMeshRoute',
       meshFormat: 'glb',

package/src/sharp-route.js

@@ -8,6 +8,10 @@ import {
   createRouteReceiptInputArtifact,
   createWebGpuRouteReceiptFromArtifacts,
 } from './route-receipt-helper.js';
+import {
+  createWebGpuRouteBackpressureProfile,
+  createWebGpuRouteSchedulerProfile,
+} from './scheduler-backpressure.js';
 
 export const SHARP_IMAGE_TO_SPLAT_ROUTE_ID = 'sharp.image-to-splat.webgpu-local.v0';
 const SHARP_MODEL_ID = 'apple/ml-sharp';
@@ -20,6 +24,55 @@ const OUTPUT_ROLES = [
   { key: 'autoCropEvidence', role: 'splat-autocrop-evidence', required: false },
 ];
 
+function createDefaultSharpScheduler() {
+  return createWebGpuRouteSchedulerProfile({
+    requestedScheduler: {
+      mode: 'throughput',
+      yieldMs: 0,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {},
+    },
+    effectiveScheduler: {
+      mode: 'throughput',
+      yieldMs: 0,
+      waitForSubmittedWorkDone: true,
+      phaseChunkSize: {},
+      unsupportedFields: [],
+    },
+    verificationState: 'scheduler-unverified',
+    breathability: {
+      spans: REQUIRED_STAGES.map(stage => ({
+        name: `${stage}-phase`,
+        stage,
+        kind: stage === 'output-capture' ? 'readback-bound' : 'gpu-submit-bound',
+        interruptible: false,
+        canYieldBefore: true,
+        canYieldAfter: true,
+        nonInterruptibleReason: stage === 'output-capture'
+          ? null
+          : 'Browser WebGPU cannot preempt a submitted SHARP adapter phase.',
+      })),
+      checkpoints: REQUIRED_STAGES.map(stage => ({
+        name: `after-${stage}`,
+        kind: stage === 'output-capture' ? 'readback' : 'stage-boundary',
+        afterStage: stage,
+        yieldable: true,
+        waitsForSubmittedWorkDone: true,
+      })),
+      notes: 'SHARP is furnace-class until finer adapter receipts prove smaller cooperative boundaries.',
+    },
+  });
+}
+
+function createDefaultSharpBackpressure() {
+  return createWebGpuRouteBackpressureProfile({
+    requestedBudget: 'visible-wait',
+    effectiveBudget: 'furnace',
+    memoryExclusivity: 'exclusive',
+    warmCacheState: 'unknown',
+  });
+}
+
 export function createSharpImageToSplatRouteReceipt(input) {
   if (!input || typeof input !== 'object') throw new Error('input must be an object');
   if (!input.input?.artifactId || !input.input?.sha256) {
@@ -78,6 +131,8 @@ export function createSharpImageToSplatRouteDefinition(input = {}) {
     requiredFeatures: input.requiredFeatures || [],
     requiredStages: routeMetadata.requiredStages,
     timingSource: routeMetadata.timingSource,
+    scheduler: input.scheduler || createDefaultSharpScheduler(),
+    backpressure: input.backpressure || createDefaultSharpBackpressure(),
     worker: input.worker || {
       exportName: 'runSharpImageToSplatRoute',
       adapterReportSchema: 'kaminos.sharp-webgpu-adapter-report.v0',