Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

test(pipeline): pin persistence step order and decision chain (#3971)

Raghav Chamadiyab1e41a8e483c
diff --git a/tests/unit/_persist_step_recorders.py b/tests/unit/_persist_step_recorders.py
new file mode 100644
index 000000000..1380bd949
--- /dev/null
+++ b/tests/unit/_persist_step_recorders.py
@@ -0,0 +1,189 @@
+"""Recorders for the steps the update persisters call, shared by the step-order tests.
+
+Each step is replaced, in the module namespace it is looked up in at call
+time, by a stand-in that appends its label to one shared call log and can be
+told to raise. The persisters import their steps inside the function body, so
+patching the defining module is enough.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import networkx as nx
+
+FAILURE = "boom"
+
+
+class StepRecorder:
+ def __init__(self, monkeypatch: Any, *, fail: frozenset[str] = frozenset()) -> None:
+ self.monkeypatch = monkeypatch
+ self.fail = fail
+ self.calls: list[tuple[str, tuple, dict]] = []
+
+ @property
+ def order(self) -> list[str]:
+ return [label for label, _args, _kwargs in self.calls]
+
+ def args_of(self, label: str) -> list[tuple[tuple, dict]]:
+ return [(args, kwargs) for name, args, kwargs in self.calls if name == label]
+
+ def _record(self, label: str, args: tuple, kwargs: dict, ret: Any) -> Any:
+ self.calls.append((label, args, kwargs))
+ if label in self.fail:
+ raise RuntimeError(FAILURE)
+ # A fresh copy: callers extend returned lists in place.
+ return list(ret) if isinstance(ret, list) else ret
+
+ def patch(self, module: Any, attr: str, *, ret: Any = None, sync: bool = False) -> None:
+ if sync:
+
+ def stand_in(*args, **kwargs):
+ return self._record(attr, args, kwargs, ret)
+
+ else:
+
+ async def stand_in(*args, **kwargs):
+ return self._record(attr, args, kwargs, ret)
+
+ self.monkeypatch.setattr(module, attr, stand_in)
+
+ def fts_class(self) -> type:
+ rec = self
+
+ class _FTS:
+ def __init__(self, _engine: Any) -> None:
+ pass
+
+ async def ensure_index(self) -> None:
+ rec._record("fts.ensure_index", (), {}, None)
+
+ async def index_pages(self, pages: Any) -> None:
+ rec._record("fts.index_pages", (list(pages),), {}, None)
+
+ async def delete_many(self, page_ids: Any) -> None:
+ rec._record("fts.delete_many", (list(page_ids),), {}, None)
+
+ return _FTS
+
+ def vector_store(self) -> Any:
+ rec = self
+
+ class _Vectors:
+ async def delete_many(self, ids: Any) -> None:
+ rec._record("vectors.delete_many", (list(ids),), {}, None)
+
+ return _Vectors()
+
+
+# Returned ids are what make the post-transaction cleanup run.
+TOMBSTONED = "file_page:src/gone.py"
+SWEPT = "onboarding:retired"
+REFUSAL = "Refused to prune src/kept.py"
+
+
+def install_shared_steps(rec: StepRecorder, *, prune_ret: tuple[int, list[str]] = (1, [])) -> None:
+ """Steps both persisters call: the incremental list and its cleanup tail."""
+ import repowise.core.generation.related_pages as related_pages
+ import repowise.core.persistence as persistence
+ import repowise.core.persistence.search as search
+ import repowise.core.pipeline.commit_health as commit_health
+ import repowise.core.pipeline.incremental as incremental
+ import repowise.core.pipeline.page_tree_sync as page_tree_sync
+ import repowise.core.pipeline.persist as persist
+ from repowise.core.persistence import crud
+
+ rec.patch(persist, "reconcile_full_index_scope", ret=[])
+ rec.patch(persist, "tombstone_pages_outside_generation", ret=[])
+ rec.patch(persist, "sweep_retired_pages", ret=[SWEPT])
+ rec.patch(persist, "sweep_absent_cycle_pages", ret=[])
+ rec.patch(persist, "sweep_absent_symbol_spotlights", ret=[])
+ rec.patch(persist, "tombstone_candidates", ret=[], sync=True)
+ rec.patch(persist, "mark_tombstone_pages", ret=[TOMBSTONED])
+ rec.patch(page_tree_sync, "rebuild_page_tree")
+ rec.patch(persist, "persist_git_refresh")
+ rec.patch(incremental, "persist_incremental_commits")
+ rec.patch(crud, "replace_dead_code_findings")
+ rec.patch(crud, "replace_doc_drift_guarded")
+ rec.patch(persist, "persist_graph_nodes")
+ rec.patch(incremental, "persist_partial_health")
+ rec.patch(persist, "persist_incremental_symbols")
+ rec.patch(persist, "persist_incremental_security_findings")
+ rec.patch(persist, "persist_incremental_edges")
+ rec.patch(related_pages, "file_import_edges", ret={}, sync=True)
+ rec.patch(crud, "backfill_related_pages", ret=0)
+ rec.patch(persist, "persist_kg")
+ rec.patch(incremental, "refresh_external_systems")
+ rec.patch(crud, "purge_proposed_decisions_by_source")
+ rec.patch(persist, "prune_deleted_file_rows", ret=prune_ret)
+ rec.patch(persist, "_analyzed_commit", ret="abc123")
+ rec.patch(crud, "finalize_performance_opportunities")
+ rec.patch(crud, "finalize_refactoring_opportunities")
+ rec.patch(commit_health, "refresh_commit_health_after_update")
+ # Core reads it from the search module, the CLI from the package.
+ fts = rec.fts_class()
+ rec.monkeypatch.setattr(search, "FullTextSearch", fts)
+ rec.monkeypatch.setattr(persistence, "FullTextSearch", fts)
+
+
+def install_decision_chain(rec: StepRecorder) -> None:
+ """The decision repairs shared by ``persist_analysis`` and the CLI full update."""
+ import repowise.core.analysis.decision_evolution as decision_evolution
+ import repowise.core.analysis.decisions.head_artifacts as head_artifacts
+ import repowise.core.analysis.decisions.reverts as reverts
+ import repowise.core.persistence.decision_id_migration as decision_id_migration
+ import repowise.core.persistence.decision_migration as decision_migration
+ import repowise.core.pipeline.persist as persist
+ from repowise.core.persistence import crud
+
+ rec.patch(crud, "unretire_auto_superseded")
+ rec.patch(crud, "purge_proposed_decisions_by_source")
+ rec.patch(crud, "reconcile_source_ranks")
+ rec.patch(crud, "reconcile_decision_confidence")
+ rec.patch(decision_id_migration, "apply_id_migration")
+ for name in (
+ "apply_migration",
+ "prune_unindexed_scope_files",
+ "backfill_scope_basis",
+ "backfill_session_scope_basis",
+ "backfill_decision_node_links",
+ ):
+ rec.patch(decision_migration, name)
+ rec.patch(crud, "bulk_upsert_decisions", ret=["decision-1"])
+ rec.patch(
+ decision_evolution,
+ "detect_supersessions_and_conflicts",
+ ret={"superseded": 0, "conflicts": 0},
+ )
+ rec.patch(crud, "recompute_decision_staleness", ret=0)
+ rec.patch(reverts, "apply_revert_supersession")
+ rec.patch(head_artifacts, "apply_head_artifact_check")
+ rec.patch(persist, "refresh_governance_findings")
+
+
+def graph_builder() -> Any:
+ graph = nx.DiGraph()
+ graph.add_node("src/a.py", node_type="file")
+ return SimpleNamespace(
+ graph=lambda: graph,
+ pagerank=lambda: {"src/a.py": 1.0},
+ traversed_file_paths={"src/a.py"},
+ )
+
+
+def parsed_files() -> list[Any]:
+ return [SimpleNamespace(file_info=SimpleNamespace(path="src/a.py"))]
+
+
+def file_diffs() -> list[Any]:
+ from repowise.core.ingestion.change_detector import FileDiff
+
+ return [FileDiff("src/a.py", "modified", None, None, None, None)]
+
+
+def dead_code_report() -> Any:
+ return SimpleNamespace(findings=[], authoritative_paths={"src/a.py"})
+
+
+GIT_META = {"src/a.py": {"file_path": "src/a.py"}}
diff --git a/tests/unit/cli/test_full_update_persist_step_order.py b/tests/unit/cli/test_full_update_persist_step_order.py
new file mode 100644
index 000000000..84ed6e4c8
--- /dev/null
+++ b/tests/unit/cli/test_full_update_persist_step_order.py
@@ -0,0 +1,387 @@
+"""The docs-mode update persister runs its steps in one pinned order.
+
+``_persist_full_update_async`` mirrors the index-only persister and adds the
+docs-only steps (pages, stale decay, decisions, generation job, FTS indexing).
+Every step is a recorder here, so these tests prove a refactor kept the
+sequence and the degraded entries, and that the steps both persisters share
+receive the same inputs from the same update.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from repowise.cli.commands.update_cmd.persistence import _persist_full_update_async
+from repowise.core.pipeline.incremental import persist_incremental_index
+from tests.unit._persist_step_recorders import (
+ FAILURE,
+ GIT_META,
+ REFUSAL,
+ SWEPT,
+ TOMBSTONED,
+ StepRecorder,
+ dead_code_report,
+ file_diffs,
+ graph_builder,
+ install_decision_chain,
+ install_shared_steps,
+ parsed_files,
+)
+from tests.unit.cli.test_update_persist_reliability import _page
+
+
+@dataclass
+class _Marker:
+ title: str = "Use durable retries"
+
+
+HAPPY_ORDER = [
+ "reconcile_full_index_scope",
+ "upsert_pages_from_generated",
+ "tombstone_pages_outside_generation",
+ "sweep_retired_pages",
+ "sweep_absent_cycle_pages",
+ "sweep_absent_symbol_spotlights",
+ # Swept embeddings leave before the SQL session commits.
+ "vectors.delete_many",
+ "tombstone_candidates",
+ "mark_tombstone_pages",
+ "file_import_edges",
+ "backfill_related_pages",
+ "mark_page_ids_stale",
+ "rebuild_page_tree",
+ "persist_kg",
+ "persist_git_refresh",
+ "persist_incremental_commits",
+ "unretire_auto_superseded",
+ "purge_proposed_decisions_by_source",
+ "purge_proposed_decisions_by_source",
+ "purge_proposed_decisions_by_source",
+ "reconcile_source_ranks",
+ "reconcile_decision_confidence",
+ "apply_id_migration",
+ "apply_migration",
+ "prune_unindexed_scope_files",
+ "backfill_scope_basis",
+ "backfill_session_scope_basis",
+ "backfill_decision_node_links",
+ "bulk_upsert_decisions",
+ "detect_supersessions_and_conflicts",
+ "recompute_decision_staleness",
+ "apply_revert_supersession",
+ "apply_head_artifact_check",
+ "refresh_governance_findings",
+ "replace_doc_drift_guarded",
+ "persist_graph_nodes",
+ "persist_partial_health",
+ "replace_dead_code_findings",
+ "persist_incremental_symbols",
+ "persist_incremental_security_findings",
+ "persist_incremental_edges",
+ "refresh_external_systems",
+ "prune_deleted_file_rows",
+ "_analyzed_commit",
+ "finalize_performance_opportunities",
+ "finalize_refactoring_opportunities",
+ "upsert_generation_job",
+ # After the session closes.
+ "fts.ensure_index",
+ "fts.index_pages",
+ "fts.delete_many",
+ "vectors.delete_many",
+ "refresh_commit_health_after_update",
+]
+
+
+def _install(rec: StepRecorder, *, prune_ret: tuple[int, list[str]] = (1, [])) -> None:
+ import repowise.core.generation as generation
+ import repowise.core.generation.cascade as cascade
+ import repowise.core.generation.scope as scope
+ import repowise.core.persistence as persistence
+ import repowise.core.pipeline.persist as persist
+ import repowise.core.pipeline.scoped_generation as scoped_generation
+ import repowise.core.repo_config as repo_config
+ from repowise.core.persistence import crud
+
+ install_shared_steps(rec, prune_ret=prune_ret)
+ install_decision_chain(rec)
+ rec.patch(persistence, "upsert_pages_from_generated")
+ rec.patch(persist, "mark_page_ids_stale")
+ rec.patch(crud, "upsert_generation_job", ret=SimpleNamespace())
+
+ # Inputs of the stale decay, not steps: stubbed without recording.
+ async def _no_rows(_session, _repo_id):
+ return []
+
+ mp = rec.monkeypatch
+ mp.setattr(repo_config, "load_repo_config", lambda _path: {})
+ mp.setattr(generation.GenerationConfig, "from_repo_config", lambda _cfg: object())
+ mp.setattr(scoped_generation, "_load_page_rows", _no_rows)
+ mp.setattr(scoped_generation, "load_kg_context", lambda _path: object())
+ mp.setattr(scope, "load_page_records", lambda _rows: [])
+ mp.setattr(scope, "build_dependencies", lambda **_kwargs: object())
+ mp.setattr(cascade, "expand_cascade", lambda *_a: SimpleNamespace(stale_ids=set()))
+
+
+def repo(tmp_path: Path) -> Path:
+ (tmp_path / ".repowise").mkdir()
+ return tmp_path
+
+
+class _Inputs:
+ """One update's worth of inputs, shared so both persisters see the same objects."""
+
+ def __init__(self) -> None:
+ self.graph_builder = graph_builder()
+ self.parsed_files = parsed_files()
+ self.file_diffs = file_diffs()
+ self.dead_code_report = dead_code_report()
+ self.health_report = object()
+ self.doc_drift_report = object()
+ self.knowledge_graph_result = object()
+ self.pages = [_page("file_page:src/a.py")]
+
+
+async def _persist_full(repo: Path, rec: StepRecorder, inputs: _Inputs, degraded: list[str]) -> int:
+ return await _persist_full_update_async(
+ repo_path=repo,
+ repo_name=repo.name,
+ generated_pages=inputs.pages,
+ file_diffs=inputs.file_diffs,
+ git_meta_map=dict(GIT_META),
+ new_decision_markers=[_Marker()],
+ decision_vector_store=rec.vector_store(),
+ provider=None,
+ partial_health_report=inputs.health_report,
+ dead_code_report=inputs.dead_code_report,
+ graph_builder=inputs.graph_builder,
+ knowledge_graph_result=inputs.knowledge_graph_result,
+ degraded=degraded,
+ doc_drift_report=inputs.doc_drift_report,
+ decay_paths=["src/a.py"],
+ parsed_files=inputs.parsed_files,
+ reconcile_full_scope=True,
+ reconcile_full_generation=True,
+ )
+
+
+async def test_every_step_runs_in_the_pinned_order(repo, monkeypatch):
+ rec = StepRecorder(monkeypatch)
+ _install(rec)
+ degraded: list[str] = []
+
+ total = await _persist_full(repo, rec, _Inputs(), degraded)
+
+ assert rec.order == HAPPY_ORDER
+ assert degraded == []
+ # The page upsert is a recorder, so the store holds no page to count.
+ assert total == 0
+ assert [a[2] for a, _k in rec.args_of("purge_proposed_decisions_by_source")] == [
+ "code_comment",
+ "readme_mining",
+ "changelog",
+ ]
+ assert rec.args_of("vectors.delete_many") == [(([SWEPT],), {}), (([TOMBSTONED],), {})]
+ assert rec.args_of("fts.delete_many") == [((sorted([SWEPT, TOMBSTONED]),), {})]
+
+
+async def test_every_failing_step_degrades_in_order(repo, monkeypatch):
+ from repowise.core.pipeline.cleanup_debt import record_cleanup_debt
+
+ # Seeded debt is what reaches the vector tail once tombstoning has failed.
+ record_cleanup_debt(repo, "vectors", {"file_page:src/old.py"})
+ survivors = {
+ # Pages have no net: a failure here fails the update.
+ "upsert_pages_from_generated",
+ "tombstone_candidates",
+ "file_import_edges",
+ "prune_deleted_file_rows",
+ "_analyzed_commit",
+ "refresh_commit_health_after_update",
+ }
+ rec = StepRecorder(
+ monkeypatch, fail=frozenset(label for label in HAPPY_ORDER if label not in survivors)
+ )
+ _install(rec, prune_ret=(1, [REFUSAL]))
+ degraded: list[str] = []
+
+ await _persist_full(repo, rec, _Inputs(), degraded)
+
+ assert rec.order == [
+ "reconcile_full_index_scope",
+ "upsert_pages_from_generated",
+ "tombstone_pages_outside_generation",
+ "sweep_retired_pages",
+ "tombstone_candidates",
+ "mark_tombstone_pages",
+ "file_import_edges",
+ "backfill_related_pages",
+ "mark_page_ids_stale",
+ "rebuild_page_tree",
+ "persist_kg",
+ "persist_git_refresh",
+ "persist_incremental_commits",
+ # One try around the whole chain: the first repair ends it.
+ "unretire_auto_superseded",
+ "apply_revert_supersession",
+ "apply_head_artifact_check",
+ "refresh_governance_findings",
+ "replace_doc_drift_guarded",
+ "persist_graph_nodes",
+ "persist_partial_health",
+ "replace_dead_code_findings",
+ "persist_incremental_symbols",
+ "persist_incremental_security_findings",
+ "persist_incremental_edges",
+ "refresh_external_systems",
+ "prune_deleted_file_rows",
+ "_analyzed_commit",
+ "finalize_performance_opportunities",
+ "upsert_generation_job",
+ "fts.ensure_index",
+ "vectors.delete_many",
+ "refresh_commit_health_after_update",
+ ]
+ assert degraded == [
+ *(
+ f"{step}: {FAILURE}"
+ for step in (
+ "Config scope reconciliation",
+ "Generation scope reconciliation",
+ "Retired page sweep",
+ "Tombstone marking",
+ "Related-pages backfill",
+ "Stale-page decay",
+ "Page tree rebuild",
+ "Knowledge-graph persist",
+ "Git persist",
+ "Commit capture",
+ "Decision persist",
+ "Revert supersession",
+ "Decision HEAD artifact check",
+ "Governance findings",
+ "Doc-drift persist",
+ "Graph nodes persist",
+ "Health persist",
+ "Dead-code persist",
+ "Symbol persist",
+ "Security persist",
+ "Graph edges persist",
+ "External systems refresh",
+ )
+ ),
+ REFUSAL,
+ f"Queue rebuild after prune: {FAILURE}",
+ f"Generation job record: {FAILURE}",
+ f"Full-text search indexing: {FAILURE}",
+ f"Deferred vector cleanup: {FAILURE}",
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Parity: the shared middle steps get the same inputs from both persisters
+# ---------------------------------------------------------------------------
+
+# Steps both persisters call. Each pair of lists below must match exactly.
+SHARED_STEPS = [
+ "reconcile_full_index_scope",
+ "tombstone_pages_outside_generation",
+ "sweep_retired_pages",
+ "sweep_absent_cycle_pages",
+ "sweep_absent_symbol_spotlights",
+ "tombstone_candidates",
+ "mark_tombstone_pages",
+ "rebuild_page_tree",
+ "persist_git_refresh",
+ "persist_incremental_commits",
+ "replace_doc_drift_guarded",
+ "persist_graph_nodes",
+ "persist_partial_health",
+ "persist_incremental_symbols",
+ "persist_incremental_security_findings",
+ "persist_incremental_edges",
+ "file_import_edges",
+ "persist_kg",
+ "refresh_external_systems",
+ "prune_deleted_file_rows",
+ "finalize_performance_opportunities",
+ "finalize_refactoring_opportunities",
+ "refresh_commit_health_after_update",
+]
+
+
+def _normalize(value: Any) -> Any:
+ # Each run opens its own session; the repo row (keyed by path) is shared.
+ name = type(value).__name__
+ if name == "AsyncSession":
+ return "<session>"
+ if name == "async_sessionmaker":
+ return "<session factory>"
+ if isinstance(value, (list, tuple)):
+ return type(value)(_normalize(v) for v in value)
+ return value
+
+
+def _calls(rec: StepRecorder, label: str) -> list[tuple[Any, dict]]:
+ # ``timings`` and ``log`` are observability, not data.
+ return [
+ (
+ _normalize(args),
+ {k: _normalize(v) for k, v in kwargs.items() if k not in {"timings", "log"}},
+ )
+ for args, kwargs in rec.args_of(label)
+ ]
+
+
+async def test_shared_steps_receive_the_same_inputs_from_both_persisters(repo, monkeypatch):
+ inputs = _Inputs()
+
+ core = StepRecorder(monkeypatch)
+ _install(core)
+ await persist_incremental_index(
+ repo,
+ inputs.graph_builder,
+ dict(GIT_META),
+ inputs.dead_code_report,
+ inputs.health_report,
+ [fd.path for fd in inputs.file_diffs],
+ doc_drift_report=inputs.doc_drift_report,
+ file_diffs=inputs.file_diffs,
+ knowledge_graph_result=inputs.knowledge_graph_result,
+ parsed_files=inputs.parsed_files,
+ reconcile_full_scope=True,
+ full_generation_page_ids={p.page_id for p in inputs.pages},
+ vector_store=core.vector_store(),
+ log=lambda _msg: None,
+ degraded=[],
+ failed_steps=[],
+ )
+
+ cli = StepRecorder(monkeypatch)
+ _install(cli)
+ await _persist_full(repo, cli, inputs, [])
+
+ for label in SHARED_STEPS:
+ assert _calls(core, label), label
+ assert _calls(core, label) == _calls(cli, label), label
+
+ # Known divergences, pinned so a unification shows up as a test change.
+ # Dead code: core hands over the finding objects, the CLI their dicts.
+ ((core_args, core_kwargs),) = _calls(core, "replace_dead_code_findings")
+ ((cli_args, cli_kwargs),) = _calls(cli, "replace_dead_code_findings")
+ assert core_args[:2] == cli_args[:2] and core_kwargs == cli_kwargs
+ # Related pages: the CLI skips the pages this run just generated.
+ ((_a, core_rel),) = _calls(core, "backfill_related_pages")
+ ((_a, cli_rel),) = _calls(cli, "backfill_related_pages")
+ assert cli_rel.pop("skip_page_ids") == {"file_page:src/a.py"}
+ assert core_rel == cli_rel
+ # Decisions: core drains only code_comment, the CLI every retired source.
+ assert [a[2] for a, _k in _calls(core, "purge_proposed_decisions_by_source")] == [
+ "code_comment"
+ ]
diff --git a/tests/unit/pipeline/test_incremental_persist_step_order.py b/tests/unit/pipeline/test_incremental_persist_step_order.py
new file mode 100644
index 000000000..6a15b690a
--- /dev/null
+++ b/tests/unit/pipeline/test_incremental_persist_step_order.py
@@ -0,0 +1,219 @@
+"""``persist_incremental_index`` runs its steps in one pinned order.
+
+Characterization, not a spec: every step is replaced by a recorder, so these
+tests prove a refactor of the persister kept the sequence, the degraded
+entries and the repair markers exactly as they were.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.core.pipeline.incremental import persist_incremental_index
+from tests.unit._persist_step_recorders import (
+ FAILURE,
+ GIT_META,
+ REFUSAL,
+ SWEPT,
+ TOMBSTONED,
+ StepRecorder,
+ dead_code_report,
+ file_diffs,
+ graph_builder,
+ install_shared_steps,
+ parsed_files,
+)
+
+HAPPY_ORDER = [
+ "reconcile_full_index_scope",
+ "tombstone_pages_outside_generation",
+ "sweep_retired_pages",
+ "sweep_absent_cycle_pages",
+ "sweep_absent_symbol_spotlights",
+ "tombstone_candidates",
+ "mark_tombstone_pages",
+ "rebuild_page_tree",
+ "persist_git_refresh",
+ "persist_incremental_commits",
+ "replace_dead_code_findings",
+ "replace_doc_drift_guarded",
+ "persist_graph_nodes",
+ "persist_partial_health",
+ "persist_incremental_symbols",
+ "persist_incremental_security_findings",
+ "persist_incremental_edges",
+ "file_import_edges",
+ "backfill_related_pages",
+ "persist_kg",
+ "refresh_external_systems",
+ "purge_proposed_decisions_by_source",
+ "prune_deleted_file_rows",
+ "_analyzed_commit",
+ "finalize_performance_opportunities",
+ "finalize_refactoring_opportunities",
+ # After the session closes.
+ "refresh_commit_health_after_update",
+ "fts.ensure_index",
+ "fts.delete_many",
+ "vectors.delete_many",
+]
+
+
+def repo(tmp_path: Path) -> Path:
+ (tmp_path / ".repowise").mkdir()
+ return tmp_path
+
+
+async def _persist(repo: Path, rec: StepRecorder, **overrides) -> tuple[list[str], list[str]]:
+ degraded: list[str] = []
+ failed_steps: list[str] = []
+ kwargs = {
+ "reconcile_full_scope": True,
+ "full_generation_page_ids": {"file_page:src/a.py"},
+ "file_diffs": file_diffs(),
+ "doc_drift_report": object(),
+ "knowledge_graph_result": object(),
+ "parsed_files": parsed_files(),
+ "vector_store": rec.vector_store(),
+ "log": lambda _msg: None,
+ "degraded": degraded,
+ "failed_steps": failed_steps,
+ }
+ kwargs.update(overrides)
+ await persist_incremental_index(
+ repo,
+ graph_builder(),
+ dict(GIT_META),
+ dead_code_report(),
+ object(),
+ ["src/a.py"],
+ **kwargs,
+ )
+ return degraded, failed_steps
+
+
+async def test_every_step_runs_in_the_pinned_order(repo, monkeypatch):
+ rec = StepRecorder(monkeypatch)
+ install_shared_steps(rec)
+
+ degraded, failed_steps = await _persist(repo, rec)
+
+ assert rec.order == HAPPY_ORDER
+ assert degraded == []
+ assert failed_steps == []
+ # The incremental path only drains the retired code_comment source.
+ assert [a[2] for a, _k in rec.args_of("purge_proposed_decisions_by_source")] == ["code_comment"]
+ # Tombstones and swept pages leave FTS; only tombstones leave the vectors.
+ assert rec.args_of("fts.delete_many") == [((sorted([SWEPT, TOMBSTONED]),), {})]
+ assert rec.args_of("vectors.delete_many") == [(([TOMBSTONED],), {})]
+ ((_args, git_kwargs),) = rec.args_of("persist_git_refresh")
+ assert git_kwargs == {"keep_commit_health": True}
+
+
+async def test_full_history_walk_skips_commit_capture_and_drains_archaeology(repo, monkeypatch):
+ rec = StepRecorder(monkeypatch)
+ install_shared_steps(rec)
+
+ await _persist(repo, rec, full_git_summary=object(), history_window_changed=True)
+
+ assert "persist_incremental_commits" not in rec.order
+ ((_args, git_kwargs),) = rec.args_of("persist_git_refresh")
+ assert git_kwargs == {"keep_commit_health": False}
+ assert [a[2] for a, _k in rec.args_of("purge_proposed_decisions_by_source")] == [
+ "code_comment",
+ "git_archaeology",
+ ]
+
+
+async def test_every_failing_step_degrades_and_only_range_scoped_ones_are_marked(repo, monkeypatch):
+ from repowise.core.pipeline.cleanup_debt import record_cleanup_debt
+
+ # Seeded debt is what reaches the cleanup tail once tombstoning has failed.
+ record_cleanup_debt(repo, "fts", {"file_page:src/old.py"})
+ record_cleanup_debt(repo, "vectors", {"file_page:src/old.py"})
+ survivors = {
+ "tombstone_candidates",
+ "file_import_edges",
+ "prune_deleted_file_rows",
+ "_analyzed_commit",
+ # Not wrapped: a failure here propagates.
+ "refresh_commit_health_after_update",
+ }
+ fail = frozenset(label for label in HAPPY_ORDER if label not in survivors)
+ rec = StepRecorder(monkeypatch, fail=fail)
+ install_shared_steps(rec, prune_ret=(1, [REFUSAL]))
+
+ degraded, failed_steps = await _persist(repo, rec)
+
+ assert rec.order == [
+ "reconcile_full_index_scope",
+ "tombstone_pages_outside_generation",
+ "sweep_retired_pages",
+ "tombstone_candidates",
+ "mark_tombstone_pages",
+ "rebuild_page_tree",
+ "persist_git_refresh",
+ "persist_incremental_commits",
+ "replace_dead_code_findings",
+ "replace_doc_drift_guarded",
+ "persist_graph_nodes",
+ "persist_partial_health",
+ "persist_incremental_symbols",
+ "persist_incremental_security_findings",
+ "persist_incremental_edges",
+ "file_import_edges",
+ "backfill_related_pages",
+ "persist_kg",
+ "refresh_external_systems",
+ "purge_proposed_decisions_by_source",
+ "prune_deleted_file_rows",
+ "_analyzed_commit",
+ "finalize_performance_opportunities",
+ "refresh_commit_health_after_update",
+ "fts.ensure_index",
+ "vectors.delete_many",
+ ]
+ assert degraded == [
+ *(
+ f"{step}: {FAILURE}"
+ for step in (
+ "Config scope reconciliation",
+ "Generation scope reconciliation",
+ "Retired page sweep",
+ "Tombstone marking",
+ "Page tree rebuild",
+ "Git persist",
+ "Commit capture",
+ "Dead-code persist",
+ "Doc-drift persist",
+ "Graph nodes persist",
+ "Health persist",
+ "Symbol persist",
+ "Security persist",
+ "Graph edges persist",
+ "Related-pages backfill",
+ "Knowledge-graph persist",
+ "External systems refresh",
+ "Decision purge",
+ )
+ ),
+ # A prune refusal is reported verbatim, not as a skipped step.
+ REFUSAL,
+ f"Queue rebuild after prune: {FAILURE}",
+ f"Tombstone full-text removal: {FAILURE}",
+ f"Tombstone vector removal: {FAILURE}",
+ ]
+ assert failed_steps == [
+ "Tombstone marking",
+ "Git persist",
+ "Dead-code persist",
+ "Health persist",
+ "Symbol persist",
+ "Security persist",
+ "Graph edges persist",
+ "External systems refresh",
+ "Tombstone full-text removal",
+ ]
diff --git a/tests/unit/pipeline/test_persist_analysis_decision_chain.py b/tests/unit/pipeline/test_persist_analysis_decision_chain.py
new file mode 100644
index 000000000..666a1f3c2
--- /dev/null
+++ b/tests/unit/pipeline/test_persist_analysis_decision_chain.py
@@ -0,0 +1,149 @@
+"""``persist_analysis`` writes its outputs and runs the decision repairs in one order.
+
+The order is load-bearing: un-retiring lands a row at ``proposed``, which the
+retired-source purge deletes, so un-retire has to come first; the id migration
+precedes everything that reads a record by id; the scope prune precedes the
+basis repairs that judge its file list. Every writer is a recorder here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.pipeline.persist import persist_analysis
+from tests.unit._persist_step_recorders import (
+ FAILURE,
+ StepRecorder,
+ install_decision_chain,
+)
+
+
+@dataclass
+class _Decision:
+ title: str = "Use durable retries"
+
+
+def _install_analysis_writers(rec: StepRecorder) -> None:
+ import repowise.core.pipeline.persist as persist
+ from repowise.core.persistence import crud
+
+ for name in (
+ "save_dead_code_findings",
+ "replace_doc_drift_guarded",
+ "save_coverage_files",
+ "upsert_git_function_blame_bulk",
+ "set_repo_function_mod_p80",
+ ):
+ rec.patch(crud, name)
+ rec.patch(persist, "_analyzed_commit", ret="abc123")
+ rec.patch(persist, "save_full_health_report")
+ rec.patch(persist, "snapshot_health_from_store")
+ install_decision_chain(rec)
+
+
+def _result() -> SimpleNamespace:
+ return SimpleNamespace(
+ dead_code_report=SimpleNamespace(findings=[]),
+ doc_drift_report=object(),
+ health_report=SimpleNamespace(
+ coverage_files=["src/a.py"],
+ coverage_format="lcov",
+ function_blame_rows=[{"symbol_id": "src/a.py::f"}],
+ repo_function_mod_p80=3,
+ ),
+ decision_report=SimpleNamespace(decisions=[_Decision()]),
+ vector_store=object(),
+ git_metadata_list=[{"file_path": "src/a.py"}],
+ repo_path="/repo",
+ )
+
+
+async def test_analysis_writes_then_decision_chain_in_pinned_order(monkeypatch):
+ from repowise.core.analysis.decision_provenance import RETIRED_SOURCES
+
+ rec = StepRecorder(monkeypatch)
+ _install_analysis_writers(rec)
+
+ await persist_analysis(_result(), object(), "repo-1")
+
+ assert rec.order == [
+ "save_dead_code_findings",
+ "replace_doc_drift_guarded",
+ "_analyzed_commit",
+ "save_full_health_report",
+ "save_coverage_files",
+ "upsert_git_function_blame_bulk",
+ "set_repo_function_mod_p80",
+ "snapshot_health_from_store",
+ "unretire_auto_superseded",
+ *["purge_proposed_decisions_by_source"] * len(RETIRED_SOURCES),
+ "reconcile_source_ranks",
+ "reconcile_decision_confidence",
+ "apply_id_migration",
+ "apply_migration",
+ "prune_unindexed_scope_files",
+ "backfill_scope_basis",
+ "backfill_session_scope_basis",
+ "backfill_decision_node_links",
+ "bulk_upsert_decisions",
+ "detect_supersessions_and_conflicts",
+ "recompute_decision_staleness",
+ "apply_revert_supersession",
+ "apply_head_artifact_check",
+ "refresh_governance_findings",
+ ]
+ assert [a[2] for a, _k in rec.args_of("purge_proposed_decisions_by_source")] == list(
+ RETIRED_SOURCES
+ )
+
+
+async def test_each_decision_repair_is_isolated_from_the_others(monkeypatch):
+ """A failing repair skips only itself (or its own group), never the chain."""
+ fail = frozenset(
+ {
+ "unretire_auto_superseded",
+ "purge_proposed_decisions_by_source",
+ "reconcile_source_ranks",
+ "reconcile_decision_confidence",
+ "apply_id_migration",
+ "apply_migration",
+ "detect_supersessions_and_conflicts",
+ "recompute_decision_staleness",
+ "apply_revert_supersession",
+ "apply_head_artifact_check",
+ "refresh_governance_findings",
+ }
+ )
+ rec = StepRecorder(monkeypatch, fail=fail)
+ _install_analysis_writers(rec)
+
+ await persist_analysis(_result(), object(), "repo-1")
+
+ assert rec.order[rec.order.index("unretire_auto_superseded") :] == [
+ "unretire_auto_superseded",
+ # The purge loop shares one try: the first failure ends the loop.
+ "purge_proposed_decisions_by_source",
+ "reconcile_source_ranks",
+ "reconcile_decision_confidence",
+ "apply_id_migration",
+ # The migration group shares one try too.
+ "apply_migration",
+ "bulk_upsert_decisions",
+ "detect_supersessions_and_conflicts",
+ "recompute_decision_staleness",
+ "apply_revert_supersession",
+ "apply_head_artifact_check",
+ "refresh_governance_findings",
+ ]
+
+
+async def test_bulk_upsert_failure_is_not_swallowed(monkeypatch):
+ rec = StepRecorder(monkeypatch, fail=frozenset({"bulk_upsert_decisions"}))
+ _install_analysis_writers(rec)
+
+ with pytest.raises(RuntimeError, match=FAILURE):
+ await persist_analysis(_result(), object(), "repo-1")
+ assert rec.order[-1] == "bulk_upsert_decisions"