rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/compliance_store.py

@@ -0,0 +1,87 @@
+"""ADR-0117 DD-1b: the compliance domain's store extension.
+
+Composes a generic `Store` (`kg_write`/`kg_read`) to persist + read the Requirement KG, so the engine store imports
+no compliance contract. A new domain writes its own typed records the same way -- the pattern, not the schema, is
+what the engine provides. The `Requirement` vertex + its property storage types are schema-declared (ADR-0067 P5b),
+so `kg_write` encodes each field (incl. `pages` as a native array, `bbox`/`applicability_json` as JSON strings)."""
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+from rag_wright.capabilities.highlight_serve import _decode_bbox
+from rag_wright.contracts.compliance import Requirement, RequirementLocation
+from rag_wright.store.arcadedb import REQUIREMENT_TYPE
+from rag_wright.store.seam import KgNode
+
+
+class ComplianceStore:
+    """Requirement-KG writes + the compliance READ facade over a generic `Store` (EP-REF-1b). The reads shape
+    the stored `Requirement` rows into the domain answers a product serves (what EP-SEAM-3 lifts), so the engine
+    store stays generic and a new domain supplies its own facade the same way."""
+
+    def __init__(self, store) -> None:
+        self._store = store
+
+    def write_requirements(self, requirements: Iterable[Requirement]) -> int:
+        """Upsert `Requirement` nodes by `requirement_id` (idempotent -- a re-ingest is a no-op on unchanged rules),
+        in one transaction. Domain-native values in; the store encodes per the declared storage type. Returns count."""
+        nodes = [
+            KgNode(REQUIREMENT_TYPE, "requirement_id", {
+                "requirement_id": req.requirement_id,
+                "source": req.source,
+                "citation": req.citation,
+                "deontic_type": req.deontic_type.value,
+                "actor": req.actor,
+                "requirement_text": req.requirement_text,
+                "evidence_standard": req.evidence_standard or "",
+                "severity": req.severity.value if req.severity else "",
+                "applicability_json": [[c.dimension, c.value] for c in req.applicability_scope],
+                "confidence": req.confidence.value,
+                "pages": [int(p) for p in req.pages],
+                "bbox": list(req.bbox) if req.bbox is not None else None,
+            })
+            for req in requirements
+        ]
+        self._store.kg_write(nodes)
+        return len(nodes)
+
+    # --- EP-REF-1b: the compliance READ facade (the reference versions the product seam lifts) ---------
+
+    def requirements_for(self, source: str) -> list[dict]:
+        """The curated requirement rows filed under one policy `source` -- the proof an ingest landed. DB-scoped
+        (`all_requirements(sources=[source])`), so a multi-policy store never fetches the rows outside scope."""
+        return self._store.all_requirements(sources=[source])
+
+    def requirement_locations(self, source: str) -> list[RequirementLocation]:
+        """Where each requirement of one policy sits in its document (pages + optional bbox), for a citation
+        preview. Reads defensively: a requirement curated before provenance landed (ADR-0107) has no pages/bbox,
+        so `pages` -> [] and a malformed/absent `bbox` -> None (a page is still openable without a rectangle)."""
+        return [
+            RequirementLocation(
+                requirement_id=str(r.get("requirement_id") or ""),
+                citation=str(r.get("citation") or ""),
+                pages=[int(p) for p in (r.get("pages") or [])],
+                bbox=_decode_bbox(r.get("bbox")),
+                text=str(r.get("requirement_text") or ""),
+            )
+            for r in self._store.all_requirements(sources=[source])
+        ]
+
+    def curated_requirement_count(self, sources: Optional[list[str]] = None) -> int:
+        """How many requirements are IN SCOPE -- the denominator of an honest coverage statement (consulted N of
+        curated M). `sources=None` counts store-wide; a list scopes it (DB-side), `[]` is zero."""
+        return len(self._store.all_requirements(sources=sources))
+
+    @staticmethod
+    def policy_of_requirement(requirement_id: str) -> str:
+        """The policy a requirement belongs to, from its id `<source>:<section>:<hash>`. Split on the FIRST colon
+        -- a source name may legitimately contain dots/hyphens ("ISO.27001-2022"), which a last-colon split eats.
+        Empty id -> ''. This prefix is the only link a `ComplianceFinding` carries back to its policy."""
+        return requirement_id.split(":", 1)[0] if requirement_id else ""
+
+    @staticmethod
+    def gated_pairs(report) -> list[dict]:
+        """The (assertion|document, rule) pairs the symbolic ACTOR gate skipped before any judge call -- honest
+        coverage (ADR-0068): a shallow copy of `ComplianceReport.gated_pairs`. The ACTOR gate ONLY; top-k semantic
+        narrowing also drops pairs and is NOT reported here, so `[]` does not mean every pair was evaluated."""
+        return [dict(entry) for entry in (getattr(report, "gated_pairs", None) or [])]

rag_wright/capabilities/contract_kg_serve.py

@@ -0,0 +1,156 @@
+"""KG-4 (FR-Q, ADR-0033): Leg A -- intra-contract scoped-query serving over the typed contract KG.
+
+This is the structured/relational/cited backend the classification-only front door (`highlight_serve`)
+couldn't give. Scoped to one `contract_id` (a clause_id is `<contract_id>:<index>:<hash>`, so a contract's
+clauses are one key range), it answers questions over the typed KG that a clause-type filter can't:
+
+- **disambiguate** same-type clauses by a property ("the *mutual* cap clause"; "the indemnity that covers
+  *fraud*") -- `disambiguate`;
+- **aggregate** across the contract ("every clause that waives *consequential* damages"; "all *governed_by*
+  facts") -- `aggregate_by_property`, `clauses_of_function`;
+- serve the whole **per-contract KG** (each clause + its typed properties) -- `contract_clause_index`.
+
+Every answer is CITED: each clause carries its `clause_id` and each property its edge provenance
+(`confidence` EXTRACTED/INFERRED/AMBIGUOUS + `span_id`, whose doc offsets live on the span) -- no claim
+without a citation (FR-Q.6). The store is duck-typed (the three `*_contract*` / `clauses_with_property`
+readbacks) so this layer is unit-tested with no live ArcadeDB.
+
+Out of scope here (need layers not in the clause KG): party<->clause ROLE questions (a per-clause party-role layer, Leg C -- not built; the PartyTo edge was retired,
+issue 0028) and cross-clause REFERENCES (not extracted). Noted for a later pass.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+class CitedProperty(BaseModel):
+    """One typed property of a clause, with its edge provenance (FR-Q.6)."""
+
+    dimension: str
+    value: str
+    edge_type: str
+    predicate_iri: str = ""
+    confidence: str = ""
+    span_id: str = ""
+
+
+class CitedClause(BaseModel):
+    """A clause in a contract with its typed properties, each cited."""
+
+    contract_id: str
+    clause_id: str
+    function: str
+    folio_iri: str = ""
+    span_id: str = ""  # the clause's operative span (1:1); rehydrate a property-less clause from THIS, reliably
+    exception_of: str = ""  # ADR-0044: if set, this clause is an INFERRED carve-out/exception to that cap clause_id
+    properties: list[CitedProperty] = []
+
+
+@runtime_checkable
+class _KGStore(Protocol):
+    def clauses_in_contract(self, contract_id: str) -> list[dict]: ...
+    def contract_clause_kg(self, contract_id: str) -> list[dict]: ...
+    def clauses_with_property(self, contract_id: str, dimension: str, value: str) -> list[dict]: ...
+    def all_spans_by_contract(self, contract_id: str) -> list[dict]: ...  # 0006-D: untyped-span fallback
+
+
+def _contract_of(clause_id: str) -> str:
+    return clause_id.split(":", 1)[0]
+
+
+def _prop(row: dict) -> CitedProperty:
+    return CitedProperty(
+        dimension=row.get("dimension", ""), value=row.get("value", ""),
+        edge_type=row.get("edge_type", ""), predicate_iri=row.get("predicate_iri") or "",
+        confidence=row.get("confidence") or "", span_id=row.get("span_id") or "",
+    )
+
+
+def contract_clause_index(
+    store: _KGStore, contract_id: str, *, include_untyped: bool = False
+) -> list[CitedClause]:
+    """The full per-contract KG: every clause (incl. property-less ones) with its typed properties, cited.
+
+    `include_untyped` (issue 0006-D): also serve the spans the classifier left UNTYPED (`function == NONE`),
+    which produce no Clause-KG node. Without this, a clause the classifier misses (e.g. a renewal clause it can't
+    map to the taxonomy) is ABSENT from what Leg-A serves -> a silent recall hole ("not_found" on a clause that
+    plainly exists). With it, an untyped span is served as a bare `CitedClause` (no properties), rehydrated from
+    its own `span_id` -- so recall is decoupled from classification (the ADR-0047 whole-index posture)."""
+    by_clause: dict[str, list[CitedProperty]] = {}
+    for row in store.contract_clause_kg(contract_id):
+        if not row.get("dimension"):  # a non-property clause edge (e.g. IsExceptionTo, ADR-0044) -> not a fact
+            continue
+        by_clause.setdefault(row["clause_id"], []).append(_prop(row))
+    index = []
+    for c in store.clauses_in_contract(contract_id):
+        cid = c["clause_id"]
+        index.append(CitedClause(
+            contract_id=_contract_of(cid), clause_id=cid, function=c.get("function", ""),
+            folio_iri=c.get("folio_iri") or "", span_id=c.get("span_id") or "",
+            properties=by_clause.get(cid, []),
+        ))
+    if include_untyped:
+        covered = {c.span_id for c in index if c.span_id}  # spans a typed clause already carries
+        for row in store.all_spans_by_contract(contract_id):
+            sid = row.get("span_id")
+            if sid and sid not in covered and (row.get("text") or "").strip():
+                index.append(CitedClause(
+                    contract_id=contract_id, clause_id=sid, function=row.get("function") or "NONE",
+                    span_id=sid, properties=[]))  # bare; rehydrate_clause_texts fetches its text by function+span
+    return index
+
+
+def clauses_of_function(store: _KGStore, contract_id: str, function: str) -> list[CitedClause]:
+    """Aggregation by clause type: all clauses of `function` in the contract, cited with their properties."""
+    return [c for c in contract_clause_index(store, contract_id) if c.function == function]
+
+
+def disambiguate(
+    store: _KGStore, contract_id: str, function: str, dimension: str, value: str
+) -> list[CitedClause]:
+    """The same-type clauses in the contract that assert (dimension, value) -- e.g. among several
+    Cap-on-Liability clauses, the *mutual* one. The scoped-query answer classification can't give."""
+    matched = {r["clause_id"] for r in store.clauses_with_property(contract_id, dimension, value)}
+    return [c for c in clauses_of_function(store, contract_id, function) if c.clause_id in matched]
+
+
+def aggregate_by_property(
+    store: _KGStore, contract_id: str, dimension: str, value: str
+) -> list[CitedClause]:
+    """Every clause in the contract asserting (dimension, value), regardless of type -- e.g. all clauses
+    that waive consequential damages, or every mutual obligation."""
+    matched = {r["clause_id"] for r in store.clauses_with_property(contract_id, dimension, value)}
+    by_id = {c.clause_id: c for c in contract_clause_index(store, contract_id)}
+    return [by_id[cid] for cid in matched if cid in by_id]
+
+
+def grounded_only(clauses: list[CitedClause]) -> list[CitedClause]:
+    """Drop the AMBIGUOUS (grounding-judge-flagged) properties -- the high-precision view for a citation UI.
+    Returns copies keeping only EXTRACTED/INFERRED properties."""
+    return [
+        c.model_copy(update={"properties": [p for p in c.properties if p.confidence != "AMBIGUOUS"]})
+        for c in clauses
+    ]
+
+
+def register_intra_document_scoped_query(registry) -> None:
+    """CAP-REG-2: register `intra_document_scoped_query` (function; intra-contract scoped KG serving)."""
+    registry.register(
+        "intra_document_scoped_query",
+        contract=CitedClause,
+        kind="function",
+        display_name="Intra-document scoped query",
+    )
+
+
+def register_clause_disambiguation(registry) -> None:
+    """CAP-REG-2: register `clause_disambiguation` (function; disambiguation by typed property)."""
+    registry.register(
+        "clause_disambiguation",
+        contract=CitedClause,
+        kind="function",
+        display_name="Clause disambiguation",
+    )

rag_wright/capabilities/contract_kg_store.py

@@ -0,0 +1,251 @@
+"""ADR-0117 DD-1b: the contract domain's store extension.
+
+Composes a generic `Store` (`kg_write`/`kg_read`) to write the typed clause KG (KG-3), the legacy flat property
+graph, and contract metadata -- so the engine store imports no contract contract. The clause/value/contract vertex
+types + the dimension->edge map + predicate IRIs are pack-authoritative (`contract_bridge.ttl`, ADR-0067 P5a/P5b);
+`kg_write` encodes each field per its declared storage type (e.g. `functions` as a JSON string). Domain-native
+values in; the store owns all wire encoding."""
+from __future__ import annotations
+
+from typing import Optional
+
+from rag_wright.capabilities.highlight_serve import _decode_bbox
+from rag_wright.contracts.contract_meta import ContractRecord
+from rag_wright.contracts.highlight import SpanLocation
+from rag_wright.contracts.property import FOLIO_SUBJECT_IRI, ClausePropertyRecord
+from rag_wright.store.arcadedb import (
+    CLAUSE_TYPE,
+    CONTRACT_TYPE,
+    IS_EXCEPTION_TO_EDGE_TYPE,
+    PROPERTY_EDGE_TYPE,
+    PROPVALUE_TYPE,
+    TYPED_PROPERTY_EDGE_TYPES,
+    _DIM_EDGE_STR,
+    _edge_predicate_iri,
+    _property_value_key,
+)
+from rag_wright.ontology.contract_taxonomy import AFFILIATE_OF, CONTRACTS_WITH  # DD-5 contract edge names
+from rag_wright.store.seam import NOT_NULL, KgEdge, KgNode
+
+
+class ContractKGStore:
+    """Typed clause-KG + contract-metadata writes over a generic `Store`."""
+
+    def __init__(self, store) -> None:
+        self._store = store
+
+    def _already_written(self, clause_id: str) -> bool:
+        """Content-hash gate (FR-S.2): a committed `clause_id` embeds the content hash, so identical content ->
+        identical assertions -- skip (and the plain edge creates therefore run at most once per clause)."""
+        return bool(self._store.kg_read(CLAUSE_TYPE, fields=["clause_id"], where={"clause_id": clause_id}, limit=1))
+
+    def write_clause_kg(self, record: ClausePropertyRecord) -> None:
+        """KG-3 (ADR-0033): the Clause node + one shared PropertyValue node per (dimension,value) + one TYPED edge
+        per assertion (grounded with a predicate IRI + provenance). Idempotent by the content-hash gate."""
+        if self._already_written(record.clause_id):
+            return
+        functions = [{"function": f.function, "confidence": f.confidence.value} for f in record.functions]
+        nodes = [KgNode(CLAUSE_TYPE, "clause_id", {
+            "clause_id": record.clause_id, "function": record.function, "folio_iri": record.folio_iri,
+            "span_id": record.span_id, "functions": functions})]
+        edges = []
+        for a in record.assertions:
+            edge_type = _DIM_EDGE_STR[a.dimension.value]
+            key = _property_value_key(a.dimension.value, a.value)
+            nodes.append(KgNode(PROPVALUE_TYPE, "value_key", {
+                "value_key": key, "dimension": a.dimension.value, "value": a.value,
+                "folio_iri": FOLIO_SUBJECT_IRI.get(a.value, "")}))
+            edges.append(KgEdge(edge_type, CLAUSE_TYPE, "clause_id", record.clause_id, PROPVALUE_TYPE, "value_key",
+                                key, {
+                                    "dimension": a.dimension.value, "predicate_iri": _edge_predicate_iri(edge_type),
+                                    "confidence": a.confidence.value, "span_id": a.span_id,
+                                    "chunk_id": str(a.provenance.chunk_id),
+                                    "source_doc_id": a.provenance.source_doc_id}))
+        self._store.kg_write(nodes, edges)
+
+    def write_property_graph(self, record: ClausePropertyRecord) -> None:
+        """Legacy flat property graph (ADR-0025/0026; superseded by `write_clause_kg`): the Clause node + shared
+        value nodes + one generic `HasProperty` edge per assertion. Same content-hash gate."""
+        if self._already_written(record.clause_id):
+            return
+        nodes = [KgNode(CLAUSE_TYPE, "clause_id", {
+            "clause_id": record.clause_id, "function": record.function, "folio_iri": record.folio_iri})]
+        edges = []
+        for a in record.assertions:
+            key = _property_value_key(a.dimension.value, a.value)
+            nodes.append(KgNode(PROPVALUE_TYPE, "value_key", {
+                "value_key": key, "dimension": a.dimension.value, "value": a.value,
+                "folio_iri": FOLIO_SUBJECT_IRI.get(a.value, "")}))
+            edges.append(KgEdge(PROPERTY_EDGE_TYPE, CLAUSE_TYPE, "clause_id", record.clause_id, PROPVALUE_TYPE,
+                                "value_key", key, {
+                                    "confidence": a.confidence.value, "span_id": a.span_id,
+                                    "chunk_id": str(a.provenance.chunk_id),
+                                    "source_doc_id": a.provenance.source_doc_id}))
+        self._store.kg_write(nodes, edges)
+
+    def patch_canonical_jurisdictions(self) -> dict[str, int]:
+        """KG-5a (DD-1c): additively canonicalize the `jurisdiction` value nodes -- write a `canonical_value` on
+        each (surface `value` untouched, kept for citation), deterministically (no LLM, no re-extraction). Fixes the
+        retrieval-match loss from surface variants (England / England and Wales / English law). Idempotent; the
+        `canonical_value` property is pack-declared. Returns {seen, canonicalized}."""
+        from rag_wright.contracts.jurisdiction import canonicalize_jurisdiction
+
+        rows = self._store.kg_read(PROPVALUE_TYPE, fields=["value_key", "value"],
+                                   where={"dimension": "jurisdiction"})
+        nodes = []
+        for r in rows:
+            canon = canonicalize_jurisdiction(r["value"])
+            if canon:
+                nodes.append(KgNode(PROPVALUE_TYPE, "value_key",
+                                    {"value_key": r["value_key"], "canonical_value": canon}))
+        if nodes:
+            self._store.kg_write(nodes)
+        return {"seen": len(rows), "canonicalized": len(nodes)}
+
+    def upsert_contract(self, record: ContractRecord) -> None:
+        """CU-B3: upsert a contract's metadata by `contract_id`. `parties` -> native list (the store json-encodes
+        the `parties_json` STRING column); `page_count` may be None (-> null)."""
+        self._store.kg_write([KgNode(CONTRACT_TYPE, "contract_id", {
+            "contract_id": record.contract_id, "name": record.name, "agreement_type": record.agreement_type,
+            "parties_json": list(record.parties), "agreement_date": record.agreement_date,
+            "effective_date": record.effective_date, "source_doc_id": record.source_doc_id,
+            "content_hash": record.content_hash, "page_count": record.page_count})])
+
+    # --- EP-REF-1a-ii: the typed clause-KG edge-traversal READS, over the generic `kg_edges` primitive. These
+    #     moved OFF the engine store (which must hold no domain traversal, ADR-0117); the store keeps only the
+    #     generic kg_edges/kg_read. Shapes are byte-for-byte the old store methods' (acceptance: identical reads).
+
+    @staticmethod
+    def _bounds(contract_id: str) -> tuple[str, str]:
+        return contract_id + ":", contract_id + ";"  # clause_ids are `<contract>:<idx>:<hash>`
+
+    def clause_typed_edges(self, clause_id: str) -> list[dict]:
+        """The clause's typed property edges: edge type, dimension, value, predicate IRI, and provenance."""
+        return self._store.kg_edges(
+            CLAUSE_TYPE, where={"clause_id": clause_id}, direction="out",
+            select={"edge_type": "e.@type", "predicate_iri": "e.predicate_iri", "dimension": "v.dimension",
+                    "value": "v.value", "folio_iri": "v.folio_iri", "confidence": "e.confidence",
+                    "span_id": "e.span_id"})
+
+    def contract_clause_kg(self, contract_id: str) -> list[dict]:
+        """The per-contract typed subgraph: one row per typed (clause -> value) edge, with the clause function,
+        edge type/dimension/value/predicate IRI, and provenance. Only PROPERTY edges (which carry a `dimension`);
+        the `dimension IS NOT NULL` guard excludes clause->clause edges (IsExceptionTo, ADR-0044)."""
+        lo, hi = self._bounds(contract_id)
+        return self._store.kg_edges(
+            CLAUSE_TYPE, key_range=("clause_id", lo, hi), direction="out", edge_where={"dimension": NOT_NULL},
+            select={"clause_id": "c.clause_id", "function": "c.function", "edge_type": "e.@type",
+                    "dimension": "e.dimension", "value": "v.value", "folio_iri": "v.folio_iri",
+                    "predicate_iri": "e.predicate_iri", "confidence": "e.confidence", "span_id": "e.span_id"})
+
+    def clauses_with_property(self, contract_id: str, dimension: str, value: str) -> list[dict]:
+        """The clauses in one contract that assert (dimension, value) -- clause_id + function + edge provenance."""
+        lo, hi = self._bounds(contract_id)
+        return self._store.kg_edges(
+            CLAUSE_TYPE, key_range=("clause_id", lo, hi), direction="out",
+            edge_where={"dimension": dimension}, target_where={"value": value},
+            select={"clause_id": "c.clause_id", "function": "c.function", "edge_type": "e.@type",
+                    "confidence": "e.confidence", "span_id": "e.span_id"})
+
+    def exceptions_of_clause(self, cap_clause_id: str) -> list[dict]:
+        """The exception/carve-out clauses linked to a Cap clause (`IsExceptionTo` in-edges, ADR-0044): the SOURCE
+        clauses reached across the incoming edge. Rows: {clause_id, function, span_id}."""
+        return self._store.kg_edges(
+            CLAUSE_TYPE, where={"clause_id": cap_clause_id}, direction="in",
+            edge_type=IS_EXCEPTION_TO_EDGE_TYPE,
+            select={"clause_id": "v.clause_id", "function": "v.function", "span_id": "v.span_id"})
+
+    def span_properties(self, span_ids: list[str]) -> dict[str, set[tuple[str, str]]]:
+        """The typed (dimension, value) assertions on each span, joined via the ADR-0025 `edge.span_id`. Scans each
+        typed edge type once (IN-filtered), so round-trips are bounded by the edge-type count, not the pool size.
+        Returns {span_id: {(dimension, value)}} (every input span present, empty if none)."""
+        out: dict[str, set[tuple[str, str]]] = {s: set() for s in span_ids}
+        if not span_ids:
+            return out
+        for edge_type in TYPED_PROPERTY_EDGE_TYPES:
+            for r in self._store.kg_edges(
+                edge_type=edge_type, edge_where={"span_id": span_ids},
+                select={"span_id": "span_id", "dimension": "dimension", "value": "inV().value"}):
+                sid, dim, val = r.get("span_id"), r.get("dimension"), r.get("value")
+                if sid in out and dim and val is not None:
+                    out[sid].add((str(dim), str(val)))
+        return out
+
+    def clauses_in_contract(self, contract_id: str) -> list[dict]:
+        """Every clause in one contract (a NODE read, delegated to the generic store -- it is a `kg_read`-
+        relocatable follow-up, not an edge traversal). Kept here so this extension is the complete `_KGStore`
+        reader the Leg-A serving (`contract_kg_serve`) needs."""
+        return self._store.clauses_in_contract(contract_id)
+
+    def all_spans_by_contract(self, contract_id: str) -> list[dict]:
+        """Every span in one contract (delegated to the generic store). The Leg-A serving
+        (`contract_clause_index(..., include_untyped=True)`) reads this so a span the classifier left untyped is
+        still a candidate -- without it, serve raised AttributeError and intra_document_qa abstained on EVERY doc."""
+        return self._store.all_spans_by_contract(contract_id)
+
+    # --- EP-REF-1b-ii: contract traversal + vocab (the reference reads EP-SEAM-3 lifts), over the entity-graph
+    #     traversal primitive + the clause index. The CONTRACTS_WITH / AFFILIATE_OF naming is the DD-5 contract
+    #     vocabulary over the generic (domain-free) graph_query.
+
+    def party_counterparties(self, entity_id: str, *, max_hops: int = 1,
+                             documents: Optional[list[str]] = None) -> list:
+        """The parties this one has a CONTRACTS_WITH edge to, each citing the contract it came from. ONE hop by
+        default -- two hops would return the counterparties OF the counterparties (parties this one has no
+        agreement with), overstating exposure. `documents` scopes the traversal (every edge on a path must belong)."""
+        from rag_wright.capabilities.graph_query import graph_query
+        return list(graph_query(entity_id, store=self._store, relationship_type=CONTRACTS_WITH,
+                                max_hops=max_hops, documents=documents).evidence)
+
+    def party_affiliates(self, entity_id: str, *, documents: Optional[list[str]] = None) -> list:
+        """The parties this one has an AFFILIATE_OF edge to (same corporate group). A SEPARATE traversal from
+        counterparties on purpose: a parent and its subsidiary are two legal persons whose obligations must not be
+        pooled, and the engine does not merge the entities -- the affiliate is its own node."""
+        from rag_wright.capabilities.graph_query import graph_query
+        return list(graph_query(entity_id, store=self._store, relationship_type=AFFILIATE_OF,
+                                documents=documents).evidence)
+
+    def contract_terms(self, contract_id: str) -> list:
+        """The typed clauses of one contract -- the terms that create the exposure. The FULL view, NOT
+        grounded-only: the high-precision view drops AMBIGUOUS properties, including the verbatim out-of-vocab
+        values ADR-0102 kept, so an exposure/citation surface must read what the graph holds, not less (a
+        precision filter is a per-caller UI choice, never baked into the facade)."""
+        from rag_wright.capabilities.contract_kg_serve import contract_clause_index
+        return list(contract_clause_index(self, contract_id))
+
+    # --- EP-REF-1b-iii: clause-type taxonomy (pure, from contracts/function.py) + span location assembly ---
+
+    @staticmethod
+    def canonical_clause_type(label: str) -> Optional[str]:
+        """Map a user's clause label onto the engine's clause-type taxonomy, or `None` if it maps to nothing.
+        Case-insensitive + alias-resolving ("Limitation of Liability" -> "Cap On Liability"), so a caller's label
+        (e.g. a correction) is VALIDATED rather than taken on trust -- an unmappable label returns None, not a
+        silent empty scope."""
+        from rag_wright.contracts.function import canonical_function
+        return canonical_function(label)
+
+    @staticmethod
+    def clause_type_vocabulary() -> tuple[str, ...]:
+        """Every clause type a sweep/correction UI can be scoped to (the engine's function-label vocabulary)."""
+        from rag_wright.contracts.function import FUNCTION_LABELS
+        return tuple(FUNCTION_LABELS)
+
+    def span_locations(self, contract_id: str) -> list[SpanLocation]:
+        """Every span of one document with where it sits in the original (pages/bbox/offsets) + the clause ids
+        extracted from it -- for a citation PREVIEW (a span-id-in-hand lookup, no query/model call). Each clause
+        carries the `span_id` it came from (the only bridge between the clause-id and span-id spaces); a clause
+        whose span is not in this document is dropped rather than inventing a location."""
+        spans = self._store.all_spans_by_contract(contract_id)
+        present = {r["span_id"] for r in spans}
+        clauses: dict[str, list[str]] = {}
+        for c in self.clauses_in_contract(contract_id):
+            sid = c.get("span_id") or ""
+            if sid in present:
+                clauses.setdefault(sid, []).append(str(c.get("clause_id") or ""))
+        return [
+            SpanLocation(
+                span_id=r["span_id"], clause_ids=clauses.get(r["span_id"], []),
+                pages=[int(p) for p in (r.get("pages") or [])], bbox=_decode_bbox(r.get("bbox")),
+                doc_start=r.get("doc_start"), doc_end=r.get("doc_end"), text=r.get("text") or "",
+            )
+            for r in spans
+        ]