# 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

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

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

**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/`:

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

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

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