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.

feat(upgrade): store-format versioning + reindex-free upgrade core (#553)

Raghav Chamadiyaf366cdc175f4
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 2a5bea4cf..c5e01bbd7 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -12,6 +12,7 @@ from __future__ import annotations
import time
import click
+import structlog
from repowise.cli.helpers import (
acquire_update_lock,
@@ -57,6 +58,8 @@ from .reporting import (
)
from .workspace import _workspace_update
+log = structlog.get_logger(__name__)
+
@click.command("update")
@click.argument("path", required=False, default=None)
@@ -343,6 +346,29 @@ def update_command(
atexit.register(release_update_lock, repo_path)
atexit.register(clear_update_queued, repo_path)
+ # --- Store-format upgrade assessment --------------------------------
+ # Single decision point for "does upgrading repowise need to touch this
+ # store". Runs any no-LLM auto actions (e.g. re-embed after an embedding
+ # model change); reindex is only ever recommended, never forced here.
+ # Placed after the single-flight lock so an auto re-embed (a full vector
+ # rebuild) can't race a concurrent update. Best-effort: the upgrade layer
+ # must never block a routine update.
+ try:
+ from repowise.cli.upgrade import apply_upgrade, assess_store
+
+ verdict = assess_store(repo_path)
+ if not verdict.is_noop:
+ if verdict.reindex_recommended and verdict.reindex_command:
+ console.print(f"[yellow]Reindex recommended:[/yellow] {verdict.reindex_command}")
+ if verdict.user_notice:
+ console.print(f"[dim]{verdict.user_notice}[/dim]")
+ if verdict.actions and not dry_run:
+ for action in verdict.actions:
+ console.print(f"[dim]Upgrade: {action.reason}[/dim]")
+ run_async(apply_upgrade(repo_path, verdict))
+ except Exception as exc: # never block a routine update on the upgrade layer
+ log.debug("store_upgrade_skipped", error=str(exc))
+
render_header(repo_path, base_ref, head)
from repowise.core.ingestion import ChangeDetector
diff --git a/packages/cli/src/repowise/cli/helpers.py b/packages/cli/src/repowise/cli/helpers.py
index 10d18953a..e0762151f 100644
--- a/packages/cli/src/repowise/cli/helpers.py
+++ b/packages/cli/src/repowise/cli/helpers.py
@@ -183,8 +183,20 @@ def load_state(repo_path: Path) -> dict[str, Any]:
def save_state(repo_path: Path, state: dict[str, Any]) -> None:
- """Write *state* to ``.repowise/state.json``."""
+ """Write *state* to ``.repowise/state.json``.
+
+ Every persist stamps the store-format markers (``store_format_version`` and
+ the ``written_by_version`` package version that wrote it) so the upgrade
+ layer always has a current record of the store's shape and provenance.
+ """
ensure_repowise_dir(repo_path)
+ try:
+ from repowise.cli import __version__ as _pkg_version
+ from repowise.core.upgrade import stamp as _stamp_store_version
+
+ _stamp_store_version(state, package_version=_pkg_version)
+ except Exception: # never let stamping block a persist
+ pass
state_path = get_repowise_dir(repo_path) / STATE_FILENAME
state_path.write_text(json.dumps(state, indent=2), encoding="utf-8")
@@ -347,9 +359,7 @@ def write_update_queued(repo_path: Path, head: str | None) -> None:
return
payload = {"target_commit": head, "queued_at": time.time()}
try:
- _update_queued_path(repo_path).write_text(
- json.dumps(payload), encoding="utf-8"
- )
+ _update_queued_path(repo_path).write_text(json.dumps(payload), encoding="utf-8")
except OSError:
pass
@@ -841,6 +851,7 @@ def validate_provider_config(provider_name: str | None = None) -> list[str]:
if provider_name == "opencode":
import shutil
+
if not shutil.which("opencode"):
warnings.append(
"Provider 'opencode' requires the opencode CLI.\n"
@@ -1061,7 +1072,9 @@ def resolve_command_target(
raise click.UsageError("--workspace and --no-workspace are mutually exclusive.")
if repo_alias is not None and no_workspace_flag:
- raise click.UsageError("--repo <alias> implies workspace mode, but --no-workspace was passed.")
+ raise click.UsageError(
+ "--repo <alias> implies workspace mode, but --no-workspace was passed."
+ )
explicit_path = path is not None
base_path = resolve_repo_path(path)
@@ -1100,14 +1113,12 @@ def resolve_command_target(
ws_config = _load_ws(ws_root)
if ws_config is None:
raise WorkspaceNotFound(
- f"Found workspace config at {ws_root} but couldn't load it. "
- "Is it valid YAML?"
+ f"Found workspace config at {ws_root} but couldn't load it. Is it valid YAML?"
)
if repo_alias is not None and ws_config.get_repo(repo_alias) is None:
available = ", ".join(ws_config.repo_aliases()) or "(none)"
raise click.UsageError(
- f"Unknown repo alias '{repo_alias}' in workspace. "
- f"Available: {available}"
+ f"Unknown repo alias '{repo_alias}' in workspace. Available: {available}"
)
reason = "via --workspace flag" if workspace_flag else f"via --repo {repo_alias}"
return CommandTarget(
diff --git a/packages/cli/src/repowise/cli/upgrade.py b/packages/cli/src/repowise/cli/upgrade.py
new file mode 100644
index 000000000..16e08ae28
--- /dev/null
+++ b/packages/cli/src/repowise/cli/upgrade.py
@@ -0,0 +1,89 @@
+"""CLI-side execution of the core upgrade decision layer.
+
+:mod:`repowise.core.upgrade` decides *what* an upgrade needs; this module is the
+edge that *executes* the no-LLM auto actions (it knows how to build embedders
+and where the parse cache lives) and assembles the inputs ``assess`` needs from
+the on-disk store. CLI commands call :func:`assess_store` to get a verdict and
+:func:`apply_upgrade` to run any automatic, never-destructive steps.
+
+Reindex is only ever recommended via the verdict, never run here.
+
+Not to be confused with :mod:`repowise.cli.commands.upgrade_flow`, which is the
+*index-tier* upgrade (``update --full``: fast -> full). This module is the
+*store-format* upgrade across repowise versions.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import structlog
+
+from repowise.core.upgrade import (
+ UpgradeContext,
+ UpgradeVerdict,
+ apply_auto,
+ assess,
+)
+
+from .helpers import REPOWISE_DIR, load_config, load_state
+
+log = structlog.get_logger(__name__)
+
+
+class _CliUpgradeContext:
+ """Concrete :class:`UpgradeContext` backed by the CLI provider stack."""
+
+ def __init__(self, repo_path: Path) -> None:
+ self._repo_path = repo_path
+
+ async def reembed_vectors(self) -> None:
+ # Reuse the exact reindex path: rebuild vectors from existing wiki
+ # pages with the resolved embedder. No LLM calls, only embedding calls.
+ from .commands.reindex_cmd import _reindex
+
+ await _reindex(self._repo_path, "auto", 20)
+
+ def drop_parse_cache(self) -> None:
+ cache = self._repo_path / REPOWISE_DIR / "parse_cache.pkl"
+ if cache.exists():
+ cache.unlink()
+
+
+def _current_embedding_model() -> str | None:
+ """The embedding model the running build would resolve right now."""
+ try:
+ from .providers.embedders import resolve_embedder, resolve_embedding_model
+
+ return resolve_embedding_model(resolve_embedder(None))
+ except Exception:
+ return None
+
+
+def assess_store(repo_path: Path) -> UpgradeVerdict:
+ """Assess what upgrading this store to the running build requires.
+
+ Pure read: loads ``state.json`` + ``config.yaml`` and the currently
+ resolved embedding model, then defers the decision to the core layer.
+ """
+ state = load_state(repo_path)
+ config = load_config(repo_path)
+ recorded_model = config.get("embedding_model")
+ return assess(
+ state,
+ recorded_embedding_model=recorded_model if isinstance(recorded_model, str) else None,
+ current_embedding_model=_current_embedding_model(),
+ )
+
+
+async def apply_upgrade(repo_path: Path, verdict: UpgradeVerdict) -> None:
+ """Run the verdict's automatic (no-LLM) actions. Best-effort, never raises."""
+ if not verdict.actions:
+ return
+ ctx: UpgradeContext = _CliUpgradeContext(repo_path)
+ ran = await apply_auto(verdict, ctx)
+ if ran:
+ log.info("upgrade_applied", actions=[str(k) for k in ran])
+
+
+__all__ = ["apply_upgrade", "assess_store"]
diff --git a/packages/core/src/repowise/core/ingestion/parse_cache.py b/packages/core/src/repowise/core/ingestion/parse_cache.py
index aec7d78f6..7d08566db 100644
--- a/packages/core/src/repowise/core/ingestion/parse_cache.py
+++ b/packages/core/src/repowise/core/ingestion/parse_cache.py
@@ -5,8 +5,9 @@ re-parses the whole repo when one file changed, and large-repo inits pay
minutes of tree-sitter time. A ParsedFile is a pure function of the file
*bytes* and the parser itself, so it caches safely keyed by
``(relative path, content hash)`` under a parser fingerprint (the compiled
-``.scm`` query sources + the package version) that invalidates the whole
-cache when extraction rules change.
+``.scm`` query sources + ``PARSER_SCHEMA_VERSION``) that invalidates the whole
+cache when extraction rules change. The fingerprint excludes the package
+version on purpose so unrelated releases keep the cache warm.
Entries are stored as pickle *bytes* snapshotted at parse time — downstream
graph builds mutate ParsedFile in place (``Import.resolved_file``,
@@ -48,18 +49,21 @@ __all__ = ["ParseCache", "parser_fingerprint"]
def parser_fingerprint() -> str:
"""Fingerprint of everything that determines a ParsedFile besides bytes.
- Hashes every ``.scm`` query source (extraction rules) plus the package
- version (parser/extractor code changes ship as releases). A mismatch
- invalidates the whole cache — correctness over reuse.
+ Hashes every ``.scm`` query source (extraction rules) plus
+ ``PARSER_SCHEMA_VERSION`` (Python-side extraction logic). Deliberately
+ *not* the package ``__version__``: an unrelated release must not churn a
+ user's whole parse cache. The schema version is bumped only when parser /
+ extractor behaviour actually changes, so a mismatch still invalidates the
+ cache when correctness demands it. See :mod:`repowise.core.upgrade.version`.
"""
h = hashlib.sha256()
h.update(f"cache-version:{_CACHE_VERSION}".encode())
try:
- from repowise.core import __version__
+ from repowise.core.upgrade.version import PARSER_SCHEMA_VERSION
- h.update(f"version:{__version__}".encode())
+ h.update(f"parser-schema:{PARSER_SCHEMA_VERSION}".encode())
except Exception:
- h.update(b"version:unknown")
+ h.update(b"parser-schema:unknown")
queries_dir = Path(__file__).parent / "queries"
try:
for scm in sorted(queries_dir.glob("*.scm")):
diff --git a/packages/core/src/repowise/core/upgrade/__init__.py b/packages/core/src/repowise/core/upgrade/__init__.py
new file mode 100644
index 000000000..6e7eb6f0d
--- /dev/null
+++ b/packages/core/src/repowise/core/upgrade/__init__.py
@@ -0,0 +1,45 @@
+"""Store-format versioning and the upgrade decision layer.
+
+This package is the single source of truth for "what shape is the ``.repowise``
+store, and does upgrading repowise need to touch it." :func:`assess` returns a
+pure :class:`UpgradeVerdict`; the CLI and server present it and (for no-LLM auto
+actions) execute it via :func:`apply_auto`. Reindex is only ever *recommended*,
+never forced.
+"""
+
+from __future__ import annotations
+
+from .manager import UpgradeContext, apply_auto, assess, stamp
+from .registry import MIGRATIONS, Migration, migrations_between
+from .verdict import (
+ UpgradeAction,
+ UpgradeActionKind,
+ UpgradeTier,
+ UpgradeVerdict,
+)
+from .version import (
+ EMBEDDING_MODEL_KEY,
+ PARSER_SCHEMA_VERSION,
+ STORE_FORMAT_VERSION,
+ STORE_FORMAT_VERSION_KEY,
+ WRITTEN_BY_VERSION_KEY,
+)
+
+__all__ = [
+ "EMBEDDING_MODEL_KEY",
+ "MIGRATIONS",
+ "PARSER_SCHEMA_VERSION",
+ "STORE_FORMAT_VERSION",
+ "STORE_FORMAT_VERSION_KEY",
+ "WRITTEN_BY_VERSION_KEY",
+ "Migration",
+ "UpgradeAction",
+ "UpgradeActionKind",
+ "UpgradeContext",
+ "UpgradeTier",
+ "UpgradeVerdict",
+ "apply_auto",
+ "assess",
+ "migrations_between",
+ "stamp",
+]
diff --git a/packages/core/src/repowise/core/upgrade/manager.py b/packages/core/src/repowise/core/upgrade/manager.py
new file mode 100644
index 000000000..c7624642e
--- /dev/null
+++ b/packages/core/src/repowise/core/upgrade/manager.py
@@ -0,0 +1,175 @@
+"""The single decision point for store upgrades.
+
+:func:`assess` is pure: given the persisted ``state`` mapping and the running
+build's versions, it returns an :class:`UpgradeVerdict`. It performs no I/O and
+no side effects, so it is trivially unit-testable and identical whether called
+from the CLI or the server.
+
+:func:`apply_auto` runs the no-LLM auto actions a verdict carries, dispatching
+through an injected :class:`UpgradeContext`. The context lives at the edge (the
+CLI knows how to build embedders and find the parse cache); core stays free of
+those dependencies.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+import structlog
+
+from .registry import migrations_between
+from .verdict import (
+ UpgradeAction,
+ UpgradeActionKind,
+ UpgradeTier,
+ UpgradeVerdict,
+)
+from .version import (
+ STORE_FORMAT_VERSION,
+ STORE_FORMAT_VERSION_KEY,
+ WRITTEN_BY_VERSION_KEY,
+)
+
+log = structlog.get_logger(__name__)
+
+
+@runtime_checkable
+class UpgradeContext(Protocol):
+ """Edge-supplied executor for a verdict's auto actions.
+
+ Each method is best-effort: an executor that cannot perform an action (or
+ fails) should log and return without raising, so a routine ``update`` never
+ breaks on an opportunistic upgrade step.
+ """
+
+ async def reembed_vectors(self) -> None:
+ """Rebuild vector embeddings from existing wiki pages (no LLM)."""
+ ...
+
+ def drop_parse_cache(self) -> None:
+ """Remove the parse cache so the next ingest re-parses from source."""
+ ...
+
+
+def assess(
+ state: Mapping[str, object],
+ *,
+ current_store_version: int = STORE_FORMAT_VERSION,
+ recorded_embedding_model: str | None = None,
+ current_embedding_model: str | None = None,
+) -> UpgradeVerdict:
+ """Decide what (if anything) upgrading this store requires.
+
+ ``state`` is the parsed ``state.json``. Missing version fields mean a legacy
+ store: ``store_format_version`` defaults to 0. The verdict's tier is the max
+ severity across the migrations spanned, escalated by an embedding-model
+ mismatch (which adds a no-LLM re-embed action).
+
+ ``recorded_embedding_model`` is the model the existing vectors were built
+ with (the pinned ``embedding_model`` in ``config.yaml``, its canonical home;
+ callers pass it explicitly). ``current_embedding_model`` is what the running
+ build resolves now; a difference triggers a re-embed.
+ """
+ from_version = _coerce_int(state.get(STORE_FORMAT_VERSION_KEY), default=0)
+ written_by = _coerce_str(state.get(WRITTEN_BY_VERSION_KEY))
+
+ spanned = migrations_between(from_version, current_store_version)
+ tier = UpgradeTier.COMPATIBLE
+ actions: list[UpgradeAction] = []
+ summaries: list[str] = []
+ reindex_command: str | None = None
+ notice_parts: list[str] = []
+
+ for migration in spanned:
+ tier = max(tier, migration.tier)
+ summaries.append(migration.summary)
+ if migration.tier == UpgradeTier.REINDEX_RECOMMENDED:
+ reindex_command = "repowise init --force"
+ notice_parts.append(migration.summary)
+ elif migration.action is not None:
+ actions.append(UpgradeAction(kind=migration.action, reason=migration.summary))
+
+ # Embedding-model mismatch is orthogonal to the format version: a store can
+ # be format-current yet hold vectors from a different embedding model (#426),
+ # which silently degrades search. Re-embedding has no LLM cost, so it is an
+ # AUTO action rather than a reindex recommendation.
+ recorded_model = recorded_embedding_model
+ if recorded_model and current_embedding_model and recorded_model != current_embedding_model:
+ tier = max(tier, UpgradeTier.AUTO)
+ actions.append(
+ UpgradeAction(
+ kind=UpgradeActionKind.REEMBED_VECTORS,
+ reason=(
+ f"embedding model changed ({recorded_model} -> "
+ f"{current_embedding_model}); re-embedding for search parity"
+ ),
+ )
+ )
+
+ user_notice = " ".join(notice_parts) if notice_parts else None
+
+ return UpgradeVerdict(
+ tier=tier,
+ from_store_version=from_version,
+ to_store_version=current_store_version,
+ written_by=written_by,
+ actions=tuple(actions),
+ user_notice=user_notice,
+ reindex_command=reindex_command,
+ summaries=tuple(summaries),
+ )
+
+
+async def apply_auto(verdict: UpgradeVerdict, ctx: UpgradeContext) -> list[UpgradeActionKind]:
+ """Run the verdict's auto actions through *ctx*. Best-effort.
+
+ Returns the kinds that ran successfully. Never raises: a failed auto action
+ is logged and skipped so a routine update is never blocked by it. A
+ ``REINDEX_RECOMMENDED`` verdict carries no actions, so nothing runs — the
+ recommendation is surfaced by the presenter layer, never forced here.
+ """
+ ran: list[UpgradeActionKind] = []
+ for action in verdict.actions:
+ try:
+ if action.kind == UpgradeActionKind.REEMBED_VECTORS:
+ await ctx.reembed_vectors()
+ elif action.kind == UpgradeActionKind.DROP_PARSE_CACHE:
+ ctx.drop_parse_cache()
+ else: # pragma: no cover - defensive; new kinds add a branch
+ log.debug("upgrade_action_unhandled", kind=str(action.kind))
+ continue
+ ran.append(action.kind)
+ log.info("upgrade_auto_action", kind=str(action.kind), reason=action.reason)
+ except Exception as exc:
+ log.warning("upgrade_auto_action_failed", kind=str(action.kind), error=str(exc))
+ return ran
+
+
+def stamp(state: dict[str, object], *, package_version: str | None) -> dict[str, object]:
+ """Write the current store-format markers into *state* in place and return it.
+
+ Called on every persist so the store always records the format and the build
+ that wrote it. ``embedding_model`` is stamped separately by the persistence
+ layer that knows the resolved embedder.
+ """
+ state[STORE_FORMAT_VERSION_KEY] = STORE_FORMAT_VERSION
+ if package_version:
+ state[WRITTEN_BY_VERSION_KEY] = package_version
+ return state
+
+
+def _coerce_int(value: object, *, default: int) -> int:
+ try:
+ return int(value) # type: ignore[arg-type]
+ except (TypeError, ValueError):
+ return default
+
+
+def _coerce_str(value: object) -> str | None:
+ if isinstance(value, str) and value:
+ return value
+ return None
+
+
+__all__ = ["UpgradeContext", "apply_auto", "assess", "stamp"]
diff --git a/packages/core/src/repowise/core/upgrade/registry.py b/packages/core/src/repowise/core/upgrade/registry.py
new file mode 100644
index 000000000..79642f10a
--- /dev/null
+++ b/packages/core/src/repowise/core/upgrade/registry.py
@@ -0,0 +1,68 @@
+"""The append-only registry of store-format migrations.
+
+Each :class:`Migration` describes the upgrade impact of moving the store *to*
+a given :data:`~repowise.core.upgrade.version.STORE_FORMAT_VERSION`. Adding a
+future migration is a single appended entry — there is no control flow to edit,
+which keeps the upgrade path scalable as the format evolves.
+
+A migration applies to a store whose recorded version is ``< to_version`` and
+whose target (the running build) is ``>= to_version``; :func:`migrations_between`
+returns exactly those, in order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from .verdict import UpgradeActionKind, UpgradeTier
+
+
+@dataclass(frozen=True, slots=True)
+class Migration:
+ """One step in the store-format history.
+
+ ``to_version``
+ The store format version this entry introduces.
+ ``tier``
+ The upgrade impact (see :class:`UpgradeTier`).
+ ``summary``
+ One line shown to the user in "what's new" / upgrade notices.
+ ``action``
+ Optional auto action to run for ``AUTO``/``RE_PARSE`` tiers. ``None``
+ for ``COMPATIBLE`` (nothing to do) and ``REINDEX_RECOMMENDED`` (never
+ auto-run — we only inform).
+ """
+
+ to_version: int
+ tier: UpgradeTier
+ summary: str
+ action: UpgradeActionKind | None = None
+
+
+#: Ordered history of store-format migrations. APPEND ONLY — never reorder or
+#: mutate shipped entries; older stores in the wild are assessed against this.
+MIGRATIONS: tuple[Migration, ...] = (
+ # v0 -> v1: the baseline. Legacy stores (no ``store_format_version`` field)
+ # are version 0; reaching v1 needs nothing beyond the additive schema
+ # reconcile that ``init_db`` already performs on every open.
+ Migration(
+ to_version=1,
+ tier=UpgradeTier.COMPATIBLE,
+ summary="Baseline store format (additive schema reconcile is automatic).",
+ action=None,
+ ),
+)
+
+
+def migrations_between(from_version: int, to_version: int) -> Sequence[Migration]:
+ """Return migrations with ``from_version < to_version <= to_version``.
+
+ Ordered ascending by ``to_version``. Empty when the store is already at or
+ ahead of the target (e.g. a store written by a newer repowise opened by an
+ older one — we never downgrade, just report nothing to do).
+ """
+ return tuple(m for m in MIGRATIONS if from_version < m.to_version <= to_version)
+
+
+__all__ = ["MIGRATIONS", "Migration", "migrations_between"]
diff --git a/packages/core/src/repowise/core/upgrade/verdict.py b/packages/core/src/repowise/core/upgrade/verdict.py
new file mode 100644
index 000000000..1baad4c7f
--- /dev/null
+++ b/packages/core/src/repowise/core/upgrade/verdict.py
@@ -0,0 +1,88 @@
+"""Value types describing the outcome of an upgrade assessment.
+
+These are pure data: :class:`UpgradeManager` produces an :class:`UpgradeVerdict`
+and never performs side effects itself. The CLI and server consume the verdict
+as their single source of truth, so neither duplicates upgrade decision logic.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+
+
+class UpgradeTier(enum.IntEnum):
+ """Severity of what an upgrade requires, ordered low to high.
+
+ Ordering matters: when several migrations apply across a version span, the
+ overall tier is the maximum (most severe) of them.
+ """
+
+ #: Nothing to do. Additive schema reconcile (already automatic) covers it.
+ COMPATIBLE = 0
+ #: A no-LLM action runs automatically in-band (e.g. re-embed vectors).
+ AUTO = 1
+ #: The parse cache is rebuilt — cheap, automatic, happens on next ingest.
+ RE_PARSE = 2
+ #: Genuinely breaking. Never auto-run; surface a notice + exact command.
+ REINDEX_RECOMMENDED = 3
+
+
+class UpgradeActionKind(enum.StrEnum):
+ """Auto-runnable actions, dispatched through an injected context.
+
+ Keeping these as opaque kinds (rather than callables) keeps the core
+ decision layer free of any dependency on the CLI provider stack — the
+ executor that knows how to build embedders lives at the edge.
+ """
+
+ #: Re-embed all wiki pages + decisions via the existing reindex path.
+ REEMBED_VECTORS = "reembed_vectors"
+ #: Drop the parse cache so the next ingest re-parses from source.
+ DROP_PARSE_CACHE = "drop_parse_cache"
+
+
+@dataclass(frozen=True, slots=True)
+class UpgradeAction:
+ """One auto action to run, with a human-readable reason."""
+
+ kind: UpgradeActionKind
+ reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class UpgradeVerdict:
+ """The full assessment of upgrading a store to the running version.
+
+ ``tier`` is the headline. ``actions`` are the no-LLM steps an executor
+ should run for ``AUTO``/``RE_PARSE`` tiers. ``user_notice`` and
+ ``reindex_command`` are populated for anything the user should see (most
+ importantly the ``REINDEX_RECOMMENDED`` case, which we only ever inform).
+ """
+
+ tier: UpgradeTier
+ from_store_version: int
+ to_store_version: int
+ written_by: str | None = None
+ actions: tuple[UpgradeAction, ...] = field(default_factory=tuple)
+ user_notice: str | None = None
+ reindex_command: str | None = None
+ #: Concise per-version highlights, filled by the presenter layer (Phase 2).
+ summaries: tuple[str, ...] = field(default_factory=tuple)
+
+ @property
+ def is_noop(self) -> bool:
+ """True when the upgrade needs nothing and warrants no message."""
+ return self.tier == UpgradeTier.COMPATIBLE and not self.actions and not self.user_notice
+
+ @property
+ def reindex_recommended(self) -> bool:
+ return self.tier == UpgradeTier.REINDEX_RECOMMENDED
+
+
+__all__ = [
+ "UpgradeAction",
+ "UpgradeActionKind",
+ "UpgradeTier",
+ "UpgradeVerdict",
+]
diff --git a/packages/core/src/repowise/core/upgrade/version.py b/packages/core/src/repowise/core/upgrade/version.py
new file mode 100644
index 000000000..a7e8c6d62
--- /dev/null
+++ b/packages/core/src/repowise/core/upgrade/version.py
@@ -0,0 +1,55 @@
+"""Authoritative version constants for the on-disk store format.
+
+These two integers are the *single source of truth* for "what shape is the
+``.repowise`` store, and does upgrading repowise need to touch it." They are
+deliberately decoupled from the package ``__version__`` so that ordinary
+releases (which ship code changes but no store-format change) never invalidate
+a user's cached work.
+
+When to bump
+------------
+``STORE_FORMAT_VERSION``
+ Bump by one whenever the *meaning or layout* of the persisted store changes
+ in a way the running code must react to (a new required column the additive
+ reconcile cannot back-fill, a vector-store layout change, a re-derivation
+ that older stores lack). Every bump MUST add a matching entry to
+ :data:`repowise.core.upgrade.registry.MIGRATIONS` declaring its upgrade
+ impact tier. The overwhelming default for a release is to leave this alone.
+
+``PARSER_SCHEMA_VERSION``
+ Bump by one only when parser / extractor logic changes such that a cached
+ ``ParsedFile`` from an older build is no longer correct (tree-sitter query
+ edits are already covered by hashing the ``.scm`` sources; bump this for
+ Python-side extraction changes). Bumping it invalidates the parse cache and
+ forces a cheap, automatic re-parse on the next ingest. Leaving package
+ ``__version__`` out of the fingerprint is the whole point: unrelated
+ releases keep the cache warm.
+"""
+
+from __future__ import annotations
+
+#: Current on-disk store format. Stamped into ``state.json`` as
+#: ``store_format_version`` on every persist. Legacy stores predating this
+#: field are treated as version 0.
+STORE_FORMAT_VERSION: int = 1
+
+#: Current parser/extractor schema. Folded into the parse-cache fingerprint in
+#: place of the package version. See :mod:`repowise.core.ingestion.parse_cache`.
+PARSER_SCHEMA_VERSION: int = 1
+
+#: state.json key holding the store format version that wrote the store.
+STORE_FORMAT_VERSION_KEY = "store_format_version"
+
+#: state.json key holding the package ``__version__`` that last wrote the store.
+WRITTEN_BY_VERSION_KEY = "written_by_version"
+
+#: state.json key holding the embedding model id the vectors were built with.
+EMBEDDING_MODEL_KEY = "embedding_model"
+
+__all__ = [
+ "EMBEDDING_MODEL_KEY",
+ "PARSER_SCHEMA_VERSION",
+ "STORE_FORMAT_VERSION",
+ "STORE_FORMAT_VERSION_KEY",
+ "WRITTEN_BY_VERSION_KEY",
+]
diff --git a/tests/unit/upgrade/__init__.py b/tests/unit/upgrade/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/unit/upgrade/test_cli_executor.py b/tests/unit/upgrade/test_cli_executor.py
new file mode 100644
index 000000000..b5a782ec4
--- /dev/null
+++ b/tests/unit/upgrade/test_cli_executor.py
@@ -0,0 +1,69 @@
+"""Tests for the CLI-side upgrade executor (``repowise.cli.upgrade``).
+
+These cover the edge that ``assess`` itself does not: reading the store's
+``config.yaml`` for the pinned embedding model, the ``UpgradeContext``
+implementation's side effects, and the best-effort resolution of the current
+embedding model.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.cli import upgrade as cliup
+from repowise.cli.helpers import save_config, save_state
+from repowise.core.upgrade import UpgradeActionKind, UpgradeTier
+
+
+def test_assess_store_clean_on_fresh_store(tmp_path: Path):
+ save_state(tmp_path, {"last_sync_commit": "abc"})
+ verdict = cliup.assess_store(tmp_path)
+ # save_state stamps the current format, so a freshly written store is a noop.
+ assert verdict.is_noop
+ assert verdict.tier == UpgradeTier.COMPATIBLE
+
+
+def test_assess_store_detects_embedding_drift(tmp_path: Path, monkeypatch):
+ save_state(tmp_path, {"last_sync_commit": "abc"})
+ save_config(
+ tmp_path,
+ "openai",
+ "gpt-5.4-nano",
+ "openai",
+ embedding_model="text-embedding-3-large",
+ )
+ # Running build now resolves a different model.
+ monkeypatch.setattr(cliup, "_current_embedding_model", lambda: "text-embedding-3-small")
+ verdict = cliup.assess_store(tmp_path)
+ assert verdict.tier == UpgradeTier.AUTO
+ assert any(a.kind == UpgradeActionKind.REEMBED_VECTORS for a in verdict.actions)
+
+
+def test_drop_parse_cache_unlinks_file(tmp_path: Path):
+ cache = tmp_path / ".repowise" / "parse_cache.pkl"
+ cache.parent.mkdir(parents=True)
+ cache.write_bytes(b"stale")
+ ctx = cliup._CliUpgradeContext(tmp_path)
+ ctx.drop_parse_cache()
+ assert not cache.exists()
+
+
+def test_drop_parse_cache_is_noop_when_absent(tmp_path: Path):
+ ctx = cliup._CliUpgradeContext(tmp_path)
+ ctx.drop_parse_cache() # must not raise when the cache file is missing
+
+
+def test_current_embedding_model_swallows_errors(monkeypatch):
+ def _boom(*_a, **_k):
+ raise RuntimeError("no providers")
+
+ monkeypatch.setattr("repowise.cli.providers.embedders.resolve_embedder", _boom, raising=False)
+ assert cliup._current_embedding_model() is None
+
+
+async def test_apply_upgrade_noop_when_no_actions(tmp_path: Path):
+ verdict = cliup.assess_store(tmp_path) # empty store -> noop verdict
+ await cliup.apply_upgrade(tmp_path, verdict) # must not raise / do nothing
diff --git a/tests/unit/upgrade/test_manager.py b/tests/unit/upgrade/test_manager.py
new file mode 100644
index 000000000..fea4b51c7
--- /dev/null
+++ b/tests/unit/upgrade/test_manager.py
@@ -0,0 +1,198 @@
+"""Unit tests for the store-format upgrade decision layer.
+
+``assess`` is pure, so these exercise the full decision matrix directly:
+legacy stores, current stores, embedding-model drift, and the
+recommend-never-force contract for a synthetic breaking migration. ``apply_auto``
+is verified to dispatch through an injected context and to never raise.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.upgrade import (
+ STORE_FORMAT_VERSION,
+ UpgradeAction,
+ UpgradeActionKind,
+ UpgradeTier,
+ UpgradeVerdict,
+ apply_auto,
+ assess,
+ stamp,
+)
+from repowise.core.upgrade import registry as registry_mod
+from repowise.core.upgrade.registry import Migration, migrations_between
+
+# --- assess: version-span tiers ------------------------------------------
+
+
+def test_legacy_store_is_compatible_noop():
+ """A store with no version fields (version 0) reaching v1 needs nothing."""
+ verdict = assess({})
+ assert verdict.from_store_version == 0
+ assert verdict.to_store_version == STORE_FORMAT_VERSION
+ assert verdict.tier == UpgradeTier.COMPATIBLE
+ assert verdict.is_noop
+ assert not verdict.actions
+
+
+def test_current_store_is_noop():
+ verdict = assess({"store_format_version": STORE_FORMAT_VERSION, "written_by_version": "0.21.0"})
+ assert verdict.is_noop
+ assert verdict.written_by == "0.21.0"
+
+
+def test_store_from_future_version_is_noop():
+ """A store written by a newer build (we never downgrade) reports nothing."""
+ verdict = assess({"store_format_version": STORE_FORMAT_VERSION + 5})
+ assert verdict.is_noop
+ assert verdict.tier == UpgradeTier.COMPATIBLE
+
+
+# --- assess: embedding-model drift ---------------------------------------
+
+
+def test_embedding_model_change_triggers_auto_reembed():
+ verdict = assess(
+ {"store_format_version": STORE_FORMAT_VERSION},
+ recorded_embedding_model="text-embedding-3-large",
+ current_embedding_model="text-embedding-3-small",
+ )
+ assert verdict.tier == UpgradeTier.AUTO
+ assert not verdict.is_noop
+ kinds = [a.kind for a in verdict.actions]
+ assert UpgradeActionKind.REEMBED_VECTORS in kinds
+
+
+def test_same_embedding_model_is_noop():
+ verdict = assess(
+ {"store_format_version": STORE_FORMAT_VERSION},
+ recorded_embedding_model="text-embedding-3-large",
+ current_embedding_model="text-embedding-3-large",
+ )
+ assert verdict.is_noop
+
+
+def test_missing_current_embedding_model_does_not_falsely_trigger():
+ """When the running build resolves no model (env unset), do not re-embed."""
+ verdict = assess(
+ {"store_format_version": STORE_FORMAT_VERSION},
+ recorded_embedding_model="text-embedding-3-large",
+ current_embedding_model=None,
+ )
+ assert verdict.is_noop
+
+
+def test_no_recorded_model_means_no_embedding_check():
+ """With no pinned model to compare against, never re-embed."""
+ verdict = assess(
+ {"store_format_version": STORE_FORMAT_VERSION},
+ recorded_embedding_model=None,
+ current_embedding_model="model-b",
+ )
+ assert verdict.is_noop
+
+
+# --- assess: recommend-never-force for breaking migrations ----------------
+
+
+def test_breaking_migration_recommends_reindex_without_actions(monkeypatch):
+ """A REINDEX_RECOMMENDED migration informs only; it carries no auto action."""
+ fake = (
+ Migration(1, UpgradeTier.COMPATIBLE, "baseline"),
+ Migration(2, UpgradeTier.REINDEX_RECOMMENDED, "graph layout changed"),
+ )
+ monkeypatch.setattr(registry_mod, "MIGRATIONS", fake)
+ verdict = assess({"store_format_version": 1}, current_store_version=2)
+ assert verdict.tier == UpgradeTier.REINDEX_RECOMMENDED
+ assert verdict.reindex_recommended
+ assert verdict.reindex_command # a command is surfaced
+ assert verdict.user_notice
+ assert not verdict.actions # never auto-run
+
+
+def test_tier_is_max_across_spanned_migrations(monkeypatch):
+ fake = (
+ Migration(1, UpgradeTier.COMPATIBLE, "baseline"),
+ Migration(2, UpgradeTier.AUTO, "auto step", UpgradeActionKind.DROP_PARSE_CACHE),
+ Migration(3, UpgradeTier.RE_PARSE, "reparse step", UpgradeActionKind.DROP_PARSE_CACHE),
+ )
+ monkeypatch.setattr(registry_mod, "MIGRATIONS", fake)
+ verdict = assess({"store_format_version": 1}, current_store_version=3)
+ assert verdict.tier == UpgradeTier.RE_PARSE
+ assert len(verdict.summaries) == 2 # the two spanned, not the baseline
+
+
+# --- registry helper ------------------------------------------------------
+
+
+def test_migrations_between_is_exclusive_inclusive(monkeypatch):
+ fake = tuple(Migration(v, UpgradeTier.COMPATIBLE, f"v{v}") for v in (1, 2, 3))
+ monkeypatch.setattr(registry_mod, "MIGRATIONS", fake)
+ spanned = migrations_between(1, 3)
+ assert [m.to_version for m in spanned] == [2, 3]
+
+
+# --- stamp ----------------------------------------------------------------
+
+
+def test_stamp_writes_version_markers():
+ state: dict[str, object] = {}
+ stamp(state, package_version="9.9.9")
+ assert state["store_format_version"] == STORE_FORMAT_VERSION
+ assert state["written_by_version"] == "9.9.9"
+
+
+def test_stamp_without_package_version_omits_written_by():
+ state: dict[str, object] = {}
+ stamp(state, package_version=None)
+ assert state["store_format_version"] == STORE_FORMAT_VERSION
+ assert "written_by_version" not in state
+
+
+# --- apply_auto -----------------------------------------------------------
+
+
+class _RecordingContext:
+ def __init__(self, fail: bool = False) -> None:
+ self.reembedded = False
+ self.dropped = False
+ self._fail = fail
+
+ async def reembed_vectors(self) -> None:
+ if self._fail:
+ raise RuntimeError("boom")
+ self.reembedded = True
+
+ def drop_parse_cache(self) -> None:
+ self.dropped = True
+
+
+async def test_apply_auto_dispatches_actions():
+ verdict = UpgradeVerdict(
+ tier=UpgradeTier.AUTO,
+ from_store_version=0,
+ to_store_version=1,
+ actions=(
+ UpgradeAction(UpgradeActionKind.REEMBED_VECTORS, "embedding changed"),
+ UpgradeAction(UpgradeActionKind.DROP_PARSE_CACHE, "parser changed"),
+ ),
+ )
+ ctx = _RecordingContext()
+ ran = await apply_auto(verdict, ctx)
+ assert ctx.reembedded and ctx.dropped
+ assert set(ran) == {UpgradeActionKind.REEMBED_VECTORS, UpgradeActionKind.DROP_PARSE_CACHE}
+
+
+async def test_apply_auto_never_raises_on_failure():
+ verdict = UpgradeVerdict(
+ tier=UpgradeTier.AUTO,
+ from_store_version=0,
+ to_store_version=1,
+ actions=(UpgradeAction(UpgradeActionKind.REEMBED_VECTORS, "x"),),
+ )
+ ctx = _RecordingContext(fail=True)
+ ran = await apply_auto(verdict, ctx) # must not raise
+ assert ran == []
diff --git a/tests/unit/upgrade/test_parse_cache_decoupling.py b/tests/unit/upgrade/test_parse_cache_decoupling.py
new file mode 100644
index 000000000..206a27bfe
--- /dev/null
+++ b/tests/unit/upgrade/test_parse_cache_decoupling.py
@@ -0,0 +1,35 @@
+"""The parse-cache fingerprint must be decoupled from the package version.
+
+An ordinary release bumps ``repowise.core.__version__`` but ships no parser
+change; that must NOT invalidate a user's parse cache. A real parser change
+bumps ``PARSER_SCHEMA_VERSION``, which MUST invalidate it.
+"""
+
+from __future__ import annotations
+
+import repowise.core.ingestion.parse_cache as pc
+import repowise.core.upgrade.version as ver
+
+
+def _fresh_fingerprint() -> str:
+ pc.parser_fingerprint.cache_clear()
+ return pc.parser_fingerprint()
+
+
+def test_package_version_change_keeps_cache_warm(monkeypatch):
+ before = _fresh_fingerprint()
+ monkeypatch.setattr("repowise.core.__version__", "999.0.0", raising=False)
+ after = _fresh_fingerprint()
+ assert before == after, "package version must not affect the parse fingerprint"
+
+
+def test_parser_schema_version_change_invalidates_cache(monkeypatch):
+ before = _fresh_fingerprint()
+ monkeypatch.setattr(ver, "PARSER_SCHEMA_VERSION", ver.PARSER_SCHEMA_VERSION + 1)
+ after = _fresh_fingerprint()
+ assert before != after, "parser schema bump must change the fingerprint"
+
+
+def test_fingerprint_is_stable_across_calls():
+ pc.parser_fingerprint.cache_clear()
+ assert pc.parser_fingerprint() == pc.parser_fingerprint()