@wlearn/lightgbm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- LightGBM v4.6.0 WASM port
+- Binary classification, multiclass, regression
+- Save/load via WLRN bundle format
+- Extra trees mode support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 StatSim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @wlearn/lightgbm
+
+LightGBM WASM port for wlearn. Gradient boosting for classification and regression,
+running in browser and Node.js via WebAssembly.
+
+## Installation
+
+```bash
+npm install @wlearn/lightgbm
+```
+
+## Usage
+
+```javascript
+import { LGBModel } from '@wlearn/lightgbm'
+
+// Create and train
+const model = await LGBModel.create({
+  objective: 'binary',
+  learning_rate: 0.05,
+  num_leaves: 31,
+  numRound: 100
+})
+model.fit(X, y)
+
+// Predict
+const predictions = model.predict(X_test)
+const probabilities = model.predictProba(X_test)
+const accuracy = model.score(X_test, y_test)
+
+// Save and load
+const bundle = model.save()
+const loaded = await LGBModel.load(bundle)
+
+// Clean up
+model.dispose()
+```
+
+## Supported objectives
+
+- `binary` -- binary classification
+- `multiclass` -- multiclass classification (softmax)
+- `multiclassova` -- multiclass one-vs-all
+- `cross_entropy` -- cross-entropy classification
+- `regression` -- regression (default)
+
+## License
+
+MIT (upstream LightGBM is MIT-licensed)

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@wlearn/lightgbm",
+  "version": "0.1.0",
+  "description": "LightGBM WASM port for wlearn",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "wasm/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules test/test.js",
+    "build": "bash scripts/build-wasm.sh",
+    "verify": "bash scripts/verify-exports.sh"
+  },
+  "dependencies": {
+    "@wlearn/types": "0.1.0",
+    "@wlearn/core": "0.1.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wlearn-org/lightgbm-wasm.git"
+  }
+}

package/src/booster.js

@@ -0,0 +1,229 @@
+import { getWasm } from './wasm.js'
+
+// FinalizationRegistry safety net
+const registry = typeof FinalizationRegistry !== 'undefined'
+  ? new FinalizationRegistry(({ ptr, freeFn }) => {
+    if (ptr[0]) {
+      console.warn('@wlearn/lightgbm: Booster was not disposed -- calling free() automatically.')
+      freeFn(ptr[0])
+    }
+  })
+  : null
+
+function withCString(wasm, str, fn) {
+  const bytes = new TextEncoder().encode(str + '\0')
+  const ptr = wasm._malloc(bytes.length)
+  wasm.HEAPU8.set(bytes, ptr)
+  try {
+    return fn(ptr)
+  } finally {
+    wasm._free(ptr)
+  }
+}
+
+function getLastError(wasm) {
+  return wasm.UTF8ToString(wasm._wl_lgb_get_last_error())
+}
+
+// Internal sentinel for loadModel path
+const LOAD_SENTINEL = Symbol('load')
+
+export class Booster {
+  #handle = null
+  #freed = false
+  #ptrRef = null
+
+  constructor(trainDataHandle, paramsStr) {
+    // Internal path: loadModel passes sentinel + handle
+    if (trainDataHandle === LOAD_SENTINEL) {
+      this.#handle = paramsStr // second arg holds the handle
+      this.#freed = false
+      this.#ptrRef = [this.#handle]
+      if (registry) {
+        registry.register(this, {
+          ptr: this.#ptrRef,
+          freeFn: (h) => getWasm()._wl_lgb_booster_free(h)
+        }, this)
+      }
+      return
+    }
+
+    const wasm = getWasm()
+    const outPtr = wasm._malloc(4)
+
+    const ret = withCString(wasm, paramsStr, (paramsPtr) =>
+      wasm._wl_lgb_booster_create(trainDataHandle, paramsPtr, outPtr)
+    )
+
+    if (ret !== 0) {
+      wasm._free(outPtr)
+      throw new Error(`Booster creation failed: ${getLastError(wasm)}`)
+    }
+
+    this.#handle = wasm.getValue(outPtr, 'i32')
+    wasm._free(outPtr)
+
+    // Leak detection
+    this.#ptrRef = [this.#handle]
+    if (registry) {
+      registry.register(this, {
+        ptr: this.#ptrRef,
+        freeFn: (h) => getWasm()._wl_lgb_booster_free(h)
+      }, this)
+    }
+  }
+
+  get handle() {
+    if (this.#freed) throw new Error('Booster already disposed')
+    return this.#handle
+  }
+
+  update() {
+    const wasm = getWasm()
+    const finishedPtr = wasm._malloc(4)
+    wasm.setValue(finishedPtr, 0, 'i32')
+
+    const ret = wasm._wl_lgb_booster_update(this.handle, finishedPtr)
+    const finished = wasm.getValue(finishedPtr, 'i32')
+    wasm._free(finishedPtr)
+
+    if (ret !== 0) {
+      throw new Error(`Booster update failed: ${getLastError(wasm)}`)
+    }
+    return finished !== 0
+  }
+
+  getNumClasses() {
+    const wasm = getWasm()
+    const outPtr = wasm._malloc(4)
+
+    const ret = wasm._wl_lgb_booster_get_num_classes(this.handle, outPtr)
+    const nc = wasm.getValue(outPtr, 'i32')
+    wasm._free(outPtr)
+
+    if (ret !== 0) {
+      throw new Error(`Booster getNumClasses failed: ${getLastError(wasm)}`)
+    }
+    return nc
+  }
+
+  predict(data, nrow, ncol, { predictType = 0, numIteration = 0 } = {}) {
+    const wasm = getWasm()
+
+    // Copy float32 data to WASM heap
+    const dataPtr = wasm._malloc(data.length * 4)
+    wasm.HEAPF32.set(data, dataPtr / 4)
+
+    // Output length
+    const outLenPtr = wasm._malloc(4)
+
+    // Allocate output buffer (estimate: nrow * numClasses)
+    // For safety, allocate max(nrow * max_classes, nrow * 100)
+    const maxOut = nrow * 100
+    const outResultPtr = wasm._malloc(maxOut * 8)
+
+    const ret = withCString(wasm, '', (paramPtr) =>
+      wasm._wl_lgb_booster_predict(
+        this.handle, dataPtr, nrow, ncol,
+        predictType, numIteration, paramPtr,
+        outLenPtr, outResultPtr
+      )
+    )
+
+    wasm._free(dataPtr)
+
+    if (ret !== 0) {
+      wasm._free(outLenPtr)
+      wasm._free(outResultPtr)
+      throw new Error(`Booster predict failed: ${getLastError(wasm)}`)
+    }
+
+    const outLen = wasm.getValue(outLenPtr, 'i32')
+    wasm._free(outLenPtr)
+
+    // Copy results
+    const result = new Float64Array(outLen)
+    for (let i = 0; i < outLen; i++) {
+      result[i] = wasm.HEAPF64[outResultPtr / 8 + i]
+    }
+    wasm._free(outResultPtr)
+
+    return result
+  }
+
+  saveModel() {
+    const wasm = getWasm()
+
+    // First pass: get required buffer length
+    const outLenPtr = wasm._malloc(4)
+    let ret = wasm._wl_lgb_booster_save_model(this.handle, 0, outLenPtr, 0)
+
+    if (ret !== 0) {
+      wasm._free(outLenPtr)
+      throw new Error(`Booster saveModel (size query) failed: ${getLastError(wasm)}`)
+    }
+
+    const bufLen = wasm.getValue(outLenPtr, 'i32')
+
+    // Second pass: get actual model string
+    const bufPtr = wasm._malloc(bufLen)
+    ret = wasm._wl_lgb_booster_save_model(this.handle, bufLen, outLenPtr, bufPtr)
+
+    if (ret !== 0) {
+      wasm._free(outLenPtr)
+      wasm._free(bufPtr)
+      throw new Error(`Booster saveModel failed: ${getLastError(wasm)}`)
+    }
+
+    const actualLen = wasm.getValue(outLenPtr, 'i32')
+    wasm._free(outLenPtr)
+
+    // Copy to JS Uint8Array (text model, null-terminated)
+    const result = new Uint8Array(actualLen - 1) // exclude null terminator
+    result.set(wasm.HEAPU8.subarray(bufPtr, bufPtr + actualLen - 1))
+    wasm._free(bufPtr)
+
+    return result
+  }
+
+  static loadModel(modelBytes) {
+    const wasm = getWasm()
+
+    // Copy model string to WASM heap (add null terminator)
+    const buf = modelBytes instanceof Uint8Array ? modelBytes : new Uint8Array(modelBytes)
+    const bufPtr = wasm._malloc(buf.length + 1)
+    wasm.HEAPU8.set(buf, bufPtr)
+    wasm.HEAPU8[bufPtr + buf.length] = 0 // null terminator
+
+    const outIterPtr = wasm._malloc(4)
+    const outPtr = wasm._malloc(4)
+
+    const ret = wasm._wl_lgb_booster_load_model(bufPtr, outIterPtr, outPtr)
+
+    wasm._free(bufPtr)
+    wasm._free(outIterPtr)
+
+    if (ret !== 0) {
+      wasm._free(outPtr)
+      throw new Error(`Booster loadModel failed: ${getLastError(wasm)}`)
+    }
+
+    const handle = wasm.getValue(outPtr, 'i32')
+    wasm._free(outPtr)
+
+    return new Booster(LOAD_SENTINEL, handle)
+  }
+
+  dispose() {
+    if (this.#freed) return
+    this.#freed = true
+
+    const wasm = getWasm()
+    wasm._wl_lgb_booster_free(this.#handle)
+
+    if (this.#ptrRef) this.#ptrRef[0] = null
+    if (registry) registry.unregister(this)
+
+    this.#handle = null
+  }
+}

package/src/dataset.js

@@ -0,0 +1,103 @@
+import { getWasm } from './wasm.js'
+
+// FinalizationRegistry safety net
+const registry = typeof FinalizationRegistry !== 'undefined'
+  ? new FinalizationRegistry(({ ptr, freeFn }) => {
+    if (ptr[0]) {
+      console.warn('@wlearn/lightgbm: Dataset was not disposed -- calling free() automatically.')
+      freeFn(ptr[0])
+    }
+  })
+  : null
+
+function withCString(wasm, str, fn) {
+  const bytes = new TextEncoder().encode(str + '\0')
+  const ptr = wasm._malloc(bytes.length)
+  wasm.HEAPU8.set(bytes, ptr)
+  try {
+    return fn(ptr)
+  } finally {
+    wasm._free(ptr)
+  }
+}
+
+function getLastError(wasm) {
+  return wasm.UTF8ToString(wasm._wl_lgb_get_last_error())
+}
+
+export class Dataset {
+  #handle = null
+  #freed = false
+  #ptrRef = null
+
+  constructor(data, nrow, ncol, params = '') {
+    const wasm = getWasm()
+
+    // Copy float32 data to WASM heap
+    const dataBytes = data.length * 4
+    const dataPtr = wasm._malloc(dataBytes)
+    wasm.HEAPF32.set(data, dataPtr / 4)
+
+    // Output handle pointer
+    const outPtr = wasm._malloc(4)
+
+    const ret = withCString(wasm, params, (paramsPtr) =>
+      wasm._wl_lgb_dataset_create_from_mat(dataPtr, nrow, ncol, paramsPtr, outPtr)
+    )
+
+    if (ret !== 0) {
+      wasm._free(dataPtr)
+      wasm._free(outPtr)
+      throw new Error(`Dataset creation failed: ${getLastError(wasm)}`)
+    }
+
+    this.#handle = wasm.getValue(outPtr, 'i32')
+    wasm._free(dataPtr)
+    wasm._free(outPtr)
+
+    // Leak detection
+    this.#ptrRef = [this.#handle]
+    if (registry) {
+      registry.register(this, {
+        ptr: this.#ptrRef,
+        freeFn: (h) => getWasm()._wl_lgb_dataset_free(h)
+      }, this)
+    }
+  }
+
+  get handle() {
+    if (this.#freed) throw new Error('Dataset already disposed')
+    return this.#handle
+  }
+
+  setLabel(labels) {
+    const wasm = getWasm()
+    const arr = labels instanceof Float32Array ? labels : new Float32Array(labels)
+    const ptr = wasm._malloc(arr.length * 4)
+    wasm.HEAPF32.set(arr, ptr / 4)
+
+    // C_API_DTYPE_FLOAT32 = 0
+    const ret = withCString(wasm, 'label', (fieldPtr) =>
+      wasm._wl_lgb_dataset_set_field(this.handle, fieldPtr, ptr, arr.length, 0)
+    )
+
+    wasm._free(ptr)
+
+    if (ret !== 0) {
+      throw new Error(`Dataset setLabel failed: ${getLastError(wasm)}`)
+    }
+  }
+
+  dispose() {
+    if (this.#freed) return
+    this.#freed = true
+
+    const wasm = getWasm()
+    wasm._wl_lgb_dataset_free(this.#handle)
+
+    if (this.#ptrRef) this.#ptrRef[0] = null
+    if (registry) registry.unregister(this)
+
+    this.#handle = null
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { LGBModel } from './model.js'
+export { loadLGB } from './wasm.js'
+export { Dataset } from './dataset.js'
+export { Booster } from './booster.js'

package/src/model.js

@@ -0,0 +1,424 @@
+import { loadLGB, getWasm } from './wasm.js'
+import { Dataset } from './dataset.js'
+import { Booster } from './booster.js'
+import {
+  normalizeY,
+  encodeBundle, decodeBundle,
+  register,
+  DisposedError, NotFittedError
+} from '@wlearn/core'
+
+// FinalizationRegistry safety net
+const leakRegistry = typeof FinalizationRegistry !== 'undefined'
+  ? new FinalizationRegistry(({ ref, freeFn }) => {
+    if (ref[0]) {
+      console.warn('@wlearn/lightgbm: LGBModel was not disposed -- calling free() automatically.')
+      freeFn(ref[0])
+    }
+  })
+  : null
+
+// --- Objective classification ---
+
+const CLASSIFIER_OBJECTIVES = new Set([
+  'binary', 'multiclass', 'multiclassova', 'cross_entropy'
+])
+
+const PROBA_OBJECTIVES = new Set([
+  'binary', 'multiclass', 'multiclassova'
+])
+
+// LightGBM params that are wlearn-only (not passed to Booster)
+const WLEARN_PARAMS = new Set(['numRound', 'coerce'])
+
+// --- Internal sentinel for load path ---
+const LOAD_SENTINEL = Symbol('load')
+
+// --- LGBModel ---
+
+export class LGBModel {
+  #booster = null
+  #freed = false
+  #boosterRef = null
+  #params = {}
+  #fitted = false
+  #nrClass = 0
+  #classes = null
+
+  constructor(handle, params, extra) {
+    if (handle === LOAD_SENTINEL) {
+      // Load path
+      this.#booster = params
+      this.#params = extra.params || {}
+      this.#nrClass = extra.nrClass || 0
+      this.#classes = extra.classes ? new Int32Array(extra.classes) : null
+      this.#fitted = true
+      this.#freed = false
+      this.#boosterRef = [this.#booster]
+      if (leakRegistry) {
+        leakRegistry.register(this, {
+          ref: this.#boosterRef,
+          freeFn: (b) => { try { b.dispose() } catch {} }
+        }, this)
+      }
+    } else {
+      // Normal construction from create()
+      this.#params = handle || {}
+      this.#freed = false
+    }
+  }
+
+  static async create(params = {}) {
+    await loadLGB()
+    return new LGBModel(params)
+  }
+
+  // --- Estimator interface ---
+
+  fit(X, y) {
+    this.#ensureNotDisposed()
+
+    // Dispose previous booster if refitting
+    if (this.#booster) {
+      this.#booster.dispose()
+      this.#booster = null
+      if (this.#boosterRef) this.#boosterRef[0] = null
+      if (leakRegistry) leakRegistry.unregister(this)
+    }
+
+    const { data: xData, rows, cols } = this.#normalizeX(X)
+    const yNorm = normalizeY(y)
+
+    // Detect objective (default to regression)
+    const obj = this.#params.objective || 'regression'
+
+    // For classifiers: validate and extract classes, remap to 0-based
+    let yTrain
+    if (CLASSIFIER_OBJECTIVES.has(obj)) {
+      const unique = new Set()
+      for (let i = 0; i < yNorm.length; i++) {
+        const v = yNorm[i]
+        if (v !== Math.floor(v)) {
+          throw new Error(`Classifier labels must be integers, got ${v} at index ${i}`)
+        }
+        unique.add(v)
+      }
+      const sorted = [...unique].sort((a, b) => a - b)
+      this.#classes = new Int32Array(sorted)
+      this.#nrClass = sorted.length
+
+      // Remap to 0-based contiguous
+      const classMap = new Map()
+      for (let i = 0; i < sorted.length; i++) classMap.set(sorted[i], i)
+      yTrain = new Float32Array(yNorm.length)
+      for (let i = 0; i < yNorm.length; i++) yTrain[i] = classMap.get(yNorm[i])
+    } else {
+      this.#classes = null
+      this.#nrClass = 0
+      yTrain = yNorm instanceof Float32Array ? yNorm : new Float32Array(yNorm)
+    }
+
+    if (yTrain.length !== rows) {
+      throw new Error(`y length (${yTrain.length}) does not match X rows (${rows})`)
+    }
+
+    // Build LightGBM param string: "key1=value1 key2=value2"
+    const numRound = this.#params.numRound || 100
+    const lgbParams = {}
+    for (const [key, val] of Object.entries(this.#params)) {
+      if (!WLEARN_PARAMS.has(key)) lgbParams[key] = val
+    }
+    // Defaults
+    if (!('objective' in lgbParams)) lgbParams.objective = obj
+    if (!('verbosity' in lgbParams)) lgbParams.verbosity = -1
+
+    // Auto-set num_class for multiclass
+    if ((obj === 'multiclass' || obj === 'multiclassova') &&
+        !('num_class' in lgbParams) && this.#nrClass > 0) {
+      lgbParams.num_class = this.#nrClass
+    }
+
+    const paramStr = Object.entries(lgbParams)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(' ')
+
+    // Create Dataset
+    const ds = new Dataset(xData, rows, cols, paramStr)
+    ds.setLabel(yTrain)
+
+    // Create Booster and train
+    const booster = new Booster(ds.handle, paramStr)
+    for (let i = 0; i < numRound; i++) {
+      booster.update()
+    }
+
+    ds.dispose()
+
+    this.#booster = booster
+    this.#fitted = true
+
+    this.#boosterRef = [this.#booster]
+    if (leakRegistry) {
+      leakRegistry.register(this, {
+        ref: this.#boosterRef,
+        freeFn: (b) => { try { b.dispose() } catch {} }
+      }, this)
+    }
+
+    return this
+  }
+
+  predict(X) {
+    this.#ensureFitted()
+    const { data: xData, rows, cols } = this.#normalizeX(X)
+    const rawPreds = this.#booster.predict(xData, rows, cols)
+
+    const obj = this.#params.objective || 'regression'
+
+    if (!CLASSIFIER_OBJECTIVES.has(obj)) {
+      return rawPreds
+    }
+
+    const result = new Float64Array(rows)
+
+    if (obj === 'binary') {
+      // Raw is P(class=1), threshold at 0.5
+      for (let i = 0; i < rows; i++) {
+        result[i] = this.#classes[rawPreds[i] > 0.5 ? 1 : 0]
+      }
+    } else if (obj === 'multiclass' || obj === 'multiclassova') {
+      // Raw is rows * nrClass probabilities, argmax
+      const nc = this.#nrClass
+      for (let i = 0; i < rows; i++) {
+        let best = 0
+        for (let c = 1; c < nc; c++) {
+          if (rawPreds[i * nc + c] > rawPreds[i * nc + best]) best = c
+        }
+        result[i] = this.#classes[best]
+      }
+    } else {
+      // cross_entropy: threshold at 0.5
+      for (let i = 0; i < rows; i++) {
+        result[i] = this.#classes[rawPreds[i] > 0.5 ? 1 : 0]
+      }
+    }
+
+    return result
+  }
+
+  predictProba(X) {
+    this.#ensureFitted()
+    const obj = this.#params.objective || 'regression'
+
+    if (!PROBA_OBJECTIVES.has(obj)) {
+      throw new Error(`predictProba requires classification objective, got "${obj}"`)
+    }
+
+    const { data: xData, rows, cols } = this.#normalizeX(X)
+    const rawPreds = this.#booster.predict(xData, rows, cols)
+
+    if (obj === 'binary') {
+      // LightGBM returns P(class=1). Expand to rows * 2: [P(class=0), P(class=1)]
+      const result = new Float64Array(rows * 2)
+      for (let i = 0; i < rows; i++) {
+        const p1 = rawPreds[i]
+        result[i * 2] = 1 - p1
+        result[i * 2 + 1] = p1
+      }
+      return result
+    }
+
+    // multiclass / multiclassova: already rows * nrClass
+    return new Float64Array(rawPreds)
+  }
+
+  score(X, y) {
+    const preds = this.predict(X)
+    const yArr = normalizeY(y)
+
+    if (!this.#isClassifier()) {
+      // R-squared
+      let ssRes = 0, ssTot = 0, yMean = 0
+      for (let i = 0; i < yArr.length; i++) yMean += yArr[i]
+      yMean /= yArr.length
+      for (let i = 0; i < yArr.length; i++) {
+        ssRes += (yArr[i] - preds[i]) ** 2
+        ssTot += (yArr[i] - yMean) ** 2
+      }
+      return ssTot === 0 ? 0 : 1 - ssRes / ssTot
+    }
+
+    // Accuracy
+    let correct = 0
+    for (let i = 0; i < preds.length; i++) {
+      if (preds[i] === yArr[i]) correct++
+    }
+    return correct / preds.length
+  }
+
+  // --- Model I/O ---
+
+  save() {
+    this.#ensureFitted()
+    const modelBytes = this.#booster.saveModel()
+    const typeId = this.#isClassifier()
+      ? 'wlearn.lightgbm.classifier@1'
+      : 'wlearn.lightgbm.regressor@1'
+    return encodeBundle(
+      {
+        typeId,
+        params: this.getParams(),
+        metadata: {
+          nrClass: this.#nrClass,
+          classes: this.#classes ? Array.from(this.#classes) : [],
+          objective: this.#params.objective || 'regression'
+        }
+      },
+      [{ id: 'model', data: modelBytes }]
+    )
+  }
+
+  static async load(bytes) {
+    const { manifest, toc, blobs } = decodeBundle(bytes)
+    return LGBModel._fromBundle(manifest, toc, blobs)
+  }
+
+  static async _fromBundle(manifest, toc, blobs) {
+    await loadLGB()
+
+    const entry = toc.find(e => e.id === 'model')
+    if (!entry) throw new Error('Bundle missing "model" artifact')
+    const raw = blobs.subarray(entry.offset, entry.offset + entry.length)
+
+    const booster = Booster.loadModel(raw)
+
+    const meta = manifest.metadata || {}
+    return new LGBModel(LOAD_SENTINEL, booster, {
+      params: manifest.params || {},
+      nrClass: meta.nrClass || 0,
+      classes: meta.classes || null
+    })
+  }
+
+  dispose() {
+    if (this.#freed) return
+    this.#freed = true
+
+    if (this.#booster) {
+      this.#booster.dispose()
+    }
+
+    if (this.#boosterRef) this.#boosterRef[0] = null
+    if (leakRegistry) leakRegistry.unregister(this)
+
+    this.#booster = null
+    this.#fitted = false
+  }
+
+  // --- Params ---
+
+  getParams() {
+    return { ...this.#params }
+  }
+
+  setParams(p) {
+    Object.assign(this.#params, p)
+    return this
+  }
+
+  static defaultSearchSpace() {
+    return {
+      objective: { type: 'categorical', values: ['binary', 'regression'] },
+      max_depth: { type: 'int_uniform', low: 3, high: 12 },
+      learning_rate: { type: 'log_uniform', low: 0.01, high: 0.3 },
+      numRound: { type: 'int_uniform', low: 50, high: 500 },
+      subsample: { type: 'uniform', low: 0.5, high: 1.0 },
+      colsample_bytree: { type: 'uniform', low: 0.5, high: 1.0 },
+      min_child_weight: { type: 'log_uniform', low: 1, high: 10 },
+      reg_lambda: { type: 'log_uniform', low: 1e-3, high: 10 },
+      reg_alpha: { type: 'log_uniform', low: 1e-3, high: 10 },
+      num_leaves: { type: 'int_uniform', low: 15, high: 127 }
+    }
+  }
+
+  // --- Inspection ---
+
+  get nrClass() {
+    return this.#nrClass
+  }
+
+  get classes() {
+    return this.#classes ? Int32Array.from(this.#classes) : new Int32Array(0)
+  }
+
+  get isFitted() {
+    return this.#fitted && !this.#freed
+  }
+
+  get capabilities() {
+    const obj = this.#params.objective || 'regression'
+    const isCls = CLASSIFIER_OBJECTIVES.has(obj)
+    return {
+      classifier: isCls,
+      regressor: !isCls,
+      predictProba: PROBA_OBJECTIVES.has(obj),
+      decisionFunction: false,
+      sampleWeight: false,
+      csr: false,
+      earlyStopping: false
+    }
+  }
+
+  get probaDim() {
+    if (!this.isFitted) return 0
+    const obj = this.#params.objective || 'regression'
+    if (obj === 'binary') return 2
+    if (obj === 'multiclass' || obj === 'multiclassova') return this.#nrClass
+    return 0
+  }
+
+  // --- Private helpers ---
+
+  #normalizeX(X) {
+    // Fast path: typed matrix { data, rows, cols }
+    if (X && typeof X === 'object' && !Array.isArray(X) && X.data) {
+      const { data, rows, cols } = X
+      if (data instanceof Float32Array) return { data, rows, cols }
+      return { data: new Float32Array(data), rows, cols }
+    }
+
+    // Slow path: number[][]
+    if (Array.isArray(X) && Array.isArray(X[0])) {
+      const rows = X.length
+      const cols = X[0].length
+      const data = new Float32Array(rows * cols)
+      for (let i = 0; i < rows; i++) {
+        for (let j = 0; j < cols; j++) {
+          data[i * cols + j] = X[i][j]
+        }
+      }
+      return { data, rows, cols }
+    }
+
+    throw new Error('X must be number[][] or { data: TypedArray, rows, cols }')
+  }
+
+  #ensureNotDisposed() {
+    if (this.#freed) throw new DisposedError('LGBModel has been disposed.')
+  }
+
+  #ensureFitted() {
+    if (this.#freed) throw new DisposedError('LGBModel has been disposed.')
+    if (!this.#fitted) throw new NotFittedError('LGBModel is not fitted. Call fit() first.')
+  }
+
+  #isClassifier() {
+    const obj = this.#params.objective || 'regression'
+    return CLASSIFIER_OBJECTIVES.has(obj)
+  }
+}
+
+// --- Register loaders with @wlearn/core ---
+
+register('wlearn.lightgbm.classifier@1', async (m, t, b) => LGBModel._fromBundle(m, t, b))
+register('wlearn.lightgbm.regressor@1', async (m, t, b) => LGBModel._fromBundle(m, t, b))

package/src/wasm.js

@@ -0,0 +1,27 @@
+// WASM loader -- loads the LightGBM WASM module (singleton, lazy init)
+
+import { createRequire } from 'module'
+
+let wasmModule = null
+let loading = null
+
+export async function loadLGB(options = {}) {
+  if (wasmModule) return wasmModule
+  if (loading) return loading
+
+  loading = (async () => {
+    // SINGLE_FILE=1: .wasm is embedded in the .cjs file, no locateFile needed
+    // Emscripten output is CJS, use createRequire for ESM compatibility
+    const require = createRequire(import.meta.url)
+    const createLightGBM = require('../wasm/lightgbm.cjs')
+    wasmModule = await createLightGBM(options)
+    return wasmModule
+  })()
+
+  return loading
+}
+
+export function getWasm() {
+  if (!wasmModule) throw new Error('WASM not loaded -- call loadLGB() first')
+  return wasmModule
+}

package/wasm/BUILD_INFO

@@ -0,0 +1,6 @@
+upstream: LightGBM v4.6.0
+upstream_commit: d02a01ac6f51d36c9e62388243bcb75c3b1b1774
+build_date: 2026-02-27T13:05:21Z
+emscripten: emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 5.0.2 (dc80f645ee70178c11666de0c3860d9e064d50e4)
+build_flags: -O2 -fexceptions SINGLE_FILE=1
+wasm_embedded: true