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(precedent): record structural facts about a checkout at index time (#1317)

Raghav Chamadiyab9df47818ab5
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index 64a266ec1..abdbae4e2 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -1293,6 +1293,9 @@ def init_command(
coverage_report_paths=(
[Path(p) for p in coverage_report] if coverage_report else None
),
+ # Local `init` is the one place a fact about this machine's
+ # environment is a fact about the user's environment.
+ derive_environment_facts=True,
)
finally:
if engine is not None:
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
index 5f639fe0e..0b9db8648 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/workspace.py
@@ -332,6 +332,7 @@ def _ingest_and_generate_repo(repo: Any, idx: int, total: int, ctx: _WorkspaceCt
),
progress=callback,
existing_kg_fingerprint=_prev_kg_fp,
+ derive_environment_facts=True,
)
)
repo_phase_timings: dict[str, float] = callback.timings
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index db18edd93..832a4a26b 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -22,6 +22,7 @@ from collections.abc import Iterable, Iterator
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
+from typing import NamedTuple
import pathspec
import structlog
@@ -62,10 +63,23 @@ class TraversalStats:
skipped_submodule: int = 0
skipped_nested_repo: int = 0
lang_counts: dict[str, int] = field(default_factory=dict)
+ nested_repo_paths: list[str] = field(default_factory=list)
+ """Repo-relative paths of the nested git repos behind ``skipped_nested_repo``.
+
+ The counter alone cannot say *which* directories are separate checkouts,
+ which is what makes the fact actionable ("run git from inside them"). Capped
+ at :data:`_MAX_NESTED_REPO_PATHS` — a memory bound on a pathological tree,
+ not a threshold: the count stays exact either way.
+ """
+ nested_repo_paths_truncated: bool = False
+ """True once the cap above dropped a name, so a reader can say "at least"."""
log = structlog.get_logger(__name__)
+#: Cap on the nested-repo names retained in :class:`TraversalStats`.
+_MAX_NESTED_REPO_PATHS = 50
+
# ---------------------------------------------------------------------------
# Blocklists
# ---------------------------------------------------------------------------
@@ -275,10 +289,13 @@ class FileTraverser:
# module (``repowise-augment = "repowise.cli.augment_hook:main"``)
# has no in-repo importer, so without this it reads as unreachable
# unless its filename happens to match an entry-stem heuristic.
- self._console_script_modules = _collect_console_script_modules(
+ console_scripts = _collect_console_scripts(
self.repo_root,
prune_nested_git=not (include_submodules or include_nested_repos),
)
+ self._console_script_names = console_scripts.names
+ self._console_script_modules = console_scripts.modules
+ self._distributions = console_scripts.distributions
self.stats = TraversalStats()
self._count_lock = threading.Lock()
log.info(
@@ -414,6 +431,10 @@ class FileTraverser:
# to the gitignore/exclude checks below).
if not self._include_nested_repos and not is_submodule and _is_nested_git_repo(abs_path):
self.stats.skipped_nested_repo += 1
+ if len(self.stats.nested_repo_paths) < _MAX_NESTED_REPO_PATHS:
+ self.stats.nested_repo_paths.append(rel_str)
+ else:
+ self.stats.nested_repo_paths_truncated = True
log.debug("Skipping nested git repo", path=rel_str)
return True
if self._gitignore.match_file(rel_str + "/"):
@@ -668,28 +689,46 @@ def _stem_is_entry_point(abs_path: Path) -> bool:
return stem in _ENTRY_POINT_STEMS
-def _collect_console_script_modules(
+class ConsoleScriptTables(NamedTuple):
+ """What one pass over the repo's ``pyproject.toml`` files yields."""
+
+ names: frozenset[str]
+ """Launcher names an installer drops in the environment's script dir."""
+ modules: frozenset[str]
+ """Dotted module targets, used for entry-point detection."""
+ distributions: frozenset[str]
+ """``[project].name`` values — the distributions this repo installs as."""
+
+
+def _collect_console_scripts(
repo_root: Path, *, prune_nested_git: bool = True
-) -> frozenset[str]:
- """Dotted-module targets declared in pyproject console-script tables.
+) -> ConsoleScriptTables:
+ """Console-script names, module targets and distribution names.
Reads ``[project.scripts]``, ``[project.gui-scripts]``, and every
``[project.entry-points.*]`` group from each ``pyproject.toml`` in the
repo. Values look like ``"repowise.cli.augment_hook:main"`` — the part
- before the colon names the module a console launcher imports at runtime.
+ before the colon names the module a console launcher imports at runtime;
+ the key is the launcher an installer drops in the environment's script
+ directory, and ``[project].name`` is the distribution it installs as.
+ All three come out of the same read: entry-point detection wants the
+ modules, shadowed-launcher detection wants the names and needs the
+ distribution to tell this repo's editable install from a dependency's.
Best-effort: unparsable files are skipped.
"""
import tomllib
from repowise.core.fs_walk import iter_glob
+ names: set[str] = set()
modules: set[str] = set()
+ distributions: set[str] = set()
try:
config_files = list(
iter_glob(repo_root, ("pyproject.toml",), prune_nested_git=prune_nested_git)
)
except OSError:
- return frozenset()
+ return ConsoleScriptTables(frozenset(), frozenset(), frozenset())
for config_file in config_files:
try:
data = tomllib.loads(config_file.read_text(encoding="utf-8"))
@@ -698,19 +737,29 @@ def _collect_console_script_modules(
project = data.get("project")
if not isinstance(project, dict):
continue
- groups = [project.get("scripts"), project.get("gui-scripts")]
+ dist = project.get("name")
+ if isinstance(dist, str) and dist.strip():
+ distributions.add(dist.strip())
+ # Only [project.scripts] / [project.gui-scripts] produce a launcher on
+ # PATH; other entry-point groups are plugin registrations, so their
+ # keys are collected as modules only.
+ launcher_groups = [project.get("scripts"), project.get("gui-scripts")]
+ groups = list(launcher_groups)
entry_points = project.get("entry-points")
if isinstance(entry_points, dict):
groups.extend(entry_points.values())
for group in groups:
if not isinstance(group, dict):
continue
- for target in group.values():
+ is_launcher = any(group is g for g in launcher_groups)
+ for name, target in group.items():
+ if is_launcher and isinstance(name, str) and name.strip():
+ names.add(name.strip())
if isinstance(target, str):
module = target.split(":", 1)[0].strip()
if module:
modules.add(module)
- return frozenset(modules)
+ return ConsoleScriptTables(frozenset(names), frozenset(modules), frozenset(distributions))
def _is_console_script_target(rel_path: str, modules: frozenset[str]) -> bool:
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 91a30ef46..0f7c5fd17 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -92,6 +92,16 @@ def build_repo_graph(
file_infos = [fi for fi in maybe_infos if fi is not None]
repo_structure = traverser.get_repo_structure(file_infos)
+ # Structural episodes, minus the formatter check: this path is the hot one
+ # (every update, plus the config-triggered re-score), so it derives only
+ # what the walk has already paid for and never spawns a subprocess.
+ try:
+ from repowise.core.precedent.structural import record_structural_episodes
+
+ record_structural_episodes(repo_path, traverser, allow_formatter_check=False)
+ except Exception:
+ pass
+
# Thread-pool source reads + content-hash parse cache split, shared with
# the init parse phase: only changed files need a tree-sitter parse.
# Cache failures degrade to all-miss (full parse), as before.
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 161b1ebca..67c4f90f9 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -199,6 +199,7 @@ async def run_pipeline(
on_page_ready: Any | None = None,
resume_controller: ResumeController | None = None,
coverage_report_paths: list[Path] | None = None,
+ derive_environment_facts: bool = False,
) -> PipelineResult:
"""Run the repowise indexing/analysis/generation pipeline.
@@ -238,6 +239,14 @@ async def run_pipeline(
generation uses repo-local config such as ``reasoning`` from
``.repowise/config.yaml`` and ``REPOWISE_REASONING``.
+ derive_environment_facts:
+ Derive the structural facts that describe the *machine* this index runs
+ on (currently whether the tree is formatter-clean, which costs one
+ subprocess). Off by default and set only by the local ``init`` command:
+ a hosted or CI indexer would otherwise measure its own container and
+ store the answer as a fact about the user's repository. The facts read
+ off the walk itself are unconditional and unaffected by this flag.
+
Returns
-------
PipelineResult
@@ -303,6 +312,7 @@ async def run_pipeline(
skip_tests=skip_tests,
skip_infra=skip_infra,
progress=progress,
+ derive_environment_facts=derive_environment_facts,
)
# Resume fast-path: when a prior run already persisted the INDEX phase
@@ -331,6 +341,7 @@ async def run_pipeline(
skip_tests=skip_tests,
skip_infra=skip_infra,
progress=progress,
+ derive_environment_facts=derive_environment_facts,
)
traversal_stats = None
git_metadata_list = list(git_meta_map.values())
diff --git a/packages/core/src/repowise/core/pipeline/phases/ingestion.py b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
index 673ab0f5f..a917fce02 100644
--- a/packages/core/src/repowise/core/pipeline/phases/ingestion.py
+++ b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
@@ -84,6 +84,32 @@ _TOP_LANGUAGES_SHOWN = 6
_SLOW_GRAPH_BUILD_FILES = 2000
+async def _record_structural_episodes(
+ repo_path: Path,
+ traverser: Any,
+ *,
+ allow_formatter_check: bool,
+) -> None:
+ """Persist structural episodes for the walk that just finished.
+
+ Imported lazily and swallowed whole: an episode is enrichment, and nothing
+ here may fail or slow an index. Off the event loop because the formatter
+ check is a blocking subprocess with a timeout, and this loop is also
+ driving progress rendering.
+ """
+ try:
+ from repowise.core.precedent.structural import record_structural_episodes
+
+ await asyncio.to_thread(
+ record_structural_episodes,
+ repo_path,
+ traverser,
+ allow_formatter_check=allow_formatter_check,
+ )
+ except Exception:
+ logger.debug("structural_episodes_skipped", exc_info=True)
+
+
def _emit_traversal_summary(
progress: ProgressCallback | None,
stats: Any,
@@ -241,6 +267,7 @@ async def _run_ingestion(
skip_tests: bool,
skip_infra: bool,
progress: ProgressCallback | None,
+ derive_environment_facts: bool = False,
) -> tuple[list[Any], list[Any], Any, dict[str, bytes], Any, Any]:
"""Traverse, parse, and build the dependency graph.
@@ -291,6 +318,15 @@ async def _run_ingestion(
await asyncio.to_thread(io_pool.shutdown, wait=True)
repo_structure = traverser.get_repo_structure(file_infos)
+
+ # Structural episodes ride the walk that just finished — nested-repo names
+ # and console scripts are by-products of it. The one check that describes
+ # the machine rather than the repository is opt-in: this function is the
+ # *full pipeline*, not ``init``, and the workspace updater and the hosted
+ # job executor both reach it.
+ await _record_structural_episodes(
+ repo_path, traverser, allow_formatter_check=derive_environment_facts
+ )
_phase_done(progress, "traverse")
# Filter
@@ -525,6 +561,7 @@ async def reparse_for_resume(
skip_tests: bool,
skip_infra: bool,
progress: ProgressCallback | None,
+ derive_environment_facts: bool = False,
) -> tuple[list[Any], list[Any], Any, dict[str, bytes], list[Any]]:
"""Parse-only ingestion for a resumed run: traverse + parse, **no graph
build or centrality**.
@@ -572,6 +609,12 @@ async def reparse_for_resume(
await asyncio.to_thread(io_pool.shutdown, wait=True)
repo_structure = traverser.get_repo_structure(file_infos)
+ # A resumed run is still the same command: the interrupted one may never
+ # have reached the derivation, so it runs here too rather than leaving a
+ # resumed repo without the facts a fresh one gets.
+ await _record_structural_episodes(
+ repo_path, traverser, allow_formatter_check=derive_environment_facts
+ )
_phase_done(progress, "traverse")
if skip_tests:
diff --git a/packages/core/src/repowise/core/precedent/__init__.py b/packages/core/src/repowise/core/precedent/__init__.py
new file mode 100644
index 000000000..a77f36d2e
--- /dev/null
+++ b/packages/core/src/repowise/core/precedent/__init__.py
@@ -0,0 +1,12 @@
+"""Precedent: dated things that happened to this code, bound to the code.
+
+The episode store (:mod:`repowise.core.precedent.store`) is deliberately
+stdlib-only so hook-time readers can open it without paying for the core
+import graph. Derivation lives beside it, one module per tier.
+"""
+
+from __future__ import annotations
+
+from .store import Episode, EpisodeStore, default_store_path
+
+__all__ = ["Episode", "EpisodeStore", "default_store_path"]
diff --git a/packages/core/src/repowise/core/precedent/store.py b/packages/core/src/repowise/core/precedent/store.py
new file mode 100644
index 000000000..00382d6bf
--- /dev/null
+++ b/packages/core/src/repowise/core/precedent/store.py
@@ -0,0 +1,276 @@
+"""EpisodeStore — one row per dated thing that happened to this repo.
+
+Lives in its own SQLite sidecar (``.repowise/episodes/episodes.db``, WAL)
+rather than wiki.db, the pattern :mod:`repowise.core.distill.store` set and
+:mod:`repowise.core.sessions.staging` already followed: index-time writes
+never contend with hook-time reads, and a corrupt episode index degrades this
+feature rather than the product.
+
+An episode is a claim with a birth, a scope and a body kept whole — which is
+what a metric cannot have. ``tier`` says where it came from and whether it is
+shareable: ``structural`` and ``git`` episodes are facts about the repository
+and travel with it; ``transcript`` episodes are per-machine and never feed a
+stored value another surface reads.
+
+Stdlib only, deliberately: a hook reads this store under a 155 ms budget, and
+that budget has already been lost once to module-level imports.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+EPISODES_DIRNAME = "episodes"
+EPISODES_DB_FILENAME = "episodes.db"
+
+#: Tiers, in availability order. Only the first two are shareable.
+TIER_STRUCTURAL = "structural"
+TIER_GIT = "git"
+TIER_TRANSCRIPT = "transcript"
+
+#: Rows not re-observed for this long are dropped. Every index refreshes
+#: ``last_seen_at`` for a fact that still holds, so this evicts only episodes
+#: whose repository has stopped being indexed — never a live one. (Contrast
+#: the OmissionStore, whose TTL is over *creation* because its rows are a
+#: transient stash.)
+DEFAULT_TTL_DAYS = 90.0
+#: Row-count cap; oldest-seen rows pruned first when exceeded.
+DEFAULT_MAX_ROWS = 5000
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS episodes (
+ id TEXT PRIMARY KEY,
+ tier TEXT NOT NULL,
+ kind TEXT NOT NULL,
+ subject TEXT NOT NULL,
+ body TEXT NOT NULL,
+ evidence TEXT NOT NULL,
+ nodes TEXT NOT NULL,
+ birth_commit TEXT,
+ birth_at REAL NOT NULL,
+ last_seen_at REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_episodes_tier_kind ON episodes(tier, kind);
+CREATE INDEX IF NOT EXISTS idx_episodes_last_seen ON episodes(last_seen_at);
+"""
+
+
+def default_store_path(repo_path: Path | str) -> Path:
+ """Path to *repo_path*'s episode database (not created here)."""
+ return Path(repo_path) / ".repowise" / EPISODES_DIRNAME / EPISODES_DB_FILENAME
+
+
+def episode_id(tier: str, kind: str, subject: str) -> str:
+ """Stable identity for an episode: same claim about the same subject."""
+ raw = "\x00".join((tier, kind, subject)).encode("utf-8")
+ return hashlib.sha256(raw).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Episode:
+ """One dated thing that happened, kept whole.
+
+ ``subject`` discriminates episodes within a kind and is part of the
+ identity, so re-deriving the same fact updates a row instead of adding
+ one. ``nodes`` is the repo-relative file set the claim is bound to — the
+ scope a later staleness query asks git about.
+ """
+
+ tier: str
+ kind: str
+ subject: str
+ body: str
+ evidence: str
+ nodes: tuple[str, ...] = field(default_factory=tuple)
+ birth_commit: str | None = None
+
+ @property
+ def id(self) -> str:
+ return episode_id(self.tier, self.kind, self.subject)
+
+
+class EpisodeStore:
+ """Synchronous SQLite store for episodes.
+
+ Synchronous on purpose, like the OmissionStore and the session staging
+ store: callers are CLI commands, index phases and hooks, where an asyncio
+ loop around SQLite is pure overhead.
+ """
+
+ def __init__(
+ self,
+ db_path: Path,
+ *,
+ ttl_days: float = DEFAULT_TTL_DAYS,
+ max_rows: int = DEFAULT_MAX_ROWS,
+ ) -> None:
+ self.db_path = db_path
+ self.ttl_days = ttl_days
+ self.max_rows = max_rows
+ db_path.parent.mkdir(parents=True, exist_ok=True)
+ self._conn = sqlite3.connect(db_path)
+ self._conn.execute("PRAGMA journal_mode=WAL")
+ self._conn.execute("PRAGMA synchronous=NORMAL")
+ self._conn.execute("PRAGMA busy_timeout=5000")
+ self._conn.executescript(_SCHEMA)
+ self._conn.commit()
+
+ @classmethod
+ def open_for_repo(cls, repo_path: Path | str) -> EpisodeStore:
+ """Open the store for *repo_path*.
+
+ The caller is responsible for checking that the repo opted in (a
+ ``.repowise`` directory exists); this never creates one where a user
+ has not run ``repowise init``.
+ """
+ return cls(default_store_path(repo_path))
+
+ # -- writes ------------------------------------------------------------
+
+ def replace_kinds(
+ self,
+ *,
+ tier: str,
+ kinds: Sequence[str],
+ episodes: Iterable[Episode],
+ now: float | None = None,
+ ) -> int:
+ """Make *kinds* within *tier* say exactly what *episodes* say.
+
+ Upsert-then-sweep rather than delete-then-insert, so ``birth_at``
+ survives on a fact that still holds — an episode whose birth resets on
+ every index is a metric wearing a record's clothes.
+
+ Scoped to *kinds* on purpose: a run that derives only some kinds (an
+ incremental update skips the ones that cost a subprocess) must not
+ delete the episodes it did not look for. Returns rows retired.
+ """
+ if not kinds:
+ return 0
+ stamp = time.time() if now is None else now
+ rows = [
+ (
+ ep.id,
+ ep.tier,
+ ep.kind,
+ ep.subject,
+ ep.body,
+ ep.evidence,
+ json.dumps(list(ep.nodes)),
+ ep.birth_commit,
+ stamp,
+ stamp,
+ )
+ for ep in episodes
+ ]
+ with self._conn: # one transaction: never half-replaced
+ if rows:
+ self._conn.executemany(
+ """
+ INSERT INTO episodes
+ (id, tier, kind, subject, body, evidence, nodes,
+ birth_commit, birth_at, last_seen_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT(id) DO UPDATE SET
+ body = excluded.body,
+ evidence = excluded.evidence,
+ nodes = excluded.nodes,
+ birth_commit = excluded.birth_commit,
+ last_seen_at = excluded.last_seen_at
+ """,
+ rows,
+ )
+ placeholders = ",".join("?" * len(kinds))
+ cur = self._conn.execute(
+ f"DELETE FROM episodes WHERE tier = ? AND kind IN ({placeholders}) "
+ "AND last_seen_at < ?",
+ (tier, *kinds, stamp),
+ )
+ retired = cur.rowcount or 0
+ self.prune(now=stamp)
+ return retired
+
+ def prune(self, *, now: float | None = None) -> None:
+ """Drop rows past TTL, then oldest-seen until under the row cap.
+
+ *now* is the write's own stamp when pruning follows a write: reading
+ the wall clock instead would make a row written microseconds earlier
+ older than the cutoff it is measured against.
+ """
+ cutoff = (time.time() if now is None else now) - self.ttl_days * 86400
+ with self._conn:
+ self._conn.execute("DELETE FROM episodes WHERE last_seen_at < ?", (cutoff,))
+ while True:
+ (rows,) = self._conn.execute("SELECT COUNT(*) FROM episodes").fetchone()
+ # Never evict the last row: it may be the one just written.
+ if rows <= max(self.max_rows, 1) or rows <= 1:
+ break
+ self._conn.execute(
+ """
+ DELETE FROM episodes WHERE id IN (
+ SELECT id FROM episodes ORDER BY last_seen_at ASC
+ LIMIT MIN(64, (SELECT COUNT(*) - 1 FROM episodes))
+ )
+ """
+ )
+
+ # -- reads -------------------------------------------------------------
+
+ def list_episodes(self, *, tier: str | None = None, kind: str | None = None) -> list[dict]:
+ """Episodes, newest birth first. Both filters are optional."""
+ sql = (
+ "SELECT id, tier, kind, subject, body, evidence, nodes, "
+ "birth_commit, birth_at, last_seen_at FROM episodes"
+ )
+ clauses: list[str] = []
+ params: list[object] = []
+ if tier is not None:
+ clauses.append("tier = ?")
+ params.append(tier)
+ if kind is not None:
+ clauses.append("kind = ?")
+ params.append(kind)
+ if clauses:
+ sql += " WHERE " + " AND ".join(clauses)
+ sql += " ORDER BY birth_at DESC, id ASC"
+ return [_row_to_dict(row) for row in self._conn.execute(sql, params)]
+
+ def count(self) -> int:
+ (rows,) = self._conn.execute("SELECT COUNT(*) FROM episodes").fetchone()
+ return int(rows)
+
+ # -- lifecycle ---------------------------------------------------------
+
+ def close(self) -> None:
+ self._conn.close()
+
+ def __enter__(self) -> EpisodeStore:
+ return self
+
+ def __exit__(self, *exc: object) -> None:
+ self.close()
+
+
+def _row_to_dict(row: tuple) -> dict:
+ try:
+ nodes = json.loads(row[6])
+ except (TypeError, ValueError):
+ nodes = []
+ return {
+ "id": row[0],
+ "tier": row[1],
+ "kind": row[2],
+ "subject": row[3],
+ "body": row[4],
+ "evidence": row[5],
+ "nodes": nodes,
+ "birth_commit": row[7],
+ "birth_at": row[8],
+ "last_seen_at": row[9],
+ }
diff --git a/packages/core/src/repowise/core/precedent/structural.py b/packages/core/src/repowise/core/precedent/structural.py
new file mode 100644
index 000000000..27e102390
--- /dev/null
+++ b/packages/core/src/repowise/core/precedent/structural.py
@@ -0,0 +1,498 @@
+"""Structural episodes: facts about the checkout, derived at index time.
+
+These are the only episodes available on a first-ever index of a repository
+with no history, no transcripts and no API key, which is the cold start every
+previous shape of this idea died on.
+
+**No new walk.** Three of the four facts are read off work the ingestion walk
+already did: the nested-repo names come from the traverser's own skip counter
+(:attr:`TraversalStats.nested_repo_paths`), the declared console scripts from
+the ``pyproject.toml`` pass the traverser already runs in ``__init__``, and the
+configuration from :func:`repo_config.load_repo_config`. The formatter check is
+the one genuinely new cost in the module — one subprocess, init only, hard
+timeout, and it degrades to **silence** rather than to a partial count
+presented as a whole one.
+
+Silence is the normal output: a repo where none of these hold emits nothing.
+There is no "no issues found" episode.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .store import TIER_STRUCTURAL, Episode, EpisodeStore
+
+_log = logging.getLogger(__name__)
+
+KIND_NESTED_REPOS = "nested_repos"
+KIND_EDITABLE_SHADOW = "editable_shadow"
+KIND_CONFIG_OVERRIDE = "config_override"
+KIND_FORMATTER_DRIFT = "formatter_drift"
+
+#: Kinds derivable from work that has already happened. Cheap enough for the
+#: update path.
+FREE_KINDS: tuple[str, ...] = (KIND_NESTED_REPOS, KIND_EDITABLE_SHADOW, KIND_CONFIG_OVERRIDE)
+#: Everything, including the kind that costs a subprocess. Init only.
+ALL_KINDS: tuple[str, ...] = (*FREE_KINDS, KIND_FORMATTER_DRIFT)
+
+#: Wall-clock ceiling on the formatter check. Exceeding it yields no episode.
+#: A whole-repo ``ruff format --check .`` over ~2,000 files measures around a
+#: second, so this is generous by an order of magnitude and still far short of
+#: anything a user would notice against a full index.
+FORMATTER_TIMEOUT_S = 10.0
+
+#: Ceiling on the one-shot ``git rev-parse`` that stamps the formatter fact.
+_GIT_TIMEOUT_S = 5.0
+
+#: Nested-repo names quoted in the episode body; the count stays exact.
+_MAX_NAMED_REPOS = 10
+
+#: Repo-local virtualenv directory names. Only in-repo environments are
+#: inspected: ``VIRTUAL_ENV`` on a CI or hosted indexer points at the
+#: *indexer's* environment, and a fact derived from that describes the wrong
+#: machine. Ceiling accepted deliberately — a developer whose venv lives
+#: outside the checkout gets silence, not a wrong episode.
+_VENV_DIRNAMES = (".venv", "venv")
+
+#: Config keys that change what a command does, with the reason each matters.
+#: Keyed on repowise's own config schema, so this carries to any repo.
+_CONFIG_CLAIMS: tuple[tuple[str, str], ...] = (
+ (
+ "exclude_patterns",
+ "files matching these patterns are never indexed, so the index cannot "
+ "answer questions about them and their absence is not evidence they do "
+ "not exist",
+ ),
+ (
+ "mcp.tools",
+ "the MCP tool surface is restricted to this list, so tools outside it "
+ "are unavailable in this repo regardless of what the docs describe",
+ ),
+)
+
+
+def derive_structural_episodes(
+ repo_path: Path | str,
+ traverser: Any,
+ *,
+ allow_formatter_check: bool,
+) -> list[Episode]:
+ """Derive structural episodes for *repo_path* from an exhausted *traverser*.
+
+ *traverser* must be a :class:`~repowise.core.ingestion.FileTraverser` whose
+ walk has already run — the nested-repo names are a by-product of it. Pass
+ ``allow_formatter_check=False`` on any path that is not ``init``.
+
+ Every check is independently best-effort: one that fails contributes
+ nothing and does not stop the others.
+ """
+ root = Path(repo_path)
+ episodes: list[Episode] = []
+ for check, enabled in (
+ (_nested_repos, True),
+ (_editable_shadow, True),
+ (_config_overrides, True),
+ (_formatter_drift, allow_formatter_check),
+ ):
+ if not enabled:
+ continue
+ try:
+ episodes.extend(check(root, traverser))
+ except Exception:
+ # A failing check costs its own fact and nothing else. Logged
+ # because this branch is otherwise indistinguishable from the
+ # fact not holding, which is the normal case.
+ _log.debug("structural check failed: %s", check.__name__, exc_info=True)
+ continue
+ return episodes
+
+
+def record_structural_episodes(
+ repo_path: Path | str,
+ traverser: Any,
+ *,
+ allow_formatter_check: bool,
+) -> int:
+ """Derive and persist structural episodes. Returns the number written.
+
+ A no-op when the repo has not opted in (no ``.repowise`` directory): this
+ never creates one. Best-effort throughout — the episode store is an
+ enrichment, and no failure here may fail an index.
+ """
+ root = Path(repo_path)
+ if not (root / ".repowise").is_dir():
+ return 0
+ kinds = ALL_KINDS if allow_formatter_check else FREE_KINDS
+ try:
+ episodes = derive_structural_episodes(
+ root, traverser, allow_formatter_check=allow_formatter_check
+ )
+ with EpisodeStore.open_for_repo(root) as store:
+ store.replace_kinds(tier=TIER_STRUCTURAL, kinds=kinds, episodes=episodes)
+ return len(episodes)
+ except Exception:
+ return 0
+
+
+# ---------------------------------------------------------------------------
+# 1. Nested and sibling git repositories — free, from the walk's own counter
+# ---------------------------------------------------------------------------
+
+
+def _nested_repos(root: Path, traverser: Any) -> list[Episode]:
+ stats = getattr(traverser, "stats", None)
+ # dict.fromkeys rather than the raw list: the counter and the sink both
+ # accumulate across walks, and a traverser walked twice would otherwise
+ # name every repo twice.
+ walked = sorted(dict.fromkeys(getattr(stats, "nested_repo_paths", ()) or ()))
+ separate = [rel for rel in walked if _is_separate_checkout(root / rel)]
+ if not separate:
+ return []
+ capped = bool(getattr(stats, "nested_repo_paths_truncated", False))
+ named = separate[:_MAX_NAMED_REPOS]
+ listed = ", ".join(named)
+ if len(separate) > len(named):
+ listed += f", and {len(separate) - len(named)} more"
+ count = f"At least {len(separate)}" if capped else str(len(separate))
+ plural = len(separate) != 1
+ body = (
+ f"{count} director{'ies' if plural else 'y'} inside this checkout "
+ f"{'are' if plural else 'is'} a separate git repository: {listed}. "
+ "Run git from inside them rather than from the root — the root's status "
+ "will not show their changes, and they are not indexed as part of this repo. "
+ "Declared submodules and linked worktrees of this same repository are "
+ "excluded; these are independent checkouts."
+ )
+ return [
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind=KIND_NESTED_REPOS,
+ subject=".",
+ body=body,
+ evidence=f"ingestion walk stopped at {len(separate)} nested .git boundaries",
+ nodes=tuple(separate),
+ )
+ ]
+
+
+def _is_separate_checkout(path: Path) -> bool:
+ """True when *path*'s ``.git`` marks a genuinely independent repository.
+
+ The traverser stops at any ``.git`` entry, which is right for indexing and
+ too broad for this claim: a ``.git`` **file** also marks a linked worktree
+ of this same repository and a submodule declared in a nested (rather than
+ root) ``.gitmodules``, neither of which is an independent checkout. The
+ file names its gitdir, so one small read separates the three. A ``.git``
+ directory is always a real repository.
+ """
+ marker = path / ".git"
+ try:
+ if marker.is_dir():
+ return True
+ gitdir = marker.read_text(encoding="utf-8", errors="replace")[:512]
+ except OSError:
+ return False
+ lowered = gitdir.replace("\\", "/").lower()
+ return "/worktrees/" not in lowered and "/modules/" not in lowered
+
+
+# ---------------------------------------------------------------------------
+# 2. An editable install shadowing a console script — half free
+# ---------------------------------------------------------------------------
+
+
+def _editable_shadow(root: Path, traverser: Any) -> list[Episode]:
+ names = getattr(traverser, "_console_script_names", None) or frozenset()
+ distributions = getattr(traverser, "_distributions", None) or frozenset()
+ if not names or not distributions:
+ return []
+ for venv in (root / name for name in _VENV_DIRNAMES):
+ if not venv.is_dir():
+ continue
+ pth = _editable_pth(venv, distributions)
+ if pth is None:
+ continue
+ shadowed = sorted(
+ (name, launcher) for name in names if (launcher := _launcher(venv, name)) is not None
+ )
+ if not shadowed:
+ continue
+ return [
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind=KIND_EDITABLE_SHADOW,
+ subject=name,
+ body=(
+ f"`{name}` is installed as a console script in {venv.name} "
+ f"alongside an editable install ({pth}). Invoking the bare "
+ f"command can run a different copy than the source in this "
+ f"checkout; run the module through the environment's own "
+ f"interpreter (`-m`) when the distinction matters."
+ ),
+ evidence=f"{launcher} beside {pth}",
+ )
+ for name, launcher in shadowed
+ ]
+ return []
+
+
+def _editable_pth(venv: Path, distributions: frozenset[str]) -> str | None:
+ """Name of an editable ``.pth`` for one of *distributions*, or None.
+
+ The distribution match is what makes the claim true rather than merely
+ alarming: a venv with an unrelated dependency installed ``-e`` plus a
+ normally-installed launcher of the same name is not a shadowed checkout,
+ and without this it read as one. Editable ``.pth`` filenames embed the
+ distribution (``__editable__.my_pkg-1.2.pth``), so both sides are
+ normalised the way packaging does before comparing.
+
+ One listing per site-packages directory, bounded by the venv layout —
+ never a tree walk.
+ """
+ wanted = {_normalise_dist(dist) for dist in distributions}
+ wanted.discard("")
+ if not wanted:
+ return None
+ for site in (*venv.glob("Lib/site-packages"), *venv.glob("lib/*/site-packages")):
+ for entry in site.glob("*.pth"):
+ lowered = entry.name.lower()
+ if "editable" not in lowered:
+ continue
+ normalised = _normalise_dist(entry.stem)
+ if any(dist in normalised for dist in wanted):
+ return entry.name
+ return None
+
+
+def _normalise_dist(name: str) -> str:
+ """Fold a distribution or filename to compare across packaging spellings.
+
+ ``my-pkg``, ``my_pkg`` and ``My.Pkg`` are the same distribution, and an
+ editable ``.pth`` may spell it any of those ways.
+ """
+ return "".join(ch for ch in name.lower() if ch.isalnum())
+
+
+def _launcher(venv: Path, name: str) -> str | None:
+ """The launcher *venv* installed for console script *name*, if any."""
+ for scripts_dir, suffixes in ((venv / "Scripts", (".exe", "")), (venv / "bin", ("",))):
+ for suffix in suffixes:
+ candidate = scripts_dir / f"{name}{suffix}"
+ if candidate.is_file():
+ return f"{scripts_dir.name}/{candidate.name}"
+ return None
+
+
+# ---------------------------------------------------------------------------
+# 3. Config that changes what a command does — free, via the loader
+# ---------------------------------------------------------------------------
+
+
+def _config_overrides(root: Path, _traverser: Any) -> list[Episode]:
+ from repowise.core.repo_config import load_repo_config
+
+ config = load_repo_config(root)
+ if not config:
+ return []
+ episodes: list[Episode] = []
+ for key, consequence in _CONFIG_CLAIMS:
+ value = _dotted_get(config, key)
+ if not value:
+ continue
+ episodes.append(
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind=KIND_CONFIG_OVERRIDE,
+ subject=key,
+ body=(
+ f"`{key}` is set in .repowise/config.yaml ({_render(value)}): "
+ f"{consequence}."
+ ),
+ evidence=f".repowise/config.yaml: {key} = {_render(value)}",
+ )
+ )
+ episodes.extend(_disabled_switches(config))
+ return episodes
+
+
+def _disabled_switches(config: dict) -> list[Episode]:
+ """Episodes for boolean blocks a user turned off (hooks, distill)."""
+ episodes: list[Episode] = []
+ for block_name, block in (("hooks", config.get("hooks")), ("distill", config.get("distill"))):
+ off = sorted(_falsy_leaves(block, block_name))
+ if not off:
+ continue
+ episodes.append(
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind=KIND_CONFIG_OVERRIDE,
+ subject=block_name,
+ body=(
+ f"{', '.join(f'`{key}`' for key in off)} "
+ f"{'is' if len(off) == 1 else 'are'} disabled in "
+ f".repowise/config.yaml, so the behaviour they gate does not "
+ f"happen in this repo even where it is documented as default."
+ ),
+ evidence=f".repowise/config.yaml: {', '.join(f'{key} = false' for key in off)}",
+ )
+ )
+ return episodes
+
+
+def _falsy_leaves(value: Any, prefix: str) -> list[str]:
+ """Dotted keys under *prefix* whose value is exactly ``False``."""
+ if not isinstance(value, dict):
+ return []
+ found: list[str] = []
+ for key, leaf in value.items():
+ path = f"{prefix}.{key}"
+ if leaf is False:
+ found.append(path)
+ elif isinstance(leaf, dict):
+ found.extend(_falsy_leaves(leaf, path))
+ return found
+
+
+def _dotted_get(config: dict, dotted: str) -> Any:
+ current: Any = config
+ for part in dotted.split("."):
+ if not isinstance(current, dict):
+ return None
+ current = current.get(part)
+ return current
+
+
+def _render(value: Any) -> str:
+ if isinstance(value, list):
+ shown = ", ".join(str(v) for v in value[:5])
+ return f"{shown}, …" if len(value) > 5 else shown
+ return str(value)
+
+
+# ---------------------------------------------------------------------------
+# 4. Formatter-clean tree — the one new subprocess
+# ---------------------------------------------------------------------------
+
+
+def _formatter_drift(root: Path, _traverser: Any) -> list[Episode]:
+ """One ``ruff format --check`` when the repo declares ruff as its formatter.
+
+ Any failure — no formatter declared, another formatter declared, no
+ executable, a timeout, a crash, unparsable output — yields no episode. A
+ budget that quietly produces a partial count is worse than no fact at all.
+ """
+ if not _declares_ruff_format(root):
+ return []
+ executable = _ruff_executable(root)
+ if executable is None:
+ return []
+ try:
+ completed = subprocess.run(
+ [executable, "format", "--check", "."],
+ cwd=str(root),
+ capture_output=True,
+ text=True,
+ timeout=FORMATTER_TIMEOUT_S,
+ env={**os.environ, "NO_COLOR": "1"},
+ )
+ except (subprocess.TimeoutExpired, OSError):
+ return []
+ if completed.returncode == 0:
+ return [] # clean tree: nothing happened, so there is no episode
+ drifted = [
+ line.split(":", 1)[1].strip()
+ for line in completed.stdout.splitlines()
+ if line.startswith("Would reformat:") and ":" in line
+ ]
+ if not drifted:
+ return [] # non-zero for some other reason — say nothing
+ return [
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind=KIND_FORMATTER_DRIFT,
+ subject="ruff format",
+ body=(
+ f"This tree is not formatter-clean: {len(drifted)} files would be "
+ f"reformatted by `ruff format`. Running it repo-wide produces a large "
+ f"diff unrelated to any change in progress. Format only the files you "
+ f"touched, and check what CI actually enforces before assuming the "
+ f"declared format command is a gate."
+ ),
+ evidence=f"ruff format --check .: {len(drifted)} files would be reformatted",
+ # The count is true of the tree at this commit and of no other. It
+ # is the only structural fact that cannot re-derive itself on an
+ # update (the check is init-only), so it carries its birth and a
+ # reader is expected to stop trusting it once the tree has moved.
+ birth_commit=_head_commit(root),
+ )
+ ]
+
+
+def _declares_ruff_format(root: Path) -> bool:
+ """True when the repo names ruff, and only ruff, as its formatter.
+
+ Deliberately stricter than :func:`detect_build_commands`, whose format
+ inference fires on a ``pyproject.toml`` containing the words "ruff" and
+ "format" anywhere. That is fine for a suggested command and wrong as the
+ premise of a stored fact: ruff-as-linter beside black-as-formatter is a
+ common pairing, and the two disagree, so the inference would tell a
+ black-clean repo it is not formatter-clean by a formatter it never chose.
+ A repo that declares any competing formatter is silent regardless.
+ """
+ pyproject = _read_text(root / "pyproject.toml")
+ if any(marker in pyproject for marker in _COMPETING_FORMATTERS):
+ return False
+ if "[tool.ruff.format]" in pyproject:
+ return True
+ # An explicit invocation anywhere a project records its own commands.
+ for candidate in ("Makefile", "package.json", ".pre-commit-config.yaml", "justfile"):
+ text = _read_text(root / candidate)
+ if "ruff format" in text or "ruff-format" in text:
+ return True
+ return False
+
+
+#: Declaring one of these means the repo formats with something else.
+_COMPETING_FORMATTERS: tuple[str, ...] = ("[tool.black]", "[tool.blue]", "[tool.yapf]")
+
+
+def _read_text(path: Path) -> str:
+ try:
+ return path.read_text(encoding="utf-8", errors="replace")
+ except OSError:
+ return ""
+
+
+def _head_commit(root: Path) -> str | None:
+ """The commit the checkout is on, or None. Best-effort, never fatal."""
+ try:
+ completed = subprocess.run(
+ ["git", "rev-parse", "HEAD"],
+ cwd=str(root),
+ capture_output=True,
+ text=True,
+ timeout=_GIT_TIMEOUT_S,
+ )
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ sha = completed.stdout.strip()
+ return sha if completed.returncode == 0 and sha else None
+
+
+def _ruff_executable(root: Path) -> str | None:
+ """Prefer the checkout's own environment, then PATH."""
+ for venv_name in _VENV_DIRNAMES:
+ for scripts_dir, filename in (
+ (root / venv_name / "Scripts", "ruff.exe"),
+ (root / venv_name / "bin", "ruff"),
+ ):
+ candidate = scripts_dir / filename
+ if candidate.is_file():
+ return str(candidate)
+ return shutil.which("ruff")
diff --git a/tests/unit/precedent/test_environment_fact_gate.py b/tests/unit/precedent/test_environment_fact_gate.py
new file mode 100644
index 000000000..f5e5ab972
--- /dev/null
+++ b/tests/unit/precedent/test_environment_fact_gate.py
@@ -0,0 +1,41 @@
+"""The one check that describes the machine must stay opt-in.
+
+``_run_ingestion`` is the *full pipeline*, not ``init``: the workspace updater
+falls back to it, and so does the hosted job executor. A formatter check run
+there measures the indexer's container and stores the answer as a fact about
+the user's repository, which is the failure mode this gate exists to prevent.
+"""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+
+from repowise.core.pipeline.orchestrator import run_pipeline
+from repowise.core.pipeline.phases.ingestion import _run_ingestion, reparse_for_resume
+
+
+def _default(fn, name: str):
+ return inspect.signature(fn).parameters[name].default
+
+
+def test_pipeline_entry_points_default_to_off() -> None:
+ for fn in (run_pipeline, _run_ingestion, reparse_for_resume):
+ assert _default(fn, "derive_environment_facts") is False, fn.__qualname__
+
+
+def test_only_the_local_init_command_opts_in() -> None:
+ """Anything else that turns this on has to justify itself here first."""
+ cli = Path(__file__).resolve().parents[3] / "packages" / "cli" / "src"
+ core = Path(__file__).resolve().parents[3] / "packages" / "core" / "src"
+ server = Path(__file__).resolve().parents[3] / "packages" / "server" / "src"
+ opted_in = {
+ py.relative_to(py.parents[4]).as_posix()
+ for root in (cli, core, server)
+ for py in root.rglob("*.py") # tests may rglob; src may not
+ if "derive_environment_facts=True" in py.read_text(encoding="utf-8", errors="ignore")
+ }
+ assert opted_in == {
+ "repowise/cli/commands/init_cmd/command.py",
+ "repowise/cli/commands/init_cmd/workspace.py",
+ }, opted_in
diff --git a/tests/unit/precedent/test_episode_store.py b/tests/unit/precedent/test_episode_store.py
new file mode 100644
index 000000000..695779d20
--- /dev/null
+++ b/tests/unit/precedent/test_episode_store.py
@@ -0,0 +1,123 @@
+"""Unit tests for the episode store (``repowise.core.precedent.store``)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.precedent.store import (
+ TIER_STRUCTURAL,
+ Episode,
+ EpisodeStore,
+ default_store_path,
+)
+
+
+def _episode(kind: str = "nested_repos", subject: str = ".", body: str = "a") -> Episode:
+ return Episode(
+ tier=TIER_STRUCTURAL,
+ kind=kind,
+ subject=subject,
+ body=body,
+ evidence="e",
+ nodes=("backend",),
+ )
+
+
+def _store(tmp_path: Path) -> EpisodeStore:
+ (tmp_path / ".repowise").mkdir(exist_ok=True)
+ return EpisodeStore.open_for_repo(tmp_path)
+
+
+class TestReplaceKinds:
+ def test_writes_and_reads_back(self, tmp_path: Path) -> None:
+ with _store(tmp_path) as store:
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]
+ )
+ rows = store.list_episodes(tier=TIER_STRUCTURAL)
+ assert len(rows) == 1
+ assert rows[0]["kind"] == "nested_repos"
+ assert rows[0]["nodes"] == ["backend"]
+
+ def test_rederiving_preserves_birth(self, tmp_path: Path) -> None:
+ """A fact that still holds keeps its birth; only the body may move."""
+ with _store(tmp_path) as store:
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL,
+ kinds=["nested_repos"],
+ episodes=[_episode(body="first")],
+ now=1000.0,
+ )
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL,
+ kinds=["nested_repos"],
+ episodes=[_episode(body="second")],
+ now=2000.0,
+ )
+ rows = store.list_episodes()
+ assert len(rows) == 1
+ assert rows[0]["birth_at"] == 1000.0
+ assert rows[0]["last_seen_at"] == 2000.0
+ assert rows[0]["body"] == "second"
+
+ def test_fact_that_stopped_holding_is_retired(self, tmp_path: Path) -> None:
+ with _store(tmp_path) as store:
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()], now=1000.0
+ )
+ retired = store.replace_kinds(
+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[], now=2000.0
+ )
+ assert retired == 1
+ with _store(tmp_path) as store:
+ assert store.count() == 0
+
+ def test_replace_is_scoped_to_named_kinds(self, tmp_path: Path) -> None:
+ """An update that skips the formatter check must not delete its episode."""
+ with _store(tmp_path) as store:
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL,
+ kinds=["nested_repos", "formatter_drift"],
+ episodes=[_episode(), _episode(kind="formatter_drift", subject="ruff format .")],
+ now=1000.0,
+ )
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL,
+ kinds=["nested_repos"],
+ episodes=[_episode()],
+ now=2000.0,
+ )
+ kinds = {row["kind"] for row in store.list_episodes()}
+ assert kinds == {"nested_repos", "formatter_drift"}
+
+ def test_no_kinds_is_a_no_op(self, tmp_path: Path) -> None:
+ with _store(tmp_path) as store:
+ store.replace_kinds(tier=TIER_STRUCTURAL, kinds=[], episodes=[_episode()])
+ assert store.count() == 0
+
+
+class TestPrune:
+ def test_ttl_drops_only_unseen_rows(self, tmp_path: Path) -> None:
+ (tmp_path / ".repowise").mkdir()
+ with EpisodeStore(default_store_path(tmp_path), ttl_days=0.0) as store:
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]
+ )
+ # Written with a current timestamp, so a zero TTL must not evict it.
+ assert store.count() == 1
+
+ def test_row_cap_never_evicts_the_last_row(self, tmp_path: Path) -> None:
+ (tmp_path / ".repowise").mkdir()
+ with EpisodeStore(default_store_path(tmp_path), max_rows=0) as store:
+ store.replace_kinds(
+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]
+ )
+ assert store.count() == 1
+
+
+class TestPaths:
+ def test_store_path_is_a_sidecar(self, tmp_path: Path) -> None:
+ path = default_store_path(tmp_path)
+ assert path.parent.parent.name == ".repowise"
+ assert path.name == "episodes.db"
+ assert not path.exists() # resolving must not create anything
diff --git a/tests/unit/precedent/test_structural_episodes.py b/tests/unit/precedent/test_structural_episodes.py
new file mode 100644
index 000000000..ac5f448e9
--- /dev/null
+++ b/tests/unit/precedent/test_structural_episodes.py
@@ -0,0 +1,436 @@
+"""Unit tests for structural episode derivation.
+
+Silence is the behaviour under test as much as the facts are: a repo where
+none of these hold must produce an empty store, and a check that cannot answer
+must produce nothing rather than a partial answer.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from types import SimpleNamespace
+
+from repowise.core.ingestion.traverser import FileTraverser
+from repowise.core.precedent import EpisodeStore
+from repowise.core.precedent.structural import (
+ FREE_KINDS,
+ KIND_CONFIG_OVERRIDE,
+ KIND_EDITABLE_SHADOW,
+ KIND_FORMATTER_DRIFT,
+ KIND_NESTED_REPOS,
+ derive_structural_episodes,
+ record_structural_episodes,
+)
+
+
+def _repo(tmp_path: Path) -> Path:
+ (tmp_path / ".repowise").mkdir()
+ (tmp_path / "pkg").mkdir()
+ (tmp_path / "pkg" / "app.py").write_text("x = 1\n", encoding="utf-8")
+ return tmp_path
+
+
+def _traverser(tmp_path: Path) -> FileTraverser:
+ traverser = FileTraverser(tmp_path)
+ list(traverser._walk()) # the derivation reads what the walk left behind
+ return traverser
+
+
+def _kinds(episodes: list) -> set[str]:
+ return {ep.kind for ep in episodes}
+
+
+class TestSilence:
+ def test_plain_repo_emits_nothing(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert episodes == []
+
+ def test_plain_repo_leaves_an_empty_store(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)
+ with EpisodeStore.open_for_repo(repo) as store:
+ assert store.count() == 0
+
+ def test_uninitialised_repo_is_never_given_a_repowise_dir(self, tmp_path: Path) -> None:
+ (tmp_path / "pkg").mkdir()
+ written = record_structural_episodes(
+ tmp_path, _traverser(tmp_path), allow_formatter_check=False
+ )
+ assert written == 0
+ assert not (tmp_path / ".repowise").exists()
+
+
+class TestNestedRepos:
+ def test_names_the_separate_checkouts(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ for name in ("backend", "frontend"):
+ (repo / name / ".git").mkdir(parents=True)
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ [nested] = [ep for ep in episodes if ep.kind == KIND_NESTED_REPOS]
+ assert set(nested.nodes) == {"backend", "frontend"}
+ assert "backend" in nested.body and "frontend" in nested.body
+
+ def test_git_file_form_counts(self, tmp_path: Path) -> None:
+ """A repo whose gitdir lives elsewhere is still an independent repo."""
+ repo = _repo(tmp_path)
+ (repo / "linked").mkdir()
+ (repo / "linked" / ".git").write_text(
+ "gitdir: C:/elsewhere/other-project/.git", encoding="utf-8"
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_NESTED_REPOS in _kinds(episodes)
+
+ def test_linked_worktree_is_not_a_separate_repo(self, tmp_path: Path) -> None:
+ """A worktree of THIS repo is the same repository, not an independent one."""
+ repo = _repo(tmp_path)
+ (repo / "wt-feature").mkdir()
+ (repo / "wt-feature" / ".git").write_text(
+ "gitdir: C:/repo/.git/worktrees/wt-feature\n", encoding="utf-8"
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_NESTED_REPOS not in _kinds(episodes)
+
+ def test_nested_submodule_is_not_a_separate_repo(self, tmp_path: Path) -> None:
+ """A submodule declared in a nested .gitmodules is absent from the root one."""
+ repo = _repo(tmp_path)
+ (repo / "vendored").mkdir()
+ (repo / "vendored" / ".git").write_text(
+ "gitdir: ../.git/modules/outer/modules/vendored\n", encoding="utf-8"
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_NESTED_REPOS not in _kinds(episodes)
+
+ def test_declared_submodule_is_not_a_separate_repo(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / "vendored").mkdir()
+ (repo / "vendored" / ".git").write_text("gitdir: ../.git/modules/vendored", "utf-8")
+ (repo / ".gitmodules").write_text(
+ '[submodule "vendored"]\n\tpath = vendored\n\turl = https://example.invalid/x\n',
+ encoding="utf-8",
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_NESTED_REPOS not in _kinds(episodes)
+
+
+class TestEditableShadow:
+ def _venv_with_editable_install(self, repo: Path, *, script: str) -> None:
+ (repo / "pyproject.toml").write_text(
+ f'[project]\nname = "x"\nversion = "0"\n\n'
+ f'[project.scripts]\n{script} = "x.cli:main"\n',
+ encoding="utf-8",
+ )
+ site = repo / ".venv" / "Lib" / "site-packages"
+ site.mkdir(parents=True)
+ (site / "__editable__.x-0.pth").write_text("/src", encoding="utf-8")
+
+ def test_launcher_beside_an_editable_pth(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ self._venv_with_editable_install(repo, script="mytool")
+ scripts = repo / ".venv" / "Scripts"
+ scripts.mkdir()
+ (scripts / "mytool.exe").write_bytes(b"MZ")
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ [shadow] = [ep for ep in episodes if ep.kind == KIND_EDITABLE_SHADOW]
+ assert shadow.subject == "mytool"
+ assert "__editable__.x-0.pth" in shadow.evidence
+
+ def test_no_launcher_means_no_episode(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ self._venv_with_editable_install(repo, script="mytool")
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_EDITABLE_SHADOW not in _kinds(episodes)
+
+ def test_editable_install_of_another_distribution_means_no_episode(
+ self, tmp_path: Path
+ ) -> None:
+ """An unrelated dependency installed -e does not shadow this checkout."""
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "my-tool"\nversion = "0"\n\n'
+ '[project.scripts]\nmytool = "my_tool.cli:main"\n',
+ encoding="utf-8",
+ )
+ site = repo / ".venv" / "Lib" / "site-packages"
+ site.mkdir(parents=True)
+ (site / "__editable__.some_dependency-2.1.pth").write_text("/elsewhere", encoding="utf-8")
+ scripts = repo / ".venv" / "Scripts"
+ scripts.mkdir()
+ (scripts / "mytool.exe").write_bytes(b"MZ")
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_EDITABLE_SHADOW not in _kinds(episodes)
+
+ def test_distribution_spelling_does_not_matter(self, tmp_path: Path) -> None:
+ """my-tool, my_tool and My.Tool are one distribution."""
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "My.Tool"\nversion = "0"\n\n'
+ '[project.scripts]\nmytool = "my_tool.cli:main"\n',
+ encoding="utf-8",
+ )
+ site = repo / ".venv" / "Lib" / "site-packages"
+ site.mkdir(parents=True)
+ (site / "__editable__.my_tool-0.1.pth").write_text("/src", encoding="utf-8")
+ scripts = repo / ".venv" / "Scripts"
+ scripts.mkdir()
+ (scripts / "mytool.exe").write_bytes(b"MZ")
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_EDITABLE_SHADOW in _kinds(episodes)
+
+ def test_launcher_without_editable_install_means_no_episode(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "x"\nversion = "0"\n\n[project.scripts]\nmytool = "x.cli:main"\n',
+ encoding="utf-8",
+ )
+ scripts = repo / ".venv" / "Scripts"
+ scripts.mkdir(parents=True)
+ (scripts / "mytool.exe").write_bytes(b"MZ")
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_EDITABLE_SHADOW not in _kinds(episodes)
+
+
+class TestConfigOverrides:
+ def test_exclude_patterns_are_reported(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / ".repowise" / "config.yaml").write_text(
+ "exclude_patterns:\n - vendor/**\n", encoding="utf-8"
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ [cfg] = [ep for ep in episodes if ep.kind == KIND_CONFIG_OVERRIDE]
+ assert cfg.subject == "exclude_patterns"
+ assert "vendor/**" in cfg.evidence
+
+ def test_disabled_switch_is_reported_once_per_block(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / ".repowise" / "config.yaml").write_text(
+ "hooks:\n read_skeleton: false\n search_digest: false\n", encoding="utf-8"
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ [cfg] = [ep for ep in episodes if ep.kind == KIND_CONFIG_OVERRIDE]
+ assert cfg.subject == "hooks"
+ assert "read_skeleton" in cfg.body and "search_digest" in cfg.body
+
+ def test_default_config_says_nothing(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / ".repowise" / "config.yaml").write_text(
+ "provider: openai\nhooks:\n read_skeleton: true\n", encoding="utf-8"
+ )
+ episodes = derive_structural_episodes(
+ repo, _traverser(repo), allow_formatter_check=False
+ )
+ assert KIND_CONFIG_OVERRIDE not in _kinds(episodes)
+
+
+class TestFormatterDrift:
+ """The one check that costs a subprocess, and the one that must stay silent
+ whenever it cannot answer."""
+
+ def _declaring_repo(self, tmp_path: Path) -> Path:
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "x"\nversion = "0"\n\n[tool.ruff.format]\nquote-style = "double"\n',
+ encoding="utf-8",
+ )
+ return repo
+
+ def test_not_run_when_the_repo_declares_no_formatter(
+ self, tmp_path: Path, monkeypatch
+ ) -> None:
+ repo = _repo(tmp_path)
+ monkeypatch.setattr(
+ "repowise.core.precedent.structural._ruff_executable",
+ lambda _root: (_ for _ in ()).throw(AssertionError("must not resolve")),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)
+
+ def test_drift_is_reported_with_the_true_count(self, tmp_path: Path, monkeypatch) -> None:
+ repo = self._declaring_repo(tmp_path)
+ monkeypatch.setattr(
+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"
+ )
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: SimpleNamespace(
+ returncode=1,
+ stdout="Would reformat: a.py\nWould reformat: b.py\n2 files would be reformatted\n",
+ stderr="",
+ ),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ [drift] = [ep for ep in episodes if ep.kind == KIND_FORMATTER_DRIFT]
+ assert "2 files" in drift.body
+ assert "ruff format --check ." in drift.evidence
+ assert "2 files would be reformatted" in drift.evidence
+
+ def test_a_repo_that_formats_with_something_else_is_silent(
+ self, tmp_path: Path, monkeypatch
+ ) -> None:
+ """Ruff-as-linter beside another formatter must not be read as ruff-as-formatter."""
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "x"\nversion = "0"\n\n'
+ '[tool.ruff.lint]\nselect = ["E"]\n\n[tool.black]\nline-length = 88\n',
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("must not run ruff")),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)
+
+ def test_ruff_as_linter_only_is_silent(self, tmp_path: Path, monkeypatch) -> None:
+ """A pyproject mentioning ruff and the word format is not a declaration."""
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "x"\nversion = "0"\ndescription = "formats things"\n\n'
+ '[tool.ruff.lint]\nselect = ["E"]\n',
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("must not run ruff")),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)
+
+ def test_a_pre_commit_declaration_counts(self, tmp_path: Path, monkeypatch) -> None:
+ repo = _repo(tmp_path)
+ (repo / "pyproject.toml").write_text(
+ '[project]\nname = "x"\nversion = "0"\n', encoding="utf-8"
+ )
+ (repo / ".pre-commit-config.yaml").write_text(
+ "repos:\n - hooks:\n - id: ruff-format\n", encoding="utf-8"
+ )
+ monkeypatch.setattr(
+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"
+ )
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: SimpleNamespace(
+ returncode=1, stdout="Would reformat: a.py\n", stderr=""
+ ),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT in _kinds(episodes)
+
+ def test_clean_tree_produces_no_episode(self, tmp_path: Path, monkeypatch) -> None:
+ repo = self._declaring_repo(tmp_path)
+ monkeypatch.setattr(
+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"
+ )
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: SimpleNamespace(returncode=0, stdout="12 files already formatted\n", stderr=""),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)
+
+ def test_timeout_produces_no_episode(self, tmp_path: Path, monkeypatch) -> None:
+ """An exceeded budget must produce nothing, never a partial count."""
+ repo = self._declaring_repo(tmp_path)
+ monkeypatch.setattr(
+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"
+ )
+
+ def _timeout(*_a, **_k):
+ raise subprocess.TimeoutExpired(cmd="ruff", timeout=1)
+
+ monkeypatch.setattr(subprocess, "run", _timeout)
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)
+
+ def test_crash_produces_no_episode(self, tmp_path: Path, monkeypatch) -> None:
+ repo = self._declaring_repo(tmp_path)
+ monkeypatch.setattr(
+ "repowise.core.precedent.structural._ruff_executable", lambda _root: "ruff"
+ )
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: SimpleNamespace(returncode=2, stdout="", stderr="boom"),
+ )
+ episodes = derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=True)
+ assert KIND_FORMATTER_DRIFT not in _kinds(episodes)
+
+ def test_update_path_never_runs_it(self, tmp_path: Path, monkeypatch) -> None:
+ repo = self._declaring_repo(tmp_path)
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("no subprocess on update")),
+ )
+ derive_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)
+ assert KIND_FORMATTER_DRIFT not in FREE_KINDS
+
+
+class TestDegradation:
+ def test_a_broken_traverser_costs_only_its_own_fact(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / ".repowise" / "config.yaml").write_text(
+ "exclude_patterns:\n - vendor/**\n", encoding="utf-8"
+ )
+ broken = SimpleNamespace() # no stats, no console-script names
+ episodes = derive_structural_episodes(repo, broken, allow_formatter_check=False)
+ assert _kinds(episodes) == {KIND_CONFIG_OVERRIDE}
+
+
+class TestPersistence:
+ def test_recording_twice_is_idempotent(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / "backend" / ".git").mkdir(parents=True)
+ for _ in range(2):
+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)
+ with EpisodeStore.open_for_repo(repo) as store:
+ assert store.count() == 1
+
+ def test_a_fact_that_stops_holding_is_dropped(self, tmp_path: Path) -> None:
+ repo = _repo(tmp_path)
+ (repo / "backend" / ".git").mkdir(parents=True)
+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)
+ (repo / "backend" / ".git").rmdir()
+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)
+ with EpisodeStore.open_for_repo(repo) as store:
+ assert store.count() == 0
+
+ def test_episodes_are_tiered_in_the_payload(self, tmp_path: Path) -> None:
+ """The tier is the line between this layer and a per-user memory."""
+ repo = _repo(tmp_path)
+ (repo / "backend" / ".git").mkdir(parents=True)
+ record_structural_episodes(repo, _traverser(repo), allow_formatter_check=False)
+ with EpisodeStore.open_for_repo(repo) as store:
+ assert {row["tier"] for row in store.list_episodes()} == {"structural"}
diff --git a/tests/unit/precedent/test_structural_perf.py b/tests/unit/precedent/test_structural_perf.py
new file mode 100644
index 000000000..3ec4ae93e
--- /dev/null
+++ b/tests/unit/precedent/test_structural_perf.py
@@ -0,0 +1,82 @@
+"""Budget guarantees for structural episode derivation.
+
+Two layers, because a wall clock alone is a weak gate on a loaded box:
+
+ 1. An import-graph guard. The episode store is read on hook paths whose
+ budget was fought down from 965 ms to 155 ms by deleting three
+ module-level imports, so the store must stay stdlib-only. This is the
+ half that catches a regression before it is a stopwatch problem.
+ 2. A wall-clock ceiling on the free facts, which run on every update. Loose
+ on purpose: it exists to catch an added walk or subprocess, not to
+ measure the machine.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from repowise.core.ingestion.traverser import FileTraverser
+from repowise.core.precedent.structural import derive_structural_episodes
+
+#: Nothing in this list may be reachable from the episode store's imports.
+_HEAVY_PREFIXES = (
+ "click",
+ "sqlalchemy",
+ "structlog",
+ "networkx",
+ "yaml",
+ "rich",
+ "pathspec",
+ "repowise.core.ingestion",
+ "repowise.core.persistence",
+ "repowise.core.generation",
+)
+
+#: Ceiling for deriving the three subprocess-free facts on a small tree.
+#: The update-path allowance is 200 ms for everything Precedent adds; this is
+#: an order of magnitude under it so a real regression is unambiguous.
+_FREE_FACTS_BUDGET_MS = 250.0
+
+
+def test_store_import_stays_stdlib_only() -> None:
+ code = (
+ "import sys; "
+ "import repowise.core.precedent.store; "
+ f"heavy = [m for m in sys.modules if m.startswith({_HEAVY_PREFIXES!r})]; "
+ "print('\\n'.join(heavy)); "
+ "sys.exit(1 if heavy else 0)"
+ )
+ result = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True)
+ assert result.returncode == 0, f"heavy imports leaked:\n{result.stdout}{result.stderr}"
+
+
+def test_free_facts_add_no_subprocess(tmp_path: Path, monkeypatch) -> None:
+ """The update path derives only what the walk already paid for."""
+ (tmp_path / ".repowise").mkdir()
+ (tmp_path / "backend" / ".git").mkdir(parents=True)
+ monkeypatch.setattr(
+ subprocess,
+ "run",
+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("no subprocess allowed here")),
+ )
+ traverser = FileTraverser(tmp_path)
+ list(traverser._walk())
+ assert derive_structural_episodes(tmp_path, traverser, allow_formatter_check=False)
+
+
+def test_free_facts_stay_within_budget(tmp_path: Path) -> None:
+ (tmp_path / ".repowise").mkdir()
+ (tmp_path / "backend" / ".git").mkdir(parents=True)
+ for i in range(200):
+ (tmp_path / f"mod_{i}.py").write_text("x = 1\n", encoding="utf-8")
+ traverser = FileTraverser(tmp_path)
+ list(traverser._walk())
+
+ derive_structural_episodes(tmp_path, traverser, allow_formatter_check=False) # warm
+ start = time.perf_counter()
+ derive_structural_episodes(tmp_path, traverser, allow_formatter_check=False)
+ elapsed_ms = (time.perf_counter() - start) * 1000
+ assert elapsed_ms < _FREE_FACTS_BUDGET_MS, f"free facts took {elapsed_ms:.1f} ms"