[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"pALY8nst07":3},"# UOR Prime Structure FFI\n\nA Lean 4 implementation of the Prime Structure/Φ-Atlas-12288 mathematical framework with FFI bindings for multiple languages.\n\n## Overview\n\nThis project implements the core mathematical concepts from the Universal Object Reference (UOR) Prime Structure specification, providing:\n\n- **12,288-element structure** (48×256) representing the fundamental mathematical object\n- **R96 resonance classifier** mapping 256 byte values to 96 resonance classes (3/8 compression)\n- **Φ boundary encoding** for page/byte coordinate packing\n- **Truth ≙ conservation** budget semantics\n- **Multi-language FFI** supporting Go, Rust, Node.js, and C\n\n## Mathematical Background\n\nThe Prime Structure is built on several key mathematical principles:\n\n- **Unity Constraint**: α₄α₅ = 1 creating fundamental symmetries\n- **96 Resonance Classes**: Exactly 96 distinct values from 8-bit patterns\n- **Conservation Laws**: Triple-cycle invariant with sum 687.110133...\n- **Holographic Duality**: Bulk↔boundary correspondence via master isomorphism Φ\n\nFor detailed mathematical context, see the formal Lean implementation in the `/lean/` directory.\n\n## Repository Structure\n\n```\n/\n├─ README.md                         # This file\n├─ lean-toolchain                     # Lean version specification\n├─ lakefile.lean                      # Build configuration\n├─ lean/\n│  └─ UOR/\n│     ├─ Prime/\n│     │  └─ Structure.lean           # 48×256 boundary + R96 (core math)\n│     ├─ Atlas/\n│     │  └─ Core.lean                # Φ-Atlas-12288 record instance\n│     ├─ FFI/\n│     │  └─ CAPI.lean                # Exported C ABI\n│     └─ Verify/\n│        └─ CLI.lean                 # CLI for testing\n├─ ffi/\n│  └─ c/\n│     ├─ uor_ffi.h                   # C header: stable ABI\n│     ├─ minimal_wrapper.c           # Minimal C implementation\n│     └─ uor_init.c                  # Lean runtime initialization\n├─ pkg/\n│  ├─ go/                            # Go bindings (basic)\n│  ├─ python/                        # Python bindings\n│  ├─ rust/                          # Rust bindings (basic)\n│  └─ node/                          # Node.js bindings\n├─ runtime/\n│  ├─ go/                            # Enhanced Go wrapper\n│  ├─ rust/                          # Enhanced Rust wrapper\n│  └─ node/                          # Enhanced Node.js wrapper\n└─ tests/\n   └─ c/test_ffi.c                   # C smoke test\n```\n\n## Building\n\n### Prerequisites\n\n- Lean 4 (stable release)\n- C compiler (gcc/clang)\n- GNU Make\n- Optional: Go, Rust, Node.js for language-specific wrappers\n\n### Quick Start with Make\n\nThe project includes a hierarchical Makefile system for easy building:\n\n```bash\n# Build everything (Lean library, FFI, and runtime wrappers)\nmake all\n\n# Run all tests\nmake test\n\n# Quick verification check\nmake check\n\n# Install to system (requires sudo for default prefix)\nsudo make install\n\n# Clean all build artifacts\nmake clean\n```\n\n### Make Targets\n\n#### Main Targets\n- `make all` - Build everything (lean, ffi, runtime)\n- `make lean` - Build Lean library only\n- `make ffi` - Build FFI components\n- `make runtime` - Build all language wrappers\n- `make test` - Run all tests\n- `make check` - Quick verification test\n- `make clean` - Remove all build artifacts\n- `make install` - Install libraries and headers\n- `make format` - Format source code (if formatters available)\n- `make docs` - Build comprehensive documentation\n\n#### Subdirectory Targets\n```bash\n# Build specific components\nmake -C lean all        # Build Lean library and executable\nmake -C ffi all         # Build FFI layer and tests\nmake -C pkg all         # Build all language bindings (basic)\nmake -C runtime all     # Build enhanced language wrappers\nmake -C tests all       # Run all tests\n\n# Run specific tests\nmake -C tests test-lean        # Lean verification only\nmake -C tests test-c           # C tests only\nmake -C tests test-pkg         # Package binding tests\nmake -C tests test-runtime     # Enhanced wrapper tests\nmake -C tests benchmark        # Performance benchmarks\n```\n\n#### Configuration Variables\n```bash\n# Build with custom settings\nmake BUILD_TYPE=debug          # Debug build\nmake VERBOSE=1                 # Verbose output\nmake PREFIX=/opt/uor install   # Custom install prefix\nmake NO_COLOR=1                # Disable colored output\n```\n\n## Documentation\n\nThe project includes comprehensive documentation that can be built using the make system:\n\n```bash\n# Build all documentation\nmake docs\n\n# Build specific documentation types\nmake -C docs html      # HTML documentation with navigation\nmake -C docs api       # API reference from Lean sources  \nmake -C docs capi      # C API documentation from headers\nmake -C docs langdocs  # Language wrapper documentation\nmake -C docs markdown  # Collect and process markdown files\nmake -C docs pdf       # PDF documentation (requires pandoc)\n\n# Serve documentation locally\nmake -C docs serve     # Starts HTTP server at localhost:8000\n```\n\n### Documentation Structure\n\nAfter building, documentation is available in `docs/build/`:\n\n- `html/index.html` - Main documentation site with navigation\n- `api/` - Lean API documentation and module reference\n- `capi/` - C API function signatures and constants\n- `lang/` - Go, Rust, and Node.js wrapper documentation\n- `markdown/` - Processed documentation files\n\nThe HTML documentation provides a comprehensive view of:\n- **Getting Started**: README, API reference, C API reference  \n- **Language Bindings**: Go, Rust, Node.js wrapper documentation\n- **Additional Resources**: Documentation index and Lean language links\n\n### Manual Build Steps (without Make)\n\n1. **Build Lean library and CLI**:\n```bash\nlake build\n```\n\nArtifacts will be generated under `.lake/build/lib/` (libUOR.{a,so,dylib})\n\n2. **Build and run CLI verification**:\n```bash\n.lake/build/bin/uor-verify\necho $?  # Should output 0 for success\n```\n\n3. **Build C smoke test**:\n```bash\ncc -Iffi/c -L.lake/build/lib tests/c/test_ffi.c -o tests/c/test_ffi \\\n   -lUOR -lLean -lpthread -ldl\n./tests/c/test_ffi  # Should output \"OK\"\n```\n\n## API Reference\n\n### Constants\n\n- `lean_uor_pages()` → 48 (number of pages)\n- `lean_uor_bytes()` → 256 (bytes per page)\n- `lean_uor_rclasses()` → 96 (resonance classes)\n- `lean_uor_abi_version()` → 1 (ABI version)\n\n### R96 Classifier\n\n- `lean_uor_r96_classify(b)` → [0,95]\n  - Returns the resonance class for byte `b`\n\n### Φ Boundary Encoding\n\n- `lean_uor_phi_encode(page, byte)` → 32-bit code\n  - Packs (page, byte) as `(page \u003C\u003C 8) | byte`\n- `lean_uor_phi_page(code)` → page (mod 48)\n  - Extracts page component\n- `lean_uor_phi_byte(code)` → byte\n  - Extracts byte component (low 8 bits)\n\n### Truth ≙ Conservation\n\n- `lean_uor_truth_zero(budget)` → 0/1\n  - Returns 1 if budget equals 0 (truth)\n- `lean_uor_truth_add(a, b)` → 0/1\n  - Returns 1 if `a + b == 0` (additive conservation)\n\n## Language Bindings\n\nThe repository provides two tiers of language bindings:\n\n### Basic Bindings (`pkg/`)\nMinimal wrappers providing direct access to core functions:\n\n**Go** (`pkg/go/`)\n```go\nimport uor \"github.com/your-repo/pkg/go/src\"\nfmt.Println(\"Pages:\", uor.Pages())      // 48\nfmt.Println(\"R96(255):\", uor.R96(255))  // Class [0,95]\n```\n\n**Python** (`pkg/python/`)  \n```python\nimport uor\nprint(f\"Pages: {uor.pages()}\")         # 48\nprint(f\"R96(255): {uor.r96(255)}\")     # Class [0,95]\n```\n\n**Rust** (`pkg/rust/`)\n```rust\nuse uor_ffi;\nprintln!(\"Pages: {}\", uor_ffi::pages()); // 48\n```\n\n**Node.js** (`pkg/node/`)\n```javascript\nconst uor = require('uor-ffi');\nconsole.log('Pages:', uor.pages());     // 48\n```\n\n### Enhanced Bindings (`runtime/`)\nRich object-oriented APIs with comprehensive types:\n\n**Go** (`runtime/go/`)\n```go\nimport \"path/to/runtime/go/uorffi\"\ncoord := uorffi.NewPhiCoordinate(3, 16)\nfmt.Println(\"Encoded:\", coord.Code())\n```\n\n**Rust** (`runtime/rust/`)\n```rust\nuse uor_runtime::*;\nlet coord = PhiCoordinate::new(3, 16)?;\nprintln!(\"Page: {}\", coord.page());\n```\n\n**Node.js** (`runtime/node/`)\n```javascript\nconst { PhiCoordinate } = require('./runtime/node');\nconst coord = new PhiCoordinate(3, 16);\nconsole.log('Code:', coord.code);\n```\n\n## Mathematical Significance\n\nThe FFI exposes key invariants from the Prime Structure formalization:\n\n1. **R96 Compression**: The 96/256 = 3/8 ratio is a universal compression bound\n2. **Page Structure**: 48-periodic organization emerges from unity constraint\n3. **Conservation Laws**: Truth ≙ conservation at budget 0\n4. **Holographic Principle**: Boundary encodes bulk information\n\n## Testing\n\nRun the verification suite:\n```bash\n# All tests\nmake test\n\n# Component-specific tests\nmake -C lean test               # Lean verification\nmake -C ffi test               # C FFI tests  \nmake -C pkg test               # Basic bindings\nmake -C runtime test           # Enhanced bindings\n\n# Language-specific tests\nmake -C pkg test-go            # Go basic bindings\nmake -C pkg test-python        # Python bindings\nmake -C runtime test-rust      # Rust enhanced bindings\nmake -C runtime test-node      # Node.js enhanced bindings\n```\n\n## Contributing\n\nContributions should maintain the mathematical integrity of the Prime Structure invariants. Key requirements:\n\n- Preserve R96 count (exactly 96 resonance classes)\n- Maintain unity constraint α₄α₅ = 1\n- Ensure conservation laws hold\n- Document any new mathematical insights\n\n## License\n\nThis implementation provides formal verification of the mathematical framework through Lean 4. See individual files for specific licensing information.\n\n## References\n\n- Lean 4 Implementation (lean/UOR/)\n- Prime Structure Module (lean/UOR/Prime/Structure.lean)\n- Atlas Core Module (lean/UOR/Atlas/Core.lean)\n- FFI C API (lean/UOR/FFI/CAPI.lean)",1780242004439]