fix(zig-golden-float): Restore src/ and all deleted files

Revert accidental deletion from commit 35a90c8:
- src/ (25 files): VSA core, VM, JIT, ternary, math
- specs/ (4 files): .tri specifications
- tools/gen/ (9 files): code generators
- examples/ (8 files): multi-language examples
- rust/ (10 files): FFI bindings and safe wrapper
- docs/ (4 files): spec and comparison docs
- build.zig, CLAUDE.md, LICENSE, README.md, install.js

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

Author: Antigravity Agent

CLAUDE.md

@@ -0,0 +1,236 @@
+# zig-golden-float — Claude Code Instructions
+
+**Repository:** https://github.com/gHashTag/zig-golden-float
+
+## Project Overview
+
+Pure Zig implementation of φ-optimized number formats for machine learning:
+- **GF16**: Golden Float16 — [sign:1][exp:6][mant:9]
+- **TF3**: Ternary Float3 — packed ternary format
+
+**Mathematical Foundation:** φ² + 1/φ² = 3 (Trinity Identity)
+
+## Architecture
+
+### Source of Truth
+
+```
+.specs/*.tri → [tri_reader.zig] → tri_gen.zig → {c, rust, zig, cpp}/
+     ↓
+  .tri files are the DNA — all else is phenotype
+```
+
+### Specification Levels
+
+| Level | Format | Capabilities |
+|-------|--------|--------------|
+| 0 — Format | GF16 | Basic: sign, exponent, mantissa, bias |
+| 1 — Ops | GF16 | Arithmetic: add, mul, fma, div, sqrt |
+| 2 — Composite | TF3 | Ternary: trit_mul, ternary_conv, dot_product |
+| 3 — Hardware | GF16 | FPGA: pipeline stages, resource mapping |
+| 4 — Training | GF16 | Training loop: forward/backward, optimizer |
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `specs/gf16.tri` | GF16 format specification |
+| `specs/tf3.tri` | TF3 ternary format specification |
+| `specs/ops.tri` | All arithmetic operations |
+| `specs/TRI-HASHES.md` | SHA256 verification hashes |
+| `src/formats/golden_float16.zig` | GF16/TF3 implementation |
+| `tools/gen/tri_reader.zig` | .tri specification parser |
+| `tools/gen/tri_gen.zig` | Multi-language code generator |
+| `tools/gen/check_tri_hashes.zig` | Hash verification tool |
+
+## Pipeline-First Development
+
+**Golden Rule:** Every new format/operation starts with a .tri spec.
+
+### Workflow
+
+```
+1. Create specs/your_format.tri
+2. zig build test  (verify spec is valid)
+3. zig run tri_gen --lang zig  (generate implementation)
+4. Add tests to generated code
+5. Commit: "feat(format): add your_format (#N)"
+```
+
+### When to Edit Direct Files
+
+**Allowed direct edits (no .tri spec needed):**
+- `src/sacred/` — Sacred constants (PHI, TRINITY)
+- `src/vsa/` — VSA core operations
+- `src/formats/golden_float16.zig` — Core GF16/TF3 implementation
+- `tools/gen/` — Code generation infrastructure
+- `build.zig` — Build system
+- `CLAUDE.md` — This file
+
+**Requires .tri spec first:**
+- New number formats
+- New arithmetic operations
+- New composite operations (matmul, conv)
+- Hardware mappings
+
+## Pre-Commit Checklist
+
+Before every commit:
+
+1. **Verify hashes:** `zig run tools/gen/check_tri_hashes --verify`
+2. **Format code:** `zig fmt src/ tools/ specs/`
+3. **Run tests:** `zig build test`
+4. **Build passes:** `zig build`
+
+## Testing
+
+```bash
+# Run all tests
+zig build test
+
+# Run specific test
+zig test src/formats/golden_float16.zig
+
+# Test .tri spec parsing
+zig run tools/gen/tri_reader --input specs/gf16.tri --verbose
+
+# Generate code from spec
+zig run tools/gen/tri_gen --lang all --dry-run
+```
+
+## Constants
+
+| Symbol | Value | Description |
+|--------|-------|-------------|
+| PHI | 1.6180339887498948 | Golden ratio φ = (1 + √5) / 2 |
+| PHI_SQ | 2.6180339887498948 | φ² |
+| PHI_INV_SQ | 0.3819660112501051 | 1/φ² |
+| TRINITY | 3.0 | φ² + 1/φ² = 3 (exact) |
+
+## Phi-Distance
+
+`|ratio - 1/φ|` — measures how close a format is to golden ratio optimum.
+
+| Format | φ-distance | Rank |
+|--------|------------|------|
+| TF3-9 | 0.018 | 🥇 |
+| **GF16** | **0.049** | 🥈 |
+| IEEE f16 | 0.118 | 3rd |
+
+## Commit Conventions
+
+```
+feat(scope): description (#N)
+fix(scope): description (#N)
+docs(scope): description
+refactor(scope): description
+test(scope): description
+```
+
+Examples:
+- `feat(specs): Add ops.tri specification (#123)`
+- `fix(build): Zig 0.15 compatibility (#124)`
+- `docs(readme): Update installation instructions`
+
+## External Links
+
+- **Trinity Framework:** https://github.com/gHashTag/trinity
+- **IBM DLFloat Paper:** https://research.ibm.com/publications/dlfloat-a-16-floating-point-format-designed-for-deep-learning-training-and-inference
+- **Zig 0.15 Docs:** https://ziglang.org/documentation/0.15.2/
+
+---
+
+## AI Coding Rules (Legacy Russian Rules Below)
+
+## 0. Главная идея
+
+В этом репозитории **источником правды** являются `.tri`‑спеки, а не Zig‑код.
+
+- Все числовые форматы (GF16, TF3 и т.п.) и операции над ними описываются в `specs/*.tri`.
+- Файлы на Zig, C, Rust, C++ считаются _производными артефактами_, которые должны генерироваться из `.tri` с помощью `tools/gen/tri_gen.zig`.
+- Ручное редактирование Zig‑кода допустимо **только** внутри строго ограниченного ядра (TTT), см. ниже.
+
+Если вы — AI‑агент (Claude Code или другой), **не пишите новый Zig‑код напрямую**, кроме явно разрешённых мест.
+
+---
+
+## 1. Где Zig разрешён
+
+Разрешено писать и редактировать Zig‑код **только** в следующих областях:
+
+- ядро числовых форматов и TTT:
+  - `tools/gen/tri_reader.zig` — парсер формата `.tri`;
+  - `tools/gen/tri_gen.zig` — генератор кода из `.tri`;
+  - `src/formats/golden_float16.zig` — минимальные runtime‑обёртки вокруг сгенерированных форматов (GF16, TF3);
+  - специализированное ядро TTT/TF3/GF16, если оно прямо помечено в комментариях как "core TTT kernel".
+
+Во всех этих файлах Zig‑код рассматривается как **часть компилятора/ядра** и может развиваться вручную.
+
+---
+
+## 2. Где Zig ЗАПРЕЩЁН
+
+Во всех остальных частях репозитория:
+
+- нельзя добавлять новые `.zig`‑файлы;
+- нельзя писать "ручную" арифметику GF16/TF3, конвертеры, VSA‑операции и т.п.;
+- нельзя править сгенерированные Zig‑файлы вместо правки `.tri`.
+
+Если нужно:
+
+- новый формат,
+- новая операция (add/mul/fma/sqrt/cmp/min/max),
+- VSA‑операция (dot/bind/bundle),
+- пример использования,
+
+**сначала измените/добавьте `.tri`‑спеку**, затем вызовите генератор:
+
+```bash
+zig run tools/gen/tri_gen --lang all --input specs/gf16.tri
+zig run tools/gen/tri_gen --lang all --input specs/tf3.tri
+```
+
+AI‑агентам: любые изменения в API чисел делайте через `.tri` + `tri_gen`, а не напрямую в `.zig`.
+
+---
+
+## 3. TRI seals: обязательная проверка
+
+Перед любым коммитом, который меняет `.tri`:
+
+1. Запусти:
+   ```bash
+   zig run tools/gen/check_tri_hashes --verify
+   ```
+2. Если скрипт показывает mismatch, сначала запусти режим обновления:
+   ```bash
+   zig run tools/gen/check_tri_hashes --update
+   ```
+   который пересчитает SHA256 для всех известных .tri и перезаписывает `specs/TRI-HASHES.md`.
+3. Повтори проверку — она должна завершиться без ошибок.
+4. Только после этого коммить изменения.
+
+AI-агентам:
+- Нельзя коммитить изменения в `specs/*.tri`, если `check_tri_hashes` сообщает рассинхрон.
+- Нельзя править `specs/TRI-HASHES.md` вручную — только через `--update`.
+
+---
+
+## 4. Правильно/Неправильно
+
+| Неправильно ❌ | Правильно ✓ |
+|----------------|-------------|
+| Добавить `fn gf16_add` в `src/gf16.zig` | Добавить `ops.add` в `specs/gf16.tri`, запустить `tri_gen` |
+| Написать VSA bind вручную в Zig | Добавить `vsa_bind` в `specs/tf3.tri`, регенерировать |
+| Править сгенерированный `.zig` | Править `.tri`, заново сгенерировать |
+| Забыть обновить TRI-HASHES.md | `zig run tools/gen/check_tri_hashes --update` перед коммитом |
+
+---
+
+## 5. Цель таких правил
+
+- Гарантировать, что вся арифметика GF16/TF3 и VSA‑операции описаны **одним стандартом** (`.tri`) и консистентно реализованы во всех языках.
+- Избежать "дрейфа реализаций", когда C, Rust, Zig и C++ начинают вести себя по‑разному.
+- Постепенно **переписать существующий ручной Zig‑код на `.tri` → tri_gen**, чтобы репозиторий стал максимально декларативным и генеративным.
+
+Если вы не уверены, можно ли править конкретный `.zig`‑файл, считайте, что **нельзя**, и сначала ищите соответствующую `.tri`‑спеку или создайте новую.

Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "golden-float"
+version = "1.0.0"
+description = "φ-optimized ML number formats (Zig binary wrapper)"
+license = "MIT"
+repository = "https://github.com/gHashTag/zig-golden-float"
+homepage = "https://github.com/gHashTag/zig-golden-float"
+documentation = "https://github.com/gHashTag/zig-golden-float/blob/main/README.md"
+keywords = ["zig", "ml", "f16", "floating-point", "optimization", "simulation"]
+categories = ["science", "mathematics"]
+readme = "README.md"
+
+[build-dependencies]
+reqwest = { version = "0.12", features = ["blocking"] }
+
+[dependencies]
+[target.'cfg(unix(all(not(target_os = "windows")))'.dependencies]
+libc = "0.2"
+
+[[bin]]
+name = "golden-float"
+path = "src/main.rs"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gHashTag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.