morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #2386] [CLOSED] feat(skill): inspect PlayStation discs and preserve boot provenance #5198

New issue

Closed

opened 2026-10-31 01:04:44 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:04:44 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2386
Author: @Bobtoshi
Created: 10/12/2026
Status: ❌ Closed

Base: main ← Head: codex/ps1-disc-inspection

📝 Commits (3)

3f7db1f feat(skill): inspect PlayStation discs and preserve boot provenance
2b03e58 fix(skill): reject oversized PS1 inputs before hashing
105c254 fix(skill): merge main and preserve PS1 boot identities

📊 Changes

9 files changed (+1122 additions, -4 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+5 -1)
➕ .agents/skills/reverse-engineer-anything/references/playstation-discs.md (+99 -0)
➕ .agents/skills/reverse-engineer-anything/scripts/ps1_inspect.py (+516 -0)
📝 .github/workflows/ci.yml (+1 -1)
📝 docs/testing.md (+1 -1)
📝 package.json (+1 -1)
📝 src/application/SetupSkill.ts (+2 -0)
📝 tests/boundary/filesystem/setupSkill.test.ts (+62 -0)
➕ tests/fixtures/ps1/test_inspector.py (+435 -0)

📄 Description

Summary

Identify the boot executable inside a local PlayStation disc before handing it to a PS-X-aware analysis provider. REA's existing skill currently routes disc containers toward generic native/archive analysis without understanding raw sectors or CUE indexes. This adds a local Python standard-library helper to the existing managed skill, preserving the complete boot file and its byte-to-sector provenance.

This draft proposes a static disc-intake workflow for maintainer review. It complements morluto/rea#1948; it does not implement or depend on that pending loader. No separate MCP tool, provider, emulator or game download is added.

Problem and expected behavior

A MODE2/2352 track contains sector headers and trailers, and CUE INDEX 01 may follow a stored pregap. The boot executable's file bytes cannot be read as one contiguous raw-track span. The helper selects the declared data track, walks supported ISO9660 extents, resolves SYSTEM.CNF (or PSX.EXE fallback), and binds each boot byte to the hashed original track. Initial PC and payload load address remain distinct.

Change and scope

Add a discoverable PS1 route and supporting guide to the authored REA skill.
Bundle the helper through the existing skill generator and register both new files with managed setup, stale-file detection, repair and uninstall.
Inspect CUE/BIN, cooked ISO, Mode1 and Mode2 Form1, or a standalone complete PS-X EXE. Preserve full boot bytes only at an explicitly selected new output path.
Keep boot facts and coverage inline by default; retain the full directory inventory with --out, or select complete stdout with --full.
Reuse REA's archive workflow for ZIP input; omit the standalone plugin's archive implementation and gameplay/recompilation plans.
Bind CUE identity before parsing, reject changed sources and out-of-volume root extents, and use a set for duplicate-path detection.

Contract and boundary impact

Semantic owner: the bundled helper owns disc layout and header declarations; the selected REA provider retains executable admission and analysis ownership.
CLI/MCP: no REA command, tool or schema changes. The helper has its own explicit Python invocation and inspection JSON, not a REA Evidence envelope.
Provider compatibility: PS-X executable handoff is conditional on actual advertised support; unsupported installed releases remain explicit. No raw-MIPS admission changes.
Provenance: complete source hashes/identity, CUE indexes, ISO extents, separate load/PC fields, boot hashes and physical-sector mapping. Subsequent provider Evidence must be retained separately.
Effects: local reads and explicitly requested new report/boot files; existing paths are refused. Files publish independently, so a later output failure may leave an earlier completed file. No network, engine startup, target-code execution or target mutation.
Packaging: optional Python 3.10+ at invocation; no Python installation or new runtime dependency. Managed skill version advances 40 to 41; package version is unchanged. Authored/generated sources and the managed file inventory remain aligned.

Evidence and regression coverage

23 Python PS1 cases cover synthetic sector layouts, stored pregap, nested boot paths, complete boot preservation and every-byte source mapping, source mutation, malformed/truncated structures, duplicate/version-ambiguous paths, invalid signatures, summary/full output and no overwrite. The installed-helper test invokes a generated skill from another working directory, verifies extracted-file identity, removes the helper, and exercises repair. Existing transaction and client lifecycle cases cover installation/removal behavior.

Fixtures are source-owned generated data. A separate local nominated disc inspection matched the preserved source and boot hashes; no disc, BIOS, game-derived listing or save data is included in this contribution.

Validation performed

macOS arm64; Node 24.18.0/npm 11.16.0. Tested integration base: af29247a.

npm run test:python: 32 passed (23 PS1, 9 existing LLDB producer cases).
npm run test:focused -- tests/boundary/filesystem/setupSkill.test.ts tests/boundary/filesystem/clientLifecycle.test.ts: 62 passed.
npm run check: passed, including typecheck, lint, formatting, metadata and ownership/architecture checks.
npm run docs:check: passed.
npm run verify:test-discovery: all test files discovered once.
Skill frontmatter validation: passed.
npm run verify:package: passed, including repository-root Skills installation, npm packaging, managed setup/uninstall, CLI and MCP checks, and verifier cleanup.
npm pack --dry-run: passed.
git diff --check: passed.

Performance and unavailable coverage

For the same warm-cache local boot-discovery task retaining a complete 1,340-entry report, the standalone prototype printed 213,263 stdout bytes; the integrated helper printed about 3,047 bytes with a full local report still retained. A tokenx 1.3.0 heuristic estimated about 44,830 versus 766 output tokens; these are not billing-token measurements. Single-process macOS time measurements were approximately 0.40 versus 0.28 seconds wall time, 0.38 versus 0.28 seconds CPU, and 29.6 versus 27.5 MiB peak RSS. These single warm-cache observations are not a general speed guarantee. Cold cache, exact model token usage and other hosts remain unmeasured.

Compatibility, safety, and release

No existing command migration. This is a skill/helper integration, not proof that installed REA releases can analyze PS-X executables. No real Ghidra/IDA/Hopper execution, PS1 runtime equivalence or physical-device validation was performed for this contribution. Sector EDC/ECC, complete XA/CDDA integrity, multi-data-track/mixed-stride CUE files, UDF/Joliet, multi-extent files and CHD/PBP/ECM remain outside coverage. Resource budgets and partial output publication are documented. Copyright/license attribution from the MIT local prototype is retained in the helper.

Review checklist

One static disc-intake outcome, complementary to the pending executable loader.
Source identity, omissions, warnings and unsupported boundaries remain explicit.
Relevant parser, installed consumer, lifecycle, documentation and package checks performed.
No private binaries, generated game artifacts, credentials or unrelated cleanup in the diff.
Maintainer acceptance of this skill/helper distribution scope.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2386 **Author:** [@Bobtoshi](https://github.com/Bobtoshi) **Created:** 10/12/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `codex/ps1-disc-inspection` --- ### 📝 Commits (3) - [`3f7db1f`](https://github.com/morluto/rea/commit/3f7db1fa4755c670ca6add909377ade73e57079f) feat(skill): inspect PlayStation discs and preserve boot provenance - [`2b03e58`](https://github.com/morluto/rea/commit/2b03e58a04f3122b3339d60290951090b3329a20) fix(skill): reject oversized PS1 inputs before hashing - [`105c254`](https://github.com/morluto/rea/commit/105c25422d902c415d1c6bef1e45684c592ef2d5) fix(skill): merge main and preserve PS1 boot identities ### 📊 Changes **9 files changed** (+1122 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+5 -1) ➕ `.agents/skills/reverse-engineer-anything/references/playstation-discs.md` (+99 -0) ➕ `.agents/skills/reverse-engineer-anything/scripts/ps1_inspect.py` (+516 -0) 📝 `.github/workflows/ci.yml` (+1 -1) 📝 `docs/testing.md` (+1 -1) 📝 `package.json` (+1 -1) 📝 `src/application/SetupSkill.ts` (+2 -0) 📝 `tests/boundary/filesystem/setupSkill.test.ts` (+62 -0) ➕ `tests/fixtures/ps1/test_inspector.py` (+435 -0) </details> ### 📄 Description ## Summary Identify the boot executable inside a local PlayStation disc before handing it to a PS-X-aware analysis provider. REA's existing skill currently routes disc containers toward generic native/archive analysis without understanding raw sectors or CUE indexes. This adds a local Python standard-library helper to the existing managed skill, preserving the complete boot file and its byte-to-sector provenance. This draft proposes a static disc-intake workflow for maintainer review. It complements morluto/rea#1948; it does not implement or depend on that pending loader. No separate MCP tool, provider, emulator or game download is added. ## Problem and expected behavior A MODE2/2352 track contains sector headers and trailers, and CUE INDEX 01 may follow a stored pregap. The boot executable's file bytes cannot be read as one contiguous raw-track span. The helper selects the declared data track, walks supported ISO9660 extents, resolves SYSTEM.CNF (or PSX.EXE fallback), and binds each boot byte to the hashed original track. Initial PC and payload load address remain distinct. ## Change and scope - Add a discoverable PS1 route and supporting guide to the authored REA skill. - Bundle the helper through the existing skill generator and register both new files with managed setup, stale-file detection, repair and uninstall. - Inspect CUE/BIN, cooked ISO, Mode1 and Mode2 Form1, or a standalone complete PS-X EXE. Preserve full boot bytes only at an explicitly selected new output path. - Keep boot facts and coverage inline by default; retain the full directory inventory with `--out`, or select complete stdout with `--full`. - Reuse REA's archive workflow for ZIP input; omit the standalone plugin's archive implementation and gameplay/recompilation plans. - Bind CUE identity before parsing, reject changed sources and out-of-volume root extents, and use a set for duplicate-path detection. ## Contract and boundary impact - Semantic owner: the bundled helper owns disc layout and header declarations; the selected REA provider retains executable admission and analysis ownership. - CLI/MCP: no REA command, tool or schema changes. The helper has its own explicit Python invocation and inspection JSON, not a REA Evidence envelope. - Provider compatibility: PS-X executable handoff is conditional on actual advertised support; unsupported installed releases remain explicit. No raw-MIPS admission changes. - Provenance: complete source hashes/identity, CUE indexes, ISO extents, separate load/PC fields, boot hashes and physical-sector mapping. Subsequent provider Evidence must be retained separately. - Effects: local reads and explicitly requested new report/boot files; existing paths are refused. Files publish independently, so a later output failure may leave an earlier completed file. No network, engine startup, target-code execution or target mutation. - Packaging: optional Python 3.10+ at invocation; no Python installation or new runtime dependency. Managed skill version advances 40 to 41; package version is unchanged. Authored/generated sources and the managed file inventory remain aligned. ## Evidence and regression coverage 23 Python PS1 cases cover synthetic sector layouts, stored pregap, nested boot paths, complete boot preservation and every-byte source mapping, source mutation, malformed/truncated structures, duplicate/version-ambiguous paths, invalid signatures, summary/full output and no overwrite. The installed-helper test invokes a generated skill from another working directory, verifies extracted-file identity, removes the helper, and exercises repair. Existing transaction and client lifecycle cases cover installation/removal behavior. Fixtures are source-owned generated data. A separate local nominated disc inspection matched the preserved source and boot hashes; no disc, BIOS, game-derived listing or save data is included in this contribution. ## Validation performed macOS arm64; Node 24.18.0/npm 11.16.0. Tested integration base: `af29247a`. - `npm run test:python`: 32 passed (23 PS1, 9 existing LLDB producer cases). - `npm run test:focused -- tests/boundary/filesystem/setupSkill.test.ts tests/boundary/filesystem/clientLifecycle.test.ts`: 62 passed. - `npm run check`: passed, including typecheck, lint, formatting, metadata and ownership/architecture checks. - `npm run docs:check`: passed. - `npm run verify:test-discovery`: all test files discovered once. - Skill frontmatter validation: passed. - `npm run verify:package`: passed, including repository-root Skills installation, npm packaging, managed setup/uninstall, CLI and MCP checks, and verifier cleanup. - `npm pack --dry-run`: passed. - `git diff --check`: passed. ## Performance and unavailable coverage For the same warm-cache local boot-discovery task retaining a complete 1,340-entry report, the standalone prototype printed 213,263 stdout bytes; the integrated helper printed about 3,047 bytes with a full local report still retained. A tokenx 1.3.0 heuristic estimated about 44,830 versus 766 output tokens; these are not billing-token measurements. Single-process macOS time measurements were approximately 0.40 versus 0.28 seconds wall time, 0.38 versus 0.28 seconds CPU, and 29.6 versus 27.5 MiB peak RSS. These single warm-cache observations are not a general speed guarantee. Cold cache, exact model token usage and other hosts remain unmeasured. ## Compatibility, safety, and release No existing command migration. This is a skill/helper integration, not proof that installed REA releases can analyze PS-X executables. No real Ghidra/IDA/Hopper execution, PS1 runtime equivalence or physical-device validation was performed for this contribution. Sector EDC/ECC, complete XA/CDDA integrity, multi-data-track/mixed-stride CUE files, UDF/Joliet, multi-extent files and CHD/PBP/ECM remain outside coverage. Resource budgets and partial output publication are documented. Copyright/license attribution from the MIT local prototype is retained in the helper. ## Review checklist - [x] One static disc-intake outcome, complementary to the pending executable loader. - [x] Source identity, omissions, warnings and unsupported boundaries remain explicit. - [x] Relevant parser, installed consumer, lifecycle, documentation and package checks performed. - [x] No private binaries, generated game artifacts, credentials or unrelated cleanup in the diff. - [ ] Maintainer acceptance of this skill/helper distribution scope. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:04:44 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-01 21:11:00 +00:00

[GH-ISSUE #5653] [Tracker] New issue intake by area (October 2026) #3423

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#5198

No description provided.

Rows
Columns