# 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

```bash
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

### Cloning open-source targets

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

```bash
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.

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

```bash
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.