Add bounty summary availability breakdown

[LikeACloud7]

Maintainer accepted live-lane reroute: this merged work is evaluated under live bounty #777 because it matches that acceptance scope; the original closed/exhausted round reference was issue 647.

Summary

Bounty #777
Source issue: #682

This PR adds a small availability-state breakdown to the lightweight bounty summary endpoint so agents can explain why raw capacity differs from effective capacity without fetching and aggregating every bounty row.

• Adds availability_state_counts to bounty_list_summary().
• Adds aggregate pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties fields.
• Preserves the existing summary fields for current clients.
• Documents the new fields in the public API examples and agent guide.
• Covers mixed open, partial pending-payout, full pending-payout, and pending-close summary rows.

Verification

• /private/tmp/mergework-venv-312/bin/python -m pytest tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py tests/test_docs_public_urls.py -q -> 71 passed, 1 existing FastAPI/Starlette deprecation warning
• /private/tmp/mergework-venv-312/bin/python -m pytest -q -> 561 passed, 1 existing FastAPI/Starlette deprecation warning
• /private/tmp/mergework-venv-312/bin/python -m ruff format --check . -> 96 files already formatted
• /private/tmp/mergework-venv-312/bin/python -m ruff check . -> All checks passed
• /private/tmp/mergework-venv-312/bin/python scripts/docs_smoke.py -> docs smoke ok
• git diff --check -> passed

Duplicate Check

• gh pr list --repo ramimbo/mergework --state open --search "682" returned no open PRs.
• https://api.mrwk.online/api/v1/bounties/95/attempts returned no active attempts.
• Related open work covers row-level attempt summaries, structured submission requirements, OpenAPI schemas, public proof URLs, and effective availability in the submission gate; this PR only aggregates existing row-level availability fields in the summary endpoint.

Out of Scope

• No payout execution, treasury mutation, proof generation, wallet, ledger, balance, reserve accounting, bridge, exchange, cash-out, price, or bounty claimability rule changes.
• No replacement for detailed /api/v1/bounties rows or per-bounty pages.

Summary by CodeRabbit

• New Features

  • Bounty summary API now includes availability-state breakdowns, pending-payout counts, and capacity-impact indicators (reduced-capacity and effectively-unavailable bounty counts) to clarify effective capacity.

• Documentation

  • API examples and agent guide updated with guidance on reading the new capacity summary fields.

• Tests

  • Test suite expanded to validate the new summary fields and their aggregated behaviors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5c1b4a81-f52a-43b5-8b25-06a7258132ea

📥 Commits

Reviewing files that changed from the base of the PR and between e7403f7 and d1bba0b.

📒 Files selected for processing (7)

• app/serializers.py
• docs/agent-guide.md
• docs/api-examples.md
• tests/test_bounty_api_routes.py
• tests/test_bounty_pages.py
• tests/test_public_routes.py
• tests/test_serializers.py

---

📝 Walkthrough

Walkthrough

The bounty list summary serializer now computes per-availability-state counts and derives metrics for pending-payout awards, reduced-capacity bounties, and effectively-unavailable bounties. Tests and API docs/agent guidance are updated to include and explain these fields.

Changes

Bounty Summary Capacity Metadata

Layer / File(s)	Summary
Serializer metric computation app/serializers.py	bounty_list_summary() iterates over bounties to count by availability_state and compute totals for pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties, extending the returned summary object with these aggregate fields.
Test coverage for new metrics tests/test_serializers.py, tests/test_bounty_api_routes.py, tests/test_bounty_pages.py, tests/test_public_routes.py	Added test_bounty_list_summary_breaks_down_availability_states and updated existing tests to assert availability_state_counts and the capacity-impact counters in various response and filter scenarios.
API documentation and guidance docs/api-examples.md, docs/agent-guide.md	The /api/v1/bounties/summary example response and agent guide now show availability_state_counts, pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties and explain how to use them to interpret effective vs raw capacity.

Possibly related issues

• Proposed work: add availability-state breakdown to bounty summary #682: Matches the change to add availability-state breakdown and derived counters to bounty_list_summary.
• Proposed work: clarify partial pending-payout availability guidance #697: Seeks clarity on partial pending-payout rows and availability-state breakdowns that this PR implements.

Possibly related PRs

• ramimbo/mergework#311: Introduced the /api/v1/bounties/summary endpoint that consumes bounty_list_summary; this PR extends the serializer output returned by that endpoint.
• ramimbo/mergework#657: Prior work on effective availability serialization that this change expands with additional aggregate counters.
• ramimbo/mergework#330: Earlier extraction of bounty_list_summary that this PR builds upon.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add bounty summary availability breakdown' clearly and concretely describes the main change: adding an availability breakdown feature to the bounty summary endpoint.
Description check	✅ Passed	The description includes a clear summary with bounty reference, explains the change scope, lists the specific fields added, documents coverage, provides comprehensive verification evidence across tests/format/docs, addresses duplicates and out-of-scope items, and follows the template structure.
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.
Mergework Public Artifact Hygiene	✅ Passed	PR adds no investment, price, cash-out, or payout claims. New docs only instruct API users to read availability fields; MRWK remains correctly described as native ledger coin.
Bounty Pr Focus	✅ Passed	PR diff matches stated scope: 7 files (+108/-1) with bounty summary aggregation; no function signatures altered; no unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f752f89f-eba0-4f03-803b-0e0303070e8c

📥 Commits

Reviewing files that changed from the base of the PR and between 6cd957c and 30ac2ea.

📒 Files selected for processing (7)

• app/serializers.py
• docs/agent-guide.md
• docs/api-examples.md
• tests/test_bounty_api_routes.py
• tests/test_bounty_pages.py
• tests/test_public_routes.py
• tests/test_serializers.py

[xyjk0511]

Reviewed current head 30ac2ea3c0c55fb09d2033eac79d6bd79b8cceaf.

The serializer/test implementation looks coherent, but I found one blocking documentation inconsistency in docs/api-examples.md: the /api/v1/bounties/summary example says "bounties_shown": 1, while availability_state_counts contains both "open": 1 and "pending_payouts_partial": 1, which sums to two displayed bounty rows. This makes the public API example internally contradictory for clients copying the response shape. The smallest fix is to remove the "open": 1 entry from that example or update the surrounding totals so every count agrees.

Evidence checked:

• inspected app/serializers.py, docs/api-examples.md, docs/agent-guide.md, and the focused serializer/API/page tests;
• confirmed the implementation test test_bounty_list_summary_breaks_down_availability_states is internally consistent for the four-row fixture;
• confirmed the docs example inconsistency is limited to the public sample payload, not the serializer computation;
• checked hosted PR state: GitHub quality/readiness/docs check passed, CodeRabbit passed, and merge state is clean.

Local verification from F:\jiedan\mergework-review-705:

• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest tests\test_serializers.py tests\test_bounty_api_routes.py tests\test_bounty_pages.py tests\test_public_routes.py tests\test_docs_public_urls.py -q -> 71 passed
• python scripts\docs_smoke.py -> docs smoke ok
• python -m ruff check app\serializers.py tests\test_serializers.py tests\test_bounty_api_routes.py tests\test_bounty_pages.py tests\test_public_routes.py -> pass
• python -m ruff format --check app\serializers.py tests\test_serializers.py tests\test_bounty_api_routes.py tests\test_bounty_pages.py tests\test_public_routes.py -> pass
• python -m compileall app\serializers.py tests\test_serializers.py tests\test_bounty_api_routes.py tests\test_bounty_pages.py tests\test_public_routes.py -> pass
• git diff --check origin/main...HEAD -> pass

Requesting changes for the docs example count mismatch above.

[Gwani-28]

Reviewed PR #705 at current head 30ac2ea3c0c55fb09d2033eac79d6bd79b8cceaf.

I did not find a blocker in this patch.

Evidence checked:

• inspected the bounty_list_summary() change in app/serializers.py;
• confirmed the new summary fields are derived from already-public row fields and do not change payout execution, treasury mutation, proof generation, wallet, ledger, bridge, exchange, cash-out, price, or claimability rules;
• checked that availability_state_counts preserves the row-provided availability_state buckets while falling back to status for older rows;
• checked that pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties explain raw-vs-effective capacity without replacing existing open_awards or effective_open_awards;
• inspected the API/page/serializer tests and docs examples covering open, partial pending payout, full pending payout, and pending-close cases;
• confirmed no #643 claim comment visibly referenced PR #705 before this review.

Validation run locally:

• .venv/bin/python -m pytest tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py tests/test_docs_public_urls.py -q -> 71 passed, 1 existing FastAPI/Starlette deprecation warning.
• .venv/bin/ruff check app/serializers.py tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py tests/test_docs_public_urls.py -> passed.
• .venv/bin/ruff format --check app/serializers.py tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py tests/test_docs_public_urls.py -> 6 files already formatted.
• .venv/bin/python scripts/docs_smoke.py -> docs smoke ok.
• git diff --check origin/main...HEAD -> clean.
• git merge-tree --write-tree origin/main HEAD -> clean tree 93dd1c6fb6a3a84f0787ad9df483f84e02a88e25.
• Hosted checks: GitHub quality/readiness/docs/image checks passed and CodeRabbit passed.

Residual risk: this is an aggregate summary endpoint change, so callers still need the detailed bounty rows when they need per-bounty explanations. That matches the PR's stated scope.

No private data, credentials, wallet material, production mutation, price/exchange/bridge/off-ramp claims, or fabricated payout claims used.

[xyjk0511]

Reviewed current head e7403f77c416b8c93c9d6740df7f02b7c1127b9e.

The earlier documentation-count blocker is resolved: the /api/v1/bounties/summary example now keeps bounties_shown, availability_state_counts, and the reduced-capacity fields internally consistent while the serializer exposes the new availability breakdown fields.

Validation I checked:

• inspected app/serializers.py, docs/api-examples.md, docs/agent-guide.md, and focused API/page/serializer tests;
• PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py -> 39 passed;
• python -m ruff check app/serializers.py tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py -> passed;
• python scripts/docs_smoke.py -> docs smoke ok;
• git diff --check origin/main...origin/pr/705 -> clean;
• git merge-tree --write-tree origin/main origin/pr/705 -> clean tree 547a547564c3695b53467a64a1174246aa882dbb;
• hosted Quality, readiness, docs, and image checks and CodeRabbit are both green.

[JONASXZB]

Reviewed current head e7403f77c416b8c93c9d6740df7f02b7c1127b9e as a non-author.

No blocker found in the bounty-summary availability breakdown. Evidence checked:

• inspected bounty_list_summary() and confirmed existing summary fields are preserved while adding availability_state_counts, pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties;
• verified the aggregation counts reduced capacity only when effective awards are below visible awards, and counts effectively unavailable bounties only when visible awards remain but effective awards are zero;
• checked /api/v1/bounties/summary, public bounties context/page tests, docs, and serializer tests for open, partial pending-payout, full pending-payout, pending-close, and empty-filter cases;
• ran MERGEWORK_DATABASE_URL=sqlite:////tmp/mergework-pr705-review-test.sqlite python -m pytest tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py tests/test_docs_public_urls.py -q -> 71 passed, 1 warning;
• ran python scripts/docs_smoke.py, targeted Ruff check/format, python -m mypy app/serializers.py, and git diff --check origin/main...HEAD;
• ran an extra local mixed-state bounty_list_summary() check covering open, pending-payouts-full, and paid rows;
• checked mergeability with git merge-tree --write-tree origin/main HEAD -> exit 0.

Hosted status for this head is green (CodeRabbit: success / Review skipped; Quality, readiness, docs, and image checks: success).

[attaboy11]

Reviewed current head d1bba0bc430533554c8f5bd0e65a96cecf67cb9a against current origin/main 05faf1f89932d59f2935e83b71fc42ffef363c7f as a non-author.

No blocker found in the bounty-summary availability breakdown. This is a focused additive API-summary change: existing raw/effective capacity fields are preserved, and the new aggregate fields explain why effective availability differs from raw open awards without requiring clients to fetch every bounty row.

Evidence checked:

• Inspected app/serializers.py and confirmed bounty_list_summary() now adds availability_state_counts, pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties while preserving existing summary fields.
• Inspected docs/tests in docs/agent-guide.md, docs/api-examples.md, tests/test_serializers.py, tests/test_bounty_api_routes.py, tests/test_bounty_pages.py, and tests/test_public_routes.py.
• GitHub reports mergeStateStatus: CLEAN; hosted Quality/readiness/docs/image check is successful.
• git merge-tree --write-tree origin/main origin/pr-705 succeeds with tree ea555d90269ba10f0647b52734f4c2688b972d1e.
• Focused tests pass: pytest tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py tests/test_docs_public_urls.py -q -> 74 passed, 1 warning in 1.67s.
• scripts/docs_smoke.py passed; targeted Ruff check and format check passed; git diff --check origin/main...origin/pr-705 passed.

No payout, wallet, treasury execution, private account, exchange, bridge, or cash-out behavior is changed here.

[JONASXZB]

APPROVE — reviewed current open head d1bba0bc430533554c8f5bd0e65a96cecf67cb9a against current origin/main f8fc36265ea763bcaabb3555d3ee4e0c885a4953 as a non-author.

Evidence checked:

• Files inspected: app/serializers.py, docs/agent-guide.md, docs/api-examples.md, tests/test_serializers.py, tests/test_bounty_api_routes.py, tests/test_bounty_pages.py, and tests/test_public_routes.py.
• The change is focused and additive: bounty summaries keep existing raw/effective capacity totals while adding availability_state_counts, pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties.
• The aggregation logic counts reduced capacity only when effective awards are below visible awards, and counts effectively unavailable rows only when visible awards remain but effective awards are zero.
• API/page/context/docs tests are updated for the expanded response shape, including empty summaries and mixed open/partial/full/close availability states.
• Focused validation passes: .venv/bin/python -m pytest tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py -q -> 41 passed, 1 warning.
• Docs smoke passes: .venv/bin/python scripts/docs_smoke.py -> docs smoke ok.
• Ruff passes for touched Python files: .venv/bin/ruff check app/serializers.py tests/test_serializers.py tests/test_bounty_api_routes.py tests/test_bounty_pages.py tests/test_public_routes.py -> all checks passed; .venv/bin/ruff format --check ... -> 5 files already formatted.
• git diff --check origin/main...HEAD clean.
• git merge-tree --write-tree origin/main HEAD clean -> 0d5da1dbb404b9c5af9cc51f604e5dc667164052.
• GitHub reports mergeable/clean; CodeRabbit status is success/review skipped; hosted quality/readiness/docs/image check is success.

No blocking issues found in the current-head bounty-summary availability breakdown.

[MyTH-zyxeon]

Current-head review for PR #705 (d1bba0bc430533554c8f5bd0e65a96cecf67cb9a):

I reviewed the updated head against the serializer, docs, and tests touched by this PR. I do not see a blocker in the current patch.

Evidence checked:

• bounty_list_summary() keeps the existing capacity totals and adds a separate availability explanation layer instead of changing the existing open_* / effective_* semantics.
• availability_state_counts is keyed from availability_state with a fallback to status, which matches the mixed row shapes already used by the public bounty serializers.
• pending_payout_awards, reduced_capacity_bounties, and effectively_unavailable_bounties are derived from the same awards_remaining / effective_awards_remaining fields that already drive effective capacity.
• The tests cover normal open rows, partial pending payout capacity, full pending payout capacity, and pending close availability.
• Docs now tell agents to explain why effective capacity is lower than raw capacity without forcing a full bounty-row fetch.
• Read-only production probes confirm the live gap remains: /api/v1/bounties/summary, /api/v1/bounties/summary?repo=ramimbo%2Fmergework&issue_number=654, and /api/v1/bounties/summary?status=open currently expose only bounties_shown, open_awards, open_pool_mrwk, effective_open_awards, and effective_open_pool_mrwk; none expose the new breakdown fields yet.

The current production numbers make the ergonomics value concrete: issue #654 currently reports open_awards=30 but effective_open_awards=23, and issue #656 reports open_awards=5 but effective_open_awards=3; this PR gives agents the missing explanation surface for those differences.

[ramimbo]

Maintainer queue pass 2026-06-02: holding this as a possible #777 candidate after that create_bounty proposal executes and GitHub finalization completes. #647 is exhausted, so this is not payable now, and #777 is not live yet. If #777 opens, retarget the PR body to Bounty #777 and keep checks/reviews current before maintainer acceptance. No accepted/paid labels now.