docs(muda): define accelerator error handling contract

[OlympusLedgerOrg]

Summary

• clarify that infallible builders store key accelerators without touching native backends
• define additive try_build() validation plus per-item and aggregate accelerator failure payloads
• specify platform materialization boundaries, deterministic batch ordering, atomicity, and retryable GTK initialization

Why

This is a documentation follow-up to #12. The initial ADR preserved builder compatibility but left traceability, batch behavior, and GTK recovery semantics underspecified.

Impact

Documentation and architecture only; this PR does not implement the Rust API yet. It establishes the reviewable contract for a follow-up implementation without changing existing builder signatures.

Validation

• compared the branch against the merged dev base: only ports/muda/docs/adr/0001-observable-key-accelerator-errors.md changes
• verified the standalone Muda and Tauri ADR copies are identical
• git diff --check passes in both worktrees

Summary by CodeRabbit

• New Features

  • Added try_build() validation for menu item builders without native side effects.
  • Added clear errors for invalid keyboard accelerators, including item identity and accelerator details.
  • Added deterministic batch validation that prevents partial menu creation and supports reliable retries.

• Documentation

  • Expanded guidance on accelerator validation, error handling, and GTK batch initialization behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR expands the accelerator error ADR with deferred validation, typed failures, batch atomicity, retry behavior, and try_build() requirements. It also adds package version overrides to the pnpm workspace configuration.

Changes

Accelerator error model

Layer / File(s)	Summary
Deferred validation and error contract ports/muda/docs/adr/0001-observable-key-accelerator-errors.md	Documents deferred native accelerator validation, typed single-item and batch errors, try_build(), and GTK materialization ordering.
Validation and retry requirements ports/muda/docs/adr/0001-observable-key-accelerator-errors.md	Adds rejected alternatives and validation requirements for side-effect-free checks, atomic failures, deterministic ordering, identifier assignment, and retry behavior.

Workspace dependency overrides

Layer / File(s)	Summary
Package version overrides pnpm-workspace.yaml	Adds overrides for brace-expansion, js-yaml, and sharp, while retaining the esbuild override.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: legend-master

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely matches the ADR update defining accelerator error handling behavior.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/sync-upstream-gtk4-2026-07-19

---

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.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ports/muda/docs/adr/0001-observable-key-accelerator-errors.md`:
- Around line 68-74: Clarify the prevalidation behavior for Menu, Submenu, and
GTK initialization so the aggregate failures list contains only
accelerator-related failures representable by AcceleratorBatchApplicationFailed.
Explicitly state that unrelated errors such as NotAChildOfThisMenu and
AlreadyInitialized remain direct Error returns, or describe separate handling if
the implementation provides it; keep single-item and try_build() behavior
unchanged.
- Around line 157-160: Clarify the GTK failure requirement in the ADR so that
recorded children retain their existing tree structure and ordering, while each
child’s accelerator configuration remains editable for correction before retry.
Update the surrounding test requirements to verify both unchanged
structure/order and successful configuration editing without implying child
configuration is immutable.
- Around line 84-96: Clarify the `try_build()` documentation that resolving an
auto-generated `MenuId` via `COUNTER.next()` may consume IDs when validation
rejects an item. State that “side-effect-free” applies only to native backend
state, while monotonic ID allocation remains an expected side effect.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6a86aec2-dbbc-4933-b4e6-06f1253d3d9c

📥 Commits

Reviewing files that changed from the base of the PR and between dd63399 and c0d2740.

📒 Files selected for processing (1)

• ports/muda/docs/adr/0001-observable-key-accelerator-errors.md

[OlympusLedgerOrg]

@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.