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

13 KiB
Raw Blame History

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.

Prime Mission — Patch the Planet

Patching our planet. Every open-source project our agents scan, patch, and disclose makes our shared infrastructure faster and cheaper for everyone. Our disclosures: gifts back to our ecosystem.

undefect.com ships under AGPLv3 when our patching campaign completes. Every patch, every UNDF, every disclosure — free, open intellectual capital. Inheritable by anyone, forever.

Pipeline: scan → ticket → patch → unit test → UNDF → disclose → PR → upstream merge → planet patched.

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 and 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."
  • Prefer "our" for shared things; "a" when something is one of many; avoid "the" — it implies fixed, singular ownership. Most teams and systems are fluid and ever-changing, like water.

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/.

Test Harness and Scanner — How They Improve

The scanner does not improve on its own. It improves when we do real work:

  1. Find a new hit — scan a target, find CWE-407 or other MOAD pattern
  2. Write the patch — defects/{project}/patch/{slug}.patch with # UNDF: ... header
  3. Write the tests — unit in tests/unit/, integration in tests/integration/, functional in tests/functional/
  4. Add intel — run generate_undf.py, push to undefect.com
  5. Update CLAUDE.md — if a new defect pattern or fix signature was involved, add it to tests/scan_verify.py DEFECTIVE_SIGS / FIX_SIGS so that pattern promotes from WARN to PASS on future scans

If a patch shows WARN in make scan-verify:

  • Check whether its defective pattern needs a new entry in DEFECTIVE_SIGS
  • Check whether its fix pattern needs a new entry in FIX_SIGS
  • Add the pattern, re-run, confirm it promotes to PASS
  • Commit the pattern addition alongside the new patch/test

The three feedback loops:

New hit found
  → patch written
  → tests pass
  → scan_verify.py PASS
  → UNDF post on undefect.com
  → scanner coverage grows by 1

WARN entry spotted
  → read the patch to find the unrecognized pattern
  → add pattern to DEFECTIVE_SIGS or FIX_SIGS
  → re-run make scan-verify, confirm PASS
  → scanner improves for all future patches using that pattern

NO_PATCH entry seen
  → write the missing patch for that defect dir
  → coverage-check passes for that entry
  → scanner coverage grows

Current state (2026-04-12):

  • 1258 UNDF entries in registry
  • 454 PASS, 441 WARN, 12 FAIL, 300 NO_PATCH, 51 PENDING
  • FAIL = real stub patches needing actual diff content (thunderbird 1-6, systemd-0003, etc.)
  • NO_PATCH = project dir exists, patch file not yet written
  • WARN = patch present but defective/fix pattern not in our lists yet

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.