@openfluke/welvet 0.3.0 → 0.75.0

package/dist/tests/coverage.ts

@@ -0,0 +1,113 @@
+/**
+ * Loom TypeScript Wrapper 345-Item Parity CLI Auditor
+ * --------------------------------------------------
+ * Verifies 100% functional parity between @openfluke/welvet and loom-core.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import welvet from '../src/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function runCLIParityAudit() {
+    console.log("\x1b[36m%s\x1b[0m", "=== Loom TypeScript Wrapper Parity Audit (CLI) ===");
+    
+    try {
+        // 1. Initialize Engine
+        await welvet.init();
+        const internalParity = welvet.getInternalParity ? welvet.getInternalParity() : [];
+        console.log(`\n[INIT] Engine Loaded. ${internalParity.length} internal symbols acquired.`);
+
+        // 2. Load expected API
+        const blueprintPath = path.resolve(__dirname, '../../wasm/expected_api.json');
+        const expectedApi = JSON.parse(fs.readFileSync(blueprintPath, 'utf8'));
+
+        // 3. Functional Proof
+        let functionalProof = false;
+        try {
+            const net = welvet.createNetwork({
+                depth: 1, rows: 1, cols: 1, layers_per_cell: 1,
+                layers: [{ type: "Dense", input_height: 4, output_height: 4, activation: "ReLU" }]
+            });
+            const input = new Float32Array(4).fill(0.5);
+            const output = net.sequentialForward(input);
+            if (output && output.length === 4) functionalProof = true;
+            net.free();
+            console.log("\x1b[32m%s\x1b[0m", "[PASS] Functional Layer Pass Verified.");
+        } catch (e) {
+            console.error("\x1b[31m%s\x1b[0m", "[FAIL] Functional Proof Error: " + (e as Error).message);
+        }
+
+        // 4. Scan
+        const results: any[] = [];
+        let totalItems = 0;
+        let passedItems = 0;
+
+        for (const [category, items] of Object.entries<any>(expectedApi)) {
+            console.log(`\n\x1b[33m[${category}]\x1b[0m`);
+            for (const item of items) {
+                totalItems++;
+                let status = "MISSING";
+                let details = "";
+
+                // Logic sync with check_ts.js
+                const camelName = item.name.charAt(0).toLowerCase() + item.name.slice(1);
+                
+                if (welvet[item.name as keyof typeof welvet] || 
+                    welvet[('create' + item.name) as keyof typeof welvet] || 
+                    welvet[('load' + item.name) as keyof typeof welvet]) {
+                    status = "PASS";
+                    details = "TS Export";
+                } else if (welvet.DType && (welvet.DType as any)[item.name.toUpperCase()]) {
+                    status = "PASS";
+                    details = "TS Constant";
+                } else if (welvet.LayerType && (welvet.LayerType as any)[item.name.toUpperCase()]) {
+                    status = "PASS";
+                    details = "TS LayerType";
+                } else {
+                    // Method check on Dummy
+                    const net = welvet.createNetwork({depth:1, rows:1, cols:1, layers_per_cell:1, layers:[]});
+                    if (net && (typeof (net as any)[item.name] === 'function' || typeof (net as any)[camelName] === 'function')) {
+                        status = "PASS";
+                        details = "Instance Method";
+                    } else if (internalParity.includes(item.name)) {
+                        status = "PASS";
+                        details = "Engine Internal (Indirect)";
+                    }
+                    if (net) net.free();
+                }
+
+                if (status === "PASS") {
+                    passedItems++;
+                    process.stdout.write(`\x1b[32m.\x1b[0m`);
+                } else {
+                    console.log(`\n  \x1b[31m[MISSING] ${item.name}\x1b[0m`);
+                }
+            }
+        }
+
+        const coverage = (passedItems / totalItems) * 100;
+        console.log(`\n\nFinal Report:`);
+        console.log(`---------------------------------`);
+        console.log(`Items Scanned : ${totalItems}`);
+        console.log(`Items Passed  : ${passedItems}`);
+        console.log(`Coverage      : ${coverage.toFixed(2)}%`);
+        console.log(`---------------------------------`);
+
+        if (coverage === 100) {
+            console.log("\x1b[32m%s\x1b[0m", "FULL PARITY ACHIEVED.");
+            process.exit(0);
+        } else {
+            console.log("\x1b[31m%s\x1b[0m", "INCOMPLETE PARITY.");
+            process.exit(1);
+        }
+
+    } catch (e) {
+        console.error("Critical Failure:", e);
+        process.exit(1);
+    }
+}
+
+runCLIParityAudit();

package/dist/types.d.ts

@@ -1,201 +1,358 @@
 /**
- * Type definitions for LOOM WASM API
+ * welvet — Type Definitions for the M-POLY-VTD AI Engine
+ *
+ * Wraps the Loom v0.75.0 WASM module which supports 21 numerical types,
+ * systolic grid propagation, target propagation, and WebGPU acceleration.
  */
-export interface LayerConfig {
-    type: string;
-    input_size?: number;
-    output_size?: number;
-    hidden_size?: number;
-    activation?: string;
-    combine_mode?: string;
-    grid_output_rows?: number;
-    grid_output_cols?: number;
-    grid_output_layers?: number;
-    grid_positions?: GridPosition[];
+export declare const DType: {
+    readonly FLOAT64: 0;
+    readonly FLOAT32: 1;
+    readonly FLOAT16: 2;
+    readonly BFLOAT16: 3;
+    readonly FP8_E4M3: 4;
+    readonly FP8_E5M2: 5;
+    readonly INT64: 6;
+    readonly INT32: 7;
+    readonly INT16: 8;
+    readonly INT8: 9;
+    readonly UINT64: 10;
+    readonly UINT32: 11;
+    readonly UINT16: 12;
+    readonly UINT8: 13;
+    readonly INT4: 14;
+    readonly UINT4: 15;
+    readonly FP4: 16;
+    readonly INT2: 17;
+    readonly UINT2: 18;
+    readonly TERNARY: 19;
+    readonly BINARY: 20;
+};
+export type DTypeValue = typeof DType[keyof typeof DType];
+export declare const LayerType: {
+    readonly DENSE: 0;
+    readonly RMS_NORM: 1;
+    readonly LAYER_NORM: 2;
+    readonly MHA: 3;
+    readonly SOFTMAX: 4;
+    readonly SWIGLU: 5;
+    readonly EMBEDDING: 6;
+    readonly RESIDUAL: 7;
+    readonly KMEANS: 8;
+    readonly RNN: 9;
+    readonly LSTM: 10;
+    readonly CNN1: 11;
+    readonly CNN2: 12;
+    readonly CNN3: 13;
+    readonly CONV_TRANSPOSED_1D: 14;
+    readonly CONV_TRANSPOSED_2D: 15;
+    readonly CONV_TRANSPOSED_3D: 16;
+};
+export type LayerTypeValue = typeof LayerType[keyof typeof LayerType];
+export declare const Activation: {
+    readonly RELU: 0;
+    readonly SILU: 1;
+    readonly GELU: 2;
+    readonly TANH: 3;
+    readonly SIGMOID: 4;
+    readonly LINEAR: 5;
+};
+export type ActivationValue = typeof Activation[keyof typeof Activation];
+export interface LayerSpec {
+    /** Layer type (use LayerType constants) */
+    type: string | number;
+    /** Numerical precision (use DType constants, default: FLOAT32) */
+    dtype?: number;
+    /** Activation function (use Activation constants) */
+    activation?: string | number;
     input_height?: number;
-    output_height?: number;
     input_width?: number;
+    input_depth?: number;
+    output_height?: number;
+    output_width?: number;
+    output_depth?: number;
     input_channels?: number;
-    output_channels?: number;
+    filters?: number;
     kernel_size?: number;
     stride?: number;
     padding?: number;
-    filters?: number;
-    d_model?: number;
     num_heads?: number;
+    num_kv_heads?: number;
+    d_model?: number;
     seq_length?: number;
-    norm_size?: number;
     vocab_size?: number;
     embedding_dim?: number;
-    epsilon?: number;
-    softmax_variant?: string;
-    temperature?: number;
-    residual?: boolean;
-    filter_gate?: LayerConfig;
-    filter_temperature?: number;
-    branches?: LayerConfig[];
+    z?: number;
+    y?: number;
+    x?: number;
+    l?: number;
+    tile_size?: number;
 }
 export interface NetworkConfig {
-    batch_size: number;
-    grid_rows?: number;
-    grid_cols?: number;
+    /** Grid depth (number of z-planes). Default: 1 */
+    depth?: number;
+    /** Grid rows (y-dimension). Default: 1 */
+    rows?: number;
+    /** Grid columns (x-dimension). Default: 1 */
+    cols?: number;
+    /** Layers per cell. Default: number of layers */
     layers_per_cell?: number;
-    layers: LayerConfig[];
-}
-export interface GridPosition {
-    branch_index: number;
-    target_row: number;
-    target_col: number;
-    target_layer: number;
+    /** Layer definitions (flat list, laid out z→y→x→l) */
+    layers: LayerSpec[];
 }
 export interface TrainingBatch {
-    Input: number[];
-    Target: number[];
-}
-export interface TrainingConfig {
-    Epochs: number;
-    LearningRate: number;
-    LossType?: string;
-    Verbose?: boolean;
-    UseGPU?: boolean;
-    PrintEveryBatch?: number;
-    GradientClip?: number;
+    input: number[] | Float32Array;
+    target: number[] | Float32Array;
+    /** Optional batch shape for input, e.g. [batchSize, features]. Defaults to [1, length]. */
+    inputShape?: number[];
+    /** Optional batch shape for target, e.g. [batchSize, outputs]. Defaults to [1, length]. */
+    targetShape?: number[];
 }
 export interface TrainingResult {
     final_loss: number;
     duration_ms: number;
     epochs_completed: number;
+    loss_history?: number[];
 }
-/**
- * Network interface with all available methods
- * All methods take a JSON string of parameters (JSON array)
- * and return a JSON string of results (JSON array)
- */
-export interface Network {
-    ForwardCPU(inputsJSON: string): string;
-    ForwardGPU(inputsJSON: string): string;
-    BackwardCPU(gradientsJSON: string): string;
-    BackwardGPU(gradientsJSON: string): string;
-    UpdateWeights(paramsJSON: string): string;
-    Train(paramsJSON: string): string;
-    ZeroGradients(paramsJSON: string): string;
-    ResetGradients(paramsJSON: string): string;
-    SaveModelToString(paramsJSON: string): string;
-    SerializeModel(paramsJSON: string): string;
-    GetWeights(paramsJSON: string): string;
-    SetWeights(paramsJSON: string): string;
-    GetBiases(paramsJSON: string): string;
-    SetBiases(paramsJSON: string): string;
-    GetLayer(paramsJSON: string): string;
-    SetLayer(paramsJSON: string): string;
-    GetActivation(paramsJSON: string): string;
-    SetActivation(paramsJSON: string): string;
-    GetLayerType(paramsJSON: string): string;
-    GetLayerSizes(paramsJSON: string): string;
-    GetBatchSize(paramsJSON: string): string;
-    SetBatchSize(paramsJSON: string): string;
-    GetGridDimensions(paramsJSON: string): string;
-    GetLayersPerCell(paramsJSON: string): string;
-    TotalLayers(paramsJSON: string): string;
-    GetNetworkInfo(paramsJSON: string): string;
-    GetTotalParameters(paramsJSON: string): string;
-    GetMemoryUsage(paramsJSON: string): string;
-    ValidateArchitecture(paramsJSON: string): string;
-    GetLastOutput(paramsJSON: string): string;
-    GetLastGradients(paramsJSON: string): string;
-    Activations(paramsJSON: string): string;
-    KernelGradients(paramsJSON: string): string;
-    BiasGradients(paramsJSON: string): string;
-    Clone(paramsJSON: string): string;
-    InitializeWeights(paramsJSON: string): string;
-    InitGPU(paramsJSON: string): string;
-    ReleaseGPU(paramsJSON: string): string;
-    GetMethods(paramsJSON: string): string;
-    GetMethodsJSON(paramsJSON: string): string;
-    ListMethods(paramsJSON: string): string;
-    HasMethod(paramsJSON: string): string;
-    GetMethodSignature(paramsJSON: string): string;
-    ApplyGradients(paramsJSON: string): string;
-    ApplyGradientsAdamW(paramsJSON: string): string;
-    ApplyGradientsRMSprop(paramsJSON: string): string;
-    ApplyGradientsSGDMomentum(paramsJSON: string): string;
-    createStepState(inputSize: number): StepState;
-    createTweenState(useChainRule?: boolean): TweenState;
-}
-/**
- * StepState interface for stepping execution
- */
-export interface StepState {
+export interface SystolicState {
+    /**
+     * Inject input into the first layer of the grid.
+     * @param data Float32Array or number[] of input values
+     */
     setInput(data: Float32Array | number[]): void;
-    stepForward(): number;
-    getOutput(): Float32Array;
-    stepBackward(gradients: Float32Array | number[]): Float32Array;
+    /**
+     * Advance the systolic grid by one clock cycle.
+     * @param captureHistory Whether to store history for backpropagation
+     * @returns Duration of the step in milliseconds
+     */
+    step(captureHistory?: boolean): number;
+    /**
+     * Read the output of a layer (default: last active layer).
+     * @param layerIdx Optional layer index (0-based)
+     */
+    getOutput(layerIdx?: number): Float32Array;
+    /**
+     * Backpropagate gradients through the stored history.
+     * @param gradients Output gradient (Float32Array or number[])
+     * @returns Input gradient as Float32Array
+     */
+    backward(gradients: Float32Array | number[]): Float32Array;
+    /**
+     * Apply target propagation (gradient-free alternative to backward).
+     * @param target Global target tensor
+     * @param lr Learning rate
+     */
+    applyTargetProp(target: Float32Array | number[], lr: number): void;
+    /** Total number of systolic steps executed. */
+    stepCount(): number;
+    /** Release resources (no-op in WASM, included for API parity). */
+    free(): void;
 }
-/**
- * TweenState interface for neural tweening execution
- */
-export interface TweenState {
-    /**
-     * Perform a tween training step
-     * @param input - Input data
-     * @param targetClass - Target class index
-     * @param outputSize - Size of output layer
-     * @param learningRate - Learning rate for this step
-     * @returns Loss value
-     */
-    TweenStep(input: Float32Array | number[], targetClass: number, outputSize: number, learningRate: number): number;
-    /** Enable/disable chain rule mode */
-    setChainRule(enabled: boolean): void;
-    /** Get current chain rule setting */
-    getChainRule(): boolean;
-    /** Get number of tween steps performed */
-    getTweenSteps(): number;
+export interface TargetPropState {
+    /**
+     * Forward pass through all layers, storing local targets.
+     * @param input Input data
+     * @returns Output as Float32Array
+     */
+    forward(input: Float32Array | number[]): Float32Array;
+    /**
+     * Backward pass using target propagation (gap-based, no chain rule).
+     * @param target Desired output
+     */
+    backward(target: Float32Array | number[]): void;
+    /**
+     * Backward pass using the chain rule (standard backprop via TP state).
+     * @param target Desired output
+     */
+    backwardChainRule(target: Float32Array | number[]): void;
+    /**
+     * Apply accumulated gap gradients to all layer weights.
+     * @param lr Learning rate
+     */
+    applyGaps(lr?: number): void;
+    /** Release resources (no-op in WASM). */
+    free(): void;
 }
-/**
- * Global WASM functions exposed by main.go
- * Only createLoomNetwork is exposed - use network.SaveModelToString() for saving
- */
-declare global {
-    function createLoomNetwork(jsonConfig: string): Network;
-    function loadLoomNetwork(jsonString: string, modelID: string): Network;
-    function createAdaptationTracker(windowMs: number, totalMs: number): AdaptationTracker;
-    function createNetworkForGraft(jsonConfig: string): number;
-    function graftNetworks(idsJSON: string, combineMode: string): string;
-    function kmeansCluster(dataJSON: string, k: number, iter: number): string;
-    function computeCorrelation(matrixAJSON: string, matrixBJSON: string): string;
-    function findComplementaryMatches(modelsJSON: string, minCoverage: number): string;
+export interface Transformer {
+    /** Internal handle ID. */
+    _id: number;
+    /**
+     * Run a full prefill/inference pass.
+     * @param tokens Array of token IDs
+     * @returns Predicted logit tensor as Float32Array
+     */
+    forwardFull(tokens: number[] | Uint32Array): Float32Array;
+    /**
+     * Run inference using WebGPU acceleration.
+     * @param tokens Array of token IDs
+     * @returns Predicted logit tensor as Float32Array
+     */
+    forwardTokenIDsWGPU(tokens: number[] | Uint32Array): Promise<Float32Array>;
+    /**
+     * High-level prefill on GPU.
+     * @param tokens Array of token IDs
+     */
+    forwardWGPU(tokens: number[] | Uint32Array): Promise<void>;
+    /**
+     * Convert tokens to a tensor representation using the embedding layer.
+     * @param tokens Array of token IDs
+     */
+    tokensToTensor(tokens: number[] | Uint32Array): Float32Array;
+    /** Release resources. */
+    free(): void;
 }
-export interface EnsembleMatch {
-    ModelA: string;
-    ModelB: string;
-    Coverage: number;
-    Overlap: number;
-    WeightedAcc?: number;
+export interface NEATPopulation {
+    /** Internal handle ID. */
+    _id: number;
+    /** Number of networks in the population. */
+    size: number;
+    /** Get a network wrapper by index. */
+    getNetwork(index: number): Network;
+    /** Run one generation given pre-computed fitnesses (length must equal size). */
+    evolveWithFitnesses(fitnesses: number[]): void;
+    /** Return the best-performing network wrapper. */
+    best(): Network;
+    /** Return the best fitness score. */
+    bestFitness(): number;
+    /** Human-readable generation summary. */
+    summary(generation: number): string;
+    /** Release resources. */
+    free(): void;
 }
-export interface GraftResult {
-    success: boolean;
-    type: string;
-    num_branches: number;
-    combine_mode: string;
-    error?: string;
+export interface Network {
+    /**
+     * Full sequential forward pass through the network.
+     * @param input Float32Array or number[] of inputs
+     * @returns Output as Float32Array
+     */
+    sequentialForward(input: Float32Array | number[]): Float32Array;
+    /**
+     * Returns a JSON string with network shape info.
+     * {depth, rows, cols, layers_per_cell, total_layers, use_gpu, default_dtype}
+     */
+    getInfo(): string;
+    /**
+     * Extract the network's DNA fingerprint as a JSON string.
+     * Use compareLoomDNA() to compare two fingerprints.
+     */
+    extractDNA(): string;
+    /**
+     * Extract the network's full blueprint as a JSON string.
+     * @param modelID Optional model identifier
+     */
+    extractNetworkBlueprint(modelID?: string): string;
+    /** Alias for extractNetworkBlueprint */
+    extractBlueprint(modelID?: string): string;
+    /** Total number of layers in the network. */
+    getLayerCount(): number;
+    /**
+     * Get the specification of a single layer.
+     * @param layerIdx 0-based layer index
+     * @returns JSON string with layer spec
+     */
+    getLayerSpec(layerIdx: number): string;
+    /**
+     * Switch a layer's numerical type at runtime (zero-cost when cached).
+     * @param layerIdx 0-based layer index
+     * @param dtype DType constant
+     * @returns JSON status/error
+     */
+    morphLayer(layerIdx: number, dtype: DTypeValue): string;
+    /**
+     * Initialize WebGPU for this network.
+     * @returns Promise that resolves with status JSON
+     */
+    initGPU(): Promise<string>;
+    /**
+     * Upload all layer weights to GPU buffers.
+     * @returns Promise that resolves with status JSON
+     */
+    syncToGPU(): Promise<string>;
+    /** Download weights back to CPU and disable GPU mode. */
+    syncToCPU(): void;
+    /**
+     * High-level supervised training loop.
+     * @param batchesJSON JSON string of TrainingBatch[]
+     * @param epochs Number of epochs
+     * @param lr Learning rate
+     * @returns JSON string with TrainingResult
+     */
+    train(batchesJSON: string, epochs: number, lr: number): string;
+    /**
+     * Create a SystolicState for the stepping API.
+     */
+    createSystolicState(): SystolicState;
+    /**
+     * Create a TargetPropState for gradient-free learning.
+     * @param useChainRule If true, uses chain-rule backprop instead of gap-based TP
+     */
+    createTargetPropState(useChainRule?: boolean): TargetPropState;
+    /**
+     * Genetic crossover with another network.
+     * @param otherID The `_id` of the other parent network
+     * @param cfgJSON JSON string from defaultSpliceConfig()
+     */
+    spliceDNA(otherID: number, cfgJSON: string): Network;
+    /**
+     * NEAT-style structural mutation.
+     * @param cfgJSON JSON string from defaultNEATConfig()
+     */
+    neatMutate(cfgJSON: string): Network;
+    /** Internal handle ID — required for spliceDNA and population operations. */
+    _id: number;
+    /** Release resources (no-op in WASM, included for API parity). */
+    free(): void;
+    /**
+     * Low-level polymorphic forward pass.
+     * @param input Input tensor data
+     */
+    forwardPolymorphic(input: Float32Array | number[]): Float32Array;
+    /**
+     * Get an individual layer wrapper.
+     * @param index 0-based layer index
+     */
+    getLayer(index: number): Layer;
 }
-export interface KMeansResult {
-    centroids: number[][];
-    assignment: number[];
-    silhouette_score: number;
+export interface Layer {
+    /** Internal handle ID. */
+    _id: number;
+    /**
+     * Dispatch a forward pass through this layer only.
+     * @param input Input tensor
+     */
+    dispatch(input: Float32Array | number[]): Float32Array;
+    /** Sync weights to GPU. */
+    syncToGPU(): Promise<void>;
+    /** Release resources. */
+    free(): void;
 }
-export interface CorrelationResult {
-    pearson: number[][];
-    spearman: number[][];
+export interface DNACompareResult {
+    similarity: number;
+    layer_count_match: boolean;
+    depth_match: boolean;
+    architecture_match: boolean;
+    [key: string]: unknown;
 }
-/**
- * AdaptationTracker interface for tracking accuracy during task changes
- */
-export interface AdaptationTracker {
-    setModelInfo(modelName: string, modeName: string): void;
-    scheduleTaskChange(atOffsetMs: number, taskID: number, taskName: string): void;
-    start(initialTask: string, initialTaskID: number): void;
-    recordOutput(isCorrect: boolean): void;
-    getCurrentTask(): number;
-    finalize(): string;
+declare global {
+    /** Build a VolumetricNetwork from a JSON config string. */
+    function createLoomNetwork(jsonConfig: string): Network;
+    /** Load a network from a SafeTensors file path. */
+    function loadLoomNetwork(path: string): Network;
+    /** Initialize WebGPU (returns a Promise). */
+    function setupWebGPU(): Promise<string>;
+    /** Compare two DNA JSON strings for architectural similarity. */
+    function compareLoomDNA(dnaA: string, dnaB: string): string;
+    /** Get the default TargetPropConfig. */
+    function getDefaultTargetPropConfig(): string;
+    /** Get the default SpliceConfig JSON string. */
+    function defaultSpliceConfig(): string;
+    /** Get the default NEATConfig JSON string for a given model dimension. */
+    function defaultNEATConfig(dModel: number): string;
+    /** Create a NEAT population from a seed network. */
+    function createLoomNEATPopulation(seedID: number, size: number, cfgJSON: string): NEATPopulation;
+    /** Create a Transformer from a network and weights. */
+    function createLoomTransformer(networkID: number, embeddings: Float32Array | number[], lmHead: Float32Array | number[], finalNorm: Float32Array | number[]): Transformer;
+    /** Get the internal parity symbol list from Go. */
+    function getLoomInternalParity(): string[];
+    /** Build a network from a JSON string. */
+    function BuildNetworkFromJSON(json: string): Network;
 }