docs(proposals): P-026 — resource state machines & stale-async-write detection

[PhysShell]

Что и зачем

Оформляет разбор чужого поста про useEffect в отдельный пропозал P-026: из критики вытащены две идеи, которые реально обобщаются за пределы React — состояние ресурса как явный enum вместо boolean/nullable-каши, и защита от stale-write в async-методах (читаем значение до await, пишем после, без cancellation/version-check). Добавлен только новый draft-документ + две строки в индексах (docs/proposals/README.md, docs/ROADMAP.md), кода/чекеров это не меняет.

Тип изменения

• docs — документация

Как проверено

• README/docs обновлены — новые ссылки на P-026 перепроверены вручную (файлы существуют, якоря корректны)
• python tests/run_tests.py — не запускался, изменения не затрагивают код
• ruff check . и mypy — не применимо, изменения только в .md

Связанные issue

Нет связанных issue.

Чеклист

• изменение покрыто тестом/селфтестом (или объяснено, почему нет) — чисто документационный пропозал, тестов не требует
• README/docs обновлены при необходимости — docs/proposals/README.md и docs/ROADMAP.md проиндексированы
• коммиты в conventional-commit стиле (feat:, fix:, docs: …)

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new proposal entry for resource state machines and stale async-write detection.
  • Expanded the priorities/index tables to include the new P-026 draft.
  • Introduced a new design proposal describing async resource lifecycle diagnostics and related open questions.

[coderabbitai]

Warning

Review limit reached

@PhysShell, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 56 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ed878d74-2d07-4e3e-98c0-95934e01021a

📥 Commits

Reviewing files that changed from the base of the PR and between 3f82fe7 and 809c902.

📒 Files selected for processing (1)

• docs/proposals/P-026-resource-state-machine.md

📝 Walkthrough

Walkthrough

This change adds a new draft design proposal document, P-026 ("Resource state machines & stale-async-write detection"), defining diagnostics ASYNC050, ASYNC051, and ASYNC052. It also adds corresponding index entries in the roadmap and proposals README.

Changes

P-026 Proposal Documentation

Layer / File(s)	Summary
P-026 proposal content docs/proposals/P-026-resource-state-machine.md	New proposal document covering motivation, scope boundaries, ASYNC050 (boolean/nullable state soup), ASYNC051 (no in-flight guard), ASYNC052 (no staleness check), an implementation sketch with a Roslyn/Python fact-flow pipeline and JSON shape, and open questions.
Roadmap and proposals index entries docs/ROADMAP.md, docs/proposals/README.md	Adds P-026 links to the ROADMAP Priorities and Proposal index tables, and a corresponding row in the proposals README index.

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

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the new P-026 proposal and its focus on resource state machines and stale-async-write detection.
Description check	✅ Passed	The description follows the required sections and fills them with relevant details, including change type, verification, related issues, and checklist.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/own-effects-state-machine-yivuv3

---

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]

🧹 Nitpick comments (1)

docs/proposals/P-026-resource-state-machine.md (1)

204-231: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Separate the type-level state-soup fact from the method-level hazards.

ASYNC050 is type-scoped, while ASYNC051/ASYNC052 are per-method. Keeping them under one async_methods family makes the extractor contract harder to reason about.

🤖 Prompt for 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.

In `@docs/proposals/P-026-resource-state-machine.md` around lines 204 - 231,
Separate the type-scoped state-soup signal from the per-method hazard data in
the P-021/P-026 proposal. Update the `async_methods` fact shape in
`ownlang/async_rules.py` so `ASYNC050` consumes its own type-level fact for
`sibling_status_fields`, while `ASYNC051` and `ASYNC052` remain under the
method-level hazards for each async method entry. Keep the
`CustomerViewModel.LoadCustomerAsync` example aligned with that split so the
extractor contract is clear and not mixed into one family.

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

Nitpick comments:
In `@docs/proposals/P-026-resource-state-machine.md`:
- Around line 204-231: Separate the type-scoped state-soup signal from the
per-method hazard data in the P-021/P-026 proposal. Update the `async_methods`
fact shape in `ownlang/async_rules.py` so `ASYNC050` consumes its own type-level
fact for `sibling_status_fields`, while `ASYNC051` and `ASYNC052` remain under
the method-level hazards for each async method entry. Keep the
`CustomerViewModel.LoadCustomerAsync` example aligned with that split so the
extractor contract is clear and not mixed into one family.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f6d1cfbe-5248-4660-852e-287237c847ef

📥 Commits

Reviewing files that changed from the base of the PR and between 5ea68da and 3f82fe7.

📒 Files selected for processing (3)

• docs/ROADMAP.md
• docs/proposals/P-026-resource-state-machine.md
• docs/proposals/README.md

[PhysShell]

Консолидировано в #190 (перенумеровано P-026 → P-027-resource-state-machine из-за коллизии семи параллельных P-026; ссылки на P-021 скорректированы). Закрываю в пользу единого PR.

---

Generated by Claude Code