Follow-up to #48/#18: Expose structured capability evidence reason code

[AriusII]

Summary

Follow-up to #48/#18.

• expose ClientCapabilityEvidenceReasonCode, a stable typed identifier for the evidence gate that supplies EffectiveReason
• preserve the existing display text, availability projection, constructors, and ClientCapabilityAvailability layout
• document the structured reason contract and add the unshipped PublicAPI baseline
• cover every missing, faulted, malformed, and unknown priority; cross-category precedence; legacy projection; and Native AOT execution

Compatibility

This is additive in CheatEngine.Client.Runtime. EffectiveReasonCode identifies the selected gate; the gate's public state remains the structured status. EffectiveReason remains the human-readable display/diagnostic text.

Validation

• dotnet restore CheatEngine.Client.slnx --locked-mode
• dotnet build CheatEngine.Client.slnx --configuration Release --no-restore --warnaserror — 0 warnings, 0 errors
• CI-equivalent MTP project matrix — 585 passed, 0 failed, 0 skipped
• dotnet pack CheatEngine.Client.slnx --configuration Release --no-build --no-restore
• ./eng/Invoke-PackageSmoke.ps1 -PackageSource ./artifacts/packages
• ./eng/Invoke-TemplateSmoke.ps1 -PackageSource ./artifacts/packages
• Native AOT publish and probe execution (win-x64) — exit code 0
• python eng/Validate-EngineeringManifest.py and 6 validator tests

Risk

Lifetime remains the code for fully satisfied evidence because it already supplied the existing fallback reason. This PR changes no host qualification or capability availability claim; no live Cheat Engine host was run.

Summary by CodeRabbit

• New Features

  • Added stable, typed reason codes for capability evidence.
  • Reason codes identify implementation, package, host, live qualification, policy, or lifetime gates.
  • Existing reason text remains available for display and diagnostics.
  • Capability state and reason codes can be evaluated independently without parsing text or duplicating priority logic.

• Documentation

  • Documented reason-code usage and behavior for unknown, faulted, malformed, or unqualified capabilities.

• Tests

  • Added coverage for reason-code priority, capability states, stable values, and runtime validation.

[coderabbitai]

Understand this PR’s impact

Explore downstream dependencies and potential security impact with Blast Radius.

View blast radius →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 39f8f177-9dc7-4f66-9cc8-9f6c52face91

📥 Commits

Reviewing files that changed from the base of the PR and between b8000f9 and 42ec5db.

📒 Files selected for processing (2)

• libs/CheatEngine.Client.Abstractions/Runtime/ClientCapabilityEvidence.cs
• tests/CheatEngine.Client.AotProbe/Program.cs

Limit details: You’ve used all 10 included reviews currently available.

---

📝 Walkthrough

Walkthrough

Capability evidence now exposes a typed EffectiveReasonCode. Reason resolution preserves existing priority and availability behavior. Documentation, API declarations, unit tests, and the AOT probe cover the new contract.

Changes

Capability evidence reason codes

Layer / File(s)	Summary
Public reason-code contract libs/CheatEngine.Client.Abstractions/Runtime/ClientCapabilityEvidenceReasonCode.cs, libs/CheatEngine.Client.Abstractions/PublicAPI.Unshipped.txt, libs/CheatEngine.Client.Abstractions/README.md, docs/adr/0004-capability-matrix.md	Adds six stable reason-code values and documents their use with independently observed gate state.
Reason resolution implementation libs/CheatEngine.Client.Abstractions/Runtime/ClientCapabilityEvidence.cs	Adds EffectiveReasonCode, preserves existing missing, faulted, malformed, and unknown priority, and maps reason codes back to evidence gates for display text.
Priority and runtime validation tests/CheatEngine.Client.Abstractions.Tests/Runtime/ClientCapabilityEvidenceTests.cs, tests/CheatEngine.Client.AotProbe/Program.cs	Tests reason-code priority, availability mapping, legacy construction, stable enum values, and satisfied evidence behavior. The AOT probe validates the lifetime reason and availability outputs.

Priority: ⬇️ Low

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

Change: Feature

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files.	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 identifies the main change: exposing a structured capability evidence reason code. The follow-up references provide relevant context.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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