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(resume): keep the pages a resumed run deliberately skipped (#1097)

Raghav Chamadiyaea360e3f311d
diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md
index a008257ad..580ce10e2 100644
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -659,8 +659,15 @@ The `JobSystem` persists checkpoint state after every completed page:
- `completed_page_ids` — list of already-generated page IDs
- `failed_page_ids` — pages that failed (retried on resume)
-On `repowise init --resume`, the job is loaded from the database, completed pages
-are skipped, and generation continues from the last checkpoint.
+On `repowise init --resume`, the set of already-written pages is read from the
+vector store rather than from the checkpoint, because the store is the one
+record that survives a killed process. This needs a job system and a store; with
+neither, a resumed run falls back to regenerating everything. Those page ids are
+skipped before their
+coroutine is built, so a resumed run spends nothing on them, and the match is on
+page id alone: a run resumed under a different provider still keeps what the
+previous one wrote. Persistence is told which ids were skipped so the stale-page
+sweep does not mistake "deliberately kept" for "no longer produced".
`repowise init` is fully idempotent. Running it twice produces the same result.
Running it after a partial previous run completes only the remaining pages.
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 528126bff..691501214 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -85,7 +85,7 @@ All three reach the indexing knobs; the LLM-only knobs appear only when model-wr
| `--harvest-decisions` / `--no-harvest-decisions` | Harvest architectural decisions during page generation (verified against source before storage). Default: on. |
| `--wiki-style` | Documentation voice/density: `comprehensive` (default), `caveman` (token-condensed, AI-first), `reference` (API-manual), `tutorial` (beginner-friendly). Interactive full runs prompt when omitted. Saved to config so `update` keeps the style. See [WIKI_STYLES.md](../layers/WIKI_STYLES.md). |
| `--language` | Output language for generated wiki pages: `en` (default), `ar`, `de`, `es`, `fr`, `hi`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ru`, `tr`, `zh`. Code, file paths, and symbol names stay untranslated. Saved to config so `update` keeps the language. Also asked in advanced interactive mode. To switch an existing wiki's language, set the flag and re-run `init --force`. |
-| `--resume` | Resume from the last checkpoint if interrupted |
+| `--resume` | Continue a previous run instead of redoing it: completed phases (indexing, analysis) are skipped, the earlier run's git tier is kept, and generation writes only the pages this repo does not have yet. Use it after an interrupted run, and after one that finished with failed pages (a provider outage, rate limiting) — pages already written are skipped with no model call, so nothing is paid for twice. Matching is per page, not per model, so switching provider still keeps what the old one wrote. |
| `--force` | Regenerate all pages even if they exist |
| `--commit-limit` | Max commits to analyze per file (default: 500, capped at 10000) |
| `--follow-renames` | Track file renames in git history |
diff --git a/docs/start/USER_GUIDE.md b/docs/start/USER_GUIDE.md
index a70836144..e908bbb7c 100644
--- a/docs/start/USER_GUIDE.md
+++ b/docs/start/USER_GUIDE.md
@@ -456,6 +456,13 @@ validate on 10 files, and `--skip-tests --skip-infra` to cut scope. Lower
**init was interrupted**
`repowise init --resume` picks up from the last checkpoint.
+**init finished but some pages are missing**
+A provider outage or rate limit can fail individual pages while the run itself
+completes. `repowise init --resume` writes only the pages that are absent and
+skips every page you already have, with no model call for them. It matches on
+the page, not on which model wrote it, so switching provider after an outage
+still keeps the pages the old one produced.
+
**Vector store looks corrupted**
`repowise reindex` rebuilds it from the existing wiki pages, with no LLM calls.
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
index dd974e423..698993589 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/generation.py
@@ -198,7 +198,9 @@ def run_repo_generation(
generation wrapper, enriches the KG, and flushes buffered cost rows in one
transaction (kept out of the contended generation window, issue #326).
- Mutates ``result`` in place with ``generated_pages`` and ``vector_store``
+ Mutates ``result`` in place with ``generated_pages``, ``preserved_page_ids``
+ (the pages a resumed run skipped, which persistence must not sweep) and
+ ``vector_store``
(the latter is shared so the Phase-2C decision dedup matches + embeds
decisions into the same store the pages land in). Returns the pages.
@@ -242,6 +244,18 @@ def run_repo_generation(
if not deterministic:
columns.append(TextColumn("[green]${task.fields[cost]:.3f}[/green]"))
+ # Filled by a resumed run with the pages it skipped because they already
+ # exist. Persistence needs them: they are absent from ``generated_pages``,
+ # and the stale sweep reads absence as "delete me" (issue #1089).
+ #
+ # Attached to the result BEFORE generation runs, not after. The workspace
+ # flow catches a generation failure and persists anyway, so an assignment
+ # that trails the run would hand the sweep an empty set on exactly the
+ # broken runs this exists to protect. Same object, so what the run fills in
+ # is what persistence reads however the block exits.
+ preserved_page_ids: set[str] = set()
+ result.preserved_page_ids = preserved_page_ids
+
with Progress(*columns, console=console) as gen_progress:
gen_callback = RichProgressCallback(gen_progress, console)
generated_pages = run_async(
@@ -259,6 +273,7 @@ def run_repo_generation(
concurrency=concurrency,
progress=gen_callback,
resume=resume,
+ preserved_page_ids=preserved_page_ids,
cost_tracker=cost_tracker,
generation_config=gen_config,
# In-memory curated modules: on a fresh init the
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 c385b4436..dce4d194d 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/persistence.py
@@ -11,6 +11,8 @@ from __future__ import annotations
from pathlib import Path
from typing import Any
+import structlog
+
from repowise.cli._repo_session import open_repo_db
from repowise.cli.helpers import (
config_fingerprint,
@@ -23,6 +25,8 @@ 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
+logger = structlog.get_logger(__name__)
+
async def build_resume_controller(repo_path: Path, *, resume: bool) -> tuple[Any, Any]:
"""Create the repo row + a ResumeController bound to a fresh engine.
@@ -39,6 +43,52 @@ async def build_resume_controller(repo_path: Path, *, resume: bool) -> tuple[Any
return ResumeController(sf, repo_id, resume=resume), engine
+# Chunk size for the preserved-page FTS backfill — keeps the IN (...) below
+# under SQLite's host-parameter limit and bounds how much page content is held
+# in memory at once.
+_FTS_BACKFILL_CHUNK = 200
+
+
+async def _index_preserved_pages(sf: Any, fts: Any, preserved_page_ids: set[str] | None) -> None:
+ """Full-text index the pages a resumed run kept rather than regenerated.
+
+ ``page_fts`` is a standalone FTS5 table with no triggers: a row appears
+ only when something calls :meth:`FullTextSearch.index`. The incremental
+ flush during generation writes SQL and nothing else, so a run killed before
+ its final persist leaves pages that exist in ``wiki_pages`` and are absent
+ from search. Those are exactly the pages a resume preserves, which would
+ make "your pages were kept" true in the database and false in every search
+ that goes looking for them.
+
+ Reads title + content back from SQL because a preserved page was never in
+ this run's memory. ``index`` is delete-then-insert, so re-indexing a page
+ that already had a row is a no-op in effect. Best-effort: search being
+ stale must never fail a run whose pages are already committed.
+ """
+ if fts is None or not preserved_page_ids:
+ return
+
+ from sqlalchemy import select
+
+ from repowise.core.persistence import get_session
+ from repowise.core.persistence.models import Page
+
+ ids = sorted(preserved_page_ids)
+ try:
+ for i in range(0, len(ids), _FTS_BACKFILL_CHUNK):
+ batch = ids[i : i + _FTS_BACKFILL_CHUNK]
+ async with get_session(sf) as session:
+ rows = (
+ await session.execute(
+ select(Page.id, Page.title, Page.content).where(Page.id.in_(batch))
+ )
+ ).all()
+ for page_id, title, content in rows:
+ await fts.index(page_id, title or "", content or "")
+ except Exception as exc: # pragma: no cover - defensive
+ logger.debug("persist.preserved_fts_backfill_failed", error=str(exc))
+
+
async def persist_result(result: Any, repo_path: Path) -> None:
"""Persist a PipelineResult to the local SQLite database.
@@ -101,12 +151,15 @@ async def persist_result(result: Any, repo_path: Path) -> None:
# forever. A type is swept when the run produced pages of it OR
# declared authority over it (curated runs are authoritative for
# module/layer pages even when every module page was skipped as
- # 1:1 with a layer); types that are neither stay protected.
+ # 1:1 with a layer); types that are neither stay protected. Pages a
+ # resumed run skipped count as reproduced — they are absent from
+ # ``generated_pages`` precisely because they already exist.
swept_page_ids = await sweep_stale_generated_pages(
session,
repo.id,
result.generated_pages,
getattr(result, "authoritative_page_types", None),
+ getattr(result, "preserved_page_ids", None),
)
else:
swept_page_ids = await persist_pipeline_result(result, session, repo.id)
@@ -147,6 +200,7 @@ async def persist_result(result: Any, repo_path: Path) -> None:
if fts is not None and result.generated_pages:
for page in result.generated_pages:
await fts.index(page.page_id, page.title, page.content)
+ await _index_preserved_pages(sf, fts, getattr(result, "preserved_page_ids", None))
# Stamp the analysis (+ generation) phases in the resume ledger now that
# they're persisted, so a future resume can skip them too.
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index 362cea72b..f063a98a5 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -219,6 +219,7 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
kg_modules: list[dict] | None = None,
kg_data: dict | None = None,
only_page_ids: set[str] | None = None,
+ preserved_page_ids: set[str] | None = None,
) -> list[GeneratedPage]:
"""Generate all wiki pages for a repository.
@@ -233,6 +234,12 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
one. This is the scoped-generation primitive behind ``repowise
generate`` and the fix for callers that used to regenerate ten
repo-wide pages as a side effect of asking for one file page.
+
+ ``preserved_page_ids`` is an out-parameter: a ``resume`` run adds to it
+ every page id it skipped because a prior run already produced it. The
+ caller hands the set to persistence, which must not sweep those ids as
+ stale. Harmless to pass on a non-resume run (nothing is skipped for that
+ reason, so nothing is added); None when the caller has no use for it.
"""
from .orchestrate import run_generate_all
@@ -257,6 +264,7 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
kg_modules=kg_modules,
kg_data=kg_data,
only_page_ids=only_page_ids,
+ preserved_page_ids=preserved_page_ids,
)
# ------------------------------------------------------------------
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 bb3a0e8ae..a9f490ab3 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -67,6 +67,7 @@ class _GenerationRun:
kg_modules: list[dict] | None = None,
kg_data: dict | None = None,
only_page_ids: set[str] | None = None,
+ preserved_page_ids: set[str] | None = None,
) -> None:
self.gen = gen
self.config = gen._config
@@ -77,6 +78,13 @@ class _GenerationRun:
# parsed and its graph built, so a requested repo-wide page is rendered
# from the complete view. See ``_emit`` for the single choke point.
self.only_page_ids = only_page_ids
+ # Resume: the ids this run skipped because a prior run already wrote
+ # them. Written into the caller's set so persistence can tell "this
+ # page was deliberately kept" from "this page is gone", which is the
+ # difference between a correct sweep and deleting the half of the
+ # wiki the resumed run was there to protect. None when the caller does
+ # not care (every non-resume path).
+ self.preserved_page_ids = preserved_page_ids
self.parsed_files = parsed_files
self.source_map = source_map
self.graph_builder = graph_builder
@@ -198,6 +206,12 @@ class _GenerationRun:
allocates its coroutine.
"""
if page_id in self.completed_ids:
+ # Recorded only here, never for an ``only_page_ids`` miss: a scoped
+ # run legitimately says nothing about the pages it was not asked
+ # for, while a resume skip is a positive statement that the page
+ # already exists and must survive this run's sweep.
+ if self.preserved_page_ids is not None:
+ self.preserved_page_ids.add(page_id)
return False
return self.only_page_ids is None or page_id in self.only_page_ids
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index ff9e84556..20868ea1d 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -147,6 +147,20 @@ class PipelineResult:
on incremental no-KG paths, which preserves degradation honesty (a fallback
run never wipes curated pages it could not reproduce)."""
+ preserved_page_ids: set[str] = field(default_factory=set)
+ """Page ids a ``--resume`` run skipped because a prior run already wrote
+ them. They are absent from ``generated_pages`` by design, so the stale-page
+ sweep would read them as gone and delete the very pages the resume existed
+ to keep (issue #1089). Empty on every non-resume run.
+
+ Filled here for symmetry, but the live route is the other one: ``--resume``
+ only exists on ``init``, which calls ``run_pipeline(generate_docs=False)``
+ and generates separately, so the init flows set this on the result
+ themselves the same way they set ``generated_pages``. No caller currently
+ reaches the assignment below (it needs ``resume`` and ``generate_docs``
+ together), so treat this field's value on a ``run_pipeline`` result as
+ untested until one does."""
+
# ---------------------------------------------------------------------------
# Pipeline
@@ -602,6 +616,8 @@ async def run_pipeline(
# PipelineResult.authoritative_page_types). Stays empty unless generation
# runs below, because a run that generated nothing decided nothing.
authoritative_page_types: set[str] = set()
+ # Filled by generation when resuming; see PipelineResult.preserved_page_ids.
+ preserved_page_ids: set[str] = set()
# DETERMINISTIC supplies its own null provider so a caller with no key can
# still get a wiki. Scoped to this phase rather than assigned over
# ``llm_client``: the analysis phase above shares that client, and its
@@ -715,6 +731,7 @@ async def run_pipeline(
decision_report=gen_decision_report,
external_systems=external_systems,
on_page_ready=on_page_ready,
+ preserved_page_ids=preserved_page_ids,
# In-memory KG — the artifact file is written after generation,
# so it cannot carry layers/tour/modules on a fresh init.
kg_modules=(
@@ -856,6 +873,7 @@ async def run_pipeline(
resume_controller.index_persisted if resume_controller is not None else False
),
authoritative_page_types=authoritative_page_types,
+ preserved_page_ids=preserved_page_ids,
)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 21f028754..294c80208 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -542,6 +542,7 @@ async def _sweep_stale_generated_pages(
repo_id: str,
generated_pages: list[Any] | None,
authoritative_page_types: set[str] | None = None,
+ preserved_page_ids: set[str] | None = None,
) -> list[str]:
"""Delete structurally-keyed generated pages this run did not produce.
@@ -557,6 +558,14 @@ async def _sweep_stale_generated_pages(
claim its history). Returns the swept page ids so the caller can drop them
from FTS after the session closes (the FTS store must not be touched
in-session).
+
+ ``preserved_page_ids`` are ids a ``--resume`` run skipped *because they
+ already exist* (see ``_GenerationRun._emit``). They are absent from
+ ``generated_pages`` by design, which is exactly what "stale" means to the
+ rest of this function, so without this argument a resume that regenerated
+ the missing half of a page type deleted the half it had just protected
+ (issue #1089). A preserved id is as current as a produced one: the id did
+ not drift, which is the only thing this sweep exists to catch.
"""
from sqlalchemy import delete, select
@@ -566,13 +575,24 @@ async def _sweep_stale_generated_pages(
for page in generated_pages or []:
produced.setdefault(page.page_type, set()).add(page.page_id)
authoritative = authoritative_page_types or set()
+ preserved = preserved_page_ids or set()
swept: list[str] = []
for page_type in _SWEPT_GENERATED_PAGE_TYPES:
current = produced.get(page_type)
if not current and page_type not in authoritative:
continue
- current = current or set()
+ # Preserved ids join the current set rather than being subtracted from
+ # the stale one: an authoritative type sweeps even when the run emitted
+ # none of it, and that branch must still keep what a resume stood on.
+ # (Defensive today — no caller sets both — but the two are independent
+ # inputs and the failure mode if they ever meet is a deleted wiki.)
+ # Filtered by type because ``preserved`` spans every page type while
+ # this loop compares against one. Ids happen to be ``type:target`` so
+ # a cross-type match is impossible, but the sweep is the wrong place to
+ # depend on an id format nothing here enforces.
+ prefix = f"{page_type}:"
+ current = (current or set()) | {p for p in preserved if p.startswith(prefix)}
existing = (
(
await session.execute(
@@ -1162,6 +1182,7 @@ async def persist_pipeline_result(
repo_id,
result.generated_pages,
getattr(result, "authoritative_page_types", None),
+ getattr(result, "preserved_page_ids", None),
)
# Placement depends on the whole page set, so it is computed here rather
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index 74e2976d8..df8f14f9f 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -43,6 +43,7 @@ async def run_generation(
kg_modules: list[dict] | None = None,
kg_data: dict | None = None,
only_page_ids: set[str] | None = None,
+ preserved_page_ids: set[str] | None = None,
) -> list[Any]:
"""Run LLM-powered page generation.
@@ -55,6 +56,10 @@ async def run_generation(
``only_page_ids`` scopes the run to an explicit set of page ids (the
``repowise generate`` path). None means the full selection, as before.
+
+ ``preserved_page_ids`` is an out-parameter filled by a ``resume`` run with
+ the ids it skipped because a prior run already wrote them. Persistence
+ needs it to keep those pages out of the stale sweep.
"""
from repowise.core.generation import (
ContextAssembler,
@@ -147,6 +152,7 @@ async def run_generation(
kg_modules=kg_modules,
kg_data=kg_data,
only_page_ids=only_page_ids,
+ preserved_page_ids=preserved_page_ids,
)
# Onboarding summary — count generated slots and surface which ones
diff --git a/tests/integration/test_generation_pipeline.py b/tests/integration/test_generation_pipeline.py
index 7b90d0eec..5c80fcde1 100644
--- a/tests/integration/test_generation_pipeline.py
+++ b/tests/integration/test_generation_pipeline.py
@@ -290,6 +290,56 @@ async def test_embedding_latency_does_not_gate_llm_concurrency():
assert vector_store.max_active_embeds == 1
+async def test_resume_reports_the_pages_it_skipped(tmp_path):
+ """The preserved-id set survives every hand-off down to the generator.
+
+ Issue #1089: persistence deletes structurally-keyed pages a run did not
+ produce, and a resumed run does not produce the pages it skipped. It now
+ reports them instead, but only if the set actually reaches ``_emit`` —
+ ``run_generation`` -> ``generate_all`` -> ``run_generate_all`` is three
+ keyword hand-offs, two of them through ``**kwargs``, where a dropped or
+ misspelled argument fails silently and takes the fix with it.
+ """
+ from repowise.core.pipeline.phases.generation import run_generation
+
+ parsed_files, source_map, repo_structure = _make_concurrency_fixture()
+ builder = GraphBuilder()
+ for parsed in parsed_files:
+ builder.add_file(parsed)
+ builder.build()
+
+ already_written = "file_page:pkg/module_0.py"
+
+ class _StoreWithPriorRun(_SlowVectorStore):
+ async def list_page_ids(self) -> set[str]:
+ return {already_written}
+
+ preserved: set[str] = set()
+ pages = await run_generation(
+ repo_path=tmp_path,
+ parsed_files=parsed_files,
+ source_map=source_map,
+ graph_builder=builder,
+ repo_structure=repo_structure,
+ git_meta_map={},
+ llm_client=MockProvider(),
+ embedder=None,
+ vector_store=_StoreWithPriorRun(delay=0),
+ concurrency=2,
+ progress=None,
+ resume=True,
+ generation_config=GenerationConfig(max_file_pages=0, cache_enabled=False),
+ preserved_page_ids=preserved,
+ )
+
+ # Reported as kept, and genuinely not regenerated.
+ assert already_written in preserved
+ assert already_written not in {page.page_id for page in pages}
+ # The rest of the wiki was still produced, so this is a skip and not a
+ # collapsed run that would look identical from the assertion above.
+ assert "file_page:pkg/module_1.py" in {page.page_id for page in pages}
+
+
# ---------------------------------------------------------------------------
# Test class
# ---------------------------------------------------------------------------
diff --git a/tests/unit/cli/test_persist_result_sweep.py b/tests/unit/cli/test_persist_result_sweep.py
index f8e4ff57e..8c69d745a 100644
--- a/tests/unit/cli/test_persist_result_sweep.py
+++ b/tests/unit/cli/test_persist_result_sweep.py
@@ -56,6 +56,7 @@ def _result(
*,
vector_store=None,
authoritative_page_types: set[str] | None = None,
+ preserved_page_ids: set[str] | None = None,
) -> SimpleNamespace:
"""A minimal PipelineResult stand-in for the ``index_done`` branch.
@@ -74,6 +75,7 @@ def _result(
git_metadata_list=[],
knowledge_graph_result=None,
authoritative_page_types=authoritative_page_types or set(),
+ preserved_page_ids=preserved_page_ids or set(),
)
@@ -225,3 +227,54 @@ async def test_persist_result_curated_zero_modules_sweeps_stale(tmp_path):
assert "layer_page:layer:Data" in ids
finally:
await engine.dispose()
+
+
+async def test_persist_result_keeps_pages_a_resume_skipped(tmp_path):
+ """Issue #1089, through the path the reporter would have taken.
+
+ A provider outage kills part of an init. `repowise init --resume`
+ regenerates the missing pages and skips the ones already written, so the
+ skipped ones are absent from ``generated_pages``. They must survive the
+ sweep, keep their vector embedding, and become searchable — the resume
+ exists to protect exactly this content, and a page nobody can find is not
+ protected in any sense the user would recognise.
+ """
+ repo_path = tmp_path / "repo"
+ repo_path.mkdir()
+ kept_id = "module_page:community-1"
+ await _seed_stale_module_page(repo_path, kept_id)
+
+ # No FTS row is seeded on purpose. A run killed mid-generation flushes
+ # pages to SQL and nothing else, so this is the state a resume actually
+ # finds: the page exists and search has never heard of it. Seeding one here
+ # would assert against a situation the broken flow never produces.
+ store = InMemoryVectorStore(MockEmbedder())
+ regenerated = _generated_page("module_page", "community-2")
+ await store.embed_batch([(kept_id, "kept body about widgets", {})])
+
+ await persist_result(
+ _result("r", [regenerated], vector_store=store, preserved_page_ids={kept_id}),
+ repo_path,
+ )
+
+ engine, sf, _ = await open_repo_db(repo_path, repo_name="r")
+ try:
+ async with get_session(sf) as session:
+ ids = (
+ (await session.execute(select(Page.id).where(Page.page_type == "module_page")))
+ .scalars()
+ .all()
+ )
+ assert set(ids) == {kept_id, "module_page:community-2"}
+
+ # Backfilled from SQL: the seeded row's content is "stale body", which
+ # is all a resume has to go on for a page it did not generate.
+ fts = FullTextSearch(engine)
+ await fts.ensure_index()
+ hits = {r.page_id for r in await fts.search("body", limit=10)}
+ assert kept_id in hits
+ finally:
+ await engine.dispose()
+
+ assert kept_id in await store.list_page_ids()
diff --git a/tests/unit/generation/test_preserved_page_ids.py b/tests/unit/generation/test_preserved_page_ids.py
new file mode 100644
index 000000000..c4fb0c665
--- /dev/null
+++ b/tests/unit/generation/test_preserved_page_ids.py
@@ -0,0 +1,74 @@
+"""The ids a resumed run reports as deliberately kept.
+
+Regression for issue #1089. ``--resume`` skips pages a prior run already wrote,
+so they are absent from ``generated_pages``. Persistence reads that absence as
+"this page is gone" and sweeps the structurally-keyed ones, which meant a resume
+sent to repair a half-finished wiki deleted the half that had survived. The run
+now records every id it skipped for that reason, and only that reason.
+
+Only the first test here fails if the fix is reverted. The other three pin the
+negative half of the contract — what must *not* be recorded — which a later
+over-broad change would break and nothing else would catch. The end-to-end
+version, covering the hand-offs between this gate and persistence, lives in
+``tests/integration/test_generation_pipeline.py``.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from repowise.core.generation.page_generator.orchestrate import _GenerationRun
+
+
+def _run(
+ *,
+ completed_ids: set[str],
+ only_page_ids: set[str] | None = None,
+ preserved: set[str] | None,
+) -> SimpleNamespace:
+ return SimpleNamespace(
+ completed_ids=completed_ids,
+ only_page_ids=only_page_ids,
+ preserved_page_ids=preserved,
+ )
+
+
+def test_resume_skip_is_recorded() -> None:
+ preserved: set[str] = set()
+ run = _run(completed_ids={"module_page:community-1"}, preserved=preserved)
+
+ assert _GenerationRun._emit(run, "module_page:community-1") is False
+ assert preserved == {"module_page:community-1"}
+
+
+def test_generated_page_is_not_recorded() -> None:
+ preserved: set[str] = set()
+ run = _run(completed_ids={"module_page:community-1"}, preserved=preserved)
+
+ assert _GenerationRun._emit(run, "module_page:community-2") is True
+ assert preserved == set()
+
+
+def test_scoped_out_page_is_not_recorded() -> None:
+ """A scoped run says nothing about the pages it was not asked for.
+
+ ``repowise generate`` skips most of the wiki by design. Recording those as
+ preserved would be a claim it never made, and the scoped path does not use
+ this sweep anyway (it has ``sweep_superseded_generated_pages``).
+ """
+ preserved: set[str] = set()
+ run = _run(
+ completed_ids=set(),
+ only_page_ids={"module_page:community-1"},
+ preserved=preserved,
+ )
+
+ assert _GenerationRun._emit(run, "module_page:community-2") is False
+ assert preserved == set()
+
+
+def test_no_sink_is_tolerated() -> None:
+ """Every non-resume caller passes None; the gate must not care."""
+ run = _run(completed_ids={"module_page:community-1"}, preserved=None)
+
+ assert _GenerationRun._emit(run, "module_page:community-1") is False
diff --git a/tests/unit/persistence/test_persist_sweep_pages.py b/tests/unit/persistence/test_persist_sweep_pages.py
index 1e55ed752..0e37c0076 100644
--- a/tests/unit/persistence/test_persist_sweep_pages.py
+++ b/tests/unit/persistence/test_persist_sweep_pages.py
@@ -214,3 +214,104 @@ async def test_incremental_no_authority_sweeps_nothing(async_session):
assert swept == []
swept = await _sweep_stale_generated_pages(async_session, repo.id, None, None)
assert swept == []
+
+
+async def test_resumed_pages_are_not_swept(async_session):
+ """Regression for issue #1089.
+
+ A resumed run regenerates the pages a provider outage lost and skips the
+ ones the interrupted run already wrote, so the skipped ones never appear in
+ ``generated_pages``. Read as "not reproduced" they were deleted, which
+ turned the command that repairs a broken wiki into the one that finished
+ breaking it. A preserved id is as current as a produced one.
+ """
+ repo = await insert_repo(async_session)
+ # Three module pages survived the first run; the resumed run rewrites only
+ # the fourth, which the outage had killed.
+ for ordinal in (1, 2, 3):
+ async_session.add(_page_row(repo.id, "module_page", f"community-{ordinal}"))
+ async_session.add(_page_row(repo.id, "layer_page", "layer:Core"))
+ await async_session.flush()
+
+ swept = await _sweep_stale_generated_pages(
+ async_session,
+ repo.id,
+ [_generated("module_page", "community-4")],
+ set(),
+ {f"module_page:community-{i}" for i in (1, 2, 3)} | {"layer_page:layer:Core"},
+ )
+ await async_session.commit()
+
+ assert swept == []
+ remaining = (
+ (await async_session.execute(select(Page.id).where(Page.repository_id == repo.id)))
+ .scalars()
+ .all()
+ )
+ assert set(remaining) == {
+ "module_page:community-1",
+ "module_page:community-2",
+ "module_page:community-3",
+ "layer_page:layer:Core",
+ }
+
+
+async def test_preserved_ids_do_not_shield_genuinely_stale_rows(async_session):
+ """Preserving is per id, not per type.
+
+ A resumed run that kept two module pages and dropped a third (its cluster
+ ordinal drifted) must still retire the third. Otherwise the fix would trade
+ one bug for the duplicate-stranding the sweep exists to prevent.
+ """
+ repo = await insert_repo(async_session)
+ async_session.add(_page_row(repo.id, "module_page", "community-1"))
+ async_session.add(_page_row(repo.id, "module_page", "community-2"))
+ async_session.add(_page_row(repo.id, "module_page", "community-155"))
+ await async_session.flush()
+
+ swept = await _sweep_stale_generated_pages(
+ async_session,
+ repo.id,
+ [_generated("module_page", "community-9")],
+ set(),
+ {"module_page:community-1", "module_page:community-2"},
+ )
+ await async_session.commit()
+
+ assert swept == ["module_page:community-155"]
+ remaining = (
+ (await async_session.execute(select(Page.id).where(Page.repository_id == repo.id)))
+ .scalars()
+ .all()
+ )
+ assert set(remaining) == {"module_page:community-1", "module_page:community-2"}
+
+
+async def test_authoritative_empty_type_still_keeps_preserved_pages(async_session):
+ """Authority plus resume: retire the unclaimed, keep what the resume stood on.
+
+ An authoritative type sweeps even when the run emitted none of it, which is
+ the one path that could still delete every layer page on a resume. The
+ preserved set has to win there too.
+ """
+ repo = await insert_repo(async_session)
+ async_session.add(_page_row(repo.id, "layer_page", "layer:Core"))
+ async_session.add(_page_row(repo.id, "layer_page", "layer:Gone"))
+ await async_session.flush()
+
+ swept = await _sweep_stale_generated_pages(
+ async_session,
+ repo.id,
+ [],
+ {"layer_page"},
+ {"layer_page:layer:Core"},
+ )
+ await async_session.commit()
+
+ assert swept == ["layer_page:layer:Gone"]
+ remaining = (
+ (await async_session.execute(select(Page.id).where(Page.repository_id == repo.id)))
+ .scalars()
+ .all()
+ )
+ assert set(remaining) == {"layer_page:layer:Core"}