# XOR in Malbolge

An interactive explanation of GPT-6 Astra's 2,028-byte solution to `L2.X2048.xor-1-len2048`: read one input byte, output that byte XOR 81, then halt. Designed for readers with a CS background who have not learned Malbolge.

## Run locally

No install or build step is needed. From this directory:

```sh
python3 -m http.server 8784 --bind 127.0.0.1
```

Open <http://127.0.0.1:8784/>. A web server is required for JavaScript modules. `?input=65` opens a particular byte. The app has no external JavaScript, fonts, telemetry, network execution service, or runtime dependencies.

Use **Step** to advance through the guided explanation. **Every instruction** exposes every pointer operation and padding instruction. **Run** plays the current mode, **Back** replays earlier state, the slider seeks to an exact instruction, and **To end** reaches output and halt. The arithmetic grid jumps to individual calculations. Click a source character to inspect it; arrow keys move within the source. Outside interactive controls, left/right arrow keys step and space toggles playback.

**Original** displays the exact source file. **Live memory** displays current values in the source region; non-printable words appear as a dot, with exact decimal and ternary values in the inspector. The highlighted character is the instruction just executed. Register arrows show the state before and after the displayed instruction or group. The data window keeps its original ASCII characters above current numeric values.

The crazy-operation panel exposes all ten independent digit lookups. Click a digit column to highlight its row and column in the operator table. Rotation highlights the last digit becoming the first. The result panel separates the XOR specification from the byte actually emitted by OUT. **Run all 256 inputs** independently executes every possible input in the browser. Trace export contains the complete factual VM execution, along with the current viewing cursor.

## Source and semantics

- `gpt-6-astra.mal`: original submitted source, 2,028 bytes.
- SHA-256: `cb28ec05a4d9d8780273ed79eb49a6be4b9fcd7427e68578e5758f860a4a4015`.
- `program.mjs`: a byte-identical JavaScript string plus the fixed enciphering table.
- `vm.mjs`: full interpreter ported from the `classic_malbolge` Rust crate in `oklo/malbolge-rungs`, profile `classic-malbolge-51-v0`.
- `app.mjs`: trace presentation and instructional explanations.
- `tests/native-reference.jsonl`: the original Rust interpreter's single-byte verification records for all 256 inputs, copied from `research/astra-xor2048-2026-09-06/single-byte-input-verification.jsonl`.

Every run executes source loading, 59,049-cell initialization, bootstrap, input preparation, all NOPs and pointer routing, arithmetic, instruction enciphering, output and halt. The displayed 55 guided steps partition the 1,148 actual instructions. Grouping affects presentation only. Each trace event records before/after registers, the fetched character, decoded operation, operand, memory writes and the seven-cell window. Rewinding reconstructs memory by replaying the original writes from fresh initial memory.

Important profile details: crazy-table rows are data digits, columns are A digits; words use ten trits including leading zeros; memory filling uses the previous cell as A and the second previous cell as data; JUMP changes C before enciphering; HALT does not encipher or increment pointers. The machine itself contains no host-language XOR shortcut; XOR is used by the UI solely for expected results and verification.

The guided prose explains the fixed solution, not arbitrary programs. The page executes this frozen source; it is not a general-purpose source editor. Each byte starts a fresh VM, so overlapping data windows share initial source characters but not mutations across runs. The app explains execution; it does not reproduce the offline optimization that constructed the data table.

## Verification

```sh
node --test tests/vm.test.mjs
```

The tests compare every output, halt status, and instruction count with the independent Rust receipts, verify the source hash, check the data-pointer positions and arithmetic schedule for every input, and exercise source validation, argument ordering, padding, JUMP enciphering, HALT, rewind, and guided partitioning.

For browser checks, provide Playwright and its Chromium executable if not installed on the usual paths:

```sh
MALBOLGE_PLAYWRIGHT=/path/to/playwright/index.mjs \
MALBOLGE_CHROMIUM=/path/to/chrome-headless-shell \
node tests/browser.test.mjs
```

These checks cover guided/exact stepping, source selection, ternary lookup, backward replay, input validation, playback and pause, all-input verification, trace download, and layouts at 390, 768, 1024 and 1440 pixels. Screenshots are saved under `tests/screenshots/` for review.

## Site integration

Production destination: [XOR in Malbolge](https://oklo.org/malbolge-xor/), with a masthead link to the [Malbolge board](https://oklo.org/malbolge/).

This self-contained directory is maintained locally inside the oklo theme at `apps/malbolge-xor/` and deployed as a standalone app to `public_html/malbolge-xor/`. Only the six runtime files (`index.html`, `style.css`, `app.mjs`, `vm.mjs`, `program.mjs`, `gpt-6-astra.mal`), this README, and the scoped `.htaccess` are needed to host it. The latter declares the JavaScript MIME type for `.mjs` modules. No existing theme files or leaderboard files are included in this deployment.