fix(web): constrain dialog session helpers to declared scopes

[mforce]

A misspelled dialog name passed to openDialog, dismissDialog, or startLoad previously compiled and could leave abandoned requests current. These helpers now accept the screen’s declared scope type S; run and isPending retain arbitrary string scopes for dynamic row actions.

The decision record accepts the remaining limits: unknown run names without an explicit dialog, forgotten session setup, and bypassed or semantically incorrect types. Runtime behavior is unchanged.

Driver verification on 547c9b324b2eb67df1648ce46f73235bb63cce8c:

• Typecheck, full coverage suite (119 files / 2,665 tests), production build, and service-worker verification passed.
• All 49 generated production JavaScript files are byte-identical to the base build.
• Six compiler mutations separately proved rejection of invalid helper scopes and acceptance of valid scopes; each mutation was restored and typecheck passed. The mutations ran at c16b130; the final commit changes documentation only.
• Two existing tests were adjusted to preserve their behavior under the narrower API; one compiler-contract case was added. Vitest alone does not validate its TypeScript assertions.

CI is green, including backend tests, Playwright, CodeQL, image/Trivy, and GitGuardian; these CI checks are CI-attested, not locally driver-run. CodeRabbit approved the final head, with a reported clone-backed analysis limitation. Separate Sonnet source-context review approved the same head. Its requested caller audit confirms all 11 screens infer the narrowed return type directly; the sole explicitly typed test variable preserves the scope union. Consumers must retain that union instead of assigning the return to a plain DialogAction that promises arbitrary string helpers. One complete review round; no further round required.

Completes the implementation for #703 PR6, owner-selected option B plus a decision record. Owner merge pending. Independent follow-ups #708, #709, #712, and #713 remain outside this PR.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: cc3e2486-05e4-4d41-b634-c1392a7bafdc

📥 Commits

Reviewing files that changed from the base of the PR and between f0f7492 and 547c9b3.

📒 Files selected for processing (3)

• docs/decisions/703-dialog-session-scope-types.md
• web/src/components/useDialogAction.test.ts
• web/src/components/useDialogAction.ts

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

---

📝 Walkthrough

Walkthrough

The hook now restricts openDialog, dismissDialog, and startLoad to declared dialog scopes. run retains string scopes for dynamic values. Tests and a decision record document the type contract, behavior limits, and verification steps.

Changes

Dialog scope typing

Layer / File(s)	Summary
Typed session helpers web/src/components/useDialogAction.ts	The session-edge methods and callbacks now use the generic scope type S. The documentation defines the retained string scope for run and session-0 behavior.
Scope type validation web/src/components/useDialogAction.test.ts, docs/decisions/703-dialog-session-scope-types.md	Compile-time tests accept declared scopes, reject unknown helper scopes, and preserve unrestricted run strings. The decision record documents the limits and verification commands.

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

Merge Risk: ⚪ Minimal · up to 547c9

This change narrows compile-time typing for dialog session helpers while preserving dynamic string scopes for run, with no runtime behavior change. No merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 …
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.
Title check	✅ Passed	The title is concise, uses the required conventional commit format, and clearly describes narrowing dialog session helpers to declared scopes.
Description check	✅ Passed	The description explains the problem, implementation, scope of runtime impact, residual risks, verification commands, mutation testing, tests, and related issue context. It omits the template headings…

✨ 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 feat/703-dialog-scope-types

Warning

Git: CodeRabbit could not clone the repository, so clone-backed analysis was skipped and this review may be incomplete. Verify repository clone access, such as SSH credentials, before requesting another full review. If clone access is intentionally unavailable, use path_filters to narrow the review scope.

---

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

[mforce]

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