secondbrain-py 0.2.1__py3-none-any.whl

brain/graph_rag/backends/base.py

@@ -0,0 +1,272 @@
+"""Storage/traversal backend Protocol for the GraphRAG layer (spec §4 D10).
+
+A :class:`GraphBackend` is the narrow, tenant-scoped interface the rest of the
+GraphRAG layer (reconcile in G1, retrieval in G2) depends on. The default
+implementation is :class:`brain.graph_rag.backends.age.AgeBackend` (Apache AGE
+inside Postgres, openCypher). Keeping the surface narrow is what makes the
+Neo4j/Memgraph kill-switch (spec §16) a drop-in replacement: a second backend
+conforms to this Protocol and the callers do not change.
+
+Every method is **tenant-scoped** — ``tenant_id`` is a required argument on each
+one (spec §4 D9). AGE has no native tenant isolation, so the AGE implementation
+enforces the tenant on every matched vertex *and* edge; a backend that cannot
+make that guarantee must not claim conformance.
+
+The graph mirrors the relational source-of-truth (migration 012); the durable
+app identity of an entity is its ``graph_entities.id`` UUID, carried on the AGE
+vertex as the ``entity_uuid`` property. Backend methods speak ``entity_uuid`` /
+``document_uuid`` (both equal the relational UUIDs), never AGE-internal IDs.
+
+This module defines only the Protocol and its return value objects; it imports
+no DB driver beyond the connection type, so it stays a pure contract that fakes
+can satisfy in unit tests.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+import psycopg
+
+from ..schema import EntityMention, GraphEntity
+
+__all__ = ["GraphBackend", "PersonScope", "TraversalHit"]
+
+
+@dataclass(frozen=True)
+class TraversalHit:
+    """One entity reached by :meth:`GraphBackend.traverse`, with its best path.
+
+    ``entity_uuid`` is the reached entity's durable id (= ``graph_entities.id``).
+    ``affinity`` is the product of the winning path's edge weights
+    (normalized lift ∈ (0, 1]; a 1-hop neighbour's affinity is just that edge's
+    weight). ``hops`` is the length of the winning (highest-affinity) path. The
+    seed itself is never returned. ``tenant_id`` records the scope the traversal
+    ran under — every element of the path was verified to carry it.
+    """
+
+    entity_uuid: str
+    affinity: float
+    hops: int
+    tenant_id: str = "default"
+
+
+@dataclass(frozen=True)
+class PersonScope:
+    """The scoped subgraph for "themes with X" expansion (spec §6b step 1).
+
+    Produced by :meth:`GraphBackend.scope_person`: starting from a seed person,
+    follow ``MENTIONED_IN`` into the person's documents and back out to the
+    entities co-mentioned in those documents. ``entity_uuids`` is the distinct
+    set of co-mentioned entities (the seed excluded); ``document_uuids`` is the
+    distinct set of connecting documents. Both are tenant-scoped. The grouping
+    stage (G2) consumes this set; SQL provides the lift weights and evidence.
+    """
+
+    seed_entity_uuid: str
+    entity_uuids: tuple[str, ...]
+    document_uuids: tuple[str, ...]
+    tenant_id: str = "default"
+
+
+@runtime_checkable
+class GraphBackend(Protocol):
+    """Tenant-scoped graph storage + bounded traversal (spec §4 D10, §8).
+
+    Implementations own a single named graph and translate these calls into
+    their engine's native operations. All write methods are idempotent: calling
+    them twice with the same arguments converges to the same graph state (the
+    relational source-of-truth is authoritative; the graph is a recomputable
+    mirror, spec §7).
+
+    Connection contract: every method takes the caller's ``conn`` so the caller
+    owns the transaction (reconcile in G1 wraps the relational rewrite and the
+    graph sync in one unit). The connection MUST already have the engine's
+    session bootstrap applied (for AGE: ``LOAD 'age'`` via
+    :func:`brain.db.connect_age` / :func:`brain.db.load_age`). :meth:`bootstrap`
+    additionally requires an autocommit connection (graph/label DDL).
+    """
+
+    def bootstrap(self, conn: psycopg.Connection[Any]) -> None:
+        """Idempotently provision the graph, its labels, and property indexes.
+
+        Ensures the graph exists, creates the vertex labels (``Entity``,
+        ``Document``) and edge labels (``MENTIONED_IN``, ``CO_OCCURS``), and
+        builds the property indexes (spec §5b). Safe to re-run. Requires an
+        autocommit connection (catalog DDL).
+        """
+        ...
+
+    def upsert_entities(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+        entities: Sequence[GraphEntity],
+    ) -> int:
+        """MERGE ``Entity`` vertices keyed on ``(tenant_id, entity_uuid)``.
+
+        Creates missing vertices and updates the mutable properties
+        (``name``/``entity_type``/``canonical_key``) of existing ones.
+        Embeddings stay relational (spec §5) and are never written here. Returns
+        the number of entities processed.
+        """
+        ...
+
+    def upsert_mention_edges(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+        document_id: str,
+        mentions: Sequence[EntityMention],
+        *,
+        document_props: Mapping[str, Any] | None = None,
+    ) -> int:
+        """Rebuild one document's ``MENTIONED_IN`` edges (split MERGE; spec §7.3).
+
+        MERGEs the ``Document`` vertex and each mentioned ``Entity`` vertex on
+        their own, then deletes and recreates this document's ``MENTIONED_IN``
+        edges. Never MERGEs the whole ``(e)-[:MENTIONED_IN]->(d)`` pattern in
+        one clause — AGE re-creates the endpoint vertices when it does. Returns
+        the number of mention edges written.
+        """
+        ...
+
+    def refresh_cooccur_edges(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+    ) -> int:
+        """Rematerialize the tenant's ``CO_OCCURS`` edges from the relational mirror.
+
+        Deletes the tenant's existing ``CO_OCCURS`` edges and recreates them
+        from ``graph_relationships`` (the derived aggregate mirror, recomputed
+        from contributions upstream; spec §5/§7). Full recompute is correct
+        because aggregates derive from the source-of-truth. Returns the number
+        of aggregate edges written.
+        """
+        ...
+
+    def traverse(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+        seed_entity_uuid: str,
+        *,
+        depth: int,
+        frontier_cap: int,
+        min_edge_weight: float = 0.0,
+    ) -> list[TraversalHit]:
+        """Bounded variable-length ``CO_OCCURS`` traversal from a seed (spec §6a).
+
+        Walks ``CO_OCCURS`` paths of length 1..``depth`` from the seed, enforces
+        ``tenant_id`` on every vertex and edge, scores each reached entity by
+        path affinity (product of edge weights) keeping the best path per
+        entity, drops paths with any edge below ``min_edge_weight``, and caps
+        the frontier. The seed itself is never returned. Returns hits ordered by
+        affinity descending, ties broken deterministically.
+
+        **Complete-or-failure contract:** the cap is applied *after* affinity
+        scoring, so an implementation must score every within-depth path rather
+        than truncate before scoring. To stay bounded it MUST detect when more
+        paths exist than it can safely score and raise :class:`GraphBackendError`
+        rather than returning a silently-truncated (possibly wrong) result — a
+        result is always either complete/correct or a loud failure.
+        """
+        ...
+
+    def scope_person(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+        seed_entity_uuid: str,
+        *,
+        frontier_cap: int,
+    ) -> PersonScope:
+        """Scope a person to co-mentioned entities + documents (spec §6b step 1).
+
+        Tenant-scoped: ``person -> MENTIONED_IN -> Document <- MENTIONED_IN <-
+        co-entity``, excluding the seed. Returns the distinct co-mentioned
+        entity set and the connecting document set, deterministically ordered.
+
+        **Bounded ranked-truncation contract:** when more than ``frontier_cap``
+        co-mention rows exist the implementation MUST keep the STRONGEST
+        ``frontier_cap`` worth of scope — co-entities ranked by co-mention
+        frequency with the seed (ties → newest shared document → entity id, a
+        total order for reproducibility) — rather than crash, so the headline
+        themes/audio surfaces stay usable for hub people. The truncation MUST
+        stay within the same bound the cap guaranteed (≤ ``frontier_cap`` rows
+        reach downstream) and MUST log a single actionable WARNING naming the
+        ``BRAIN_GRAPH_FRONTIER_CAP`` knob — never a silent partial result.
+        """
+        ...
+
+    def detach_delete_entities(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+        entity_uuids: Sequence[str],
+    ) -> int:
+        """``DETACH DELETE`` specific ``Entity`` vertices for a tenant (spec §7.4).
+
+        The orphan-GC primitive the reconcile layer (G1) calls after the
+        relational source-of-truth has dropped a person's last mention: the
+        catalog row is gone, so its now-bare AGE vertex (no remaining
+        ``MENTIONED_IN`` / ``CO_OCCURS`` edges) must be removed too, or the
+        graph drifts from the relational mirror. Only the listed
+        ``entity_uuids`` carrying ``tenant_id`` are removed; an empty sequence
+        is a no-op. Returns the number of vertices actually deleted (reflects
+        reality — a uuid with no matching vertex does not inflate the count).
+        Idempotent: re-deleting an already-gone vertex matches nothing and
+        contributes zero.
+        """
+        ...
+
+    def detach_delete_documents(
+        self,
+        conn: psycopg.Connection[Any],
+        tenant_id: str,
+        document_uuids: Sequence[str],
+    ) -> int:
+        """``DETACH DELETE`` specific ``Document`` vertices for a tenant (spec §7).
+
+        The document-removal primitive the reconcile layer (G1) calls from
+        ``remove_document`` (and from ``reconcile_document`` when an edit drops a
+        document to zero person mentions): ``DETACH DELETE`` removes the matched
+        ``Document`` vertices together with their attached ``MENTIONED_IN``
+        edges. Only the listed ``document_uuids`` carrying ``tenant_id`` are
+        removed; an empty sequence is a no-op. Returns the number of vertices
+        actually deleted. Idempotent.
+        """
+        ...
+
+    def clear_tenant(self, conn: psycopg.Connection[Any], tenant_id: str) -> int:
+        """Atomically clear ALL of one tenant's vertices + edges (spec §7 rebuild).
+
+        ``DETACH DELETE`` every ``Entity`` and ``Document`` vertex carrying
+        ``tenant_id`` (which removes their attached ``MENTIONED_IN`` /
+        ``CO_OCCURS`` edges) — including any AGE-only state with no relational
+        counterpart (a ``Document`` vertex for a doc removed from the relational
+        source, a stale AGE-only ``Entity``). The clear-then-rebuild primitive
+        the ``brain graphrag build --force`` path calls FIRST so the AGE mirror
+        is rebuilt fresh from the relational source-of-truth with no stale
+        survivors. Other tenants are untouched even when they share
+        ``entity_uuid`` / ``document_uuid`` values (the tenant property is matched
+        on every vertex). Atomic — runs inside its own ``conn.transaction()`` (a
+        real transaction on an autocommit connection, a SAVEPOINT when nested),
+        so a mid-clear failure rolls back wholesale rather than leaving a
+        half-cleared mirror. Returns the number of vertices deleted.
+        """
+        ...
+
+    def drop_graph(self, conn: psycopg.Connection[Any], tenant_id: str) -> int:
+        """Tenant-aware teardown: remove all of one tenant's vertices + edges.
+
+        ``DETACH DELETE`` every ``Entity`` and ``Document`` vertex carrying
+        ``tenant_id`` (which removes their attached edges). Other tenants are
+        untouched. Returns the number of vertices deleted. Equivalent to
+        :meth:`clear_tenant` (teardown vs clear-before-rebuild are the same
+        operation); kept as a distinct, intention-revealing name for decommission
+        callers.
+        """
+        ...

brain/graph_rag/build.py

@@ -0,0 +1,344 @@
+"""Corpus-wide people-aspect graph build driver (wave G1-d, GraphRAG, spec §9/§12).
+
+The batch equivalent of the per-document reconcile hook (wave G1-c): walk a
+stream of document ids and reconcile each one's people aspect into the graph.
+Backs ``brain graphrag build --backfill`` — the one-shot way to populate (or
+re-derive) the people graph for a corpus that was ingested before graph sync was
+enabled, or to propagate a corpus-wide config change.
+
+**Single source of truth for the per-doc logic.** :func:`build_graph` calls the
+SAME :func:`brain.graph_rag.reconcile.reconcile_document` the incremental hook
+uses, with the SAME immutable :class:`~brain.graph_rag.reconcile.ReconcileConfig`
+— so a batched backfill produces a graph identical to having reconciled each
+document one-by-one as it was ingested. No co-occurrence / weighting / AGE-sync
+logic is reimplemented here; this module only iterates and tallies.
+
+**Resumability (idempotent via the watermark).** ``reconcile_document`` skips a
+document whose per-aspect ``graph_index_state`` watermark is unchanged, so a
+build is safe to re-run and to resume after an interruption: re-running revisits
+the documents in the same ascending-id order (see
+:func:`brain.queries.iter_all_document_ids`) and the already-indexed prefix is
+skipped cheaply (one ``SELECT`` per doc). This only holds when each document
+commits independently, which it does when the caller passes an **autocommit**
+connection — ``reconcile_document`` then opens its own top-level transaction per
+document (see the reconcile module's "Connection contract"). The
+``brain graphrag build`` CLI sets ``conn.autocommit = True`` before calling this.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+import psycopg
+
+from ..errors import GraphReconcileError
+from .aggregates import (
+    _gc_orphan_concepts,
+    _gc_orphan_persons,
+    _recompute_aggregates,
+    refresh_aggregates,
+)
+from .backends.base import GraphBackend
+from .extract import EntityExtractor
+from .person_resolver import prebuilt_directory_resolver
+from .reconcile import ReconcileConfig, ReconcileResult, reconcile_document
+from .schema import GraphEntity
+
+__all__ = ["BuildResult", "ProgressCallback", "build_graph"]
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    """Tally of a :func:`build_graph` run.
+
+    ``processed`` is the number of documents reconcile was attempted on (bounded
+    by ``limit``); ``reconciled`` is how many did graph work; ``skipped`` is how
+    many short-circuited on an unchanged watermark (``reconciled + skipped ==
+    processed``); ``orphans_removed`` is the total zero-mention entity vertices
+    GC'd across the run; ``relationship_count`` is the number of tenant
+    ``graph_relationships`` edges materialized by the post-loop refresh (0 when no
+    document did work, so no refresh ran). Because the per-document reconcile
+    defers the tenant-wide aggregate recompute + orphan GC + AGE ``CO_OCCURS``
+    rebuild, ``orphans_removed`` and ``relationship_count`` are sourced from the
+    single post-loop :func:`~brain.graph_rag.aggregates.refresh_aggregates`, not
+    summed per document.
+    """
+
+    processed: int = 0
+    reconciled: int = 0
+    skipped: int = 0
+    orphans_removed: int = 0
+    relationship_count: int = 0
+
+
+# Invoked after each document with ``(processed_count, document_id, result)`` so
+# a CLI caller can throttle progress output without this module owning any I/O.
+ProgressCallback = Callable[[int, str, ReconcileResult], None]
+
+
+def build_graph(
+    conn: psycopg.Connection[Any],
+    document_ids: Iterable[str],
+    *,
+    backend: GraphBackend,
+    config: ReconcileConfig,
+    limit: int | None = None,
+    progress: ProgressCallback | None = None,
+    extractor: EntityExtractor | None = None,
+    force: bool = False,
+) -> BuildResult:
+    """Reconcile each document's people aspect into the graph (batch backfill).
+
+    Iterates ``document_ids`` (already ordered by the caller — ascending id for
+    a resumable build), calling :func:`reconcile_document` on each with the
+    shared ``config`` + ``backend``. Stops after ``limit`` documents when set
+    (caps the corpus for testing / partial runs). Returns a :class:`BuildResult`
+    tally; ``progress`` (when given) is called once per processed document.
+
+    **Deferred whole-tenant refresh (perf).** Every per-document reconcile runs
+    with ``defer_tenant_refresh=True``, so the tenant-wide derived layers — the
+    ``graph_relationships`` recompute, the orphan GC, and the AGE ``CO_OCCURS``
+    rematerialization — are skipped per document and recomputed ONCE after the
+    loop via :func:`~brain.graph_rag.aggregates.refresh_aggregates` (only when at
+    least one document did work). The AGE ``CO_OCCURS`` rebuild is a whole-tenant
+    operation whose cost scales with the tenant's relationship count R, so running
+    it per document made a corpus build O(docs × R); hoisting it to a single final
+    pass makes the build O(docs × doc_entities + R) while producing the identical
+    end state (the derived layers are a deterministic full recompute from the
+    per-document relational source-of-truth, which IS still written per document).
+    Applies to both the plain backfill and the ``force`` rebuild below.
+
+    **Directory index hoist (perf, Fix B).** The People-Hub directory index
+    (``directory_entries``) drives person resolution but is corpus-wide and does
+    NOT change during a build, so this driver builds it ONCE before the loop and
+    injects it through reconcile's ``person_resolver`` DI seam (via
+    :func:`brain.graph_rag.person_resolver.prebuilt_directory_resolver`) — instead
+    of every per-document reconcile rebuilding the ~1.2k-row ``SELECT`` + dict.
+    The incremental ingest hook (``sync.py``) is unaffected: it uses the default
+    resolver, which builds its own single-document index.
+
+    The connection SHOULD be autocommit so each document commits on its own,
+    making the build resumable after an interruption (see the module docstring).
+    A non-autocommit connection still works but the whole run becomes one
+    transaction — an interruption then rolls everything back.
+
+    ``extractor`` is the concept-aspect DI seam (wave G2-c): when
+    ``config.concepts_enabled`` is True it MUST be provided (production passes
+    :func:`brain.graph_rag.extract.make_extractor`; tests pass a fake), and each
+    document's concept aspect is (re)indexed alongside its person aspect under its
+    own watermark. When concepts are disabled (the default) it is ignored and the
+    build is person-only — fully backward compatible. The force pre-pass GCs
+    orphans of BOTH aspects + restores ALL of the tenant's entity vertices (any
+    type), so a force rebuild faithfully restores any existing concept graph from
+    the relational source-of-truth even without re-extraction.
+
+    ``force=True`` is the authoritative **clean-then-rebuild** recovery path
+    (``brain graphrag build --force``) that produces a clean state in BOTH the
+    relational source AND the AGE mirror. It:
+
+    1. cleans the RELATIONAL source for the tenant — recompute
+       ``graph_relationships`` from the current contributions (drops aggregate
+       rows stranded by deleted docs) and GC orphan entities (zero remaining
+       mentions); reuses :func:`~brain.graph_rag.aggregates._recompute_aggregates`
+       + :func:`~brain.graph_rag.aggregates._gc_orphan_persons`. This is what
+       makes the zero-doc / all-docs-deleted case authoritative (no per-doc
+       reconcile runs there to clean up);
+    2. clears the tenant's ENTIRE existing AGE mirror
+       (:meth:`~brain.graph_rag.backends.base.GraphBackend.clear_tenant`), so no
+       stale survivors remain — a ``Document`` vertex for a doc removed from the
+       relational source, an AGE-only ``Entity`` with no catalog row, orphan
+       edges;
+    3. restores every (now non-orphan) tenant ``Entity`` vertex from the clean
+       relational catalog (the pre-pass that lets the per-doc full-tenant
+       ``CO_OCCURS`` rematerialization find its endpoints); then
+    4. threads :func:`reconcile_document`'s force flag through every document,
+       bypassing the per-aspect watermark so each doc is fully re-reconciled and
+       its watermark rewritten.
+
+    Net result: BOTH stores are clean — no orphan entities and
+    ``graph_relationships`` (relational + the AGE ``CO_OCCURS`` mirror) reflect
+    only current contributions — and the AGE mirror is rebuilt fresh from the
+    relational source-of-truth (entities + ``MENTIONED_IN`` + ``Document``
+    vertices + ``CO_OCCURS``). A zero-document corpus ends empty in both stores.
+    No document short-circuits, so ``reconciled == processed`` and
+    ``skipped == 0``.
+
+    ``force`` is incompatible with ``limit`` (a clear-then-partial-rebuild would
+    permanently lose the un-rebuilt remainder) — passing both raises
+    :class:`brain.errors.GraphReconcileError` (the CLI rejects it earlier as a
+    ``BadParameter``). A zero-document corpus + ``force`` clears the tenant to an
+    empty graph (correct).
+    """
+    if force and limit is not None:
+        # A clear-then-partial-rebuild is incoherent: the clear wipes the whole
+        # tenant mirror, but a limited loop would only rebuild a prefix, leaving
+        # the rest permanently missing. Reject the combination (the CLI surfaces
+        # this as a BadParameter before reaching here).
+        raise GraphReconcileError(
+            "build_graph(force=True) rebuilds the full corpus and cannot be "
+            "combined with limit (a clear-then-partial-rebuild is incoherent)"
+        )
+
+    if force:
+        # Authoritative rebuild = a clean state in BOTH stores (spec §7), in this
+        # order: clean the relational source, then clear + rebuild the AGE mirror
+        # FROM that clean source.
+        #
+        # The pre-pass (steps 1-3) runs inside ONE outer transaction so it is
+        # atomic AS A UNIT: a failure during the restore (step 3), AFTER the AGE
+        # mirror was cleared (step 2), rolls EVERYTHING back — relational + AGE
+        # are left exactly as they were before the --force call. A recovery
+        # command must never leave the graph in a worse (cleared / half-restored)
+        # state than it started. ``clear_tenant`` and ``upsert_entities`` open
+        # their own ``conn.transaction()``, which nest here as SAVEPOINTs, and
+        # each AGE primitive activates its own ``ag_catalog`` search_path for the
+        # duration of its statements; the relational steps run on the default
+        # search_path. The per-doc reconcile LOOP below stays incremental and
+        # resumable (each document commits in its own transaction) — only the
+        # clear/restore must be atomic together.
+        with conn.transaction():
+            # 1. RELATIONAL clean: recompute graph_relationships from the CURRENT
+            #    contributions (drops aggregate rows stranded by deleted docs) and
+            #    GC orphan entities (zero remaining mentions). Reuses the same
+            #    aggregate helpers as reconcile/refresh — no duplicated logic.
+            #    This is what makes the zero-doc / all-docs-deleted case
+            #    authoritative: there is no per-doc reconcile then to GC/recompute,
+            #    so the stale relational rows would otherwise survive (and be
+            #    mirrored into AGE by the pre-pass below).
+            _recompute_aggregates(conn, config.tenant_id, config.generic_df_ratio)
+            # GC orphans of BOTH aspects (concept GC is a no-op when no concept
+            # entities exist, so this is safe for the person-only default too).
+            _gc_orphan_persons(conn, config.tenant_id)
+            _gc_orphan_concepts(conn, config.tenant_id)
+            # 2. Clear the tenant's entire AGE mirror so nothing stale survives — a
+            #    Document vertex for a doc removed from the relational source, an
+            #    AGE-only Entity with no catalog row, orphan edges.
+            backend.clear_tenant(conn, config.tenant_id)
+            # 3. Restore Entity vertices from the now-clean relational catalog. The
+            #    GC in step 1 ran first, so orphan entities never reach AGE; this
+            #    pre-pass lets each per-doc CO_OCCURS refresh bind its endpoints (a
+            #    per-doc reconcile rematerializes the WHOLE tenant's CO_OCCURS,
+            #    which requires every contribution-referenced Entity vertex to
+            #    exist).
+            _restore_tenant_entity_vertices(conn, config.tenant_id, backend=backend)
+
+    # Perf Fix B (2026-05-24): build the People-Hub directory index ONCE for the
+    # whole batch and inject it through reconcile's person_resolver DI seam,
+    # instead of every per-document reconcile rebuilding it. The directory
+    # (``directory_entries``, ~1.2k rows) is corpus-wide and does NOT change
+    # during a build, so rebuilding the SELECT + dict per document is pure waste
+    # (~30-80 ms/doc). The incremental ingest hook (``sync.py``) keeps using the
+    # default resolver, which builds its own single-document index, so the
+    # one-doc path is unchanged. Late import keeps this module import-cheap
+    # (``build_people`` pulls in the wiki package), mirroring person_resolver's
+    # own late import of the same helper.
+    from ..wiki.build_people import _build_directory_index
+
+    directory = _build_directory_index(conn, sender_denylist=config.sender_denylist)
+    resolver = prebuilt_directory_resolver(directory)
+
+    processed = 0
+    reconciled = 0
+    skipped = 0
+    orphans_removed = 0
+    for document_id in document_ids:
+        if limit is not None and processed >= limit:
+            break
+        result = reconcile_document(
+            conn,
+            document_id,
+            backend=backend,
+            config=config,
+            person_resolver=resolver,
+            extractor=extractor,
+            force=force,
+            defer_tenant_refresh=True,
+        )
+        processed += 1
+        if result.skipped:
+            skipped += 1
+        else:
+            reconciled += 1
+        orphans_removed += result.orphans_removed
+        if progress is not None:
+            progress(processed, document_id, result)
+
+    # Each per-document reconcile above ran with ``defer_tenant_refresh=True``, so
+    # the tenant-wide derived layers — ``graph_relationships`` (normalized lift +
+    # generic suppression), the orphan GC of both aspects, the AGE ``CO_OCCURS``
+    # rematerialization, and the orphan-vertex DETACH DELETE — were skipped per
+    # document and are recomputed ONCE here from the now-complete relational
+    # source-of-truth. This is the SAME whole-tenant operation reconcile ran per
+    # document before (``refresh_aggregates`` reuses the identical aggregate + GC
+    # helpers), hoisted out of the loop: a corpus build drops from O(docs ×
+    # tenant_R) per-doc CO_OCCURS rebuilds to O(docs × doc_entities + tenant_R)
+    # (one final rebuild), and the end state is identical (a deterministic full
+    # recompute from the source-of-truth).
+    #
+    # Gate on ``reconciled > 0``: the refresh runs only when at least one document
+    # changed the relational source (so the derived layers are stale). When every
+    # document short-circuited on its watermark (an idempotent re-run, or a plain
+    # ``--backfill`` over an unchanged corpus) the derived layers are already
+    # consistent from the build that did the work, so skipping the refresh keeps
+    # the re-run a true no-op AND avoids a spurious ``refresh_cooccur_edges`` that
+    # would raise against a deliberately-dropped AGE mirror (the recovery path for
+    # that is ``--force``, which always reconciles).
+    #
+    # CRASH-WINDOW RECOVERY: if a deferred build is interrupted AFTER the last
+    # document's watermark is written but BEFORE this final refresh runs, a
+    # same-command rerun all-skips (``reconciled == 0``) and will NOT repair the
+    # derived layer (``graph_relationships`` / AGE ``CO_OCCURS``) — run
+    # ``brain graphrag refresh`` (or ``brain graphrag build --force``) to repair.
+    # The relational source-of-truth stays correct throughout.
+    relationship_count = 0
+    if reconciled > 0:
+        refresh = refresh_aggregates(conn, backend=backend, config=config)
+        relationship_count = refresh.relationship_count
+        orphans_removed += refresh.orphans_removed
+    return BuildResult(
+        processed=processed,
+        reconciled=reconciled,
+        skipped=skipped,
+        orphans_removed=orphans_removed,
+        relationship_count=relationship_count,
+    )
+
+
+def _restore_tenant_entity_vertices(
+    conn: psycopg.Connection[Any], tenant_id: str, *, backend: GraphBackend
+) -> int:
+    """Re-MERGE every relational ``graph_entities`` row for a tenant into AGE.
+
+    The force-rebuild pre-pass (spec §7 authoritative rebuild). A per-document
+    :func:`reconcile_document` recreates the doc's own entity vertices but then
+    rematerializes the WHOLE tenant's ``CO_OCCURS`` edges, which requires *every*
+    contribution-referenced entity to already have an AGE vertex
+    (:meth:`~brain.graph_rag.backends.base.GraphBackend.refresh_cooccur_edges`
+    raises if an endpoint vertex is missing). After a dropped or corrupted AGE
+    mirror that invariant is broken — the relational catalog still lists every
+    entity but no AGE vertex exists — so the first forced doc's cooccur refresh
+    would fail to bind an endpoint that belongs to a not-yet-processed doc.
+    Restoring all of the tenant's Entity vertices up front (an idempotent MERGE)
+    re-establishes the invariant, so each subsequent forced per-doc reconcile
+    rebuilds mentions / MENTIONED_IN / Document vertices / CO_OCCURS exactly as
+    the incremental path would. Returns the number of entity vertices restored.
+    """
+    rows = conn.execute(
+        "SELECT id::text, entity_type, name, canonical_key "
+        "FROM graph_entities WHERE tenant_id = %s",
+        (tenant_id,),
+    ).fetchall()
+    entities = [
+        GraphEntity(
+            id=str(row[0]),
+            entity_type=str(row[1]),
+            name=str(row[2]),
+            canonical_key=str(row[3]),
+            tenant_id=tenant_id,
+        )
+        for row in rows
+    ]
+    if entities:
+        backend.upsert_entities(conn, tenant_id, entities)
+    return len(entities)