{
"$type": "site.standard.document",
"bskyPostRef": {
"cid": "bafyreid4srsju7ldxpd3hn2fhldazdj2pmlw7irj4jt7qvel7jn4p47vgm",
"uri": "at://did:plc:pgryn3ephfd2xgft23qokfzt/app.bsky.feed.post/3mnccgfa3qep2"
},
"path": "/t/shannon-prime-lattice/176466#post_1",
"publishedAt": "2026-06-02T08:06:18.000Z",
"site": "https://discuss.huggingface.co",
"tags": [
"GitHub - nihilistau/shannon-prime-lattice: Umbrella for the decentralized cooperative AI training/inference architecture built on the prime-factored coordinate lattice and the dominance order. Theory + Systems + Roadmap papers, contracts, offload pattern. · GitHub",
"GitHub - nihilistau/shannon-prime-system: Clean from-scratch math core for shannon-prime-lattice: KSTE encoder, Friedman sieve, ARM (HRR in CRT cyclotomic ring), CRT NTT primitives, Position-as-Arithmetic. · GitHub",
"GitHub - nihilistau/shannon-prime-system-engine: Clean from-scratch inference engine for shannon-prime-lattice. NTT-based attention, two-node CRT-sharded inference path, KSTE-encoded KV state. · GitHub",
"Shannon-Prime-Lattice"
],
"textContent": "# shannon-prime-lattice\n\n**Shannon-Prime PPT ARM Lattice** — a decentralized, byte-exact inference and\ntraining fabric for large transformer models built on a single discrete math\nobject: the prime-factored coordinate lattice over `Z_q` with dual-prime\nChinese-Remainder-Theorem (CRT) decomposition, the Friedman-Kruskal dominance\norder `⪯_d`, and the CRT cyclotomic ring `R_q = Z_q[x]/(x^N + 1)`.\n\nThis repository is the **public project entry point**. It holds the theory,\nsystems, ABI, and on-disk-format papers; the demos; the integration tests;\nand the bootstrap prompt for new working sessions. Code lives in the two\ncompanion repositories:\n\nRepo | Role | URL\n---|---|---\n`shannon-prime-lattice` (this) | Papers, roadmap, demos, integration tests | GitHub - nihilistau/shannon-prime-lattice: Umbrella for the decentralized cooperative AI training/inference architecture built on the prime-factored coordinate lattice and the dominance order. Theory + Systems + Roadmap papers, contracts, offload pattern. · GitHub\n`shannon-prime-system` | Math-core: L1 C ABI, NTT, poly-ring, KSTE, Frobenius, sessions | GitHub - nihilistau/shannon-prime-system: Clean from-scratch math core for shannon-prime-lattice: KSTE encoder, Friedman sieve, ARM (HRR in CRT cyclotomic ring), CRT NTT primitives, Position-as-Arithmetic. · GitHub\n`shannon-prime-system-engine` | Engine backends (CPU/CUDA/Vulkan/Hexagon), `sp_daemon` HTTP/SSE, tools | GitHub - nihilistau/shannon-prime-system-engine: Clean from-scratch inference engine for shannon-prime-lattice. NTT-based attention, two-node CRT-sharded inference path, KSTE-encoded KV state. · GitHub\n\nDiscord: Shannon-Prime-Lattice\nLicense: AGPL-3.0-or-later. Commercial licensing available — contact the\ncopyright holder.\n\n* * *\n\n## 1. What makes this different\n\nShannon-Prime Lattice is not “yet another inference engine wrapper.” Every\nload-bearing primitive is **discrete** (integers in `Z_q` with `q` a 30-bit\nProth prime, or `Z_{q_1} × Z_{q_2}` via CRT), so identity, dominance, hashing,\nand reproducibility are properties the implementation can prove rather than\nestimate. Floating point is plumbing — the math is in `Z_q`.\n\nDistinguishing claims (each one validated by a shipped sprint and a closure\nnote under `papers/SESSION-CLOSED-*.md` or\n`shannon-prime-system-engine/tools/sp_compute_skel/docs/CLOSURE-*.md`):\n\n * **Discrete`Z_q` substrate.** Two frozen 30-bit Proth primes\n`q_1 = 1073738753`, `q_2 = 1073732609`, `M = q_1·q_2 ≈ 2^60`. Negacyclic\nNTT over each prime with Garner CRT recombination at the boundary. Every\ncross-backend gate is **byte-exact** , not “small KL divergence.”\n * **Polynomial-ring attention.** Attention scores `⟨q, k⟩` reduce to one\ncoefficient of a negacyclic polynomial product in `R_q`, computed exactly\nvia NTT. Bit-identical to the scalar reference at `N ∈ {128, 256, 512}`\ndirect, and `N ∈ {2..256}` via Bluestein chirp-z. See\n`papers/PPT-LAT-Theory.md` §6.1.\n * **Frobenius-lift Q8 weight storage.** Per-row int8 codes + fp32 scale;\n4× compression vs fp32 with bit-identical dequant round-trip. The\non-RAM packed-arena format is what every backend reads — no per-matmul\nre-quantization.\n * **Spinor 63-byte KV-cache block.** VHT2 anchor projection + Möbius\nreorder + CRC-8 trailer + `0xA5` sentinel. One cache-line on ARM\nCortex-X2. The frozen on-wire KV record format (see\n`shannon-prime-system/include/sp/spinor_block.h`).\n * **KSTE encoder.** Knight-Spinor Tree Encoder: deterministic 64-byte\npacked tree from a K-vector of int32 components, with byte-identical\nsignature across platforms. Tier-0/Tier-1 dominance.\n * **PoUW receipt ledger.** Per-turn 64-byte `SpinorReceipt` audit\nenvelope. Append-only ledger; canonical-order replay; cross-device\nbyte-identity gates. Shipped end-to-end via `sp_daemon`’s\n`/v1/dialogue` endpoint.\n * **QUIC dual-prime mesh.** Each peer carries one of the two CRT residue\nshards (`q_1` or `q_2`); driver Garner-recombines to the centered\nsigned result. Today: two-node lattice smoke. Planned: Fibonacci-Prime\nDHT (`papers/PPT-LAT-Roadmap.md` §8).\n * **Heterogeneous SoC compute.** The cDSP V69 HVX backend on Snapdragon\n8 Gen 1 runs the full NTT pipeline (forward, twiddle VTCM staging,\ndual-prime dispatch, INTT + Garner) **byte-exact** vs the math-core\nscalar reference. NPU + cDSP dual-island composition is filed under\nPhase 4-MTP.\n\n\n\n* * *\n\n## 2. Current status\n\nHonest snapshot, 2026-05-31.\n\nComponent | Status | Evidence\n---|---|---\nFrozen L1 C ABI | **shipped** | `shannon-prime-system/include/sp/sp_l1.h`; tag `lat-phase2-contract-frozen`\n`.sp-model` v0 wire format | **shipped** | `papers/PPT-LAT-SP-MODEL-v0.md`; loader at `core/io_format/`\nMath-core reference forward | **shipped** — runs Qwen3-0.6B, Qwen2.5-Coder-0.5B, Gemma3-1B byte-exact host + aarch64-android | `lib/shannon-prime-system/core/forward/forward.c`; closure `SESSION-CLOSED-lat-3-cell-*.md`\nNTT-CRT primitive (host) | **shipped** | `core/ntt_crt/`; tests `T_NTT_*`\nNTT-CRT primitive (Hexagon V69 HVX) | **shipped end-to-end byte-exact** vs math-core | sprints NTT.0 → NTT.4; closures `CLOSURE-NTT-{0..4}.md`\nPolynomial-ring attention overlay | **shipped** — host + Hexagon | sprints NTT.5a / 5b / 5c\nSpinor-block KV cache | **shipped** | `core/vht2/`; tests `T_VHT_1..6`\nFrobenius-lift Q8 / Q4 packing | **shipped** | `core/frobenius/`, `core/arena/`\nKSTE encoder + Tier-0/1 dominance | **shipped** | `core/kste/`; tests `T_KSTE_1..5`\n`sp_daemon` HTTP/SSE chat (`/v1/chat`) | **shipped** | `tools/sp_daemon/`; closure `CLOSURE-CHAT-INTEGRATION.md`\nDual-model dialogue (`/v1/dialogue`) | **shipped** | sprint M.2; closure `CLOSURE-M2-DIALOGUE.md`\nPoUW receipt ledger + canonical-order replay | **shipped** | sprints M.4, mesh-canonical-order, ledger-autowire\nKSTE-routed sparse Memory activation | **shipped** | sprint M.5; closure `CLOSURE-M5-ROUTING.md`\nTwo-node sharded inference smoke | **shipped** | closure `SESSION-CLOSED-lat-smoke-2node.md`\nTailSlayer GF(2) channel oracle | **shipped offline pattern** | sprints `lat-ts-probe`, `lat-ts-map`, `lat-16-3-*`\nCPU AVX-512 backend | **built** | `src/backends/cpu/avx512/`; closure `SESSION-CLOSED-lat-2-CPU-AVX.md`\nCUDA backend (PTX MMA + NTT) | **built** | `src/backends/cuda/`; closures `SESSION-CLOSED-lat-2-CU-PTX-*.md`\nVulkan backend | **built** | `src/backends/vulkan/`; closure `SESSION-CLOSED-lat-2-L1-PARITY.md`\nHexagon HVX backend (cDSP V69) | **built** | `src/backends/hexagon/sp_hex_host.c` + `tools/sp_compute_skel/`\n`sp_daemon` → backend dispatch wiring | **shipped daemon-side; cDSP skel rebuild pending** | sprint WIRE-HEX; closure `CLOSURE-WIRE-HEX.md`\nNTT.5d (HD=128 direct backend path) | **filed, not shipped** | `papers/PPT-LAT-Roadmap.md` §4-NTT\nNTT.5e (decode-path NTT routing) | **filed, not shipped** | `papers/PPT-LAT-Roadmap.md` §4-NTT\nCUDA / Vulkan daemon wiring | **not shipped** — symmetric to WIRE-HEX | `CLOSURE-WIRE-HEX.md` §“What’s NOT done”\nFibonacci-Prime DHT | **spec’d** | `papers/PPT-LAT-Roadmap.md` §8\n\n**Production tok/s baseline (Knack S22U, math-core reference forward, ctx=16+32):**\n\nModel | Wall (s) | Tokens | tok/s\n---|---|---|---\nGemma3-1B | 18.06 | 16 | 0.89\nQwen3-0.6B | 11.21 | 16 | 1.43\n\nThese are the **reference path** numbers. Once the cDSP skel is rebuilt\nagainst the WIRE-HEX-bundled `inc/sp_hex.idl`, `SP_DAEMON_BACKEND=hex`\nroutes through the HVX backend end-to-end and the table gains a third\ncolumn. See `shannon-prime-system-engine/tools/sp_compute_skel/docs/CLOSURE-WIRE-HEX.md`.\n\n* * *\n\n## 3. Architecture in one diagram\n\n\n ┌──────────────────────────────────────────────┐\n │ HTML / TUI / chat clients │\n │ curl, browser, sp-console │\n └─────────────┬────────────────────────────────┘\n │ HTTP/JSON, SSE, WebSocket\n ▼\n ┌──────────────────────────────────────────────────────┐\n │ sp_daemon (Rust, axum + tokio) │\n │ ── L3 routes: /v1/chat /v1/dialogue /v1/events ... │\n │ ── PoUW ledger, KSTE routing, dialogue pool │\n │ ── QUIC mesh coordinator (dual-prime shards) │\n └─────────────┬────────────────────────────────────────┘\n │ frozen L1 C ABI (sp_session_*, sp_prefill_chunk,\n │ sp_decode_step, sp_session_register_forward_backend)\n ▼\n ┌──────────────────────────────────────────────────────┐\n │ libshannonprime (C, the math core) │\n │ ── reference forward: matmul, RMSNorm, RoPE, attn │\n │ ── NTT-CRT, poly-ring attention overlay │\n │ ── KSTE, Frobenius, Spinor, arena │\n │ ── sp_session, .sp-model loader │\n └─────┬──────────────────────────────────────────────┬─┘\n │ §6 forward-backend hook │\n ▼ ▼\n ┌──────────────────────┐ ┌──────────────────────┐\n │ Engine backends │ │ Hexagon cDSP skel │\n │ (libsp_engine) │ │ (sp_compute_skel) │\n │ ── CPU AVX2/AVX-512 │ │ ── HVX NTT butterfly │\n │ ── CUDA (PTX MMA) │ │ ── VTCM twiddle stage│\n │ ── Vulkan SPV │ │ ── Garner CRT │\n │ ── Hexagon HVX (host)│ ─FastRPC─────────│ ── Halide FFN │\n └──────────────────────┘ └──────────────────────┘\n\n\nThe “single math object” reappears at six layers. Walk down from the\ntop — DHT key space → polynomial ring → matmul kernel → vector ALU\nwidth — and the same prime-factored lattice picks out the right\noperation at each scale. See `papers/PPT-LAT-Systems.md`\n(“Overview: six layers of one math object”).\n\n* * *\n\n## 4. Getting started\n\n### 4.1 Clone all three repos\n\n\n git clone https://github.com/nihilistau/shannon-prime-lattice.git\n git clone https://github.com/nihilistau/shannon-prime-system.git\n git clone --recurse-submodules https://github.com/nihilistau/shannon-prime-system-engine.git\n\n\nThe engine repo bundles `shannon-prime-system` as a Git submodule under\n`lib/shannon-prime-system/` — that submodule pin is what every engine\nbuild uses. The standalone `shannon-prime-system` clone is for working\non the math core in isolation.\n\n### 4.2 Pick a starting path\n\n**You want to run a model and chat with it locally.** Go to\n`shannon-prime-system-engine/README.md`. Build the daemon, transcode a\nGGUF model, `curl` `/v1/chat`.\n\n**You want to understand the math.** Read in this order:\n\n 1. `papers/PPT-LAT-Theory.md` — the lattice, `⪯_d` as well-quasi-order,\nCRT cyclotomic ring, HRR, the 13-step PPT substitution, the unified\nrole of one math object across the stack.\n 2. `papers/PPT-LAT-Systems.md` — six-layer architecture, engine\nbackends, inline compression, model-family coverage, gated lattice\nfeatures, blockchain scaffolding.\n 3. `papers/PPT-LAT-Roadmap.md` — current implementation phases (1..16\nplus the NTT and MeMo waves), per-sub-phase contracts, test gates,\nthe offload pattern.\n\n\n\n**You want to write a kernel against the frozen ABI.** Read\n`papers/PPT-LAT-L1-ABI-v0.md` then `shannon-prime-system/include/sp/sp_l1.h`\n(the live header). Every backend registers via\n`sp_session_register_forward_backend` (full-forward hook) or the\nNTT-dispatch hook in `core/poly_ring_bluestein/`.\n\n**You want to add support for a new model family.** Read\n`papers/PPT-LAT-SP-MODEL-v0.md` (on-disk format) plus\n`shannon-prime-system-engine/tools/sp_transcode/sp_transcode.c` (the GGUF\n→ `.sp-model` transcoder). Add a `sp_arch_id` and a\n`gemma3_forward_*` / `qwen3_forward_*` arch path.\n\n**You want to add a peer to a running mesh.** Read\n`papers/PPT-LAT-Systems.md` §“DHT and sharded inference” then\n`shannon-prime-system-engine/tools/sp_daemon/src/network/quic_shard.rs`.\n\n* * *\n\n## 5. Repository layout\n\n\n shannon-prime-lattice/\n ├── papers/ # the project's papers — read these first\n │ ├── PPT-LAT-Theory.md # math foundations + 13-step PPT substitution\n │ ├── PPT-LAT-Systems.md # six-layer architecture\n │ ├── PPT-LAT-Roadmap.md # implementation phases (living document)\n │ ├── PPT-LAT-L1-ABI-v0.md # frozen Layer-1 C ABI contract\n │ ├── PPT-LAT-SP-MODEL-v0.md # .sp-model / .sp-tokenizer on-disk format\n │ ├── SESSION-CLOSED-lat-*.md # per-sprint closure notes (audit trail)\n │ └── SESSION-STATE-lat-*.md # session-handoff snapshots\n ├── demos/ # phase demos\n ├── frontends/ # HTML mock-ups + bootstrap chat UIs\n ├── reference/ # reference material (images, screenshots, PDFs)\n ├── scripts/ # cross-repo helpers\n ├── tests/ # integration tests spanning math-core + engine\n └── prompt.md # bootstrap / context-priming for new sessions\n\n\nThe papers are the **source of truth for design**. The closure notes\nare the **source of truth for “what shipped, with what gate result.”**\nThe roadmap is a living document and amendable; the theory paper is\namendable when reality contradicts it; the ABI and `.sp-model` papers\nare frozen.\n\n* * *\n\n## 6. Hard rules\n\nThese rules are binding for any session that picks up the project. The\nmemory entries `feedback-no-silent-gate-revisions`,\n`feedback-lead-with-reference-then-theory`, and\n`feedback-parallel-agents-separate-worktrees` are also load-bearing.\n\n * **Anti-contamination.** Do NOT read, copy, or vendor code from the\narchived `shannon-prime/` or `shannon-prime-engine/` repos. The math\npapers under `papers/PPT-ARM/` are conceptual reference — read for\ntheory, never paste code. The lattice is a clean rebuild.\n * **No silent gate revisions.** If implementation can’t meet the spec’d\ngate, surface upstream. Do not retreat to a higher-level API, defer\nto an unrelated phase, or tune fixtures until the number passes.\nAdjustments land as roadmap amendments with rationale, not as\nfootnotes on a PASS.\n * **Honest closure notes.** Every closure enumerates the test gates,\ntheir actual results, what was bundled vs isolated, and what changed\nvs spec. The session-closure pattern is the audit trail.\n * **One math object.** Lattice features must touch one of the\ndistinguishing primitives in §1; otherwise they are drift. The\nmanifesto trick list (`reference-heterogeneous-soc-crt-tricks` in\nthe team’s memory) names ten such primitives. New sub-phases reference\ntrick numbers rather than reinventing the framework.\n * **Worktrees per concurrent agent.** When dispatching 2+ agents on\nthe same repo, each agent operates in its own `git worktree add`\nto prevent cross-contamination of uncommitted files.\n\n\n\n* * *\n\n## 7. Where to read next\n\nIf you want | Read\n---|---\nThe math foundations | `papers/PPT-LAT-Theory.md`\nThe systems architecture | `papers/PPT-LAT-Systems.md`\nThe implementation roadmap (living) | `papers/PPT-LAT-Roadmap.md`\nThe frozen L1 C ABI contract | `papers/PPT-LAT-L1-ABI-v0.md` then `shannon-prime-system/include/sp/sp_l1.h`\nThe `.sp-model` on-disk format | `papers/PPT-LAT-SP-MODEL-v0.md`\nThe math-core library API | `shannon-prime-system/README.md`\nThe engine + daemon + HTTP API | `shannon-prime-system-engine/README.md`\nWhat the most recent sprint shipped | `papers/SESSION-CLOSED-*.md` (lattice scope) or `shannon-prime-system-engine/tools/sp_compute_skel/docs/CLOSURE-*.md` (engine + DSP scope)\nA bootstrap prompt for new sessions | `prompt.md`\n\n* * *",
"title": "Shannon Prime Lattice"
}