sloptimize 0.3.0

package/src/attach.mjs

@@ -0,0 +1,197 @@
+// ============================================================
+// attach.mjs — tier 0: attach to a browser, inject, record (SPEC-attach)
+// ============================================================
+// Raw CDP over Node's built-in WebSocket — no dependencies, the package
+// posture. Owns: injection (classify.js + inject-body.js concatenated into
+// one IIFE), the emit binding, the rolling sampling profiler, incident
+// CLUSTERING (M-A1: one cause = one cluster, however often it fires), and
+// the .sloptimize/ files.
+import { readFileSync, mkdirSync, writeFileSync, appendFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const SRC = dirname(fileURLToPath(import.meta.url));
+
+export function buildInjectScript() {
+  const classify = readFileSync(join(SRC, 'classify.js'), 'utf8').replace(/^export /gm, '');
+  const body = readFileSync(join(SRC, 'inject-body.js'), 'utf8');
+  return `(() => {\n${classify}\n${body}\n})();`;
+}
+
+/** M-A1 — incident identity. One CAUSE investigates once: cluster key is the
+ *  classification plus the top attributed frame (or creation-stack head);
+ *  repeats increment a count instead of re-waking anyone. */
+export function clusterKey(rec, topFrame) {
+  const guess = rec.classification && rec.classification[0] ? rec.classification[0].guess : rec.type;
+  return `${guess}|${topFrame ?? ''}`;
+}
+
+/** Top self-time frames from a CDP Profiler.stop payload, idle/program
+ *  filtered, heaviest first. Pure — unit-tested against a fixture. */
+export function topFramesFromProfile(profile, limit = 5) {
+  if (!profile || !profile.nodes) return [];
+  const self = new Map();
+  const byId = new Map(profile.nodes.map((n) => [n.id, n]));
+  const samples = profile.samples ?? [];
+  const deltas = profile.timeDeltas ?? [];
+  for (let i = 0; i < samples.length; i++) {
+    const us = deltas[i] ?? 0;
+    self.set(samples[i], (self.get(samples[i]) ?? 0) + us);
+  }
+  const rows = [];
+  for (const [id, us] of self) {
+    const n = byId.get(id);
+    if (!n) continue;
+    const f = n.callFrame ?? {};
+    if (f.functionName === '(idle)' || f.functionName === '(program)' || f.functionName === '(garbage collector)') continue;
+    rows.push({
+      fn: f.functionName || '(anonymous)',
+      url: f.url ? `${f.url.split('/').slice(-1)[0]}:${(f.lineNumber ?? 0) + 1}` : '',
+      selfMs: +(us / 1000).toFixed(1),
+    });
+  }
+  rows.sort((a, b) => b.selfMs - a.selfMs);
+  return rows.slice(0, limit);
+}
+
+async function discoverTarget(port) {
+  const res = await fetch(`http://127.0.0.1:${port}/json/list`);
+  const targets = await res.json();
+  const page = targets.find((t) => t.type === 'page' && !t.url.startsWith('devtools'));
+  if (!page) throw new Error('no page target — is a tab open?');
+  return page.webSocketDebuggerUrl;
+}
+
+export async function attach(opts = {}) {
+  const port = opts.port ?? 9222;
+  const dir = opts.dir ?? '.sloptimize';
+  const log = opts.log ?? ((...a) => console.log('[attach]', ...a));
+  mkdirSync(dir, { recursive: true });
+
+  let child = null;
+  if (opts.launch) {
+    const bin = process.env.SLOPTIMIZE_BROWSER
+      ?? ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome'].find(existsSync);
+    if (!bin) throw new Error('no browser found — set SLOPTIMIZE_BROWSER');
+    child = spawn(bin, [`--remote-debugging-port=${port}`, '--no-first-run',
+      ...(opts.headless ? ['--headless=new', '--no-sandbox', '--disable-dev-shm-usage', '--enable-unsafe-swiftshader', '--use-angle=swiftshader'] : []),
+      opts.launch], { stdio: 'ignore' });
+    log(`launched ${bin} → ${opts.launch}`);
+    for (let i = 0; i < 50; i++) {
+      try { await discoverTarget(port); break; } catch { await new Promise((r) => setTimeout(r, 300)); }
+    }
+  }
+
+  const wsUrl = await discoverTarget(port);
+  const ws = new WebSocket(wsUrl);
+  await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+  let seq = 0;
+  const pending = new Map();
+  const send = (method, params = {}) => new Promise((res, rej) => {
+    const id = ++seq;
+    pending.set(id, { res, rej });
+    ws.send(JSON.stringify({ id, method, params }));
+  });
+
+  // ── State: clusters + last profile chunk ──
+  const clusters = new Map();   // key → {count, firstAt, lastAt, sample}
+  let lastCreateStackHead = null;
+  let profiling = false;
+
+  async function rotateProfile() {
+    if (!profiling) return null;
+    try {
+      const { profile } = await send('Profiler.stop');
+      await send('Profiler.start');
+      return profile;
+    } catch { return null; }
+  }
+
+  async function onRecord(rec) {
+    if (rec.type === 'gpu-create') {
+      lastCreateStackHead = (rec.stack || '').split('\n')[0]?.trim() ?? null;
+      appendFileSync(join(dir, 'perf.jsonl'), JSON.stringify(rec) + '\n');
+      return;
+    }
+    if (rec.type === 'profile') {
+      writeFileSync(join(dir, 'profile.json'), JSON.stringify({ ...rec, regime: opts.headless ? 'software' : 'unknown', at: new Date().toISOString() }, null, 2));
+      return;
+    }
+    if (rec.type === 'hitch') {
+      // Attribute: grab the current profiler chunk and take the heaviest
+      // frames. The chunk spans up to the rotation window, so a freeze that
+      // dominated its window names itself; the caveat rides the record.
+      const profile = await rotateProfile();
+      rec.topFrames = topFramesFromProfile(profile);
+      rec.profileWindow = 'rolling-chunk';
+      const guess = rec.classification?.[0]?.guess;
+      const top = guess === 'shader-compile' ? lastCreateStackHead
+        : rec.topFrames[0] ? `${rec.topFrames[0].fn}@${rec.topFrames[0].url}` : null;
+      let key = clusterKey(rec, top);
+      // MERGE before minting (M-A1): if any existing cluster's identifying
+      // frame appears anywhere in this hitch's top frames, this is the same
+      // cause seen from a different leaf — V8 inlining moves the hot function
+      // into its caller between occurrences (measured on the exit fixture:
+      // freeze #1 named seededFreezeWork, freeze #2 arrived as its caller).
+      // Inlining that erases the frame ENTIRELY still splits a cause in two;
+      // stated in the spec as a standing limit, not papered over.
+      if (!clusters.has(key)) {
+        const names = new Set((rec.topFrames ?? []).slice(0, 3).map((f) => `${f.fn}@${f.url}`));
+        for (const existing of clusters.keys()) {
+          const frame = existing.split('|')[1];
+          if (frame && names.has(frame)) { key = existing; break; }
+        }
+      }
+      const c = clusters.get(key);
+      if (c) {
+        c.count++; c.lastAt = rec.at;
+        rec.cluster = { key, count: c.count, new: false };
+      } else {
+        clusters.set(key, { count: 1, firstAt: rec.at, lastAt: rec.at, sample: rec });
+        rec.cluster = { key, count: 1, new: true };
+        // The PUSH edge: only a NEW cause reaches stdout (the agent's wake
+        // line) — M-A1's exit criterion made mechanical.
+        log(`INCIDENT ${key} — ${rec.frameMs}ms, top: ${top ?? 'unattributed'}`);
+      }
+      appendFileSync(join(dir, 'perf.jsonl'), JSON.stringify(rec) + '\n');
+      writeFileSync(join(dir, 'clusters.json'), JSON.stringify([...clusters.entries()].map(([k, v]) => ({ key: k, count: v.count, firstAt: v.firstAt, lastAt: v.lastAt })), null, 2));
+      return;
+    }
+    appendFileSync(join(dir, 'perf.jsonl'), JSON.stringify(rec) + '\n');
+    if (rec.type === 'armed') log(`recorder armed in page: ${rec.url}`);
+  }
+
+  ws.onmessage = (ev) => {
+    const msg = JSON.parse(ev.data);
+    if (msg.id && pending.has(msg.id)) {
+      const { res, rej } = pending.get(msg.id);
+      pending.delete(msg.id);
+      msg.error ? rej(new Error(msg.error.message)) : res(msg.result);
+      return;
+    }
+    if (msg.method === 'Runtime.bindingCalled' && msg.params.name === '__sloptimizeEmit') {
+      try { void onRecord(JSON.parse(msg.params.payload)); } catch { /* one bad record */ }
+    }
+  };
+
+  await send('Runtime.enable');
+  await send('Page.enable');
+  await send('Runtime.addBinding', { name: '__sloptimizeEmit' });
+  await send('Page.addScriptToEvaluateOnNewDocument', { source: buildInjectScript() });
+  await send('Profiler.enable');
+  await send('Profiler.setSamplingInterval', { interval: 500 });
+  await send('Profiler.start');
+  profiling = true;
+  // The injection applies to NAVIGATIONS — a page that was already loading
+  // when we attached (the --launch race) never runs it. One reload closes
+  // that hole deterministically; dev pages reload for a living.
+  if (opts.navigate) await send('Page.navigate', { url: opts.navigate });
+  else await send('Page.reload', { ignoreCache: false });
+  log(`attached on :${port} — recorder injected; profiler rolling`);
+
+  return {
+    close: async () => { try { ws.close(); } catch { /* done */ } if (child) child.kill(); },
+    clusters,
+  };
+}

package/src/census.js

@@ -0,0 +1,193 @@
+// ============================================================
+// census.js — the static per-entity cost census (SPEC §4.1)
+// ============================================================
+// A scene walk, on demand, never per-frame. The host hands it entity roots
+// (id + Object3D); everything else is read off the graph. Draw calls are a
+// runtime fact and are reported as `null` here — profile.json carries the
+// measured number (principle 4).
+
+const INSTANCING_MIN_COUNT = 20;      // N same-geometry+material meshes worth a hint
+const MATERIAL_DEDUP_MIN = 8;
+const OVERSIZED_TEXTURE_DIM = 4096;
+
+function triCount(geometry) {
+  if (!geometry) return 0;
+  // drawRange first: a pooled/merged mesh trims what it actually submits via
+  // setDrawRange, and counting the full buffer bills the GPU for triangles it
+  // never sees — the first field census read a 2-mesh corpse pool as 524k
+  // tris this way. Infinity (the default) falls through to the buffer size.
+  const range = geometry.drawRange;
+  const full = geometry.index ? geometry.index.count
+    : (geometry.attributes && geometry.attributes.position ? geometry.attributes.position.count : 0);
+  const used = range && range.count !== Infinity ? Math.min(range.count, full) : full;
+  return Math.floor(used / 3);
+}
+
+function materialKey(m) {
+  // Identical-parameter detection without serializing textures: type + the
+  // scalar/color params that force separate programs or batches.
+  try {
+    return [m.type, m.color?.getHex?.() ?? '', m.roughness ?? '', m.metalness ?? '',
+      m.map?.uuid ?? '', m.transparent ?? false, m.side ?? 0].join('|');
+  } catch { return m.uuid; }
+}
+
+function walkEntity(root) {
+  const out = {
+    meshes: 0, visibleMeshes: 0, instancedMeshes: 0, triangles: 0,
+    visibleTriangles: 0, castShadow: 0,
+    materials: new Map(), geometries: new Map(), pairs: new Map(),
+    matParams: new Map(), textures: new Map(),
+  };
+  // Visibility is INHERITED: an invisible group's children never draw
+  // whatever their own flag says, and a pooled mesh parked with
+  // visible=false costs no draw call. The census reports both counts —
+  // total (memory/census weight) and visible (draw weight) — and the
+  // instancing hint keys on the VISIBLE count, because sending an agent to
+  // instance a parked pool is a guess dressed as a measurement.
+  const stack = [[root, root.visible !== false]];
+  while (stack.length) {
+    const [node, parentVisible] = stack.pop();
+    if (!node) continue;
+    const vis = parentVisible && node.visible !== false;
+    if (node.isMesh) {
+      const inst = !!node.isInstancedMesh;
+      out.meshes++;
+      if (vis) out.visibleMeshes++;
+      if (inst) out.instancedMeshes++;
+      // For InstancedMesh, .count IS the drawn instance count (the host's
+      // pools shrink it via setInstancedDrawCount), so an empty pool
+      // multiplies by ~0 rather than by its capacity.
+      const tris = triCount(node.geometry) * (inst ? (node.count ?? 1) : 1);
+      out.triangles += tris;
+      if (vis) out.visibleTriangles += tris;
+      if (node.castShadow) out.castShadow++;
+      const mats = Array.isArray(node.material) ? node.material : [node.material];
+      for (const m of mats) {
+        if (!m) continue;
+        out.materials.set(m.uuid, m);
+        const pk = materialKey(m);
+        out.matParams.set(pk, (out.matParams.get(pk) ?? 0) + 1);
+        for (const slot of ['map', 'normalMap', 'roughnessMap', 'emissiveMap', 'aoMap']) {
+          const tex = m[slot];
+          if (tex && tex.image) out.textures.set(tex.uuid, tex);
+        }
+      }
+      if (node.geometry) {
+        out.geometries.set(node.geometry.uuid, node.geometry);
+        const m0 = mats[0];
+        const pairKey = `${node.geometry.uuid}|${m0 ? m0.uuid : ''}`;
+        const p = out.pairs.get(pairKey) ?? { geometry: node.geometry.uuid, material: m0?.uuid ?? '', count: 0, visibleCount: 0, instanced: false };
+        p.count += 1;
+        if (vis) p.visibleCount += 1;
+        p.instanced = p.instanced || inst;
+        out.pairs.set(pairKey, p);
+      }
+    }
+    const kids = node.children;
+    if (kids) for (let i = 0; i < kids.length; i++) stack.push([kids[i], vis]);
+  }
+  return out;
+}
+
+function textureBytesEstimate(textures) {
+  let bytes = 0;
+  for (const t of textures.values()) {
+    const img = t.image;
+    const w = img?.width ?? 0, h = img?.height ?? 0;
+    bytes += w * h * 4 * (t.generateMipmaps === false ? 1 : 1.33);
+  }
+  return Math.round(bytes);
+}
+
+/**
+ * @param {object} opts
+ * @param {{id:string, root:object, persistent?:boolean}[]} opts.entities
+ * @param {{geometries:number,textures:number}} [opts.previousTotals]
+ */
+export function buildCensus(opts) {
+  const entities = [];
+  const hints = [];
+  const totals = { calls: null, meshes: 0, triangles: 0, uniqueMaterials: 0, uniqueGeometries: 0, textureBytesEstimate: 0, geometries: 0, textures: 0 };
+  const allMats = new Set(); const allGeos = new Set(); const allTex = new Set();
+
+  for (const ent of opts.entities ?? []) {
+    const w = walkEntity(ent.root);
+    const sharedGroups = [...w.pairs.values()].filter((p) => p.count >= 2)
+      .sort((a, b) => b.count - a.count).slice(0, 10);
+    const row = {
+      id: ent.id,
+      meshes: w.meshes,
+      visibleMeshes: w.visibleMeshes,
+      instancedMeshes: w.instancedMeshes,
+      triangles: w.triangles,
+      visibleTriangles: w.visibleTriangles,
+      uniqueMaterials: w.materials.size,
+      uniqueGeometries: w.geometries.size,
+      sharedGeometryGroups: sharedGroups,
+      textureBytesEstimate: textureBytesEstimate(w.textures),
+      castShadow: w.castShadow,
+      visible: ent.root.visible !== false,
+      persistent: ent.persistent ?? true,
+    };
+    entities.push(row);
+    totals.meshes += w.meshes;
+    totals.triangles += w.triangles;
+    for (const u of w.materials.keys()) allMats.add(u);
+    for (const u of w.geometries.keys()) allGeos.add(u);
+    for (const u of w.textures.keys()) allTex.add(u);
+    totals.textureBytesEstimate += row.textureBytesEstimate;
+
+    // ── hints (closed vocabulary, SPEC §4.1) ──
+    for (const grp of sharedGroups) {
+      // Keyed on VISIBLE members: a parked pool (visible=false) draws
+      // nothing, and hinting it would send the loop after a non-cost. The
+      // pool still shows in the counts above; it is just not a draw-call fix.
+      if (!grp.instanced && (grp.visibleCount ?? grp.count) >= INSTANCING_MIN_COUNT) {
+        hints.push({
+          kind: 'instancing-candidate',
+          entity: ent.id,
+          detail: `${grp.visibleCount} visible meshes share one geometry+material and are not instanced (${grp.count} incl. pooled)`,
+          estimate: { callsSavedAtLeast: (grp.visibleCount ?? grp.count) - 1 },
+          fix: `merge into one InstancedMesh at the construction site of ${ent.id}`,
+        });
+        break; // one per entity — the top group carries the point
+      }
+    }
+    for (const [, n] of w.matParams) {
+      if (n >= MATERIAL_DEDUP_MIN && w.materials.size > 1) {
+        hints.push({
+          kind: 'material-dedup-candidate',
+          entity: ent.id,
+          detail: `${n} materials share identical parameters — one shared material batches them`,
+        });
+        break;
+      }
+    }
+    for (const t of w.textures.values()) {
+      const img = t.image;
+      if (img && (img.width > OVERSIZED_TEXTURE_DIM || img.height > OVERSIZED_TEXTURE_DIM)) {
+        hints.push({ kind: 'oversized-texture', entity: ent.id,
+          detail: `texture ${img.width}x${img.height} exceeds ${OVERSIZED_TEXTURE_DIM}` });
+        break;
+      }
+    }
+  }
+  totals.uniqueMaterials = allMats.size;
+  totals.uniqueGeometries = allGeos.size;
+  totals.geometries = allGeos.size;
+  totals.textures = allTex.size;
+
+  if (opts.previousTotals) {
+    const dg = totals.geometries - (opts.previousTotals.geometries ?? 0);
+    const dt = totals.textures - (opts.previousTotals.textures ?? 0);
+    if (dg > 50 || dt > 20) {
+      hints.push({
+        kind: 'undisposed-suspect',
+        detail: `geometries ${opts.previousTotals.geometries}→${totals.geometries}, textures ${opts.previousTotals.textures}→${totals.textures} across censuses — monotonic growth suggests missing dispose()`,
+      });
+    }
+  }
+
+  return { at: new Date().toISOString(), totals, entities, hints };
+}

package/src/classify.js

@@ -0,0 +1,70 @@
+// ============================================================
+// classify.js — the closed hitch-classification vocabulary (SPEC §3.3)
+// ============================================================
+// A guess without its reason is banned (principle 4): every entry returned
+// carries `evidence`, and the set is closed — extending it is a spec change,
+// not a code change.
+
+/** @typedef {{guess:string, confidence:'low'|'medium'|'high', evidence:string}} Guess */
+
+/**
+ * Classify one hitch from its counter deltas and timing split.
+ * Returns guesses ranked most-likely-first; always at least one.
+ *
+ * @param {object} h
+ * @param {number} h.frameMs        whole frame delta
+ * @param {number} h.medianMs       rolling median at the time of the hitch
+ * @param {number} h.insideRenderMs wall time inside the render call
+ * @param {object} h.delta          counter deltas vs previous frame
+ * @param {number} [h.spawned]      entities spawned this frame (if known)
+ * @param {boolean} [h.memorySampled] performance.memory was available
+ * @returns {Guess[]}
+ */
+export function classifyHitch(h) {
+  const out = [];
+  const d = h.delta ?? {};
+  if ((d.programs ?? 0) > 0) {
+    out.push({
+      guess: 'shader-compile',
+      confidence: (d.programs ?? 0) >= 2 ? 'high' : 'medium',
+      evidence: `programs +${d.programs} in the hitch frame`,
+    });
+  }
+  if ((d.textures ?? 0) > 0 && (d.programs ?? 0) === 0) {
+    out.push({
+      guess: 'texture-upload',
+      confidence: 'medium',
+      evidence: `textures +${d.textures}, programs unchanged`,
+    });
+  }
+  if ((h.spawned ?? 0) >= 3) {
+    out.push({
+      guess: 'spawn-burst',
+      confidence: 'medium',
+      evidence: `${h.spawned} entities spawned in the hitch frame`,
+    });
+  }
+  const inside = h.insideRenderMs ?? 0;
+  if (inside > 0 && inside >= h.frameMs * 0.6) {
+    out.push({
+      guess: 'long-render',
+      confidence: 'high',
+      evidence: `inside-render ${inside.toFixed(1)}ms of a ${h.frameMs.toFixed(1)}ms frame`,
+    });
+  } else if (h.frameMs > 0 && inside < h.frameMs * 0.25) {
+    out.push({
+      guess: 'long-script',
+      confidence: inside > 0 ? 'medium' : 'low',
+      evidence: `frame ${h.frameMs.toFixed(1)}ms with only ${inside.toFixed(1)}ms inside render`,
+    });
+  }
+  if (out.length === 0) {
+    out.push({
+      guess: 'gc-or-upload-by-elimination',
+      confidence: h.memorySampled ? 'medium' : 'low',
+      evidence: 'no counter moved and the render share is inconclusive'
+        + (h.memorySampled ? '' : ' (performance.memory unavailable, downgrading)'),
+    });
+  }
+  return out;
+}

package/src/footprint.js

@@ -0,0 +1,170 @@
+// ============================================================
+// footprint.js — the identity of a bottleneck, apart from its occurrence (SPEC §3.7)
+// ============================================================
+// A ledger line says WHEN something happened and how bad it was. Two lines a
+// day apart, on two builds, on two players' machines, are very often the SAME
+// thing happening again — and a catalogue that cannot say so is a log, not a
+// catalogue. The footprint is the part of a record that names the CAUSE:
+// the kind of incident, the phase it lives in, the closed-vocabulary verdict,
+// and whatever the record carries that identifies the site (the materials a
+// hitch minted, the track and axis a jitter moved on, the tag a warm ran).
+// Never the parts that name the OCCURRENCE: the timestamp, the frame number,
+// the exact milliseconds or metres, the build, the machine.
+//
+// Same cause on a new build → same footprint: that is what lets "how often has
+// this happened" and "which fixes were applied to it" be answered by a fold
+// over the ledger, and what a service aggregating many clients dedupes on.
+//
+// THE GAME'S OWN STATE IS PART OF THE CAUSE. A hitch while flying a heavy hull
+// with a copilot aboard in a firefight is not the same issue as the same hitch
+// on foot in an empty lobby, and no profiler can know which facets matter for
+// a given game. So the host declares them: `context()` returns a few
+// LOW-CARDINALITY facets (`{ stance: 'helm', hull: 'walker', crew: 'copilot',
+// combat: 'yes' }` — categories, never positions or counters), the runtime
+// canonicalises them (`canonicalContext`) and stamps the string on every
+// record as `ctx`, and the key hashes it. Any game feeding sloptimize gets the
+// same catalogue shape from its own facets.
+//
+// Time is deliberately NOT a facet: when an issue happened is the occurrence
+// (`at`, and the catalogue's first/last); the footprint is what was going on.
+// The key is kept readable beside the id so a human — or a service re-deriving
+// ids after a vocabulary change — can see what was hashed. `v` versions the
+// derivation: a change to what goes into a key is a new version, never a
+// silent re-shuffle of old ids.
+//
+// Pure, dependency-free, browser and node: the same bytes hash to the same id
+// wherever the record is read.
+
+export const FOOTPRINT_VERSION = 1;
+
+/** FNV-1a, 32-bit, as 8 hex characters. Not cryptographic and not meant to be
+ *  — a dedupe key over a few thousand distinct causes, stable across runtimes
+ *  without a crypto dependency. */
+export function fnv1a32(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * The host's situation facets as ONE canonical string: keys sorted, `k=v`
+ * pairs joined by ',', separators scrubbed from values. Cheap enough to
+ * refresh once a second and hand to the recorder per frame as a string —
+ * nothing allocates on the frame path.
+ */
+export function canonicalContext(ctx) {
+  if (!ctx || typeof ctx !== 'object') return '';
+  const scrub = (v) => String(v).replace(/[|,=\s]+/g, '_').slice(0, 40);
+  return Object.keys(ctx).filter((k) => ctx[k] !== undefined && ctx[k] !== null && ctx[k] !== '').sort()
+    .map((k) => `${scrub(k)}=${scrub(ctx[k])}`).join(',');
+}
+
+/** The trailing context segment of a key, as facets — `{}` when none. */
+export function contextOfKey(key) {
+  const seg = String(key ?? '').split('|').find((p) => p.startsWith('ctx:'));
+  if (!seg) return {};
+  const out = {};
+  for (const pair of seg.slice(4).split(',')) { const i = pair.indexOf('='); if (i > 0) out[pair.slice(0, i)] = pair.slice(i + 1); }
+  return out;
+}
+
+/** The verdict a record leads with, or 'unclassified'. */
+function topGuess(rec) {
+  return rec.classification?.[0]?.guess ?? 'unclassified';
+}
+
+/** The materials a hitch minted, as a sorted, deduped site list — `a@b` pairs
+ *  (material@object), the same identity the wake line prints. */
+function mintSite(rec) {
+  if (!Array.isArray(rec.mints) || rec.mints.length === 0) return '';
+  const ids = [...new Set(rec.mints.map((m) => `${m.material ?? '?'}@${m.object ?? '?'}`))].sort();
+  return ids.join(',');
+}
+
+/** Which way a jitter moved: vertical (a step, a ground clamp, a fall) or
+ *  horizontal (a correction, a teleport across the ground). x vs z would only
+ *  say which way the pilot happened to be facing. */
+function jumpAxis(rec) {
+  const j = Array.isArray(rec.jump) ? rec.jump : null;
+  if (!j || j.length < 3) return 'unknown';
+  const [x, y, z] = j.map((n) => Math.abs(Number(n) || 0));
+  const mag = Math.sqrt(x * x + y * y + z * z);
+  if (mag === 0) return 'unknown';
+  return y >= 0.7 * mag ? 'vertical' : 'horizontal';
+}
+
+/**
+ * The readable key of a record's footprint, or null for records that are not
+ * incidents (heartbeats, arm probes, a settle that settled).
+ */
+export function footprintKey(rec) {
+  const base = baseKey(rec);
+  if (base === null) return null;
+  // The host's situation, when the record carries one (see the header).
+  const ctx = typeof rec.ctx === 'string' && rec.ctx ? rec.ctx : (rec.ctx && typeof rec.ctx === 'object' ? canonicalContext(rec.ctx) : '');
+  return ctx ? `${base}|ctx:${ctx}` : base;
+}
+
+function baseKey(rec) {
+  if (!rec || typeof rec !== 'object') return null;
+  const phase = rec.phase ?? '?';
+  switch (rec.type) {
+    case 'hitch': {
+      const site = mintSite(rec);
+      return `hitch|${phase}|${topGuess(rec)}${site ? `|${site}` : ''}`;
+    }
+    case 'usermark': {
+      // The human's press is a timestamp; the cause is what the worst frame
+      // under it was doing. A "nominal" window (nothing under the bar) is its
+      // own bucket: the operator felt something the counters did not see.
+      const w = rec.worstFrames?.[0];
+      return `usermark|${phase}|${w?.classification?.[0]?.guess ?? 'unclassified'}`;
+    }
+    case 'jitter':
+      return `jitter|${rec.track ?? '?'}|${rec.kind ?? '?'}|${phase}|${topGuess(rec)}|${jumpAxis(rec)}`;
+    case 'warm':
+      return `warm|${rec.tag ?? '?'}|${rec.kind ?? '?'}|${phase}`;
+    case 'gpu-stall':
+      return `gpu-stall|${phase}`;
+    case 'gpu-settle':
+      // Only a cap hit is an incident; a settled wait is verification evidence.
+      return rec.settled === false ? `gpu-settle|${rec.tag ?? '?'}` : null;
+    default:
+      return null;
+  }
+}
+
+/** `{ v, id, key }` for an incident record, or null when it has none. A record
+ *  that already carries a footprint of the current version keeps it — the
+ *  writer's word stands, and the fold never re-hashes what was stamped. */
+export function footprintOf(rec) {
+  if (rec && rec.footprint && rec.footprint.v === FOOTPRINT_VERSION && typeof rec.footprint.id === 'string') return rec.footprint;
+  const key = footprintKey(rec);
+  if (key === null) return null;
+  return { v: FOOTPRINT_VERSION, id: fnv1a32(`v${FOOTPRINT_VERSION}:${key}`), key };
+}
+
+/** The glyph and a short human label for a footprint key — what a row leads
+ *  with in every reader (watch, report, the debugger's Issues tab). */
+export function describeFootprint(key) {
+  const parts = String(key ?? '').split('|').filter((p) => !p.startsWith('ctx:'));
+  const ctx = contextOfKey(key);
+  const d = describeBase(parts);
+  return { ...d, ctx };
+}
+
+function describeBase(parts) {
+  const [type] = parts;
+  switch (type) {
+    case 'hitch': return { glyph: '⚡', label: `hitch · ${parts[2] ?? '?'}${parts[3] ? ` · ${parts[3].split(',').length} mint site(s)` : ''}`, phase: parts[1] ?? '?' };
+    case 'usermark': return { glyph: '★', label: `keyframe · ${parts[2] ?? '?'}`, phase: parts[1] ?? '?' };
+    case 'jitter': return { glyph: '↯', label: `jitter · ${parts[1] ?? '?'} ${parts[2] ?? '?'} · ${parts[4] ?? '?'} · ${parts[5] ?? '?'}`, phase: parts[3] ?? '?' };
+    case 'warm': return { glyph: '🔥', label: `warm · ${parts[1] ?? '?'} (${parts[2] ?? '?'})`, phase: parts[3] ?? '?' };
+    case 'gpu-stall': return { glyph: '⏳', label: 'gpu-process stall', phase: parts[1] ?? '?' };
+    case 'gpu-settle': return { glyph: '⏳', label: `gpu-settle cap hit · ${parts[1] ?? '?'}`, phase: '' };
+    default: return { glyph: '·', label: String(key ?? ''), phase: '' };
+  }
+}