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
fix(generation): keep a page whose provider call failed (Refs #1089) (#1104)
Raghav Chamadiyaad8b17db5045
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.pyindex dce4d194d..5568fc1ce 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py@@ -24,6 +24,7 @@ from repowise.cli.helpers import ()from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_jsonfrom repowise.core.docs_mode import docs_mode_state_fields+from repowise.core.generation.models import count_stub_fallbackslogger = structlog.get_logger(__name__)@@ -167,7 +168,13 @@ async def persist_result(result: Any, repo_path: Path) -> None:# Record a completed GenerationJob so the web UI can show# "last synced" / "last re-indexed" timestamps.now = datetime.now(UTC)- page_count = len(result.generated_pages) if result.generated_pages else 0+ _pages = result.generated_pages or []+ page_count = len(_pages)+ # A page that fell back to its stub has a row, so it counts towards the+ # total, but the model never wrote it. Counting it as completed is what+ # would let a run that lost half its pages report a clean sweep to the+ # web UI, which reads this row rather than the job checkpoint.+ stub_fallbacks = count_stub_fallbacks(_pages)job = await upsert_generation_job(session,repository_id=repo.id,@@ -175,7 +182,8 @@ async def persist_result(result: Any, repo_path: Path) -> None:total_pages=page_count,config={"mode": "full_resync", "source": "cli_init"},)- job.completed_pages = page_count+ job.completed_pages = page_count - stub_fallbacks+ job.failed_pages = stub_fallbacksjob.started_at = nowjob.finished_at = nowdiff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.pyindex 9c79ef46d..200b3b6d1 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py@@ -696,10 +696,14 @@ async def _persist_full_update_async(from datetime import UTC as _UTCfrom datetime import datetime+ from repowise.core.generation.models import count_stub_fallbacksfrom repowise.core.persistence.crud import upsert_generation_jobnow = datetime.now(_UTC)page_count = len(generated_pages)+ # See init_cmd/persistence.py: a stub the provider failure put+ # up has a row but no prose, so it is not a completed page.+ stub_fallbacks = count_stub_fallbacks(generated_pages)job = await upsert_generation_job(session,repository_id=repo_id,@@ -707,7 +711,8 @@ async def _persist_full_update_async(total_pages=page_count,config={"mode": "incremental", "source": "cli_update"},)- job.completed_pages = page_count+ job.completed_pages = page_count - stub_fallbacks+ job.failed_pages = stub_fallbacksjob.started_at = nowjob.finished_at = nowexcept Exception as exc:diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.pyindex 2adeab16c..6623da64a 100644--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py@@ -295,9 +295,13 @@ async def _run_upgrade(try:from datetime import UTC, datetime+ from repowise.core.generation.models import count_stub_fallbacksfrom repowise.core.persistence.crud import upsert_generation_jobnow = datetime.now(UTC)+ # See init_cmd/persistence.py: a stub the provider failure put up+ # has a row but no prose, so it is not a completed page.+ stub_fallbacks = count_stub_fallbacks(generated_pages)job = await upsert_generation_job(session,repository_id=repo_id,@@ -305,7 +309,8 @@ async def _run_upgrade(total_pages=len(generated_pages),config={"mode": "upgrade", "source": "cli_update_full"},)- job.completed_pages = len(generated_pages)+ job.completed_pages = len(generated_pages) - stub_fallbacks+ job.failed_pages = stub_fallbacksjob.started_at = nowjob.finished_at = nowexcept Exception:diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.pyindex a22a486d8..a5794c486 100644--- a/packages/core/src/repowise/core/generation/models.py+++ b/packages/core/src/repowise/core/generation/models.py@@ -360,6 +360,30 @@ MODEL_WRITTEN_PAGE_TYPES: frozenset[str] = frozenset({"module_page", "repo_overview", "architecture_diagram", "onboarding"})+# Metadata key holding the provider error a page fell back to its stub over.+# Present only on a stub the run substituted for a model page whose provider+# call raised, which is not the same thing as a stub a deterministic run meant+# to write. The distinction is what lets the level runner record the page as+# failed while still handing back a row.+STUB_FALLBACK_ERROR = "stub_fallback_error"+++def is_stub_fallback(page: Any) -> bool:+ """True when *page* is a stub standing in for a failed provider call."""+ return STUB_FALLBACK_ERROR in (getattr(page, "metadata", None) or {})+++def count_stub_fallbacks(pages: Iterable[Any]) -> int:+ """How many of *pages* the model never actually wrote.++ Every writer of a ``GenerationJob`` row needs this same split, because a+ stub is in ``generated_pages`` like any other page: counting the list is+ what would let a run that lost half its pages report a clean sweep. Four+ call sites deriving it separately is four chances for one of them to drift+ back into counting a failure as a success, which is the bug itself.+ """+ return sum(1 for page in pages if is_stub_fallback(page))+def member_structural_key(members: Iterable[str], *, prefix: str) -> str:"""Return a stable identity for a page defined by the files it covers.diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.pyindex a9f490ab3..b70ce603f 100644--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py@@ -21,6 +21,7 @@ import structlogfrom ..context_assembler import FilePageContextfrom ..models import (STRUCTURALLY_KEYED_PAGE_TYPES,+ STUB_FALLBACK_ERROR,GeneratedPage,compute_page_id,member_structural_key,@@ -573,6 +574,18 @@ class _GenerationRun:result = await coroif isinstance(result, GeneratedPage):+ # A page whose provider call raised comes back as its+ # structural stub rather than being dropped (issue #1089),+ # so the row exists and `repowise generate` can refill it.+ # It is still a failure: the job checkpoint has to say so,+ # or a run that lost half its pages reports a clean sweep.+ stub_error = result.metadata.get(STUB_FALLBACK_ERROR)+ if (+ stub_error is not None+ and self.job_system is not None+ and self.job_id is not None+ ):+ self.job_system.fail_page(self.job_id, page_id, stub_error)# Summary capture is cheap (string ops) — keep inline so# the next page's context assembly sees it immediately.self.completed_page_summaries[result.target_path] = overview_summary(@@ -594,9 +607,20 @@ class _GenerationRun:# re-embedding it re-bills the embedder for every unchanged# page on every update. Ephemeral stores start empty each# run and still need it.- if self.vector_store is not None and not (- result.metadata.get("reused_from_prior_run")- and getattr(self.vector_store, "persists_across_runs", False)+ #+ # A stub standing in for a failed page is held back. Not to+ # save the embedding call: ``_seed_resume`` reads the store+ # back as the list of pages already done, so embedding the+ # stub is what would tell the next ``--resume`` there is+ # nothing left to write here. The page is still persisted+ # and full-text indexed; only the resume ledger is spared.+ if (+ self.vector_store is not None+ and stub_error is None+ and not (+ result.metadata.get("reused_from_prior_run")+ and getattr(self.vector_store, "persists_across_runs", False)+ )):embed_items.append(_embed_item(result))return result@@ -643,7 +667,10 @@ class _GenerationRun:pages = [r for r in results if isinstance(r, GeneratedPage)]if self.job_system is not None and self.job_id is not None:for r in pages:- self.job_system.complete_page(self.job_id, r.page_id)+ # Already recorded as failed above. A page cannot be both, and+ # "completed" is the half a reader would believe.+ if r.metadata.get(STUB_FALLBACK_ERROR) is None:+ self.job_system.complete_page(self.job_id, r.page_id)return pages# ------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex 01d50d9e7..9a2ef7998 100644--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py@@ -19,11 +19,41 @@ from repowise.core.ingestion.models import ParsedFile, RepoStructurefrom .. import onboarding as _onboardingfrom ..architecture_mermaid import embed_mermaidfrom ..context_assembler import FilePageContext, LayerPageContext-from ..models import GENERATION_LEVELS, GeneratedPage, compute_source_hash+from ..models import (+ GENERATION_LEVELS,+ STUB_FALLBACK_ERROR,+ GeneratedPage,+ compute_source_hash,+)log = structlog.get_logger(__name__)+def _stub_fallback(page: GeneratedPage, page_type: str, exc: Exception) -> GeneratedPage:+ """Mark *page* as the stub standing in for a model page the provider lost.++ Dropping the page instead is what made a provider outage unrecoverable+ (issue #1089): scope resolution runs over persisted page records, so a page+ no run ever wrote is invisible to ``generate`` and to ``update`` alike, and+ nothing can ask for it again. The stub is already the shape these four page+ types take before a model writes them, so substituting it costs one render+ and leaves a row that ``repowise generate`` refills like any other stub.++ The error is stamped rather than only logged because the level runner reads+ it back: this page still has to count as a failure in the job checkpoint,+ and must not reach the vector store that ``--resume`` treats as its record+ of what is already done.+ """+ page.metadata[STUB_FALLBACK_ERROR] = str(exc)[:500]+ log.warning(+ "page_generation.stub_fallback",+ page_type=page_type,+ target_path=page.target_path,+ error=str(exc),+ )+ return page++class PerTypeGenerationMixin:"""Per-type ``generate_*`` methods. Requires the host to provide``_assembler``, ``_render``, ``_call_provider`` and@@ -182,9 +212,13 @@ class PerTypeGenerationMixin:page = self._stub_module_page(ctx, page_target, title, module_git_summary)return _stamp_concept(page)user_prompt = self._render("module_page.j2", ctx=ctx, module_git_summary=module_git_summary)- response = await self._call_provider(- "module_page", user_prompt, str(uuid.uuid4()), target_path=page_target- )+ try:+ response = await self._call_provider(+ "module_page", user_prompt, str(uuid.uuid4()), target_path=page_target+ )+ except Exception as exc:+ stub = self._stub_module_page(ctx, page_target, title, module_git_summary)+ return _stamp_concept(_stub_fallback(stub, "module_page", exc))page = self._build_generated_page("module_page",page_target,@@ -252,9 +286,15 @@ class PerTypeGenerationMixin:ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary)user_prompt = self._render("repo_overview.j2", ctx=ctx, repo_git_summary=repo_git_summary)- response = await self._call_provider(- "repo_overview", user_prompt, str(uuid.uuid4()), target_path=repo_name- )+ try:+ response = await self._call_provider(+ "repo_overview", user_prompt, str(uuid.uuid4()), target_path=repo_name+ )+ except Exception as exc:+ stub = self._stub_repo_overview(+ ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary+ )+ return _stub_fallback(stub, "repo_overview", exc)return self._build_generated_page("repo_overview",repo_name,@@ -281,9 +321,18 @@ class PerTypeGenerationMixin:ctx, repo_name, f"Architecture Diagram: {repo_name}", overview_mermaid)user_prompt = self._render("architecture_diagram.j2", ctx=ctx)- response = await self._call_provider(- "architecture_diagram", user_prompt, str(uuid.uuid4()), target_path=repo_name- )+ try:+ response = await self._call_provider(+ "architecture_diagram", user_prompt, str(uuid.uuid4()), target_path=repo_name+ )+ except Exception as exc:+ # The stub embeds the same KG-derived map the model path overwrites+ # the model's diagram with, so the fallback keeps the diagram and+ # loses only the prose around it.+ stub = self._stub_architecture_diagram(+ ctx, repo_name, f"Architecture Diagram: {repo_name}", overview_mermaid+ )+ return _stub_fallback(stub, "architecture_diagram", exc)# Swap the LLM's free-form diagram for the deterministic KG-derived map# (idempotent, applies to fresh and reused content). Falls back to the# LLM's own mermaid when the KG can't produce one.@@ -339,9 +388,15 @@ class PerTypeGenerationMixin:# Fold the onboarding generation version into the reuse hash so a# builder/template upgrade forces a one-time regen of cached pages.salt = _onboarding.ONBOARDING_GENERATION_VERSION- response = await self._call_provider(- "onboarding", user_prompt, str(uuid.uuid4()), target_path=target, source_salt=salt- )+ try:+ response = await self._call_provider(+ "onboarding", user_prompt, str(uuid.uuid4()), target_path=target, source_salt=salt+ )+ except Exception as exc:+ # ``_stub_onboarding_page`` stamps the subkind metadata itself, so+ # the fallback is interchangeable with the deterministic path.+ stub = self._stub_onboarding_page(spec, ctx, target)+ return _stub_fallback(stub, "onboarding", exc)# Grounding post-check: strip ungrounded path/symbol citations from the# output. Runs on fresh AND reused content (``response.content`` carries# the prior page's bytes on a cache hit), so an existing user's cacheddiff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.pyindex 608cf2bc5..7a0dd4949 100644--- a/packages/core/src/repowise/core/persistence/crud/pages.py+++ b/packages/core/src/repowise/core/persistence/crud/pages.py@@ -26,10 +26,36 @@ from ._shared import _parse_dt# ---------------------------------------------------------------------------+def _would_bury_prose(existing: Page | None, metadata: dict | None) -> bool:+ """True when writing this page would replace real prose with a failure stub.++ The generator substitutes a structural stub for a model page whose provider+ call failed (issue #1089) so the page has a row to be found by. That is the+ right answer when nothing was there. It is the wrong one on top of a page a+ model already wrote: one 529 during ``update`` would otherwise cost the user+ the page and file the good version behind a snapshot nobody knows to look+ for.++ Narrow on purpose. A stub landing on a row that is *itself* a stub is not+ prose loss, so it falls through to the normal idempotent path and keeps+ refreshing the fields that say where the page sits.++ Imported lazily to keep persistence independent of generation at module+ load, the same reason :func:`load_prior_pages` defers ``PriorPage``.+ """+ if existing is None or not metadata:+ return False+ from repowise.core.generation.models import STUB_FALLBACK_ERROR+ from repowise.core.providers.llm.template import TEMPLATE_PROVIDER_NAME++ return STUB_FALLBACK_ERROR in metadata and existing.provider_name != TEMPLATE_PROVIDER_NAME++def _apply_page_upsert(session: AsyncSession,existing: Page | None,*,+ keep_existing_prose: bool = False,page_id: str,repository_id: str,page_type: str,@@ -64,6 +90,22 @@ def _apply_page_upsert(for :func:`upsert_pages_from_generated`)."""if existing is not None:+ # The page keeps the prose it already has (see+ # :func:`_would_bury_prose`), but it still moved: placement is decided+ # after generation, by a pass that mutates the page objects, and this+ # write is where it lands. Refreshing those fields and nothing else+ # keeps the tree correct without touching what the page says. The+ # failure marker deliberately does not go to ``metadata_json`` — this+ # row has prose, so recording it as a stub would be a lie the stub+ # counters and ``generate`` would both read.+ if keep_existing_prose:+ existing.title = title+ existing.target_path = target_path+ existing.parent_page_id = parent_page_id+ existing.display_order = display_order+ existing.section_number = section_number+ existing.structural_key = structural_key+ return existing# Idempotent no-op: content, prompt hash and model all unchanged, so# do not bump the version or spawn a PageVersion snapshot; only refresh# the cheap derived fields (metadata enrichment lands here).@@ -204,6 +246,7 @@ async def upsert_page(page = _apply_page_upsert(session,existing,+ keep_existing_prose=_would_bury_prose(existing, metadata),page_id=page_id,repository_id=repository_id,page_type=page_type,@@ -355,6 +398,9 @@ async def upsert_pages_from_generated(_apply_page_upsert(session,existing_by_id.get(gp.page_id),+ keep_existing_prose=_would_bury_prose(+ existing_by_id.get(gp.page_id), gp.metadata+ ),page_id=gp.page_id,repository_id=repository_id,page_type=gp.page_type,diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex 294c80208..d1d9c203d 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -13,7 +13,10 @@ from typing import Anyimport structlog-from repowise.core.generation.models import STRUCTURALLY_KEYED_PAGE_TYPES+from repowise.core.generation.models import (+ STRUCTURALLY_KEYED_PAGE_TYPES,+ STUB_FALLBACK_ERROR,+)logger = structlog.get_logger(__name__)@@ -659,6 +662,13 @@ async def sweep_superseded_generated_pages(page_type = page.page_typeif page_type not in _SWEPT_GENERATED_PAGE_TYPES:continue+ # A stub standing in for a failed provider call is the "failed to+ # generate" case this function's contract already carves out: it claims+ # no files, so a prior row covering them is not superseded. Counting its+ # members would retire the very page whose regeneration just failed, and+ # take its version history with it.+ if STUB_FALLBACK_ERROR in (getattr(page, "metadata", None) or {}):+ continueproduced_ids.setdefault(page_type, set()).add(page.page_id)metadata = getattr(page, "metadata", None) or {}members = metadata.get("file_paths") or metadata.get("files") or []diff --git a/packages/server/src/repowise/server/job_executor.py b/packages/server/src/repowise/server/job_executor.pyindex 5cf5ac51a..da3b6eabd 100644--- a/packages/server/src/repowise/server/job_executor.py+++ b/packages/server/src/repowise/server/job_executor.py@@ -544,7 +544,13 @@ async def execute_job(elapsed = time.monotonic() - starttotal_input = sum(p.input_tokens for p in all_pages)total_output = sum(p.output_tokens for p in all_pages)+ from repowise.core.generation.models import count_stub_fallbacks+pages_generated = len(all_pages)+ # A stub the generator put up for a failed provider call has a row but+ # no prose. The hosted UI reads this job row, so counting it as+ # completed is what would let an outage look like a clean run.+ stub_fallbacks = count_stub_fallbacks(all_pages)async with get_session(session_factory) as session:job = await get_generation_job(session, job_id)@@ -567,7 +573,10 @@ async def execute_job(session,job_id,"completed",- completed_pages=pages_generated if pages_generated else result.file_count,+ completed_pages=(+ pages_generated - stub_fallbacks if pages_generated else result.file_count+ ),+ failed_pages=stub_fallbacks,total_pages=pages_generated if pages_generated else result.file_count,)@@ -1035,7 +1044,10 @@ async def _run_generate_job(elapsed = time.monotonic() - starttotal_input = sum(getattr(p, "input_tokens", 0) for p in generated_pages)total_output = sum(getattr(p, "output_tokens", 0) for p in generated_pages)+ from repowise.core.generation.models import count_stub_fallbacks+pages_generated = len(generated_pages)+ stub_fallbacks = count_stub_fallbacks(generated_pages)async with get_session(session_factory) as session:job = await get_generation_job(session, job_id)@@ -1058,7 +1070,8 @@ async def _run_generate_job(session,job_id,"completed",- completed_pages=pages_generated,+ completed_pages=pages_generated - stub_fallbacks,+ failed_pages=stub_fallbacks,total_pages=pages_generated,)total_pages, remaining_templates = await _repo_page_counts(session, repo_id)diff --git a/tests/unit/cli/test_persist_result_job_counts.py b/tests/unit/cli/test_persist_result_job_counts.pynew file mode 100644index 000000000..223378b61--- /dev/null+++ b/tests/unit/cli/test_persist_result_job_counts.py@@ -0,0 +1,98 @@+"""The GenerationJob row must not count a failure stub as a written page.++The web UI reads this row, not the job checkpoint under ``.repowise/jobs/``.+Before the stub fallback (issue #1089) a failed page contributed nothing to+``generated_pages``, so the row under-counted. Now it has a row, and counting+it as completed would let a run that lost half its pages report a clean sweep.+"""++from __future__ import annotations++from datetime import UTC, datetime+from types import SimpleNamespace++from sqlalchemy import select++from repowise.cli._repo_session import open_repo_db+from repowise.cli.commands.init_cmd.persistence import persist_result+from repowise.core.generation.models import STUB_FALLBACK_ERROR, GeneratedPage+from repowise.core.persistence import get_session+from repowise.core.persistence.models import GenerationJob+++def _page(target: str, *, stub_error: str | None = None) -> GeneratedPage:+ now = datetime.now(UTC).isoformat()+ page = GeneratedPage(+ page_id=f"module_page:{target}",+ page_type="module_page",+ title=target,+ content=f"content for {target}",+ source_hash="x" * 64,+ model_name="mock",+ provider_name="template" if stub_error else "mock",+ input_tokens=0 if stub_error else 1,+ output_tokens=0 if stub_error else 1,+ cached_tokens=0,+ generation_level=4,+ target_path=target,+ created_at=now,+ updated_at=now,+ )+ if stub_error:+ page.metadata[STUB_FALLBACK_ERROR] = stub_error+ return page+++def _result(pages: list[GeneratedPage]) -> SimpleNamespace:+ return SimpleNamespace(+ repo_name="r",+ index_persisted_incrementally=True,+ generated_pages=pages,+ tech_stack=None,+ vector_store=None,+ dead_code_report=None,+ health_report=None,+ decision_report=None,+ git_metadata_list=[],+ knowledge_graph_result=None,+ authoritative_page_types=set(),+ preserved_page_ids=set(),+ )+++async def _job(repo_path) -> GenerationJob:+ engine, sf, _ = await open_repo_db(repo_path, repo_name="r")+ try:+ async with get_session(sf) as session:+ return (await session.execute(select(GenerationJob))).scalars().one()+ finally:+ await engine.dispose()+++async def test_stub_fallbacks_are_counted_as_failed_not_completed(tmp_path):+ repo_path = tmp_path / "repo"+ repo_path.mkdir()++ pages = [+ _page("a"),+ _page("b"),+ _page("c", stub_error="upstream 529 overloaded"),+ ]+ await persist_result(_result(pages), repo_path)++ job = await _job(repo_path)+ assert job.total_pages == 3+ assert job.completed_pages == 2+ assert job.failed_pages == 1+++async def test_a_clean_run_still_reports_every_page_completed(tmp_path):+ repo_path = tmp_path / "repo"+ repo_path.mkdir()++ await persist_result(_result([_page("a"), _page("b")]), repo_path)++ job = await _job(repo_path)+ assert job.total_pages == 2+ assert job.completed_pages == 2+ assert job.failed_pages == 0diff --git a/tests/unit/generation/test_count_stub_fallbacks.py b/tests/unit/generation/test_count_stub_fallbacks.pynew file mode 100644index 000000000..474472ae3--- /dev/null+++ b/tests/unit/generation/test_count_stub_fallbacks.py@@ -0,0 +1,74 @@+"""The shared split every GenerationJob writer needs.++Four places record how many pages a run wrote: ``init``, ``update``, the+upgrade flow, and the two server job paths. A stub the generator substituted+for a failed provider call (issue #1089) sits in ``generated_pages`` like any+other page, so each of them counting the list would report an outage as a+clean run. They share this helper so the four cannot drift apart.+"""++from __future__ import annotations++from datetime import UTC, datetime++from repowise.core.generation.models import (+ STUB_FALLBACK_ERROR,+ GeneratedPage,+ count_stub_fallbacks,+ is_stub_fallback,+)+++def _page(target: str, *, stub_error: str | None = None) -> GeneratedPage:+ now = datetime.now(UTC).isoformat()+ page = GeneratedPage(+ page_id=f"module_page:{target}",+ page_type="module_page",+ title=target,+ content="body",+ source_hash="x" * 64,+ model_name="mock",+ provider_name="template" if stub_error else "mock",+ input_tokens=0,+ output_tokens=0,+ cached_tokens=0,+ generation_level=4,+ target_path=target,+ created_at=now,+ updated_at=now,+ )+ if stub_error:+ page.metadata[STUB_FALLBACK_ERROR] = stub_error+ return page+++def test_counts_only_the_pages_a_provider_failure_produced():+ pages = [_page("a"), _page("b", stub_error="529"), _page("c", stub_error="timeout")]++ assert count_stub_fallbacks(pages) == 2+++def test_a_clean_run_counts_zero():+ assert count_stub_fallbacks([_page("a"), _page("b")]) == 0+++def test_empty_is_zero():+ assert count_stub_fallbacks([]) == 0+++def test_a_deterministic_stub_is_not_a_failure():+ """A template page nothing failed on. Same ``provider_name``, no marker."""+ deterministic = _page("a")+ deterministic.provider_name = "template"++ assert is_stub_fallback(deterministic) is False+ assert count_stub_fallbacks([deterministic]) == 0+++def test_tolerates_a_page_without_metadata():+ """The server paths hand this whatever the pipeline returned."""++ class _Bare:+ pass++ assert count_stub_fallbacks([_Bare()]) == 0diff --git a/tests/unit/generation/test_run_level_stub_fallback.py b/tests/unit/generation/test_run_level_stub_fallback.pynew file mode 100644index 000000000..331dac4cd--- /dev/null+++ b/tests/unit/generation/test_run_level_stub_fallback.py@@ -0,0 +1,121 @@+"""How ``_GenerationRun.run_level`` treats a stub that stood in for a failure.++The page comes back as a ``GeneratedPage`` (issue #1089), so the level runner+can no longer read "a page arrived" as "the page was written". Two things have+to stay true of the substitute: the job still records it as failed, and it+never reaches the vector store, which is the list ``--resume`` reads back as+the work already done.+"""++from __future__ import annotations++import asyncio+from datetime import UTC, datetime+from types import SimpleNamespace++from repowise.core.generation.models import STUB_FALLBACK_ERROR, GeneratedPage+from repowise.core.generation.page_generator.orchestrate import _GenerationRun+++def _page(page_id: str, *, stub_error: str | None = None) -> GeneratedPage:+ now = datetime.now(UTC).isoformat()+ page = GeneratedPage(+ page_id=page_id,+ page_type="module_page",+ title=page_id,+ content=f"# {page_id}",+ source_hash="deadbeef",+ model_name="mock-model",+ provider_name="template" if stub_error else "mock",+ input_tokens=0 if stub_error else 1,+ output_tokens=0 if stub_error else 1,+ cached_tokens=0,+ generation_level=4,+ target_path=page_id,+ created_at=now,+ updated_at=now,+ )+ if stub_error:+ page.metadata[STUB_FALLBACK_ERROR] = stub_error+ return page+++class _RecordingStore:+ persists_across_runs = True++ def __init__(self) -> None:+ self.batches: list[list[tuple]] = []++ async def embed_batch(self, items):+ self.batches.append(list(items))+++class _RecordingJobSystem:+ def __init__(self) -> None:+ self.completed: list[str] = []+ self.failed: list[tuple[str, str]] = []+ self.levels: list[int] = []++ def update_level(self, job_id, level):+ self.levels.append(level)++ def complete_page(self, job_id, page_id):+ self.completed.append(page_id)++ def fail_page(self, job_id, page_id, error):+ self.failed.append((page_id, error))+++def _run_level() -> tuple[list[GeneratedPage], _RecordingJobSystem, _RecordingStore]:+ store = _RecordingStore()+ jobs = _RecordingJobSystem()++ async def _go():+ async def written():+ return _page("module_page:ok")++ async def fell_back():+ return _page("module_page:lost", stub_error="upstream 529 overloaded")++ run = SimpleNamespace(+ semaphore=asyncio.Semaphore(4),+ job_system=jobs,+ job_id="job-1",+ on_page_done=None,+ on_page_ready=None,+ vector_store=store,+ completed_page_summaries={},+ )+ return await _GenerationRun.run_level(+ run,+ [("module_page:ok", written()), ("module_page:lost", fell_back())],+ level=4,+ )++ return asyncio.run(_go()), jobs, store+++def test_stub_fallback_is_recorded_as_a_failed_page() -> None:+ """A run that lost half its pages must not report a clean sweep."""+ _pages, jobs, _store = _run_level()++ assert jobs.failed == [("module_page:lost", "upstream 529 overloaded")]+++def test_stub_fallback_is_not_recorded_as_completed() -> None:+ """A page cannot be both, and "completed" is the half a reader believes."""+ _pages, jobs, _store = _run_level()++ assert jobs.completed == ["module_page:ok"]+++def test_stub_fallback_is_kept_out_of_the_resume_ledger() -> None:+ """``_seed_resume`` seeds "already done" from the vector store.++ Embedding the stub is what would tell the next ``--resume`` there is+ nothing left to write here, stranding the page it exists to repair.+ """+ _pages, _jobs, store = _run_level()++ embedded = [pid for batch in store.batches for (pid, *_rest) in batch]+ assert embedded == ["module_page:ok"]diff --git a/tests/unit/generation/test_stub_fallback_never_overwrites.py b/tests/unit/generation/test_stub_fallback_never_overwrites.pynew file mode 100644index 000000000..1aaf5899d--- /dev/null+++ b/tests/unit/generation/test_stub_fallback_never_overwrites.py@@ -0,0 +1,327 @@+"""A failure stub must never replace a page that already has prose.++Substituting the stub (issue #1089) turned a failed page from "nothing was+written" into "a row was written", which put it on a collision course with two+places built around the old shape: the upsert, which would archive good prose+behind a version nobody knows to look for, and the superseded-page sweep, whose+contract already carves out "a page that failed to generate claims no files".+"""++from __future__ import annotations++import json++import pytest+from sqlalchemy import select++from repowise.core.generation.models import STUB_FALLBACK_ERROR+from repowise.core.persistence import create_engine, create_session_factory, get_session+from repowise.core.persistence.crud import upsert_page, upsert_repository+from repowise.core.persistence.crud.pages import upsert_pages_from_generated+from repowise.core.persistence.database import init_db+from repowise.core.persistence.models import Page, PageVersion+from repowise.core.pipeline.persist import sweep_superseded_generated_pages+++class _Gen:+ """Duck-typed GeneratedPage, as the upsert helpers read one."""++ def __init__(self, page_id, page_type, content, provider_name, metadata):+ self.page_id = page_id+ self.page_type = page_type+ self.title = page_id+ self.content = content+ self.summary = ""+ self.target_path = page_id.split(":", 1)[1]+ self.source_hash = "hash"+ self.model_name = "mock-model"+ self.provider_name = provider_name+ self.input_tokens = 0+ self.output_tokens = 0+ self.cached_tokens = 0+ self.generation_level = 4+ self.confidence = 1.0+ self.freshness_status = "fresh"+ self.metadata = metadata+ self.parent_page_id = None+ self.display_order = 0+ self.section_number = None+ self.structural_key = None+ self.created_at = "2026-07-26T00:00:00+00:00"+ self.updated_at = "2026-07-26T00:00:00+00:00"+++def _stub(page_id, *, members=None):+ return _Gen(+ page_id,+ "module_page",+ "# stub\n\nrendered from structure",+ "template",+ {STUB_FALLBACK_ERROR: "upstream 529 overloaded", "file_paths": members or []},+ )+++async def session_factory(tmp_path):+ engine = create_engine(f"sqlite+aiosqlite:///{tmp_path / 'wiki.db'}")+ await init_db(engine)+ yield create_session_factory(engine)+ await engine.dispose()+++async def test_stub_does_not_overwrite_existing_prose(session_factory):+ """One 529 during `update` must not cost the user a written page."""+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")+ await upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo.id,+ page_type="module_page",+ title="API",+ content="# API\n\nreal model-written prose",+ summary="",+ target_path="src/api",+ source_hash="prompt-hash",+ model_name="mock-model",+ provider_name="anthropic",+ )++ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [_stub("module_page:src/api")], repo.id)++ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/api"))+ ).scalar_one()+ assert page.content == "# API\n\nreal model-written prose"+ assert page.provider_name == "anthropic"+++async def test_stub_over_existing_prose_creates_no_version_churn(session_factory):+ """Not even archived: a snapshot is the kind of loss nobody goes looking for."""+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")+ await upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo.id,+ page_type="module_page",+ title="API",+ content="# API\n\nreal model-written prose",+ summary="",+ target_path="src/api",+ source_hash="prompt-hash",+ model_name="mock-model",+ provider_name="anthropic",+ )++ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [_stub("module_page:src/api")], repo.id)++ async with get_session(session_factory) as session:+ versions = (await session.execute(select(PageVersion))).scalars().all()+ assert versions == []+++async def test_keeping_the_prose_still_lets_the_page_move(session_factory):+ """Placement is decided after generation and lands on this write.++ Keeping the prose must not also freeze the page where it used to sit, or a+ failed page quietly falls out of the tree the reader navigates.+ """+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")+ await upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo.id,+ page_type="module_page",+ title="API",+ content="# API\n\nreal model-written prose",+ summary="",+ target_path="src/api",+ source_hash="prompt-hash",+ model_name="mock-model",+ provider_name="anthropic",+ parent_page_id=None,+ display_order=0,+ )++ moved = _stub("module_page:src/api")+ moved.parent_page_id = "layer_page:services"+ moved.display_order = 7+ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [moved], repo.id)++ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/api"))+ ).scalar_one()+ assert page.content == "# API\n\nreal model-written prose"+ assert page.parent_page_id == "layer_page:services"+ assert page.display_order == 7+++async def test_prose_page_is_not_recorded_as_a_stub(session_factory):+ """It has prose. Marking it failed would make the stub counters lie."""+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")+ await upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo.id,+ page_type="module_page",+ title="API",+ content="# API\n\nreal model-written prose",+ summary="",+ target_path="src/api",+ source_hash="prompt-hash",+ model_name="mock-model",+ provider_name="anthropic",+ )++ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [_stub("module_page:src/api")], repo.id)++ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/api"))+ ).scalar_one()+ assert STUB_FALLBACK_ERROR not in json.loads(page.metadata_json)+++async def test_a_stub_landing_on_a_stub_keeps_the_post_generation_enrichment(+ session_factory,+):+ """The double write a normal init does: incremental flush, then final persist.++ No prose is at risk here, so this must take the ordinary idempotent path+ and not the carve-out. The enrichment added between the two writes+ (interlinking, related pages, the tour) reaches the row only through+ ``metadata_json``, which the carve-out deliberately does not write — so+ that is the field that tells the two paths apart.+ """+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")++ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [_stub("module_page:src/api")], repo.id)++ enriched = _stub("module_page:src/api")+ enriched.metadata["wiki_links"] = ["module_page:src/db"]+ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [enriched], repo.id)++ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/api"))+ ).scalar_one()+ metadata = json.loads(page.metadata_json)+ assert metadata["wiki_links"] == ["module_page:src/db"]+ # Still a stub, so `generate` still offers to write it.+ assert page.provider_name == "template"+ assert STUB_FALLBACK_ERROR in metadata+++async def test_stub_is_still_written_when_the_page_is_new(session_factory):+ """The whole point: a page nothing ever wrote gets a row to be found by."""+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")++ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [_stub("module_page:src/new")], repo.id)++ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/new"))+ ).scalar_one()+ assert page.provider_name == "template"+++async def test_stub_members_do_not_retire_the_page_whose_generation_failed(+ session_factory,+):+ """A concept group renaming itself while the provider is down.++ The old row's files all appear in the stub written under the new id, so+ without the carve-out the sweep reads the old page as superseded and+ deletes it, taking its version history with it.+ """+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")+ await upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo.id,+ page_type="module_page",+ title="API",+ content="# API\n\nreal model-written prose",+ summary="",+ target_path="src/api",+ source_hash="prompt-hash",+ model_name="mock-model",+ provider_name="anthropic",+ metadata={"file_paths": ["src/api/a.py", "src/api/b.py"]},+ )++ async with get_session(session_factory) as session:+ swept = await sweep_superseded_generated_pages(+ session,+ repo.id,+ [_stub("module_page:src/api/v2", members=["src/api/a.py", "src/api/b.py"])],+ )++ assert swept == []+ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/api"))+ ).scalar_one_or_none()+ assert page is not None+++async def test_a_written_page_still_retires_the_row_it_supersedes(session_factory):+ """The carve-out must not disarm the sweep for pages that did generate."""+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")+ await upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo.id,+ page_type="module_page",+ title="API",+ content="# API",+ summary="",+ target_path="src/api",+ source_hash="prompt-hash",+ model_name="mock-model",+ provider_name="anthropic",+ metadata={"file_paths": ["src/api/a.py", "src/api/b.py"]},+ )++ written = _Gen(+ "module_page:src/api/v2",+ "module_page",+ "# API v2\n\nprose",+ "anthropic",+ {"file_paths": ["src/api/a.py", "src/api/b.py"]},+ )+ async with get_session(session_factory) as session:+ swept = await sweep_superseded_generated_pages(session, repo.id, [written])++ assert swept == ["module_page:src/api"]+++async def test_the_error_survives_to_the_database(session_factory):+ """A run that produced stubs must be diagnosable after the fact."""+ async with get_session(session_factory) as session:+ repo = await upsert_repository(session, name="demo", local_path="/demo")++ async with get_session(session_factory) as session:+ await upsert_pages_from_generated(session, [_stub("module_page:src/new")], repo.id)++ async with get_session(session_factory) as session:+ page = (+ await session.execute(select(Page).where(Page.id == "module_page:src/new"))+ ).scalar_one()+ assert "529" in json.loads(page.metadata_json)[STUB_FALLBACK_ERROR]diff --git a/tests/unit/generation/test_stub_on_provider_error.py b/tests/unit/generation/test_stub_on_provider_error.pynew file mode 100644index 000000000..9a09e8d9a--- /dev/null+++ b/tests/unit/generation/test_stub_on_provider_error.py@@ -0,0 +1,123 @@+"""A model page whose provider call fails falls back to its structural stub.++Dropping the page was what made a provider outage unrecoverable (issue #1089).+Scope resolution runs over persisted page records, so a page no run ever wrote+is invisible to ``generate`` and to ``update`` alike and cannot be asked for+again. Falling back to the stub leaves a row that reads as unwritten, which is+the state ``generate`` already knows how to repair.+"""++from __future__ import annotations++from dataclasses import dataclass++import pytest++from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.models import (+ MODEL_WRITTEN_PAGE_TYPES,+ STUB_FALLBACK_ERROR,+ GeneratedPage,+)+from repowise.core.generation.page_generator import PageGenerator+from repowise.core.generation.scope import load_page_records+from repowise.core.providers.llm.mock import MockProvider+++@dataclass+class _Row:+ """Duck-typed persisted Page row, as ``load_page_records`` reads one."""++ id: str+ page_type: str+ target_path: str+ provider_name: str+ freshness_status: str = "fresh"+ metadata_json: str = "{}"+++class _OutageProvider(MockProvider):+ """A provider that fails the way a real outage does: every call raises."""++ async def generate(self, *args, **kwargs):+ raise RuntimeError("upstream 529 overloaded")+++def outage_gen(sample_config) -> PageGenerator:+ return PageGenerator(_OutageProvider(), ContextAssembler(sample_config), sample_config)+++async def _overview(gen: PageGenerator, sample_repo_structure) -> GeneratedPage:+ return await gen.generate_repo_overview(+ sample_repo_structure,+ pagerank={},+ sccs=[],+ community={},+ repo_name="demo",+ )+++async def test_provider_failure_returns_a_page_instead_of_raising(+ outage_gen, sample_repo_structure+):+ page = await _overview(outage_gen, sample_repo_structure)++ assert isinstance(page, GeneratedPage)+ assert page.page_id == "repo_overview:demo"+ assert page.content.strip()+++async def test_fallback_page_reads_as_unwritten(outage_gen, sample_repo_structure):+ """``provider_name='template'`` is the one signal every stub check reads.++ ``generate`` selects its work with it, ``_page_stats`` counts it, and+ ``docs_mode`` flips on it. A fallback stamped with the real provider would+ claim the wiki is fully written and stop offering to fill the gap.+ """+ page = await _overview(outage_gen, sample_repo_structure)++ assert page.provider_name == "template"+ assert page.input_tokens == 0+ assert page.output_tokens == 0+++async def test_fallback_page_is_selected_by_generate_as_a_stub(outage_gen, sample_repo_structure):+ """The end the whole change exists for: the page can be asked for again."""+ page = await _overview(outage_gen, sample_repo_structure)++ (record,) = load_page_records(+ [+ _Row(+ id=page.page_id,+ page_type=page.page_type,+ target_path=page.target_path,+ provider_name=page.provider_name,+ )+ ]+ )++ assert record.is_template+ assert record.page_type in MODEL_WRITTEN_PAGE_TYPES+++async def test_fallback_carries_the_provider_error(outage_gen, sample_repo_structure):+ """The level runner reads this back to record the page as failed."""+ page = await _overview(outage_gen, sample_repo_structure)++ assert "upstream 529 overloaded" in page.metadata[STUB_FALLBACK_ERROR]+++async def test_deterministic_stub_is_not_marked_as_a_failure(sample_config, sample_repo_structure):+ """A deterministic run meant to write a stub. Nothing failed, so the job+ must not be told one did, and the page still belongs in the resume ledger.+ """+ from dataclasses import replace++ config = replace(sample_config, deterministic=True)+ gen = PageGenerator(MockProvider(), ContextAssembler(config), config)++ page = await _overview(gen, sample_repo_structure)++ assert page.provider_name == "template"+ assert STUB_FALLBACK_ERROR not in page.metadata