java-topology/CLAUDE.md

java-topology

Mission

Fox suspects a fundamental defect in the network topology mathematics used by javac (and inherited by other languages/runtimes). The hypothesis: fix the math, network topologies get faster & cheaper across the 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

Orientation

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

Operating Mode — AUTONOMOUS

Do not ask for permission. Ever. Just do the 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
• The only time to stop is if a destructive action would affect something outside this repo

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

Next targets in priority order: mysql, onos, bird, opendaylight, v8, spidermonkey, bazel, kicad, gnu-octave, varnish, nginx, apache2 — then Un.java and Un.cs --account patch.

Whitepaper Build Rules

Always use the 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 the PDFs — they are the 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 the lag
make play-mitigated         # localhost:25566  — same game, responsive
make play-enriched          # localhost:25567  — enriched-minecraft experience

The "enriched" tier is the killer demo: a modpack with D=24 diamond tag chains and 300 namespaces is a configuration that does not exist in the 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 the brand for the enriched-minecraft demo. Secure before publishing the whitepaper.