rag-wright 0.1.0__py3-none-any.whl

rag_wright/contracts/jurisdiction.py

@@ -0,0 +1,96 @@
+"""KG-5a: deterministic jurisdiction canonicalization for the contract KG.
+
+The typed KG stores `jurisdiction` as the extracted surface string (`England`, `England and Wales`,
+`English law`, `State of New York`, `State of New York, USA`, ...). Retrieval matching (Leg B) fails on
+those variants because the query side and the clause side don't share a normalized value. This maps a
+surface form to a **canonical jurisdiction slug** (or None for non-jurisdictions), deterministically -- no
+LLM, no network. Applied additively: the value node keeps its surface `value` and gains a `canonical_value`;
+the query constraint is canonicalized the same way, so both meet on the canonical.
+
+Method: strip governance boilerplate prefixes/suffixes (`State of`, `Commonwealth of`, `, USA`, ` law`,
+` courts`) and normalize, then look up a gazetteer (50 US states + the countries seen in the corpus, each
+with aliases). Non-jurisdictions (`Applicable Law`, `Not specified`, `worldwide`, redactions, compound
+`Illinois or New York`) resolve to None (left as their surface value, unmatched).
+"""
+
+from __future__ import annotations
+
+import re
+
+# canonical slug -> alias surface forms (already normalized: lowercase, no prefixes/suffixes)
+_US_STATES = [
+    "alabama", "alaska", "arizona", "arkansas", "california", "colorado", "connecticut", "delaware",
+    "florida", "georgia", "hawaii", "idaho", "illinois", "indiana", "iowa", "kansas", "kentucky",
+    "louisiana", "maine", "maryland", "massachusetts", "michigan", "minnesota", "mississippi", "missouri",
+    "montana", "nebraska", "nevada", "new hampshire", "new jersey", "new mexico", "new york",
+    "north carolina", "north dakota", "ohio", "oklahoma", "oregon", "pennsylvania", "rhode island",
+    "south carolina", "south dakota", "tennessee", "texas", "utah", "vermont", "virginia", "washington",
+    "west virginia", "wisconsin", "wyoming",
+]
+
+# country / non-US aliases -> canonical slug (normalized)
+_COUNTRY_ALIASES: dict[str, str] = {
+    "england": "england", "english": "england", "england and wales": "england",
+    "united kingdom": "england", "uk": "england", "great britain": "england", "britain": "england",
+    "scotland": "scotland", "wales": "wales", "northern ireland": "northern_ireland",
+    "china": "china", "prc": "china", "people's republic of china": "china",
+    "united states": "united_states", "united states of america": "united_states", "usa": "united_states",
+    "u.s.a.": "united_states", "us": "united_states",
+    "canada": "canada", "british columbia": "british_columbia", "ontario": "ontario",
+    "belgium": "belgium", "germany": "germany", "france": "france", "japan": "japan", "spain": "spain",
+    "italy": "italy", "italian": "italy", "south africa": "south_africa", "israel": "israel",
+    "taiwan": "taiwan", "netherlands": "netherlands", "switzerland": "switzerland", "australia": "australia",
+    "singapore": "singapore", "hong kong": "hong_kong", "ireland": "ireland",
+}
+
+# build the normalized-alias -> canonical index
+_INDEX: dict[str, str] = {s: s.replace(" ", "_") for s in _US_STATES}
+_INDEX.update(_COUNTRY_ALIASES)
+
+# surfaces that are NOT a jurisdiction (governance boilerplate / nulls / references / vague) -> None
+_JUNK = re.compile(
+    r"applicable\s+law|governing\s+law|not\s+specified|not\s+explicitly|unspecified|none\s+specified"
+    r"|^none$|^other$|best's|exhibit|section\b|bankruptcy\s+code|any\s+jurisdiction|jurisdiction\s+governing"
+    r"|franchised\s+restaurant|^territory$|^union$|^worldwide$|\*|\[|last\s+sentence|internal\s+laws",
+    re.IGNORECASE,
+)
+_PREFIXES = ("the state of ", "state of ", "the commonwealth of ", "commonwealth of ",
+             "the province of ", "province of ", "the ")
+_SUFFIXES = (", u.s.a.", ", usa", ", united states of america", ", united states", " (u.s.a.)",
+             " (usa)", " and its territories")
+
+
+def _normalize(surface: str) -> str:
+    s = " ".join(surface.lower().strip().split())
+    for p in _PREFIXES:
+        if s.startswith(p):
+            s = s[len(p):]
+            break
+    for suf in _SUFFIXES:
+        s = s.replace(suf, "")
+    s = re.sub(r"\s+(law|laws|courts|court|state)$", "", s).strip()
+    return s
+
+
+# longest alias first, for the containment fallback (word-bounded)
+_ALIAS_ITEMS = sorted(_INDEX.items(), key=lambda kv: -len(kv[0]))
+
+
+def _containment(norm: str) -> str | None:
+    """Fallback for surfaces the exact lookup misses: scan for known jurisdiction aliases as whole words.
+    Resolve only if it names exactly one place -- treating a US state named alongside 'the United States'
+    (federal) as that state ('New York and ... the United States of America' -> new_york). Genuinely
+    ambiguous compounds ('Illinois or New York') stay None."""
+    found = {canon for alias, canon in _ALIAS_ITEMS if re.search(rf"\b{re.escape(alias)}\b", norm)}
+    if len(found) > 1:
+        found.discard("united_states")  # a state + US federal -> the state
+    return next(iter(found)) if len(found) == 1 else None
+
+
+def canonicalize_jurisdiction(surface: str) -> str | None:
+    """Map a jurisdiction surface form to a canonical slug (e.g. 'england', 'new_york'), or None if it is
+    not a resolvable single jurisdiction (boilerplate, null, reference, ambiguous compound). Deterministic."""
+    if not surface or _JUNK.search(surface):
+        return None
+    norm = _normalize(surface)
+    return _INDEX.get(norm) or _containment(norm)

rag_wright/contracts/ontology.py

@@ -0,0 +1,142 @@
+"""The ontology and extraction-target models (FR-C.8, §16.2, ADR-0002).
+
+The ontology is the closed vocabulary the knowledge graph conforms to. T4 owns the ontology
+*structure* (the type enums and the fact models that reference them); T8 owns the ontology
+*membership* (deriving the concrete types from the Data Catalog, FR-C.8). Both are real: deferring
+membership entirely would leave the downstream contract and extraction work with nothing to bind.
+
+- `ClauseCategory`: the 41 CUAD clause categories. Membership here is authoritative (ADR-0002). The
+  values are the canonical CUAD label names; T8 reconciles them against the exact label strings in
+  the CUAD data once the corpus is acquired (T7).
+- Entity/relationship taxonomy (DD-5, ADR-0066/0117): the party/entity node types and the entity-to-entity
+  relationship (edge) types are NO LONGER a hardcoded engine enum. `EntityNode.entity_type` and
+  `RelationshipFact.relationship_type` are OPAQUE domain strings the caller names; the closed value sets are
+  DOMAIN knowledge declared by the pack (the reference contract pack's are in `ontology/contract_taxonomy.py`).
+  A new domain supplies its own without reopening these contracts.
+
+The extraction-target models (`EntityNode`, `ClauseFact`, `RelationshipFact`) are what graph
+extraction (T5) produces and graph storage (T24) writes. Their type fields are the ontology enums,
+so a fact whose type is not in the ontology is rejected at construction (RAC-4). The fact models
+extend `GraphFact` (T2), so they carry provenance and a confidence tag; `EntityNode` is a canonical
+node (identifier, name, type, no facts), per the thin entity skeleton in SPEC.md section 8.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from rag_wright.contracts.identifiers import EntityId
+from rag_wright.contracts.provenance import GraphFact
+
+
+class ClauseCategory(str, Enum):
+    """The 41 CUAD clause categories (ADR-0002). Authoritative; T8 reconciles exact label strings."""
+
+    DOCUMENT_NAME = "Document Name"
+    PARTIES = "Parties"
+    AGREEMENT_DATE = "Agreement Date"
+    EFFECTIVE_DATE = "Effective Date"
+    EXPIRATION_DATE = "Expiration Date"
+    RENEWAL_TERM = "Renewal Term"
+    NOTICE_PERIOD_TO_TERMINATE_RENEWAL = "Notice Period To Terminate Renewal"
+    GOVERNING_LAW = "Governing Law"
+    MOST_FAVORED_NATION = "Most Favored Nation"
+    NON_COMPETE = "Non-Compete"
+    EXCLUSIVITY = "Exclusivity"
+    NO_SOLICIT_OF_CUSTOMERS = "No-Solicit Of Customers"
+    COMPETITIVE_RESTRICTION_EXCEPTION = "Competitive Restriction Exception"
+    NO_SOLICIT_OF_EMPLOYEES = "No-Solicit Of Employees"
+    NON_DISPARAGEMENT = "Non-Disparagement"
+    TERMINATION_FOR_CONVENIENCE = "Termination For Convenience"
+    ROFR_ROFO_ROFN = "Rofr/Rofo/Rofn"
+    CHANGE_OF_CONTROL = "Change Of Control"
+    ANTI_ASSIGNMENT = "Anti-Assignment"
+    REVENUE_PROFIT_SHARING = "Revenue/Profit Sharing"
+    PRICE_RESTRICTIONS = "Price Restrictions"
+    MINIMUM_COMMITMENT = "Minimum Commitment"
+    VOLUME_RESTRICTION = "Volume Restriction"
+    IP_OWNERSHIP_ASSIGNMENT = "IP Ownership Assignment"
+    JOINT_IP_OWNERSHIP = "Joint IP Ownership"
+    LICENSE_GRANT = "License Grant"
+    NON_TRANSFERABLE_LICENSE = "Non-Transferable License"
+    AFFILIATE_LICENSE_LICENSOR = "Affiliate License-Licensor"
+    AFFILIATE_LICENSE_LICENSEE = "Affiliate License-Licensee"
+    UNLIMITED_ALL_YOU_CAN_EAT_LICENSE = "Unlimited/All-You-Can-Eat-License"
+    IRREVOCABLE_OR_PERPETUAL_LICENSE = "Irrevocable Or Perpetual License"
+    SOURCE_CODE_ESCROW = "Source Code Escrow"
+    POST_TERMINATION_SERVICES = "Post-Termination Services"
+    AUDIT_RIGHTS = "Audit Rights"
+    UNCAPPED_LIABILITY = "Uncapped Liability"
+    CAP_ON_LIABILITY = "Cap On Liability"
+    LIQUIDATED_DAMAGES = "Liquidated Damages"
+    WARRANTY_DURATION = "Warranty Duration"
+    INSURANCE = "Insurance"
+    COVENANT_NOT_TO_SUE = "Covenant Not To Sue"
+    THIRD_PARTY_BENEFICIARY = "Third Party Beneficiary"
+
+
+class EntityNode(BaseModel):
+    """A canonical entity node in the graph skeleton (SPEC.md section 8): identifier, name, type.
+
+    No facts and no confidence: entity nodes are canonical (resolved against the registry, FR-C.7), not
+    extracted facts. DD-5 (ADR-0066/0117): `entity_type` is an OPAQUE string the domain names -- the engine
+    does not constrain the taxonomy. The reference contract pack's value set lives in
+    `ontology/contract_taxonomy.py` (e.g. "Organization"/"Person"); a new domain names its own.
+    """
+
+    entity_id: EntityId
+    entity_type: str
+    name: str
+
+
+class ClauseFact(GraphFact):
+    """A clause occurrence extracted from a chunk (extends `GraphFact`: provenance + confidence).
+
+    `category` must be one of the 41 CUAD clause categories, so a non-ontology category is rejected.
+    """
+
+    category: ClauseCategory
+
+
+class RelationshipFact(GraphFact):
+    """A directed entity-to-entity relationship extracted from a chunk (extends `GraphFact`:
+    provenance + confidence).
+
+    The endpoints are pre-resolution entity mentions (surface forms), directed `source_ref ->
+    target_ref`: source and target are distinct roles, not a symmetric pair, so T8 can add directed
+    corporate-hierarchy relationship types without reopening this model. Entity resolution
+    (FR-C.7 / T24) later maps each ref to a canonical `entity_id`.
+
+    `relationship_type` is an OPAQUE domain string (DD-5, ADR-0066/0117): the engine does not constrain the
+    edge taxonomy; the caller (a domain graph) names it, and the reference contract pack's value set lives in
+    `ontology/contract_taxonomy.py` (e.g. "Contracts With"/"Affiliate Of"). The agreement a co-party fact
+    derives from is its provenance's source document (`provenance.source_doc_id`); because every `GraphFact`
+    requires provenance, that reference is always present, which makes shared-party multi-hop questions
+    answerable from the graph.
+
+    Self-loop is rejected here only at the ref level (the same mention as both source and target).
+    The post-resolution check (two *distinct* mentions that resolve to the same `entity_id`) belongs
+    with entity resolution (T24), because two mentions can legitimately resolve to one entity.
+    """
+
+    source_ref: str  # pre-resolution entity mention (surface form)
+    relationship_type: str  # opaque domain edge type (DD-5); the caller/domain pack names it
+    target_ref: str  # pre-resolution entity mention (surface form)
+
+    @field_validator("source_ref", "target_ref")
+    @classmethod
+    def _ref_non_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("source_ref and target_ref must be non-empty entity mentions")
+        return v
+
+    @model_validator(mode="after")
+    def _no_ref_self_loop(self) -> RelationshipFact:
+        if self.source_ref.strip() == self.target_ref.strip():
+            raise ValueError(
+                "source_ref and target_ref must be distinct mentions (ref-level self-loop); the "
+                "post-resolution same-entity_id check belongs with entity resolution (T24)"
+            )
+        return self

rag_wright/contracts/property.py

@@ -0,0 +1,201 @@
+"""The clause PROPERTY schema and contract (T57, FR-C.6, ADR-0025).
+
+Demand-derived from the 57 ACORD test queries (schema review gate, approved). Every ACORD query is a
+FUNCTION (clause type, `contracts/function.py`) plus zero-or-more PROPERTY constraints; this module is
+the contract for the property layer the extractor (T57b) populates and the property graph (T57c)
+persists. The clause itself stays source-of-truth in the clause OKF bundle; the property graph points
+back to it (`clause_id`), and the schema stores no clause text.
+
+Two tiers, mirroring the approved design:
+- cross-cutting dimensions that recur across the liability/indemnity family (mutuality, favorability,
+  carve_out, covered_subject, covered_parties, party_asymmetry);
+- function-specific dimensions (cap basis/quantum, damage type, warranty scope, claim scope,
+  procedural right, governing-law multiplicity, IP ownership, non-solicit target, renewal mechanism,
+  notice period, jurisdiction).
+
+Each PROPERTY is a graph fact: `PropertyAssertion` extends `GraphFact` (FR-S.4 provenance +
+EXTRACTED/INFERRED/AMBIGUOUS confidence) and cites the operative span it was read from (`span_id`,
+the ADR-0025 join key) -- no claim without a citation (FR-Q.6). Closed-vocabulary dimensions validate
+their value against `CLOSED_VOCAB`; a value outside the vocabulary is admissible ONLY as an AMBIGUOUS
+assertion (the `other` escape, approved), so the extractor and the T58 query-decomposer share exactly
+one vocabulary. Multi-valued dimensions (a carve-out set) are several assertions of the same
+dimension; scalar dimensions are at most one -- the graph writer turns each assertion into one
+typed edge to a (deduped) value node.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from rag_wright.contracts.function import FUNCTION_LABEL_SET, NO_FUNCTION, FunctionScore
+from rag_wright.contracts.ontology import ClauseCategory
+from rag_wright.contracts.provenance import ConfidenceTag, GraphFact
+from rag_wright.ontology._generated_vocab import VOCAB as _GENERATED_VOCAB  # ADR-0066: generated FROM the ttl
+
+
+class PropertyDimension(str, Enum):
+    """The property axes the ACORD queries filter on. Tier 1 = cross-cutting; tier 2 = function-specific."""
+
+    # tier 1 -- cross-cutting (recur across the liability / indemnity family)
+    MUTUALITY = "mutuality"
+    FAVORABILITY = "favorability"
+    CARVE_OUT = "carve_out"
+    COVERED_SUBJECT = "covered_subject"
+    COVERED_PARTIES = "covered_parties"
+    PARTY_ASYMMETRY = "party_asymmetry"
+    # tier 2 -- function-specific
+    CAP_BASIS = "cap_basis"
+    CAP_QUANTUM = "cap_quantum"  # open-valued (e.g. "12_months", "1x_fees")
+    DAMAGE_TYPE = "damage_type"
+    WARRANTY_SCOPE = "warranty_scope"
+    CLAIM_SCOPE = "claim_scope"
+    PROCEDURAL = "procedural"
+    JURISDICTION = "jurisdiction"  # open-valued (e.g. "england", "new_york")
+    LAW_MULTIPLICITY = "law_multiplicity"
+    IP_OWNERSHIP = "ip_ownership"
+    NONSOLICIT_TARGET = "nonsolicit_target"
+    TEMPORAL_BOUND = "temporal_bound"  # open-valued (e.g. "12_months", "unbounded")
+    RENEWAL_MECHANISM = "renewal_mechanism"
+    NOTICE_PERIOD = "notice_period"  # open-valued
+    # tier 3 -- CUAD-family extensions (KG-4: full CUAD clause coverage beyond the ACORD-derived set)
+    EXCLUSIVITY_TYPE = "exclusivity_type"
+    RIGHT_OF_FIRST_TYPE = "right_of_first_type"
+    RESTRICTION_SCOPE = "restriction_scope"  # non-compete scope
+    COC_CONSENT = "coc_consent"  # change-of-control consent regime
+    ASSIGNMENT_CONSENT = "assignment_consent"  # anti-assignment consent regime
+    ESCROW_RELEASE_TRIGGER = "escrow_release_trigger"  # source-code escrow
+    MFN_SCOPE = "mfn_scope"
+    TERMINATION_RIGHT = "termination_right"  # termination-for-convenience
+    AUDIT_FREQUENCY = "audit_frequency"  # open-valued (e.g. "annual", "quarterly")
+    COMMITMENT_QUANTUM = "commitment_quantum"  # open-valued (minimum commitment / volume restriction)
+    LD_TRIGGER = "ld_trigger"  # open-valued (liquidated-damages trigger)
+    # ADR-0049 (2): new closed-vocab dimensions for the taxonomy-gap clause types (the type-specific facet each
+    # one carries that had no existing dimension). Vocab domain-designed + corpus-checked (ADR-0049 step 2).
+    DISPUTE_METHOD = "dispute_method"    # how disputes are resolved (Dispute Resolution)
+    COLLATERAL_TYPE = "collateral_type"  # collateral a security interest attaches to (Security Interest; list)
+    FORCE_MAJEURE_EVENT = "force_majeure_event"              # excused events (Force Majeure; list)
+    ROYALTY_BASIS = "royalty_basis"                          # how a royalty is calculated (Royalties)
+    CONFIDENTIALITY_EXCEPTION = "confidentiality_exception"  # permitted disclosures (Confidentiality; list)
+    CONDITION_TYPE = "condition_type"                        # kind of condition (Condition Precedent)
+
+
+# Closed controlled vocabularies (approved OQ3). A dimension NOT in this map is open-valued
+# (jurisdiction, cap_quantum, temporal_bound, notice_period) -- any non-empty value with an
+# EXTRACTED/INFERRED confidence is admissible. `cap_basis` keeps a closed enum (the shape of the cap)
+# while `cap_quantum` carries the light open scalar (no structured money object -- SPEC section 8).
+# ADR-0066: the closed vocabularies are GENERATED FROM contract_bridge.ttl (the source of truth) into
+# _generated_vocab.VOCAB (string-keyed); here they are re-keyed by PropertyDimension. To change a vocabulary,
+# edit the ttl and re-run scripts/generate_contract_python.py -- never edit the value sets in Python.
+CLOSED_VOCAB: dict[PropertyDimension, frozenset[str]] = {
+    PropertyDimension(dim): values for dim, values in _GENERATED_VOCAB.items()
+}
+
+_FOLIO_BASE = "https://folio.openlegalstandard.org/"
+
+# Clause-TYPE -> FOLIO IRI (naming alignment only, no OWL import; verified against the live FOLIO API,
+# T57). 15/16 aligned types have a home; Joint IP Ownership and Revenue/Profit Sharing have no clean
+# FOLIO class (native, no IRI). Keyed by the function label string (CUAD value or extension value).
+FOLIO_CLAUSE_IRI: dict[str, str] = {
+    ClauseCategory.CAP_ON_LIABILITY.value: _FOLIO_BASE + "RD0R9lAU0GYr2Rm3CDcMWQn",
+    ClauseCategory.GOVERNING_LAW.value: _FOLIO_BASE + "RCinm0jvGGkzcHth7AnasRI",
+    ClauseCategory.LIQUIDATED_DAMAGES.value: _FOLIO_BASE + "R8gVw3PYPaZJ9kce3wE60ag",
+    ClauseCategory.CHANGE_OF_CONTROL.value: _FOLIO_BASE + "Rx73OtOSnOdjzb248cqESZ",
+    ClauseCategory.AUDIT_RIGHTS.value: _FOLIO_BASE + "Rbjf6IGvMubNB3VG6OHa2J",
+    ClauseCategory.NO_SOLICIT_OF_EMPLOYEES.value: _FOLIO_BASE + "RBPNQSqdDfSS0uPPJ8pfxVL",
+    ClauseCategory.NO_SOLICIT_OF_CUSTOMERS.value: _FOLIO_BASE + "RBPNQSqdDfSS0uPPJ8pfxVL",
+    ClauseCategory.ROFR_ROFO_ROFN.value: _FOLIO_BASE + "R8vrLOm6RKTfx8fw40CYWsh",
+    ClauseCategory.THIRD_PARTY_BENEFICIARY.value: _FOLIO_BASE + "R97DdQGgeUgH9OJAvTnJreN",
+    ClauseCategory.IP_OWNERSHIP_ASSIGNMENT.value: _FOLIO_BASE + "RCvIzbBC4HsPoR3TCjrDPSr",
+    ClauseCategory.MINIMUM_COMMITMENT.value: _FOLIO_BASE + "RClWiJIjOouUllydauOfq00",
+    ClauseCategory.RENEWAL_TERM.value: _FOLIO_BASE + "R6ZPNSiwrrkYAEVTRoOKiv",
+    "Indemnification": _FOLIO_BASE + "R9oz08cWJcI23x0nYU1h0it",
+    "Indirect/Consequential Damages Waiver": _FOLIO_BASE + "RBpLvGtycyCm93U686txQg2",
+    "Warranty Disclaimer": _FOLIO_BASE + "RC8mge0bMEuSUAMJUlgN0rZ",
+}
+
+# Carve-out / covered SUBJECT value -> FOLIO IRI. Only these four subjects have a standalone FOLIO
+# concept IRI (T57); the rest are native (no IRI). Used to tag shared `Exception`/`Subject` value nodes.
+FOLIO_SUBJECT_IRI: dict[str, str] = {
+    "fraud": _FOLIO_BASE + "RqGxSnAp9vX42GRKHqwvBe",
+    "gross_negligence": _FOLIO_BASE + "RB2XGaLZqJPXLJOm052Pwrf",
+    "willful_misconduct": _FOLIO_BASE + "RCuhDmyUHjn92exJ8dx1zO1",
+    "confidentiality": _FOLIO_BASE + "ROqkYuzXx4hg7XafuJWBfJ",
+}
+
+
+class PropertyAssertion(GraphFact):
+    """One property of a clause: a (dimension, value) read from an operative span, carrying provenance
+    + confidence (FR-S.4) and the span citation (FR-Q.6, ADR-0025). A closed-vocabulary value outside
+    its vocabulary is admissible ONLY as AMBIGUOUS (the `other` escape) -- this keeps the extractor and
+    the query-decomposer on one shared vocabulary while still recording genuinely novel values."""
+
+    dimension: PropertyDimension
+    value: str
+    span_id: str = ""  # the operative span cited (ADR-0025 join key); "" = clause-level only
+
+    @field_validator("value")
+    @classmethod
+    def _value_non_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("property value must be non-empty")
+        return v
+
+    @model_validator(mode="after")
+    def _value_in_vocab_or_ambiguous(self) -> PropertyAssertion:
+        vocab = CLOSED_VOCAB.get(self.dimension)
+        if vocab is not None and self.value not in vocab and self.confidence != ConfidenceTag.AMBIGUOUS:
+            raise ValueError(
+                f"value {self.value!r} is not in the closed vocabulary for {self.dimension.value} "
+                f"({sorted(vocab)}); an out-of-vocabulary value is admissible only as an AMBIGUOUS "
+                "assertion (the 'other' escape)"
+            )
+        return self
+
+
+class ClausePropertyRecord(BaseModel):
+    """The property layer for one clause: its FUNCTION plus its property assertions.
+
+    `clause_id` is the parent chunk id's string form (the clause is source-of-truth in the clause OKF
+    bundle; the property graph points back to it). `function` must be a member of the retrieval
+    function taxonomy (FUNCTION_LABELS). Every assertion is anchored to this clause: its provenance's
+    chunk id must be this `clause_id`, so a property cannot cite a different clause (FR-Q.6). `folio_iri`
+    names the clause TYPE (naming alignment only) and is filled from `FOLIO_CLAUSE_IRI` when known.
+    """
+
+    clause_id: str
+    function: str
+    folio_iri: str = ""
+    # The operative span this clause was extracted from (1:1; ADR-0025). Known at extraction (op.span_id) and
+    # persisted here so a PROPERTY-LESS clause still has a reliable, one-to-one span link for citation/rehydration
+    # -- not lost, and never guessed by function label (which is one-to-many). "" only for legacy pre-backfill rows.
+    span_id: str = ""
+    assertions: list[PropertyAssertion] = []
+    # INGEST-LLM-CLASSIFIER (ADR-0048): the multi-label classification, ranked primary-first. `function` above is
+    # the PRIMARY (functions[0].function) -- the label query readers use; this additive list carries the
+    # secondaries + confidence for the deferred multi-label consumers. Empty on legacy / LegalBERT-single records.
+    functions: list[FunctionScore] = []
+
+    @field_validator("function")
+    @classmethod
+    def _function_in_taxonomy(cls, v: str) -> str:
+        # a real clause's function is a taxonomy member; the `NO_FUNCTION` sentinel is allowed ONLY for a
+        # query-constraint record (a query has no clause function -- only its extracted properties are used).
+        if v != NO_FUNCTION and v not in FUNCTION_LABEL_SET:
+            raise ValueError(
+                f"function {v!r} is not in the retrieval function taxonomy (FUNCTION_LABELS) "
+                f"or the {NO_FUNCTION!r} no-function sentinel"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _assertions_anchored_to_clause(self) -> ClausePropertyRecord:
+        for a in self.assertions:
+            if str(a.provenance.chunk_id) != self.clause_id:
+                raise ValueError(
+                    "every assertion must be anchored to the record's clause_id "
+                    f"(assertion provenance chunk_id {str(a.provenance.chunk_id)!r} != "
+                    f"clause_id {self.clause_id!r})"
+                )
+        return self

rag_wright/contracts/provenance.py

@@ -0,0 +1,78 @@
+"""Provenance and confidence contracts (FR-S.4).
+
+Every stored unit carries provenance: for text, the source document and the chunk it came from;
+for graph-derived facts, additionally a confidence tag. Provenance is what makes "no claim without
+a citation" (FR-Q.6) enforceable, and the confidence tag is what marks a graph fact as evidence to
+be verified, not truth (SPEC.md section 14).
+
+`Provenance` and `ConfidenceTag` are the reusable primitives; `GraphFact` is the base that graph
+extraction (T5) and graph storage (T24) build their nodes, edges, and facts on.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from rag_wright.contracts.identifiers import ChunkId
+
+
+class ConfidenceTag(str, Enum):
+    """The confidence a graph-derived fact carries (FR-S.4). A closed set, no other value.
+
+    - ``EXTRACTED``: read directly from a source chunk.
+    - ``INFERRED``: derived by reasoning over one or more chunks, not stated verbatim.
+    - ``AMBIGUOUS``: supported but with competing readings or unresolved mentions.
+    """
+
+    EXTRACTED = "EXTRACTED"
+    INFERRED = "INFERRED"
+    AMBIGUOUS = "AMBIGUOUS"
+
+
+class Provenance(BaseModel):
+    """The source document and chunk a stored text unit came from (FR-S.4).
+
+    The `chunk_id` (FR-S.2) already carries its source-document identifier; `source_doc_id` is kept
+    as an explicit, denormalized field so a citation is self-describing, so records can be filtered
+    and indexed by source document at the store level (metadata filters, FR-Q.1), and so downstream
+    code never has to parse `chunk_id` to recover the document. The redundancy is safe only because
+    the two fields cannot disagree: the `_source_matches_chunk` validator runs on every construction
+    and deserialization path (raw constructor, `model_validate`, `model_validate_json`), and
+    `Provenance.of(chunk_id)` derives `source_doc_id` from the chunk so callers cannot create an
+    inconsistent one. Store deserialization must therefore use a validating path
+    (`model_validate` / `model_validate_json`), not `model_construct`, which bypasses all validation.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    source_doc_id: str
+    chunk_id: ChunkId
+
+    @model_validator(mode="after")
+    def _source_matches_chunk(self) -> Provenance:
+        if self.source_doc_id != self.chunk_id.source_doc_id:
+            raise ValueError(
+                "source_doc_id must match chunk_id.source_doc_id "
+                f"({self.source_doc_id!r} != {self.chunk_id.source_doc_id!r}); "
+                "use Provenance.of(chunk_id) to derive it"
+            )
+        return self
+
+    @classmethod
+    def of(cls, chunk_id: ChunkId) -> Provenance:
+        """Build a `Provenance` from a chunk id, deriving `source_doc_id` from it (no drift)."""
+        return cls(source_doc_id=chunk_id.source_doc_id, chunk_id=chunk_id)
+
+
+class GraphFact(BaseModel):
+    """The base for a graph-derived fact: it carries provenance and a confidence tag (FR-S.4).
+
+    Graph nodes and edges (FR-I.4) carry the originating `chunk_id` (through `provenance`) and a
+    `confidence` tag. Graph extraction (T5) and graph storage (T24) extend this base with their own
+    ontology-conforming fields.
+    """
+
+    provenance: Provenance
+    confidence: ConfidenceTag

rag_wright/contracts/query_intent.py

@@ -0,0 +1,53 @@
+"""The NL->type query-understanding output contract (CU-A1 / CU-C1, ADR-0029).
+
+The front door of the CUAD pipeline: a natural-language question about a known contract is parsed (one LLM
+call) into this structured intent. `clause_types` are validated to the retrieval FUNCTION taxonomy
+(`FUNCTION_LABELS`), normalized case-insensitively at the boundary. `intent` routes the serve stage:
+- highlight  -> return the clause's spans as-is
+- extract    -> also field-extract `value_to_extract` from the matched clause (value-type categories)
+- discriminate -> `value_condition` selects among same-type clauses (case (b): detected now, stage stubbed)
+`in_taxonomy=False` marks an out-of-taxonomy query -> serve falls back to semantic span search + a
+low-confidence flag. Multi-type is allowed (`clause_types` is a list).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, field_validator
+
+from rag_wright.contracts.function import canonical_function
+
+Intent = Literal["highlight", "extract", "discriminate"]
+
+
+class QueryIntent(BaseModel):
+    """Structured NL->type intent produced by query understanding (CU-C1)."""
+
+    model_config = {"frozen": True}
+
+    clause_types: list[str] = []  # subset of FUNCTION_LABELS (canonicalized); empty iff out-of-taxonomy
+    intent: Intent = "highlight"
+    value_to_extract: str | None = None  # for intent=extract: which value to pull from the clause
+    value_condition: str | None = None  # for intent=discriminate: the value condition selecting the clause
+    in_taxonomy: bool = True  # False -> semantic fallback + low-confidence flag at serve
+    confidence: float = 1.0  # 0..1 query-understanding confidence
+
+    @field_validator("clause_types")
+    @classmethod
+    def _canonicalize_types(cls, v: list[str]) -> list[str]:
+        out: list[str] = []
+        for label in v:
+            canon = canonical_function(label)
+            if canon is None:
+                raise ValueError(f"clause_type {label!r} is not in the FUNCTION taxonomy")
+            if canon not in out:
+                out.append(canon)
+        return out
+
+    @field_validator("confidence")
+    @classmethod
+    def _check_confidence(cls, v: float) -> float:
+        if not 0.0 <= v <= 1.0:
+            raise ValueError(f"confidence must be in [0, 1], got {v}")
+        return v

rag_wright/contracts/span.py

@@ -0,0 +1,76 @@
+"""Operative-span store record (FR-R, ADR-0025).
+
+One record per operative span in the ArcadeDB `Span` hybrid index. Unlike a `ChunkRecord` (dense over the
+summary, text kept in a sidecar), the span IS the small retrieval unit, so the record carries the span text:
+the dense vector is over the span, the sparse vector is over the span, the `function` is the classifier tag
+(T56), and the parent pointer (`parent_chunk_id` + the clause's OKF path) locates the full clause for the
+rerank stage. `span_id` embeds the parent (identifier rule).
+"""
+
+from __future__ import annotations
+
+import math
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from rag_wright.contracts.chunk import BGE_M3_DENSE_DIM
+
+
+class SpanRecord(BaseModel):
+    """One operative-span record for the `Span` hybrid index (dense + sparse over the span text).
+
+    CUAD-highlighting fields (CU-A1, ADR-0029) are OPTIONAL/defaulted so the ACORD span leg (which does not
+    set them) is unaffected: `contract_id` is the source-document id used by the within-contract typed filter
+    (derivable from `parent_chunk_id` but stored explicitly for an indexed WHERE); `doc_start`/`doc_end` are
+    document-absolute character offsets of the span (the citation the app highlights on); `page`/`bbox` are the
+    optional PDF-overlay provenance (Docling-supplied where available). `parent_chunk_id` is the parent-clause
+    pointer (a clause == a chunk), so no separate clause_id field is added.
+    """
+
+    model_config = {"frozen": True}
+
+    span_id: str  # "{parent_chunk_id}#{span_index}"
+    parent_chunk_id: str  # the parent CLAUSE id (a clause is a chunk); the span<->clause link
+    parent_okf_path: str = ""  # where the parent clause lives in the clause OKF bundle
+    span_index: int
+    text: str
+    function: str = ""  # the PRIMARY function-classifier tag (T56); "" until classified. == functions[0] when set.
+    functions: list[str] = []  # T55/ADR-0114: the top-k soft tags primary-first (SetFit ensemble); `function` is
+    #   functions[0]. Realizes the multi-tag soft-tagger so a span is discoverable under several clause types.
+    dense_vector: list[float]  # dense over the span; length == BGE_M3_DENSE_DIM
+    sparse_vector: dict[int, float]  # sparse over the span: token-id -> non-negative weight
+    contract_id: str = ""  # CU-A1: source contract/document id (within-contract typed filter)
+    doc_start: int | None = None  # CU-A1: document-absolute char offset (citation); None on the ACORD leg
+    doc_end: int | None = None  # CU-A1: exclusive
+    page: int | None = None  # CU-A1: 1-based FIRST page for PDF-overlay highlight (== pages[0] when known)
+    pages: list[int] = []  # issue 0032/CU-B5: ALL 1-based source pages this span overlaps (a clause can cross a
+    #   page boundary); empty when the parse carried no page provenance (e.g. the text-only ingest leg)
+    bbox: tuple[float, float, float, float] | None = None  # CU-A1: (left, top, right, bottom) on `page`, best-effort
+
+    @model_validator(mode="after")
+    def _check_offsets(self) -> "SpanRecord":
+        if self.doc_start is not None and self.doc_start < 0:
+            raise ValueError("doc_start must be non-negative")
+        if self.doc_start is not None and self.doc_end is not None and self.doc_end < self.doc_start:
+            raise ValueError(f"doc_end ({self.doc_end}) must be >= doc_start ({self.doc_start})")
+        if self.page is not None and self.page < 1:
+            raise ValueError("page is 1-based; must be >= 1")
+        if any(p < 1 for p in self.pages):
+            raise ValueError("pages are 1-based; each must be >= 1")
+        return self
+
+    @field_validator("dense_vector")
+    @classmethod
+    def _check_dense(cls, v: list[float]) -> list[float]:
+        if len(v) != BGE_M3_DENSE_DIM:
+            raise ValueError(f"dense_vector must have length {BGE_M3_DENSE_DIM}, got {len(v)}")
+        if not all(math.isfinite(x) for x in v):
+            raise ValueError("dense_vector must contain only finite values")
+        return v
+
+    @field_validator("sparse_vector")
+    @classmethod
+    def _check_sparse(cls, v: dict[int, float]) -> dict[int, float]:
+        if any(weight < 0 for weight in v.values()):
+            raise ValueError("sparse_vector weights must be non-negative")
+        return v