# OxygenBasic Patched Compiler Rebuild Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Use subagent-driven development only if the user explicitly asks for parallel agents.

**Goal:** Rebuild the OxygenBasic binaries so the merged 2026-04-15 source patches are actually present in `oxygen.dll`, `oxygen64.dll`, `co2.exe`, `co2m64.exe`, and related front ends.

**Architecture:** Work in an isolated rebuild copy, keep the assembled release folder immutable until verification passes, bootstrap the patched self-hosted compiler from the reviewed binaries, then do a second rebuild using the newly built binaries. `inc\OXFB` and FreeBASIC are used only as a bootstrap/toolchain sanity check unless the self-host route is proven impossible.

**Tech Stack:** OxygenBasic self compiler, reviewed V1 `co2.exe`/`oxygen.dll`, installed FreeBASIC 1.05.0 win32 at `F:\00_RPGM\01_FreeBasic\FreeBASIC-1.05.0-win32\fbc.exe`, PowerShell verification scripts, final ZIP packaging.

---

## Current Facts

- The complete release folder exists at `C:\Users\theog\Desktop\Oxygen Basic\Release\OxygenBasic_Complete_2026-04-15`.
- The current release binaries are carried forward from the reviewed V1 package, not rebuilt.
- FreeBASIC 1.05.0 win32 is installed and can compile/run a simple program.
- FreeBASIC 1.05.0 win64 is not suitable for the old Oxygen FreeBASIC source because it fails on pointer-to-`long` casts.
- The `FreeBASIC-1.05.0-win32-mingworg` package was unusable here because its assembler depends on missing legacy DLLs.
- `inc\OXFB\oxygen.bas` can build `inc\OXFB\oxygen.dll` with FreeBASIC 1.05.0 win32, but that source tree is older than the patched `inc\self` tree.
- The patched `inc\self` tree is the authoritative source for the 2026-04-15 features.
- Known bootstrap blockers seen with the old reviewed compiler:
  - `inc\self\pars.inc` uses `select wr` at line 1602, which the reviewed compiler does not parse for this string case.
  - `inc\self\meta.inc` uses `select w1` at lines 1226 and 1286, same bootstrap compatibility problem.
  - `inc\JsonUtil.inc` has compile problems under the reviewed compiler around `this.ParseValue(...)` and local object creation in helper functions.

## Files And Responsibilities

- Modify during rebuild work only:
  - `inc\self\pars.inc` - bootstrap-compatible parser code.
  - `inc\self\meta.inc` - bootstrap-compatible meta/preprocessor code.
  - `inc\JsonUtil.inc` - JSON API code adjusted to compile under the rebuilt compiler.
  - `tools\co2.o2bas` - 32-bit command-line compiler front end.
  - `tools\co2m64.o2bas` - 64-bit command-line compiler front end.
  - `inc\self\co2m64.o2bas` and `inc\self\co2m641.o2bas` - alternate/self 64-bit front ends.
  - `docs\release\REBUILD_NOTES_2026-04-15.md` - final rebuild evidence and decisions.
  - `docs\release\MERGE_MANIFEST_2026-04-15.md` - append rebuilt binary hashes after success.
- Build but do not directly edit unless required:
  - `inc\self\Oxygendll.o2bas` - 32-bit `oxygen.dll` build target.
  - `inc\self\Oxygen64dll.o2bas` - 64-bit `oxygen64.dll` build target.
- Preserve unless all verification passes:
  - Root `oxygen.dll`, `oxygen64.dll`, `co2.exe`, `co2m64.exe`, `oxide.exe`, `peroxide.exe`.

## Task 1: Create An Isolated Rebuild Workspace

- [ ] **Step 1: Create a clean working copy**

Run:

```powershell
$src = 'C:\Users\theog\Desktop\Oxygen Basic\Release\OxygenBasic_Complete_2026-04-15'
$work = 'C:\Users\theog\Desktop\Oxygen Basic\RebuildWork\OxygenBasic_Complete_2026-04-15_rebuild'
if (Test-Path -LiteralPath $work) { Remove-Item -LiteralPath $work -Recurse -Force }
New-Item -ItemType Directory -Force -Path (Split-Path -Parent $work) | Out-Null
Copy-Item -LiteralPath $src -Destination $work -Recurse -Force
```

Expected: `$work` exists and contains the full release tree.

- [ ] **Step 2: Snapshot original binary hashes**

Run:

```powershell
Get-FileHash -Algorithm SHA256 `
  "$work\oxygen.dll", "$work\oxygen64.dll", "$work\co2.exe", "$work\co2m64.exe", "$work\oxide.exe", "$work\peroxide.exe" |
  Format-Table Path,Hash -AutoSize
```

Expected: six hashes are printed. Save them into `docs\release\REBUILD_NOTES_2026-04-15.md`.

- [ ] **Step 3: Confirm FreeBASIC is usable**

Run:

```powershell
& 'F:\00_RPGM\01_FreeBasic\FreeBASIC-1.05.0-win32\fbc.exe' -version
```

Expected: `FreeBASIC Compiler - Version 1.05.0 ..., built for win32 (32bit)`.

## Task 2: Establish Baseline Compiler Behavior

- [ ] **Step 1: Run old reviewed compiler against the new samples**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\demos\System\CompilerFeatures_2026_04_15.o2bas
.\co2.exe -m .\demos\DataProcessing\JSONparsing.o2bas
.\co2.exe -m -g .\demos\Diagnostics\DebugMapDemo_2026_04_15.o2bas
Pop-Location
```

Expected before rebuild: language/JSON/debugmap failures or missing generated artifacts. Record exact output.

- [ ] **Step 2: Verify old simple samples still compile**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\t.o2bas
Pop-Location
```

Expected: no hang. If an executable is generated, record its path. If not, record the behavior.

## Task 3: Make The Patched Self Source Bootstrap-Compatible

- [ ] **Step 1: Build `oxygen.dll` from the patched self source and capture the first error**

Run:

```powershell
Push-Location "$work\inc\self"
..\..\co2.exe -m Oxygendll.o2bas
Pop-Location
```

Expected initial failure: old compiler stops on the first syntax it cannot parse.

- [ ] **Step 2: Replace string `select` bootstrap blockers with equivalent `if` chains**

Modify:

- `inc\self\pars.inc`
- `inc\self\meta.inc`

Pattern:

```oxygenbasic
select wr
case "property"
  ...
case "module"
  ...
end select
```

Bootstrap-compatible form:

```oxygenbasic
if wr="property"
  ...
elseif wr="module"
  ...
endif
```

Do the same for the two `select w1` blocks in `inc\self\meta.inc`.

- [ ] **Step 3: Re-run the 32-bit DLL build**

Run:

```powershell
Push-Location "$work\inc\self"
..\..\co2.exe -m Oxygendll.o2bas
Pop-Location
```

Expected: either `oxygen.dll` is produced in `inc\self`, or the next concrete compiler error is exposed.

- [ ] **Step 4: Iterate only on true bootstrap syntax blockers**

Rules:

- Keep semantics identical to the patch.
- Prefer syntactic lowering over feature removal.
- After each edit, rerun only `..\..\co2.exe -m Oxygendll.o2bas`.
- Stop after three unrelated blockers and document them before continuing.

Expected completion: `C:\Users\theog\Desktop\Oxygen Basic\RebuildWork\OxygenBasic_Complete_2026-04-15_rebuild\inc\self\oxygen.dll` exists.

## Task 4: Stage 1 Install And Rebuild `co2.exe`

- [ ] **Step 1: Copy the stage 1 DLL into the work root**

Run:

```powershell
Copy-Item -LiteralPath "$work\inc\self\oxygen.dll" -Destination "$work\oxygen.dll" -Force
```

Expected: root `oxygen.dll` hash changes.

- [ ] **Step 2: Rebuild `tools\co2.o2bas` with the stage 1 DLL**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\tools\co2.o2bas
Pop-Location
```

Expected: `co2.exe` is generated or replaced in the work root.

- [ ] **Step 3: Verify the rebuilt front end exposes `-g`**

Run:

```powershell
Push-Location $work
.\co2.exe -m
Pop-Location
```

Expected: help text contains `-g               emit debug map / line table text file`.

## Task 5: Stage 2 Self-Rebuild For Stability

- [ ] **Step 1: Rebuild `oxygen.dll` again using rebuilt `co2.exe`**

Run:

```powershell
Push-Location "$work\inc\self"
..\..\co2.exe -m Oxygendll.o2bas
Pop-Location
Copy-Item -LiteralPath "$work\inc\self\oxygen.dll" -Destination "$work\oxygen.dll" -Force
```

Expected: second-stage DLL builds without introducing new source edits.

- [ ] **Step 2: Rebuild `co2.exe` again**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\tools\co2.o2bas
Pop-Location
```

Expected: second-stage front end builds cleanly.

- [ ] **Step 3: Compare stage 1 and stage 2 behavior**

Run the sample checks from Task 8. If stage 2 regresses, keep stage 1 binaries and document why.

## Task 6: Fix `JsonUtil.inc` For The Rebuilt Compiler

- [ ] **Step 1: Compile the JSON sample and capture the exact first error**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\demos\DataProcessing\JSONparsing.o2bas
Pop-Location
```

Expected before fixes: a concrete `inc\JsonUtil.inc` error, if still present.

- [ ] **Step 2: Lower fragile method calls and local object construction**

Modify `inc\JsonUtil.inc` only as needed.

Known likely adjustments:

- Replace ambiguous `this.ParseValue(...)` calls with the local method call form accepted by the rebuilt compiler.
- Replace helper-level `new JsonDoc jd` in `JsonFormat` and `JsonValid` if it still triggers nested declaration errors.
- Remove default parameter syntax from public helper functions only if the rebuilt compiler still rejects it.

- [ ] **Step 3: Re-run the JSON sample after each edit**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\demos\DataProcessing\JSONparsing.o2bas
Pop-Location
```

Expected: sample compiles and either runs directly or produces its expected executable.

## Task 7: Rebuild 64-bit Compiler Artifacts

- [ ] **Step 1: Try the 64-bit DLL target**

Run:

```powershell
Push-Location "$work\inc\self"
..\..\co2.exe -m Oxygen64dll.o2bas
Pop-Location
```

Expected: `inc\self\oxygen64.dll` is produced, or a clear 64-bit-only failure is recorded.

- [ ] **Step 2: Install `oxygen64.dll` into the work root**

Run only if Step 1 passed:

```powershell
Copy-Item -LiteralPath "$work\inc\self\oxygen64.dll" -Destination "$work\oxygen64.dll" -Force
```

- [ ] **Step 3: Rebuild 64-bit front ends**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\tools\co2m64.o2bas
.\co2.exe -m .\inc\self\co2m64.o2bas
.\co2.exe -m .\inc\self\co2m641.o2bas
Pop-Location
```

Expected: `co2m64.exe` and any self variants build cleanly. If only the root `tools\co2m64.o2bas` target is required for release, document the status of the alternates.

## Task 8: Release Verification Matrix

- [ ] **Step 1: Verify compiler feature sample**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\demos\System\CompilerFeatures_2026_04_15.o2bas
Pop-Location
```

Expected: no compile error. The sample demonstrates `#pragma`, property, module, and interface lowering.

- [ ] **Step 2: Verify JSON sample**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\demos\DataProcessing\JSONparsing.o2bas
Pop-Location
```

Expected: no compile error and JSON output/formatting behavior is visible if the sample runs.

- [ ] **Step 3: Verify DebugMap v2 sample**

Run:

```powershell
Push-Location $work
Remove-Item .\demos\Diagnostics\DebugMapDemo_2026_04_15.dbgmap.txt -ErrorAction SilentlyContinue
.\co2.exe -m -g .\demos\Diagnostics\DebugMapDemo_2026_04_15.o2bas
Test-Path .\demos\Diagnostics\DebugMapDemo_2026_04_15.dbgmap.txt
Pop-Location
```

Expected: command succeeds and the `.dbgmap.txt` file exists with line/procedure/map data.

- [ ] **Step 4: Verify LMStudioAI sample compiles without contacting a server**

Run:

```powershell
Push-Location $work
.\co2.exe -m .\demos\System\Internet\LMStudioAI_Demo.o2bas
Pop-Location
```

Expected: compilation succeeds. Runtime API calls may be skipped unless LM Studio is running at `http://127.0.0.1:1234/v1`.

- [ ] **Step 5: Verify exported API names**

Run:

```powershell
rg -n "o2_debug|o2_debugmap|o2_stats" "$work\inc\OxygenAPI.inc" "$work\inc\self\main.inc"
```

Expected: declarations and exports for `o2_debug`, `o2_debugmap`, and extended `o2_stats` are present.

## Task 9: Promote Verified Binaries Into The Release

- [ ] **Step 1: Copy verified binaries from work root into release root**

Run only after Task 8 passes:

```powershell
$release = 'C:\Users\theog\Desktop\Oxygen Basic\Release\OxygenBasic_Complete_2026-04-15'
Copy-Item -LiteralPath "$work\oxygen.dll"   -Destination "$release\oxygen.dll"   -Force
Copy-Item -LiteralPath "$work\co2.exe"      -Destination "$release\co2.exe"      -Force
Copy-Item -LiteralPath "$work\oxygen64.dll" -Destination "$release\oxygen64.dll" -Force
Copy-Item -LiteralPath "$work\co2m64.exe"   -Destination "$release\co2m64.exe"   -Force
```

Expected: root binaries are updated only after verification.

- [ ] **Step 2: Copy source fixes into the release tree**

Copy only the files changed intentionally:

```powershell
Copy-Item -LiteralPath "$work\inc\self\pars.inc" -Destination "$release\inc\self\pars.inc" -Force
Copy-Item -LiteralPath "$work\inc\self\meta.inc" -Destination "$release\inc\self\meta.inc" -Force
Copy-Item -LiteralPath "$work\inc\JsonUtil.inc"  -Destination "$release\inc\JsonUtil.inc"  -Force
```

Expected: release source matches the verified binaries.

- [ ] **Step 3: Update release docs**

Modify:

- `docs\release\README_Complete_2026-04-15.md`
- `docs\release\CHANGELOG_2026-04-15.md`
- `docs\release\MERGE_MANIFEST_2026-04-15.md`
- `docs\release\REBUILD_NOTES_2026-04-15.md`

Required notes:

- Binaries are now rebuilt from the merged 2026-04-15 source.
- FreeBASIC 1.05.0 win32 path used for the OXFB sanity build.
- Self-hosted build stages used for final binaries.
- Any 64-bit target limitations, if present.

## Task 10: Repackage And Verify The Final ZIP

- [ ] **Step 1: Recreate the ZIP**

Run:

```powershell
$releaseRoot = 'C:\Users\theog\Desktop\Oxygen Basic\Release'
$releaseName = 'OxygenBasic_Complete_2026-04-15'
$zip = Join-Path $releaseRoot "$releaseName.zip"
Remove-Item -LiteralPath $zip -ErrorAction SilentlyContinue
Compress-Archive -LiteralPath (Join-Path $releaseRoot $releaseName) -DestinationPath $zip -Force
```

Expected: ZIP is created.

- [ ] **Step 2: Verify clean one-folder extraction**

Run:

```powershell
$verify = Join-Path $env:TEMP 'OxygenBasic_Complete_2026-04-15_zip_verify'
if (Test-Path -LiteralPath $verify) { Remove-Item -LiteralPath $verify -Recurse -Force }
Expand-Archive -LiteralPath $zip -DestinationPath $verify -Force
Get-ChildItem -LiteralPath $verify -Force | Select-Object Name,Mode
```

Expected: exactly one top-level folder named `OxygenBasic_Complete_2026-04-15`.

- [ ] **Step 3: Run final smoke tests from extracted ZIP**

Run:

```powershell
$zroot = Join-Path $verify 'OxygenBasic_Complete_2026-04-15'
Push-Location $zroot
.\co2.exe -m .\demos\System\CompilerFeatures_2026_04_15.o2bas
.\co2.exe -m .\demos\DataProcessing\JSONparsing.o2bas
.\co2.exe -m -g .\demos\Diagnostics\DebugMapDemo_2026_04_15.o2bas
Pop-Location
```

Expected: all three commands succeed; DebugMap output exists.

## Fallback Plan: Port Patches Into `inc\OXFB`

Use this only if the self-hosted route cannot be stabilized.

- [ ] Compare `inc\self` patch files against `inc\OXFB\o2*.bas` equivalents.
- [ ] Port DebugMap v2 globals and APIs from `inc\self\glob.inc` and `inc\self\main.inc` into `inc\OXFB\o2glob.bas` and `inc\OXFB\oxygen.bas`/related modules.
- [ ] Port V2 language/parser changes from `inc\self\pars.inc`, `meta.inc`, `link.inc`, `tran.inc`, and related files into the corresponding `o2*.bas` files.
- [ ] Build with:

```powershell
Push-Location "$work\inc\OXFB"
& 'F:\00_RPGM\01_FreeBasic\FreeBASIC-1.05.0-win32\fbc.exe' -dll oxygen.bas
Pop-Location
```

- [ ] Use the resulting DLL only if the same Task 8 verification matrix passes.

## Stop Conditions

- Do not replace the release root binaries until the rebuilt binaries pass Task 8.
- Do not claim the ZIP is complete until Task 10 passes from a fresh extraction.
- If the rebuild requires changing parser semantics instead of syntax compatibility, pause and document the exact risk before promoting binaries.
- If 32-bit rebuild passes and 64-bit rebuild fails, produce a documented 32-bit rebuilt release candidate rather than silently shipping mixed binaries.
