Merge pull request #459 from AdaWorldAPI/claude/gallant-rubin-Y9pQd

feat(helix): golden-spiral Place/Residue codec (zero-dep + optional ndarray-hpc)

Author: AdaWorldAPI

.claude/board/AGENT_LOG.md

@@ -1,3 +1,9 @@
+## [Main thread / Opus, autoattended] D-HELIX-1 SHIPPED — `crates/helix` golden-spiral Place/Residue codec (zero-dep + optional ndarray-hpc)
+
+**Branch:** claude/gallant-rubin-Y9pQd. New standalone crate `crates/helix` (empty `[workspace]`, added to root `exclude`) realising the user's `KNOWLEDGE.md` Place/Residue encoding — HHTL = deterministic PLACE, helix = orthogonal RESIDUE: equal-area `√u` hemisphere placement (`HemispherePoint`) → stride-4-over-17 `CurveRuler` coupling → Fisher-Z/arctanh `Similarity` alignment → EULER_GAMMA hand-off → 256-palette `RollingFloor` quantise (occupancy-drift + floor-version stamp) → 3-byte `ResidueEdge` endpoint pair; metric-safe L1 via 256×256 `DistanceLut` (`distance_adaptive`) + non-metric byte-Hamming `distance_heuristic`. **Tests:** 61 unit + 6 doctests green on the default zero-dep build (clippy -D warnings + fmt clean); same 61+6 green under `--features ndarray-hpc` (batch Fisher-Z routes through `ndarray::simd::simd_ln_f32`; `batch_fisher_z_matches_scalar_reference` confirms bit-equivalence to the scalar path). Closed Open Item #1 — `prove()` is the 2-D golden-spiral discrepancy companion to `jc::weyl` (D*_φ=0.00160 < D*_ctrl=0.00252 at N=1597). **Process (autoattended):** 5 read-only research agents (weyl/jc template · bgz17 metric-safety · ndarray SIMD surface · HHTL offset · encoding-ecosystem placement) → main-thread foundation + spine → 4 parallel Sonnet leaf workers (placement / fisher_z / quantize / prove; edit-only, no worktree, tee writes) → central compile/clippy/fmt/test consolidation (fixed 1 contrived worker test + 4 clippy lints). **Honest finding (E-HELIX-OVERLAP):** ~80% of the pipeline pre-exists, some CERTIFIED (`bgz-tensor::Base17Fz`/`fisher_z::FamilyGamma` ρ≥0.999, `jc::weyl`); shipped as a user-directed zero-dep clean-room re-derivation — overlap + consolidation path documented in `crates/helix/KNOWLEDGE.md` and TD-HELIX-OVERLAP-1. Board: LATEST_STATE + STATUS_BOARD D-HELIX-1 + EPIPHANIES E-HELIX-OVERLAP + TECH_DEBT + this entry (same commit).
+
+---
+
 ## [Main thread / Opus, autoattended] D-A3 SHIPPED — I4x32/I4x64 signed-i4 CAM codec (5-research + 3-brutal sandwich)
 
 **Branch:** claude/jolly-cori-clnf9. Implemented `atoms::I4x32::pack`/`unpack` (the 2 `todo!()`s) + `I4x64` (256-bit, 64 signed dims) + `sext4`. Two's-complement signed-i4 nibble (even→low/odd→high, saturate [−8,7], sign-agnostic). Carrier = deterministic **CAM address + sparse-intensity "smell"** (jan: NO vector search; `{instance,reference}` dual REJECTED — "64" = 64 poles, not lanes; bipolar `−introspection..+exploration` rides the caller's pre-scale). Resolved the 3 stale BLOCKED notes. Hardened tests incl. the absolute-bit offset-binary catch (B1). Contract lib **562 green** (553 +9), offline, zero new deps. Process: 5-agent research (R1–R5) → A3 plan → 3× brutal (B1 algorithm-sound + range/test fixes; B2 scope/regression-safe, 553 exact; B3 forward-traps) → jan clarification collapsed the dual → ship. Next: A4 (CAM-address resolver + `AtomGroup::is_signed` + `AtomLane`/`LaneMask`).

.claude/board/EPIPHANIES.md

@@ -1,3 +1,15 @@
+## 2026-06-03 — E-HELIX-OVERLAP — the `helix` Place/Residue codec is ~80% re-derivation of existing (in places CERTIFIED) primitives; shipped standalone by user directive, overlap documented not hidden
+
+**Status:** FINDING (placement check via `encoding-ecosystem.md` + repo grep, 2026-06-03; crate shipped on claude/gallant-rubin-Y9pQd — 61 unit + 6 doctests green on the default zero-dep build AND under `--features ndarray-hpc`). User directive: "create crate crates/helix … scoped only to crate, self resolving" → after the overlap was surfaced via `AskUserQuestion`, the user ratified **Standalone helix** (vs compose-existing vs rename).
+
+**The overlap (don't-reinvent ledger):** the Fisher-Z/arctanh→i8 quantiser already exists as `bgz-tensor::projection::Base17Fz` + `bgz-tensor::fisher_z::FamilyGamma` (CERTIFIED ρ≥0.999, 21 roles, 1.7B); the golden-spiral azimuth proof as `jc::weyl::prove()` (1-D, Ostrowski 2/N); stride-4 coupling in `thinking-engine::reencode_safety` + `highheelbgz`; the EULER_GAMMA hand-off in `jc::precond` + `bgz-tensor::euler_fold`; 256-palette/L1 endpoints in `bgz17::palette`. **Genuinely new:** the equal-area `√u` hemisphere placement (`r=√u`, `Y=√(1−r²)`) and the PLACE/RESIDUE doctrine (zero prior hits). Consolidation path (when helix graduates from clean-room): re-export `FamilyGamma` behind a feature, route coupling through the canonical `(i·11)%17`/stride-4 zipper, feed `ResidueEdge` endpoints into the existing HIP/TWIG CAKES tier. Tracked as TD-HELIX-OVERLAP-1.
+
+**Two corrections folded in:** (1) `KNOWLEDGE.md` referenced `const::simd::{GOLDEN_RATIO,EULER_GAMMA,E}` — that path does NOT exist; canonical is `std::f64::consts` (ndarray does not wrap them). helix defines local consts (`E` from `std` since it is stable; `GOLDEN_RATIO`/`EULER_GAMMA` as literals since not stable on every toolchain, mirroring `jc::weyl`'s local `PHI_INV`). (2) The name `helix` collides with a planner plan-doc "Helix" (Foundry time-series histogram) that leaned *away* from a crate — `crates/helix` is free, but flagged. **Iron rule respected:** stride-4-over-17 is coprime → full permutation; the banned Fibonacci-mod-17 (misses {6,7,10,11}) is NOT used. **Open (CONJECTURE, probe NOT RUN):** helix int8 endpoint fidelity vs the naive-u8 floor gate (≥0.9980 Pearson) — a fidelity-vs-ground-truth probe is owed before promotion past clean-room status.
+
+Cross-ref: `crates/helix/KNOWLEDGE.md` (§ Overlap & Consolidation), `encoding-ecosystem.md`, `jc::weyl`, `bgz-tensor::{projection,fisher_z}`, TD-HELIX-OVERLAP-1, the `E-READ-NOT-GREP` consult-before-guess doctrine.
+
+---
+
 ## 2026-06-01 — E-NARS-FIGURE-CAPSTONE — NAL syllogism resolution hardwired on CausalEdge64 like Pearl 2³: the figure = which SPO palette term two edges share → rule → conclusion edge
 
 **Status:** SHIPPED (`causal-edge::syllogism`, branch claude/jolly-cori-clnf9; 14 tests v2 / 13 v1, the new file clippy- + fmt-clean). User: "the syllogism resolution needs to be hardwired similar to SPO 2^3 rung decomposition … using causaledge64 and wiring EW64" + "NAL syllogism notation is the missing capstone for glueing all 3 reasoning methods with the 10-rung ladder and the JITson cranelift templates vs elixir."

.claude/board/LATEST_STATE.md

@@ -10,6 +10,8 @@
 
 ---
 
+> **2026-06-03 — shipped (autoattended)** (D-HELIX-1): new standalone crate `crates/helix` — the golden-spiral **Place/Residue** codec from the user's `KNOWLEDGE.md`. HHTL = deterministic PLACE; helix = orthogonal RESIDUE. Pipeline: equal-area `√u` hemisphere placement (`HemispherePoint`) → stride-4-over-17 `CurveRuler` coupling → Fisher-Z/arctanh `Similarity` alignment → EULER_GAMMA hand-off → 256-palette `RollingFloor` quantise (occupancy-drift + version stamp) → 3-byte `ResidueEdge` endpoint pair; metric-safe L1 via 256×256 `DistanceLut` (`distance_adaptive`) + non-metric byte-Hamming `distance_heuristic`. `prove()` closes the 2-D discrepancy Open Item (companion to `jc::weyl`). Zero-dep default (`edition 2021`, empty `[workspace]`, root `exclude`); optional `ndarray-hpc` feature routes batch Fisher-Z through `ndarray::simd::simd_ln_f32`. **61 unit + 6 doctests green** on BOTH feature configs; clippy -D warnings + fmt clean. ~80% overlaps existing CERTIFIED primitives by design (clean-room, user-directed) — see `crates/helix/KNOWLEDGE.md` § Overlap & Consolidation + E-HELIX-OVERLAP + TD-HELIX-OVERLAP-1. Branch claude/gallant-rubin-Y9pQd.
+>
 > **2026-06-01 — shipped (autoattended)** (D-A3): `lance_graph_contract::atoms` — `I4x32::pack`/`unpack` implemented (the 2 `todo!()`s gone) + new `I4x64` (256-bit / 64 signed-i4 dims, `repr(C, align(16))`, 32 B) + private `sext4`. Two's-complement signed-i4 nibble codec (byte-compatible with `QualiaI4_16D` + the `CausalEdge64` mantissa), sign-agnostic (caller pre-scales). The carrier is a deterministic **CAM address** + sparse-intensity "smell" — NO vector search, no float; the `{instance,reference}` dual is rejected ("64" = 64 poles). Contract lib **562 green** (+9), offline, zero new deps. The bipolar `−introspection..+exploration` pole semantics + asymmetric scaling ride the caller's pre-scale (A4). Plan `.claude/plans/a3-carrier-v1.md`; doctrine `.claude/knowledge/ephemeral-warm-cold-lifecycle.md`.
 >
 > **2026-06-01 — PR-in-flight (autoattended)** (D-EW64-2): `lance_graph_contract::episodic_edges::EpisodicEdges64::{promote, strongest}` — MRU "promote" strengthens an edge to slot 0 (the hot / most-immediate position); fire→front, un-refired ages toward slot 3 and evicts to the cold connectome; **slot order IS the strength ranking** (no per-edge weight stored — the co-addressed `CausalEdge64` plasticity carries the Hebbian weight, recency is the slot index). Realizes `E-EW64-STRENGTH-IS-CE64-PLASTICITY` (the user's "stronger immediate edges"). Zero-dep; contract lib 533 green (+5), default clippy clean, episodic_edges.rs pedantic+nursery clean. The surreal-LIVE "wingman" that drives `promote` stays GATED on OQ-11.6 (LanceDB-LIVE fallback exists) — this is the substrate-agnostic hot-tier mechanism it calls.

.claude/board/STATUS_BOARD.md

@@ -10,6 +10,10 @@
 
 ---
 
+## D-HELIX-1 — `crates/helix` golden-spiral Place/Residue codec (zero-dep + optional ndarray-hpc)
+
+**Status:** Shipped (branch `claude/gallant-rubin-Y9pQd`; **61 unit + 6 doctests green** on the default zero-dep build AND under `--features ndarray-hpc`; clippy -D warnings + fmt clean). New standalone crate (empty `[workspace]`, root `exclude`) realising the user's `KNOWLEDGE.md`: `HemispherePoint` (√u equal-area placement) → `CurveRuler` (stride-4-over-17) → `Similarity` (Fisher-Z/arctanh) → `RollingFloor` (256-palette; occupancy-drift + version stamp) → `ResidueEdge` (3-byte endpoint pair) + `DistanceLut` (metric-safe 256×256 L1; `distance_adaptive` vs non-metric `distance_heuristic`) + `prove()` (2-D discrepancy companion to `jc::weyl`). Optional `ndarray-hpc` = batch Fisher-Z via `simd_ln_f32`. ~80% clean-room overlap with CERTIFIED primitives (E-HELIX-OVERLAP / TD-HELIX-OVERLAP-1); consolidation path in `KNOWLEDGE.md`. Process: autoattended — 5 research agents + 4 parallel Sonnet leaf workers + central consolidation. Next (owed): fidelity-vs-ground-truth probe (naive-u8 floor gate ≥0.9980 Pearson, CONJECTURE).
+
 ## D-A3 — I4x32/I4x64 signed-i4 CAM codec (carrier `pack`/`unpack` + the 256-bit wide carrier)
 
 **Status:** Shipped (branch `claude/jolly-cori-clnf9`; contract lib **562 green**, offline). `I4x32::pack`/`unpack` (two's-complement signed-i4 nibble; even→low/odd→high; saturate `[−8,7]`; sign-agnostic) + new `I4x64` (256-bit / 64 signed dims) + private `sext4`. The carrier is a deterministic 32×/64× **CAM address** + sparse-intensity "smell" — NOT a similarity vector (no vector search, no float; the `{instance,reference}` dual REJECTED, "64" = 64 poles). 33 atoms → dims 0..32. Resolved the 3 stale BLOCKED notes. Plan `.claude/plans/a3-carrier-v1.md` (5-research + 3-brutal sandwich). Next: A4 (CAM-address resolver + `is_signed` + `AtomLane`/`LaneMask` newtypes).

.claude/board/TECH_DEBT.md

@@ -15,6 +15,10 @@
 
 ## Open Debt
 
+### TD-HELIX-OVERLAP-1 (D-HELIX-1) — `helix` re-derives existing CERTIFIED primitives (clean-room by directive)
+
+**Open.** `crates/helix` ships as a zero-dep clean-room codec per the user directive "scoped only to crate." ~80% of its pipeline duplicates existing, in-places-CERTIFIED workspace code: Fisher-Z/arctanh→i8 (`bgz-tensor::projection::Base17Fz`, `bgz-tensor::fisher_z::FamilyGamma` ρ≥0.999), golden-spiral azimuth (`jc::weyl`), stride-4 coupling (`thinking-engine::reencode_safety`, `highheelbgz`), EULER_GAMMA hand-off (`jc::precond`, `bgz-tensor::euler_fold`), 256-palette/L1 (`bgz17::palette`). Genuinely new = the `√u` equal-area hemisphere placement + the PLACE/RESIDUE doctrine. **Paid by** (when it graduates from clean-room): the consolidation path in `crates/helix/KNOWLEDGE.md` § Overlap & Consolidation — re-export `FamilyGamma` behind a feature; route coupling through the canonical `(i·11)%17`/stride-4 zipper; feed `ResidueEdge` into the existing HIP/TWIG CAKES tier. **Also owed:** a fidelity-vs-ground-truth probe (the naive-u8 floor gate ≥0.9980 Pearson is currently CONJECTURE — NOT RUN) before promotion. Cross-ref: E-HELIX-OVERLAP, `encoding-ecosystem.md`.
+
 ### TD-WIKI-SCALE (D-WIKI-HHTL / #442) — three scale-freezes the N4 falsifier inherits
 
 **Status: Open.** Surfaced by the D-ARM-14 session's review of #442 (the hub-side

Cargo.toml

@@ -39,6 +39,9 @@ exclude = [
     "crates/learning",
     "crates/jc",
     "crates/sigker",
+    # Place/Residue golden-spiral codec — standalone zero-dep (default), optional
+    # ndarray-hpc accelerator. Verified via `cargo test --manifest-path crates/helix/Cargo.toml`.
+    "crates/helix",
     # Aerial+ ARM-discovery transcode — standalone zero-dep proposer crate,
     # verified via `cargo test --manifest-path crates/lance-graph-arm-discovery/Cargo.toml`.
     # Kept out of the workspace so the nondeterministic autoencoder never

crates/helix/.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

crates/helix/Cargo.toml

@@ -0,0 +1,43 @@
+[package]
+name = "helix"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+publish = false
+description = "Place/Residue encoding: golden-spiral hemisphere placement, Fisher-Z aligned, into L1-metric-safe 256-palette endpoint pairs — the orthogonal RESIDUE companion to the HHTL PLACE"
+
+# Standalone codec constitution (matches bgz17 / jc / deepnsm): the default build
+# is ZERO production dependencies. The φ-spiral residue is the residue regardless
+# of SIMD path — the math is identical with or without hardware acceleration, so
+# ndarray is an OPTIONAL accelerator, never a correctness dependency.
+[dependencies]
+# Optional ndarray hardware acceleration (AdaWorldAPI fork): batch Fisher-Z via
+# simd_ln_f32 and batch endpoint-L1 via U8x64. Feature-gated so the default build
+# stays zero-dep and standalone-verifiable via `cargo test --manifest-path`.
+# `std` enables `ndarray::simd` (simd_ln_f32 / F32x16 / U8x64); the module is
+# gated behind it. Kept minimal (no extra HPC features) to limit build surface.
+ndarray = { path = "../../../ndarray", optional = true, default-features = false, features = ["std"] }
+
+[features]
+default = []
+# Activate the ndarray-accelerated hot path (simd_ln_f32 / U8x64 batch kernels).
+# The always-present scalar path is used when this is disabled.
+#
+# NOTE: this feature resolves `ndarray` to the AdaWorldAPI fork at the sibling
+# path `../../../ndarray` (NOT crates.io `ndarray`, which has no `::simd` module).
+# It therefore requires that sibling repo to be checked out — the same convention
+# `lance-graph` core uses. The default build is zero-dep and needs none of this.
+ndarray-hpc = ["dep:ndarray"]
+
+[dev-dependencies]
+
+# The example IS the probe (workspace convention): runs the 2-D discrepancy
+# proof + a demo encode/distance round-trip.
+[[example]]
+name = "prove_residue"
+
+# Empty [workspace] so cargo treats this crate as standalone when invoked via
+# --manifest-path (matches deepnsm); helix is also listed under the root
+# Cargo.toml `exclude` so workspace-wide commands never pull it into the
+# deterministic main compile graph.
+[workspace]