@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.1

package/src/ml/classical/logistic.ts

@@ -0,0 +1,125 @@
+/**
+ * ml/classical/logistic.ts — (multinomial) logistic regression.
+ *
+ * Softmax regression with L2, fitted by full-batch gradient descent; two classes
+ * is ordinary logistic regression. No internal feature scaling: a task supplies
+ * features on a stable scale, so a weight means the same thing on every machine —
+ * which is what lets trained weights FEDERATE (`exportParams` / `importParams`).
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { classCount, featureDim, softmax, topProbability } from "./math.js";
+
+export interface LogisticOptions {
+  classes?: number;
+  learningRate?: number;
+  epochs?: number;
+  /** L2 penalty on weights (not biases). Default 1e-3. */
+  l2?: number;
+}
+
+export class LogisticModel implements MlPredictor {
+  /** Row-major weights [classes × dim]. */
+  readonly weights: Float32Array;
+  readonly bias: Float32Array;
+
+  constructor(
+    readonly dim: number,
+    readonly classes: number,
+  ) {
+    this.weights = new Float32Array(classes * dim);
+    this.bias = new Float32Array(classes);
+  }
+
+  logits(x: ArrayLike<number>): number[] {
+    const z: number[] = [];
+    for (let c = 0; c < this.classes; c++) {
+      let s = this.bias[c]!;
+      const off = c * this.dim;
+      for (let i = 0; i < this.dim; i++) s += this.weights[off + i]! * (x[i] ?? 0);
+      z.push(s);
+    }
+    return z;
+  }
+
+  proba(x: ArrayLike<number>): number[] {
+    return Array.from(softmax(this.logits(x)));
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const scores = this.proba(x);
+    return { scores, confidence: topProbability(scores) };
+  }
+
+  /** Weighted mean cross-entropy over `samples` (the eval-gate loss). */
+  loss(samples: readonly MlSample[]): number {
+    let sum = 0;
+    let wSum = 0;
+    for (const s of samples) {
+      const w = s.weight ?? 1;
+      sum += -w * Math.log(Math.max(this.proba(s.x)[s.y] ?? 0, 1e-12));
+      wSum += w;
+    }
+    return wSum > 0 ? sum / wSum : 0;
+  }
+
+  /** One full-batch gradient step; returns the pre-step mean loss. */
+  step(samples: readonly MlSample[], learningRate: number, l2: number): number {
+    const gW = new Float64Array(this.weights.length);
+    const gB = new Float64Array(this.classes);
+    let loss = 0;
+    let wSum = 0;
+    for (const s of samples) {
+      const w = s.weight ?? 1;
+      const p = this.proba(s.x);
+      loss += -w * Math.log(Math.max(p[s.y]!, 1e-12));
+      wSum += w;
+      for (let c = 0; c < this.classes; c++) {
+        const g = w * (p[c]! - (c === s.y ? 1 : 0));
+        gB[c] = gB[c]! + g;
+        const off = c * this.dim;
+        for (let i = 0; i < this.dim; i++) gW[off + i] = gW[off + i]! + g * s.x[i]!;
+      }
+    }
+    const inv = wSum > 0 ? 1 / wSum : 0;
+    for (let j = 0; j < this.weights.length; j++) {
+      this.weights[j] = this.weights[j]! - learningRate * (gW[j]! * inv + l2 * this.weights[j]!);
+    }
+    for (let c = 0; c < this.classes; c++) this.bias[c] = this.bias[c]! - learningRate * gB[c]! * inv;
+    return loss * inv;
+  }
+
+  exportParams(): Float32Array {
+    const out = new Float32Array(this.weights.length + this.bias.length);
+    out.set(this.weights, 0);
+    out.set(this.bias, this.weights.length);
+    return out;
+  }
+
+  importParams(params: ArrayLike<number>): void {
+    if (params.length !== this.weights.length + this.bias.length) {
+      throw new Error(`LogisticModel.importParams: expected ${this.weights.length + this.bias.length} values, got ${params.length}`);
+    }
+    for (let j = 0; j < this.weights.length; j++) this.weights[j] = params[j]!;
+    for (let c = 0; c < this.bias.length; c++) this.bias[c] = params[this.weights.length + c]!;
+  }
+}
+
+/**
+ * Fit logistic regression. Pass `init` to continue from existing weights (a local
+ * round on top of a merged federated head).
+ */
+export function fitLogistic(
+  samples: readonly MlSample[],
+  opts: LogisticOptions = {},
+  init?: LogisticModel,
+): LogisticModel {
+  const d = featureDim(samples.map((s) => s.x));
+  const k = opts.classes ?? init?.classes ?? classCount(samples.map((s) => s.y));
+  const model = init ?? new LogisticModel(d, k);
+  if (model.dim !== d || model.classes !== k) throw new Error(`fitLogistic: init is ${model.dim}×${model.classes}, data is ${d}×${k}`);
+  const lr = opts.learningRate ?? 0.5;
+  const l2 = opts.l2 ?? 1e-3;
+  const epochs = opts.epochs ?? 300;
+  for (let e = 0; e < epochs; e++) model.step(samples, lr, l2);
+  return model;
+}

package/src/ml/classical/math.ts

@@ -0,0 +1,93 @@
+/**
+ * ml/classical/math.ts — the small vector helpers every classical algorithm shares.
+ * Pure, allocation-light, deterministic.
+ */
+import { SeededRng } from "../../utils/rng.js";
+
+/** The engine's ONE sigmoid / softmax (`training/cpu_ops.ts`). */
+export { sigmoid, softmax } from "../../training/cpu_ops.js";
+
+export type Vec = ArrayLike<number>;
+
+export function dot(a: Vec, b: Vec): number {
+  const n = Math.min(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < n; i++) s += a[i]! * b[i]!;
+  return s;
+}
+
+export function norm(a: Vec): number {
+  return Math.sqrt(dot(a, a));
+}
+
+/** Cosine similarity in [-1, 1]; 0 when either vector is zero. */
+export function cosine(a: Vec, b: Vec): number {
+  const na = norm(a);
+  const nb = norm(b);
+  return na > 0 && nb > 0 ? dot(a, b) / (na * nb) : 0;
+}
+
+export function squaredDistance(a: Vec, b: Vec): number {
+  const n = Math.min(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < n; i++) {
+    const d = a[i]! - b[i]!;
+    s += d * d;
+  }
+  return s;
+}
+
+/** Median of a numeric list (copy-sorted). NaN for an empty list. */
+export function median(values: readonly number[]): number {
+  if (values.length === 0) return Number.NaN;
+  const s = [...values].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+}
+
+/** Index of the largest value (first on ties). */
+export function argmax(values: ArrayLike<number>): number {
+  let best = 0;
+  for (let i = 1; i < values.length; i++) if (values[i]! > values[best]!) best = i;
+  return best;
+}
+
+/** Number of distinct classes implied by integer labels 0..k-1. */
+export function classCount(labels: readonly number[]): number {
+  let k = 0;
+  for (const y of labels) {
+    if (!Number.isInteger(y) || y < 0) throw new Error(`class label must be a non-negative integer, got ${y}`);
+    k = Math.max(k, y + 1);
+  }
+  return Math.max(k, 2);
+}
+
+/** Feature dimension of a non-empty sample matrix; throws on ragged rows. */
+export function featureDim(X: readonly Vec[]): number {
+  if (X.length === 0) throw new Error("no samples");
+  const d = X[0]!.length;
+  for (const x of X) if (x.length !== d) throw new Error(`ragged features: expected ${d}, got ${x.length}`);
+  return d;
+}
+
+/** Confidence of a probability vector: its top probability. */
+export function topProbability(p: readonly number[]): number {
+  return p.length ? Math.max(...p) : 0;
+}
+
+/** A deterministic [0,1) source for algorithms that sample — the engine's ONE seeded RNG. */
+export function seededUniform(seed: number): () => number {
+  const rng = new SeededRng(seed);
+  return () => rng.next();
+}
+
+/**
+ * Average path length of an unsuccessful BST search over n points — the
+ * isolation-forest normaliser c(n).
+ */
+export function averagePathLength(n: number): number {
+  if (n <= 1) return 0;
+  if (n === 2) return 1;
+  const harmonic = Math.log(n - 1) + 0.5772156649;
+  return 2 * harmonic - (2 * (n - 1)) / n;
+}

package/src/ml/classical/naive_bayes.ts

@@ -0,0 +1,77 @@
+/**
+ * ml/classical/naive_bayes.ts — Gaussian naive Bayes.
+ *
+ * Per class: a weighted prior, and an independent Gaussian per feature. Variance
+ * is smoothed by a fraction of the largest feature variance (as scikit-learn's
+ * `var_smoothing`), so a constant feature never divides by zero.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { classCount, featureDim, softmax, topProbability } from "./math.js";
+
+export interface NaiveBayesOptions {
+  classes?: number;
+  /** Fraction of the largest feature variance added to every variance. Default 1e-9. */
+  varSmoothing?: number;
+}
+
+export class NaiveBayesModel implements MlPredictor {
+  constructor(
+    readonly logPrior: Float64Array,
+    readonly mean: Float64Array[],
+    readonly variance: Float64Array[],
+  ) {}
+
+  /** Per-class joint log-likelihood log P(c) + Σ log N(x_i | μ, σ²). */
+  jointLogLikelihood(x: ArrayLike<number>): number[] {
+    return this.mean.map((mu, c) => {
+      const v = this.variance[c]!;
+      let ll = this.logPrior[c]!;
+      for (let i = 0; i < mu.length; i++) {
+        const d = (x[i] ?? 0) - mu[i]!;
+        ll += -0.5 * Math.log(2 * Math.PI * v[i]!) - (d * d) / (2 * v[i]!);
+      }
+      return ll;
+    });
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const scores = Array.from(softmax(this.jointLogLikelihood(x)));
+    return { scores, confidence: topProbability(scores) };
+  }
+}
+
+export function fitNaiveBayes(samples: readonly MlSample[], opts: NaiveBayesOptions = {}): NaiveBayesModel {
+  const d = featureDim(samples.map((s) => s.x));
+  const k = opts.classes ?? classCount(samples.map((s) => s.y));
+  const wSum = new Float64Array(k);
+  const mean = Array.from({ length: k }, () => new Float64Array(d));
+  const variance = Array.from({ length: k }, () => new Float64Array(d));
+
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    wSum[s.y] = wSum[s.y]! + w;
+    for (let i = 0; i < d; i++) mean[s.y]![i] = mean[s.y]![i]! + w * s.x[i]!;
+  }
+  for (let c = 0; c < k; c++) if (wSum[c]! > 0) for (let i = 0; i < d; i++) mean[c]![i] = mean[c]![i]! / wSum[c]!;
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    for (let i = 0; i < d; i++) {
+      const diff = s.x[i]! - mean[s.y]![i]!;
+      variance[s.y]![i] = variance[s.y]![i]! + w * diff * diff;
+    }
+  }
+  let maxVar = 0;
+  for (let c = 0; c < k; c++) {
+    for (let i = 0; i < d; i++) {
+      variance[c]![i] = wSum[c]! > 0 ? variance[c]![i]! / wSum[c]! : 0;
+      maxVar = Math.max(maxVar, variance[c]![i]!);
+    }
+  }
+  const eps = (opts.varSmoothing ?? 1e-9) * Math.max(maxVar, 1e-12) + 1e-12;
+  for (let c = 0; c < k; c++) for (let i = 0; i < d; i++) variance[c]![i] = variance[c]![i]! + eps;
+
+  const total = wSum.reduce((a, b) => a + b, 0);
+  // An unseen class keeps a vanishing (not -∞) prior so softmax stays defined.
+  const logPrior = Float64Array.from(wSum, (w) => Math.log(Math.max(w, 1e-12) / total));
+  return new NaiveBayesModel(logPrior, mean, variance);
+}

package/src/ml/classical/robust_z.ts

@@ -0,0 +1,65 @@
+/**
+ * ml/classical/robust_z.ts — robust (median/MAD) z-scores for anomaly detection.
+ *
+ * Per feature: z = |x − median| / (1.4826 · MAD). Median and MAD are not dragged
+ * by the very outliers being looked for, unlike mean and standard deviation. When
+ * MAD is 0 (more than half the history identical) the mean absolute deviation
+ * stands in, then a floor, so a constant history still scores a change.
+ *
+ * Prediction: `scores[0] = max_i z_i / threshold` — ≥ 1 is anomalous.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { featureDim, median } from "./math.js";
+
+/** MAD → standard deviation for normally-distributed data. */
+const MAD_TO_SD = 1.4826;
+/** Mean absolute deviation → standard deviation for normally-distributed data. */
+const MEANAD_TO_SD = 1.2533;
+
+export interface RobustZOptions {
+  /** z at which a feature counts as anomalous. Default 3.5 (Iglewicz & Hoaglin). */
+  threshold?: number;
+  /** Smallest scale per feature, as a fraction of |median| (plus 1e-9). Default 0.01. */
+  minScaleFraction?: number;
+}
+
+export class RobustZModel implements MlPredictor {
+  constructor(
+    readonly center: Float64Array,
+    readonly scale: Float64Array,
+    readonly threshold: number,
+  ) {}
+
+  /** Per-feature robust z-scores (absolute). */
+  zScores(x: ArrayLike<number>): number[] {
+    return Array.from(this.center, (c, i) => Math.abs((x[i] ?? 0) - c) / this.scale[i]!);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const score = Math.max(0, ...this.zScores(x)) / this.threshold;
+    return { scores: [score], confidence: anomalyConfidence(score) };
+  }
+}
+
+/** Confidence of an anomaly score normalised so 1 is the threshold: distance from it, capped. */
+export function anomalyConfidence(score: number): number {
+  return Math.max(0, Math.min(1, Math.abs(score - 1)));
+}
+
+export function fitRobustZ(samples: readonly MlSample[], opts: RobustZOptions = {}): RobustZModel {
+  const X = samples.map((s) => s.x);
+  const d = featureDim(X);
+  const minFrac = opts.minScaleFraction ?? 0.01;
+  const center = new Float64Array(d);
+  const scale = new Float64Array(d);
+  for (let i = 0; i < d; i++) {
+    const col = X.map((x) => x[i]!);
+    const med = median(col);
+    const dev = col.map((v) => Math.abs(v - med));
+    let s = MAD_TO_SD * median(dev);
+    if (!(s > 0)) s = MEANAD_TO_SD * (dev.reduce((a, b) => a + b, 0) / dev.length);
+    center[i] = med;
+    scale[i] = Math.max(s, minFrac * Math.abs(med) + 1e-9);
+  }
+  return new RobustZModel(center, scale, opts.threshold ?? 3.5);
+}

package/src/ml/dense_head.ts

@@ -0,0 +1,157 @@
+/**
+ * ml/dense_head.ts — the catalog's trainable head: linear, or one tanh hidden layer,
+ * over a feature vector (usually an experience embedding).
+ *
+ * It is a {@link TrainableHead} (so the ONE {@link HeadTrainer} fits it, on the
+ * GPU when there is one) and an {@link MlPredictor} (so the runner answers with
+ * it). Its parameters flatten to one vector — the unit that federates.
+ */
+import { gaussianArray, SeededRng } from "../utils/rng.js";
+import { softmax } from "../training/cpu_ops.js";
+import { assignParams, flattenParams, type HeadParam, type TrainableHead } from "./head_trainer.js";
+import type { MlPrediction, MlPredictor, MlSample } from "./types.js";
+
+export interface DenseHeadConfig {
+  inputDim: number;
+  /** Hidden width; 0 = a linear head. */
+  hiddenDim: number;
+  /** Classes (softmax) or 1 (mse regression). */
+  outputDim: number;
+  /** `softmax` = classification over `outputDim` classes; `mse` = scalar regression. */
+  objective: "softmax" | "mse";
+  seed?: number;
+}
+
+export class DenseHead implements TrainableHead<MlSample>, MlPredictor {
+  readonly config: Required<DenseHeadConfig>;
+  private readonly _params: HeadParam[];
+  private readonly _grads: HeadParam[];
+
+  constructor(config: DenseHeadConfig) {
+    this.config = { seed: 0x4e4d, ...config };
+    const { inputDim, hiddenDim, outputDim, objective } = this.config;
+    if (objective === "mse" && outputDim !== 1) throw new Error("DenseHead: mse objective needs outputDim 1");
+    if (objective === "softmax" && outputDim < 2) throw new Error("DenseHead: softmax objective needs outputDim ≥ 2");
+    const rng = new SeededRng(this.config.seed);
+    const next = () => rng.next();
+    const inner = hiddenDim > 0 ? hiddenDim : inputDim;
+    const shapes: [string, number, number][] = [
+      ...(hiddenDim > 0
+        ? ([
+            ["w1", hiddenDim * inputDim, 1 / Math.sqrt(inputDim)],
+            ["b1", hiddenDim, 0],
+          ] as [string, number, number][])
+        : []),
+      ["w2", outputDim * inner, 1 / Math.sqrt(inner)],
+      ["b2", outputDim, 0],
+    ];
+    this._params = shapes.map(([name, n, std]) => ({ name, numel: n, data: std > 0 ? gaussianArray(n, std, next) : new Float32Array(n) }));
+    this._grads = shapes.map(([name, n]) => ({ name, numel: n, data: new Float32Array(n) }));
+  }
+
+  private _p(name: string): Float32Array {
+    return this._params.find((p) => p.name === name)!.data;
+  }
+
+  private _g(name: string): Float32Array {
+    return this._grads.find((p) => p.name === name)!.data;
+  }
+
+  parameters(): HeadParam[] {
+    return this._params;
+  }
+
+  gradients(): HeadParam[] {
+    return this._grads;
+  }
+
+  zeroGrad(): void {
+    for (const g of this._grads) g.data.fill(0);
+  }
+
+  /** Hidden activation (or the input itself for a linear head) and the output logits/value. */
+  private _forward(x: ArrayLike<number>): { h: Float32Array; z: Float32Array } {
+    const { inputDim, hiddenDim, outputDim } = this.config;
+    let h: Float32Array;
+    if (hiddenDim > 0) {
+      const w1 = this._p("w1");
+      const b1 = this._p("b1");
+      h = new Float32Array(hiddenDim);
+      for (let j = 0; j < hiddenDim; j++) {
+        let s = b1[j]!;
+        for (let i = 0; i < inputDim; i++) s += w1[j * inputDim + i]! * (x[i] ?? 0);
+        h[j] = Math.tanh(s);
+      }
+    } else {
+      h = Float32Array.from({ length: inputDim }, (_, i) => x[i] ?? 0);
+    }
+    const w2 = this._p("w2");
+    const b2 = this._p("b2");
+    const z = new Float32Array(outputDim);
+    for (let k = 0; k < outputDim; k++) {
+      let s = b2[k]!;
+      for (let j = 0; j < h.length; j++) s += w2[k * h.length + j]! * h[j]!;
+      z[k] = s;
+    }
+    return { h, z };
+  }
+
+  /** Loss and dLoss/dz of one sample (unweighted). */
+  private _lossGrad(z: Float32Array, y: number): { loss: number; dz: Float32Array } {
+    if (this.config.objective === "mse") {
+      const d = z[0]! - y;
+      return { loss: 0.5 * d * d, dz: Float32Array.of(d) };
+    }
+    const p = softmax(z);
+    const dz = Float32Array.from(p, (v, k) => v - (k === y ? 1 : 0));
+    return { loss: -Math.log(Math.max(p[y] ?? 0, 1e-12)), dz };
+  }
+
+  loss(s: MlSample): number {
+    return (s.weight ?? 1) * this._lossGrad(this._forward(s.x).z, s.y).loss;
+  }
+
+  accumulate(s: MlSample): number {
+    const w = s.weight ?? 1;
+    const { inputDim, hiddenDim, outputDim } = this.config;
+    const { h, z } = this._forward(s.x);
+    const { loss, dz } = this._lossGrad(z, s.y);
+    const w2 = this._p("w2");
+    const gW2 = this._g("w2");
+    const gB2 = this._g("b2");
+    const dh = new Float32Array(h.length);
+    for (let k = 0; k < outputDim; k++) {
+      const g = w * dz[k]!;
+      gB2[k] = gB2[k]! + g;
+      for (let j = 0; j < h.length; j++) {
+        gW2[k * h.length + j] = gW2[k * h.length + j]! + g * h[j]!;
+        dh[j] = dh[j]! + g * w2[k * h.length + j]!;
+      }
+    }
+    if (hiddenDim > 0) {
+      const gW1 = this._g("w1");
+      const gB1 = this._g("b1");
+      for (let j = 0; j < hiddenDim; j++) {
+        const dpre = dh[j]! * (1 - h[j]! * h[j]!);
+        gB1[j] = gB1[j]! + dpre;
+        for (let i = 0; i < inputDim; i++) gW1[j * inputDim + i] = gW1[j * inputDim + i]! + dpre * (s.x[i] ?? 0);
+      }
+    }
+    return w * loss;
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const { z } = this._forward(x);
+    if (this.config.objective === "mse") return { scores: [z[0]!], confidence: 1 };
+    const scores = Array.from(softmax(z));
+    return { scores, confidence: Math.max(...scores) };
+  }
+
+  exportParams(): Float32Array {
+    return flattenParams(this._params);
+  }
+
+  importParams(params: ArrayLike<number>): void {
+    assignParams(this._params, params);
+  }
+}

package/src/ml/features.ts

@@ -0,0 +1,61 @@
+/**
+ * ml/features.ts — how an input becomes a feature vector.
+ *
+ * Text goes through the existing CPU embedder seam ({@link TextEmbedder}, which
+ * `EvermindTextEmbedder` implements: the person's own Evermind turns text into
+ * an L2-normalised vector with no GPU and no network). Numeric fields are
+ * appended as the task supplies them — on a FIXED scale (see {@link logScale}),
+ * never one fitted to local data, so a federated weight means the same thing on
+ * every machine.
+ */
+import type { TextEmbedder } from "../lm/text_embedder.js";
+import type { FeatureSpec } from "./types.js";
+
+export type { TextEmbedder } from "../lm/text_embedder.js";
+
+/** Feature vector of one input: `[embed(text) …, numeric …]`. */
+export async function extractFeatures<I>(spec: FeatureSpec<I>, input: I, embedder?: TextEmbedder): Promise<Float32Array> {
+  const parts: ArrayLike<number>[] = [];
+  if (spec.text) {
+    if (!embedder) throw new Error("extractFeatures: this task embeds text but no embedder was supplied");
+    parts.push(await embedder.embed(spec.text(input)));
+  }
+  if (spec.numeric) {
+    const nums = spec.numeric(input);
+    for (const v of nums) if (!Number.isFinite(v)) throw new Error(`extractFeatures: non-finite numeric feature ${v}`);
+    parts.push(nums);
+  }
+  if (parts.length === 0) throw new Error("extractFeatures: the feature spec has neither text nor numeric fields");
+  const out = new Float32Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+/** Feature vectors of many inputs, in order. */
+export async function extractFeatureMatrix<I>(
+  spec: FeatureSpec<I>,
+  inputs: readonly I[],
+  embedder?: TextEmbedder,
+): Promise<Float32Array[]> {
+  const out: Float32Array[] = [];
+  for (const i of inputs) out.push(await extractFeatures(spec, i, embedder));
+  return out;
+}
+
+/**
+ * A count or size on a fixed log scale: log1p(max(v, 0)) / log1p(ref). `ref` is
+ * the value that maps to 1 (e.g. 100k tokens), so the scale is the same everywhere.
+ */
+export function logScale(v: number, ref: number): number {
+  return Math.log1p(Math.max(0, v)) / Math.log1p(Math.max(ref, 1));
+}
+
+/** A ratio clamped to [0, max] — fill fractions, success rates. */
+export function clampRatio(numerator: number, denominator: number, max = 4): number {
+  if (!(denominator > 0)) return 0;
+  return Math.max(0, Math.min(max, numerator / denominator));
+}