anima-python 0.13.1__py3-none-any.whl

anima_py/core/clm_serialize_v2.py

@@ -0,0 +1,486 @@
+# ==========================================================================
+# ⛔ ENGINE-INTERNAL — DO NOT RUN DIRECTLY. 학습/직렬화는 cli/ 단일진입만:
+#   anima train | anima serialize  (canonical=hexa cli/{train,serialize}.hexa).
+# `python3 train/clm/model/clm_serialize_v2.py` 직접 실행 = 단일진입 우회(#2603) + DIRECTIONAL. cli/ import만 허용.
+# ==========================================================================
+#!/usr/bin/env python3
+"""Lane P REMEDY — torch -> .clm serializer matching core/clm_decode.hexa EXACTLY.
+
+The prior CLM/model/clm_serialize.py emits a 2-track JSON-header format that
+shares only the "CLM\\x01" magic with the ENGINE decoder and is NOT loadable
+(see .verdicts/lane-p-clm/F-CLM-SERIALIZE-GAP.txt). This v2 serializer packs the
+EXACT CLM\\x01 v0.2 byte layout that core/clm_decode.hexa::clm_decodable parses.
+
+CLM\\x01 v0.2 byte layout (ground truth = core/clm_decode.hexa + the golden
+reference state/laneg_d768_recover/reexport_d768_v2_fast.clm):
+
+  [0:4]  MAGIC "CLM\\x01"  = bytes 67,76,77,1
+  [4]    nblk : u8          = 6  (production CLMConvMoE, E=2 / 1 trunk layer)
+  then nblk conv blocks, each:
+    u32 cout (LE)
+    u32 rest (LE)            rest = Cin*K
+    int4 nibbles             ((cout*rest+1)//2 bytes, 2 codes/byte, sym int4)
+    fp32 per-channel scale   (cout float32 LE)
+  block order (decoder-fixed):
+    block0 ecW : cout=d,  rest=d*K   (K = rest0/d)
+    block1 tcW : cout=d,  rest=d*K
+    block2 e0W : cout=d,  rest=d*K
+    block3 e1W : cout=d,  rest=d*K
+    block4 rW  : cout=E,  rest=d     (router, K=1) -> E=2
+    block5 roW : cout=V,  rest=d     (readout, K=1) -> V=256
+  CLMX v0.2 trailer (REQUIRED — clm_decodable()=false without it):
+    "CLMX" = 67,76,77,88
+    n_ext : u8 = 11
+    then 11 ext arrays, EACH = u32 count (LE) + count float32 (LE), in ORDER:
+      embed (V*d), ecB (d), tcB (d), e0B (d), e1B (d), rB (E), roB (V),
+      tgG (d), tgB (d), noG (d), noB (d)
+    (tg* = trunk GroupNorm affine, no* = output GroupNorm affine)
+
+int4-sym quant (decoder dequant w[co,j] = code * scale[co]):
+  per OUTPUT channel co:  scale[co] = max_j(|w[co,j]|) / 7   (clamped >0)
+                          code[co,j] = round(w[co,j]/scale[co]) clamped to [-7,7]
+
+NIBBLE PACKING — must match the decoder byte-for-byte. The decoder reads, for a
+flat code index i (i even):
+    code[i]   = (byte & 0xF) - 8        # low nibble
+    code[i+1] = ((byte >> 4) & 0xF) - 8 # high nibble
+So: low nibble  holds the EVEN index code (+8 offset),
+    high nibble holds the ODD  index code (+8 offset).
+  byte = ((code[i+1]+8) << 4) | (code[i]+8)
+The trailing code of an odd-length run pads its high nibble with 0.
+
+torch is imported lazily: pass a ckpt path / state_dict (torch present) OR a
+plain dict of numpy/list weight arrays (torch absent) so the serializer is
+testable without torch.
+"""
+from __future__ import annotations
+
+# ⛔ ENGINE-INTERNAL — DO NOT RUN DIRECTLY (단일진입 우회 #2603). cli/ import만 허용.
+# 가드는 `from __future__` 뒤에 둔다 — 앞에 두면 SyntaxError(from __future__ must be at top).
+import sys as _anima_entry_guard
+if __name__ == "__main__":
+    _anima_entry_guard.exit("⛔ clm_serialize_v2.py 직접 실행 금지 — cli/ 단일진입(anima train/serialize, canonical=hexa) 경유. #2603")
+
+import struct
+from typing import Dict, Any
+
+try:
+    import numpy as np
+except Exception:  # pragma: no cover - numpy is effectively always present
+    np = None
+
+MAGIC = bytes([67, 76, 77, 1])      # "CLM\x01"
+CLMX = bytes([67, 76, 77, 88])      # "CLMX"
+CLMB = bytes([67, 76, 77, 66])      # "CLMB" — bind-readout (Hadamard) extension
+INT4_SYM_MAX = 7
+
+# readout-type flag (CLMB byte[4]). 0 = additive Conv1d(d->V) (default, NO CLMB
+# section); 1 = bind/Hadamard  g=u*v ; 2 = bind_linear (param-matched add) g=u+v.
+RO_ADDITIVE = 0
+RO_BIND_HADAMARD = 1
+RO_BIND_LINEAR = 2
+
+# state_dict key names of a CLMConvMoE configured E=2 / n_trunk_layers=1.
+# (CLM/model/model.py: embed, embed_conv, trunk[0], moe.router, moe.experts[0/1],
+#  norm_out, readout). The decoder block order is ecW,tcW,e0W,e1W,rW,roW.
+_KEYMAP = {
+    "ecW": "embed_conv.conv.weight",
+    "tcW": "trunk.0.conv.conv.weight",
+    "e0W": "moe.experts.0.conv.conv.weight",
+    "e1W": "moe.experts.1.conv.conv.weight",
+    "rW":  "moe.router.weight",
+    "roW": "readout.weight",
+    # ext (CLMX) sources
+    "embed": "embed.weight",
+    "ecB": "embed_conv.conv.bias",
+    "tcB": "trunk.0.conv.conv.bias",
+    "e0B": "moe.experts.0.conv.conv.bias",
+    "e1B": "moe.experts.1.conv.conv.bias",
+    "rB":  "moe.router.bias",
+    "roB": "readout.bias",
+    "tgG": "trunk.0.norm.weight",
+    "tgB": "trunk.0.norm.bias",
+    "noG": "norm_out.weight",
+    "noB": "norm_out.bias",
+}
+
+_BLOCK_ORDER = ["ecW", "tcW", "e0W", "e1W", "rW", "roW"]
+_EXT_ORDER = ["embed", "ecB", "tcB", "e0B", "e1B", "rB", "roB",
+              "tgG", "tgB", "noG", "noB"]
+
+
+# --------------------------------------------------------------------------- #
+# v0.3 — GENERAL (n_trunk_layers L, n_experts E) block/ext ordering.
+#
+# The CLM\x01 format is ALREADY self-describing: nblk (byte[4]) + each block's
+# (cout,rest) + n_ext + each ext count fully determine the layout. v0.2 only
+# *hardcoded* the block-role assignment (L=1,E=2). v0.3 generalizes that
+# assignment WITHOUT changing the byte grammar, so it is byte-exact backward
+# compatible — a v0.3 file with L=1,E=2 is byte-identical to a v0.2 file.
+#
+# General block order   (nblk = L + E + 3):
+#   ecW · tcW_0..tcW_{L-1} · e0W..e{E-1}W · rW(cout=E) · roW(cout=V)
+# General ext order      (n_ext = 2L + E + 6):
+#   embed · ecB · tcB_0..tcB_{L-1} · e0B..e{E-1}B · rB · roB ·
+#   tgG_0..tgG_{L-1} · tgB_0..tgB_{L-1} · noG · noB
+#
+# At L=1,E=2 this reduces EXACTLY to _BLOCK_ORDER / _EXT_ORDER above (the trunk
+# bias tcB_0, then expert biases e0B,e1B, then rB,roB, then trunk GN tgG_0,tgB_0,
+# then noG,noB) — byte-identical to v0.2.
+#
+# (L,E) recovery at decode time: E = cout of block[nblk-2] (router), V = cout of
+# block[nblk-1] (readout), L = nblk - E - 3.  No new bytes, no magic bump.
+# --------------------------------------------------------------------------- #
+
+# torch state_dict key templates for the general CLMConvMoE (model.py).
+#   embed.weight · embed_conv.conv.{weight,bias}
+#   trunk.{i}.conv.conv.{weight,bias} · trunk.{i}.norm.{weight,bias}
+#   moe.experts.{j}.conv.conv.{weight,bias} · moe.router.{weight,bias}
+#   norm_out.{weight,bias} · readout.{weight,bias}
+def _general_block_keymap(L: int, E: int):
+    """logical slot -> torch key, for the L*E general block order."""
+    km = {"ecW": "embed_conv.conv.weight"}
+    for i in range(L):
+        km[f"tc{i}W"] = f"trunk.{i}.conv.conv.weight"
+    for j in range(E):
+        km[f"e{j}W"] = f"moe.experts.{j}.conv.conv.weight"
+    km["rW"] = "moe.router.weight"
+    km["roW"] = "readout.weight"
+    return km
+
+
+def _general_ext_keymap(L: int, E: int):
+    km = {"embed": "embed.weight", "ecB": "embed_conv.conv.bias"}
+    for i in range(L):
+        km[f"tc{i}B"] = f"trunk.{i}.conv.conv.bias"
+    for j in range(E):
+        km[f"e{j}B"] = f"moe.experts.{j}.conv.conv.bias"
+    km["rB"] = "moe.router.bias"
+    km["roB"] = "readout.bias"
+    for i in range(L):
+        km[f"tg{i}G"] = f"trunk.{i}.norm.weight"
+    for i in range(L):
+        km[f"tg{i}B"] = f"trunk.{i}.norm.bias"
+    km["noG"] = "norm_out.weight"
+    km["noB"] = "norm_out.bias"
+    return km
+
+
+def _general_block_order(L: int, E: int):
+    return (["ecW"] + [f"tc{i}W" for i in range(L)]
+            + [f"e{j}W" for j in range(E)] + ["rW", "roW"])
+
+
+def _general_ext_order(L: int, E: int):
+    return (["embed", "ecB"]
+            + [f"tc{i}B" for i in range(L)]
+            + [f"e{j}B" for j in range(E)]
+            + ["rB", "roB"]
+            + [f"tg{i}G" for i in range(L)]
+            + [f"tg{i}B" for i in range(L)]
+            + ["noG", "noB"])
+
+
+def _to_np(x) -> "np.ndarray":
+    """Coerce a torch.Tensor / numpy array / nested list to a float32 numpy array."""
+    if np is None:
+        raise RuntimeError("numpy is required for serialize_v2")
+    # torch tensor (duck-typed: has detach + cpu + numpy)
+    if hasattr(x, "detach"):
+        x = x.detach().cpu().float().numpy()
+    return np.asarray(x, dtype=np.float32)
+
+
+def _conv_w_to_2d(w: "np.ndarray", name: str) -> "np.ndarray":
+    """Map a weight tensor to the (cout, rest=Cin*K) 2-D layout the decoder expects.
+
+    nn.Conv1d weight is (out, in, K). Decoder col-major within a block walks
+    j = ci*K + k (see clm_decode _clmd_conv1d xcol indexing: ci*K + k), and the
+    weight is read flat as w[co*rest + j] with j over Cin*K. nn.Conv1d's (out,in,K)
+    flattened C-order is exactly co, then (in, K) -> in*K + k = ci*K + k. So a
+    plain reshape(cout, -1) is byte-correct.
+    nn.Linear-style (router/readout are Conv1d k=1) -> (out, in, 1) -> (out, in).
+    """
+    w = np.asarray(w, dtype=np.float32)
+    if w.ndim == 3:
+        cout = w.shape[0]
+        return w.reshape(cout, -1)
+    if w.ndim == 2:
+        return w
+    raise ValueError(f"unexpected weight ndim {w.ndim} for {name}")
+
+
+def _quant_block(w2d: "np.ndarray"):
+    """int4-sym per-output-channel quant. Returns (codes int8 [cout,rest], scale f32 [cout])."""
+    cout = w2d.shape[0]
+    amax = np.abs(w2d).max(axis=1)
+    scale = np.maximum(amax / INT4_SYM_MAX, 1e-12).astype(np.float32)  # >0, never div0
+    codes = np.round(w2d / scale[:, None])
+    codes = np.clip(codes, -INT4_SYM_MAX, INT4_SYM_MAX).astype(np.int64)
+    return codes.reshape(-1), scale, cout, w2d.shape[1]
+
+
+def _pack_nibbles(codes_flat: "np.ndarray") -> bytes:
+    """Pack flat int4 codes [-7,7] to bytes, 2 codes/byte, matching the decoder:
+       low nibble = even-index code (+8), high nibble = odd-index code (+8)."""
+    n = codes_flat.shape[0]
+    off = (codes_flat.astype(np.int64) + 8) & 0xF            # 0..15
+    if n % 2 == 1:
+        off = np.concatenate([off, np.zeros(1, dtype=np.int64)])
+    lo = off[0::2]   # even indices -> low nibble
+    hi = off[1::2]   # odd indices  -> high nibble
+    packed = ((hi << 4) | lo).astype(np.uint8)
+    return packed.tobytes()
+
+
+def _pack_conv_block(w2d: "np.ndarray") -> bytes:
+    codes_flat, scale, cout, rest = _quant_block(w2d)
+    out = bytearray()
+    out += struct.pack("<I", cout)
+    out += struct.pack("<I", rest)
+    out += _pack_nibbles(codes_flat)
+    out += scale.astype("<f4").tobytes()
+    return bytes(out)
+
+
+def _pack_ext(arr: "np.ndarray") -> bytes:
+    flat = np.asarray(arr, dtype=np.float32).reshape(-1)
+    return struct.pack("<I", flat.shape[0]) + flat.astype("<f4").tobytes()
+
+
+def _resolve_state_dict(state_dict_or_ckpt, cfg) -> Dict[str, "np.ndarray"]:
+    """Return a {logical_or_torch_key: np.ndarray} mapping.
+
+    Accepts:
+      - a path (str) to a torch ckpt  -> torch.load (lazy import)
+      - a torch state_dict (OrderedDict of tensors)
+      - a plain dict keyed by torch keys (e.g. 'embed.weight') OR by logical
+        slot names (e.g. 'embed','ecW',...) -> values numpy/list arrays.
+    """
+    sd = state_dict_or_ckpt
+    if isinstance(sd, str):
+        import torch  # lazy
+        sd = torch.load(sd, map_location="cpu")
+        if isinstance(sd, dict) and "model" in sd and hasattr(sd.get("model"), "items"):
+            sd = sd["model"]
+    return sd
+
+
+def _get(sd: Dict[str, Any], logical: str, keymap=None) -> "np.ndarray":
+    """Fetch a weight by logical slot name, accepting either logical keys or
+    torch state_dict keys in the source dict. `keymap` overrides _KEYMAP (used by
+    the general v0.3 path with per-(L,E) slot names)."""
+    km = keymap if keymap is not None else _KEYMAP
+    if logical in sd:
+        return _to_np(sd[logical])
+    tkey = km[logical]
+    if tkey in sd:
+        return _to_np(sd[tkey])
+    raise KeyError(
+        f"missing weight for slot '{logical}' (tried torch key '{tkey}'); "
+        f"available keys: {list(sd.keys())[:12]}..."
+    )
+
+
+def _assert_e2_l1(cfg):
+    """The CORE decoder hardcodes E=2 experts + 1 trunk layer. Enforce it."""
+    if cfg is None:
+        return
+    n_e = getattr(cfg, "n_experts", None)
+    n_l = getattr(cfg, "n_trunk_layers", None)
+    if n_e is not None and n_e != 2:
+        raise ValueError(
+            f"core/clm_decode.hexa is FIXED to E=2 experts; cfg.n_experts={n_e}. "
+            f"Train with a CLMConfig(n_experts=2, n_trunk_layers=1) preset."
+        )
+    if n_l is not None and n_l != 1:
+        raise ValueError(
+            f"core/clm_decode.hexa is FIXED to 1 trunk layer; "
+            f"cfg.n_trunk_layers={n_l}. Train with n_trunk_layers=1."
+        )
+
+
+def serialize_v2(state_dict_or_ckpt, cfg, out_path: str) -> str:
+    """Pack a CLMConvMoE (E=2 / 1-trunk) state_dict to a CLM\\x01 v0.2 .clm that
+    core/clm_decode.hexa loads. Returns out_path.
+
+    cfg may be a CLMConfig (asserted E=2/L1) or None (skip the assert — caller
+    vouches the dict already matches the E=2/L1 slot layout, e.g. synthetic test).
+    """
+    if np is None:
+        raise RuntimeError("numpy is required for serialize_v2")
+    _assert_e2_l1(cfg)
+    sd = _resolve_state_dict(state_dict_or_ckpt, cfg)
+
+    blob = bytearray()
+    blob += MAGIC
+    blob += struct.pack("<B", 6)            # nblk = 6
+
+    for slot in _BLOCK_ORDER:
+        w = _get(sd, slot)
+        w2d = _conv_w_to_2d(w, slot)
+        blob += _pack_conv_block(w2d)
+
+    blob += CLMX
+    blob += struct.pack("<B", len(_EXT_ORDER))   # n_ext = 11
+    for slot in _EXT_ORDER:
+        blob += _pack_ext(_get(sd, slot))
+
+    with open(out_path, "wb") as f:
+        f.write(blob)
+    return out_path
+
+
+def serialize_v3(state_dict_or_ckpt, n_trunk_layers: int, n_experts: int,
+                 out_path: str) -> str:
+    """Pack a GENERAL CLMConvMoE(n_trunk_layers=L, n_experts=E, d, K) to a
+    CLM\\x01 v0.3 .clm that core/clm_decode.hexa loads.
+
+    v0.3 == v0.2 byte grammar, generalized block/ext counts (see the v0.3 note
+    above). At L=1,E=2 the output is BYTE-IDENTICAL to serialize_v2 (verified by
+    the round-trip gate). d, K, V are read from the weight shapes — no width
+    hardcode. Returns out_path.
+    """
+    if np is None:
+        raise RuntimeError("numpy is required for serialize_v3")
+    L, E = int(n_trunk_layers), int(n_experts)
+    if L < 1 or E < 1:
+        raise ValueError(f"need L>=1 and E>=1, got L={L} E={E}")
+    sd = _resolve_state_dict(state_dict_or_ckpt, None)
+    blob = _pack_main_blob(sd, L, E)
+    with open(out_path, "wb") as f:
+        f.write(blob)
+    return out_path
+
+
+def _pack_main_blob(sd: Dict[str, Any], L: int, E: int) -> bytearray:
+    """Pack the MAIN CLM\\x01 body (MAGIC + nblk + conv blocks + CLMX + ext arrays)
+    for a general (L,E) CLMConvMoE, returning a bytearray (no CLMB section). Shared
+    by serialize_v3 (additive) and serialize_v3_bind (which appends a CLMB section).
+    The readout slot roW (cout=block[nblk-1].cout=V, rest) is taken from
+    'readout.weight' / roB from 'readout.bias': for a bind model the caller has
+    routed Wo -> readout.{weight,bias} so the block is (V, k) instead of (V, d)
+    (the byte grammar is self-describing — rest is read from the header at decode)."""
+    bkm = _general_block_keymap(L, E)
+    ekm = _general_ext_keymap(L, E)
+    border = _general_block_order(L, E)
+    eorder = _general_ext_order(L, E)
+    nblk = len(border)            # = L + E + 3
+    n_ext = len(eorder)           # = 2L + E + 6
+
+    blob = bytearray()
+    blob += MAGIC
+    blob += struct.pack("<B", nblk)
+    for slot in border:
+        w = _get(sd, slot, bkm)
+        w2d = _conv_w_to_2d(w, slot)
+        blob += _pack_conv_block(w2d)
+    blob += CLMX
+    blob += struct.pack("<B", n_ext)
+    for slot in eorder:
+        blob += _pack_ext(_get(sd, slot, ekm))
+    return blob
+
+
+def _bget(sd: Dict[str, Any], names) -> "np.ndarray":
+    """Fetch the first present key among `names` from a (torch- or logical-keyed)
+    state dict, coerced to a float32 numpy array. Accepts a 'base.'-stripped dict."""
+    for nm in names:
+        if nm in sd:
+            return _to_np(sd[nm])
+    raise KeyError(f"none of {names} present (have: {list(sd.keys())[:16]}...)")
+
+
+def serialize_v3_bind(state_dict_or_ckpt, n_trunk_layers: int, n_experts: int,
+                      readout_type: int, out_path: str) -> str:
+    """Pack a BIND-readout CLMConvMoE (the EXP-3 ARM-BIND architecture:
+    BindCLM = production trunk + Hadamard byte readout u=Wa(x), v=Wb(x),
+    g=u*v (readout_type=1) or u+v (readout_type=2), logits=Wo(g)) to a CLM\\x01
+    .clm that core/clm_decode.hexa loads.
+
+    BYTE LAYOUT (backward-compatible, in-place extension — no magic bump):
+      · MAIN body == serialize_v3, EXCEPT the readout slot roW carries **Wo**
+        (cout=V, rest=k) and roB carries **Wo.bias** (V). All trunk/embed/MoE
+        blocks+ext are IDENTICAL to the additive ctrl arm (only the readout
+        differs — the EXP-3 design intent). The self-describing (d,E,V,L,K)
+        recovery is UNCHANGED (E=block[nblk-2].cout, V=block[nblk-1].cout, the
+        readout block's `rest` field = k).
+      · a CLMB trailer is appended AFTER the CLMX ext arrays:
+          "CLMB"            (67,76,77,66)
+          readout_type:u8   (1=Hadamard u*v, 2=linear u+v)
+          Wa conv block     (cout=k, rest=d, int4-sym + per-channel fp32 scale)
+          Wb conv block     (cout=k, rest=d, int4-sym + per-channel fp32 scale)
+          Wa_bias ext       (u32 k + k*f32)
+          Wb_bias ext       (u32 k + k*f32)
+        An additive .clm has NO CLMB section, so the decoder defaults
+        readout_type=0 (a_engine_native_learning backward-compat: existing
+        additive .clm decode byte-identically).
+
+    Accepts a torch state_dict (BindCLM.state_dict(): base.<trunk...> + Wa/Wb/Wo
+    .{weight,bias}) OR a logical dict (Wa,WaB,Wb,WbB,Wo,WoB + v3 slot names).
+    Returns out_path."""
+    if np is None:
+        raise RuntimeError("numpy is required for serialize_v3_bind")
+    L, E = int(n_trunk_layers), int(n_experts)
+    rt = int(readout_type)
+    if L < 1 or E < 1:
+        raise ValueError(f"need L>=1 and E>=1, got L={L} E={E}")
+    if rt not in (RO_BIND_HADAMARD, RO_BIND_LINEAR):
+        raise ValueError(f"readout_type must be 1 (hadamard) or 2 (linear), got {rt}")
+    sd = _resolve_state_dict(state_dict_or_ckpt, None)
+
+    # normalize: strip BindCLM's 'base.' trunk prefix into bare CLMConvMoE keys.
+    norm: Dict[str, Any] = {}
+    for k, v in sd.items():
+        nk = k[5:] if k.startswith("base.") else k
+        norm[nk] = v
+
+    # bind readout weights (Wa/Wb -> CLMB ; Wo -> routed into the roW/roB slots).
+    Wa = _bget(norm, ["Wa.weight", "Wa"])
+    WaB = _bget(norm, ["Wa.bias", "WaB"])
+    Wb = _bget(norm, ["Wb.weight", "Wb"])
+    WbB = _bget(norm, ["Wb.bias", "WbB"])
+    Wo = _bget(norm, ["Wo.weight", "Wo"])
+    WoB = _bget(norm, ["Wo.bias", "WoB"])
+    norm["readout.weight"] = Wo        # (V, k, 1) -> roW block (cout=V, rest=k)
+    norm["readout.bias"] = WoB         # (V,)      -> roB ext
+
+    blob = _pack_main_blob(norm, L, E)
+    blob += CLMB
+    blob += struct.pack("<B", rt)
+    blob += _pack_conv_block(_conv_w_to_2d(Wa, "Wa"))   # (k, d)
+    blob += _pack_conv_block(_conv_w_to_2d(Wb, "Wb"))   # (k, d)
+    blob += _pack_ext(WaB)                               # (k,)
+    blob += _pack_ext(WbB)                               # (k,)
+
+    with open(out_path, "wb") as f:
+        f.write(blob)
+    return out_path
+
+
+def serialize(state_dict_or_ckpt, n_trunk_layers: int, n_experts: int,
+              out_path: str) -> str:
+    """Unified entry: routes to serialize_v3 (general). For L=1,E=2 the v3 path
+    is byte-identical to serialize_v2, so this is the single serializer for ANY
+    (L,E,d). cfg-free — caller states (L,E) explicitly."""
+    return serialize_v3(state_dict_or_ckpt, n_trunk_layers, n_experts, out_path)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import argparse, json, os, sys
+    ap = argparse.ArgumentParser(description="torch CLMConvMoE -> CLM\\x01 v0.2 .clm")
+    ap.add_argument("--ckpt", required=True, help="torch state_dict ckpt path")
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--n-experts", type=int, default=2)
+    ap.add_argument("--n-trunk-layers", type=int, default=1)
+    ap.add_argument("--d-model", type=int, default=768)
+    ap.add_argument("--kernel-size", type=int, default=3)
+    a = ap.parse_args()
+    _HERE = os.path.dirname(os.path.abspath(__file__))
+    if _HERE not in sys.path:
+        sys.path.insert(0, _HERE)
+    from model import CLMConfig  # noqa
+    cfg = CLMConfig(n_experts=a.n_experts, n_trunk_layers=a.n_trunk_layers,
+                    d_model=a.d_model, kernel_size=a.kernel_size)
+    p = serialize_v2(a.ckpt, cfg, a.out)
+    print(json.dumps({"out": p, "bytes": os.path.getsize(p)}))

anima_py/core/clml.py

@@ -0,0 +1,155 @@
+"""core/clml.py — fork-A read-side context-pooling LANE (CLML), CORE-owned SSOT.
+
+The ρ·weave recombination wall (was G1) is READOUT-ROUTING, not trunk representation-capacity
+(H_9235 H2-lite): both concepts of a two-concept context ARE linearly present (mean-pool recovery
+0.95/0.97), but the last-position (generation) readout only carries the most-recent concept
+(last-position recovery A=0.07, B=1.00 — pure receptive-field decay, language-independent). The
+CLML lane fixes the ROUTE without touching the trunk: it reads the trunk's per-position penultimate
+`yn`, causally pools the full context (where the earlier concept survives), and adds a gated,
+tether-clipped logit bias at composed positions. $0 pre-check PROVEN: mean-pool→gelu bottleneck
+routes both concepts to held-out XOR (0.98) where last-position (0.47) and a linear head (0.43)
+FAIL (state/g1_gamma_binding_lane/fork_a_precheck.py).
+
+DISJOINT (a_substrate_disjoint): read-only tap of `yn` + an additive logit bias whose gate is
+LEARNED to open only at composed positions — trunk weights, emit-drive lane, Ψ-tension untouched.
+Absent trailer <=> byte-identical to today's .clm (loaders passthrough on short/absent read).
+
+CORE-owned, ONE file (mirrors core/slw.py): lane_apply (torch-free numpy inference mirror,
+byte-parity partner of core/decode.hexa) · pack_clml/read_clml ("CLML" trailer codec) · CLMLModule
+(torch training module, DIRECTIONAL, defined only when torch importable so inference stays torch-free).
+"""
+
+from __future__ import annotations
+
+import struct
+import numpy as np
+
+# ── "CLML" trailer magic (mirrors the CLMB/SLW trailer convention) ──────────────
+CLML_MAGIC = bytes([67, 76, 77, 76])   # "CLML"
+
+
+def _sigmoid(x):
+    return 1.0 / (1.0 + np.exp(-np.clip(x, -30, 30)))
+
+
+def _gelu(x):
+    return 0.5 * x * (1.0 + np.tanh(0.7978845608028654 * (x + 0.044715 * x**3)))
+
+
+# --------------------------------------------------------------------------- #
+# (a) numpy inference mirror — torch-free, byte-parity target for core/decode.hexa
+# --------------------------------------------------------------------------- #
+def lane_apply(yn, logits, clml):
+    """Add the CLML read-side pooling bias to the readout logits.
+
+    yn:     (T, d) float — pre-readout trunk penultimate (the _fwd_trunk output; the SAME
+            representation the $0 pre-check pooled — pre-SLW-slot).
+    logits: (T, V) float — the trunk readout logits to condition.
+    clml:   dict from read_clml (W1 (d,r), b1 (r,), W2 (r,V), w_g (2d,), b_g scalar, tau, r).
+    Returns (T, V): logits + clip( g_t · gelu(c_t·W1+b1)·W2 , ±tau ), where c_t is the CAUSAL
+    cumulative mean of yn (0-param pool) and g_t = sigmoid(w_g·[yn_t;c_t]+b_g) is the learned
+    composed-position gate. lane_type=0 or clml=None => exact passthrough (logits unchanged).
+    Op order IDENTICAL to CLMLModule.forward (2-production parity)."""
+    if clml is None or int(clml.get("lane_type", 0)) == 0:
+        return logits
+    yn = np.asarray(yn); dt = logits.dtype
+    T, d = yn.shape
+    csum = np.cumsum(yn, axis=0)
+    counts = np.arange(1, T + 1, dtype=yn.dtype).reshape(T, 1)
+    c = csum / counts                                        # (T,d) causal mean pool
+    gate = _sigmoid(np.concatenate([yn, c], axis=1) @ clml["w_g"] + clml["b_g"])   # (T,)
+    z = _gelu(c @ clml["W1"] + clml["b1"])                   # (T,r) gelu bottleneck
+    delta = (z @ clml["W2"]) * gate[:, None]                 # (T,V) gated logit bias
+    delta = np.clip(delta, -float(clml["tau"]), float(clml["tau"]))
+    return (logits + delta).astype(dt)
+
+
+# --------------------------------------------------------------------------- #
+# (b) "CLML" trailer codec — write (serialize) + read (loaders) · LE f32
+#   header: CLML magic · lane_type u8 · r u32 · tau f32
+#   arrays (row-major): W1[d·r] b1[r] W2[r·V] w_g[2d] b_g[1]   (d,V from the model)
+# --------------------------------------------------------------------------- #
+_ARR_ORDER = ("W1", "b1", "W2", "w_g", "b_g")
+
+
+def pack_clml(w: dict) -> bytes:
+    """Pack a CLML weight dict into appended trailer bytes. `w` = W1 (d,r), b1 (r,),
+    W2 (r,V), w_g (2d,), b_g scalar, lane_type, r, tau. Absent trailer <=> byte-identical
+    additive/SLW model, so a writer only calls this when the model actually has a lane."""
+    out = bytearray()
+    out += CLML_MAGIC
+    out += struct.pack("<BIf", int(w.get("lane_type", 1)), int(w["r"]), float(w["tau"]))
+    for name in _ARR_ORDER:
+        out += np.asarray(w[name], dtype="<f4").reshape(-1).tobytes()
+    return bytes(out)
+
+
+def read_clml(buf: bytes, off: int, d: int, V: int):
+    """Read a CLML trailer at byte offset `off`. `d`,`V` come from the model (loader passes
+    W["d"], W["V"]). Returns (clml_dict, new_off) or (None, off) if absent/short (passthrough-
+    safe, same guard idiom as read_slw)."""
+    if off < 0 or off + 9 > len(buf) or buf[off:off + 4] != CLML_MAGIC:
+        return None, off
+    p = off + 4
+    lane_type = buf[p]; p += 1
+    (r,) = struct.unpack_from("<I", buf, p); p += 4
+    (tau,) = struct.unpack_from("<f", buf, p); p += 4
+    def take(n, shape):
+        nonlocal p
+        arr = np.frombuffer(buf, "<f4", n, p).reshape(shape).copy(); p += n * 4
+        return arr
+    clml = {"lane_type": int(lane_type), "r": int(r), "tau": float(tau)}
+    clml["W1"] = take(d * r, (d, r))
+    clml["b1"] = take(r, (r,))
+    clml["W2"] = take(r * V, (r, V))
+    clml["w_g"] = take(2 * d, (2 * d,))
+    clml["b_g"] = float(np.frombuffer(buf, "<f4", 1, p)[0]); p += 4
+    return clml, p
+
+
+def clml_weights_from_torch(mod) -> dict:
+    """Extract the CLML weight dict (numpy) from a trained torch CLMLModule."""
+    def n(t):
+        return t.detach().cpu().numpy().astype("<f4")
+    return {
+        "lane_type": 1, "r": int(mod.r), "tau": float(mod.tau),
+        "W1": n(mod.W1.weight).T, "b1": n(mod.W1.bias),          # nn.Linear weight is (out,in)=(r,d) → (d,r)
+        "W2": n(mod.W2.weight).T,                                 # (V,r) → (r,V)
+        "w_g": n(mod.w_g.weight).reshape(-1), "b_g": n(mod.w_g.bias),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# (c) torch training module (DIRECTIONAL) — defined only when torch is present so
+#     the inference import (lane_apply / read_clml) stays torch-free (pod-clean).
+# --------------------------------------------------------------------------- #
+try:
+    import torch as _torch
+    import torch.nn as _nn
+    _HAS_TORCH = True
+except Exception:                     # pragma: no cover - inference pod has no torch
+    _HAS_TORCH = False
+
+if _HAS_TORCH:
+    class CLMLModule(_nn.Module):
+        """Learnable read-side context-pooling lane. forward(yn:(B,T,d), logits:(B,T,V)) ->
+        (B,T,V). Op order MIRRORS core/clml.lane_apply exactly for 2-production parity.
+        Trains ONLY {W1,b1,W2,w_g,b_g} — the trunk is frozen (fork A = read-side, DISJOINT)."""
+
+        def __init__(self, d, V, r=128, tau=8.0):
+            super().__init__()
+            self.d, self.V, self.r, self.tau = d, V, r, tau
+            self.W1 = _nn.Linear(d, r)
+            self.W2 = _nn.Linear(r, V, bias=False)
+            self.w_g = _nn.Linear(2 * d, 1)
+
+        def forward(self, yn, logits):
+            B, T, d = yn.shape
+            csum = _torch.cumsum(yn, dim=1)
+            counts = _torch.arange(1, T + 1, device=yn.device, dtype=yn.dtype).view(1, T, 1)
+            c = csum / counts
+            gate = _torch.sigmoid(self.w_g(_torch.cat([yn, c], dim=-1)))     # (B,T,1)
+            z = _torch.nn.functional.gelu(self.W1(c))
+            delta = self.W2(z) * gate
+            delta = _torch.clamp(delta, -self.tau, self.tau)
+            return logits + delta