rememberstack 0.1.0__py3-none-any.whl

rememberstack/core/ranking.py

@@ -0,0 +1,200 @@
+"""Pure rank operators (retrieval §3: `fuse`, `rerank`): the D9 fusion math.
+
+These are the fusion and reranking stages as *pure* functions — no spine, no
+ports, no I/O — so the same code fuses an agent's ad-hoc channel set and a
+recipe's fixed one, and every stage is inspectable rather than a black box.
+
+**Reciprocal-rank fusion (RRF).** When several channels each return a ranked
+list — semantic search, BM25, FTS — they cannot be compared by raw score:
+a cosine distance and a BM25 score are different units, and two embedding
+families are not on the same scale either. RRF sidesteps that by scoring an
+item purely on its *ranks*: an item that placed 1st in one channel and 3rd in
+another scores ``1/(k+1) + 1/(k+3)``. The constant ``k`` (≈60, a starting
+default retained after the WP-5.6 relevance grid could not distinguish the
+tested values) damps the top ranks so one channel cannot dominate on a single
+high placement. Items no channel returned score zero and drop out. The result
+is one order that rewards agreement across channels without ever comparing
+incomparable scores.
+
+**Reranking** is the same currency read differently: given a set of items each
+carrying a named signal (graph distance to a focal entity, evidence count),
+reorder by that signal. It is a stage, not a verdict — the caller sees the
+signal value on every item and can chain another stage on top.
+"""
+
+from collections.abc import Callable
+from collections.abc import Sequence
+from typing import Final
+from uuid import UUID
+
+from rememberstack.model import RankedItem
+
+DEFAULT_RRF_K: Final = 60
+"""The conventional starting default for RRF damping (D9/S46).
+
+WP-5.6 retained it because the small canary grid did not distinguish the
+tested k values; it was not empirically selected over them.
+"""
+
+DEFAULT_GRAPH_DISTANCE_WEIGHT: Final = 0.10
+"""Smallest tested nonzero proximity bonus on WP-5.6's best plateau."""
+
+DEFAULT_EVIDENCE_COUNT_WEIGHT: Final = 0.10
+"""Smallest tested nonzero corroboration bonus on WP-5.6's best plateau."""
+
+
+def reciprocal_rank_fusion(
+    *, rankings: Sequence[Sequence[UUID]], k: int = DEFAULT_RRF_K
+) -> tuple[RankedItem, ...]:
+    """Fuse several ranked id lists into one RRF-scored order (D9/S46).
+
+    Each inner sequence is one channel's ranking, best first. An item's
+    score is the sum over channels of ``1/(k + rank)`` (rank 1-based), so
+    agreement across channels wins without ever comparing raw scores. Only
+    an item's BEST rank within a channel counts — a channel that lists an id
+    twice contributes once, so one channel cannot forge cross-channel
+    agreement. Ties break on the id's own order for determinism. `k` must be
+    positive.
+    """
+    if k < 1:
+        raise ValueError("the RRF constant k must be at least 1")
+    scores: dict[UUID, float] = {}
+    contributions: dict[UUID, dict[str, float]] = {}
+    for channel, ranking in enumerate(rankings):
+        seen: set[UUID] = set()
+        for rank, item_id in enumerate(ranking, start=1):
+            if item_id in seen:
+                continue  # a duplicate in one channel counts only at its best rank
+            seen.add(item_id)
+            increment = 1.0 / (k + rank)
+            scores[item_id] = scores.get(item_id, 0.0) + increment
+            contributions.setdefault(item_id, {})[f"channel_{channel}"] = increment
+    ordered = sorted(scores, key=lambda item_id: (-scores[item_id], item_id.bytes))
+    return tuple(
+        RankedItem(
+            item_id=item_id, score=scores[item_id], signals=contributions[item_id]
+        )
+        for item_id in ordered
+    )
+
+
+def rerank_by_signal(
+    *, items: Sequence[RankedItem], signal: str, ascending: bool = False
+) -> tuple[RankedItem, ...]:
+    """Reorder items by one named signal each already carries (D9/S46/S48).
+
+    `graph_distance` reranks ascending (nearer the focal entity is more
+    relevant); `evidence_count` reranks descending (more corroboration
+    first). An item missing the signal sorts last in either direction
+    rather than raising — a partial signal is a weaker rerank, not an
+    error — and keeps its incoming `score` rather than being stamped with a
+    non-finite sentinel that would not survive JSON. An item that HAS the
+    signal takes it as its new `score`; `signals` is preserved throughout so
+    a later stage can read every contribution.
+    """
+    sentinel = float("inf") if ascending else float("-inf")
+
+    def key(item: RankedItem) -> tuple[float, bytes]:
+        value = item.signals.get(signal, sentinel)
+        return (value if ascending else -value, item.item_id.bytes)
+
+    return tuple(
+        item.model_copy(update={"score": item.signals[signal]})
+        if signal in item.signals
+        else item
+        for item in sorted(items, key=key)
+    )
+
+
+def rerank_by_weighted_signals(
+    *,
+    items: Sequence[RankedItem],
+    graph_distance_weight: float = DEFAULT_GRAPH_DISTANCE_WEIGHT,
+    evidence_count_weight: float = DEFAULT_EVIDENCE_COUNT_WEIGHT,
+) -> tuple[RankedItem, ...]:
+    """Blend normalized RRF, proximity, and support without unit confusion.
+
+    The incoming RRF score remains the base signal. Graph distance becomes a
+    closeness score (nearer is larger), and evidence count becomes a normalized
+    corroboration score. Missing optional signals contribute zero. WP-5.6
+    exercised the two bonuses on a small canary grid; deterministic ids break
+    ties. Normalization is relative to this candidate set, so absolute scores
+    are not comparable across separate calls or pages.
+    """
+    if graph_distance_weight < 0 or evidence_count_weight < 0:
+        raise ValueError("rerank weights must be non-negative")
+    if not items:
+        return ()
+    base = _relative_to_best(values=tuple(item.score for item in items))
+    graph = _normalized_optional(
+        items=items, signal="graph_distance", higher_is_better=False
+    )
+    evidence = _normalized_optional(
+        items=items, signal="evidence_count", higher_is_better=True
+    )
+    weighted = tuple(
+        base[index]
+        + graph_distance_weight * graph[index]
+        + evidence_count_weight * evidence[index]
+        for index in range(len(items))
+    )
+    rescored = tuple(
+        item.model_copy(
+            update={
+                "score": weighted[index],
+                "signals": {
+                    **item.signals,
+                    "rrf_score": item.score,
+                    "rrf_normalized": base[index],
+                    "graph_proximity_normalized": graph[index],
+                    "evidence_support_normalized": evidence[index],
+                    "weighted_relevance": weighted[index],
+                },
+            }
+        )
+        for index, item in enumerate(items)
+    )
+    return tuple(sorted(rescored, key=lambda item: (-item.score, item.item_id.bytes)))
+
+
+def _normalized_optional(
+    *, items: Sequence[RankedItem], signal: str, higher_is_better: bool
+) -> tuple[float, ...]:
+    """Normalize one optional signal, leaving missing values at zero."""
+    present = tuple(item.signals[signal] for item in items if signal in item.signals)
+    if not present:
+        return tuple(0.0 for _ in items)
+    normalized = _normalizer(values=present, higher_is_better=higher_is_better)
+    return tuple(
+        normalized(item.signals[signal]) if signal in item.signals else 0.0
+        for item in items
+    )
+
+
+def _normalized(
+    *, values: tuple[float, ...], higher_is_better: bool
+) -> tuple[float, ...]:
+    """Map a complete numeric signal to [0, 1]."""
+    normalizer = _normalizer(values=values, higher_is_better=higher_is_better)
+    return tuple(normalizer(value) for value in values)
+
+
+def _relative_to_best(*, values: tuple[float, ...]) -> tuple[float, ...]:
+    """Preserve close positive RRF differences instead of stretching them."""
+    high = max(values)
+    if high <= 0:
+        return _normalized(values=values, higher_is_better=True)
+    return tuple(max(value, 0.0) / high for value in values)
+
+
+def _normalizer(
+    *, values: tuple[float, ...], higher_is_better: bool
+) -> Callable[[float], float]:
+    """Build a compact min-max normalizer for one candidate set."""
+    low = min(values)
+    high = max(values)
+    if high == low:
+        return lambda _value: 1.0
+    if higher_is_better:
+        return lambda value: (value - low) / (high - low)
+    return lambda value: (high - value) / (high - low)

rememberstack/core/recipe_linter.py

@@ -0,0 +1,149 @@
+"""The recipe registration linter (D50/D41): grain semantics, mechanically.
+
+A recipe declares two enums — `output_grain` and `answer_intent` — and a
+`chain` of primitive ops. The database CHECK enforces the headline bar
+(`current_facts` ⇒ `fact` grain); this linter enforces the *chain-level*
+rules the DB cannot see, so a registration that would let a recipe lie about
+what it returns is rejected before it ever reaches a surface:
+
+- **`current_facts` may ride only validity-filtered fact primitives.** This
+  is the D41 bar in full: a recipe that answers "what holds now" must compose
+  lookups/aggregates that filter both temporal clocks — never a claims search,
+  which is evidence ("what a source *asserted*"), not fact.
+- **The chain's terminal grain must match `output_grain`.** A recipe that
+  ends on a claims search cannot advertise `fact`; one that ends on a K-page
+  read cannot advertise `evidence`. The grain a caller reads is the grain the
+  last step actually produces.
+- **Each intent implies a shape.** `assertion_history` is evidence-grain,
+  `change_feed` ends on the delta, `audit` ends on a decision trail. These
+  keep the MCP tool a caller sees honest about what it will get back.
+
+`fuse` produces an **evidence-grade ordering**, not the confirmed records
+themselves: its output is a ranking of candidate ids still to be hydrated
+(matching the `fuse` primitive's own grain), so a recipe that ends on a fuse
+is evidence, never fact. The op vocabulary the linter accepts is exactly the
+set the executor can run — a chain never lints only to fail at execution.
+"""
+
+from dataclasses import dataclass
+
+from rememberstack.model import Grain
+from rememberstack.model import Recipe
+from rememberstack.model import RecipeAnswerIntent
+
+
+class RecipeLintError(Exception):
+    """A recipe registration the linter rejected, with the reason stated."""
+
+
+@dataclass(frozen=True)
+class _OpSpec:
+    """What a chain op produces, for the mechanical grain checks."""
+
+    grain: Grain  # the D49 grain this op's envelope carries
+    validity_filtered: bool  # filters BOTH clocks to "now" (the current_facts bar)
+    min_inputs: int = 0  # prior steps this op must consume
+
+
+# The op vocabulary a recipe chain may compose — exactly the set the executor
+# implements, so a lint-clean chain always runs. `validity_filtered` is the
+# strict current-instant test (both clocks): only the point-in-time lookups
+# qualify. `aggregate` is NOT one of them — its forms span history (timeline)
+# or count live-but-expired rows — so it can never sit in a `current_facts`
+# recipe. `fuse` returns an evidence-grade ranking (candidates to hydrate).
+_OPS: dict[str, _OpSpec] = {
+    "lookup_relations": _OpSpec(Grain.FACT, validity_filtered=True),
+    "lookup_observations": _OpSpec(Grain.FACT, validity_filtered=True),
+    "aggregate": _OpSpec(Grain.FACT, validity_filtered=False),
+    "search_claims": _OpSpec(Grain.EVIDENCE, validity_filtered=False),
+    "hydrate_relation": _OpSpec(Grain.COMPOSITE, validity_filtered=False),
+    "transcript": _OpSpec(Grain.COMPOSITE, validity_filtered=False),
+    "delta": _OpSpec(Grain.COMPOSITE, validity_filtered=False),
+    "pages_about": _OpSpec(Grain.COMPILED, validity_filtered=False),
+    "fuse": _OpSpec(Grain.EVIDENCE, validity_filtered=False, min_inputs=1),
+}
+
+KNOWN_OPS = frozenset(_OPS)
+"""The primitive ops a recipe chain may name — exactly the executor's set."""
+
+
+def lint_recipe(recipe: Recipe) -> None:
+    """Validate a recipe against the D50/D41 grain rules, or raise.
+
+    Runs before every registration: a chain that would let a recipe
+    misreport its grain, or a `current_facts` recipe that reaches for
+    evidence, never becomes a row. Raises `RecipeLintError` naming the first
+    violation; returns None when the recipe is well-formed.
+    """
+    _check_ops_and_inputs(recipe)
+    terminal_grain = _OPS[recipe.chain[-1].op].grain
+    if terminal_grain != recipe.output_grain:
+        raise RecipeLintError(
+            f"recipe {recipe.name!r} declares output_grain"
+            f" {recipe.output_grain.value!r} but its chain ends on a"
+            f" {terminal_grain.value!r}-grain op"
+        )
+    _check_intent(recipe)
+
+
+def _check_ops_and_inputs(recipe: Recipe) -> None:
+    """Every op is known, and every input references an earlier step."""
+    for index, step in enumerate(recipe.chain):
+        spec = _OPS.get(step.op)
+        if spec is None:
+            raise RecipeLintError(
+                f"recipe {recipe.name!r} step {index} names unknown op"
+                f" {step.op!r}; known ops: {', '.join(sorted(KNOWN_OPS))}"
+            )
+        if len(step.inputs) < spec.min_inputs:
+            raise RecipeLintError(
+                f"recipe {recipe.name!r} step {index} ({step.op}) needs at"
+                f" least {spec.min_inputs} input(s)"
+            )
+        for referenced in step.inputs:
+            if not 0 <= referenced < index:
+                raise RecipeLintError(
+                    f"recipe {recipe.name!r} step {index} references step"
+                    f" {referenced}, which is not an earlier step"
+                )
+
+
+def _check_intent(recipe: Recipe) -> None:
+    """The answer_intent → chain-shape rules (the mechanical grain bar)."""
+    intent = recipe.answer_intent
+    if intent is RecipeAnswerIntent.CURRENT_FACTS:
+        if recipe.output_grain is not Grain.FACT:
+            raise RecipeLintError(
+                f"recipe {recipe.name!r} answers current_facts but is not"
+                " fact-grain (the D41 bar)"
+            )
+        for index, step in enumerate(recipe.chain):
+            spec = _OPS[step.op]
+            if not (spec.validity_filtered and spec.grain is Grain.FACT):
+                raise RecipeLintError(
+                    f"recipe {recipe.name!r} answers current_facts but step"
+                    f" {index} ({step.op}) is not a validity-filtered fact"
+                    " primitive — 'what holds now' never rides evidence or a"
+                    " history-spanning aggregate (D41)"
+                )
+    elif intent is RecipeAnswerIntent.ASSERTION_HISTORY:
+        if recipe.output_grain is not Grain.EVIDENCE:
+            raise RecipeLintError(
+                f"recipe {recipe.name!r} answers assertion_history but is not"
+                " evidence-grain — 'what sources asserted' is evidence (D41)"
+            )
+    elif intent is RecipeAnswerIntent.CHANGE_FEED:
+        if recipe.chain[-1].op != "delta":
+            raise RecipeLintError(
+                f"recipe {recipe.name!r} answers change_feed but does not end"
+                " on the delta primitive"
+            )
+    elif intent is RecipeAnswerIntent.AUDIT:
+        if recipe.chain[-1].op not in {"transcript", "hydrate_relation"}:
+            raise RecipeLintError(
+                f"recipe {recipe.name!r} answers audit but does not end on a"
+                " decision trail (transcript or hydrate_relation)"
+            )
+    # ORIENTATION is deliberately shape-permissive: a shaped overview may be a
+    # fact aggregate, a K page, or a bundle — its honesty is the grain match
+    # already checked, not a fixed op.

rememberstack/core/section_snap.py

@@ -0,0 +1,209 @@
+"""The deterministic section snap (D57, e1 §3): LLM spans → block partition.
+
+The structurer LLM proposes section boundaries as character spans, and being
+an LLM it can propose anything — overlaps, gaps, reversed spans, offsets past
+the end of the document, absurd nesting. Chunks are runs of whole blocks that
+must never cross a section, so sections MUST be unions of whole blocks; this
+module is the deterministic layer that makes that true for every possible
+input ("LLM proposes, a deterministic layer disposes").
+
+The algorithm is pure and total: proposed spans + the block grid in, a
+well-formed section tree out, never an exception. Malformed input degrades to
+a coarser but correct partition; the worst case is the synthetic root alone.
+"""
+
+from collections.abc import Sequence
+from typing import Final
+
+from rememberstack.model import Block
+from rememberstack.model import ProposedSection
+from rememberstack.model import SnappedSection
+
+SECTION_ROLES: Final = frozenset(
+    {
+        "body",
+        "abstract",
+        "introduction",
+        "results",
+        "methods",
+        "discussion",
+        "conclusion",
+        "references",
+        "appendix",
+        "table",
+        "figure_caption",
+        "nav",
+        "boilerplate",
+        "legal",
+    }
+)
+"""The section_role enum (D39): anything else the LLM invents becomes body."""
+
+_MAX_DEPTH: Final = 16
+"""Nesting deeper than this is flattened away — the blocks stay with the
+deepest surviving ancestor. A guard against pathological LLM recursion, not a
+semantic limit; real documents never approach it."""
+
+
+def snap_sections(
+    *,
+    proposed: Sequence[ProposedSection],
+    blocks: Sequence[Block],
+    title: str | None,
+    markdown_chars: int,
+) -> tuple[SnappedSection, ...]:
+    """Normalize a proposed section tree onto the block grid (e1 §3).
+
+    The five steps, in order: (1) every proposed start snaps BACKWARD to the
+    start of the block containing it; (2) siblings sort by snapped start,
+    longer proposed span first, emission order last, and siblings sharing a
+    snapped start collapse into one — the longer span wins and adopts the
+    loser's children; (3) siblings tile forward — each ends where the next
+    begins, the last at its parent's end, so blocks before the first child
+    are the parent's direct content; (4) children clip to their parent's
+    range and empty sections are pruned; (5) the root always spans the whole
+    block sequence.
+
+    Returns depth-first document order, root first. The empty document gets
+    the lone root with the empty block range ``0..-1``.
+    """
+    root_title = title or ""
+    last_block = len(blocks) - 1
+    root = SnappedSection(
+        node_path="0",
+        parent_path=None,
+        title=root_title,
+        role="body",
+        block_start=0,
+        block_end=last_block,
+        char_start=0,
+        char_end=markdown_chars,
+        summary="",
+        ordinal=0,
+    )
+    if last_block < 0:
+        return (root,)
+    output: list[SnappedSection] = [root]
+    _snap_level(
+        nodes=proposed,
+        parent_path="0",
+        parent_start=0,
+        parent_end=last_block,
+        blocks=blocks,
+        depth=1,
+        output=output,
+    )
+    return tuple(output)
+
+
+def _snap_level(
+    *,
+    nodes: Sequence[ProposedSection],
+    parent_path: str,
+    parent_start: int,
+    parent_end: int,
+    blocks: Sequence[Block],
+    depth: int,
+    output: list[SnappedSection],
+) -> None:
+    """Snap one sibling level into the parent's block range, then recurse."""
+    if depth >= _MAX_DEPTH:
+        return
+    candidates = _ordered_candidates(
+        nodes=nodes, parent_start=parent_start, parent_end=parent_end, blocks=blocks
+    )
+    for index, (start, node, adopted) in enumerate(candidates):
+        end = (
+            candidates[index + 1][0] - 1  # tile: end where the next begins
+            if index + 1 < len(candidates)
+            else parent_end
+        )
+        if end < start:
+            continue  # empty after tiling/clipping: pruned
+        path = f"{parent_path}.{index}"
+        output.append(
+            SnappedSection(
+                node_path=path,
+                parent_path=parent_path,
+                title=node.title,
+                role=_sanitize_role(role=node.role),
+                block_start=start,
+                block_end=end,
+                char_start=blocks[start].char_start,
+                char_end=blocks[end].char_end,
+                summary=node.summary,
+                ordinal=len(output),
+            )
+        )
+        _snap_level(
+            nodes=(*node.children, *adopted),
+            parent_path=path,
+            parent_start=start,
+            parent_end=end,
+            blocks=blocks,
+            depth=depth + 1,
+            output=output,
+        )
+
+
+def _ordered_candidates(
+    *,
+    nodes: Sequence[ProposedSection],
+    parent_start: int,
+    parent_end: int,
+    blocks: Sequence[Block],
+) -> list[tuple[int, ProposedSection, tuple[ProposedSection, ...]]]:
+    """Snap starts, order siblings, collapse same-start ties (steps 1–2).
+
+    Yields ``(snapped_start, winner, adopted_children)`` with strictly
+    increasing starts; a tie's loser is dropped and its children are adopted
+    by the winner so a duplicated heading cannot erase a subtree. Step 4's
+    clipping is applied here where it prunes whole nodes: a zero-length
+    proposal, and a proposal whose char span lies entirely outside its
+    parent's char range, are empty after clipping — pruned, never inflated
+    into a real section by the start clamp + tiling (Codex review).
+    """
+    parent_char_start = blocks[parent_start].char_start
+    parent_char_end = blocks[parent_end].char_end
+    snapped: list[tuple[int, int, int, ProposedSection]] = []
+    for emission_index, node in enumerate(nodes):
+        if node.char_end <= node.char_start:
+            continue  # zero-length (or reversed): pruned
+        if node.char_end <= parent_char_start or node.char_start >= parent_char_end:
+            continue  # no overlap with the parent: empty after clipping
+        start = _snap_start(char=node.char_start, blocks=blocks)
+        start = max(start, parent_start)
+        if start > parent_end:
+            continue  # entirely outside the parent: pruned by clipping
+        proposed_length = node.char_end - node.char_start
+        snapped.append((start, -proposed_length, emission_index, node))
+    snapped.sort(key=lambda entry: entry[:3])
+    candidates: list[tuple[int, ProposedSection, tuple[ProposedSection, ...]]] = []
+    for start, _, _, node in snapped:
+        if candidates and candidates[-1][0] == start:
+            winner_start, winner, adopted = candidates[-1]
+            candidates[-1] = (winner_start, winner, (*adopted, *node.children))
+            continue
+        candidates.append((start, node, ()))
+    return candidates
+
+
+def _snap_start(*, char: int, blocks: Sequence[Block]) -> int:
+    """Step 1: the ordinal of the block containing ``char``, snapping backward.
+
+    A char before the first block clamps to block 0; a char past the last
+    block's end clamps to the last block. Chars falling between blocks (in
+    inter-block whitespace) belong to the preceding block — backward snap.
+    """
+    if char <= blocks[0].char_start:
+        return 0
+    for ordinal in range(len(blocks) - 1, -1, -1):
+        if blocks[ordinal].char_start <= char:
+            return ordinal
+    return 0
+
+
+def _sanitize_role(*, role: str) -> str:
+    """An invented role name degrades to body — the enum is the contract."""
+    normalized = role.strip().lower()
+    return normalized if normalized in SECTION_ROLES else "body"

rememberstack/core/storage_routing.py

@@ -0,0 +1,27 @@
+"""Storage-class routing for raw originals (D51 guardrail 3).
+
+Which originals stay cheap to read and which go cold is a *policy* decision
+about the corpus, not a storage-provider mechanic — so it lives here, in
+pure logic, and both the ingest path (which routes at the write) and the
+provider adapters (which apply the class) depend on it rather than on each
+other.
+
+Media a multimodal harness actually reads stays hot: for a video, an audio
+file, or a photo *input*, the original IS the artifact — conversion yields
+only a lossy transcript or description. Text and office originals are kept
+for audit and re-conversion, so they go cold. Routing at the write is what
+kills the grep-the-archive cost bug at the source rather than on the bill.
+"""
+
+from typing import Final
+
+HOT_MIME_PREFIXES: Final = ("video/", "audio/", "image/")
+"""Originals a harness reads directly — the bytes themselves are the value."""
+
+HOT: Final = "hot"
+COLD: Final = "cold"
+
+
+def storage_class_for(*, mime: str) -> str:
+    """Route one original's storage class by mime (per-deployment policy)."""
+    return HOT if mime.startswith(HOT_MIME_PREFIXES) else COLD

rememberstack/eval/__init__.py

@@ -0,0 +1,53 @@
+"""Evaluation package: the D22 harness and the golden suites."""
+
+from rememberstack.eval.consumption import make_retrieval_evaluator
+from rememberstack.eval.consumption import make_s58_evaluator
+from rememberstack.eval.consumption import S58_CANARIES
+from rememberstack.eval.consumption import seed_s58_canaries
+from rememberstack.eval.contradiction import CONTRADICTION_PRECISION_FLOOR
+from rememberstack.eval.contradiction import CONTRADICTION_RECALL_FLOOR
+from rememberstack.eval.contradiction import run_contradiction_suite
+from rememberstack.eval.contradiction import seed_contradiction_cases
+from rememberstack.eval.harness import CaseEvaluator
+from rememberstack.eval.harness import EvalHarness
+from rememberstack.eval.lifecycle import flag_rate_by_extractor
+from rememberstack.eval.lifecycle import register_lifecycle_evaluator
+from rememberstack.eval.lifecycle import run_lifecycle_suite
+from rememberstack.eval.operational_scale import OPERATIONAL_SCALE_VERSION
+from rememberstack.eval.operational_scale import record_operational_scale_report
+from rememberstack.eval.resolution import PRECISION_FLOOR
+from rememberstack.eval.resolution import RECALL_FLOOR
+from rememberstack.eval.resolution import run_resolution_suite
+from rememberstack.eval.resolution import seed_synthetic_golden_pairs
+from rememberstack.eval.retrieval_spikes import record_retrieval_spike_report
+from rememberstack.eval.retrieval_spikes import RETRIEVAL_SPIKE_VERSION
+from rememberstack.eval.skeleton import make_skeleton_evaluator
+from rememberstack.eval.skeleton import seed_skeleton_canaries
+from rememberstack.eval.skeleton import SKELETON_CANARIES
+
+__all__ = (
+    "CONTRADICTION_PRECISION_FLOOR",
+    "CONTRADICTION_RECALL_FLOOR",
+    "CaseEvaluator",
+    "make_retrieval_evaluator",
+    "make_s58_evaluator",
+    "run_contradiction_suite",
+    "flag_rate_by_extractor",
+    "register_lifecycle_evaluator",
+    "run_lifecycle_suite",
+    "seed_contradiction_cases",
+    "seed_s58_canaries",
+    "S58_CANARIES",
+    "EvalHarness",
+    "OPERATIONAL_SCALE_VERSION",
+    "PRECISION_FLOOR",
+    "RECALL_FLOOR",
+    "record_retrieval_spike_report",
+    "record_operational_scale_report",
+    "RETRIEVAL_SPIKE_VERSION",
+    "run_resolution_suite",
+    "seed_synthetic_golden_pairs",
+    "SKELETON_CANARIES",
+    "make_skeleton_evaluator",
+    "seed_skeleton_canaries",
+)