feat(runtime): add generic guest-memory write boundary (IGuestMemoryWriter)

[mao2009]

Summary

Adds IGuestMemoryWriter and a default GuestMemoryWriter — the write-side
mirror of the existing IGuestMemoryReader/GuestMemoryReader (PR #350).
This is Issue #359, filed as a follow-up to PR #358 (ADR-014 amendment
"B0:56 GetC0Table / B0:57 GetB0Table evaluated, not registered"), which found
that no boundary in this Runtime could write to guest memory at all.

This PR implements only the generic write boundary. It does not register
GetC0Table/GetB0Table, gets, or any other BIOS service, and does not
model the A0/B0/C0 jump-table layout — those remain gated by Issue #360
(guest-visible BIOS kernel jump-table state abstraction), which is
independently blocked on unconfirmed canonical-address evidence.

What changed

• IGuestMemoryWriter / GuestMemoryWriter (PSXRecomp.Core.Runtime):
  Try-style single-byte write, sharing Ps1AddressTranslation.TryTranslate
  (KUSEG/KSEG0/KSEG1) and the RAM-only bound (Ps1MemoryMap.RamSize) with the
  reader. The writer depends on the shared translation helper directly, not
  on the reader class, so the two boundaries stay independent.
• Deliberately unwired into BiosHleRuntime. No registered service needs
  it yet — this mirrors the precedent the guest-memory read boundary and the
  output sink both set (landed unwired, wired only once a concrete consumer
  existed).
• docs/adr/014-bios-hle-runtime-contract.md — new amendment "Runtime
  guest-memory write boundary".
• docs/runtime/bios-hle-evidence.md — support matrix, per-service table
  (gets, GetC0Table, GetB0Table rows), and open questions 6/9 updated;
  open question 10 added recording this boundary as done.
• src/PSXRecomp.Tests/Runtime/GuestMemoryWriterTests.cs — new tests.

Tests

• deterministic initialization (fresh instances over independent backing
  stores never share state)
• valid write (KUSEG) and KUSEG/KSEG0/KSEG1 alias write reaching the same
  physical byte
• invalid/unmapped address (KSEG2, out-of-RAM KUSEG, at-RAM-end) rejected
  without reaching the physical write path
• determinism across repeated writes
• round-trip through the existing IGuestMemoryReader boundary
• null-sink constructor guard

Verification

Item	Result
dotnet test src/PSXRecomp.Tests --filter FullyQualifiedName~GuestMemory	✅ 60 passed, 0 failed
dotnet test src/PSXRecomp.Tests/PSXRecomp.Tests.csproj -c Release	✅ 1450 passed, 0 failed, 14 skipped (pre-existing — real-ROM local-fixture tests needing a gitignored rom/ dir)
Native (cmake/ctest)	Not applicable — no native code touched
scripts/ci/check-artifact-policy.ps1	✅ passed, no violations
git diff --check	✅ clean
Architecture analyzer (AARC002–007)	✅ build succeeded (analyzer runs at compile time; no violations)

Self-review

• Scope: touches only the new boundary + its tests + the two docs it
  requires (ADR-014, evidence inventory). No existing service's registration
  or behavior changes (BiosHleRuntime's registry is untouched: (A0, 0x3C),
  (A0, 0x3E), (B0, 0x3F)).
• Coupling check: initially had the writer call
  GuestMemoryReader.TryTranslate (a reader-class wrapper); fixed during
  self-review to call Ps1AddressTranslation.TryTranslate directly, so the
  writer doesn't depend on the reader class for translation.
• No title-specific behavior anywhere.

Remaining work

• [Runtime/BIOS] Guest-visible BIOS kernel jump-table (A0/B0/C0) state abstraction #360 (jump-table state abstraction) stays open and blocked on unconfirmed
  canonical-address evidence — not resolved by this PR.
• Issue [Runtime] Guest-memory write boundary (IGuestMemoryWriter) #359 acceptance criteria are fully met by this PR.

Related

Closes #359. Refs #279, #360.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01TYUNZnNGEsvo97erGQUs2U

Summary by CodeRabbit

• New Features
  • Added a generic guest-memory byte-writing capability for valid RAM addresses.
  • Supports equivalent address aliases and safely rejects invalid or unmapped destinations without modifying memory.
• Documentation
  • Updated runtime support documentation and architecture records to describe the new write capability and its current availability.
  • Clarified that BIOS runtime integration and jump-table address details remain pending.
• Tests
  • Added coverage for valid writes, address aliases, invalid ranges, isolated instances, read-back verification, and invalid configuration handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 0a9f85d7-b1da-4350-9fc3-d0e60d102c3b

📥 Commits

Reviewing files that changed from the base of the PR and between 7dd4c8e and 69d7aa6.

📒 Files selected for processing (5)

• docs/adr/014-bios-hle-runtime-contract.md
• docs/runtime/bios-hle-evidence.md
• src/PSXRecomp.Core/Runtime/GuestMemoryWriter.cs
• src/PSXRecomp.Core/Runtime/IGuestMemoryWriter.cs
• src/PSXRecomp.Tests/Runtime/GuestMemoryWriterTests.cs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds IGuestMemoryWriter and GuestMemoryWriter for translated, RAM-only byte writes. Tests cover address aliases and rejected writes. ADR-014 and runtime evidence document the boundary and its deliberate absence from BiosHleRuntime.

Changes

Guest memory write boundary

Layer / File(s)	Summary
Runtime write contract and implementation src/PSXRecomp.Core/Runtime/IGuestMemoryWriter.cs, src/PSXRecomp.Core/Runtime/GuestMemoryWriter.cs, src/PSXRecomp.Tests/Runtime/GuestMemoryWriterTests.cs	Adds a domain-level Try-style write interface and an implementation that reuses PS1 address translation, writes only within RAM, rejects invalid addresses without invoking the physical write delegate, and validates constructor input. Tests cover aliases, bounds, determinism, isolation, reader round-trips, and null delegates.
Runtime contract documentation docs/adr/014-bios-hle-runtime-contract.md, docs/runtime/bios-hle-evidence.md	Documents the write boundary, its deliberate lack of BiosHleRuntime wiring, and the remaining unresolved jump-table address, format, and contents.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 69d7a

The guest-memory write boundary is bounded, tested, and intentionally remains unwired, so it does not alter existing BIOS service behavior.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 40.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 3 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding the generic runtime guest-memory write boundary.
Linked Issues check	✅ Passed	The changes satisfy issue #359. They add the try-style interface and implementation, reuse address translation, enforce RAM-only bounds, use an injected physical write delegate, reject invalid writes …
Out of Scope Changes check	✅ Passed	All changes support issue #359. The implementation, tests, ADR amendment, and runtime evidence updates are in scope. No BIOS service registration, jump-table modeling, or BiosHleRuntime wiring was add…

Full details: Docstring Coverage

Explanation

Docstring coverage is 25.00% which is insufficient. The required threshold is 40.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/runtime-guest-memory-write-359

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mao2009]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[mao2009]

CodeRabbit review result (HEAD 69d7aa6)

No actionable comments. Pre-merge checks: 4 passed, 1 warning.

Docstring Coverage warning (25.00% vs. 40% threshold) — not-an-issue,
justified. The measured 12 functions across 3 files include this PR's test
file (GuestMemoryWriterTests.cs); .coderabbit.yaml's own
code_generation.docstrings path instructions and
docs/development/documentation-policy.md explicitly exclude ordinary test
methods from the "must document" set ("Do not add restating
comments/docstrings to ordinary test methods"). Every production member this
PR adds (IGuestMemoryWriter, its method, GuestMemoryWriter, its
constructor and TryWriteByte) already carries an XML doc comment. The check
itself runs in mode: warning and is documented as never blocking merge by
itself. No documentation gap exists in the in-scope (production) surface; no
change made.

All other pre-merge checks passed: Description, Title, Linked Issues (#359),
Out of Scope Changes.