Document failure message construction and memoization table role

[Copilot]

Added detailed documentation explaining Ohm's two-phase error message construction process and the critical role of the memoization table in failure tracking.

Changes

• Added "How Failure Messages are Constructed" section to doc/api-reference.md under MatchFailure objects
  • Documents Phase 1: tracking rightmost failure position during initial match via MatchState.rightmostFailurePosition and processFailure()
  • Documents Phase 2: re-running match with positionToRecordFailures to collect specific failures at rightmost position
  • Explains memoization table entries store rightmostFailureOffset and failuresAtRightmostPosition alongside match results
  • Clarifies why storing failures in memo table is critical: without it, memoized rule applications would lose failure information, producing incomplete error messages
  • Includes concrete example showing grammar "a" "b" | "a" "c" with input "ad" producing Expected "b" or "c"
  • Notes "fluffy" failures (e.g., implicit whitespace) are filtered from final messages

The documentation addresses the specific question of why and how failure information is stored in the memory table (memoization table) and used during the second matching phase.

Original prompt

Add to the documentation a description of exactly how the failure messages are constructed. Pay particular attention to how and why the rightmost failure position is stored in the memory table, and how that is used later.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.