sloptimize 0.3.0

package/src/proposals.mjs

@@ -0,0 +1,268 @@
+// ============================================================
+// proposals.mjs — the fix loop, in git and nothing else (SPEC §8.5)
+// ============================================================
+// A fix an agent wants to land is a PROPOSAL: a `sloptimize/<slug>` branch
+// holding the change, and one entry in `.sloptimize/fixes.jsonl` naming the
+// issue, the solution, the commit and the measured before/after. The
+// debugger lists proposals with a status READ FROM GIT — proposed while the
+// branch stands ahead of main, merged once its commit is an ancestor of
+// main, rejected once the branch is gone — and offers merge / reject, which
+// are a merge commit into main and a branch delete. There is no pull
+// request, no forge API, no token: a repo with no remote works identically,
+// and one with a remote gets the branch and main pushed.
+//
+// The status entries appended here (`fix-status`) are the audit trail; the
+// live truth is git, and `listFixes` prefers it.
+import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, relative, isAbsolute } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const NOT_A_REPO = "this project isn't a git repo — run `git init` (and commit) before sloptimize can propose or merge fixes";
+export const AUTOMATION_LEVELS = ['propose', 'merge'];
+
+function git(cwd, args, opts = {}) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], ...opts }).toString().trim();
+}
+function tryGit(cwd, args) { try { return git(cwd, args); } catch { return null; } }
+
+export function isGitRepo(repoDir) {
+  return tryGit(repoDir, ['rev-parse', '--is-inside-work-tree']) === 'true';
+}
+function requireRepo(repoDir) { if (!isGitRepo(repoDir)) throw new Error(NOT_A_REPO); }
+
+/** The integration branch: `main` if it exists, else `master`, else the
+ *  current branch. */
+export function mainBranch(repoDir) {
+  for (const b of ['main', 'master']) if (tryGit(repoDir, ['rev-parse', '--verify', '-q', `refs/heads/${b}`])) return b;
+  return git(repoDir, ['branch', '--show-current']);
+}
+function hasRemote(repoDir) { return (tryGit(repoDir, ['remote']) ?? '') !== ''; }
+const short = (sha) => sha.slice(0, 12);
+
+export function slugOf(title) {
+  return String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'fix';
+}
+
+// ── ledger ──────────────────────────────────────────────────────────────────
+function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+function append(dir, rec) {
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, 'fixes.jsonl'), JSON.stringify(rec) + '\n');
+}
+/** Fold fix entries and their status lines into one record per fix. */
+function foldFixes(dir) {
+  const byId = new Map();
+  for (const r of readJsonl(join(dir, 'fixes.jsonl'))) {
+    // A record-only entry (`sloptimize fix --title …`, or an older ledger)
+    // has no id: derive a stable one so it lists beside the proposals.
+    if (r.type === 'fix') { const id = r.id ?? `rec-${(r.at ?? '').replace(/[^0-9]/g, '')}-${slugOf(r.title ?? '').slice(0, 24)}`; byId.set(id, { ...r, id }); }
+    else if (r.type === 'fix-status' && byId.has(r.id)) Object.assign(byId.get(r.id), { status: r.status, statusAt: r.at, ...(r.mergeCommit ? { mergeCommit: r.mergeCommit } : {}) });
+  }
+  return [...byId.values()];
+}
+
+// ── settings ────────────────────────────────────────────────────────────────
+export function readSettings(dir) {
+  try {
+    const s = JSON.parse(readFileSync(join(dir, 'settings.json'), 'utf8'));
+    return { automation: AUTOMATION_LEVELS.includes(s.automation) ? s.automation : 'propose' };
+  } catch { return { automation: 'propose' }; }
+}
+export function writeSettings(dir, settings) {
+  if (!AUTOMATION_LEVELS.includes(settings.automation)) throw new Error(`automation must be one of ${AUTOMATION_LEVELS.join(' | ')}`);
+  mkdirSync(dir, { recursive: true });
+  const next = { automation: settings.automation };
+  writeFileSync(join(dir, 'settings.json'), JSON.stringify(next, null, 2) + '\n');
+  return next;
+}
+
+// ── propose ─────────────────────────────────────────────────────────────────
+/**
+ * Turn the working tree's changes (or the current branch's unmerged commits)
+ * into a proposal. `measure(records)` is optional: given, it returns the
+ * measured before/after windows (history.buildFix); absent or throwing, the
+ * proposal carries `before: null, after: null` — a fix may be proposed
+ * before its after-data exists, and the numbers arrive when it is played.
+ */
+export function proposeFix(repoDir, dir, opts) {
+  requireRepo(repoDir);
+  if (!opts?.title) throw new Error('a proposal needs a title');
+  const main = mainBranch(repoDir);
+  // Dirty = anything outside the ledger dir itself. Match on the directory
+  // boundary: a sibling file whose NAME starts with the dir's (".sloptimize-x")
+  // is a change to propose, not the ledger.
+  const ledgerRel = relative(repoDir, dir);
+  const inLedger = (path) => !!ledgerRel && !ledgerRel.startsWith('..') && (path === ledgerRel || path.startsWith(ledgerRel + '/'));
+  const dirty = git(repoDir, ['status', '--porcelain', '--untracked-files=all']).split('\n').filter(Boolean)
+    .some((l) => !inLedger(l.slice(3).replace(/^"|"$/g, '')));
+  const current = git(repoDir, ['branch', '--show-current']);
+  let branch = opts.branch ?? (current.startsWith('sloptimize/') ? current : `sloptimize/${slugOf(opts.title)}`);
+  if (!dirty) {
+    const ahead = Number(tryGit(repoDir, ['rev-list', '--count', `${main}..HEAD`]) ?? 0);
+    if (ahead === 0 || current === main) throw new Error('nothing to propose: the working tree is clean and HEAD is not ahead of ' + main);
+    branch = opts.branch ?? current;   // already committed on a branch: propose that branch as it stands
+  } else {
+    if (current !== branch) {
+      if (tryGit(repoDir, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`])) git(repoDir, ['checkout', '-q', branch]);
+      else git(repoDir, ['checkout', '-q', '-b', branch]);
+    }
+    // Never stage the ledger itself, wherever it lives relative to the repo:
+    // stage everything, then unstage the ledger dir (a no-op when, as in the
+    // reference deployment, it is gitignored — an exclude pathspec on an
+    // ignored path makes git refuse instead).
+    git(repoDir, ['add', '-A']);
+    const rel = relative(repoDir, dir);
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) tryGit(repoDir, ['reset', '-q', '--', rel]);
+    git(repoDir, ['commit', '-q', '-m', opts.message ?? opts.title]);
+  }
+  const commit = short(git(repoDir, ['rev-parse', branch]));
+  const base = short(git(repoDir, ['merge-base', main, branch]));
+  // The proposal lives on its branch; the checkout goes back to where the
+  // agent was working. Its change has MOVED to the branch, so the tree is
+  // clean on return — a session mid-ticket is not left parked on a
+  // sloptimize/ branch it never asked for.
+  if (dirty && current !== branch) git(repoDir, ['checkout', '-q', current]);
+  let pushed = false;
+  if (hasRemote(repoDir) && opts.push !== false) {
+    try { git(repoDir, ['push', '-q', '-u', 'origin', branch]); pushed = true; } catch { pushed = false; }
+  }
+  let before = null, after = null;
+  if (opts.measure) { try { ({ before, after } = opts.measure()); } catch { /* no evidence yet */ } }
+  const fix = {
+    type: 'fix', id: `${Date.now().toString(36)}-${slugOf(opts.title).slice(0, 24)}`,
+    at: new Date().toISOString(), title: opts.title,
+    ...(opts.issue ? { issue: opts.issue } : {}), ...(opts.solution ? { solution: opts.solution } : {}),
+    ...(opts.files ? { files: opts.files } : {}),
+    ...(opts.footprints?.length ? { footprints: opts.footprints } : {}),
+    branch, commit, base, main, from: current, pushed, status: 'proposed', before, after,
+  };
+  append(dir, fix);
+  return fix;
+}
+
+// ── pull requests, from git alone ───────────────────────────────────────────
+// GitHub publishes every PR's head as `refs/pull/<n>/head`, readable with a
+// plain `git ls-remote` and no token. A fix whose branch head (or recorded
+// commit) is one of those heads IS that PR; the panel gets a link. Any other
+// forge, or no match: no `pr`, nothing else changes.
+
+/** {owner, repo, url} when origin is on github.com, else null. */
+export function githubOrigin(remoteUrl) {
+  const m = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remoteUrl ?? '');
+  return m ? { owner: m[1], repo: m[2], url: `https://github.com/${m[1]}/${m[2]}` } : null;
+}
+
+/** Parse `git ls-remote` output into [{number, sha}] for pull heads. */
+export function parsePullRefs(text) {
+  const out = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const m = /^([0-9a-f]{40})\s+refs\/pull\/(\d+)\/head$/.exec(line.trim());
+    if (m) out.push({ number: Number(m[2]), sha: m[1] });
+  }
+  return out;
+}
+
+/** The PR a fix corresponds to — by its branch head, else its recorded
+ *  commit (a short sha is a prefix of the head). Highest number wins when a
+ *  head was reused. */
+export function matchPR(fix, refs, origin) {
+  if (!origin || !refs?.length) return null;
+  const heads = [fix.head, fix.commit].filter(Boolean);
+  let best = null;
+  for (const r of refs) {
+    if (heads.some((h) => r.sha.startsWith(h) || h.startsWith(r.sha))) { if (!best || r.number > best.number) best = r; }
+  }
+  return best ? { number: best.number, url: `${origin.url}/pull/${best.number}` } : null;
+}
+
+const PULL_REFS_TTL_MS = 60_000;
+const _pullRefsCache = new Map();   // repoDir → { at, refs, origin }
+function pullRefs(repoDir) {
+  const hit = _pullRefsCache.get(repoDir);
+  if (hit && Date.now() - hit.at < PULL_REFS_TTL_MS) return hit;
+  const origin = githubOrigin(tryGit(repoDir, ['remote', 'get-url', 'origin']));
+  let refs = [];
+  if (origin) {
+    try { refs = parsePullRefs(execFileSync('git', ['ls-remote', 'origin', 'refs/pull/*/head'], { cwd: repoDir, stdio: ['ignore', 'pipe', 'ignore'], timeout: 8_000 }).toString()); }
+    catch { refs = []; }
+  }
+  const entry = { at: Date.now(), refs, origin };
+  _pullRefsCache.set(repoDir, entry);
+  return entry;
+}
+
+// ── list ────────────────────────────────────────────────────────────────────
+/** Every proposal with its status as git sees it now. */
+export function listFixes(repoDir, dir) {
+  if (!isGitRepo(repoDir)) return { repo: false, error: NOT_A_REPO, fixes: [] };
+  const main = mainBranch(repoDir);
+  const mainHead = git(repoDir, ['rev-parse', main]);
+  const { refs, origin } = pullRefs(repoDir);
+  const withPR = (f) => { const pr = matchPR(f, refs, origin); return pr ? { ...f, pr } : f; };
+  const fixes = foldFixes(dir).map((f) => {
+    if (!f.branch || !f.commit) return withPR({ ...f, status: f.status ?? 'recorded' });
+    const branchHead = tryGit(repoDir, ['rev-parse', '--verify', '-q', `refs/heads/${f.branch}`]);
+    const merged = tryGit(repoDir, ['merge-base', '--is-ancestor', f.commit, main]) !== null;
+    let status = f.status;
+    if (merged) status = 'merged';
+    else if (!branchHead) status = f.status === 'rejected' ? 'rejected' : 'orphaned';
+    else status = 'proposed';
+    const mergeBase = branchHead ? tryGit(repoDir, ['merge-base', main, branchHead]) : null;
+    const ahead = branchHead ? Number(tryGit(repoDir, ['rev-list', '--count', `${main}..${branchHead}`]) ?? 0) : 0;
+    return withPR({ ...f, status, ahead, upToDate: mergeBase !== null && mergeBase === mainHead, head: branchHead ? short(branchHead) : null });
+  }).sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+  return { repo: true, main, ...(origin ? { origin: origin.url } : {}), fixes };
+}
+
+// ── merge / reject ──────────────────────────────────────────────────────────
+function findFix(dir, id) {
+  const f = foldFixes(dir).find((x) => x.id === id);
+  if (!f) throw new Error(`no proposal with id ${id}`);
+  return f;
+}
+
+/** Merge a proposal into main with a merge commit; push main if a remote
+ *  exists. Refuses anything that is not a plain, current, unmerged proposal:
+ *  the direct-push-to-main class of accident is exactly what this must not
+ *  be a new door for. */
+export function mergeFix(repoDir, dir, id) {
+  requireRepo(repoDir);
+  const f = findFix(dir, id);
+  const main = mainBranch(repoDir);
+  if (tryGit(repoDir, ['merge-base', '--is-ancestor', f.commit, main]) !== null) throw new Error(`already merged: ${f.title}`);
+  const current = git(repoDir, ['branch', '--show-current']);
+  if (current !== main) throw new Error(`checkout is on '${current}', not '${main}' — merge from the ${main} checkout`);
+  if (git(repoDir, ['status', '--porcelain', '--untracked-files=no']) !== '') throw new Error(`the ${main} checkout has uncommitted changes — commit or discard them first`);
+  const branchHead = tryGit(repoDir, ['rev-parse', '--verify', '-q', `refs/heads/${f.branch}`]);
+  if (!branchHead) throw new Error(`branch ${f.branch} no longer exists`);
+  if (hasRemote(repoDir)) { tryGit(repoDir, ['fetch', '-q', 'origin', main]); }
+  const mainHead = git(repoDir, ['rev-parse', main]);
+  const remoteMain = hasRemote(repoDir) ? tryGit(repoDir, ['rev-parse', `origin/${main}`]) : null;
+  if (remoteMain && remoteMain !== mainHead) throw new Error(`local ${main} is not at origin/${main} — pull first`);
+  if (git(repoDir, ['merge-base', main, branchHead]) !== mainHead) throw new Error(`proposal is not based on current ${main} — rebase ${f.branch} first`);
+  git(repoDir, ['merge', '-q', '--no-ff', '-m', `Merge sloptimize fix: ${f.title}`, branchHead]);
+  const mergeCommit = short(git(repoDir, ['rev-parse', 'HEAD']));
+  let pushed = false;
+  if (hasRemote(repoDir)) { try { git(repoDir, ['push', '-q', 'origin', main]); pushed = true; } catch { pushed = false; } }
+  const status = { type: 'fix-status', id, at: new Date().toISOString(), status: 'merged', mergeCommit, pushed };
+  append(dir, status);
+  return status;
+}
+
+/** Delete a proposal's branch (locally, and on the remote if pushed). */
+export function rejectFix(repoDir, dir, id) {
+  requireRepo(repoDir);
+  const f = findFix(dir, id);
+  const main = mainBranch(repoDir);
+  if (tryGit(repoDir, ['merge-base', '--is-ancestor', f.commit, main]) !== null) throw new Error(`already merged: ${f.title}`);
+  const current = git(repoDir, ['branch', '--show-current']);
+  if (current === f.branch) git(repoDir, ['checkout', '-q', f.from && f.from !== f.branch ? f.from : main]);
+  tryGit(repoDir, ['branch', '-D', f.branch]);
+  if (hasRemote(repoDir)) tryGit(repoDir, ['push', '-q', 'origin', '--delete', f.branch]);
+  const status = { type: 'fix-status', id, at: new Date().toISOString(), status: 'rejected' };
+  append(dir, status);
+  return status;
+}

package/src/recorder.js

@@ -0,0 +1,235 @@
+// ============================================================
+// recorder.js — the flight recorder (SPEC §3, plus §3.5 usermark)
+// ============================================================
+// Framework-agnostic: the host calls `frame(sample)` once per render with
+// numbers it already has (three's renderer.info + two clock reads). The
+// recorder owns the ring, the hitch math, the rate limits and the summaries;
+// it allocates nothing on the steady path (pre-allocated ring, records only
+// when a hitch or a usermark actually happens).
+//
+// The host decides transport: `drainRecords()` hands back and clears whatever
+// accumulated; the caller ships them wherever its sink lives. The recorder
+// must never be the hitch it reports — no JSON, no strings, no closures per
+// frame.
+
+import { classifyHitch } from './classify.js';
+
+const RING = 600;                 // ~10s at 60fps (SPEC §3.1)
+const MAX_RECORDS_PER_SESSION = 500;
+const MIN_RECORD_GAP_MS = 1000;   // at most 1 hitch record per second
+
+const FIELDS = ['frameMs', 'insideRenderMs', 'calls', 'triangles', 'programs',
+  'textures', 'geometries', 'spawned'];
+
+export function createRecorder(opts = {}) {
+  const now = opts.now ?? (() => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
+  const budgetFrameMs = opts.budgetFrameMs ?? 16.7;
+
+  // The ring: one Float64Array lane per field plus paused/timestamps lanes.
+  const lanes = Object.fromEntries(FIELDS.map((f) => [f, new Float64Array(RING)]));
+  const pausedLane = new Uint8Array(RING);
+  const atLane = new Float64Array(RING);
+  let head = 0;       // next write index
+  let count = 0;      // filled slots (≤ RING)
+  let frameNo = 0;
+
+  // Rolling median over the last window of NON-paused frames, recomputed
+  // lazily at a coarse cadence — a per-frame exact median would sort 600
+  // numbers every frame for a threshold that moves slowly.
+  let cachedMedian = budgetFrameMs;
+  let medianStale = 60;
+
+  let records = [];
+  let sessionRecords = 0;
+  let droppedSinceLast = 0;
+  let lastRecordAt = -Infinity;
+
+  function sortedNonPaused(field, sinceIdx = 0) {
+    const vals = [];
+    for (let i = 0; i < count; i++) {
+      const idx = (head - 1 - i + RING * 2) % RING;
+      if (pausedLane[idx]) continue;
+      vals.push(lanes[field][idx]);
+    }
+    vals.sort((a, b) => a - b);
+    return vals;
+  }
+  function pct(sorted, p) {
+    if (sorted.length === 0) return null;
+    return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * p))];
+  }
+
+  function rollingMedian() {
+    if (--medianStale <= 0 || cachedMedian === null) {
+      const s = sortedNonPaused('frameMs');
+      cachedMedian = pct(s, 0.5) ?? budgetFrameMs;
+      medianStale = 60;
+    }
+    return cachedMedian;
+  }
+
+  function prevIdx(back = 1) { return (head - 1 - back + RING * 2) % RING; }
+
+  return {
+    /** One frame's numbers. Zero-allocation on the steady path. */
+    frame(s) {
+      const idx = head;
+      for (const f of FIELDS) lanes[f][idx] = s[f] ?? 0;
+      pausedLane[idx] = s.paused ? 1 : 0;
+      atLane[idx] = now();
+      head = (head + 1) % RING;
+      if (count < RING) count++;
+      frameNo++;
+
+      if (s.paused) return;
+      const median = rollingMedian();
+      const threshold = Math.max(2 * median, budgetFrameMs * 1.5);
+      if (s.frameMs <= threshold || count < 30) return;
+
+      // A hitch. Rate limits first (SPEC §3.3): silence must mean nothing
+      // was dropped, so the drops are counted and reported on the NEXT record.
+      const t = now();
+      if (t - lastRecordAt < MIN_RECORD_GAP_MS || sessionRecords >= MAX_RECORDS_PER_SESSION) {
+        droppedSinceLast++;
+        return;
+      }
+      lastRecordAt = t;
+      sessionRecords++;
+
+      const prev = prevIdx(1);
+      const delta = {};
+      for (const f of ['calls', 'triangles', 'programs', 'textures', 'geometries']) {
+        delta[f] = count > 1 ? lanes[f][idx] - lanes[f][prev] : 0;
+      }
+      const rec = {
+        type: 'hitch',
+        at: new Date().toISOString(),
+        frame: frameNo,
+        frameMs: s.frameMs,
+        medianMs: +median.toFixed(2),
+        insideRenderMs: s.insideRenderMs ?? 0,
+        delta,
+        classification: classifyHitch({
+          frameMs: s.frameMs, medianMs: median, insideRenderMs: s.insideRenderMs ?? 0,
+          delta, spawned: s.spawned ?? 0, memorySampled: !!s.memorySampled,
+        }),
+      };
+      if (s.world) rec.world = s.world;
+      // Phase is a string the HOST passes per frame (menu/boot/launch/match…)
+      // — stamped at mint time so the record names the moment the hitch
+      // happened, not the moment it was drained/posted (drains run on a 2s
+      // cadence, and a launch is over in less).
+      if (s.phase) rec.phase = s.phase;
+      // The host's situation facets (SPEC §3.7), a canonical string the host
+      // refreshes on its own cadence — stamped at mint like the phase.
+      if (s.ctx) rec.ctx = s.ctx;
+      if (droppedSinceLast > 0) { rec.droppedSinceLast = droppedSinceLast; droppedSinceLast = 0; }
+      records.push(rec);
+    },
+
+    /** SPEC §3.2 — the rolling summary. Absent fields stay absent. */
+    summary() {
+      const sortedMs = sortedNonPaused('frameMs');
+      const seconds = count > 1
+        ? (atLane[prevIdx(0)] - atLane[prevIdx(count - 1)]) / 1000
+        : 0;
+      const last = prevIdx(0);
+      const median = pct(sortedMs, 0.5);
+      const s = {
+        at: new Date().toISOString(),
+        window: { frames: sortedMs.length, seconds: +Math.max(0, seconds).toFixed(1) },
+        frame: {},
+        render: {}, memory: {},
+        paused: count > 0 ? pausedLane[last] === 1 : false,
+      };
+      if (median !== null) {
+        s.frame.medianMs = +median.toFixed(2);
+        s.frame.p95Ms = +pct(sortedMs, 0.95).toFixed(2);
+        s.frame.fps = median > 0 ? Math.round(1000 / median) : 0;
+        const inside = sortedNonPaused('insideRenderMs');
+        s.frame.insideRenderMs = +pct(inside, 0.5).toFixed(2);
+      }
+      if (count > 0) {
+        s.render.calls = lanes.calls[last];
+        s.render.triangles = lanes.triangles[last];
+        s.memory.geometries = lanes.geometries[last];
+        s.memory.textures = lanes.textures[last];
+        s.memory.programs = lanes.programs[last];
+      }
+      return s;
+    },
+
+    /**
+     * §3.5 — USERMARK. The human's half of hitch detection: they FELT it, so
+     * they press the key and the recorder freezes the evidence — the trailing
+     * `windowMs` of ring samples, summarized, with the worst frames ranked
+     * and each classified exactly like an automatic hitch. Exists because the
+     * automatic threshold cannot see "it feels wrong" (steady-but-low fps,
+     * micro-stutter under the hitch bar), and because a human timestamp turns
+     * ten seconds of ring into a labeled training example.
+     */
+    usermark(meta = {}) {
+      const windowMs = meta.windowMs ?? 5000;
+      const tNow = now();
+      const idxs = [];
+      for (let i = 0; i < count; i++) {
+        const idx = prevIdx(i);
+        if (tNow - atLane[idx] > windowMs) break;
+        idxs.push(idx);
+      }
+      const ms = idxs.filter((i) => !pausedLane[i]).map((i) => lanes.frameMs[i]).sort((a, b) => a - b);
+      const worst = [...idxs]
+        .filter((i) => !pausedLane[i])
+        .sort((a, b) => lanes.frameMs[b] - lanes.frameMs[a])
+        .slice(0, 5)
+        .map((i) => {
+          const prev = (i - 1 + RING) % RING;
+          const delta = {};
+          for (const f of ['calls', 'triangles', 'programs', 'textures', 'geometries']) {
+            delta[f] = lanes[f][i] - lanes[f][prev];
+          }
+          const median = pct(ms, 0.5) ?? 0;
+          // A worst frame UNDER the hitch bar is a healthy window, and saying
+          // so beats forcing the classifier to name a culprit for a 17.8ms
+          // frame (field capture: a perfect 300-frame window labeled
+          // long-script — a guess with no incident under it).
+          const nominal = lanes.frameMs[i] <= Math.max(2 * median, 25);
+          return {
+            agoMs: Math.round(tNow - atLane[i]),
+            frameMs: +lanes.frameMs[i].toFixed(1),
+            insideRenderMs: +lanes.insideRenderMs[i].toFixed(1),
+            delta,
+            classification: nominal
+              ? [{ guess: 'nominal', confidence: 'high', evidence: `worst frame ${lanes.frameMs[i].toFixed(1)}ms is inside the hitch bar — a healthy window` }]
+              : classifyHitch({
+                frameMs: lanes.frameMs[i], medianMs: median,
+                insideRenderMs: lanes.insideRenderMs[i], delta,
+                spawned: lanes.spawned[i],
+              }),
+          };
+        });
+      const mark = {
+        type: 'usermark',
+        at: new Date().toISOString(),
+        frame: frameNo,
+        window: {
+          ms: windowMs,
+          frames: idxs.length,
+          medianMs: pct(ms, 0.5) !== null ? +pct(ms, 0.5).toFixed(2) : undefined,
+          p95Ms: pct(ms, 0.95) !== null ? +pct(ms, 0.95).toFixed(2) : undefined,
+        },
+        worstFrames: worst,
+      };
+      if (meta.note) mark.note = meta.note;
+      if (meta.phase) mark.phase = meta.phase;
+      if (meta.ctx) mark.ctx = meta.ctx;
+      if (meta.inputsHeld) mark.inputsHeld = meta.inputsHeld;
+      if (meta.world) mark.world = meta.world;
+      records.push(mark);
+      return mark;
+    },
+
+    /** Hand back accumulated records and clear — the host owns transport. */
+    drainRecords() { const r = records; records = []; return r; },
+  };
+}