Skip to content

CLAUDE.md

Latest commit

 

History

History
33 lines (20 loc) · 16.6 KB

CLAUDE.md

File metadata and controls

33 lines (20 loc) · 16.6 KB
Raw

CLAUDE.md — shannon-prime-system-engine (the inference engine)

★ CURRENT STATE — KEYSTONE (tag keystone-1, 2026-06-25). Canonical whole-system map: shannon-prime-lattice/papers/PPT-LAT-KEYSTONE.md + PPT-LAT-KEYSTONE-API.md (call surface). KEYSTONE-era surfaces here: the served daemon tools/sp_daemon/ (memory agency in routes.rs — SP_FORGET/SP_DECIDE; the SP_CURRENT_CONVO consolidation hook; the served console frontend_mockups/index.html). FIVE repos now (added shannon-prime-harness). Read the foundation doc before trusting the "Current edge (2026-06-…)" notes below (session history).

This is Shannon-Prime's inference engine. The canonical session bootstrap is D:\F\shannon-prime-repos\shannon-prime-lattice\prompt.md — read it first (project, current state, methodology, machine, doc map, operator). This file is the short version + this repo's specifics.

⚙️ BUILD FROM CLEAN — read before building or debugging a build. The CPU / math-core build uses clang-cl (MSVC-ABI), NOT cl.exe — lib/shannon-prime-system/core/exact_islands/exact_islands.c uses __int128, which cl.exe cannot compile (error C4235). scripts/env/env-cpu.bat is pinned to clang-cl; do not revert it to MSVC (that drift = clean-build RED = a prime cause of the restart cycle). Canonical from-clean chain (build-cpu clang-cl -DSP_ENGINE_WITH_AVX512=OFF -DSP_ENGINE_BUILD_TESTS=OFF → build-host-cuda-backend.bat → cargo build --release --features wire_cuda_backend, CARGO_TARGET_DIR=target-wirecuda) + every gotcha: shannon-prime-lattice/papers/BUILD-ENV-TOOLCHAIN.md (gate G-CLEAN-BUILD; verified GREEN 2026-06-28, commit a69fac7).

Repo role: the inference engine + backends, consuming the math core via the lib/shannon-prime-system submodule. Key surfaces:

  • src/backends/cuda/cuda_forward.cu — the gemma4 CUDA forward + decode (per-layer SWA/global geometry, shared-KV, AltUp/PL=0, softcap), the OK_Q4B k_gemv_q4b_dp4a kernel, the CUDA-graph decode path, the SP_XBAR_* harness (P1 KV splice/capture + P2.a SP_XBAR_EMB entry injection + rank/score lanes), the SP_BYTEEXACT exact-integer islands (RMSNorm/softmax/GELU/RoPE + attention k_attn_decode_win_bx, device dual-prime; default-off = byte-identical null floor), and the additive gemma4_kv_decode_logits (the daemon's token-by-token decode entry). The XBAR experiments + the 12B B1 artifact runs happen here.
  • src/backends/cpu/ (overlay dispatch into the math-core decode), vulkan/, hexagon/.
  • tools/sp_transcode/ — sp_transcode --st: the safetensors-direct pipeline (the ONLY trusted gemma4-12B weight path; GGUF lane is dead, see ledger 06-R8). Writes OK_Q8 / OK_Q4B .sp-model.
  • tools/sp_dsp_smoke/ — the L2 universal Rust crate (orchestrator + scalar bit-exact reference): the dual-prime Barrett / mod-q matmul / Garner CRT / NTT ladder is bit-exact-gated here, and the 4 nonlinear fp32 islands now have exact-integer references in src/sp_islands_q_ref.rs (G-ISLANDS-Q-REF GREEN, RoPE via deterministic fixed-point CORDIC — no libm).
  • tools/sp_daemon/ — the universal resident daemon. Feature wire_cuda_backend drives the real 12B end-to-end through the L1 ABI: prefill via sp_session_register_forward_backend (G-WIRE-CUDA-GEMMA4) and token-by-token DECODE via the new L1 verb sp_session_register_kvdecode_backend (G-WIRE-CUDA-DECODE-GEMMA4, 32/32 == oracle, VRAM flat O(1)); gate bin sp_wire_cuda_decode_gate.
  • tests/test_gemma4_cuda.c, tests/test_xbar_p1_cuda.c, tests/bench_gemv_int8.cu.

Current edge (2026-07-01): FAITHFULNESS AXIS CLOSED END-TO-END on the served 12B chat. The recall+faithfulness stack is now LIVE and closed under ADR-002 (decide in latent, execute in clean text, NEVER fuse; deciders don't execute — lattice papers/PPT-LAT-ADR-002-DECIDE-EXECUTE-SPINE.md). Three legs: (1) the live recall selector is L5-cosine — SP_RECALL_L5=1 (τ=0.30 via SP_RECALL_L5_TAU) matches the query's global-layer-5 embedding (recall.rs l5_query_embed/cos512) against each episode's stored L5 query-key and delivers the episode TEXT in-context; 86.89% paraphrase LIVE, gate G-L5-RECALL-LIVE, engine d9099cd. (2) the generative judge is PARKED — the hard-foreign kill-test showed 0 benefit vs L5-direct+τ (PASSed 15/18), so SP_B3_JUDGE stays built + gated but OFF the hot path (honest negative, not deleted). (3) the zero-prior / private-data hole is CLOSED by a deterministic attribute-grounding gate — the SNE crucible exposed 80% confab + 5% secret-leak on NOVEL entities; SP_RECALL_ATTR_GATE=1 computes recall::attr_absent_ratio(query, fact) and, when the query's salient words are ABSENT (≥SP_RECALL_ATTR_TAU, default 0.5) AND the query carries a high-entropy entity token (recall::query_has_entity_token), sets a ZERO-INFERENCE symbolic decline consumed at the synthesis seam BEFORE decode_step — so NO gemma4 forward runs, confab/leak is mathematically impossible, and the turn resolves in microseconds. Gate G-SNE-ATTRGATE-ZEROINF: confab→0, leak→0, recall 100%, paraphrase untouched; engine HEAD fc2e846. Code: tools/sp_daemon/src/recall.rs (attr_absent_ratio, query_has_entity_token, l5_query_embed, cos512); routes.rs (SP_RECALL_L5 branch + the symbolic_decline synthesis-seam short-circuit). All three flags are default-off = byte-identical null floor; turn on the closed stack with SP_RECALL_L5=1 SP_RECALL_ATTR_GATE=1. NEXT: SWARM re-elevated (mesh/PoUW consolidation) now that the single-node faithfulness axis is closed. Status source of truth lives in the lattice: papers/VERIFIED-SCOREBOARD.md, START-HERE.md, PPT-LAT-KEYSTONE.md, PPT-LAT-FINDINGS-LEDGER.md, PPT-LAT-ADR-002-DECIDE-EXECUTE-SPINE.md.

Prior edge (2026-06-24): WHOLE-MACHINE DIFFUSION-JUDGE PERF ~2x stacked, byte-exact -- + a recall regression to chase + the Cola north-star. The diffusiongemma-26B-A4B MoE judge (cuda_forward.cu dg_* path) got two stacked streaming levers: SP_DG_SCRATCHREUSE (PROVEN default-on, engine e31c70d) hoists the per-expert synchronizing cudaMalloc/cudaFree into a reused device pool (dg_scratch_get/dg_scratch_free), ~1.46x reversed-A/B (OFF 281/285s vs ON 193/194s); SP_DG_ASYNC (byte-exact, default-OFF, promotion HELD, engine 2a1c830) pinned double-buffers the spillover experts (dedicated dg_ustream + 4 slots + up_ev/cons_ev + host-W-A-R guard), ~2x stacked, verified by the SP_DG_MOECHK determinism oracle (per-layer f64 sum + FNV-1a of dmoe): 240/240 single-item + tonight's 1440/1440 6-item concurrency stress OFF==ON. Async parity required fixing a PRE-EXISTING dg_self_cond OOB (harness sized self-cond to CL=16 vs forward C=256 -> a dg_k_softmax_rows/V=262144 vocab-softmax over-read of uninitialised memory), compute-sanitizer memcheck-pinpointed + fixed (zero-init dev alloc + full-canvas sizing). CORRECTION (2026-06-24, later -- earlier CAVEAT WITHDRAWN): the "recall regression" was a misread. The self-conditioning is CORRECTLY wired (tests/test_diffjudge_denoise.c:437 have_prev gate -> step-0 plain forward, steps 1+ feed prior logits); the killed native run scored 8.3% recall, which is the NATIVE judge being weak (95.6% is the EXTERNAL llama.cpp oracle; native was always ~25% single-forward) -- the "iterative denoise rescues the native judge" hypothesis is REFUTED, NOT a regression. SP_DG_ASYNC is byte-exact + default-off; no regression blocks it. prefix-KV RESURRECTED: Cola E1 (verified, _diffgemma_reference/diffusion-gemma.cpp:43-54 + ARCH-NOTES.md:40-52) shows the reference prompt is causal-over-prompt (NEVER attends canvas), so prompt K/V is canvas-invariant, and the reference ships a prefix-KV decode variant (llm_graph_input_attn_diffusion_decode, forward only the canvas per step) -- our 6.9e-4/NaN refutation was FALSE. prefix-KV RECLAIMED: proof re-run shows the K/V delta is fp non-associativity (mask verified asymmetric cuda_forward.cu:5477-5482), and the ANSWER-PARITY gate G-DG-PREFIXKV-PARITY is GREEN (SP_DG_PREFIXKV 0 vs 1 = bit-identical picks + ans_tok over 3 items, fast quicker). The fast path already exists behind SP_DG_PREFIXKV (N6 port). NEXT = wider parity + production speedup sweep, then gate + promote. Cola block-causal does NOT map to prefix-KV (model already prompt-causal); detail lattice papers/DESIGN-COLA-DLM-MAPPING.md section 2 (corrected) + SESSION-HANDOFF.md section 0-NOW correction. Detail: lattice SESSION-HANDOFF.md section 0-NOW + memory project_perf_wholemachine.md.

Prior edge (2026-06-20): the AUTONOMOUS LIBRARIAN (learned W_c head) went LIVE on the served 12B chat (since SUPERSEDED on the hot path by the L5-cosine selector above; SP_B3_WC remains gated-GREEN). A learned W_c head (tools/sp_daemon/src/recall.rs WcHead/load_wc/wc_score; relevance = logsumexp-over-positions then mean-over-heads through a HD=512->r=32 projection) does autonomous instance-level episodic recall: routes.rs SP_B3_WC branch scores every registry episode, takes the (E+1)-way argmax over [episodes, NULL=s0], and replays the winner @SP_REPLAY_MTARGET=42 (bounded mass) or rejects to a clean prompt; default-off (env unset) = byte-identical null floor. Gate G-CHAT-B3-WC-DIV2 = 360/361 recall + 50/50 foreign-reject, int16==f32 lossless, s0=+0.102; G-CHAT-B3-WC-DEPLOY = LIVE on the metal (matched -> RECALL ep_n_div_000 9.858; foreign -> NULL -> clean "Paris"). The relevance foundation is the teacher-forced ablation knockout (SP_B3_SECRET, cudaMemset-ablate the secret's source KV rows: novel -33.56 vs parametric -0.15, TAU=-8.0) which is both the admission oracle and the head's labeler; the curator is tools/xbar_lsh/mint_corpus*.py + the single-pass ep.secret admission. Deploy blob _b3_wc/wc_deploy.bin (WCB1) via tools/xbar_lsh/export_wc_deploy.py; launch run_console_recall.bat; the console Send button toggles to an interrupt (POST /v1/abort/:id, session cancel_flag). Commits edc8079 (deploy) / 87044d8 (head) / f62e6ef (diversity). Boundary thesis extends: autonomous recall is won by a LEARNED head on a DIVERSE corpus, not hand-designed signals (every one a measured negative; corpus diversity was the binding constraint). Detail: lattice CONTRACT-CHAT-FULLSTACK + SESSION-HANDOFF.md §0d.

Prior edge (2026-06-18): the BYTE-EXACT FORWARD is COMPLETE + gated on the real Gemma-4-12B. Byte-exact here = exact-integer arithmetic / cross-machine determinism (the AUDITABILITY mission) — explicitly NOT compression (the incoherence-rotation / column-reorder compression levers were convicted as redundant against the existing per-32-block OK_Q4B at gold PPL 4.6665). The dual-prime LINEAR algebra was already bit-exact-gated in the L2 crate tools/sp_dsp_smoke (Barrett, mod-q matmul, Garner CRT inv=894602413, NTT; primes q1=1073738753 q2=1073732609, M=q1·q2≈2^60 fits u64 → no __int128); the session re-derived that and added the genuinely-new piece: the 4 nonlinear fp32 islands (RMSNorm/softmax/GELU/RoPE) as exact-integer references — tools/sp_dsp_smoke/src/sp_islands_q_ref.rs (G-ISLANDS-Q-REF GREEN host: RMS 5.8e-6 / softmax 1.3e-6 / GELU 2.8e-6 / RoPE 9.2e-6 fidelity, order-immune; RoPE via deterministic fixed-point CORDIC = no libm) + math-core core/exact_islands/ (gate T_EXACT_ISLANDS). The gemma4 CUDA forward converts all 4 islands + attention to exact-integer device kernels behind SP_BYTEEXACT (default-off = byte-identical null floor; device techniques avoid __int128 — __umul64hi, a 64-bit isqrt split for RMS, device CORDIC for RoPE, bx_garner/bx_exp_fixed dual-prime, k_attn_decode_win_bx negacyclic dot). The daemon (tools/sp_daemon, feature wire_cuda_backend) drives the 12B end-to-end: prefill via sp_session_register_forward_backend (G-WIRE-CUDA-GEMMA4) and token-by-token DECODE via the NEW L1 verb sp_session_register_kvdecode_backend + additive gemma4_kv_decode_logits (G-WIRE-CUDA-DECODE-GEMMA4: 32/32 tokens bit-identical to the oracle, VRAM flat O(1)). GATES (real 12B, gemma4-12b-b1.sp-model): G-BYTEEXACT-ISLANDS-CUDA GREEN (on-model RMS 3.8e-5 / GELU 8.2e-7 / RoPE 9.6e-6); G-BYTEEXACT-FORWARD-12B GREEN — Leg A SP_BYTEEXACT off = PPL 4.6665 == baseline byte-identical (null floor), Leg B on = 4.6569 parity, run-to-run BIT-IDENTICAL (determinism = the cross-machine proxy). Commits: engine 69c0588 (lineage 9c2aad3→…→eee3aac→6b9a786→69c0588), math-core submodule d9d96f3; receipts tests/fixtures/xbar_r3/. HONEST CAVEATS: (1) the ONE remaining item is EXTERNAL — a true bit-identical logit check across two PHYSICAL GPUs (needs a 2nd machine; on-machine we have run-to-run determinism + reduction-order immunity as the proxy); (2) PPL parity measured at n=42 (small-N; the −0.21% deflection is within noise); (3) the boundary thesis holds — O_K wins on EXACT ARITHMETIC (the container), structure-on-content compression is measured-inert (honest negatives).

Prior edge (2026-06-18): XBAR memory UNIFIED onto the exact-integer O_K substrate (Q(√-163)) — the organism breathes end-to-end on the discrete container. The whole memory stack was re-carried off generic float carriers onto the engine-native dual-prime negacyclic CRT-NTT (math-core core/ntt_crt + core/poly_ring; frozen primes q1=1073738753 q2=1073732609 M=1152908312643096577). G-R3-BIND-on-O_K Leg A (0019b86): Ring-3 VSA bind 256/256 bit-identical to native sp_pr_mul/ntt/sp_pr_score_kstore; ±1 carrier int==float recall; reduction-order-immune (M byte-identical across permutations vs float 4.44e-15 drift); tools/ring3/g_r3_bind_ok.py. G-R3-ORGANISM-NATIVE (1f0f6be): live dualroute + nightshift ripped off float-FFT, now on native sp_pr_mul via tools/ring3/ok_bind.py (D=1024 = two 512-blocks; CAP=32 preserved). G-R2-FROB (dbe4103/d076797): Frobenius π^k INTEGER Ring-2 episode store, rank-2 O_K lattice (coarse a + residual b; a16 ~lossless / a8b4 12b / a16b8 24b sub-ULP relL2 1.2e-7 @ 0.76× store); tools/curator/frob_episode.py. HONEST: "lossless" = reconstruction fidelity; the n=42 PPL gate is blind below ~1% (no fake +0.000%). G-XBAR-ORGANISM-FULL (15e7051): full loop on REAL episodes — continuous audio (EAR) → C2 256-bit sig → native integer Ring-3 superposition (with text decoys) → audio-cue retrieve top-1 → C2 Hamming verify (accept audio / reject text) → Frobenius integer store → continuous float lands clean into the 12B resident cache (checks=5 fails=0); tools/ring3/g_xbar_organism_full.py. G-PERIOD6-REBASE (d2d7ceb): C2/Ring-3 content-hash period 8→6 to the true gemma4 global layers {5,11,…,47}, re-gated GREEN. BOUNDARY THESIS: O_K wins on EXACT ARITHMETIC (the container); every structure-on-content lever is measured-inert and kept as an honest negative — Leg B split-prime O_K Dirichlet carriers (d7d96fe, operationally inert), G-R3-MOBIUS (1e70763, sheds memories 1.000→0.969@N=32), G-R2-FROB-ENTROPY (e6d17bb, 1.02× dead weight — lever is bit-width), G-T2-WEIGHTS (ac76c8e, T2-Möbius fails on the real gemma-4-12b embedding, recon cos 0.032 == random). Receipts in tests/fixtures/xbar_r3/ + tests/fixtures/xbar_organism/. The one-shot gemma4_decode_cuda stays byte-untouched (null floor); all new work is host/env-gated. NEXT = T4 Frobenius π^k of the 9.4GB model WEIGHTS (validated lever, untouched), then KAIROS post-organism.

Build: CUDA host = VS2019 BuildTools + CUDA, build-cuda/ dir, ninja (sm_75 on the dev 2060). Canonical CPU = MinGW gcc 15.2, build/ dir (MSVC cannot build CPU). Authoritative doc: docs/BUILD-ENV.md. GPU numbers need warmup + long window + both clocks pinned (-lgc is SM-only; a weight-GEMV is memory-bound).

Git (binding lesson): lib/shannon-prime-system is a submodule of the same repo as the standalone shannon-prime-system checkout, so the two can diverge. git fetch + check behind before building/committing; commit + push every repo touched per milestone.

Non-negotiables: receipts-first (no number without a command); bit-exact / top-1-lossless gates per precision; no silent gate revision (surface upstream); reference-first when porting (read llama.cpp / the reference with file:line before coding); check code + commits + git fetch before trusting memory; verify Gemini's claims; drive by default; bakes are OS-owned + log-tailed, never poll-watched. Full detail in lattice prompt.md.

Environment & credentials (2026-06-11): compute lanes, shells/traps, storage law (incl. the models\ SHA-pairing rule) → lattice ENVIRONMENT.md. Current state/queue → lattice SESSION-HANDOFF.md. Secrets → archive\notes_and_stuff\creds\claude-credentials.txt (outside all repos; reference paths, never values).