Track 2: substrate-typed array library — vectorized arithmetic + resonance access

First piece of the substrate-typed-array track. The differentiator
vs numpy: every element of an OMC int array carries φ-resonance and
HIM (Harmonic Interference Metric) computed from the substrate at
HInt construction time. The new builtins expose vectorized operations
that PRESERVE this substrate-typing through element-wise math, plus
two reduction-like operations that EXTRACT the substrate metadata
as parallel arrays — things Python literally can't do because i64
doesn't carry resonance.

NEW BUILTINS (9):

  Vectorized arithmetic (broadcast scalar ↔ array on either side):
    arr_add(a, b)      — element-wise +
    arr_sub(a, b)      — element-wise -
    arr_mul(a, b)      — element-wise *
    arr_div_int(a, b)  — element-wise / (zero divisor → 0, no NaN
                          propagation; Singularity is at value level
                          not array level)
    arr_neg(a)         — unary -
    arr_scale(a, k)    — explicit scalar mul (sugar for arr_mul)

  Substrate-aware (the differentiator from numpy):
    arr_resonance_vec(a)  — per-element φ-resonance score [0..1]
    arr_him_vec(a)        — per-element Harmonic Interference Metric
    arr_fold_all(a)       — vectorized fold; snaps every element to
                            its nearest Fibonacci attractor

Helper added at module scope:

  elementwise_op(a: &Value, b: &Value, name, op: F)
    F: Fn(i64, i64) -> i64. Handles (array, array), (array, scalar),
    (scalar, array). Mismatched array lengths error explicitly —
    no implicit shape-1 expansion (keeps behavior obvious for a
    minimum-viable broadcast). Output Values are wrapped via
    HInt::new so per-element substrate-resonance gets recomputed
    from the arithmetic result.

Tests (examples/tests/test_substrate_array.omc — 15 tests, all pass):
  - Element-wise: add / sub / mul / neg
  - Scalar broadcast: arr_scale, arr_add(arr, scalar), arr_sub(scalar, arr)
  - Division with zero-divisor handling
  - Per-element resonance: Fibonacci values resonance ~1.0,
    off-attractor < 1.0; HIM low for on-attractor
  - arr_fold_all snaps to attractors (post-fold every element is
    an exact Fibonacci value, verified via is_attractor)
  - Composition: ML-shaped pipeline (raw → scale → bias → fold →
    score by mean resonance) stays substrate-coherent
  - Composition with existing reductions: arr_add then arr_sum_int;
    arr_mul (square) then arr_sum_int (sum of squares)

What this unlocks for the harmonic-LLM thesis:
  - Feature vectors with per-element substrate-resonance tracking
  - Substrate-aware activations: f(x) = arr_mul(arr_resonance_vec(x), x)
    weights every element by its own substrate coherence
  - Quantization-via-fold: arr_fold_all is a no-config substrate-
    aligned quantizer (compose with arr_resonance_vec to detect
    quantization error)

What's NOT yet shipped (next session for Track 2):
  - Broadcasting beyond scalar↔array (no shape-1 expansion between
    differently-shaped arrays)
  - 2D arrays / matrices (matmul, transpose)
  - Substrate-aware autograd (forward-mode + reverse-mode)
  - End-to-end harmonic ML pipeline demo using these primitives

Regression: 225 OMC tests + 15 new substrate-array = 240 OMC tests
pass. All previous suites green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

examples/tests/test_substrate_array.omc

@@ -0,0 +1,178 @@
+# Track 2: substrate-typed array library — MVP tests.
+#
+# Vectorized arithmetic + per-element substrate metadata access:
+#   arr_add / arr_sub / arr_mul / arr_div_int / arr_neg / arr_scale
+#   arr_resonance_vec  — every element's φ-resonance
+#   arr_him_vec        — every element's HIM score
+#   arr_fold_all       — element-wise snap to nearest Fibonacci attractor
+#
+# The defining feature vs numpy: every element of an OMC int array
+# carries substrate-resonance metadata. arr_resonance_vec / arr_him_vec
+# expose this; Python can't because i64 doesn't carry resonance.
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_true(cond, msg) {
+    if !cond { test_record_failure(msg); }
+}
+
+fn approx_eq(a, b, tol) {
+    h d = a - b;
+    if d < 0 { d = 0 - d; }
+    return d <= tol;
+}
+
+# ---- Element-wise arithmetic ----
+
+fn test_arr_add() {
+    h a = [1, 2, 3, 4];
+    h b = [10, 20, 30, 40];
+    h c = arr_add(a, b);
+    assert_eq(arr_len(c), 4, "length preserved");
+    assert_eq(arr_get(c, 0), 11, "1+10");
+    assert_eq(arr_get(c, 3), 44, "4+40");
+}
+
+fn test_arr_sub() {
+    h c = arr_sub([10, 20, 30], [1, 2, 3]);
+    assert_eq(arr_get(c, 0), 9, "10-1");
+    assert_eq(arr_get(c, 2), 27, "30-3");
+}
+
+fn test_arr_mul() {
+    h c = arr_mul([1, 2, 3], [10, 10, 10]);
+    assert_eq(arr_get(c, 0), 10, "1*10");
+    assert_eq(arr_get(c, 2), 30, "3*10");
+}
+
+fn test_arr_neg() {
+    h c = arr_neg([1, 0 - 2, 3, 0 - 4]);
+    assert_eq(arr_get(c, 0), 0 - 1, "neg 1");
+    assert_eq(arr_get(c, 1), 2, "neg -2");
+}
+
+# ---- Scalar broadcasting ----
+
+fn test_arr_scale() {
+    h c = arr_scale([1, 2, 3, 4], 5);
+    assert_eq(arr_get(c, 0), 5, "1*5");
+    assert_eq(arr_get(c, 3), 20, "4*5");
+}
+
+fn test_arr_add_scalar() {
+    # 2nd arg is a scalar — broadcasts to every element.
+    h c = arr_add([10, 20, 30], 1);
+    assert_eq(arr_get(c, 0), 11, "10+1");
+    assert_eq(arr_get(c, 2), 31, "30+1");
+}
+
+fn test_arr_scalar_lhs() {
+    # 1st arg is a scalar — broadcasts to every element.
+    h c = arr_sub(100, [1, 2, 3]);
+    assert_eq(arr_get(c, 0), 99, "100-1");
+    assert_eq(arr_get(c, 2), 97, "100-3");
+}
+
+# ---- Division ----
+
+fn test_arr_div_int() {
+    h c = arr_div_int([10, 20, 30], [2, 5, 0]);
+    assert_eq(arr_get(c, 0), 5, "10/2");
+    assert_eq(arr_get(c, 1), 4, "20/5");
+    # Div by zero → 0 (no NaN propagation through array)
+    assert_eq(arr_get(c, 2), 0, "30/0 -> 0");
+}
+
+# ---- Substrate-typed dtype: per-element resonance ----
+
+fn test_arr_resonance_vec_attractors() {
+    # Fibonacci numbers have resonance = 1.0
+    h r = arr_resonance_vec([0, 1, 2, 3, 5, 8, 13, 21]);
+    h i = 0;
+    while i < arr_len(r) {
+        assert_true(approx_eq(arr_get(r, i), 1.0, 0.001),
+            "Fibonacci has resonance ~1.0");
+        i = i + 1;
+    }
+}
+
+fn test_arr_resonance_vec_off_attractor() {
+    # Off-attractor values have resonance < 1.0
+    h r = arr_resonance_vec([7, 100, 99]);
+    h i = 0;
+    while i < arr_len(r) {
+        assert_true(arr_get(r, i) < 1.0, "off-attractor resonance < 1");
+        i = i + 1;
+    }
+}
+
+fn test_arr_him_vec() {
+    # On-attractor values have low HIM (Harmonic Interference Metric).
+    h h_attr = arr_him_vec([1, 2, 3, 5, 8, 13]);
+    h i = 0;
+    while i < arr_len(h_attr) {
+        assert_true(arr_get(h_attr, i) < 0.5,
+            "on-attractor HIM < 0.5");
+        i = i + 1;
+    }
+}
+
+# ---- Substrate-aware quantization ----
+
+fn test_arr_fold_all() {
+    # 7 → 8 (nearest Fibonacci), 100 → 89, 50 → 55 (or 34, depends on
+    # tiebreaker; just check the output is on an attractor).
+    h folded = arr_fold_all([7, 100, 9, 22]);
+    # All elements should be Fibonacci attractors after folding.
+    h all_attractors = 1;
+    h i = 0;
+    while i < arr_len(folded) {
+        if is_attractor(arr_get(folded, i)) == 0 {
+            all_attractors = 0;
+        }
+        i = i + 1;
+    }
+    assert_eq(all_attractors, 1, "all folded elements on attractors");
+}
+
+# ---- Composition: ML-shaped pipeline ----
+
+fn test_pipeline_substrate_aware_features() {
+    # Simulate a feature-engineering pipeline:
+    #   1. Take raw counts
+    #   2. Scale by a constant
+    #   3. Add a per-sample bias
+    #   4. Fold to substrate-aligned buckets
+    #   5. Score by mean resonance — high resonance = substrate-coherent
+    h raw = [3, 5, 8, 13, 21, 34];   # Fibonacci already
+    h scaled = arr_scale(raw, 2);     # [6, 10, 16, 26, 42, 68]
+    h biased = arr_add(scaled, 1);    # [7, 11, 17, 27, 43, 69]
+    h folded = arr_fold_all(biased);  # snap to nearest attractors
+    h resonance = arr_resonance_vec(folded);
+    # Sum of resonances; for fully substrate-aligned data, ~6.0
+    h s = 0.0;
+    h i = 0;
+    while i < arr_len(resonance) {
+        s = s + arr_get(resonance, i);
+        i = i + 1;
+    }
+    assert_true(s > 5.5, "pipeline output stays substrate-coherent");
+}
+
+# ---- Composition with existing reductions ----
+
+fn test_arr_add_then_sum() {
+    h c = arr_add([1, 2, 3], [10, 20, 30]);
+    assert_eq(arr_sum_int(c), 66, "sum after element-wise add");
+}
+
+fn test_arr_mul_then_dot() {
+    # Square via element-wise mul, then dot-with-ones for sum-of-squares.
+    h v = [3, 4, 5];
+    h squared = arr_mul(v, v);  # [9, 16, 25]
+    assert_eq(arr_sum_int(squared), 50, "sum of squares 3,4,5");
+}

omnimcode-core/src/interpreter.rs

@@ -2003,6 +2003,9 @@ impl Interpreter {
             | "arr_argmax" | "arr_argmin" | "arr_cumsum" | "arr_diff" | "arr_range"
             | "arr_unique_count" | "arr_partition_by"
             | "arr_min_float" | "arr_max_float" | "arr_gcd" | "fnv1a_hash"
+            // Substrate-typed array library
+            | "arr_add" | "arr_sub" | "arr_mul" | "arr_div_int" | "arr_neg"
+            | "arr_scale" | "arr_resonance_vec" | "arr_him_vec" | "arr_fold_all"
             | "arr_mean" | "arr_variance" | "arr_stddev" | "arr_median"
             | "arr_harmonic_mean" | "arr_geometric_mean"
             | "arr_sum_sq" | "arr_norm" | "arr_dot"
@@ -5385,6 +5388,143 @@ impl Interpreter {
                     Err("arr_dot: requires two arrays".to_string())
                 }
             }
+            // ---- Substrate-typed array library (Track 2 MVP) -------
+            //
+            // Vectorized arithmetic + substrate-aware reductions on
+            // arrays of HInt. The dispatch boundary marshals int
+            // arrays through the L1.6 buffer; these handlers produce
+            // new arrays element-wise (so the substrate-resonance
+            // metadata on each output HInt is recomputed from the
+            // arithmetic result — no special tagging needed).
+            //
+            // Broadcasting: if the 2nd arg is a scalar (HInt / HFloat),
+            // it's repeated for every element of the 1st arg's array.
+            // Two arrays must match length (no implicit shape-1 broadcast).
+            "arr_add" => {
+                if args.len() < 2 {
+                    return Err("arr_add requires (a, b)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                let b = self.eval_expr(&args[1])?;
+                Ok(elementwise_op(&a, &b, "arr_add", |x, y| x.wrapping_add(y))?)
+            }
+            "arr_sub" => {
+                if args.len() < 2 {
+                    return Err("arr_sub requires (a, b)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                let b = self.eval_expr(&args[1])?;
+                Ok(elementwise_op(&a, &b, "arr_sub", |x, y| x.wrapping_sub(y))?)
+            }
+            "arr_mul" => {
+                if args.len() < 2 {
+                    return Err("arr_mul requires (a, b)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                let b = self.eval_expr(&args[1])?;
+                Ok(elementwise_op(&a, &b, "arr_mul", |x, y| x.wrapping_mul(y))?)
+            }
+            "arr_div_int" => {
+                // Integer division. Zero divisor produces 0 in that
+                // slot (matches harmonic_anomaly-style "no propagation
+                // of NaN through arrays" — Singularity is at the value
+                // level, not the array level).
+                if args.len() < 2 {
+                    return Err("arr_div_int requires (a, b)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                let b = self.eval_expr(&args[1])?;
+                Ok(elementwise_op(&a, &b, "arr_div_int",
+                    |x, y| if y == 0 { 0 } else { x / y })?)
+            }
+            "arr_neg" => {
+                // Unary element-wise negation.
+                if args.is_empty() {
+                    return Err("arr_neg requires (array)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                if let Value::Array(arr) = a {
+                    let out: Vec<Value> = arr.items.borrow().iter()
+                        .map(|v| Value::HInt(HInt::new(v.to_int().wrapping_neg())))
+                        .collect();
+                    Ok(Value::Array(HArray::from_vec(out)))
+                } else {
+                    Err("arr_neg: requires an array".to_string())
+                }
+            }
+            "arr_scale" => {
+                // arr_scale(arr, k) — explicit scalar multiply. Same as
+                // arr_mul(arr, k) when k is a scalar; provided as a
+                // named alias so callers can opt into the broadcast
+                // shape without it being inferred.
+                if args.len() < 2 {
+                    return Err("arr_scale requires (array, scalar)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                let k = self.eval_expr(&args[1])?;
+                Ok(elementwise_op(&a, &k, "arr_scale", |x, y| x.wrapping_mul(y))?)
+            }
+            // arr_resonance_vec(arr) -> array of f64 per-element
+            // resonance scores. The substrate-typed dtype's defining
+            // operation: each output element is HInt::compute_resonance
+            // of the corresponding input. Python literally can't do
+            // this — there's no φ-resonance attached to an i64.
+            "arr_resonance_vec" => {
+                if args.is_empty() {
+                    return Err("arr_resonance_vec requires (array)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                if let Value::Array(arr) = a {
+                    let out: Vec<Value> = arr.items.borrow().iter()
+                        .map(|v| Value::HFloat(HInt::compute_resonance(v.to_int())))
+                        .collect();
+                    Ok(Value::Array(HArray::from_vec(out)))
+                } else {
+                    Err("arr_resonance_vec: requires an array".to_string())
+                }
+            }
+            // arr_him_vec(arr) -> array of f64 per-element HIM scores.
+            // Complement to arr_resonance_vec: HIM is the
+            // Harmonic-Interference-Metric — how off-attractor each
+            // value is. Together with resonance, these are the two
+            // substrate-typed metadata channels carried per-element.
+            "arr_him_vec" => {
+                if args.is_empty() {
+                    return Err("arr_him_vec requires (array)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                if let Value::Array(arr) = a {
+                    let out: Vec<Value> = arr.items.borrow().iter()
+                        .map(|v| {
+                            let h = HInt::new(v.to_int());
+                            Value::HFloat(h.him_score)
+                        })
+                        .collect();
+                    Ok(Value::Array(HArray::from_vec(out)))
+                } else {
+                    Err("arr_him_vec: requires an array".to_string())
+                }
+            }
+            // arr_fold_all(arr) -> new array with every element snapped
+            // to its nearest Fibonacci attractor. Vectorized fold.
+            // Substrate-canonical denoising / quantization primitive.
+            "arr_fold_all" => {
+                if args.is_empty() {
+                    return Err("arr_fold_all requires (array)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?;
+                if let Value::Array(arr) = a {
+                    let out: Vec<Value> = arr.items.borrow().iter()
+                        .map(|v| {
+                            let folded = crate::phi_pi_fib::fold_to_nearest_attractor(v.to_int());
+                            Value::HInt(HInt::new(folded))
+                        })
+                        .collect();
+                    Ok(Value::Array(HArray::from_vec(out)))
+                } else {
+                    Err("arr_fold_all: requires an array".to_string())
+                }
+            }
             "arr_concat" => {
                 if args.len() < 2 {
                     return Err("arr_concat requires (array_a, array_b)".to_string());
@@ -7739,6 +7879,51 @@ fn values_equal(a: &Value, b: &Value) -> bool {
 
 // Free function reused by quantize / quantization_ratio / mean_omni_weight.
 // Snap |n| to the nearest Fibonacci attractor, preserving sign.
+/// Track-2 substrate-typed-array helper: element-wise binary op
+/// over (array, array) or (array, scalar). Scalar broadcasts to
+/// every position of the array. Two-array length mismatch is an
+/// error (no implicit shape-1 expansion — keeps behavior obvious).
+/// `op` takes (i64, i64) and returns i64; the helper wraps the
+/// result in HInt so per-element substrate resonance gets recomputed
+/// from the arithmetic output.
+pub(crate) fn elementwise_op<F: Fn(i64, i64) -> i64>(
+    a: &Value,
+    b: &Value,
+    name: &str,
+    op: F,
+) -> Result<Value, String> {
+    match (a, b) {
+        (Value::Array(arr_a), Value::Array(arr_b)) => {
+            let ai = arr_a.items.borrow();
+            let bi = arr_b.items.borrow();
+            if ai.len() != bi.len() {
+                return Err(format!(
+                    "{}: length mismatch ({} vs {})", name, ai.len(), bi.len()
+                ));
+            }
+            let out: Vec<Value> = ai.iter().zip(bi.iter())
+                .map(|(x, y)| Value::HInt(HInt::new(op(x.to_int(), y.to_int()))))
+                .collect();
+            Ok(Value::Array(HArray::from_vec(out)))
+        }
+        (Value::Array(arr_a), scalar) => {
+            let sv = scalar.to_int();
+            let out: Vec<Value> = arr_a.items.borrow().iter()
+                .map(|x| Value::HInt(HInt::new(op(x.to_int(), sv))))
+                .collect();
+            Ok(Value::Array(HArray::from_vec(out)))
+        }
+        (scalar, Value::Array(arr_b)) => {
+            let sv = scalar.to_int();
+            let out: Vec<Value> = arr_b.items.borrow().iter()
+                .map(|y| Value::HInt(HInt::new(op(sv, y.to_int()))))
+                .collect();
+            Ok(Value::Array(HArray::from_vec(out)))
+        }
+        _ => Err(format!("{}: requires at least one array argument", name)),
+    }
+}
+
 /// Convert a `serde_json::Value` into an OMC `Value`. JSON object →
 /// `Value::Dict`, JSON array → `Value::Array`, numbers split into
 /// `HInt` (when representable as i64) vs `HFloat` (everything else).
@@ -8194,6 +8379,8 @@ pub(crate) const HEAL_BUILTIN_NAMES: &[&str] = &[
     "arr_argmax", "arr_argmin", "arr_cumsum", "arr_diff", "arr_range",
     "arr_unique_count", "arr_partition_by",
     "arr_min_float", "arr_max_float", "arr_gcd", "fnv1a_hash",
+    "arr_add", "arr_sub", "arr_mul", "arr_div_int", "arr_neg",
+    "arr_scale", "arr_resonance_vec", "arr_him_vec", "arr_fold_all",
     "arr_mean", "arr_variance", "arr_stddev", "arr_median",
     "arr_harmonic_mean", "arr_geometric_mean",
     "arr_sum_sq", "arr_norm", "arr_dot",