rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/registry.py

@@ -0,0 +1,262 @@
+"""The capability registration seam (FR-S.5, contract use).
+
+Two registrations from one key, the capability's FR-C / FR-I / FR-Q name (see the "ARD registration"
+note in tasks.md):
+
+- **Internal registration:** a built capability is registered by its name with its contract, so the
+  MCP skill surface (T31) can expose it.
+- **ARD registration:** registration also emits an ARD manifest *skeleton* (RegistryEntry-shaped,
+  the ADR-0005 mirror in `ard.py`) that GraphWright's compiler discovers and binds. The name is the
+  single shared key and the URN anchor, so the internal registry and the ARD manifest speak one
+  vocabulary. The `name` must be identical to the capability's name in the shared spec (the
+  cross-spec join key the Orchestration Spec binds against).
+
+**Kind is explicit per capability** (no default), following the binding rule (docs/adr/0003):
+`mcp_tool` crosses the MCP boundary (query-side governed skills, FR-S.5); `function` is an in-process
+graph-node call (parser, embedder, reranker, fusion); `agent_skill` is loaded knowledge (RLM
+chunking / synthesis, the RLM skill), not callable. A capability that fits none of the six kinds is
+flagged, not forced.
+
+**The emitted skeleton is a DRAFT.** Its representative queries (2-5, required by the schema) and
+trust attestations are authored at the capability's own task via `ManifestSkeleton.author(...)`,
+which returns the complete, validated `RegistryEntry` for the loadable path. A draft is never a
+`RegistryEntry` and must be kept out of the loadable registry directory: GraphWright's
+`RegistryStore` globs `*.json` non-recursively at the root, so drafts belong in a `staging/`
+subdirectory (never globbed) until authored. Nothing, including the compiler's glob, ever loads a
+partial as if it were registered.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.ard import (
+    CALLABLE_KINDS,
+    MEDIA_TYPE_BY_KIND,
+    URN_NAMESPACE,
+    URN_PUBLISHER,
+    ArdEnvelope,
+    Attestation,
+    CapabilityInterface,
+    EntryKind,
+    GovernanceBlock,
+    RegistryEntry,
+    ResponseBounds,
+    SkillRuntime,
+    TrustManifest,
+)
+
+# The ARD URN is domain-anchored (ARD v0.9 4.2.1): urn:air:<publisher>:<namespace>:<name>. The
+# publisher and namespace are the single source in ard.py (dreamai.io / rag_wright).
+_DEFAULT_OWNER = "dreamai.io"
+
+# The canonical capability slugs are the cross-spec join keys (SPEC.md section 5, "FR-C canonical
+# slugs"). The slug is the semantic capability name, never a requirement id (`hybrid_search`, never
+# `fr-c-3`), so it survives spec renumbering. SPEC.md is authoritative; this frozenset mirrors it so
+# registration rejects a name that is not a canonical capability (a typo, a requirement id, or an
+# invented name) — the same shared-vocabulary discipline as the ARD schema mirror. Adding a
+# capability updates both. FR-C.9 is a single slug (`generation`): reasoning, generation, and
+# vision-to-text are one capability, bound at whichever node needs them.
+CANONICAL_CAPABILITY_SLUGS: frozenset[str] = frozenset(
+    {
+        "graph_extraction",  # FR-C.6
+        "entity_disambiguation",  # FR-C.7 (canonicalize: normalize/reject/cluster; the T23b stage)
+        "entity_resolution",  # FR-C.7 (closed-world linking to EDGAR CIK)
+        "ontology_registry_derivation",  # FR-C.8 (foundation derivation: slug, but no ARD manifest)
+        "generation",  # FR-C.9 (grounded/cited/abstaining answer generation)
+        "vision_to_text",  # agent_skill: FR-C.9 single vision-language act (SKILL.md); split from generation (ADR-0014), SKILL-SPLIT
+        "rlm_chunking",  # FR-I.1 (applies the RLM skill; dynamic RLM discoverer -> agent_skill)
+        "rlm_synthesis",  # FR-Q.5 (applies the RLM skill)
+        "rlm_method",  # FR-C.10 (the shared RLM method skill, if registered)
+        "okf_compile",  # FR-K.1-K.4 (foundation derivation: slug, but no ARD manifest; T46)
+        "okf_navigate",  # FR-K.6 (query-discovered traversal: slug + ARD manifest; T50)
+        # --- CAP-REG-2: the built contract-KG capabilities ---
+        "typed_value_normalization",  # function: canonicalization + subsumption (KG-5a)
+        "extraction_grounding_judge",  # function: ADR-0028 lexical grounding gate
+        "extraction_semantic_judge",  # agent_skill: ADR-0040 Layer 3 verify-or-refute reading (SKILL.md); SKILL-SPLIT
+        "extraction_semantic_gate",  # function: applies the semantic-judge skill + AMBIGUOUS downgrade (deterministic)
+        "intra_document_scoped_query",  # function: intra-contract scoped KG serving (Leg A)
+        "clause_disambiguation",  # function: disambiguation by property (Leg A)
+        "clause_function_classification",  # model: LegalBERT function classifier (T56)
+        "clause_property_classification",  # model: the 29-dim best-of-both property classifier fleet (ADR-0115/0116, EP-RT-1)
+        "jev_decision",  # model: generic Jev System-1 typed-decision client (OpenRouter Decisions API), ADR-0119; async/IO-bound
+        "query_function_classification",  # agent_skill: taxonomy-constrained query->function (KG-5e)
+        # --- CAP-REG-3: the KG-primary retrieval core (packaged out of eval/kg_primary.py) ---
+        "span_relevance_judgment",  # agent_skill: per-span relevance VERDICT (span x condition -> relevant/not/uncertain); issue 0023, SKILL-SPLIT
+        # --- KG-7: the Party<->Contract unifying link over the one contract KG (ADR-0036) ---
+        "clause_exception_linking",  # function: IsExceptionTo edges (Uncapped -> Cap carve-out) by proximity (ADR-0044)
+        # --- LG-1/LG-2: hardened LangGraph subgraphs ---
+        "typed_clause_extraction",  # subgraph: extract -> adapt -> reground -> escalate -> [HITL] -> dead-letter
+        "query_constraint_extraction",  # subgraph: query-side typed constraint extraction (graceful-empty)
+        # --- LG-3: composite pipeline subgraphs (compose the component subgraphs + registered capabilities) ---
+        "relational_qa",  # subgraph: graph_query -> chunk_read -> generate_answer (entity question -> cited answer)
+        "intra_document_qa",  # subgraph: scoped KG query -> generate_answer (contract + question -> cited answer)
+        "typed_property_retrieval",  # subgraph: front-door + property_boosted_retrieval (Leg B, LEGB-SUBGRAPH). THE
+        #   corpus-wide function+property retrieval leg; retired the redundant cross_corpus_retrieval (inferior pool)
+        "contract_ingestion_pipeline",  # subgraph: generic corpus ingest (chunk->extract->resolve->write->link)
+        # --- Compliance module rung 1 (roadmap §13): the ad-compliance engine ---
+        "requirement_extraction",  # subgraph: extract(docling-graph, multi-call) -> adapt; regulatory section -> Requirement[] (CC-2, SKILL-SPLIT)
+        "requirement_adaptation",  # function: ExtractedRegulationSection -> validated Requirement[] (deterministic)
+        "claim_extraction",  # agent_skill: single LLM extraction act (ad -> ExtractedAd); SKILL-SPLIT
+        "claim_adaptation",  # function: ExtractedAd -> validated Claim[] (deterministic)
+        "compliance_judgment",  # agent_skill: single LLM judgment act ((claim, requirement) -> verdict); SKILL-SPLIT
+        "compliance_finding_assembly",  # function: raw verdict + inputs -> cited ComplianceFinding (deterministic)
+        "compliance_ingestion",  # subgraph: regulatory corpus -> Requirement KG (CC-5)
+        "compliance_check",  # subgraph: subject doc x requirements -> cited findings + gap matrix (CC-6)
+        "compliance_check_mcp",  # mcp_tool: the discoverable MCP-tool surface of compliance_check (MCP-PROTO)
+        "intra_document_qa_mcp",  # mcp_tool: the discoverable MCP-tool surface of intra_document_qa (MCP-PROTO B1)
+        "relational_qa_mcp",  # mcp_tool: the discoverable MCP-tool surface of relational_qa (MCP-PROTO B2)
+        "typed_property_retrieval_mcp",  # mcp_tool: the MCP-tool surface of typed_property_retrieval (MCP-PROTO B3)
+    }
+)
+
+
+def capability_urn(name: str) -> str:
+    """The domain-anchored ARD URN for a capability name (urn:air:dreamai.io:rag_wright:<name>)."""
+    return f"urn:air:{URN_PUBLISHER}:{URN_NAMESPACE}:{name}"
+
+
+class ManifestSkeleton(BaseModel):
+    """A DRAFT ARD manifest: the fields registration can derive, minus the authored fields.
+
+    Not loadable as a `RegistryEntry` (it has no representative queries yet). `author(...)` fills the
+    authored fields and returns the complete, validated `RegistryEntry`.
+    """
+
+    name: str
+    kind: EntryKind
+    identifier: str  # the URN
+    media_type: str
+    display_name: str
+    response_bounds: Optional[ResponseBounds] = None  # present for callable kinds only
+    owner: str = _DEFAULT_OWNER
+    description: Optional[str] = None
+    tags: list[str] = []
+
+    def author(
+        self,
+        representative_queries: list[str],
+        *,
+        attestations: Optional[list[Attestation]] = None,
+        identity: Optional[str] = None,
+        identity_type: str = "domain",
+        golden_eval_ref: Optional[str] = None,
+        requires: Optional[list[str]] = None,
+        skill_runtime: Optional[SkillRuntime] = None,
+        capability_interface: Optional[CapabilityInterface] = None,
+        description: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+    ) -> RegistryEntry:
+        """Author the draft into a complete, validated `RegistryEntry` for the loadable path.
+
+        `representative_queries` (2-5) and any trust `attestations` are the fields that could not be
+        derived at registration; the schema validators enforce them. `capability_interface` is the
+        optional GraphWright vendor extension (ADR-0030), declared per capability at its own task.
+        """
+        envelope = ArdEnvelope(
+            identifier=self.identifier,
+            display_name=self.display_name,
+            type=self.media_type,
+            representative_queries=representative_queries,
+            trust_manifest=TrustManifest(
+                identity=identity or self.identifier,
+                identity_type=identity_type,
+                attestations=attestations or [],
+            ),
+            description=description if description is not None else self.description,
+            tags=tags if tags is not None else self.tags,
+        )
+        return RegistryEntry(
+            kind=self.kind,
+            envelope=envelope,
+            response_bounds=self.response_bounds,
+            requires=requires or [],
+            skill_runtime=skill_runtime,
+            capability_interface=capability_interface,
+            golden_eval_ref=golden_eval_ref,
+            governance=GovernanceBlock(owner=self.owner),
+        )
+
+
+@dataclass(frozen=True)
+class CapabilityRegistration:
+    """One registered capability: its name, kind, contract, and its draft ARD manifest skeleton."""
+
+    name: str
+    kind: EntryKind
+    contract: type[BaseModel]
+    skeleton: ManifestSkeleton
+
+
+class CapabilityRegistry:
+    """An in-process registry of built capabilities, keyed by the capability name (FR-S.5)."""
+
+    def __init__(self) -> None:
+        self._by_name: dict[str, CapabilityRegistration] = {}
+
+    def register(
+        self,
+        name: str,
+        *,
+        contract: type[BaseModel],
+        kind: EntryKind,
+        display_name: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        response_bounds: Optional[ResponseBounds] = None,
+    ) -> CapabilityRegistration:
+        """Register a capability by name with its contract and (explicit) kind, emitting its ARD
+        skeleton. Rejects a malformed name, an unknown kind, or a duplicate registration."""
+        if name not in CANONICAL_CAPABILITY_SLUGS:
+            raise ValueError(
+                f"{name!r} is not a canonical capability slug (SPEC.md section 5, FR-C canonical "
+                f"slugs); register under the exact slug, one of {sorted(CANONICAL_CAPABILITY_SLUGS)}"
+            )
+        if kind not in MEDIA_TYPE_BY_KIND:
+            raise ValueError(
+                f"unknown capability kind {kind!r}; must be one of {sorted(MEDIA_TYPE_BY_KIND)} "
+                "(flag a capability that fits none of the six rather than forcing it)"
+            )
+        if name in self._by_name:
+            raise ValueError(f"capability {name!r} is already registered (duplicate)")
+
+        if kind in CALLABLE_KINDS:
+            bounds = response_bounds or ResponseBounds()
+        else:  # agent_skill is loaded, not called
+            if response_bounds is not None:
+                raise ValueError(f"kind {kind!r} is not callable and must not declare response_bounds")
+            bounds = None
+
+        skeleton = ManifestSkeleton(
+            name=name,
+            kind=kind,
+            identifier=capability_urn(name),
+            media_type=MEDIA_TYPE_BY_KIND[kind],
+            display_name=display_name or name,
+            response_bounds=bounds,
+            description=description,
+            tags=tags or [],
+        )
+        registration = CapabilityRegistration(
+            name=name, kind=kind, contract=contract, skeleton=skeleton
+        )
+        self._by_name[name] = registration
+        return registration
+
+    def get(self, name: str) -> CapabilityRegistration:
+        """The registration for a name, or raise `KeyError` if the name is unknown."""
+        if name not in self._by_name:
+            raise KeyError(f"no capability registered under {name!r}")
+        return self._by_name[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._by_name
+
+    def __len__(self) -> int:
+        return len(self._by_name)
+
+    def names(self) -> list[str]:
+        return sorted(self._by_name)

rag_wright/capabilities/remote_encoders.py

@@ -0,0 +1,94 @@
+"""MS1-6 (MODAL-STACK-1, ADR-0039): HTTP-client adapters that route the query-side encoders to the co-located
+A100 GPU-services stack (`scripts/modal_stack_a100.py`).
+
+The LLM surfaces route to vLLM-Granite via the model seam (`RAG_SERVING`, MS1-1/3); BGE-M3 embed + LegalBERT
+classify are DIRECT classes, not through the seam, so they get their own remote adapters here. Each matches
+the local interface it replaces (`embedding.Embedder` / `LegalBertFunctionClassifier`), so it drops into the
+same query seam -- the product then runs the query's non-LLM GPU work (embed + classify) on the SAME A100 as
+vLLM, the whole point of D2. Selected by the `STACK_URL` env (mirroring the LLM's `RAG_SERVING` switch); unset
+-> the local in-process encoders. `post` is injected so the adapters are hermetically testable (no network).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from typing import Any, Callable
+
+
+def _post_json(url: str, payload: dict, timeout: int = 120) -> dict:
+    req = urllib.request.Request(
+        url, data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"}, method="POST")
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read())
+
+
+class RemoteBGEEmbedder:
+    """BGE-M3 dense/sparse encode via the A100 `/embed` endpoint. Matches `embedding.BGEM3Embedder`
+    (encode_dense / encode_sparse / encode_batch), producing vectors in the SAME space as the KG's stored
+    span vectors (verified byte-identical in MS1-5b)."""
+
+    def __init__(self, base_url: str, *, post: Callable[..., dict] = _post_json) -> None:
+        self._url = base_url.rstrip("/") + "/embed"
+        self._post = post
+
+    def encode_dense(self, text: str) -> list[float]:
+        return self._post(self._url, {"text": text})["dense"][0]
+
+    def encode_sparse(self, text: str) -> dict[int, float]:
+        return {int(k): float(v) for k, v in self._post(self._url, {"text": text})["sparse"][0].items()}
+
+    def encode_batch(self, texts: list[str]) -> tuple[list[list[float]], list[dict[int, float]]]:
+        out = self._post(self._url, {"texts": list(texts)})
+        sparse = [{int(k): float(v) for k, v in s.items()} for s in out["sparse"]]
+        return out["dense"], sparse
+
+
+class RemoteLegalBertClassifier:
+    """LegalBERT function classification via the A100 `/classify` endpoint. Matches
+    `LegalBertFunctionClassifier` (classify / classify_topk)."""
+
+    def __init__(self, base_url: str, *, post: Callable[..., dict] = _post_json) -> None:
+        self._url = base_url.rstrip("/") + "/classify"
+        self._post = post
+
+    def classify(self, texts: list[str], *, batch_size: int = 32) -> list[str]:
+        if not texts:
+            return []
+        return self._post(self._url, {"texts": list(texts)})["labels"]
+
+    def classify_topk(self, texts: list[str], *, k: int = 2, batch_size: int = 32) -> list[list[str]]:
+        if not texts:
+            return []
+        return self._post(self._url, {"texts": list(texts), "k": k})["topk"]
+
+
+def stack_url() -> str | None:
+    """The co-located A100 stack base URL from `STACK_URL` (the query-encoder serving switch), or None (local)."""
+    return os.getenv("STACK_URL")
+
+
+def query_embedder(*, post: Callable[..., dict] = _post_json) -> Any:
+    """The query-side embedder: the remote A100 `/embed` adapter when `STACK_URL` is set, else the local
+    in-process `BGEM3Embedder` (dev/default). One env (`STACK_URL`) moves the query's embed onto the A100."""
+    url = stack_url()
+    if url:
+        return RemoteBGEEmbedder(url, post=post)
+    from rag_wright.capabilities.embedding import BGEM3Embedder
+
+    return BGEM3Embedder()
+
+
+def query_classifier(model_path: Any = None, *, post: Callable[..., dict] = _post_json) -> Any:
+    """The query-side function classifier: the remote A100 `/classify` adapter when `STACK_URL` is set, else
+    the local in-process `LegalBertFunctionClassifier` loaded from `model_path`."""
+    url = stack_url()
+    if url:
+        return RemoteLegalBertClassifier(url, post=post)
+    from pathlib import Path
+
+    from rag_wright.spans.legalbert_classifier import LegalBertFunctionClassifier
+
+    return LegalBertFunctionClassifier.load(Path(model_path or "data/models/legalbert_function"))

rag_wright/capabilities/requirement_extraction.py

@@ -0,0 +1,247 @@
+"""CC-2 (compliance §13), SKILL-SPLIT: the extraction ACT + the adaptation FUNCTION for `requirement_extraction`.
+
+Per the capability-architecture rubric, `requirement_extraction` is a SUBGRAPH (its `auto/dense` extraction is
+MULTI-LLM-call; the extract -> adapt chaining is the deterministic workflow). This module holds the subgraph's
+two pieces:
+
+- **the extraction ACT** (`extract_regulation_section`) -- the docling-graph schema-driven extraction using the
+  co-located skill asset `skills/requirement_extraction/template.py` (ExtractedRegulationSection). Runs `"auto"`
+  (dense on long sections, skeleton-then-fill). The subgraph's extract node.
+- **`requirement_adaptation` (function)** -- `to_requirements`: DETERMINISTIC, no model. Maps the raw extraction
+  to validated `Requirement`s (deontic vocab coercion -> AMBIGUOUS; off-vocab claim_type dropped; blank skipped;
+  citation = the section; content-hash id). The subgraph's adapt node.
+
+The subgraph itself (extract -> adapt, hardened) is `subgraphs/requirement_extraction.py`. The template lives
+with the skill (an Agent-Skill asset), re-exported here for consumers/tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable
+
+from rag_wright.capabilities.dg_extraction import aextract_parties, extract_parties
+from rag_wright.contracts.compliance import ClaimType, Constraint, DeonticType, Requirement
+from rag_wright.contracts.provenance import ConfidenceTag
+from rag_wright.skills.requirement_extraction.template import (  # the skill's schema asset
+    ExtractedRegulationSection,
+    ExtractedRequirement,
+)
+
+__all__ = ["ExtractedRegulationSection", "ExtractedRequirement", "extract_regulation_section",
+           "ajev_extract_regulation_section", "operative_rule_spans", "to_requirements",
+           "register_requirement_adaptation"]
+
+
+def operative_rule_spans(text: str) -> list[tuple[str, str]]:
+    """CIC (ADR-0119 scaffolding): deterministically split a section's text into candidate rule spans (reusing the
+    engine's byte-faithful `segment_clause`), keep the OPERATIVE ones (carrying a deontic cue), and derive each
+    span's deontic_type from its cue (ttl-driven `deontic_type_of`). Returns `[(verbatim_span_text,
+    deontic_local_name)]`. NO LLM. This is the span-producer front end a decision model (`jev_decision`, ADR-0119)
+    judges per span; it is NOT wired into the live ingest extraction, which is unchanged."""
+    from rag_wright.ontology.loader import deontic_type_of
+    from rag_wright.spans.segment import segment_clause
+
+    out: list[tuple[str, str]] = []
+    for span in segment_clause("", text or ""):
+        span_text = span.text.strip()
+        deontic = deontic_type_of(span_text)
+        if deontic is not None:
+            out.append((span_text, deontic))
+    return out
+
+_CLAIM_TYPES = {c.value for c in ClaimType}
+_DEONTIC = {d.value for d in DeonticType}
+
+# --- CIC (ADR-0119): the Jev-decision extraction act -- deterministic spans + ONE Jev call/span (operative gate +
+# claim_types + actor), cue-deontic, verbatim text. The decision KNOWLEDGE (the operative rubric, the per-ClaimType
+# and per-ActorRole criteria) is authored in compliance_bridge.ttl and LOADED here (ADR-0066/0119), never hardcoded.
+# The few-shot GUIDANCE below is prompt-engineering overlay (code), not domain vocab. The open fields applicability
+# + evidence_standard are NOT produced here (open-vocab; a residual-LLM/ttl follow-up) -- for FTC the claim_types
+# ARE the applicability (claim_type constraints via `to_requirements`).
+_JEV_GUIDANCE = (
+    "Guidance: 'This supplement cures insomnia' -> efficacy, health; 'lasts 3x longer than Brand X' -> "
+    "performance, comparative; 'reduced to $9.99' -> pricing; 'as recommended by Dr. Smith' -> endorsement. "
+    "Actor: who the rule binds.\n\nRule:\n")
+
+
+def _jev_questions() -> dict:
+    """Build the Jev question-set from the ttl decision knowledge (ADR-0119): the operative rubric
+    (`load_operative_rubric`), the actor `choice` (`load_actor_role_criteria` + an 'other' catch-all), and one
+    `noul` per ClaimType (`load_claim_type_criteria`)."""
+    from rag_wright.ontology.loader import (
+        load_actor_role_criteria, load_claim_type_criteria, load_operative_rubric,
+    )
+
+    rub = load_operative_rubric()
+    actor_criteria = {**load_actor_role_criteria(), "other": "none of the above, multiple parties, or unspecified"}
+    q = {"operative": {"type": "noul", "instructions": rub["instructions"],
+                       "criteria": {"true": rub["true"], "false": rub["false"]}},
+         "actor": {"type": "choice", "instructions": "Who does this rule primarily bind?", "criteria": actor_criteria}}
+    for ct, desc in load_claim_type_criteria().items():
+        q[f"ct_{ct}"] = {"type": "noul", "instructions": f"Does this rule apply to {ct} advertising claims?",
+                         "criteria": {"true": desc, "false": f"not specifically about {ct}"}}
+    return q
+
+
+# --- ADR-0119: the GATED residual extraction for the OPEN fields (applicability + evidence_standard). These are
+# open-text, not closed decisions, so Jev cannot produce them; a tiny structured LLM call fills them ONLY for the
+# rules that carry a conditional/evidence cue (most rules skip it -> per-rule LLM stays near-zero).
+_COND_CUES = ("if ", "where ", "unless", "provided", "only if", "when ", "except")
+_EVID_CUES = ("substantiat", "evidence", "competent and reliable", "scientific", "proof")
+
+
+def _needs_residual(span_text: str) -> bool:
+    low = span_text.lower()
+    return any(c in low for c in _COND_CUES) or any(c in low for c in _EVID_CUES)
+
+
+async def _residual_open_fields(span_text: str, model_id: str) -> tuple[list[str], str]:
+    """Extract the OPEN fields (applicability conditions + evidence standard) of one rule via a tiny structured
+    LLM call (the model-profile seam). Gated by `_needs_residual`, so this runs only on the few rules that have a
+    conditional/evidence cue. Degrades to ([], '') on any failure (recall-first: never drop the rule)."""
+    from pydantic import BaseModel, Field
+
+    from rag_wright.models.seam import build_structured
+
+    class _Open(BaseModel):
+        applicability: list[str] = Field(
+            default_factory=list,
+            description="conditions the rule applies under, as 'dimension: value' (e.g. 'jurisdiction: California', "
+                        "'employee_class: hourly'); empty if the rule applies unconditionally")
+        evidence_standard: str = Field(
+            default="", description="the substantiation the rule requires, if any (e.g. 'competent and reliable scientific evidence')")
+
+    try:
+        out = await build_structured(model_id, _Open).ainvoke(
+            f"Extract the applicability conditions and the evidence standard of this regulatory rule, if any:\n{span_text}")
+        return list(out.applicability or []), (out.evidence_standard or "").strip()
+    except Exception:  # noqa: BLE001 - recall-first: open fields are best-effort, never fail the rule
+        return [], ""
+
+
+async def ajev_extract_regulation_section(
+    text: str, *, concurrency: int = 8, op_threshold: float | None = None, ct_threshold: float | None = None,
+    residual_model_id: str | None = None,
+) -> ExtractedRegulationSection:
+    """CIC (ADR-0119): the Jev-decision extraction act. Deterministic `operative_rule_spans` produces candidate
+    spans; ONE Jev call per span (routed through the capability layer, `jev_decision`) decides operative-gate +
+    actor + claim_types; deontic_type is the cue-rule; requirement_text is the verbatim span. Drops spans the Jev
+    operative gate rejects. Thresholds default from the decision-model profile (`op_threshold`/`multilabel`),
+    overridable here. applicability/evidence_standard are left empty here (see note)."""
+    from rag_wright.capabilities.invoke import capability_impl
+    from rag_wright.models.profiles import decision_profile
+
+    spans = operative_rule_spans(text)
+    if not spans:
+        return ExtractedRegulationSection(section="", requirements=[])
+    prof = decision_profile()
+    op_thr = prof.op_threshold if op_threshold is None else op_threshold
+    ct_thr = prof.multilabel_threshold if ct_threshold is None else ct_threshold
+    if residual_model_id is None:
+        from rag_wright.models.profiles import ModelRole, model_for
+        residual_model_id = model_for(ModelRole.STRUCTURED_REASONING)
+    jev = capability_impl("jev_decision")  # async (resources, inputs) -> decision body; store-independent
+    questions = _jev_questions()
+    ct_keys = [k[3:] for k in questions if k.startswith("ct_")]  # the ttl-driven ClaimType set
+    sem = asyncio.Semaphore(max(1, concurrency))
+
+    async def _one(span_text: str, deontic: str) -> ExtractedRequirement | None:
+        async with sem:
+            d = await jev(None, {"state": _JEV_GUIDANCE + span_text, "questions": questions})
+            ans = d["answers"]
+            if float(ans["operative"].get("noul", 0.0)) < op_thr:
+                return None  # Jev gate: not a binding rule -> drop (refines the cue-presence gate's precision)
+            claim_types = [ct for ct in ct_keys if float(ans[f"ct_{ct}"].get("noul", 0.0)) >= ct_thr]
+            # GATED residual: open fields only for rules with a conditional/evidence cue (most skip -> no LLM)
+            applicability, evidence = ([], "")
+            if _needs_residual(span_text):
+                applicability, evidence = await _residual_open_fields(span_text, residual_model_id)
+        return ExtractedRequirement(requirement_text=span_text, deontic_type=deontic,
+                                    actor=str(ans["actor"].get("choice", "")), claim_types=claim_types,
+                                    applicability=applicability, evidence_standard=evidence)
+    reqs = [r for r in await asyncio.gather(*(_one(t, d) for t, d in spans)) if r is not None]
+    return ExtractedRegulationSection(section="", requirements=reqs)
+
+
+def _coerce_deontic(raw: str) -> tuple[DeonticType, bool]:
+    """(DeonticType, ambiguous?) -- map the model's string to the closed vocab; an off-vocab value coerces to
+    OBLIGATION and flags AMBIGUOUS (a rule with an unreadable force is kept but marked, never dropped)."""
+    value = (raw or "").strip().lower()
+    if value in _DEONTIC:
+        return DeonticType(value), False
+    return DeonticType.OBLIGATION, True
+
+
+ExtractFn = Callable[..., Any]  # (text, model, *, template, **kw) -> ExtractedRegulationSection | None
+
+
+def extract_regulation_section(
+    text: str, *, model: Any, extract_fn: ExtractFn = extract_parties,
+    max_tokens: int = 2000, preamble_chars: int = 24_000, extraction_contract: str = "auto",
+) -> ExtractedRegulationSection | None:
+    """The extraction ACT (the requirement_extraction skill, docling-graph runtime): fill the skill's
+    `template.py` schema from a § section's text. `extraction_contract="auto"` -> dense (multi-call) on long
+    sections so rules are not silently self-rationed. `extract_fn` is injected for hermetic tests."""
+    return extract_fn(text, model, template=ExtractedRegulationSection,
+                      max_tokens=max_tokens, preamble_chars=preamble_chars,
+                      extraction_contract=extraction_contract)
+
+
+async def aextract_regulation_section(
+    text: str, *, model: Any, aextract_fn: Any = aextract_parties,
+    max_tokens: int = 2000, preamble_chars: int = 24_000, extraction_contract: str = "auto",
+) -> ExtractedRegulationSection | None:
+    """ASYNC (ADR-0057): the async twin of `extract_regulation_section` -- docling-graph extraction on the async
+    seam (`aextract_parties`, true wall-clock deadline via the injected client). `aextract_fn` injected for tests."""
+    return await aextract_fn(text, model, template=ExtractedRegulationSection,
+                             max_tokens=max_tokens, preamble_chars=preamble_chars,
+                             extraction_contract=extraction_contract)
+
+
+def to_requirements(extracted: ExtractedRegulationSection, *, source: str, section: str) -> list[Requirement]:
+    """`requirement_adaptation` (FUNCTION -- deterministic, no model): adapt an extracted section to validated
+    `Requirement`s. Off-vocab deontic -> AMBIGUOUS; off-vocab claim_type dropped; blank rule text skipped.
+    Citation = the section; id = the content-hash scheme."""
+    out: list[Requirement] = []
+    for item in extracted.requirements:
+        text = (item.requirement_text or "").strip()
+        if not text:
+            continue
+        deontic, ambiguous = _coerce_deontic(item.deontic_type)
+        # claim_type is the ADVERTISING reference (closed FTC vocab -> off-vocab dropped, unchanged).
+        scope = [Constraint(dimension="claim_type", value=ct.strip().lower())
+                 for ct in item.claim_types if ct.strip().lower() in _CLAIM_TYPES]
+        # P3a (Gap 2): generic 'dimension: value' applicability conditions for ANY policy domain -- kept
+        # RECALL-FIRST (an unknown customer dimension is NOT dropped; the query-side matcher is dimension-agnostic).
+        seen = {c.as_tuple() for c in scope}
+        for cond in getattr(item, "applicability", None) or []:
+            dim, sep, val = (cond or "").partition(":")
+            dim, val = dim.strip().lower(), val.strip().lower()
+            if not (sep and dim and val) or (dim, val) in seen:
+                continue
+            seen.add((dim, val))
+            scope.append(Constraint(dimension=dim, value=val))
+        out.append(Requirement(
+            requirement_id=Requirement.make_id(source, section, text),
+            source=source,
+            citation=f"§ {section}",
+            deontic_type=deontic,
+            actor=(item.actor or "").strip() or "unspecified",
+            applicability_scope=scope,
+            requirement_text=text,
+            evidence_standard=(item.evidence_standard or "").strip() or None,
+            confidence=ConfidenceTag.AMBIGUOUS if ambiguous else ConfidenceTag.EXTRACTED,
+        ))
+    return out
+
+
+def register_requirement_adaptation(registry) -> None:
+    """Register `requirement_adaptation` (FUNCTION -- deterministic): the raw ExtractedRegulationSection ->
+    validated `Requirement[]` (deontic coercion, off-vocab handling, citation, content-hash id). No model."""
+    registry.register(
+        "requirement_adaptation",
+        contract=Requirement,
+        kind="function",
+        display_name="Requirement adaptation (extracted section -> validated Requirements)",
+    )