@holoscript/core 8.0.7 → 8.0.9

package/dist/traits/control-loop.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+var chunkQSYBHQAD_cjs = require('../chunk-QSYBHQAD.cjs');
+require('../chunk-ZHPMP447.cjs');
+
+
+
+Object.defineProperty(exports, "controlLoopHandler", {
+  enumerable: true,
+  get: function () { return chunkQSYBHQAD_cjs.controlLoopHandler; }
+});
+Object.defineProperty(exports, "stepMpc", {
+  enumerable: true,
+  get: function () { return chunkQSYBHQAD_cjs.stepMpc; }
+});
+Object.defineProperty(exports, "stepPid", {
+  enumerable: true,
+  get: function () { return chunkQSYBHQAD_cjs.stepPid; }
+});
+//# sourceMappingURL=control-loop.cjs.map
+//# sourceMappingURL=control-loop.cjs.map

package/dist/traits/control-loop.d.ts

@@ -0,0 +1 @@
+export * from './ControlLoopTrait.js';

package/dist/traits/control-loop.js

@@ -0,0 +1,4 @@
+export { controlLoopHandler, stepMpc, stepPid } from '../chunk-KPGC7SK2.js';
+import '../chunk-W4GABFCR.js';
+//# sourceMappingURL=control-loop.js.map
+//# sourceMappingURL=control-loop.js.map

package/dist/traits/engines/cloth-verlet.d.ts

@@ -0,0 +1,65 @@
+/**
+ * cloth-verlet — pure Verlet+constraint cloth solver.
+ *
+ * Extracted from `packages/runtime/src/traits/PhysicsTraits.ts` ClothTrait
+ * (was lines 120-214) to apply the RULING 2 per-trait wrapper pattern
+ * established by NeuralAnimation: engine-agnostic core math, both core/traits
+ * and runtime/traits get thin wrappers around the same engine.
+ *
+ * No THREE.js / PhysicsWorld dependency. Operates on raw Float32Array
+ * position buffers — caller supplies them, engine modifies in place.
+ *
+ * /stub-audit 2026-04-26 flagged ClothTrait at 15 effective LOC + 17 compiler
+ * refs as a CONFIRMED Pattern B violation. The core/traits/ClothTrait.ts
+ * handler emits cloth_create/cloth_step/cloth_apply_force events that ZERO
+ * runtime listeners ever consume. The actual cloth simulation lives in
+ * runtime/traits/PhysicsTraits.ts (Pattern E manifestation: two unbridged
+ * TraitSystems). This engine extraction is the first step toward bridging
+ * — the math now lives in a place both can call.
+ */
+/**
+ * Mutable simulation state. Caller owns the buffers; engine modifies in place
+ * on every step. Float32Array layout is row-major xyz: positions[i*3..i*3+3].
+ */
+export interface ClothVerletState {
+    /** Current vertex positions (count * 3 floats). Modified in place by stepClothVerlet. */
+    positions: Float32Array;
+    /** Previous-tick vertex positions (count * 3 floats). Modified in place. */
+    prevPositions: Float32Array;
+    /** Vertex indices that are pinned (immovable). */
+    pinned: Set<number>;
+    /** Distance constraints — each entry is [vertexA, vertexB, restLength]. */
+    constraints: Array<[number, number, number]>;
+    /** Wall-clock simulation time (seconds). Caller-managed; engine reads only. */
+    time: number;
+}
+export interface ClothVerletConfig {
+    /** 0–1 — how strongly constraints pull vertices back to rest length. */
+    stiffness: number;
+    /** 0–1 — velocity damping per step (0 = no damping, 1 = full stop). */
+    damping: number;
+    /** Gravity scale (1 = -9.81 m/s² on Y). */
+    gravityScale: number;
+    /** 0–1 — turbulent wind force magnitude. */
+    windResponse: number;
+}
+/**
+ * Build the structural-spring constraint set for a square cloth grid.
+ *
+ * Connects each vertex to its right + bottom neighbor (no diagonals — that's
+ * the shear constraint set, intentionally omitted here for backward parity
+ * with the previous runtime impl). Rest length is computed from the actual
+ * positions in the buffer at construction time, so non-uniform initial
+ * grids are supported.
+ */
+export declare function buildClothConstraints(resolution: number, positions: Float32Array): Array<[number, number, number]>;
+/**
+ * Advance one Verlet integration step + iterative constraint solve.
+ *
+ * Modifies state.positions and state.prevPositions in place.
+ * Caller is responsible for advancing state.time before/after the call —
+ * engine reads it for wind turbulence but does not modify.
+ *
+ * Iteration count for constraint solve = ceil(stiffness * 5).
+ */
+export declare function stepClothVerlet(state: ClothVerletState, config: ClothVerletConfig, delta: number): void;

package/dist/traits/engines/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 var chunkRUVBFAF7_cjs = require('../../chunk-RUVBFAF7.cjs');
-var chunk2GCNOI2U_cjs = require('../../chunk-2GCNOI2U.cjs');
-require('../../chunk-HCCQLAA4.cjs');
+var chunkDN6F4DHH_cjs = require('../../chunk-DN6F4DHH.cjs');
+require('../../chunk-ZHPMP447.cjs');
 
 // src/traits/engines/onnx-motion-matching.ts
 var TRAJ_SAMPLES = 12;
@@ -187,7 +187,7 @@ var OnnxMotionMatchingEngine = class {
       );
     }
     this.descriptor = desc;
-    this.adapter = options.adapter ?? chunk2GCNOI2U_cjs.createPureJsInferenceAdapter(desc.inputDim, desc.outputDim);
+    this.adapter = options.adapter ?? chunkDN6F4DHH_cjs.createPureJsInferenceAdapter(desc.inputDim, desc.outputDim);
   }
   async load() {
     await this.adapter.load(this.descriptor.modelUrl);
@@ -441,67 +441,67 @@ Object.defineProperty(exports, "validateTrainingFrame", {
 });
 Object.defineProperty(exports, "BUNDLED_MODEL_SEED", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.BUNDLED_MODEL_SEED; }
+  get: function () { return chunkDN6F4DHH_cjs.BUNDLED_MODEL_SEED; }
 });
 Object.defineProperty(exports, "HIDDEN_DIM", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.HIDDEN_DIM; }
+  get: function () { return chunkDN6F4DHH_cjs.HIDDEN_DIM; }
 });
 Object.defineProperty(exports, "NoOpInferenceAdapter", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.NoOpInferenceAdapter; }
+  get: function () { return chunkDN6F4DHH_cjs.NoOpInferenceAdapter; }
 });
 Object.defineProperty(exports, "OnnxNodeInferenceAdapter", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.OnnxNodeInferenceAdapter; }
+  get: function () { return chunkDN6F4DHH_cjs.OnnxNodeInferenceAdapter; }
 });
 Object.defineProperty(exports, "PHASE_CONTROL_POINTS", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.PHASE_CONTROL_POINTS; }
+  get: function () { return chunkDN6F4DHH_cjs.PHASE_CONTROL_POINTS; }
 });
 Object.defineProperty(exports, "PfnnNetwork", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.PfnnNetwork; }
+  get: function () { return chunkDN6F4DHH_cjs.PfnnNetwork; }
 });
 Object.defineProperty(exports, "PureJsInferenceAdapter", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.PureJsInferenceAdapter; }
+  get: function () { return chunkDN6F4DHH_cjs.PureJsInferenceAdapter; }
 });
 Object.defineProperty(exports, "add", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.add; }
+  get: function () { return chunkDN6F4DHH_cjs.add; }
 });
 Object.defineProperty(exports, "createBundledPfnn", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.createBundledPfnn; }
+  get: function () { return chunkDN6F4DHH_cjs.createBundledPfnn; }
 });
 Object.defineProperty(exports, "createNoOpInferenceAdapter", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.createNoOpInferenceAdapter; }
+  get: function () { return chunkDN6F4DHH_cjs.createNoOpInferenceAdapter; }
 });
 Object.defineProperty(exports, "createOnnxNodeInferenceAdapter", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.createOnnxNodeInferenceAdapter; }
+  get: function () { return chunkDN6F4DHH_cjs.createOnnxNodeInferenceAdapter; }
 });
 Object.defineProperty(exports, "createPureJsInferenceAdapter", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.createPureJsInferenceAdapter; }
+  get: function () { return chunkDN6F4DHH_cjs.createPureJsInferenceAdapter; }
 });
 Object.defineProperty(exports, "createTensor", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.createTensor; }
+  get: function () { return chunkDN6F4DHH_cjs.createTensor; }
 });
 Object.defineProperty(exports, "eluInPlace", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.eluInPlace; }
+  get: function () { return chunkDN6F4DHH_cjs.eluInPlace; }
 });
 Object.defineProperty(exports, "matmul", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.matmul; }
+  get: function () { return chunkDN6F4DHH_cjs.matmul; }
 });
 Object.defineProperty(exports, "resolveOnnxModelPath", {
   enumerable: true,
-  get: function () { return chunk2GCNOI2U_cjs.resolveOnnxModelPath; }
+  get: function () { return chunkDN6F4DHH_cjs.resolveOnnxModelPath; }
 });
 exports.BUNDLED_MODELS = BUNDLED_MODELS;
 exports.INPUT_DIM = INPUT_DIM;

package/dist/traits/engines/index.d.ts

@@ -1,279 +1,19 @@
 /**
  * @holoscript/core/traits/engines — motion-matching engine surface
  *
- * Hand-crafted declarations mirroring packages/core/src/traits/engines/index.ts
- * (a barrel of: motion-matching, onnx-motion-matching, synthetic-walk-cycle,
- * onnx-adapter, pfnn-network, motion-data-schema, cloth-verlet, noise, tensor-ops).
+ * Lightweight barrel exporting only the engines (no plugin imports, no
+ * compiler dependencies). Lets downstream packages — @holoscript/runtime,
+ * @holoscript/r3f-renderer, third-party engines — import the inference
+ * surface without dragging the full traits barrel through their bundler.
+ *
+ * idea-run-3 BUILD-1 scaffolding (founder ruling 2026-04-26).
  */
-
-// ── motion-matching ───────────────────────────────────────────────────────────
-
-export interface Vec3 {
-  x: number;
-  y: number;
-  z: number;
-}
-
-export interface SkeletonPose {
-  joints: Record<string, { position: [number, number, number]; rotation: [number, number, number, number] }>;
-  timestamp: number;
-}
-
-export interface ContactFeatures {
-  leftFoot: boolean;
-  rightFoot: boolean;
-  [extra: string]: boolean;
-}
-
-export type Gait = 'idle' | 'walk' | 'trot' | 'run' | 'crouch';
-
-export interface MotionInferenceInput {
-  targetVelocity: Vec3;
-  currentPhase: number;
-  delta: number;
-  terrainNormal?: Vec3;
-  energyEfficiency?: number;
-}
-
-export interface MotionInferenceResult {
-  pose: SkeletonPose;
-  phase: number;
-  trajectory: Array<[number, number, number]>;
-  stability: number;
-  contactFeatures: ContactFeatures;
-  gait: Gait;
-  kineticEnergyProxy: number;
-}
-
-export interface MotionMatchingEngine {
-  readonly modelId: string;
-  readonly loaded: boolean;
-  load(): Promise<void>;
-  infer(input: MotionInferenceInput): MotionInferenceResult;
-  dispose(): void;
-}
-
-export type MotionMatchingEngineFactory = (modelId: string) => MotionMatchingEngine;
-
-export declare const TRAJECTORY_HORIZON_FRAMES: 12;
-export declare const TRAJECTORY_FRAME_DT: number;
-
-export declare function magnitude(v: Vec3): number;
-export declare function classifyGait(speed: number, energyEfficiency: number): Gait;
-export declare function projectLinearTrajectory(velocity: Vec3): Array<[number, number, number]>;
-
-export declare class NullMotionMatchingEngine implements MotionMatchingEngine {
-  readonly modelId: string;
-  loaded: boolean;
-  constructor(modelId: string);
-  load(): Promise<void>;
-  infer(input: MotionInferenceInput): MotionInferenceResult;
-  dispose(): void;
-}
-export declare function createNullMotionMatchingEngine(modelId: string): MotionMatchingEngine;
-
-// ── onnx-motion-matching ─────────────────────────────────────────────────────
-
-export declare const INPUT_DIM: number;
-export declare const OUTPUT_DIM: number;
-
-export interface ModelDescriptor {
-  id: string;
-  url: string;
-  inputDim: number;
-  outputDim: number;
-  description?: string;
-}
-
-export declare const BUNDLED_MODELS: Record<string, ModelDescriptor>;
-
-export declare function encodeInputTensor(input: MotionInferenceInput): Float32Tensor;
-
-export declare class OnnxMotionMatchingEngine implements MotionMatchingEngine {
-  readonly modelId: string;
-  loaded: boolean;
-  constructor(modelId: string);
-  load(): Promise<void>;
-  infer(input: MotionInferenceInput): MotionInferenceResult;
-  dispose(): void;
-}
-export declare function createOnnxMotionMatchingEngine(modelId: string): MotionMatchingEngine;
-
-// ── synthetic-walk-cycle ──────────────────────────────────────────────────────
-
-export declare const SYNTHETIC_WALK_JOINTS: readonly string[];
-export declare function buildSyntheticBipedPose(
-  phase: number,
-  speed: number
-): Record<string, { position: [number, number, number]; rotation: [number, number, number, number] }>;
-
-export declare class SyntheticWalkCycleEngine implements MotionMatchingEngine {
-  readonly modelId: string;
-  loaded: boolean;
-  constructor(modelId: string);
-  load(): Promise<void>;
-  infer(input: MotionInferenceInput): MotionInferenceResult;
-  dispose(): void;
-}
-export declare function createSyntheticWalkCycleEngine(modelId?: string): MotionMatchingEngine;
-
-// ── onnx-adapter ─────────────────────────────────────────────────────────────
-
-export type ExecutionProvider = 'webgpu' | 'wasm' | 'cpu' | 'cuda';
-export type TensorShape = readonly number[];
-
-export interface Float32Tensor {
-  data: Float32Array;
-  shape: TensorShape;
-}
-
-export interface InferenceRequest {
-  inputs: Record<string, Float32Tensor>;
-  outputs?: string[];
-}
-
-export interface InferenceResponse {
-  outputs: Record<string, Float32Tensor>;
-  durationMs: number;
-  providerUsed: ExecutionProvider;
-}
-
-export interface InferenceAdapter {
-  readonly name: string;
-  readonly preferredProvider: ExecutionProvider;
-  readonly loaded: boolean;
-  load(modelUrl: string): Promise<void>;
-  run(request: InferenceRequest): Promise<InferenceResponse>;
-  runSync?(request: InferenceRequest): InferenceResponse;
-  dispose(): void;
-}
-
-export declare class NoOpInferenceAdapter implements InferenceAdapter {
-  readonly name: 'NoOpInferenceAdapter';
-  readonly preferredProvider: ExecutionProvider;
-  loaded: boolean;
-  load(modelUrl: string): Promise<void>;
-  runSync(request: InferenceRequest): InferenceResponse;
-  run(request: InferenceRequest): Promise<InferenceResponse>;
-  dispose(): void;
-}
-export declare function createNoOpInferenceAdapter(): InferenceAdapter;
-
-export declare class PureJsInferenceAdapter implements InferenceAdapter {
-  readonly name: 'PureJsInferenceAdapter';
-  readonly preferredProvider: ExecutionProvider;
-  loaded: boolean;
-  constructor(inputDim?: number, outputDim?: number);
-  load(modelUrl: string): Promise<void>;
-  runSync(request: InferenceRequest): InferenceResponse;
-  run(request: InferenceRequest): Promise<InferenceResponse>;
-  dispose(): void;
-}
-export declare function createPureJsInferenceAdapter(inputDim?: number, outputDim?: number): InferenceAdapter;
-
-export declare class OnnxNodeInferenceAdapter implements InferenceAdapter {
-  readonly name: 'OnnxNodeInferenceAdapter';
-  readonly preferredProvider: ExecutionProvider;
-  loaded: boolean;
-  constructor(preferredProvider?: ExecutionProvider);
-  load(modelUrl: string): Promise<void>;
-  run(request: InferenceRequest): Promise<InferenceResponse>;
-  dispose(): void;
-}
-export declare function createOnnxNodeInferenceAdapter(preferredProvider?: ExecutionProvider): InferenceAdapter;
-export declare function resolveOnnxModelPath(modelUrl: string): Promise<string | null>;
-
-// ── pfnn-network ──────────────────────────────────────────────────────────────
-
-export declare const PHASE_CONTROL_POINTS: 4;
-export declare const HIDDEN_DIM: 64;
-
-export declare function eluInPlace(data: Float32Array): void;
-
-export declare class PfnnNetwork {
-  readonly inputDim: number;
-  readonly outputDim: number;
-  constructor(inputDim: number, outputDim: number, seed?: number);
-  forward(input: Float32Array, phase: number): Float32Array;
-}
-
-export declare const BUNDLED_MODEL_SEED: number;
-export declare function createBundledPfnn(inputDim: number, outputDim: number): PfnnNetwork;
-
-// ── motion-data-schema ────────────────────────────────────────────────────────
-
-export declare const MOTION_DATA_SCHEMA_VERSION: 1;
-
-export interface TrainingFrame {
-  timestampMs: number;
-  velocity: Vec3;
-  pose: SkeletonPose;
-  contact: ContactFeatures;
-  phase: number;
-  gait: Gait;
-}
-
-export interface InferenceFrame {
-  timestampMs: number;
-  input: MotionInferenceInput;
-  output: MotionInferenceResult;
-}
-
-export interface MotionCapture {
-  captureId: string;
-  createdAtMs: number;
-  frameRateHz: number;
-  jointNames: string[];
-  frames: TrainingFrame[];
-}
-
-export interface TrainingCorpus {
-  schemaVersion: typeof MOTION_DATA_SCHEMA_VERSION;
-  corpusId: string;
-  createdAtMs: number;
-  motionCaptures: MotionCapture[];
-}
-
-// ── cloth-verlet ──────────────────────────────────────────────────────────────
-
-export interface ClothVerletState {
-  positions: Float32Array;
-  prevPositions: Float32Array;
-  pinned: Set<number>;
-  constraints: Array<[number, number, number]>;
-  time: number;
-}
-
-export interface ClothVerletConfig {
-  stiffness: number;
-  damping: number;
-  gravityScale: number;
-  windResponse: number;
-}
-
-export declare function buildClothConstraints(
-  resolution: number,
-  positions: Float32Array
-): Array<[number, number, number]>;
-
-export declare function stepClothVerlet(
-  state: ClothVerletState,
-  config: ClothVerletConfig,
-  delta: number
-): void;
-
-// ── noise ─────────────────────────────────────────────────────────────────────
-
-export declare function noise(t: number, seed: number): number;
-export declare function smoothNoise(t: number, seed: number): number;
-
-// ── tensor-ops ────────────────────────────────────────────────────────────────
-
-export interface DenseTensor {
-  shape: number[];
-  data: Float32Array;
-}
-
-export declare function createTensor(shape: number[], data?: ArrayLike<number>): DenseTensor;
-export declare function add(a: DenseTensor, b: DenseTensor): DenseTensor;
-export declare function matmul(a: DenseTensor, b: DenseTensor): DenseTensor;
+export * from './motion-matching';
+export * from './onnx-motion-matching';
+export * from './synthetic-walk-cycle';
+export * from './onnx-adapter';
+export * from './pfnn-network';
+export * from './motion-data-schema';
+export * from './cloth-verlet';
+export * from './noise';
+export * from './tensor-ops';

package/dist/traits/engines/index.js

@@ -1,8 +1,8 @@
 import { TRAJECTORY_HORIZON_FRAMES, projectLinearTrajectory, magnitude } from '../../chunk-GVOKJNUN.js';
 export { MOTION_DATA_SCHEMA_VERSION, NullMotionMatchingEngine, SYNTHETIC_WALK_JOINTS, SyntheticWalkCycleEngine, TRAJECTORY_FRAME_DT, TRAJECTORY_HORIZON_FRAMES, buildSyntheticBipedPose, classifyGait, createNullMotionMatchingEngine, createSyntheticWalkCycleEngine, inferenceFrameToTensor, magnitude, projectLinearTrajectory, validateMotionCapture, validateTrainingCorpus, validateTrainingFrame } from '../../chunk-GVOKJNUN.js';
-import { createPureJsInferenceAdapter } from '../../chunk-7E7GCQCK.js';
-export { BUNDLED_MODEL_SEED, HIDDEN_DIM, NoOpInferenceAdapter, OnnxNodeInferenceAdapter, PHASE_CONTROL_POINTS, PfnnNetwork, PureJsInferenceAdapter, add, createBundledPfnn, createNoOpInferenceAdapter, createOnnxNodeInferenceAdapter, createPureJsInferenceAdapter, createTensor, eluInPlace, matmul, resolveOnnxModelPath } from '../../chunk-7E7GCQCK.js';
-import '../../chunk-OL46QLBJ.js';
+import { createPureJsInferenceAdapter } from '../../chunk-OG3MBHM3.js';
+export { BUNDLED_MODEL_SEED, HIDDEN_DIM, NoOpInferenceAdapter, OnnxNodeInferenceAdapter, PHASE_CONTROL_POINTS, PfnnNetwork, PureJsInferenceAdapter, add, createBundledPfnn, createNoOpInferenceAdapter, createOnnxNodeInferenceAdapter, createPureJsInferenceAdapter, createTensor, eluInPlace, matmul, resolveOnnxModelPath } from '../../chunk-OG3MBHM3.js';
+import '../../chunk-W4GABFCR.js';
 
 // src/traits/engines/onnx-motion-matching.ts
 var TRAJ_SAMPLES = 12;

package/dist/traits/engines/motion-data-schema.d.ts

@@ -0,0 +1,119 @@
+/**
+ * MotionMatching training/inference data schema.
+ *
+ * Defines the on-disk + in-memory shape for motion data consumed by the
+ * future MotionMatchingEngine reimplementation (BUILD-1, per /founder
+ * ruling 2026-04-26 — primary-literature reimplement: Holden 2017
+ * Phase-Functioned NN, Starke 2019 NSM, 2020 Local Motion Phases,
+ * 2022 DeepPhase).
+ *
+ * Schema is versioned so future captures remain identifiable as the format
+ * evolves. v1 covers the minimum needed for Phase-Functioned + NSM-style
+ * inference: per-frame joint transforms, root velocity, contact features,
+ * gait label, phase value.
+ *
+ * No backend dependency (pure types + validators). Backends — ONNX, pure-JS
+ * forward pass, WebGPU compute — slot in via the MotionMatchingEngine
+ * interface in motion-matching.ts.
+ */
+import type { Vec3, ContactFeatures, Gait, SkeletonPose } from './motion-matching';
+export declare const MOTION_DATA_SCHEMA_VERSION: 1;
+/**
+ * One frame of training data — paired (input, output) for supervised learning.
+ *
+ * Captured at FPS specified in the parent TrainingCorpus. Source can be:
+ *   - mocap (Vicon, Xsens, etc.)
+ *   - retargeted gameplay (Unity ML Agents reinforcement-learning rollouts)
+ *   - synthetic (procedural walk-cycle generator — see fixtures/)
+ */
+export interface TrainingFrame {
+    /** Sequential frame index within the parent capture session. */
+    frameIndex: number;
+    /** Wall-clock timestamp when the frame was captured (ms epoch). */
+    timestampMs: number;
+    /** Skeletal pose at this frame. Keys are joint names (skeleton-specific). */
+    pose: SkeletonPose;
+    /** Root-bone linear velocity in world-space (m/s). */
+    rootVelocity: Vec3;
+    /** Root-bone angular velocity around vertical axis (rad/s). */
+    rootAngularVelocity: number;
+    /** Phase value in [0, 1) — the Phase-Functioned cyclic position. */
+    phase: number;
+    /** Terrain surface normal at the root position (optional — defaults to up). */
+    terrainNormal?: Vec3;
+    /** Foot-contact bitmask — which feet are grounded at this frame. */
+    contactFeatures: ContactFeatures;
+    /** Discrete gait label — for classifier head + ablation studies. */
+    gait: Gait;
+    /** Energy-cost annotation for this frame (joules — optional, for energy-aware training). */
+    energyCost?: number;
+}
+/**
+ * One frame of inference input — what the engine receives at runtime.
+ * Strict subset of TrainingFrame — only the input fields, no labels.
+ */
+export interface InferenceFrame {
+    pose: SkeletonPose;
+    rootVelocity: Vec3;
+    rootAngularVelocity: number;
+    phase: number;
+    terrainNormal?: Vec3;
+}
+/**
+ * A captured motion sequence. Multiple frames sharing skeleton + sampling rate.
+ */
+export interface MotionCapture {
+    /** Schema version — used to gate ingest compatibility. */
+    schemaVersion: typeof MOTION_DATA_SCHEMA_VERSION;
+    /** Capture identifier — e.g. "mocap_walk_run_001" or "synth_walk_cycle_v1". */
+    captureId: string;
+    /** Skeleton identifier — e.g. "biped_humanoid_v2". */
+    skeletonId: string;
+    /** Source modality. */
+    source: 'mocap' | 'retargeted' | 'synthetic' | 'gameplay';
+    /** Capture frame rate in Hz (typically 30 or 60). */
+    fps: number;
+    /** License + provenance — required for any capture used in training. */
+    license: {
+        /** SPDX identifier or 'proprietary' — must be commercial-use-OK for HoloScript. */
+        spdx: string;
+        /** Original creator / capture owner. */
+        attribution: string;
+        /** URL or reference to the capture source. */
+        sourceUrl?: string;
+    };
+    /** Sequential frames in temporal order. */
+    frames: TrainingFrame[];
+}
+/**
+ * A training corpus = many MotionCaptures grouped for one training run.
+ */
+export interface TrainingCorpus {
+    schemaVersion: typeof MOTION_DATA_SCHEMA_VERSION;
+    /** Corpus identifier — e.g. "biped_v1_train_2026-Q3". */
+    corpusId: string;
+    /** Target skeleton — all captures must share this. */
+    skeletonId: string;
+    /** Train/val/test split — frames assigned by captureId, not frame-by-frame. */
+    splits: {
+        train: string[];
+        val: string[];
+        test: string[];
+    };
+    captures: MotionCapture[];
+}
+export declare function validateTrainingFrame(frame: TrainingFrame): void;
+export declare function validateMotionCapture(capture: MotionCapture): void;
+export declare function validateTrainingCorpus(corpus: TrainingCorpus): void;
+/**
+ * Convert an InferenceFrame into the flat tensor input shape that backends
+ * (ONNX, WebGPU compute, pure-JS forward pass) all consume identically.
+ *
+ * Layout: [phase, rootVelX, rootVelY, rootVelZ, rootAngVel,
+ *          terrainNX, terrainNY, terrainNZ,
+ *          jointPos[0..N*3-1], jointRot[0..N*4-1]]
+ *
+ * Joint order is determined by the caller-provided sortedJointNames so the
+ * tensor layout is deterministic across calls (matches training-time order).
+ */
+export declare function inferenceFrameToTensor(frame: InferenceFrame, sortedJointNames: string[]): Float32Array;