SSM-AI – Appendix I — Lens Builder (I10–I12)

# Inputs: arrays e_raw[], m[], and an example RSI to preview bands
def percentile_abs(vals, p):
    xs = sorted(abs(v) for v in vals)
    i = int(max(0, min(len(xs)-1, round((p/100.0)*(len(xs)-1)))))
    return xs[i]

def atanh_safe(x):
    x = max(-0.999999, min(0.999999, x))
    from math import log
    return 0.5 * log((1+x)/(1-x))

def tanh_fast(x):
    from math import tanh
    return tanh(x)

def choose_unit(e_vals):                      # p95 of |e|
    return percentile_abs(e_vals, 95)

def choose_c(e_vals, target=0.60):            # map p95 to boundary (A+ or A++)
    e95 = max(percentile_abs(e_vals, 95), 1e-12)
    from math import atanh
    return atanh(target) / e95

def pick_gamma(m_vals, a_vals, weeks, gammas=(0.0,0.5,1.0,1.5,2.0)):
    # minimize stability variance across weeks; break ties by smaller gamma
    def rsi_port(rows, eps_a=1e-6, eps_w=1e-12):
        U=W=0.0
        for a,w in rows:
            x = max(-1+eps_a, min(1-eps_a, a))
            U += w * atanh_safe(x); W += w
        return 0.0 if W<=0 else tanh_fast(U/max(W, 1e-12))
    import math
    best = (None, 1e30)
    for g in gammas:
        ports=[]
        for wk, idxs in weeks.items():
            rows=[(a_vals[i], (abs(m_vals[i])**g if g>0 else 1.0)) for i in idxs]
            ports.append(rsi_port(rows))
        mu=sum(ports)/len(ports)
        sigma=math.sqrt(sum((x-mu)**2 for x in ports)/len(ports))
        if sigma < best[1]-1e-12 or (abs(sigma-best[1])<=1e-12 and (best[0] is None or g<best[0])):
            best=(g, sigma)
    return best[0]

def calibrate_and_stamp(e_raw, m, target=0.60, iso_utc="2025-10-29T00:00:00Z"):
    Unit = choose_unit(e_raw)
    c    = choose_c(e_raw, target=target)
    weeks = {"w0": list(range(len(e_raw)))}          # simple single-bucket default
    a_vals = [tanh_fast(c * (e / max(Unit, 1e-12))) for e in e_raw]
    gamma  = pick_gamma(m_vals=m, a_vals=a_vals, weeks=weeks)

    # preview RSI & band from this slice
    U=W=0.0
    for a in a_vals:
        x=max(-0.999999, min(0.999999, a)); U += atanh_safe(x); W += 1.0
    RSI  = 0.0 if W<=0 else tanh_fast(U / max(W, 1e-12))
    band = ("A++" if RSI>=0.90 else "A+" if RSI>=0.60 else
            "A0" if RSI>-0.60 else "A-" if RSI>-0.90 else "A--")

    stamp = (
      "SSMCLOCK1|{iso}|SSMLENS|Unit={Unit:.6f}|c={c:.6f}|gamma={g:.2f}"
      "|RSI={rsi:.6f}|band={band}|manifest=knobs_hash"
    ).format(iso=iso_utc, Unit=Unit, c=c, g=gamma, rsi=RSI, band=band)

    print("Unit={:.6f}  c={:.6f}  gamma={:.2f}".format(Unit, c, gamma))
    print(stamp)

"lens_decode_v1": {
  "Unit": 0.780000,
  "c": 0.888650,
  "weights": {"policy": "uniform"},          # or {"policy":"abs_m_gamma","gamma":1.0}
  "eps_a": 1e-6, "eps_w": 1e-12,
  "bands": {"A++":0.90,"A+":0.60,"A0":-0.60,"A-":-0.90,"A--":-1.00},
  "gate": {"mode":"mul"}                     # or "u_scale"
}

# Quick verifier (drop-in)
def verify_lens_acceptance(a_vals, manifest):
    eps_a = manifest.get("eps_a", 1e-6); eps_w = manifest.get("eps_w", 1e-12)
    def clamp1(x): return max(-1+eps_a, min(1-eps_a, x))
    from math import tanh
    assert all(-1 < a < 1 for a in a_vals)                          # bounded
    # Order/shard invariance on a toy slice
    def fuse(seq):
        from math import atanh
        U=W=0.0
        for a in seq:
            U += atanh(clamp1(a)); W += 1.0
        return 0.0 if W<=0 else tanh(U / max(W, eps_w))
    assert abs(fuse(a_vals) - fuse(list(reversed(a_vals)))) < 1e-12
    return True