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.

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.py
index 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_json
from repowise.core.docs_mode import docs_mode_state_fields
+from repowise.core.generation.models import count_stub_fallbacks
logger = 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_fallbacks
job.started_at = now
job.finished_at = now
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
index 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 _UTC
from datetime import datetime
+ from repowise.core.generation.models import count_stub_fallbacks
from repowise.core.persistence.crud import upsert_generation_job
now = 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_fallbacks
job.started_at = now
job.finished_at = now
except Exception as exc:
diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.py
index 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_fallbacks
from repowise.core.persistence.crud import upsert_generation_job
now = 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_fallbacks
job.started_at = now
job.finished_at = now
except Exception:
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index 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.py
index 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 structlog
from ..context_assembler import FilePageContext
from ..models import (
STRUCTURALLY_KEYED_PAGE_TYPES,
+ STUB_FALLBACK_ERROR,
GeneratedPage,
compute_page_id,
member_structural_key,
@@ -573,6 +574,18 @@ class _GenerationRun:
result = await coro
if 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.py
index 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, RepoStructure
from .. import onboarding as _onboarding
from ..architecture_mermaid import embed_mermaid
from ..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 cached
diff --git a/packages/core/src/repowise/core/persistence/crud/pages.py b/packages/core/src/repowise/core/persistence/crud/pages.py
index 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.py
index 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 Any
import 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_type
if 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 {}):
+ continue
produced_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.py
index 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() - start
total_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() - start
total_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.py
new file mode 100644
index 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 == 0
diff --git a/tests/unit/generation/test_count_stub_fallbacks.py b/tests/unit/generation/test_count_stub_fallbacks.py
new file mode 100644
index 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()]) == 0
diff --git a/tests/unit/generation/test_run_level_stub_fallback.py b/tests/unit/generation/test_run_level_stub_fallback.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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