mapspinner 0.1.1

package/.claude/workflows/fps-perf.js

@@ -0,0 +1,147 @@
+export const meta = {
+  name: 'fps-perf',
+  description: 'Find + attack TV8 runtime FPS bottlenecks: measure the GPU VS/FS split on a headed browser, rank the lever, cut, re-measure, verify no visual regression',
+  whenToUse: 'When the live frame rate is low (close-approach / low-alt especially). Runs the measure-first loop: __diag.gpuTimer attributes frame ms to VS (per-vertex 14-oct broadShapeM x3/vertex) vs FS (per-pixel shade) vs CPU emit, ranks the most-performant lever, proposes the cut, and re-measures. Needs a headed browser (EXT_disjoint_timer_query_webgl2 is absent in headless node-gl).',
+  phases: [
+    { title: 'Map',     detail: 'parallel readers over the runtime frame path: gl-render.js draw/emit, planet-orchestrator.js LOD/cull, terrain.glsl VS displace + FS shade' },
+    { title: 'Measure', detail: 'headed-browser __diag.gpuTimer baseline: fullMs (VS+FS), vsRasterMs (VS+raster), fsMs delta, per rung (orbit/lowalt/closeup/deck)' },
+    { title: 'Rank',    detail: 'pick the dominant cost (VS triple-fractal / GRID tessellation / deck maxLevel / over-subdivision / FS per-pixel / CPU emit) as the single most-performant lever' },
+    { title: 'Cut',     detail: 'one reduction for the ranked lever, with the LOD-invariance + no-seam constraint stated' },
+    { title: 'Verify',  detail: 'per cut: re-measure gpuTimer delta + continuous-normals/no-seam visual witness + lab gates; each shader edit = one cold compile so batch reloads' },
+  ],
+}
+
+// ----------------------------------------------------------------------------
+// TV8 fps-perf workflow. The BEHIND-LIMB cull (planet-orchestrator.js limb cull + forward-cone
+// rescue) already removes ~50-80% of generated leaves, and frustum cull is intentionally OFF (it
+// mis-culled bulged on-screen quads). So the remaining runtime cost is the KEPT VISIBLE quads x the
+// per-vertex work. The known prime lever: terrain.glsl's lit-normal FD runs TWO extra full broadShapeM
+// (14-octave) calls per vertex on top of the displacement call = 3x fractal/vertex over GRID=24 ->
+// (24+2)^2=676 verts/quad. broadShapeM MUST stay a pure LOD-invariant world-dir function (a per-tile /
+// LOD octave fade was TRIED + REFUTED: adjacent tiles diverge at the shared edge = seams/popping), so
+// any cheaper gradient must not reintroduce that seam. The measurement gap this workflow closes: node
+// headless gl has no EXT_disjoint_timer_query_webgl2, so VS-vs-FS attribution was impossible -- a HEADED
+// browser + __diag.gpuTimer (full frame vs __fsCheap short-circuit frame) finally names the split, so
+// the lever is PICKED from a number, not guessed.
+// ----------------------------------------------------------------------------
+
+const FRAME_FILES = [
+  { path: 'src/gl-render.js',           lens: 'per-frame instBuf Float32Array(n*5)+bufferData upload, drawElementsInstanced, GRID mesh size, uniform set, _lastInstQuads reuse guard' },
+  { path: 'src/planet-orchestrator.js', lens: 'per-frame quadtree split (splitFactor/altSplitMul low-alt PEAK/distFactor), maxLevel + altitude-gated deck cap, behind-limb cull + forward-cone rescue, leaf emit count. NOTE the altSplitMul PEAK is the highest-payoff LOD-quad-count lever measured (2026-06-04): a LIVE window.__splitFactor sweep at the worst rung names the quads-vs-pxPerPoly knee with NO edit/cold-compile.' },
+  { path: 'src/shaders/terrain.glsl',   lens: 'VS vtxDisplace + the lit-normal FD (2 extra full broadShapeM/vertex), broadShapeM octave count, FS per-pixel shade (riverMask/strata/biome/detail-normal taps)' },
+]
+
+const COST_SCHEMA = {
+  type: 'object',
+  properties: {
+    costs: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name:        { type: 'string' },
+          file:        { type: 'string' },
+          stage:       { type: 'string', description: 'VS | FS | CPU-emit | LOD-quad-count' },
+          perWhat:     { type: 'string', description: 'per-vertex | per-pixel | per-quad | per-frame' },
+          cutIdea:     { type: 'string' },
+          lodInvariant:{ type: 'boolean', description: 'true if the cut keeps broadShapeM a pure LOD-invariant world-dir fn (no seam)' },
+          regressionRisk: { type: 'string', description: 'low | medium | high, and the witness that proves no-regression (continuous normals / no seam / lab gate)' },
+        },
+        required: ['name', 'file', 'stage', 'cutIdea', 'regressionRisk'],
+      },
+    },
+  },
+  required: ['costs'],
+}
+
+phase('Map')
+const maps = await parallel(FRAME_FILES.map(f => () =>
+  agent(
+    `Read ${f.path} in the TV8 repo and map every per-frame RUNTIME cost it carries (focus: ${f.lens}). ` +
+    `For each cost return name, file, stage (VS|FS|CPU-emit|LOD-quad-count), perWhat, a concrete cutIdea, ` +
+    `whether it keeps broadShapeM LOD-invariant (no seam), and regressionRisk with the witness that proves no-regression. ` +
+    `Do NOT edit anything; this is a read+map pass.`,
+    { label: `map:${f.path.split('/').pop()}`, phase: 'Map', schema: COST_SCHEMA }
+  )
+))
+const costs = maps.filter(Boolean).flatMap(m => m.costs)
+
+// MEASURE is a HEADED-browser dispatch the human (or the gm chain) runs OUTSIDE this workflow, because
+// the workflow's subagents have no browser surface -- they reason over the map + the gpuTimer numbers
+// the chain captured. The chain passes the measured split in via args.measured (fullMs/vsRasterMs/fsMs
+// per rung). If absent, the Rank agent reasons from the static map + the known triple-fractal prior.
+// MEASURE health-check FIRST (2026-06-04 lesson): before trusting any gpuTimer number, read
+// window.__pageErr and confirm dbg.quads()>0 with __altM tracking dbg.gotoDown(km). A FROZEN __altM +
+// zero quads + the loading overlay still up is a CRASHED render loop (e.g. a ReferenceError thrown
+// per-frame), NOT a slow one -- gpuTimer will read ~0.002ms on an empty frame and mislead the rank.
+// LIVEST lever-finding: sweep window.__splitFactor live ([2.0,1.4,1.0,0.7]) + orch.clearCache() at the
+// worst rung, reading gpuTimer + pxPerPoly each step; the quads/vsRaster/pxPerPoly knee names the cut
+// with no source edit and no ~190s cold compile. Then bake the winning value into altSplitMul's PEAK.
+phase('Measure')
+const measured = (typeof args === 'object' && args && args.measured) ? args.measured : null
+log(measured
+  ? `gpuTimer split provided: ${JSON.stringify(measured)}`
+  : 'no measured split passed (args.measured); ranking from the static map + the triple-fractal VS prior')
+
+phase('Rank')
+const ranking = await agent(
+  `Rank these TV8 per-frame runtime costs to pick the SINGLE most-performant FPS lever. ` +
+  `Context: behind-limb cull already removes ~50-80% of leaves; frustum cull is intentionally OFF; the ` +
+  `prime known cost is the VS running 3x full broadShapeM/vertex (displace + 2 FD taps) over 676 verts/quad. ` +
+  (measured ? `MEASURED gpuTimer split (authoritative): ${JSON.stringify(measured, null, 2)}. ` : `No live measurement; weight the VS triple-fractal prior. `) +
+  `Pick the lever with the highest payoff that keeps broadShapeM LOD-invariant (no seam). Costs:\n${JSON.stringify(costs, null, 2)}`,
+  { label: 'rank', phase: 'Rank', schema: {
+      type: 'object',
+      properties: {
+        lever: { type: 'string', description: 'the single chosen lever' },
+        stage: { type: 'string', description: 'VS | FS | CPU-emit | LOD-quad-count' },
+        rationale: { type: 'string' },
+        ranked: { type: 'array', items: { type: 'object', properties: {
+          name: { type: 'string' }, rank: { type: 'number' }, expectedSaving: { type: 'string' },
+          gate: { type: 'string' } }, required: ['name', 'rank', 'expectedSaving', 'gate'] } },
+      }, required: ['lever', 'stage', 'ranked'] } }
+)
+
+phase('Cut')
+// Propose the concrete edit for the chosen lever + the witness that proves it (re-measured gpuTimer
+// delta + continuous-normals/no-seam visual witness). Adversarially verify each before it is applied.
+const cuts = await pipeline(
+  ranking.ranked.sort((a, b) => a.rank - b.rank),
+  sec => agent(
+    `Propose the concrete code edit for TV8 FPS lever "${sec.name}" (expected saving ${sec.expectedSaving}). ` +
+    `Give the exact file, the old snippet, the new snippet, and the WITNESS that proves it: the re-measured ` +
+    `__diag.gpuTimer fullMs/fsMs delta AND the visual invariant (continuous normals across a tile boundary, ` +
+    `no seam/popping, glError 0). Gate: ${sec.gate}. broadShapeM MUST stay a pure LOD-invariant world-dir fn ` +
+    `(a per-tile / screen-space gradient that diverges at shared edges = the refuted seam). If risk is high, say so.`,
+    { label: `cut:${sec.name}`, phase: 'Cut', schema: {
+        type: 'object',
+        properties: {
+          file: { type: 'string' }, oldSnippet: { type: 'string' }, newSnippet: { type: 'string' },
+          witness: { type: 'string' }, safe: { type: 'boolean' }, notes: { type: 'string' },
+        }, required: ['file', 'witness', 'safe'] } }
+  ),
+  (proposal, sec) => agent(
+    `Adversarially verify this TV8 FPS cut for "${sec.name}". Could it reintroduce a tile-edge seam, break ` +
+    `LOD invariance, change the rendered terrain (shape/biome/lighting), break a uniform, or fail to compile? ` +
+    `Default to safe=false if uncertain. Proposal:\n${JSON.stringify(proposal, null, 2)}`,
+    { label: `verify:${sec.name}`, phase: 'Verify', schema: {
+        type: 'object',
+        properties: { real: { type: 'boolean' }, safe: { type: 'boolean' }, reason: { type: 'string' } },
+        required: ['real', 'safe', 'reason'] } }
+  ).then(v => ({ section: sec.name, proposal, verdict: v }))
+)
+
+const safe = cuts.filter(Boolean).filter(c => c.proposal.safe && c.verdict.safe)
+const risky = cuts.filter(Boolean).filter(c => !(c.proposal.safe && c.verdict.safe))
+return {
+  lever: ranking.lever,
+  stage: ranking.stage,
+  rationale: ranking.rationale,
+  measured,
+  ranked: ranking.ranked,
+  safeCuts: safe.map(c => ({ section: c.section, file: c.proposal.file, witness: c.proposal.witness })),
+  gatedCuts: risky.map(c => ({ section: c.section, reason: c.verdict.reason })),
+  note: 'Re-measure __diag.gpuTimer after each cut on a headed browser; broadShapeM stays LOD-invariant ' +
+        '(no per-tile/screen-space gradient that seams). Batch terrain.glsl edits into ONE reload ' +
+        '(each shader edit = a fresh ~188s cold compile). Witness continuous normals + glError 0 before COMPLETE.',
+}

package/.claude/workflows/optimize-dna.js

@@ -0,0 +1,201 @@
+export const meta = {
+  name: 'optimize-dna',
+  description: 'Maximize whole-project optimization through the 12-principle synthesized-engineering-DNA lens. Fans out per-axis finders (correctness, speed, simplification/maintenance-burden, architecture-pliability, jank/tell-tale-AI), adversarially verifies each finding (is it real? does fixing it regress another axis?), then arbitrates ALL findings across axes into ONE DNA-ranked plan. Composes the speed-dna workflow for the speed axis rather than re-implementing it.',
+  whenToUse: 'When the user wants a holistic optimization pass over the WHOLE project (not just speed) -- correctness/bugs, runtime/compile speed, simplification + maintenance-burden reduction, architecture pliability, and machine-shaped jank -- ranked and arbitrated as one budget through the compound DNA lens. The cross-axis arbitration is the capability no single skill has: code-review finds bugs, simplify finds cleanups, speed-dna finds speed levers, but nothing weighs a simplification that costs perf against a perf cut that adds risk.',
+  phases: [
+    { title: 'Constraints', detail: 'P5 physics-first: fix the hard project constraints + the measured-dead record (FS source-shrink dead, atlas is the only compile lever, broadShapeM LOD-invariant/no-seam, 141s/shader-edit) so no finder proposes refuted or physics-fighting work' },
+    { title: 'Map',         detail: 'one reader per optimization AXIS maps that axis surface (correctness, speed, simplification, architecture, jank) tagged with the DNA principle that judges it' },
+    { title: 'Find',        detail: 'parallel finders per axis surface findings (a bug, a perf lever, a dedupe/simplification, a bespoke->native swap that NET-SHRINKS, a tell-tale-AI shape)' },
+    { title: 'Verify',      detail: 'P6 adversarial: each finding gets refuted -- is it REAL, and does fixing it REGRESS another axis (a simplification that costs perf, a perf cut that adds risk, a dep that net-grows surface)?' },
+    { title: 'Arbitrate',   detail: 'P11 crucible / P2+P9+P12: rank ALL surviving cross-axis findings into ONE budget by DNA-principle order weighted by felt human-value; resolve every cross-axis conflict explicitly' },
+    { title: 'Plan',        detail: 'P10 honest interface: return the DNA-justified, witness-bearing, cross-axis-arbitrated optimization plan, each item with the no-regression witness and the principle that ranked it' },
+  ],
+}
+
+// ----------------------------------------------------------------------------
+// optimize-dna -- the whole-project optimization workflow. It does NOT duplicate the existing
+// single-concern tooling (P2 subtractive / P4 composition spine): the SPEED axis is delegated to
+// the speed-dna workflow (which already arbitrates compile-vs-fps); code-review / simplify already
+// own bug-hunting and cleanup. What this workflow ADDS is the layer above them: a CROSS-AXIS
+// arbitration that ranks a bug fix, a perf lever, a simplification, an architecture swap, and a
+// jank cleanup against EACH OTHER in one budget, by DNA-principle order, weighted by felt impact.
+//
+// The load-bearing priors every finder must respect (P7 measure-don't-assume, P3 revert-and-don't-
+// rechase):
+//   - COLD-COMPILE: FS source-shrink is MEASURED-DEAD; the only real compile lever is atlas/THC
+//     height-bake (removes the per-vertex fractal from the VS). FPS prime lever = the VS 3x-fractal
+//     /vertex + LOD quad count. broadShapeM MUST stay a pure LOD-invariant world-dir fn (per-tile/
+//     screen-space octave fade was TRIED + REFUTED = seams).
+//   - Each terrain.glsl edit = one ~141s cold ANGLE compile -> a finder that proposes a shader micro-
+//     edit must justify it against that cost (P5/P12: a change a user never feels but costs 141s to
+//     ship is negative value).
+//   - Net-smaller-surface rule (P2): a bespoke->library/native swap is only a win if it NET-SHRINKS
+//     the shipped+maintained surface; adding a heavy dep to delete a few lines is the failure mode.
+//
+// args (all optional): { axes: <string[] subset of the 5 axis keys to run; default all>,
+//                        runSpeedChild: <bool, run the speed-dna child for the speed axis; default false
+//                          since it needs headed-browser numbers -- when false the speed finder reasons
+//                          from the static map + the measured priors>,
+//                        speedArgs: <forwarded to the speed-dna child: {measured, compile}> }
+// ----------------------------------------------------------------------------
+
+const A = (typeof args === 'object' && args) ? args : {}
+
+// The 12 principles as the ranking lens handed to every finder + the arbiter (P1 data-first: kept as
+// data, never branched on).
+const DNA = [
+  'P1 data-first: is this a state/data-model problem (fix the model, not the control flow around it)?',
+  'P2 subtractive: can the thing be REMOVED rather than improved? does a fix NET-SHRINK the surface?',
+  'P3 evolutionary: ship the simplest thing that works; revert-first on regressions.',
+  'P4 composition-spine: does each module do one thing, understandable at its call site?',
+  'P5 physics-first: what hardware/driver constraint bounds this (ANGLE compile, ALU, bandwidth, vert count)?',
+  'P6 adversarial: is misuse structurally possible? make the wrong thing hard.',
+  'P7 empirical: is there a MEASURED number, or a guess? refuse measured-dead levers.',
+  'P8 automated-correctness: can a guardrail (lint/type/pure-fn/gate) prevent this class of bug?',
+  'P9 worst-case: does it help the WORST case (close-approach fps / cold first-load), not just average?',
+  'P10 honest-interface: does any public contract / default behaviour lie about what it guarantees?',
+  'P11 crucible: does the hardest integration (close-approach, cold load, real input) still hold?',
+  'P12 human-value: does a real user FEEL this? trace the impact chain to a human outcome.',
+]
+
+// The optimization AXES. Each is one finder surface; speed is delegated to the speed-dna child.
+const AXES = [
+  { key: 'correctness', principles: 'P6/P8/P9/P11',
+    prompt: 'Hunt CORRECTNESS issues: real bugs, unguarded invalid states, worst-case failure modes (close-approach, cold load, degenerate input), silent-catastrophic paths, missing guardrails. For each: the bug, the file:line, the failure trigger, and the structural guardrail (P8) that would prevent the class.' },
+  { key: 'speed', principles: 'P5/P7/P9', delegate: 'speed-dna',
+    prompt: 'Map the SPEED levers (cold compile + runtime fps) WITHOUT re-deriving the speed-dna analysis. Respect the measured-dead record (FS source-shrink dead; atlas is the only compile lever; VS triple-fractal + LOD-quad-count are the fps levers). Surface only the top levers + their expected saving + the no-seam/LOD-invariance gate.' },
+  { key: 'simplification', principles: 'P2/P4',
+    prompt: 'Hunt SIMPLIFICATION + maintenance-burden cuts: duplicated logic (drift-prone reimplementations like a second copy of a mirror), dead code, abstractions that cost more than they deliver, config options that could be a default, kitchen-sink modules. For each: what to REMOVE/merge, the net-lines-saved, and the risk witness (lint/gate that proves no behaviour change).' },
+  { key: 'architecture', principles: 'P1/P4/P10',
+    prompt: 'Hunt ARCHITECTURE-pliability improvements: a bad data model the code works around (P1), a bespoke reimplementation a popular well-maintained library/native API replaces with a NET-SMALLER surface (P2 -- reject if the dep net-grows surface), a layer boundary that is bypassed, a dishonest default/interface (P10). For each: the change, the net-surface delta, and why it is clearly outstanding.' },
+  { key: 'jank', principles: 'P12 + gm-discipline',
+    prompt: 'Hunt JANK + tell-tale-AI shapes: unfinished edges, half-wired paths, immaturity across gui/ux/client-state/server-state and the client/server boundary; AND machine-authored tells (boilerplate flourishes, over-hedged comments, generic scaffold names, decorative non-ASCII glyphs that should be ASCII). For each: the surface, what unfinished/machine-shaped thing it is, and the polish/convert fix.' },
+]
+
+const FINDING_SCHEMA = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          title:        { type: 'string' },
+          axis:         { type: 'string', description: 'correctness | speed | simplification | architecture | jank' },
+          file:         { type: 'string', description: 'file:line if known' },
+          what:         { type: 'string', description: 'the concrete issue + the concrete fix' },
+          dnaPrinciple: { type: 'string', description: 'the principle that most justifies acting (e.g. P2 subtractive)' },
+          surfaceDelta: { type: 'string', description: 'net lines/files/deps added or removed by the fix (P2 net-shrink test)' },
+          crossAxisRisk:{ type: 'string', description: 'does the fix regress another axis? (simplify costs perf, perf cut adds risk, dep net-grows surface)' },
+          measuredDead: { type: 'boolean', description: 'true if this is a known refuted/measured-dead lever (e.g. FS source-shrink for cold compile)' },
+          felt:         { type: 'string', description: 'P12: the human outcome a real user feels, or "internal only"' },
+        },
+        required: ['title', 'axis', 'what', 'dnaPrinciple'],
+      },
+    },
+  },
+  required: ['findings'],
+}
+
+// --- Constraints (P5 physics-first) ---------------------------------------------------------
+phase('Constraints')
+const CONSTRAINTS = [
+  'COLD COMPILE: FS source-shrink is MEASURED-DEAD (ANGLE DCEs unused funcs; cost is intrinsic HLSL translation of the FS/VS main). The only real compile lever is the atlas/THC height-bake (removes the per-vertex broadShapeM fractal from the VS). Driver-cached: warm 41ms, cold ~141s, recurs on shader SOURCE change.',
+  'FPS: the VS runs 3x full 12-oct broadShapeM/vertex (displace + 2 central-diff taps); behind-limb cull removes ~50-80% leaves; frustum cull intentionally OFF.',
+  'broadShapeM MUST stay a pure LOD-invariant world-dir fn: a per-tile/screen-space octave fade was TRIED + REFUTED (seams at shared tile edges).',
+  'Each terrain.glsl edit = one ~141s cold compile -> a shader micro-edit a user never feels is negative value (P5/P12). BATCH shader edits.',
+  'NET-SMALLER-SURFACE (P2): a bespoke->library/native swap is a win ONLY if it net-shrinks the shipped+maintained surface; a heavy dep to delete a few lines net-grows it.',
+  'There is ONE canonical broadShapeM Node mirror (terrain-lab-shape.js, 2026-06-09 consolidation); a finder proposing a second copy is reintroducing refuted drift.',
+]
+log('Constraints fixed (' + CONSTRAINTS.length + '); measured-dead + refuted levers will be refused.')
+
+// --- Map + Find (fan-out, one finder per axis) ----------------------------------------------
+phase('Map')
+const selected = Array.isArray(A.axes) && A.axes.length ? AXES.filter(x => A.axes.includes(x.key)) : AXES
+log('running ' + selected.length + ' optimization axes: ' + selected.map(x => x.key).join(', '))
+
+phase('Find')
+const perAxis = await parallel(selected.map(ax => async () => {
+  // The SPEED axis is delegated to the speed-dna workflow (compose, do not re-implement).
+  if (ax.delegate === 'speed-dna' && A.runSpeedChild) {
+    try {
+      const speed = await workflow('speed-dna', A.speedArgs || {})
+      const ranked = (speed && speed.ranked) || []
+      return { findings: ranked.map(r => ({
+        title: 'speed: ' + (r.name || r.lever || 'lever'), axis: 'speed', file: speed.topAxis || '',
+        what: (r.expectedSaving ? ('expected ' + r.expectedSaving + '. ') : '') + (speed.rationale || ''),
+        dnaPrinciple: r.dnaPrinciple || 'P5', surfaceDelta: '', crossAxisRisk: (r.gate || ''),
+        measuredDead: false, felt: 'frame rate / load time',
+      })) }
+    } catch (e) {
+      log('speed-dna child failed (' + String(e.message || e) + '); falling back to static speed map')
+    }
+  }
+  return agent(
+    ax.prompt + '\n' +
+    'Judge each finding through the synthesized-engineering-DNA lens (this axis leans on ' + ax.principles + '):\n' +
+    DNA.map(d => '  - ' + d).join('\n') + '\n' +
+    'HARD CONSTRAINTS (a finding that violates one is invalid -- flag measuredDead=true):\n' +
+    CONSTRAINTS.map(c => '  - ' + c).join('\n') + '\n' +
+    'Return findings with title, axis="' + ax.key + '", file:line, what (issue + concrete fix), dnaPrinciple, surfaceDelta (P2 net-shrink), crossAxisRisk, measuredDead, felt (P12). Read-only; do NOT edit.',
+    { label: 'find:' + ax.key, phase: 'Find', schema: FINDING_SCHEMA }
+  )
+}))
+const found = perAxis.filter(Boolean).flatMap(r => (r && r.findings) || [])
+const live  = found.filter(f => !f.measuredDead)
+const dead  = found.filter(f => f.measuredDead)
+log('found ' + found.length + ' (' + live.length + ' live, ' + dead.length + ' measured-dead dropped)')
+
+// --- Verify (P6 adversarial: is it real, does it regress another axis?) ----------------------
+phase('Verify')
+const verified = await pipeline(
+  live,
+  f => agent(
+    'Adversarially verify this TV8 optimization finding. (1) Is it REAL -- not a false positive, not already handled, not a measured-dead lever (FS source-shrink for cold compile, a per-tile broadShapeM fade, a second mirror copy)? (2) Does fixing it REGRESS another optimization axis -- a simplification that costs perf, a perf cut that adds correctness risk or a seam, a dep that net-GROWS the surface, an architecture change that breaks a public default? Default real=false / regresses=true if uncertain. Finding:\n' + JSON.stringify(f, null, 2),
+    { label: 'verify:' + (f.axis || '?') + ':' + (f.title || '').slice(0, 24), phase: 'Verify', schema: {
+        type: 'object',
+        properties: { real: { type: 'boolean' }, regressesOtherAxis: { type: 'boolean' }, reason: { type: 'string' } },
+        required: ['real', 'regressesOtherAxis', 'reason'] } }
+  ).then(v => ({ ...f, verdict: v }))
+)
+const confirmed = verified.filter(Boolean).filter(f => f.verdict && f.verdict.real && !f.verdict.regressesOtherAxis)
+const gated     = verified.filter(Boolean).filter(f => !(f.verdict && f.verdict.real && !f.verdict.regressesOtherAxis))
+log('confirmed ' + confirmed.length + '/' + live.length + ' after adversarial verify')
+
+// --- Arbitrate (P11 crucible / P2+P9+P12: ONE budget across all axes) ------------------------
+phase('Arbitrate')
+const ranking = confirmed.length ? await agent(
+  'You are arbitrating the TV8 whole-project optimization budget across ALL axes (correctness, speed, simplification, architecture, jank) as ONE ranked plan, through the synthesized-engineering-DNA lens. Rank the CONFIRMED findings below highest-payoff first, applying the principle order P1>P2>...>P12 (earlier principles win conflicts) weighted by P12 human-value (a thing a user FEELS continuously outranks an internal nicety). ' +
+  'Resolve every CROSS-AXIS conflict explicitly: when two findings touch the same code or trade against each other (a simplification vs a perf lever, a correctness guardrail vs subtractive removal), state which wins and cite the principle. Prefer the change that REMOVES surface (P2) and helps the WORST case (P9). Confirmed findings:\n' + JSON.stringify(confirmed, null, 2),
+  { label: 'arbitrate', phase: 'Arbitrate', schema: {
+      type: 'object',
+      properties: {
+        topItem: { type: 'string', description: 'the single highest-payoff optimization to do first' },
+        rationale: { type: 'string', description: 'why first, in DNA-principle terms' },
+        crossAxisConflicts: { type: 'array', items: { type: 'object', properties: {
+          conflict: { type: 'string' }, winner: { type: 'string' }, principle: { type: 'string' } },
+          required: ['conflict', 'winner', 'principle'] } },
+        ranked: { type: 'array', items: { type: 'object', properties: {
+          title: { type: 'string' }, axis: { type: 'string' }, rank: { type: 'number' },
+          dnaPrinciple: { type: 'string' }, expectedValue: { type: 'string' }, gate: { type: 'string' } },
+          required: ['title', 'axis', 'rank', 'expectedValue'] } },
+      }, required: ['topItem', 'ranked'] } }
+) : { topItem: null, rationale: 'no confirmed findings survived adversarial verify', crossAxisConflicts: [], ranked: [] }
+
+// --- Plan (P10 honest interface) ------------------------------------------------------------
+phase('Plan')
+return {
+  workflow: 'optimize-dna',
+  constraints: CONSTRAINTS,
+  axesRun: selected.map(x => x.key),
+  measuredDeadDropped: dead.map(f => ({ title: f.title, axis: f.axis, why: f.what })),
+  topItem: ranking.topItem,
+  rationale: ranking.rationale,
+  crossAxisConflicts: ranking.crossAxisConflicts || [],
+  ranked: ranking.ranked,
+  gatedFindings: gated.map(f => ({ title: f.title, axis: f.axis, reason: f.verdict && f.verdict.reason })),
+  note: 'Apply ranked items highest-first. Each is cross-axis-verified (real + does not regress another axis). ' +
+        'Speed items: re-measure on a HEADED browser; broadShapeM stays LOD-invariant; FS source-shrink for cold compile is measured-dead. ' +
+        'Architecture/dep swaps must NET-SHRINK the surface. BATCH terrain.glsl edits (each = ~141s cold compile). ' +
+        'Run the speed-dna workflow directly for a deep speed pass; this workflow is the cross-axis layer above it.',
+}

package/.claude/workflows/shader-bottleneck-dna.js

@@ -0,0 +1,168 @@
+export const meta = {
+  name: 'shader-bottleneck-dna',
+  description: 'Profile + eliminate every possible bottleneck in the TV8 shaders (terrain.glsl VS+FS, water path, probe variant) through the synthesized-engineering-DNA lens: physics-first constraints, measure-first, subtract-before-add, adversarial refute-by-default verify. Fans out per-surface finders + web-research agents; outputs a ranked, witness-bearing cut plan.',
+  whenToUse: 'When the user wants an exhaustive shader-only bottleneck sweep (runtime ALU/varying/branch cost AND FXC/ANGLE compile shape), honouring the refuted-lever record (VS no-loss frontier, FS source-shrink dead, atlas faceting) so no dead lever is re-chased.',
+  phases: [
+    { title: 'Constraints', detail: 'P5 physics-first: fix the hard priors as data -- VS-bound (96%), FD 3-tap irreducible at no-loss, FXC uOctMax/fdIters invariants, refuted-lever list' },
+    { title: 'Research',    detail: 'P7: web agents gather external evidence (FXC codegen pitfalls, ANGLE translation cost, snoise cost models, varying/interpolator pressure) -- evidence feeds finders, never ships unverified' },
+    { title: 'Find',        detail: 'fan-out finders per shader surface, each blind to the others, each handed the constraints + research digest' },
+    { title: 'Verify',      detail: 'P6 adversarial: every candidate refuted by 3 lenses (correctness/fidelity, FXC-invariant, actually-measurable); 2-of-3 survive threshold' },
+    { title: 'Rank',        detail: 'P2+P9+P12 arbitration into ONE ranked plan with per-cut witness' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// The refuted record (P7: measured-dead, finders must NOT propose these):
+//  - VS octave reduction below 12 / wider FD step / analytic-derivative normal / full-height
+//    atlas: ALL refuted 2026-06-10 (tv8-VS-perf-frontier record) -- fidelity loss measured.
+//  - FS source-shrink for cold compile: measured-dead (cost = FXC optimize, not chars).
+//  - per-tile/screen-space octave fade: seams at shared tile edges.
+//  - constant-bound fractal loops / differencing composeHeight across call sites: FXC
+//    mis-translation roots (uOctMax + fdIters fixes, commits f062365 + d56a202) -- INVARIANT.
+//  - CPU-frame alloc/upload churn: 96% GPU-bound, refuted wb08pmga5.
+// What HAS CHANGED since those records (fresh ground the finders target):
+//  - 4770801 moved the domain warp to the VS (vTexWarp varying, -9 snoise3/px) and halved freqs.
+//  - d56a202 rewrote the FD normal as a runtime-bounded fdIters loop (3x height in ONE loop).
+//  - The FS still carries ~17 snoise3/px in places (rockface fBm, mottle, overlay) -- FS was
+//    "not the bottleneck" pre-warp-move; the VS/FS split MUST be re-measured post-change.
+// ---------------------------------------------------------------------------
+
+const A = (typeof args === 'object' && args) ? args : {}
+const measured = A.measured || null   // fresh gpuTimer split {fullMs, vsRasterMs, fsMs} per rung
+
+const DNA = [
+  'P2 subtractive: prefer REMOVING a tap/branch/varying outright over speeding it',
+  'P5 physics-first: name the bound (ALU, interpolator count, register pressure, FXC optimize time)',
+  'P7 empirical: every claim needs a measurable witness; UNMEASURED is a flag, not a guess',
+  'P9 worst-case: the deck (close-approach) rung and the d3d11 cold path outrank averages',
+  'P12 human-value: per-frame stutter > once-per-machine compile',
+]
+
+const CONSTRAINTS = [
+  'VS-bound: ~96% of frame GPU is VS+raster at the deck (measured). The lit-normal FD 3-tap through the fdIters loop is the irreducible VS cost at zero fidelity loss (frontier record 2026-06-10) -- do not re-propose octave cuts, wider FD, analytic normals, or full-height atlas.',
+  'FXC invariants (d3d11 default Chrome): uOctMax + fdIters loops stay runtime-bounded; never difference composeHeight across call sites; any NEW VS fractal loop gets a runtime bound.',
+  'highp islands on every planet-scale quantity stay; global mediump elsewhere.',
+  'broadShapeM stays a pure LOD-invariant world-dir fn (per-tile octave fade = seams, refuted).',
+  'FS source-shrink is dead as a compile lever; cold d3d11 compile is 31s (corrected figure) and acceptable.',
+  'Each terrain.glsl edit = one cold FXC compile for d3d11 users; BATCH shader edits into one reload; dev loop is vulkan (140ms).',
+  'Verification surface: warm-tab /cmd + __diag (gpuTimer, bisect, groundTruth, seamProbe, verify.mjs suite). gpuTimer through the spool-browser verb TIMES OUT -- use /cmd.',
+]
+
+// Shader surfaces, each a finder lens. Fresh-ground emphasis per the changed-since record.
+const SURFACES = [
+  { key: 'vs-height',     lens: 'terrain.glsl VS height path: vtxDisplace, broadShapeM call count, the fdIters FD loop shape (is any height work duplicated outside it? is the water uIsWater gate still dead-code-free?), carve fns, anchor cbias. Count snoise3 evaluations per vertex on the worst path.' },
+  { key: 'vs-varyings',   lens: 'VS->FS interface: count every varying (incl. new vTexWarp), their precision, packing opportunities (vec2 pairs into vec4), interpolator pressure on mobile-class GPUs, and any varying computed but consumed only on a gated FS path.' },
+  { key: 'fs-material',   lens: 'terrain.glsl FS material/splat: per-pixel snoise3 census post-4770801 (rockface 3-oct fBm, mottle, detail overlay, strata), texture tap count per layer (4 layers x albedo+normal A/B), texIdent path, slope/rock gates -- which taps are live on FLAT ground (the common case, P9)?' },
+  { key: 'fs-lighting',   lens: 'terrain.glsl FS lighting: detail-normal biplanar RNM taps, slope/gorge AO, aerial perspective single-scatter, haze/overlay fades -- distance/pxWorld gating completeness: does every expensive term fade out where invisible?' },
+  { key: 'fs-water',      lens: 'water shading path: per-pixel cost, whether water pixels pay terrain-material costs before the water branch, ocean/lake/river branch structure under d3d11 (branch flattening = both sides paid).' },
+  { key: 'compile-shape', lens: 'FXC compile-time shape: loop bounds, function inlining sites, anything that could regress the 31s cold figure or re-trigger per-callsite divergence; probe _PROBE_ variant sharing.' },
+  { key: 'branch-divergence', lens: 'branch + precision audit: mediump leaks onto hot math, highp where mediump suffices on non-planet-scale values, branches FXC will flatten (both sides executed), redundant normalize/pow/exp on hot paths.' },
+]
+
+const FINDING_SCHEMA = {
+  type: 'object',
+  properties: {
+    findings: { type: 'array', items: { type: 'object', properties: {
+      name: { type: 'string' }, file: { type: 'string' }, line: { type: 'string' },
+      stage: { type: 'string', description: 'VS | FS | varying | compile' },
+      perWhat: { type: 'string', description: 'per-vertex | per-pixel | per-frame | once-cold' },
+      mechanism: { type: 'string', description: 'the physical cost mechanism (ALU taps, interpolators, branch flatten, FXC inline)' },
+      cutIdea: { type: 'string' },
+      estSaving: { type: 'string' },
+      refutedLever: { type: 'boolean', description: 'true if this matches the refuted record -- finder must self-flag' },
+      fidelityRisk: { type: 'string', description: 'none | low | medium | high + what could visibly change' },
+      witness: { type: 'string', description: 'the measurable probe that proves the cut worked with no regression' },
+    }, required: ['name', 'file', 'stage', 'mechanism', 'cutIdea', 'fidelityRisk', 'witness'] } },
+  },
+  required: ['findings'],
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  properties: {
+    real: { type: 'boolean' }, safe: { type: 'boolean' }, reason: { type: 'string' },
+  },
+  required: ['real', 'safe', 'reason'],
+}
+
+// --- Constraints ---------------------------------------------------------------------------
+phase('Constraints')
+log('Constraints fixed (' + CONSTRAINTS.length + '); refuted levers will be self-flagged and dropped, not re-chased.')
+
+// --- Research (web evidence, P7) -------------------------------------------------------------
+phase('Research')
+const RESEARCH_TOPICS = [
+  'ANGLE D3D11 FXC HLSL codegen performance pitfalls for WebGL2 GLSL: loop unrolling, branch flattening, interpolator limits, dynamic indexing penalties. Cite sources.',
+  'GPU vertex-shader optimization for procedural terrain: simplex noise ALU cost models, fewest-instruction snoise/simplex variants, vertex cache and varying-count costs on AMD RDNA and mobile GPUs. Cite sources.',
+  'WebGL2 fragment shader cost on flattened branches and mediump vs highp throughput on AMD and mobile; best practice for distance-gated shading terms. Cite sources.',
+]
+const research = await parallel(RESEARCH_TOPICS.map((t, i) => () =>
+  agent('Research via web search (WebSearch/WebFetch): ' + t + ' Return a compact digest of CLAIMS with source URLs; mark each claim verified-by-source vs speculative.',
+    { label: 'research:' + i, phase: 'Research' })
+))
+const researchDigest = research.filter(Boolean).join('\n---\n').slice(0, 8000)
+log('research digests gathered: ' + research.filter(Boolean).length + '/' + RESEARCH_TOPICS.length)
+
+// --- Find (fan-out per surface) --------------------------------------------------------------
+phase('Find')
+const found = await pipeline(
+  SURFACES,
+  s => agent(
+    'TV8 shader bottleneck finder, surface "' + s.key + '". Read src/shaders/terrain.glsl (and src/gl-render.js for uniform/varying wiring) and enumerate EVERY cost on this lens: ' + s.lens + '\n' +
+    'Judge through the DNA lens:\n' + DNA.map(d => '  - ' + d).join('\n') + '\n' +
+    'HARD CONSTRAINTS (violating proposals are auto-dead):\n' + CONSTRAINTS.map(c => '  - ' + c).join('\n') + '\n' +
+    (measured ? 'MEASURED gpuTimer split: ' + JSON.stringify(measured) + '\n' : 'No fresh measurement passed -- flag every estSaving UNMEASURED.\n') +
+    'External research digest (claims with sources; treat as hypotheses to check against the actual code):\n' + researchDigest + '\n' +
+    'Return findings with file:line, the cost MECHANISM, a concrete cutIdea, fidelityRisk, and the witness probe. Self-flag refutedLever=true for anything matching the refuted record. Read-only pass; do not edit.',
+    { label: 'find:' + s.key, phase: 'Find', schema: FINDING_SCHEMA }
+  ),
+  (res, s) => {
+    const live = (res && res.findings || []).filter(f => !f.refutedLever)
+    return parallel(live.map(f => () =>
+      parallel(['fidelity-correctness', 'fxc-invariant', 'measurability'].map(lens => () =>
+        agent(
+          'Adversarially REFUTE this TV8 shader cut candidate via the ' + lens + ' lens. ' +
+          (lens === 'fidelity-correctness' ? 'Could it visibly change terrain shape/material/lighting, seam at tile edges, or break LOD invariance? Read the actual code at the cited location.' :
+           lens === 'fxc-invariant' ? 'Does it reintroduce a constant-bound fractal loop, difference composeHeight across call sites, drop a highp island, or otherwise risk the FXC d3d11 mis-translation class? Read the cited code.' :
+           'Is the claimed saving actually measurable with the named witness, and plausibly non-noise given the VS-bound 96% prior? An FS-only cut at the deck is likely noise.') +
+          ' Default real=false/safe=false if uncertain. Candidate:\n' + JSON.stringify(f, null, 2),
+          { label: 'verify:' + f.name + ':' + lens, phase: 'Verify', schema: VERDICT_SCHEMA }
+        )
+      )).then(vs => {
+        const ok = vs.filter(Boolean).filter(v => v.real && v.safe).length >= 2
+        return { surface: s.key, finding: f, confirmed: ok, verdicts: vs }
+      })
+    ))
+  }
+)
+
+const all = found.filter(Boolean).flat().filter(Boolean)
+const confirmed = all.filter(x => x.confirmed)
+const refuted = all.filter(x => !x.confirmed)
+log('candidates: ' + all.length + ' -> confirmed ' + confirmed.length + ', refuted ' + refuted.length)
+
+// --- Rank (single budget) --------------------------------------------------------------------
+phase('Rank')
+const ranking = confirmed.length ? await agent(
+  'Rank these CONFIRMED TV8 shader cuts into ONE ordered plan (highest payoff first) through the DNA lens: ' +
+  'P2 removal>speedup, P9 worst-rung (deck FPS, d3d11 path) first, P12 per-frame>once-cold, P7 measured>estimated. ' +
+  'Batch note: all terrain.glsl edits ship as ONE reload. Confirmed cuts:\n' + JSON.stringify(confirmed.map(c => c.finding), null, 2),
+  { label: 'rank', phase: 'Rank', schema: { type: 'object', properties: {
+      ranked: { type: 'array', items: { type: 'object', properties: {
+        rank: { type: 'number' }, name: { type: 'string' }, file: { type: 'string' },
+        expectedSaving: { type: 'string' }, witness: { type: 'string' } },
+        required: ['rank', 'name', 'file', 'witness'] } },
+      rationale: { type: 'string' } }, required: ['ranked'] } }
+) : { ranked: [], rationale: 'no confirmed cuts survived adversarial verify' }
+
+return {
+  workflow: 'shader-bottleneck-dna',
+  constraints: CONSTRAINTS,
+  researchSources: researchDigest.slice(0, 2000),
+  candidates: all.length,
+  confirmed: confirmed.map(c => ({ surface: c.surface, ...c.finding })),
+  refuted: refuted.map(c => ({ surface: c.surface, name: c.finding.name, why: (c.verdicts || []).filter(v => v && !(v.real && v.safe)).map(v => v.reason).join(' | ') })),
+  ranked: ranking.ranked,
+  rationale: ranking.rationale,
+  note: 'Apply ranked cuts as ONE batched terrain.glsl reload; witness each via /cmd warm-tab (compile clean, glError 0, gpuTimer delta, bisect/seamProbe no-regression, backend-ab d3d11 parity); then verify.mjs full suite.',
+}