Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(refactoring): serve composed opportunities from a materialized read model (#1992)
Raghav Chamadiya01289585356a
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 82ab6e46c..167c88f69 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -719,6 +719,8 @@ get_health(include=["trend"], only=["trend"])get_health(include=["accuracy"], only=["accuracy"])get_health(include=["coverage"], only=["coverage"])get_health(include=["performance","refactoring"], only=["performance_opportunities","refactoring_plans"])+get_health(include=["refactoring"], only=["refactoring_opportunities"], limit=6)+get_health(opportunity_id="refop2_...")```**Parameters:**@@ -727,12 +729,18 @@ get_health(include=["performance","refactoring"], only=["performance_opportuniti|-----------|------|----------|-------------|| `targets` | list[string] | No | File paths, or `module:foo` to expand a module's file set. Empty means dashboard mode. || `include` | list[string] | No | Opt-in blocks (default response stays lean): `"biomarkers"` (findings in dashboard mode), `"refactoring"` (structured, graph-aware refactoring plans; see below), `"trend"` (snapshot diff + declining / predicted-decline alerts), `"coverage"`, `"accuracy"` (the "does the score find the bugs?" stat, dashboard mode), `"signals"` (per-file process / people / topology signals, targeted mode), `"churn_complexity"` (churn x complexity quadrant points, dashboard mode), and a dimension name (`"performance"` / `"defect"` / `"maintainability"`) to filter findings to that pillar. |-| `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode`, `_meta`, `unresolved`, `known_modules` and each kept list's `*_total` sibling always survive. The three `include` **block** names work as aliases: `biomarkers`→`findings`, `accuracy`→`defect_accuracy`, `refactoring`→`refactoring_plans`. The `include` **dimension** names (`performance`, `defect`, `maintainability`) do not — they filter rows inside several blocks and have no single key to resolve to, so they land in `unknown_only_keys`. Nor does `signals`, which merges into `metrics[].signals` — in targeted mode, where `signals` applies, name `metrics` instead. |+| `only` | list[string] | No | Keep just these top-level keys. `include` adds blocks, `only` subtracts them. `mode`, `_meta`, `unresolved`, `known_modules` and each kept list's `*_total` sibling always survive. The three `include` **block** names work as aliases: `biomarkers`→`findings`, `accuracy`→`defect_accuracy`, `refactoring`→`refactoring_plans`. Note that `refactoring_plans` is the raw+per-detector list and is now **opt-in**: `include=["refactoring"]` leads with+`refactoring_opportunities`, the composed unit, and emitting both would ship two+representations of the same work in one response. The `include` **dimension** names (`performance`, `defect`, `maintainability`) do not — they filter rows inside several blocks and have no single key to resolve to, so they land in `unknown_only_keys`. Nor does `signals`, which merges into `metrics[].signals` — in targeted mode, where `signals` applies, name `metrics` instead. || `repo` | string | No | *(workspace only)* Target repo alias || `limit` | int | No | Max rows in **every** ranked list (default 20, capped at 50). `0` means no rows; the `*_total` siblings still report the true counts. || `finding_id` | string | No | Resolve an emitted stable health-finding `id` directly in one call. || `plan_id` | string | No | Resolve an emitted stable refactoring-plan `id` directly in one call. |-| `opportunity_id` | string | No | Resolve a performance opportunity `id` directly. Mutually exclusive with the two above; passing more than one returns `mode: "conflict"` naming them rather than answering about whichever was checked first. |+| `opportunity_id` | string | No | Resolve one opportunity `id` directly. The prefix picks the pillar: `perf...` is a performance cause, `refop...` a composed refactoring. Mutually exclusive with the two above; passing more than one returns `mode: "conflict"` naming them rather than answering about whichever was checked first. |+| `refactoring_type` / `refactoring_confidence` / `refactoring_effort` | string | No | Queue filters over the same read model and vocabulary the REST route uses. An unrecognized value is reported back in `ignored_arguments` rather than silently narrowing to nothing. |+| `refactoring_view` | string | No | Named ordering for `refactoring_opportunities`. `diversified` (default) round-robins the rank order over cause, refactoring type and area, because the ranked head is a genuine run of ties; `canonical` is the published rank order verbatim, ties and all; `file_spread` asked for one row per file, which a composed opportunity satisfies by construction, so it resolves onto the diversified order. Both older values keep working. It also selects the legacy `refactoring_plans` list's view, where `diversified` resolves to that list's historical `canonical` default. |+| `cursor` | int | No | Zero-based offset into a ranked collection; the `recovery` block names the exact next call. || `performance_view` | string | No | `detail` (default) or `summary`. `summary` keeps identity, counts and plan state and drops the explanatory fields. || `performance_context` | string | No | `production` / `tooling` / `test` / `unknown` / `all`. || `performance_boundary` | string | No | `db` / `network` / `filesystem` / `subprocess` / `lock` / `none`. |@@ -866,7 +874,26 @@ The opt-in enrichments:- **`churn_complexity`** returns `churn_complexity` points (one per recently-changedfile: 90-day commit count, max CCN, NLOC, score, churn percentile): therefactor zone where volatility and tangle collide.-- **`refactoring`** returns ranked, structured refactoring plans (not template+- **`refactoring`** returns `refactoring_opportunities`: one composed unit per+ file, carrying the diagnosis it leads with (`lead_biomarker`), whether it+ actually addresses that diagnosis (`addresses_primary_problem`, tri-state -+ `null` means no dominant finding was recorded, which is not `false`), its+ ordered `steps` with a `mechanical` / `judgment` `applicability` each, and+ counts for the evidence behind it. Ordered by `refactoring_view`. A step+ carrying `relocated_by` names an earlier step that moves its symbol to another+ file: locate the symbol again before applying it, because the step's own+ `file_path` and span describe where the symbol was.+ `get_health(opportunity_id="refop...")` returns the full ordered steps, the+ member plan payloads, the validation profile and structured `next_actions`;+ `only=["refactoring_evidence"]` plus `cursor` pages the evidence.+- **`refactoring_directive`** rides on a bare `get_health()`: one opportunity,+ what it addresses, and the exact `opportunity_id` call that opens it. One+ primary-key read; it never touches the queue. **`refactoring_summary`**+ (`only=["refactoring_summary"]`) is the rollup by type, effort, confidence,+ lifecycle and mechanical-vs-judgment, with facets.+- **`refactoring_plans`** is the raw per-detector list, unchanged and still+ addressable by `plan_id`, but **opt-in**: name it in `only` to get it. It+ returns ranked, structured refactoring plans (not templatestrings): `extract_class` (the cohesion `groups` to split into), `extract_helper`(clone `occurrences` + `suggested_site`), `move_method` (`{method, from_class,to_class}`), and `break_cycle` (the import `cut_edges`). Each plan carries itsdiff --git a/docs/layers/REFACTORING.md b/docs/layers/REFACTORING.mdindex e0fdb486c..f1b2ca613 100644--- a/docs/layers/REFACTORING.md+++ b/docs/layers/REFACTORING.md@@ -95,6 +95,55 @@ detector-native benefit even with zero health impact. Ties break deterministical> works **across files** (class splits, method moves, cycle breaks), and feeds the> co-change + graph context straight into the plan.+## Opportunities: the unit a surface serves++A **plan** is one detector output. An **opportunity** is one file's composed+refactoring: the diagnosis it leads with, its plans ordered so that applying+them in sequence is safe, and the clone groups that support the diagnosis+without instructing a change. The plan stays the addressable atom; a step names+one by `plan_id`.++Composition is deterministic and pure+(`analysis/health/refactoring/opportunity.py`), and it runs at **index time**:+the finalizer writes `refactoring_opportunities` and a one-row+`refactoring_summaries` headline in the same transaction that reconciles the+plans. Folding at read time was measured at 91 ms over 2,283 plans and 787 ms+at ten times that, plus 1,118 ms to rebuild the validation profiles, so every+page cost the whole repository.++| Field | Meaning |+|---|---|+| `opportunity_id` | `refop<model>_<digest>` over the member plan ids. Evidence is deliberately outside the kernel: a clone appearing or vanishing must not rename work an agent holds an id for. |+| `lead_biomarker` | The file's dominant finding, from the one owner of that rule (`analysis/health/models.py::primary_finding`). |+| `addresses_primary_problem` | Tri-state. `null` means no dominant finding was recorded, which is not the same claim as `false`. On the dogfood index it reads 201 true / 380 false / 3 unknown, and the false answers are the honest ones. |+| `steps[].applicability` | `mechanical` or `judgment`, with the reasons and the facts behind it, and the facts it could not establish under `unknowns`. Extraction is the only mechanical class. |+| `steps[].relocated_by` | An earlier step that moves this step's symbol to another file. The step's own `file_path` and span describe where the symbol *was*: locate it again before applying. Any surface that renders an ordered step list must say so. |+| `status` | Rolled up from the member plans' triage. Resolved only when every step is; one step marked a false positive does not resolve the rest. An `acknowledged` step is still outstanding work, so it keeps composing. |+| `steps[].finding_ids` | The findings this step's cause produced, so a step round-trips to its diagnosis through `get_health(finding_id=...)`. The key is **omitted entirely** when no finding on the file is addressable by id (a store written before findings carried public ids); an empty list means "none for this cause", which is a different answer. `lead_finding_ids` on the opportunity follows the same rule. |+| `steps[].validation_profile_id` | Points into the opportunity's `validation_profiles`. Resolved once at index time; the test-reachability walk behind it is never repeated per request. |++`performance_fix` plans are excluded by construction: the performance layer+composes, ranks and owns the lifecycle of its own opportunities.++### Ordering, and `refactoring_view`++The ranked head is honestly flat. On the dogfood index eight of the top ten+score identically: single high-confidence extractions recovering the same+quantised `complex_method` deduction, separated only by file path. They really+are equal under the published factors, so the answer is a queue that spends its+first rows on distinct problems rather than a tiebreaker invented to hide the+tie.++| `refactoring_view` | Order |+|---|---|+| `diversified` *(default)* | Rank order round-robined over (lead biomarker, lead refactoring type, containing area). Falls back to plain rank order when a repository has one cause in one area. |+| `canonical` | The published rank order verbatim, ties and all. What the old default produced. |+| `file_spread` | Asked for one row per file. An opportunity *is* one file's work, so the spread is satisfied by construction; the value resolves onto the diversified order, which is what it was reaching for. |++Both older values keep working. The same parameter also selects the legacy+`refactoring_plans` list's view, where `diversified` resolves to that list's+historical `canonical` default.+## Surfaces```bash@@ -102,19 +151,36 @@ repowise health --refactoring-targets # ranked table``````python-# MCP: the same structured plans, ranked-get_health(include=["refactoring"])-get_health(targets=["src/api/server.py"]) # one file-get_health(targets=["module:src.api"]) # one module+# MCP. A bare call already carries one bounded refactoring_directive.+get_health()+get_health(include=["refactoring"], only=["refactoring_opportunities"], limit=6)+get_health(include=["refactoring"], only=["refactoring_summary"])+get_health(opportunity_id="refop2_...") # steps, plans, validation+get_health(opportunity_id="refop2_...", only=["refactoring_evidence"], cursor=3)+get_health(plan_id="refac2_...") # one plan, and its owner+get_health(include=["refactoring"], only=["refactoring_plans"]) # the raw list, opt-in+get_health(targets=["src/api/server.py"]) # one file``````text-# REST: what the web tab reads+# REST. Both surfaces read services/refactoring_health.py, so they cannot+# answer differently; a parity suite asserts order, filters, totals and detail.+GET /api/repos/{repo_id}/refactoring/opportunities?view=diversified&limit=20+GET /api/repos/{repo_id}/refactoring/opportunities?file_path=src/api/server.py+GET /api/repos/{repo_id}/refactoring/opportunities/{opportunity_id}+GET /api/repos/{repo_id}/refactoring/summaryGET /api/repos/{repo_id}/refactoring/targets?refactoring_type=extract_class&min_confidence=highGET /api/repos/{repo_id}/refactoring/targets/page?limit=60&offset=0&refactoring_type=performance_fixGET /api/repos/{repo_id}/refactoring/{suggestion_id} # one plan + blast-radius detail```+A file's opportunities are a **separate call** - the queue filtered by+`file_path` - and deliberately not a field on the file-detail aggregate. That+aggregate is already the widest read in the server and every one of its callers+would pay for this whether or not it renders it, while the surface that wants+it knows it wants it. R2's `(repository_id, status, file_path)` index makes it+one indexed lookup rather than a scan.+The web **Refactoring** page uses one shared plan board and drawer for everytype, including a Performance filter. Its initial data path is bounded andserver-owned: search, type, confidence, effort, canonical sorting, true totals,diff --git a/packages/core/alembic/versions/0059_refactoring_opportunities.py b/packages/core/alembic/versions/0059_refactoring_opportunities.pynew file mode 100644index 000000000..0d8401c9e--- /dev/null+++ b/packages/core/alembic/versions/0059_refactoring_opportunities.py@@ -0,0 +1,121 @@+"""Materialize composed refactoring opportunities and the repository headline.++Composition folds a file's plans into one ordered opportunity, and the+validation profile behind each step costs a test-reachability walk. Both ran+per request over every open plan, so a page of twenty cost the repository:+measured on the dogfood index, folding 2,283 plans is 91 ms (787 ms at ten+times the rows) and hydrating their validation is 1,118 ms.++This adds the read model the serving layer pages: one row per opportunity with+the filter, order and identity columns a query needs, and one summary row per+repository for the bare-dashboard directive. Both are derived state, rebuilt by+the finalizer on every analysis, so an existing store upgrades empty and+repopulates on its next run.++Revision ID: 0059+Revises: 0058+Create Date: 2026-08-29+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "0059"+down_revision: str | None = "0058"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None++_OPPORTUNITY_INDEXES = (+ ("ix_refactoring_opportunities_repo_id", ["repository_id", "opportunity_id"]),+ (+ "ix_refactoring_opportunities_repo_status_queue",+ ["repository_id", "status", "queue_position"],+ ),+ (+ "ix_refactoring_opportunities_repo_status_rank",+ ["repository_id", "status", "rank_position"],+ ),+ (+ "ix_refactoring_opportunities_repo_status_type_rank",+ ["repository_id", "status", "lead_refactoring_type", "rank_position"],+ ),+ (+ "ix_refactoring_opportunities_repo_status_path",+ ["repository_id", "status", "file_path"],+ ),+)+++def upgrade() -> None:+ op.create_table(+ "refactoring_opportunities",+ sa.Column("id", sa.String(32), primary_key=True),+ sa.Column(+ "repository_id",+ sa.String(32),+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),+ nullable=False,+ ),+ sa.Column("opportunity_id", sa.String(64), nullable=False),+ sa.Column(+ "refactoring_model_version", sa.Integer(), nullable=False, server_default="0"+ ),+ sa.Column("status", sa.String(32), nullable=False, server_default="open"),+ sa.Column("rank_position", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("queue_position", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("rank_score", sa.Float(), nullable=False, server_default="0"),+ sa.Column("file_path", sa.Text(), nullable=False, server_default=""),+ sa.Column("lead_biomarker", sa.String(64), nullable=True),+ sa.Column("lead_refactoring_type", sa.String(32), nullable=False, server_default=""),+ # Nullable on purpose: "no lead to compare against" is a different+ # answer from "does not address the lead", and the surface says so.+ sa.Column("addresses_primary_problem", sa.Boolean(), nullable=True),+ sa.Column("effort_bucket", sa.String(4), nullable=False, server_default="M"),+ sa.Column("confidence", sa.String(16), nullable=False, server_default="medium"),+ sa.Column("step_count", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("mechanical_steps", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("judgment_steps", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("evidence_total", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("affected_files_total", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("recoverable_health", sa.Float(), nullable=False, server_default="0"),+ sa.Column("details_json", sa.Text(), nullable=False, server_default="{}"),+ sa.Column("analyzed_commit", sa.String(40), nullable=True),+ sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),+ sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),+ sa.UniqueConstraint(+ "repository_id",+ "refactoring_model_version",+ "opportunity_id",+ name="uq_refactoring_opportunities_repo_model_id",+ ),+ )+ for name, columns in _OPPORTUNITY_INDEXES:+ op.create_index(name, "refactoring_opportunities", columns, if_not_exists=True)++ op.create_table(+ "refactoring_summaries",+ sa.Column(+ "repository_id",+ sa.String(32),+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),+ primary_key=True,+ ),+ sa.Column(+ "refactoring_model_version", sa.Integer(), nullable=False, server_default="0"+ ),+ sa.Column("opportunities_total", sa.Integer(), nullable=False, server_default="0"),+ sa.Column("summary_json", sa.Text(), nullable=False, server_default="{}"),+ sa.Column("analyzed_commit", sa.String(40), nullable=True),+ sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),+ )+++def downgrade() -> None:+ op.drop_table("refactoring_summaries")+ for name, _columns in _OPPORTUNITY_INDEXES:+ op.drop_index(name, table_name="refactoring_opportunities", if_exists=True)+ op.drop_table("refactoring_opportunities")diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.pyindex 59bd86a3d..e80924db0 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py@@ -76,6 +76,13 @@ from .refactoring import (update_refactoring_suggestion_status,upsert_refactoring_suggestions,)+from .refactoring_opportunities import (+ finalize_refactoring_opportunities,+ get_refactoring_opportunity,+ get_refactoring_summary,+ list_refactoring_opportunities,+ refactoring_facet_counts,+)__all__ = ["FILE_TREND_SNAPSHOT_WINDOW",@@ -87,6 +94,7 @@ __all__ = ["covered_source_files","files_covered_by","finalize_performance_opportunities",+ "finalize_refactoring_opportunities","finalize_refactoring_suggestions","get_average_health","get_coverage_summary",@@ -104,17 +112,21 @@ __all__ = ["get_performance_opportunity","get_performance_plan_rows","get_performance_summary",+ "get_refactoring_opportunity","get_refactoring_suggestion","get_refactoring_suggestions",+ "get_refactoring_summary","get_test_coverage_summary","list_evidence_for_opportunities","list_health_snapshots","list_opportunity_evidence","list_performance_opportunities",+ "list_refactoring_opportunities","load_coverage_for_repo","opportunity_details","performance_facet_counts","performance_file_rollups",+ "refactoring_facet_counts","replace_dead_code_findings","replace_governance_findings","save_coverage_files",diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.pynew file mode 100644index 000000000..514cc7898--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring_opportunities.py@@ -0,0 +1,612 @@+"""Materialized refactoring opportunities: one writer, indexed readers.++Composition and validation run once per health persistence transaction over the+authoritative stored plans, and everything that serves the queue reads the+result. Measured on the dogfood index before this existed: folding 2,283 plans+cost 91 ms per request (787 ms at ten times the rows) and hydrating their+validation profiles another 1,118 ms, so a page of twenty cost the repository.++The writer is the only place that decides lifecycle, and it decides it by+rolling up the member plans' triage rather than holding an opinion of its own -+an opportunity is exactly as resolved as the work it names. An opportunity+nobody composes this run is resolved rather than deleted, so a held id keeps+answering and stops reading as current.+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++from sqlalchemy import Select, func, select+from sqlalchemy.ext.asyncio import AsyncSession++from ...models import (+ HealthFinding,+ RefactoringOpportunity,+ RefactoringSuggestion,+ RefactoringSummary,+ _new_uuid,+ _now_utc,+)++if TYPE_CHECKING:+ from ....analysis.health.refactoring.opportunity import (+ RefactoringOpportunity as OpportunityModel,+ )++_PERF_TYPE = "performance_fix"++# Plan states an opportunity is still composed from. ``resolved`` and+# ``false_positive`` are the two that stop describing work.+_LIVE_PLAN_STATUSES = frozenset({"open", "acknowledged"})++# Orders the queue can be read in. Every one ends in a unique column so the+# total order is deterministic and a deep offset cannot repeat or skip a row.+_ORDERS: dict[str, tuple[Any, ...]] = {+ "queue": (RefactoringOpportunity.queue_position.asc(),),+ "rank": (RefactoringOpportunity.rank_position.asc(),),+ "health": (+ RefactoringOpportunity.recoverable_health.desc(),+ RefactoringOpportunity.rank_position.asc(),+ ),+ "effort": (+ RefactoringOpportunity.step_count.asc(),+ RefactoringOpportunity.rank_position.asc(),+ ),+ "file": (+ RefactoringOpportunity.file_path.asc(),+ RefactoringOpportunity.rank_position.asc(),+ ),+}++DEFAULT_ORDER = "queue"+++# ---------------------------------------------------------------------------+# Writer+# ---------------------------------------------------------------------------+++def _diversified_order(opportunities: list[OpportunityModel]) -> list[int]:+ """Rank positions reordered so the head is not one cause in one directory.++ The ranked head is honestly flat: on the dogfood index eight of the top ten+ score identically, single high-confidence extractions recovering the same+ quantised deduction, separated only by file path. They are equal under the+ published factors, so the fix is not a tiebreaker invented to hide the tie -+ it is showing a queue that spends its first rows on distinct problems.++ Round-robins over (lead biomarker, lead refactoring type, area), groups+ ordered by their best member, members within a group in rank order.++ The area is the containing directory capped at two segments, never the file+ itself: the flat head is eight *different* files, so any key that varies per+ file gives each row its own group and reproduces rank order exactly. What+ actually repeats is the cause, the kind of work and the part of the tree.++ Deterministic, and a repository with one cause in one area degrades to+ plain rank order rather than inventing a difference.+ """+ groups: dict[tuple[str, str, str], list[int]] = {}+ for position, item in enumerate(opportunities):+ parent = item.file_path.rsplit("/", 1)[0] if "/" in item.file_path else ""+ area = "/".join(parent.split("/")[:2])+ groups.setdefault(+ (item.lead_biomarker or "", item.lead_refactoring_type, area), []+ ).append(position)+ ordered_groups = sorted(groups.values(), key=lambda members: members[0])+ order: list[int] = []+ for round_index in range(max((len(m) for m in ordered_groups), default=0)):+ for members in ordered_groups:+ if round_index < len(members):+ order.append(members[round_index])+ return order+++def _finding_ids_by_file(findings: list[HealthFinding]) -> dict[str, dict[str, list[str]]]:+ """Public finding ids per file, grouped by biomarker, for evidence round-trips."""+ out: dict[str, dict[str, list[str]]] = {}+ for finding in findings:+ public_id = finding.public_id+ if not public_id:+ continue+ out.setdefault(finding.file_path, {}).setdefault(finding.biomarker_type, []).append(+ public_id+ )+ return out+++def _details_payload(+ opportunity: OpportunityModel,+ *,+ validations: dict[str, dict[str, Any]],+ finding_ids: dict[str, list[str]],+) -> dict[str, Any]:+ """Everything explanatory, kept out of the indexed columns.++ Steps carry a validation profile id rather than the profile, and the+ profiles are stored once per opportunity: a file's steps usually share one+ test set, and repeating it per step is how a response stops fitting.+ """+ profiles: dict[str, dict[str, Any]] = {}+ steps: list[dict[str, Any]] = []+ for step in opportunity.steps:+ payload = step.as_dict()+ validation = validations.get(step.plan_id)+ if validation:+ profile_id = _validation_profile_id(validation)+ profiles.setdefault(profile_id, {"id": profile_id, **validation})+ payload["validation_profile_id"] = profile_id+ # The findings this step's cause names, so an agent can round-trip from+ # a step back to the diagnosis that produced it in one call. Emitted+ # only when this file has addressable findings at all: on a store+ # written before findings carried public ids there are none, and an+ # empty list there would claim "this cause produced no finding" when+ # the truth is "no finding here is addressable by id".+ if finding_ids:+ payload["finding_ids"] = finding_ids.get(step.source_biomarker, [])+ steps.append(payload)+ return {+ "steps": steps,+ "evidence": [item.as_dict() for item in opportunity.evidence],+ "affected_files": list(opportunity.affected_files),+ "rank_factors": dict(opportunity.rank_factors),+ "why_ranked": [dict(item) for item in opportunity.why_ranked],+ "validation_profiles": list(profiles.values()),+ **(+ {"lead_finding_ids": finding_ids.get(opportunity.lead_biomarker or "", [])}+ if finding_ids+ else {}+ ),+ }+++def _validation_profile_id(validation: dict[str, Any]) -> str:+ import hashlib++ encoded = json.dumps(validation, sort_keys=True, separators=(",", ":"), default=str)+ return "validation_" + hashlib.sha256(encoded.encode()).hexdigest()[:16]+++def _row_kwargs(+ opportunity: OpportunityModel,+ *,+ rank_position: int,+ queue_position: int,+ status: str,+ details: dict[str, Any],+ analyzed_commit: str | None,+) -> dict[str, Any]:+ return {+ "opportunity_id": opportunity.opportunity_id,+ "refactoring_model_version": opportunity.refactoring_model_version,+ "status": status,+ "rank_position": rank_position,+ "queue_position": queue_position,+ "rank_score": float(opportunity.rank_score),+ "file_path": opportunity.file_path,+ "lead_biomarker": opportunity.lead_biomarker,+ "lead_refactoring_type": opportunity.lead_refactoring_type,+ "addresses_primary_problem": opportunity.addresses_primary_problem,+ "effort_bucket": opportunity.effort_bucket,+ "confidence": opportunity.confidence,+ "step_count": opportunity.step_count,+ "mechanical_steps": opportunity.mechanical_steps,+ "judgment_steps": opportunity.judgment_steps,+ "evidence_total": len(opportunity.evidence),+ "affected_files_total": len(opportunity.affected_files),+ "recoverable_health": float(opportunity.recoverable_health),+ "details_json": json.dumps(details, separators=(",", ":"), default=str),+ "analyzed_commit": analyzed_commit,+ }+++def _summary_payload(+ opportunities: list[OpportunityModel],+ statuses: dict[str, str],+ lead_details: dict[str, Any] | None,+) -> dict[str, Any]:+ by_type: dict[str, int] = {}+ by_effort: dict[str, int] = {}+ by_confidence: dict[str, int] = {}+ by_status: dict[str, int] = {}+ mechanical = judgment = 0+ addresses_primary = not_primary = unknown_primary = 0+ for item in opportunities:+ by_type[item.lead_refactoring_type] = by_type.get(item.lead_refactoring_type, 0) + 1+ by_effort[item.effort_bucket] = by_effort.get(item.effort_bucket, 0) + 1+ by_confidence[item.confidence] = by_confidence.get(item.confidence, 0) + 1+ state = statuses.get(item.opportunity_id, "open")+ by_status[state] = by_status.get(state, 0) + 1+ mechanical += item.mechanical_steps+ judgment += item.judgment_steps+ if item.addresses_primary_problem is True:+ addresses_primary += 1+ elif item.addresses_primary_problem is False:+ not_primary += 1+ else:+ unknown_primary += 1+ return {+ "opportunities_total": len(opportunities),+ "files_total": len({item.file_path for item in opportunities}),+ "steps_total": mechanical + judgment,+ "mechanical_steps_total": mechanical,+ "judgment_steps_total": judgment,+ "by_lead_type": by_type,+ "by_effort": by_effort,+ "by_confidence": by_confidence,+ "by_status": by_status,+ "addresses_primary_problem": {+ "yes": addresses_primary,+ "no": not_primary,+ "unknown": unknown_primary,+ },+ "lead": lead_details,+ }+++async def finalize_refactoring_opportunities(+ session: AsyncSession,+ repository_id: str,+ *,+ analyzed_commit: str | None = None,+) -> int:+ """Compose the stored plans into opportunities and reconcile the read model.++ Called by both index paths inside the transaction that has just written the+ plans, so composition always sees the authoritative set rather than a+ partially-written one. Repository-wide even on an incremental run: an+ opportunity is a fold over a file's plans, and a file the run did not touch+ can still lose its opportunity when a cross-file clone elsewhere resolves.++ Returns the number of open opportunities.+ """+ from ....analysis.health.models import primary_biomarker_by_file+ from ....analysis.health.refactoring.opportunity import (+ compose_opportunities,+ opportunity_status,+ )+ from ....analysis.health.refactoring.recommendations import hydrate_recommendations++ plan_rows = list(+ (+ await session.execute(+ select(RefactoringSuggestion).where(+ RefactoringSuggestion.repository_id == repository_id,+ RefactoringSuggestion.refactoring_type != _PERF_TYPE,+ )+ )+ )+ .scalars()+ .all()+ )+ # Acknowledged is outstanding work a person has picked up, not work that is+ # gone: dropping it here would resolve the opportunity the moment someone+ # said they were doing it.+ live_plans = [row for row in plan_rows if row.status in _LIVE_PLAN_STATUSES]+ findings = list(+ (+ await session.execute(+ select(HealthFinding).where(HealthFinding.repository_id == repository_id)+ )+ )+ .scalars()+ .all()+ )++ opportunities = compose_opportunities(+ live_plans, primary_biomarker_by_file=primary_biomarker_by_file(findings)+ )++ # Validation is resolved once, here, for exactly the plans that became+ # steps. It used to be rebuilt on every request for every open plan, which+ # is the single largest cost the serving path used to carry.+ step_plan_ids = {step.plan_id for item in opportunities for step in item.steps}+ step_rows = [row for row in live_plans if row.public_id in step_plan_ids]+ validations: dict[str, dict[str, Any]] = {}+ if step_rows:+ # Keyed by the storage id ``rehydrate_suggestion`` carries through, never+ # by position: ``hydrate_recommendations`` returns its results in rank+ # order, so zipping them against the input pairs most steps with another+ # plan's validation profile.+ public_by_storage = {row.id: row.public_id for row in step_rows}+ for recommendation in await hydrate_recommendations(+ session, repository_id, step_rows+ ):+ public_id = public_by_storage.get(+ getattr(recommendation.suggestion, "id", None)+ )+ # Through ``as_dict`` rather than the attribute: ``validation`` is a+ # dataclass, and the serialized form is the one every surface shows.+ validation = recommendation.as_dict().get("validation")+ if public_id and validation:+ validations[public_id] = validation++ plan_status = {row.public_id: row.status for row in plan_rows if row.public_id}+ statuses = {+ item.opportunity_id: opportunity_status(item, plan_status) for item in opportunities+ }+ finding_ids = _finding_ids_by_file(findings)+ queue_order = _diversified_order(opportunities)++ details_by_id = {+ item.opportunity_id: _details_payload(+ item,+ validations=validations,+ finding_ids=finding_ids.get(item.file_path, {}),+ )+ for item in opportunities+ }+ queue_position_by_rank = {rank: slot for slot, rank in enumerate(queue_order)}++ await _reconcile_opportunities(+ session,+ repository_id,+ opportunities,+ statuses=statuses,+ details_by_id=details_by_id,+ queue_position_by_rank=queue_position_by_rank,+ analyzed_commit=analyzed_commit,+ )++ lead_rank = queue_order[0] if queue_order else None+ lead = opportunities[lead_rank] if lead_rank is not None else None+ lead_details = None+ if lead is not None:+ lead_details = {+ "opportunity_id": lead.opportunity_id,+ "file_path": lead.file_path,+ "lead_biomarker": lead.lead_biomarker,+ "lead_refactoring_type": lead.lead_refactoring_type,+ "addresses_primary_problem": lead.addresses_primary_problem,+ "step_count": lead.step_count,+ "mechanical_steps": lead.mechanical_steps,+ "judgment_steps": lead.judgment_steps,+ "effort_bucket": lead.effort_bucket,+ "confidence": lead.confidence,+ "recoverable_health": round(lead.recoverable_health, 3),+ "status": statuses.get(lead.opportunity_id, "open"),+ }+ await _write_summary(+ session,+ repository_id,+ opportunities,+ statuses=statuses,+ lead_details=lead_details,+ analyzed_commit=analyzed_commit,+ )+ return sum(1 for state in statuses.values() if state != "resolved")+++async def _reconcile_opportunities(+ session: AsyncSession,+ repository_id: str,+ opportunities: list[OpportunityModel],+ *,+ statuses: dict[str, str],+ details_by_id: dict[str, dict[str, Any]],+ queue_position_by_rank: dict[int, int],+ analyzed_commit: str | None,+) -> None:+ """Update, insert, and resolve, in one pass over the stored rows."""+ from ....analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION++ stored = {+ (row.refactoring_model_version, row.opportunity_id): row+ for row in (+ await session.execute(+ select(RefactoringOpportunity).where(+ RefactoringOpportunity.repository_id == repository_id,+ # Rows an older model minted are left exactly as they are:+ # their keys can never be composed again, so reading them+ # only to re-resolve them would grow this read for the life+ # of the repository.+ RefactoringOpportunity.refactoring_model_version+ == REFACTORING_MODEL_VERSION,+ )+ )+ )+ .scalars()+ .all()+ }+ seen: set[tuple[int, str]] = set()+ now = _now_utc()+ for rank_position, item in enumerate(opportunities):+ key = (item.refactoring_model_version, item.opportunity_id)+ seen.add(key)+ values = _row_kwargs(+ item,+ rank_position=rank_position,+ queue_position=queue_position_by_rank.get(rank_position, rank_position),+ status=statuses.get(item.opportunity_id, "open"),+ details=details_by_id.get(item.opportunity_id, {}),+ analyzed_commit=analyzed_commit,+ )+ row = stored.get(key)+ if row is None:+ session.add(+ RefactoringOpportunity(id=_new_uuid(), repository_id=repository_id, **values)+ )+ continue+ for name, value in values.items():+ setattr(row, name, value)+ row.updated_at = now+ for key, row in stored.items():+ if key not in seen and row.status != "resolved":+ row.status = "resolved"+ row.updated_at = now+ await session.flush()+++async def _write_summary(+ session: AsyncSession,+ repository_id: str,+ opportunities: list[OpportunityModel],+ *,+ statuses: dict[str, str],+ lead_details: dict[str, Any] | None,+ analyzed_commit: str | None,+) -> None:+ from ....analysis.health.refactoring.identity import REFACTORING_MODEL_VERSION++ payload = json.dumps(+ _summary_payload(opportunities, statuses, lead_details), separators=(",", ":")+ )+ row = await session.get(RefactoringSummary, repository_id)+ if row is None:+ row = RefactoringSummary(repository_id=repository_id)+ session.add(row)+ row.refactoring_model_version = REFACTORING_MODEL_VERSION+ row.opportunities_total = len(opportunities)+ row.summary_json = payload+ row.analyzed_commit = analyzed_commit+ row.updated_at = _now_utc()+ await session.flush()+++# ---------------------------------------------------------------------------+# Indexed readers+# ---------------------------------------------------------------------------+++def _opportunity_filters(+ repository_id: str,+ *,+ status: str,+ lead_type: str | None,+ confidence: str | None,+ effort: str | None,+ file_paths: list[str] | None,+ mechanical_only: bool,+ addresses_primary: bool | None,+) -> list[Any]:+ predicates: list[Any] = [+ RefactoringOpportunity.repository_id == repository_id,+ RefactoringOpportunity.status == status,+ ]+ if lead_type is not None:+ predicates.append(RefactoringOpportunity.lead_refactoring_type == lead_type)+ if confidence is not None:+ predicates.append(RefactoringOpportunity.confidence == confidence)+ if effort is not None:+ predicates.append(RefactoringOpportunity.effort_bucket == effort)+ if file_paths is not None:+ predicates.append(RefactoringOpportunity.file_path.in_(file_paths))+ if mechanical_only:+ predicates.append(RefactoringOpportunity.mechanical_steps > 0)+ if addresses_primary is not None:+ predicates.append(+ RefactoringOpportunity.addresses_primary_problem.is_(addresses_primary)+ )+ return predicates+++async def list_refactoring_opportunities(+ session: AsyncSession,+ repository_id: str,+ *,+ status: str = "open",+ lead_type: str | None = None,+ confidence: str | None = None,+ effort: str | None = None,+ file_paths: list[str] | None = None,+ mechanical_only: bool = False,+ addresses_primary: bool | None = None,+ order: str = DEFAULT_ORDER,+ limit: int = 20,+ offset: int = 0,+) -> tuple[list[RefactoringOpportunity], int]:+ """One page and its total: two statements, whatever the row count."""+ predicates = _opportunity_filters(+ repository_id,+ status=status,+ lead_type=lead_type,+ confidence=confidence,+ effort=effort,+ file_paths=file_paths,+ mechanical_only=mechanical_only,+ addresses_primary=addresses_primary,+ )+ total = int(+ (+ await session.execute(+ select(func.count()).select_from(RefactoringOpportunity).where(*predicates)+ )+ ).scalar_one()+ )+ query: Select[Any] = (+ select(RefactoringOpportunity)+ .where(*predicates)+ .order_by(*_ORDERS.get(order, _ORDERS[DEFAULT_ORDER]))+ .offset(max(offset, 0))+ .limit(max(limit, 0))+ )+ rows = list((await session.execute(query)).scalars().all())+ return rows, total+++async def get_refactoring_opportunity(+ session: AsyncSession, repository_id: str, opportunity_id: str+) -> RefactoringOpportunity | None:+ """Resolve one opportunity id. Indexed seek, newest model version first."""+ result = await session.execute(+ select(RefactoringOpportunity)+ .where(+ RefactoringOpportunity.repository_id == repository_id,+ RefactoringOpportunity.opportunity_id == opportunity_id,+ )+ .order_by(RefactoringOpportunity.refactoring_model_version.desc())+ .limit(1)+ )+ return result.scalar_one_or_none()+++async def get_refactoring_summary(+ session: AsyncSession, repository_id: str+) -> RefactoringSummary | None:+ """The repository headline, by primary key."""+ return await session.get(RefactoringSummary, repository_id)+++async def refactoring_facet_counts(+ session: AsyncSession, repository_id: str, *, status: str = "open"+) -> dict[str, dict[str, int]]:+ """Counts for every facet dimension, in one statement.++ Grouped by all three dimensions at once and folded here rather than one+ statement each, so adding a facet never adds a round trip.+ """+ columns = (+ RefactoringOpportunity.lead_refactoring_type,+ RefactoringOpportunity.effort_bucket,+ RefactoringOpportunity.confidence,+ )+ rows = await session.execute(+ select(*columns, func.count())+ .where(+ RefactoringOpportunity.repository_id == repository_id,+ RefactoringOpportunity.status == status,+ )+ .group_by(*columns)+ )+ facets: dict[str, dict[str, int]] = {"lead_type": {}, "effort": {}, "confidence": {}}+ for lead_type, effort, confidence, count in rows.all():+ for name, key in (+ ("lead_type", lead_type),+ ("effort", effort),+ ("confidence", confidence),+ ):+ if key is not None:+ facets[name][str(key)] = facets[name].get(str(key), 0) + int(count)+ return facets+++__all__ = [+ "DEFAULT_ORDER",+ "finalize_refactoring_opportunities",+ "get_refactoring_opportunity",+ "get_refactoring_summary",+ "list_refactoring_opportunities",+ "refactoring_facet_counts",+]diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 5b778c89f..f28a8cb28 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1446,6 +1446,127 @@ class PerformanceSummary(Base):)+class RefactoringOpportunity(Base):+ """One file's composed refactoring work, materialized for serving.++ Composition folds a file's plans into one ordered, precondition-aware+ opportunity. Folding at read time costs the whole repository per request+ (measured: 91 ms over 2,283 plans, 787 ms at ten times that), and the+ validation profile behind each step costs another second of test-reachability+ walking. Both run once, when plans are persisted, and land here; a page is+ then an indexed range scan.++ Filter, order and identity live in columns because SQLite and PostgreSQL+ both index those and neither indexes a JSON predicate portably. The ordered+ steps, evidence, rank factors and validation profiles stay in+ ``details_json``, where a new fact costs no migration.+ """++ __tablename__ = "refactoring_opportunities"++ id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)+ repository_id: Mapped[str] = mapped_column(+ String(32), ForeignKey("repositories.id", ondelete="CASCADE"), nullable=False+ )+ # ``refop<model>_<digest>``, the digest of the member plan ids. Unique per+ # repository *and* model version, for the reason the plan id is.+ opportunity_id: Mapped[str] = mapped_column(String(64), nullable=False)+ refactoring_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ # Rolled up from the member plans' triage, never written directly here.+ status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")+ # Position in the deterministic rank order.+ rank_position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ # Position in the diversified default order. Separate column because the+ # two orders answer different questions and both have to be indexed: rank+ # answers "what scores highest", queue answers "what should a queue show+ # first" when the ranked head is a run of ties from one package.+ queue_position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ rank_score: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)+ file_path: Mapped[str] = mapped_column(Text, nullable=False, default="")+ # The file's dominant biomarker; ``None`` when no finding names one.+ lead_biomarker: Mapped[str | None] = mapped_column(String(64), nullable=True)+ lead_refactoring_type: Mapped[str] = mapped_column(String(32), nullable=False, default="")+ # Tri-state on purpose: ``None`` means no lead was available to compare+ # against, which is not the same claim as "does not address it".+ addresses_primary_problem: Mapped[bool | None] = mapped_column(Boolean, nullable=True)+ effort_bucket: Mapped[str] = mapped_column(String(4), nullable=False, default="M")+ confidence: Mapped[str] = mapped_column(String(16), nullable=False, default="medium")+ step_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ mechanical_steps: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ judgment_steps: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ evidence_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ affected_files_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ recoverable_health: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)+ details_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")+ analyzed_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), nullable=False, default=_now_utc+ )+ updated_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc+ )++ __table_args__ = (+ UniqueConstraint(+ "repository_id",+ "refactoring_model_version",+ "opportunity_id",+ name="uq_refactoring_opportunities_repo_model_id",+ ),+ Index("ix_refactoring_opportunities_repo_id", "repository_id", "opportunity_id"),+ Index(+ "ix_refactoring_opportunities_repo_status_queue",+ "repository_id",+ "status",+ "queue_position",+ ),+ Index(+ "ix_refactoring_opportunities_repo_status_rank",+ "repository_id",+ "status",+ "rank_position",+ ),+ Index(+ "ix_refactoring_opportunities_repo_status_type_rank",+ "repository_id",+ "status",+ "lead_refactoring_type",+ "rank_position",+ ),+ Index(+ "ix_refactoring_opportunities_repo_status_path",+ "repository_id",+ "status",+ "file_path",+ ),+ )+++class RefactoringSummary(Base):+ """The current refactoring headline for one repository, in one row.++ A bare dashboard has to lead with one actionable opportunity without+ touching the queue, so the lead and the rollup are written by the+ transaction that materializes the opportunities and read back by primary+ key. Current state, never history.+ """++ __tablename__ = "refactoring_summaries"++ repository_id: Mapped[str] = mapped_column(+ String(32),+ ForeignKey("repositories.id", ondelete="CASCADE"),+ primary_key=True,+ )+ refactoring_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ opportunities_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ summary_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")+ analyzed_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)+ updated_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc+ )++class HealthFileMetric(Base):"""Per-file aggregate metrics + final score."""diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.pyindex 59695b87d..71ad58180 100644--- a/packages/core/src/repowise/core/pipeline/incremental.py+++ b/packages/core/src/repowise/core/pipeline/incremental.py@@ -939,6 +939,7 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non"""from repowise.core.persistence.crud import (finalize_performance_opportunities,+ finalize_refactoring_opportunities,upsert_health_findings,upsert_health_metrics,upsert_refactoring_suggestions,@@ -1004,6 +1005,12 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Nonanalyzed_commit=analyzed_commit,plan_policy=getattr(report, "performance_plan_policy", None),)+ # Repository-wide, like the queue above and for the same reason: an+ # opportunity folds a file's plans, and a file this run did not touch+ # can still lose one when a cross-file plan elsewhere resolves.+ await finalize_refactoring_opportunities(+ session, repo_id, analyzed_commit=analyzed_commit+ )# Per-function blame rollup for the changed files (keeps git_function_blame# current between full indexes; FULL git tier only — empty otherwise).fn_blame_rows = getattr(report, "function_blame_rows", None)diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 60c2eaf68..a09fac56a 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -1513,6 +1513,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:from repowise.core.persistence.crud import (bulk_upsert_decisions,finalize_performance_opportunities,+ finalize_refactoring_opportunities,recompute_decision_staleness,save_coverage_files,save_dead_code_findings,@@ -1565,6 +1566,12 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:analyzed_commit=head_sha,plan_policy=getattr(hr, "performance_plan_policy", None),)+ # Fold the plans just written into per-file opportunities. Last in+ # the savepoint because it composes over the stored rows, so it has+ # to see the reconciliation above rather than the detector output.+ await finalize_refactoring_opportunities(+ session, repo_id, analyzed_commit=head_sha+ )# Resolved coverage rows, when a report was ingested this run.coverage_files = getattr(hr, "coverage_files", None)if coverage_files:diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pyindex a15d59890..30a156ff9 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py@@ -177,6 +177,8 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"trends[]","metrics[]","refactoring_plans[]",+ "refactoring_opportunities[]",+ "refactoring_summary","performance_opportunities[]","performance_summary","high_leverage_files[]",@@ -185,10 +187,11 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {protected=("mode","directive",- # The performance lead is bounded by construction and is the only- # actionable performance content a bare dashboard carries, so- # shedding it would leave the pillar with counts and nothing to do.+ # Both pillar leads are bounded by construction and are the only+ # actionable content a bare dashboard carries for them, so shedding+ # one would leave that pillar with counts and nothing to do."performance_directive",+ "refactoring_directive","opportunity_id","model_state","targets",diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex f435f1191..fa2c55ce8 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -9,7 +9,7 @@ from pathlib import Pathfrom time import perf_counterfrom typing import Any-from sqlalchemy import select+from sqlalchemy import func, selectfrom repowise.core.analysis.health.churn_complexity import churn_complexity_pointsfrom repowise.core.analysis.health.complexity.languages import LANGUAGE_MAPS@@ -73,6 +73,34 @@ from repowise.server.services.performance_health import (evidence_block,parse_query,)+from repowise.server.services.refactoring_health import CANONICAL_VIEWS as _REFACTORING_VIEWS+from repowise.server.services.refactoring_health import DEFAULT_VIEW as _REFACTORING_VIEW_DEFAULT+from repowise.server.services.refactoring_health import (+ RefactoringHealthService,+ plan_view,+)+from repowise.server.services.refactoring_health import (+ parse_query as parse_refactoring_query,+)++# The opportunity id space is shared with the performance pillar's, and told+# apart by prefix alone, so ``opportunity_id`` stays one selector.+_REFACTORING_OPPORTUNITY_PREFIX = "refop"++_REFACTORING_COLLECTION_CAP = 6+"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""++_REFACTORING_STEP_CAP = 3+"""Steps per row in the queue. The detail call pages the rest."""++_REFACTORING_STEP_PAGE_CAP = 20+"""Ceiling on one page of a detail call's ordered steps."""++_REFACTORING_EVIDENCE_CAP = 3+"""Evidence rows beside a detail response. ``only=['refactoring_evidence']`` pages more."""++_REFACTORING_EVIDENCE_PAGE_CAP = 20+"""Ceiling on one evidence page."""_PERFORMANCE_COLLECTION_CAP = 6"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""@@ -208,6 +236,68 @@ async def _resolve_finding()+@dataclass(frozen=True, slots=True)+class _RefactoringBlocks:+ """Everything the refactoring pillar contributes to one response."""++ page: Any = None+ summary: dict[str, Any] | None = None+ directive: dict[str, Any] | None = None+ ignored: dict[str, str] = field(default_factory=dict)+++async def _refactoring_blocks(+ service: RefactoringHealthService,+ *,+ wants: Any,+ included: bool,+ file_paths: tuple[str, ...] | None,+ scoped: bool,+ limit: int,+ cursor: int,+ view: str,+ lead_type: str | None = None,+ confidence: str | None = None,+ effort: str | None = None,+) -> _RefactoringBlocks:+ """Read the materialized queue, its rollup, and the dashboard lead.++ Each block is gated on surviving the projection, so a caller that asked for+ one of the three does not pay for the other two.+ """+ page = None+ ignored: dict[str, str] = {}+ if included:+ emits_queue = wants("refactoring_opportunities")+ query, ignored = parse_refactoring_query(+ view=view,+ lead_type=lead_type,+ confidence=confidence,+ effort=effort,+ file_paths=list(file_paths) if file_paths else None,+ limit=min(max(limit, 0), _REFACTORING_COLLECTION_CAP) if emits_queue else 1,+ offset=cursor if emits_queue else 0,+ )+ page = await service.page(+ query,+ steps_per_item=_REFACTORING_STEP_CAP if emits_queue else 0,+ with_facets=wants("refactoring_summary"),+ )+ return _RefactoringBlocks(+ page=page,+ summary=await service.summary() if included and wants("refactoring_summary") else None,+ # The dashboard lead only. A targeted call is already about a file the+ # caller named, so pointing it at the repository's worst file elsewhere+ # would be answering a question nobody asked.+ directive=(+ await service.directive()+ if not scoped and wants("refactoring_directive")+ else None+ ),+ ignored=ignored,+ )++async def _performance_detail_response(session: Any,repository: Any,@@ -245,24 +335,87 @@ async def _performance_detail_response(repository=repository, targets=[file_path] if file_path else None),}- metric_rows = (- list(- (- await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository.id,- HealthFileMetric.file_path == file_path,- )- )- ).scalars()+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ return result+++async def _refactoring_detail_response(+ session: Any,+ repository: Any,+ reference_repository: str,+ opportunity_id: str,+ *,+ evidence_only: bool,+ limit: int,+ cursor: int,+) -> dict[str, Any]:+ """One composed opportunity, or one page of the evidence behind it."""+ service = RefactoringHealthService(session, repository.id, reference_repository)+ if evidence_only:+ detail = await service.detail(+ opportunity_id,+ step_limit=0,+ evidence_limit=min(max(limit, 0), _REFACTORING_EVIDENCE_PAGE_CAP),+ evidence_offset=cursor,+ with_plans=False,)- if file_path- else []+ block = {k: v for k, v in detail.items() if k.startswith("evidence")}+ result = {+ "mode": "refactoring_evidence",+ "opportunity_id": opportunity_id,+ "resolved": bool(detail.get("resolved")),+ **block,+ "_meta": _build_meta(repository=repository),+ }+ if block.get("evidence_next_cursor") is not None:+ result["recovery"] = {+ "evidence": {+ "remaining": block["evidence_total"] - block["evidence_next_cursor"],+ "call": (+ f"get_health(opportunity_id={opportunity_id!r}, "+ f"only=['refactoring_evidence'], limit={limit}, "+ f"cursor={block['evidence_next_cursor']})"+ ),+ }+ }+ return result+ detail = await service.detail(+ opportunity_id,+ step_limit=min(max(limit, 0), _REFACTORING_STEP_PAGE_CAP),+ step_offset=cursor,+ evidence_limit=_REFACTORING_EVIDENCE_CAP,)- _attach_health_analysis_meta(result["_meta"], metric_rows)+ file_path = detail.get("file_path")+ if not detail.get("resolved"):+ detail.setdefault(+ "model_state", _refactoring_model_state(opportunity_id)+ )+ result = {+ "mode": "refactoring_opportunity",+ **detail,+ "_meta": _build_meta(+ repository=repository, targets=[file_path] if file_path else None+ ),+ }+ await _attach_repository_analysis_meta(session, repository, result["_meta"])return result+def _refactoring_model_state(opportunity_id: str) -> dict[str, Any]:+ """Tell a stale-model id apart from a wrong one, from the string alone."""+ from repowise.core.analysis.health.refactoring.identity import (+ REFACTORING_MODEL_VERSION,+ model_state,+ )++ state = model_state(+ opportunity_id.replace(_REFACTORING_OPPORTUNITY_PREFIX, "refac", 1)+ )+ state["public_id"] = opportunity_id+ state["refactoring_model_version"] = REFACTORING_MODEL_VERSION+ return state++def _perf_rank(biomarker_type: str | None, details: Any) -> int:"""Order-of-magnitude ordering key for one ``performance`` finding.@@ -917,11 +1070,71 @@ def _attach_health_analysis_meta(meta: dict[str, Any], metrics: list[HealthFileMetric]) -> None:"""Keep stored analysis distinct from index/live Git verification."""- meta["health_semantics"] = health_semantics_contract()analyzed = [m for m in metrics if getattr(m, "updated_at", None)]- commits = {c for m in analyzed if (c := getattr(m, "analyzed_commit", None))}latest = max(analyzed, key=lambda m: m.updated_at) if analyzed else None- latest_commit = getattr(latest, "analyzed_commit", None) if latest else None+ _write_health_analysis_meta(+ meta,+ has_metrics=bool(metrics),+ latest_at=latest.updated_at if latest is not None else None,+ latest_commit=getattr(latest, "analyzed_commit", None) if latest else None,+ distinct_commits=len({c for m in analyzed if (c := getattr(m, "analyzed_commit", None))}),+ )+++async def _attach_repository_analysis_meta(+ session: Any, repository: Any, meta: dict[str, Any]+) -> None:+ """The same block, computed over the repository rather than one file.++ "Has this repository's health analysis recorded its commit" is a fact about+ the analysis, but every detail mode used to answer it from the rows it+ happened to be reporting on. A ``plan_id`` call scoped to a file whose row+ carries a commit said ``available`` at the same instant the dashboard said+ ``degraded (analysis_commit_not_recorded)`` from the repo-wide latest row,+ and the reverse when the scoped file was the one missing it. Three bounded+ aggregates, so agreeing costs no scan.+ """+ latest = (+ await session.execute(+ select(HealthFileMetric.updated_at, HealthFileMetric.analyzed_commit)+ .where(+ HealthFileMetric.repository_id == repository.id,+ HealthFileMetric.updated_at.is_not(None),+ )+ .order_by(HealthFileMetric.updated_at.desc())+ .limit(1)+ )+ ).first()+ total, distinct = (+ await session.execute(+ select(+ func.count(),+ func.count(func.distinct(HealthFileMetric.analyzed_commit)),+ ).where(HealthFileMetric.repository_id == repository.id)+ )+ ).one()+ _write_health_analysis_meta(+ meta,+ has_metrics=total > 0,+ latest_at=latest[0] if latest else None,+ latest_commit=latest[1] if latest else None,+ distinct_commits=distinct,+ )+++def _write_health_analysis_meta(+ meta: dict[str, Any],+ *,+ has_metrics: bool,+ latest_at: Any,+ latest_commit: str | None,+ distinct_commits: int,+) -> None:+ """The one place the analysis-freshness block is shaped."""+ meta["health_semantics"] = health_semantics_contract()+ metrics = has_metrics+ analyzed = latest_at is not None+ commits_count = distinct_commitsstatus = "available" if latest_commit else "degraded" if metrics else "unavailable"analysis: dict[str, Any] = {"status": status,@@ -944,17 +1157,16 @@ def _attach_health_analysis_meta(if not metrics:analysis["reason"] = "no_stored_health_metrics"if analyzed:- assert latest is not None- analyzed_at = latest.updated_at.isoformat()+ analyzed_at = latest_at.isoformat()analysis["analyzed_at"] = analyzed_atmeta["health_analyzed_at"] = analyzed_atif latest_commit:analyzed_commit = latest_commit[:12]analysis["analyzed_commit"] = analyzed_commitmeta["health_analyzed_commit"] = analyzed_commit- if len(commits) > 1:- analysis["analyzed_commits_distinct"] = len(commits)- meta["health_analyzed_commits_distinct"] = len(commits)+ if commits_count > 1:+ analysis["analyzed_commits_distinct"] = commits_count+ meta["health_analyzed_commits_distinct"] = commits_countif not latest_commit:analysis["reason"] = "analysis_commit_not_recorded"analysis["analyzed_commit"] = None@@ -1231,7 +1443,10 @@ async def get_health(repo: str | None = None,limit: int = 20,only: list[str] | None = None,- refactoring_view: str = "canonical",+ refactoring_view: str = _REFACTORING_VIEW_DEFAULT,+ refactoring_type: str | None = None,+ refactoring_confidence: str | None = None,+ refactoring_effort: str | None = None,cursor: int = 0,finding_id: str | None = None,plan_id: str | None = None,@@ -1250,26 +1465,26 @@ async def get_health(Args:targets: file paths or ``module:<name>``. Empty means dashboard;- unmatched ones appear in ``unresolved``, surviving any ``only``.+ unmatched ones land in ``unresolved``, surviving ``only``.include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |- ``accuracy`` | ``signals`` | ``churn_complexity``, or one dimension- name. ``performance`` also adds the opportunity queue.+ ``accuracy`` | ``signals`` | ``churn_complexity``, or a dimension.+ ``performance`` and ``refactoring`` add their queues.only: keys to keep; identity, counts and recovery survive.``biomarkers``, ``accuracy`` and ``refactoring`` alias their blockkey. ``performance``, ``defect`` and ``maintainability`` do not:they filter rows and land in ``unknown_only_keys``.repo: usually omitted.limit: max rows per ranked list, ``0`` for none.- refactoring_view: ``canonical`` (default) or ``file_spread``.- cursor: zero-based offset for ranked collections.- finding_id: stable ``id`` emitted by a health finding.- plan_id: stable ``id`` emitted by a refactoring plan.- opportunity_id: ``perf...`` id from ``performance_directive`` or the- queue: the cause, its plan or why there is none, and evidence,- which ``only=["performance_evidence"]`` plus ``cursor`` pages.- Excludes the two ids above.+ cursor: zero-based offset into a ranked list.+ finding_id: stable ``id`` from a health finding.+ plan_id: stable ``id`` from a refactoring plan.+ opportunity_id: ``perf...`` or ``refop...`` id from a directive or+ queue: the unit, its steps or plan, and evidence paged by+ ``only=["*_evidence"]``. Excludes the two ids above.+ refactoring_view: ``diversified`` (default) | ``canonical`` |+ ``file_spread``; refactoring_type / _confidence / _effort filter.performance_view / _context / _boundary / _confidence / _sort: queue- projection and filters; the facets list their values.+ projection and filters; the facets list them."""started = perf_counter()@@ -1283,8 +1498,8 @@ async def get_health(# "the totals, none of the rows" silently returned a row.limit = max(limit, 0)cursor = max(cursor, 0)- if refactoring_view not in {"canonical", "file_spread"}:- refactoring_view = "canonical"+ if refactoring_view not in _REFACTORING_VIEWS:+ refactoring_view = _REFACTORING_VIEW_DEFAULTinclude_set = set(include or [])known_includes = {"biomarkers",@@ -1334,6 +1549,11 @@ async def get_health(or wants("recommendation_lede")or wants("performance_summary"))+ wants_refactoring_opportunities = (+ wants("refactoring_opportunities")+ or wants("recommendation_lede")+ or wants("refactoring_summary")+ )# Everything downstream of the test/production split, in one place.## Keep this list exhaustive. The read it gates is not free (the column list@@ -1379,6 +1599,8 @@ async def get_health("churn_complexity","coverage.files","refactoring_plans",+ "refactoring_opportunities",+ "refactoring_evidence","performance_opportunities","performance_evidence",}@@ -1394,7 +1616,12 @@ async def get_health(if tail_start < len(rows):next_limit = (min(row_cap or 6, 6)- if label in {"refactoring_plans", "performance_opportunities"}+ if label+ in {+ "refactoring_plans",+ "refactoring_opportunities",+ "performance_opportunities",+ }else min(len(rows) - tail_start, 50))page_recoveries[label] = (@@ -1433,23 +1660,20 @@ async def get_health(targets=[match.file_path] if match else None,),}- metric_rows = (- list(- (- await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository.id,- HealthFileMetric.file_path == match.file_path,- )- )- ).scalars()- )- if match- else []- )- _attach_health_analysis_meta(result["_meta"], metric_rows)+ await _attach_repository_analysis_meta(session, repository, result["_meta"])return result+ if opportunity_id and opportunity_id.startswith(_REFACTORING_OPPORTUNITY_PREFIX):+ return await _refactoring_detail_response(+ session,+ repository,+ reference_repository,+ opportunity_id,+ evidence_only=only_set == {"refactoring_evidence"},+ limit=limit,+ cursor=cursor,+ )+if opportunity_id:return await _performance_detail_response(session,@@ -1462,48 +1686,35 @@ async def get_health()if plan_id:- plan_rows = await get_refactoring_suggestions(session, repository.id)- recommendations = await hydrate_recommendations(- session, repository.id, plan_rows- )- match = next(- (- row- for row in recommendations- if plan_id- in {row.id, _refactoring_plan_id(row, reference_repository)}- ),- None,+ # An indexed seek and one hydration, not a full load and a linear+ # scan: resolving one id used to cost every open plan in the repo.+ service = RefactoringHealthService(+ session, repository.id, reference_repository)+ resolved = await service.plan_detail(plan_id)+ plan = resolved.get("plan") if resolved.get("resolved") else None+ if plan is not None:+ plan.setdefault("id", plan_id)+ plan["repository"] = reference_repositoryresult = {"mode": "refactoring_plan","plan_id": plan_id,- "plan": (- _serialize_refactoring(match, reference_repository)- if match- else None- ),- "resolved": match is not None,+ "plan": plan,+ "resolved": bool(resolved.get("resolved")),"_meta": _build_meta(repository=repository,- targets=[match.suggestion.file_path] if match else None,+ targets=[plan["file_path"]] if plan else None,),}- metric_rows = (- list(- (- await session.execute(- select(HealthFileMetric).where(- HealthFileMetric.repository_id == repository.id,- HealthFileMetric.file_path == match.suggestion.file_path,- )- )- ).scalars()+ if resolved.get("opportunity_id"):+ result["opportunity_id"] = resolved["opportunity_id"]+ result["next_action"] = resolved["next_action"]+ elif plan is not None:+ result["opportunity_note"] = (+ "This plan is addressable but is not a step of any composed "+ "opportunity; a demoted clone is supporting evidence, not work.")- if match- else []- )- _attach_health_analysis_meta(result["_meta"], metric_rows)+ await _attach_repository_analysis_meta(session, repository, result["_meta"])return resultall_metrics_q = select(HealthFileMetric).where(@@ -1784,11 +1995,18 @@ async def get_health(# asked for, scoped to the same targets, exclude-filtered like findings.refactoring_rows: list[Any] = []refactoring_recommendations: list[Recommendation] = []- if (- "refactoring" in include_set- and (wants("refactoring_plans") or wants("recommendation_lede"))- and not nothing_resolved- ):+ # Only when a caller names the plan list. ``include=["refactoring"]``+ # leads with composed opportunities now, and emitting both would ship+ # two representations of the same work in one response - 52k chars on+ # this repo, past the expanded budget, most of it duplicated. The+ # documented ``only=["refactoring_plans"]`` call is unchanged.+ plans_requested = "refactoring" in include_set and (+ "refactoring_plans" in only_set+ # The cross-pillar lede quotes one plan beside one performance+ # opportunity, and only when both pillars were asked for.+ or ({"performance", "refactoring"} <= include_set and wants("recommendation_lede"))+ )+ if plans_requested and not nothing_resolved:refactoring_rows = filter_rows_by_attr(await get_refactoring_suggestions(session,@@ -1803,7 +2021,7 @@ async def get_health(repository.id,refactoring_rows,metric_rows=all_metrics,- view=refactoring_view, # type: ignore[arg-type]+ view=plan_view(refactoring_view),)# The materialized causal read model. Filtering, ordering, paging, plan@@ -1812,6 +2030,22 @@ async def get_health(performance_service = PerformanceHealthService(session, repository.id, reference_repository)+ refactoring_service = RefactoringHealthService(+ session, repository.id, reference_repository+ )+ refactoring = await _refactoring_blocks(+ refactoring_service,+ wants=wants,+ included="refactoring" in include_set and wants_refactoring_opportunities,+ file_paths=tuple(effective_targets) if scoped else None,+ scoped=scoped,+ limit=limit,+ cursor=cursor,+ view=refactoring_view,+ lead_type=refactoring_type,+ confidence=refactoring_confidence,+ effort=refactoring_effort,+ )performance = await _performance_blocks(performance_service,wants=wants,@@ -2096,6 +2330,15 @@ async def get_health(# above is unchanged: performance findings carry no defect impact,# so they never competed for it and the dashboard said nothing an# agent could act on about them.+ # Two more additive leads, on the same terms: the block above ranks+ # files by health deficit and cannot say which composed work to do,+ # and it explicitly reports that no plan addresses the cause it+ # names on most files. These say what there is to do about it.+ **(+ {"refactoring_directive": refactoring.directive}+ if refactoring.directive is not None+ else {}+ ),**({"performance_directive": performance.directive}if performance.directive is not None@@ -2220,7 +2463,7 @@ async def get_health()result["test_findings_total"] = test_findings_total- if "refactoring" in include_set:+ if plans_requested:# Canonical is the shared REST/MCP/CLI order. File diversity remains# available only through the explicitly named ``file_spread`` view.validation_profiles: dict[str, dict[str, Any]] = {}@@ -2302,6 +2545,37 @@ async def get_health(if len(recent) > limit:result["trend"]["recent_reduced_reason"] = "limit"+ if refactoring.page is not None and wants("refactoring_opportunities"):+ result["refactoring_opportunities"] = refactoring.page.items+ result["refactoring_opportunities_total"] = refactoring.page.total+ result["refactoring_opportunities_emitted"] = len(refactoring.page.items)+ if len(refactoring.page.items) < refactoring.page.total:+ result["refactoring_opportunities_reduced_reason"] = (+ "collection_cap" if limit > _REFACTORING_COLLECTION_CAP else "limit"+ )+ if refactoring.page.next_offset is not None:+ page_recoveries["refactoring_opportunities"] = (+ refactoring.page.next_offset,+ _REFACTORING_COLLECTION_CAP,+ refactoring.page.total - refactoring.page.next_offset,+ )+ if refactoring.ignored:+ result["ignored_arguments"] = {+ **result.get("ignored_arguments", {}),+ **refactoring.ignored,+ }++ if refactoring.summary is not None:+ result["refactoring_summary"] = {+ **refactoring.summary,+ "facets": refactoring.page.facets if refactoring.page else {},+ "view": refactoring_view,+ "next_call": (+ "get_health(include=['refactoring'], "+ "only=['refactoring_opportunities'], limit=6)"+ ),+ }+if performance.page is not None and wants("performance_opportunities"):result["performance_opportunities"] = performance.page.itemsresult["performance_opportunities_total"] = performance.page.total@@ -2579,7 +2853,13 @@ async def get_health(# dashboard (no targets) keeps the repo-level warning.result["_meta"] = _build_meta(repository=repository, targets=targets if targets else None)analyzed_source = metric_rows if scoped else all_metrics- _attach_health_analysis_meta(result["_meta"], analyzed_source)+ if scoped:+ # Scoped calls used to answer repository freshness from the caller's own+ # files, which is how the same repo read ``available`` and ``degraded``+ # in the same second depending on which mode answered.+ await _attach_repository_analysis_meta(session, repository, result["_meta"])+ else:+ _attach_health_analysis_meta(result["_meta"], analyzed_source)# Server-side wall clock, as ``get_context`` already reports. Without it a# regression in here is invisible until someone profiles it by hand.for label, dropped in semantic_omissions.items():diff --git a/packages/server/src/repowise/server/routers/refactoring.py b/packages/server/src/repowise/server/routers/refactoring.pyindex 295105e2f..293792603 100644--- a/packages/server/src/repowise/server/routers/refactoring.py+++ b/packages/server/src/repowise/server/routers/refactoring.py@@ -27,6 +27,16 @@ from repowise.core.analysis.health.refactoring.recommendations import (from repowise.core.persistence import crudfrom repowise.core.persistence.crud.analysis.refactoring import ALLOWED_STATUSESfrom repowise.server.deps import get_db_session, verify_api_key+from repowise.server.services.refactoring_health import (+ CANONICAL_ORDERS,+ CANONICAL_VIEWS,+ DEFAULT_VIEW,+ RefactoringHealthService,+ parse_query,+)++_STEPS_PER_ROW = 3+"""Steps carried on a queue row; the detail call pages the rest."""router = APIRouter(prefix="/api/repos",@@ -371,6 +381,93 @@ async def _local_repo_path(session: AsyncSession, repo_id: str) -> Path:return repo_path+# ---------------------------------------------------------------------------+# Composed opportunities. Thin adapters: filtering, ordering, paging, facets+# and detail all live in ``services/refactoring_health.py``, which the MCP+# surface reads through as well, so the two cannot answer differently.+# ---------------------------------------------------------------------------+++def _service(session: AsyncSession, repo_id: str) -> RefactoringHealthService:+ return RefactoringHealthService(session, repo_id, repo_id)++[email protected]("/{repo_id}/refactoring/opportunities")+async def get_refactoring_opportunities(+ repo_id: str,+ refactoring_type: str | None = Query(None, description="Filter by lead refactoring type"),+ confidence: str | None = Query(None, description="low | medium | high"),+ effort: str | None = Query(None, description="S | M | L | XL"),+ file_path: str | None = Query(None, description="One repo-relative file path"),+ mechanical: bool = Query(False, description="Only opportunities with a mechanical step"),+ view: str = Query(DEFAULT_VIEW, description=" | ".join(CANONICAL_VIEWS)),+ order: str | None = Query(None, description=" | ".join(CANONICAL_ORDERS)),+ limit: int = Query(20, ge=1, le=100),+ offset: int = Query(0, ge=0),+ session: AsyncSession = Depends(get_db_session),+) -> dict[str, Any]:+ """One page of composed opportunities, with facets and the rollup."""+ query, ignored = parse_query(+ lead_type=refactoring_type,+ confidence=confidence,+ effort=effort,+ mechanical=mechanical,+ file_paths=[file_path] if file_path else None,+ view=view,+ order=order,+ limit=limit,+ offset=offset,+ )+ page = await _service(session, repo_id).page(+ query, steps_per_item=_STEPS_PER_ROW, with_facets=True, with_summary=True+ )+ body: dict[str, Any] = {+ "items": page.items,+ "total": page.total,+ "offset": page.offset,+ "has_more": page.next_offset is not None,+ "next_offset": page.next_offset,+ "facets": page.facets,+ "summary": page.summary,+ }+ if ignored:+ body["ignored_arguments"] = ignored+ return body++[email protected]("/{repo_id}/refactoring/summary")+async def get_refactoring_rollup(+ repo_id: str,+ session: AsyncSession = Depends(get_db_session),+) -> dict[str, Any]:+ """The repository rollup and its one lead, by primary key."""+ service = _service(session, repo_id)+ return {"summary": await service.summary(), "directive": await service.directive()}++[email protected]("/{repo_id}/refactoring/opportunities/{opportunity_id}")+async def get_refactoring_opportunity_detail(+ repo_id: str,+ opportunity_id: str,+ step_limit: int = Query(20, ge=0, le=200),+ step_offset: int = Query(0, ge=0),+ evidence_limit: int = Query(8, ge=0, le=200),+ evidence_offset: int = Query(0, ge=0),+ session: AsyncSession = Depends(get_db_session),+) -> dict[str, Any]:+ """One opportunity: its ordered steps, evidence, validation and plans."""+ detail = await _service(session, repo_id).detail(+ opportunity_id,+ step_limit=step_limit,+ step_offset=step_offset,+ evidence_limit=evidence_limit,+ evidence_offset=evidence_offset,+ )+ if not detail.get("resolved"):+ raise HTTPException(status_code=404, detail="Unknown opportunity id")+ return detail++@router.get("/{repo_id}/refactoring/settings", response_model=RefactoringSettings)async def get_refactoring_settings(repo_id: str,diff --git a/packages/server/src/repowise/server/services/refactoring_health.py b/packages/server/src/repowise/server/services/refactoring_health.pynew file mode 100644index 000000000..32473c9ad--- /dev/null+++ b/packages/server/src/repowise/server/services/refactoring_health.py@@ -0,0 +1,655 @@+"""One read model for refactoring opportunities, shared by REST and MCP.++Both surfaces used to load every open plan, hydrate it, rank it and page it in+Python, and they disagreed about almost everything they did with the result:+different filter vocabularies, two incompatible pagination contracts, and two+ways of resolving one id - REST an indexed point lookup, MCP a full hydration+followed by a linear scan. Query, filter, order, page, facets, detail and the+directive live here now, so the agent surface and the product surface cannot+drift apart.++Nothing in this module composes or ranks. Composition is+``analysis/health/refactoring/opportunity.py`` and it runs at index time; this+module reads what the finalizer wrote.+"""++from __future__ import annotations++import json+from dataclasses import dataclass, field+from typing import Any, Literal++from sqlalchemy import or_, select+from sqlalchemy.ext.asyncio import AsyncSession++from repowise.core.persistence.crud.analysis.refactoring_opportunities import (+ get_refactoring_opportunity,+ get_refactoring_summary,+ list_refactoring_opportunities,+ refactoring_facet_counts,+)+from repowise.core.persistence.models import RefactoringOpportunity, RefactoringSuggestion++# ``refactoring_view`` predates the opportunity. Both old values keep working+# and both are documented in docs/layers/REFACTORING.md:+#+# - ``canonical`` the published rank order, ties and all. What the old default+# produced, kept for a caller that wants the score order verbatim.+# - ``file_spread`` asked for one row per file. An opportunity *is* one file's+# work, so the spread is now satisfied by construction; the value maps onto+# the diversified order, which is what it was reaching for.+# - ``diversified`` the new default. Rank order round-robined over cause and+# directory, because the ranked head is a genuine run of ties.+_VIEW_ORDERS: dict[str, str] = {+ "canonical": "rank",+ "file_spread": "queue",+ "diversified": "queue",+}+CANONICAL_VIEWS = tuple(_VIEW_ORDERS)+DEFAULT_VIEW = "diversified"++# The legacy plan list has no notion of the diversified order, so the new+# default resolves to the value that list has always defaulted to.+_PLAN_VIEWS = {"canonical": "canonical", "file_spread": "file_spread", "diversified": "canonical"}++CANONICAL_ORDERS = ("queue", "rank", "health", "effort", "file")+_CONFIDENCES = ("low", "medium", "high")+_EFFORTS = ("S", "M", "L", "XL")+_TYPES = (+ "break_cycle",+ "extract_class",+ "extract_helper",+ "extract_method",+ "move_method",+ "split_file",+)++_UNAVAILABLE = {+ "status": "unavailable",+ "reason": "no_refactoring_analysis",+ "detail": "No refactoring analysis is stored for this repository. Run `repowise update`.",+}+++@dataclass(frozen=True, slots=True)+class RefactoringQuery:+ """A normalized queue request. The only shape either adapter passes down."""++ lead_type: str | None = None+ confidence: str | None = None+ effort: str | None = None+ mechanical_only: bool = False+ addresses_primary: bool | None = None+ file_paths: tuple[str, ...] | None = None+ view: str = DEFAULT_VIEW+ order: str | None = None+ limit: int = 20+ offset: int = 0++ @property+ def resolved_order(self) -> str:+ """An explicit ``order`` wins; otherwise the view picks one."""+ if self.order in CANONICAL_ORDERS:+ return self.order+ return _VIEW_ORDERS.get(self.view, _VIEW_ORDERS[DEFAULT_VIEW])+++@dataclass(frozen=True, slots=True)+class RefactoringPage:+ items: list[dict[str, Any]]+ total: int+ offset: int+ next_offset: int | None+ facets: dict[str, dict[str, int]] = field(default_factory=dict)+ summary: dict[str, Any] | None = None+ ignored_arguments: dict[str, str] = field(default_factory=dict)+++def parse_query(+ *,+ lead_type: str | None = None,+ confidence: str | None = None,+ effort: str | None = None,+ mechanical: bool | None = None,+ addresses_primary: bool | None = None,+ file_paths: list[str] | tuple[str, ...] | None = None,+ view: str | None = None,+ order: str | None = None,+ limit: int = 20,+ offset: int = 0,+) -> tuple[RefactoringQuery, dict[str, str]]:+ """Normalize a caller's arguments, naming anything it had to discard.++ An unrecognized value is reported back rather than silently treated as "no+ filter": a caller who misspells a type should not be told the repository is+ clean.+ """+ ignored: dict[str, str] = {}++ def admit(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:+ if value is None:+ return None+ if value in allowed:+ return value+ ignored[name] = value+ return None++ resolved_view = view or DEFAULT_VIEW+ if resolved_view not in _VIEW_ORDERS:+ ignored["refactoring_view"] = resolved_view+ resolved_view = DEFAULT_VIEW+ return (+ RefactoringQuery(+ lead_type=admit("refactoring_type", lead_type, _TYPES),+ confidence=admit("confidence", confidence, _CONFIDENCES),+ effort=admit("effort", effort, _EFFORTS),+ mechanical_only=bool(mechanical),+ addresses_primary=addresses_primary,+ file_paths=tuple(file_paths) if file_paths else None,+ view=resolved_view,+ order=admit("order", order, CANONICAL_ORDERS),+ limit=max(int(limit), 0),+ offset=max(int(offset), 0),+ ),+ ignored,+ )+++def plan_view(view: str | None) -> Literal["canonical", "file_spread"]:+ """The legacy plan list's view for a caller's ``refactoring_view``."""+ return _PLAN_VIEWS.get(view or DEFAULT_VIEW, "canonical") # type: ignore[return-value]+++def evidence_block(+ evidence: list[dict[str, Any]], total: int, offset: int+) -> dict[str, Any]:+ """One evidence page plus the exact call that reads the rest."""+ emitted = len(evidence)+ block: dict[str, Any] = {+ "evidence": evidence,+ "evidence_total": total,+ "evidence_emitted": emitted,+ "evidence_truncated": offset + emitted < total,+ }+ if block["evidence_truncated"]:+ block["evidence_reduced_reason"] = "evidence_page"+ block["evidence_next_cursor"] = offset + emitted+ return block+++class RefactoringHealthService:+ """Query, page, detail and headline over the materialized opportunities."""++ def __init__(self, session: AsyncSession, repository_id: str, repository: str) -> None:+ self._session = session+ self._repository_id = repository_id+ self._repository = repository++ # -- queue ------------------------------------------------------------++ async def page(+ self,+ query: RefactoringQuery,+ *,+ steps_per_item: int | None = None,+ evidence_per_item: int = 0,+ with_facets: bool = False,+ with_summary: bool = False,+ ) -> RefactoringPage:+ """One page: two statements, plus one each for facets and the headline.++ The statement count is constant in page size and in row count. The+ indexes cover repository, status and the orderings, plus lead type and+ file path; ``mechanical_only`` and ``addresses_primary`` are residual+ filters over the open set, so those two are bounded by the open row+ count rather than by the page. Neither has a consumer yet - index them+ when one exists, not before.+ """+ rows, total = await list_refactoring_opportunities(+ self._session,+ self._repository_id,+ lead_type=query.lead_type,+ confidence=query.confidence,+ effort=query.effort,+ file_paths=list(query.file_paths) if query.file_paths else None,+ mechanical_only=query.mechanical_only,+ addresses_primary=query.addresses_primary,+ order=query.resolved_order,+ limit=query.limit,+ offset=query.offset,+ )+ items = [+ self._serialize(row, steps_limit=steps_per_item, evidence_limit=evidence_per_item)+ for row in rows+ ]+ next_offset = query.offset + len(items)+ return RefactoringPage(+ items=items,+ total=total,+ offset=query.offset,+ next_offset=next_offset if next_offset < total else None,+ facets=(+ await refactoring_facet_counts(self._session, self._repository_id)+ if with_facets+ else {}+ ),+ summary=await self.summary() if with_summary else None,+ )++ # -- headline ---------------------------------------------------------++ async def summary(self) -> dict[str, Any]:+ """The Level-1 rollup, read by primary key."""+ row = await get_refactoring_summary(self._session, self._repository_id)+ if row is None:+ return dict(_UNAVAILABLE)+ payload = _loads(row.summary_json)+ payload["status"] = "available"+ payload["refactoring_model_version"] = row.refactoring_model_version+ payload["analyzed_commit"] = row.analyzed_commit+ return payload++ async def directive(self) -> dict[str, Any]:+ """The Level-0 lead: one opportunity, and the exact call that opens it.++ The same primary-key read the summary uses, so a bare dashboard pays one+ statement for it and never touches the queue.+ """+ row = await get_refactoring_summary(self._session, self._repository_id)+ if row is None:+ return dict(_UNAVAILABLE)+ payload = _loads(row.summary_json)+ lead = payload.get("lead")+ if not lead:+ return {+ "status": "clear",+ "reason": "no_open_opportunities",+ "detail": "No refactoring opportunity is open for this repository.",+ "opportunities_total": int(payload.get("opportunities_total") or 0),+ }+ addresses = lead.get("addresses_primary_problem")+ directive: dict[str, Any] = {+ "status": "available",+ "opportunity_id": lead.get("opportunity_id"),+ "fix_first": lead.get("file_path"),+ "reason": lead.get("lead_biomarker"),+ "lead_refactoring_type": lead.get("lead_refactoring_type"),+ "steps": lead.get("step_count"),+ "mechanical_steps": lead.get("mechanical_steps"),+ "judgment_steps": lead.get("judgment_steps"),+ "effort_bucket": lead.get("effort_bucket"),+ "confidence": lead.get("confidence"),+ "recovers_health_points": lead.get("recoverable_health"),+ "addresses_primary_problem": addresses,+ "opportunities_total": int(payload.get("opportunities_total") or 0),+ "next_action": {+ "tool": "get_health",+ "arguments": {"opportunity_id": lead.get("opportunity_id")},+ },+ }+ # The honest half. A file's plans very often answer a different question+ # from the one that made it the worst file, and saying so beats routing+ # an agent to cleanup it will read as the fix.+ if addresses is False:+ directive["note"] = (+ f"These steps do not address {lead.get('lead_biomarker')!r}, this file's "+ "dominant finding. Treat them as related cleanup, not the fix for it."+ )+ elif addresses is None:+ directive["note"] = (+ "No dominant finding was recorded for this file, so whether these steps "+ "address it is unknown rather than no."+ )+ return directive++ # -- detail -----------------------------------------------------------++ async def detail(+ self,+ opportunity_id: str,+ *,+ step_limit: int = 20,+ step_offset: int = 0,+ evidence_limit: int = 3,+ evidence_offset: int = 0,+ with_plans: bool = True,+ ) -> dict[str, Any]:+ """One opportunity by id: an indexed seek, then its member plans."""+ row = await get_refactoring_opportunity(+ self._session, self._repository_id, opportunity_id+ )+ if row is None:+ return {+ "resolved": False,+ "opportunity_id": opportunity_id,+ "reason": "unknown_opportunity_id",+ }+ details = _loads(row.details_json)+ steps = list(details.get("steps") or [])+ page = steps[step_offset : step_offset + max(step_limit, 0)]+ payload = self._serialize(row, steps_limit=None, evidence_limit=0)+ payload["resolved"] = True+ payload["steps"] = page+ payload["steps_total"] = len(steps)+ payload["steps_emitted"] = len(page)+ if step_offset + len(page) < len(steps):+ payload["steps_reduced_reason"] = "limit"+ payload["steps_next_cursor"] = step_offset + len(page)+ evidence = list(details.get("evidence") or [])+ payload.update(+ evidence_block(+ evidence[evidence_offset : evidence_offset + max(evidence_limit, 0)],+ len(evidence),+ evidence_offset,+ )+ )+ payload["validation_profiles"] = list(details.get("validation_profiles") or [])+ payload["affected_files"] = list(details.get("affected_files") or [])+ payload["lead_finding_ids"] = list(details.get("lead_finding_ids") or [])+ payload["next_actions"] = self._next_actions(row, page)+ if with_plans and page:+ payload["plans"] = await self._plans_for([s["plan_id"] for s in page])+ # Ordered steps carry ``relocated_by``; a surface that renders them must+ # say the symbol has to be located again before the step is applied.+ if any(step.get("relocated_by") for step in page):+ payload["ordering_note"] = (+ "A step carrying `relocated_by` names a symbol an earlier step moves. "+ "Locate it again before applying the step; its file and span describe "+ "where the symbol was."+ )+ return payload++ async def plan_detail(self, plan_id: str) -> dict[str, Any]:+ """Resolve one plan id without hydrating the repository.++ Every read is a seek. The row comes from the storage-or-public id index,+ its rank inputs from the one metric row and the one file's centrality,+ and its validation from the profile the finalizer already resolved. The+ payload is built by the same ``build_recommendations`` every surface+ uses, so it is field-identical to the hydrated form; what is gone is the+ two full-table reads and the test-reachability walk that made resolving+ one id cost the repository.+ """+ from repowise.core.analysis.health.refactoring.recommendations import (+ build_recommendations,+ rehydrate_suggestion,+ )+ from repowise.core.persistence.crud import get_refactoring_suggestion++ row = await get_refactoring_suggestion(self._session, self._repository_id, plan_id)+ if row is None:+ return {"resolved": False, "plan_id": plan_id, "reason": "unknown_plan_id"}+ owner = await self._owning_opportunity(row.public_id, row.file_path)+ metric_by_path, centrality = await self._rank_inputs(row.file_path)+ built = build_recommendations(+ [rehydrate_suggestion(row)],+ metric_by_path=metric_by_path,+ centrality=centrality,+ validations={0: _stored_validation(owner, row.public_id)},+ )+ payload = built[0].as_dict() if built else _plan_payload(row)+ payload["id"] = row.public_id or row.id+ payload["status"] = row.status+ result: dict[str, Any] = {"resolved": True, "plan_id": plan_id, "plan": payload}+ if owner is not None:+ # On the envelope as well as the plan: a plan is a step of one+ # opportunity, and that is the unit the caller should move to.+ payload["opportunity_id"] = owner.opportunity_id+ result["opportunity_id"] = owner.opportunity_id+ result["next_action"] = {+ "tool": "get_health",+ "arguments": {"opportunity_id": owner.opportunity_id},+ }+ return result++ async def _rank_inputs(self, file_path: str) -> tuple[dict[str, Any], dict[str, float]]:+ """The two rank inputs for one file, as seeks rather than repo reads.++ ``build_recommendations`` wants a metric per path and an in-degree per+ node. Serving one plan used to load every metric row and every graph+ metric in the repository to supply them for a single file.+ """+ from repowise.core.persistence.models import GraphMetric, HealthFileMetric++ metric = (+ await self._session.execute(+ select(HealthFileMetric).where(+ HealthFileMetric.repository_id == self._repository_id,+ HealthFileMetric.file_path == file_path,+ )+ )+ ).scalar_one_or_none()+ rows = (+ await self._session.execute(+ select(GraphMetric.node_id, GraphMetric.in_degree).where(+ GraphMetric.repository_id == self._repository_id,+ or_(+ GraphMetric.node_id == file_path,+ # The separator matters: a bare ``f"{file_path}%"`` also+ # matches a sibling whose name extends this one, so+ # ``Component.ts`` would absorb ``Component.tsx``.+ GraphMetric.node_id.like(f"{file_path}::%"),+ ),+ )+ )+ ).all()+ return (+ {metric.file_path: metric} if metric is not None else {},+ {node_id: float(in_degree or 0.0) for node_id, in_degree in rows},+ )++ # -- internals --------------------------------------------------------++ async def _owning_opportunity(self, public_id: str | None, file_path: str) -> Any | None:+ """The opportunity holding this plan, found through its file.++ One indexed lookup on ``(repository_id, status, file_path)``: a plan+ belongs to at most one file's opportunity, so the file narrows it to a+ single candidate and the step list confirms it.+ """+ if not public_id:+ return None+ rows = list(+ (+ await self._session.execute(+ select(RefactoringOpportunity)+ .where(+ RefactoringOpportunity.repository_id == self._repository_id,+ RefactoringOpportunity.status == "open",+ RefactoringOpportunity.file_path == file_path,+ )+ .limit(5)+ )+ )+ .scalars()+ .all()+ )+ for row in rows:+ steps = _loads(row.details_json).get("steps") or []+ if any(step.get("plan_id") == public_id for step in steps):+ return row+ return None++ async def _plans_for(self, plan_ids: list[str]) -> list[dict[str, Any]]:+ """The member plans' payloads, in one indexed query over the page."""+ if not plan_ids:+ return []+ rows = list(+ (+ await self._session.execute(+ select(RefactoringSuggestion).where(+ RefactoringSuggestion.repository_id == self._repository_id,+ RefactoringSuggestion.public_id.in_(plan_ids),+ )+ )+ )+ .scalars()+ .all()+ )+ by_id = {row.public_id: row for row in rows}+ return [_plan_payload(by_id[pid]) for pid in plan_ids if pid in by_id]++ def _next_actions(self, row: Any, steps: list[dict[str, Any]]) -> list[dict[str, Any]]:+ """Structured follow-ups, so a drill-down ends somewhere rather than stops."""+ actions: list[dict[str, Any]] = []+ first = steps[0] if steps else None+ if first and first.get("line_start") is not None and first.get("line_end") is not None:+ actions.append(+ {+ "why": "read the span the first step names",+ "tool": "get_symbol",+ "arguments": {+ "symbol_id": f"{first['file_path']}:{first['line_start']}-{first['line_end']}"+ },+ }+ )+ actions.append(+ {+ "why": "what history says about touching this file",+ "tool": "get_risk",+ "arguments": {"targets": [row.file_path]},+ }+ )+ if row.evidence_total:+ actions.append(+ {+ "why": "page the supporting observations",+ "tool": "get_health",+ "arguments": {+ "opportunity_id": row.opportunity_id,+ "only": ["refactoring_evidence"],+ },+ }+ )+ return actions++ def _serialize(+ self, row: Any, *, steps_limit: int | None = None, evidence_limit: int = 0+ ) -> dict[str, Any]:+ details = _loads(row.details_json)+ steps = list(details.get("steps") or [])+ evidence = list(details.get("evidence") or [])+ payload: dict[str, Any] = {+ "opportunity_id": row.opportunity_id,+ "refactoring_model_version": row.refactoring_model_version,+ "status": row.status,+ "file_path": row.file_path,+ "lead_biomarker": row.lead_biomarker,+ "lead_refactoring_type": row.lead_refactoring_type,+ "addresses_primary_problem": row.addresses_primary_problem,+ "effort_bucket": row.effort_bucket,+ "confidence": row.confidence,+ "step_count": row.step_count,+ "mechanical_steps": row.mechanical_steps,+ "judgment_steps": row.judgment_steps,+ "evidence_total": row.evidence_total,+ "affected_files_total": row.affected_files_total,+ "recoverable_health": round(float(row.recoverable_health), 3),+ "rank_score": round(float(row.rank_score), 4),+ "rank_position": row.rank_position,+ "queue_position": row.queue_position,+ "rank_factors": details.get("rank_factors") or {},+ "why_ranked": details.get("why_ranked") or [],+ }+ if steps_limit is not None:+ kept = steps[: max(steps_limit, 0)]+ payload["steps"] = kept+ payload["steps_total"] = len(steps)+ payload["steps_emitted"] = len(kept)+ if len(kept) < len(steps):+ payload["steps_reduced_reason"] = "limit"+ if evidence_limit:+ payload.update(evidence_block(evidence[:evidence_limit], len(evidence), 0))+ return payload+++def _stored_validation(owner: Any, public_id: str | None) -> Any:+ """The validation profile the finalizer resolved for this step.++ Test reachability is a graph walk over the whole unanswered set; it belongs+ at index time, and this reads its result rather than repeating it.+ """+ from repowise.core.analysis.health.refactoring.recommendations import (+ ValidationPlan,+ ValidationTarget,+ )++ if owner is None or not public_id:+ return None+ details = _loads(owner.details_json)+ wanted = next(+ (+ step.get("validation_profile_id")+ for step in (details.get("steps") or [])+ if step.get("plan_id") == public_id+ ),+ None,+ )+ if not wanted:+ return None+ profile = next(+ (p for p in (details.get("validation_profiles") or []) if p.get("id") == wanted),+ None,+ )+ if profile is None:+ return None+ target_fields = set(ValidationTarget.__dataclass_fields__)+ values = {+ key: value+ for key, value in profile.items()+ if key in ValidationPlan.__dataclass_fields__+ }+ values["targets"] = [+ ValidationTarget(**{k: v for k, v in target.items() if k in target_fields})+ for target in (profile.get("targets") or [])+ if isinstance(target, dict)+ ]+ return ValidationPlan(**values)+++def _plan_payload(row: Any) -> dict[str, Any]:+ """The stored plan, without re-hydrating rank or validation.++ Detail reads the payload the detector wrote and the finalizer already+ validated; recomputing benefit and coverage here is what made a one-row+ lookup cost the repository.+ """+ return {+ "id": row.public_id or row.id,+ "refactoring_type": row.refactoring_type,+ "file_path": row.file_path,+ "target_symbol": row.target_symbol,+ "line_start": row.line_start,+ "line_end": row.line_end,+ "plan": _loads(row.plan_json),+ "evidence": _loads(row.evidence_json),+ "blast_radius": _loads(row.blast_radius_json),+ "impact_delta": row.impact_delta,+ "effort_bucket": row.effort_bucket,+ "confidence": row.confidence,+ "source_biomarker": row.source_biomarker,+ "status": row.status,+ }+++def _loads(raw: str | None) -> dict[str, Any]:+ if not raw:+ return {}+ try:+ value = json.loads(raw)+ except (TypeError, ValueError):+ return {}+ return value if isinstance(value, dict) else {}+++__all__ = [+ "CANONICAL_ORDERS",+ "CANONICAL_VIEWS",+ "DEFAULT_VIEW",+ "RefactoringHealthService",+ "RefactoringPage",+ "RefactoringQuery",+ "evidence_block",+ "parse_query",+ "plan_view",+]diff --git a/packages/types/src/refactoring.ts b/packages/types/src/refactoring.tsindex c877e423c..912bfdc1a 100644--- a/packages/types/src/refactoring.ts+++ b/packages/types/src/refactoring.ts@@ -115,3 +115,241 @@ export interface GeneratedCode {validation: Record<string, unknown>;spans: GeneratedSpan[];}++/* ---------------------------------------------------------------------------+ * Composed opportunities (repowise 0.47.0).+ *+ * The product unit is a file's composed refactoring: the diagnosis it leads+ * with, its steps in an order that is safe to apply, and the observations+ * behind it. Plans remain addressable and unchanged; a step names one.+ * Every field here is additive, so an older server simply omits the block.+ * ------------------------------------------------------------------------ */++/** ``mechanical`` only when the detector's proof obligations all hold. */+export type StepClassification = "mechanical" | "judgment";++export interface StepApplicability {+ classification: StepClassification;+ /** Closed vocabulary; see docs/layers/REFACTORING.md. */+ reasons: string[];+ facts: Record<string, unknown>;+ /** Facts the layer could not establish. Never silently false. */+ unknowns: string[];+}++export interface OpportunityStep {+ /** The plan this step is; resolves through the plan detail route. */+ plan_id: string;+ refactoring_type: RefactoringType;+ target_symbol: string;+ file_path: string;+ line_start: number | null;+ line_end: number | null;+ effort_bucket: EffortBucket;+ confidence: Confidence;+ impact_delta: number;+ source_biomarker: string;+ /**+ * An earlier step that moves this step's symbol to another file. When set,+ * this step's file and span say where the symbol was: locate it again before+ * applying. Any surface rendering an ordered list has to say so.+ */+ relocated_by: string | null;+ applicability: StepApplicability;+ /** Findings this step's cause produced, for a round trip to the diagnosis. */+ finding_ids?: string[];+ validation_profile_id?: string;+}++/** A supporting observation. Never an instruction to change anything. */+export interface OpportunityEvidence {+ plan_id: string;+ refactoring_type: RefactoringType;+ target_symbol: string;+ source_biomarker: string;+ summary: Record<string, unknown>;+}++export type OpportunityStatus = "open" | "acknowledged" | "resolved";++export interface RefactoringOpportunity {+ /** ``refop<model>_<digest>`` over the member plan ids. */+ opportunity_id: string;+ refactoring_model_version: number;+ status: OpportunityStatus;+ file_path: string;+ /** The file's dominant finding; null when none was recorded. */+ lead_biomarker: string | null;+ lead_refactoring_type: RefactoringType | "";+ /**+ * Tri-state. ``null`` means no dominant finding was available to compare+ * against, which is not the same claim as ``false``.+ */+ addresses_primary_problem: boolean | null;+ effort_bucket: EffortBucket;+ confidence: Confidence;+ step_count: number;+ mechanical_steps: number;+ judgment_steps: number;+ evidence_total: number;+ affected_files_total: number;+ recoverable_health: number;+ rank_score: number;+ rank_position: number;+ /** Position in the diversified default order. */+ queue_position: number;+ rank_factors: Record<string, number>;+ why_ranked: Array<{ factor: string; value: number }>;+ steps?: OpportunityStep[];+ steps_total?: number;+ steps_emitted?: number;+ steps_reduced_reason?: string;+ /** Present only when the queue row was asked for inline evidence. */+ evidence?: OpportunityEvidence[];+ evidence_emitted?: number;+ evidence_truncated?: boolean;+ evidence_reduced_reason?: string;+ evidence_next_cursor?: number;+}++/**+ * A detail lookup either resolved or did not; the two shapes share nothing but+ * the discriminant, so narrow on `resolved` before reading anything else.+ * REST 404s on the unresolved branch, MCP returns it verbatim.+ */+export type RefactoringOpportunityDetail =+ | RefactoringOpportunityDetailResolved+ | RefactoringOpportunityDetailUnresolved;++export interface RefactoringOpportunityDetailUnresolved {+ resolved: false;+ opportunity_id: string;+ reason: "unknown_opportunity_id";+ /** MCP only: tells a stale-model id apart from one never minted here. */+ model_state?: {+ state: "current" | "stale_model" | "unrecognized";+ public_id: string;+ requested_model_version: number | null;+ refactoring_model_version: number;+ refresh_required: boolean;+ };+}++export interface RefactoringOpportunityDetailResolved extends RefactoringOpportunity {+ resolved: true;+ steps: OpportunityStep[];+ steps_total: number;+ steps_emitted: number;+ steps_reduced_reason?: string;+ steps_next_cursor?: number;+ evidence: OpportunityEvidence[];+ evidence_emitted: number;+ evidence_truncated: boolean;+ evidence_reduced_reason?: string;+ evidence_next_cursor?: number;+ affected_files: string[];+ /** Absent when no finding on this file is addressable by id. */+ lead_finding_ids?: string[];+ validation_profiles: Array<{ id: string } & RecommendationValidation>;+ /** The member plans' payloads, so the steps are executable in one call. */+ plans: RefactoringPlan[];+ next_actions: Array<{ why: string; tool: string; arguments: Record<string, unknown> }>;+ /** Present only when a step carries `relocated_by`. */+ ordering_note?: string;+}++/** Named orderings for the queue. ``diversified`` is the default. */+export type RefactoringView = "diversified" | "canonical" | "file_spread";++/** No stored analysis: the counts genuinely do not exist, so none are present. */+export interface RefactoringRollupUnavailable {+ status: "unavailable";+ reason: "no_refactoring_analysis";+ detail: string;+}++export interface RefactoringRollupAvailable {+ status: "available";+ opportunities_total: number;+ files_total: number;+ steps_total: number;+ mechanical_steps_total: number;+ judgment_steps_total: number;+ by_lead_type: Record<string, number>;+ by_effort: Record<string, number>;+ by_confidence: Record<string, number>;+ by_status: Record<string, number>;+ addresses_primary_problem: { yes: number; no: number; unknown: number };+ /** The same lead the directive reads; null when nothing is open. */+ lead: RefactoringDirectiveLead | null;+ refactoring_model_version: number;+ analyzed_commit: string | null;+ /** Present on the MCP block only. */+ facets?: Record<string, Record<string, number>>;+ next_call?: string;+}++export type RefactoringOpportunityRollup =+ | RefactoringRollupAvailable+ | RefactoringRollupUnavailable;++export interface RefactoringDirectiveLead {+ opportunity_id: string;+ file_path: string;+ lead_biomarker: string | null;+ lead_refactoring_type: string;+ addresses_primary_problem: boolean | null;+ step_count: number;+ mechanical_steps: number;+ judgment_steps: number;+ effort_bucket: EffortBucket;+ confidence: Confidence;+ recoverable_health: number;+ status: OpportunityStatus;+}++/**+ * The Level-0 lead on a bare health call. Three shapes, one discriminant:+ * there is work, there is none, or there is no analysis to answer from.+ */+export type RefactoringDirective =+ | RefactoringDirectiveAvailable+ | { status: "clear"; reason: "no_open_opportunities"; detail: string; opportunities_total: number }+ | RefactoringRollupUnavailable;++export interface RefactoringDirectiveAvailable {+ status: "available";+ opportunity_id: string;+ fix_first: string;+ reason: string | null;+ lead_refactoring_type: string;+ steps: number;+ mechanical_steps: number;+ judgment_steps: number;+ effort_bucket: EffortBucket;+ confidence: Confidence;+ recovers_health_points: number;+ addresses_primary_problem: boolean | null;+ opportunities_total: number;+ next_action: { tool: string; arguments: Record<string, unknown> };+ /** Set when the steps do not address the file's dominant finding, or cannot say. */+ note?: string;+}++export interface RefactoringOpportunityPage {+ items: RefactoringOpportunity[];+ total: number;+ offset: number;+ has_more: boolean;+ next_offset: number | null;+ facets: Record<string, Record<string, number>>;+ summary: RefactoringOpportunityRollup | null;+ /** Values the server could not admit, named rather than dropped. */+ ignored_arguments?: Record<string, string>;+}++/** ``GET /api/repos/{repo_id}/refactoring/summary``. */+export interface RefactoringSummaryResponse {+ summary: RefactoringOpportunityRollup;+ directive: RefactoringDirective;+}diff --git a/tests/unit/persistence/test_refactoring_opportunity_store.py b/tests/unit/persistence/test_refactoring_opportunity_store.pynew file mode 100644index 000000000..72b6f38fd--- /dev/null+++ b/tests/unit/persistence/test_refactoring_opportunity_store.py@@ -0,0 +1,95 @@+"""The materialized opportunity store: migration shape and model agreement."""++from __future__ import annotations++import sqlite3+from pathlib import Path+++def _tables(db_path: Path) -> set[str]:+ conn = sqlite3.connect(db_path)+ try:+ return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}+ finally:+ conn.close()+++def _columns(db_path: Path, table: str) -> set[str]:+ conn = sqlite3.connect(db_path)+ try:+ return {row[1] for row in conn.execute(f'PRAGMA table_info("{table}")')}+ finally:+ conn.close()+++def _indexes(db_path: Path, table: str) -> set[str]:+ conn = sqlite3.connect(db_path)+ try:+ return {row[1] for row in conn.execute(f'PRAGMA index_list("{table}")')}+ finally:+ conn.close()+++def _alembic_config(db_path: Path):+ from alembic.config import Config++ root = Path(__file__).resolve().parents[3] / "packages" / "core"+ # Built without the ini file on purpose; see the performance store's twin.+ config = Config()+ config.set_main_option("script_location", str(root / "alembic"))+ config.set_main_option("sqlalchemy.url", f"sqlite+aiosqlite:///{db_path}")+ return config+++def test_the_migration_upgrades_and_rolls_back(tmp_path: Path) -> None:+ from alembic import command++ db_path = tmp_path / "wiki.db"+ config = _alembic_config(db_path)++ command.upgrade(config, "0059")+ assert {"refactoring_opportunities", "refactoring_summaries"} <= _tables(db_path)+ assert {+ "opportunity_id",+ "refactoring_model_version",+ "status",+ "rank_position",+ "queue_position",+ "addresses_primary_problem",+ "details_json",+ } <= _columns(db_path, "refactoring_opportunities")++ command.downgrade(config, "0058")+ assert not {"refactoring_opportunities", "refactoring_summaries"} & _tables(db_path)+++def test_the_migration_and_the_model_declare_the_same_shape(tmp_path: Path) -> None:+ """A local store is built by ``init_db`` and never sees Alembic.++ So the two descriptions have to agree, or a hosted store and a local one+ disagree about the table this phase serves everything from.+ """+ import asyncio++ from alembic import command++ from repowise.core.persistence.database import create_engine, init_db++ migrated = tmp_path / "migrated.db"+ command.upgrade(_alembic_config(migrated), "head")++ declared = tmp_path / "declared.db"++ async def _build() -> None:+ engine = create_engine(f"sqlite+aiosqlite:///{declared}")+ await init_db(engine)+ await engine.dispose()++ asyncio.run(_build())++ for table in ("refactoring_opportunities", "refactoring_summaries"):+ assert _columns(migrated, table) == _columns(declared, table), table+ # Index names too: the queue reads through them by name in the query plan.+ assert _indexes(migrated, "refactoring_opportunities") == _indexes(+ declared, "refactoring_opportunities"+ )diff --git a/tests/unit/server/mcp/test_cross_tool_reference_contracts.py b/tests/unit/server/mcp/test_cross_tool_reference_contracts.pyindex 072a87a6c..fe4e52c51 100644--- a/tests/unit/server/mcp/test_cross_tool_reference_contracts.py+++ b/tests/unit/server/mcp/test_cross_tool_reference_contracts.py@@ -542,6 +542,14 @@ async def test_canonical_emitter_reference_inventory(reference_repo, health_data[context_target], include=["callers", "callees"]))+ # The plan list is an opt-in projection now: ``include=["refactoring"]``+ # leads with composed opportunities. The plan reference is still emitted by+ # get_health, so the inventory asks the call that carries it.+ responses["get_health"].append(+ await tool_middleware(get_health)(+ include=["refactoring"], only=["refactoring_plans"]+ )+ )inventory = {emitter: [refdiff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 712025066..712e98f5b 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -21,9 +21,14 @@ async def test_get_health_dashboard(setup_mcp, health_data):assert result["mode"] == "dashboard"assert result["kpis"]["file_count"] == 2assert result["kpis"]["worst_performer_path"] == "src/auth/service.py"- # Two leads, both first: the defect one and the performance pillar's own,- # which carries no defect impact and so never competed for the first.- assert list(result)[:3] == ["directive", "performance_directive", "mode"]+ # Three leads, all first: the defect one, and one per pillar that carries+ # no defect impact and so never competed for it.+ assert list(result)[:4] == [+ "directive",+ "refactoring_directive",+ "performance_directive",+ "mode",+ ]assert "high_leverage_files" in resultassert "worst_files" not in resultassert result["secondary_rankings"]["worst_files"]["total"] == 2@@ -186,10 +191,16 @@ async def test_get_health_dashboard_surfaces_leverage(setup_mcp, health_data):@pytest.mark.asyncioasync def test_get_health_refactoring_capped_and_leverage_ranked(setup_mcp, health_data):- """refactoring_plans is bounded by limit and reports the honest total."""+ """refactoring_plans is bounded by limit and reports the honest total.++ Named explicitly: ``include=["refactoring"]`` leads with the composed+ opportunity queue, and the raw plan list is the opt-in projection.+ """from repowise.server.mcp_server import get_health- result = await get_health(include=["refactoring"], limit=5)+ result = await get_health(+ include=["refactoring"], only=["refactoring_plans"], limit=5+ )assert "refactoring_plans" in resultassert len(result["refactoring_plans"]) <= 5# Honest truncation signal is always present when refactoring is requested.@@ -285,9 +296,14 @@ def test_validation_profiles_deduplicate_without_dropping_commands_or_target_tes@pytest.mark.asyncio-async def test_target_freshness_uses_only_the_requested_health_rows(- setup_mcp, health_data, session-):+async def test_freshness_is_a_repository_fact_in_every_mode(setup_mcp, health_data, session):+ """Whether the analysis recorded its commit cannot depend on the mode asked.++ Each mode used to compute "latest analysed row" over whatever rows it was+ reporting on, so a call scoped to an older file reported that file's commit+ as the repository's, and a detail call could read ``available`` at the same+ instant the dashboard read ``degraded``. The block is repository-wide now.+ """from datetime import UTC, datetimefrom sqlalchemy import select@@ -311,10 +327,17 @@ async def test_target_freshness_uses_only_the_requested_health_rows(by_path["src/db/models.py"].analyzed_commit = "b" * 40await session.flush()- result = await get_health(targets=["src/auth/service.py"], only=["metrics"])- assert result["_meta"]["health_analyzed_at"].startswith("2025-01-01")- assert result["_meta"]["health_analyzed_commit"] == "a" * 12- assert "health_analyzed_commits_distinct" not in result["_meta"]+ scoped = await get_health(targets=["src/auth/service.py"], only=["metrics"])+ dashboard = await get_health(only=["kpis"])+ for meta in (scoped["_meta"], dashboard["_meta"]):+ # The repository's newest analysed row, not the scoped file's.+ assert meta["health_analyzed_at"].startswith("2026-01-01")+ assert meta["health_analyzed_commit"] == "b" * 12+ assert meta["health_analyzed_commits_distinct"] == 2+ assert (+ scoped["_meta"]["health_analysis"]["status"]+ == dashboard["_meta"]["health_analysis"]["status"]+ )@pytest.mark.asyncio@@ -1592,9 +1615,14 @@ async def test_refactoring_plans_spread_across_files(setup_mcp, health_data, ses],)- plans = (await get_health(include=["refactoring"], limit=4, refactoring_view="file_spread"))[- "refactoring_plans"- ]+ plans = (+ await get_health(+ include=["refactoring"],+ only=["refactoring_plans"],+ limit=4,+ refactoring_view="file_spread",+ )+ )["refactoring_plans"]assert len(plans) == 4# Both files are represented rather than the worst file owning the list.assert len({p["file_path"] for p in plans}) == 2@@ -1628,7 +1656,9 @@ async def test_refactoring_spread_is_exhaustive_when_one_file_has_them_all(],)- plans = (await get_health(include=["refactoring"], limit=4))["refactoring_plans"]+ plans = (+ await get_health(include=["refactoring"], only=["refactoring_plans"], limit=4)+ )["refactoring_plans"]assert len(plans) == 4assert {p["file_path"] for p in plans} == {"src/auth/service.py"}diff --git a/tests/unit/server/mcp/test_health_semantics_matrix.py b/tests/unit/server/mcp/test_health_semantics_matrix.pyindex 948e8c7bc..6d51ebe7c 100644--- a/tests/unit/server/mcp/test_health_semantics_matrix.py+++ b/tests/unit/server/mcp/test_health_semantics_matrix.py@@ -80,7 +80,6 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (invariant_paths=("metrics","findings",- "refactoring_plans","_meta.health_analysis","_meta.health_semantics",),@@ -108,7 +107,6 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (invariant_paths=("metrics","findings",- "refactoring_plans","_meta.health_analysis","_meta.health_semantics",),@@ -206,7 +204,9 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (),comparison="independent performance and refactoring projections",comparison_kwargs=_frozen(- include=("performance", "refactoring"), limit=1+ include=("performance", "refactoring"),+ only=("performance_opportunities", "refactoring_plans"),+ limit=1,),plans_requested=True,expected_plan_count=1,@@ -244,7 +244,6 @@ SEALED_HEALTH_SEMANTICS: tuple[HealthSemanticsCase, ...] = (recovery="none",invariant_paths=("findings",- "refactoring_plans","_meta.health_analysis","_meta.health_semantics",),@@ -495,7 +494,10 @@ async def test_sealed_projection_invariance_uses_independent_calls(setup_mcp, heassert directive["_meta"]["health_analysis"] == dashboard["_meta"]["health_analysis"]broad = await get_health(- targets=["src/auth/service.py"], include=["refactoring"], limit=2+ targets=["src/auth/service.py"],+ include=["refactoring"],+ only=["metrics", "findings", "refactoring_plans", "kpis"],+ limit=2,)narrow = await get_health(targets=["src/auth/service.py"],diff --git a/tests/unit/server/test_refactoring_opportunities.py b/tests/unit/server/test_refactoring_opportunities.pynew file mode 100644index 000000000..007e375fa--- /dev/null+++ b/tests/unit/server/test_refactoring_opportunities.py@@ -0,0 +1,629 @@+"""Serving contracts for composed refactoring opportunities.++REST and MCP read one service over one materialized read model, so the two+must answer identically, and a page must cost its page rather than the+repository. Both are asserted here, the second by counting statements rather+than by wall clock.+"""++from __future__ import annotations++import tempfile+from pathlib import Path+from typing import Any++import pytest+from httpx import AsyncClient+from sqlalchemy import event++from repowise.core.persistence import crud+++async def _repo(client: AsyncClient) -> str:+ repo_dir = Path(tempfile.mkdtemp()) / "opp-repo"+ repo_dir.mkdir(exist_ok=True)+ (repo_dir / ".git").mkdir(exist_ok=True)+ resp = await client.post(+ "/api/repos",+ json={+ "index": False,+ "name": "opp-repo",+ "local_path": str(repo_dir),+ "url": "https://github.com/example/opp-repo",+ },+ )+ assert resp.status_code == 201+ return resp.json()["id"]+++def _plan(path: str, symbol: str, **over: Any) -> dict[str, Any]:+ plan = {+ "refactoring_type": "extract_method",+ "file_path": path,+ "target_symbol": symbol,+ "line_start": 10,+ "line_end": 30,+ "plan": {"extracted_name": f"_{symbol}_part", "local_scope": True},+ "evidence": {"ccn_removed": 6, "slice_nloc": 20},+ "impact_delta": 1.0,+ "effort_bucket": "S",+ "blast_radius": {"scope": "local"},+ "confidence": "high",+ "source_biomarker": "complex_method",+ }+ plan.update(over)+ return plan+++def _finding(path: str, biomarker: str = "complex_method", impact: float = 3.0) -> dict[str, Any]:+ return {+ "file_path": path,+ "biomarker_type": biomarker,+ "severity": "high",+ "function_name": "f",+ "line_start": 10,+ "line_end": 30,+ "details": {},+ "health_impact": impact,+ "reason": "seeded",+ "dimension": "defect",+ }+++async def _seed(client: AsyncClient, app, *, files: int = 8) -> str:+ """A repository whose plans compose into one opportunity per file."""+ repo_id = await _repo(client)+ paths = [f"pkg{i % 3}/mod{i}.py" for i in range(files)]+ async with app.state.session_factory() as session:+ await crud.save_health_findings(session, repo_id, [_finding(p) for p in paths])+ await crud.save_refactoring_suggestions(+ session,+ repo_id,+ [_plan(path, f"sym{i}", impact_delta=float(files - i)) for i, path in enumerate(paths)],+ )+ await crud.finalize_refactoring_opportunities(session, repo_id, analyzed_commit="c" * 40)+ await session.commit()+ return repo_id+++async def _mcp(app):+ """Point the MCP tool at this test's database and hand back ``get_health``."""+ import asyncio++ from repowise.server.mcp_server import _state+ from repowise.server.mcp_server.tool_health import get_health++ _state._session_factory = app.state.session_factory+ _state._repo_path = "/tmp/opp-repo"+ _state._registry = None+ _state._vector_store_ready = asyncio.Event()+ _state._vector_store_ready.set()+ return get_health+++# ---------------------------------------------------------------------------+# The writer+# ---------------------------------------------------------------------------+++async def test_finalizer_composes_one_opportunity_per_file(client, app):+ repo_id = await _seed(client, app, files=5)+ resp = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")+ assert resp.status_code == 200+ body = resp.json()+ assert body["total"] == 5+ assert len({item["file_path"] for item in body["items"]}) == 5+ for item in body["items"]:+ assert item["opportunity_id"].startswith("refop2_")+ assert item["step_count"] == 1+ # The lead was supplied, so this is a real answer rather than unknown.+ assert item["addresses_primary_problem"] is True+++async def test_addresses_primary_problem_is_unknown_without_a_lead(client, app):+ """A file with no recorded finding gets ``None``, never a quiet ``False``."""+ repo_id = await _repo(client)+ async with app.state.session_factory() as session:+ await crud.save_refactoring_suggestions(session, repo_id, [_plan("pkg/x.py", "s")])+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ assert body["items"][0]["addresses_primary_problem"] is None+++async def test_an_opportunity_nobody_composes_resolves_rather_than_vanishing(client, app):+ repo_id = await _seed(client, app, files=3)+ before = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ held = before["items"][0]["opportunity_id"]+ async with app.state.session_factory() as session:+ # A run that detects nothing resolves every plan, so nothing composes.+ await crud.save_refactoring_suggestions(session, repo_id, [])+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()+ after = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ assert after["total"] == 0+ # The id an agent is holding still resolves, and reads as resolved.+ detail = await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{held}")+ assert detail.status_code == 200+ assert detail.json()["status"] == "resolved"+++async def test_lifecycle_rolls_up_from_the_member_plans(client, app):+ repo_id = await _seed(client, app, files=2)+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ detail = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities/"+ f"{body['items'][0]['opportunity_id']}"+ )+ ).json()+ plan_id = detail["steps"][0]["plan_id"]+ async with app.state.session_factory() as session:+ await crud.update_refactoring_suggestion_status(session, repo_id, plan_id, "acknowledged")+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()+ refreshed = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities/{detail['opportunity_id']}"+ )+ ).json()+ assert refreshed["status"] == "acknowledged"+++# ---------------------------------------------------------------------------+# REST == MCP+# ---------------------------------------------------------------------------+++async def test_rest_and_mcp_agree_on_order_totals_and_detail(client, app):+ repo_id = await _seed(client, app, files=9)+ get_health = await _mcp(app)++ rest = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 6}+ )+ ).json()+ mcp = await get_health(+ include=["refactoring"], only=["refactoring_opportunities"], limit=6+ )++ assert rest["total"] == mcp["refactoring_opportunities_total"]+ assert [item["opportunity_id"] for item in rest["items"]] == [+ item["opportunity_id"] for item in mcp["refactoring_opportunities"]+ ]+ assert [item["rank_position"] for item in rest["items"]] == [+ item["rank_position"] for item in mcp["refactoring_opportunities"]+ ]++ target = rest["items"][0]["opportunity_id"]+ rest_detail = (+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{target}")+ ).json()+ mcp_detail = await get_health(opportunity_id=target)+ for key in (+ "opportunity_id",+ "file_path",+ "lead_biomarker",+ "step_count",+ "rank_score",+ "addresses_primary_problem",+ "steps",+ ):+ assert rest_detail[key] == mcp_detail[key], key+++async def test_rest_and_mcp_agree_under_a_view(client, app):+ repo_id = await _seed(client, app, files=9)+ get_health = await _mcp(app)+ for view in ("canonical", "diversified", "file_spread"):+ rest = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities",+ params={"limit": 6, "view": view},+ )+ ).json()+ mcp = await get_health(+ include=["refactoring"],+ only=["refactoring_opportunities"],+ limit=6,+ refactoring_view=view,+ )+ assert [i["opportunity_id"] for i in rest["items"]] == [+ i["opportunity_id"] for i in mcp["refactoring_opportunities"]+ ], view+++async def test_an_unknown_filter_value_is_named_not_swallowed(client, app):+ repo_id = await _seed(client, app, files=3)+ body = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities",+ params={"refactoring_type": "extract_nonsense"},+ )+ ).json()+ # A misspelling must not read as "the repository is clean".+ assert body["ignored_arguments"] == {"refactoring_type": "extract_nonsense"}+ assert body["total"] == 3+++# ---------------------------------------------------------------------------+# Cost+# ---------------------------------------------------------------------------+++def _counter(engine) -> list[str]:+ seen: list[str] = []++ @event.listens_for(engine.sync_engine, "before_cursor_execute")+ def _before(conn, cursor, statement, params, context, executemany):+ seen.append(statement)++ return seen+++async def test_queue_query_count_is_constant_in_page_size_and_row_count(+ client, app, test_engine+):+ """The statement count must not move when the page or the repository grows."""+ small = await _seed(client, app, files=4)+ large = await _seed(client, app, files=40)+ counts = {}+ seen = _counter(test_engine)+ for label, repo_id, limit in (+ ("small-1", small, 1),+ ("small-20", small, 20),+ ("large-1", large, 1),+ ("large-20", large, 20),+ ("large-100", large, 100),+ ):+ seen.clear()+ resp = await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": limit}+ )+ assert resp.status_code == 200+ counts[label] = len(seen)+ assert len(set(counts.values())) == 1, counts+++async def test_a_deep_offset_costs_the_same_as_the_first_page(client, app, test_engine):+ repo_id = await _seed(client, app, files=40)+ seen = _counter(test_engine)+ seen.clear()+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 5, "offset": 0}+ )+ first = len(seen)+ seen.clear()+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 5, "offset": 30}+ )+ assert len(seen) == first+++async def test_point_lookups_are_bounded_and_do_not_scale_with_the_repository(+ client, app, test_engine+):+ """Resolving one id used to hydrate every open plan in the repository."""+ small = await _seed(client, app, files=4)+ large = await _seed(client, app, files=60)+ get_health = await _mcp(app)+ seen = _counter(test_engine)+ costs = {}+ for label, repo_id in (("small", small), ("large", large)):+ body = (+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")+ ).json()+ target = body["items"][0]["opportunity_id"]+ seen.clear()+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{target}")+ costs[f"{label}-opportunity"] = len(seen)++ detail = (+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{target}")+ ).json()+ seen.clear()+ await get_health(plan_id=detail["steps"][0]["plan_id"])+ costs[f"{label}-plan"] = len(seen)++ assert costs["small-opportunity"] == costs["large-opportunity"], costs+ assert costs["small-plan"] == costs["large-plan"], costs+ # The service's own share of an opportunity lookup: the row and its plans.+ assert costs["large-opportunity"] <= 5, costs+++async def test_a_files_opportunities_are_one_indexed_lookup(client, app, test_engine):+ repo_id = await _seed(client, app, files=40)+ seen = _counter(test_engine)+ seen.clear()+ body = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities",+ params={"file_path": "pkg0/mod0.py"},+ )+ ).json()+ assert body["total"] == 1+ assert body["items"][0]["file_path"] == "pkg0/mod0.py"+++# ---------------------------------------------------------------------------+# The agent contract+# ---------------------------------------------------------------------------+++async def test_bare_get_health_carries_one_bounded_refactoring_directive(client, app):+ repo_id = await _seed(client, app, files=12)+ get_health = await _mcp(app)+ result = await get_health()+ directive = result["refactoring_directive"]+ assert directive["status"] == "available"+ assert directive["opportunity_id"].startswith("refop2_")+ assert directive["next_action"]["arguments"]["opportunity_id"] == directive["opportunity_id"]+ assert directive["opportunities_total"] == 12+ # Level 0 is a lead, not a queue: it must stay small enough to survive.+ assert len(str(directive)) < 1536+ assert "refactoring_opportunities" not in result++ # And the id it names resolves in one call.+ detail = await get_health(opportunity_id=directive["opportunity_id"])+ assert detail["resolved"] is True+ assert detail["mode"] == "refactoring_opportunity"+ assert detail["steps"]+ del repo_id+++async def test_the_directive_is_clear_rather_than_absent_with_no_opportunities(client, app):+ repo_id = await _repo(client)+ async with app.state.session_factory() as session:+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()+ get_health = await _mcp(app)+ assert (await get_health())["refactoring_directive"]["status"] == "clear"+++async def test_the_summary_rolls_up_by_type_effort_and_classification(client, app):+ await _seed(client, app, files=6)+ get_health = await _mcp(app)+ summary = (+ await get_health(include=["refactoring"], only=["refactoring_summary"])+ )["refactoring_summary"]+ assert summary["status"] == "available"+ assert summary["opportunities_total"] == 6+ assert summary["by_lead_type"]["extract_method"] == 6+ assert summary["mechanical_steps_total"] + summary["judgment_steps_total"] == 6+ assert summary["addresses_primary_problem"]["yes"] == 6+ assert "facets" in summary+ assert "refactoring_opportunities" in summary["next_call"]+++async def test_the_default_queue_does_not_reproduce_the_ranked_head(client, app):+ """Eight equal scores from one area must not own the first page.++ The scores really are equal under the published factors, so the answer is a+ queue that spends its first rows on distinct problems, not a tiebreaker.+ """+ repo_id = await _repo(client)+ # One area with a long run of identical scores, plus two other areas.+ plans = [_plan(f"crowded/m{i}.py", f"s{i}", impact_delta=1.0) for i in range(8)]+ plans += [_plan("other/a.py", "a", impact_delta=1.0), _plan("third/b.py", "b", impact_delta=1.0)]+ async with app.state.session_factory() as session:+ await crud.save_refactoring_suggestions(session, repo_id, plans)+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()++ default = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities", params={"limit": 3}+ )+ ).json()["items"]+ canonical = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities",+ params={"limit": 3, "view": "canonical"},+ )+ ).json()["items"]++ areas = {item["file_path"].split("/")[0] for item in default}+ assert areas == {"crowded", "other", "third"}+ # Pure rank order still available, and still the flat run it honestly is.+ assert {item["file_path"].split("/")[0] for item in canonical} == {"crowded"}+++async def test_a_step_names_the_findings_its_cause_produced(client, app):+ repo_id = await _seed(client, app, files=2)+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ detail = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities/"+ f"{body['items'][0]['opportunity_id']}"+ )+ ).json()+ step = detail["steps"][0]+ assert step["finding_ids"], "a step must round-trip to the diagnosis behind it"++ get_health = await _mcp(app)+ resolved = await get_health(finding_id=step["finding_ids"][0])+ assert resolved["resolved"] is True+++async def test_the_detail_hands_back_structured_next_calls(client, app):+ repo_id = await _seed(client, app, files=2)+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ detail = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities/"+ f"{body['items'][0]['opportunity_id']}"+ )+ ).json()+ tools = {action["tool"] for action in detail["next_actions"]}+ assert {"get_symbol", "get_risk"} <= tools+ assert detail["plans"], "the steps' payloads come back with them"+ assert detail["validation_profiles"], "validation is served, not recomputed"+++async def test_a_plan_id_resolves_to_the_opportunity_that_owns_it(client, app):+ repo_id = await _seed(client, app, files=3)+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ owner = body["items"][0]["opportunity_id"]+ detail = (+ await client.get(f"/api/repos/{repo_id}/refactoring/opportunities/{owner}")+ ).json()+ get_health = await _mcp(app)+ resolved = await get_health(plan_id=detail["steps"][0]["plan_id"])+ assert resolved["resolved"] is True+ assert resolved["opportunity_id"] == owner+ assert resolved["next_action"]["arguments"]["opportunity_id"] == owner+ # The payload every surface shows, rank components included.+ assert "rank_score" in resolved["plan"]+ assert "validation" in resolved["plan"]+++async def test_an_unknown_opportunity_id_says_which_kind_of_unknown(client, app):+ await _seed(client, app, files=2)+ get_health = await _mcp(app)+ missing = await get_health(opportunity_id="refop2_" + "0" * 20)+ assert missing["resolved"] is False+ assert missing["model_state"]["state"] == "current"+ stale = await get_health(opportunity_id="refop1_" + "0" * 20)+ assert stale["model_state"]["state"] == "stale_model"+++async def test_each_step_keeps_its_own_validation_profile(client, app):+ """Validation must be keyed by plan, not by position.++ ``hydrate_recommendations`` returns its results in rank order, so pairing+ them positionally against the rows handed in gives most steps another+ plan's tests. Two plans on two files with different affected-file sets, and+ a rank order that is the reverse of the read order, catch it.+ """+ repo_id = await _repo(client)+ local = _plan("alpha/only_here.py", "local_sym", impact_delta=0.5)+ spanning = {+ **_plan("beta/anchor.py", "dup_block", impact_delta=9.0),+ "refactoring_type": "extract_helper",+ "plan": {+ "occurrences": [+ {"file": "beta/anchor.py", "line_start": 10, "line_end": 30},+ {"file": "gamma/other.py", "line_start": 5, "line_end": 25},+ ],+ "suggested_site": {"module": "beta", "directory": "beta"},+ "duplicated_lines": 20,+ },+ "evidence": {"occurrence_count": 2, "duplicated_lines": 20, "co_change_count": 9},+ "blast_radius": {+ "files": ["beta/anchor.py", "gamma/other.py"],+ "file_count": 2,+ "co_change_count": 9,+ },+ "source_biomarker": "dry_violation",+ }+ async with app.state.session_factory() as session:+ # Inserted lowest-rank-first, so the rank order is the reverse.+ await crud.save_refactoring_suggestions(session, repo_id, [local, spanning])+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()++ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ seen = {}+ for item in body["items"]:+ detail = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities/{item['opportunity_id']}"+ )+ ).json()+ profiles = {p["id"]: p for p in detail["validation_profiles"]}+ for step in detail["steps"]:+ profile = profiles[step["validation_profile_id"]]+ seen[step["file_path"]] = set(profile["affected_files"])++ assert seen["alpha/only_here.py"] == {"alpha/only_here.py"}+ assert seen["beta/anchor.py"] == {"beta/anchor.py", "gamma/other.py"}+++async def test_rest_and_mcp_agree_under_every_queue_filter(client, app):+ """MCP could order the queue but not filter it; REST could do both."""+ repo_id = await _repo(client)+ plans = [+ _plan("a/one.py", "s1", impact_delta=3.0, confidence="high", effort_bucket="S"),+ _plan("b/two.py", "s2", impact_delta=2.0, confidence="medium", effort_bucket="L"),+ {+ **_plan("c/three.py", "s3", impact_delta=1.0),+ "refactoring_type": "split_file",+ "plan": {"groups": [{"name": "g1", "symbols": ["x"]}]},+ "source_biomarker": "large_file",+ },+ ]+ async with app.state.session_factory() as session:+ await crud.save_refactoring_suggestions(session, repo_id, plans)+ await crud.finalize_refactoring_opportunities(session, repo_id)+ await session.commit()+ get_health = await _mcp(app)++ for params, kwargs in (+ ({"refactoring_type": "split_file"}, {"refactoring_type": "split_file"}),+ ({"confidence": "high"}, {"refactoring_confidence": "high"}),+ ({"effort": "L"}, {"refactoring_effort": "L"}),+ ({"refactoring_type": "nope"}, {"refactoring_type": "nope"}),+ ):+ rest = (+ await client.get(+ f"/api/repos/{repo_id}/refactoring/opportunities",+ params={"limit": 6, **params},+ )+ ).json()+ mcp = await get_health(+ include=["refactoring"], only=["refactoring_opportunities"], limit=6, **kwargs+ )+ assert rest["total"] == mcp["refactoring_opportunities_total"], params+ assert [i["opportunity_id"] for i in rest["items"]] == [+ i["opportunity_id"] for i in mcp["refactoring_opportunities"]+ ], params+ # An unrecognized value is named on both surfaces, never swallowed.+ assert rest.get("ignored_arguments") == mcp.get("ignored_arguments"), params+++async def test_limit_zero_returns_the_totals_and_no_rows(client, app):+ """``limit=0`` is the documented "totals, no rows" call at every level."""+ repo_id = await _seed(client, app, files=4)+ body = (await client.get(f"/api/repos/{repo_id}/refactoring/opportunities")).json()+ get_health = await _mcp(app)+ detail = await get_health(opportunity_id=body["items"][0]["opportunity_id"], limit=0)+ assert detail["steps"] == []+ assert detail["steps_total"] == 1+ assert detail["steps_emitted"] == 0+++async def test_a_capped_queue_says_why_it_was_capped(client, app):+ repo_id = await _seed(client, app, files=20)+ get_health = await _mcp(app)+ result = await get_health(+ include=["refactoring"], only=["refactoring_opportunities"], limit=3+ )+ assert result["refactoring_opportunities_total"] == 20+ assert result["refactoring_opportunities_emitted"] == 3+ assert result["refactoring_opportunities_reduced_reason"] == "limit"+ assert result["recovery"]["refactoring_opportunities"]["remaining"] == 17+ del repo_id