SSM-AI – Appendix J — SDK Packaging & Golden Tests (J1–J3)

ssm_ai/
  __init__.py
  lane.py          # two-lane numeral, clamp, tanh/atanh, lane mul/div (M2)
  fuse.py          # order-invariant streaming fuse (U/W), shard merge
  lens.py          # contrasts e, mapping a := tanh(c*e), two-channel helpers
  rsi.py           # chooser: RSI := tanh((V_out - U_in)/max(W_in, eps_w))
  gate.py          # calm gate: g_t in [0,1], modes "mul" and "u_scale"
  bands.py         # A++/A+/A0/A-/A--, hysteresis helpers
  path.py          # step scores, priors in u-space, path pooling, rollback
  stamp.py         # SSM-Clock stamps, knobs_hash utilities
  manifest.py      # schema load/validate, deterministic defaults
  audit.py         # CSV/JSONL emit: (m,a,U,W,RSI,RSI_env,band,stamp)
  hw/
    fx_specs.py    # SSMH fixed-point formats, tanh/atanh LUT generation
  examples/
    decoding_demo.py
    rag_demo.py
    tools_demo.py
  tests/
    data/golden_vectors.csv
    test_lane.py
    test_fuse.py
    test_rsi.py
    test_gate.py
    test_path.py
    test_bands.py

# lane.py
class LaneValue:
    def __init__(self, m: float, a: float, eps_a: float = 1e-6):
        self.m = m
        self.a = clamp_align(a, eps_a)
    def collapse(self) -> float:                 # phi((m,a)) = m
        return self.m

def clamp_align(a: float, eps_a: float = 1e-6) -> float:
    return max(-1 + eps_a, min(1 - eps_a, a))

def lane_mul(a1: float, a2: float, eps_a: float = 1e-6) -> float:
    from math import atanh, tanh
    a1 = clamp_align(a1, eps_a); a2 = clamp_align(a2, eps_a)
    return tanh(atanh(a1) + atanh(a2))          # M2

def lane_div(a1: float, a2: float, eps_a: float = 1e-6) -> float:
    from math import atanh, tanh
    a1 = clamp_align(a1, eps_a); a2 = clamp_align(a2, eps_a)
    return tanh(atanh(a1) - atanh(a2))          # M2

# fuse.py
class Fuse:
    def __init__(self, eps_a: float = 1e-6, eps_w: float = 1e-12):
        self.U = 0.0; self.W = 0.0; self.eps_a = eps_a; self.eps_w = eps_w
    def add(self, a: float, w: float = 1.0) -> None:
        from math import atanh
        a = max(-1 + self.eps_a, min(1 - self.eps_a, a))
        self.U += w * atanh(a); self.W += w
    def merge(self, other: "Fuse") -> None:
        self.U += other.U; self.W += other.W
    def value(self) -> float:
        from math import tanh
        return tanh(self.U / max(self.W, self.eps_w))

# lens.py
def lens_contrast(P: list[tuple[float,float]],
                  N: list[tuple[float,float]],
                  Unit: float = 1.0) -> float:
    num = sum(a*v for a, v in P) - sum(b*v for b, v in N)
    return num / max(Unit, 1e-12)

def align_single(e: float, c: float = 1.0) -> float:
    from math import tanh
    return tanh(c * e)

def map_to_alignment(e_in: float, e_out: float, c: float = 1.0) -> tuple[float,float]:
    from math import tanh
    return (tanh(-c * e_in), tanh(+c * e_out))

# rsi.py
def rsi_from_alignments(a_in_items: list[tuple[float,float]],
                        a_out_items: list[tuple[float,float]],
                        eps_w: float = 1e-12, eps_a: float = 1e-6) -> float:
    from math import atanh, tanh
    U_in = V_out = W = 0.0
    for a, w in a_in_items:
        a = max(-1 + eps_a, min(1 - eps_a, a)); U_in += w * atanh(a); W += w
    for a, w in a_out_items:
        a = max(-1 + eps_a, min(1 - eps_a, a)); V_out += w * atanh(a)
    return 0.0 if W <= 0 else tanh((V_out - U_in) / max(W, eps_w))

# gate.py
def apply_gate(RSI: float, g: float, mode: str = "mul", eps_a: float = 1e-6) -> float:
    from math import atanh, tanh
    x = max(-1 + eps_a, min(1 - eps_a, RSI))
    return g * x if mode == "mul" else tanh(g * atanh(x))

# bands.py
def to_band(x: float) -> str:
    return "A++" if x >= 0.90 else "A+" if x >= 0.60 else "A0" if x > -0.60 else "A-" if x > -0.90 else "A--"

def to_band_hysteresis(x: float, prev_band: str | None, h_up: float = 0.02, h_dn: float = 0.02) -> str:
    if prev_band is None: return to_band(x)
    if prev_band == "A++" and x >= 0.90 - h_dn: return "A++"
    if prev_band == "A+"  and (0.60 - h_dn) <= x < (0.90 + h_up): return "A+"
    if prev_band == "A0"  and (-0.60 - h_dn) < x < (0.60 + h_up): return "A0"
    if prev_band == "A-"  and (-0.90 - h_dn) < x <= (-0.60 + h_up): return "A-"
    if prev_band == "A--" and x <= -0.90 + h_up: return "A--"
    return to_band(x)

# path.py
class PathScore:
    def __init__(self, eps_a: float = 1e-6, eps_w: float = 1e-12):
        self.U = 0.0; self.W = 0.0; self.stack = []; self.eps_a = eps_a; self.eps_w = eps_w
    def add_step(self, RSI_used: float, beta: float = 0.0, b_s: float = 0.0, w: float = 1.0) -> None:
        from math import atanh
        x = max(-1 + self.eps_a, min(1 - self.eps_a, RSI_used))
        u_step = atanh(x) + beta * b_s
        self.U += w * u_step; self.W += w; self.stack.append((w * u_step, w))
    def undo_step(self) -> None:
        if not self.stack: return
        dU, dW = self.stack.pop(); self.U -= dU; self.W -= dW
    def rsi_path(self) -> float:
        from math import tanh
        return tanh(self.U / max(self.W, self.eps_w))

# stamp.py
def knobs_hash(manifest_obj: dict) -> str:
    import hashlib, json
    canon = json.dumps(manifest_obj, separators=(',', ':'), sort_keys=True)
    return hashlib.sha256(canon.encode("utf-8")).hexdigest()

# manifest.py
def validate_manifest(obj: dict) -> None:
    assert "eps_a" in obj and "eps_w" in obj and "bands" in obj

{
  "dtype": "float64",
  "eps_a": 1e-6,
  "eps_w": 1e-12,
  "weights": {"policy": "uniform"},               // or {"policy":"abs_m_gamma","gamma":1.0}
  "bands": {"A++":0.90, "A+":0.60, "A0":-0.60, "A-":-0.90, "A--":-1.00,
            "hysteresis":{"h_up":0.02,"h_dn":0.02},
            "band_on":"RSI_env"},
  "gate": {"mode":"mul",
           "rho":0.20, "g_min":0.00, "eps_g":1e-12,
           "weights":{"F":1,"D":1,"L":1,"E":1,"V":1,"Q":0},
           "safety_notch":{"enabled":false,"s_thr":0.80}},
  "division_policy": "strict",
  "lens_presets": {
    "decode_v1": {"Unit":1.0, "c":1.0, "terms":"inline formula"},
    "rag_v1":    {"Unit":1.0, "c":1.0}
  }
}