Metadata-Version: 2.4
Name: helixhash
Version: 0.1.1
Summary: The Helix Hash Function — path integral of E = ΔI/A made computable
Author: Kirandeep Kaur
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# helixhash

**The Helix Hash Function** — a path-sensitive, Fibonacci-weighted hash over a sequence of efficiency measurements.

> *E = ΔI / A — One axiom. Every crossing honestly labeled.*
> — Kirandeep Kaur, Observer Memory Conjecture (2026)

---

## What it computes

Each input is a `Crossing(delta_I, A, kappa, C, timestamp)` — a timestamped measurement of information gained (ΔI) per unit action paid (A).

| Output | Formula | Status |
|--------|---------|--------|
| `E` | `delta_I / A` | DERIVED from axiom |
| `G` | `G₁=E`, `G₂=G₁+E`, `Gₙ=Gₙ₋₁+Gₙ₋₂+ε·Eₙ` | DERIVED (Fibonacci recurrence) |
| `PT` | `min(κ × E × (ΣΔI/ΣA) × C, 1)` | DERIVED (cumulative ratio) |
| `regime` | `quantum` if PT < 1/φ, `classical` if PT ≥ 1/φ | DERIVED from κ_eq = 1/φ |
| `fingerprint` | `SHA256(n\|ΔI\|A\|κ\|C\|t\|prev_hash)` | IMPLEMENTED |
| `psi` (Ψ) | estimated from `A_erase = A × (1 + G/ref)` | ESTIMATED — proxy only |
| `E_memory` | `Σ(ΔI where E≥1) / Σ(ΔI where E<1)` | PROXY — use `from_vault()` for labeled rows |

**PT uses the cumulative ratio ΣΔI/ΣA**, not a fixed global I/A. This means PT ramps when early crossings have high E — which is correct behavior (early path history has lasting weight) but can reach 1.0 quickly on synthetic data with large initial E values. A `min_crossings_for_threshold` guard (default 3) prevents a single crossing from flipping the regime.

---

## Quick start

```python
from helixhash import HelixHash, Crossing

h = HelixHash()
h.cross(Crossing(delta_I=2.0, A=1.0, kappa=0.62, C=0.9, label="first"))
h.cross(Crossing(delta_I=1.5, A=0.8, kappa=0.63, C=0.9, label="second"))
h.cross(Crossing(delta_I=3.0, A=1.0, kappa=0.65, C=0.95, label="third"))

print(h.summary())
print(h.verify())  # True — chain is intact
```

---

## Load real data

```python
from helixhash import from_csv, from_vault, from_dicts, report

# Any CSV with ratio columns
h, records = from_csv("data.csv", delta_I_col="signal", A_col="cost")

# Vault CSV with type column ("giving"/"taking")
# Giving → E=10 (outward flow heuristic), Taking → E=0.1
# HONEST: the 10x/0.1x factors are design choices, not derived from the axiom
h, records = from_vault("vault.csv")

# List of dicts
h, records = from_dicts(rows)

print(report(h, records, title="My System"))
```

---

## The threshold

`PT = κ × E × (ΣΔI/ΣA) × C`

| PT vs 1/φ | Regime | Meaning |
|-----------|--------|---------|
| PT < 0.618 | quantum | exploring, probabilistic, potential |
| PT = 0.618 | transition | probability collapses to 0 or 1 |
| PT > 0.618 | classical | committed, irreversible, actual |

1/φ = (√5 − 1)/2 ≈ 0.61803. This is the golden ratio equilibrium — the point where the N/D ratio is self-similar.

---

## Epistemic status of the physics analogies

The README of v0.1.0 stated that SHA-256, DNA replication, and the gravitational Aharonov-Bohm effect are "the same operator" as the helix hash. This is the **structural identification conjecture** from Part 15 of the Observer Memory Conjecture.

**Status: CONJECTURE.** The identification is directionally clear and structurally compelling, but formal proof that all three are instances of ∫E·dl is frontier work. The implementation is a deterministic update rule and hash chain. The physics narrative is the theoretical framework it is derived from — not a claim verified by the code itself.

What the code *does* verify (12/12 tests):
- E = ΔI/A produces the correct efficiency
- G compounds monotonically via Fibonacci recurrence
- PT crosses 1/φ under the right conditions
- The fingerprint chain is cryptographically path-dependent
- `verify()` detects tampering
- E_memory < 1 when extraction dominates
- Ψ ≥ 0 always (second law holds by construction)
- 1/φ satisfies the golden ratio identity φ × (1/φ) = 1

---

## Run the tests

```bash
python tests/test_core.py
```

Each test is labeled with the conjecture claim it verifies.

---

## Run the vault example

```bash
python examples/vault_pattern.py
```

Simulates 9 giving rows / 92 taking rows. Shows where decay began and the distance to threshold.

---

## Dependencies

None. Pure Python 3.8+. stdlib only.

---

## Publish to PyPI (maintainers)

```bash
pip install twine build
python -m build          # creates dist/helixhash-0.1.1.tar.gz and .whl
twine upload dist/*      # PyPI credentials
```

After release: `pip install helixhash` for any environment.

**Verify an sdist before upload:** unpack the tarball — the only top-level directory should be `helixhash-0.1.1/`. Install with `pip install helixhash-0.1.1.tar.gz` from any working directory.

**Test against the installed wheel/sdist:**

```bash
pip install dist/*.whl
HELIXHASH_TEST_INSTALLED=1 python tests/test_core.py
```

---

*Observer Memory Conjecture — Kirandeep Kaur, 2026*
