onn: ChildFold + geodesic expansion (Sovereign Lattice port)

RandomCoder-lab · claude · RandomCoder-lab · commit f8623d4bdee7 · 2026-05-16T17:42:09.000-05:00
After exploring /home/thearchitect/Sovereign_Lattice/omninet_package/
the user pointed at, ported the load-bearing primitive from
register_singularity_integration.py — the ChildFold mechanism that
expands a single high-tension register seed into a deterministic
boundary-exploration subspace.

New primitives:

  omc_spawn_child_fold(seed, reason?) -&gt; dict
    Deterministic ChildFold from any HInt seed. Returns the same
    seven-field dict (fold_id, focus_numerator, focus_denominator,
    spawn_reason, resonance_target, explored_value, final_resonance)
    that the Sovereign Lattice OmniRegister would produce when its
    tension exceeded 1/φ.

  omc_geodesic_expand(seed, n_samples) -&gt; [[value, resonance], ...]
    Walks the φ-field geodesic from seed toward its nearest Fibonacci
    attractor in n equal steps. Deterministic. Each sample carries
    substrate metadata. The "replicate from a single token" idea
    formalized as a substrate-anchored walk.

GEODESIC_RECONSTRUCTION_NOTES.md is the honest writeup:

  What this IS:
    - deterministic per seed (no randomness)
    - substrate-anchored (every output is HInt-typed)
    - bounded (ChildFold O(1), expand O(n))
    - composable (feed explored_value back as new seed)

  What this IS NOT:
    - semantic decompression of arbitrary text (i64 has 64 bits of
      entropy; can't materialize 1KB payloads without a learned
      generative model)
    - the PyTorch tensor reconstruction the user mentioned —
      that's a future research project; what we built is the
      deterministic backbone a learned model would condition on
    - a context-window solver on its own; it's a building block

  What it's USEFUL FOR (concretely):
    - reproducible substrate-anchored pseudo-random sequences
    - compressed message acknowledgements (send seed, receiver
      runs same fold, dict matches)
    - substrate-driven loop unrolling at tension boundaries

Tests: 10 OMC cases covering deterministic per-seed, different
seeds → different folds, focus_numerator on attractor, 7→8 case,
final_resonance ≈ 1.0 at landing, geodesic length / pair shape /
zero-samples / determinism / resonance range.

Verdict on the user's broader claim: the substrate primitives
needed to CONDITION a learned tensor-reconstruction model now
exist. The learned model itself is a separate (multi-week)
research project I can't build in this session.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/OMC_REFERENCE.md b/OMC_REFERENCE.md
@@ -2,9 +2,9 @@
 
 Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFERENCE.md` to regenerate.
 
-**Total documented builtins**: 639
+**Total documented builtins**: 641
 
-**OMC-unique**: 72 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
+**OMC-unique**: 74 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
 
 ---
 
@@ -53,7 +53,7 @@ Other high-value calls: `omc_unique_builtins()` (the OMC-only surface), `omc_pyt
 - [tokenizer](#tokenizer) (17 builtins)
 - [code_intel](#code_intel) (17 builtins)
 - [messaging](#messaging) (5 builtins)
-- [onn](#onn) (5 builtins)
+- [onn](#onn) (7 builtins)
 - [llm_workflow](#llm_workflow) (7 builtins)
 - [math](#math) (82 builtins)
 - [dicts](#dicts) (31 builtins)
@@ -5094,6 +5094,26 @@ Orchestration primitive: compress context to M3(N) specialists, write each as a
 omc_llm_self_instantiate(history, "refactor X", "/tmp/spawn", 18173)  // [{prompt_path, mu, sigma, ...}]
 ```
 
+### `omc_spawn_child_fold` 🔱 *OMC-unique*
+
+**Signature**: `(seed: int, reason?: string) -> dict`
+
+Ported from Sovereign_Lattice register_singularity_integration. Given any HInt seed, deterministically produce a ChildFold = the boundary exploration a parent register would have performed at tension > 1/φ. Returns {fold_id, focus_numerator, focus_denominator, spawn_reason, resonance_target, explored_value, final_resonance}.
+
+```omc
+omc_spawn_child_fold(7, "tension exceeded")  // explores 7→8 boundary
+```
+
+### `omc_geodesic_expand` 🔱 *OMC-unique*
+
+**Signature**: `(seed: int, n_samples: int) -> [[value, resonance], ...]`
+
+Walk the φ-field geodesic from `seed` toward its nearest Fibonacci attractor in n equal steps. Each sample is a (value, resonance) pair. Deterministic. Geometric (not semantic) reconstruction from a single substrate-anchored seed.
+
+```omc
+omc_geodesic_expand(7, 5)  // 5 samples along path 7 → 8
+```
+
 ---
 
 ## llm_workflow
diff --git a/examples/demos/GEODESIC_RECONSTRUCTION_NOTES.md b/examples/demos/GEODESIC_RECONSTRUCTION_NOTES.md
@@ -0,0 +1,154 @@
+# Geodesic Reconstruction from Singular Tokens — what's real vs aspirational
+
+## What the user pointed at
+
+> "in /home/thearchitect/thesoverignlattice [...] using the Geodesic
+> tensor data through pytorch, you could replicate entire forms of
+> compressed data from singular tokens."
+
+## What's actually in the lattice
+
+Found at `/home/thearchitect/Sovereign_Lattice/omninet_package/`. Two
+load-bearing concepts that map onto this claim:
+
+### 1. "Programs are geodesics through curved φ-field geometry"
+   - From `docs/reference/OMNICODE_COMPLETE_REFERENCE.md` and
+     `OMNICPU_ROADMAP.md`
+   - Bugs = high-curvature regions
+   - Optimization = straightening the path
+   - Code quality = geometric smoothness
+
+### 2. `ChildFold` spawning from `register_singularity_integration.py`
+   - Triggered when an OmniRegister's tension exceeds `1/φ ≈ 0.618`
+   - Each ChildFold has:
+     - `focus_region: (numerator, denominator)` — the singular point
+     - `operation` — what triggered it
+     - `resonance_target` — what φ-state to drive toward
+   - `explore_boundary()` folds the numerator to its nearest Fibonacci
+     attractor (the "boundary resolution")
+   - **Reports back to parent** — the fold-back loop we already have
+
+This is the concrete mechanism behind "expand from a single token."
+A single high-tension register value carries enough state (via its
+nearest-attractor + distance-to-attractor pair) to deterministically
+reconstruct a *small computation* — the ChildFold.
+
+## What I built
+
+Two new OMC builtins port the mechanism:
+
+### `omc_spawn_child_fold(seed, reason?)`
+Deterministic ChildFold from any HInt seed. Returns a dict carrying:
+- `fold_id` — stable hash of seed
+- `focus_numerator` — nearest Fibonacci attractor (the "boundary")
+- `focus_denominator` — distance to that attractor
+- `spawn_reason` — what triggered the fold
+- `resonance_target` — `1/(1 + distance)`
+- `explored_value` — fold result
+- `final_resonance` — substrate metadata of the result
+
+Example: `omc_spawn_child_fold(7, "x")` → numerator=8, denominator=1,
+explored_value=8, final_resonance≈1.0. The seed `7` (which has
+resonance < 1) expanded into a deterministic computational
+subspace where the boundary at 8 (resonance = 1.0) is reached.
+
+### `omc_geodesic_expand(seed, n_samples)`
+Walks the φ-field geodesic from `seed` toward its attractor in
+`n` equal steps. Each sample is `(value, resonance)`. Deterministic.
+
+This is the operationalized "replicate from a singular token":
+a single seed determines an N-element trace through substrate
+space. Same seed always reproduces the same trace.
+
+## Honest framing — what this IS
+
+- **Deterministic per seed**: given the seed integer, anyone can
+  reconstruct the same ChildFold or geodesic walk. No randomness.
+- **Substrate-anchored**: every output value carries its own
+  resonance/HIM metadata via HInt.
+- **Bounded**: ChildFold is O(1); geodesic_expand is O(n).
+- **Composable**: feed the explored_value back as a new seed to
+  spawn another fold — recursive ChildFold towers.
+
+## Honest framing — what this IS NOT
+
+- **Not semantic decompression of arbitrary text.** The user's
+  "replicate entire forms of compressed data from singular tokens"
+  phrasing reaches further than what's implementable here. A single
+  i64 carries log2(2^64) = 64 bits of entropy maximum. You cannot
+  reconstruct an arbitrary 1KB payload from a 64-bit seed without
+  either (a) the seed being a cryptographic hash that indexes into
+  a lookup table the receiver already has, or (b) the receiver
+  having a generative model that was trained to expand seeds into
+  payloads.
+- **Not the PyTorch tensor reconstruction.** The lattice docs
+  reference "Geodesic tensor data through pytorch" but the actual
+  Python code I found does fold-escape over scalars, not tensor
+  reconstruction. The tensor-reconstruction claim may be a future
+  goal or in a file I didn't find.
+- **Not a context-window solver on its own.** What it IS is the
+  primitive an LLM could use *together* with a learned expansion
+  model — the seed becomes a deterministic compressed handle into
+  the model's parameter space. That's a different (and bigger)
+  project than substrate primitives alone.
+
+## What this is useful for, concretely
+
+1. **Stable pseudo-random sequences anchored at a substrate-meaningful
+   start**: `omc_geodesic_expand(known_seed, N)` always produces the
+   same N-element trace. Useful for reproducible experiments,
+   deterministic randomization in tests.
+
+2. **Compressed message acknowledgements**: instead of echoing back
+   a full payload, send `omc_spawn_child_fold(content_hash, reason)`
+   — receiver runs the same fold and verifies the dict matches.
+   Few bytes; full integrity.
+
+3. **Substrate-driven loop unrolling**: given a tight loop with
+   tension at iteration boundary, spawn a ChildFold to explore the
+   boundary value deterministically. That's the recursive-orchestrator
+   pattern in the Hermes ONN docs.
+
+## Connection to PyTorch tensor reconstruction (speculative)
+
+The bigger claim — *"using the Geodesic tensor data through PyTorch
+you could replicate entire forms of compressed data from singular
+tokens"* — would require:
+
+1. A learned generative model (transformer or otherwise) that takes
+   a substrate-typed seed as conditioning and produces a tensor
+   payload.
+2. Training the model to invert: given the original tensor, find
+   the seed whose geodesic-expansion best approximates it.
+3. Using the substrate primitives we ALREADY have as the conditioning
+   layer.
+
+That's a meaningful follow-on research project. The substrate
+primitives (canonical hash, fold-back, geodesic expansion) are the
+deterministic backbone; the learned model is the lossy-decompression
+layer. Together they'd give "tensor expansion from a single seed."
+
+I can't build the learned model in this session — but the
+deterministic primitives needed to *condition* one now exist.
+
+## Files
+
+| Path | Purpose |
+|------|---------|
+| `omnimcode-core/src/onn.rs` | `ChildFold`, `spawn_child_fold`, `geodesic_expand` |
+| `examples/tests/test_geodesic.omc` | 10 tests, all green |
+| `examples/demos/GEODESIC_RECONSTRUCTION_NOTES.md` | This file |
+
+## Verdict
+
+Built the deterministic substrate backbone of single-token
+reconstruction. Honest about what it isn't: it isn't a learned
+generative model, and you can't pull arbitrary 1KB payloads out
+of a 64-bit seed without one. What you CAN do is reproduce a
+substrate-anchored trace deterministically — useful for
+acknowledgements, reproducible tests, and as the conditioning
+layer for a future learned model.
+
+The path from "substrate primitives" to "tensor expansion from
+single seeds" is real, but it crosses a learned-model boundary
+this session can't cross alone.
diff --git a/examples/tests/test_geodesic.omc b/examples/tests/test_geodesic.omc
@@ -0,0 +1,92 @@
+# ChildFold / geodesic-expand tests (Sovereign Lattice port).
+
+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); } }
+
+# ChildFold deterministic per seed
+fn test_child_fold_deterministic() {
+    h a = omc_spawn_child_fold(7, "test");
+    h b = omc_spawn_child_fold(7, "test");
+    assert_eq(dict_get(a, "fold_id"), dict_get(b, "fold_id"), "same seed → same id");
+    assert_eq(dict_get(a, "explored_value"), dict_get(b, "explored_value"), "same exploration");
+}
+
+# Different seeds → different folds
+fn test_child_fold_different_seeds() {
+    h a = omc_spawn_child_fold(7, "x");
+    h b = omc_spawn_child_fold(100, "x");
+    assert_true(dict_get(a, "fold_id") != dict_get(b, "fold_id"), "differ");
+}
+
+# focus_numerator is a Fibonacci attractor
+fn test_child_fold_numerator_is_attractor() {
+    h cf = omc_spawn_child_fold(7, "x");
+    h num = dict_get(cf, "focus_numerator");
+    assert_eq(is_attractor(num), 1, "numerator on attractor");
+}
+
+# 7 folds to 8 (nearest Fib)
+fn test_child_fold_7_to_8() {
+    h cf = omc_spawn_child_fold(7, "x");
+    assert_eq(dict_get(cf, "focus_numerator"), 8, "7 → 8");
+    assert_eq(dict_get(cf, "focus_denominator"), 1, "distance 1");
+}
+
+# final_resonance ~ 1.0 since we land on an attractor
+fn test_child_fold_final_resonance_high() {
+    h cf = omc_spawn_child_fold(7, "x");
+    h r = dict_get(cf, "final_resonance");
+    h diff = r - 1.0;
+    if diff < 0.0 { diff = 0.0 - diff; }
+    assert_true(diff < 0.01, "lands on attractor");
+}
+
+# Geodesic expand basic
+fn test_geodesic_basic_length() {
+    h samples = omc_geodesic_expand(7, 5);
+    assert_eq(arr_len(samples), 5, "5 samples");
+}
+
+# Geodesic returns pairs
+fn test_geodesic_returns_pairs() {
+    h samples = omc_geodesic_expand(7, 3);
+    h first = arr_get(samples, 0);
+    assert_eq(arr_len(first), 2, "[value, resonance]");
+}
+
+# Zero samples returns empty
+fn test_geodesic_zero() {
+    h samples = omc_geodesic_expand(7, 0);
+    assert_eq(arr_len(samples), 0, "n=0 → empty");
+}
+
+# Geodesic deterministic
+fn test_geodesic_deterministic() {
+    h a = omc_geodesic_expand(42, 4);
+    h b = omc_geodesic_expand(42, 4);
+    h i = 0;
+    while i < arr_len(a) {
+        h pa = arr_get(a, i);
+        h pb = arr_get(b, i);
+        assert_eq(arr_get(pa, 0), arr_get(pb, 0), concat_many("val ", to_string(i)));
+        i = i + 1;
+    }
+}
+
+# Each sample is HInt — resonance in [0, 1]
+fn test_geodesic_resonance_in_range() {
+    h samples = omc_geodesic_expand(50, 10);
+    h i = 0;
+    while i < arr_len(samples) {
+        h s = arr_get(samples, i);
+        h r = arr_get(s, 1);
+        assert_true(r >= 0.0, concat_many("r ", to_string(i), " >= 0"));
+        assert_true(r <= 1.0, concat_many("r ", to_string(i), " <= 1"));
+        i = i + 1;
+    }
+}
diff --git a/omnimcode-core/src/compiler.rs b/omnimcode-core/src/compiler.rs
@@ -303,6 +303,7 @@ impl Compiler {
                         | "omc_find_similar"
                         | "omc_self_instantiate" | "omc_context_compress"
                         | "omc_llm_self_instantiate"
+                        | "omc_geodesic_expand"
                         // Forward-mode autograd duals (Track 2 — 2026-05-16)
                         | "dual" | "dual_add" | "dual_sub"
                         | "dual_mul" | "dual_div" | "dual_neg"
diff --git a/omnimcode-core/src/docs.rs b/omnimcode-core/src/docs.rs
@@ -1152,6 +1152,20 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         example: "omc_llm_self_instantiate(history, \"refactor X\", \"/tmp/spawn\", 18173)  // [{prompt_path, mu, sigma, ...}]",
         unique_to_omc: true,
     },
+    BuiltinDoc {
+        name: "omc_spawn_child_fold", category: "onn",
+        signature: "(seed: int, reason?: string) -> dict",
+        description: "Ported from Sovereign_Lattice register_singularity_integration. Given any HInt seed, deterministically produce a ChildFold = the boundary exploration a parent register would have performed at tension > 1/φ. Returns {fold_id, focus_numerator, focus_denominator, spawn_reason, resonance_target, explored_value, final_resonance}.",
+        example: "omc_spawn_child_fold(7, \"tension exceeded\")  // explores 7→8 boundary",
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "omc_geodesic_expand", category: "onn",
+        signature: "(seed: int, n_samples: int) -> [[value, resonance], ...]",
+        description: "Walk the φ-field geodesic from `seed` toward its nearest Fibonacci attractor in n equal steps. Each sample is a (value, resonance) pair. Deterministic. Geometric (not semantic) reconstruction from a single substrate-anchored seed.",
+        example: "omc_geodesic_expand(7, 5)  // 5 samples along path 7 → 8",
+        unique_to_omc: true,
+    },
     // ---- LLM workflow bundles ----
     BuiltinDoc {
         name: "omc_cheatsheet", category: "llm_workflow",
diff --git a/omnimcode-core/src/interpreter.rs b/omnimcode-core/src/interpreter.rs
@@ -7960,6 +7960,60 @@ impl Interpreter {
                 }).collect();
                 Ok(Value::Array(HArray::from_vec(out)))
             }
+            // omc_spawn_child_fold(seed: int, reason: string)
+            //   -> dict {fold_id, focus_numerator, focus_denominator,
+            //            spawn_reason, resonance_target, explored_value,
+            //            final_resonance}
+            //
+            // Ported from Sovereign_Lattice register_singularity_integration.
+            // A ChildFold is the "expand a single token into its
+            // computational subspace" primitive — given any HInt-shaped
+            // seed, deterministically produce the boundary exploration
+            // the parent register would have performed if its tension
+            // exceeded 1/φ.
+            "omc_spawn_child_fold" => {
+                if args.is_empty() {
+                    return Err("omc_spawn_child_fold requires (seed: int, reason?: string)".to_string());
+                }
+                let seed = self.eval_expr(&args[0])?.to_int();
+                let reason = if args.len() >= 2 {
+                    self.eval_expr(&args[1])?.to_display_string()
+                } else { "tension threshold exceeded".to_string() };
+                let cf = crate::onn::spawn_child_fold(seed, &reason);
+                let mut map = std::collections::BTreeMap::new();
+                map.insert("fold_id".to_string(), Value::HInt(HInt::new(cf.fold_id)));
+                map.insert("focus_numerator".to_string(), Value::HInt(HInt::new(cf.focus_numerator)));
+                map.insert("focus_denominator".to_string(), Value::HInt(HInt::new(cf.focus_denominator)));
+                map.insert("spawn_reason".to_string(), Value::String(cf.spawn_reason));
+                map.insert("resonance_target".to_string(), Value::HFloat(cf.resonance_target));
+                map.insert("explored_value".to_string(), Value::HInt(HInt::new(cf.explored_value)));
+                map.insert("final_resonance".to_string(), Value::HFloat(cf.final_resonance));
+                Ok(Value::dict_from(map))
+            }
+            // omc_geodesic_expand(seed: int, n_samples: int)
+            //   -> [[value, resonance], ...]
+            //
+            // "Replicate compressed data from a single token" formalized:
+            // walk the φ-field geodesic from `seed` toward its nearest
+            // Fibonacci attractor in n_samples equal steps. Each sample
+            // is a (value, resonance) pair. Deterministic per (seed, n).
+            //
+            // Useful for: stable substrate-anchored pseudo-random sequences,
+            // expanding a single recall-key into a memory trace, geometric
+            // (not semantic) reconstruction.
+            "omc_geodesic_expand" => {
+                if args.len() < 2 {
+                    return Err("omc_geodesic_expand requires (seed: int, n_samples: int)".to_string());
+                }
+                let seed = self.eval_expr(&args[0])?.to_int();
+                let n = self.eval_expr(&args[1])?.to_int().max(0) as usize;
+                let samples = crate::onn::geodesic_expand(seed, n);
+                let out: Vec<Value> = samples.iter().map(|(v, r)| {
+                    let pair = vec![Value::HInt(HInt::new(*v)), Value::HFloat(*r)];
+                    Value::Array(HArray::from_vec(pair))
+                }).collect();
+                Ok(Value::Array(HArray::from_vec(out)))
+            }
             // omc_llm_self_instantiate(context: string[], task: string,
             //                          base_dir: string, base_sender_id: int)
             //   -> dict[] manifest of {specialist_id, prompt_path,
diff --git a/omnimcode-core/src/onn.rs b/omnimcode-core/src/onn.rs
