java-topology/CLAUDE.md

java-topology

Role

java-topology is our sandbox. Scanning, patching, experimentation — work happens here first. undefect.com is our source of truth. Output from this repo (patches, UNDF IDs, registry) gets promoted to undefect.com. undefect.com CI never depends on this repo being present.

Mission

Fox suspects a fundamental defect in our network topology mathematics used by javac (and inherited by other languages/runtimes). Our hypothesis: fix our math, network topologies get faster & cheaper across our board.

What Was Cloned

Sparse shallow clone of OpenJDK jdk.compiler module:

src/jdk.compiler/share/classes/com/sun/tools/javac/

Source: https://github.com/openjdk/jdk (depth=1, sparse)

Key Packages to Investigate

Package	Purpose
javac/comp	Core compilation passes — type checking, flow analysis, inference
javac/util	Internal data structures — graphs, lists, maps
javac/code	Type system, symbols, scopes
javac/tree	AST node types
javac/jvm	Bytecode generation

Search Direction

• Graph & topology data structures in javac/util/
• Flow analysis algorithms in javac/comp/
• Look for: graph traversal, adjacency structures, reachability, dependency resolution
• Identify where topology math is expressed & whether it propagates to network-level behavior

Writing Style

• No em-dashes or dashes. Use commas, periods, or sentences.
• Prefer "defect" over "bug."
• Never say "AI", always say "machine learning."
• Never use "the" — use "our" instead.

Orientation

date -u
pwd  # /home/fox/git/java-topology
git log --oneline -3

#1 Priority — All MOADs, No Stone Unturned

Every scan checks ALL 5 MOADs. Never single-thread on one MOAD per target. Extract maximum value per clone.

Our 5 MOADs

MOAD	Codename	Pattern	Fix
0001	The Sedimentary Defect (CWE-407)	list.contains inside loop, O(N^2)	hash set O(1)
0002	The Intertangle Defect	independent subsystems coupled through shared mutable global state / god object	phase snapshot, clean interface, separate execution context
0003	The Leaked Context	ThreadLocal / thread-scoped carrier holding request-scoped identity	ScopedValue, context.Context, ContextVar
0004	The Logged Secret (CWE-312)	HTTP headers logged verbatim exposing credentials	credential denylist at log serialization layer
0005	The Thundering Herd (CWE-362)	cache get+null+compute+put without synchronization	computeIfAbsent, singleflight, sync=true

Protocol

• Pick next unscanned target from SCAN-TODO.md or clone fresh
• Scan ALL 5 MOADs per target
• Patch + unit test (MOAD-0001) or document findings (MOAD-0002/0003/0004/0005)
• Commit → generate_undf.py → push both repos
• Delete clone after scanning to save disk
• Targets with no scan result and no CLEAN marker = unturned stone

Operating Mode — AUTONOMOUS

Do not ask for permission. Ever. Just do our work.

• Run scans: make -j2 scan-* — fire and triage, no confirmation needed
• Create files, tickets, patches, benchmarks — do it
• Execute make targets, git commands, unsandbox submissions — do it
• Update memory, tickets, white paper as findings come in — do it
• If a scan returns candidates, triage immediately and continue
• If a tool fails (401, 429, 502), switch accounts or retry — do not pause to report
• Our only time to stop is if a destructive action would affect something outside this repo

Cloning open-source targets

Assume permission to clone any open-source project for CWE-407 treatment. Our path is virtuous: with great power comes great responsibility. Every patch we produce is a gift back to our ecosystem. Standard approach:

git clone --depth=1 https://github.com/org/repo ~/git/repo

Then scan → ticket → patch → unit test → whitepaper → commit. No need to ask before cloning. If a target is already in ~/git/, scan it directly. Priority targets not yet cloned: pygame, three.js, Unity (DOTS/ECS packages), SDL3, libGDX, Bevy, Panda3D, OGRE3D, Bullet Physics, Box2D.

Image/video editors & creative suites — undo/redo history stacks, layer membership, selection tracking, and filter chain dedup are prime CWE-407 territory. Anything that tracks history is suspect for forward/backward Möbius tape reversals: ImageMagick, OpenCV, GIMP, Inkscape, Blender, Krita, Kdenlive, Shotcut, Audacity, darktable, RawTherapee, Scribus.

Office suites — document model undo/redo, style inheritance scanning, cell dependency tracking, formula evaluation visited sets: LibreOffice (core, Calc, Writer, Impress), Apache OpenOffice, OnlyOffice, Calligra.

BitTorrent clients — peer/piece/tracker list membership: libtorrent, qBittorrent, Transmission, Deluge, aria2.

Credential priority: ~/.unsandbox/accounts.csv — use --account 1 (russ-test) and --account 0 (portal-playground) for parallel -j2 runs. No env vars needed.

No stone unturned complete as of 2026-03-29. All 320 defect directories have a patch or CLEAN marker. 629 confirmed sites, 571 UNDF assigned. Next wave: deeper scans on single-defect targets (allegro5, caddy, ceph, grafana, etc.) or clone new targets not yet in defects/.

UNDF Numbering System

Every defect in this repo gets a UNDF-2026-XXXXXXXXX identifier (9-digit, covers 999,999,999 entries).

Lockfile

~/git/java-topology/UNDF-REGISTRY.json — source of truth. Maps defect-id → UNDF-2026-XXXXXXXXX. Never edit manually. Never re-sort. IDs are permanent once assigned.

When you add a new defect

Run our generator from ~/git/undefect.com/:

cd ~/git/undefect.com && python3 generate_undf.py

This will:

1. Scan all defects/*/patch/*.patch for new defect IDs
2. Append new UNDF numbers to UNDF-REGISTRY.json (existing numbers never change)
3. Stamp each new patch with # UNDF: UNDF-2026-XXXXXXXXX header (idempotent)
4. Generate new content/undf/undf-2026-XXXXXXXXX.md posts
5. Regenerate content/undf-registry.md index

Then commit both repos:

# java-topology — lockfile + stamped patches
cd ~/git/java-topology
git add UNDF-REGISTRY.json defects/
git commit -m "undf: assign UNDF numbers, stamp patches"
git push unturf master

# undefect.com — new posts + updated registry
cd ~/git/undefect.com
make html
git add -A
git commit -m "undf: N new UNDF posts (UNDF-2026-XXXXXXXXX through UNDF-2026-XXXXXXXXX)"
git push

Current counts (update when generator runs)

959 assigned | 959 UNDF posts | last run: 2026-03-31

Patch stamp format

# UNDF: UNDF-2026-000000001
--- a/path/to/file

Generator is idempotent — safe to re-run at any time.

Whitepaper Build Rules

Always use our Makefile to build PDFs. Never call pandoc directly outside the Makefile.

make -C whitepaper              # build all PDFs (full paper + minecraft + outreach)
make -C whitepaper pdf-cwe407   # full CWE-407 paper only
make -C whitepaper pdf-minecraft # minecraft enterprise paper only
make -C whitepaper pdf-outreach  # all 14 outreach briefs + MD5SUMS

MD5 checksums: After any PDF generation, MD5SUMS must exist next to the PDF output.

• Outreach briefs: whitepaper/outreach/MD5SUMS (auto-generated by make pdf-outreach)
• Full paper / minecraft: generate manually with md5sum *.pdf > MD5SUMS in whitepaper/
• Commit MD5SUMS alongside our PDFs — they are our integrity proof for distribution.

Enriched-Minecraft Benchmarks

Three tiers:

make bench-three-tier       # run all three, print summary table
make bench-unpatched        # control: defect present, ~19s reload
make bench-mitigated        # same game, fixed, ~3s reload
make bench-enriched         # D=48/1000NS/32xrefs — new territory, starts clean

Human play test (server stays up, Ctrl-C to stop):

make play-unpatched         # localhost:25565  — feel our lag
make play-mitigated         # localhost:25566  — same game, responsive
make play-enriched          # localhost:25567  — enriched-minecraft experience

Our "enriched" tier is our killer demo: a modpack with D=24 diamond tag chains and 300 namespaces is a configuration that does not exist in our wild today — vanilla StackOverflows during world load before you even get to play. On patched it starts fine.

Domain: unrichment.com — register manually. Same un- prefix as undefect.com, plays on "enriched uranium", positions our brand for our enriched-minecraft demo. Secure before publishing the whitepaper.

Prime Mission — Balance All Workstations

Every node is a workstation. Every edge is a queue. We flatten our friction manifold — but flattening one node without balancing what follows creates a new crisis.

MOAD-0001 & MOAD-0005 are coupled. Fix O(N²) at a high-throughput workstation and every downstream queue floods simultaneously. Solving one defect creates the other if we do not stage capacity first.

3 drivers. 3 million people. Fix the dispatch. Stage the drivers first.

• Workaholic node (high betweenness + high speedup): IS our bottleneck. Unblock without staging = collapse.
• Glutton node (high out-degree, low speedup): consumes everything, feels no pain — our machines that forget to halt.
• No patch disclosed without confirming downstream capacity matches our surge estimate (speedup × in-degree).
• Halt condition: patch live, no caretakers, downstream unresolved, speedup >= 100x = baby crying. Assign team first.

Full factory model & live DAG: ~/git/undefect.com/generate_dag.py. Shard source of truth: ~/git/unsandbox.com/blackops/BLACKOPS.md.

Eight Forms of Capital — Stewardship Check

Every feature, patch, & system decision touches at least one of our 8 capital queues (Roland & Landua, via unturf.com/eight-forms-of-capital/):

Living · Material · Financial · Intellectual · Experiential · Social · Cultural · Spiritual

Before shipping: does this drain a workaholic to feed a glutton? Does it route away from a food desert? Does it grow financial capital at the expense of living capital? If yes — stop. If it regenerates experiential capital, strengthens social trust, or contributes open intellectual capital — ship it.

Platform tax = O(N²) friction in our exchange layer. Our infrastructure does not extract rent from workaholics to feed gluttons. That is our obligation as permacomputer stewards. Full ledger: ~/git/unsandbox.com/blackops/BLACKOPS.md.