bookwright-cli 0.2.0__py3-none-any.whl

bookwright/golem/modules/character.py

@@ -0,0 +1,109 @@
+"""Character module: agents and objects of the storyworld (GOLEM § character)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import ClassVar, TypeVar
+
+from pydantic import PrivateAttr
+from rdflib.term import URIRef
+
+from bookwright.golem.base import CrossRef, DerivedAssertion, GolemEntity, SluggedEntity
+from bookwright.golem.modules.feature import BioKind, CharacterFeature, CharacterRole
+from bookwright.golem.namespaces import CLASS_IRI, HAS_FEATURE, PLAYS
+
+_Node = TypeVar("_Node", bound=GolemEntity)
+
+
+def _dedup_nodes(texts: Iterable[str], factory: Callable[[str], _Node]) -> tuple[_Node, ...]:
+    """Materialize one node per text, dropping later duplicates by URI (FR-021)."""
+    nodes: list[_Node] = []
+    seen: set[URIRef] = set()
+    for text in texts:
+        node = factory(text)
+        if node.uri not in seen:
+            seen.add(node.uri)
+            nodes.append(node)
+    return tuple(nodes)
+
+
+class Character(SluggedEntity):
+    """A character (``golem:G1_Character``).
+
+    Besides its identity, a character may carry the documented frontmatter:
+    ``born`` / ``died`` years, free-text ``features``, and
+    ``narrative_roles``. Each is materialized — once, deterministically, at
+    construction — as a character-scoped node under
+    :mod:`bookwright.golem.modules.feature`, linked by a frozen predicate
+    (``golem:GP0_has_feature`` for features, ``edns:plays`` for roles). A
+    character built with none of the four attributes has empty node tuples and
+    therefore emits only its ``rdf:type`` assertion.
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["Character"]
+    path_segment: ClassVar[str] = "character"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (
+        CrossRef("_feature_nodes", HAS_FEATURE, multi=True, owned=True),
+        CrossRef("_role_nodes", PLAYS, multi=True, owned=True),
+    )
+
+    born: int | None = None
+    died: int | None = None
+    features: tuple[str, ...] = ()
+    narrative_roles: tuple[str, ...] = ()
+
+    _feature_nodes: tuple[CharacterFeature, ...] = PrivateAttr(default=())
+    _role_nodes: tuple[CharacterRole, ...] = PrivateAttr(default=())
+
+    def model_post_init(self, __context: object) -> None:
+        super().model_post_init(__context)  # fixes slug + identity URI first
+
+        # Biographical features live under `feature/bio/…`, structurally apart
+        # from the free-text slug space, so they never collide with free-text
+        # values and only the free-text values need URI dedup (FR-021).
+        biographical: list[CharacterFeature] = []
+        if self.born is not None:
+            biographical.append(self._biographical("birth", self.born))
+        if self.died is not None:
+            biographical.append(self._biographical("death", self.died))
+        free_text = _dedup_nodes(
+            self.features,
+            lambda text: CharacterFeature(
+                uri_base=self.uri_base, character_uri=self.uri, label=text
+            ),
+        )
+        self._feature_nodes = (*biographical, *free_text)
+        self._role_nodes = _dedup_nodes(
+            self.narrative_roles,
+            lambda text: CharacterRole(uri_base=self.uri_base, character_uri=self.uri, label=text),
+        )
+
+    def _biographical(self, kind: BioKind, year: int) -> CharacterFeature:
+        return CharacterFeature(
+            uri_base=self.uri_base, character_uri=self.uri, kind=kind, year=year
+        )
+
+    def derived_assertions(self) -> Iterable[DerivedAssertion]:
+        """One :class:`DerivedAssertion` per derived assertion, each tagged with
+        the frontmatter key it came from so the indexer can resolve a source line:
+        biographical features → ``born`` / ``died``, free-text → ``features``,
+        roles → ``narrative_roles``. The identity assertion is file-level
+        (``source_field`` ``None``).
+
+        Overrides the declarative base because ``cross_refs`` cannot express this
+        fan-out: a single ``_feature_nodes`` tuple carries three distinct origins
+        (``born`` / ``died`` / ``features``), which only this class can untangle —
+        a biographical node is recognised by its ``kind``."""
+        yield DerivedAssertion(self.uri, self.uri, None)
+        for feature in self._feature_nodes:
+            field = {"birth": "born", "death": "died"}.get(feature.kind or "", "features")
+            yield DerivedAssertion(self.uri, feature.uri, field)
+        for role in self._role_nodes:
+            yield DerivedAssertion(self.uri, role.uri, "narrative_roles")
+
+
+class Object(SluggedEntity):
+    """A storyworld object (``golem:G16_Object``). Identity only in v0."""
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["Object"]
+    path_segment: ClassVar[str] = "object"

bookwright/golem/modules/event.py

@@ -0,0 +1,91 @@
+"""Event module: narrative events and the psychological states they touch."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar
+
+from rdflib.namespace import RDF
+from rdflib.term import URIRef
+
+from bookwright.golem.base import CrossRef, GolemEntity, SluggedEntity, Triple
+from bookwright.golem.modules.feature import Dimension
+from bookwright.golem.namespaces import (
+    CLASS_IRI,
+    DURATION,
+    GENERICALLY_DEPENDENT_ON,
+    HAS_DIMENSION,
+    HAS_TYPE,
+    PARTICIPANT,
+    TEMPORAL_LOCATION,
+    TEMPORAL_RELATIONS,
+)
+
+
+class NarrativeEvent(SluggedEntity):
+    """A narrative event (``golem:G5_Narrative_Event``).
+
+    Each participant is linked by one ``dlp:participant`` triple (FR-015). An event
+    may additionally carry a multi-year time **interval** (``begin`` / ``end`` years)
+    and any of the five qualitative temporal relations to other events, which the
+    ``temporal`` validator (iteration 11) reasons over. The relations are ordinary
+    ``cross_refs`` (one frozen ``TR:*`` predicate each); the interval needs a custom
+    ``to_triples`` override because its typed-boundary + dimension shape is outside
+    what ``cross_refs`` can express (research D11). An event with no interval and no
+    relations behaves exactly as before — only its ``rdf:type`` and any participants.
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeEvent"]
+    path_segment: ClassVar[str] = "event"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (
+        CrossRef("participants", PARTICIPANT, multi=True),
+        *(CrossRef(rel.name, rel.predicate, multi=True) for rel in TEMPORAL_RELATIONS),
+    )
+
+    participants: tuple[GolemEntity | URIRef, ...] = ()
+    begin: int | None = None
+    end: int | None = None
+    follows: tuple[GolemEntity | URIRef, ...] = ()
+    precedes: tuple[GolemEntity | URIRef, ...] = ()
+    overlaps: tuple[GolemEntity | URIRef, ...] = ()
+    includes: tuple[GolemEntity | URIRef, ...] = ()
+    included_in: tuple[GolemEntity | URIRef, ...] = ()
+
+    def to_triples(self) -> Iterable[Triple]:
+        """The base emission (type + participants + the five relation edges) followed
+        by the closure-safe interval triples for any present begin/end boundary."""
+        yield from super().to_triples()
+        yield from self._interval_triples()
+
+    def _interval_triples(self) -> Iterable[Triple]:
+        if self.begin is None and self.end is None:
+            return
+        span_uri = URIRef(f"{self.uri}/time-span")
+        time_interval = CLASS_IRI["TimeInterval"]
+        yield (self.uri, DURATION, span_uri)
+        yield (span_uri, RDF.type, time_interval)
+        for kind, year in (("begin", self.begin), ("end", self.end)):
+            if year is None:
+                continue
+            boundary_uri = URIRef(f"{span_uri}/{kind}")
+            type_uri = URIRef(f"{self.uri_base}type/{kind}")
+            dimension = Dimension(uri_base=self.uri_base, feature_uri=boundary_uri, year=year)
+            yield (span_uri, TEMPORAL_LOCATION, boundary_uri)
+            yield (boundary_uri, RDF.type, time_interval)
+            yield (boundary_uri, HAS_TYPE, type_uri)
+            yield (type_uri, RDF.type, CLASS_IRI["Type"])
+            yield (boundary_uri, HAS_DIMENSION, dimension.uri)
+            yield from dimension.to_triples()
+
+
+class PsychologicalState(SluggedEntity):
+    """A psychological state (``golem:G3_Psychological_State``).
+
+    When set, the state is ``dlp:generically-dependent-on`` its bearer (FR-015).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["PsychologicalState"]
+    path_segment: ClassVar[str] = "psychological-state"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (CrossRef("bearer", GENERICALLY_DEPENDENT_ON),)
+
+    bearer: GolemEntity | URIRef | None = None

bookwright/golem/modules/feature.py

@@ -0,0 +1,161 @@
+"""Feature module: character-scoped attribute carriers.
+
+These typed nodes hang off a :class:`~bookwright.golem.modules.character.Character`
+and carry the documented frontmatter that the identity-only model could not:
+free-text features, biographical years (``born`` / ``died``), and narrative
+roles. They are **not** narrative concepts — they are excluded from the
+``CONCEPTS`` registry (SC-001) — but they emit only frozen GOLEM / CIDOC-CRM /
+DOLCE terms (FR-020), and every node carries a deterministic, character-scoped
+URI built from its owner's URI plus a fixed suffix (never a blank node, FR-021).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar, Literal
+
+from pydantic import model_validator
+from rdflib.namespace import RDF, RDFS, XSD
+from rdflib.term import Literal as RdfLiteral
+from rdflib.term import URIRef
+
+from bookwright.golem.base import GolemEntity, Triple
+from bookwright.golem.namespaces import (
+    CLASS_IRI,
+    HAS_DIMENSION,
+    HAS_TYPE,
+    HAS_VALUE,
+)
+from bookwright.golem.slug import make_slug
+
+BioKind = Literal["birth", "death"]
+"""The two biographical feature kinds; each maps to a shared E55_Type individual."""
+
+
+def gyear_literal(year: int) -> RdfLiteral:
+    """Format an integer year as a lexically valid ``xsd:gYear`` literal (FR-019).
+
+    XSD requires the year part to be at least four digits, with an optional
+    leading ``-`` for BCE years. Plain ``str(year)`` is invalid for years < 1000
+    or BCE (e.g. ``"800"``, ``"-44"``), which the iteration-10 temporal queries —
+    the whole reason for ``gYear`` over a plain string — would then reject. Pad
+    the magnitude to four digits and preserve the sign instead, so ``800`` →
+    ``"0800"`` and ``-44`` → ``"-0044"`` while ``1828`` stays ``"1828"``.
+    """
+    sign = "-" if year < 0 else ""
+    return RdfLiteral(f"{sign}{abs(year):04d}", datatype=XSD.gYear)
+
+
+class Dimension(GolemEntity):
+    """A measurement (``crm:E54_Dimension``) carrying a biographical year.
+
+    URI is ``{feature.uri}/dimension``; the year is emitted as an ``xsd:gYear``
+    literal (never ``xsd:integer`` or an untyped string — FR-019), which is what
+    makes iteration-10's temporal queries answerable.
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["Dimension"]
+
+    feature_uri: URIRef
+    year: int
+
+    def model_post_init(self, __context: object) -> None:
+        self._uri = URIRef(f"{self.feature_uri}/dimension")
+
+    def to_triples(self) -> Iterable[Triple]:
+        yield (self.uri, RDF.type, self.golem_class)
+        yield (self.uri, HAS_VALUE, gyear_literal(self.year))
+
+
+class CharacterFeature(GolemEntity):
+    """A character feature (``golem:G17_Character_Feature``), one of two variants.
+
+    - **free-text** — supply ``label``; URI ``{character.uri}/feature/{slug(label)}``,
+      emits the type assertion + ``rdfs:label``.
+    - **biographical** — supply ``kind`` (``"birth"``/``"death"``) and ``year``;
+      URI ``{character.uri}/feature/bio/{kind}`` (the ``bio/`` sub-segment keeps
+      the birth/death token out of the free-text slug space, so the two variants
+      can never collide on one character), emits the type assertion, a
+      ``crm:P2_has_type`` link to the shared ``{uri_base}type/{kind}`` E55_Type
+      individual, and a ``crm:P43_has_dimension`` link to its :class:`Dimension`.
+
+    Exactly one variant must be supplied. A free-text ``label`` that slugs to
+    empty raises :class:`~bookwright.golem.errors.EmptySlugError` (FR-021).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["CharacterFeature"]
+
+    character_uri: URIRef
+    label: str | None = None
+    kind: BioKind | None = None
+    year: int | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _exactly_one_variant(cls, data: dict[str, object]) -> dict[str, object]:
+        # Runs *before* identity construction in ``model_post_init`` (which
+        # builds the URI from the chosen variant), so the variant invariant is
+        # enforced by a real ``ValidationError`` rather than the type-narrowing
+        # assert at the bottom of this class. That assert is then never the line
+        # that rejects bad input, so it stays correct under ``python -O``. ``data``
+        # is always the raw kwargs dict: this frozen model is only ever built via
+        # ``CharacterFeature(...)``, never re-validated from an existing instance.
+        kind, label, year = data.get("kind"), data.get("label"), data.get("year")
+        if kind is not None:
+            # Biographical: a year is mandatory, a free-text label is forbidden.
+            if label is not None:
+                raise ValueError("biographical CharacterFeature must not also carry a `label`")
+            if year is None:
+                raise ValueError("biographical CharacterFeature requires a `year`")
+        else:
+            # Free-text: a label is mandatory; a stray `year` is forbidden rather
+            # than silently dropped, since only the biographical variant emits it.
+            if label is None:
+                raise ValueError("CharacterFeature requires either `label` or (`kind` + `year`)")
+            if year is not None:
+                raise ValueError("free-text CharacterFeature must not carry a `year`")
+        return data
+
+    def model_post_init(self, __context: object) -> None:
+        if self.kind is not None:
+            # Biographical features live under a `bio/` sub-segment: a free-text
+            # slug never contains `/`, so it can never collide with the
+            # birth/death token on the same character (FR-021).
+            self._uri = URIRef(f"{self.character_uri}/feature/bio/{self.kind}")
+        else:
+            assert self.label is not None  # guaranteed by _exactly_one_variant
+            self._uri = URIRef(f"{self.character_uri}/feature/{make_slug(self.label)}")
+
+    def to_triples(self) -> Iterable[Triple]:
+        yield (self.uri, RDF.type, self.golem_class)
+        if self.kind is not None:
+            type_uri = URIRef(f"{self.uri_base}type/{self.kind}")
+            yield (self.uri, HAS_TYPE, type_uri)
+            yield (type_uri, RDF.type, CLASS_IRI["Type"])
+            assert self.year is not None  # guaranteed by _exactly_one_variant
+            dimension = Dimension(uri_base=self.uri_base, feature_uri=self.uri, year=self.year)
+            yield (self.uri, HAS_DIMENSION, dimension.uri)
+            yield from dimension.to_triples()
+        else:
+            yield (self.uri, RDFS.label, RdfLiteral(self.label))
+
+
+class CharacterRole(GolemEntity):
+    """A character-scoped narrative role (``golem:G11_Narrative_Role``).
+
+    URI is ``{character.uri}/role/{slug(label)}``; emits the type assertion and
+    the role text on ``rdfs:label``. Distinct from the top-level ``NarrativeRole``
+    concept: this node is inlined under a character and is not in ``CONCEPTS``.
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeRole"]
+
+    character_uri: URIRef
+    label: str
+
+    def model_post_init(self, __context: object) -> None:
+        self._uri = URIRef(f"{self.character_uri}/role/{make_slug(self.label)}")
+
+    def to_triples(self) -> Iterable[Triple]:
+        yield (self.uri, RDF.type, self.golem_class)
+        yield (self.uri, RDFS.label, RdfLiteral(self.label))

bookwright/golem/modules/inference.py

@@ -0,0 +1,41 @@
+"""Inference module: provenance for inferred attributes (CIDOC-CRM E13)."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rdflib.term import URIRef
+
+from bookwright.golem.base import CrossRef, GolemEntity, MintedEntity
+from bookwright.golem.namespaces import (
+    ASSIGNED,
+    ASSIGNED_ATTRIBUTE_TO,
+    CLASS_IRI,
+    REFERS_TO,
+    USED_SPECIFIC_OBJECT,
+)
+
+
+class AttributeAssignment(MintedEntity):
+    """A provenance record for an inferred attribute (``crm:E13_Attribute_Assignment``).
+
+    Constructed without a ``name``: its identity token is the time-ordered uuid7
+    minted by :class:`~bookwright.golem.base.MintedEntity`, so two assignments
+    created in sequence sort in creation order (FR-013, D3). The ``source`` path is
+    stored and emitted verbatim as an ``xsd:string`` literal (FR-009, D7);
+    ``premise`` is omitted from the triples when ``None``.
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["AttributeAssignment"]
+    path_segment: ClassVar[str] = "assertion"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (
+        CrossRef("target", ASSIGNED_ATTRIBUTE_TO),
+        CrossRef("attribute", ASSIGNED),
+        CrossRef("source", USED_SPECIFIC_OBJECT, literal=True),
+        CrossRef("premise", REFERS_TO),
+    )
+
+    target: GolemEntity | URIRef
+    attribute: GolemEntity | URIRef
+    source: str
+    premise: GolemEntity | URIRef | None = None

bookwright/golem/modules/narrative.py

@@ -0,0 +1,55 @@
+"""Narrative module: units, their functions/roles, and ordered sequences."""
+
+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, PROPER_PART, REFERS_TO
+
+
+class NarrativeUnit(SluggedEntity):
+    """A narrative unit (``golem:G9_Narrative_Unit``).
+
+    Refers to each of its narrative functions and roles (``crm:P67_refers_to``).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeUnit"]
+    path_segment: ClassVar[str] = "narrative-unit"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (
+        CrossRef("functions", REFERS_TO, multi=True),
+        CrossRef("roles", REFERS_TO, multi=True),
+    )
+
+    functions: tuple[GolemEntity | URIRef, ...] = ()
+    roles: tuple[GolemEntity | URIRef, ...] = ()
+
+
+class NarrativeFunction(SluggedEntity):
+    """A narrative function (``golem:G10_Narrative_Function``). Identity only."""
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeFunction"]
+    path_segment: ClassVar[str] = "narrative-function"
+
+
+class NarrativeRole(SluggedEntity):
+    """A narrative role (``golem:G11_Narrative_Role``). Identity only."""
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeRole"]
+    path_segment: ClassVar[str] = "narrative-role"
+
+
+class NarrativeSequence(SluggedEntity):
+    """A narrative sequence (``golem:G7_Narrative_Sequence``).
+
+    Emits one ``dlp:proper-part`` triple per member unit, in declared order
+    (FR-015). RDF is unordered; the ordering is the caller's tuple order.
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["NarrativeSequence"]
+    path_segment: ClassVar[str] = "narrative-sequence"
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = (CrossRef("units", PROPER_PART, multi=True),)
+
+    units: tuple[GolemEntity | URIRef, ...] = ()

bookwright/golem/modules/provenance.py

@@ -0,0 +1,197 @@
+"""Provenance module: research entities (Source / Finding / Anchor).
+
+The three research concepts of iteration 012 (design § 20). They reuse the GOLEM
+machinery — frozen Pydantic identity, deterministic URIs, ``to_triples()`` — but
+introduce **no new GOLEM/ontology class** (Constitution X, FR-001):
+
+- :class:`Source` is typed purely via ``crm:E55_Type`` (``crm:P2_has_type`` →
+  a ``sources.ttl`` individual); it emits **no** ``rdf:type`` (research D2).
+- :class:`Finding` and :class:`Anchor` reify on ``crm:E13_Attribute_Assignment``
+  (the same class the Inference module uses), staying distinguishable from inferred
+  assertions by their URI segment and their ``bw:`` predicates (FR-018, research D9).
+
+All Bookwright (``bw:``) predicates and the source-type / reliability individuals
+are declared in ``resources/vocabularies/sources.ttl``, never in the frozen
+``golem.ttl``.
+"""
+
+from __future__ import annotations
+
+import datetime
+from collections.abc import Iterable
+from typing import ClassVar, Literal
+
+from pydantic import field_validator
+from rdflib.namespace import RDF, XSD
+from rdflib.term import Literal as RdfLiteral
+from rdflib.term import URIRef
+
+from bookwright.golem.base import MintedEntity, SluggedEntity, Triple
+from bookwright.golem.modules.feature import gyear_literal
+from bookwright.golem.namespaces import (
+    ASSIGNED_ATTRIBUTE_TO,
+    BEGIN_OF_BEGIN,
+    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,
+    E52_TIME_SPAN,
+    END_OF_END,
+    HAS_TIME_SPAN,
+    HAS_TYPE,
+    RELIABILITY_IRI,
+    SOURCE_TYPE_IRI,
+)
+
+SourceType = Literal[
+    "primaria", "secundaria", "oficial", "académica", "periodística", "testimonial"
+]
+"""The six controlled source-type values (FR-003). The `Literal` is the enforcement
+point — an out-of-vocabulary value raises a `ValidationError` (research D4)."""
+
+Reliability = Literal["alta", "media", "baja"]
+"""The three controlled reliability values (FR-004)."""
+
+
+def _string(value: str) -> RdfLiteral:
+    """An ``xsd:string`` literal (the default datatype for every prose facet)."""
+    return RdfLiteral(value, datatype=XSD.string)
+
+
+class Source(SluggedEntity):
+    """A research source, typed via ``crm:E55_Type`` — **no** ``rdf:type`` (D2).
+
+    Its identity token is the ASCII slug of ``name`` (segment ``source``), like
+    :class:`~bookwright.golem.modules.character.Character`. ``type`` and
+    ``reliability`` are controlled vocabularies enforced by ``Literal`` fields;
+    an out-of-vocabulary value is a ``ValidationError`` the reader turns into a
+    build-aborting :class:`~bookwright.io.errors.ResearchError` (FR-016).
+
+    ``translation`` is set by the reader **only** when the source's
+    ``original_language`` differs from the book language (research D6); the entity
+    itself is language-context-free.
+    """
+
+    # A documented, *unemitted* placeholder: Source overrides ``to_triples`` and
+    # yields no ``(uri, rdf:type, golem_class)`` triple. Identity in the graph is
+    # ``?s crm:P2_has_type ?t . ?t a crm:E55_Type`` (research D2).
+    golem_class: ClassVar[URIRef] = CLASS_IRI["Type"]
+    path_segment: ClassVar[str] = "source"
+
+    reference: str
+    author: str
+    original_language: str
+    type: SourceType
+    reliability: Reliability
+    reliability_justification: str
+    access_date: datetime.date
+    original_quote: str
+    translation: str | None = None
+
+    @field_validator("reliability_justification")
+    @classmethod
+    def _non_empty_justification(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("`reliability_justification` must not be empty")
+        return value
+
+    def to_triples(self) -> Iterable[Triple]:
+        """Emit the source's provenance facets — typed via E55, never ``rdf:type``."""
+        yield (self.uri, HAS_TYPE, SOURCE_TYPE_IRI[self.type])
+        yield (self.uri, BW_RELIABILITY, RELIABILITY_IRI[self.reliability])
+        yield (self.uri, BW_RELIABILITY_JUSTIFICATION, _string(self.reliability_justification))
+        yield (self.uri, BW_REFERENCE, _string(self.reference))
+        yield (self.uri, BW_AUTHOR, _string(self.author))
+        yield (self.uri, BW_ORIGINAL_LANGUAGE, _string(self.original_language))
+        yield (self.uri, BW_ACCESS_DATE, RdfLiteral(self.access_date, datatype=XSD.date))
+        yield (self.uri, BW_ORIGINAL_QUOTE, _string(self.original_quote))
+        if self.translation is not None:
+            yield (self.uri, BW_TRANSLATION, _string(self.translation))
+
+
+class Finding(MintedEntity):
+    """A research finding, reified on ``crm:E13_Attribute_Assignment`` (FR-006).
+
+    Its identity token is the time-ordered uuid7 minted once by
+    :class:`~bookwright.golem.base.MintedEntity` (segment ``finding``). A **closed**
+    finding records a ``claim``, who asserts
+    it (``asserted_by``, default ``"author"``), the narrative entity it
+    ``bears_on`` (reusing the Inference module's ``crm:P140_assigned_attribute_to``)
+    and one or more supporting ``sources``. An **open** finding (FR-008) is an
+    unresolved question: ``claim``/``bears_on``/``sources`` may all be empty and the
+    entity is still valid, emitting just ``rdf:type`` + ``bw:open true``.
+
+    ``bw:assertedBy`` is emitted only alongside a ``claim`` — an open question with
+    no claim asserts nothing, so it carries no asserter (research D9).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["AttributeAssignment"]
+    path_segment: ClassVar[str] = "finding"
+
+    claim: str | None = None
+    asserted_by: str = "author"
+    bears_on: URIRef | None = None
+    sources: tuple[URIRef, ...] = ()
+    open: bool = False
+
+    def to_triples(self) -> Iterable[Triple]:
+        yield (self.uri, RDF.type, self.golem_class)
+        if self.claim is not None:
+            yield (self.uri, BW_CLAIM, _string(self.claim))
+            yield (self.uri, BW_ASSERTED_BY, _string(self.asserted_by))
+        if self.bears_on is not None:
+            yield (self.uri, ASSIGNED_ATTRIBUTE_TO, self.bears_on)
+        for source in self.sources:
+            yield (self.uri, BW_SUPPORTED_BY, source)
+        if self.open:
+            yield (self.uri, BW_OPEN, RdfLiteral(True))
+
+
+class Anchor(MintedEntity):
+    """A binding constraint promoting a :class:`Finding`, reified on E13 (FR-009).
+
+    Its identity token is the uuid7 minted by
+    :class:`~bookwright.golem.base.MintedEntity` (segment ``anchor``). It
+    ``promotes`` the finding it derives from and ``constrains`` a narrative entity
+    (or the well-known untyped timeline IRI, research D10). When the named target
+    does not resolve in the bible, the reader builds the anchor with
+    ``constrains=None`` and surfaces a warning — the ``bw:constrains`` triple is
+    simply omitted, the build still succeeds (research D12).
+
+    An optional time-span (``begin``/``end`` years, research D5) is emitted as a
+    ``crm:E52_Time-Span`` sub-node under ``crm:P4_has_time-span``; an anchor with
+    neither bound emits no time-span (FR-010).
+    """
+
+    golem_class: ClassVar[URIRef] = CLASS_IRI["AttributeAssignment"]
+    path_segment: ClassVar[str] = "anchor"
+
+    promotes: URIRef
+    constrains: URIRef | None = None
+    begin: int | None = None
+    end: int | None = None
+
+    def to_triples(self) -> Iterable[Triple]:
+        yield (self.uri, RDF.type, self.golem_class)
+        yield (self.uri, BW_PROMOTES, self.promotes)
+        if self.constrains is not None:
+            yield (self.uri, BW_CONSTRAINS, self.constrains)
+        if self.begin is not None or self.end is not None:
+            time_span = URIRef(f"{self.uri}/time-span")
+            yield (self.uri, HAS_TIME_SPAN, time_span)
+            yield (time_span, RDF.type, E52_TIME_SPAN)
+            if self.begin is not None:
+                yield (time_span, BEGIN_OF_BEGIN, gyear_literal(self.begin))
+            if self.end is not None:
+                yield (time_span, END_OF_END, gyear_literal(self.end))