bookwright-cli 0.2.0__py3-none-any.whl

bookwright/golem/modules/relationship.py

@@ -0,0 +1,38 @@
+"""Relationship module: social relationships and the roles within them."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rdflib.term import URIRef
+
+from bookwright.golem.base import CrossRef, GolemEntity, SluggedEntity
+from bookwright.golem.namespaces import CLASS_IRI, PARTICIPANT, REFERS_TO
+
+
+class SocialRelationship(SluggedEntity):
+    """A social relationship (``golem:G4_Social_Relationship``).
+
+    Each participant is linked by one ``dlp:participant`` triple (FR-015).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["SocialRelationship"]
+    path_segment: ClassVar[str] = "relationship"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (
+        CrossRef("participants", PARTICIPANT, multi=True),
+    )
+
+    participants: tuple[GolemEntity | URIRef, ...] = ()
+
+
+class RelationshipRole(SluggedEntity):
+    """A relationship role (``golem:G6_Relationship_Role``).
+
+    When set, the role refers to its owning relationship (``crm:P67_refers_to``).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["RelationshipRole"]
+    path_segment: ClassVar[str] = "relationship-role"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (CrossRef("relationship", REFERS_TO),)
+
+    relationship: GolemEntity | URIRef | None = None

bookwright/golem/modules/setting.py

@@ -0,0 +1,30 @@
+"""Setting module: settings and the narrative locations placed within them."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rdflib.term import URIRef
+
+from bookwright.golem.base import CrossRef, GolemEntity, SluggedEntity
+from bookwright.golem.namespaces import CLASS_IRI, GENERIC_LOCATION
+
+
+class Setting(SluggedEntity):
+    """A setting (``golem:G12_Setting``). Identity only in v0."""
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["Setting"]
+    path_segment: ClassVar[str] = "setting"
+
+
+class NarrativeLocation(SluggedEntity):
+    """A narrative location (``golem:G13_Narrative_Location``).
+
+    When set, the location is ``dlp:generic-location`` of its setting (FR-015).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeLocation"]
+    path_segment: ClassVar[str] = "location"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (CrossRef("setting", GENERIC_LOCATION),)
+
+    setting: GolemEntity | URIRef | None = None

bookwright/golem/namespaces.py

@@ -0,0 +1,332 @@
+"""Namespaces, class/predicate IRIs, prefix binding and the frozen ontology.
+
+All IRIs are hard-coded (confirmed against the vendored ``golem.ttl`` @
+``f666128a…``); the Turtle is never parsed at import time, keeping construction
+cheap and side-effect-free (research D5). The frozen ontology is loaded only by
+:func:`load_frozen_ontology` / :func:`frozen_terms`, which back the term-closure
+test (SC-003).
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import NamedTuple
+
+from rdflib import Graph, Namespace
+from rdflib.namespace import RDF, RDFS, XSD
+from rdflib.term import URIRef
+
+from bookwright.resources.schemas import SCHEMA_DIR
+
+__all__ = [
+    "ASSIGNED",
+    "ASSIGNED_ATTRIBUTE_TO",
+    "BEGIN_OF_BEGIN",
+    "BW",
+    "BW_ACCESS_DATE",
+    "BW_ASSERTED_BY",
+    "BW_AUTHOR",
+    "BW_CLAIM",
+    "BW_CONSTRAINS",
+    "BW_OPEN",
+    "BW_ORIGINAL_LANGUAGE",
+    "BW_ORIGINAL_QUOTE",
+    "BW_PROMOTES",
+    "BW_REFERENCE",
+    "BW_RELIABILITY",
+    "BW_RELIABILITY_JUSTIFICATION",
+    "BW_SUPPORTED_BY",
+    "BW_TRANSLATION",
+    "CLASS_IRI",
+    "CRM",
+    "CSM",
+    "DLP",
+    "DURATION",
+    "E52_TIME_SPAN",
+    "EDNS",
+    "END_OF_END",
+    "FOLLOWS",
+    "GENERICALLY_DEPENDENT_ON",
+    "GENERIC_LOCATION",
+    "GOLEM",
+    "HAS_DIMENSION",
+    "HAS_FEATURE",
+    "HAS_TIME_SPAN",
+    "HAS_TYPE",
+    "HAS_VALUE",
+    "PARTICIPANT",
+    "PLAYS",
+    "PRECEDES",
+    "PROPER_PART",
+    "RDF",
+    "RDFS",
+    "REFERS_TO",
+    "RELIABILITY_IRI",
+    "SOURCE_TYPE_IRI",
+    "TEMPORALLY_INCLUDED_IN",
+    "TEMPORALLY_INCLUDES",
+    "TEMPORALLY_OVERLAPS",
+    "TEMPORAL_LOCATION",
+    "TEMPORAL_RELATIONS",
+    "TR",
+    "USED_SPECIFIC_OBJECT",
+    "XSD",
+    "TemporalRelation",
+    "bind_prefixes",
+    "frozen_terms",
+    "load_frozen_ontology",
+    "timeline_uri",
+]
+
+# --- Namespaces -------------------------------------------------------------
+
+GOLEM = Namespace("https://w3id.org/golem/ontology#")
+CRM = Namespace("http://www.cidoc-crm.org/cidoc-crm/")
+# The DOLCE-Lite-Plus layer the frozen GOLEM ontology actually emits its
+# participation / part / dependence / location predicates from (research D5).
+DLP = Namespace("http://www.ontologydesignpatterns.org/ont/dlp/DOLCE-Lite.owl#")
+# The DOLCE ExtendedDnS layer that supplies ``plays`` (character →
+# narrative role) — a *different* file from the DOLCE-Lite ``DLP`` above, kept
+# bound to its own ``edns`` prefix so the distinction stays visible (FR-018).
+EDNS = Namespace("http://www.ontologydesignpatterns.org/ont/dlp/ExtendedDnS.owl#")
+# The DOLCE TemporalRelations layer: the five qualitative event relations plus
+# ``temporal-location`` (interval → boundary). All five relations are frozen
+# (research D11, verified against ``golem.ttl``).
+TR = Namespace("http://www.ontologydesignpatterns.org/ont/dlp/TemporalRelations.owl#")
+# The DOLCE CommonSenseMapping layer supplying ``duration`` (event → its
+# time-interval, ⊑ ``temporal-location``).
+CSM = Namespace("http://www.ontologydesignpatterns.org/ont/dlp/CommonSenseMapping.owl#")
+# Bookwright's own vocabulary — the research/provenance terms (``bw:reference``,
+# ``bw:claim``, ``bw:constrains``, the source-type / reliability E55 individuals).
+# Declared in ``resources/vocabularies/sources.ttl``, **never** in the frozen
+# ``golem.ttl``; intentionally outside the ``CLASS_IRI`` closure (Constitution X;
+# research D3).
+BW = Namespace("https://bookwright.dev/vocab/bw#")
+
+_PREFIXES: tuple[tuple[str, Namespace], ...] = (
+    ("golem", GOLEM),
+    ("crm", CRM),
+    ("dlp", DLP),
+    ("edns", EDNS),
+    ("tr", TR),
+    ("csm", CSM),
+    ("bw", BW),
+    ("rdf", Namespace(str(RDF))),
+    ("rdfs", Namespace(str(RDFS))),
+    ("xsd", Namespace(str(XSD))),
+)
+
+
+def bind_prefixes(graph: Graph) -> None:
+    """Bind exactly one short prefix per namespace, deterministically (FR-010).
+
+    ``replace=True`` overrides rdflib's auto-bound aliases so serialized Turtle
+    is byte-stable across runs.
+    """
+    for prefix, namespace in _PREFIXES:
+        graph.bind(prefix, namespace, replace=True, override=True)
+
+
+# --- Concept class IRIs (FR-004 local names) --------------------------------
+
+CLASS_IRI: dict[str, URIRef] = {
+    "Character": GOLEM["G1_Character"],
+    "Object": GOLEM["G16_Object"],
+    "SocialRelationship": GOLEM["G4_Social_Relationship"],
+    "RelationshipRole": GOLEM["G6_Relationship_Role"],
+    "NarrativeEvent": GOLEM["G5_Narrative_Event"],
+    "PsychologicalState": GOLEM["G3_Psychological_State"],
+    "Setting": GOLEM["G12_Setting"],
+    "NarrativeLocation": GOLEM["G13_Narrative_Location"],
+    "NarrativeUnit": GOLEM["G9_Narrative_Unit"],
+    "NarrativeFunction": GOLEM["G10_Narrative_Function"],
+    "NarrativeRole": GOLEM["G11_Narrative_Role"],
+    "NarrativeSequence": GOLEM["G7_Narrative_Sequence"],
+    "AttributeAssignment": CRM["E13_Attribute_Assignment"],
+    # Character-scoped attribute-carrier classes (FR-020). These are NOT
+    # narrative concepts — they are excluded from the CONCEPTS registry — but
+    # their rdf:type IRIs live here so the closure test (SC-003) covers them too.
+    "CharacterFeature": GOLEM["G17_Character_Feature"],
+    "Dimension": CRM["E54_Dimension"],
+    "Type": CRM["E55_Type"],
+    # The DOLCE-Lite time-interval carrying an event's begin/end boundaries
+    # (research D11). Closure-safe — emitted by NarrativeEvent's interval triples.
+    "TimeInterval": DLP["time-interval"],
+}
+"""Class name → rdf:type IRI. Every value is asserted ∈ frozen_terms() (SC-003)."""
+
+# --- Cross-reference predicate IRIs (FR-015) -------------------------------
+
+PARTICIPANT = DLP["participant"]
+"""Perdurant → endurant participation (relationship / event participants)."""
+PROPER_PART = DLP["proper-part"]
+"""Whole → ordered part (narrative sequence → its units)."""
+GENERICALLY_DEPENDENT_ON = DLP["generically-dependent-on"]
+"""Dependent → bearer (psychological state → its character)."""
+GENERIC_LOCATION = DLP["generic-location"]
+"""Located → locus (narrative location → its setting)."""
+REFERS_TO = CRM["P67_refers_to"]
+"""Generic cross-reference (role → relationship, unit → function/role, premise)."""
+ASSIGNED_ATTRIBUTE_TO = CRM["P140_assigned_attribute_to"]
+"""Attribute assignment → the entity it makes an attribution about."""
+ASSIGNED = CRM["P141_assigned"]
+"""Attribute assignment → the attribute it asserts."""
+USED_SPECIFIC_OBJECT = CRM["P16_used_specific_object"]
+"""Attribute assignment → the source used in the inference (carries the path)."""
+
+# --- Character-attribute predicates (FR-017/018/019, D14) -------------------
+
+HAS_FEATURE = GOLEM["GP0_has_feature"]
+"""Character → one of its character features (biographical or free-text)."""
+PLAYS = EDNS["plays"]
+"""Character → a narrative role it plays (DOLCE ExtendedDnS, distinct from dlp)."""
+HAS_TYPE = CRM["P2_has_type"]
+"""Biographical feature → its E55_Type (the birth / death individual)."""
+HAS_DIMENSION = CRM["P43_has_dimension"]
+"""Biographical feature → its E54_Dimension (carrying the year value)."""
+HAS_VALUE = CRM["P90_has_value"]
+"""Dimension → its primitive value (the year as an xsd:gYear literal)."""
+
+# --- Temporal-interval predicates (FR-015, research D11) --------------------
+
+DURATION = CSM["duration"]
+"""Event → its time-interval (⊑ ``temporal-location``); carries the begin/end span."""
+TEMPORAL_LOCATION = TR["temporal-location"]
+"""Interval → one of its begin/end boundary intervals."""
+FOLLOWS = TR["follows"]
+"""Event strictly after another (the canonical strict-order relation)."""
+PRECEDES = TR["precedes"]
+"""Event strictly before another (inverse direction of ``follows``)."""
+TEMPORALLY_OVERLAPS = TR["temporally-overlaps"]
+"""Two events share part of their extent (symmetric)."""
+TEMPORALLY_INCLUDES = TR["temporally-includes"]
+"""Event whose extent contains another's (containment)."""
+TEMPORALLY_INCLUDED_IN = TR["temporally-included-in"]
+"""Event whose extent is contained within another's (inverse containment)."""
+
+# --- Research / provenance predicates (iteration 012, research D3) -----------
+# Bookwright's own ``bw:`` terms. Declared in ``sources.ttl``, referenced from
+# ``golem/modules/provenance.py``; NONE are added to ``CLASS_IRI`` or the
+# closure-checked lists in ``test_namespaces.py`` — they sit outside the frozen
+# GOLEM ontology by design (Constitution X).
+
+BW_REFERENCE = BW["reference"]
+"""Source → its bibliographic reference or URL (``xsd:string``)."""
+BW_AUTHOR = BW["author"]
+"""Source → its author (``xsd:string``)."""
+BW_ORIGINAL_LANGUAGE = BW["originalLanguage"]
+"""Source → the ISO 639-1 code of its original language (``xsd:string``)."""
+BW_RELIABILITY = BW["reliability"]
+"""Source → its reliability E55_Type individual (``alta``/``media``/``baja``)."""
+BW_RELIABILITY_JUSTIFICATION = BW["reliabilityJustification"]
+"""Source → the prose justifying its reliability rating (``xsd:string``)."""
+BW_ACCESS_DATE = BW["accessDate"]
+"""Source → the date it was consulted (``xsd:date``)."""
+BW_ORIGINAL_QUOTE = BW["originalQuote"]
+"""Source → the verbatim quote in its original language (``xsd:string``)."""
+BW_TRANSLATION = BW["translation"]
+"""Source → the quote's translation; emitted iff source language ≠ book language."""
+BW_CLAIM = BW["claim"]
+"""Finding → the real-world assertion it records (``xsd:string``)."""
+BW_ASSERTED_BY = BW["assertedBy"]
+"""Finding → who asserts the claim — agent or author (``xsd:string``)."""
+BW_SUPPORTED_BY = BW["supportedBy"]
+"""Finding → one supporting Source (one triple per source)."""
+BW_OPEN = BW["open"]
+"""Finding → ``true`` when it is an unresolved open question (``xsd:boolean``)."""
+BW_PROMOTES = BW["promotes"]
+"""Anchor → the Finding it promotes into a binding constraint."""
+BW_CONSTRAINS = BW["constrains"]
+"""Anchor → the narrative entity (or the timeline) the constraint bears on."""
+
+SOURCE_TYPE_IRI: dict[str, URIRef] = {
+    "primaria": BW["source-type/primaria"],
+    "secundaria": BW["source-type/secundaria"],
+    "oficial": BW["source-type/oficial"],
+    "académica": BW["source-type/academica"],
+    "periodística": BW["source-type/periodistica"],
+    "testimonial": BW["source-type/testimonial"],
+}
+"""Front-matter ``type`` value → its ``a crm:E55_Type`` individual (ASCII-slugged
+IRI). The accented Spanish key is the author-facing value; the IRI is slugged
+(research D4). Declared in ``sources.ttl``; enforced by the ``Source`` ``Literal``."""
+
+RELIABILITY_IRI: dict[str, URIRef] = {
+    "alta": BW["reliability/alta"],
+    "media": BW["reliability/media"],
+    "baja": BW["reliability/baja"],
+}
+"""Front-matter ``reliability`` value → its ``a crm:E55_Type`` individual IRI."""
+
+# --- Reused CIDOC-CRM time-span terms (anchor time-span, research D5) --------
+# Already-bound ``crm:`` predicates/classes referenced directly; never added to
+# ``CLASS_IRI`` (the frozen closure is GOLEM's, not the whole of CIDOC-CRM).
+
+HAS_TIME_SPAN = CRM["P4_has_time-span"]
+"""Anchor → its ``E52_Time-Span`` sub-node (optional, research D5)."""
+E52_TIME_SPAN = CRM["E52_Time-Span"]
+"""``rdf:type`` of an anchor's time-span sub-node."""
+BEGIN_OF_BEGIN = CRM["P82a_begin_of_the_begin"]
+"""Time-span → its begin year (``xsd:gYear``)."""
+END_OF_END = CRM["P82b_end_of_the_end"]
+"""Time-span → its end year (``xsd:gYear``)."""
+
+
+def timeline_uri(uri_base: str) -> URIRef:
+    """The well-known, **untyped** timeline IRI an anchor constrains (research D10).
+
+    GOLEM has no single node for "the timeline" (it is a collection of events), yet
+    FR-009 lets an anchor constrain it. This returns the conventional ``{uri_base}
+    timeline`` IRI — referenced as the object of ``bw:constrains`` only, never typed
+    — so era-level anchors resolve without introducing a new GOLEM class.
+    """
+    return URIRef(f"{uri_base}timeline")
+
+
+class TemporalRelation(NamedTuple):
+    """One qualitative event-to-event temporal relation (research D11).
+
+    ``name`` is the single canonical key used across every layer — the bible
+    frontmatter key, the :class:`NarrativeEvent` field, the SPARQL projection key,
+    and the validator's predicate map — so the layers never drift apart or fork on
+    spelling. ``predicate`` is the frozen ``TR:*`` IRI the relation serializes to.
+    """
+
+    name: str
+    predicate: URIRef
+
+
+TEMPORAL_RELATIONS: tuple[TemporalRelation, ...] = (
+    TemporalRelation("follows", FOLLOWS),
+    TemporalRelation("precedes", PRECEDES),
+    TemporalRelation("overlaps", TEMPORALLY_OVERLAPS),
+    TemporalRelation("includes", TEMPORALLY_INCLUDES),
+    TemporalRelation("included_in", TEMPORALLY_INCLUDED_IN),
+)
+"""The five qualitative temporal relations, in canonical order — the single source
+of truth every consumer derives its own view from (cross_refs, bible keys, queries,
+the ``temporal`` validator)."""
+
+# --- Frozen ontology --------------------------------------------------------
+
+_SCHEMA_PACKAGE = "bookwright.resources.schemas"
+_ONTOLOGY_RELPATH = f"{SCHEMA_DIR}/golem.ttl"
+
+
+def load_frozen_ontology() -> Graph:
+    """Parse the vendored frozen GOLEM ontology into a fresh rdflib graph."""
+    resource = resources.files(_SCHEMA_PACKAGE).joinpath(_ONTOLOGY_RELPATH)
+    data = resource.read_text(encoding="utf-8")
+    graph = Graph()
+    graph.parse(data=data, format="turtle")
+    return graph
+
+
+def frozen_terms() -> set[URIRef]:
+    """Every IRI defined or referenced in the frozen ontology (closure backstop).
+
+    Term closure (SC-003) holds iff every class/predicate emitted by any
+    ``to_triples()`` is a member of this set.
+    """
+    graph = load_frozen_ontology()
+    return {term for triple in graph for term in triple if isinstance(term, URIRef)}

bookwright/golem/serialize.py

@@ -0,0 +1,25 @@
+"""Collection-level Turtle serialization (research D8, FR-012)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from rdflib import Graph
+
+from bookwright.golem.base import GolemEntity
+from bookwright.golem.namespaces import bind_prefixes
+
+
+def to_turtle(entities: Iterable[GolemEntity]) -> str:
+    """Serialize ``entities`` to a single prefixed Turtle document.
+
+    Builds a fresh graph, binds the short prefixes (FR-010), adds every triple
+    each entity yields, and serializes. The output parses back through rdflib
+    and round-trips isomorphically (SC-004).
+    """
+    graph = Graph()
+    bind_prefixes(graph)
+    for entity in entities:
+        for triple in entity.to_triples():
+            graph.add(triple)
+    return graph.serialize(format="turtle")

bookwright/golem/slug.py

@@ -0,0 +1,22 @@
+"""Deterministic, ASCII-only slug generation (design § 4.5, FR-005/006)."""
+
+from __future__ import annotations
+
+from slugify import slugify
+
+from bookwright.golem.errors import EmptySlugError
+
+
+def make_slug(name: str) -> str:
+    """Return the canonical slug for ``name``.
+
+    Uses ``python-slugify`` in its default mode: lowercase, ASCII
+    transliteration (``José Peña`` → ``jose-pena``), single-hyphen separators,
+    edges trimmed. The rule is pure, so the same name always yields the same
+    slug (FR-005). A name that reduces to the empty string (e.g. punctuation
+    only) is rejected loudly with :class:`EmptySlugError` (FR-006).
+    """
+    slug = slugify(name)
+    if not slug:
+        raise EmptySlugError(name)
+    return slug

bookwright/indexers/__init__.py

@@ -0,0 +1,47 @@
+"""Pluggable graph-engine seam: the ``Indexer`` protocol + a name→class registry.
+
+Adding a future engine is one ``INDEXER_REGISTRY`` entry — never a change to
+build/query command code (FR-008). ``GrafeoIndexer`` is intentionally **not**
+registered (deferred to v0.3 — Principle X).
+"""
+
+from __future__ import annotations
+
+from .base import Indexer, IndexTriple
+from .errors import (
+    GraphLoadError,
+    GraphNotBuiltError,
+    IndexerError,
+    InvalidQueryError,
+    UnknownIndexerError,
+)
+from .rdflib_indexer import RdflibIndexer
+
+INDEXER_REGISTRY: dict[str, type[Indexer]] = {"rdflib": RdflibIndexer}
+"""Engine name → concrete class. The manifest's ``[bookwright] indexer`` keys it."""
+
+
+def resolve_indexer(name: str) -> type[Indexer]:
+    """Return the engine class registered under ``name`` (FR-007).
+
+    Raises :class:`UnknownIndexerError` — naming the unknown engine and listing
+    the available ones — when ``name`` is not registered.
+    """
+    try:
+        return INDEXER_REGISTRY[name]
+    except KeyError as exc:
+        raise UnknownIndexerError(name, available=sorted(INDEXER_REGISTRY)) from exc
+
+
+__all__ = [
+    "INDEXER_REGISTRY",
+    "GraphLoadError",
+    "GraphNotBuiltError",
+    "IndexTriple",
+    "Indexer",
+    "IndexerError",
+    "InvalidQueryError",
+    "RdflibIndexer",
+    "UnknownIndexerError",
+    "resolve_indexer",
+]

bookwright/indexers/base.py

@@ -0,0 +1,55 @@
+"""The ``Indexer`` protocol — the stable engine seam build/query depend on.
+
+Both ``graph`` verbs depend only on this structural contract (design § 12.1),
+never on a concrete engine (FR-005/008). A future engine conforms by shape
+alone — ``Protocol`` over ABC keeps it decoupled (R4).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from rdflib.term import Literal, URIRef
+
+IndexTriple = tuple[
+    URIRef | str,
+    URIRef | str,
+    URIRef | Literal | str | int | float,
+]
+"""One triple accepted by :meth:`Indexer.add_triple` (IRI-like ``str`` coerced)."""
+
+
+@runtime_checkable
+class Indexer(Protocol):
+    """A pluggable graph engine (design § 12.1)."""
+
+    def load(self, ttl_path: Path) -> None:
+        """Parse a Turtle file into the engine's graph."""
+        ...
+
+    def save(self, ttl_path: Path) -> None:
+        """Serialize to Turtle with short prefixes bound (FR-015); make parent dirs."""
+        ...
+
+    def add_triple(
+        self,
+        s: URIRef | str,
+        p: URIRef | str,
+        o: URIRef | Literal | str | int | float,
+    ) -> None:
+        """Add one triple; IRI-like ``str`` subjects/predicates coerce to ``URIRef``."""
+        ...
+
+    def query(self, sparql: str) -> Iterable[dict[str, Any]]:
+        """Run a SELECT; yield one dict per row (var → ``str``). Raise on bad SPARQL."""
+        ...
+
+    # NOTE: a `construct(sparql) -> Indexer` verb is intentionally absent — no v0
+    # command runs CONSTRUCT. Re-add it here alongside its first consumer (the
+    # validation system, iteration 10) rather than carrying an unused seam now.
+
+    def count(self) -> int:
+        """Return the number of triples currently held."""
+        ...

bookwright/indexers/errors.py

@@ -0,0 +1,80 @@
+"""Exception hierarchy for the indexer (graph-engine) seam.
+
+Every concrete error inherits the canonical ``--json`` envelope from the shared
+``BookwrightError`` base (Principle IX, data-model § 6); this module declares only
+each error's ``code`` and ``details``.
+"""
+
+from __future__ import annotations
+
+from bookwright.errors import BookwrightError
+
+
+class IndexerError(BookwrightError):
+    """Base for every failure mode the ``bookwright.indexers`` package owns.
+
+    Abstract: declares no ``code`` and is never serialized directly.
+    """
+
+
+class UnknownIndexerError(IndexerError):
+    """The manifest names an engine that is not in ``INDEXER_REGISTRY`` (FR-007).
+
+    Carries the offending name and the sorted set of registered engines so the
+    error names both the unknown engine and the available ones.
+    """
+
+    code = "unknown_indexer"
+
+    def __init__(self, name: str, available: list[str]) -> None:
+        self.name = name
+        self.available = available
+        super().__init__(
+            f"unknown indexer {name!r}; available: {', '.join(available)}",
+            {"name": name, "available": available},
+        )
+
+
+class GraphNotBuiltError(IndexerError):
+    """``graph query`` ran with no ``bible/graph.ttl`` on disk (FR-016)."""
+
+    code = "graph_not_built"
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(
+            f"no graph at {path}; run `bookwright graph build` first",
+            {"path": path},
+        )
+
+
+class GraphLoadError(IndexerError):
+    """``bible/graph.ttl`` exists but the engine could not parse it (FR-016).
+
+    Distinct from :class:`GraphNotBuiltError` (no file at all): the file is there
+    but malformed — e.g. a hand-edit broke the Turtle. Surfaced as a clean error
+    envelope, never a raw rdflib traceback.
+    """
+
+    code = "graph_load_failed"
+
+    def __init__(self, path: str, reason: str) -> None:
+        self.path = path
+        self.reason = reason
+        super().__init__(
+            f"could not parse graph at {path}: {reason}",
+            {"path": path, "reason": reason},
+        )
+
+
+class InvalidQueryError(IndexerError):
+    """A malformed SPARQL string was handed to ``query`` (FR-016).
+
+    No partial rows are yielded before this is raised.
+    """
+
+    code = "invalid_query"
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"invalid SPARQL query: {reason}", {"reason": reason})