bookwright-cli 0.2.0__py3-none-any.whl

bookwright/core/manifest.py

@@ -0,0 +1,343 @@
+"""Typed in-memory model of a Bookwright `manifest.toml`.
+
+Public surface is re-exported from `bookwright.core` (see contracts/manifest_api.md).
+This module owns the Pydantic v2 model tree and the load/dump/build entry
+points. The builder body lives in `bookwright.core._build` and the
+`pydantic.ValidationError` translator in `bookwright.core._translate`, both
+internal helpers kept separate to honour the Principle IV 500-line ceiling.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Literal
+
+import tomlkit
+import tomlkit.exceptions
+from packaging.version import InvalidVersion, Version
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    ValidationError,
+    model_validator,
+)
+from pydantic_core import PydanticCustomError
+from tomlkit.toml_document import TOMLDocument
+
+from bookwright import __version__ as _BOOKWRIGHT_VERSION
+from bookwright.core._blocks import (
+    BOOK_STATUSES,
+    BOOK_TYPES,
+    BookBlock,
+    BookwrightBlock,
+    IntegrationBlock,
+    PathsBlock,
+    ValidatorsBlock,
+    VocabulariesBlock,
+)
+from bookwright.core._build import _build_manifest
+from bookwright.core._research_block import ResearchBlock
+from bookwright.core._translate import _translate_validation_error
+from bookwright.core.errors import (
+    ManifestNotFoundError,
+    ManifestOverwriteError,
+    ManifestSyntaxError,
+    ManifestWarning,
+)
+
+KNOWN_MANIFEST_VERSIONS: frozenset[int] = frozenset({1})
+"""The set of `manifest_version` integers this CLI understands natively."""
+
+__all__ = [
+    "BOOK_STATUSES",
+    "BOOK_TYPES",
+    "KNOWN_MANIFEST_VERSIONS",
+    "BookBlock",
+    "BookwrightBlock",
+    "IntegrationBlock",
+    "Manifest",
+    "PathsBlock",
+    "ValidatorsBlock",
+    "VocabulariesBlock",
+]
+
+
+def _default_skills_dir_map() -> dict[str, str]:
+    """Late-imported view of the integrations registry.
+
+    Used by ``_build_manifest`` to fill the per-key skills_dir default
+    (R2). The late import inside the function body keeps ``bookwright.core``
+    importable in isolation; no module-top dependency on
+    ``bookwright.integrations`` exists.
+    """
+
+    # Late import per R2 — keeps bookwright.core importable in isolation
+    # and prevents a load-order cycle between core and integrations.
+    from bookwright.integrations import INTEGRATION_REGISTRY  # noqa: PLC0415
+
+    return {key: cls.default_skills_dir for key, cls in INTEGRATION_REGISTRY.items()}
+
+
+def _installed_version() -> str:
+    """Thin indirection so tests can monkey-patch the installed CLI version."""
+
+    return _BOOKWRIGHT_VERSION
+
+
+def _classify_manifest_version(parsed: int) -> Literal["known", "future"]:
+    """FR-013 vs FR-014 single source of truth."""
+
+    if parsed in KNOWN_MANIFEST_VERSIONS:
+        return "known"
+    return "future"
+
+
+def _classify_manifest_version_warnings(
+    raw: str,
+) -> tuple[ManifestWarning, ...]:
+    """Return the (possibly empty) warning tuple for a known/future `manifest_version`.
+
+    Called only after Pydantic validation accepted `raw`, so `int(raw)` is
+    safe — no need to re-run the regex validator (which raises
+    `PydanticCustomError` outside Pydantic's machinery).
+    """
+
+    parsed = int(raw)
+    if _classify_manifest_version(parsed) == "known":
+        return ()
+    max_known = max(KNOWN_MANIFEST_VERSIONS)
+    return (
+        ManifestWarning(
+            rule_id="manifest_version.unknown_future",
+            field_path="bookwright.manifest_version",
+            offending_value=raw,
+            message=(
+                f"manifest_version {parsed} is newer than this CLI knows about "
+                f"(max known: {max_known}); load was best-effort"
+            ),
+        ),
+    )
+
+
+class Manifest(BaseModel):
+    """Root model. Unknown top-level blocks round-trip via `extra='allow'`."""
+
+    model_config = ConfigDict(extra="allow", strict=True)
+
+    bookwright: BookwrightBlock
+    book: BookBlock
+    vocabularies: VocabulariesBlock = Field(default_factory=VocabulariesBlock)
+    validators: ValidatorsBlock = Field(default_factory=ValidatorsBlock)
+    integration: IntegrationBlock
+    paths: PathsBlock = Field(default_factory=PathsBlock)
+    research: ResearchBlock = Field(default_factory=ResearchBlock)
+
+    _document: TOMLDocument | None = PrivateAttr(default=None)
+    _warnings: tuple[ManifestWarning, ...] = PrivateAttr(default=())
+
+    @property
+    def warnings(self) -> tuple[ManifestWarning, ...]:
+        """Non-fatal notes attached during `load()`; empty for freshly built manifests.
+
+        Exposed as a read-only property (not a Pydantic field) so a user-authored
+        `[warnings]` block in `manifest.toml` rounds-trips via `extra="allow"`
+        instead of colliding with a declared field.
+        """
+
+        return self._warnings
+
+    @model_validator(mode="after")
+    def _check_cli_floor(self) -> Manifest:
+        # cli_version_min was already validated as PEP 440 by its field validator;
+        # field errors short-circuit model_validators, so we never see invalid input here.
+        required = Version(self.bookwright.cli_version_min)
+        installed_raw = _installed_version()
+        try:
+            installed = Version(installed_raw)
+        except InvalidVersion as exc:
+            raise PydanticCustomError(
+                "installed_not_pep440",
+                "installed CLI version '{installed}' is not valid PEP 440",
+                {
+                    "value": self.bookwright.cli_version_min,
+                    "installed": installed_raw,
+                },
+            ) from exc
+        if installed < required:
+            raise PydanticCustomError(
+                "installed_too_old",
+                "installed CLI {installed} is older than required {required}",
+                {
+                    "value": self.bookwright.cli_version_min,
+                    "installed": installed_raw,
+                    "required": self.bookwright.cli_version_min,
+                },
+            )
+        return self
+
+    @classmethod
+    def load(cls, path: Path | str) -> Manifest:
+        """Read, parse, and validate a manifest file. See contracts/manifest_api.md."""
+
+        resolved = Path(path)
+        if not resolved.exists():
+            raise ManifestNotFoundError(resolved)
+        text = resolved.read_text(encoding="utf-8")
+        try:
+            document = tomlkit.parse(text)
+        except tomlkit.exceptions.ParseError as exc:
+            line = getattr(exc, "line", None)
+            column = getattr(exc, "col", None)
+            raise ManifestSyntaxError(
+                path=resolved,
+                line=line,
+                column=column,
+                message=str(exc),
+            ) from exc
+        try:
+            instance = cls.model_validate(document.unwrap())
+        except ValidationError as exc:
+            raise _translate_validation_error(exc) from exc
+        instance._document = document
+        instance._warnings = _classify_manifest_version_warnings(
+            instance.bookwright.manifest_version
+        )
+        return instance
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        title: str,
+        authors: list[str],
+        integration_key: str,
+        **overrides: Any,
+    ) -> Manifest:
+        """Construct a fresh manifest from minimal inputs. See contracts/manifest_api.md."""
+
+        # R10 — only consult the integrations registry when the caller
+        # didn't supply an explicit `integration_skills_dir`. Otherwise
+        # `_build_manifest` ignores the map entirely, so building it
+        # (and the `bookwright.integrations` import that triggers
+        # `_register_builtins()`) is wasted work — and worse, it forces
+        # every Manifest.build caller through the registry even when
+        # core-only behaviour is what they want.
+        #
+        # R23 — align the "supplied" predicate with `_build_manifest`'s
+        # documented None-as-default contract (see _build.py: explicit-None
+        # overrides are dropped from `effective_overrides`). Using
+        # ``"integration_skills_dir" in overrides`` here would diverge:
+        # ``Manifest.build(..., integration_skills_dir=None)`` would skip
+        # the registry, then `_build_manifest` would also skip the
+        # override (None filtered), then `default_skills_dir[key]` would
+        # raise KeyError → misleading TypeError. ``.get(...) is not None``
+        # keeps both call sites in agreement.
+        default_skills_dir: dict[str, str] = (
+            {} if overrides.get("integration_skills_dir") is not None else _default_skills_dir_map()
+        )
+
+        return _build_manifest(
+            cls,
+            title=title,
+            authors=authors,
+            integration_key=integration_key,
+            installed_version=_installed_version(),
+            default_skills_dir=default_skills_dir,
+            **overrides,
+        )
+
+    def set_integration(self, *, key: str, skills_dir: str) -> None:
+        """Update the ``[integration]`` block in place, preserving comments and order.
+
+        Mutates **both** the validated model field and the backing ``tomlkit``
+        document, so a subsequent :meth:`dump` writes the new ``key`` /
+        ``skills_dir`` while every other key, comment, and the block ordering
+        round-trip untouched (FR-020). The ``[integration.options]`` sub-table is
+        left as-is — the two v0 integrations both default to no options, and a
+        future per-integration option migration is an additive concern.
+
+        Requires an instance produced by :meth:`load` or :meth:`build` (i.e. one
+        carrying a ``tomlkit`` document); a bare construction raises ``RuntimeError``,
+        the same contract as :meth:`dump`.
+        """
+
+        document = self._document
+        if document is None:
+            raise RuntimeError(
+                "Manifest.set_integration() requires an instance produced by "
+                "Manifest.load() or Manifest.build()."
+            )
+        table = document["integration"]
+        table["key"] = key
+        table["skills_dir"] = skills_dir
+        self.integration = self.integration.model_copy(
+            update={"key": key, "skills_dir": skills_dir}
+        )
+
+    def dump(self, path: Path | str, *, overwrite: bool = False) -> Path:
+        """Atomically write the manifest to `path`. See contracts/manifest_api.md."""
+
+        target = Path(path)
+        if target.exists() and not overwrite:
+            raise ManifestOverwriteError(target)
+
+        document = self._document
+        if document is None:
+            raise RuntimeError(
+                "Manifest.dump() requires an instance produced by Manifest.load() "
+                "or Manifest.build(); bare constructions have no tomlkit document "
+                "to serialize."
+            )
+
+        body = tomlkit.dumps(document)
+
+        parent = target.parent
+        parent.mkdir(parents=True, exist_ok=True)
+        tmp_fd, tmp_path = tempfile.mkstemp(
+            dir=str(parent),
+            prefix=f".{target.name}.",
+            suffix=".tmp",
+        )
+        try:
+            # `newline=""` disables Python's universal-newlines translation
+            # so the file we hand-fsynced lands byte-identical on every
+            # platform (Windows would otherwise rewrite `\n` to `\r\n`,
+            # breaking the FR-020 round-trip guarantee).
+            with os.fdopen(tmp_fd, "w", encoding="utf-8", newline="") as handle:
+                handle.write(body)
+                handle.flush()
+                os.fsync(handle.fileno())
+            if overwrite:
+                os.replace(tmp_path, target)
+            else:
+                # `os.link` is atomic: if the target appears between the
+                # early `exists()` check and here, link raises FileExistsError
+                # rather than silently clobbering — closes the TOCTOU race.
+                try:
+                    os.link(tmp_path, target)
+                except FileExistsError as exc:
+                    raise ManifestOverwriteError(target) from exc
+                # Once `os.link` succeeds, `target` already holds the new
+                # bytes (as a hard link). Failing to remove the tmp side of
+                # the link does NOT undo that commit — raising here would
+                # mislead callers into thinking the write failed and would
+                # violate the FR-021 atomicity contract from the opposite
+                # direction. Best-effort cleanup; leave a leaked tmp file
+                # rather than a phantom failure.
+                with contextlib.suppress(OSError):
+                    os.unlink(tmp_path)
+        except BaseException:
+            # Suppress *all* OSError variants during cleanup so the real
+            # exception (the one that triggered this branch) is not
+            # shadowed by a PermissionError / EBUSY / etc. raised by the
+            # cleanup itself.
+            with contextlib.suppress(OSError):
+                os.unlink(tmp_path)
+            raise
+
+        return target.resolve()

bookwright/errors.py

@@ -0,0 +1,47 @@
+"""The shared error base — the single source of truth for the JSON-over-stdout
+error envelope (Principle IX, review finding R3).
+
+Every Bookwright error that can reach a ``--json`` boundary subclasses
+``BookwrightError`` and inherits its one canonical ``to_json()``; no error class
+defines its own envelope serializer. This module is the lowest layer: it imports
+**nothing** from ``core``/``golem``/``io``/``indexers``/``validation``/
+``integrations``/``commands`` (FR-010), so it can be imported by all of them with
+no risk of a cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class BookwrightError(Exception):
+    """Base for every Bookwright error that reaches a ``--json`` boundary.
+
+    Subclasses declare a class-level ``code`` (the machine-readable identifier),
+    pass a human ``message`` and optional ``details`` to ``__init__``, and inherit
+    the one canonical ``to_json()``. A subclass MAY set ``self.code`` per instance
+    (``_UsageError``). Abstract package roots leave ``code`` unset and are never
+    serialized.
+    """
+
+    # Class-level default; concrete subclasses assign it (or set ``self.code``).
+    # Deliberately a plain annotation, NOT ``ClassVar[str]``: a ``ClassVar`` would
+    # forbid ``_UsageError``'s per-instance ``self.code`` override under
+    # ``mypy --strict`` (research Decision 2).
+    code: str
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        self.message = message
+        self.details = details
+        super().__init__(message)
+
+    def to_json(self) -> dict[str, Any]:
+        """The canonical error envelope; ``details`` only when non-empty."""
+        payload: dict[str, Any] = {
+            "status": "error",
+            "code": self.code,
+            "message": self.message,
+        }
+        if self.details:
+            payload["details"] = self.details
+        return payload

bookwright/golem/__init__.py

@@ -0,0 +1,71 @@
+"""GOLEM domain model: typed, frozen entities with deterministic RDF identity.
+
+Public surface: the thirteen GOLEM concept classes, the two
+character-scoped attribute carriers (``CharacterFeature`` / ``Dimension`` —
+exported for iteration-10 introspection but deliberately **not** in
+``CONCEPTS``), the ``GolemError`` / ``EmptySlugError`` types, the ``CONCEPTS``
+name→class registry, and ``to_turtle``. See
+specs/005-golem-domain-model/contracts/golem_api.md for the stable contract.
+"""
+
+from __future__ import annotations
+
+from bookwright.golem.base import DerivedAssertion
+from bookwright.golem.errors import EmptySlugError, GolemError
+from bookwright.golem.modules.character import Character, Object
+from bookwright.golem.modules.event import NarrativeEvent, PsychologicalState
+from bookwright.golem.modules.feature import CharacterFeature, Dimension
+from bookwright.golem.modules.inference import AttributeAssignment
+from bookwright.golem.modules.narrative import (
+    NarrativeFunction,
+    NarrativeRole,
+    NarrativeSequence,
+    NarrativeUnit,
+)
+from bookwright.golem.modules.provenance import Anchor, Finding, Source
+from bookwright.golem.modules.relationship import RelationshipRole, SocialRelationship
+from bookwright.golem.modules.setting import NarrativeLocation, Setting
+from bookwright.golem.serialize import to_turtle
+
+CONCEPTS: dict[str, type] = {
+    "Character": Character,
+    "Object": Object,
+    "SocialRelationship": SocialRelationship,
+    "RelationshipRole": RelationshipRole,
+    "NarrativeEvent": NarrativeEvent,
+    "PsychologicalState": PsychologicalState,
+    "Setting": Setting,
+    "NarrativeLocation": NarrativeLocation,
+    "NarrativeUnit": NarrativeUnit,
+    "NarrativeFunction": NarrativeFunction,
+    "NarrativeRole": NarrativeRole,
+    "NarrativeSequence": NarrativeSequence,
+    "AttributeAssignment": AttributeAssignment,
+}
+"""Concept name → class, for downstream introspection (contract § surface)."""
+
+__all__ = [
+    "CONCEPTS",
+    "Anchor",
+    "AttributeAssignment",
+    "Character",
+    "CharacterFeature",
+    "DerivedAssertion",
+    "Dimension",
+    "EmptySlugError",
+    "Finding",
+    "GolemError",
+    "NarrativeEvent",
+    "NarrativeFunction",
+    "NarrativeLocation",
+    "NarrativeRole",
+    "NarrativeSequence",
+    "NarrativeUnit",
+    "Object",
+    "PsychologicalState",
+    "RelationshipRole",
+    "Setting",
+    "SocialRelationship",
+    "Source",
+    "to_turtle",
+]

bookwright/golem/base.py

@@ -0,0 +1,200 @@
+"""The frozen-entity base: deterministic identity + the rdf:type triple.
+
+Every GOLEM concept is an immutable Pydantic v2 model (research D1). Identity is
+computed once, in ``model_post_init`` — which runs *after* validation, so an
+:class:`~bookwright.golem.errors.EmptySlugError` raised while slugging a name
+propagates unwrapped (not folded into a ``pydantic.ValidationError``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import ClassVar, NamedTuple
+
+import uuid_utils
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+from rdflib.namespace import RDF, XSD
+from rdflib.term import Literal, URIRef
+
+from bookwright.golem.slug import make_slug
+
+Triple = tuple[URIRef, URIRef, URIRef | Literal]
+"""An rdflib triple emitted by :meth:`GolemEntity.to_triples`."""
+
+
+def ref_uri(ref: GolemEntity | URIRef) -> URIRef:
+    """Resolve a cross-reference target to the URIRef used in a linking triple."""
+    return ref.uri if isinstance(ref, GolemEntity) else ref
+
+
+class DerivedAssertion(NamedTuple):
+    """One source-derived assertion this entity makes, for provenance (FR-011).
+
+    The indexer turns each into a ``crm:E13_Attribute_Assignment``, resolving
+    :attr:`source_field` to a ``file:line`` locator via the frontmatter reader's
+    ``key_lines``. The model names the *originating field* — never a file path —
+    so it stays source-agnostic: where a value lives on disk is the indexer's
+    knowledge, not the ontology's.
+
+    - ``target``: the entity the assertion is about (e.g. the character).
+    - ``attribute``: the materialized node the assertion introduces (a feature /
+      role / participant URI), or ``target`` itself for the identity assertion.
+    - ``source_field``: the model field — identical to the frontmatter key by
+      FR-010 (``born`` / ``died`` / ``features`` / ``narrative_roles`` /
+      ``participants``) — that the assertion derived from; ``None`` for the
+      identity assertion, which carries only file-level provenance.
+    """
+
+    target: URIRef
+    attribute: URIRef
+    source_field: str | None
+
+
+class CrossRef(NamedTuple):
+    """A declarative cross-reference edge: one field → its linking predicate (FR-015).
+
+    Concepts list these in :attr:`GolemEntity.cross_refs` instead of hand-rolling
+    a ``to_triples`` override, so the base emits every edge uniformly and a new
+    concept can never forget to chain the ``rdf:type`` assertion.
+
+    - ``multi``: the field is a tuple; emit one triple per item, in tuple order.
+    - ``literal``: emit the field value verbatim as an ``xsd:string`` (e.g. a
+      source path), not a resolved reference.
+    - ``owned``: the targets are sub-nodes this entity owns rather than peer
+      entities serialized in their own right; after each link triple, chain the
+      target's own ``to_triples()`` so the whole sub-tree is emitted here. (Used
+      with ``multi`` — a character owns its feature / role nodes.)
+    - otherwise the field is a single optional reference, omitted when ``None``.
+    """
+
+    attr: str
+    predicate: URIRef
+    multi: bool = False
+    literal: bool = False
+    owned: bool = False
+
+
+class GolemEntity(BaseModel):
+    """Abstract base for every GOLEM concept.
+
+    Subclasses set the class-level ``golem_class`` (rdf:type target) and
+    ``path_segment`` (FR-004), and provide a token via ``_build_token``.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        arbitrary_types_allowed=True,
+    )
+
+    uri_base: str
+
+    golem_class: ClassVar[URIRef]
+    path_segment: ClassVar[str]
+    cross_refs: ClassVar[tuple[CrossRef, ...]] = ()
+
+    _uri: URIRef = PrivateAttr()
+
+    def model_post_init(self, __context: object) -> None:
+        self._uri = URIRef(f"{self.uri_base}{self.path_segment}/{self._build_token()}")
+
+    def _build_token(self) -> str:  # pragma: no cover - overridden by every concrete class
+        raise NotImplementedError
+
+    @property
+    def uri(self) -> URIRef:
+        """The deterministic, immutable identifier (FR-003/004/007)."""
+        return self._uri
+
+    def to_triples(self) -> Iterable[Triple]:
+        """Yield this entity's triples: the ``rdf:type`` assertion (FR-008, always
+        first) followed by every edge declared in :attr:`cross_refs` (FR-015) —
+        and, for an ``owned`` edge, the target sub-node's own triples chained
+        immediately after its link triple.
+
+        Concepts customize emission declaratively via ``cross_refs`` only when
+        their edges are URIRef references or ``xsd:string`` literals — the two
+        shapes this method knows how to emit. Concepts whose emission falls
+        outside that path override ``to_triples`` deliberately: ``CharacterFeature``
+        and ``CharacterRole`` emit an ``rdfs:label`` plain literal (and the former
+        a discriminator-keyed sub-tree), and ``Dimension`` emits a typed
+        ``xsd:gYear`` literal — none of which ``cross_refs`` can express.
+        """
+        yield (self.uri, RDF.type, self.golem_class)
+        for ref in self.cross_refs:
+            value = getattr(self, ref.attr)
+            if ref.multi:
+                for item in value:
+                    yield (self.uri, ref.predicate, ref_uri(item))
+                    if ref.owned:
+                        yield from item.to_triples()
+            elif ref.literal:
+                yield (self.uri, ref.predicate, Literal(value, datatype=XSD.string))
+            elif value is not None:
+                yield (self.uri, ref.predicate, ref_uri(value))
+
+    def derived_assertions(self) -> Iterable[DerivedAssertion]:
+        """Yield one :class:`DerivedAssertion` per source-derived assertion: the
+        identity assertion first (``source_field`` ``None`` → file-level
+        provenance), then one per cross-reference edge tagged with its
+        originating field name.
+
+        Read declaratively from :attr:`cross_refs`, so an entity whose field name
+        already equals its frontmatter key — ``NarrativeEvent`` /
+        ``SocialRelationship`` with ``participants`` — needs no override.
+        ``literal`` edges (a verbatim source path, not an attribute) are skipped.
+        An entity that fans one field out across several origin keys — ``Character``
+        splits a single owned-node tuple across ``born`` / ``died`` / ``features`` —
+        overrides this, exactly as such concepts already override
+        :meth:`to_triples`.
+        """
+        yield DerivedAssertion(self.uri, self.uri, None)
+        for ref in self.cross_refs:
+            if ref.literal:
+                continue
+            value = getattr(self, ref.attr)
+            if ref.multi:
+                for item in value:
+                    yield DerivedAssertion(self.uri, ref_uri(item), ref.attr)
+            elif value is not None:
+                yield DerivedAssertion(self.uri, ref_uri(value), ref.attr)
+
+
+class SluggedEntity(GolemEntity):
+    """A named concept whose identity token is the ASCII slug of its name."""
+
+    name: str
+
+    _slug: str = PrivateAttr()
+
+    def model_post_init(self, __context: object) -> None:
+        self._slug = make_slug(self.name)
+        super().model_post_init(__context)
+
+    def _build_token(self) -> str:
+        return self._slug
+
+    @property
+    def slug(self) -> str:
+        """The slugged token of :attr:`name` (FR-005)."""
+        return self._slug
+
+
+class MintedEntity(GolemEntity):
+    """A nameless concept whose identity token is a freshly minted, time-ordered uuid7.
+
+    Used by the ``crm:E13_Attribute_Assignment`` reifications — the inference
+    ``AttributeAssignment`` and the research ``Finding`` / ``Anchor`` — which have
+    no natural name to slug. The token is generated once in ``model_post_init`` and
+    frozen, so entities created in sequence sort in creation order (FR-013, D3).
+    """
+
+    _token: str = PrivateAttr()
+
+    def model_post_init(self, __context: object) -> None:
+        self._token = str(uuid_utils.uuid7())
+        super().model_post_init(__context)
+
+    def _build_token(self) -> str:
+        return self._token

bookwright/golem/errors.py

@@ -0,0 +1,29 @@
+"""Exception hierarchy for the GOLEM domain model.
+
+The error JSON shape is the canonical envelope owned by ``BookwrightError`` (this
+iteration normalized the former flat ``{"error": …}`` body onto it).
+"""
+
+from __future__ import annotations
+
+from bookwright.errors import BookwrightError
+
+
+class GolemError(BookwrightError):
+    """Base for every failure mode the ``bookwright.golem`` package owns.
+
+    Abstract: declares no ``code`` and is never serialized directly.
+    """
+
+
+class EmptySlugError(GolemError):
+    """A canonical name slugged to the empty string (FR-006).
+
+    Carries the offending name so a caller can report exactly what was rejected.
+    """
+
+    code = "golem_empty_slug"
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"name {name!r} slugifies to an empty string", {"name": name})

bookwright/golem/modules/__init__.py

@@ -0,0 +1 @@
+"""Per-GOLEM-module concept classes (design § 4.2 grouping)."""