Remove unverified binary tools from tracking

bin/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!README.md

bin/README.md

@@ -0,0 +1,15 @@
+# Local third-party tools
+
+This directory is reserved for optional, machine-local binaries. Its contents are ignored by Git;
+only this README and `.gitignore` are repository content.
+
+The installed-data archive parity test can use `BinExtractALF.exe` here together with its matching
+`LzssCpp.dll`. These files are not required by the runtime or the asset-independent test suite, and
+their provenance and redistribution terms have not been verified. Do not commit them. The historical
+local copies audited on 2026-08-03 had these SHA-256 values:
+
+- `BinExtractALF.exe`: `46167CDF3DA1F02733CE1E7F0DA99D155E934EDE0987CA79C8927F48FEB25FE2`
+- `LzssCpp.dll`: `596B9DDB07CA5C29CEE609E846F1512654EDEC56310A90D6C2A6951BE1E39FE1`
+
+`pe-sieve32.exe` is no longer used. The failed IAT reconstruction experiment is retained in
+`docs/engine-re.md`; the Frida import-map workflow replaced it.

docs/PROJECT-STRUCTURE.md

@@ -22,7 +22,7 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
 │   └── *.exe (uninstallers), SAS0099.OGG …   other shipped files.
 │
 ├── extracted/                               ← DERIVED (game-side) — extracted ALF contents,
-│   │                                          ~3.9 GB, regenerable via age-reimpl/bin/BinExtractALF.
+│   │                                          ~3.9 GB, regenerable with a local archive extractor.
 │   └── DATA1/ … DATA5/                         DATA1 = 481 .BIN scripts (the corpus we parse)
 │                                               + AGF/BMP/WAV in the others.
 │
@@ -32,7 +32,7 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     ├── global.json                           pins the validated .NET 8 SDK feature band
     ├── .editorconfig / .gitattributes        UTF-8, indentation, text/EOL, and binary-file policy;
     │                                         tracked source and generated references use canonical LF
-    ├── .github/workflows/core-validation.yml read-only Ubuntu-hosted asset-independent core gate
+    ├── .github/workflows/core-validation.yml planned Ubuntu-hosted core gate; source-only audit pending fix
     ├── run-godot.ps1 / run-godot.cmd         tracked development launcher + Windows wrapper;
     │                                          resolves Godot/game-root from parameters, environment,
     │                                          PATH, and the conventional sibling install
@@ -60,10 +60,9 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── movie-corpus-gate/                  C# full-corpus FFmpeg decode/lifecycle acceptance tool
     │   └── probe_*.py                          format reverse-engineering probes (historical)
     │
-    ├── bin/                                  3rd-party binaries we use (not ours, not the game's)
+    ├── bin/                                  ignored home for optional machine-local tools
-    │   ├── BinExtractALF.exe                   ALF archive extractor → produces extracted/
+    │   ├── README.md / .gitignore              tracked policy; binaries never enter Git
-    │   ├── LzssCpp.dll                         its LZSS codec dependency
+    │   └── BinExtractALF.exe + LzssCpp.dll     optional local archive oracle (unverified provenance)
-    │   └── pe-sieve32.exe                      (hollowsprocess) unpacked-PE dumper — engine-RE escalation (see docs/engine-re.md)
     │
     ├── vm-map/                               VM / reverse-engineering reference artifacts
     │   ├── opcodes.toml                        ★ CANONICAL opcode reference (hand-edited: ABI + semantics
@@ -285,7 +284,8 @@ have no repository output tree and write their automatic maps below `user://diag
   and under `extracted/DATA1/`, the game-folder copy (patch v1.03) wins. `paths.scripts()` resolves
   this automatically (overrides win).
 - **`build/` and `extracted/` are disposable.** `build/` regenerates via `tools/extract_phase2.py`
-  (or `sys4load.py`); `extracted/` regenerates via `bin/BinExtractALF.exe` on the `.ALF` files.
+  (or `sys4load.py`); `extracted/` regenerates from the `.ALF` files with a separately obtained local
+  extractor. `bin/README.md` records the optional local convention; no extractor binary is tracked.
   Safe to delete and rebuild; do not hand-edit.
 - **Opcode knowledge is edited ONLY in `vm-map/opcodes.toml`** (ABI + semantics + provenance +
   `depends_on`). Run `tools/opcodes_build.py --build` to regenerate the shim (`tools/age_opcodes_himegari.py`),

docs/asset-resolution-re.md

@@ -275,7 +275,7 @@ scene-local numeric addressing mode.
    LZSS-or-raw header section, 4/8/truecolor source pixels, LZSS-or-raw pixel section, bottom-up row/stride
    conversion, and optional `ACIF` LZSS alpha plane. Port only the algorithm and attribution into
    platform-neutral .NET code; do not carry GARbro's WPF/GameRes dependencies. Kelebek's extractor and the
-   on-disk `BinExtractALF.exe` are validation references; the Kelebek repository exposes no clear license,
+   separately obtained local `BinExtractALF.exe` is a validation reference; the Kelebek repository exposes no clear license,
    so its code should not be copied without clarification. The focused `LzssDecoder` is shared with
    `Sys4AssetCatalog`; raw and compressed information/pixel/ACIF sections use the same bounded primitive.
 4. **Runtime consumers (packed-id correction complete 2026-07-21).** Script loading, textures, voice,
@@ -461,7 +461,8 @@ VFS-B passes its bounded gates in `Sys4AssetStoreTests`: the installed AAI expan
 `0x118` (expanded size at `0x110`, packed size at `0x114`) to one `APPEND01.ALF` archive and 81 80-byte
 records. All records carry selector 1 and literal `$1$` names. The full directory has stable SHA-256
 `23F0C104A45C099CEFB7D333362716EDE6F20B9EC53E4C3705A8E3A87063708E` over its ordered record fields.
-The integration gate runs `BinExtractALF.exe` into a disposable directory, compares all 81 names, validates
+The private installed-data integration gate can run a machine-local `bin/BinExtractALF.exe` into a disposable
+directory, compares all 81 names, validates
 every range and size, and byte-compares all 81 payloads. `Sys4ScriptProvider` resolves a real append script
 through `0x01xxxxxx`; direct base-name lookup deliberately does not see append records.
 

docs/engine-re.md

@@ -34,7 +34,7 @@ Related: `docs/scjump-progression.md` (the SCJUMP decoder that hit this wall), `
   → `run_analysis`.
 - **Load sanity check (AGF-decoder landmark):** at VA `0x474f23`, `CMP word ptr [ESI + 0x4], 0x4d42`
   (the `BM`/BMP-magic check) confirms the image is correctly based + decoded.
-- IAT reconstruction — **tried, DOESN'T WORK on this binary (2026-07-09):** `bin/pe-sieve32.exe /pid
+- IAT reconstruction — **tried, DOESN'T WORK on this binary (2026-07-09):** a local PE-sieve 0.4.1.1 `/pid
   <PID> /imp 3 /dmode 3 /dir build/pe-sieve` (run from **PowerShell**, not Git Bash — it mangles
   `/flags`) ran fine but the game is packed with a **zeroed IAT** resolved via `GetProcAddress` at load,
   so there is no conventional import table to rebuild. Of 363 "imports" it emitted, only ~17 are genuine
@@ -46,7 +46,8 @@ Related: `docs/scjump-progression.md` (the SCJUMP decoder that hit this wall), `
   30×, `in_main:0`, non-terminated). ⇒ **do not graft pe-sieve output** — grafting the noise would inject
   wrong import names. The game's hot APIs (`ReadFile`/`CreateFileA`/`timeGetTime`/d3d9 device methods) are
   `GetProcAddress`-resolved into private pointer tables, invisible to a static IAT scan. Report/dump left
-  at `build/pe-sieve/process_<pid>/` (disposable).
+  at `build/pe-sieve/process_<pid>/` (disposable). The executable was removed from the repository and purged
+  from reachable history on 2026-08-03; it is obsolete and is not needed to reproduce the accepted workflow.
 
   **→ The Frida import-map approach — ✅ DONE 2026-07-09 (replaced pe-sieve).** Named the
   dynamically-resolved APIs at their call sites via the LIVE process. `tools/frida/map_imports.py`

docs/platform-portability.md

@@ -53,9 +53,9 @@ claiming portable exports.
 | Filesystem semantics | Several filename and containment comparisons use `OrdinalIgnoreCase`; installed assets are conventionally uppercase | Needs validation on case-sensitive filesystems; may hide casing or containment mistakes | Add Linux/macOS tests with mixed-case synthetic roots and use filesystem-appropriate containment rules |
 | Save/profile/settings storage | `Sys4PersistencePaths` models AGE's independent `SAVEPATH` and `REGFILEPATH` resolutions. Godot replaces Himegari's related profile directory with `user://`, yielding `user://SAVE` for native S3SD/S4SD/S3RT files and thumbnails plus `user://SYS4REG.INI` for the BOM-less CP932 options file; the preserving writer changes only its nine `[sound]` keys | Save payloads and engine options are isolated together without changing either native format. Native/drop-in resolution remains available through `USEAPPDATAFOLDER` plus both SYS4INI paths. A single-root override is rejected when `SAVEPATH` is not beneath `REGFILEPATH`, preventing cross-profile guesses | Expose explicit profile/native selection through the future launcher and allow independent overrides for profiles whose two native paths are unrelated. Validate CP932 availability, replace/flush, case, permissions, and interrupted-write behavior on each export target |
 | Game-install, runtime metadata, and repository discovery | `GameRootSelection` accepts `--game-root`, then probes the executable directory and current working directory for `SYS4INI.BIN`; on Unix the frontend prefers inherited shell `PWD` because Godot may change the process directory during project startup. Godot injects the selected root into its catalog and loose-first ALF store. `Himegari.csproj` embeds generated `build/opcodes.json`, and the frontend loads that assembly resource rather than `Paths.OpcodesJson`. `Paths.cs` remains a development/test locator; its page-map use is compiled only for `TOOLS` builds | Installed game data and packaged VM metadata no longer depend on the workspace sibling layout. The Linux export passed an explicit absolute game root outside the repository and read the installed archives. Exported automatic page maps use `user://diagnostics/page-maps`; editor/development runs preserve `build/page-map-<SCENE>.jsonl` | Let the future profile launcher pass `--game-root`, and run executable-directory/CWD plus case/permission smoke gates on Linux and macOS |
-| Archive parity oracle | One integration test launches `bin/BinExtractALF.exe` | Windows-only test helper, not a shipped runtime dependency | Skip/replace on non-Windows CI; runtime ALF/AAI readers do not depend on it |
+| Archive parity oracle | One integration test can launch a machine-local `bin/BinExtractALF.exe`; the binary and matching DLL are ignored and have unverified redistribution terms | Windows-only installed-data helper, not a shipped runtime dependency | Keep it in an explicit private workspace gate; runtime ALF/AAI readers do not depend on it |
-| Native RE tools | Frida/Ghidra helpers target the original `AGE.EXE`; supporting utilities include Windows executables and Windows command conventions | Development/research only | Keep separate from export requirements; document platform prerequisites per tool |
+| Native RE tools | Frida/Ghidra helpers target the original `AGE.EXE`; PE-sieve was tried and replaced by the Frida import-map workflow | Development/research only; no native RE executable is tracked | Keep separate from export requirements; document platform prerequisites per tool |
-| Python workflow and core CI | The operating guide uses Windows `py -3.11`; `validate.py` launches child tools through `sys.executable` and has POSIX process-group cleanup plus `ps`-based leak auditing | The asset-independent core gate is platform-neutral. Tracked generated references and the engine solution/project files have canonical LF blobs. The read-only `ubuntu-24.04` workflow provisions Python 3.11 plus `global.json`'s SDK and invokes the same core driver; private corpus and Godot runtime phases stay outside hosted CI | Confirm the first hosted result after a remote is selected and the workflow is pushed; retain Windows-native GDI parity and private installed-game/runtime checks as separate trusted gates |
+| Python workflow and core CI | The operating guide uses Windows `py -3.11`; `validate.py` launches child tools through `sys.executable` and has POSIX process-group cleanup plus `ps`-based leak auditing | Tracked generated references and the engine solution/project files have canonical LF blobs. A source-only checkout found 501/590 engine cases hermetic, 89 installed-corpus/native-oracle cases still reached by `core`, and one Python bootstrap test coupled to the external corpus. The target Gitea server's known-good baseline is `ubuntu-latest`, checkout v4, setup-dotnet v4, and Gitea-specific artifact upload | Explicitly classify the 89 workspace cases and inject a synthetic opcode corpus fixture, then run the corrected core gate in Gitea. Retain Windows-native GDI parity and private installed-game/runtime checks as separate trusted gates |
 
 No authored runtime code currently calls native DirectSound, Direct3D, Vulkan, Metal, or OpenGL. Mentions of
 those APIs in `docs/engine-re.md` describe the original AGE implementation. Both the software-oracle display

docs/remake-architecture-and-roadmap.md

@@ -930,6 +930,20 @@ do not mix mechanical moves with semantic changes.
    the tracked workflow is dormant and its first hosted Linux execution remains a publication-time confirmation,
    not a condition hidden by this commit.
 
+   **Private-repository preflight and binary purge (2026-08-03):** a clean source-only checkout disproved the
+   earlier asset-independent claim: after opcode generation, 501/590 engine cases pass while 89 installed-corpus
+   or native-oracle cases fail, and `test_opcodes.py` still scans the external script corpus. The target Gitea
+   server demonstrates a working `ubuntu-latest` runner with checkout/setup-dotnet v4 and Gitea-specific artifact
+   upload. CI must explicitly separate those workspace cases and inject a synthetic opcode fixture before Actions
+   is enabled; missing private data will not be converted into green skips.
+
+   The unverified `bin/BinExtractALF.exe`, `bin/LzssCpp.dll`, and obsolete `bin/pe-sieve32.exe` are removed from
+   tracking and purged from every reachable commit before the first remote is added. A verified full bundle made
+   immediately before the rewrite is the recovery boundary. `bin/` now tracks policy only and ignores optional
+   machine-local extractor files; PE-sieve remains documented solely as a failed historical experiment. This
+   resolves the committed-binary portion of item 3, but Kelebek-derived source/data and the user-owned project
+   license choice remain unresolved for wider distribution.
+
 **Not cleanup targets:** generated `build/` output, the two intentional solution files, historical
 `docs/superpowers/` plans/specifications, and fidelity-specific complexity that is directly covered by the
 native ABI. Reorganization is successful when ownership and reproduction become clearer, not when the raw
@@ -1276,10 +1290,10 @@ layer's rendering diverges from ADV; save layout.
 ---
 
 ## 8. Immediate next step
-Continue step 5 of the **codebase consolidation** maintenance slice by making the user-owned project-license and
+Continue step 5 of the **codebase consolidation** maintenance slice by making the Linux core gate genuinely
-third-party-artifact decisions required before distribution. Resolve, replace, or exclude the unverified
+source-only: classify the installed-corpus/native-oracle engine tests as an explicit workspace suite, inject a
-BinExtractALF/LzssCpp and Kelebek-derived material before adding the canonical license, notice, and checksum/
+synthetic corpus seam into the opcode-bootstrap unit test, and align the workflow with the target Gitea server's
-provenance manifest set. Do not infer a license choice, publish/configure a remote, or remove local artifacts as
+known-good `ubuntu-latest` action baseline. Then make the user-owned project-license and Kelebek-derived-material
-part of that decision.
+decisions required before wider distribution. Do not infer a license choice or publish/configure a remote.
 Concrete playthrough blockers may still preempt this bounded maintenance work; the consolidation effort does
 not replace Phase B gameplay validation or the open cross-platform gates.

docs/tools-reference.md

@@ -35,13 +35,22 @@ by a failed preflight; rebuild each through its owning tool in this reference. R
 `--godot`, then `AGE_GODOT_CONSOLE`, then `godot4`/`godot`/`godot-mono` on `PATH`. Game-root resolution uses
 `--game-root`, then `AGE_GAME_ROOT`, then the conventional sibling install and always requires `SYS4INI.BIN`.
 
-The hosted wrapper is `.github/workflows/core-validation.yml`: a read-only `ubuntu-24.04` job provisions
+The planned hosted wrapper is `.github/workflows/core-validation.yml`. A clean source-only checkout audit on
-Python 3.11 and the SDK selected by `global.json`, then runs
+2026-08-03 found that `--level core` still runs 89 installed-corpus/native-oracle engine cases and that
-`python -X utf8 tools/validate.py --level core`. Pull requests, pushes to `main`, and manual dispatch select the
+`test_opcodes.py` bootstraps from the external script corpus. The workflow therefore remains dormant until those
-same gate; superseded branch runs are cancelled, and `build/validation/**` is retained for seven days only when
+tests are explicitly separated from the hermetic core suite; missing data must not become a successful skip.
-the job fails. It has no secrets, cache, game corpus, Godot runtime, packaging, or deployment access. Until a
+The known-good configuration on the target Gitea server uses `ubuntu-latest`, `actions/checkout@v4`,
-remote is configured and the commit is pushed, the tracked workflow is dormant and its first hosted result is
+`actions/setup-dotnet@v4`, and `christopherhx/gitea-upload-artifact@v4`. The future core workflow should match
-still pending.
+that runner/action baseline, provision Python 3.11, and keep private corpus, Godot runtime, packaging,
+deployment, and secrets outside the job.
+
+## Optional local binary tools
+
+`bin/` is an ignored machine-local tool directory, not a source or artifact distribution directory. A local
+`BinExtractALF.exe` plus its matching `LzssCpp.dll` may be used by the installed-data archive parity test and to
+regenerate `../extracted/`; neither is a runtime dependency. Their known local hashes and unverified provenance
+are recorded in `bin/README.md`. PE-sieve is obsolete and is not retained; its historical experiment remains in
+`docs/engine-re.md`.
 
 ## Container parse / disassemble