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(performance): serve the opportunity queue from a materialized read model (#1981)
Raghav Chamadiyaf84eb0b2cc27
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 1f030f6c0..82ab6e46c 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -732,6 +732,12 @@ get_health(include=["performance","refactoring"], only=["performance_opportuniti| `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. |+| `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`. |+| `performance_confidence` | string | No | Evidence confidence: `high` / `medium` / `low`. Fix safety and actionability are separate facets. |+| `performance_sort` | string | No | `rank` (default) / `leverage` / `observations`. |**Returns:** Dashboard mode (no `targets`) returns a `directive`, repo-level KPIs(hotspot health, average health, worst performer, maintainability / performance@@ -894,10 +900,15 @@ payload:| signal | reads | why ||---|---|---|-| the marker | `biomarker_type` | superlinear (`nested_loop_quadratic` 5) > N×M or lock-serialized (4) > one crossing per iteration, or one crossing proven on a hot path (3) > in-loop CPU/allocation (2) > cheap in-loop idioms (1) |-| the boundary | `details.boundary_kind` | `subprocess` 4 > `network` 3 > `db`/`lock` 2 > `filesystem` 1 — a process spawn in a loop is not a stat in a loop |+| the marker | `biomarker_type` | superlinear (`nested_loop_quadratic`, `nested_loop_with_io`, `sql_cartesian_join` 6) > lock-serialized (5) > one crossing per iteration, or one proven on a hot path (4) > in-loop CPU/allocation (3) > repeated acquisition with no boundary (2); an unweighted marker takes the floor (1) |+| the boundary | `details.boundary_kind` | `subprocess` 5 > `network`/`db` 4 > `lock` 3 > `filesystem` 2. A process spawn in a loop is not a stat in a loop || the call shape | `details.cross_function` | +1. An intra-function loop is usually visibly bounded at the call site; a cross-function N+1 is the one nobody sees by reading the loop |+These are the same weights the causal opportunity ranking reads. Two tables+used to answer "which marker costs more" and had drifted apart on markers both+named, so a finding and the opportunity built from it could disagree about the+same evidence.+Request-reachability is read off the marker rather than a column:`hot_path_sync_io` and `nested_loop_quadratic` are only ever emitted for afunction the perf ranker called hot (top-quintile call-graph in-degree, or a@@ -934,6 +945,33 @@ get_health(only=["top_findings"]) # + top_findings_total, auget_health(only=["kpis"], limit=0) # headline numbers, no rows at all```+### Performance: one lead, then drill down++A bare `get_health()` carries `performance_directive`: one bounded lead with+its status (`plan_ready` / `advisory` / `investigate` / `clear` / `unavailable`),+up to three `why_ranked` facets, the exact plan state, and a structured+`next_action`. Performance findings carry `health_impact: 0` by construction, so+they never competed for the main `directive` and the dashboard used to report+counts and nothing to act on. `clear` means no supported pattern surfaced, which+is not a claim about how the code runs; `unavailable` means this index has not+materialized the analysis yet, or did so under an older model.++```+get_health() # the lead+get_health(include=["performance"], only=["performance_summary"])+get_health(include=["performance"], only=["performance_opportunities"], performance_context="production")+get_health(opportunity_id="perf2_...") # the cause, its plan, its evidence+get_health(opportunity_id="perf2_...", only=["performance_evidence"], cursor=3)+```++Ids are stable within a performance model version and are never translated+across one, because grouping decides membership and two models disagree about+it. An id from an older model resolves to `model_state.state: "stale_model"`+with `refresh_required`, rather than failing to match and reading as "no plan".+Evidence rows carry the finding's public `finding_id`, which round-trips through+the `finding_id` selector; storage row ids are republished on every analysis and+are never emitted.+---## Supplementary toolsdiff --git a/packages/api-client/src/code-health.ts b/packages/api-client/src/code-health.tsindex 260df27e4..10c67d40b 100644--- a/packages/api-client/src/code-health.ts+++ b/packages/api-client/src/code-health.ts@@ -14,6 +14,10 @@ import type {HealthFileBreakdownResponse,HealthOverviewResponse,HealthTrendResponse,+ PerformanceActionabilityState,+ PerformanceExecutionContext,+ PerformanceOpportunityConfidence,+ PerformanceOpportunityDetail,PerformanceOpportunityPage,HealthWorkQueueQuery,HealthWorkQueueResponse,@@ -45,6 +49,15 @@ export type {HealthWorkQueueQuery,HealthWorkQueueResponse,ModuleCoverageRow,+ PerformanceActionabilityState,+ PerformanceExecutionContext,+ PerformanceFacets,+ PerformanceOpportunity,+ PerformanceOpportunityConfidence,+ PerformanceOpportunityDetail,+ PerformanceOpportunityEvidence,+ PerformanceOpportunityPage,+ PerformanceOpportunitySummary,RefactoringQuery,RefactoringTarget,RefactoringTargetsResponse,@@ -74,7 +87,18 @@ export async function listHealthFindings(}export interface PerformanceOpportunityPageParams {- context?: "production_tooling" | "test" | "all";+ /**+ * Canonical contexts. `production_tooling` is a retired spelling the server+ * still answers as Production+Tooling; it is never returned as a context.+ */+ context?: PerformanceExecutionContext | "all" | "production_tooling";+ boundary?: string;+ /** Evidence confidence, reported apart from fix safety and actionability. */+ confidence?: PerformanceOpportunityConfidence;+ actionability?: PerformanceActionabilityState;+ /** `summary` drops the explanatory fields and keeps identity and counts. */+ view?: "detail" | "summary";+ sort?: "rank" | "leverage" | "observations";limit?: number;offset?: number;}@@ -85,7 +109,28 @@ export async function getPerformanceOpportunities(): Promise<PerformanceOpportunityPage> {return apiGet<PerformanceOpportunityPage>(`/api/repos/${repoId}/health/performance-opportunities`,- { context: opts.context, limit: opts.limit, offset: opts.offset },+ {+ context: opts.context,+ boundary: opts.boundary,+ confidence: opts.confidence,+ actionability: opts.actionability,+ view: opts.view,+ sort: opts.sort,+ limit: opts.limit,+ offset: opts.offset,+ },+ );+}++/** One opportunity by its stable id, with bounded evidence. */+export async function getPerformanceOpportunity(+ repoId: string,+ opportunityId: string,+ opts: { evidenceLimit?: number; evidenceOffset?: number } = {},+): Promise<PerformanceOpportunityDetail> {+ return apiGet<PerformanceOpportunityDetail>(+ `/api/repos/${repoId}/health/performance-opportunities/${encodeURIComponent(opportunityId)}`,+ { evidence_limit: opts.evidenceLimit, evidence_offset: opts.evidenceOffset },);}diff --git a/packages/core/alembic/versions/0057_performance_opportunities.py b/packages/core/alembic/versions/0057_performance_opportunities.pynew file mode 100644index 000000000..94679bbc3--- /dev/null+++ b/packages/core/alembic/versions/0057_performance_opportunities.py@@ -0,0 +1,158 @@+"""Materialize performance opportunities and give findings a queryable identity.++The performance queue was rebuilt from every open performance finding on every+request, so serving one page of twenty cost the whole repository. This adds the+table that holds the grouped result, the columns that make identity and plan+linkage indexable instead of JSON predicates, and the single-row current+summary a bare dashboard reads.++Every column is nullable or defaulted, and every index is additive, so an+existing store upgrades without a rewrite and repopulates on its next analysis.++Revision ID: 0057+Revises: 0056+Create Date: 2026-08-29+"""++from __future__ import annotations++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "0057"+down_revision: str | None = "0056"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None++_FINDING_INDEXES = (+ ("ix_health_findings_repo_public_id", ["repository_id", "public_id"]),+ (+ "ix_health_findings_repo_status_dimension_opportunity",+ ["repository_id", "status", "dimension", "opportunity_id"],+ ),+)++_OPPORTUNITY_INDEXES = (+ ("ix_performance_opportunities_repo_id", ["repository_id", "opportunity_id"]),+ (+ "ix_performance_opportunities_repo_status_rank",+ ["repository_id", "status", "rank_position"],+ ),+ (+ "ix_performance_opportunities_repo_status_context_rank",+ ["repository_id", "status", "execution_context", "rank_position"],+ ),+ (+ "ix_performance_opportunities_repo_status_action_rank",+ ["repository_id", "status", "actionability_state", "rank_position"],+ ),+ (+ "ix_performance_opportunities_repo_status_path",+ ["repository_id", "status", "file_path"],+ ),+)+++def upgrade() -> None:+ op.add_column("health_findings", sa.Column("public_id", sa.String(64), nullable=True))+ op.add_column("health_findings", sa.Column("opportunity_id", sa.String(64), nullable=True))+ for name, columns in _FINDING_INDEXES:+ op.create_index(name, "health_findings", columns, if_not_exists=True)++ op.add_column(+ "refactoring_suggestions", sa.Column("opportunity_id", sa.String(64), nullable=True)+ )+ op.create_index(+ "ix_refactoring_suggestions_repo_type_opportunity",+ "refactoring_suggestions",+ ["repository_id", "refactoring_type", "opportunity_id"],+ if_not_exists=True,+ )++ op.create_table(+ "performance_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(+ "performance_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("rank_score", sa.Integer(), nullable=False, server_default="0"),+ sa.Column(+ "execution_context", sa.String(16), nullable=False, server_default="unknown"+ ),+ sa.Column("boundary_kind", sa.String(32), nullable=True),+ sa.Column("biomarker_type", sa.String(64), nullable=False, server_default=""),+ sa.Column(+ "actionability_state", sa.String(16), nullable=False, server_default="investigate"+ ),+ sa.Column("evidence_confidence", sa.String(16), nullable=False, server_default="low"),+ sa.Column("plan_state", sa.String(16), nullable=False, server_default="no_safe_plan"),+ sa.Column("fix_strategy", sa.String(64), nullable=True),+ sa.Column("fix_safety", sa.String(16), nullable=True),+ sa.Column("file_path", sa.Text(), nullable=False, server_default=""),+ sa.Column("intervention_symbol", sa.Text(), nullable=True),+ sa.Column("terminal_sink", sa.Text(), nullable=True),+ sa.Column("observations_total", sa.Integer(), nullable=False, server_default="0"),+ sa.Column(+ "affected_call_sites_total", sa.Integer(), nullable=False, server_default="0"+ ),+ sa.Column("affected_files_total", sa.Integer(), 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",+ "performance_model_version",+ "opportunity_id",+ name="uq_performance_opportunities_repo_model_id",+ ),+ )+ for name, columns in _OPPORTUNITY_INDEXES:+ op.create_index(name, "performance_opportunities", columns, if_not_exists=True)++ op.create_table(+ "performance_summaries",+ sa.Column(+ "repository_id",+ sa.String(32),+ sa.ForeignKey("repositories.id", ondelete="CASCADE"),+ primary_key=True,+ ),+ sa.Column(+ "performance_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("performance_summaries")+ for name, _columns in _OPPORTUNITY_INDEXES:+ op.drop_index(name, table_name="performance_opportunities", if_exists=True)+ op.drop_table("performance_opportunities")++ op.drop_index(+ "ix_refactoring_suggestions_repo_type_opportunity",+ table_name="refactoring_suggestions",+ if_exists=True,+ )+ op.drop_column("refactoring_suggestions", "opportunity_id")++ for name, _columns in _FINDING_INDEXES:+ op.drop_index(name, table_name="health_findings", if_exists=True)+ op.drop_column("health_findings", "opportunity_id")+ op.drop_column("health_findings", "public_id")diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.pyindex f417a3861..c85c76afa 100644--- a/packages/core/src/repowise/core/analysis/health/engine.py+++ b/packages/core/src/repowise/core/analysis/health/engine.py@@ -56,6 +56,7 @@ from .perf import (link_performance_findings,)from .refactoring import (+ PerformancePlanPolicy,RefactoringContext,RefactoringSuggestion,detect_refactorings,@@ -561,6 +562,10 @@ class HealthAnalyzer:kpis=kpis,function_blame_rows=self._function_blame_rows(walked),refactoring_suggestions=suggestions,+ performance_plan_policy=PerformancePlanPolicy(+ enabled=refactoring_enabled and "performance_fix" not in disabled_refactorings,+ min_confidence=refactoring_min_confidence,+ ),)async def analyze_async(@@ -754,6 +759,10 @@ class HealthAnalyzer:kpis=kpis,function_blame_rows=self._function_blame_rows(walked),refactoring_suggestions=suggestions,+ performance_plan_policy=PerformancePlanPolicy(+ enabled=refactoring_enabled and "performance_fix" not in disabled_refactorings,+ min_confidence=refactoring_min_confidence,+ ),)# ------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/analysis/health/finding_identity.py b/packages/core/src/repowise/core/analysis/health/finding_identity.pynew file mode 100644index 000000000..fa38d31d8--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/finding_identity.py@@ -0,0 +1,79 @@+"""The public identity of one health finding.++Every finding is republished on each analysis, so a storage row id is a fresh+UUID every time and cannot be quoted back. This kernel names the finding by+what it *is* instead, which makes the id stable across runs, storable as a+column, and safe to hand to an agent.++The kernel holds structural coordinates and detector evidence. It deliberately+excludes prose and derived values: ``reason`` is generated text that a wording+change would churn, and two ``details`` keys are outputs of later passes rather+than facts about the location, so leaving them in would make the id of a+finding move whenever an unrelated model changed its mind.+"""++from __future__ import annotations++import hashlib+import json+import posixpath+from typing import Any++from .rows import detail_map, field++FINDING_ID_VERSION = 1+"""Version of the identity kernel below.++It is hashed rather than spelled into the id, because the public reference+vocabulary is ``<kind>_<digest>`` across every tool and a finding has no+cross-version resolution story to tell: bumping this simply changes every+value, and an id minted by an older kernel stops matching.+"""++_PREFIX = "finding"++_DERIVED_DETAIL_KEYS = frozenset({"opportunity_id", "reliable_entry_reachability"})+"""Detail keys written by later passes, not by the detector that found the row.++``opportunity_id`` is stamped by causal grouping, so leaving it in would make+every finding id churn whenever the performance model version moved.+``reliable_entry_reachability`` is a repository-wide graph answer that flips+when unrelated code changes.+"""+++def _path_identity(path: str) -> str:+ """One repository-relative POSIX form, so a Windows caller matches."""+ normalized = posixpath.normpath(str(path).strip().replace("\\", "/"))+ return normalized.removeprefix("./")+++def finding_public_id(row: Any) -> str:+ """The stable public id for one finding row."""+ details = {+ key: value+ for key, value in detail_map(row).items()+ if key not in _DERIVED_DETAIL_KEYS+ }+ kernel = {+ "kernel_version": FINDING_ID_VERSION,+ "dimension": field(row, "dimension", None) or "defect",+ "path": _path_identity(field(row, "file_path", "") or ""),+ "kind": field(row, "biomarker_type", "") or "",+ "symbol": field(row, "function_name", None) or "",+ "line_start": field(row, "line_start", None),+ "line_end": field(row, "line_end", None),+ "details": details,+ }+ payload = json.dumps(kernel, sort_keys=True, separators=(",", ":"), default=str)+ digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:20]+ return f"{_PREFIX}_{digest}"+++def is_finding_public_id(value: str) -> bool:+ """Whether a caller-supplied string has the shape this kernel mints."""+ prefix, separator, digest = value.partition("_")+ return bool(separator) and prefix == _PREFIX and len(digest) == 20+++__all__ = ["FINDING_ID_VERSION", "finding_public_id", "is_finding_public_id"]diff --git a/packages/core/src/repowise/core/analysis/health/models.py b/packages/core/src/repowise/core/analysis/health/models.pyindex d92befb1c..722a92415 100644--- a/packages/core/src/repowise/core/analysis/health/models.py+++ b/packages/core/src/repowise/core/analysis/health/models.py@@ -91,3 +91,9 @@ class HealthReport:# closure whose performance rows/plans were recomputed for full parity.authoritative_paths: set[str] = field(default_factory=set)performance_authoritative_paths: set[str] = field(default_factory=set)+ # Plan policy for the writer that persists these findings. The performance+ # plans in ``refactoring_suggestions`` above are a report-level convenience+ # built from one run's findings; the authoritative ones are generated once,+ # against the merged stored set, and need this configuration to get there.+ # Typed ``Any`` for the same reason as ``refactoring_suggestions``.+ performance_plan_policy: Any | None = Nonediff --git a/packages/core/src/repowise/core/analysis/health/perf/facts.py b/packages/core/src/repowise/core/analysis/health/perf/facts.pyindex b1e9b75d2..796355b5a 100644--- a/packages/core/src/repowise/core/analysis/health/perf/facts.py+++ b/packages/core/src/repowise/core/analysis/health/perf/facts.py@@ -7,31 +7,11 @@ in: analyzer dataclass, ORM row, or plain dict all reduce here.from __future__ import annotations-import jsonfrom dataclasses import dataclassfrom typing import Any--def field(row: Any, name: str, default: Any = None) -> Any:- """Read one attribute from a dataclass, an ORM row, or a dict."""- if isinstance(row, dict):- return row.get(name, default)- return getattr(row, name, default)---def detail_map(row: Any) -> dict[str, Any]:- """The finding's open ``details`` payload, whether stored or in memory."""- value = field(row, "details", None)- if isinstance(value, dict):- return value- raw = field(row, "details_json", None)- if isinstance(raw, str):- try:- loaded = json.loads(raw)- return loaded if isinstance(loaded, dict) else {}- except (TypeError, ValueError):- return {}- return {}+from ..finding_identity import finding_public_id+from ..rows import detail_map, fielddef is_performance(row: Any) -> bool:@@ -125,8 +105,9 @@ class ObservationFacts:def observation_facts(row: Any) -> ObservationFacts:details = detail_map(row)raw_path = details.get("path", ())+ stored = field(row, "public_id", None)return ObservationFacts(- finding_id=str(field(row, "id", "") or ""),+ finding_id=stored if isinstance(stored, str) and stored else finding_public_id(row),file_path=str(field(row, "file_path", "")),function_name=field(row, "function_name", None),line_start=field(row, "line_start", None),@@ -152,8 +133,9 @@ def performance_facts(rows: list[Any]) -> list[ObservationFacts]:def evidence_row(facts: ObservationFacts) -> dict[str, Any]:"""One public evidence entry.- ``finding_id`` is the storage row id, not a content hash: empty before- persistence, a fresh UUID after. It points within one index only.+ ``finding_id`` is the finding's public id, which round-trips through the+ ``finding_id`` selector on both surfaces. Storage row ids are republished+ on every analysis and never leave this package."""return {"finding_id": facts.finding_id,diff --git a/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py b/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.pyindex 30cac7948..bf64d6632 100644--- a/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py+++ b/packages/core/src/repowise/core/analysis/health/perf/opportunity_rank.py@@ -20,17 +20,54 @@ from math import log2from typing import AnyBOUNDARY_POINTS = {"subprocess": 5, "network": 4, "db": 4, "lock": 3, "filesystem": 2}+"""What one crossing of each boundary costs, as an order of magnitude.++A process spawn is milliseconds, a wire round-trip hundreds of microseconds up,+a pooled local query tens, and a filesystem call is usually a page-cache hit.+"A subprocess spawn in a loop is not a stat in a loop" is the whole point.+"""+MULTIPLIER_POINTS = {+ # Superlinear in the input."nested_loop_with_io": 6,"nested_loop_quadratic": 6,+ "sql_cartesian_join": 6,+ # One wait every other thread queues behind."blocking_io_under_lock": 5,+ # One boundary crossing per iteration, or one proven to sit on a hot path."io_in_loop": 4,"serial_await_in_loop": 4,"resource_construction_in_loop": 4,+ "goroutine_in_unbounded_loop": 4,+ "hot_path_sync_io": 4,+ # In-loop CPU or allocation: real, and orders below a round-trip."membership_test_against_list_in_loop": 3,"string_concat_in_loop": 3,+ "blocking_sync_in_async": 3,+ "pandas_iterrows_in_loop": 3,+ "pd_concat_in_loop": 3,+ "json_parse_in_loop": 3,+ "array_spread_in_reduce": 3,+ "defer_in_loop": 3,+ "regex_compile_in_loop": 3,+ "list_insert_zero_in_loop": 3,+ # Repeated acquisition with no boundary behind it."lock_in_loop": 2,}+"""How often the marker proves the cost is paid.++Exhaustive over every detector declaring the performance category, because+both the observation order and the opportunity order read it and a marker+missing from here would silently take the floor on both.+"""++UNKNOWN_MULTIPLIER_POINTS = 1+"""A detector added without a weight under-ranks rather than jumps the queue."""++CROSS_FUNCTION_POINTS = 1+"""A loop and a sink in different functions is the one nobody sees by reading+the loop, so it earns a point that an intra-function hit does not."""+CONTEXT_POINTS = {"production": 3, "tooling": 2, "test": 1, "unknown": 1}PROVENANCE_POINTS = {"call-site": 3, "direct": 3, "reliable-edge": 2, "name-fallback": 0}@@ -114,6 +151,20 @@ def change_risk(affected_files: int) -> str:return _band(affected_files, _CHANGE_RISK_BANDS, "wide")+def observation_rank(marker: str | None, boundary: str | None, cross_function: bool) -> int:+ """Order-of-magnitude key for one raw observation, not one opportunity.++ Findings all carry zero health impact by construction, so without this the+ performance rows in a ranked list came back in file order. Same tables as+ the opportunity order above, deliberately: "which marker costs more" is one+ question, and answering it twice with two sets of numbers is how the two+ surfaces came to disagree about the same marker.+ """+ points = MULTIPLIER_POINTS.get(marker or "", UNKNOWN_MULTIPLIER_POINTS)+ points += BOUNDARY_POINTS.get(boundary or "", 0)+ return points + (CROSS_FUNCTION_POINTS if cross_function else 0)++def rank_factors(*,marker: str,@@ -174,13 +225,16 @@ __all__ = ["AMPLIFICATION","BOUNDARY_POINTS","CONTEXT_POINTS",+ "CROSS_FUNCTION_POINTS","MULTIPLIER_POINTS","PROVENANCE_POINTS",+ "UNKNOWN_MULTIPLIER_POINTS","amplification","change_risk","dominant_marker","exposure","leverage",+ "observation_rank","rank_factors","rank_sort_key","weakest_provenance",diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.pyindex 69cf339ce..884620d32 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/__init__.py@@ -27,7 +27,7 @@ from .models import (RefactoringContext,RefactoringSuggestion,)-from .performance_fix import performance_fix_suggestions+from .performance_fix import PerformancePlanPolicy, performance_fix_suggestionsfrom .rank import rank_suggestionsfrom .registry import (RefactoringDetector,@@ -39,6 +39,7 @@ from .registry import (__all__ = ["CONFIDENCE_LEVELS",+ "PerformancePlanPolicy","RefactoringContext","RefactoringDetector","RefactoringSuggestion",diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py b/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.pyindex 525ab6345..07b520e04 100644--- a/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py+++ b/packages/core/src/repowise/core/analysis/health/refactoring/performance_fix.py@@ -3,6 +3,7 @@from __future__ import annotationsfrom collections.abc import Iterable, Mapping+from dataclasses import dataclassfrom repowise.core.analysis.execution_graph import file_of_symbol@@ -11,6 +12,19 @@ from .models import RefactoringSuggestionfrom .registry import effort_bucket+@dataclass(frozen=True, slots=True)+class PerformancePlanPolicy:+ """Whether authoritative plans are generated, and at what confidence floor.++ Read from analyzer configuration and carried to the writer that persists+ them, because that writer sees the merged stored findings and this module+ has no view of configuration.+ """++ enabled: bool = True+ min_confidence: str | None = None++def performance_fix_suggestions(opportunities: Iterable[PerformanceOpportunity],*,@@ -101,4 +115,4 @@ def performance_fix_suggestions(return out-__all__ = ["performance_fix_suggestions"]+__all__ = ["PerformancePlanPolicy", "performance_fix_suggestions"]diff --git a/packages/core/src/repowise/core/analysis/health/rows.py b/packages/core/src/repowise/core/analysis/health/rows.pynew file mode 100644index 000000000..edb909ad5--- /dev/null+++ b/packages/core/src/repowise/core/analysis/health/rows.py@@ -0,0 +1,36 @@+"""Reading one health finding whatever shape it arrives in.++A finding reaches this package as an analyzer dataclass before persistence, as+an ORM row after it, and as a plain dict in tests and fixtures. Everything that+reads one goes through these two adapters so no consumer has to know which.+"""++from __future__ import annotations++import json+from typing import Any+++def field(row: Any, name: str, default: Any = None) -> Any:+ """Read one attribute from a dataclass, an ORM row, or a dict."""+ if isinstance(row, dict):+ return row.get(name, default)+ return getattr(row, name, default)+++def detail_map(row: Any) -> dict[str, Any]:+ """The finding's open ``details`` payload, whether stored or in memory."""+ value = field(row, "details", None)+ if isinstance(value, dict):+ return value+ raw = field(row, "details_json", None)+ if isinstance(raw, str):+ try:+ loaded = json.loads(raw)+ return loaded if isinstance(loaded, dict) else {}+ except (TypeError, ValueError):+ return {}+ return {}+++__all__ = ["detail_map", "field"]diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.pyindex 83bdcec99..895bb2746 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/__init__.py@@ -8,7 +8,7 @@ imports are unaffected.from __future__ import annotations-from . import coverage, coverage_map, dead_code, health, refactoring # noqa: F401+from . import coverage, coverage_map, dead_code, health, performance, refactoring # noqa: F401from .coverage import (get_coverage_summary,load_coverage_for_repo,@@ -54,6 +54,18 @@ from .health import (upsert_health_findings,upsert_health_metrics,)+from .performance import (+ finalize_performance_opportunities,+ get_health_finding_by_public_id,+ get_performance_opportunity,+ get_performance_plan_rows,+ get_performance_summary,+ list_evidence_for_opportunities,+ list_opportunity_evidence,+ list_performance_opportunities,+ opportunity_details,+ performance_facet_counts,+)from .refactoring import (get_refactoring_suggestion,get_refactoring_suggestions,@@ -69,23 +81,33 @@ __all__ = ["backfill_module_attribution","covered_source_files","files_covered_by",+ "finalize_performance_opportunities","get_average_health","get_coverage_summary","get_dead_code_findings","get_dead_code_summary","get_deduction_by_path","get_file_language_map",+ "get_health_finding_by_public_id","get_health_findings","get_health_metrics","get_health_snapshot_file_counts","get_health_snapshot_headline","get_health_summary","get_perf_coverage",+ "get_performance_opportunity",+ "get_performance_plan_rows",+ "get_performance_summary","get_refactoring_suggestion","get_refactoring_suggestions","get_test_coverage_summary",+ "list_evidence_for_opportunities","list_health_snapshots",+ "list_opportunity_evidence",+ "list_performance_opportunities","load_coverage_for_repo",+ "opportunity_details",+ "performance_facet_counts","replace_dead_code_findings","replace_governance_findings","save_coverage_files",diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/health.py b/packages/core/src/repowise/core/persistence/crud/analysis/health.pyindex 4b76cb2b3..cc607a8eb 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/health.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/health.py@@ -26,6 +26,55 @@ from ...models import (from .._shared import _BATCH_SIZE+def _health_finding_row_kwargs(finding: Any, repository_id: str) -> dict:+ """Normalize an analyzer dataclass or a plain dict into ORM row kwargs.++ All three writers land here, so a column added to the row is written by+ every path or by none. ``public_id`` is stamped here because this is the+ one place every persisted finding passes through.+ """+ # Deferred: the analysis package imports persistence, so a module-level+ # import here would close the cycle.++ # Deferred: the analysis package imports persistence, so importing it at+ # module level here would close the cycle.+ from ....analysis.health.finding_identity import finding_public_id+ from ....analysis.health.rows import detail_map++ if hasattr(finding, "biomarker_type"):+ severity = finding.severity+ data = {+ "file_path": finding.file_path,+ "biomarker_type": finding.biomarker_type,+ "severity": str(severity.value) if hasattr(severity, "value") else str(severity),+ "function_name": finding.function_name,+ "line_start": finding.line_start,+ "line_end": finding.line_end,+ "details_json": json.dumps(finding.details or {}),+ "health_impact": float(finding.health_impact),+ "reason": finding.reason or "",+ "dimension": getattr(finding, "dimension", None) or "defect",+ }+ else:+ data = dict(finding)+ if "details" in data:+ data["details_json"] = json.dumps(data.pop("details") or {})+ data.setdefault("public_id", finding_public_id(finding))+ if data.get("dimension") == "performance":+ # Present before the finalizer runs because the analyzer stamps it into+ # ``details``; the finalizer restates it from authoritative stored rows.+ data.setdefault("opportunity_id", detail_map(finding).get("opportunity_id"))+ return {+ "id": _new_uuid(),+ "repository_id": repository_id,+ **{+ k: v+ for k, v in data.items()+ if k not in ("id", "repository_id") and hasattr(HealthFinding, k)+ },+ }++async def save_health_findings(session: AsyncSession,repository_id: str,@@ -48,37 +97,7 @@ async def save_health_findings(for i in range(0, len(findings), _BATCH_SIZE):batch = findings[i : i + _BATCH_SIZE]for f in batch:- if hasattr(f, "biomarker_type"):- severity = f.severity- severity_str = str(severity.value) if hasattr(severity, "value") else str(severity)- data = {- "file_path": f.file_path,- "biomarker_type": f.biomarker_type,- "severity": severity_str,- "function_name": f.function_name,- "line_start": f.line_start,- "line_end": f.line_end,- "details_json": json.dumps(f.details or {}),- "health_impact": float(f.health_impact),- "reason": f.reason or "",- "dimension": getattr(f, "dimension", None) or "defect",- }- else:- data = dict(f)- if "details" in data:- data["details_json"] = json.dumps(data.pop("details") or {})-- session.add(- HealthFinding(- id=_new_uuid(),- repository_id=repository_id,- **{- k: v- for k, v in data.items()- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)- },- )- )+ session.add(HealthFinding(**_health_finding_row_kwargs(f, repository_id)))await session.flush()@@ -131,37 +150,7 @@ async def replace_governance_findings(for i in range(0, len(findings), _BATCH_SIZE):batch = findings[i : i + _BATCH_SIZE]for f in batch:- if hasattr(f, "biomarker_type"):- severity = f.severity- severity_str = str(severity.value) if hasattr(severity, "value") else str(severity)- data = {- "file_path": f.file_path,- "biomarker_type": f.biomarker_type,- "severity": severity_str,- "function_name": f.function_name,- "line_start": f.line_start,- "line_end": f.line_end,- "details_json": json.dumps(f.details or {}),- "health_impact": float(f.health_impact),- "reason": f.reason or "",- "dimension": getattr(f, "dimension", None) or "defect",- }- else:- data = dict(f)- if "details" in data:- data["details_json"] = json.dumps(data.pop("details") or {})-- session.add(- HealthFinding(- id=_new_uuid(),- repository_id=repository_id,- **{- k: v- for k, v in data.items()- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)- },- )- )+ session.add(HealthFinding(**_health_finding_row_kwargs(f, repository_id)))await session.flush()@@ -942,37 +931,7 @@ async def upsert_health_findings(for i in range(0, len(scoped), _BATCH_SIZE):batch = scoped[i : i + _BATCH_SIZE]for f in batch:- if hasattr(f, "biomarker_type"):- severity = f.severity- severity_str = str(severity.value) if hasattr(severity, "value") else str(severity)- data = {- "file_path": f.file_path,- "biomarker_type": f.biomarker_type,- "severity": severity_str,- "function_name": f.function_name,- "line_start": f.line_start,- "line_end": f.line_end,- "details_json": json.dumps(f.details or {}),- "health_impact": float(f.health_impact),- "reason": f.reason or "",- "dimension": getattr(f, "dimension", None) or "defect",- }- else:- data = dict(f)- if "details" in data:- data["details_json"] = json.dumps(data.pop("details") or {})-- session.add(- HealthFinding(- id=_new_uuid(),- repository_id=repository_id,- **{- k: v- for k, v in data.items()- if k not in ("id", "repository_id") and hasattr(HealthFinding, k)- },- )- )+ session.add(HealthFinding(**_health_finding_row_kwargs(f, repository_id)))await session.flush()diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/performance.py b/packages/core/src/repowise/core/persistence/crud/analysis/performance.pynew file mode 100644index 000000000..bffb9b615--- /dev/null+++ b/packages/core/src/repowise/core/persistence/crud/analysis/performance.py@@ -0,0 +1,670 @@+"""Materialized performance opportunities: one writer, indexed readers.++Grouping runs once per health persistence transaction over the authoritative+stored findings, and everything that serves the queue reads the result. That is+the whole point of this module: a request should cost its page, not the+repository.++The writer is deliberately the only place that decides lifecycle. A cause that+stops being observed is resolved rather than deleted, so an id an agent is+holding keeps answering, and rows minted by an older model version are resolved+for the same reason - they can no longer describe the current tree.+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++from sqlalchemy import delete, func, select, update+from sqlalchemy.ext.asyncio import AsyncSession++from ...models import (+ HealthFileMetric,+ HealthFinding,+ PerformanceOpportunity,+ PerformanceSummary,+ RefactoringSuggestion,+ _new_uuid,+ _now_utc,+)+from .refactoring import _refactoring_row_kwargs++if TYPE_CHECKING:+ from ....analysis.health.perf.opportunities import (+ PerformanceOpportunity as OpportunityModel,+ )+ from ....analysis.health.refactoring.performance_fix import PerformancePlanPolicy++_PLAN_TYPE = "performance_fix"++_EVIDENCE_LIMIT = 8+"""Evidence rows folded into a persisted plan's affected-location list.++Serving reads evidence from the findings table by opportunity, so this bounds+the plan payload only.+"""++# Columns the causal model reads off a row. Narrower than the ORM entity on+# purpose: the finalizer walks every open performance finding, and ``severity``+# and ``health_impact`` are not inputs to grouping.+_OBSERVATION_COLUMNS = (+ HealthFinding.id,+ HealthFinding.public_id,+ HealthFinding.file_path,+ HealthFinding.biomarker_type,+ HealthFinding.function_name,+ HealthFinding.line_start,+ HealthFinding.line_end,+ HealthFinding.reason,+ HealthFinding.details_json,+ HealthFinding.dimension,+ HealthFinding.opportunity_id,+)+++def opportunity_details(opportunity: OpportunityModel) -> dict[str, Any]:+ """The explanatory half of one opportunity, the half no query filters on.++ Everything a column already holds is deliberately absent, so the row and+ the payload cannot drift into disagreeing about the same fact.+ """+ return {+ "biomarker_types": list(opportunity.biomarker_types),+ "shared_path_suffix": list(opportunity.shared_path_suffix),+ "resource_fingerprints": list(opportunity.resource_fingerprints),+ "reliable_entry_reachability": opportunity.reliable_entry_reachability,+ "provenance": opportunity.provenance,+ "facets": dict(opportunity.facets),+ "actionability_reason": opportunity.actionability_reason,+ "prerequisites": list(opportunity.prerequisites),+ "rank_factors": dict(opportunity.rank_factors),+ "why_ranked": [dict(entry) for entry in opportunity.why_ranked],+ "fix_rationale": opportunity.fix.rationale if opportunity.fix else None,+ }+++def _row_kwargs(+ opportunity: OpportunityModel,+ *,+ position: int,+ plan_state: str,+ analyzed_commit: str | None,+) -> dict[str, Any]:+ fix = opportunity.fix+ return {+ "opportunity_id": opportunity.opportunity_id,+ "performance_model_version": opportunity.performance_model_version,+ "status": "open",+ "rank_position": position,+ "rank_score": opportunity.rank_score,+ "execution_context": opportunity.execution_context,+ "boundary_kind": opportunity.boundary_kind,+ "biomarker_type": opportunity.biomarker_type,+ "actionability_state": opportunity.actionability_state,+ "evidence_confidence": opportunity.confidence,+ "plan_state": plan_state,+ "fix_strategy": fix.strategy if fix else None,+ "fix_safety": fix.safety if fix else None,+ "file_path": _intervention_file(opportunity),+ "intervention_symbol": opportunity.intervention_symbol,+ "terminal_sink": opportunity.terminal_sink,+ "observations_total": opportunity.observations_total,+ "affected_call_sites_total": opportunity.affected_call_sites_total,+ "affected_files_total": opportunity.affected_files_total,+ "details_json": json.dumps(opportunity_details(opportunity), separators=(",", ":")),+ "analyzed_commit": analyzed_commit,+ }+++def _intervention_file(opportunity: OpportunityModel) -> str:+ """The file a reader would open first: the intervention, else the evidence."""+ symbol = opportunity.intervention_symbol+ if symbol:+ return symbol.split("::", 1)[0]+ return opportunity.evidence[0]["file_path"] if opportunity.evidence else ""+++def _summary_payload(opportunities: list[OpportunityModel], plan_states: dict[str, str]) -> dict:+ """The compact current headline, written once and read by primary key."""+ counts: dict[str, int] = {}+ contexts: dict[str, int] = {}+ boundaries: dict[str, int] = {}+ for item in opportunities:+ counts[item.actionability_state] = counts.get(item.actionability_state, 0) + 1+ contexts[item.execution_context] = contexts.get(item.execution_context, 0) + 1+ key = item.boundary_kind or "none"+ boundaries[key] = boundaries.get(key, 0) + 1+ lead = opportunities[0] if opportunities else None+ return {+ "actionability": counts,+ "context": contexts,+ "boundary": boundaries,+ "with_plan_total": sum(1 for state in plan_states.values() if state == "available"),+ "lead": None+ if lead is None+ else {+ "opportunity_id": lead.opportunity_id,+ "actionability_state": lead.actionability_state,+ "biomarker_type": lead.biomarker_type,+ "boundary_kind": lead.boundary_kind,+ "execution_context": lead.execution_context,+ "intervention_symbol": lead.intervention_symbol,+ "terminal_sink": lead.terminal_sink,+ "file_path": _intervention_file(lead),+ "observations_total": lead.observations_total,+ "affected_call_sites_total": lead.affected_call_sites_total,+ "affected_files_total": lead.affected_files_total,+ "plan_state": plan_states.get(lead.opportunity_id, "no_safe_plan"),+ "why_ranked": [dict(entry) for entry in lead.why_ranked],+ "prerequisites": list(lead.prerequisites),+ "actionability_reason": lead.actionability_reason,+ },+ }+++async def finalize_performance_opportunities(+ session: AsyncSession,+ repository_id: str,+ *,+ analyzed_commit: str | None = None,+ plan_policy: PerformancePlanPolicy | None = None,+) -> int:+ """Rebuild this repository's performance read model from stored findings.++ Called by both the repo-wide and the per-path health writers, after their+ own rows land and inside their transaction, so the queue can never describe+ a set of findings that was never committed. Returns the number of open+ opportunities.+ """+ # Deferred throughout this module: the analysis package imports+ # persistence, so a module-level import here would close the cycle.+ from ....analysis.health.perf.opportunities import build_performance_opportunities+ from ....analysis.health.refactoring.performance_fix import PerformancePlanPolicy++ policy = plan_policy or PerformancePlanPolicy()+ rows = list(+ (+ await session.execute(+ select(*_OBSERVATION_COLUMNS).where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ HealthFinding.dimension == "performance",+ )+ )+ ).all()+ )+ opportunities = build_performance_opportunities(rows, evidence_limit=_EVIDENCE_LIMIT)++ await _restamp_findings(session, rows)+ plan_states = await _replace_plans(session, repository_id, opportunities, policy)+ await _reconcile_opportunities(session, repository_id, opportunities, plan_states, analyzed_commit)+ await _write_summary(session, repository_id, opportunities, plan_states, analyzed_commit)+ return len(opportunities)+++async def _restamp_findings(session: AsyncSession, rows: list[Any]) -> None:+ """Point every stored observation at its cause, and give it a public id.++ The causal key reads one observation's own facts, so the link only ever+ changes for rows written before the column existed or under an older model.+ """++ from ....analysis.health.finding_identity import finding_public_id+ from ....analysis.health.perf.opportunities import opportunity_id_for_finding++ changed = []+ for row in rows:+ values = {}+ if (opportunity_id := opportunity_id_for_finding(row)) != row.opportunity_id:+ values["opportunity_id"] = opportunity_id+ if not row.public_id:+ # A store written before the column existed. Backfilling here is+ # what lets its evidence carry a quotable reference without a+ # separate migration pass over the table.+ values["public_id"] = finding_public_id(row)+ if values:+ changed.append({"id": row.id, **values})+ if changed:+ await session.execute(update(HealthFinding), changed)+++async def _replace_plans(+ session: AsyncSession,+ repository_id: str,+ opportunities: list[OpportunityModel],+ policy: PerformancePlanPolicy,+) -> dict[str, str]:+ """Write the authoritative plans and report each opportunity's plan state.++ Plans are generated here rather than from an analysis report because the+ report sees one run's findings while this sees the merged stored set, and a+ partial run must not be allowed to publish a plan built from a subset.+ """++ from ....analysis.health.refactoring.performance_fix import performance_fix_suggestions++ await session.execute(+ delete(RefactoringSuggestion).where(+ RefactoringSuggestion.repository_id == repository_id,+ RefactoringSuggestion.refactoring_type == _PLAN_TYPE,+ )+ )+ states = {+ item.opportunity_id: ("no_safe_plan" if item.fix is None else "not_persisted")+ for item in opportunities+ }+ if not policy.enabled:+ return states++ nloc_by_file = dict(+ (+ await session.execute(+ select(HealthFileMetric.file_path, HealthFileMetric.nloc).where(+ HealthFileMetric.repository_id == repository_id+ )+ )+ ).all()+ )+ suggestions = performance_fix_suggestions(+ opportunities,+ nloc_by_file=nloc_by_file,+ min_confidence=policy.min_confidence,+ )+ for suggestion in suggestions:+ session.add(RefactoringSuggestion(**_refactoring_row_kwargs(suggestion, repository_id)))+ states[suggestion.plan["opportunity_id"]] = "available"+ await session.flush()+ return states+++async def _reconcile_opportunities(+ session: AsyncSession,+ repository_id: str,+ opportunities: list[OpportunityModel],+ plan_states: dict[str, str],+ analyzed_commit: str | None,+) -> None:+ """Update, insert, and resolve, in one pass over the stored rows."""+ stored = {+ (row.performance_model_version, row.opportunity_id): row+ for row in (+ await session.execute(+ select(PerformanceOpportunity).where(+ PerformanceOpportunity.repository_id == repository_id+ )+ )+ )+ .scalars()+ .all()+ }+ seen: set[tuple[int, str]] = set()+ now = _now_utc()+ for position, item in enumerate(opportunities):+ key = (item.performance_model_version, item.opportunity_id)+ seen.add(key)+ values = _row_kwargs(+ item,+ position=position,+ plan_state=plan_states.get(item.opportunity_id, "no_safe_plan"),+ analyzed_commit=analyzed_commit,+ )+ row = stored.get(key)+ if row is None:+ session.add(+ PerformanceOpportunity(+ 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():+ # A cause nobody observed this run, or one an older model minted, is+ # resolved rather than removed: a held id must keep answering, and it+ # must not keep reading as current.+ 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],+ plan_states: dict[str, str],+ analyzed_commit: str | None,+) -> None:++ from ....analysis.health.perf.opportunities import PERFORMANCE_MODEL_VERSION++ payload = json.dumps(_summary_payload(opportunities, plan_states), separators=(",", ":"))+ row = await session.get(PerformanceSummary, repository_id)+ if row is None:+ row = PerformanceSummary(repository_id=repository_id)+ session.add(row)+ row.performance_model_version = PERFORMANCE_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+# ---------------------------------------------------------------------------+++async def get_performance_summary(+ session: AsyncSession, repository_id: str+) -> PerformanceSummary | None:+ """The current headline, by primary key. One statement, no scan."""+ return await session.get(PerformanceSummary, repository_id)+++async def get_performance_opportunity(+ session: AsyncSession, repository_id: str, opportunity_id: str+) -> PerformanceOpportunity | None:+ """One materialized opportunity, current model or resolved older one."""+ result = await session.execute(+ select(PerformanceOpportunity)+ .where(+ PerformanceOpportunity.repository_id == repository_id,+ PerformanceOpportunity.opportunity_id == opportunity_id,+ )+ .order_by(PerformanceOpportunity.performance_model_version.desc())+ .limit(1)+ )+ return result.scalars().first()+++def _predicates(+ repository_id: str,+ *,+ contexts: frozenset[str] | None,+ boundary: str | None,+ confidence: str | None,+ actionability: str | None,+ file_paths: tuple[str, ...] | None,+) -> list[Any]:+ where: list[Any] = [+ PerformanceOpportunity.repository_id == repository_id,+ PerformanceOpportunity.status == "open",+ ]+ if contexts is not None:+ where.append(PerformanceOpportunity.execution_context.in_(sorted(contexts)))+ if boundary is not None:+ where.append(+ PerformanceOpportunity.boundary_kind.is_(None)+ if boundary == "none"+ else PerformanceOpportunity.boundary_kind == boundary+ )+ if confidence is not None:+ where.append(PerformanceOpportunity.evidence_confidence == confidence)+ if actionability is not None:+ where.append(PerformanceOpportunity.actionability_state == actionability)+ if file_paths is not None:+ where.append(PerformanceOpportunity.file_path.in_(list(file_paths)))+ return where+++_ORDERS = {+ "rank": (PerformanceOpportunity.rank_position.asc(),),+ "leverage": (+ PerformanceOpportunity.affected_call_sites_total.desc(),+ PerformanceOpportunity.rank_position.asc(),+ ),+ "observations": (+ PerformanceOpportunity.observations_total.desc(),+ PerformanceOpportunity.rank_position.asc(),+ ),+}+"""Orderings the queue offers, each ending in rank so every one is total.++Applied in SQL rather than to the fetched page: sorting a page selected by a+different key would order twenty rows correctly and the repository wrongly.+"""+++async def list_performance_opportunities(+ session: AsyncSession,+ repository_id: str,+ *,+ contexts: frozenset[str] | None = None,+ boundary: str | None = None,+ confidence: str | None = None,+ actionability: str | None = None,+ file_paths: tuple[str, ...] | None = None,+ sort: str = "rank",+ limit: int = 20,+ offset: int = 0,+) -> tuple[list[PerformanceOpportunity], int]:+ """One page in the requested order, plus the exact total behind it.++ Both statements are index-driven and the fetched rows are the page, so cost+ tracks the page rather than the repository.+ """+ where = _predicates(+ repository_id,+ contexts=contexts,+ boundary=boundary,+ confidence=confidence,+ actionability=actionability,+ file_paths=file_paths,+ )+ total = int(+ (+ await session.execute(+ select(func.count()).select_from(PerformanceOpportunity).where(*where)+ )+ ).scalar_one()+ )+ rows = (+ (+ await session.execute(+ select(PerformanceOpportunity)+ .where(*where)+ .order_by(*_ORDERS.get(sort, _ORDERS["rank"]))+ .offset(offset)+ .limit(limit)+ )+ )+ .scalars()+ .all()+ )+ return list(rows), total+++async def performance_facet_counts(+ session: AsyncSession,+ repository_id: str,+ *,+ file_paths: tuple[str, ...] | None = None,+) -> list[tuple[str, str | None, str, str, str, int]]:+ """Grouped counts over every open opportunity, in one aggregate statement.++ Returned pre-aggregation rather than as finished facets so the caller can+ cross-filter: a facet must be counted with every filter applied *except*+ its own, or choosing one value would erase the alternatives.+ """+ where = _predicates(+ repository_id,+ contexts=None,+ boundary=None,+ confidence=None,+ actionability=None,+ file_paths=file_paths,+ )+ result = await session.execute(+ select(+ PerformanceOpportunity.execution_context,+ PerformanceOpportunity.boundary_kind,+ PerformanceOpportunity.evidence_confidence,+ PerformanceOpportunity.actionability_state,+ PerformanceOpportunity.plan_state,+ func.count(),+ )+ .where(*where)+ .group_by(+ PerformanceOpportunity.execution_context,+ PerformanceOpportunity.boundary_kind,+ PerformanceOpportunity.evidence_confidence,+ PerformanceOpportunity.actionability_state,+ PerformanceOpportunity.plan_state,+ )+ )+ return [tuple(row) for row in result.all()]+++async def get_performance_plan_rows(+ session: AsyncSession, repository_id: str, opportunity_ids: list[str]+) -> dict[str, RefactoringSuggestion]:+ """The plans for one page of opportunities, in one indexed batch."""+ if not opportunity_ids:+ return {}+ rows = (+ (+ await session.execute(+ select(RefactoringSuggestion).where(+ RefactoringSuggestion.repository_id == repository_id,+ RefactoringSuggestion.refactoring_type == _PLAN_TYPE,+ RefactoringSuggestion.opportunity_id.in_(opportunity_ids),+ )+ )+ )+ .scalars()+ .all()+ )+ matches: dict[str, RefactoringSuggestion] = {}+ for row in rows:+ # The writer replaces every plan for the repository, so one per cause is+ # what a store this writer produced holds. Choosing deterministically+ # keeps a store an older writer left with two from returning a different+ # plan on every read.+ key = row.opportunity_id+ if key and (key not in matches or row.id < matches[key].id):+ matches[key] = row+ return matches+++async def list_opportunity_evidence(+ session: AsyncSession,+ repository_id: str,+ opportunity_id: str,+ *,+ limit: int = 8,+ offset: int = 0,+ total: int | None = None,+) -> tuple[list[Any], int]:+ """One page of the observations behind a cause, and their exact total.++ A caller holding the opportunity row already knows the total, and it is the+ same number over the same rows in the same transaction, so passing it in+ saves a count.+ """+ where = [+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ HealthFinding.dimension == "performance",+ HealthFinding.opportunity_id == opportunity_id,+ ]+ if total is None:+ total = int(+ (+ await session.execute(+ select(func.count()).select_from(HealthFinding).where(*where)+ )+ ).scalar_one()+ )+ rows = (+ await session.execute(+ select(*_OBSERVATION_COLUMNS)+ .where(*where)+ .order_by(+ HealthFinding.file_path.asc(),+ HealthFinding.line_start.asc(),+ HealthFinding.id.asc(),+ )+ .offset(offset)+ .limit(limit)+ )+ ).all()+ return list(rows), total+++async def list_evidence_for_opportunities(+ session: AsyncSession,+ repository_id: str,+ opportunity_ids: list[str],+ *,+ per_opportunity: int = 3,+) -> dict[str, list[Any]]:+ """A few evidence rows for each opportunity on a page, in one statement.++ Ranked inside the database rather than fetched and trimmed afterwards, so+ a page containing one very large cause still reads a bounded number of+ rows. Both supported backends implement the window function this uses.+ """+ if not opportunity_ids or per_opportunity <= 0:+ return {}+ ranked = (+ select(+ *_OBSERVATION_COLUMNS,+ func.row_number()+ .over(+ partition_by=HealthFinding.opportunity_id,+ order_by=(+ HealthFinding.file_path.asc(),+ HealthFinding.line_start.asc(),+ HealthFinding.id.asc(),+ ),+ )+ .label("position"),+ )+ .where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ HealthFinding.dimension == "performance",+ HealthFinding.opportunity_id.in_(opportunity_ids),+ )+ .subquery()+ )+ rows = (+ await session.execute(select(ranked).where(ranked.c.position <= per_opportunity))+ ).all()+ grouped: dict[str, list[Any]] = {}+ for row in sorted(rows, key=lambda item: item.position):+ grouped.setdefault(row.opportunity_id, []).append(row)+ return grouped+++async def get_health_finding_by_public_id(+ session: AsyncSession, repository_id: str, public_id: str+) -> HealthFinding | None:+ """One finding by its quoted public id, through the index."""+ result = await session.execute(+ select(HealthFinding)+ .where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.public_id == public_id,+ )+ .limit(1)+ )+ return result.scalars().first()+++__all__ = [+ "finalize_performance_opportunities",+ "get_health_finding_by_public_id",+ "get_performance_opportunity",+ "get_performance_plan_rows",+ "get_performance_summary",+ "list_evidence_for_opportunities",+ "list_opportunity_evidence",+ "list_performance_opportunities",+ "opportunity_details",+ "performance_facet_counts",+]diff --git a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.pyindex ae324511c..87b6c932b 100644--- a/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py+++ b/packages/core/src/repowise/core/persistence/crud/analysis/refactoring.py@@ -37,6 +37,17 @@ def _refactoring_row_kwargs(suggestion: Any, repository_id: str) -> dict:if key in data:data[f"{key}_json"] = json.dumps(data.pop(key) or {})+ if data.get("refactoring_type") == "performance_fix":+ # Lift the causal id out of the plan payload into its own column. Two+ # surfaces used to answer "does this opportunity have a plan" by reading+ # two different JSON fields, and one of them always said no.+ try:+ plan = json.loads(data.get("plan_json") or "{}")+ except (TypeError, ValueError):+ plan = {}+ if isinstance(plan, dict) and isinstance(plan.get("opportunity_id"), str):+ data.setdefault("opportunity_id", plan["opportunity_id"])+return {"id": _new_uuid(),"repository_id": repository_id,diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.pyindex 89e25e880..c1039d582 100644--- a/packages/core/src/repowise/core/persistence/models.py+++ b/packages/core/src/repowise/core/persistence/models.py@@ -1199,6 +1199,15 @@ class HealthFinding(Base):# performance). Nullable + no backfill: old rows stay NULL until the next# index recomputes them; new writes always set it (defaults to "defect").dimension: Mapped[str | None] = mapped_column(String(16), nullable=True, default="defect")+ # The finding's stable public identity, from+ # ``analysis.health.finding_identity``. Stored so a quoted id resolves by+ # index instead of by hashing every open row. Nullable while stores written+ # before the column existed still carry NULL.+ public_id: Mapped[str | None] = mapped_column(String(64), nullable=True)+ # The causal performance opportunity this observation belongs to, on+ # performance rows only. Also inside ``details_json``; the column is what+ # makes "the evidence for this opportunity" an indexed seek.+ opportunity_id: Mapped[str | None] = mapped_column(String(64), nullable=True)status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=_now_utc@@ -1207,15 +1216,24 @@ class HealthFinding(Base):DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc)- # The table had no index at all, so every read full-scanned it. Two shapes+ # The table had no index at all, so every read full-scanned it. Four shapes# are served: a file-scoped lookup (``get_health`` with targets, the call an- # agent makes to self-check a file before and after an edit) and a- # repo-wide top-N ordered by impact. The first index turns the scan into a- # seek; the second lets the ranked read stop early instead of sorting the- # whole table into a temp B-tree.+ # agent makes to self-check a file before and after an edit), a repo-wide+ # top-N ordered by impact, a quoted public id, and the evidence for one+ # causal opportunity. The first turns the scan into a seek; the second lets+ # the ranked read stop early instead of sorting the whole table into a temp+ # B-tree; the last two keep drill-down proportional to the page.__table_args__ = (Index("ix_health_findings_repo_status_path", "repository_id", "status", "file_path"),Index("ix_health_findings_repo_status_impact", "repository_id", "status", "health_impact"),+ Index("ix_health_findings_repo_public_id", "repository_id", "public_id"),+ Index(+ "ix_health_findings_repo_status_dimension_opportunity",+ "repository_id",+ "status",+ "dimension",+ "opportunity_id",+ ),)@@ -1248,6 +1266,12 @@ class RefactoringSuggestion(Base):blast_radius_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")confidence: Mapped[str] = mapped_column(String(16), nullable=False, default="medium")source_biomarker: Mapped[str] = mapped_column(String(64), nullable=False, default="")+ # The performance opportunity this plan addresses, on ``performance_fix``+ # rows only. The id also sits inside ``plan_json``; the column is the+ # repository-scoped link the queue joins on, so linking a page of+ # opportunities to their plans is one indexed batch rather than a scan of+ # every plan's JSON.+ opportunity_id: Mapped[str | None] = mapped_column(String(64), nullable=True)status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=_now_utc@@ -1256,6 +1280,133 @@ class RefactoringSuggestion(Base):DateTime(timezone=True), nullable=False, default=_now_utc, onupdate=_now_utc)+ __table_args__ = (+ Index(+ "ix_refactoring_suggestions_repo_type_opportunity",+ "repository_id",+ "refactoring_type",+ "opportunity_id",+ ),+ )+++class PerformanceOpportunity(Base):+ """One causal performance opportunity, materialized for serving.++ The queue used to be rebuilt from every open performance finding on every+ request, so a page of twenty cost the whole repository. Grouping happens+ once, when findings are persisted, and lands 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. Everything+ explanatory - facets, rank factors, why-ranked, prerequisites, path suffix -+ stays in ``details_json``, where a new fact costs no migration.+ """++ __tablename__ = "performance_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+ )+ # Public causal id, ``perf<model>_<digest>``. Unique per repository *and*+ # model version, never globally: the same cause in two repositories is two+ # rows, and two model versions disagree about membership by construction.+ opportunity_id: Mapped[str] = mapped_column(String(64), nullable=False)+ performance_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ # ``open`` or ``resolved``. A cause that stops being observed is resolved,+ # not deleted, so a quoted id keeps answering after the code was fixed.+ status: Mapped[str] = mapped_column(String(32), nullable=False, default="open")+ # Position in the deterministic total order, so the queue reads in rank+ # order from an index rather than sorting the repository per request.+ rank_position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ rank_score: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ execution_context: Mapped[str] = mapped_column(String(16), nullable=False, default="unknown")+ boundary_kind: Mapped[str | None] = mapped_column(String(32), nullable=True)+ biomarker_type: Mapped[str] = mapped_column(String(64), nullable=False, default="")+ actionability_state: Mapped[str] = mapped_column(String(16), nullable=False, default="investigate")+ evidence_confidence: Mapped[str] = mapped_column(String(16), nullable=False, default="low")+ # ``available`` | ``no_safe_plan`` | ``not_persisted``, decided once by the+ # writer that also decides whether a plan row exists.+ plan_state: Mapped[str] = mapped_column(String(16), nullable=False, default="no_safe_plan")+ fix_strategy: Mapped[str | None] = mapped_column(String(64), nullable=True)+ fix_safety: Mapped[str | None] = mapped_column(String(16), nullable=True)+ # The file holding the symbol worth editing, so target scoping is a column.+ file_path: Mapped[str] = mapped_column(Text, nullable=False, default="")+ intervention_symbol: Mapped[str | None] = mapped_column(Text, nullable=True)+ terminal_sink: Mapped[str | None] = mapped_column(Text, nullable=True)+ observations_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ affected_call_sites_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ affected_files_total: Mapped[int] = mapped_column(Integer, nullable=False, default=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",+ "performance_model_version",+ "opportunity_id",+ name="uq_performance_opportunities_repo_model_id",+ ),+ Index("ix_performance_opportunities_repo_id", "repository_id", "opportunity_id"),+ Index(+ "ix_performance_opportunities_repo_status_rank",+ "repository_id",+ "status",+ "rank_position",+ ),+ Index(+ "ix_performance_opportunities_repo_status_context_rank",+ "repository_id",+ "status",+ "execution_context",+ "rank_position",+ ),+ Index(+ "ix_performance_opportunities_repo_status_action_rank",+ "repository_id",+ "status",+ "actionability_state",+ "rank_position",+ ),+ Index("ix_performance_opportunities_repo_status_path", "repository_id", "status", "file_path"),+ )+++class PerformanceSummary(Base):+ """The current performance headline for one repository, in one row.++ A bare dashboard call must be able to lead with something actionable+ without touching the queue, so the lead and the counts are written by the+ same transaction that materializes the opportunities and read back by+ primary key. One row per repository: this is the *current* state, not+ history, and must never be served from a trend snapshot.+ """++ __tablename__ = "performance_summaries"++ repository_id: Mapped[str] = mapped_column(+ String(32),+ ForeignKey("repositories.id", ondelete="CASCADE"),+ primary_key=True,+ )+ performance_model_version: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ opportunities_total: Mapped[int] = mapped_column(Integer, nullable=False, default=0)+ # Counts, context split, and the single lead. Read whole or not at all, so+ # there is nothing to filter on and no reason to spend columns.+ 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 b0e646d88..9f7a89051 100644--- a/packages/core/src/repowise/core/pipeline/incremental.py+++ b/packages/core/src/repowise/core/pipeline/incremental.py@@ -938,6 +938,7 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Nonand metrics across an incremental ``repowise update``."""from repowise.core.persistence.crud import (+ finalize_performance_opportunities,upsert_health_findings,upsert_health_metrics,upsert_refactoring_suggestions,@@ -952,54 +953,55 @@ async def persist_partial_health(session: Any, repo_id: str, report: Any) -> Non)if not changed_paths and not performance_paths:return- if changed_paths:- await upsert_health_metrics(- session,- repo_id,- report.metrics or [],- analyzed_commit=await _analyzed_commit(session, repo_id),- )- await upsert_health_findings(- session, repo_id, list(report.findings or []), file_paths=changed_paths- )- if performance_paths:- await upsert_health_findings(- session,- repo_id,- list(report.findings or []),- file_paths=performance_paths,- dimension="performance",- )- # Refactoring suggestions for the changed files only (unchanged files keep- # theirs). Scoped delete-then-insert across the full changed-file set, so a- # file that became clean has its stale suggestions removed.- if changed_paths:- await upsert_refactoring_suggestions(- session,- repo_id,- list(getattr(report, "refactoring_suggestions", None) or []),- file_paths=changed_paths,- )- if performance_paths:- performance_suggestions = [- suggestion- for suggestion in list(getattr(report, "refactoring_suggestions", None) or [])- if suggestion.refactoring_type == "performance_fix"- ]- # A causal plan is stored at its shared intervention, which can sit- # downstream of every caller file in the performance invalidation- # closure. Include those targets in the scoped replacement or the- # findings refresh while their matching plans are silently discarded.- performance_plan_paths = sorted(- set(performance_paths)- | {suggestion.file_path for suggestion in performance_suggestions}- )- await upsert_refactoring_suggestions(+ analyzed_commit = await _analyzed_commit(session, repo_id)+ # One savepoint over the findings and everything derived from them. This+ # writer's caller logs a failed step and carries on to commit the rest of+ # the run, so without the savepoint a rebuild that failed halfway would+ # leave the queue describing findings that were never stored.+ async with session.begin_nested():+ if changed_paths:+ await upsert_health_metrics(+ session,+ repo_id,+ report.metrics or [],+ analyzed_commit=analyzed_commit,+ )+ await upsert_health_findings(+ session, repo_id, list(report.findings or []), file_paths=changed_paths+ )+ if performance_paths:+ await upsert_health_findings(+ session,+ repo_id,+ list(report.findings or []),+ file_paths=performance_paths,+ dimension="performance",+ )+ # Refactoring suggestions for the changed files only (unchanged files+ # keep theirs). Scoped delete-then-insert across the full changed-file+ # set, so a file that became clean has its stale suggestions removed.+ if changed_paths:+ await upsert_refactoring_suggestions(+ session,+ repo_id,+ [+ suggestion+ for suggestion in (getattr(report, "refactoring_suggestions", None) or [])+ if suggestion.refactoring_type != "performance_fix"+ ],+ file_paths=changed_paths,+ )+ # A partial run sees a subset of the findings, so the plans and the+ # queue it would derive are a subset too. Both are rebuilt here instead,+ # from the merged stored rows, by the same writer the full path uses.+ # That is what makes the two paths agree, and it retires the file-scoped+ # plan bookkeeping that used to try to reach a shared intervention from+ # its callers.+ await finalize_performance_opportunities(session,repo_id,- performance_suggestions,- file_paths=performance_plan_paths,- refactoring_type="performance_fix",+ analyzed_commit=analyzed_commit,+ plan_policy=getattr(report, "performance_plan_policy", None),)# Per-function blame rollup for the changed files (keeps git_function_blame# current between full indexes; FULL git tier only — empty otherwise).diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex f8ce2e64d..47f11235a 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -1512,6 +1512,7 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:from repowise.core.analysis.health.trends import snapshot_file_mapsfrom repowise.core.persistence.crud import (bulk_upsert_decisions,+ finalize_performance_opportunities,recompute_decision_staleness,save_coverage_files,save_dead_code_findings,@@ -1534,8 +1535,35 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:# index instead of assuming the two moved together.head_sha = getattr(result, "head_commit", None) or getattr(result, "commit_sha", None)await save_health_metrics(session, repo_id, hr.metrics or [], analyzed_commit=head_sha)- if hr.findings:- await save_health_findings(session, repo_id, hr.findings)+ # One savepoint over the findings and everything derived from them, so+ # a rebuild that failed halfway cannot leave the queue describing+ # findings that were never stored. It runs on an empty finding set too:+ # the queue has to be reconciled to nothing just the same.+ async with session.begin_nested():+ if hr.findings:+ await save_health_findings(session, repo_id, hr.findings)+ # Structured refactoring suggestions (Extract Class, ...). Repo-wide+ # delete-then-insert like findings; empty list clears prior rows.+ # Performance plans are excluded: the finalizer below owns them, so+ # they are generated once, from the merged stored findings, by the+ # same writer on the full and the incremental path.+ await save_refactoring_suggestions(+ session,+ repo_id,+ [+ suggestion+ for suggestion in (getattr(hr, "refactoring_suggestions", None) or [])+ if getattr(suggestion, "refactoring_type", None) != "performance_fix"+ ],+ )+ # Group the stored performance findings into the materialized causal+ # read model, then reconcile lifecycle and plans.+ await finalize_performance_opportunities(+ session,+ repo_id,+ analyzed_commit=head_sha,+ plan_policy=getattr(hr, "performance_plan_policy", None),+ )# Resolved coverage rows, when a report was ingested this run.coverage_files = getattr(hr, "coverage_files", None)if coverage_files:@@ -1546,11 +1574,6 @@ async def persist_analysis(result: Any, session: Any, repo_id: str) -> None:source_format=getattr(hr, "coverage_format", None) or "lcov",ingested_commit_sha=head_sha,)- # Structured refactoring suggestions (Extract Class, ...). Repo-wide- # delete-then-insert like findings; empty list clears prior rows.- await save_refactoring_suggestions(- session, repo_id, getattr(hr, "refactoring_suggestions", None) or []- )# Per-function blame rollup (FULL tier only; empty otherwise).fn_blame_rows = getattr(hr, "function_blame_rows", None)if fn_blame_rows:diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pyindex c15cf2be1..a15d59890 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py@@ -178,12 +178,19 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"metrics[]","refactoring_plans[]","performance_opportunities[]",+ "performance_summary","high_leverage_files[]","secondary_rankings",),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.+ "performance_directive",+ "opportunity_id",+ "model_state","targets","unresolved","known_modules",diff --git a/packages/server/src/repowise/server/mcp_server/_references.py b/packages/server/src/repowise/server/mcp_server/_references.pyindex bc1d5ac03..a6bff398a 100644--- a/packages/server/src/repowise/server/mcp_server/_references.py+++ b/packages/server/src/repowise/server/mcp_server/_references.py@@ -125,6 +125,35 @@ def stable_entity_id(prefix: str, repository: str, coordinates: Mapping[str, objreturn f"{prefix}_{content_id(identity)}"+def refactoring_plan_id(suggestion: Any, repository: str) -> str:+ """Return the public ID for one refactoring plan, ORM row or dataclass.++ Lives here rather than beside one caller because two surfaces address the+ same plan and must arrive at the same string.+ """++ raw_plan = getattr(suggestion, "plan", None)+ if raw_plan is None:+ raw_plan = getattr(suggestion, "plan_json", None) or "{}"+ try:+ raw_plan = json.loads(raw_plan)+ except (TypeError, json.JSONDecodeError):+ raw_plan = str(raw_plan)+ return stable_entity_id(+ "plan",+ repository,+ {+ "path": path_identity(suggestion.file_path),+ "kind": suggestion.refactoring_type,+ "symbol": suggestion.target_symbol or "",+ "line_start": suggestion.line_start,+ "line_end": suggestion.line_end,+ "source_biomarker": suggestion.source_biomarker or "",+ "plan": raw_plan,+ },+ )++# Compatibility aliases for the get_why-specific module that originally# owned these primitives. Keeping the private spellings prevents a mechanical# promotion from changing sealed evidence identities or downstream imports.@@ -138,6 +167,7 @@ __all__ = ["content_id","omission_reference","path_identity",+ "refactoring_plan_id","reference","repository_identity","source_reference",diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.pyindex 94e37f6fa..1cb824927 100644--- a/packages/server/src/repowise/server/mcp_server/tool_health.py+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py@@ -4,7 +4,7 @@ from __future__ import annotationsimport hashlibimport json-from dataclasses import asdict+from dataclasses import asdict, dataclass, fieldfrom pathlib import Pathfrom time import perf_counterfrom typing import Any@@ -16,10 +16,11 @@ from repowise.core.analysis.health.churn_complexity import churn_complexity_poinfrom repowise.core.analysis.health.complexity.languages import LANGUAGE_MAPSfrom repowise.core.analysis.health.coverage import decay_since, measurement_reffrom repowise.core.analysis.health.defect_accuracy import compute_defect_accuracy+from repowise.core.analysis.health.finding_identity import finding_public_idfrom repowise.core.analysis.health.grading import HEALTHY_MIN, band_forfrom repowise.core.analysis.health.grading import distribution as health_distributionfrom repowise.core.analysis.health.perf.coverage import PerfCoverage, coverage_for_metrics-from repowise.core.analysis.health.perf.opportunities import build_performance_opportunities+from repowise.core.analysis.health.perf.opportunity_rank import observation_rankfrom repowise.core.analysis.health.refactoring.recommendations import (Recommendation,build_recommendations,@@ -36,6 +37,7 @@ from repowise.core.persistence.crud import (get_coverage_summary,get_file_language_map,get_git_metadata_bulk,+ get_health_finding_by_public_id,get_hotspot_file_paths,get_node_degree_counts_bulk,get_refactoring_suggestions,@@ -60,106 +62,226 @@ from repowise.server.mcp_server._helpers import (filter_rows_by_attr,)from repowise.server.mcp_server._meta import build_meta as _build_meta-from repowise.server.mcp_server._references import path_identity, stable_entity_id--# How much a single execution of each I/O boundary costs, as an order of-# magnitude rather than a measurement: a process spawn is milliseconds, a wire-# round-trip is hundreds of microseconds up, a pooled local query is tens, and a-# filesystem call is usually a page-cache hit. "A subprocess spawn in a loop is-# not a filesystem stat in a loop" is the whole point of ranking on this.-_PERF_BOUNDARY_POINTS = {"subprocess": 4, "network": 3, "db": 2, "lock": 2, "filesystem": 1}--# What the marker itself proves about *how often* the boundary cost is paid.-# Two independent proofs, and neither dominates — which is why the three signals-# are added rather than multiplied:-#-# * a **multiplier** — the cost repeats per iteration (N), per nested pair-# (N x M), or quadratically. Every ``*_in_loop`` marker carries this.-# * **hotness** — the cost is paid on a request-reachable path.-# ``hot_path_sync_io`` and ``nested_loop_quadratic`` are the request--# reachability signal, and it needs no new column: both are emitted **only**-# for a function ``perf.ranking.PerfRanker`` called hot (top-quintile-# call-graph in-degree, or a churny/hotspot file), so their presence is-# already a proof. ``blocking_io_under_lock`` proves something adjacent —-# every thread serializes behind the wait.-#-# ``hot_path_sync_io`` therefore sits level with a plain loop marker, not above-# it: it proves hotness and no multiplier, and a loop proves a multiplier and no-# hotness. Boundary kind is what separates them in practice.-#-# Deliberately not ``severity``: the column disagrees with this ordering and-# cannot be fixed from here without a re-score. ``hot_path_sync_io`` is written-# ``LOW`` and ``io_in_loop`` ``MEDIUM``, so the marker carrying a hotness proof-# is graded *below* the ungated one — and on this repo severity takes exactly-# two values across all 697 perf findings (522 medium, 175 low), which is not-# an ordering.-#-# Exhaustive over the 20 detectors declaring ``category = "performance"``;-# ``test_perf_rank.py`` fails if a new one is added without a weight, so the-# default below is a guard rather than a resting place.-_PERF_MARKER_POINTS = {- # Superlinear, and gated on hotness.- "nested_loop_quadratic": 5,- # N x M round-trips, or a wait every thread queues behind.- "nested_loop_with_io": 4,- "blocking_io_under_lock": 4,- "sql_cartesian_join": 4,- # One boundary crossing per iteration — the N+1 family.- "io_in_loop": 3,- "serial_await_in_loop": 3,- "lock_in_loop": 3,- "goroutine_in_unbounded_loop": 3,- "resource_construction_in_loop": 3,- # One crossing, but proven to sit on a hot path.- "hot_path_sync_io": 3,- # In-loop CPU/allocation costs: real, and orders below a round-trip.- "blocking_sync_in_async": 2,- "pandas_iterrows_in_loop": 2,- "pd_concat_in_loop": 2,- "json_parse_in_loop": 2,- "array_spread_in_reduce": 2,- "defer_in_loop": 2,- "regex_compile_in_loop": 1,- "string_concat_in_loop": 1,- "membership_test_against_list_in_loop": 1,- "list_insert_zero_in_loop": 1,-}+from repowise.server.mcp_server._references import (+ path_identity,+ refactoring_plan_id,+ stable_entity_id,+)+from repowise.server.services.performance_health import (+ PerformanceHealthService,+ PerformancePage,+ evidence_block,+ parse_query,+)++_PERFORMANCE_COLLECTION_CAP = 6+"""Opportunities per response, independent of ``limit``. ``cursor`` pages it."""++_PERFORMANCE_EVIDENCE_CAP = 3+"""Evidence rows per opportunity in the collection. The detail call pages more."""++_PERFORMANCE_EVIDENCE_PAGE_CAP = 20+"""Ceiling on one evidence page. ``limit`` still means what it says below it,+including ``limit=0`` for the totals and no rows."""+++def _selector_conflict(**selectors: str | None) -> dict[str, Any] | None:+ """Refuse two detail selectors instead of answering about one of them.++ Preferring whichever was checked first gave a caller a confident answer to+ a question they had not only asked, with no sign the other was dropped.+ """+ named = sorted(name for name, value in selectors.items() if value)+ if len(named) < 2:+ return None+ return {+ "mode": "conflict",+ "resolved": False,+ "reason": "mutually_exclusive_selectors",+ "selectors": named,+ "detail": "Pass exactly one of finding_id, plan_id, opportunity_id.",+ }+++@dataclass(frozen=True, slots=True)+class _PerformanceBlocks:+ """Everything the performance pillar contributes to one response."""++ page: PerformancePage | None = None+ summary: dict[str, Any] | None = None+ directive: dict[str, Any] | None = None+ ignored: dict[str, str] = field(default_factory=dict)+++async def _performance_blocks(+ service: PerformanceHealthService,+ *,+ wants: Any,+ included: bool,+ file_paths: tuple[str, ...] | None,+ scoped: bool,+ limit: int,+ cursor: int,+ view: str | None,+ context: str | None,+ boundary: str | None,+ confidence: str | None,+ sort: str | None,+) -> _PerformanceBlocks:+ """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:+ # The lede quotes only the first row and no evidence, so a projection+ # down to it reads one row rather than a page of six.+ emits_queue = wants("performance_opportunities")+ query, ignored = parse_query(+ context=context,+ boundary=boundary,+ confidence=confidence,+ view=view,+ sort=sort,+ file_paths=file_paths,+ limit=min(max(limit, 0), _PERFORMANCE_COLLECTION_CAP) if emits_queue else 1,+ offset=cursor if emits_queue else 0,+ )+ page = await service.page(+ query,+ evidence_per_item=_PERFORMANCE_EVIDENCE_CAP if emits_queue else 0,+ # Facets are rendered by the summary block alone, so a queue or a+ # lede does not pay for the aggregate.+ with_facets=wants("performance_summary"),+ )+ return _PerformanceBlocks(+ page=page,+ summary=await service.summary() if included and wants("performance_summary") else None,+ # The bare dashboard lead: one primary-key read of the current summary+ # row, so it does not grow with the repository and never touches the+ # queue.+ directive=(+ await service.directive() if not scoped and wants("performance_directive") else None+ ),+ ignored=ignored,+ )+++async def _resolve_finding(+ session: Any, repository_id: str, finding_id: str, repository: str+) -> Any:+ """Find one health finding by any id form a caller can be holding.++ The public id is a column, so the common case is a seek. The scan is the+ compatibility path: a raw storage id, or an id minted before the column+ existed, still has to resolve.+ """+ match = await get_health_finding_by_public_id(session, repository_id, finding_id)+ if match is not None:+ return match+ rows = (+ (+ await session.execute(+ select(HealthFinding).where(+ HealthFinding.repository_id == repository_id,+ HealthFinding.status == "open",+ )+ )+ )+ .scalars()+ .all()+ )+ return next(+ (+ row+ for row in rows+ if finding_id+ in {+ row.id,+ _health_finding_id(row, repository),+ _legacy_health_finding_id(row, repository),+ }+ ),+ None,+ )-# Unknown marker. Deliberately the floor, not the middle: a detector added-# without a weight should under-rank rather than jump the queue, the same-# degrade-to-no-signal direction the perf gate itself takes.-_PERF_UNKNOWN_MARKER_POINTS = 1-# A hit whose loop and whose sink are in different functions. Worth a point on-# its own: an intra-function loop is often visibly bounded at the call site,-# while a cross-function N+1 is the one nobody sees by reading the loop.-_PERF_CROSSFN_POINTS = 1+async def _performance_detail_response(+ session: Any,+ repository: Any,+ reference_repository: str,+ opportunity_id: str,+ *,+ evidence_only: bool,+ limit: int,+ cursor: int,+) -> dict[str, Any]:+ """One causal opportunity, or one page of the evidence behind it.++ ``limit`` means what it means everywhere else, ``0`` included: reading it+ as "unset" would return a page the caller declined.+ """+ service = PerformanceHealthService(session, repository.id, reference_repository)+ evidence_limit = min(max(limit, 0), _PERFORMANCE_EVIDENCE_PAGE_CAP)+ if evidence_only:+ rows, total = await service.evidence(+ opportunity_id, limit=evidence_limit, offset=cursor+ )+ return {+ "mode": "performance_evidence",+ "opportunity_id": opportunity_id,+ "resolved": total > 0,+ **evidence_block(rows, total, cursor),+ "_meta": _build_meta(repository=repository),+ }+ detail = await service.detail(opportunity_id, evidence_limit=evidence_limit)+ file_path = detail.get("file_path")+ result = {+ "mode": "performance_opportunity",+ **detail,+ "_meta": _build_meta(+ 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()+ )+ if file_path+ else []+ )+ _attach_health_analysis_meta(result["_meta"], metric_rows)+ return resultdef _perf_rank(biomarker_type: str | None, details: Any) -> int:- """Order-of-magnitude ranking key for one ``performance`` finding.-- The performance dimension had none. Every finding carries- ``health_impact: 0`` by construction — the dimension is deliberately never- blended into the score — so the list came back in whatever order the impact- tie broke, which is file order. "Which of these 697 matters" was- unanswerable from the payload, and worse, the *cap* was arbitrary too: with- ``include=['performance']`` the head is 20 of 697 chosen by nothing.-- Additive over three signals the payload already carries, in points rather- than a calibrated scale, because it is an **ordering key and not a score**.- Nothing here is blended into ``score`` / ``performance_score``, and nothing- here was fitted against the defect corpus — the frozen weights this file- documents stay frozen. A caller who disagrees can re-rank: every input is in+ """Order-of-magnitude ordering key for one ``performance`` finding.++ Every performance finding carries ``health_impact: 0`` by construction, so+ without a key the list came back in file order and "which of these matters"+ was unanswerable from the payload.++ The weights live with the opportunity ranking rather than here. Two tables+ used to answer "which marker costs more" and they had already drifted apart+ on markers both named, so a finding and the opportunity built from it could+ disagree about the same evidence. Nothing here is blended into ``score`` or+ ``performance_score``; a caller who disagrees can re-rank from``biomarker_type`` and ``details`` on the same row."""if not isinstance(details, dict):details = {}- points = _PERF_MARKER_POINTS.get(biomarker_type or "", _PERF_UNKNOWN_MARKER_POINTS)- points += _PERF_BOUNDARY_POINTS.get(details.get("boundary_kind") or "", 0)- if details.get("cross_function"):- points += _PERF_CROSSFN_POINTS- return points+ return observation_rank(+ biomarker_type, details.get("boundary_kind"), bool(details.get("cross_function"))+ )def _rank_emitted(rows: list[Any]) -> list[Any]:@@ -200,7 +322,23 @@ def _rank_emitted(rows: list[Any]) -> list[Any]:return sorted(rows, key=key)-def _health_finding_id(f: HealthFinding, repository: str) -> str:+def _health_finding_id(f: Any, repository: str) -> str:+ """The finding's public id: the stored one, else the same kernel recomputed.++ Storage row ids are republished on every analysis, so they cannot be quoted+ back. This is the id evidence carries and the ``finding_id`` selector+ resolves, and it is a column, so resolving it is a seek.+ """+ stored = getattr(f, "public_id", None)+ return stored if isinstance(stored, str) and stored else finding_public_id(f)+++def _legacy_health_finding_id(f: Any, repository: str) -> str:+ """The pre-column id form, still accepted so a quoted one keeps resolving.++ Its kernel held generated prose and derived detail keys, so it moved+ whenever a detector reworded itself or a later model changed its mind.+ """try:details = json.loads(f.details_json) if f.details_json else {}except (TypeError, json.JSONDecodeError):@@ -254,27 +392,8 @@ def _serialize_finding(f: HealthFinding, repository: str = "default") -> dict[stdef _refactoring_plan_id(r: Any, repository: str) -> str:- suggestion = r.suggestion if isinstance(r, Recommendation) else r- raw_plan = getattr(suggestion, "plan", None)- if raw_plan is None:- raw_plan = getattr(suggestion, "plan_json", None) or "{}"- try:- raw_plan = json.loads(raw_plan)- except (TypeError, json.JSONDecodeError):- raw_plan = str(raw_plan)- return stable_entity_id(- "plan",- repository,- {- "path": path_identity(suggestion.file_path),- "kind": suggestion.refactoring_type,- "symbol": suggestion.target_symbol or "",- "line_start": suggestion.line_start,- "line_end": suggestion.line_end,- "source_biomarker": suggestion.source_biomarker or "",- "plan": raw_plan,- },- )+ """Unwrap a hydrated recommendation, then defer to the identity owner."""+ return refactoring_plan_id(r.suggestion if isinstance(r, Recommendation) else r, repository)def _serialize_refactoring(@@ -1083,6 +1202,22 @@ def _compute_kpis('only=["performance_opportunities","refactoring_plans"])',("get_health",),),+ ToolRecipe(+ "health_performance_summary",+ 'get_health(include=["performance"], only=["performance_summary"])',+ ("get_health",),+ ),+ ToolRecipe(+ "health_performance_opportunity",+ 'get_health(opportunity_id="perf...")',+ ("get_health",),+ ),+ ToolRecipe(+ "health_performance_evidence",+ 'get_health(opportunity_id="perf...", '+ 'only=["performance_evidence"], cursor=0)',+ ("get_health",),+ ),),)async def get_health(@@ -1095,36 +1230,49 @@ async def get_health(cursor: int = 0,finding_id: str | None = None,plan_id: str | None = None,+ opportunity_id: str | None = None,+ performance_view: str | None = None,+ performance_context: str | None = None,+ performance_boundary: str | None = None,+ performance_confidence: str | None = None,+ performance_sort: str | None = None,) -> dict:"""Code-health scores and findings from stored analysis.No ``targets`` returns a dashboard; targets return ranked files and findings.- This verifies Git/index facts but never recomputes health. For comparisons,- commit health changes then run ``repowise update``; it ignores uncommitted edits.+ Never recomputes health: commit changes, then run ``repowise update``.+ Every block and accepted value: docs/agent/MCP_TOOLS.md.Args:- targets: file paths or ``module:<name>``. Empty → dashboard. Unmatched- targets appear in ``unresolved`` and survive any ``only``.+ targets: file paths or ``module:<name>``. Empty means dashboard;+ unmatched ones appear in ``unresolved``, surviving any ``only``.include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |- ``accuracy`` | ``signals`` | ``churn_complexity`` |- ``performance``/``defect``/``maintainability`` (dimension).- ``performance`` adds causal opportunities; with ``refactoring``,- a compact recommendation lede. Pair with ``only`` to project.- only: top-level keys to keep; identity, counts, unresolved targets,- and recovery metadata survive. ``biomarkers``, ``accuracy``, and- ``refactoring`` alias; ``performance``, ``defect``, and- ``maintainability`` do not.+ ``accuracy`` | ``signals`` | ``churn_complexity``, or one dimension+ name. ``performance`` also adds the opportunity queue.+ only: keys to keep; identity, counts and recovery survive.+ ``biomarkers``, ``accuracy`` and ``refactoring`` alias their block+ key. ``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). Performance- opportunities and refactoring plans have independent caps of 6;- performance evidence is capped at 3 rows per opportunity.- refactoring_view: ``canonical`` (default) or diversified- ``file_spread``.- cursor: zero-based offset for top-level ranked collections.+ 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.+ performance_view / _context / _boundary / _confidence / _sort: queue+ projection and filters; the facets list their values.+"""started = perf_counter()+ conflict = _selector_conflict(+ finding_id=finding_id, plan_id=plan_id, opportunity_id=opportunity_id+ )+ if conflict is not None:+ return conflict# ``0`` means none, matching the ``module_limit`` convention on the REST# coverage route. It used to clamp up to 1, so the documented way to ask for# "the totals, none of the rows" silently returned a row.@@ -1170,8 +1318,10 @@ async def get_health(# block that carries findings survives the projection.wants_findings = wants("findings") or wants("top_findings")wants_test_findings = wants("test_findings")- wants_performance_opportunities = wants("performance_opportunities") or wants(- "recommendation_lede"+ wants_performance_opportunities = (+ wants("performance_opportunities")+ or wants("recommendation_lede")+ or wants("performance_summary"))# Everything downstream of the test/production split, in one place.#@@ -1219,6 +1369,7 @@ async def get_health("coverage.files","refactoring_plans","performance_opportunities",+ "performance_evidence",}def bounded(rows: list[Any], label: str, *, cap: int | None = None) -> list[Any]:@@ -1256,25 +1407,8 @@ async def get_health(reference_repository = ctx.alias or repository.nameif finding_id:- rows = list(- (- await session.execute(- select(HealthFinding).where(- HealthFinding.repository_id == repository.id,- HealthFinding.status == "open",- )- )- )- .scalars()- .all()- )- match = next(- (- row- for row in rows- if finding_id in {row.id, _health_finding_id(row, reference_repository)}- ),- None,+ match = await _resolve_finding(+ session, repository.id, finding_id, reference_repository)result = {"mode": "finding",@@ -1305,6 +1439,17 @@ async def get_health(_attach_health_analysis_meta(result["_meta"], metric_rows)return result+ if opportunity_id:+ return await _performance_detail_response(+ session,+ repository,+ reference_repository,+ opportunity_id,+ evidence_only=only_set == {"performance_evidence"},+ limit=limit,+ cursor=cursor,+ )+if plan_id:plan_rows = await get_refactoring_suggestions(session, repository.id)recommendations = await hydrate_recommendations(@@ -1648,6 +1793,27 @@ async def get_health(view=refactoring_view, # type: ignore[arg-type])+ # The materialized causal read model. Filtering, ordering, paging, plan+ # linkage, and facets are the shared service's; this tool caps the+ # collection, pages it, and serializes what comes back.+ performance_service = PerformanceHealthService(+ session, repository.id, reference_repository+ )+ performance = await _performance_blocks(+ performance_service,+ wants=wants,+ included="performance" in include_set and wants_performance_opportunities,+ file_paths=tuple(effective_targets) if scoped else None,+ scoped=scoped,+ limit=limit,+ cursor=cursor,+ view=performance_view,+ context=performance_context,+ boundary=performance_boundary,+ confidence=performance_confidence,+ sort=performance_sort,+ )+coverage_rows: list[Any] = []coverage_summary: dict[str, Any] = {}if "coverage" in include_set and not nothing_resolved:@@ -1913,6 +2079,15 @@ async def get_health(plan_biomarkers_by_path,plan_count_by_path,),+ # A second, additive lead for the performance pillar. The block+ # 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.+ **(+ {"performance_directive": performance.directive}+ if performance.directive is not None+ else {}+ ),"mode": "dashboard","kpis": kpis,"distribution": health_distribution(all_metrics),@@ -2114,67 +2289,60 @@ async def get_health(if len(recent) > limit:result["trend"]["recent_reduced_reason"] = "limit"- opportunities = []- if "performance" in include_set and wants_performance_opportunities:- performance_rows = [row for row in lead_rows if _in_dimensions(row, {"performance"})]- opportunities = build_performance_opportunities(- performance_rows,- evidence_limit=max(len(performance_rows), 3),- )- opportunity_payload = []- selected_opportunities = bounded(- opportunities,- "performance_opportunities",- cap=min(limit, 6),- )- for opportunity in selected_opportunities:- payload = opportunity.as_dict()- evidence = list(payload.get("evidence", []))- payload["evidence"] = bounded(- evidence,- f"performance_opportunities.{opportunity.opportunity_id}.evidence",- cap=3,+ if performance.page is not None and wants("performance_opportunities"):+ result["performance_opportunities"] = performance.page.items+ result["performance_opportunities_total"] = performance.page.total+ result["performance_opportunities_emitted"] = len(performance.page.items)+ if performance.page.next_offset is not None:+ page_recoveries["performance_opportunities"] = (+ performance.page.next_offset,+ _PERFORMANCE_COLLECTION_CAP,+ performance.page.total - performance.page.next_offset,)- payload["evidence_total"] = payload.get("observations_total", len(evidence))- payload["evidence_emitted"] = len(payload["evidence"])- if payload["evidence_emitted"] < payload["evidence_total"]:- payload["evidence_reduced_reason"] = "evidence_cap"- opportunity_payload.append(payload)- result["performance_opportunities"] = opportunity_payload- result["performance_opportunities_total"] = len(opportunities)+ if performance.ignored:+ result["ignored_arguments"] = {+ **result.get("ignored_arguments", {}),+ **performance.ignored,+ }++ if performance.summary is not None:+ result["performance_summary"] = {+ **performance.summary,+ "facets": performance.page.facets if performance.page else {},+ "next_call": (+ "get_health(include=['performance'], "+ "only=['performance_opportunities'], limit=6)"+ ),+ }if {"performance", "refactoring"} <= include_set and wants("recommendation_lede"):- performance_lead = opportunities[0] if opportunities else None+ performance_lead = (+ performance.page.items[0] if performance.page and performance.page.items else None+ )recommendation_lead = (refactoring_recommendations[0] if refactoring_recommendations else None)- matching = next(- (- recommendation- for recommendation in refactoring_recommendations- if performance_lead is not None- and recommendation.suggestion.refactoring_type == "performance_fix"- and (recommendation.suggestion.evidence or {}).get("opportunity_id")- == performance_lead.opportunity_id- ),- None,- )lead_payload = (_serialize_refactoring(recommendation_lead, reference_repository)if recommendation_leadelse None)result["recommendation_lede"] = {- "performance_opportunities_total": len(opportunities),+ "performance_opportunities_total": (+ performance.page.total if performance.page else 0+ ),"refactoring_plans_total": len(refactoring_recommendations),"performance_lead": ({- "opportunity_id": performance_lead.opportunity_id,- "intervention_symbol": performance_lead.intervention_symbol,- "boundary_kind": performance_lead.boundary_kind,- "execution_context": performance_lead.execution_context,- "affected_call_sites_total": performance_lead.affected_call_sites_total,- "rank_score": performance_lead.rank_score,+ key: performance_lead[key]+ for key in (+ "opportunity_id",+ "intervention_symbol",+ "boundary_kind",+ "execution_context",+ "affected_call_sites_total",+ "rank_score",+ )}if performance_leadelse None@@ -2197,8 +2365,14 @@ async def get_health(if lead_payloadelse None),+ # The exact plan for the exact lead, from the one place that decides+ # plan linkage. This used to match on a key the plan writer never+ # wrote, so it was unconditionally null."performance_plan_id": (- _refactoring_plan_id(matching, reference_repository) if matching else None+ performance_lead["plan_reference"] if performance_lead else None+ ),+ "performance_plan_reason": (+ performance_lead["plan_reason"] if performance_lead else None),"next_call": (f"get_health(targets={raw_targets!r}, repo={repo!r}, "@@ -2279,7 +2453,9 @@ async def get_health("test_findings": test_findings_total,"churn_complexity": len(churn_points),"refactoring_plans": len(refactoring_recommendations),- "performance_opportunities": len(opportunities),+ "performance_opportunities": (+ performance.page.total if performance.page is not None else 0+ ),}for key, total in collection_totals.items():if total is None:@@ -2331,6 +2507,9 @@ async def get_health("unknown_include_keys","unknown_include_keys_total","unknown_include_keys_emitted",+ # A rejected filter value is a caller-error report, so it+ # survives a projection for the same reason ``unresolved`` does.+ "ignored_arguments","recovery",}| {diff --git a/packages/server/src/repowise/server/routers/code_health/performance_routes.py b/packages/server/src/repowise/server/routers/code_health/performance_routes.pyindex c28f89c99..3b9b498f6 100644--- a/packages/server/src/repowise/server/routers/code_health/performance_routes.py+++ b/packages/server/src/repowise/server/routers/code_health/performance_routes.py@@ -1,133 +1,127 @@-"""Bounded causal performance opportunities and raw-evidence drill-down."""+"""Bounded causal performance opportunities and raw-evidence drill-down.++A thin adapter: query parameters map onto the shared performance service, and+the response is what that service returned. Filtering, ordering, paging, plan+linkage, and facets live there, so this surface and the agent surface cannot+drift apart about what the same opportunity is.+"""from __future__ import annotations-import json-from typing import Any, Literal+from typing import Anyfrom fastapi import Depends, Queryfrom sqlalchemy.ext.asyncio import AsyncSession-from repowise.core.analysis.health.perf.opportunities import (- build_performance_opportunities,- opportunity_id_for_finding,-)-from repowise.core.persistence import crudfrom repowise.server.deps import get_db_session+from repowise.server.services.performance_health import (+ PerformanceHealthService,+ parse_query,+)from ._router import router-from .loaders import _attach_symbol_ids-from .serializers import _finding_to_dict---def _json_dict(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 {}---def _plan_ids(rows: list[Any]) -> dict[str, str]:- matches: dict[str, str] = {}- for row in rows:- opportunity_id = _json_dict(row.plan_json).get("opportunity_id")- if isinstance(opportunity_id, str) and opportunity_id:- plan_id = str(row.id)- matches[opportunity_id] = min(matches.get(opportunity_id, plan_id), plan_id)- return matches---def _finding_opportunity_id(row: Any) -> str:- persisted = _json_dict(getattr(row, "details_json", None)).get("opportunity_id")- return (- persisted if isinstance(persisted, str) and persisted else opportunity_id_for_finding(row)- )-def _plan_link(opportunity: Any, plan_id: str | None) -> dict[str, str | None]:- if plan_id:- return {- "plan_id": plan_id,- "plan_status": "available",- "plan_reason": "A stored performance plan addresses this exact opportunity.",- }- if opportunity.fix is None:- return {- "plan_id": None,- "plan_status": "no_safe_plan",- "plan_reason": (- "The analysis found the shared cause but could not prove one coherent "- "intervention without guessing."- ),- }+def _service(session: AsyncSession, repo_id: str) -> PerformanceHealthService:+ """Bind the shared service to this repository.++ The repository token only scopes the agent-address-space plan reference,+ which this surface strips: a plan here is addressed by the row id its own+ detail route resolves.+ """+ return PerformanceHealthService(session, repo_id, repo_id)+++_EVIDENCE_PER_ITEM = 8+"""Evidence rows carried inline on a queue row, so the tab can show the paths."""+++def _item(item: dict[str, Any]) -> dict[str, Any]:+ """Drop the reference minted for the other address space."""+ return {key: value for key, value in item.items() if key != "plan_reference"}+++def _summary(summary: dict[str, Any]) -> dict[str, Any]:+ """Add the flat counter names the current tab reads.++ A projection of the canonical rollup, not a second count: every value is+ read off the fields above it. The flat names retire with the tab.+ """+ context = summary.get("context", {})+ total = summary.get("total", 0)+ with_plan = summary.get("with_plan_total", 0)return {- "plan_id": None,- "plan_status": "not_persisted",- "plan_reason": (- "A supported strategy exists, but this index does not contain its matching "- "stored plan. Reindex to refresh recommendations."- ),+ **summary,+ "production_total": context.get("production", 0),+ "tooling_total": context.get("tooling", 0),+ "test_total": context.get("test", 0),+ "unknown_total": context.get("unknown", 0),+ "with_plan_total": with_plan,+ "without_plan_total": total - with_plan,}@router.get("/api/repos/{repo_id}/health/performance-opportunities")async def list_performance_opportunities(repo_id: str,- context: Literal["production_tooling", "test", "all"] = Query("production_tooling"),+ context: str = Query("all"),+ boundary: str | None = Query(None),+ confidence: str | None = Query(None),+ actionability: str | None = Query(None),+ view: str = Query("detail"),+ sort: str = Query("rank"),limit: int = Query(20, ge=1, le=100),offset: int = Query(0, ge=0),session: AsyncSession = Depends(get_db_session),) -> dict[str, Any]:- """One bounded page over the canonical causal read model.+ """One bounded page over the materialized causal read model.- Findings and performance-plan rows are each read once. Exact- ``opportunity_id`` equality is the only accepted plan match.+ The rows fetched are the page, not the repository: grouping already+ happened when the findings were persisted."""- findings = await crud.get_health_findings(session, repo_id, dimension="performance")- plan_rows = await crud.get_refactoring_suggestions(- session, repo_id, refactoring_type="performance_fix"+ query, ignored = parse_query(+ context=context,+ boundary=boundary,+ confidence=confidence,+ actionability=actionability,+ view=view,+ sort=sort,+ limit=limit,+ offset=offset,+ )+ page = await _service(session, repo_id).page(+ query, evidence_per_item=_EVIDENCE_PER_ITEM, with_facets=True, with_summary=True)- opportunities = build_performance_opportunities(findings, evidence_limit=8)- matches = _plan_ids(plan_rows)- contexts = {- "production_tooling": {"production", "tooling"},- "test": {"test"},- # An unclassifiable file is reported as unknown rather than assumed to- # ship, so it belongs in the unfiltered view and is counted below.- "all": {"production", "tooling", "test", "unknown"},- }[context]- filtered = [item for item in opportunities if item.execution_context in contexts]- total = len(filtered)- page = filtered[offset : offset + limit]- next_offset = offset + len(page) if offset + len(page) < total else Nonereturn {- "items": [- {- **item.as_dict(),- **_plan_link(item, matches.get(item.opportunity_id)),- }- for item in page- ],- "total": total,- "has_more": next_offset is not None,- "next_offset": next_offset,- "summary": {- "total": len(opportunities),- "production_total": sum(- item.execution_context == "production" for item in opportunities- ),- "tooling_total": sum(item.execution_context == "tooling" for item in opportunities),- "test_total": sum(item.execution_context == "test" for item in opportunities),- "unknown_total": sum(item.execution_context == "unknown" for item in opportunities),- "with_plan_total": sum(item.opportunity_id in matches for item in opportunities),- "without_plan_total": sum(item.opportunity_id not in matches for item in opportunities),- },+ "items": [_item(item) for item in page.items],+ "total": page.total,+ "has_more": page.next_offset is not None,+ "next_offset": page.next_offset,+ "facets": page.facets,+ "summary": _summary(page.summary),+ **({"ignored_arguments": ignored} if ignored else {}),}[email protected]("/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}")+async def get_performance_opportunity_detail(+ repo_id: str,+ opportunity_id: str,+ 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 by its stable id, with bounded evidence.++ An id from an older performance model resolves to an explicit stale-model+ state and the refresh that fixes it, rather than reading as "no plan".+ """+ detail = await _service(session, repo_id).detail(+ opportunity_id, evidence_limit=evidence_limit, evidence_offset=evidence_offset+ )+ return _item(detail)++@router.get("/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}/findings")async def list_performance_opportunity_findings(repo_id: str,@@ -136,24 +130,21 @@ async def list_performance_opportunity_findings(offset: int = Query(0, ge=0),session: AsyncSession = Depends(get_db_session),) -> dict[str, Any]:- """Click-gated raw canonical observations for one stable opportunity id."""- findings = await crud.get_health_findings(session, repo_id, dimension="performance")- matched = [- finding for finding in findings if _finding_opportunity_id(finding) == opportunity_id- ]- matched.sort(key=lambda row: (row.file_path, row.line_start or 0, row.id))- total = len(matched)- page = matched[offset : offset + limit]- items = await _attach_symbol_ids(- session, repo_id, [_finding_to_dict(finding) for finding in page]+ """Click-gated raw observations for one stable opportunity id."""+ items, total = await _service(session, repo_id).evidence(+ opportunity_id, limit=limit, offset=offset)- next_offset = offset + len(page) if offset + len(page) < total else None+ emitted = offset + len(items)return {"items": items,"total": total,- "has_more": next_offset is not None,- "next_offset": next_offset,+ "has_more": emitted < total,+ "next_offset": emitted if emitted < total else None,}-__all__ = ["list_performance_opportunities", "list_performance_opportunity_findings"]+__all__ = [+ "get_performance_opportunity_detail",+ "list_performance_opportunities",+ "list_performance_opportunity_findings",+]diff --git a/packages/server/src/repowise/server/services/performance_health.py b/packages/server/src/repowise/server/services/performance_health.pynew file mode 100644index 000000000..c2d25e490--- /dev/null+++ b/packages/server/src/repowise/server/services/performance_health.py@@ -0,0 +1,630 @@+"""One read model for performance opportunities, serving REST and MCP.++Both surfaces used to load every open finding, regroup the repository, filter+in Python, and link plans by reading two different JSON fields. They disagreed+about the second of those, so one of them never linked a plan at all. This+module owns the query, the order, the page, the facets, the plan link, the+detail, and the recovery once; the two adapters map their own vocabulary onto+it and serialize what comes back.++Nothing here decides what an opportunity *means*. Grouping, actionability, and+rank live in the analysis package, and the values this module reads were+already decided when the opportunities were materialized.+"""++from __future__ import annotations++import json+from dataclasses import dataclass, field+from typing import Any, Literal++from sqlalchemy.ext.asyncio import AsyncSession++from repowise.core.analysis.health.finding_identity import finding_public_id+from repowise.core.analysis.health.perf.opportunities import (+ PERFORMANCE_MODEL_VERSION,+ model_state,+)+from repowise.core.analysis.health.rows import detail_map+from repowise.core.persistence.crud import (+ get_performance_opportunity,+ get_performance_plan_rows,+ get_performance_summary,+ list_evidence_for_opportunities,+ list_opportunity_evidence,+ list_performance_opportunities,+ performance_facet_counts,+)++from ..mcp_server._references import refactoring_plan_id++PerformanceContext = Literal["production", "tooling", "test", "unknown", "all"]++CANONICAL_CONTEXTS = ("production", "tooling", "test", "unknown")+"""The whole vocabulary. ``all`` is every one of them, never a subset."""++_DEPRECATED_CONTEXTS = {"production_tooling": frozenset({"production", "tooling"})}+"""Accepted for one compatibility window and never emitted as canonical.++An older client asks for Production+Tooling under one name. Answering it keeps+that client working; echoing the name back would make a retired spelling look+like the current product concept.+"""++CANONICAL_SORTS = ("rank", "leverage", "observations")+CANONICAL_VIEWS = ("detail", "summary")+_CONFIDENCES = ("high", "medium", "low")+_ACTIONABILITIES = ("plan_ready", "advisory", "investigate")+_BOUNDARIES = ("db", "network", "filesystem", "subprocess", "lock", "none")++_PLAN_REASONS = {+ "available": "A stored performance plan addresses this exact opportunity.",+ "no_safe_plan": (+ "The analysis found the shared cause but could not prove one coherent "+ "intervention without guessing."+ ),+ "not_persisted": (+ "A supported strategy exists, but this index does not contain its matching "+ "stored plan. Reindex to refresh recommendations."+ ),+}++_SUMMARY_UNAVAILABLE = {+ "status": "unavailable",+ "reason": "no_materialized_analysis",+ "detail": (+ "This index has no materialized performance analysis. Run repowise update "+ "to build it."+ ),+}+++@dataclass(frozen=True, slots=True)+class PerformanceQuery:+ """One request for a page of the queue, in canonical terms.++ Built by :func:`parse_query` so both adapters normalize identically and an+ unrecognized value is reported rather than silently read as "no results".+ """++ context: PerformanceContext = "all"+ boundary: str | None = None+ confidence: str | None = None+ actionability: str | None = None+ view: str = "detail"+ sort: str = "rank"+ file_paths: tuple[str, ...] | None = None+ limit: int = 20+ offset: int = 0++ @property+ def contexts(self) -> frozenset[str] | None:+ if self.context == "all":+ return None+ alias = _DEPRECATED_CONTEXTS.get(self.context)+ return alias if alias is not None else frozenset({self.context})+++@dataclass(frozen=True, slots=True)+class PlanLink:+ """Where the plan for one opportunity lives, in both address spaces.++ ``row_id`` resolves through the repository-scoped REST route and+ ``public_id`` through the ``plan_id`` selector on the agent surface. The+ rule that decides *whether* there is a plan is above them and is written+ once.+ """++ state: str+ row_id: str | None = None+ public_id: str | None = None++ @property+ def reason(self) -> str:+ return _PLAN_REASONS[self.state]+++@dataclass(frozen=True, slots=True)+class PerformancePage:+ items: list[dict[str, Any]]+ total: int+ offset: int+ next_offset: int | None+ facets: dict[str, list[dict[str, Any]]]+ summary: dict[str, Any]+ ignored_arguments: dict[str, str] = field(default_factory=dict)+++def parse_query(+ *,+ context: str | None = None,+ boundary: str | None = None,+ confidence: str | None = None,+ actionability: str | None = None,+ view: str | None = None,+ sort: str | None = None,+ file_paths: tuple[str, ...] | None = None,+ limit: int = 20,+ offset: int = 0,+) -> tuple[PerformanceQuery, dict[str, str]]:+ """Normalize caller input, reporting anything unrecognized by name.++ An unknown filter value must not read as an empty repository, so it is+ dropped from the query and named in the returned map instead.+ """+ ignored: dict[str, str] = {}++ def pick(name: str, value: str | None, allowed: tuple[str, ...]) -> str | None:+ if value is None or value == "":+ return None+ if value in allowed:+ return value+ ignored[name] = value+ return None++ resolved_context: PerformanceContext = "all"+ if context:+ if context in CANONICAL_CONTEXTS or context == "all" or context in _DEPRECATED_CONTEXTS:+ resolved_context = context # type: ignore[assignment]+ else:+ ignored["performance_context"] = context+ return (+ PerformanceQuery(+ context=resolved_context,+ boundary=pick("performance_boundary", boundary, _BOUNDARIES),+ confidence=pick("performance_confidence", confidence, _CONFIDENCES),+ actionability=pick("performance_actionability", actionability, _ACTIONABILITIES),+ view=pick("performance_view", view, CANONICAL_VIEWS) or "detail",+ sort=pick("performance_sort", sort, CANONICAL_SORTS) or "rank",+ file_paths=file_paths,+ limit=max(0, limit),+ offset=max(0, offset),+ ),+ ignored,+ )+++class PerformanceHealthService:+ """Query, page, detail, facets, plan linkage, and recovery, in one place."""++ def __init__(self, session: AsyncSession, repository_id: str, repository: str) -> None:+ self._session = session+ self._repository_id = repository_id+ self._repository = repository++ # -- collection --------------------------------------------------------++ async def page(+ self,+ query: PerformanceQuery,+ *,+ evidence_per_item: int = 0,+ with_facets: bool = False,+ with_summary: bool = False,+ ) -> PerformancePage:+ """One page and its plan links, plus whatever else the caller renders.++ Three statements for the page itself: the rows, their count, and their+ plans, and each fetches the page rather than the repository. Evidence,+ facets, and the headline each cost one more and are opt-in, because a+ caller that quotes one row should not pay for a rollup it discards.++ The facet aggregate is the one that reads more than the page: it groups+ every open opportunity, which is the only way to report the counts a+ filter control needs. It stays a single indexed aggregate over a table+ that already holds one row per cause rather than one per observation.+ """+ rows, total = await list_performance_opportunities(+ self._session,+ self._repository_id,+ contexts=query.contexts,+ boundary=query.boundary,+ confidence=query.confidence,+ actionability=query.actionability,+ file_paths=query.file_paths,+ sort=query.sort,+ limit=query.limit,+ offset=query.offset,+ )+ links = await self._plan_links(rows)+ evidence = await self._evidence_for(rows, evidence_per_item)+ items = [+ {+ **self._serialize(+ row, links[row.opportunity_id], summary=query.view == "summary"+ ),+ **(+ evidence_block(+ evidence.get(row.opportunity_id, []), row.observations_total, 0+ )+ if evidence_per_item+ else {}+ ),+ }+ for row in rows+ ]+ emitted = query.offset + len(items)+ return PerformancePage(+ items=items,+ total=total,+ offset=query.offset,+ next_offset=emitted if emitted < total else None,+ facets=await self._facets(query) if with_facets else {},+ summary=await self.summary() if with_summary else {},+ )++ async def _evidence_for(+ self, rows: list[Any], per_item: int+ ) -> dict[str, list[dict[str, Any]]]:+ """A few observations for every row on the page, in one statement.++ Ranked inside the database, so a page holding one very large cause+ still reads a bounded number of rows.+ """+ if not per_item or not rows:+ return {}+ grouped = await list_evidence_for_opportunities(+ self._session,+ self._repository_id,+ [row.opportunity_id for row in rows],+ per_opportunity=per_item,+ )+ return {key: [evidence_payload(row) for row in group] for key, group in grouped.items()}++ async def _plan_links(self, rows: list[Any]) -> dict[str, PlanLink]:+ """One indexed batch for the whole page, never one query per row."""+ plans = await get_performance_plan_rows(+ self._session, self._repository_id, [row.opportunity_id for row in rows]+ )+ links: dict[str, PlanLink] = {}+ for row in rows:+ plan = plans.get(row.opportunity_id)+ if plan is None:+ # The materialized state already distinguishes "no safe plan"+ # from "a strategy exists but this index has no plan row".+ state = row.plan_state if row.plan_state != "available" else "not_persisted"+ links[row.opportunity_id] = PlanLink(state)+ continue+ links[row.opportunity_id] = PlanLink(+ "available",+ row_id=str(plan.id),+ public_id=refactoring_plan_id(plan, self._repository),+ )+ return links++ async def _facets(self, query: PerformanceQuery) -> dict[str, list[dict[str, Any]]]:+ """Counts per filter value, each cross-filtered by the *other* filters.++ Counting a facet under its own filter would leave every alternative at+ zero, so choosing one value would erase the others from the control.+ """+ grouped = await performance_facet_counts(+ self._session, self._repository_id, file_paths=query.file_paths+ )+ dimensions = {+ "context": 0,+ "boundary": 1,+ "confidence": 2,+ "actionability": 3,+ "plan_state": 4,+ }+ selected = {+ "context": query.contexts,+ "boundary": None if query.boundary is None else frozenset({query.boundary}),+ "confidence": None if query.confidence is None else frozenset({query.confidence}),+ "actionability": (+ None if query.actionability is None else frozenset({query.actionability})+ ),+ "plan_state": None,+ }+ facets: dict[str, list[dict[str, Any]]] = {}+ for name, index in dimensions.items():+ counts: dict[str, int] = {}+ for row in grouped:+ if any(+ values is not None+ and other != name+ and (row[dimensions[other]] or "none") not in values+ for other, values in selected.items()+ ):+ continue+ counts[row[index] or "none"] = counts.get(row[index] or "none", 0) + row[5]+ facets[name] = [+ {"value": value, "total": total}+ for value, total in sorted(counts.items(), key=lambda item: (-item[1], item[0]))+ ]+ return facets++ # -- headline ----------------------------------------------------------++ async def summary(self) -> dict[str, Any]:+ """The compact rollup, from the one-row current summary.++ Reads by primary key, so a bare dashboard pays one statement for its+ performance headline however large the repository is.+ """+ return _summary_of(await get_performance_summary(self._session, self._repository_id))++ async def directive(self) -> dict[str, Any]:+ """One bounded next action for a bare dashboard call.++ Selection is the best concrete next action rather than the highest raw+ rank: the materialized order already sorts actionable work above+ high-volume evidence, so the lead is the first row.++ The lead and the counts come off the same row read, because the lead is+ the reason the row exists.+ """+ row = await get_performance_summary(self._session, self._repository_id)+ summary = _summary_of(row)+ if summary["status"] == "unavailable":+ return {+ "status": "unavailable",+ "reason": summary["reason"],+ "detail": summary["detail"],+ }+ lead = _loads(row.summary_json).get("lead")+ counts = summary["actionability"]+ base = {+ "performance_model_version": PERFORMANCE_MODEL_VERSION,+ "opportunities_total": summary["total"],+ "plan_ready_total": counts.get("plan_ready", 0),+ "advisory_total": counts.get("advisory", 0),+ "investigate_total": counts.get("investigate", 0),+ }+ if summary["status"] == "stale_model":+ return {+ **base,+ "status": "unavailable",+ "reason": "stale_model",+ "detail": (+ "The stored performance analysis predates the current model. "+ "Run repowise update to rescore."+ ),+ }+ if lead is None:+ return {+ **base,+ "status": "clear",+ # Never "fast": the analysis found no supported pattern, which+ # is not a measurement of how this code runs.+ "detail": "No supported open pattern surfaced.",+ }+ return {+ **base,+ "status": lead["actionability_state"],+ "opportunity_id": lead["opportunity_id"],+ "title": _title(lead),+ "file_path": lead["file_path"],+ "execution_context": lead["execution_context"],+ "boundary_kind": lead["boundary_kind"],+ "affected_call_sites_total": lead["affected_call_sites_total"],+ "observations_total": lead["observations_total"],+ "why_ranked": lead["why_ranked"][:3],+ "plan_state": lead["plan_state"],+ "plan_reason": _PLAN_REASONS[lead["plan_state"]],+ "prerequisites": lead["prerequisites"],+ "next_action": {+ "tool": "get_health",+ "arguments": {"opportunity_id": lead["opportunity_id"]},+ },+ }++ # -- detail ------------------------------------------------------------++ async def detail(+ self, opportunity_id: str, *, evidence_limit: int = 3, evidence_offset: int = 0+ ) -> dict[str, Any]:+ """One opportunity by id, with bounded evidence and exact plan state."""+ state = model_state(opportunity_id)+ row = await get_performance_opportunity(+ self._session, self._repository_id, opportunity_id+ )+ if row is None:+ return {+ "resolved": False,+ "opportunity_id": opportunity_id,+ "model_state": state,+ "detail": _unresolved_detail(state),+ }+ links = await self._plan_links([row])+ payload = self._serialize(row, links[opportunity_id])+ evidence, total = await self.evidence(+ opportunity_id,+ limit=evidence_limit,+ offset=evidence_offset,+ total=row.observations_total,+ )+ payload.update(+ {+ "resolved": True,+ "lifecycle_status": row.status,+ "analyzed_commit": row.analyzed_commit,+ "model_state": state,+ **evidence_block(evidence, total, evidence_offset),+ }+ )+ return payload++ async def evidence(+ self,+ opportunity_id: str,+ *,+ limit: int = 3,+ offset: int = 0,+ total: int | None = None,+ ) -> tuple[list[dict[str, Any]], int]:+ """One page of the observations behind a cause, and their exact total."""+ rows, total = await list_opportunity_evidence(+ self._session,+ self._repository_id,+ opportunity_id,+ limit=max(0, limit),+ offset=max(0, offset),+ total=total,+ )+ return [evidence_payload(row) for row in rows], total++ # -- serialization -----------------------------------------------------++ def _serialize(self, row: Any, link: PlanLink, *, summary: bool = False) -> dict[str, Any]:+ """Rebuild the canonical opportunity payload from row plus details.++ Columns carry what a query filters or orders on and ``details_json``+ carries the rest, so no fact is stored twice and nothing here computes+ a value the writer already decided.+ """+ details = _loads(row.details_json)+ payload = {+ "opportunity_id": row.opportunity_id,+ "performance_model_version": row.performance_model_version,+ "biomarker_type": row.biomarker_type,+ "biomarker_types": details.get("biomarker_types", []),+ "boundary_kind": row.boundary_kind,+ "execution_context": row.execution_context,+ "terminal_sink": row.terminal_sink,+ "intervention_symbol": row.intervention_symbol,+ "file_path": row.file_path,+ "affected_call_sites_total": row.affected_call_sites_total,+ "affected_files_total": row.affected_files_total,+ "observations_total": row.observations_total,+ "confidence": row.evidence_confidence,+ "actionability_state": row.actionability_state,+ "rank_score": row.rank_score,+ "rank_position": row.rank_position,+ "why_ranked": details.get("why_ranked", []),+ "plan_id": link.row_id,+ "plan_reference": link.public_id,+ "plan_status": link.state,+ "plan_reason": link.reason,+ }+ if summary:+ return payload+ fix_strategy = row.fix_strategy+ return {+ **payload,+ "shared_path_suffix": details.get("shared_path_suffix", []),+ "resource_fingerprints": details.get("resource_fingerprints", []),+ "reliable_entry_reachability": details.get("reliable_entry_reachability"),+ "provenance": details.get("provenance"),+ "facets": details.get("facets", {}),+ "actionability_reason": details.get("actionability_reason"),+ "prerequisites": details.get("prerequisites", []),+ "rank_factors": details.get("rank_factors", {}),+ "fix": None+ if fix_strategy is None+ else {+ "strategy": fix_strategy,+ "safety": row.fix_safety,+ "rationale": details.get("fix_rationale") or "",+ },+ }+++def _summary_of(row: Any) -> dict[str, Any]:+ """The canonical rollup for one stored summary row, or its absence.++ A missing row means this index has never materialized the analysis, which+ is a different answer from an empty one and must not read as a clean+ repository.+ """+ if row is None:+ return dict(_SUMMARY_UNAVAILABLE)+ payload = _loads(row.summary_json)+ stale = row.performance_model_version != PERFORMANCE_MODEL_VERSION+ return {+ "status": "stale_model" if stale else "current",+ "performance_model_version": PERFORMANCE_MODEL_VERSION,+ "materialized_model_version": row.performance_model_version,+ "analyzed_commit": row.analyzed_commit,+ "total": row.opportunities_total,+ "actionability": payload.get("actionability", {}),+ "context": payload.get("context", {}),+ "boundary": payload.get("boundary", {}),+ "with_plan_total": payload.get("with_plan_total", 0),+ **(+ {"refresh_required": True, "detail": "Run repowise update to rescore."}+ if stale+ else {}+ ),+ }+++def evidence_block(+ evidence: list[dict[str, Any]], total: int, offset: int+) -> dict[str, Any]:+ """Evidence plus the exact recovery for what it left out."""+ emitted = offset + len(evidence)+ block: dict[str, Any] = {+ "evidence": evidence,+ "evidence_total": total,+ "evidence_emitted": len(evidence),+ "evidence_truncated": emitted < total,+ }+ if emitted < total:+ block["evidence_reduced_reason"] = "evidence_page"+ block["evidence_next_cursor"] = emitted+ return block+++def _title(lead: dict[str, Any]) -> str:+ """A human cause, not a marker name."""+ symbol = lead.get("intervention_symbol") or lead.get("terminal_sink") or lead["file_path"]+ return f"{lead['biomarker_type']} reaching {symbol}"+++def _unresolved_detail(state: dict[str, Any]) -> str:+ if state["state"] == "stale_model":+ return (+ "That id was minted by performance model "+ f"{state['requested_model_version']}; this index is on model "+ f"{state['performance_model_version']}. Membership differs between "+ "models, so the id is not translated. Run repowise update to rescore."+ )+ if state["state"] == "unrecognized":+ return "That is not a performance opportunity id."+ return "No open or resolved opportunity in this repository carries that id."+++def evidence_payload(row: Any) -> dict[str, Any]:+ """One public evidence entry, addressed by the finding's public id.++ The stored id when there is one, the same kernel recomputed when a store+ predates the column, and never the storage row id.+ """+ details = detail_map(row)+ return {+ "finding_id": row.public_id or finding_public_id(row),+ "file_path": row.file_path,+ "biomarker_type": row.biomarker_type or "",+ "function_name": row.function_name,+ "line_start": row.line_start,+ "line_end": row.line_end,+ "reason": row.reason,+ "path": list(details.get("path", ())),+ "provenance": details.get("resolution_basis", "direct"),+ }+++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_CONTEXTS",+ "CANONICAL_SORTS",+ "CANONICAL_VIEWS",+ "PerformanceHealthService",+ "PerformancePage",+ "PerformanceQuery",+ "PlanLink",+ "evidence_block",+ "evidence_payload",+ "parse_query",+]diff --git a/packages/types/src/health.ts b/packages/types/src/health.tsindex 6ce7385af..39d5624be 100644--- a/packages/types/src/health.ts+++ b/packages/types/src/health.ts@@ -253,8 +253,33 @@ export interface PerformanceOpportunityEvidence {provenance: string;}+export type PerformanceActionabilityState = "plan_ready" | "advisory" | "investigate";+export type PerformancePlanStatus = "available" | "no_safe_plan" | "not_persisted";++/** One rank term, the input it read, and the points it contributed. */+export interface PerformanceWhyRanked {+ factor: string;+ value: string | number | boolean | null;+ points: number;+}++/**+ * The facets that are not published anywhere else on the row.+ * `confidence` stays evidence confidence and `fix.safety` stays fix safety,+ * so no value appears twice.+ */+export interface PerformanceOpportunityFacets {+ actionability_confidence: PerformanceOpportunityConfidence;+ exposure: string;+ amplification: string;+ leverage: string;+ change_risk: string;+}+export interface PerformanceOpportunity {opportunity_id: string;+ /** Ids are stable within a model version and never translated across one. */+ performance_model_version: number;biomarker_type: string;biomarker_types: string[];boundary_kind: C4IoKind | null;@@ -262,34 +287,99 @@ export interface PerformanceOpportunity {terminal_sink: string | null;shared_path_suffix: string[];intervention_symbol: string | null;+ /** The file holding the symbol worth editing. */+ file_path: string;+ resource_fingerprints: string[];affected_call_sites_total: number;affected_files_total: number;observations_total: number;evidence: PerformanceOpportunityEvidence[];evidence_truncated: boolean;+ evidence_total: number;+ evidence_emitted: number;+ /** Offset for the next evidence page, absent once the last one is emitted. */+ evidence_next_cursor?: number;reliable_entry_reachability: boolean | null;provenance: string;+ /** Evidence confidence: how reliably the call path resolved. */confidence: PerformanceOpportunityConfidence;+ facets: PerformanceOpportunityFacets;+ actionability_state: PerformanceActionabilityState;+ actionability_reason: string;+ prerequisites: string[];rank_score: number;+ rank_position: number;rank_factors: Record<string, number>;+ why_ranked: PerformanceWhyRanked[];fix: PerformanceOpportunityFix | null;/** Exact stored match. Never inferred from file, marker, or rank. */plan_id: string | null;- plan_status: "available" | "no_safe_plan" | "not_persisted";+ plan_status: PerformancePlanStatus;plan_reason: string;}+/** Whether a quoted id still names something this index can resolve. */+export interface PerformanceModelState {+ state: "current" | "stale_model" | "unrecognized";+ opportunity_id: string;+ requested_model_version: number | null;+ performance_model_version: number;+ refresh_required: boolean;+}++/**+ * One opportunity by id. An unresolved id still answers, with the model state+ * and what to do about it, rather than reading as "nothing to fix here".+ */+export type PerformanceOpportunityDetail =+ | ({+ resolved: true;+ lifecycle_status: "open" | "resolved";+ analyzed_commit: string | null;+ model_state: PerformanceModelState;+ evidence_total: number;+ evidence_emitted: number;+ evidence_next_cursor?: number;+ } & PerformanceOpportunity)+ | {+ resolved: false;+ opportunity_id: string;+ model_state: PerformanceModelState;+ detail: string;+ };++/** Counts per value for one filter, cross-filtered by the other filters. */+export interface PerformanceFacetCount {+ value: string;+ total: number;+}++export type PerformanceFacets = Record<string, PerformanceFacetCount[]>;+export interface PerformanceOpportunitySummary {+ /** `current` once materialized, `stale_model` after a model bump, or+ * `unavailable` when this index has not been analyzed yet. */+ status: "current" | "stale_model" | "unavailable";total: number;+ performance_model_version?: number;+ analyzed_commit?: string | null;+ actionability?: Partial<Record<PerformanceActionabilityState, number>>;+ context?: Partial<Record<PerformanceExecutionContext, number>>;+ boundary?: Record<string, number>;+ with_plan_total: number;+ /** Flat counters the current tab reads, projected from `context` above. */production_total: number;tooling_total: number;test_total: number;- with_plan_total: number;+ unknown_total: number;without_plan_total: number;}export interface PerformanceOpportunityPage extends Paginated<PerformanceOpportunity> {summary: PerformanceOpportunitySummary;+ facets: PerformanceFacets;+ /** Filter values the server did not recognize, named rather than dropped. */+ ignored_arguments?: Record<string, string>;}export interface HealthModuleRow {diff --git a/packages/ui/__tests__/health/performance-view.test.tsx b/packages/ui/__tests__/health/performance-view.test.tsxindex 1caff9191..34f94f5db 100644--- a/packages/ui/__tests__/health/performance-view.test.tsx+++ b/packages/ui/__tests__/health/performance-view.test.tsx@@ -14,6 +14,7 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {items: [{opportunity_id: "opp-1",+ performance_model_version: 2,biomarker_type: "io_in_loop",biomarker_types: ["io_in_loop"],boundary_kind: "db",@@ -21,6 +22,8 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {terminal_sink: "src/db.py::fetch",shared_path_suffix: ["src/shared.py::load", "src/db.py::fetch"],intervention_symbol: "src/shared.py::load",+ file_path: "src/shared.py",+ resource_fingerprints: [],affected_call_sites_total: 2,affected_files_total: 2,observations_total: 6,@@ -49,11 +52,26 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {},],evidence_truncated: true,+ evidence_total: 6,+ evidence_emitted: 2,+ evidence_next_cursor: 2,reliable_entry_reachability: true,provenance: "reliable-edge",confidence: "medium",+ facets: {+ actionability_confidence: "medium",+ exposure: "entry_reachable",+ amplification: "per_iteration",+ leverage: "local",+ change_risk: "moderate",+ },+ actionability_state: "advisory",+ actionability_reason: "strategy_requires_validation",+ prerequisites: ["batch_api_contract"],rank_score: 12.5,+ rank_position: 0,rank_factors: {},+ why_ranked: [{ factor: "boundary_kind", value: "db", points: 4 }],fix: {strategy: "batch_or_prefetch_io",safety: "advisory",@@ -67,11 +85,14 @@ function page(planId: string | null = "plan-1"): PerformanceOpportunityPage {total: 1,has_more: false,next_offset: null,+ facets: {},summary: {+ status: "current",total: 2,production_total: 1,tooling_total: 0,test_total: 1,+ unknown_total: 0,with_plan_total: planId ? 1 : 0,without_plan_total: planId ? 1 : 2,},diff --git a/tests/fixtures/perf_corpus/golden_opportunities.json b/tests/fixtures/perf_corpus/golden_opportunities.jsonindex c739ebbb0..aad16d559 100644--- a/tests/fixtures/perf_corpus/golden_opportunities.json+++ b/tests/fixtures/perf_corpus/golden_opportunities.json@@ -15,7 +15,7 @@{"biomarker_type": "serial_await_in_loop","file_path": "src/app/fanout.py",- "finding_id": "async_serial_awaits-09",+ "finding_id": "hf1_b157597c538312230160","function_name": "gather_all","line_end": 92,"line_start": 90,@@ -90,7 +90,7 @@{"biomarker_type": "resource_construction_in_loop","file_path": "src/app/clients.py",- "finding_id": "resource_construction-16",+ "finding_id": "hf1_5ad540ed5be9ff91a083","function_name": "each","line_end": 172,"line_start": 170,@@ -165,7 +165,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/entry.py",- "finding_id": "reachability_states-25",+ "finding_id": "hf1_0823db7a2e988fb8b165","function_name": "a","line_end": 252,"line_start": 250,@@ -180,7 +180,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/entry.py",- "finding_id": "reachability_states-26",+ "finding_id": "hf1_578bec48b788a57ce085","function_name": "b","line_end": 257,"line_start": 255,@@ -265,7 +265,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/api.py",- "finding_id": "specific_shared_helper-03",+ "finding_id": "hf1_e944c79df994e87201d0","function_name": "list_users","line_end": 32,"line_start": 30,@@ -280,7 +280,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/api.py",- "finding_id": "specific_shared_helper-04",+ "finding_id": "hf1_369c4ed522b7c79bb338","function_name": "list_orders","line_end": 33,"line_start": 31,@@ -366,7 +366,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/reindex.py",- "finding_id": "cost_shape_merge-21",+ "finding_id": "hf1_f326415f03634da6edff","function_name": "one","line_end": 212,"line_start": 210,@@ -381,7 +381,7 @@{"biomarker_type": "nested_loop_with_io","file_path": "src/app/reindex.py",- "finding_id": "cost_shape_merge-22",+ "finding_id": "hf1_1ca34d0590635ad5fa7e","function_name": "many","line_end": 217,"line_start": 215,@@ -466,7 +466,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/sync.py",- "finding_id": "same_file_db_helper-07",+ "finding_id": "hf1_ddc30fca4e968dc937dc","function_name": "sync_one","line_end": 72,"line_start": 70,@@ -481,7 +481,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/sync.py",- "finding_id": "same_file_db_helper-08",+ "finding_id": "hf1_8a8dbf682cb16d7351a0","function_name": "sync_all","line_end": 73,"line_start": 71,@@ -566,7 +566,7 @@{"biomarker_type": "blocking_io_under_lock","file_path": "src/app/cache.py",- "finding_id": "single_lock_owner-11",+ "finding_id": "hf1_42138363b2d56be00569","function_name": "refresh","line_end": 112,"line_start": 110,@@ -649,7 +649,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/billing.py",- "finding_id": "generic_infra_sink-01",+ "finding_id": "hf1_5e1434284085c8d89807","function_name": "handle","line_end": 13,"line_start": 11,@@ -733,7 +733,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/orders.py",- "finding_id": "generic_infra_sink-00",+ "finding_id": "hf1_b5e9b88139938221b07f","function_name": "handle","line_end": 12,"line_start": 10,@@ -817,7 +817,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/reports.py",- "finding_id": "generic_infra_sink-02",+ "finding_id": "hf1_5a4726fc8549aab5f4a3","function_name": "handle","line_end": 14,"line_start": 12,@@ -901,7 +901,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/job.py",- "finding_id": "context_split-18",+ "finding_id": "hf1_6076ccc742fcda80f642","function_name": "run","line_end": 202,"line_start": 200,@@ -985,7 +985,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/lone.py",- "finding_id": "sink_without_caller-33",+ "finding_id": "hf1_7ecc1136a23953fb0936","function_name": "run","line_end": 11,"line_start": 9,@@ -1067,7 +1067,7 @@{"biomarker_type": "io_in_loop","file_path": "scripts/backfill.py",- "finding_id": "context_split-19",+ "finding_id": "hf1_5ff8013358afaf016e7c","function_name": "run","line_end": 202,"line_start": 200,@@ -1151,7 +1151,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/edge.py",- "finding_id": "provenance_mix-23",+ "finding_id": "hf1_af7e43a631e63d3a640c","function_name": "run","line_end": 232,"line_start": 230,@@ -1235,7 +1235,7 @@{"biomarker_type": "io_in_loop","file_path": "tests/test_job.py",- "finding_id": "context_split-20",+ "finding_id": "hf1_0a2ba842c19f76c1c567","function_name": "run","line_end": 202,"line_start": 200,@@ -1319,7 +1319,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/guess.py",- "finding_id": "provenance_mix-24",+ "finding_id": "hf1_5f39d2fe1231369724a4","function_name": "run","line_end": 242,"line_start": 240,@@ -1404,7 +1404,7 @@{"biomarker_type": "membership_test_against_list_in_loop","file_path": "src/app/filters.py",- "finding_id": "membership_scan-14",+ "finding_id": "hf1_5b38d822737127eff696","function_name": "select","line_end": 152,"line_start": 150,@@ -1482,7 +1482,7 @@{"biomarker_type": "string_concat_in_loop","file_path": "src/app/render.py",- "finding_id": "string_accumulation-15",+ "finding_id": "hf1_b1d031c5caf612deae23","function_name": "to_csv","line_end": 162,"line_start": 160,@@ -1559,7 +1559,7 @@{"biomarker_type": "blocking_io_under_lock","file_path": "src/app/pool.py",- "finding_id": "distinct_lock_owners-13",+ "finding_id": "hf1_53aa0b7de62bef7cf3a1","function_name": "reaper","line_end": 132,"line_start": 130,@@ -1574,7 +1574,7 @@{"biomarker_type": "blocking_io_under_lock","file_path": "src/app/pool.py",- "finding_id": "distinct_lock_owners-12",+ "finding_id": "hf1_70aae64c974e10e8567e","function_name": "writer","line_end": 132,"line_start": 130,@@ -1654,7 +1654,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/formatter.py",- "finding_id": "shared_dominator_fan_in-29",+ "finding_id": "hf1_49feb9a4d9831db3880b","function_name": "run","line_end": 24,"line_start": 22,@@ -1669,7 +1669,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/lexer.py",- "finding_id": "shared_dominator_fan_in-27",+ "finding_id": "hf1_02b54f38fbb30a5c663f","function_name": "run","line_end": 22,"line_start": 20,@@ -1684,7 +1684,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/linter.py",- "finding_id": "shared_dominator_fan_in-28",+ "finding_id": "hf1_b142f6e353eb4b957ec5","function_name": "run","line_end": 23,"line_start": 21,@@ -1699,7 +1699,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/resolver.py",- "finding_id": "shared_dominator_fan_in-30",+ "finding_id": "hf1_f43aa873be79bf90590a","function_name": "run","line_end": 25,"line_start": 23,@@ -1779,7 +1779,7 @@{"biomarker_type": "resource_construction_in_loop","file_path": "src/app/clients.py",- "finding_id": "resource_construction-17",+ "finding_id": "hf1_199ce617b3bc8a442dc6","function_name": "each_varying","line_end": 182,"line_start": 180,@@ -1852,7 +1852,7 @@{"biomarker_type": "serial_await_in_loop","file_path": "src/app/fanout.py",- "finding_id": "async_serial_awaits-10",+ "finding_id": "hf1_a20deca6f8a2935a9f60","function_name": "gather_seq","line_end": 97,"line_start": 95,@@ -1925,7 +1925,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/walker.py",- "finding_id": "filesystem_fan_out-05",+ "finding_id": "hf1_1ac91145d11248da1c67","function_name": "scan","line_end": 52,"line_start": 50,@@ -2004,7 +2004,7 @@{"biomarker_type": "io_in_loop","file_path": "src/app/walker.py",- "finding_id": "filesystem_fan_out-06",+ "finding_id": "hf1_6f6b30a7872faf6737f0","function_name": "index","line_end": 53,"line_start": 51,@@ -2083,7 +2083,7 @@{"biomarker_type": "io_in_loop","file_path": "docs/snippets/walk.py",- "finding_id": "unclassified_context-31",+ "finding_id": "hf1_233c919884cf9aa50001","function_name": "demo","line_end": 10,"line_start": 8,@@ -2156,7 +2156,7 @@{"biomarker_type": "io_in_loop","file_path": "bootstrap.py",- "finding_id": "unclassified_context-32",+ "finding_id": "hf1_072c88fe4bfe6a1bab1f","function_name": "main","line_end": 16,"line_start": 14,diff --git a/tests/unit/health/test_perf_identity_contract.py b/tests/unit/health/test_perf_identity_contract.pyindex 8aae13f13..8717f27d7 100644--- a/tests/unit/health/test_perf_identity_contract.py+++ b/tests/unit/health/test_perf_identity_contract.py@@ -17,6 +17,7 @@ import copyimport pytest+from repowise.core.analysis.health.finding_identity import finding_public_idfrom repowise.core.analysis.health.perf.opportunities import (PERFORMANCE_MODEL_VERSION,build_performance_opportunities,@@ -266,26 +267,48 @@ def test_the_plan_id_is_absent_from_plan_evidence_today() -> None:assert "opportunity_id" not in plan.evidence-def test_a_performance_finding_has_no_content_derived_public_reference() -> None:- """The only stable public key on a performance finding is its group id.+def test_evidence_is_addressed_by_a_content_derived_public_reference() -> None:+ """Evidence carries the finding's public id, never a storage row id.- ``evidence[].finding_id`` is the storage row id: empty in memory, a random- UUID once persisted. Nothing joins on it across a reindex, so it is not- an identity.+ The row id is republished on every analysis, so a caller who quoted one+ back was quoting a value that no longer existed. The public id is derived+ from the finding's own coordinates, so it survives the reindex and is the+ same string before and after persistence."""in_memory = _row()del in_memory["id"]- opportunity = build_performance_opportunities([in_memory])[0]- assert opportunity.evidence[0]["finding_id"] == ""+ reference = build_performance_opportunities([in_memory])[0].evidence[0]["finding_id"]+ assert reference == finding_public_id(in_memory)persisted = _row(id="8f14e45fceea167a5a36dedd4bea2543")- assert build_performance_opportunities([persisted])[0].evidence[0]["finding_id"] == (- "8f14e45fceea167a5a36dedd4bea2543"+ assert build_performance_opportunities([persisted])[0].evidence[0]["finding_id"] == reference++ stored = _row(id="8f14e45fceea167a5a36dedd4bea2543", public_id="finding_already_stored")+ assert build_performance_opportunities([stored])[0].evidence[0]["finding_id"] == (+ "finding_already_stored")link_performance_findings([persisted])assert persisted["details"]["opportunity_id"] == CROSS_FUNCTION_ID+def test_the_public_finding_id_ignores_prose_and_derived_details() -> None:+ """Rewording a detector, or a later model changing its mind, moves nothing.++ The id is stored on the row and quoted by agents, so anything that can+ change without the finding moving has to stay out of its kernel.+ """+ base = _row()+ assert finding_public_id(base) == finding_public_id(_row(reason="reworded entirely"))+ assert finding_public_id(base) == finding_public_id(+ _row(details={**base["details"], "opportunity_id": "perf9_deadbeef"})+ )+ assert finding_public_id(base) == finding_public_id(+ _row(details={**base["details"], "reliable_entry_reachability": True})+ )+ # Structural coordinates are in the kernel, so a real move is a new id.+ assert finding_public_id(base) != finding_public_id(_row(line_start=999))++def test_a_path_node_that_names_nothing_never_becomes_an_intervention_symbol() -> None:"""An empty node is absence, not a symbol called \"\"."""row = _row(details={"path": ["", "src/app/db.py::get_session"]})diff --git a/tests/unit/persistence/test_models.py b/tests/unit/persistence/test_models.pyindex 0ea407b52..d6e087181 100644--- a/tests/unit/persistence/test_models.py+++ b/tests/unit/persistence/test_models.py@@ -319,6 +319,8 @@ def test_base_includes_all_models():"health_file_metrics","health_snapshots","refactoring_suggestions",+ "performance_opportunities",+ "performance_summaries","coverage_files","test_coverage","pipeline_jobs",diff --git a/tests/unit/persistence/test_performance_materialization.py b/tests/unit/persistence/test_performance_materialization.pynew file mode 100644index 000000000..774b87df4--- /dev/null+++ b/tests/unit/persistence/test_performance_materialization.py@@ -0,0 +1,372 @@+"""The writer that turns stored performance findings into a servable queue.++Grouping used to happen on every read, so a page of twenty cost the whole+repository. It happens here instead, once per health persistence transaction,+and both index paths call it. These tests pin what that means: the same answer+from a full and a partial run, plans generated exactly once, a cause that stops+being observed resolved rather than dropped, and a schema that upgrades and+rolls back.+"""++from __future__ import annotations++import json+import sqlite3+from pathlib import Path++import pytest+from sqlalchemy import select++from repowise.core.analysis.health.models import HealthFindingData, Severity+from repowise.core.analysis.health.perf.opportunities import (+ PERFORMANCE_MODEL_VERSION,+ link_performance_findings,+)+from repowise.core.analysis.health.refactoring.performance_fix import PerformancePlanPolicy+from repowise.core.persistence import crud+from repowise.core.persistence.models import (+ HealthFinding,+ PerformanceOpportunity,+ PerformanceSummary,+ RefactoringSuggestion,+)+from tests.unit.persistence.helpers import insert_repo++_SHARED = ["{caller}::run", "src/shared.py::load", "src/db.py::fetch"]+++def _finding(path: str, line: int, *, marker: str = "serial_await_in_loop", **details):+ return HealthFindingData(+ biomarker_type=marker,+ severity=Severity.MEDIUM,+ file_path=path,+ function_name="run",+ line_start=line,+ line_end=line,+ details={+ "boundary_kind": "db",+ "cross_function": True,+ "path": [node.format(caller=path) for node in _SHARED],+ "resolution_basis": "call-site",+ "dataflow_verified": True,+ **details,+ },+ health_impact=0.0,+ reason="Awaited database work repeats for every loop iteration.",+ dimension="performance",+ )+++def _corpus() -> list:+ return [_finding("src/a.py", 10), _finding("src/b.py", 20), _finding("src/c.py", 30)]+++async def _write(session, repo_id: str, findings: list, **kwargs) -> int:+ link_performance_findings(findings)+ await crud.save_health_findings(session, repo_id, findings)+ return await crud.finalize_performance_opportunities(session, repo_id, **kwargs)+++async def _rows(session, repo_id: str) -> list[PerformanceOpportunity]:+ result = await session.execute(+ select(PerformanceOpportunity)+ .where(PerformanceOpportunity.repository_id == repo_id)+ .order_by(PerformanceOpportunity.rank_position)+ )+ return list(result.scalars().all())+++async def test_one_pass_materializes_the_queue_its_plans_and_its_headline(+ async_session,+) -> None:+ repo = await insert_repo(async_session)+ total = await _write(async_session, repo.id, _corpus(), analyzed_commit="b" * 40)++ assert total == 1+ (row,) = await _rows(async_session, repo.id)+ assert row.status == "open"+ assert row.rank_position == 0+ assert row.observations_total == 3+ assert row.affected_call_sites_total == 3+ assert row.intervention_symbol == "src/shared.py::load"+ assert row.file_path == "src/shared.py"+ assert row.plan_state == "available"+ assert row.performance_model_version == PERFORMANCE_MODEL_VERSION+ assert row.analyzed_commit == "b" * 40++ # Filter and order live in columns; the rest stays in the open payload, and+ # nothing appears in both.+ details = json.loads(row.details_json)+ assert set(details) & {"execution_context", "rank_score", "boundary_kind"} == set()+ assert details["facets"]["leverage"] == "local"++ plans = await crud.get_refactoring_suggestions(+ async_session, repo.id, refactoring_type="performance_fix"+ )+ assert [plan.opportunity_id for plan in plans] == [row.opportunity_id]++ summary = await crud.get_performance_summary(async_session, repo.id)+ assert summary.opportunities_total == 1+ assert json.loads(summary.summary_json)["lead"]["opportunity_id"] == row.opportunity_id+++async def test_every_stored_observation_carries_its_cause_and_its_public_id(+ async_session,+) -> None:+ """Both are columns, which is what makes drill-down an indexed seek."""+ repo = await insert_repo(async_session)+ await _write(async_session, repo.id, _corpus())+ rows = (+ (+ await async_session.execute(+ select(HealthFinding).where(HealthFinding.repository_id == repo.id)+ )+ )+ .scalars()+ .all()+ )+ (opportunity,) = await _rows(async_session, repo.id)+ assert {row.opportunity_id for row in rows} == {opportunity.opportunity_id}+ assert all(row.public_id and row.public_id.startswith("finding_") for row in rows)+ assert len({row.public_id for row in rows}) == 3+++async def test_a_store_written_before_the_columns_existed_is_backfilled(+ async_session,+) -> None:+ """The columns are nullable, so an upgraded store arrives with them empty."""+ repo = await insert_repo(async_session)+ await _write(async_session, repo.id, _corpus())+ await async_session.execute(+ HealthFinding.__table__.update()+ .where(HealthFinding.repository_id == repo.id)+ .values(public_id=None, opportunity_id=None)+ )+ await crud.finalize_performance_opportunities(async_session, repo.id)++ rows = (+ (+ await async_session.execute(+ select(HealthFinding).where(HealthFinding.repository_id == repo.id)+ )+ )+ .scalars()+ .all()+ )+ assert all(row.public_id and row.opportunity_id for row in rows)+++async def test_a_partial_run_and_a_full_run_reach_the_same_queue(async_session) -> None:+ """The partial path sees a subset, so it must not build the queue itself.++ It writes its own findings and then rebuilds from the merged stored set,+ which is the only way the two paths can agree.+ """+ full_repo = await insert_repo(async_session, name="full", local_path="/tmp/full")+ await _write(async_session, full_repo.id, _corpus())+ expected = [+ (row.opportunity_id, row.rank_position, row.observations_total, row.plan_state)+ for row in await _rows(async_session, full_repo.id)+ ]++ partial_repo = await insert_repo(async_session, name="partial", local_path="/tmp/partial")+ first = _corpus()[:1]+ link_performance_findings(first)+ await crud.save_health_findings(async_session, partial_repo.id, first)+ rest = _corpus()[1:]+ link_performance_findings(rest)+ await crud.upsert_health_findings(+ async_session,+ partial_repo.id,+ rest,+ file_paths=["src/b.py", "src/c.py"],+ )+ await crud.finalize_performance_opportunities(async_session, partial_repo.id)++ assert [+ (row.opportunity_id, row.rank_position, row.observations_total, row.plan_state)+ for row in await _rows(async_session, partial_repo.id)+ ] == expected+++async def test_a_cause_nobody_observes_is_resolved_and_its_plan_withdrawn(+ async_session,+) -> None:+ repo = await insert_repo(async_session)+ await _write(async_session, repo.id, _corpus())+ (before,) = await _rows(async_session, repo.id)++ await _write(async_session, repo.id, [_finding("src/z.py", 40, marker="io_in_loop")])+ rows = {row.opportunity_id: row for row in await _rows(async_session, repo.id)}++ assert rows[before.opportunity_id].status == "resolved"+ assert len([row for row in rows.values() if row.status == "open"]) == 1+ # The withdrawn cause's plan goes with it: plans are replaced wholesale+ # from the current opportunities, never left behind pointing at nothing.+ plans = await crud.get_refactoring_suggestions(+ async_session, repo.id, refactoring_type="performance_fix"+ )+ assert before.opportunity_id not in {plan.opportunity_id for plan in plans}+++async def test_a_row_from_an_older_model_is_resolved_rather_than_reused(+ async_session,+) -> None:+ """Two model versions disagree about membership, so neither can stand in+ for the other. The old row stays addressable and stops reading as current.+ """+ repo = await insert_repo(async_session)+ await _write(async_session, repo.id, _corpus())+ async_session.add(+ PerformanceOpportunity(+ id="0" * 32,+ repository_id=repo.id,+ opportunity_id="perf1_0123456789abcdef0123",+ performance_model_version=PERFORMANCE_MODEL_VERSION - 1,+ status="open",+ )+ )+ await async_session.flush()++ await crud.finalize_performance_opportunities(async_session, repo.id)+ rows = {row.opportunity_id: row.status for row in await _rows(async_session, repo.id)}+ assert rows["perf1_0123456789abcdef0123"] == "resolved"+++async def test_disabling_plans_leaves_the_queue_and_withdraws_the_plans(+ async_session,+) -> None:+ repo = await insert_repo(async_session)+ await _write(+ async_session,+ repo.id,+ _corpus(),+ plan_policy=PerformancePlanPolicy(enabled=False),+ )+ (row,) = await _rows(async_session, repo.id)+ assert row.plan_state == "not_persisted"+ assert row.fix_strategy == "parallelize_independent_awaits"+ assert (+ await async_session.execute(+ select(RefactoringSuggestion).where(+ RefactoringSuggestion.repository_id == repo.id+ )+ )+ ).scalars().first() is None+++async def test_a_repository_with_no_performance_findings_still_has_a_headline(+ async_session,+) -> None:+ """A missing summary row means "never analyzed"; an empty one means clear.++ Collapsing the two would make an index that has not run yet look healthy.+ """+ repo = await insert_repo(async_session)+ assert await crud.get_performance_summary(async_session, repo.id) is None++ await crud.finalize_performance_opportunities(async_session, repo.id)+ summary = await crud.get_performance_summary(async_session, repo.id)+ assert isinstance(summary, PerformanceSummary)+ assert summary.opportunities_total == 0+ assert json.loads(summary.summary_json)["lead"] is None+++async def test_a_rebuild_that_fails_halfway_leaves_the_previous_state(+ async_session, monkeypatch+) -> None:+ """The queue must never describe findings that were never stored.++ The incremental caller logs a failed health step and carries on to commit+ the rest of the run, so the savepoint around the write is what stops a+ half-finished rebuild from becoming the current answer.+ """+ from repowise.core.persistence.crud.analysis import performance as writer++ repo = await insert_repo(async_session)+ await _write(async_session, repo.id, _corpus(), analyzed_commit="1" * 40)+ (before,) = await _rows(async_session, repo.id)++ async def explode(*_args, **_kwargs):+ raise RuntimeError("summary write failed")++ monkeypatch.setattr(writer, "_write_summary", explode)+ findings = [_finding("src/z.py", 40, marker="io_in_loop")]+ link_performance_findings(findings)+ with pytest.raises(RuntimeError):+ async with async_session.begin_nested():+ await crud.save_health_findings(async_session, repo.id, findings)+ await crud.finalize_performance_opportunities(async_session, repo.id)++ rows = await _rows(async_session, repo.id)+ assert [(row.opportunity_id, row.status) for row in rows] == [+ (before.opportunity_id, "open")+ ]+ summary = await crud.get_performance_summary(async_session, repo.id)+ assert summary.analyzed_commit == "1" * 40+ stored = (+ (+ await async_session.execute(+ select(HealthFinding.file_path).where(+ HealthFinding.repository_id == repo.id+ )+ )+ )+ .scalars()+ .all()+ )+ assert sorted(stored) == ["src/a.py", "src/b.py", "src/c.py"]+++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 test_the_migration_upgrades_and_rolls_back(tmp_path: Path) -> None:+ """Explicit migration for managed stores, both directions.++ Local stores are created by ``init_db`` and never see Alembic, which is why+ the model declaration and this migration have to describe the same shape.+ """+ from alembic import command+ from alembic.config import Config++ root = Path(__file__).resolve().parents[3] / "packages" / "core"+ db_path = tmp_path / "wiki.db"+ # Built without the ini file on purpose. Passing it makes ``env.py`` call+ # ``fileConfig``, which reconfigures logging for the rest of the session and+ # silences the warnings other tests assert on.+ config = Config()+ config.set_main_option("script_location", str(root / "alembic"))+ config.set_main_option("sqlalchemy.url", f"sqlite+aiosqlite:///{db_path}")++ command.upgrade(config, "0057")+ assert {"performance_opportunities", "performance_summaries"} <= _tables(db_path)+ assert {"public_id", "opportunity_id"} <= _columns(db_path, "health_findings")+ assert "opportunity_id" in _columns(db_path, "refactoring_suggestions")++ command.downgrade(config, "0056")+ assert not {"performance_opportunities", "performance_summaries"} & _tables(db_path)+ assert not {"public_id", "opportunity_id"} & _columns(db_path, "health_findings")+ assert "opportunity_id" not in _columns(db_path, "refactoring_suggestions")diff --git a/tests/unit/persistence/test_refactoring_suggestions_crud.py b/tests/unit/persistence/test_refactoring_suggestions_crud.pyindex 38421816d..3c60b7720 100644--- a/tests/unit/persistence/test_refactoring_suggestions_crud.py+++ b/tests/unit/persistence/test_refactoring_suggestions_crud.py@@ -197,7 +197,14 @@ async def test_performance_only_partial_scope_clears_stale_plan(async_session):@pytest.mark.asyncio-async def test_partial_performance_scope_persists_downstream_intervention(async_session):+async def test_a_partial_run_never_persists_its_own_performance_plans(async_session):+ """A partial run sees a subset of the findings, so its plans are a subset.++ The plans it carries are a report-level convenience. The authoritative ones+ are rebuilt from the merged stored findings by the writer both index paths+ share, which is also what retired the path bookkeeping this writer used to+ need to reach a shared intervention downstream of its callers.+ """from repowise.core.pipeline.incremental import persist_partial_healthrepo = await insert_repo(async_session)@@ -224,7 +231,5 @@ async def test_partial_performance_scope_persists_downstream_intervention(async_await persist_partial_health(async_session, repo.id, report)await async_session.commit()- rows = await get_refactoring_suggestions(async_session, repo.id)- assert [(row.refactoring_type, row.file_path, row.target_symbol) for row in rows] == [- ("performance_fix", "shared.py", "shared.py::load")- ]+ # No stored findings, so the rebuild leaves no performance plan behind.+ assert await get_refactoring_suggestions(async_session, repo.id) == []diff --git a/tests/unit/server/mcp/test_health.py b/tests/unit/server/mcp/test_health.pyindex 43f046e32..83d2eb83e 100644--- a/tests/unit/server/mcp/test_health.py+++ b/tests/unit/server/mcp/test_health.py@@ -21,7 +21,9 @@ 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"- assert list(result)[:2] == ["directive", "mode"]+ # 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"]assert "high_leverage_files" in resultassert "worst_files" not in resultassert result["secondary_rankings"]["worst_files"]["total"] == 2@@ -388,11 +390,20 @@ async def test_combined_recommendation_lede_is_compact_and_self_directing(}],)+ # The queue is materialized, so the fixture's findings only reach the lede+ # once the writer both index paths use has grouped them.+ from repowise.core.persistence.crud import finalize_performance_opportunities++ await finalize_performance_opportunities(session, health_data)+ await session.commit()+result = await get_health(include=["performance", "refactoring"], only=["recommendation_lede"])lede = result["recommendation_lede"]assert set(result) <= {"mode", "recommendation_lede", "_meta"}assert lede["performance_opportunities_total"] == 1- assert lede["refactoring_plans_total"] == 1+ # Two: the seeded extract-class plan, and the authoritative performance+ # plan the finalizer generated for the fixture's own opportunity.+ assert lede["refactoring_plans_total"] == 2assert lede["performance_lead"]["boundary_kind"] == "db"assert {"benefit", "leverage", "cost", "risk"} <= set(lede["recommendation_lead"])assert "validation" not in lede["recommendation_lead"]diff --git a/tests/unit/server/mcp/test_overview_surface.py b/tests/unit/server/mcp/test_overview_surface.pyindex 7d674885b..63880b880 100644--- a/tests/unit/server/mcp/test_overview_surface.py+++ b/tests/unit/server/mcp/test_overview_surface.py@@ -209,4 +209,12 @@ async def test_live_registry_recipe_calls_bind_to_current_tool_signatures(setup_'get_health(include=["performance","refactoring"], ''only=["performance_opportunities","refactoring_plans"])'),+ "health_performance_summary": (+ 'get_health(include=["performance"], only=["performance_summary"])'+ ),+ "health_performance_opportunity": 'get_health(opportunity_id="perf...")',+ "health_performance_evidence": (+ 'get_health(opportunity_id="perf...", '+ 'only=["performance_evidence"], cursor=0)'+ ),}diff --git a/tests/unit/server/mcp/test_perf_rank.py b/tests/unit/server/mcp/test_perf_rank.pyindex 2d8185d66..e590462e7 100644--- a/tests/unit/server/mcp/test_perf_rank.py+++ b/tests/unit/server/mcp/test_perf_rank.py@@ -19,11 +19,11 @@ import uuidimport pytestfrom repowise.core.analysis.health.biomarkers import registered_biomarkers-from repowise.server.mcp_server.tool_health import (- _PERF_MARKER_POINTS,- _perf_rank,- _rank_emitted,+from repowise.core.analysis.health.perf.opportunity_rank import (+ MULTIPLIER_POINTS,+ UNKNOWN_MULTIPLIER_POINTS,)+from repowise.server.mcp_server.tool_health import _perf_rank, _rank_emitted# ---------------------------------------------------------------------------# The key itself@@ -31,7 +31,12 @@ from repowise.server.mcp_server.tool_health import (def test_every_performance_biomarker_carries_a_weight() -> None:- """The weight table must not silently acquire a default.+ """One weight table, and it must not silently acquire a default.++ The observation key and the opportunity rank read the same table. They+ used to keep one each and had already drifted apart on markers both named,+ so a finding and the opportunity built from it disagreed about the same+ evidence.A detector added without a weight ranks at the floor, which is the safedirection but also an invisible one — a new high-cost marker would sort@@ -42,12 +47,12 @@ def test_every_performance_biomarker_carries_a_weight() -> None:b.name for b in registered_biomarkers() if getattr(b, "category", "") == "performance"}assert registered, "no performance detectors registered — the check is vacuous"- assert registered <= set(_PERF_MARKER_POINTS), (- f"unweighted performance biomarkers: {sorted(registered - set(_PERF_MARKER_POINTS))}"+ assert registered <= set(MULTIPLIER_POINTS), (+ f"unweighted performance biomarkers: {sorted(registered - set(MULTIPLIER_POINTS))}")# And no stale entries pointing at detectors that no longer exist.- assert set(_PERF_MARKER_POINTS) <= registered, (- f"weights for unregistered markers: {sorted(set(_PERF_MARKER_POINTS) - registered)}"+ assert set(MULTIPLIER_POINTS) <= registered, (+ f"weights for unregistered markers: {sorted(set(MULTIPLIER_POINTS) - registered)}")@@ -91,7 +96,8 @@ def test_the_gated_markers_carry_their_hotness_proof() -> None:def test_an_unknown_marker_sinks_rather_than_floats() -> None:- assert _perf_rank("some_future_marker", {}) == min(_PERF_MARKER_POINTS.values())+ assert _perf_rank("some_future_marker", {}) == UNKNOWN_MULTIPLIER_POINTS+ assert min(MULTIPLIER_POINTS.values()) > UNKNOWN_MULTIPLIER_POINTSdef test_malformed_details_never_raise() -> None:@@ -219,21 +225,22 @@ async def test_the_perf_head_is_the_costliest_findings_not_the_first_alphabeticathat was file order, so a small ``limit`` returned the cheapest findings inthe repo and called them the top ones.- The base fixture's perf finding carries a non-zero impact, so it still leads- — the key breaks ties *within* an impact tier and never reorders across one.+ The base fixture's perf finding carries a non-zero impact, so it still+ leads: the key breaks ties *within* an impact tier and never reorders+ across one."""from repowise.server.mcp_server import get_healthresult = await get_health(include=["biomarkers", "performance"], limit=4)assert [f["file_path"] for f in result["findings"]] == ["src/auth/service.py",+ "h_nested_db.py","i_spawn_xfn.py",- "g_hot_spawn.py","f_db_xfn.py",]- # Rank 6 is a three-way tie (the base fixture's row, the cross-function db- # N+1 and the nested db loop); ``file_path`` is what makes the order total.- assert [f["perf_rank"] for f in result["findings"]] == [6, 8, 7, 6]+ ranks = [f["perf_rank"] for f in result["findings"]]+ # A tie at the top, broken by ``file_path`` so the order is total.+ assert ranks[1] == ranks[2] > ranks[3]# The total still describes the whole filtered set, so the cap stays visible.assert result["findings_total"] == 10@@ -256,17 +263,14 @@ async def test_perf_rank_is_absent_from_every_other_dimension(setup_mcp, perf_fi@pytest.mark.asyncioasync def test_narrow_projection_leads_with_one_shared_causal_opportunity(- setup_mcp, perf_findings, session, monkeypatch, tmp_path+ setup_mcp, perf_findings, session):+ """One shared helper, five callers, one cause, and a recoverable tail."""import json- from repowise.core.distill.store import OmissionStore+ from repowise.core.persistence.crud import finalize_performance_opportunitiesfrom repowise.core.persistence.models import HealthFindingfrom repowise.server.mcp_server import get_health- from repowise.server.mcp_server._budget import collector as collector_module-- store_path = tmp_path / "omissions.db"- monkeypatch.setattr(collector_module, "default_store_path", lambda _root: store_path)for index, caller in enumerate(("src/a.py", "src/b.py", "src/c.py", "src/d.py", "src/e.py"), start=10@@ -296,8 +300,12 @@ async def test_narrow_projection_leads_with_one_shared_causal_opportunity())await session.flush()+ await finalize_performance_opportunities(session, perf_findings)+ await session.commit()- result = await get_health(include=["performance"], only=["performance_opportunities"], limit=50)+ result = await get_health(+ include=["performance"], only=["performance_opportunities"], limit=50+ )shared = [itemfor item in result["performance_opportunities"]@@ -311,47 +319,21 @@ async def test_narrow_projection_leads_with_one_shared_causal_opportunity(assert {item["function_name"] for item in shared[0]["evidence"]} == {"run"}assert shared[0]["evidence_total"] == 5assert shared[0]["evidence_emitted"] == 3- assert shared[0]["evidence_reduced_reason"] == "evidence_cap"- refs = result["_meta"]["omitted"]["refs"]- assert len(refs) == 1- store = OmissionStore(store_path)- try:- omitted = store.get(refs[0]) or ""- finally:- store.close()- assert '"line_start": 13' in omitted- assert '"line_start": 14' in omitted- assert '"line_start": 10' not in omitted- assert result["performance_opportunities_total"] >= 1- assert "top_findings" not in result---async def test_the_default_dashboard_does_not_pay_for_the_ranking_read(- setup_mcp, perf_findings, monkeypatch-):- """``details_json`` joins the narrow read only when perf can reach the head.-- Every perf finding carries impact 0, so in a mixed list all the defect- findings sort above them and the rank cannot move a row — paying for the- column there would be 6.6ms bought for nothing. This asserts the *read*:- the response is identical either way, so a payload-only test would pass on- the unfixed code.- """- from repowise.server.mcp_server import get_health, tool_health-- selected: list[list[str]] = []- real = tool_health.select-- def spy(*cols):- selected.append([getattr(c, "key", str(c)) for c in cols])- return real(*cols)-- monkeypatch.setattr(tool_health, "select", spy)-- await get_health()- assert not any("details_json" in cols for cols in selected)-- selected.clear()- await get_health(include=["biomarkers", "performance"])- assert any("details_json" in cols for cols in selected)+ assert shared[0]["evidence_reduced_reason"] == "evidence_page"++ # The tail is recovered by paging it, not by unpacking an omission blob.+ # A blob would have cost the full read of every observation to build.+ tail = await get_health(+ opportunity_id=shared[0]["opportunity_id"],+ only=["performance_evidence"],+ cursor=shared[0]["evidence_next_cursor"],+ limit=50,+ )+ assert [item["line_start"] for item in tail["evidence"]] == [13, 14]+ assert tail["evidence_total"] == 5+ assert "evidence_next_cursor" not in tail++ # And every reference round-trips through the finding selector.+ detail = await get_health(finding_id=tail["evidence"][0]["finding_id"])+ assert detail["resolved"] is True+ assert detail["finding"]["file_path"] == "src/d.py"diff --git a/tests/unit/server/mcp/test_performance_levels.py b/tests/unit/server/mcp/test_performance_levels.pynew file mode 100644index 000000000..26a0ca51f--- /dev/null+++ b/tests/unit/server/mcp/test_performance_levels.py@@ -0,0 +1,452 @@+"""The agent contract for performance: actionable by default, deep on demand.++Four levels, one read model. The dashboard leads with something to do, the+summary rolls it up, the queue pages it, and one id drills all the way to+evidence and back out through the finding selector. The REST surface is the+same projection of the same rows, which is what these tests hold it to.+"""++from __future__ import annotations++import json+import uuid++import pytest+from sqlalchemy import event+from sqlalchemy.engine import Engine++from repowise.core.persistence.crud import finalize_performance_opportunities+from repowise.core.persistence.models import HealthFinding++_CALLERS = ("src/a.py", "src/b.py", "src/c.py", "src/d.py", "src/e.py")+++def _row(repo_id: str, caller: str, line: int) -> HealthFinding:+ return HealthFinding(+ id=str(uuid.uuid4()),+ repository_id=repo_id,+ file_path=caller,+ biomarker_type="serial_await_in_loop",+ severity="medium",+ function_name="run",+ line_start=line,+ line_end=line,+ details_json=json.dumps(+ {+ "boundary_kind": "db",+ "cross_function": True,+ "path": [f"{caller}::run", "src/shared.py::load", "src/db.py::fetch"],+ "resolution_basis": "call-site",+ "dataflow_verified": True,+ }+ ),+ health_impact=0.0,+ reason="Awaited database work repeats for every loop iteration.",+ dimension="performance",+ status="open",+ )+++async def materialized(session, health_data: str) -> str:+ """Five callers behind one shared helper, plus the base fixture's own row.++ The fixture contributes a second production cause, which is why the totals+ below are two rather than one.+ """+ for index, caller in enumerate(_CALLERS, start=10):+ session.add(_row(health_data, caller, index))+ await session.flush()+ await finalize_performance_opportunities(session, health_data, analyzed_commit="c" * 40)+ await session.commit()+ return health_data+++class _Statements:+ """Counts statements on every engine, including ones a tool opens itself."""++ def __init__(self) -> None:+ self.n = 0++ def __enter__(self):+ event.listen(Engine, "before_cursor_execute", self._hit)+ return self++ def __exit__(self, *_exc) -> None:+ event.remove(Engine, "before_cursor_execute", self._hit)++ def _hit(self, *_args, **_kwargs) -> None:+ self.n += 1+++async def test_a_bare_dashboard_leads_with_something_to_do(setup_mcp, materialized):+ """Performance carries no defect impact, so it never won the main lead.++ The dashboard reported counts and nothing an agent could act on. The+ additive lead is one primary-key read of the current summary row.+ """+ from repowise.server.mcp_server import get_health++ result = await get_health()+ directive = result["performance_directive"]+ assert directive["status"] == "plan_ready"+ assert directive["opportunity_id"].startswith("perf")+ assert directive["plan_state"] == "available"+ assert directive["next_action"] == {+ "tool": "get_health",+ "arguments": {"opportunity_id": directive["opportunity_id"]},+ }+ assert 0 < len(json.dumps(directive)) <= 1500+ # The existing lead is untouched.+ assert "directive" in result+++async def test_the_cheapest_documented_call_stays_cheap(setup_mcp, materialized):+ """``only=["directive"]`` must not start paying for the second lead."""+ from repowise.server.mcp_server import get_health++ result = await get_health(only=["directive"])+ assert "performance_directive" not in result+ assert "directive" in result+++async def test_a_clear_repository_never_reports_that_it_is_fast(setup_mcp, health_data):+ """No supported pattern is not a measurement of how the code runs."""+ from repowise.core.persistence.crud import finalize_performance_opportunities as finalize+ from repowise.server.mcp_server import _state, get_health++ async with _state._session_factory() as session:+ await session.execute(+ HealthFinding.__table__.delete().where(HealthFinding.dimension == "performance")+ )+ await finalize(session, health_data)+ await session.commit()+ directive = (await get_health())["performance_directive"]+ assert directive["status"] == "clear"+ assert "fast" not in directive["detail"].lower()+++async def test_an_unanalyzed_index_is_unavailable_not_clear(setup_mcp, health_data):+ """A missing materialization must not read as a clean repository."""+ from repowise.server.mcp_server import get_health++ directive = (await get_health())["performance_directive"]+ assert directive["status"] == "unavailable"+ assert directive["reason"] == "no_materialized_analysis"+++async def test_the_summary_rolls_up_and_names_the_next_call(setup_mcp, materialized):+ from repowise.server.mcp_server import get_health++ result = await get_health(include=["performance"], only=["performance_summary"])+ summary = result["performance_summary"]+ assert summary["status"] == "current"+ assert summary["actionability"]["plan_ready"] == 1+ assert summary["with_plan_total"] == 2+ assert summary["analyzed_commit"] == "c" * 40+ assert "get_health" in summary["next_call"]+ assert len(json.dumps(summary)) <= 3000+++async def test_the_queue_filters_before_it_caps(setup_mcp, materialized):+ from repowise.server.mcp_server import get_health++ result = await get_health(+ include=["performance"],+ only=["performance_opportunities"],+ performance_context="production",+ performance_boundary="db",+ )+ assert result["performance_opportunities_total"] == 2+ assert {+ item["execution_context"] for item in result["performance_opportunities"]+ } == {"production"}++ narrowed = await get_health(+ include=["performance"],+ only=["performance_opportunities"],+ performance_confidence="medium",+ )+ assert narrowed["performance_opportunities_total"] == 0++ empty = await get_health(+ include=["performance"],+ only=["performance_opportunities"],+ performance_context="test",+ )+ assert empty["performance_opportunities_total"] == 0+++async def test_an_unrecognized_filter_value_is_named_not_silently_empty(+ setup_mcp, materialized+):+ from repowise.server.mcp_server import get_health++ result = await get_health(+ include=["performance"],+ only=["performance_opportunities"],+ performance_context="staging",+ )+ assert result["performance_opportunities_total"] == 2+ assert result["ignored_arguments"] == {"performance_context": "staging"}+++async def test_the_summary_view_omits_evidence_without_changing_identity(+ setup_mcp, materialized+):+ from repowise.server.mcp_server import get_health++ detailed = await get_health(include=["performance"], only=["performance_opportunities"])+ summary = await get_health(+ include=["performance"],+ only=["performance_opportunities"],+ performance_view="summary",+ )+ assert (+ detailed["performance_opportunities"][0]["opportunity_id"]+ == summary["performance_opportunities"][0]["opportunity_id"]+ )+ assert "facets" not in summary["performance_opportunities"][0]+ assert "facets" in detailed["performance_opportunities"][0]+++async def test_one_id_returns_the_cause_its_plan_and_its_rank_rationale(+ setup_mcp, materialized+):+ from repowise.server.mcp_server import get_health++ lead = (await get_health())["performance_directive"]["opportunity_id"]+ result = await get_health(opportunity_id=lead)++ assert result["mode"] == "performance_opportunity"+ assert result["resolved"] is True+ assert result["opportunity_id"] == lead+ assert result["intervention_symbol"] == "src/shared.py::load"+ assert result["plan_status"] == "available"+ assert result["plan_reference"].startswith("plan_")+ assert result["confidence"] == "high"+ assert result["fix"]["safety"] == "proven"+ assert result["facets"]["leverage"] == "shared"+ assert result["why_ranked"]+ assert len(json.dumps(result)) <= 20_000++ # The plan reference resolves through the plan selector.+ plan = await get_health(plan_id=result["plan_reference"])+ assert plan["resolved"] is True+++async def test_evidence_pages_to_exhaustion_with_no_duplicate_or_missing_row(+ setup_mcp, materialized+):+ from repowise.server.mcp_server import get_health++ lead = (await get_health())["performance_directive"]["opportunity_id"]+ seen: list[str] = []+ cursor: int | None = 0+ while cursor is not None:+ page = await get_health(+ opportunity_id=lead, only=["performance_evidence"], cursor=cursor, limit=2+ )+ seen.extend(item["finding_id"] for item in page["evidence"])+ cursor = page.get("evidence_next_cursor")+ assert len(seen) == len(set(seen)) == 5+++async def test_every_evidence_reference_round_trips_through_the_finding_selector(+ setup_mcp, materialized+):+ """Evidence used to carry the storage row id, which a reindex replaces."""+ from repowise.server.mcp_server import get_health++ lead = (await get_health())["performance_directive"]["opportunity_id"]+ page = await get_health(opportunity_id=lead, only=["performance_evidence"], limit=50)+ for item in page["evidence"]:+ resolved = await get_health(finding_id=item["finding_id"])+ assert resolved["resolved"] is True+ assert resolved["finding"]["file_path"] == item["file_path"]+ assert resolved["finding"]["id"] == item["finding_id"]+++async def test_asking_for_no_rows_returns_no_rows(setup_mcp, materialized):+ """``limit=0`` is the documented way to ask for the totals and nothing else.++ Reading it as "unset" would hand back a page the caller declined, which is+ the same defect the ranked collections already fixed.+ """+ from repowise.server.mcp_server import get_health++ lead = (await get_health())["performance_directive"]["opportunity_id"]+ page = await get_health(+ opportunity_id=lead, only=["performance_evidence"], limit=0+ )+ assert page["evidence"] == []+ assert page["evidence_total"] == 5+ assert page["evidence_next_cursor"] == 0++ detail = await get_health(opportunity_id=lead, limit=0)+ assert detail["evidence"] == []+ assert detail["evidence_total"] == 5+++async def test_the_summary_costs_the_same_however_many_causes_there_are(+ setup_mcp, materialized, session+):+ """The facet aggregate reads every open cause; its query count must not."""+ from repowise.server.mcp_server import get_health++ with _Statements() as small:+ await get_health(include=["performance"], only=["performance_summary"])++ for index in range(40):+ row = _row(materialized, f"src/bulk_{index}.py", 500 + index)+ row.details_json = row.details_json.replace(+ "src/db.py::fetch", f"src/db.py::fetch_{index}"+ )+ session.add(row)+ await session.flush()+ await finalize_performance_opportunities(session, materialized)+ await session.commit()++ with _Statements() as large:+ result = await get_health(include=["performance"], only=["performance_summary"])+ assert result["performance_summary"]["total"] > 40+ assert large.n == small.n+ assert {entry["value"] for entry in result["performance_summary"]["facets"]["context"]}+++async def test_an_id_from_an_older_model_reports_stale_and_how_to_refresh(+ setup_mcp, materialized+):+ from repowise.server.mcp_server import get_health++ result = await get_health(opportunity_id="perf_0123456789abcdef0123")+ assert result["resolved"] is False+ assert result["model_state"]["state"] == "stale_model"+ assert result["model_state"]["refresh_required"] is True+ assert "repowise update" in result["detail"]++ unknown = await get_health(opportunity_id="not-an-id")+ assert unknown["model_state"]["state"] == "unrecognized"+++async def test_two_detail_selectors_conflict_explicitly(setup_mcp, materialized):+ """Preferring one silently answered confidently about the wrong question."""+ from repowise.server.mcp_server import get_health++ result = await get_health(finding_id="finding_x", opportunity_id="perf2_x")+ assert result["mode"] == "conflict"+ assert result["resolved"] is False+ assert result["selectors"] == ["finding_id", "opportunity_id"]+++async def test_the_lede_links_the_exact_plan_for_the_exact_lead(setup_mcp, materialized):+ """This used to match on a key the plan writer never wrote, so it was null."""+ from repowise.server.mcp_server import get_health++ result = await get_health(+ include=["performance", "refactoring"], only=["recommendation_lede"]+ )+ lede = result["recommendation_lede"]+ assert lede["performance_plan_id"] is not None+ assert lede["performance_plan_id"].startswith("plan_")+ plan = await get_health(plan_id=lede["performance_plan_id"])+ assert plan["resolved"] is True+++async def test_the_queue_costs_the_same_however_many_opportunities_there_are(+ setup_mcp, materialized, session+):+ """Query count is what this holds: wall clock on a laptop is not evidence."""+ from repowise.server.mcp_server import get_health++ with _Statements() as small:+ await get_health(include=["performance"], only=["performance_opportunities"], limit=2)++ for index in range(40):+ # A distinct sink per row, so these are forty causes rather than one.+ row = _row(materialized, f"src/bulk_{index}.py", 500 + index)+ row.details_json = row.details_json.replace(+ "src/db.py::fetch", f"src/db.py::fetch_{index}"+ )+ session.add(row)+ await session.flush()+ await finalize_performance_opportunities(session, materialized)+ await session.commit()++ with _Statements() as large:+ result = await get_health(+ include=["performance"], only=["performance_opportunities"], limit=2+ )+ assert result["performance_opportunities_total"] > 40+ assert large.n == small.n+ assert len(result["performance_opportunities"]) == 2+++async def test_rest_and_the_agent_surface_project_the_same_rows(+ setup_mcp, materialized, factory+):+ """Two adapters, one service. Order, totals, identity, and plan state agree."""+ from repowise.server.mcp_server import get_health+ from repowise.server.routers.code_health.performance_routes import (+ list_performance_opportunities,+ )++ agent = await get_health(+ include=["performance"], only=["performance_opportunities"], limit=6+ )+ async with factory() as session:+ rest = await list_performance_opportunities(+ materialized,+ context="all",+ boundary=None,+ confidence=None,+ actionability=None,+ view="detail",+ sort="rank",+ limit=6,+ offset=0,+ session=session,+ )++ assert rest["total"] == agent["performance_opportunities_total"]+ shared = (+ "opportunity_id",+ "rank_position",+ "actionability_state",+ "execution_context",+ "boundary_kind",+ "plan_status",+ "confidence",+ "observations_total",+ "affected_call_sites_total",+ )+ assert [{key: item[key] for key in shared} for item in rest["items"]] == [+ {key: item[key] for key in shared} for item in agent["performance_opportunities"]+ ]+ # Two address spaces for the same plan: the row id this surface's own+ # detail route resolves, and the reference the agent selector resolves.+ assert all(item["plan_id"] for item in rest["items"] if item["plan_status"] == "available")+ assert "plan_reference" not in rest["items"][0]+ assert all(+ item["plan_reference"]+ for item in agent["performance_opportunities"]+ if item["plan_status"] == "available"+ )diff --git a/tests/unit/server/test_performance_opportunities.py b/tests/unit/server/test_performance_opportunities.pyindex 17bb96513..8e2fabb0c 100644--- a/tests/unit/server/test_performance_opportunities.py+++ b/tests/unit/server/test_performance_opportunities.py@@ -1,18 +1,20 @@-"""Bounded causal performance product API and exact plan handoff."""+"""Bounded causal performance product API and exact plan handoff.++Every case seeds through the writer that both index paths use, because the+queue is materialized: findings alone are no longer a queue, and a test that+inserted findings and read the surface would be testing a state the product+never reaches.+"""from __future__ import annotationsfrom httpx import AsyncClient+from sqlalchemy import selectfrom repowise.core.analysis.health.models import HealthFindingData, Severity-from repowise.core.analysis.health.perf.opportunities import (- build_performance_opportunities,- link_performance_findings,-)-from repowise.core.analysis.health.refactoring.performance_fix import (- performance_fix_suggestions,-)+from repowise.core.analysis.health.perf.opportunities import link_performance_findingsfrom repowise.core.persistence import crud+from repowise.core.persistence.models import PerformanceOpportunityfrom tests.unit.server.conftest import create_test_repo@@ -36,9 +38,8 @@ def _finding(path: str, line: int, path_nodes: list[str], *, marker: str = "io_i)-async def _seed(app, client: AsyncClient) -> tuple[str, str]:- repo = await create_test_repo(client)- findings = [+def _findings() -> list:+ return [_finding("src/a.py", 10, ["src/a.py::run", "src/shared.py::load", "src/db.py::fetch"]),_finding("src/b.py", 20, ["src/b.py::run", "src/shared.py::load", "src/db.py::fetch"]),# A separate test-suite cause with no coherent shared intervention.@@ -49,49 +50,63 @@ async def _seed(app, client: AsyncClient) -> tuple[str, str]:marker="serial_await_in_loop",),]+++async def _materialize(app, repo_id: str, findings: list) -> None:link_performance_findings(findings)- opportunities = build_performance_opportunities(findings)- production = next(item for item in opportunities if item.execution_context == "production")- plans = performance_fix_suggestions([production])async with app.state.session_factory() as session:- await crud.save_health_findings(session, repo["id"], findings)- await crud.save_refactoring_suggestions(session, repo["id"], plans)+ await crud.save_health_findings(session, repo_id, findings)+ await crud.finalize_performance_opportunities(+ session, repo_id, analyzed_commit="a" * 40+ )await session.commit()- return repo["id"], production.opportunity_id-async def test_opportunities_are_grouped_bounded_and_split_by_context(- client: AsyncClient, app-) -> None:- repo_id, opportunity_id = await _seed(app, client)- production = (- await client.get(- f"/api/repos/{repo_id}/health/performance-opportunities", params={"limit": 1}+async def _seed(app, client: AsyncClient, findings: list | None = None) -> tuple[str, str]:+ repo = await create_test_repo(client)+ await _materialize(app, repo["id"], _findings() if findings is None else findings)+ async with app.state.session_factory() as session:+ rows = (+ (+ await session.execute(+ select(PerformanceOpportunity).where(+ PerformanceOpportunity.repository_id == repo["id"],+ PerformanceOpportunity.execution_context == "production",+ )+ )+ )+ .scalars()+ .all())- ).json()+ return repo["id"], rows[0].opportunity_id if rows else ""- assert len(production["items"]) == 1- assert production["items"][0]["opportunity_id"] == opportunity_id- assert production["items"][0]["affected_call_sites_total"] == 2- assert production["items"][0]["confidence"] == "medium"- assert production["items"][0]["plan_status"] == "available"- assert production["items"][0]["plan_id"]- assert production["summary"] == {- "total": 2,- "production_total": 1,- "tooling_total": 0,- "test_total": 1,- "unknown_total": 0,- "with_plan_total": 1,- "without_plan_total": 1,- }- test_page = (+async def _page(client: AsyncClient, repo_id: str, **params) -> dict:+ return (await client.get(- f"/api/repos/{repo_id}/health/performance-opportunities",- params={"context": "test"},+ f"/api/repos/{repo_id}/health/performance-opportunities", params=params)).json()+++async def test_opportunities_are_grouped_bounded_and_split_by_context(+ client: AsyncClient, app+) -> None:+ repo_id, opportunity_id = await _seed(app, client)+ page = await _page(client, repo_id, context="production", limit=1)++ assert len(page["items"]) == 1+ assert page["items"][0]["opportunity_id"] == opportunity_id+ assert page["items"][0]["affected_call_sites_total"] == 2+ assert page["items"][0]["confidence"] == "medium"+ assert page["items"][0]["plan_status"] == "available"+ assert page["items"][0]["plan_id"]+ assert page["summary"]["total"] == 2+ assert page["summary"]["context"] == {"production": 1, "test": 1}+ assert page["summary"]["with_plan_total"] == 1+ assert page["summary"]["status"] == "current"++ test_page = await _page(client, repo_id, context="test")assert test_page["total"] == 1assert test_page["items"][0]["plan_id"] is Noneassert test_page["items"][0]["plan_status"] == "no_safe_plan"@@ -115,13 +130,15 @@ async def test_raw_evidence_is_paged_and_plan_matching_never_falls_back().json()assert first["total"] == 2assert len(first["items"]) == len(second["items"]) == 1- assert first["items"][0]["id"] != second["items"][0]["id"]+ assert first["items"][0]["finding_id"] != second["items"][0]["finding_id"]+ # A public reference, never the storage row id a reindex replaces.+ assert first["items"][0]["finding_id"].startswith("finding_")async with app.state.session_factory() as session:rows = await crud.get_refactoring_suggestions(session, repo_id)- rows[0].plan_json = '{"opportunity_id":"unrelated"}'+ rows[0].opportunity_id = "unrelated"await session.commit()- page = (await client.get(f"/api/repos/{repo_id}/health/performance-opportunities")).json()+ page = await _page(client, repo_id, context="production")assert page["items"][0]["plan_id"] is Noneassert page["items"][0]["plan_status"] == "not_persisted"@@ -132,22 +149,165 @@ async def test_an_unclassifiable_file_is_counted_and_stays_visible(app, client:Reporting an unclassifiable file as production was the thing to fix. Losingit from every view instead would be the same mistake pointing the other way."""- repo = await create_test_repo(client)- findings = [- _finding(- "docs/snippets/walk.py",- 10,- ["docs/snippets/walk.py::demo", "src/shared.py::load", "src/db.py::fetch"],+ repo_id, _ = await _seed(+ app,+ client,+ [+ _finding(+ "docs/snippets/walk.py",+ 10,+ ["docs/snippets/walk.py::demo", "src/shared.py::load", "src/db.py::fetch"],+ )+ ],+ )+ body = await _page(client, repo_id, context="all")+ assert body["summary"]["context"] == {"unknown": 1}+ assert [item["execution_context"] for item in body["items"]] == ["unknown"]+ assert (await _page(client, repo_id, context="unknown"))["total"] == 1+++async def test_the_retired_context_spelling_still_answers_but_is_never_echoed(+ app, client: AsyncClient+) -> None:+ """An older client asked for Production+Tooling under one name.++ Answering it keeps that client working. Echoing the name back would make a+ retired spelling look like the current product concept.+ """+ repo_id, _ = await _seed(app, client)+ body = await _page(client, repo_id, context="production_tooling")+ assert body["total"] == 1+ assert [item["execution_context"] for item in body["items"]] == ["production"]+ assert "production_tooling" not in body["summary"]["context"]+++async def test_an_unrecognized_filter_value_is_reported_not_read_as_no_data(+ app, client: AsyncClient+) -> None:+ """Silently emptying the queue would look like a clean repository."""+ repo_id, _ = await _seed(app, client)+ body = await _page(client, repo_id, context="staging", boundary="pigeon")+ assert body["total"] == 2+ assert body["ignored_arguments"] == {+ "performance_context": "staging",+ "performance_boundary": "pigeon",+ }+++async def test_facets_keep_the_alternatives_a_selected_filter_would_erase(+ app, client: AsyncClient+) -> None:+ """A facet counted under its own filter reports every other value as zero."""+ repo_id, _ = await _seed(app, client)+ facets = (await _page(client, repo_id, context="test"))["facets"]+ assert {entry["value"] for entry in facets["context"]} == {"production", "test"}+ assert {entry["value"]: entry["total"] for entry in facets["context"]}["production"] == 1+ # A filter on another dimension does narrow this one.+ assert (await _page(client, repo_id, boundary="network"))["facets"]["context"] == []+++async def test_an_id_from_an_older_model_reports_stale_rather_than_no_plan(+ app, client: AsyncClient+) -> None:+ """A first-model id used to fail to match, which read as nothing to do."""+ repo_id, _ = await _seed(app, client)+ body = (+ await client.get(+ f"/api/repos/{repo_id}/health/performance-opportunities/perf_0123456789abcdef0123")- ]- link_performance_findings(findings)+ ).json()+ assert body["resolved"] is False+ assert body["model_state"]["state"] == "stale_model"+ assert body["model_state"]["refresh_required"] is True+ assert "repowise update" in body["detail"]+++async def test_detail_carries_the_facets_and_evidence_for_one_cause(+ app, client: AsyncClient+) -> None:+ repo_id, opportunity_id = await _seed(app, client)+ body = (+ await client.get(+ f"/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}",+ params={"evidence_limit": 1},+ )+ ).json()+ assert body["resolved"] is True+ assert body["lifecycle_status"] == "open"+ assert body["analyzed_commit"] == "a" * 40+ assert body["model_state"]["state"] == "current"+ assert set(body["facets"]) == {+ "actionability_confidence",+ "exposure",+ "amplification",+ "leverage",+ "change_risk",+ }+ assert body["evidence_total"] == 2+ assert body["evidence_emitted"] == 1+ assert body["evidence_next_cursor"] == 1+ assert body["plan_status"] == "available"+++async def test_a_cause_that_stops_being_observed_is_resolved_not_deleted(+ app, client: AsyncClient+) -> None:+ """A held id has to keep answering after the code was fixed."""+ repo_id, opportunity_id = await _seed(app, client)+ await _materialize(app, repo_id, [_findings()[2]])++ page = await _page(client, repo_id, context="all")+ assert [item["opportunity_id"] for item in page["items"]] != [opportunity_id]+ detail = (+ await client.get(+ f"/api/repos/{repo_id}/health/performance-opportunities/{opportunity_id}"+ )+ ).json()+ assert detail["resolved"] is True+ assert detail["lifecycle_status"] == "resolved"+++async def test_an_alternative_order_is_applied_before_the_page_not_after(+ app, client: AsyncClient+) -> None:+ """Sorting the fetched page would order twenty rows right and the repo wrong."""+ repo_id, opportunity_id = await _seed(app, client)+ by_leverage = await _page(client, repo_id, context="all", sort="leverage", limit=1)+ assert by_leverage["total"] == 2+ # The production cause carries two call sites; the test one carries a+ # single site, so leverage puts production first whatever its rank is.+ assert by_leverage["items"][0]["opportunity_id"] == opportunity_id+ assert by_leverage["items"][0]["affected_call_sites_total"] == 2+++async def test_a_page_costs_the_page_not_the_repository(app, client: AsyncClient) -> None:+ """Two hundred unrelated findings must not reach the performance queue."""+ repo_id, _ = await _seed(app, client)async with app.state.session_factory() as session:- await crud.save_health_findings(session, repo["id"], findings)+ await crud.save_health_findings(+ session,+ repo_id,+ [+ HealthFindingData(+ biomarker_type="long_function",+ severity=Severity.MEDIUM,+ file_path=f"src/noise_{index}.py",+ function_name="run",+ line_start=index,+ line_end=index,+ details={},+ health_impact=1.0,+ reason="Unrelated defect finding.",+ dimension="defect",+ )+ for index in range(200)+ ]+ + _findings(),+ )+ await crud.finalize_performance_opportunities(session, repo_id)await session.commit()- response = await client.get(- f"/api/repos/{repo['id']}/health/performance-opportunities", params={"context": "all"}- )- body = response.json()- assert body["summary"]["unknown_total"] == 1- assert [item["execution_context"] for item in body["items"]] == ["unknown"]+ page = await _page(client, repo_id, context="all", limit=1)+ assert page["total"] == 2+ assert len(page["items"]) == 1+ assert page["summary"]["total"] == 2