rag-wright 0.1.0__py3-none-any.whl

rag_wright/spans/property_extractor.py

@@ -0,0 +1,365 @@
+"""T57b (FR-C.6, ADR-0025/0026): the targeted PROPERTY extractor.
+
+Given an operative span, its FUNCTION (from the T56 classifier), and its clause provenance, extract the
+queryable PROPERTIES the span states -> a `ClausePropertyRecord` (T57a). Structured output through the
+model-profile seam (DeepSeek V4 Pro by default; quality-sensitive extraction). The extractor is
+FUNCTION-AWARE: it only asks for the dimensions that apply to that clause type (`FUNCTION_DIMENSIONS`),
+which keeps the prompt tight, the output on-vocabulary, and out-of-scope dimensions from being invented.
+
+The LLM->contract mapping (`build_record`) is a pure, unit-tested function: it scope-filters to the
+function's dimensions, and coerces an out-of-vocabulary value to an AMBIGUOUS assertion (the schema's
+`other` escape) rather than dropping or crashing. At ingestion (T57c) this runs concurrently via
+`util.map_concurrent`.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ValidationError
+
+from rag_wright.contracts.function import canonical_function
+from rag_wright.contracts.identifiers import ChunkId
+from rag_wright.contracts.property import (
+    CLOSED_VOCAB,
+    FOLIO_CLAUSE_IRI,
+    ClausePropertyRecord,
+    PropertyAssertion,
+    PropertyDimension,
+)
+from rag_wright.contracts.provenance import ConfidenceTag, Provenance
+from rag_wright.models.profiles import ModelRole, model_for
+from rag_wright.models.seam import build_structured
+
+_D = PropertyDimension
+
+# Which property dimensions apply to which FUNCTION (the two-tier schema, operationalized). A clause type
+# not listed falls back to the cross-cutting pair; extraction stays focused on what the ACORD queries
+# actually filter that clause type on.
+FUNCTION_DIMENSIONS: dict[str, tuple[PropertyDimension, ...]] = {
+    "Cap On Liability": (_D.MUTUALITY, _D.FAVORABILITY, _D.CARVE_OUT, _D.CAP_BASIS, _D.CAP_QUANTUM, _D.PARTY_ASYMMETRY),
+    "Uncapped Liability": (_D.MUTUALITY, _D.FAVORABILITY, _D.CARVE_OUT, _D.PARTY_ASYMMETRY),
+    "Indirect/Consequential Damages Waiver": (_D.MUTUALITY, _D.FAVORABILITY, _D.CARVE_OUT, _D.DAMAGE_TYPE),
+    "Warranty Disclaimer": (_D.FAVORABILITY, _D.WARRANTY_SCOPE),
+    "Indemnification": (_D.MUTUALITY, _D.FAVORABILITY, _D.CLAIM_SCOPE, _D.COVERED_SUBJECT, _D.COVERED_PARTIES, _D.PROCEDURAL),
+    "Governing Law": (_D.JURISDICTION, _D.LAW_MULTIPLICITY, _D.DISPUTE_METHOD),
+    "No-Solicit Of Employees": (_D.NONSOLICIT_TARGET, _D.TEMPORAL_BOUND),
+    "No-Solicit Of Customers": (_D.NONSOLICIT_TARGET, _D.TEMPORAL_BOUND),
+    "Renewal Term": (_D.RENEWAL_MECHANISM, _D.NOTICE_PERIOD),
+    "Notice Period To Terminate Renewal": (_D.RENEWAL_MECHANISM, _D.NOTICE_PERIOD),
+    "IP Ownership Assignment": (_D.IP_OWNERSHIP, _D.COVERED_PARTIES),
+    "Joint IP Ownership": (_D.IP_OWNERSHIP, _D.COVERED_PARTIES),
+    "License Grant": (_D.COVERED_PARTIES,),
+    "Affiliate License-Licensor": (_D.COVERED_PARTIES,),
+    "Affiliate License-Licensee": (_D.COVERED_PARTIES,),
+    # CLS-F: the 8 corpus-sourced dims mapped to their functions (canonical 52-label taxonomy names)
+    "Dispute Resolution": (_D.DISPUTE_METHOD,),
+    "Confidentiality": (_D.CONFIDENTIALITY_EXCEPTION,),
+    "Royalties": (_D.ROYALTY_BASIS,),
+    "Security Interest": (_D.COLLATERAL_TYPE,),
+    "Condition Precedent": (_D.CONDITION_TYPE,),
+    "Force Majeure": (_D.FORCE_MAJEURE_EVENT,),
+    "Source Code Escrow": (_D.ESCROW_RELEASE_TRIGGER,),
+    "Rofr": (_D.RIGHT_OF_FIRST_TYPE,),
+    "Rofo": (_D.RIGHT_OF_FIRST_TYPE,),
+    "Rofn": (_D.RIGHT_OF_FIRST_TYPE,),
+}
+_DEFAULT_DIMENSIONS: tuple[PropertyDimension, ...] = (_D.MUTUALITY, _D.FAVORABILITY)
+
+
+def dimensions_for(function: str) -> tuple[PropertyDimension, ...]:
+    return FUNCTION_DIMENSIONS.get(function, _DEFAULT_DIMENSIONS)
+
+
+def scoped_dims(functions: tuple[str, ...]) -> Optional[set[PropertyDimension]]:
+    """CLS-D SOFT function-scoping: the UNION of applicable dims over the clause's (top-k) function soft-tags.
+    A classifier cannot say 'not present', so without scoping every dim fires on every span (over-emission on the
+    subjective dims the grounding gate can't prune). Scoping to the top-k functions' dims fixes that while staying
+    tolerant of the ~0.5 function accuracy (the union over top-k catches the right function even when top-1 is
+    wrong). An EMPTY `functions` (a genuinely untagged provision) returns None -> no scoping (run every dim)."""
+    if not functions:
+        return None
+    out: set[PropertyDimension] = set()
+    for f in functions:
+        out.update(dimensions_for(f))
+    return out
+
+
+# CLS-B/C rework (ADR-0066 candidate for ontology migration, like FUNCTION_DIMENSIONS): the FUNCTION-INDEPENDENT
+# Step-3a routing. The classifier lane fills every dim the registry covers. These 7 numeric/open dims are the ONLY
+# ones the LLM extracts -- a classifier cannot emit a number/place/duration -- and that is PERMANENT. The 8
+# corpus-starved closed-vocab dims (dispute_method, royalty_basis, condition_type, collateral_type,
+# force_majeure_event, confidentiality_exception, right_of_first_type, escrow_release_trigger) are NOT extracted
+# here until CLS-F sources data, after which they join the CLASSIFIER lane -- never the LLM.
+RESIDUAL_LLM_DIMS: tuple[PropertyDimension, ...] = (
+    _D.CAP_QUANTUM, _D.JURISDICTION, _D.TEMPORAL_BOUND, _D.NOTICE_PERIOD,
+    _D.AUDIT_FREQUENCY, _D.COMMITMENT_QUANTUM, _D.LD_TRIGGER,
+)
+# Classifier dims that do not clear the confidence bar (cap_basis numeric, renewal_mechanism subjective): served
+# locally like the rest, but emitted AMBIGUOUS so the grounding gate + query side treat them as low-confidence.
+# They flip to EXTRACTED if a better model/more data later clears the bar; they are NEVER routed to the LLM.
+ACCEPT_WEAK_DIMS: frozenset[PropertyDimension] = frozenset({_D.CAP_BASIS, _D.RENEWAL_MECHANISM})
+
+# The residual numeric/open dims are EXTRACTIVE (a number, amount, place, duration) -- not label selection -- so
+# they need a value-verbatim prompt, not the closed-vocab "one of {...}" or "lowercase_snake" phrasing.
+_RESIDUAL_DIM_HINTS: dict[PropertyDimension, str] = {
+    _D.CAP_QUANTUM: "the monetary amount or formula of a liability cap (e.g. '$1,000,000', '12 months of fees')",
+    _D.JURISDICTION: "the governing-law jurisdiction (e.g. 'Delaware', 'England and Wales')",
+    _D.TEMPORAL_BOUND: "the clause's time bound or duration (e.g. '3 years', 'the Term')",
+    _D.NOTICE_PERIOD: "the required notice period (e.g. '60 days', 'ninety (90) days')",
+    _D.AUDIT_FREQUENCY: "how often an audit is permitted (e.g. 'annually', 'twice per year')",
+    _D.COMMITMENT_QUANTUM: "a committed quantity or minimum (e.g. '10,000 units', '$500,000')",
+    _D.LD_TRIGGER: "the event that triggers liquidated damages (a short phrase)",
+}
+
+
+def residual_extraction_prompt(text: str) -> str:
+    """The residual LLM prompt: the 7 numeric/open dims only, extracted VERBATIM (not categorized). One call."""
+    lines = "\n".join(f"- {d.value}: {_RESIDUAL_DIM_HINTS[d]}" for d in RESIDUAL_LLM_DIMS)
+    return (
+        "Extract these NUMERIC/OPEN properties from the contract clause span, ONLY when the span explicitly states "
+        "them; omit any not present (do not guess). Report each value VERBATIM from the text -- a number, amount, "
+        "place, or duration, NOT a category label. Confidence EXTRACTED (stated) or INFERRED (clearly implied).\n\n"
+        f"Properties:\n{lines}\n\nSpan:\n{text[:2000]}"
+    )
+
+
+class ExtractedProperty(BaseModel):
+    """One property as the LLM emits it (pre-provenance): a dimension, a value, and a confidence."""
+
+    dimension: PropertyDimension
+    value: str
+    confidence: ConfidenceTag
+
+
+class PropertyExtraction(BaseModel):
+    """The LLM's structured output for one span: the properties it states (empty if none)."""
+
+    properties: list[ExtractedProperty] = []
+
+
+def extraction_prompt(function: str, dimensions: tuple[PropertyDimension, ...], text: str) -> str:
+    """The extraction prompt: only the dimensions that apply to this function, with their vocabularies."""
+    lines = []
+    for d in dimensions:
+        vocab = CLOSED_VOCAB.get(d)
+        if vocab:
+            lines.append(f"- {d.value}: one or more of {sorted(vocab)}; a genuinely novel value must be AMBIGUOUS")
+        else:
+            lines.append(f"- {d.value}: a short lowercase_snake value (open-valued)")
+    dims = "\n".join(lines)
+    return (
+        f"You extract queryable PROPERTIES from a '{function}' contract clause span for a legal search index.\n"
+        "Report ONLY properties the span actually states; omit any dimension the span does not address "
+        "(do not guess). Confidence: EXTRACTED (stated), INFERRED (clearly implied), AMBIGUOUS (a novel "
+        "value outside the list, or competing readings). Multi-valued dimensions (e.g. carve_out) may have "
+        "several entries.\n\n"
+        f"Dimensions for a '{function}' clause:\n{dims}\n\n"
+        f"Span:\n{text[:2000]}"
+    )
+
+
+def build_record(
+    *, chunk_id: ChunkId, function: str, span_id: str, extraction: PropertyExtraction
+) -> ClausePropertyRecord:
+    """Map an LLM `PropertyExtraction` to a validated `ClausePropertyRecord` (pure; no model call).
+
+    Scope-filters to the function's dimensions (drops any invented out-of-scope dimension), and coerces an
+    out-of-vocabulary value to an AMBIGUOUS assertion (the schema's `other` escape) instead of dropping it.
+    """
+    function = canonical_function(function) or function  # normalize classifier casing (e.g. 'Ip' -> 'IP')
+    prov = Provenance.of(chunk_id)
+    applicable = set(dimensions_for(function))
+    assertions: list[PropertyAssertion] = []
+    for p in extraction.properties:
+        if p.dimension not in applicable:
+            continue  # function-aware: ignore a dimension that does not belong to this clause type
+        try:
+            assertions.append(
+                PropertyAssertion(
+                    provenance=prov, confidence=p.confidence, dimension=p.dimension, value=p.value, span_id=span_id
+                )
+            )
+        except ValidationError:
+            # out-of-vocabulary value with a non-AMBIGUOUS confidence -> retain it as the AMBIGUOUS escape
+            try:
+                assertions.append(
+                    PropertyAssertion(
+                        provenance=prov, confidence=ConfidenceTag.AMBIGUOUS, dimension=p.dimension,
+                        value=p.value, span_id=span_id,
+                    )
+                )
+            except ValidationError:
+                continue  # empty value or otherwise unsalvageable -> drop
+    return ClausePropertyRecord(
+        clause_id=str(chunk_id), function=function, folio_iri=FOLIO_CLAUSE_IRI.get(function, ""),
+        assertions=assertions,
+    )
+
+
+@runtime_checkable
+class PropertyExtractor(Protocol):
+    """Span -> `ClausePropertyRecord`. The seam a test stubs and T57c drives via `map_concurrent`."""
+
+    def __call__(self, *, chunk_id: ChunkId, function: str, text: str, span_id: str) -> ClausePropertyRecord: ...
+
+
+class SeamPropertyExtractor:
+    """The real extractor: structured output through the model-profile seam on STRUCTURED_REASONING
+    (DeepSeek V4 Pro by default). Retries a bare `None` (a transient miss `with_structured_output`
+    returns), returning an empty record only if extraction persistently fails (the span keeps its
+    function; it simply carries no properties)."""
+
+    def __init__(self, model_id: Optional[str] = None, *, runnable=None, retries: int = 3) -> None:
+        self._runnable = runnable or build_structured(
+            model_id or model_for(ModelRole.STRUCTURED_REASONING), PropertyExtraction
+        )
+        self._retries = retries
+
+    def __call__(self, *, chunk_id: ChunkId, function: str, text: str, span_id: str = "") -> ClausePropertyRecord:
+        prompt = extraction_prompt(function, dimensions_for(function), text)
+        extraction: Optional[PropertyExtraction] = None
+        for _ in range(self._retries):
+            try:
+                extraction = self._runnable.invoke(prompt)
+            except Exception:  # noqa: BLE001 - transient provider/parse error; retry
+                continue
+            if extraction is not None:
+                break
+        return build_record(
+            chunk_id=chunk_id, function=function, span_id=span_id,
+            extraction=extraction or PropertyExtraction(),
+        )
+
+
+class HybridPropertyExtractor:
+    """CLS-B/C (FR-C.6/FR-I.4): the FUNCTION-INDEPENDENT Step-3a property extractor. This is THE extractor for
+    these dimensions -- not a toggle over an LLM fallback (ADR: the classifier lane is the decided path).
+
+    Two lanes, function-independent (the clause function is a soft tag on the record, never a gate):
+      * CLASSIFIER lane -- every dim the registry covers is answered by its trained `DimClassifier` (top-k soft
+        tags: rank-0 EXTRACTED, lower ranks INFERRED). `ACCEPT_WEAK_DIMS` are emitted AMBIGUOUS (low-confidence).
+      * RESIDUAL LLM lane -- ONE consolidated call for `RESIDUAL_LLM_DIMS` ONLY (the 7 numeric/open dims a
+        classifier cannot emit). The LLM is NEVER asked for a classifier dim, and any starved/other dim it
+        volunteers is filtered out.
+    The 8 corpus-starved dims are not extracted here (they join the classifier lane after CLS-F). Same
+    `PropertyExtractor` Protocol, so the ADR-0028 grounding + ADR-0040 symbolic gates downstream apply unchanged.
+    Classifiers honor the device-agnostic serving seam (GPU-if-available-else-CPU); the LLM stays on the seam."""
+
+    def __init__(self, registry=None, *, runnable=None, model_id: Optional[str] = None, retries: int = 3,
+                 classifier_fn=None) -> None:
+        self._registry = registry
+        self._runnable = runnable or build_structured(
+            model_id or model_for(ModelRole.STRUCTURED_REASONING), PropertyExtraction)
+        self._retries = retries
+        # EP-RT-7: when set, the classifier LANE is obtained through the `clause_property_classification` capability
+        # (the single production path) instead of this instance's local fleet -- `(text, functions) -> [{dimension,
+        # value, confidence}]`. The capability impl (`classify_properties`) itself always uses the local fleet, so
+        # there is no recursion. `None` -> this instance owns the fleet (the capability adapter's own extractor).
+        self._classifier_fn = classifier_fn
+
+    def _classifier_lane(self, prov: Provenance, text: str, span_id: str,
+                         functions: tuple[str, ...]) -> list[PropertyAssertion]:
+        """The classifier-lane assertions: via the capability (`_classifier_fn`) when injected, else the local fleet."""
+        if self._classifier_fn is None:
+            return self._classifier_assertions(prov, text, span_id, scoped_dims(functions))
+        out: list[PropertyAssertion] = []
+        for tag in self._classifier_fn(text, tuple(functions)):
+            try:
+                out.append(PropertyAssertion(
+                    provenance=prov, confidence=ConfidenceTag(tag["confidence"]),
+                    dimension=PropertyDimension(tag["dimension"]), value=tag["value"], span_id=span_id))
+            except (ValidationError, ValueError):
+                continue  # a value/dim/confidence the contract rejects -> drop (same as the local lane)
+        return out
+
+    def _classifier_assertions(self, prov: Provenance, text: str, span_id: str,
+                               applicable: Optional[set[PropertyDimension]]) -> list[PropertyAssertion]:
+        """Classifier lane: soft-scoped to the function's applicable dims (`applicable=None` -> every covered dim),
+        top-k soft tags (accept-weak -> AMBIGUOUS)."""
+        out: list[PropertyAssertion] = []
+        for d in self._registry.dims:
+            if applicable is not None and d not in applicable:
+                continue  # out of the clause function's scope -> don't emit (over-emission fix)
+            clf = self._registry.get(d)
+            if clf is None:
+                continue
+            for rank, (value, _prob) in enumerate(clf.classify(text)):
+                if str(value).lower() == "none":
+                    continue  # ABSTAIN sentinel (ADR-0116): the classifier says "dim not present" -> emit nothing
+                if d in ACCEPT_WEAK_DIMS:
+                    conf = ConfidenceTag.AMBIGUOUS
+                else:
+                    conf = ConfidenceTag.EXTRACTED if rank == 0 else ConfidenceTag.INFERRED
+                try:
+                    out.append(PropertyAssertion(provenance=prov, confidence=conf, dimension=d,
+                                                 value=value, span_id=span_id))
+                except ValidationError:
+                    continue  # a value outside the dim vocab (shouldn't happen from a trained head) -> drop
+        return out
+
+    def classify_properties(self, text: str, *, functions: tuple[str, ...] = ()) -> list[dict]:
+        """EP-RT-1 (ADR-0117): the classifier LANE as a standalone `model`-kind capability -- closed-vocab property
+        assertions for one provision, soft-scoped to the clause `functions` (no LLM, no gates). Returns
+        `[{dimension, value, confidence}]` (primary-first within each dim). `functions=()` -> every covered dim."""
+        prov = Provenance.of(ChunkId(source_doc_id="classify", chunk_index=0, content_hash="0" * 64))
+        asserts = self._classifier_assertions(prov, text, "", scoped_dims(functions))
+        return [{"dimension": a.dimension.value, "value": a.value, "confidence": a.confidence.value}
+                for a in asserts]
+
+    def _residual_assertions(self, prov: Provenance, extraction: Optional[PropertyExtraction],
+                             span_id: str) -> list[PropertyAssertion]:
+        """Keep ONLY the 7 residual dims from the LLM's answer -- never a classifier dim or a starved dim."""
+        out: list[PropertyAssertion] = []
+        residual = set(RESIDUAL_LLM_DIMS)
+        for p in (extraction.properties if extraction else []):
+            if p.dimension not in residual:
+                continue
+            try:
+                out.append(PropertyAssertion(provenance=prov, confidence=p.confidence, dimension=p.dimension,
+                                             value=p.value, span_id=span_id))
+            except ValidationError:
+                continue
+        return out
+
+    def _record(self, chunk_id: ChunkId, function: str, assertions: list[PropertyAssertion],
+                span_id: str = "") -> ClausePropertyRecord:
+        # Carry the record-level operative-span anchor (ADR-0025) EVEN when property-less: Leg A rehydrates a
+        # property-less clause from its own `span_id` (else it has no citable text and the serve step abstains).
+        return ClausePropertyRecord(clause_id=str(chunk_id), function=function,
+                                    folio_iri=FOLIO_CLAUSE_IRI.get(function, ""),
+                                    span_id=span_id, assertions=assertions)
+
+    def __call__(self, *, chunk_id: ChunkId, function: str, text: str, span_id: str = "",
+                 functions: tuple[str, ...] = ()) -> ClausePropertyRecord:
+        function = canonical_function(function) or function
+        prov = Provenance.of(chunk_id)
+        assertions = self._classifier_lane(prov, text, span_id, functions)
+        extraction: Optional[PropertyExtraction] = None  # ONE residual call (the 7 numeric dims), always fires
+        for _ in range(self._retries):
+            try:
+                extraction = self._runnable.invoke(residual_extraction_prompt(text))
+            except Exception:  # noqa: BLE001 - transient provider/parse error; retry
+                continue
+            if extraction is not None:
+                break
+        assertions += self._residual_assertions(prov, extraction, span_id)
+        return self._record(chunk_id, function, assertions, span_id)
+
+    async def aextract(self, *, chunk_id: ChunkId, function: str, text: str,
+                       span_id: str = "", functions: tuple[str, ...] = ()) -> ClausePropertyRecord:
+        """ASYNC-B2b (ADR-0057): async twin -- classifiers run in-process (ms), the ONE residual call is awaited.
+        `functions` = the clause's top-k function soft-tags for soft-scoping (empty -> every covered dim runs)."""
+        function = canonical_function(function) or function
+        prov = Provenance.of(chunk_id)
+        assertions = self._classifier_lane(prov, text, span_id, functions)
+        extraction: Optional[PropertyExtraction] = None
+        for _ in range(self._retries):
+            try:
+                extraction = await self._runnable.ainvoke(residual_extraction_prompt(text))
+            except Exception:  # noqa: BLE001 - transient provider/parse error; retry
+                continue
+            if extraction is not None:
+                break
+        assertions += self._residual_assertions(prov, extraction, span_id)
+        return self._record(chunk_id, function, assertions, span_id)

rag_wright/spans/property_grounding.py

@@ -0,0 +1,182 @@
+"""T61 (FR-C.6, ADR-0028): the deterministic property-grounding judge.
+
+Most of the property vocabulary maps to legal TERMS OF ART that must physically appear in the clause. This
+judge checks, locally and deterministically (no model, no network), whether an `EXTRACTED` value on a
+lexically-anchored dimension actually has its surface cue in the text. If not, the value is UNGROUNDED --
+almost certainly hallucinated (e.g. Flash emitting `carve_out=fraud` on a clause with no "fraud").
+
+Two uses (double duty):
+1. **Escalation trigger** (T58b cascade): run the fast model (Flash) for the bulk, and re-extract only the
+   clauses the judge flags with the precise model (Pro). Concentrates the throttled Pro calls on the
+   deterministically-suspect cases; a false flag costs one extra Pro call, never correctness.
+2. **Permanent quality gate** on the final graph: `reground` downgrades an ungrounded `EXTRACTED` assertion
+   to `AMBIGUOUS` (kept, but marked unverified so soft-boost down-weights it) regardless of which model
+   produced it -- so the shared property-value nodes stay clean.
+
+Coverage: lexically-anchored closed values (cue check), plus open-valued scalars (token overlap,
+GROUNDING-OPENVALUED). LIMITATION: the closed SEMANTIC dimensions (mutuality, favorability, party_asymmetry,
+cap_basis, the consent regimes) carry no surface form and are NOT checkable here; their errors pass through
+unflagged and are the target of the Layer-3 semantic judge (ADR-0040, JUDGE-SEMANTIC).
+"""
+
+from __future__ import annotations
+
+import re
+
+from rag_wright.contracts.property import (
+    CLOSED_VOCAB,
+    ClausePropertyRecord,
+    PropertyAssertion,
+    PropertyDimension,
+)
+from rag_wright.contracts.provenance import ConfidenceTag
+
+_D = PropertyDimension
+
+# Open-valued dimensions carry a free-text scalar (jurisdiction, cap_quantum, temporal_bound, notice_period,
+# audit_frequency, commitment_quantum, ld_trigger) rather than a closed vocabulary. GROUNDING-OPENVALUED
+# (ADR-0040): unlike a closed SEMANTIC dim (mutuality/etc., which stays Layer-3's job), an open value SHOULD
+# have a textual anchor -- an EXTRACTED `jurisdiction=Delaware` on a clause that never mentions Delaware is a
+# fabrication. Checked by TOKEN OVERLAP (lenient: grounded if ANY significant token of the value appears), so
+# normalized forms survive (`12_months` grounded by "months" in "twelve (12) months") while pure inventions
+# with no overlapping token are flagged.
+OPEN_VALUED_DIMENSIONS: frozenset[PropertyDimension] = frozenset(
+    d for d in PropertyDimension if d not in CLOSED_VOCAB
+)
+
+# dimension -> value -> surface cues (lowercased substrings). A value ABSENT from this map is NOT
+# lexically anchored (semantic/open-valued) and is treated as grounded (the judge cannot disprove it).
+GROUNDING_CUES: dict[PropertyDimension, dict[str, tuple[str, ...]]] = {
+    _D.CARVE_OUT: {
+        "indemnification": ("indemnif", "hold harmless"),
+        "confidentiality": ("confidential",),
+        "third_party_ip_infringement": ("infring",),
+        "fraud": ("fraud",),
+        "gross_negligence": ("gross negligence",),
+        "willful_misconduct": ("willful misconduct", "wilful misconduct"),
+        "bodily_injury": ("bodily injury", "personal injury", "death"),
+        "applicable_law": ("law",),
+    },
+    _D.COVERED_SUBJECT: {
+        "ip_infringement": ("infring",),
+        "trademark": ("trademark",),
+        "copyright": ("copyright",),
+        "violation_of_law": ("violation of law", "breach of law", "applicable law", "law"),
+        "fraud": ("fraud",),
+        "gross_negligence": ("gross negligence",),
+    },
+    _D.DAMAGE_TYPE: {
+        "indirect": ("indirect",),
+        "consequential": ("consequential",),
+        "incidental": ("incidental",),
+        "punitive": ("punitive", "exemplary"),
+        "special": ("special",),
+    },
+    _D.WARRANTY_SCOPE: {
+        "implied": ("implied", "merchantability", "fitness for"),
+        "express": ("express",),
+        "as_is": ("as is", "as-is", "with all faults"),
+        "non_reliance": ("non-reliance", "nonreliance", "no reliance", "not relied"),
+    },
+    _D.PROCEDURAL: {
+        "duty_to_defend": ("defend", "defense", "defence"),
+        "control_of_defense": ("control of the defense", "control of the defence", "control of defense",
+                               "sole control", "conduct of the defense", "conduct the defense"),
+    },
+    _D.COVERED_PARTIES: {
+        "affiliates": ("affiliate",),
+        "licensor_affiliates": ("affiliate",),
+        "licensee_affiliates": ("affiliate",),
+    },
+    _D.CLAIM_SCOPE: {
+        "third_party": ("third party", "third-party"),
+    },
+    # tier 3 -- CUAD-family extensions (KG-4). Only the strongly lexically-anchored values; the semantic
+    # ones (consent regimes, mfn_scope, termination_right) are not checkable and pass through.
+    _D.EXCLUSIVITY_TYPE: {
+        "exclusive": ("exclusive",),
+        "sole": ("sole",),
+        "non_exclusive": ("non-exclusive", "nonexclusive", "non exclusive"),
+    },
+    _D.RIGHT_OF_FIRST_TYPE: {
+        "rofr": ("first refusal",),
+        "rofo": ("first offer",),
+        "rofn": ("first negotiation",),
+    },
+    _D.ESCROW_RELEASE_TRIGGER: {
+        "bankruptcy": ("bankrupt", "insolven"),
+        "breach": ("breach", "default"),
+        "discontinuance": ("discontinu", "cease", "no longer"),
+    },
+    _D.RESTRICTION_SCOPE: {
+        "geographic": ("geographic", "territor", "worldwide", "region"),
+        "activity": ("activit", "business", "compet"),
+    },
+}
+
+
+def is_lexically_anchored(dimension: PropertyDimension, value: str) -> bool:
+    """Whether this (dimension, value) has a defined surface cue the judge can check at all."""
+    return value in GROUNDING_CUES.get(dimension, {})
+
+
+def _open_value_grounded(value: str, text: str) -> bool:
+    """An open-valued scalar is grounded if ANY significant token of its (normalized) value appears in the
+    text -- lenient so normalized forms survive, strict enough to flag a value with no textual anchor at all."""
+    low = text.lower()
+    tokens = [t for t in re.split(r"[^a-z0-9]+", value.lower()) if len(t) >= 2]
+    if not tokens:  # nothing checkable (e.g. a single-char value) -> cannot disprove
+        return True
+    return any(t in low for t in tokens)
+
+
+def is_grounded(dimension: PropertyDimension, value: str, text: str) -> bool:
+    """True if the value is supported by the text. Lexically-anchored (closed-vocab) values require their cue
+    to appear; open-valued scalars require a token overlap (GROUNDING-OPENVALUED); closed SEMANTIC values
+    (mutuality/etc.) carry no surface form and are treated as grounded -- the judge cannot disprove them."""
+    cues = GROUNDING_CUES.get(dimension, {}).get(value)
+    if cues is not None:
+        low = text.lower()
+        return any(cue in low for cue in cues)
+    if dimension in OPEN_VALUED_DIMENSIONS:
+        return _open_value_grounded(value, text)
+    return True
+
+
+def ungrounded_assertions(record: ClausePropertyRecord, text: str) -> list[PropertyAssertion]:
+    """The record's `EXTRACTED` assertions on a lexically-anchored dimension whose cue is ABSENT from the
+    text -- the likely hallucinations. `INFERRED`/`AMBIGUOUS` are not flagged (they do not claim to be
+    stated verbatim)."""
+    return [
+        a for a in record.assertions
+        if a.confidence == ConfidenceTag.EXTRACTED and not is_grounded(a.dimension, a.value, text)
+    ]
+
+
+def needs_escalation(record: ClausePropertyRecord, text: str) -> bool:
+    """Escalation trigger: True if any EXTRACTED value is ungrounded -> re-extract this clause with the
+    precise model (the T58b Flash->Pro cascade)."""
+    return bool(ungrounded_assertions(record, text))
+
+
+def reground(record: ClausePropertyRecord, text: str) -> ClausePropertyRecord:
+    """Quality gate (double duty): downgrade every ungrounded `EXTRACTED` assertion to `AMBIGUOUS` (kept but
+    flagged unverified, so soft-boost down-weights it) -- a model-agnostic gate on the final graph."""
+    flagged = {id(a) for a in ungrounded_assertions(record, text)}
+    if not flagged:
+        return record
+    new = [
+        a.model_copy(update={"confidence": ConfidenceTag.AMBIGUOUS}) if id(a) in flagged else a
+        for a in record.assertions
+    ]
+    return record.model_copy(update={"assertions": new})
+
+
+def register_extraction_grounding_judge(registry) -> None:
+    """CAP-REG-2: register `extraction_grounding_judge` (function; ADR-0028 lexical grounding gate)."""
+    registry.register(
+        "extraction_grounding_judge",
+        contract=ClausePropertyRecord,
+        kind="function",
+        display_name="Extraction grounding judge",
+    )

rag_wright/spans/reclassify.py

@@ -0,0 +1,77 @@
+"""INGEST-LLM-CLASSIFIER (ADR-0048) Phase A: the non-destructive reclassify logic.
+
+Pure, testable core (no store, no LLM): given a chunk's spans (full context) + the existing Clause labels + a
+batched classifier, compute the NEW primary + multi-label per existing clause, and detect PRIMARY FLIPS (the only
+thing that triggers Phase B re-extraction). The store driver (`scripts/reclassify_kg.py`) reads/writes the KG and
+runs this concurrently with X/N progress."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Any
+
+from rag_wright.contracts.function import NO_FUNCTION, FunctionScore, primary_function
+
+
+@dataclass(frozen=True)
+class ClauseReclass:
+    """The reclassification of one existing Clause: its id/span, old primary, and the new scores + primary."""
+
+    clause_id: str
+    span_id: str
+    old_function: str
+    new_scores: list[FunctionScore]
+    new_primary: str  # primary_function(new_scores) or NO_FUNCTION
+
+    @property
+    def primary_flipped(self) -> bool:
+        return self.old_function != self.new_primary
+
+
+def reclassify_chunk(
+    chunk_text: str,
+    ordered_spans: list[tuple[str, str]],       # [(span_id, span_text)] in span order (full chunk = context)
+    existing_by_span: dict[str, tuple[str, str]],  # span_id -> (clause_id, old_function) for existing Clauses
+    classify_fn: Any,
+) -> list[ClauseReclass]:
+    """Batched-classify the chunk's spans (one call, chunk as context), then map the result back to the chunk's
+    EXISTING Clause nodes only (non-destructive: spans without an existing Clause are left to Phase B)."""
+    if not ordered_spans:
+        return []
+    scores_per_span = classify_fn.classify_spans(chunk_text, [t for _, t in ordered_spans])
+    out: list[ClauseReclass] = []
+    for (span_id, _), scores in zip(ordered_spans, scores_per_span):
+        if span_id in existing_by_span:
+            clause_id, old_fn = existing_by_span[span_id]
+            out.append(ClauseReclass(
+                clause_id=clause_id, span_id=span_id, old_function=old_fn,
+                new_scores=list(scores), new_primary=primary_function(scores) or NO_FUNCTION))
+    return out
+
+
+@dataclass
+class ReclassDelta:
+    """The aggregate reclassification delta (for the dry-run report + gating Phase B)."""
+
+    total: int = 0
+    unchanged: int = 0
+    flipped: int = 0                       # primary changed -> Phase B re-extraction candidates
+    to_none: int = 0                       # primary flipped to NO_FUNCTION (clause should be retired)
+    from_none: int = 0                     # was NONE-ish, now a real function (should not happen for EXISTING clauses)
+    transitions: Counter = field(default_factory=Counter)  # (old -> new) -> count, flips only
+
+    def add(self, rc: ClauseReclass) -> None:
+        self.total += 1
+        if rc.primary_flipped:
+            self.flipped += 1
+            self.transitions[(rc.old_function, rc.new_primary)] += 1
+            if rc.new_primary == NO_FUNCTION:
+                self.to_none += 1
+            if rc.old_function == NO_FUNCTION:
+                self.from_none += 1
+        else:
+            self.unchanged += 1
+
+    def top_transitions(self, n: int = 15) -> list[tuple[tuple[str, str], int]]:
+        return self.transitions.most_common(n)