Substrate-routed O(log_phi_pi_fibonacci N) primitives + README rewrite

Adds a complete O(log_phi_pi_fibonacci N) algorithm family to OMC's
native runtime, plus Zeckendorf encoding as a first-class integer format.
50+ new builtins exposing the F(k)/phi^(pi*k) substrate search algorithm
that already lived in phi_pi_fib::phi_pi_fib_search_v2.

Substrate primitives (interpreter + phi_pi_fib.rs):
- zeckendorf / from_zeckendorf / zeckendorf_weight / zeckendorf_bit
- substrate_search / substrate_lower_bound / substrate_upper_bound
- substrate_rank / substrate_count_range / substrate_slice_range
- substrate_intersect / substrate_difference / substrate_insert
- substrate_quantile / substrate_select_k / substrate_nearest
- substrate_min_distance / substrate_hash / attractor_bucket
- harmonic_align / harmonic_unalign / harmonic_score / harmonic_resample
- phi_pow / phi_pi_pow / phi_pi_log_distance
- resonance_band_histogram / is_phi_resonant / is_zeckendorf_valid
- nth_fibonacci / attractor_table / fib_chunks

Native baselines for apples-to-apples comparison:
- int_binary_search / int_lower_bound / int_upper_bound
- sorted_merge / sorted_union / sorted_dedupe
- arr_sum_int / arr_product / arr_sort_int / arr_is_sorted
- arr_min_int / arr_max_int / arr_avg_distance / 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
- Earlier session: 22 math/array/stats/substrate builtins (kept)

Dict/string helpers also added (carried from prior batch):
- dict_pop / dict_get_or / dict_size / dict_clear / dict_items
- str_split_lines / str_count / str_is_empty / str_to_int / str_to_float
- str_capitalize / mod_pow / bit_count / bit_length / digit_sum / digit_count

Compiler:
- Type tags for int / float returns so JIT lowering stays correct
- Suppressed warnings (gate_map, unused new(), import_module marker)

Tests:
- examples/tests/test_substrate_primitives.omc — 57 tests covering
  every new primitive, including round-trip invariants for Zeckendorf,
  cross-consistency (substrate_search == int_binary_search), boundary
  cases, and monotonicity. All pass.
- examples/tests/test_new_builtins.omc — extended to 70 tests.

Benchmark:
- experiments/substrate_primitives/bench_substrate_search.omc — 4-way
  comparison: linear vs OMC binary vs substrate vs int_binary at
  N=1024 / 8192 / 65536. Shows substrate uses 7.3 vs binary's 16
  probes at N=65536 (0.459x ratio matches log_phi_pi_fibonacci bound)
  but pays more per probe.

High-level wrapper library:
- examples/lib/substrate.omc — s_*/i_*/h_* naming for the three
  styles (substrate-routed / int-binary / harmonic-aligned).

README:
- Comprehensive rewrite emphasizing what makes OMC unique vs other
  languages: substrate-as-primitive, dual-band execution,
  O(log_phi_pi_fibonacci N) algorithms, Zeckendorf encoding,
  CRT-PE winning on TinyShakespeare, self-healing compiler,
  two-engine byte-identical parity, JIT pragmas.
- Added omnimcode-gdextension (Godot 4 binding) to repo layout.

Gitignore:
- Exclude omnimcode-gdextension/bin/ (built artifact).

Build: clean. Tests: 145 OMC tests + 41 codegen tests + cargo
unit tests all green.

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

Author: RandomCoder-lab

.gitignore

@@ -37,3 +37,6 @@ omnimcode-ffi/.cargo/
 examples/movielens_*.csv
 examples/recommend/sample_10k.csv
 examples/recommend/sample_100k.csv
+
+# Gdextension built artifacts (rebuild from src/)
+omnimcode-gdextension/bin/

README.md

@@ -0,0 +1,90 @@
+# substrate.omc — high-level wrappers around the O(log_phi_pi_fibonacci N)
+# primitives in the OMC native runtime.
+#
+# Conventions:
+#   - Functions named `s_*` are substrate-routed (use the F(k)/phi^(pi*k)
+#     probe sequence). They preserve harmonic structure across probes.
+#   - Functions named `i_*` are native int-binary equivalents. Use them
+#     when raw throughput on uniform data matters more than substrate
+#     coherence.
+#   - Functions named `h_*` are harmonic-aligned operations (Fibonacci
+#     attractor / Zeckendorf operations).
+
+# Build an empty substrate-friendly sorted-int container. Just an alias
+# for an empty array — used to signal intent to other readers.
+fn s_new() {
+    return [];
+}
+
+# Add a value into a sorted container, keeping it sorted. Returns the
+# insertion index.
+fn s_add(container, value) {
+    return substrate_insert(container, value);
+}
+
+# Substrate-routed exact lookup: returns the index or -1.
+fn s_find(container, value) {
+    return substrate_search(container, value);
+}
+
+# Substrate-routed range count: how many elements in [lo, hi).
+fn s_count_range(container, lo, hi) {
+    return substrate_count_range(container, lo, hi);
+}
+
+# Substrate-routed range slice: array of elements in [lo, hi).
+fn s_slice_range(container, lo, hi) {
+    return substrate_slice_range(container, lo, hi);
+}
+
+# Substrate-routed nearest value lookup.
+fn s_nearest(container, value) {
+    return substrate_nearest(container, value);
+}
+
+# Substrate-routed median (50th percentile).
+fn s_median(container) {
+    return substrate_quantile(container, 500);
+}
+
+# Substrate-routed percentile [0, 100].
+fn s_percentile(container, p) {
+    return substrate_quantile(container, p * 10);
+}
+
+# Snap a value to the nearest Fibonacci attractor.
+fn h_snap(value) {
+    return harmonic_align(value);
+}
+
+# Residual after substrate alignment (non-attractor component).
+fn h_residual(value) {
+    return harmonic_unalign(value);
+}
+
+# Substrate-distance: ln(|a-b|+1) / (pi * ln(phi)).
+fn h_distance(a, b) {
+    return phi_pi_log_distance(a, b);
+}
+
+# Substrate-aligned hash for keying into dict/bloom structures.
+fn h_hash(value) {
+    return substrate_hash(value);
+}
+
+# Zeckendorf weight: number of Fibonacci terms in n's decomposition.
+fn h_weight(n) {
+    return zeckendorf_weight(n);
+}
+
+# Substrate-coherence score for an array (0.0 .. 1.0).
+fn h_score(arr) {
+    return harmonic_score(arr);
+}
+
+# Build a sorted set from an unsorted array via substrate operations.
+# Result is sorted, deduplicated, and ready for s_find / s_count_range.
+fn s_from_array(arr) {
+    h sorted = arr_sort_int(arr);
+    return sorted_dedupe(sorted);
+}