folio-resolve 0.1.0__py3-none-any.whl

folio_resolve/__init__.py

@@ -0,0 +1,107 @@
+"""folio-resolve — the shared FOLIO source-text-to-concept matching engine.
+
+A lift-and-improve extraction of the matching intelligence that previously lived — and diverged —
+across folio-mapper, folio-enrich, and folio-insights (informally shared through a fragile
+``sys.path`` hack). This package is the single pinned source of truth: the word-order-invariant
+scorer, span decomposition, the place-name / short-label gates, the alias blocklist, the
+domain-prior judge, and the annotate primitives.
+
+Public surface (see module docstrings for provenance):
+
+* scoring       — ``compute_relevance_score``, ``word_overlap``, ``LEGAL_TERM_EXPANSIONS``
+* ontology      — ``Concept``, ``OntologyProvider``, ``InMemoryOntology``, ``FolioPythonProvider``
+* entity_ruler  — ``FOLIOEntityRuler`` (pure-Python Aho-Corasick)
+* reconciler    — ``Reconciler``, ``ConceptMatch``
+* decompose     — ``decompose`` (conjunction split + shared-head)
+* gates         — ``PlaceNameGate``, ``ShortLabelGate``
+* blocklist     — ``AliasBlocklist`` (Action != Auction)
+* sources       — ``SourceClassifier`` (metadata/front-matter exclusion)
+* domain_prior  — ``DomainPrior``, ``DomainPriorSuggester``, ``TaxonomyNode`` (multi-tag)
+* calibration   — ``ScoreCalibration`` (weak-band recalibration)
+* judge         — ``Judge``, ``build_judge_prompt``, ``parse_judge_json``
+* pipeline      — ``MatchPipeline`` (filter -> expand -> rank -> judge)
+* resolve       — ``LabelResolver``, ``ResolvedConcept`` (decompose-first, branch-carrying)
+* annotate      — ``ConceptTag``, ``TagVerdict``, ``Annotation``, ``FeedbackStore``, lifecycle
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .blocklist import AliasBlocklist, BlockedAlias, load_seed_blocklist
+from .calibration import CalibrationSample, ScoreCalibration
+from .decompose import decompose
+from .domain_prior import DomainPrior, DomainPriorSuggester, SubjectTag, TagStatus, TaxonomyNode
+from .entity_ruler import FOLIOEntityRuler
+from .gates import GateDecision, PlaceNameGate, ShortLabelGate
+from .judge import Judge, build_judge_prompt, enforce_verdict, parse_judge_json
+from .ontology import Concept, FolioPythonProvider, InMemoryOntology, LabelInfo, OntologyProvider
+from .pipeline import MatchCandidate, MatchPipeline
+from .reconciler import ConceptMatch, Reconciler, ReconciliationResult
+from .resolve import (
+    CONJUNCT_THRESHOLD,
+    WHOLE_STRING_THRESHOLD,
+    LabelResolver,
+    ResolvedConcept,
+)
+from .scoring import (
+    LEGAL_TERM_EXPANSIONS,
+    SEARCH_STOPWORDS,
+    compute_relevance_score,
+    content_words,
+    generate_search_terms,
+    tokenize,
+    word_overlap,
+)
+from .sources import SourceClassifier, SourceType
+from .spec import BUILTIN_SPECS, CANON_SPEC, FOLIO_SPEC, OntologySpec
+
+__all__ = [
+    "BUILTIN_SPECS",
+    "CANON_SPEC",
+    "CONJUNCT_THRESHOLD",
+    "FOLIO_SPEC",
+    "LEGAL_TERM_EXPANSIONS",
+    "SEARCH_STOPWORDS",
+    "WHOLE_STRING_THRESHOLD",
+    "AliasBlocklist",
+    "BlockedAlias",
+    "CalibrationSample",
+    "Concept",
+    "ConceptMatch",
+    "DomainPrior",
+    "DomainPriorSuggester",
+    "FOLIOEntityRuler",
+    "FolioPythonProvider",
+    "GateDecision",
+    "InMemoryOntology",
+    "Judge",
+    "LabelInfo",
+    "LabelResolver",
+    "MatchCandidate",
+    "MatchPipeline",
+    "OntologyProvider",
+    "OntologySpec",
+    "PlaceNameGate",
+    "Reconciler",
+    "ReconciliationResult",
+    "ResolvedConcept",
+    "ScoreCalibration",
+    "ShortLabelGate",
+    "SourceClassifier",
+    "SourceType",
+    "SubjectTag",
+    "TagStatus",
+    "TaxonomyNode",
+    "__version__",
+    "build_judge_prompt",
+    "compute_relevance_score",
+    "content_words",
+    "decompose",
+    "enforce_verdict",
+    "generate_search_terms",
+    "load_seed_blocklist",
+    "parse_judge_json",
+    "tokenize",
+    "word_overlap",
+]

folio_resolve/annotate/__init__.py

@@ -0,0 +1,46 @@
+"""Annotate primitives — the feature-rich display + feedback layer.
+
+Per Damien's ``feedback_share`` directive: folio-resolve must be first-class, not a minimal
+extraction. This package lifts folio-enrich's confidence scores, per-item feedback, notes,
+reject/restore lifecycle, and feedback insights as library primitives — plus the new **per-tag
+verdict** (``correct`` / ``weak`` / ``wrong`` + note) the Ch02 review demanded.
+"""
+
+from .lifecycle import (
+    bulk_reject,
+    cascade_promote,
+    promote,
+    reject,
+    restore,
+)
+from .models import (
+    Annotation,
+    ConceptTag,
+    FeedbackEntry,
+    FeedbackItem,
+    InsightsSummary,
+    Span,
+    StageEvent,
+    TagVerdict,
+    Verdict,
+)
+from .render import RenderedSegment, render_segments
+
+__all__ = [
+    "Annotation",
+    "ConceptTag",
+    "FeedbackEntry",
+    "FeedbackItem",
+    "InsightsSummary",
+    "RenderedSegment",
+    "Span",
+    "StageEvent",
+    "TagVerdict",
+    "Verdict",
+    "bulk_reject",
+    "cascade_promote",
+    "promote",
+    "reject",
+    "render_segments",
+    "restore",
+]

folio_resolve/annotate/feedback_store.py

@@ -0,0 +1,95 @@
+"""File-backed feedback store with insights aggregation.
+
+Ported from folio-enrich ``storage/feedback_store.py``: one JSON file per feedback entry, written
+atomically (tempfile + rename), plus ``get_insights`` aggregation. Synchronous here (no aiofiles
+dependency) — the atomic-rename guarantee is preserved.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections import Counter
+from pathlib import Path
+
+from .models import FeedbackEntry, InsightsSummary
+
+
+class FeedbackStore:
+    def __init__(self, base_dir: str | Path) -> None:
+        self._base = Path(base_dir)
+        self._base.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, feedback_id: str) -> Path:
+        return self._base / f"{feedback_id}.json"
+
+    def save(self, entry: FeedbackEntry) -> None:
+        path = self._path(entry.id)
+        fd, tmp = tempfile.mkstemp(dir=self._base, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(entry.model_dump_json(indent=2))
+            os.replace(tmp, path)
+        finally:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+
+    def load(self, feedback_id: str) -> FeedbackEntry | None:
+        path = self._path(feedback_id)
+        if not path.exists():
+            return None
+        return FeedbackEntry.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def list_all(self) -> list[FeedbackEntry]:
+        out: list[FeedbackEntry] = []
+        for p in self._base.glob("*.json"):
+            out.append(FeedbackEntry.model_validate_json(p.read_text(encoding="utf-8")))
+        return out
+
+    def delete(self, feedback_id: str) -> bool:
+        path = self._path(feedback_id)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    def find_by_annotation(self, job_id: str, annotation_id: str) -> FeedbackEntry | None:
+        for entry in self.list_all():
+            if entry.job_id == job_id and entry.annotation_id == annotation_id:
+                return entry
+        return None
+
+    def get_insights(self, job_id: str | None = None) -> InsightsSummary:
+        entries = [e for e in self.list_all() if job_id is None or e.job_id == job_id]
+        summary = InsightsSummary(total_feedback=len(entries))
+        by_stage: dict[str, dict[str, int]] = {}
+        down_counter: Counter[str] = Counter()
+        dismissed_counter: Counter[str] = Counter()
+        down_labels: dict[str, str] = {}
+        for e in entries:
+            if e.rating == "up":
+                summary.thumbs_up += 1
+            elif e.rating == "down":
+                summary.thumbs_down += 1
+            elif e.rating == "dismissed":
+                summary.total_dismissed += 1
+            bucket = by_stage.setdefault(e.stage or "overall", {"up": 0, "down": 0, "dismissed": 0})
+            if e.rating in bucket:
+                bucket[e.rating] += 1
+            if e.rating == "down" and e.folio_iri:
+                down_counter[e.folio_iri] += 1
+                down_labels[e.folio_iri] = e.folio_label or ""
+            if e.rating == "dismissed" and e.folio_iri:
+                dismissed_counter[e.folio_iri] += 1
+                down_labels.setdefault(e.folio_iri, e.folio_label or "")
+        summary.by_stage = by_stage
+        summary.most_downvoted_concepts = [
+            {"iri": iri, "label": down_labels.get(iri, ""), "count": n}
+            for iri, n in down_counter.most_common(10)
+        ]
+        summary.most_dismissed_concepts = [
+            {"iri": iri, "label": down_labels.get(iri, ""), "count": n}
+            for iri, n in dismissed_counter.most_common(10)
+        ]
+        summary.recent_feedback = sorted(entries, key=lambda e: e.created_at, reverse=True)[:20]
+        return summary

folio_resolve/annotate/lifecycle.py

@@ -0,0 +1,71 @@
+"""Annotation lifecycle transitions.
+
+Ported from folio-enrich's ``api/routes/enrich.py`` endpoints as pure functions: reject / restore
+/ promote / cascade-promote / bulk-reject. Each stamps a ``StageEvent(stage="user", ...)`` onto
+the annotation's lineage — the per-annotation audit trail — exactly as the source did at the route
+layer. Keeping these framework-free lets any consumer (FastAPI, CLI, the folio-insights annotator)
+reuse the same transitions.
+"""
+
+from __future__ import annotations
+
+from .models import Annotation, StageEvent, _now
+
+
+def reject(annotation: Annotation, *, comment: str = "") -> Annotation:
+    annotation.state = "rejected"
+    annotation.dismissed_at = _now()
+    annotation.lineage.append(
+        StageEvent(stage="user", action="user_rejected", detail=comment)
+    )
+    return annotation
+
+
+def restore(annotation: Annotation) -> Annotation:
+    annotation.state = "confirmed"
+    annotation.dismissed_at = None
+    annotation.feedback = []
+    annotation.lineage.append(StageEvent(stage="user", action="user_restored"))
+    return annotation
+
+
+def promote(annotation: Annotation, concept_index: int) -> Annotation:
+    """Swap a backup concept to primary (index 0)."""
+    if not 0 <= concept_index < len(annotation.concepts):
+        raise IndexError(f"concept_index {concept_index} out of range")
+    concept = annotation.concepts.pop(concept_index)
+    annotation.concepts.insert(0, concept)
+    annotation.state = "confirmed"
+    annotation.lineage.append(
+        StageEvent(stage="user", action="user_promotion", detail=f"promoted {concept.iri}")
+    )
+    return annotation
+
+
+def cascade_promote(
+    annotations: list[Annotation], *, old_iri: str, new_iri: str
+) -> list[Annotation]:
+    """Promote ``new_iri`` over ``old_iri`` across every annotation where both are present."""
+    updated: list[Annotation] = []
+    for ann in annotations:
+        if ann.primary_iri != old_iri:
+            continue
+        idx = next((i for i, c in enumerate(ann.concepts) if c.iri == new_iri), None)
+        if idx is None:
+            continue
+        promote(ann, idx)
+        ann.lineage.append(
+            StageEvent(stage="user", action="user_promotion", detail=f"Cascade: {old_iri} -> {new_iri}")
+        )
+        updated.append(ann)
+    return updated
+
+
+def bulk_reject(annotations: list[Annotation], *, folio_iri: str, comment: str = "") -> list[str]:
+    """Reject every non-rejected annotation whose primary IRI is ``folio_iri``. Returns their ids."""
+    rejected_ids: list[str] = []
+    for ann in annotations:
+        if ann.state != "rejected" and ann.primary_iri == folio_iri:
+            reject(ann, comment=comment)
+            rejected_ids.append(ann.id)
+    return rejected_ids

folio_resolve/annotate/models.py

@@ -0,0 +1,135 @@
+"""Annotation data models.
+
+Lifted from folio-enrich ``models/annotation.py`` + ``models/feedback.py`` and extended with
+``ConceptTag`` and ``TagVerdict`` — the per-tag ``correct``/``weak``/``wrong`` + note affordance
+the Ch02 review directed ("classification must be PER TAG, not per unit").
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+class Verdict(StrEnum):
+    CORRECT = "correct"
+    WEAK = "weak"
+    WRONG = "wrong"
+
+
+class Span(BaseModel):
+    start: int
+    end: int
+    text: str
+    sentence_text: str | None = None
+
+
+class StageEvent(BaseModel):
+    """A single step in an annotation's lineage (which stage did what, when)."""
+
+    stage: str
+    action: str  # "created" | "confirmed" | "rejected" | "restored" | "user_promotion" | ...
+    detail: str = ""
+    confidence: float | None = None
+    reasoning: str = ""
+    timestamp: str = Field(default_factory=_now)
+
+
+class FeedbackItem(BaseModel):
+    """Thumbs up/down + note on an annotation or a specific stage event."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    rating: str  # "up" | "down"
+    stage: str | None = None
+    comment: str = ""
+    created_at: str = Field(default_factory=_now)
+
+
+class ConceptTag(BaseModel):
+    """A FOLIO concept anchored to a span within a unit, with why-it-fired provenance."""
+
+    iri: str
+    label: str
+    confidence: float = 0.0
+    branch: str = ""
+    extraction_path: str = ""  # "entity_ruler" | "llm" | "semantic" | "heading_context" | "proposed_class"
+    match_score: float | None = None
+    span: Span | None = None
+
+
+class TagVerdict(BaseModel):
+    """A reviewer's per-tag judgment — the missing per-tag layer.
+
+    Feeds the self-improving loop: a ``wrong`` verdict on a homonym appends to the alias
+    blocklist; ``correct``/``weak``/``wrong`` at the match score train the score calibration; each
+    verdict is a regression fixture.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    unit_id: str
+    run_id: str = ""
+    corpus_name: str = ""
+    tag_iri: str
+    tag_label: str = ""
+    extraction_path: str = ""
+    match_score: float | None = None
+    verdict: Verdict
+    note: str = ""
+    domain_prior: str = ""
+    book: str = ""
+    chapter: str = ""
+    reviewer: str = ""
+    reviewed_at: str = Field(default_factory=_now)
+
+
+class Annotation(BaseModel):
+    """A span with one or more concept candidates, a state, lineage, and feedback."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    span: Span
+    concepts: list[ConceptTag] = Field(default_factory=list)
+    state: str = "preliminary"  # "preliminary" | "confirmed" | "rejected"
+    dismissed_at: str | None = None
+    lineage: list[StageEvent] = Field(default_factory=list)
+    feedback: list[FeedbackItem] = Field(default_factory=list)
+
+    @property
+    def primary_iri(self) -> str:
+        return self.concepts[0].iri if self.concepts else ""
+
+
+class FeedbackEntry(BaseModel):
+    """A self-contained feedback record that outlives job cleanup."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    job_id: str
+    annotation_id: str
+    rating: str  # "up" | "down" | "dismissed"
+    stage: str | None = None
+    comment: str = ""
+    annotation_text: str = ""
+    sentence_text: str | None = None
+    folio_iri: str | None = None
+    folio_label: str | None = None
+    lineage: list[dict[str, object]] = Field(default_factory=list)
+    created_at: str = Field(default_factory=_now)
+
+
+class InsightsSummary(BaseModel):
+    """Aggregated feedback insights."""
+
+    total_feedback: int = 0
+    thumbs_up: int = 0
+    thumbs_down: int = 0
+    total_dismissed: int = 0
+    by_stage: dict[str, dict[str, int]] = Field(default_factory=dict)
+    most_downvoted_concepts: list[dict[str, object]] = Field(default_factory=list)
+    most_dismissed_concepts: list[dict[str, object]] = Field(default_factory=list)
+    recent_feedback: list[FeedbackEntry] = Field(default_factory=list)

folio_resolve/annotate/render.py

@@ -0,0 +1,69 @@
+"""Span-layout primitive — the boundary-sweep, ported to Python.
+
+folio-enrich's ``renderAnnotatedText`` computes non-overlapping display segments from possibly
+overlapping/nested annotation spans by collecting all boundary points, sorting them, and, for each
+adjacent-point segment, finding the annotations that cover it. That algorithm is display-framework
+agnostic, so we lift it as a **library primitive** that returns ``RenderedSegment`` offset tuples;
+the folio-insights v2 Svelte component (separate op) consumes these to draw nested chips. Returning
+offsets — not HTML — keeps the library UI-neutral.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import Annotation
+
+
+@dataclass(frozen=True)
+class RenderedSegment:
+    start: int
+    end: int
+    text: str
+    annotation_ids: tuple[str, ...]  # covering annotations, highest-confidence-first
+
+
+def render_segments(text: str, annotations: list[Annotation]) -> list[RenderedSegment]:
+    """Flatten overlapping annotation spans into ordered, non-overlapping display segments."""
+    if not text:
+        return []
+
+    points: set[int] = {0, len(text)}
+    for ann in annotations:
+        points.add(max(0, ann.span.start))
+        points.add(min(len(text), ann.span.end))
+    ordered = sorted(p for p in points if 0 <= p <= len(text))
+
+    segments: list[RenderedSegment] = []
+    for i in range(len(ordered) - 1):
+        seg_start, seg_end = ordered[i], ordered[i + 1]
+        if seg_start >= seg_end:
+            continue
+        covering = [
+            ann for ann in annotations if ann.span.start <= seg_start and ann.span.end >= seg_end
+        ]
+        # Dedup by primary IRI, keeping the highest-confidence annotation per IRI.
+        best_by_iri: dict[str, Annotation] = {}
+        for ann in covering:
+            iri = ann.primary_iri or f"__no_iri_{ann.id}"
+            conf = ann.concepts[0].confidence if ann.concepts else 0.0
+            existing = best_by_iri.get(iri)
+            existing_conf = (
+                existing.concepts[0].confidence if existing and existing.concepts else -1.0
+            )
+            if existing is None or conf > existing_conf:
+                best_by_iri[iri] = ann
+        ranked = sorted(
+            best_by_iri.values(),
+            key=lambda a: (a.concepts[0].confidence if a.concepts else 0.0),
+            reverse=True,
+        )
+        segments.append(
+            RenderedSegment(
+                start=seg_start,
+                end=seg_end,
+                text=text[seg_start:seg_end],
+                annotation_ids=tuple(a.id for a in ranked),
+            )
+        )
+    return segments

folio_resolve/blocklist.py

@@ -0,0 +1,145 @@
+"""Alias / homonym blocklist.
+
+Ch02 unit ``4b06a90c``: *"Action != Auction. Awful."* — a deterministic homonym the LLM judge
+should never have to catch. folio-mapper and folio-enrich both lack a deterministic homonym
+guard. This module is that guard: a versioned set of ``(surface_term, blocked_iri, domain)``
+triples. A ``wrong`` per-tag verdict on a homonym appends a triple here, and the matcher consults
+it to drop the bad candidate before it ever reaches a judge.
+
+The blocklist is domain-scoped: ``domain=None`` blocks the pairing everywhere; a specific domain
+(e.g. ``"litigation"``) blocks it only when that domain prior is active, so an alias that is wrong
+in one practice area can remain valid in another.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# The shipped seed lives as package data so every consumer loads the same recorded verdicts.
+SEED_RESOURCE = ("folio_resolve.data", "alias_blocklist.json")
+
+
+@dataclass(frozen=True)
+class BlockedAlias:
+    surface_term: str
+    blocked_iri: str
+    domain: str | None = None
+    reason: str = ""
+
+    def key(self) -> tuple[str, str, str]:
+        return (self.surface_term.lower(), self.blocked_iri, (self.domain or "").lower())
+
+
+class AliasBlocklist:
+    """A set of blocked ``(surface_term, iri, domain)`` pairings the matcher consults."""
+
+    def __init__(self, entries: Iterable[BlockedAlias] | None = None) -> None:
+        self._entries: dict[tuple[str, str, str], BlockedAlias] = {}
+        for entry in entries or []:
+            self.add(entry)
+
+    def add(self, entry: BlockedAlias) -> None:
+        self._entries[entry.key()] = entry
+
+    def block(
+        self, surface_term: str, blocked_iri: str, domain: str | None = None, reason: str = ""
+    ) -> None:
+        self.add(BlockedAlias(surface_term, blocked_iri, domain, reason))
+
+    def is_blocked(self, surface_term: str, iri: str, *, domains: Iterable[str] | None = None) -> bool:
+        """True if this surface_term→iri pairing is blocked globally or in any active domain."""
+        term = surface_term.lower()
+        # Global block (domain unset) applies everywhere.
+        if (term, iri, "") in self._entries:
+            return True
+        return any((term, iri, domain.lower()) in self._entries for domain in domains or [])
+
+    def filter_candidates(
+        self,
+        surface_term: str,
+        candidates: Iterable[tuple[str, float]],
+        *,
+        domains: Iterable[str] | None = None,
+    ) -> list[tuple[str, float]]:
+        """Drop ``(iri, score)`` candidates blocked for this surface term."""
+        domain_list = list(domains or [])
+        return [
+            (iri, score)
+            for iri, score in candidates
+            if not self.is_blocked(surface_term, iri, domains=domain_list)
+        ]
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def is_empty(self) -> bool:
+        return not self._entries
+
+    def entries(self) -> list[BlockedAlias]:
+        return list(self._entries.values())
+
+    # -- persistence -------------------------------------------------------
+
+    @classmethod
+    def load(cls, path: str | Path) -> AliasBlocklist:
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        return cls(
+            BlockedAlias(
+                surface_term=row["surface_term"],
+                blocked_iri=row["blocked_iri"],
+                domain=row.get("domain"),
+                reason=row.get("reason", ""),
+            )
+            for row in data.get("blocked_aliases", [])
+        )
+
+    @classmethod
+    def from_seed(cls) -> AliasBlocklist:
+        """Load the blocklist shipped as package data (the recorded Ch01/Ch02 verdicts).
+
+        Returns an empty blocklist (never raises) if the seed resource is missing, so a consumer
+        degrades to "no homonym vetoes" rather than crashing the tagger.
+        """
+        pkg, name = SEED_RESOURCE
+        try:
+            data = (resources.files(pkg) / name).read_text(encoding="utf-8")
+        except (FileNotFoundError, ModuleNotFoundError, OSError):
+            logger.warning("Alias blocklist seed %s/%s not found; using empty blocklist", pkg, name)
+            return cls()
+        rows = json.loads(data).get("blocked_aliases", [])
+        return cls(
+            BlockedAlias(
+                surface_term=row["surface_term"],
+                blocked_iri=row["blocked_iri"],
+                domain=row.get("domain"),
+                reason=row.get("reason", ""),
+            )
+            for row in rows
+        )
+
+    def save(self, path: str | Path) -> None:
+        payload = {
+            "version": 1,
+            "blocked_aliases": [
+                {
+                    "surface_term": e.surface_term,
+                    "blocked_iri": e.blocked_iri,
+                    "domain": e.domain,
+                    "reason": e.reason,
+                }
+                for e in self._entries.values()
+            ],
+        }
+        Path(path).write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def load_seed_blocklist() -> AliasBlocklist:
+    """Module-level convenience: the shipped seed blocklist (recorded Ch01/Ch02 verdicts)."""
+    return AliasBlocklist.from_seed()