rag-wright 0.1.0__py3-none-any.whl

rag_wright/ontology/contract_taxonomy.py

@@ -0,0 +1,24 @@
+"""The reference CONTRACT domain pack's entity-node + entity-relationship taxonomy (DD-5/DD-7, ADR-0066/0117).
+
+De-domaining (DD-5): the engine's generic primitives + contracts are taxonomy-free -- `entity_type` and
+`relationship_type` are plain strings the CALLER (a domain graph) names. The closed value sets below are DOMAIN
+knowledge.
+
+ADR-0066 end-state (DD-7): those values are now declared in `contract_bridge.ttl` (the single source of truth) and
+rendered into `_generated_vocab.py` by codegen, CI-diff-enforced (`tests/ontology/test_generated_vocab_in_sync.py`).
+This module is the stable import surface the domain builders use -- it RE-EXPORTS the generated constants, so no
+code hardcodes the values. To change the taxonomy, edit the ttl and regenerate; never edit the generated file or
+re-add literals here. A new domain declares its own entity/edge types in its own pack the same way.
+"""
+from __future__ import annotations
+
+from rag_wright.ontology._generated_vocab import (  # generated FROM contract_bridge.ttl (DD-7); do not hardcode here
+    AFFILIATE_OF,
+    CONTRACTS_WITH,
+    ENTITY_TYPES,
+    ORGANIZATION,
+    PERSON,
+    RELATIONSHIP_TYPES,
+)
+
+__all__ = ["ORGANIZATION", "PERSON", "CONTRACTS_WITH", "AFFILIATE_OF", "ENTITY_TYPES", "RELATIONSHIP_TYPES"]

rag_wright/ontology/derive.py

@@ -0,0 +1,58 @@
+"""Ontology derivation (T8, FR-C.8): reconcile the T4 ontology against the real CUAD data.
+
+T4 declared the 41 `ClauseCategory` values from the published CUAD label set. This module confirms
+they match the actual `master_clauses.csv` columns and produces a CSV-column -> canonical-category
+mapping. The CSV headers carry artifacts the reconciliation absorbs so downstream annotation reading
+(T9) binds to the canonical categories regardless: paired answer columns use inconsistent spacing
+(`-Answer` and `- Answer`), and some names are cased differently (`Ip Ownership Assignment` vs the
+ontology's canonical `IP Ownership Assignment`). Matching is spacing-tolerant on answer columns and
+case-insensitive on category names; the ontology keeps its canonical casing.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.ontology import ClauseCategory
+
+_ANSWER_SUFFIX = re.compile(r"-\s*answer$", re.IGNORECASE)
+
+
+def clause_category_columns(header: list[str]) -> list[str]:
+    """The category columns of `master_clauses.csv`: everything but `Filename` and answer columns."""
+    return [
+        col
+        for col in header
+        if col.strip().lower() != "filename" and not _ANSWER_SUFFIX.search(col.strip())
+    ]
+
+
+class Reconciliation(BaseModel):
+    """The result of reconciling CSV category columns against the `ClauseCategory` ontology."""
+
+    matched: dict[str, ClauseCategory]  # CSV column -> canonical category
+    missing: list[ClauseCategory]  # ontology categories with no CSV column
+    extra: list[str]  # CSV columns matching no ontology category
+
+    @property
+    def ok(self) -> bool:
+        return not self.missing and not self.extra
+
+
+def reconcile_clause_categories(csv_columns: list[str]) -> Reconciliation:
+    """Match CSV category columns to `ClauseCategory` (case-insensitive), reporting gaps both ways."""
+    by_norm = {category.value.lower(): category for category in ClauseCategory}
+    matched: dict[str, ClauseCategory] = {}
+    extra: list[str] = []
+    seen: set[ClauseCategory] = set()
+    for column in csv_columns:
+        category = by_norm.get(column.strip().lower())
+        if category is None:
+            extra.append(column)
+        else:
+            matched[column] = category
+            seen.add(category)
+    missing = [category for category in ClauseCategory if category not in seen]
+    return Reconciliation(matched=matched, missing=missing, extra=extra)

rag_wright/ontology/loader.py

@@ -0,0 +1,435 @@
+"""ADR-0066: the runtime loader for the contract ontology `.ttl` -- the seed of the ontology-as-source-of-truth
+substrate. Parses `contract_bridge.ttl` into the domain knowledge structures the engine consumes: the closed
+vocabularies, scalar/list cardinality, the function -> applicable-dimensions applicability, the deontic polarity
+(+ restrictive functions), and the value rollups.
+
+Phase 0 uses this only to PROVE the ttl reproduces today's Python constants (the equivalence gate). Phase 1
+generates the Python vocab/enums FROM this loader; Phase 2 hands the SHACL shapes straight to pyshacl. The `.ttl`
+uses a uniform, label-keyed layer (a `cbr:PropertyDimension` node per dimension with `owl:oneOf` + a
+`cbr:cardinality` tag; a `sh:NodeShape` per clause function; `skos:broader` for rollups), so this loader is
+robust to IRI encoding -- it reads `rdfs:label`, never decodes an IRI.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+
+from rdflib import Graph
+from rdflib.collection import Collection
+from rdflib.namespace import OWL, RDF, RDFS, SH, SKOS
+
+_TTL_PATH = Path(__file__).with_name("contract_bridge.ttl")
+_COMPLIANCE_TTL_PATH = Path(__file__).with_name("compliance_bridge.ttl")
+
+
+def load_compliance_vocab(path: Path | str = _COMPLIANCE_TTL_PATH) -> dict[str, set[str]]:
+    """ADR-0066 P3b: the closed vocabularies declared in compliance_bridge.ttl, keyed by class local-name
+    (`DeonticType`, `ClaimType`, `Severity`, `RuleScope`, `Verdict`) -> the set of `owl:oneOf` value local-names.
+    The Python enums in contracts/compliance.py are drift-locked to this (the ttl is the source of truth)."""
+    g = Graph()
+    g.parse(str(path), format="turtle")
+    out: dict[str, set[str]] = {}
+    for cls in g.subjects(OWL.oneOf, None):
+        local = str(cls).rsplit("#", 1)[-1]
+        members = {str(m).rsplit("#", 1)[-1] for m in Collection(g, g.value(cls, OWL.oneOf))}
+        out[local] = members
+    return out
+
+
+_CMP = "https://ragwright.local/ontology/compliance-bridge#"
+
+
+@lru_cache(maxsize=4)
+def load_deontic_cues(path: str = str(_COMPLIANCE_TTL_PATH)) -> frozenset[str]:
+    """ADR-0066 P3c (Gap 1): the deontic CUES declared in compliance_bridge.ttl (`cmp:cue` on each deontic type) --
+    the lexical markers of operative normative force. The requirement-ingestion validity gate uses them: a section
+    with none of these cues is non-operative and is skipped. Cached per path."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    return frozenset(str(v).strip().lower() for v in g.objects(None, URIRef(_CMP + "cue")) if str(v).strip())
+
+
+@lru_cache(maxsize=4)
+def load_deontic_cue_map(path: str = str(_COMPLIANCE_TTL_PATH)) -> dict[str, str]:
+    """CIC-0 (ADR-0066): the deontic CUE -> deontic TYPE map authored in compliance_bridge.ttl (`cmp:cue` on each
+    `cmp:DeonticType`), e.g. {'must': 'obligation', 'must not': 'prohibition', 'may': 'permission'}. Keys are
+    lowercased cue phrases; values are the DeonticType local-names. This is the ttl-driven source for the ingest
+    cue-RULE (`deontic_type_of`): a rule's deontic_type is derived deterministically from its text's cue instead of
+    from an LLM field. Shares its cue set with `load_deontic_cues` (the operative gate). Cached per path."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    cue = URIRef(_CMP + "cue")
+    out: dict[str, str] = {}
+    for subj, obj in g.subject_objects(cue):
+        value = str(obj).strip().lower()
+        if value:
+            out[value] = str(subj).rsplit("#", 1)[-1]
+    return out
+
+
+@lru_cache(maxsize=1)
+def _deontic_cue_type_pattern() -> tuple[re.Pattern, dict[str, str]]:
+    """The compiled cue regex (longest cue first, so 'must not' is tried before 'must') + the cue->type map."""
+    cue_map = load_deontic_cue_map()
+    cues = sorted(cue_map, key=len, reverse=True)
+    return re.compile(r"\b(?:" + "|".join(re.escape(c) for c in cues) + r")\b", re.IGNORECASE), cue_map
+
+
+def deontic_type_of(text: str) -> str | None:
+    """CIC-0 (ADR-0066): the deontic TYPE of a rule span, from its FIRST deontic cue (ttl `cmp:cue`), longest cue
+    first so 'must not' / 'may not' (prohibition) win over 'must' / 'may'. Returns the DeonticType local-name
+    (obligation / prohibition / permission) or None when the text carries no cue (non-operative). The deterministic
+    cue-rule that replaces the LLM's deontic_type field at ingest; a non-None result also means the span is
+    operative (same cue basis as `is_operative`)."""
+    if not text:
+        return None
+    pattern, cue_map = _deontic_cue_type_pattern()
+    m = pattern.search(text)
+    return cue_map[m.group(0).lower()] if m else None
+
+
+@lru_cache(maxsize=4)
+def load_actor_synonyms(path: str = str(_COMPLIANCE_TTL_PATH)) -> dict[str, str]:
+    """ADR-0066 P4a: the actor-role synonyms from compliance_bridge.ttl -- `{synonym -> canonical role}` built from
+    each `cmp:ActorRole`'s `skos:altLabel` (synonym) -> `skos:prefLabel` (canonical). The query-side actor gate
+    (`canonical_actor`) normalizes with this. Cached per path."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    out: dict[str, str] = {}
+    for role in g.subjects(RDF.type, URIRef(_CMP + "ActorRole")):
+        pref = str(g.value(role, SKOS.prefLabel) or "").strip().lower()
+        if not pref:
+            continue
+        for alt in g.objects(role, SKOS.altLabel):
+            out[str(alt).strip().lower()] = pref
+    return out
+
+
+@lru_cache(maxsize=4)
+def load_claim_type_criteria(path: str = str(_COMPLIANCE_TTL_PATH)) -> dict[str, str]:
+    """ADR-0119: `{ClaimType local-name -> cmp:decisionCriterion}` -- the one-line criterion each claim type uses
+    as its typed-decision (noul) question. Authored in compliance_bridge.ttl, not in capability code (ADR-0066)."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    crit = URIRef(_CMP + "decisionCriterion")
+    out: dict[str, str] = {}
+    for m in g.subjects(RDF.type, URIRef(_CMP + "ClaimType")):
+        c = g.value(m, crit)
+        if c is not None:
+            out[str(m).rsplit("#", 1)[-1]] = str(c)
+    return out
+
+
+@lru_cache(maxsize=4)
+def load_actor_role_criteria(path: str = str(_COMPLIANCE_TTL_PATH)) -> dict[str, str]:
+    """ADR-0119: `{ActorRole prefLabel -> cmp:decisionCriterion}` -- the actor `choice` options + their criteria,
+    from the ttl (includes the workplace-domain `employer`). Authored in the ontology, not capability code."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    crit = URIRef(_CMP + "decisionCriterion")
+    out: dict[str, str] = {}
+    for role in g.subjects(RDF.type, URIRef(_CMP + "ActorRole")):
+        c = g.value(role, crit)
+        label = str(g.value(role, SKOS.prefLabel) or str(role).rsplit("#", 1)[-1]).strip().lower()
+        if c is not None and label:
+            out[label] = str(c)
+    return out
+
+
+@lru_cache(maxsize=4)
+def load_operative_rubric(path: str = str(_COMPLIANCE_TTL_PATH)) -> dict[str, str]:
+    """ADR-0119: the operative-rule binary gate's `{instructions, true, false}` from `cmp:operativeRuleQuestion`
+    in compliance_bridge.ttl -- the decision knowledge the `jev_decision` gate asks, authored in the ontology."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    q = URIRef(_CMP + "operativeRuleQuestion")
+
+    def _v(prop: str) -> str:
+        v = g.value(q, URIRef(_CMP + prop))
+        return str(v) if v is not None else ""
+
+    return {"instructions": _v("questionInstructions"), "true": _v("criterionTrue"), "false": _v("criterionFalse")}
+
+
+@lru_cache(maxsize=4)
+def load_role_domains(path: str = str(_COMPLIANCE_TTL_PATH)) -> dict[str, str]:
+    """ADR-0068 (engine issue 0013): the DISJOINTNESS knowledge for the actor gate -- `{canonical role -> domain}`
+    built from each `cmp:ActorRole`'s `skos:prefLabel` (canonical) -> `cmp:roleDomain`. Two roles are disjoint iff
+    both appear here with DIFFERENT domains; the recall-first gate excludes only disjoint pairs (a role absent
+    here, or two roles in the same domain, are compatible). A customer domain declares its roles' roleDomain in
+    its own pack to get cross-domain narrowing. Cached per path."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    out: dict[str, str] = {}
+    for role in g.subjects(RDF.type, URIRef(_CMP + "ActorRole")):
+        pref = str(g.value(role, SKOS.prefLabel) or "").strip().lower()
+        domain = str(g.value(role, URIRef(_CMP + "roleDomain")) or "").strip().lower()
+        if pref and domain:
+            out[pref] = domain
+    return out
+
+
+_FTC_PACK_PATH = Path(__file__).parent / "packs" / "ftc_16cfr255.ttl"
+
+
+@lru_cache(maxsize=4)
+def load_section_overrides(path: str = str(_FTC_PACK_PATH)) -> tuple[dict[str, str], dict[str, frozenset[str]]]:
+    """ADR-0066 P4b: a domain pack's per-section overrides from `cmp:SectionOverride` instances. Returns
+    `(rule_scope, claim_types)`: `{section -> 'content'|'context'}` (only sections that pin a scope) and
+    `{section -> {claim type value}}` (all claim types when `cmp:appliesToAllClaimTypes` is true, else the explicit
+    `cmp:appliesToClaimType` set -- empty for a definitions section). Cached per path."""
+    from rdflib import URIRef
+
+    g = Graph()
+    g.parse(path, format="turtle")
+    all_claim_types = frozenset(load_compliance_vocab().get("ClaimType", set()))
+    rule_scope: dict[str, str] = {}
+    claim_types: dict[str, frozenset[str]] = {}
+    for so in g.subjects(RDF.type, URIRef(_CMP + "SectionOverride")):
+        section = str(g.value(so, URIRef(_CMP + "section")) or "").strip()
+        if not section:
+            continue
+        all_flag = g.value(so, URIRef(_CMP + "appliesToAllClaimTypes"))
+        if all_flag is not None and bool(all_flag.toPython()):
+            claim_types[section] = all_claim_types
+        else:
+            claim_types[section] = frozenset(
+                str(ct).rsplit("#", 1)[-1] for ct in g.objects(so, URIRef(_CMP + "appliesToClaimType")))
+        rs = g.value(so, URIRef(_CMP + "overrideRuleScope"))
+        if rs is not None:
+            rule_scope[section] = str(rs).rsplit("#", 1)[-1]
+    return rule_scope, claim_types
+
+
+@lru_cache(maxsize=4)
+def load_shapes_graph(path: str = str(_TTL_PATH)) -> Graph:
+    """ADR-0066 P2: the ttl parsed as an rdflib Graph -- its `sh:NodeShape`s ARE the SHACL shapes handed to pyshacl
+    at runtime, so the symbolic layer reads the symbolic artifact directly (no Python-built shapes). pyshacl uses
+    the shapes and ignores the ttl's non-SHACL triples. Cached per path."""
+    g = Graph()
+    g.parse(path, format="turtle")
+    return g
+_CBR = "https://ragwright.local/ontology/contract-bridge#"
+# The engine's pack-schema DECLARATION meta-vocabulary (DD-8): the classes/predicates a pack `.ttl` uses to declare
+# its KG node/edge types + entity taxonomy (KgVertexType/vertexName/kgProperty/uniqueIndexOn/KgStructuralEdge/
+# edgeName, EntityNodeType/EntityRelationshipType). Engine-namespaced (not contract-namespaced), so a NON-contract
+# domain declares its schema in this shared language without borrowing the contract pack's namespace (AC-journey).
+_ENG = "https://ragwright.local/ontology/engine#"
+_DIMENSION_CLASS = _CBR + "PropertyDimension"
+
+
+@dataclass(frozen=True)
+class ContractOntologyView:
+    """The contract domain knowledge parsed out of `contract_bridge.ttl` (all string-keyed by label)."""
+
+    closed_vocab: dict[str, set[str]] = field(default_factory=dict)
+    multivalued: set[str] = field(default_factory=set)
+    function_applicable_dims: dict[str, set[str]] = field(default_factory=dict)
+    permission_polarity: dict[str, set[str]] = field(default_factory=dict)
+    restrictive_functions: set[str] = field(default_factory=set)
+    value_rollup: dict[str, dict[str, set[str]]] = field(default_factory=dict)
+    # issue 0037: ingest synonyms -- {dimension: {normalized surface term: canonical member}}. A skos:broader edge
+    # whose BROADER is a closed-vocab member but whose NARROWER is not (a specific surface term). Used at ingest to
+    # canonicalize an out-of-vocab extracted value onto its canonical member (else the value is kept verbatim).
+    value_synonyms: dict[str, dict[str, str]] = field(default_factory=dict)
+    # DD-7 (ADR-0066): the entity-graph taxonomy -- entity node types (cbr:EntityNodeType) + entity-to-entity
+    # relationship types (cbr:EntityRelationshipType), by label. Was the Python EntityType/RelationshipType enum.
+    entity_types: set[str] = field(default_factory=set)
+    relationship_types: set[str] = field(default_factory=set)
+
+
+def _label(g: Graph, node) -> str:
+    lbl = g.value(node, RDFS.label)
+    return str(lbl) if lbl is not None else ""
+
+
+def load_contract_ontology(path: Path | str = _TTL_PATH) -> ContractOntologyView:
+    """Parse the contract bridge ontology into a `ContractOntologyView`."""
+    g = Graph()
+    g.parse(str(path), format="turtle")
+
+    closed_vocab: dict[str, set[str]] = {}
+    multivalued: set[str] = set()
+    dim_label_by_node: dict[str, str] = {}      # dimension IRI -> label (for the applicability shapes)
+    value_label_by_node: dict[str, str] = {}    # value IRI -> label (for rollups + oneOf)
+    value_dim_by_node: dict[str, str] = {}       # value IRI -> its dimension label (for rollups)
+
+    for dim in g.subjects(RDF.type, _dim_class()):
+        label = _label(g, dim)
+        dim_label_by_node[str(dim)] = label
+        if str(g.value(dim, _cbr("cardinality")) or "") == "list":
+            multivalued.add(label)
+        one_of = g.value(dim, OWL.oneOf)
+        if one_of is not None:  # a CLOSED dimension (open-valued dims omit owl:oneOf)
+            members = list(Collection(g, one_of))
+            values = set()
+            for m in members:
+                vlabel = _label(g, m)
+                values.add(vlabel)
+                value_label_by_node[str(m)] = vlabel
+                value_dim_by_node[str(m)] = label
+            closed_vocab[label] = values
+
+    # Applicability + deontic: one sh:NodeShape per clause function.
+    function_applicable_dims: dict[str, set[str]] = {}
+    permission_polarity: dict[str, set[str]] = {}
+    restrictive_functions: set[str] = set()
+    for shape in g.subjects(RDF.type, SH.NodeShape):
+        target = g.value(shape, SH.targetClass)
+        fn = _label(g, target)
+        if not fn:
+            continue
+        dims: set[str] = set()
+        for prop in g.objects(shape, SH.property):
+            path = g.value(prop, SH.path)
+            dlabel = dim_label_by_node.get(str(path), _label(g, path))
+            dims.add(dlabel)
+            in_list = g.value(prop, SH["in"])
+            if in_list is not None:  # deontic: restrictive function forbids the permission-polarity values
+                restrictive_functions.add(fn)
+                allowed = {str(x) for x in Collection(g, in_list)}
+                forbidden = closed_vocab.get(dlabel, set()) - allowed
+                if forbidden:
+                    permission_polarity.setdefault(dlabel, set()).update(forbidden)
+        function_applicable_dims[fn] = dims
+
+    # Value rollups: skos:broader between value individuals.
+    value_rollup: dict[str, dict[str, set[str]]] = {}
+    # issue 0037: ingest synonyms -- {dim: {normalized surface: canonical member}} from a skos:broader edge whose
+    # BROADER is a closed member but whose NARROWER is not (a specific surface term); surface = narrower local-name
+    # + its skos:altLabels. (A narrower that IS a member is a query-side rollup, handled above.)
+    value_synonyms: dict[str, dict[str, str]] = {}
+    for narrower, broader in g.subject_objects(SKOS.broader):
+        dim = value_dim_by_node.get(str(narrower))
+        if dim is not None:  # narrower is itself a vocab member -> a query-side value rollup
+            value_rollup.setdefault(dim, {}).setdefault(
+                value_label_by_node.get(str(narrower), ""), set()).add(
+                value_label_by_node.get(str(broader), ""))
+            continue
+        bdim = value_dim_by_node.get(str(broader))  # narrower is a surface synonym -> map to the broader member
+        bval = value_label_by_node.get(str(broader))
+        if not bdim or not bval:
+            continue
+        surfaces = {_label(g, narrower) or str(narrower).rsplit("#", 1)[-1]}
+        surfaces |= {str(a) for a in g.objects(narrower, SKOS.altLabel)}
+        for s in surfaces:
+            key = re.sub(r"[^A-Za-z0-9]+", "", s).lower()
+            if key:
+                value_synonyms.setdefault(bdim, {})[key] = bval
+
+    # DD-7: the entity-graph taxonomy (entity node types + entity-to-entity relationship types), by label.
+    entity_types = {_label(g, s) for s in g.subjects(RDF.type, _eng("EntityNodeType"))}
+    relationship_types = {_label(g, s) for s in g.subjects(RDF.type, _eng("EntityRelationshipType"))}
+
+    return ContractOntologyView(
+        closed_vocab=closed_vocab, multivalued=multivalued,
+        function_applicable_dims=function_applicable_dims,
+        permission_polarity=permission_polarity, restrictive_functions=restrictive_functions,
+        value_synonyms=value_synonyms,
+        value_rollup=value_rollup,
+        entity_types=entity_types, relationship_types=relationship_types)
+
+
+@dataclass(frozen=True)
+class KgVertexType:
+    """ADR-0067 P5b: a domain KG vertex-type declaration the store creates -- name, its `(property, SQL type)`
+    pairs, and the property to build a UNIQUE index on (if any)."""
+
+    name: str
+    properties: tuple[tuple[str, str], ...]
+    unique_index: str | None
+
+
+@lru_cache(maxsize=8)
+def load_kg_schema(path: str | None = None) -> tuple[tuple[KgVertexType, ...], frozenset[str]]:
+    """ADR-0067 P5b: the DOMAIN KG node/edge storage schema from the ttl -- `(vertex types, structural edge names)`.
+    The engine infra (Chunk/Span/Entity) stays generic in store code; these domain types are pack-declared. Cached.
+    `path=None` is the engine's reference CONTRACT pack; a new domain passes its OWN pack `.ttl` (AC-journey)."""
+    g = Graph()
+    g.parse(str(path or _TTL_PATH), format="turtle")
+    vertices = []
+    for v in g.subjects(RDF.type, _eng("KgVertexType")):
+        props = tuple(sorted((str(p).split(":", 1)[0], str(p).split(":", 1)[1])
+                             for p in g.objects(v, _eng("kgProperty")) if ":" in str(p)))
+        ui = g.value(v, _eng("uniqueIndexOn"))
+        vertices.append(KgVertexType(name=str(g.value(v, _eng("vertexName"))), properties=props,
+                                     unique_index=(str(ui) if ui is not None else None)))
+    vertices.sort(key=lambda x: x.name)
+    edges = frozenset(str(g.value(e, _eng("edgeName")))
+                      for e in g.subjects(RDF.type, _eng("KgStructuralEdge")))
+    return tuple(vertices), edges
+
+
+@lru_cache(maxsize=4)
+def load_typed_edges(path: str = str(_TTL_PATH)) -> tuple[dict[str, str], dict[str, str]]:
+    """ADR-0067 P5a: the KG typed-edge map from contract_bridge.ttl. Returns `(dim_edge, edge_iri)`:
+    `{dimension value -> KG edge type}` (from `cbr:kgEdge`) and `{edge type -> predicate IRI}` (from
+    `cbr:predicateIri` on each `cbr:KgEdgeType`). The property-graph edge types are ontology-authoritative;
+    `store/arcadedb.py` builds `_TYPED_DIMENSION_EDGE` / `_edge_predicate_iri` from this. Cached per path."""
+    g = Graph()
+    g.parse(str(path), format="turtle")
+    edge_iri = {str(g.value(e, RDFS.label)): str(g.value(e, _cbr("predicateIri")))
+                for e in g.subjects(RDF.type, _cbr("KgEdgeType"))}
+    dim_edge = {str(g.value(dim, RDFS.label)): str(g.value(edge, RDFS.label))
+                for dim, edge in g.subject_objects(_cbr("kgEdge"))}
+    return dim_edge, edge_iri
+
+
+def _dim_class():
+    from rdflib import URIRef
+    return URIRef(_DIMENSION_CLASS)
+
+
+def _cbr(frag: str):
+    from rdflib import URIRef
+    return URIRef(_CBR + frag)
+
+
+def _eng(frag: str):
+    from rdflib import URIRef
+    return URIRef(_ENG + frag)
+
+
+def load_template_fields(path: Path | str = _TTL_PATH):
+    """ADR-0066 P1b-1: the extraction template's fields as captured in the ttl, as `TemplateFieldSpec`s in the
+    same order the template declares them (`cbr:fieldOrder`). Round-trips `bootstrap_template_capture` -- the drift
+    test asserts this equals a fresh introspection of `clause_template.py`."""
+    from rag_wright.ontology.template_introspect import TemplateFieldSpec
+
+    g = Graph()
+    g.parse(str(path), format="turtle")
+    specs: list = []
+    for node in g.subjects(RDF.type, _cbr("TemplateField")):
+        order = g.value(node, _cbr("fieldOrder"))
+        ml = g.value(node, _cbr("maxLength"))
+        specs.append((int(order), TemplateFieldSpec(
+            model=str(g.value(node, _cbr("onModel"))),
+            name=str(g.value(node, RDFS.label)),
+            kind=str(g.value(node, _cbr("fieldKind"))),
+            default_token=str(g.value(node, _cbr("default"))),
+            definition=str(g.value(node, SKOS.definition) or ""),
+            enum_class=(str(v) if (v := g.value(node, _cbr("enumClass"))) is not None else None),
+            model_ref=(str(v) if (v := g.value(node, _cbr("modelRef"))) is not None else None),
+            edge_label=(str(v) if (v := g.value(node, _cbr("edgeLabel"))) is not None else None),
+            max_length=(int(ml) if ml is not None else None),
+            examples=(tuple(str(e) for e in Collection(g, exlist))
+                      if (exlist := g.value(node, _cbr("examples"))) is not None else ()),
+        )))
+    return [spec for _, spec in sorted(specs, key=lambda t: t[0])]

rag_wright/ontology/packs/ftc_16cfr255.ttl

@@ -0,0 +1,29 @@
+# ftc_16cfr255.ttl -- the FTC 16 CFR Part 255 (Endorsement Guides) DOMAIN PACK (ADR-0066 P4b).
+#
+# The REFERENCE domain pack: the curated per-section overrides for the FTC endorsement guides, as
+# cmp:SectionOverride instances (the shape is declared in compliance_bridge.ttl). Loaded by the query side to
+# override DEON-1 rule scope + DEON-8 applicable claim types for FTC-cited requirements. A customer domain ships
+# its OWN pack; nothing FTC-specific is hardcoded in engine code.
+#
+# KEY FINDING (CC-6): the FTC endorsement guides apply by CONTEXT (is the ad an endorsement?), NOT by claim_type,
+# so every operative section applies to ALL claim types; only the definitions section (255.0) applies to none.
+# 255.5 (material-connection disclosure) + 255.4 (organization endorsements) are CONTEXT rules (always included).
+
+@prefix ftc:  <https://ragwright.local/ontology/packs/ftc-16cfr255#> .
+@prefix cmp:  <https://ragwright.local/ontology/compliance-bridge#> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<https://ragwright.local/ontology/packs/ftc-16cfr255> a owl:Ontology ;
+    rdfs:label "FTC 16 CFR 255 domain pack" ;
+    rdfs:comment "Curated per-section overrides for the FTC Endorsement Guides (the engine's reference domain pack)." .
+
+ftc:s255_0 a cmp:SectionOverride ; cmp:section "255.0" ; cmp:appliesToAllClaimTypes false .  # definitions -> none
+ftc:s255_1 a cmp:SectionOverride ; cmp:section "255.1" ; cmp:appliesToAllClaimTypes true .   # general considerations
+ftc:s255_2 a cmp:SectionOverride ; cmp:section "255.2" ; cmp:appliesToAllClaimTypes true .   # consumer endorsements
+ftc:s255_3 a cmp:SectionOverride ; cmp:section "255.3" ; cmp:appliesToAllClaimTypes true .   # expert endorsements
+ftc:s255_4 a cmp:SectionOverride ; cmp:section "255.4" ; cmp:appliesToAllClaimTypes true ;   # organization endorsements
+    cmp:overrideRuleScope cmp:context .
+ftc:s255_5 a cmp:SectionOverride ; cmp:section "255.5" ; cmp:appliesToAllClaimTypes true ;   # material-connection disclosure
+    cmp:overrideRuleScope cmp:context .
+ftc:s255_6 a cmp:SectionOverride ; cmp:section "255.6" ; cmp:appliesToAllClaimTypes true .   # endorsements to children

rag_wright/ontology/registry.py

@@ -0,0 +1,87 @@
+"""The entity registry (T8, FR-C.8 / FR-C.7) -- a DOMAIN-NEUTRAL closed-world registry of canonical entities.
+
+ADR-0067: the registry is generic. A domain's canonical `entity_id`s and their surface normalization are the
+domain's concern: the surface-form normalizer is INJECTABLE (`EntityRegistry(normalize=...)`, default = a generic
+name key), and the domain's own builder constructs the registry (the reference builder lives in the corpus
+layer, keyed by that corpus's canonical ids). This module imports nothing corpus-specific.
+
+Lookup is **closed-world**: `resolve` returns `None` for an unknown surface form, never a fabricated id. The
+concrete matching strategy (fuzzy / embedding / language-model-assisted, SPEC section 16.3) is T24's; this
+registry is the closed set T24 resolves against, plus an exact normalized-surface-form index.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Callable, Optional, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.identifiers import EntityId
+
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def default_surface_key(name: str) -> str:
+    """The default DOMAIN-NEUTRAL surface-form key: lowercase, non-alphanumeric runs folded to a single space."""
+    return _NON_ALNUM.sub(" ", (name or "").lower()).strip()
+
+
+@runtime_checkable
+class EntityResolver(Protocol):
+    """The entity-resolution seam (DD-3, ADR-0067 P5c): map a surface form to a canonical `entity_id`, or
+    `None` (closed-world -- never a fabricated id). The RESOLUTION STRATEGY is the domain's concern and is
+    injected into `resolve_entities` (FR-C.7): the generic default is the exact-normalized surface-form
+    `EntityRegistry` (below); a domain pack injects its own registry built by that corpus's loader in the
+    corpus layer (keyed by that domain's canonical ids). A product may bind any strategy (fuzzy / embedding /
+    an external service) as long as it honors this signature and the closed-world contract. The generic
+    resolution invariants (cluster surface-form sweep, two-channel dedup, self-loop dropping) stay in the
+    capability, not the resolver. This module names no specific domain (the SEC-free scope guard enforces it)."""
+
+    def resolve(self, surface_form: str) -> Optional[EntityId]:
+        ...
+
+
+class RegistryRecord(BaseModel):
+    """One registered entity: its canonical id, conformed name, ticker, and known aliases."""
+
+    entity_id: EntityId
+    canonical_name: str
+    ticker: Optional[str] = None
+    aliases: list[str] = []
+
+
+class EntityRegistry:
+    """A closed-world registry of canonical entities, indexed by normalized surface form."""
+
+    def __init__(self, *, normalize: Optional[Callable[[str], str]] = None) -> None:
+        self._by_id: dict[str, RegistryRecord] = {}
+        self._index: dict[str, EntityId] = {}  # normalized surface form -> entity_id
+        self.skipped_ids: list[str] = []  # raw canonical-id values that failed normalization (builder-specific)
+        self._normalize = normalize or default_surface_key  # ADR-0067: domain-neutral, injectable
+
+    def _index_surface(self, surface: str, entity_id: EntityId) -> None:
+        key = self._normalize(surface)
+        if key:
+            self._index.setdefault(key, entity_id)
+
+    def add(self, record: RegistryRecord) -> None:
+        self._by_id[record.entity_id.value] = record
+        self._index_surface(record.canonical_name, record.entity_id)
+        if record.ticker:
+            self._index_surface(record.ticker, record.entity_id)
+        for alias in record.aliases:
+            self._index_surface(alias, record.entity_id)
+
+    def get(self, entity_id: EntityId) -> Optional[RegistryRecord]:
+        return self._by_id.get(entity_id.value)
+
+    def resolve(self, surface_form: str) -> Optional[EntityId]:
+        """The canonical `entity_id` for a known surface form, or `None` (closed-world)."""
+        return self._index.get(self._normalize(surface_form))
+
+    def __len__(self) -> int:
+        return len(self._by_id)
+
+    def __contains__(self, entity_id: EntityId) -> bool:
+        return entity_id.value in self._by_id