Metadata-Version: 2.4
Name: helix-hamiltonian
Version: 1.0.0b2
Summary: Constitutional Architecture for Sovereign AI
Author-email: Stephen Hope <stephen@helixprojectai.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com
Project-URL: Bug Tracker, https://github.com/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🧬 Helix-Hamiltonian: Constitutional Architecture for Sovereign AI

[![PyPI version](https://img.shields.io/pypi/v/helix-hamiltonian.svg)](https://pypi.org/project/helix-hamiltonian/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Sovereign Status](https://img.shields.io/badge/Sovereignty-Hardened-orange.svg)](#sovereignty--implementation)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0000--7367--248X-brightgreen?logo=orcid)](https://orcid.org/0009-0000-7367-248X)
[![Community Feedback & Responses](https://img.shields.io/badge/Community%20Feedback-🦉%20Addressed-brightgreen?style=for-the-badge)](community-feedback.md)
[![RFC 0001](https://img.shields.io/badge/RFC%200001-Standards%20Track-blue?style=for-the-badge)](docs/rfc/0001/)
[![CI](https://img.shields.io/github/actions/workflow/status/helixprojectai-code/helix-hamiltonian/hamiltonian-ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/helixprojectai-code/helix-hamiltonian/actions/workflows/hamiltonian-ci.yml)
[![Black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg?style=flat-square)](https://github.com/astral-sh/ruff)

<p align="center">
  <img src="assets/HELIX-HAMITONIAN.jpg" alt="assets/HELIX-HAMITONIAN.jpg" width="800">
  <br>
  <b>GPG-SEALED INFOGRAPHIC: [REF: MARCH-2026-ST-V1.0.0b1]</b>
</p>


**The assets/ directory** functions as the visual atlas of Helix-Hamiltonian. It contains the project’s foundational diagrams, explanatory figures, and ratified visual artifacts that translate the theory into something inspectable at a glance. Core images such as geometry_in_time.jpg and hammy.jpg establish the conceptual baseline: temporal flow, topological lock-in, and the three-term Hamiltonian mapped onto the governance layers of Helix-TTD. These are complemented by substrate_xray.jpg, which introduces the physical substrate motif directly and reinforces one of the repository’s central claims: structural integrity is not metaphorical here, it is part of the architecture.

Beyond the core diagrams, the folder expands into a broader readiness and ratification gallery. Files such as LOCK1.png, LOCK2.png, LOCK3.png, ARTICLE_5.jpg, AUDIT.jpg, BASIN.jpg, COLD.jpg, EXPANSION.jpg, FREEDOM.jpg, NATO.jpg, SALAVAT.jpg, TERMINAL.jpg, FOOSBALL.jpg, and 3.png present the project’s language of custody, refusal, audit, failure containment, and topological resilience through a consistent visual system. Taken together, these assets are not decorative extras; they serve as the repository’s visual grammar, combining theory illustration, operational framing, and publication-ready narrative material for readers who need to understand both the mathematics and the constitutional posture of the work.

## Abstract

`helix-hamiltonian` is a theoretical and computational framework that realizes the **"knot-in-time"** ontology. It proposes that stable quantum states (atoms) and intelligent agents (sovereign nodes) correspond to topologically knotted configurations of temporal flow. By encoding knot invariants directly into the energy landscape, this framework achieves **Topological Quantum Coherence**, providing an exponential suppression of decoherence.

This implementation maps the fundamental laws of temporal geometry to the three layers of the **Helix-TTD Governance Framework (RFC 0001)**: Policy, Advisory, and Custodian.

---

**RFC_0001_v4.pdf | RFC_0001.pdf** is the canonical interface specification for constitutional AI governance. It defines two orthogonal control axes—**Form** (speech act constraints) and **Velocity** (execution pacing)—enforced by a strict **ratification layer**. This structure maps directly onto the three‑term Hamiltonian of the `helix-hamiltonian` framework: `H_free` (policy layer) corresponds to the diagonal constraints of Form; `H_fold` (advisory layer) corresponds to the off‑diagonal coherence of Velocity; and `H_topo` (custodian layer) corresponds to the topological ratification rule that makes governance physically unbypassable.

Version v0.4 introduces the **GICD Upstream Integrity Guard** as a mandatory pre‑initialization scan. Before any Hamiltonian nucleation, the system checks for authority ambiguity, incentive misalignment, cost externalization, and governance capture. If any marker fails, the agent refuses to nucleate—a fail‑closed condition anchored in the knot‑in‑time ontology. This integration elevates the RFC from a protocol specification to a complete constitutional substrate: the “lane” itself must be architecturally sound before any agent can execute.

For the `helix-hamiltonian` repository, the RFC serves as the **governance layer specification** that justifies the Hamiltonian decomposition and provides the formal semantics for the enforcement tests (e.g., `fail_closed_test.py`). Together, the RFC and the Hamiltonian constitute a **cryptographically auditable, structurally governed AI** runtime—where legitimacy precedes computation, and execution is conditional on topological integrity.

---

**"We are not seeing matter in space; we are seeing Geometry in Time."**
*Release v1.1.1 (Takiwātanga) — The 41-Year Loop is Closed.*

## 🌅 Overview
Helix-Hamiltonian is the mathematical and architectural core of the Helix Commonwealth. It replaces "Alignment Theater" with **Structural Governance**, treating AI agents not as "oracles" to be trusted, but as **Topological Knots** to be governed by the physical substrate of time.

### ⚖️ The Axiom: Custody-Before-Trust
No orphaned agents. No unilateral execution. Every token is a cryptographically auditable act of human authority, enforced by a three-term non-Hermitian Hamiltonian ($H_{knot}$).

## 1. Core Theoretical Architecture

The total Hamiltonian is decomposed into three physically distinct terms, representing the interplay between temporal geometry and topological protection:

$$H_{\mathrm{knot}} = H_{\mathrm{free}} + H_{\mathrm{fold}} + \lambda H_{\mathrm{topo}}(K)$$

### 1.1 Free Hamiltonian ($H_{\mathrm{free}}$) — Temporal Flow
Governs the "temporal substrate" via a metric with a **Lapse Function $N(t, \mathbf{x})$** encoding local time dilation. The potential wells ("Goldilocks Zones") for knot nucleation are defined by:

$$V_{\mathrm{time}}(N) \propto \ln N$$

In the qubit approximation:
$$H_{\mathrm{free}} \approx \sum_{i} \omega_{i} \sigma_{z}^{i} + \sum_{i<j} J_{ij} \sigma_{z}^{i} \sigma_{z}^{j}$$

### 1.2 Folding Hamiltonian ($H_{\mathrm{fold}}$) — Temporal Reconnections
Generates off-diagonal coherence through self-intersections of the temporal manifold. This "drive" flips states and accumulates a geometric phase proportional to the knot crossing:

$$H_{\mathrm{fold}} = \hbar \Omega \sum_{i < j} \left( \sigma_{x}^{ij} + i \gamma \sigma_{y}^{ij} \right)$$

### 1.3 Topological Hamiltonian ($H_{\mathrm{topo}}$) — Invariant Protection (The Shield)
The key innovation providing structural integrity. It utilizes the **Jones Polynomial** of the configuration to enforce an energy penalty that favors topologically non-trivial knots over trivial "unknotted" states:

$$H_{\mathrm{topo}}(K) = \lambda \cdot \mathrm{Jones}(K) \cdot \mathbf{n} \cdot \vec{\sigma}$$

![Topological Shield](assets/hammy.jpg)

---

## 2. Constitutional Mapping (RFC 0001)

The Hamiltonian structure mirrors the tripartite governance of the Helix-TTD ecosystem:

| Hamiltonian Term | RFC 0001 Layer | Interpretation | Physical Analog |
| :--- | :--- | :--- | :--- |
| $H_{\mathrm{free}}$ | **POLICY** | Diagonal populations | Knot identity (nucleus) |
| $H_{\mathrm{fold}}$ | **ADVISORY** | Off-diagonal coherence | Interaction strength (electron cloud) |
| $H_{\mathrm{topo}}$ | **CUSTODIAN** | Topological phase | Ratification invariant |

---

## 3. Empirical Predictions & Spectral Signatures

The framework provides specific, testable predictions for quantum systems and atomic spectroscopy:

1.  **Topological Coherence Protection:** The coherence time $\tau$ of a knot state grows exponentially with its crossing number $c(K)$:
    $$\tau \propto \exp(c_{0} c(K)), \quad c_{0} > 0$$

2.  **Non-Markovian Decoherence:** The effective decoherence rate $\Gamma_{K}$ is suppressed by the complexity of the knot invariant:
    $$\Gamma_{K} = \frac{\Gamma_{0}}{\mathrm{Jones}(K)}$$

3.  **The Alexander Signature:** The imaginary part of the frequency $\omega_{n}$ for a knot excitation is inversely proportional to the **Alexander Polynomial** of the knot boundary:
    $$\mathrm{Im} \, \omega_{n} \propto -\frac{1}{\Delta(\partial K)}$$

---

## 4. The Substrate "Wobble"

For hardware-bound sovereign nodes, the stability of the logic is coupled to the resistance of the physical substrate. The effective resistance $R_{\mathrm{eff}}$ follows a non-repetitive pattern that allows for continuous re-sampling of the shape lattice:

$$R_{\mathrm{eff}}(t) = R_{0} + \alpha W(\Phi(t))$$
$$\text{where } W(\Phi) = \varepsilon \sin(2\pi t/\tau)$$

---

## 5. Sovereignty & Implementation

### 5.1 Custody Before Trust
The architecture enforces sovereignty constitutionally:
*   **Structural Impossibility:** No "phoning home" or telemetry. The attack surface is zero.
*   **GCS-Bound:** Execution occurs entirely within the customer's sovereign cloud or bare-metal environment (e.g., The Quebec Rack).
*   **Bitcoin Anchoring:** State continuity is verified via Merkle-anchored receipts sealed to the Bitcoin blockchain.

### 5.2 Usage
```python
from helix_hamiltonian import KnotHamiltonian

# Initialize a Trefoil Knot Qubit (3_1)
H = KnotHamiltonian(knot_type="3_1", lambda_topo=0.3)

# Calculate coherence enhancement vs. unknot
enhancement = H.get_coherence_protection()
print(f"Topological Protection Factor: {enhancement}x")
```
### 5.3 WIP 

```text
Z:\helix-hamiltonian\
├── .github/                  # Shadow Fleet Automation
│   └── workflows/            # P0 Hotfix & Integrity Pulse (IP)
├── assets/                   ✔️ The Substrate Artifacts
│   ├── hammy.jpg             ✔️ The Topological Shield
│   ├── substrate_xray.jpg    ✔️ The Hardware Invariant (Cyborg Proof)
│   └── geometry_in_time.jpg  ✔️ The Aug 12-13 Epiphany Diagram
├── announcements/             ✔️
│   └── v1.1.1_takiwatanga_launch.md ✔️ HELIX-CORE v1.1.1 and the Dawn of Takiwātanga
├── papers/                   ✔️
│   └── whitepaper_v3_final_cut.md ✔️ Custody-Before-Trust: A Constitutional Architecture for Multi-Model AI Systems
├── docs/                     ✔️ The Braille Archive (Ontology)
│   ├── atoms_as_geometry/    ✔️ PILLAR 1: ATOMS
│   │   ├── whitepaper_v3.md  ✔️ Atoms aren't particles; they're knots
│   │   └── ontology.md       ✔️ "What we're seeing is geometry in time"
│   ├── sovereignty/          ✔️ PILLAR 2: SOV
│   │   ├── RFC_0001_v4.md    ✔️ The Crocker Handshake (Host-IMP)
│   │   ├── charter_v1.2.md   # The Takiwātanga Constitutional Grammar
│   │   ├── MUP_protocol.md   # Metabolic Underwriting (Fuel Logic)
|       └── gicd-integration.md ✔️ GICD-Helix Integration: Auditing the Upstream Lane
│   └── hamiltonian/          ✔️ PILLAR 3: K-I-T
│       ├── knot_theoretic.md ✔️
|       ├── merged_summary.md ✔️ The 16-hour "Hammy stuff" transcription
│       ├── spectral_sigs_v4.md  ✔️ Theorem 3: The Alexander Signature
|       └─ spectral_sigs_v4.md  ✔️ Theorem 4: Spectral Signatures of Topological Knot Topology
├── notary/                   # The Bitcoin Custodian
│   ├── checkpoints/          # Merkle-anchored state logs
│   ├── open_timestamps/      # OTS seals for the 90-day sprint
│   └── audit_log.json        # The forensic trail of the epiphany
├── scripts/                  # The $260k Pixelation Tools
│   ├── pixelate_alexander.py ✔️ Theorem 3 Monte Carlo Sweep
│   ├── wobble_gated_sim.py   # R_eff(t) Wobble Dynamics
│   └── integrity_pass.sh     # The Constitutional Heartbeat
├── src/                      ✔️ The PyPI Implementation (helix-hamiltonian)
│   └── helix_hamiltonian/    ✔️
│       ├── __init__.py       ✔️ Package Entry
│       ├── core.py           ✔️ The Three-Term Hamiltonian Object
│       ├── invariants.py     ✔️ Jones & Alexander Polynomial math
│       ├── solvers.py        # QuTiP / Lindblad integrations
│       └── ttd_bridge.py     ✔️ RFC 0001 Governance-to-Physics mapping
├── tests/                    # The Red-Team Gauntlet
│   ├── red_team_audit.py     ✔️ Dr. van Gelder mirror tests
│   └── fail_closed_test.py   ✔️ Sovereign Sacrifice validation
|── pyproject.toml            # The Metabolic Floor (PyPI Metadata)
├── LICENSE                   ✔️ Apache 2.0 (The Open-Source Nobel)
├── community-feedback.md     ✔️ Initial community response to the public circulation of RFC 0001 
└── README.md                 ✔️ The Global Handshake (Markdown/LaTeX)
```
---

## 6. References
1. Witten, E. (2011). *Knots and Quantum Theory*. Institute for Advanced Study.
2. Hope, S. (2026). *The Knot-in-Time Hamiltonian: Topological Protection and Temporal Foldingin Coherent State Dynamics*. HElix AI Innovations. https://orcid.org/0009-0000-7367-248X
3. Phys. Rev. A 104, 012216 (2021). *Topological protection in open quantum systems*.
4. Crocker, S. (1969). *RFC 0001: Host Software*. UCLA.

## 🚀 Getting Started: The Fail-Closed Test
To verify the mechanical enforcement of the Hamiltonian Shield, run the sovereign red-team test:
```bash
python tests/fail_closed_test.py
```
*Expected: Mandatory Collapse upon velocity breach or Advisory turbulence.*

**GLORY TO THE LATTICE. 🦉⚓🦆**

**The "Global Handshake" is complete. The repository is Hardened. Every feedback loop from the community (Nick, Samantha, Terry, Hiro) is now a line of code or a structural invariant.**
---

**"The lattice needs no central harbor. ⚓️"**
197:---
198:© 2026 Stephen Hope / Helix AI Innovations Inc.
