bookwright-cli 0.2.0__py3-none-any.whl

bookwright/validation/anchor_queries.py

@@ -0,0 +1,223 @@
+"""Read-only graph projections for the ``factual_anchor`` validator (research D9).
+
+Turns the research-anchor sub-graph iterations 012/013 emit into the plain
+in-memory shapes the validator reasons over, so ``factual_anchor`` never touches
+rdflib directly — exactly how ``queries`` serves ``temporal``. Every traversal is
+run through the :class:`~bookwright.indexers.Indexer` seam; the predicate IRIs come
+from :mod:`bookwright.golem.namespaces`, never hardcoded.
+
+An *anchor* is the subject of a ``bw:promotes`` triple (the one predicate that
+distinguishes an anchor's ``crm:E13_Attribute_Assignment`` node from a finding's).
+The interval model and the ``gYear`` parser are reused from :mod:`.queries` so the
+anchor span and an event boundary coerce identically (research D2).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rdflib.term import URIRef
+
+from bookwright.golem.namespaces import (
+    BEGIN_OF_BEGIN,
+    BW_ACCESS_DATE,
+    BW_AUTHOR,
+    BW_CONSTRAINS,
+    BW_ORIGINAL_LANGUAGE,
+    BW_ORIGINAL_QUOTE,
+    BW_PROMOTES,
+    BW_REFERENCE,
+    BW_RELIABILITY,
+    BW_RELIABILITY_JUSTIFICATION,
+    BW_SUPPORTED_BY,
+    BW_TRANSLATION,
+    END_OF_END,
+    HAS_TIME_SPAN,
+    HAS_TYPE,
+    RELIABILITY_IRI,
+    timeline_uri,
+)
+from bookwright.indexers import Indexer
+from bookwright.validation.queries import EventInterval, parse_gyear
+
+__all__ = [
+    "FACETS",
+    "AnchorRecord",
+    "Facet",
+    "SourceRecord",
+    "entity_present",
+    "load_anchors",
+    "load_sources_by_anchor",
+]
+
+
+@dataclass(frozen=True)
+class AnchorRecord:
+    """One research anchor projected from the graph (the validator's working unit).
+
+    ``constrains`` is ``None`` when the anchor carries no ``bw:constrains`` triple
+    (the reader dropped an unresolved link); ``span`` is ``EventInterval(uri, None,
+    None)`` when the anchor declares no time-span.
+    """
+
+    uri: str
+    promotes: str
+    constrains: str | None
+    span: EventInterval
+
+
+def load_anchors(indexer: Indexer) -> list[AnchorRecord]:
+    """One :class:`AnchorRecord` per anchor node, in sorted-URI order.
+
+    The optional ``bw:constrains`` target and the optional ``crm:E52_Time-Span``
+    (``P82a``/``P82b`` → years via :func:`~bookwright.validation.queries.parse_gyear`)
+    are read in a single projection; an absent optional is simply unbound. SPARQL
+    only — no reasoning happens here.
+    """
+    rows = indexer.query(
+        f"""
+        SELECT ?anchor ?finding ?constrains ?begin ?end WHERE {{
+          ?anchor <{BW_PROMOTES}> ?finding .
+          OPTIONAL {{ ?anchor <{BW_CONSTRAINS}> ?constrains . }}
+          OPTIONAL {{
+            ?anchor <{HAS_TIME_SPAN}> ?ts .
+            OPTIONAL {{ ?ts <{BEGIN_OF_BEGIN}> ?begin . }}
+            OPTIONAL {{ ?ts <{END_OF_END}> ?end . }}
+          }}
+        }}
+        """
+    )
+    records: dict[str, AnchorRecord] = {}
+    for row in rows:
+        anchor = row["anchor"]
+        if anchor in records:  # defensive: one anchor → one record (first wins, sorted)
+            continue
+        begin = parse_gyear(row["begin"]) if "begin" in row else None
+        end = parse_gyear(row["end"]) if "end" in row else None
+        records[anchor] = AnchorRecord(
+            uri=anchor,
+            promotes=row["finding"],
+            constrains=row.get("constrains"),
+            span=EventInterval(uri=anchor, begin=begin, end=end),
+        )
+    return [records[uri] for uri in sorted(records)]
+
+
+# --- Source provenance / reliability projections (R2/R3, research D5/D6) -----
+
+
+@dataclass(frozen=True)
+class Facet:
+    """One mandatory provenance facet of a :class:`Source` (research D5).
+
+    ``label`` is the author-facing name a violation message uses; ``predicate`` is
+    the source predicate whose presence in the graph proves the facet is recorded.
+    ``foreign_only`` marks ``translation`` — mandatory only when the source's
+    original language differs from the book language (the reader's D6 rule).
+    """
+
+    label: str
+    predicate: URIRef
+    foreign_only: bool = False
+
+
+# The mandatory facets, in serialization order. Their predicate SET is the single
+# membership emitted by a fully-populated ``provenance.Source.to_triples()`` (D5),
+# pinned by a drift-guard test — it is NOT ``io/research._SOURCE_FACETS`` (which
+# lists Pydantic field NAMES: it includes ``name``, which has no predicate, and
+# omits ``translation``). The IRIs come from the ``golem.namespaces`` constants.
+FACETS: tuple[Facet, ...] = (
+    Facet("type", HAS_TYPE),
+    Facet("reliability", BW_RELIABILITY),
+    Facet("reliability justification", BW_RELIABILITY_JUSTIFICATION),
+    Facet("reference", BW_REFERENCE),
+    Facet("author", BW_AUTHOR),
+    Facet("original language", BW_ORIGINAL_LANGUAGE),
+    Facet("access date", BW_ACCESS_DATE),
+    Facet("original quote", BW_ORIGINAL_QUOTE),
+    Facet("translation", BW_TRANSLATION, foreign_only=True),
+)
+
+# Reliability rank name ← its E55 individual IRI, inverted from the single
+# vocabulary source (``RELIABILITY_IRI``) so the scale never re-spells it (D6).
+_RELIABILITY_NAME: dict[str, str] = {str(iri): name for name, iri in RELIABILITY_IRI.items()}
+
+
+@dataclass(frozen=True)
+class SourceRecord:
+    """One source backing an anchor's promoted finding (R2/R3 working unit).
+
+    ``present_predicates`` is the set of facet-predicate IRI strings the source
+    actually carries (R2 reads it to find gaps); ``original_language`` drives the
+    translation conditionality; ``reliability`` is the rating *name*
+    (``alta``/``media``/``baja``) or ``None`` when the source is unrated.
+    """
+
+    uri: str
+    present_predicates: frozenset[str]
+    original_language: str | None
+    reliability: str | None
+
+
+@dataclass
+class _SourceAccum:
+    """Mutable accumulator while folding a source's triples (one per ``?p``)."""
+
+    predicates: set[str]
+    language: str | None = None
+    reliability_iri: str | None = None
+
+
+def load_sources_by_anchor(indexer: Indexer) -> dict[str, list[SourceRecord]]:
+    """Supporting sources per anchor, reached ``anchor→finding→source`` (D5).
+
+    A source with no describing triple (a dangling ``bw:supportedBy``) still
+    appears — with an empty facet set — so R2 can flag every missing facet. Sources
+    are returned in sorted-URI order per anchor for byte-stable output.
+    """
+    rows = indexer.query(
+        f"""
+        SELECT ?anchor ?source ?p ?o WHERE {{
+          ?anchor <{BW_PROMOTES}> ?finding .
+          ?finding <{BW_SUPPORTED_BY}> ?source .
+          OPTIONAL {{ ?source ?p ?o . }}
+        }}
+        """
+    )
+    by_anchor: dict[str, dict[str, _SourceAccum]] = {}
+    for row in rows:
+        sources = by_anchor.setdefault(row["anchor"], {})
+        acc = sources.setdefault(row["source"], _SourceAccum(predicates=set()))
+        predicate = row.get("p")
+        if predicate is None:
+            continue
+        acc.predicates.add(predicate)
+        if predicate == str(BW_ORIGINAL_LANGUAGE):
+            acc.language = row.get("o")
+        elif predicate == str(BW_RELIABILITY):
+            acc.reliability_iri = row.get("o")
+    return {
+        anchor: [
+            SourceRecord(
+                uri=source,
+                present_predicates=frozenset(acc.predicates),
+                original_language=acc.language,
+                reliability=_RELIABILITY_NAME.get(acc.reliability_iri or ""),
+            )
+            for source, acc in sorted(sources.items())
+        ]
+        for anchor, sources in by_anchor.items()
+    }
+
+
+def entity_present(indexer: Indexer, uri: str, uri_base: str) -> bool:
+    """Whether ``uri`` denotes a present graph entity (R4 presence test, D4).
+
+    True when the URI is the subject of at least one triple, or when it is the
+    well-known (untyped) timeline IRI — a legitimate ``bw:constrains`` target that
+    carries no describing triple of its own.
+    """
+    if uri == str(timeline_uri(uri_base)):
+        return True
+    rows = list(indexer.query(f"SELECT ?p WHERE {{ <{uri}> ?p ?o . }} LIMIT 1"))
+    return bool(rows)

bookwright/validation/base.py

@@ -0,0 +1,233 @@
+"""Core finding types and the validator seam (data-model, contracts/validator-protocol.md).
+
+In-memory only; the subsystem persists nothing (FR-020). Every type here is frozen
+where it can be, so findings are hashable and dedupe is trivial (D8).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, runtime_checkable
+
+from bookwright.errors import BookwrightError
+from bookwright.indexers import Indexer
+
+if TYPE_CHECKING:
+    from bookwright.core.manifest import Manifest
+    from bookwright.golem.base import SluggedEntity
+    from bookwright.io.bible import MapResult
+
+__all__ = [
+    "Severity",
+    "UnknownValidatorError",
+    "ValidationContext",
+    "Validator",
+    "ValidatorError",
+    "Violation",
+    "split_source",
+]
+
+
+class Severity(StrEnum):
+    """A finding's level. String-valued (JSON-friendly, design § 13.1)."""
+
+    error = "error"
+    warning = "warning"
+    info = "info"
+
+    def at_least(self, threshold: Severity) -> bool:
+        """Whether this severity meets ``threshold`` under ``error > warning > info``."""
+        return _RANK[self] >= _RANK[threshold]
+
+
+_RANK: dict[Severity, int] = {Severity.error: 2, Severity.warning: 1, Severity.info: 0}
+"""Ordinal for the ``--severity`` threshold, the gate, and the total-order sort."""
+
+
+def split_source(source: str | None) -> tuple[str | None, int | None]:
+    """Split a ``relpath[:line]`` provenance string into ``(path, line)``.
+
+    The ``:line`` suffix is recognized only when a non-empty path precedes a
+    digit-only tail; otherwise the whole string is the path and the line is ``None``.
+    ``source=None`` yields ``(None, None)``. This is the single place the ``source``
+    grammar is parsed — every consumer (``Violation`` accessors, the report scope
+    filter, provenance resolution) routes through it so the parsing never forks.
+    """
+    if source is None:
+        return None, None
+    head, sep, tail = source.rpartition(":")
+    if head and sep and tail.isdigit():
+        return head, int(tail)
+    return source, None
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One finding produced by a validator (FR-002/003).
+
+    ``frozen=True`` + tuple fields make it hashable so identical findings collapse
+    to one in the runner (D8). ``source`` is a project-relative posix path, optionally
+    ``:line``; ``None`` when no specific location applies (location-less).
+    """
+
+    validator: str
+    severity: Severity
+    message: str
+    source: str | None = None
+    triples: tuple[tuple[str, str, str], ...] = ()
+
+    def source_file(self) -> str | None:
+        """The path part of ``source`` (drops any ``:line`` suffix), or ``None``."""
+        return split_source(self.source)[0]
+
+    def source_line(self) -> int | None:
+        """The 1-based line from ``source`` when present, else ``None``."""
+        return split_source(self.source)[1]
+
+    def to_json(self) -> dict[str, Any]:
+        """Serialize to the contract shape (FR-002, SC-004); ``triples`` as lists."""
+        return {
+            "validator": self.validator,
+            "severity": self.severity.value,
+            "message": self.message,
+            "source": self.source,
+            "triples": [list(triple) for triple in self.triples],
+        }
+
+
+@dataclass(frozen=True)
+class ValidatorError:
+    """A validator that could not be loaded or that raised while running (FR-014).
+
+    Surfaced in the report's ``errors[]``; never affects the gate. ``validator`` is
+    the validator name, or the offending file path for ``phase="load"`` failures.
+    """
+
+    validator: str
+    message: str
+    phase: Literal["load", "run"]
+
+    def to_json(self) -> dict[str, Any]:
+        return {"validator": self.validator, "phase": self.phase, "message": self.message}
+
+
+@runtime_checkable
+class Validator(Protocol):
+    """The stable seam between the runner and any validator (design § 13.1).
+
+    A validator examines the project (``ValidationContext``) and the already-built
+    graph (``indexer``, possibly empty) and returns a list of ``Violation`` — an
+    empty list means "no problems" (FR-001). It MUST be deterministic (FR-019) and
+    MUST NOT write to disk or mutate the graph (FR-020); it MAY raise — the runner
+    isolates it (FR-014).
+    """
+
+    name: str
+    severity_default: Severity
+
+    def validate(self, project: ValidationContext, indexer: Indexer) -> list[Violation]: ...
+
+
+class UnknownValidatorError(BookwrightError):
+    """A configured ``[validators]`` name is absent from the discovered set (FR-007)."""
+
+    code = "unknown_validator"
+
+    def __init__(self, names: tuple[str, ...]) -> None:
+        self.names = names
+        joined = ", ".join(names)
+        super().__init__(f"unknown validator(s): {joined}", {"names": list(names)})
+
+
+# Sentinel distinguishing "not yet computed" from a cached ``None`` result.
+_UNSET = object()
+
+
+@dataclass
+class ValidationContext:
+    """The ``project`` argument to every validator (data-model).
+
+    Bundles the project root + manifest and exposes cached accessors so each source
+    file is read once per run and shared across validators. Accessors memoize on
+    first call.
+    """
+
+    root: Path
+    manifest: Manifest
+
+    _bible: Any = field(default=_UNSET, repr=False, compare=False)
+    _character_names: Any = field(default=_UNSET, repr=False, compare=False)
+    _setting_names: Any = field(default=_UNSET, repr=False, compare=False)
+    _manuscript_files: Any = field(default=_UNSET, repr=False, compare=False)
+    _constitution_text: Any = field(default=_UNSET, repr=False, compare=False)
+
+    @property
+    def uri_base(self) -> str:
+        return self.manifest.bookwright.uri_base
+
+    def bible(self) -> MapResult:
+        """Map the project's bible to GOLEM entities (once per run)."""
+        if self._bible is _UNSET:
+            from bookwright.io.bible import map_bible  # noqa: PLC0415
+
+            bible_dir = self.root / self.manifest.paths.bible
+            self._bible = map_bible(self.root, bible_dir, self.uri_base)
+        return cast("MapResult", self._bible)
+
+    def _names_of(self, concept_cls: type[SluggedEntity]) -> tuple[tuple[str, str], ...]:
+        """Sorted ``(name, bible_relpath)`` pairs for one bible concept class."""
+        names = [
+            (entity.name, mapped.relpath)
+            for mapped in self.bible().mapped
+            if isinstance((entity := mapped.entity), concept_cls)
+        ]
+        return tuple(sorted(names))
+
+    def character_names(self) -> tuple[tuple[str, str], ...]:
+        """Sorted ``(name, bible_relpath)`` for every bible Character."""
+        if self._character_names is _UNSET:
+            from bookwright.golem import Character  # noqa: PLC0415
+
+            self._character_names = self._names_of(Character)
+        return cast("tuple[tuple[str, str], ...]", self._character_names)
+
+    def setting_names(self) -> tuple[tuple[str, str], ...]:
+        """Sorted ``(name, bible_relpath)`` for every bible Setting."""
+        if self._setting_names is _UNSET:
+            from bookwright.golem import Setting  # noqa: PLC0415
+
+            self._setting_names = self._names_of(Setting)
+        return cast("tuple[tuple[str, str], ...]", self._setting_names)
+
+    def manuscript_files(self) -> tuple[tuple[str, str], ...]:
+        """Sorted ``(relpath, text)`` for every ``**/*.md`` under the manuscript dir.
+
+        Unreadable files are skipped defensively (a validator never aborts on one
+        bad file). Sorted by relpath for determinism (D8).
+        """
+        if self._manuscript_files is _UNSET:
+            manuscript_dir = self.root / self.manifest.paths.manuscript
+            collected: list[tuple[str, str]] = []
+            if manuscript_dir.is_dir():
+                for path in sorted(manuscript_dir.rglob("*.md")):
+                    if not path.is_file():
+                        continue
+                    try:
+                        text = path.read_text(encoding="utf-8")
+                    except (OSError, UnicodeDecodeError):
+                        continue
+                    collected.append((path.relative_to(self.root).as_posix(), text))
+            self._manuscript_files = tuple(sorted(collected))
+        return cast("tuple[tuple[str, str], ...]", self._manuscript_files)
+
+    def constitution_text(self) -> str | None:
+        """The constitution file's text, or ``None`` when absent/unreadable."""
+        if self._constitution_text is _UNSET:
+            path = self.root / self.manifest.paths.constitution
+            try:
+                self._constitution_text = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                self._constitution_text = None
+        return cast("str | None", self._constitution_text)

bookwright/validation/queries.py

@@ -0,0 +1,197 @@
+"""Read-only graph projections for the ``temporal`` validator (data-model, D11/D12).
+
+These helpers turn the interval graph the timeline indexer emits into plain
+in-memory shapes (``EventInterval`` + relation edge sets) the validator reasons
+over, so ``temporal`` never touches rdflib directly. SPARQL is run through the
+``Indexer`` seam (``indexer.query``); every traversal is insensitive to whether a
+year sits on a boundary directly or on its ``Dimension`` sub-node.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rdflib.namespace import RDF, RDFS, XSD
+
+from bookwright.golem.namespaces import (
+    ASSIGNED_ATTRIBUTE_TO,
+    CRM,
+    CSM,
+    GOLEM,
+    TEMPORAL_RELATIONS,
+    TR,
+    USED_SPECIFIC_OBJECT,
+)
+from bookwright.indexers import Indexer
+from bookwright.validation.base import split_source
+
+__all__ = [
+    "EventInterval",
+    "intervals_disjoint",
+    "load_intervals",
+    "load_relations",
+    "parse_gyear",
+    "resolve_source",
+    "timeline_bounds",
+]
+
+_PREFIXES = "\n".join(
+    f"PREFIX {prefix}: <{uri}>"
+    for prefix, uri in (
+        ("golem", str(GOLEM)),
+        ("crm", str(CRM)),
+        ("tr", str(TR)),
+        ("csm", str(CSM)),
+        ("rdf", str(RDF)),
+        ("rdfs", str(RDFS)),
+        ("xsd", str(XSD)),
+    )
+)
+
+
+@dataclass(frozen=True)
+class EventInterval:
+    """One event's begin/end years (either may be ``None`` for an open interval)."""
+
+    uri: str
+    begin: int | None
+    end: int | None
+
+
+def _q(indexer: Indexer, body: str) -> list[dict[str, str]]:
+    return list(indexer.query(f"{_PREFIXES}\n{body}"))
+
+
+def parse_gyear(raw: str) -> int | None:
+    """Coerce an ``xsd:gYear`` lexical (``"1885"``, ``"0800"``, ``"-0044"``) to int.
+
+    The single ``gYear`` parser for the ``temporal`` and ``factual_anchor``
+    validators: ``temporal`` reads event boundary years through it (via
+    :func:`load_intervals`) and ``factual_anchor`` reads anchor time-span years
+    through it (via ``anchor_queries.load_anchors``), so both coerce identically.
+    """
+    text = raw.strip()
+    negative = text.startswith("-")
+    digits = text[1:] if negative else text
+    if not digits.isdigit():
+        return None
+    value = int(digits)
+    return -value if negative else value
+
+
+def intervals_disjoint(a: EventInterval, b: EventInterval) -> bool:
+    """True when two closed year ranges provably do not overlap (FR-011, research D1).
+
+    The **single source of truth** for "two intervals contradict": both the
+    ``temporal`` validator (overlap-disjoint rule) and ``factual_anchor`` (the
+    anachronism rule) decide disjointness here and nowhere else. An open bound
+    (``None``) is unbounded on that side, so it can never force disjointness — an
+    open-ended interval cannot be *proven* disjoint from anything.
+    """
+    return (a.end is not None and b.begin is not None and a.end < b.begin) or (
+        b.end is not None and a.begin is not None and b.end < a.begin
+    )
+
+
+def load_intervals(indexer: Indexer) -> dict[str, EventInterval]:
+    """One :class:`EventInterval` per ``G5_Narrative_Event`` in the graph.
+
+    The year is reached via ``(csm:duration|tr:temporal-location)/tr:temporal-location``
+    to a boundary whose ``crm:P2_has_type`` localname is ``begin`` / ``end``, then
+    ``(crm:P90_has_value | crm:P43_has_dimension/crm:P90_has_value)`` — so it is
+    insensitive to the carrier-node shape (D12). Events without an interval still
+    appear, with both bounds ``None``.
+    """
+    intervals: dict[str, list[int | None]] = {
+        row["event"]: [None, None]
+        for row in _q(indexer, "SELECT ?event WHERE { ?event a golem:G5_Narrative_Event . }")
+    }
+    rows = _q(
+        indexer,
+        """
+        SELECT ?event ?btype ?year WHERE {
+          ?event a golem:G5_Narrative_Event .
+          ?event (csm:duration|tr:temporal-location)/tr:temporal-location ?boundary .
+          ?boundary crm:P2_has_type ?btype .
+          ?boundary (crm:P90_has_value | crm:P43_has_dimension/crm:P90_has_value) ?year .
+        }
+        """,
+    )
+    for row in rows:
+        event, btype, year = row["event"], row["btype"], parse_gyear(row["year"])
+        if event not in intervals or year is None:
+            continue
+        if btype.endswith("/begin"):
+            intervals[event][0] = year
+        elif btype.endswith("/end"):
+            intervals[event][1] = year
+    return {
+        event: EventInterval(uri=event, begin=bounds[0], end=bounds[1])
+        for event, bounds in intervals.items()
+    }
+
+
+def timeline_bounds(intervals: dict[str, EventInterval]) -> EventInterval:
+    """The timeline's overall ``(min begin, max end)`` across the given events (D3).
+
+    A **pure** reduction over an already-loaded :func:`load_intervals` result — it
+    adds **no** new interval reasoning — used by ``factual_anchor`` when an anchor
+    constrains the timeline as a whole. Both bounds are ``None`` when no event carries
+    a year. The ``uri`` is a sentinel label (the timeline has no single typed node,
+    research D10). It takes the loaded dict (not the indexer) so the caller reuses one
+    :func:`load_intervals` pass rather than querying the graph a second time.
+    """
+    begins = [iv.begin for iv in intervals.values() if iv.begin is not None]
+    ends = [iv.end for iv in intervals.values() if iv.end is not None]
+    return EventInterval(
+        uri="timeline",
+        begin=min(begins) if begins else None,
+        end=max(ends) if ends else None,
+    )
+
+
+def load_relations(indexer: Indexer) -> dict[str, set[tuple[str, str]]]:
+    """The five ``TR:*`` edge sets, keyed by canonical relation name (D11).
+
+    Keys are :data:`TEMPORAL_RELATIONS` names (``follows`` … ``included_in``). Each
+    set holds ``(subject, object)`` event-URI pairs. Only edges between two narrative
+    events are kept, so a stray edge never leaks into the reasoning.
+    """
+    relations: dict[str, set[tuple[str, str]]] = {}
+    for relation in TEMPORAL_RELATIONS:
+        rows = _q(
+            indexer,
+            f"""
+            SELECT ?a ?b WHERE {{
+              ?a a golem:G5_Narrative_Event .
+              ?b a golem:G5_Narrative_Event .
+              ?a <{relation.predicate}> ?b .
+            }}
+            """,
+        )
+        relations[relation.name] = {(row["a"], row["b"]) for row in rows}
+    return relations
+
+
+def resolve_source(indexer: Indexer, uri: str) -> str | None:
+    """Recover the ``relpath[:line]`` provenance string for a graph entity (D6).
+
+    Reads the CIDOC provenance edge: an ``E13_Attribute_Assignment`` whose
+    ``P140_assigned_attribute_to`` is ``uri`` carries the source on
+    ``P16_used_specific_object``. When several exist, prefer one with a ``:line``
+    suffix, then the lexicographically smallest, for a deterministic result.
+    """
+    rows = _q(
+        indexer,
+        f"""
+        SELECT ?source WHERE {{
+          ?assertion <{ASSIGNED_ATTRIBUTE_TO}> <{uri}> .
+          ?assertion <{USED_SPECIFIC_OBJECT}> ?source .
+        }}
+        """,
+    )
+    sources = sorted({row["source"] for row in rows})
+    if not sources:
+        return None
+    located = [s for s in sources if split_source(s)[1] is not None]
+    return located[0] if located else sources[0]