engineering/java-topology
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
java-topology/CLAUDE.md

8.2 KiB
Raw Blame History

java-topology

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.