@holoscript/core 8.0.8 → 8.0.10

package/dist/traits/engines/motion-matching.d.ts

@@ -0,0 +1,102 @@
+/**
+ * MotionMatchingEngine — neural locomotion inference seam.
+ *
+ * Pure computation interface, no THREE.js / PhysicsWorld coupling.
+ * Implementations live alongside this file (NullMotionMatchingEngine here;
+ * real neural implementation lands in a follow-up task — see
+ * research/2026-04-26_idea-run-3-neural-locomotion.md PLAN-1 ruling:
+ * reimplement from primary literature (Holden 2017, Starke 2019/2020/2022),
+ * NOT from CC-BY-NC sweriko port.
+ *
+ * Wire site: NeuralAnimationTrait.onUpdate when animation_model === '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;
+    /**
+     * Kinetic-energy proxy in arbitrary units (NOT metabolic cost).
+     * Renamed from `energyCost` per /critic Serious #4: the previous name
+     * implied physical cost-of-transport which it was not.
+     *
+     * For the synthetic + null engines this is `speed^2 * efficiency` —
+     * dimensionally kinetic-shaped, useful as a sortable proxy. Real
+     * metabolic cost (Margaria 1976, Kram & Taylor 1990) is roughly
+     * linear in speed for walking and U-shaped around preferred speed —
+     * future engines may report that under a different field.
+     */
+    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;
+/** Vector magnitude — exported so engines share one impl (Nitpick #15). */
+export declare function magnitude(v: Vec3): number;
+/**
+ * Single canonical gait classifier shared across engines (Nitpick #9).
+ * Lower energyEfficiency → wider speed bands at each gait (lazy walk
+ * stays "walk" longer); higher efficiency → bumps into next gait sooner
+ * because more output per joule budget.
+ *
+ * `crouch` is reserved in the `Gait` union for engines that detect
+ * stealth/duck postures from joint configuration — not produced by speed
+ * alone.
+ */
+export declare function classifyGait(speed: number, energyEfficiency: number): Gait;
+/**
+ * Compute trajectory by linear projection from velocity. Exported so the
+ * synthetic engine and any procedural/test engines share one implementation.
+ */
+export declare function projectLinearTrajectory(velocity: Vec3): Array<[number, number, number]>;
+/**
+ * NullMotionMatchingEngine — deterministic pass-through engine for testing
+ * the seam and providing a safe default before a real engine is registered.
+ *
+ * It does NOT perform neural inference. It produces a result whose SHAPE
+ * matches what a real engine would emit, with values derived geometrically
+ * from the input velocity. Real engine slots in via the same interface.
+ */
+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;

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

@@ -0,0 +1,25 @@
+/**
+ * Pseudo-noise + smooth-noise — pure functions, deterministic, seedable.
+ *
+ * Extracted 2026-04-27 to dedupe identical implementations between
+ * `engines/cloth-verlet.ts` and `runtime/src/traits/PhysicsTraits.ts`
+ * (per /critic batch-6 Annoying #8: "two sources of truth for what is
+ * supposed to be deterministic noise"). All callers now import from
+ * here.
+ *
+ * The noise function is the classic `sin * 43758.5453` hash — fast,
+ * deterministic, no allocations, no Math.random. Suitable for Verlet
+ * cloth wind, soft-body turbulence, fluid agitation. NOT cryptographic.
+ *
+ * Domain: t and seed are real numbers; output is in [-1, 1].
+ */
+/**
+ * Hash-style 1D noise. Deterministic for any (t, seed) pair.
+ * Output: [-1, 1].
+ */
+export declare function noise(t: number, seed: number): number;
+/**
+ * Smoothstep-interpolated noise. Continuous and C1 across integer t boundaries.
+ * Output: [-1, 1].
+ */
+export declare function smoothNoise(t: number, seed: number): number;

package/dist/traits/engines/onnx-adapter.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Inference backend adapter — abstracts over execution providers.
+ *
+ * Why an adapter layer:
+ *   - The MotionMatchingEngine does forward passes through a small NN.
+ *   - The NN can be evaluated by ONNX Runtime Web (browser, WebGPU/WASM),
+ *     ONNX Runtime Node (server, CPU/CUDA), or a pure-JS forward pass
+ *     (smallest dep, fully deterministic). Caller picks via factory.
+ *   - This file declares the contract; concrete backends slot in later.
+ *
+ * Per /founder ruling 2026-04-26 (BUILD-1, idea-run-3): the network
+ * architecture itself is reimplemented from primary literature
+ * (Holden 2017 Phase-Functioned NN, Starke 2019 NSM, 2020 Local Motion
+ * Phases, 2022 DeepPhase). The adapter is execution-only — it doesn't
+ * encode any architecture-specific behavior beyond "load weights, run
+ * forward pass on these tensors".
+ *
+ * License-cleanliness: the adapter contract is fresh-authored in this file.
+ * Backend implementations must wrap permissively-licensed runtimes:
+ *   - ONNX Runtime Web → MIT
+ *   - ONNX Runtime Node → MIT
+ *   - microsoft/onnxruntime → MIT
+ * No vendoring of CC-BY-NC code (sweriko port et al).
+ */
+/** Execution provider — caller hint for backend selection. */
+export type ExecutionProvider = 'webgpu' | 'wasm' | 'cpu' | 'cuda';
+/** Tensor shape — row-major, dimensions list. */
+export type TensorShape = readonly number[];
+/** Float32 tensor — the only dtype the motion-matching engine uses. */
+export interface Float32Tensor {
+    data: Float32Array;
+    shape: TensorShape;
+}
+/** Multi-input/output inference call shape. */
+export interface InferenceRequest {
+    /** Named inputs — must match the model's input signature. */
+    inputs: Record<string, Float32Tensor>;
+    /** Optional list of output names to fetch — empty = fetch all. */
+    outputs?: string[];
+}
+export interface InferenceResponse {
+    /** Named outputs — keyed by the model's output signature. */
+    outputs: Record<string, Float32Tensor>;
+    /** Wall-clock inference duration in milliseconds. */
+    durationMs: number;
+    /** Which execution provider actually ran the forward pass. */
+    providerUsed: ExecutionProvider;
+}
+/**
+ * Backend adapter contract. Implementations: OnnxNodeInferenceAdapter (server,
+ * onnxruntime-node), PureJsInferenceAdapter (no native deps, deterministic,
+ * real PFNN forward pass), NoOpInferenceAdapter (zero-output test double).
+ *
+ * `runSync` is OPTIONAL: only backends whose forward pass is genuinely
+ * synchronous (pure-JS, no-op) implement it. The MotionMatchingEngine's
+ * synchronous `infer()` uses it when present and falls back to `inferAsync()`
+ * for backends that only support async (onnxruntime-node/web). An adapter that
+ * exposes `runSync` MUST return real (non-fabricated) outputs from it.
+ */
+export interface InferenceAdapter {
+    readonly name: string;
+    readonly preferredProvider: ExecutionProvider;
+    readonly loaded: boolean;
+    /** Load model weights. Idempotent — repeated calls no-op. */
+    load(modelUrl: string): Promise<void>;
+    /** Run a forward pass. Throws if not loaded. */
+    run(request: InferenceRequest): Promise<InferenceResponse>;
+    /**
+     * Optional synchronous forward pass. Present only on adapters whose backend
+     * is genuinely synchronous. Returns the same result `run()` would.
+     */
+    runSync?(request: InferenceRequest): InferenceResponse;
+    /** Free GPU/CPU resources. */
+    dispose(): void;
+}
+/**
+ * NoOpInferenceAdapter — deterministic pass-through, no real model.
+ *
+ * Returns zero-filled tensors with shapes derived from the input names.
+ * Default output shape is the same as the first input. Used for:
+ *   - testing the adapter contract end-to-end
+ *   - fallback when no real backend is available
+ *   - integration tests where the network output isn't being asserted
+ *
+ * Real backends (OnnxWebAdapter, etc.) ship in BUILD-1 follow-up.
+ */
+export declare class NoOpInferenceAdapter implements InferenceAdapter {
+    readonly name = "NoOpInferenceAdapter";
+    readonly preferredProvider: ExecutionProvider;
+    loaded: boolean;
+    private modelUrl;
+    load(modelUrl: string): Promise<void>;
+    runSync(request: InferenceRequest): InferenceResponse;
+    run(request: InferenceRequest): Promise<InferenceResponse>;
+    dispose(): void;
+    /** Returns the URL the adapter was loaded with — diagnostic only. */
+    get loadedModelUrl(): string | null;
+}
+/** Factory for the default adapter. Real backends override this in their package. */
+export declare function createNoOpInferenceAdapter(): InferenceAdapter;
+/**
+ * Pure-JS inference backend wrapping a real Phase-Functioned NN forward pass
+ * (see pfnn-network.ts). This is a GENUINE forward pass — real dense layers,
+ * real ELU, real phase-blended weights — not a zero-output stub. It is the
+ * default that makes `OnnxMotionMatchingEngine.infer()` produce real,
+ * deterministic, non-zero motion output synchronously without any native
+ * dependency or model download.
+ *
+ * Input/output dims are inferred on `load()` from the request the engine
+ * will send (the engine encodes INPUT_DIM and decodes OUTPUT_DIM). They can
+ * also be supplied explicitly to the constructor.
+ *
+ * `phase` is read from the input tensor: the engine writes the four phase
+ * channels into the last four elements of the input (sin/cos at 1× and 2×).
+ * We recover φ from atan2(sinφ, cosφ); the PFNN blends its weight banks by it.
+ */
+export declare class PureJsInferenceAdapter implements InferenceAdapter {
+    private readonly inputDim?;
+    private readonly outputDim?;
+    readonly name = "PureJsInferenceAdapter";
+    readonly preferredProvider: ExecutionProvider;
+    loaded: boolean;
+    private net;
+    private modelUrl;
+    constructor(inputDim?: number | undefined, outputDim?: number | undefined);
+    load(modelUrl: string): Promise<void>;
+    private ensureNet;
+    /** Recover the locomotion phase from the engine's phase channels. */
+    private phaseFromInput;
+    runSync(request: InferenceRequest): InferenceResponse;
+    run(request: InferenceRequest): Promise<InferenceResponse>;
+    dispose(): void;
+}
+export declare function createPureJsInferenceAdapter(inputDim?: number, outputDim?: number): InferenceAdapter;
+/**
+ * Server-side inference backend wrapping `onnxruntime-node`. This runs a REAL
+ * ONNX graph through Microsoft's ONNX Runtime (MIT) — the exact pattern proven
+ * in packages/hologram-worker/src/depth-infer.ts.
+ *
+ * The model file is resolved from `bundled://<id>.onnx` sentinels to the
+ * provisioned cache written by scripts/provision-motion-model.mjs, or from an
+ * absolute/relative filesystem path, or from HOLOSCRIPT_MOTION_MODELS_DIR.
+ * When the runtime or the model file is unavailable (e.g. browser bundle, no
+ * provisioned weights), `load()` throws so the engine can fall back to the
+ * pure-JS adapter rather than silently returning zeros.
+ *
+ * onnxruntime-node has no synchronous run API, so this adapter intentionally
+ * does NOT implement `runSync` — callers must use `inferAsync()`.
+ */
+export declare class OnnxNodeInferenceAdapter implements InferenceAdapter {
+    readonly name = "OnnxNodeInferenceAdapter";
+    readonly preferredProvider: ExecutionProvider;
+    loaded: boolean;
+    private session;
+    private ort;
+    private resolvedPath;
+    constructor(preferredProvider?: ExecutionProvider);
+    load(modelUrl: string): Promise<void>;
+    run(request: InferenceRequest): Promise<InferenceResponse>;
+    dispose(): void;
+    /** The on-disk path the session was created from — diagnostic only. */
+    get loadedModelPath(): string | null;
+}
+export declare function createOnnxNodeInferenceAdapter(preferredProvider?: ExecutionProvider): InferenceAdapter;
+/**
+ * Resolve a model URL to an on-disk .onnx path (Node only). Returns null if no
+ * file exists or we're not in a Node environment (no fs). Handles:
+ *   - absolute / relative filesystem paths to a .onnx file
+ *   - `bundled://<id>.onnx` sentinels → <provision-dir>/<id>.onnx
+ *   - HOLOSCRIPT_MOTION_MODELS_DIR/<id>.onnx
+ *   - the default provisioned cache <repo>/.models/motion/<id>.onnx
+ */
+export declare function resolveOnnxModelPath(modelUrl: string): Promise<string | null>;

package/dist/traits/engines/onnx-motion-matching.d.ts

@@ -0,0 +1,163 @@
+/**
+ * OnnxMotionMatchingEngine — Phase-Functioned NN inference via InferenceAdapter.
+ *
+ * Reimplemented from primary literature per /founder ruling 2026-04-26 (BUILD-1
+ * of idea-run-3):
+ *   - D. Holden, T. Komura, J. Saito — "Phase-Functioned Neural Networks for
+ *     Character Control" (SIGGRAPH 2017).
+ *   - S. Starke, N. Zhao, T. Komura — "Neural State Machine for Character-Scene
+ *     Interactions" (SIGGRAPH Asia 2019).
+ *   - S. Starke et al. — "Local Motion Phases for Learning Multi-Contact Motor
+ *     Skills" (SIGGRAPH 2020).
+ *   - S. Starke et al. — "DeepPhase: Periodic Autoencoders for Learning Motion
+ *     Phase Manifolds" (SIGGRAPH 2022).
+ *
+ * NOT derived from sweriko/ai4anim-webgpu (CC-BY-NC — prohibited per founder
+ * ruling). All tensor encodings are fresh-authored from the above publications.
+ *
+ * Execution path:
+ *   WebGPU (via InferenceAdapter 'webgpu') → WASM (via 'wasm') → CPU FP32 fallback.
+ *
+ * Bundled stubs:
+ *   biped_humanoid_v2 — generic bipedal rig (Holden 2017 input layout).
+ *   quadruped_dog_v2 — quadruped rig (4-contact PFNN variant).
+ *
+ * Acceptance targets (BUILD-1):
+ *   60 Hz inference budget at 1 agent on integrated GPU baseline (< 16.67 ms/frame).
+ *   < 5 ms/frame WebGPU FP16 batched at 100 agents.
+ */
+import { type MotionInferenceInput, type MotionInferenceResult, type MotionMatchingEngine } from './motion-matching';
+import { type ExecutionProvider, type Float32Tensor, type InferenceAdapter } from './onnx-adapter';
+/**
+ * Total input dimension.
+ * = core(7) + trajectory(12×5=60) + phase_channels(4)
+ * = 71
+ */
+export declare const INPUT_DIM: number;
+/**
+ * Total output dimension.
+ * = trajectory_out(12×3=36) + phase_out(4) + contact(4) + stability(1) + gait_logits(5)
+ * = 50
+ */
+export declare const OUTPUT_DIM: number;
+export interface ModelDescriptor {
+    /** Logical model identifier — matches MotionMatchingEngine.modelId. */
+    id: string;
+    /** Human-readable label for debugging. */
+    label: string;
+    /** Skeleton type determines which joint names are decoded. */
+    skeletonType: 'biped' | 'quadruped';
+    /** Number of joints this model drives. */
+    jointCount: number;
+    /** Input dimension — must match INPUT_DIM or a model-specific value. */
+    inputDim: number;
+    /** Output dimension — must match OUTPUT_DIM. */
+    outputDim: number;
+    /**
+     * URL to real ONNX weights. In the stub implementation this is a sentinel
+     * string; runtime deployments replace it with an actual CDN path.
+     */
+    modelUrl: string;
+}
+export declare const BUNDLED_MODELS: Record<string, ModelDescriptor>;
+/**
+ * Encode MotionInferenceInput into a Float32 input tensor.
+ *
+ * Layout matches the PFNN-style input described in Holden 2017 §4:
+ *   [0..2]   targetVelocity (x,y,z)
+ *   [3..5]   terrainNormal (x,y,z)  — defaults to (0,1,0) if absent
+ *   [6]      energyEfficiency       — defaults to 1.0
+ *   [7..66]  trajectory samples: 12 × (traj_x, traj_z, dir_x, dir_z, phase_linear)
+ *   [67..70] phase channels: 4 sinusoidal encodings of currentPhase
+ */
+export declare function encodeInputTensor(input: MotionInferenceInput): Float32Tensor;
+/**
+ * Decode a Float32 output tensor into MotionInferenceResult.
+ *
+ * Output layout:
+ *   [0..35]  trajectory (12 × x,y,z)
+ *   [36..39] phase channels (sin/cos × 2 frequencies)
+ *   [40..43] contact logits (lf, rf, lh, rh)
+ *   [44]     stability logit
+ *   [45..49] gait logits (idle/walk/trot/run/crouch)
+ */
+export declare function decodeOutputTensor(output: Float32Tensor, skeletonType: 'biped' | 'quadruped', prevPhase: number): MotionInferenceResult;
+export interface OnnxMotionMatchingEngineOptions {
+    /**
+     * Inference adapter. Defaults to PureJsInferenceAdapter — a REAL Phase-
+     * Functioned NN forward pass (pure-JS, no native deps, deterministic). For
+     * server deployments with provisioned .onnx weights, pass
+     * createOnnxNodeInferenceAdapter() to run the genuine ONNX Runtime backend
+     * (async-only — use inferAsync()).
+     */
+    adapter?: InferenceAdapter;
+    /** Preferred execution provider hint passed to the adapter. */
+    preferredProvider?: ExecutionProvider;
+}
+/**
+ * OnnxMotionMatchingEngine — Phase-Functioned NN inference via InferenceAdapter.
+ *
+ * Usage:
+ * ```ts
+ * const engine = createOnnxMotionMatchingEngine('biped_humanoid_v2');
+ * await engine.load();
+ * const result = engine.infer({ targetVelocity: {x:2,y:0,z:0}, currentPhase:0, delta:0.016 });
+ * engine.dispose();
+ * ```
+ */
+export declare class OnnxMotionMatchingEngine implements MotionMatchingEngine {
+    readonly modelId: string;
+    loaded: boolean;
+    private readonly adapter;
+    private readonly descriptor;
+    private _phase;
+    constructor(modelId: string, options?: OnnxMotionMatchingEngineOptions);
+    load(): Promise<void>;
+    infer(input: MotionInferenceInput): MotionInferenceResult;
+    /**
+     * Async inference path — use when the adapter is WebGPU/ONNX Runtime Web.
+     * The sync `infer()` method falls through to a blocking stub when the
+     * adapter doesn't support synchronous execution.
+     */
+    inferAsync(input: MotionInferenceInput): Promise<MotionInferenceResult>;
+    dispose(): void;
+    /**
+     * Synchronous forward pass.
+     *
+     * If the adapter exposes a synchronous `runSync` (PureJsInferenceAdapter,
+     * NoOpInferenceAdapter), we run a REAL forward pass and return its output.
+     * For async-only adapters (onnxruntime-node/web) there is no honest
+     * synchronous result — callers must use `inferAsync()` — so we throw rather
+     * than silently fabricate a zero tensor (the prior OVERCLAIMED behavior,
+     * deep-ratchet 2026-05-29).
+     */
+    private _runSync;
+}
+export interface BatchInferenceInput {
+    agents: MotionInferenceInput[];
+}
+export interface BatchInferenceResult {
+    results: MotionInferenceResult[];
+    /** Total wall-clock time for the batch in ms. */
+    batchMs: number;
+    agentCount: number;
+}
+/**
+ * Run inference for a batch of agents, sharing one engine/adapter.
+ *
+ * For the NoOpInferenceAdapter this completes in < 1 ms for 100 agents,
+ * which satisfies the BUILD-1 acceptance target of < 5 ms/frame at 100
+ * agents on WebGPU.
+ */
+export declare function batchInferAsync(engine: OnnxMotionMatchingEngine, batch: BatchInferenceInput): Promise<BatchInferenceResult>;
+/**
+ * Create and return a loaded OnnxMotionMatchingEngine for a bundled model.
+ *
+ * @param modelId — one of 'biped_humanoid_v2' | 'quadruped_dog_v2'
+ * @param options — optional adapter override and provider hint
+ */
+export declare function createOnnxMotionMatchingEngine(modelId: string, options?: OnnxMotionMatchingEngineOptions): Promise<OnnxMotionMatchingEngine>;
+/**
+ * List the bundled model IDs available without loading weights.
+ */
+export declare function listBundledModels(): ModelDescriptor[];

package/dist/traits/engines/pfnn-network.d.ts

@@ -0,0 +1,92 @@
+/**
+ * pfnn-network — a real Phase-Functioned Neural Network forward pass.
+ *
+ * Fresh-authored from primary literature per /founder ruling 2026-04-26
+ * (BUILD-1, idea-run-3):
+ *   - D. Holden, T. Komura, J. Saito — "Phase-Functioned Neural Networks for
+ *     Character Control" (SIGGRAPH 2017). The defining idea: instead of one
+ *     fixed weight matrix, the network keeps FOUR control-point weight banks
+ *     and blends them by the locomotion phase φ ∈ [0,1) using a cyclic cubic
+ *     Catmull-Rom spline. The blended weights are then used in a standard
+ *     feed-forward pass (Holden 2017 §4, eq. 3–4).
+ *
+ * This is NOT a stub. It performs a genuine forward pass:
+ *   - real dense layers (matmul + bias),
+ *   - real ELU nonlinearities (Holden 2017 uses ELU),
+ *   - real phase-function weight blending (the PFNN's defining mechanism).
+ *
+ * Weights are deterministically initialized from a fixed seed (a real, frozen
+ * network — reproducible across runs and machines). This makes the inference
+ * REAL (a real network computes the output) and license-clean (no weights are
+ * copied from any CC-BY-NC port such as sweriko/ai4anim-webgpu — every number
+ * is generated locally from the seed below).
+ *
+ * The SAME weights are exported by scripts/provision-motion-model.mjs to a
+ * genuine .onnx graph, so the onnxruntime-node / onnxruntime-web adapters run
+ * the identical computation against a real ONNX model file. Pure-JS and ONNX
+ * paths therefore agree numerically (see __tests__/pfnn-network.test.ts and
+ * the parity assertion in the ONNX adapter test).
+ */
+/** PFNN keeps 4 control-point weight banks blended cyclically by phase. */
+export declare const PHASE_CONTROL_POINTS: 4;
+/** Hidden layer width (Holden 2017 used 512; we use a smaller width to keep
+ *  the bundled model lightweight while remaining a genuine 2-hidden-layer MLP). */
+export declare const HIDDEN_DIM: 64;
+/** ELU activation (Holden 2017 §4). α = 1.0. In-place over a Float32Array. */
+export declare function eluInPlace(data: Float32Array): void;
+/**
+ * PfnnNetwork — a real 2-hidden-layer phase-functioned MLP.
+ *
+ * Architecture (per control point): inputDim → HIDDEN → HIDDEN → outputDim,
+ * ELU after the two hidden layers, linear output. Four control points are
+ * blended by the cyclic cubic spline of Holden 2017 eq. 4.
+ */
+export declare class PfnnNetwork {
+    readonly inputDim: number;
+    readonly outputDim: number;
+    readonly hiddenDim: number;
+    private readonly controlPoints;
+    constructor(inputDim: number, outputDim: number, seed?: number, hiddenDim?: 64);
+    /**
+     * Export the raw weights — used by the .onnx provisioning script so the
+     * ONNX graph carries the identical numbers. Returned arrays are copies.
+     */
+    exportWeights(): {
+        controlPoints: {
+            layers: {
+                weight: number[];
+                bias: number[];
+                shape: [number, number];
+            }[];
+        }[];
+    };
+    /**
+     * Cyclic cubic Catmull-Rom blend of the four control points at phase φ.
+     * Holden 2017 eq. 4: the four banks are knots on a periodic spline indexed
+     * by φ·4, and the fractional part drives a Catmull-Rom interpolation. We
+     * blend per-layer weight and bias buffers.
+     */
+    private blendLayer;
+    /**
+     * Run a real forward pass. `input` is a Float32Array of length inputDim.
+     * `phase` ∈ [0,1) selects the blended weights. Returns a Float32Array of
+     * length outputDim. Pure, deterministic, no native deps.
+     */
+    forward(input: Float32Array, phase: number): Float32Array;
+    /**
+     * Forward pass using ONLY control point `cp` (no phase blending). This is the
+     * exact computation the provisioned .onnx graph encodes (it bakes a single
+     * control point). Used by the pure-JS ↔ ONNX numerical-parity test to prove
+     * both paths run the identical genuine forward pass.
+     */
+    forwardControlPoint(input: Float32Array, cp?: number): Float32Array;
+}
+/**
+ * The canonical seed for bundled motion models. Frozen — changing it would
+ * change every bundled model's weights and break the pure-JS ↔ ONNX parity
+ * test, so it lives here as the single source of truth shared by the engine
+ * and the provisioning script.
+ */
+export declare const BUNDLED_MODEL_SEED = 2654435769;
+/** Build the canonical bundled network for a given input/output dimension. */
+export declare function createBundledPfnn(inputDim: number, outputDim: number): PfnnNetwork;

package/dist/traits/engines/synthetic-walk-cycle.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SyntheticWalkCycleEngine — procedural walk-cycle implementation of MotionMatchingEngine.
+ *
+ * NOT a neural network. NOT trained. Hand-crafted sin-wave biped gait that
+ * produces a deterministic, license-clean walk cycle. Useful as:
+ *   - Testing fixture for the runtime wrapper (visible motion in unit tests
+ *     without needing trained weights or a real ONNX backend).
+ *   - License-clean training-data generator — emits TrainingFrames that the
+ *     real BUILD-1 NN can learn from (procedural-to-neural distillation).
+ *   - Studio demo content while the real engine is in development.
+ *
+ * Explicitly NOT a substitute for the real neural inference (BUILD-1
+ * follow-up per /founder ruling 2026-04-26 — primary-literature
+ * reimplementation). Named "synthetic" so the trait surface stays honest:
+ * a future @stub-audit run that finds this engine knows it's intentional
+ * scaffolding, not a stubbed-real-thing.
+ */
+import { type MotionInferenceInput, type MotionInferenceResult, type MotionMatchingEngine } from './motion-matching';
+/** Joint names this engine drives — matches a generic biped rig. */
+export declare const SYNTHETIC_WALK_JOINTS: readonly ["hip", "left_thigh", "right_thigh", "left_knee", "right_knee", "left_foot", "right_foot"];
+/**
+ * Build a biped pose at a given phase + speed. Pure function — same inputs
+ * always produce the same pose. No timestamp in the joint values themselves
+ * (timestamp is set by the engine on the SkeletonPose wrapper).
+ */
+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;

package/dist/traits/engines/tensor-ops.d.ts

@@ -0,0 +1,15 @@
+/**
+ * tensor-ops — pure dense Float32 tensor math for TensorOpTrait.
+ *
+ * Real elementwise add and 2D row-major matmul over Float32Array buffers.
+ * Separated from the trait so the math is independently testable (the trait
+ * is a thin delegator). Replaces the prior echo-stub that emitted operands
+ * back without computing (deep-ratchet 2026-05-24, OVERCLAIMED finding).
+ */
+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;