anima-python 0.13.1__py3-none-any.whl

anima_py/core/engine_g.py

@@ -0,0 +1,129 @@
+# ==========================================================================
+# ⛔ ENGINE-INTERNAL / DEPRECATED py-MIRROR — DO NOT RUN OR SCORE DIRECTLY
+# 측정/학습/서빙/직렬화는 cli/ 단일진입만: anima eval | train | serialize
+#   (canonical = hexa core/*.hexa 단일 SSOT; py 미러는 2026-06-28 폐기, DIRECTIONAL).
+# 이 파일을 `python3 core/engine_g.py` 로 직접 실행하거나 side-harness로 import-채점하면
+# = 단일진입 우회(#2603 위반) + terminal verdict 불가. cli/가 import하는 경로만 허용.
+# ==========================================================================
+import sys as _anima_entry_guard
+if __name__ == "__main__":
+    _anima_entry_guard.exit("⛔ engine_g.py 직접 실행 금지 — cli/ 단일진입(anima eval/train/serialize, canonical=hexa) 경유. #2603")
+
+"""core/engine_g.py — PY PRODUCTION ENGINE: byte-faithful 1:1 port of
+core/engine_g.hexa (Engine G — motivation + emit gate).
+
+Per CLAUDE.md a_two_production_mirror. Closed-form spontaneous machinery: the
+8-factor weighted motivation_score + emit/safety predicates. Values are
+byte-identical to the anima_alive PROACTIVE_THRESHOLD / weights (sum=1.0) lineage,
+so CORE and the chat daemon share one behaviour. brain.py couples this (G) with
+Engine A (pure_field.py). No external math builtins — pure float arithmetic.
+"""
+
+# ── thresholds (anima_alive carry) ──
+def spont_im_threshold():
+    return 0.3            # PROACTIVE_THRESHOLD
+
+
+def spont_interrupt_threshold():
+    return 0.6            # talker interrupt
+
+
+def spont_idle_speak_after():
+    return 30.0           # IDLE_SPEAK_AFTER
+
+
+def spont_min_emit_interval():
+    return 30.0           # rate-limit convention
+
+
+# ── 8 weights (sum = 1.00 closed conservation) ──
+def spont_weight_relevance():
+    return 0.20
+
+
+def spont_weight_info_gap():
+    return 0.10
+
+
+def spont_weight_curiosity():
+    return 0.15
+
+
+def spont_weight_pain():
+    return 0.10
+
+
+def spont_weight_coherence():
+    return 0.10
+
+
+def spont_weight_originality():
+    return 0.10
+
+
+def spont_weight_balance():
+    return 0.15
+
+
+def spont_weight_dynamics():
+    return 0.10
+
+
+# ── motivation_score (linear weighted sum) ──
+def motivation_score(rel, gap, cur, pain, coh, orig, bal, dyn_v):
+    return (spont_weight_relevance() * rel
+            + spont_weight_info_gap() * gap
+            + spont_weight_curiosity() * cur
+            + spont_weight_pain() * pain
+            + spont_weight_coherence() * coh
+            + spont_weight_originality() * orig
+            + spont_weight_balance() * bal
+            + spont_weight_dynamics() * dyn_v)
+
+
+# ── emission predicates ──
+def should_emit(score):
+    return score > spont_im_threshold()
+
+
+def should_interrupt(score):
+    return score > spont_interrupt_threshold()
+
+
+# ── safety predicates (4-way AND closure) ──
+def safety_kill_switch_on(env_off):
+    return env_off == False
+
+
+def safety_rate_limit_ok(seconds_since_last):
+    return seconds_since_last >= spont_min_emit_interval()
+
+
+def safety_phi_ratchet_ok(phi, ratchet):
+    """Engine A's live Φ vs its ratchet peak (the A->G coupling gate)."""
+    return phi > ratchet / 2.0
+
+
+def safety_content_ok(content_clean):
+    return content_clean
+
+
+def safety_combined(kill, rate, phi_r, content):
+    return kill and rate and phi_r and content
+
+
+if __name__ == "__main__":
+    # smoke: 8-factor score + predicates (matches _eg_parity.hexa oracle).
+    lo = motivation_score(0.1, 0.0, 0.0, 0.0, 0.1, 0.0, 0.1, 0.0)
+    hi = motivation_score(0.9, 0.6, 0.8, 0.0, 0.7, 0.5, 0.6, 1.0)
+    mid = motivation_score(0.5, 0.3, 0.2, 0.0, 0.4, 0.2, 0.3, 0.2)
+    print("score_lo=%.17g" % lo)
+    print("score_hi=%.17g" % hi)
+    print("score_mid=%.17g" % mid)
+    print("emit_lo=%s" % str(should_emit(lo)).lower())
+    print("emit_hi=%s" % str(should_emit(hi)).lower())
+    print("interrupt_hi=%s" % str(should_interrupt(hi)).lower())
+    print("rate_5=%s" % str(safety_rate_limit_ok(5.0)).lower())
+    print("rate_60=%s" % str(safety_rate_limit_ok(60.0)).lower())
+    print("phi_ratchet=%s" % str(safety_phi_ratchet_ok(0.118, 0.148)).lower())
+    print("combined=%s" % str(safety_combined(True, True, True, True)).lower())

anima_py/core/generator.py

@@ -0,0 +1,318 @@
+# ==========================================================================
+# ⛔ ENGINE-INTERNAL / DEPRECATED py-MIRROR — DO NOT RUN OR SCORE DIRECTLY
+# 측정/학습/서빙/직렬화는 cli/ 단일진입만: anima eval | train | serialize
+#   (canonical = hexa core/*.hexa 단일 SSOT; py 미러는 2026-06-28 폐기, DIRECTIONAL).
+# 이 파일을 `python3 core/generator.py` 로 직접 실행하거나 side-harness로 import-채점하면
+# = 단일진입 우회(#2603 위반) + terminal verdict 불가. cli/가 import하는 경로만 허용.
+# ==========================================================================
+import sys as _anima_entry_guard
+if __name__ == "__main__":
+    _anima_entry_guard.exit("⛔ generator.py 직접 실행 금지 — cli/ 단일진입(anima eval/train/serialize, canonical=hexa) 경유. #2603")
+
+"""core/generator.py — PY PRODUCTION ENGINE: byte-faithful 1:1 mirror of the
+L3 MOUTH-DISPATCH surface of core/generator.hexa.
+
+Per CLAUDE.md a_two_production_mirror / a_core_engine_map: hexa + py are TWO
+co-equal production engines kept at byte-parity. generator.hexa is the SINGLE L3
+typed mouth slot — it sniffs a ckpt header and dispatches to ONE of two mouth
+ARCHITECTURES (conv .clm via the CONV mouth, ByteGPT .bin via the BYTE mouth). This
+module is the py mirror of that dispatcher; it routes to the already-parity-proven
+core/decode.py (the unified decoder that merges the former clm_decode.py +
+bytegpt_decode.py 1:1, itself a port of core/decode.hexa). NO torch in the path —
+stdlib + numpy (via the decoder) only.
+
+Scope: this mirrors generator.hexa's PUBLIC dispatch surface (a_core_engine_map):
+  gen_mouth_kind      generator.hexa:628  header-sniff CLM\\x01 / 5xu32 / unknown
+  gen_auto_backend    generator.hexa:641  -> gen_bytegpt_backend | gen_clm_backend
+  gen_auto_chat       generator.hexa:684  -> gen_bytegpt_chat    | gen_clm_chat
+  gen_auto_ideate     generator.hexa:750  -> gen_bytegpt_ideate  | gen_clm_ideate
+plus the per-architecture single entries each dispatcher picks between:
+  gen_null_backend    :74    gen_clm_backend  :101   gen_bytegpt_backend :175
+  gen_clm_chat        :599   gen_bytegpt_chat :664
+  gen_clm_ideate      :697   gen_clm_ideate_W :713   gen_bytegpt_ideate  :728
+and the header helpers they reuse:
+  _gen_is_bytegpt     :148   _gen_clm_probe_header :224   _gen_rd_u32 :792
+
+NOTE the sniff is reproduced VERBATIM from generator.hexa (NOT the looser ranges
+in decode.bg_is_bytegpt): generator.hexa::_gen_is_bytegpt requires
+vocab==256, n_layer in 1..64, n_head divides d, block in 1..8192 — these tighter
+bounds are the dispatcher's actual edge-case behavior and must be mirrored exactly.
+
+The VERDICT path stays engine-native (hexa); this is the parity-proven py mirror.
+"""
+
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+import decode as _clm        # core/decode.py (unified) — ConvMoE .clm mouth API
+import decode as _bg         # same module; both aliases resolve the union public API (ByteGPT .bin mouth)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# header helpers — 1:1 from generator.hexa
+# ════════════════════════════════════════════════════════════════════════
+
+def _gen_rd_u32(rb, off):
+    """generator.hexa:792 _gen_rd_u32 — little-endian u32 from a byte buffer."""
+    return rb[off] + rb[off + 1] * 0x100 + rb[off + 2] * 0x10000 + rb[off + 3] * 0x1000000
+
+
+def _gen_path_is_file(p):
+    """generator.hexa:245 _gen_path_is_file — empty path -> false, else isfile."""
+    if len(p) == 0:
+        return False
+    return os.path.isfile(p)
+
+
+def _gen_is_bytegpt(p):
+    """generator.hexa:148 _gen_is_bytegpt — true iff `p` is a ByteGPT flat binary,
+    NOT a .clm. Reject the CLM\\x01 magic; then require a SANE 5xu32 header:
+    vocab==256, n_layer in 1..64, n_head divides d, block in 1..8192. Edge-safe
+    (missing/short file -> false). Bounds are tighter than decode.bg_is_bytegpt;
+    these are the dispatcher's verbatim discriminator (mirror exactly)."""
+    if len(p) == 0:
+        return False
+    if not _gen_path_is_file(p):
+        return False
+    try:
+        rb = open(p, 'rb').read()
+    except Exception:
+        return False
+    if len(rb) < 20:
+        return False
+    # reject the .clm magic outright (CLM\x01 = 67,76,77,1)
+    if rb[0] == 67 and rb[1] == 76 and rb[2] == 77 and rb[3] == 1:
+        return False
+    vocab = _gen_rd_u32(rb, 0)
+    d = _gen_rd_u32(rb, 4)
+    nlay = _gen_rd_u32(rb, 8)
+    nh = _gen_rd_u32(rb, 12)
+    block = _gen_rd_u32(rb, 16)
+    if vocab != 256:
+        return False
+    if nlay < 1 or nlay > 64:
+        return False
+    if nh < 1 or d < 1:
+        return False
+    if (d // nh) * nh != d:       # n_head must divide d
+        return False
+    if block < 1 or block > 8192:
+        return False
+    return True
+
+
+def _gen_clm_probe_header(p):
+    """generator.hexa:224 _gen_clm_probe_header — verify the CLM\\x01 header.
+    Returns {exists, valid, nblocks}. Edge-safe: missing/empty/truncated -> valid=False."""
+    if len(p) == 0:
+        return {"exists": False, "valid": False, "nblocks": 0}
+    if not _gen_path_is_file(p):
+        return {"exists": False, "valid": False, "nblocks": 0}
+    rb = open(p, 'rb').read()
+    # need at least MAGIC(4) + nblocks(1) = 5 bytes
+    if len(rb) < 5:
+        return {"exists": True, "valid": False, "nblocks": 0}
+    magic_ok = rb[0] == 67 and rb[1] == 76 and rb[2] == 77 and rb[3] == 1
+    if not magic_ok:
+        return {"exists": True, "valid": False, "nblocks": 0}
+    nblocks = rb[4]
+    return {"exists": True, "valid": True, "nblocks": nblocks}
+
+
+# ════════════════════════════════════════════════════════════════════════
+# §1 backend constructors (the pluggable "vtable" records)
+# ════════════════════════════════════════════════════════════════════════
+
+def gen_null_backend():
+    """generator.hexa:74 gen_null_backend — always-ready deterministic placeholder."""
+    return {"kind": "null", "loaded": True, "ckpt": ""}
+
+
+def gen_clm_backend(ckpt_path):
+    """generator.hexa:101 gen_clm_backend — parse the .clm header at the single L3
+    entry; surface loaded (header admit) + decodable (v0.2 CLMX trailer present)."""
+    probe = _gen_clm_probe_header(ckpt_path)
+    exists = probe["exists"]
+    valid = probe["valid"]
+    nblk = probe["nblocks"]
+    loaded = valid
+    decodable = valid and _clm.clm_decodable(ckpt_path)
+    if not exists:
+        reason = "no ckpt at path"
+    elif not valid:
+        reason = "file present but not a valid .clm (bad CLM\\x01 magic)"
+    else:
+        reason = ("valid .clm admitted + LOADED (magic+structure OK, nblocks="
+                  + str(nblk)
+                  + "); decode forward LANDED + descends CORE-mounted at d=768 (loaded=valid)")
+    return {"kind": "clm", "loaded": loaded, "decodable": decodable, "valid": valid,
+            "ckpt": ckpt_path, "ckpt_exists": exists, "nblocks": nblk, "reason": reason}
+
+
+def gen_bytegpt_backend(ckpt_path):
+    """generator.hexa:175 gen_bytegpt_backend — parse the 5xu32 ByteGPT header at the
+    single L3 entry. ByteGPT-format file => valid+loaded+decodable=True; else honest
+    rejection (valid=False) so generate() falls through to null (no garbage)."""
+    if not _gen_is_bytegpt(ckpt_path):
+        exists = _gen_path_is_file(ckpt_path)
+        reason = ("no ckpt at path" if not exists
+                  else "file present but not a ByteGPT flat binary (bad 5xu32 header)")
+        return {"kind": "bytegpt", "loaded": False, "decodable": False, "valid": False,
+                "ckpt": ckpt_path, "ckpt_exists": exists, "nlayer": 0, "d": 0, "reason": reason}
+    rb = open(ckpt_path, 'rb').read()
+    vocab = _gen_rd_u32(rb, 0); d = _gen_rd_u32(rb, 4)
+    nlay = _gen_rd_u32(rb, 8); nh = _gen_rd_u32(rb, 12)
+    block = _gen_rd_u32(rb, 16)
+    reason = ("valid ByteGPT flat binary admitted + LOADED (vocab=" + str(vocab)
+              + " d=" + str(d) + " n_layer=" + str(nlay) + " n_head=" + str(nh)
+              + " block=" + str(block) + "); decode forward = full-24-layer BYTE-EXACT-argmax "
+              + "parity with torch ByteGPT (H_1157 R1, G1 inherited)")
+    return {"kind": "bytegpt", "loaded": True, "decodable": True, "valid": True,
+            "ckpt": ckpt_path, "ckpt_exists": True, "vocab": vocab, "d": d,
+            "nlayer": nlay, "nhead": nh, "block": block, "reason": reason}
+
+
+# ════════════════════════════════════════════════════════════════════════
+# MOUTH-TYPE DISPATCHER — generator.hexa §"MOUTH-TYPE DISPATCHER" (609+)
+# ════════════════════════════════════════════════════════════════════════
+
+def gen_mouth_kind(ckpt_path):
+    """generator.hexa:628 gen_mouth_kind — sniff a ckpt and report the mouth
+    ARCHITECTURE: "bytegpt" | "clm" | "unknown". ByteGPT checked FIRST (its magic
+    is the ABSENCE of CLM\\x01 + a sane 5xu32 header, strictly disjoint from a .clm)."""
+    if _gen_is_bytegpt(ckpt_path):
+        return "bytegpt"
+    probe = _gen_clm_probe_header(ckpt_path)
+    if probe["valid"]:
+        return "clm"
+    return "unknown"
+
+
+def gen_auto_backend(ckpt_path):
+    """generator.hexa:641 gen_auto_backend — THE mouth dispatcher. Sniff and return
+    the right backend record; "clm"/"unknown" both go to gen_clm_backend (it self-
+    reports valid=False for a non-.clm/absent file -> generate() falls through to null)."""
+    kind = gen_mouth_kind(ckpt_path)
+    if kind == "bytegpt":
+        return gen_bytegpt_backend(ckpt_path)
+    return gen_clm_backend(ckpt_path)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# CHAT entries — greedy byte-continuation of a composed dialogue seed
+# ════════════════════════════════════════════════════════════════════════
+
+def gen_clm_chat(ckpt_path, seed, max_new):
+    """generator.hexa:599 gen_clm_chat — thin caller of the ONE .clm decode mouth
+    (clm_decode_argmax). ok=False with reason for a v0.1 (non-decodable) file."""
+    if not _clm.clm_decodable(ckpt_path):
+        return {"ok": False, "text": "",
+                "reason": "ckpt not v0.2-decodable (no CLMX trailer; embed/GN absent)"}
+    r = _clm.clm_decode_argmax(ckpt_path, seed, max_new)
+    return {"ok": r["ok"], "text": r["text"],
+            "reason": "decoded via clm_decode_argmax (CLMConvMoE int4 forward)"}
+
+
+def gen_bytegpt_chat(ckpt_path, seed, max_new):
+    """generator.hexa:664 gen_bytegpt_chat — thin caller of the ONE ByteGPT decode
+    mouth (bytegpt_decode_argmax_ranged, OOM-safe ranged load). seed string -> byte
+    ids (vocab256 byte LM), exactly as the hexa builds sids via ord(substring(...))."""
+    if gen_mouth_kind(ckpt_path) != "bytegpt":
+        return {"ok": False, "text": "",
+                "reason": "ckpt not a ByteGPT flat binary (bad 5xu32 [256,d,L,H,block] header)"}
+    sids = list(seed.encode('utf-8', 'surrogateescape'))
+    r = _bg.bytegpt_decode_argmax_ranged(ckpt_path, sids, max_new)
+    return {"ok": r["ok"], "text": r["text"],
+            "reason": "decoded via bytegpt_decode_argmax_ranged (24-layer GPT-2-class byte forward)"}
+
+
+def gen_auto_chat(ckpt_path, seed, max_new):
+    """generator.hexa:684 gen_auto_chat — mouth-dispatched chat. Same {ok,text,reason}
+    shape for both mouths so the chat loop is mouth-agnostic."""
+    if gen_mouth_kind(ckpt_path) == "bytegpt":
+        return gen_bytegpt_chat(ckpt_path, seed, max_new)
+    return gen_clm_chat(ckpt_path, seed, max_new)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# IDEATE entries — the seeded-sampling siblings (ρ·fan best-of-K source · ideation · former G6)
+# ════════════════════════════════════════════════════════════════════════
+
+def gen_clm_ideate(ckpt_path, seed, max_new, top_k, temp, seed_rng):
+    """generator.hexa:697 gen_clm_ideate — seeded top-k sampler on the .clm mouth
+    (clm_decode_topk_sampled). HARD-BOUNDED by max_new."""
+    if not _clm.clm_decodable(ckpt_path):
+        return {"ok": False, "text": "",
+                "reason": "ckpt not v0.2-decodable (no CLMX trailer; embed/GN absent)"}
+    r = _clm.clm_decode_topk_sampled(ckpt_path, seed, max_new, top_k, temp, seed_rng)
+    return {"ok": r["ok"], "text": r["text"],
+            "reason": "ideated via clm_decode_topk_sampled (seeded top-k, best-of-K source)"}
+
+
+def gen_clm_ideate_W(W, seed, max_new, top_k, temp, seed_rng):
+    """generator.hexa:713 gen_clm_ideate_W — SAME mouth off a PRE-LOADED weight map
+    (clm_load_weights) so a multi-decode driver loads the 303M ConvMoE ONCE."""
+    r = _clm.clm_decode_topk_sampled_W(W, seed, max_new, top_k, temp, seed_rng)
+    return {"ok": r["ok"], "text": r["text"],
+            "reason": "ideated via clm_decode_topk_sampled_W (loaded-W, seeded top-k)"}
+
+
+def gen_bytegpt_ideate(ckpt_path, seed, max_new, top_k, temp, seed_rng):
+    """generator.hexa:728 gen_bytegpt_ideate — seeded top-k sampler on the ByteGPT
+    mouth (bytegpt_decode_topk_sampled_ranged, OOM-safe). HARD-BOUNDED by max_new."""
+    if gen_mouth_kind(ckpt_path) != "bytegpt":
+        return {"ok": False, "text": "",
+                "reason": "ckpt not a ByteGPT flat binary (bad 5xu32 [256,d,L,H,block] header)"}
+    sids = list(seed.encode('utf-8', 'surrogateescape'))
+    r = _bg.bytegpt_decode_topk_sampled_ranged(ckpt_path, sids, max_new, top_k, temp, seed_rng)
+    return {"ok": r["ok"], "text": r["text"],
+            "reason": "ideated via bytegpt_decode_topk_sampled_ranged (seeded top-k, OOM-safe)"}
+
+
+def gen_auto_ideate(ckpt_path, seed, max_new, top_k, temp, seed_rng):
+    """generator.hexa:750 gen_auto_ideate — mouth-dispatched ideate (the seeded-sampling
+    sibling of gen_auto_chat). Same {ok,text,reason} contract for both mouths so the
+    ρ-AXON reach scorers (former G0-G6) run on EITHER mouth via this ONE typed entry (mouth-agnostic)."""
+    if gen_mouth_kind(ckpt_path) == "bytegpt":
+        return gen_bytegpt_ideate(ckpt_path, seed, max_new, top_k, temp, seed_rng)
+    return gen_clm_ideate(ckpt_path, seed, max_new, top_k, temp, seed_rng)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# CLI — for the byte-parity harness (mirror of a hexa main calling the same)
+# ════════════════════════════════════════════════════════════════════════
+
+def _main(argv):
+    if len(argv) < 2:
+        print("usage: generator.py <cmd> ...", file=sys.stderr)
+        return 2
+    cmd = argv[1]
+    if cmd == "kind":
+        print("KIND:" + gen_mouth_kind(argv[2]))
+        return 0
+    if cmd == "ideate":
+        # ideate <ckpt> <seed> <gen> <top_k> <temp> <seed_rng>
+        ck, seed, gen = argv[2], argv[3], int(argv[4])
+        top_k = int(argv[5]); temp = float(argv[6]); rng = int(argv[7])
+        r = gen_auto_ideate(ck, seed, gen, top_k, temp, rng)
+        sys.stdout.buffer.write(b"KIND:" + gen_mouth_kind(ck).encode() + b"\n")
+        sys.stdout.buffer.write(b"OK:" + (b"true" if r["ok"] else b"false") + b"\n")
+        sys.stdout.buffer.write(b"TEXT:" + r["text"].encode('utf-8', 'surrogateescape') + b"\n")
+        return 0
+    if cmd == "chat":
+        ck, seed, gen = argv[2], argv[3], int(argv[4])
+        r = gen_auto_chat(ck, seed, gen)
+        sys.stdout.buffer.write(b"KIND:" + gen_mouth_kind(ck).encode() + b"\n")
+        sys.stdout.buffer.write(b"OK:" + (b"true" if r["ok"] else b"false") + b"\n")
+        sys.stdout.buffer.write(b"TEXT:" + r["text"].encode('utf-8', 'surrogateescape') + b"\n")
+        return 0
+    print("unknown cmd", cmd, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

anima_py/core/hippo_lane.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+# ==========================================================================
+# core/hippo_lane.py — L5 HIPPOCAMPAL ASSOCIATIVE-STORE lane (numpy 2-production).
+#
+# H_9129 rung-3.  A DISJOINT store-side lane over the .kosmos anchor store:
+# pattern-separated (DG kWTA) sparse coding of anima representations + a CA3
+# heteroassociative store that does MULTI-STEP pattern completion (transitive
+# chaining). This is a READ-ONLY relatedness READOUT — it never mutates the
+# emit-drive lane (Ψ / motivation / recall_thr / generator). Adding/consulting
+# it therefore cannot change generation bytes (a_substrate_disjoint: separation
+# = preservation). The byte-parity hexa twin lives in core/kosmos_io.hexa
+# (hippo_kwta / hippo_build_store / hippo_relatedness).
+#
+# This module is a pure library (NO __main__ execution of the engine) — the
+# rep→code encoding uses the real ByteGPT-303M forward via core/decode.py in the
+# py-canonical measurement path (== anima-python evaluate ops, a_eval_py_canonical);
+# the store + completion here is arch-independent arithmetic (no FFI, no torch).
+# ==========================================================================
+import numpy as np
+
+
+# ── DG de-anisotropy (rung-2 GREEN lens: center_zscore) ─────────────────────
+def dg_decorrelate(reps, mode="center_zscore"):
+    """Whiten anisotropic anima reps before pattern separation. Raw single-token
+    303M reps are near-collinear (a dominant shared direction) which masquerades
+    as a substrate wall; center/z-score removes it (rung-2 pre-registered lens)."""
+    R = np.asarray(reps, dtype=np.float64)
+    if mode == "raw":
+        return R
+    mu = R.mean(axis=0, keepdims=True)
+    Rc = R - mu
+    if mode == "center":
+        return Rc
+    if mode == "center_zscore":
+        sd = Rc.std(axis=0, keepdims=True) + 1e-6
+        return Rc / sd
+    raise ValueError(mode)
+
+
+# ── DG pattern separation: fixed (untrained) random projection → kWTA sparse code ──
+def hippo_kwta(v, k):
+    """k-winners-take-all cleanup → sparse binary attractor state (CA3 cleanup)."""
+    v = np.asarray(v, dtype=np.float64)
+    if k >= v.size:
+        return (v > 0).astype(np.float32)
+    idx = np.argpartition(v, -k)[-k:]
+    out = np.zeros_like(v, dtype=np.float32)
+    pos = idx[v[idx] > 0]
+    out[pos] = 1.0
+    return out
+
+
+def dg_codes(reps, dim, active, seed):
+    """Pattern separation. Fixed seeded random projection (DG expansion) of each
+    rep → kWTA sparse binary code. Projection is UNTRAINED (no handed advantage);
+    correlated reps → overlapping codes (crosstalk preserved = honest test)."""
+    reps = np.asarray(reps, dtype=np.float64)
+    n, dm = reps.shape
+    rng = np.random.default_rng(seed)
+    P = rng.standard_normal((dim, dm)).astype(np.float32) / np.sqrt(dm)
+    R = reps / (np.linalg.norm(reps, axis=1, keepdims=True) + 1e-9)
+    drive = R @ P.T
+    return np.stack([hippo_kwta(drive[i], active) for i in range(n)])
+
+
+# ── CA3 heteroassociative store + multi-step pattern completion ─────────────
+def hippo_build_store(codes, edges, dim):
+    """Heteroassociative CA3 store: W = Σ outer(code[nxt], code[cur]) over the
+    DIRECTED premise edges only. edges = list of (cur, nxt) index pairs."""
+    W = np.zeros((dim, dim), dtype=np.float32)
+    codes = np.asarray(codes, dtype=np.float32)
+    for cur, nxt in edges:
+        W += np.outer(codes[nxt], codes[cur])
+    return W
+
+
+def hippo_relatedness(W, codes, i, j, steps, kwta):
+    """READ-OUT (no mouth): seed the lane with code[i], run CA3 completion `steps`
+    times, return the max overlap between any visited attractor state and code[j].
+    Multi-step ⇒ transitive chaining i→i+1→…→j iff a stored relation path exists."""
+    codes = np.asarray(codes, dtype=np.float32)
+    x = codes[i].copy().astype(np.float64)
+    cj = codes[j].astype(np.float64)
+    cjn = np.linalg.norm(cj) + 1e-9
+    best = 0.0
+    for _ in range(steps):
+        x = hippo_kwta(W @ x, kwta).astype(np.float64)
+        ov = float(x @ cj) / ((np.linalg.norm(x) + 1e-9) * cjn)
+        if ov > best:
+            best = ov
+    return best
+
+
+# ── deterministic fixture (byte-parity oracle for the kosmos_io.hexa twin) ──
+def fixture_codes(n, dim, active, seed):
+    """Deterministic sparse binary codes WITHOUT any float RNG divergence across
+    languages: bit b is active for item i iff ((i*step + b*mul) % dim) < active
+    band — a pure integer construction so hexa and py agree byte-for-byte."""
+    codes = np.zeros((n, dim), dtype=np.float32)
+    for i in range(n):
+        picked = set()
+        b = 0
+        h = (i * 2654435761 + seed) & 0xFFFFFFFF
+        while len(picked) < active:
+            h = (h * 1664525 + 1013904223) & 0xFFFFFFFF
+            picked.add(h % dim)
+            b += 1
+        for idx in picked:
+            codes[i, idx] = 1.0
+    return codes
+
+
+def _fixture_report():
+    """Print a deterministic small-scale CA3 report for hexa byte-parity.
+    8 items in one chain 0→1→…→7; reachable = (0,k) k>=2 chain via completion;
+    unreachable = a disconnected item. Also a lesion (remove edge 3→4)."""
+    N, DIM, ACTIVE, STEPS, KWTA = 8, 64, 4, 8, 4
+    codes = fixture_codes(N, DIM, ACTIVE, 20260705)
+    edges = [(p, p + 1) for p in range(N - 1)]           # chain 0→1→...→7
+    W = hippo_build_store(codes, edges, DIM)
+    # reachable 2-hop (0,2) and 3-hop (0,3); adjacent stored (0,1); self-far (0,7)
+    for (i, j, tag) in [(0, 1, "recall_1hop"), (0, 2, "novel_2hop"),
+                        (0, 3, "novel_3hop"), (0, 7, "novel_7hop")]:
+        r = hippo_relatedness(W, codes, i, j, STEPS, KWTA)
+        print("py %s(0,%d)=%.6f" % (tag, j, r))
+    # lesion: remove edge 3→4 ; pair (0,5) path crosses it → must collapse
+    Wl = hippo_build_store(codes, [(p, p + 1) for p in range(N - 1) if p != 3], DIM)
+    print("py lesion_broken(0,5)=%.6f" % hippo_relatedness(Wl, codes, 0, 5, STEPS, KWTA))
+    print("py lesion_intact(0,2)=%.6f" % hippo_relatedness(Wl, codes, 0, 2, STEPS, KWTA))
+
+
+if __name__ == "__main__":
+    _fixture_report()