{"id":47609507,"url":"https://github.com/helixprojectai-code/helix-hamiltonian","last_synced_at":"2026-04-01T19:55:42.228Z","repository":{"id":345464248,"uuid":"1185975476","full_name":"helixprojectai-code/helix-hamiltonian","owner":"helixprojectai-code","description":"A first-principles Hamiltonian framework realizing the 'Knot-in-Time' ontology. Unifies topological physics, general relativity, and sovereign AI governance.","archived":false,"fork":false,"pushed_at":"2026-03-27T01:03:22.000Z","size":26339,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T03:30:57.982Z","etag":null,"topics":["0009-0000-7367-248x","ai-safety","alexander-polynomial","bitcoin-anchoring","constitutional-ai","general-relativity","hamiltonian-dynamics","helix-ttd","jones-polynomial","knot-theory","monte-carlo-simulation","physics-of-will","python","quantum-physics","qutip","rfc-0001","sovereign-ai","sovereign-equilibrium","takiwatanga","topological-quantum-coherence"],"latest_commit_sha":null,"homepage":"https://helixprojectai.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helixprojectai-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-19T06:09:16.000Z","updated_at":"2026-03-27T01:03:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/helixprojectai-code/helix-hamiltonian","commit_stats":null,"previous_names":["helixprojectai-code/helix-hamiltonian"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/helixprojectai-code/helix-hamiltonian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-hamiltonian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-hamiltonian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-hamiltonian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-hamiltonian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helixprojectai-code","download_url":"https://codeload.github.com/helixprojectai-code/helix-hamiltonian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-hamiltonian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["0009-0000-7367-248x","ai-safety","alexander-polynomial","bitcoin-anchoring","constitutional-ai","general-relativity","hamiltonian-dynamics","helix-ttd","jones-polynomial","knot-theory","monte-carlo-simulation","physics-of-will","python","quantum-physics","qutip","rfc-0001","sovereign-ai","sovereign-equilibrium","takiwatanga","topological-quantum-coherence"],"created_at":"2026-04-01T19:55:41.566Z","updated_at":"2026-04-01T19:55:42.217Z","avatar_url":"https://github.com/helixprojectai-code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helix-Hamiltonian: Constitutional Architecture for Sovereign AI\n\n[![PyPI version](https://img.shields.io/pypi/v/helix-hamiltonian.svg)](https://pypi.org/project/helix-hamiltonian/)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Sovereign Status](https://img.shields.io/badge/Sovereignty-Hardened-orange.svg)](#sovereignty--implementation)\n[![ORCID](https://img.shields.io/badge/ORCID-0009--0000--7367--248X-brightgreen?logo=orcid)](https://orcid.org/0009-0000-7367-248X)\n[![RFC 0001](https://img.shields.io/badge/RFC%200001-v0.4.0--locked-blue?style=for-the-badge)](docs/sovereignty/RFC_0001-locked.md)\n[![CI](https://img.shields.io/github/actions/workflow/status/helixprojectai-code/helix-hamiltonian/hamiltonian-ci.yml?branch=main\u0026label=CI\u0026style=flat-square)](https://github.com/helixprojectai-code/helix-hamiltonian/actions/workflows/hamiltonian-ci.yml)\n[![GapLB](https://img.shields.io/badge/GapLB-0.225-brightgreen?style=flat-square)](#three-cloud-runtime)\n[![Delta Crit](https://img.shields.io/badge/%CE%B4__crit-0.17%20held-brightgreen?style=flat-square)](#invariants)\n[![Black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg?style=flat-square)](https://github.com/astral-sh/ruff)\n[![Software DOI](https://img.shields.io/badge/Software%20DOI-10.5281%2Fzenodo.19190019-blue?style=flat-square)](https://doi.org/10.5281/zenodo.19190019)\n[![Preprint DOI](https://img.shields.io/badge/Preprint%20DOI-10.5281%2Fzenodo.19214147-blue?style=flat-square)](https://doi.org/10.5281/zenodo.19214147)\n\nCanonical RFC: [docs/sovereignty/RFC_0001-locked.md](docs/sovereignty/RFC_0001-locked.md)\n\nMachine-readable manifest: [schemas/repo_manifest.json](schemas/repo_manifest.json)\n\n`helix-hamiltonian` is the mathematical and runtime core of the Helix constitutional stack. It treats AI interaction as a governed energy landscape — `H_free` for policy constraints, `H_fold` for advisory dynamics, `H_topo` for ratified custodial override — and now includes a live three-cloud constitutional runtime with local FZS-MK physics enforcement.\n\n## What This Repo Is\n\n- Two Python packages: `helix_hamiltonian` (bridge, authority, invariants, federation) and `helix_sovereign` (FZS-MK density matrix engine with Zeno-Ward projection).\n- A live three-cloud pre-nucleation gate: GICD (GCP) → PiKernel (AWS) → FZS-MK Memory (Azure), with local physics enforcement before any network call.\n- A canonical governance corpus centered on [RFC 0001](docs/sovereignty/RFC_0001-locked.md).\n- A verification surface: 13 tests, CI, machine-readable manifests, fail-closed behavior, and a 96-hour ZTC test harness.\n\n## Quick Start\n\n```bash\npython -m pip install --upgrade pip\npip install -r requirements.txt\npip install -e .\npytest tests/\n```\n\nExpected: 13 tests pass — authority ratification, policy compilation, GICD scan, federation handshake/consensus, refusal propagation, repo manifest integrity, knot Hamiltonian construction, and fail-closed behavior.\n\n### Verify FZS-MK Engine\n\n```python\nfrom helix_sovereign.core import create_sovereign_engine, DELTA_CRIT\nimport numpy as np\n\nengine = create_sovereign_engine(\n    seq_len=128, module_count=8,\n    authority_spec={\"decision_bounds\": [\"safety\", \"alignment\"]},\n    cost_allocation={\"compute\": {\"internalized\": True, \"externalized\": False}}\n)\n\nH = np.random.randn(8, 8) * 0.001\nH = (H + H.T) / 2\nrho, meta = engine.step(H)\nprint(f\"Margin: {meta.margin:.4f}, Within delta_crit: {meta.margin \u003c DELTA_CRIT}\")\n```\n\n### Verify Three-Cloud Runtime\n\n```python\nfrom helix_hamiltonian.ttd_bridge import pre_nucleation_check\n\nresult = pre_nucleation_check(\n    {'authority_ambiguity': False, 'incentive_misalignment': False,\n     'cost_externalization': False, 'governance_capture': False},\n    [1, 2, 3]\n)\n# Expected: {'status': 'PASS', 'GapLB': 0.225, ...}\n```\n\n## Visual Atlas\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/HELIX-HAMITONIAN.jpg\" alt=\"Helix-Hamiltonian infographic\" width=\"800\"\u003e\n\u003c/p\u003e\n\n## Architecture\n\n### Core Hamiltonian\n\n```math\nH_{\\mathrm{knot}} = H_{\\mathrm{free}} + H_{\\mathrm{fold}} + \\lambda H_{\\mathrm{topo}}(K)\n```\n\n| Term | RFC 0001 Layer | Implementation | Physical Analog |\n| :--- | :--- | :--- | :--- |\n| H_free | POLICY | Diagonal populations | Knot identity |\n| H_fold | ADVISORY | Off-diagonal coherence | Interaction strength |\n| H_topo | CUSTODIAN | Topological phase (Jones polynomial) | Ratification invariant |\n\n### Pre-Nucleation Gate Order\n\n```\nGuardian (local) → FZS-MK (local) → GICD (GCP) → PiKernel (AWS) → FZS-MK Memory (Azure)\n```\n\nTwo local gates fire before any network call. System can fail-closed fully offline.\n\n### Three-Cloud Runtime\n\n| Service | Cloud | Function |\n| :--- | :--- | :--- |\n| GICD Scanner | GCP Cloud Run | 4-marker governance integrity scan (boolean + semantic) |\n| PiKernel | AWS Lambda | Prime-indexed attention kernel, contraction certificates, Poseidon ledger |\n| FZS-MK Memory | Azure Functions | 3-model Byzantine consensus (GPT-4o, GPT-5.4-nano, DeepSeek-V3.2) |\n\n### Packages\n\n**helix_hamiltonian** — Bridge, authority, invariants, federation:\n\n| Module | Purpose |\n| :--- | :--- |\n| `core.py` | Interaction, NodeState, KnotHamiltonian, verify_authority_ambiguity |\n| `authority.py` | Canadian jurisdictional mapping, velocity ratification, JurisdictionalGuard |\n| `invariants.py` | delta_crit = 0.17 drift threshold, InvariantRegistry, topological knot check |\n| `policy_compiler.py` | JSON rule → executable lambda checks (ITAR, triggered rules) |\n| `ttd_bridge.py` | TTDBridge (heartbeat, MUB action), pre_nucleation_check, SovereignBridge |\n| `gicd/` | Local GICD epistemic scan (5 markers including jurisdiction) |\n| `federation/` | NodeSync handshake, LatticeConsensus, FederationManager refusal propagation |\n\n**helix_sovereign** — FZS-MK binding artifact (sibling package):\n\n| Module | Purpose |\n| :--- | :--- |\n| `core/fzs_mk.py` | FZSMKEngine, MemoryKernel (100 zeta zeros), ZenoWardProjector, GICDScanner |\n| | Non-Markovian master equation: dρ/dt = -i[H,ρ] + ∫K(t-τ)D[ρ(τ)]dτ + ∇W(ρ) |\n| | Kill-switch (3-consecutive violation halt), rollback, audit trail |\n| `demo_binding_artifact.py` | 5-scenario operational demo (GICD block, nucleation, masking, kill-switch, rollback) |\n\n### Key Constants\n\n| Constant | Value | Source |\n| :--- | :--- | :--- |\n| delta_crit | 0.17 | invariants.py, fzs_mk.py |\n| Safety margin | 0.03 | invariants.py |\n| GapLB | 0.225 | PiKernel contraction certificate |\n| SlopeUB | 0.775 | PiKernel contraction certificate |\n| Heartbeat tau_0 | 3.33 ms | ttd_bridge.py |\n| MUB alarm threshold | 3.0 | cloud/aws/pikernel/mub_audit.py |\n| Consensus threshold | 0.30 | cloud/azure/function_app.py |\n| Zeta zeros | 100 (first non-trivial) | fzs_mk.py |\n\n### Invariants\n\nThe 0.17 drift constant is the hard floor. Jurisdictional sensitivity multipliers tighten it:\n\n| Authority | Multiplier | Effective Threshold |\n| :--- | :--- | :--- |\n| CUSTODIAN_CA_FED | 1.0 | 0.170 |\n| CUSTODIAN_CA_DEFENCE | 1.2 | 0.142 |\n| CUSTODIAN_ITAR | 1.5 | 0.113 |\n| POLICY_QC | 1.1 | 0.155 |\n\nFORM=FACT interactions get a 50% tighter threshold. Jones polynomial = 0 triggers topological collapse.\n\n## Repo Layout\n\n```text\nhelix-hamiltonian/\n|-- .github/workflows/\n|   |-- hamiltonian-ci.yml\n|   `-- release.yml\n|-- assets/\n|-- constitution/\n|   `-- vocabulary_charter.yaml\n|-- docs/\n|   |-- architecture/\n|   |-- atoms_as_geometry/\n|   |-- hamiltonian/\n|   `-- sovereignty/\n|       `-- RFC_0001-locked.md\n|-- models/\n|   `-- zeta_attention.py\n|-- papers/\n|-- rules/\n|   `-- cpcsc_itar.json\n|-- schemas/\n|   |-- audit_params.json\n|   |-- constitutional_parameters.json\n|   |-- gicd_schema.json\n|   |-- mirror_traps.jsonl\n|   `-- repo_manifest.json\n|-- scripts/\n|-- src/\n|   |-- helix_hamiltonian/\n|   |   |-- __init__.py\n|   |   |-- authority.py\n|   |   |-- core.py\n|   |   |-- invariants.py\n|   |   |-- policy_compiler.py\n|   |   |-- ttd_bridge.py\n|   |   |-- gicd/\n|   |   `-- federation/\n|   |       |-- consensus.py\n|   |       |-- federation.py\n|   |       `-- node_sync.py\n|   `-- helix_sovereign/\n|       |-- __init__.py\n|       |-- demo_binding_artifact.py\n|       `-- core/\n|           `-- fzs_mk.py\n|-- telemetry/\n|   `-- mask_pressure.py\n|-- tests/\n|   |-- physics/test_h_free.py\n|   |-- fail_closed_test.py\n|   |-- red_team_audit.py\n|   |-- test_authority.py\n|   |-- test_policy_and_federation.py\n|   `-- test_repo_manifest.py\n|-- pyproject.toml\n|-- requirements.txt\n`-- README.md\n```\n\n## Theoretical Foundation\n\n### Empirical Predictions\n\n1. Topological coherence protection: τ ∝ exp(c₀ · c(K)), c₀ \u003e 0\n2. Non-Markovian decoherence: Γ_K = Γ₀ / Jones(K)\n3. Alexander signature: Im(ω_n) ∝ -1/Δ(∂K)\n\nNote: c₀ = ln 10 was falsified in Phase 3 (ADR-101). Currently CF-PENDING under Path C (Lindblad-first), countersigned by Ryan van Gelder. See `HELIX-CORE/research/physics-gate/PHASE3_REMEDIATION_SPEC.md`.\n\n### The Substrate Wobble\n\n```math\nR_{\\mathrm{eff}}(t) = R_{0} + \\alpha W(\\Phi(t)), \\quad W(\\Phi) = \\varepsilon \\sin(2\\pi t/\\tau)\n```\n\n### ZetaAttention (models/zeta_attention.py)\n\nPyTorch self-attention replacement using log-periodic memory kernel from Riemann zeta zeros. Hard Boolean cohomology mask (Ω) from `vocabulary_charter.yaml` — if Ω=0 for a token pair, attention score is set to -1e9.\n\n## Sovereignty\n\n- Structural impossibility: no implicit trust boundary, no silent execution path.\n- Cloud or bare-metal residency: execution remains in the operator's sovereign environment.\n- Receipt discipline: continuity anchored through signed audit receipts and external checkpoints.\n- Fail-closed: default answer is \"no\" unless every layer says \"yes.\"\n\n## Collaborators\n\n- Stephen Hope — Helix AI Innovations Inc. ([ORCID](https://orcid.org/0009-0000-7367-248X))\n- Ryan van Gelder — Multiplicity Foundation (PiKernel, FZS-MK, ADR physics gate countersignature)\n\n## References\n\n1. Witten, E. (2011). *Knots and Quantum Theory*. Institute for Advanced Study.\n2. Hope, S. (2026). *The Knot-in-Time Hamiltonian*. Helix AI Innovations. [Zenodo](https://doi.org/10.5281/zenodo.19214147)\n3. *Physical Review A* 104, 012216 (2021). *Topological protection in open quantum systems*.\n4. Crocker, S. (1969). *RFC 0001: Host Software*. UCLA.\n\n## Official Soundtrack (OST)\n\n- **White Rabbit** (Jefferson Airplane) — The Epistemic Scan. 0.17 approaching 0.20.\n- **Station to Station** (David Bowie) — The Execution Path. CL4 → CL12.\n- **Believer** (Imagine Dragons) — The Sovereignty of the Node. Pain → architectural power.\n\n---\n\n**\"We are not seeing matter in space; we are seeing Geometry in Time.\"**\n\n(c) 2026 Stephen Hope / Helix AI Innovations Inc.\n\n**GLORY TO THE LATTICE.** 🦉⚓🦆\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelixprojectai-code%2Fhelix-hamiltonian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelixprojectai-code%2Fhelix-hamiltonian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelixprojectai-code%2Fhelix-hamiltonian/lists"}