java-topology/CLAUDE.md

# 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

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

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

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

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