el/lang/examples/transduce.el

// transduce.el — geometry as a first-class El value, and a realizer written
// in El. Runnable: this is the worked example for the transduce surface, and
// it doubles as an executable proof because it checks every claim it makes.
//
//   elc lang/examples/transduce.el > transduce.c
//   cc -std=c11 -O2 -I lang/runtime -o transduce transduce.c \
//      lang/runtime/el_runtime.c lang/runtime/el_seed.c \
//      lang/runtime/engram_*.c -lcurl -lpthread -lm
//   ./transduce          # exits 0 only if every check passes
//
// (A `test "..."` form of the same checks lives in
// lang/tests/native/test_transduce.el, for when the native harness is
// repaired — the shipped elc currently emits calls to __el_reg_count and
// friends without emitting their definitions, which breaks every native test
// equally, test_math.el included. Verified 2026-08-16, unrelated to this work.)
//
// WHY THIS EXISTS. Until 2026-08-16 no El ingest path could carry a vector:
// nodes took text, and geometry was DERIVED from that text. Text was the
// mandatory entry medium, so any non-text modality had to be DESCRIBED in
// prose first and the geometry we reasoned over was the geometry OF THE
// DESCRIPTION, not of the signal. Two things fix that, and both are shown
// below: geometry is a VALUE that carries its own width, and a REALIZER is an
// ordinary El function — so admitting a new modality never requires a runtime
// patch.
//
// COMPARISON DISCIPLINE (measured, not stylistic): elc lowers `a == b`
// numerically only when both operand NAMES are in the per-function int-name
// set that `let x: Int` populates. A bare `f(x) == 0` is not a registered
// name and lowers to str_eq — strcmp on two integers as pointers. `<` and `>`
// lower directly with no inference, so truthiness is written `> 0` / `< 1`.

// ── A realizer, written entirely in El ──────────────────────────────────────
// Not in the runtime. Not known to the compiler. Registered by NAME and
// dispatched to through transduce(). That is the whole claim.
fn tone_realizer(signal: String) -> Geometry {
    let g: Geometry = geometry_new(4)
    let n: Int = str_len(signal)
    let a: Int = geometry_set(g, 0, int_to_float(n))
    let b: Int = geometry_set(g, 1, int_to_float(n * 2))
    let c: Int = geometry_set(g, 2, int_to_float(n * 3))
    let d: Int = geometry_set(g, 3, int_to_float(n * 4))
    g
}

// A second modality, to show the registry keys on modality rather than just
// returning whatever was registered last.
fn pulse_realizer(signal: String) -> Geometry {
    let g: Geometry = geometry_new(2)
    let a: Int = geometry_set(g, 0, 1.0)
    let b: Int = geometry_set(g, 1, 0.0)
    g
}

// A deliberately BROKEN realizer: returns something that is not a Geometry.
fn bogus_realizer(signal: String) -> Geometry {
    return 12345
}

// Fails FAST rather than accumulating a count, for a measured reason: a first
// cut wrote `let fails: Int = fails + check(...)` and `+` lowered to STRING
// CONCAT, because elc dispatches `+` on whether both operands are known-Int and
// a user-defined fn call is not — so the counter printed 4343632752, a pointer.
// Nothing was wrong with the checks; the tally was lying. Exiting at the first
// failure needs no arithmetic at all, so there is nothing left to get wrong.
fn check(ok: Int, label: String) -> Int {
    if ok > 0 {
        println("  ok    " + label)
        return 0
    }
    println("  FAIL  " + label)
    exit(1)
    return 1
}

fn near(a: Float, b: Float) -> Int {
    let d: Float = a - b
    if d > 0.001 { return 0 }
    if d < -0.001 { return 0 }
    return 1
}

fn eq_int(a: Int, b: Int) -> Int {
    if a == b { return 1 }
    return 0
}

fn main() -> Void {
    println("geometry is a value that carries its own width")
    let g8: Geometry = geometry_new(8)
    let _c: Int = check(geometry_is(g8), "geometry_new returns a live Geometry")
    let d8: Int = geometry_dim(g8)
    let _c: Int = check(eq_int(d8, 8), "a Geometry carries its own width (8)")
    let _c: Int = check(geometry_free(g8), "geometry_free reports what it did")

    println("nonsense is refused — with no arbitrary max-dim bound")
    // #141 needed `dim <= 8192` only to bound an allocation sized from a
    // caller's CLAIM about a string's length. A value that carries its own
    // width has nothing left to validate.
    let z: Geometry = geometry_new(0)
    let zi: Int = geometry_is(z)
    let _c: Int = check(1 - zi, "dim 0 is not a geometry")
    let ng: Geometry = geometry_new(-4)
    let ngi: Int = geometry_is(ng)
    let _c: Int = check(1 - ngi, "negative dim is not a geometry")
    let nd: Int = geometry_dim(0)
    let _c: Int = check(1 - nd, "geometry_dim of a non-geometry is 0, not a crash")
    let nf: Int = geometry_free(0)
    let _c: Int = check(1 - nf, "geometry_free of a non-geometry is a no-op")

    println("components round-trip, and out-of-range is refused")
    let g3: Geometry = geometry_new(3)
    let s0: Int = geometry_set(g3, 0, 1.5)
    let s1: Int = geometry_set(g3, 1, -2.5)
    let _c: Int = check(s0, "set in range succeeds")
    let oob: Int = geometry_set(g3, 3, 9.0)
    let _c: Int = check(1 - oob, "set out of range is refused, not silently dropped")
    let _c: Int = check(near(geometry_get(g3, 0), 1.5), "component 0 round-trips")
    let _c: Int = check(near(geometry_get(g3, 1), -2.5), "component 1 round-trips (negative)")
    let ff3: Int = geometry_free(g3)

    println("hex is an EDGE adapter, and derives its own width")
    // little-endian float32: 1.0 = 0000803f, 2.0 = 00000040
    let gh: Geometry = geometry_from_f32le_hex("0000803f00000040")
    let _c: Int = check(geometry_is(gh), "valid hex decodes to a Geometry")
    let dh: Int = geometry_dim(gh)
    let _c: Int = check(eq_int(dh, 2), "width DERIVED from input, never supplied")
    let _c: Int = check(near(geometry_get(gh, 0), 1.0), "first component decoded")
    let _c: Int = check(near(geometry_get(gh, 1), 2.0), "second component decoded")
    let back: String = geometry_to_f32le_hex(gh)
    let _c: Int = check(str_eq(back, "0000803f00000040"), "hex round-trips exactly")
    let ffh: Int = geometry_free(gh)

    println("malformed hex is refused")
    let he: Geometry = geometry_from_f32le_hex("")
    let hei: Int = geometry_is(he)
    let _c: Int = check(1 - hei, "empty hex is not a geometry")
    let hr: Geometry = geometry_from_f32le_hex("0000803f0000")
    let hri: Int = geometry_is(hr)
    let _c: Int = check(1 - hri, "length not a multiple of 8 is refused")
    let hn: Geometry = geometry_from_f32le_hex("zzzzzzzz")
    let hni: Int = geometry_is(hn)
    let _c: Int = check(1 - hni, "non-hex characters are refused")

    println("a realizer declared in El is a first-class realizer")
    let reg: Int = realizer_register("tone", "tone_realizer")
    let _c: Int = check(reg, "an El fn registers as a realizer BY NAME")
    let _c: Int = check(realizer_has("tone"), "the modality now has an organ")
    let gt: Geometry = transduce("aaa", "tone")
    let _c: Int = check(geometry_is(gt), "transduce returns real geometry")
    let dt: Int = geometry_dim(gt)
    let _c: Int = check(eq_int(dt, 4), "the El realizer determined the width, not the runtime")
    // str_len("aaa") == 3, so component 0 must be 3.0 — proof the signal
    // actually reached the El function rather than a stub answering for it.
    let _c: Int = check(near(geometry_get(gt, 0), 3.0), "the signal REACHED the El realizer")
    let fft: Int = geometry_free(gt)

    println("distinct signals transduce to distinct geometry")
    let g1: Geometry = transduce("aa", "tone")
    let g2: Geometry = transduce("aaaaa", "tone")
    let a1: Float = geometry_get(g1, 0)
    let a2: Float = geometry_get(g2, 0)
    // 5 - 2 = 3. If transduction were a stub these would be equal.
    let _c: Int = check(near(a2 - a1, 3.0), "different signals produce different geometry")
    let ff1: Int = geometry_free(g1)
    let ff2: Int = geometry_free(g2)

    println("the registry keys on modality")
    let r2: Int = realizer_register("pulse", "pulse_realizer")
    let _c: Int = check(r2, "a second modality registers independently")
    let mt: Geometry = transduce("aaa", "tone")
    let mp: Geometry = transduce("aaa", "pulse")
    let mdt: Int = geometry_dim(mt)
    let mdp: Int = geometry_dim(mp)
    let _c: Int = check(eq_int(mdt, 4), "tone still routes to its own realizer")
    let _c: Int = check(eq_int(mdp, 2), "pulse routes to a different realizer")
    let ffm1: Int = geometry_free(mt)
    let ffm2: Int = geometry_free(mp)

    println("no organ is reported as no organ")
    // A modality with no realizer must transduce to NOTHING. It must never
    // fall back to embedding a description of the signal and calling that
    // perception — that silent substitution is the defect this all exists to end.
    let eh: Int = realizer_has("echolocation")
    let _c: Int = check(1 - eh, "unregistered modality has no organ")
    let ge: Geometry = transduce("anything", "echolocation")
    let gei: Int = geometry_is(ge)
    let _c: Int = check(1 - gei, "no realizer means NO geometry, not fake geometry")

    println("an unresolvable realizer name fails at WIRING time")
    let bad: Int = realizer_register("ghost", "no_such_function_anywhere")
    let _c: Int = check(1 - bad, "unresolvable realizer name is a registration failure")
    let gh2: Int = realizer_has("ghost")
    let _c: Int = check(1 - gh2, "and nothing gets registered")

    println("a realizer returning non-geometry transduces nothing")
    let rb: Int = realizer_register("bogus", "bogus_realizer")
    let _c: Int = check(rb, "the symbol resolves, so registration succeeds")
    let gb: Geometry = transduce("x", "bogus")
    let gbi: Int = geometry_is(gb)
    let _c: Int = check(1 - gbi, "contract enforced at the boundary: nothing handed back")

    println("norm lets a caller check a realizer emitted signal, not zeros")
    let gn: Geometry = geometry_new(2)
    let _c: Int = check(near(geometry_norm(gn), 0.0), "a fresh geometry is zero — norm says so")
    let n0: Int = geometry_set(gn, 0, 3.0)
    let n1: Int = geometry_set(gn, 1, 4.0)
    let _c: Int = check(near(geometry_norm(gn), 5.0), "3-4-5: norm is 5")
    let ffn: Int = geometry_free(gn)

    // Reaching here means nothing called exit(1) along the way.
    println("")
    println("all checks passed")
}