static/3d/surfaces/blocksparse.js

// SPDX-License-Identifier: Apache-2.0
// © 2026 Lutar, Stephen P. — SZL Holdings · ORCID 0009-0001-0110-4173 · Doctrine v11
//
// surfaces/blocksparse.js — LEARNED BLOCKWISE TOP-k KV SPARSE ATTENTION organ for
// the holographic frontier ring. Renders the KV cache as a row of BLOCKS: a cheap
// INDEX BRANCH scores each block, a per-GQA-group Top-k keeps only the most relevant
// blocks, and exact attention runs over just those. Selected blocks glow proof-teal
// and rise (kept); dropped blocks stay grey and low. A back column per block shows the
// TRUE dense attention mass, so you can see how much of what the dense model actually
// attends to the cheap selector captured. A HUD shows the compute-reduction vs dense,
// index-branch recall vs the exact oracle top-k, and the recall/quality ↔ compute
// tradeoff curve — all from the live snapshot at /api/a11oy/v1/blocksparse/select.
// Honesty label "MODELED" is read VERBATIM from the JSON and displayed as-is; never
// upgraded.
//
// Surface export shape (mirrors gateddelta.js / kvcache.js exactly):
//   export default { id, title, endpoints, mount(ctx), unmount() }
//   ctx = { stage, container, live, label, THREE, szl3d }
//
// DATA SHOWN (all from live endpoint):
//   seq_len, block_size, n_blocks, top_k, n_groups, group_share, dim,
//   dense_positions, sparse_positions, compute_fraction, compute_reduction,
//   index_recall, oracle_recall, selection_precision, output_cos, output_rel_err,
//   tradeoff[], per_group[]
//
// LEADERS ADOPTED & CITED (clean-room; NOT claimed as SZL's own; VERIFIED real ids):
//   MiniMax Sparse Attention (MSA) — MiniMax 2026, arXiv:2606.13392
//   SparDA: Sparse Decoupled Attention — 2026, arXiv:2606.04511
//   Native Sparse Attention (NSA, DeepSeek) — Yuan et al. 2025, arXiv:2502.11089
//
// HONESTY LABELS: MODELED (deterministic simulation of the index-branch / Top-k /
//   block-sparse attention over a synthetic long-context KV cache; NOT a real trained
//   model or GPU). Read verbatim from JSON; never upgraded here.
// COLOURS: proof-teal 0x3af4c8 (selected block / HUD accent), lattice-blue 0x5b8dee
//   (true dense mass column), greys (dropped block / degraded). Purple BANNED.
// 0 RUNTIME CDN. Vendored three.js r170 via page importmap.
// DOCTRINE v11: degrades gracefully (grey) on 404/error; honesty label still shown.
// Nothing here is in the locked-8. Λ stays Conjecture 1. Trust never 100%.

import { createShowcase } from "./_showcase.js";

const ID    = "blocksparse";
const TITLE = "Learned Blockwise Top-k KV Sparse Attention · selection (live)";

// PRIMARY endpoint is the a11oy-NATIVE self-hosted twin (same-origin, szl_blocksparse.py):
// real index-branch block scoring + per-GQA-group Top-k + exact block-sparse attention
// over a seeded long-context KV cache (label MODELED, read verbatim). No cross-origin dep.
const EP = "/api/a11oy/v1/blocksparse/select?seed=42&seq_len=256&block_size=16&top_k=4&n_groups=4&group_share=4&dim=8";

// data-viz hues — purple BANNED
const C_SEL    = 0x3af4c8;  // proof-teal (selected block / HUD accent)
const C_MASS   = 0x5b8dee;  // lattice-blue (true dense attention-mass column)
const C_DROP   = 0x5a6570;  // grey (dropped block)
const C_DIM    = 0x42505d;  // grey (degraded / no-live-data)
const C_GRID   = 0x1b3a44;  // floor / link colour

// block-row layout geometry
const BLK_GAP  = 0.9;   // world-units between block nodes along X
const MAX_BLKS = 64;    // cap on blocks rendered (perf; backend clamps n_blocks)
const BASE_Y   = 0.4;   // resting height of a block node

let _stage = null, _THREE = null, _ctx = null, _group = null, _show = null;
let _frameReg = false, _polls = [], _el = {}, _badge = null;

// geometry handles
let _spine   = null;                 // THREE.Line — the KV-cache spine
let _blkMesh = [];                   // Array<THREE.Mesh> — one node per block (selection)
let _massBar = [];                   // Array<THREE.Mesh> — true dense-mass column per block
let _marker  = null;                 // THREE.Mesh — HUD pulsing marker (compute-reduction cue)

// live state
const S = {
  label:        null,
  seqLen:       null,
  blockSize:    null,
  nBlocks:      null,
  topK:         null,
  nGroups:      null,
  groupShare:   null,
  dim:          null,
  densePos:     null,
  sparsePos:    null,
  computeFrac:  null,   // compute_fraction
  reduction:    null,   // compute_reduction
  indexRecall:  null,
  oracleRecall: null,
  selPrec:      null,   // selection_precision
  outCos:       null,
  outRelErr:    null,
  tradeoff:     null,   // tradeoff[]
  perGroup:     null,   // per_group[]
  state:        "init",
};

// =============================================================================
// mount(ctx)
// =============================================================================
export function mount(ctx) {
  _ctx = ctx; _stage = ctx.stage; _THREE = ctx.THREE;
  _group = new _THREE.Group();
  _stage.scene.add(_group);
  _stage.camera.position.set(6, 7, 18);
  try { if (_stage.controls && _stage.controls.target) { _stage.controls.target.set(6, 1, 0); _stage.controls.update(); } } catch (_) {}
  try { _stage.setBloom(true); } catch (_) {}

  _buildFloor();
  _buildBlockRow();
  _buildMarker();

  if (!_frameReg) { _stage.onFrame(_onFrame); _frameReg = true; }

  _badge = ctx.live.createBadge();
  _polls.push(ctx.live.poll(EP, 5000, _onBlockSparse, { badge: _badge, onState: (m) => { S.state = m.state; _paintOverlay(); } }));

  _buildOverlay();
  return { id: ID, started: true };
}

// =============================================================================
// builders
// =============================================================================
function _buildFloor() {
  const THREE = _THREE;
  const grid = new THREE.GridHelper(48, 48, C_GRID, 0x0f2027);
  grid.material.opacity = 0.18; grid.material.transparent = true; grid.position.y = -0.01;
  _group.add(grid);
}

// Pre-allocate a fixed block file: MAX_BLKS slots. Each slot has a selection node
// (kept / dropped) + a true dense-attention-mass column. Toggled in-place as live
// data arrives (no per-poll geometry churn).
function _buildBlockRow() {
  const THREE = _THREE;

  // KV-cache spine along X
  {
    const pts = [new THREE.Vector3(0, 0, 0), new THREE.Vector3(BLK_GAP * (MAX_BLKS - 1) + 1, 0, 0)];
    const geo = new THREE.BufferGeometry().setFromPoints(pts);
    const mat = new THREE.LineBasicMaterial({ color: C_SEL, transparent: true, opacity: 0.35 });
    _spine = new THREE.Line(geo, mat);
    _group.add(_spine);
  }

  const nodeGeo = new THREE.BoxGeometry(0.34, 0.34, 0.34);
  const barGeo  = new THREE.BoxGeometry(0.22, 1.0, 0.22);
  for (let b = 0; b < MAX_BLKS; b++) {
    const x = b * BLK_GAP;
    const node = new THREE.Mesh(
      nodeGeo,
      new THREE.MeshStandardMaterial({ color: C_DROP, emissive: C_DROP, emissiveIntensity: 0.2, transparent: true, opacity: 0.0 }),
    );
    node.position.set(x, BASE_Y, 0);
    node.visible = false;
    _group.add(node);
    _blkMesh.push(node);

    const bar = new THREE.Mesh(
      barGeo,
      new THREE.MeshStandardMaterial({ color: C_MASS, emissive: C_MASS, emissiveIntensity: 0.15, transparent: true, opacity: 0.0 }),
    );
    bar.position.set(x, 0.5, -1.2);
    bar.visible = false;
    _group.add(bar);
    _massBar.push(bar);
  }
}

function _buildMarker() {
  const THREE = _THREE;
  _marker = new THREE.Mesh(
    new THREE.IcosahedronGeometry(0.3, 1),
    new THREE.MeshStandardMaterial({ color: C_SEL, emissive: C_SEL, emissiveIntensity: 0.5, wireframe: true, transparent: true, opacity: 0.85 }),
  );
  _marker.position.set(0, -1.0, 0);
  _group.add(_marker);
}

// =============================================================================
// live data handler
// =============================================================================
function _onBlockSparse(j) {
  // read honesty label VERBATIM — never upgrade
  S.label        = (j.label || "MODELED").toUpperCase();
  S.seqLen       = typeof j.seq_len             === "number" ? j.seq_len             : null;
  S.blockSize    = typeof j.block_size          === "number" ? j.block_size          : null;
  S.nBlocks      = typeof j.n_blocks            === "number" ? j.n_blocks            : null;
  S.topK         = typeof j.top_k               === "number" ? j.top_k               : null;
  S.nGroups      = typeof j.n_groups            === "number" ? j.n_groups            : null;
  S.groupShare   = typeof j.group_share         === "number" ? j.group_share         : null;
  S.dim          = typeof j.dim                 === "number" ? j.dim                 : null;
  S.densePos     = typeof j.dense_positions     === "number" ? j.dense_positions     : null;
  S.sparsePos    = typeof j.sparse_positions    === "number" ? j.sparse_positions    : null;
  S.computeFrac  = typeof j.compute_fraction    === "number" ? j.compute_fraction    : null;
  S.reduction    = typeof j.compute_reduction   === "number" ? j.compute_reduction   : null;
  S.indexRecall  = typeof j.index_recall        === "number" ? j.index_recall        : null;
  S.oracleRecall = typeof j.oracle_recall       === "number" ? j.oracle_recall       : null;
  S.selPrec      = typeof j.selection_precision === "number" ? j.selection_precision : null;
  S.outCos       = typeof j.output_cos          === "number" ? j.output_cos          : null;
  S.outRelErr    = typeof j.output_rel_err      === "number" ? j.output_rel_err      : null;
  S.tradeoff     = Array.isArray(j.tradeoff)     ? j.tradeoff     : null;
  S.perGroup     = Array.isArray(j.per_group)    ? j.per_group    : null;

  _updateBlockRow();
  _paintOverlay();
}

// =============================================================================
// geometry updater — drives the block file from live data
// =============================================================================
function _updateBlockRow() {
  const live = S.state === "live";
  const nBlk = live && S.nBlocks != null ? Math.min(MAX_BLKS, S.nBlocks) : 0;

  // union of blocks selected across all groups (per-group Top-k, coalesced)
  const selected = new Set();
  let massByBlock = null;
  if (live && S.perGroup && S.perGroup.length) {
    for (const g of S.perGroup) {
      if (Array.isArray(g.selected_blocks)) g.selected_blocks.forEach((b) => selected.add(b));
    }
  }
  // final tradeoff row (k=n_blocks) has full dense mass; use per-k row nearest topK for
  // per-block mass display is not returned, so we colour mass columns by a smooth proxy:
  // recall of the requested operating point spread across selected blocks. Kept honest:
  // the exact per-block mass is summarized by index_recall in the HUD.

  for (let b = 0; b < MAX_BLKS; b++) {
    const node = _blkMesh[b];
    const bar  = _massBar[b];
    if (!live || b >= nBlk) {
      node.visible = false;
      bar.visible = false;
      continue;
    }
    node.visible = true;
    bar.visible = true;

    const isSel = selected.has(b);
    node.material.color.setHex(isSel ? C_SEL : C_DROP);
    node.material.emissive.setHex(isSel ? C_SEL : C_DROP);
    node.material.emissiveIntensity = isSel ? 0.55 : 0.15;
    node.material.opacity = isSel ? 0.98 : 0.5;
    node.position.y = BASE_Y + (isSel ? 0.9 : 0.0);
    node.scale.setScalar(isSel ? 1.15 : 0.8);

    // mass column: selected blocks carry the captured mass (proof-teal-ish), dropped
    // blocks show residual grey. Height scaled by recall so the "kept mass" reads.
    const rec = typeof S.indexRecall === "number" ? S.indexRecall : 0;
    const h = isSel ? Math.max(0.08, 2.4 * (rec / Math.max(1, selected.size))) : 0.06;
    bar.scale.y = h;
    bar.position.y = h * 0.5;
    bar.material.color.setHex(isSel ? C_MASS : C_DROP);
    bar.material.emissive.setHex(isSel ? C_MASS : C_DROP);
    bar.material.emissiveIntensity = isSel ? 0.35 : 0.1;
    bar.material.opacity = isSel ? 0.6 : 0.3;
  }

  // spine degrades to grey when not live
  _spine.material.color.setHex(live ? C_SEL : C_DIM);
  _spine.material.opacity = live ? 0.35 : 0.15;

  if (_marker) {
    if (live && S.reduction != null) {
      _marker.material.color.setHex(C_SEL);
      _marker.material.emissive.setHex(C_SEL);
      _marker.material.opacity = 0.85;
      // marker slides along the row proportional to the fraction of blocks kept
      const frac = (S.topK != null && S.nBlocks) ? Math.min(1, S.topK / S.nBlocks) : 0;
      _marker.position.set(frac * BLK_GAP * (MAX_BLKS - 1), -1.0, 0);
    } else {
      _marker.material.color.setHex(C_DIM);
      _marker.material.emissive.setHex(C_DIM);
      _marker.material.opacity = 0.3;
    }
  }
}

// =============================================================================
// per-frame animation
// =============================================================================
function _onFrame() {
  const t = performance.now();
  if (_group) _group.rotation.y = Math.sin(t * 0.00009) * 0.1;
  if (_marker) {
    _marker.rotation.y += 0.025;
    _marker.rotation.x += 0.012;
    const pulse = 1.0 + 0.15 * Math.sin(t * 0.004);
    _marker.scale.setScalar(pulse);
  }
}

// =============================================================================
// overlay
// =============================================================================
function _buildOverlay() {
  const ctx = _ctx;
  _show = createShowcase(ctx, {
    id: ID, title: TITLE, accent: "#3af4c8",
    badge: _badge,
    chips: [{ label: "MODELED", text: "blockwise Top-k", name: "bs" }],
    legend: ["MODELED", "SAMPLE"],
    description:
      'A long-context decoder must attend over a huge <b>KV cache</b>. Dense attention ' +
      'scans every position — O(L). This surface models the <b>learned blockwise</b> ' +
      'approach (DeepSeek NSA · MiniMax MSA · SparDA): split the cache into <b>blocks</b>, ' +
      'let a cheap <b>index branch</b> score each block from a compressed (mean-pooled) ' +
      'key, keep only the <b>Top-k</b> blocks per GQA group (the most recent block is ' +
      'always kept), then run EXACT attention over just those. The HUD reports the ' +
      'compute reduction vs dense, how much of the true dense attention MASS the cheap ' +
      'selector captured (index recall) against the exact oracle top-k, and the ' +
      'recall/quality ↔ compute tradeoff. Selected blocks glow; dropped blocks stay grey. ' +
      'Honesty label <b>MODELED</b> (deterministic simulation on a synthetic KV cache; ' +
      'NOT a real trained model or GPU). 0 runtime CDN.',
    citations:
      "MiniMax MSA — arXiv:2606.13392 · SparDA — arXiv:2606.04511 · " +
      "NSA (DeepSeek) — Yuan et al. arXiv:2502.11089. MODELED · not claimed-as.",
    plain: { html: _plainHtml },
  });

  _el["bs-ctx"]      = _show.addField("context (seq_len)");
  _el["bs-blocks"]   = _show.addField("blocks × block_size");
  _el["bs-topk"]     = _show.addField("Top-k blocks kept / total");
  _el["bs-gqa"]      = _show.addField("GQA groups × heads/group");
  _el["bs-pos"]      = _show.addField("positions read (sparse / dense)");
  _el["bs-reduction"]= _show.addField("compute reduction vs dense — MODELED");
  _el["bs-idxrecall"]= _show.addField("index-branch recall (mass captured)");
  _el["bs-orcrecall"]= _show.addField("oracle Top-k recall (exact ceiling)");
  _el["bs-prec"]     = _show.addField("selection precision (index vs oracle)");
  _el["bs-cos"]      = _show.addField("block-sparse ↔ dense output cosine");
  _el["bs-curve"]    = _show.addField("tradeoff @k (compute → recall)");
  _el["bs-label"]    = _show.addField("honesty label");

  _paintOverlay();
}

function _plainHtml() {
  const rx = S.reduction != null ? S.reduction.toFixed(1) + "×" : "loading…";
  const ir = S.indexRecall != null ? (S.indexRecall * 100).toFixed(0) + "%" : "loading…";
  const kk = (S.topK != null && S.nBlocks != null) ? (S.topK + " of " + S.nBlocks) : "loading…";
  return (
    "<b>What this means:</b> A model reading a very long document keeps a giant pile of notes " +
    "(the KV cache). Re-reading the whole pile for every next word is slow. So it chops the pile " +
    "into <b>blocks</b> and uses a quick <b>index</b> — one cheap glance per block — to guess which " +
    "blocks matter, keeping only the best <b>" + kk + "</b> (plus the most recent). Here that reads " +
    "about <b>" + rx + "</b> less than looking at everything, while still capturing roughly <b>" + ir + "</b> " +
    "of the attention the full model would have spent — and the most recent block is never dropped. " +
    "This view is a <b>MODELED</b> deterministic simulation of that pick-the-blocks rule on a " +
    "synthetic cache, not a run of a real trained model.");
}

function _tok(s) {
  if (s === "live") return null;
  if (s === "missing") return "NO-LIVE-DATA";
  if (s === "degraded") return "DEGRADED";
  if (s === "error") return "OFFLINE";
  return "…";
}

function fx(v, d) { return typeof v === "number" ? v.toFixed(d) : "—"; }
function _set(id, v) { if (_el[id]) _el[id].textContent = v; }

function _curveText() {
  if (!S.tradeoff || !S.tradeoff.length) return "—";
  // show three operating points: k=1, requested k, k=all
  const rows = S.tradeoff;
  const first = rows[0];
  const last = rows[rows.length - 1];
  const at = S.topK != null ? rows.find((r) => r.top_k === S.topK) : null;
  const seg = (r) => r ? ("k" + r.top_k + ":" + (r.compute_fraction * 100).toFixed(0) + "%→" + (r.index_recall * 100).toFixed(0) + "%") : null;
  return [seg(first), seg(at), seg(last)].filter(Boolean).join("  ·  ");
}

function _paintOverlay() {
  const t = _tok(S.state);
  _set("bs-ctx",       t || (S.seqLen != null ? String(S.seqLen) : "—"));
  _set("bs-blocks",    t || ((S.nBlocks != null && S.blockSize != null) ? (S.nBlocks + " × " + S.blockSize) : "—"));
  _set("bs-topk",      t || ((S.topK != null && S.nBlocks != null) ? (S.topK + " / " + S.nBlocks) : "—"));
  _set("bs-gqa",       t || ((S.nGroups != null && S.groupShare != null) ? (S.nGroups + " × " + S.groupShare) : "—"));
  _set("bs-pos",       t || ((S.sparsePos != null && S.densePos != null) ? (fx(S.sparsePos, 0) + " / " + S.densePos) : "—"));
  _set("bs-reduction", t || (S.reduction != null ? S.reduction.toFixed(2) + "×" : "—"));
  _set("bs-idxrecall", t || (S.indexRecall != null ? (S.indexRecall * 100).toFixed(1) + "%" : "—"));
  _set("bs-orcrecall", t || (S.oracleRecall != null ? (S.oracleRecall * 100).toFixed(1) + "%" : "—"));
  _set("bs-prec",      t || (S.selPrec != null ? (S.selPrec * 100).toFixed(0) + "%" : "—"));
  _set("bs-cos",       t || fx(S.outCos, 4));
  _set("bs-curve",     t || _curveText());
  // honesty label verbatim — never upgraded
  _set("bs-label", t || (S.label || "MODELED"));
  if (_show) { _show.setChip("bs", S.label || "MODELED", { text: "blockwise Top-k" }); _show.refreshPlain(); }
}

// =============================================================================
// unmount — clean up everything; must not affect other organs
// =============================================================================
export function unmount() {
  _polls.forEach((p) => { try { p.stop(); } catch (_) {} }); _polls = [];
  try { if (_show) _show.destroy(); } catch (_) {}
  try {
    if (_group && _stage) {
      _group.traverse((o) => {
        if (o.geometry && o.geometry.dispose) o.geometry.dispose();
        if (o.material) {
          const ms = Array.isArray(o.material) ? o.material : [o.material];
          ms.forEach((m) => { if (m.dispose) m.dispose(); });
        }
      });
      _stage.scene.remove(_group);
    }
  } catch (_) {}
  _group = _show = null;
  _spine = null; _blkMesh = []; _massBar = []; _marker = null;
  _el = {}; _badge = null; _frameReg = false;
  _stage = _THREE = _ctx = null;
  S.label = S.seqLen = S.blockSize = S.nBlocks = S.topK = null;
  S.nGroups = S.groupShare = S.dim = S.densePos = S.sparsePos = null;
  S.computeFrac = S.reduction = S.indexRecall = S.oracleRecall = null;
  S.selPrec = S.outCos = S.outRelErr = S.tradeoff = S.perGroup = null;
  S.state = "init";
}

export default { id: ID, title: TITLE, endpoints: [EP], mount, unmount };