rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/claim_extraction.py

@@ -0,0 +1,153 @@
+"""CC-3 (compliance §13 C-3), SKILL-SPLIT: subject ad -> `Claim[]`, split into a SKILL + a FUNCTION.
+
+Per the capability-architecture principle (`function` = deterministic/no-model; a single LLM act = an authored
+`agent_skill`; a workflow = `subgraph`), this is two capabilities:
+
+- **`claim_extraction` (agent_skill)** -- the claim-extraction METHOD, authored as `skills/claim_extraction/`
+  (SKILL.md + the `template.py` schema asset: `ExtractedAd`/`ExtractedClaim`). One docling-graph call (`direct`,
+  ads are short) fills the template. `extract_ad` is its runtime; `extract_fn` is injected for hermetic tests.
+- **`claim_adaptation` (function)** -- `to_claims`: DETERMINISTIC, no model. Maps the raw `ExtractedAd` to the
+  closed CC-1 `Claim` vocab (off-vocab claim_type kept-but-AMBIGUOUS -- a checkable assertion is never dropped),
+  attaches the span provenance + content-hash `claim_id`.
+
+`claim_extraction(...)` composes them (skill -> function) for callers. The schema lives with the skill (an
+Agent-Skill asset), re-exported here for consumers/tests.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from rag_wright.capabilities.dg_extraction import aextract_parties, extract_parties
+from rag_wright.contracts.compliance import Claim, ClaimType
+from rag_wright.contracts.provenance import ConfidenceTag
+from rag_wright.skills.claim_extraction.template import ExtractedAd, ExtractedClaim  # the skill's schema asset
+
+__all__ = ["ExtractedAd", "ExtractedClaim", "extract_ad", "aextract_ad", "to_claims", "claim_extraction",
+           "aclaim_extraction", "register_claim_extraction", "register_claim_adaptation"]
+
+_CLAIM_TYPES = {c.value for c in ClaimType}
+# off-vocab fallback: keep the claim (never drop a checkable assertion) but mark it AMBIGUOUS. EFFICACY is the
+# broadest "the product works" type; the AMBIGUOUS tag is what actually signals the uncertainty downstream.
+_FALLBACK_CLAIM_TYPE = ClaimType.EFFICACY
+
+
+def _coerce_claim_type(raw: str) -> tuple[ClaimType, bool]:
+    """(ClaimType, ambiguous?) -- map the model's string to the closed vocab; an off-vocab value keeps the
+    claim under the fallback type and flags AMBIGUOUS (never drop a real assertion)."""
+    value = (raw or "").strip().lower()
+    if value in _CLAIM_TYPES:
+        return ClaimType(value), False
+    return _FALLBACK_CLAIM_TYPE, True
+
+
+def _clean(v: str) -> str | None:
+    v = (v or "").strip()
+    return v or None
+
+
+def to_claims(extracted: ExtractedAd, *, source_doc: str) -> list[Claim]:
+    """`claim_adaptation` (FUNCTION -- deterministic, no model): adapt an extracted ad to validated `Claim`s.
+    Off-vocab claim_type -> fallback + AMBIGUOUS; blank assertion skipped. `claim_id` uses the content-hash
+    scheme; the (source_doc, assertion) is the span cite."""
+    from rag_wright.contracts.compliance import Constraint
+
+    out: list[Claim] = []
+    for index, item in enumerate(extracted.claims):
+        text = (item.assertion_text or "").strip()
+        if not text:
+            continue
+        claim_type, ambiguous = _coerce_claim_type(item.claim_type)
+        actor = _clean(item.actor)
+        # DEON-8: surface the ROLE actor as a dimension-agnostic Constraint on `.scope` (mirroring the generic
+        # `to_facts`), so the obligation actor gate (DEON-7) works on the ad path too. The typed `.actor` is kept.
+        scope = [Constraint(dimension="actor", value=actor.lower())] if actor else []
+        out.append(Claim(
+            fact_id=Claim.make_id(source_doc, index, text),
+            source_doc=source_doc,
+            claim_type=claim_type,
+            assertion_text=text,
+            scope=scope,
+            actor=actor,
+            subject_product=_clean(item.subject_product),
+            quantitative_value=_clean(item.quantitative_value),
+            disclosures_present=[d.strip() for d in item.disclosures_present if d and d.strip()],
+            evidence_referenced=bool(item.evidence_referenced),
+            medium=_clean(item.medium),
+            confidence=ConfidenceTag.AMBIGUOUS if ambiguous else ConfidenceTag.EXTRACTED,
+        ))
+    return out
+
+
+ExtractFn = Callable[..., Any]  # (text, model, *, template, **kw) -> ExtractedAd | None
+
+
+def extract_ad(
+    text: str, *, model: Any, extract_fn: ExtractFn = extract_parties,
+    max_tokens: int = 1500, preamble_chars: int = 8000, extraction_contract: str = "direct",
+) -> ExtractedAd | None:
+    """The `claim_extraction` SKILL's runtime: run the docling-graph extraction (the skill's `template.py`
+    schema) through the model seam and return the raw `ExtractedAd` (or None). Ads are short -> `direct`."""
+    return extract_fn(text, model, template=ExtractedAd,
+                      max_tokens=max_tokens, preamble_chars=preamble_chars,
+                      extraction_contract=extraction_contract)
+
+
+def claim_extraction(
+    text: str, *, model: Any, source_doc: str,
+    extract_fn: ExtractFn = extract_parties, max_tokens: int = 1500, preamble_chars: int = 8000,
+    extraction_contract: str = "direct",
+) -> list[Claim]:
+    """Compose the SKILL (extract_ad) and the FUNCTION (to_claims): extract the raw ad, then adapt to `Claim`s.
+    Returns [] if extraction yields nothing."""
+    extracted = extract_ad(text, model=model, extract_fn=extract_fn, max_tokens=max_tokens,
+                           preamble_chars=preamble_chars, extraction_contract=extraction_contract)
+    if extracted is None:
+        return []
+    return to_claims(extracted, source_doc=source_doc)
+
+
+async def aextract_ad(
+    text: str, *, model: Any, aextract_fn: Any = aextract_parties,
+    max_tokens: int = 1500, preamble_chars: int = 8000, extraction_contract: str = "direct",
+) -> ExtractedAd | None:
+    """ASYNC-C1 (ADR-0057): the async twin of `extract_ad` -- the claim-extraction docling-graph act 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=ExtractedAd,
+                             max_tokens=max_tokens, preamble_chars=preamble_chars,
+                             extraction_contract=extraction_contract)
+
+
+async def aclaim_extraction(
+    text: str, *, model: Any, source_doc: str, aextract_fn: Any = aextract_parties,
+    max_tokens: int = 1500, preamble_chars: int = 8000, extraction_contract: str = "direct",
+) -> list[Claim]:
+    """ASYNC-C1 (ADR-0057): the async twin of `claim_extraction` -- await the async extraction ACT, then the
+    deterministic `to_claims` adaptation. Same contract: [] if extraction yields nothing."""
+    extracted = await aextract_ad(text, model=model, aextract_fn=aextract_fn, max_tokens=max_tokens,
+                                  preamble_chars=preamble_chars, extraction_contract=extraction_contract)
+    if extracted is None:
+        return []
+    return to_claims(extracted, source_doc=source_doc)
+
+
+def register_claim_extraction(registry) -> None:
+    """Register `claim_extraction` as an AGENT_SKILL (CC-3): a single docling-graph LLM extraction act, authored
+    as `skills/claim_extraction/` (SKILL.md + the template.py schema). Typed output = `ExtractedAd`."""
+    registry.register(
+        "claim_extraction",
+        contract=ExtractedAd,
+        kind="agent_skill",
+        display_name="Claim extraction (subject ad -> checkable claims; authored skill)",
+    )
+
+
+def register_claim_adaptation(registry) -> None:
+    """Register `claim_adaptation` (FUNCTION -- deterministic): the skill's raw `ExtractedAd` -> validated
+    `Claim[]` (closed vocab, off-vocab kept-but-AMBIGUOUS, span provenance, content-hash id)."""
+    registry.register(
+        "claim_adaptation",
+        contract=Claim,
+        kind="function",
+        display_name="Claim adaptation (extracted ad -> validated Claims)",
+    )

rag_wright/capabilities/clause_exception_linking.py

@@ -0,0 +1,117 @@
+"""ADR-0044: the `IS_EXCEPTION_TO` derived carve-out relationship (exception clause -> the Cap clause it excepts).
+
+A single contract's liability structure is usually stored as TWO disconnected clauses -- a `Cap On Liability`
+clause (often without its carve-outs) and a separate, often property-less `Uncapped Liability` clause (the
+carve-out, e.g. "uncapped for negligence") -- with NO relationship between them. So a query like "how is
+liability capped, and under what conditions?" gets two contradictory-looking fragments and the generator
+abstains, instead of "capped at X, EXCEPT uncapped for negligence."
+
+This capability adds the missing link WITHOUT re-ingesting: a pure pass over the already-populated clauses (a derived-relationship
+linking pass over the existing KG) that writes `IsExceptionTo` edges. The signal is SYMBOLIC co-occurrence +
+POSITIONAL PROXIMITY: within a contract, an `Uncapped` clause whose operative span is within `window` characters
+of a `Cap` clause's span (~ the same liability section) is that cap's carve-out. Distant co-occurrence is NOT
+linked (probably an unrelated standalone uncapped clause). The link is **INFERRED** (a reasoned inference, not an
+extracted fact, FR-S.4): surfaced at query time and human-validatable, never a silent hard claim.
+
+Scope (ADR-0044): the edge type is general; only the cap<->uncapped pair is populated for now.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from pydantic import BaseModel
+
+from rag_wright.capabilities.registry import CapabilityRegistry
+from rag_wright.contracts.provenance import ConfidenceTag
+
+CAP_FUNCTION = "Cap On Liability"
+EXCEPTION_FUNCTION = "Uncapped Liability"
+DEFAULT_PROXIMITY_WINDOW = 3000  # chars between the two spans' ranges (~ one liability section); tunable
+
+
+class ClauseExceptionLink(BaseModel):
+    """One `IsExceptionTo` edge: the `exception_clause_id` (an Uncapped clause) is a carve-out/exception to the
+    `cap_clause_id` (a Cap clause) in `contract_id`. Confidence INFERRED -- a derived, reasoned link (FR-S.4)."""
+
+    exception_clause_id: str
+    cap_clause_id: str
+    contract_id: str
+    confidence: ConfidenceTag = ConfidenceTag.INFERRED
+
+
+class ClauseExceptionLinkResult(BaseModel):
+    """The capability's output: the derived `IsExceptionTo` links + the honest unlinked count."""
+
+    links: list[ClauseExceptionLink]
+    unlinked_exceptions: int  # Uncapped clauses with no in-window Cap clause (skipped, not linked)
+    contracts_processed: int
+
+
+def _gap(a: dict, b: dict) -> int:
+    """Character gap between two spans' [doc_start, doc_end] ranges (0 if they overlap)."""
+    a0, a1 = int(a.get("doc_start") or 0), int(a.get("doc_end") or 0)
+    b0, b1 = int(b.get("doc_start") or 0), int(b.get("doc_end") or 0)
+    if a1 < b0:
+        return b0 - a1
+    if b1 < a0:
+        return a0 - b1
+    return 0
+
+
+def derive_exception_links(
+    positions: list[dict], *, window: int = DEFAULT_PROXIMITY_WINDOW,
+    cap_function: str = CAP_FUNCTION, exception_function: str = EXCEPTION_FUNCTION,
+) -> ClauseExceptionLinkResult:
+    """Pure: within each contract, link each `exception_function` clause to the NEAREST `cap_function` clause
+    whose operative span is within `window` chars (proximity ~ same section) -> an INFERRED `IsExceptionTo` link.
+    A distant or cap-less exception clause is counted `unlinked`, never linked to a far cap (that would be a
+    false carve-out). One link per (exception, cap) pair. `positions`: rows with {clause_id, function,
+    contract_id, doc_start, doc_end}."""
+    by_contract: dict[str, dict[str, list[dict]]] = defaultdict(lambda: {"cap": [], "exc": []})
+    for p in positions:
+        bucket = by_contract[p["contract_id"]]
+        if p["function"] == cap_function:
+            bucket["cap"].append(p)
+        elif p["function"] == exception_function:
+            bucket["exc"].append(p)
+
+    links: list[ClauseExceptionLink] = []
+    unlinked = 0
+    for contract_id, bucket in by_contract.items():
+        caps = bucket["cap"]
+        if not caps:  # uncapped clauses but no cap clause in this contract -> nothing to except
+            unlinked += len(bucket["exc"])
+            continue
+        for exc in bucket["exc"]:
+            nearest = min(caps, key=lambda cap: _gap(exc, cap))
+            if _gap(exc, nearest) <= window:
+                links.append(ClauseExceptionLink(
+                    exception_clause_id=exc["clause_id"], cap_clause_id=nearest["clause_id"],
+                    contract_id=contract_id))
+            else:
+                unlinked += 1  # co-occurs but distant -> probably unrelated; do not link (no false carve-out)
+
+    return ClauseExceptionLinkResult(
+        links=links, unlinked_exceptions=unlinked, contracts_processed=len(by_contract))
+
+
+def clause_exception_linking(store: Any, *, window: int = DEFAULT_PROXIMITY_WINDOW) -> ClauseExceptionLinkResult:
+    """The registered capability (ADR-0044): read the Cap + Uncapped clause positions, derive the proximity-based
+    `IsExceptionTo` links, write them (idempotent, clears the layer first), and return the result. No re-ingest --
+    a derived-relationship pass over the existing KG."""
+    positions = store.clause_positions([CAP_FUNCTION, EXCEPTION_FUNCTION])
+    result = derive_exception_links(positions, window=window)
+    store.write_clause_exception_links(result.links)
+    return result
+
+
+def register_clause_exception_linking(registry: CapabilityRegistry) -> None:
+    """ADR-0044: register `clause_exception_linking` (function; the cap<->uncapped carve-out relationship)."""
+    registry.register(
+        "clause_exception_linking",
+        contract=ClauseExceptionLinkResult,
+        kind="function",
+        display_name="Clause exception linking (IsExceptionTo carve-out edges over the contract KG)",
+    )

rag_wright/capabilities/compliance_judgment.py

@@ -0,0 +1,322 @@
+"""CC-4 (compliance §13.2), SKILL-SPLIT: the judgment node, split into a SKILL + a deterministic FUNCTION.
+
+Per the capability-architecture principle (a `function` is deterministic and takes no model; a single LLM act is
+an authored `agent_skill`; a workflow is a `subgraph`), the judgment is two capabilities:
+
+- **`compliance_judgment` (agent_skill)** -- the LLM judgment METHOD, authored as `skills/compliance_judgment/
+  SKILL.md` and applied through the model seam (product = Granite, ADR-0039). Given one claim + one requirement
+  and ONLY the ad text, it returns a raw `JudgeVerdict` (verdict / rationale / confidence). `build_compliance_
+  judge_fn` is its runtime; `structured_factory` is injected for hermetic tests.
+- **`compliance_finding_assembly` (function)** -- `assemble_finding`: DETERMINISTIC, no model. Maps the raw
+  verdict to the closed vocab (unreadable/missing -> needs_review, the conservative default), attaches the
+  BOTH-SIDED citation FROM THE INPUTS (the model never authors a citation), and returns the `ComplianceFinding`.
+
+`compliance_judgment(...)` composes them (skill -> function) for callers; `judge_pairs` runs the composition
+concurrently (async + semaphore + LLM-CALL-TIMEOUT). The applying capability owns the guarantees the skill does
+not (verdict vocab, conservative default, citation) -- the SKILL.md teaches only the reading.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Awaitable, Callable, Optional
+
+from pydantic import BaseModel
+
+from rag_wright.contracts.compliance import (
+    CheckableFact,
+    Claim,
+    ComplianceFinding,
+    DeonticType,
+    Requirement,
+    Verdict,
+)
+from rag_wright.models.seam import build_structured
+from rag_wright.util.concurrent import map_concurrent
+
+_VERDICTS = {v.value for v in Verdict}
+_SKILL_PATH = Path(__file__).parents[1] / "skills" / "compliance_judgment" / "SKILL.md"  # advertising method
+# COMP-VERDICT-GENERIC: the DOMAIN-AGNOSTIC judgment method -- the base the advertising SKILL specializes.
+_GENERIC_SKILL_PATH = Path(__file__).parents[1] / "skills" / "generic_compliance_judgment" / "SKILL.md"
+
+
+class JudgeVerdict(BaseModel):
+    """The raw structured output of one judge call (the `compliance_judgment` SKILL's typed output). `verdict`
+    is a loose string mapped to the closed `Verdict` by the FUNCTION (an unreadable value -> needs_review);
+    citations are added from the inputs by the function, never authored here."""
+
+    verdict: str
+    rationale: str = ""
+    confidence: float = 0.0
+
+
+# judge_fn: (subject_fact, requirement) -> JudgeVerdict, or None if the judge could not rule (-> conservative
+# default). Accepts any `CheckableFact` (the advertising `Claim` is one).
+JudgeFn = Callable[[CheckableFact, Requirement], Optional[JudgeVerdict]]
+# ASYNC-C1 (ADR-0057): the async judge seam -- same signature, awaitable result (the model call gets a true
+# wall-clock deadline via build_structured's .ainvoke).
+AJudgeFn = Callable[[CheckableFact, Requirement], Awaitable[Optional[JudgeVerdict]]]
+
+# The per-call appendix bound onto the SKILL method (the static method teaches the reading; the specific
+# requirement + subject are appended at call time, the okf_navigate `_with_question` pattern).
+# COMP-VERDICT-GENERIC: split into a domain-agnostic BASE tail (requirement + subject assertion -- works for ANY
+# CheckableFact / domain) + an ADVERTISING enrichment line (claim_type / disclosures / evidence). The generic
+# judge uses only the base; the advertising judge appends the enrichment (behavior unchanged).
+_BASE_PROMPT_TAIL = (
+    "\n\nREQUIREMENT ({deontic}, {citation}; applies to {actor}):\n{requirement_text}\n\n"
+    "SUBJECT:\n{assertion}"
+)
+_AD_ENRICHMENT = "\n\nCLAIM SIGNALS: type={claim_type}; disclosures_present={disclosures}; evidence_referenced={evidence}"
+
+
+def _skill_body(path: Path) -> str:
+    """A SKILL.md body with its YAML frontmatter stripped -- the judge's system/method prompt."""
+    text = path.read_text(encoding="utf-8")
+    if text.startswith("---"):
+        marker = text.find("\n---", 3)
+        if marker != -1:
+            text = text[marker + 4 :]
+    return text.strip()
+
+
+def judgment_method() -> str:
+    """The ADVERTISING compliance-judgment method (skills/compliance_judgment/SKILL.md, FTC doctrine)."""
+    return _skill_body(_SKILL_PATH)
+
+
+def generic_judgment_method() -> str:
+    """COMP-VERDICT-GENERIC: the DOMAIN-AGNOSTIC judgment method (skills/generic_compliance_judgment/SKILL.md) --
+    no advertising doctrine, so the generic judge reasons about "the subject" in any domain."""
+    return _skill_body(_GENERIC_SKILL_PATH)
+
+
+def _base_tail(fact: CheckableFact, requirement: Requirement) -> str:
+    """The domain-agnostic judge appendix: the requirement + the subject assertion. Works for ANY CheckableFact.
+    issue 0044: the DEON-8 document signals (disclosure/evidence union) are appended here from `document_signals`
+    -- so the JUDGE still sees them (prompt unchanged), while `assertion_text` (and thus the citation) stays pure
+    document text. `document_signals` is '' for a plain fact, so the generic path is unaffected."""
+    return _BASE_PROMPT_TAIL.format(
+        deontic=requirement.deontic_type.value, citation=requirement.citation, actor=requirement.actor,
+        requirement_text=requirement.requirement_text, assertion=fact.assertion_text) \
+        + (getattr(fact, "document_signals", "") or "")
+
+
+# DEON-1 (issue 0012): the neuro-symbolic deontic framing -- the KG's deontic_type tells the judge HOW to reason.
+# An OBLIGATION is breached by ABSENCE: the subject text above is the document's relevant content (DEON judges an
+# obligation ONCE over the document, not per sentence), so the judge must DECIDE yes/no, not hedge to "unclear"
+# just because the required element is missing -- absence IS the violation.
+_OBLIGATION_FRAMING = (
+    "\n\nDEONTIC FRAMING -- this requirement is an OBLIGATION (it must be SATISFIED): the subject text above is the "
+    "document's relevant content, checked as a whole. Decide definitively: if the required element (e.g. the "
+    "disclosure/action) IS present, COMPLIANT; if it is ABSENT from this text, that is a VIOLATION -- a missing "
+    "required element is itself the breach. Do NOT answer needs_review merely because the element is absent.")
+
+
+def _deontic_framing(requirement: Requirement) -> str:
+    return _OBLIGATION_FRAMING if requirement.deontic_type is DeonticType.OBLIGATION else ""
+
+
+# DEON-9 (issue 0012): permission-as-defense -- the same-source PERMISSIONS linked to this O/F rule (carve-outs /
+# safe-harbors). The judge reasons over the rule AND its exceptions: a subject that falls within a permitted
+# carve-out is NOT a violation. Only apply an exception that genuinely fits the subject (never a blanket excuse).
+_DEFENSE_FRAMING = (
+    "\n\nEXCEPTIONS / DEFENSES (permitted carve-outs that may EXCUSE this rule):\n{defenses}\n"
+    "If the subject falls within one of these permitted exceptions, the rule is NOT violated -- rule COMPLIANT, "
+    "and say which exception applies. Only apply an exception that genuinely fits the subject.")
+
+
+def _defense_framing(requirement: Requirement) -> str:
+    defenses = getattr(requirement, "defenses", None) or []
+    if not defenses:
+        return ""
+    return _DEFENSE_FRAMING.format(defenses="\n".join(f"- {d}" for d in defenses))
+
+
+def _ad_signals(fact: CheckableFact) -> str:
+    """DEON-8: the ADVERTISING claim-signals line -- rendered only for a typed `Claim`. An obligation judged ONCE
+    (DEON-1) hands the judge a plain `CheckableFact` EVIDENCE BUNDLE with no claim_type; return '' so the ad judge
+    TOLERATES it (the bundle's disclosure signals ride in its text via DEON-8 Option 1) instead of crashing on a
+    missing attribute."""
+    ct = getattr(fact, "claim_type", None)
+    if ct is None:
+        return ""
+    return _AD_ENRICHMENT.format(
+        claim_type=ct.value, disclosures=fact.disclosures_present or "none", evidence=fact.evidence_referenced)
+
+
+def build_generic_judge_fn(model_id: str, *, structured_factory=build_structured) -> JudgeFn:
+    """COMP-VERDICT-GENERIC: the DOMAIN-AGNOSTIC judge -- rules a `(subject_fact, requirement)` pair on TEXT alone
+    using the GENERIC judgment method (no advertising doctrine; reasons about "the subject" in any domain), so it
+    gives a verdict in ANY compliance domain. Same conservative default as the advertising judge; the method +
+    the appendix (base tail only, no claim signals) differ."""
+    method = generic_judgment_method()
+
+    def judge(fact: CheckableFact, requirement: Requirement) -> Optional[JudgeVerdict]:
+        return structured_factory(model_id, JudgeVerdict).invoke(
+            method + _base_tail(fact, requirement) + _defense_framing(requirement) + _deontic_framing(requirement))
+
+    return judge
+
+
+def build_ageneric_judge_fn(model_id: str, *, structured_factory=build_structured) -> AJudgeFn:
+    """ASYNC-C1 (ADR-0057): the async twin of `build_generic_judge_fn` -- the DOMAIN-AGNOSTIC judge on the async
+    structured seam (`.ainvoke`, a true wall-clock deadline on the model call). Same method + base tail."""
+    method = generic_judgment_method()
+
+    async def judge(fact: CheckableFact, requirement: Requirement) -> Optional[JudgeVerdict]:
+        return await structured_factory(model_id, JudgeVerdict).ainvoke(
+            method + _base_tail(fact, requirement) + _defense_framing(requirement) + _deontic_framing(requirement))
+
+    return judge
+
+
+def build_compliance_judge_fn(model_id: str, *, structured_factory=build_structured) -> JudgeFn:
+    """The advertising `compliance_judgment` SKILL runtime: a Granite-backed judge `JudgeFn` through the model seam
+    (product = vLLM-Granite; ADR-0039). Base tail (requirement + subject) + the ADVERTISING claim signals
+    (claim_type / disclosures / evidence). Behavior unchanged from before the CheckableFact split.
+    `structured_factory` is injected for tests."""
+    method = judgment_method()
+
+    def judge(claim: Claim, requirement: Requirement) -> Optional[JudgeVerdict]:
+        prompt = (method + _base_tail(claim, requirement) + _ad_signals(claim)
+                  + _defense_framing(requirement) + _deontic_framing(requirement))
+        return structured_factory(model_id, JudgeVerdict).invoke(prompt)
+
+    return judge
+
+
+def build_acompliance_judge_fn(model_id: str, *, structured_factory=build_structured) -> AJudgeFn:
+    """ASYNC-C1 (ADR-0057): the async twin of `build_compliance_judge_fn` -- the advertising judge on the async
+    structured seam (`.ainvoke`, a true wall-clock deadline). Same method + base tail + claim signals."""
+    method = judgment_method()
+
+    async def judge(claim: Claim, requirement: Requirement) -> Optional[JudgeVerdict]:
+        prompt = (method + _base_tail(claim, requirement) + _ad_signals(claim)
+                  + _defense_framing(requirement) + _deontic_framing(requirement))
+        return await structured_factory(model_id, JudgeVerdict).ainvoke(prompt)
+
+    return judge
+
+
+def _to_verdict(raw: str) -> Verdict:
+    """Map the LLM's verdict string to the closed vocab; an unreadable value -> NEEDS_REVIEW (conservative)."""
+    value = (raw or "").strip().lower().replace("-", "_").replace(" ", "_")
+    return Verdict(value) if value in _VERDICTS else Verdict.NEEDS_REVIEW
+
+
+def assemble_finding(
+    claim: Claim, requirement: Requirement, ruling: Optional[JudgeVerdict]
+) -> ComplianceFinding:
+    """`compliance_finding_assembly` (FUNCTION -- deterministic, no model): map the skill's raw `JudgeVerdict`
+    (or None) to a `ComplianceFinding`. None or an off-vocab verdict conservatively defaults to `needs_review`;
+    the BOTH-SIDED citation is taken from the INPUTS (the model never authors a citation)."""
+    if ruling is None:
+        verdict, rationale, confidence = Verdict.NEEDS_REVIEW, "judge did not return a ruling", 0.0
+    else:
+        verdict = _to_verdict(ruling.verdict)
+        rationale = ruling.rationale
+        confidence = min(1.0, max(0.0, ruling.confidence))
+    # UNIFY-A / SEG-1: cite "doc {locator}: {assertion}" where the locator is the fact's structural path
+    # ("§ 4.2", "§ 4.2 ¶3", "§ 4.2 · bullet 2") when present, else "" -> the old "doc: assertion" (back-compat).
+    # Still input-authored (the model never writes the citation).
+    _loc = claim.locator()
+    _sec = f" {_loc}" if _loc else ""
+    return ComplianceFinding(
+        claim_id=claim.fact_id,
+        requirement_id=requirement.requirement_id,
+        verdict=verdict,
+        rationale=rationale,
+        citation_claim=f"{claim.source_doc}{_sec}: {claim.assertion_text}",  # issue 0044: doc text only, no signals
+        citation_requirement=f"{requirement.citation} ({requirement.requirement_id}): {requirement.requirement_text}",
+        citation_claim_kind=getattr(claim, "citation_kind", "verbatim"),  # issue 0044: verbatim vs assembled
+        confidence=confidence,
+    )
+
+
+def compliance_judgment(claim: Claim, requirement: Requirement, *, judge_fn: JudgeFn) -> ComplianceFinding:
+    """Compose the SKILL (LLM judgment) and the FUNCTION (deterministic assembly): run `judge_fn` then
+    `assemble_finding`. A None ruling conservatively defaults to `needs_review`. Citations come from the inputs."""
+    return assemble_finding(claim, requirement, judge_fn(claim, requirement))
+
+
+_JUDGE_TIMEOUT_S = float(os.environ.get("RAG_JUDGE_TIMEOUT_S", "90"))  # per-pair wall-clock bound (LLM-CALL-TIMEOUT)
+
+
+def judge_pairs(
+    pairs: list[tuple[Claim, Requirement]], *, judge_fn: JudgeFn, max_concurrency: int = 8,
+    timeout_s: float | None = _JUDGE_TIMEOUT_S,
+) -> list[ComplianceFinding]:
+    """Run the skill->function composition over many `(claim, requirement)` pairs concurrently (async +
+    semaphore, per the parallel-LLM rule). Order is preserved. CC-6 drives this over a subject doc's claims x
+    their applicable requirements.
+
+    `timeout_s` (LLM-CALL-TIMEOUT) bounds each judgment with a hard wall-clock deadline so a stalled provider
+    response never hangs the batch; a timed-out pair (map_concurrent -> None) becomes a conservative
+    needs_review finding (the same conservative default as a judge that could not rule)."""
+    results = map_concurrent(
+        pairs, lambda pair: compliance_judgment(pair[0], pair[1], judge_fn=judge_fn),
+        max_concurrency=max_concurrency, timeout_s=timeout_s,
+    )
+    return [
+        result if result is not None
+        else assemble_finding(claim, requirement, None)  # timed out -> conservative needs_review
+        for (claim, requirement), result in zip(pairs, results)
+    ]
+
+
+async def ajudge_pairs(
+    pairs: list[tuple[Claim, Requirement]], *, ajudge_fn: AJudgeFn, max_concurrency: int = 8,
+    timeout_s: float | None = _JUDGE_TIMEOUT_S, timeout_retries: int = 1,
+) -> list[ComplianceFinding]:
+    """ASYNC-C1 (ADR-0057): the async twin of `judge_pairs` -- run the async judge over many `(claim,
+    requirement)` pairs concurrently (asyncio.gather + Semaphore, the parallel-LLM rule), order preserved.
+
+    Matches `judge_pairs`/`map_concurrent_async` semantics exactly: each judgment is bounded by `timeout_s` (a
+    hard wall-clock deadline via `asyncio.timeout`); on the deadline the call is retried up to `timeout_retries`
+    times, then the pair becomes `None` -> a conservative needs_review finding. A NON-timeout judge error
+    propagates (the same as the sync path), so a genuine bug is never masked as needs_review."""
+    semaphore = asyncio.Semaphore(max_concurrency)
+
+    async def _rule(claim: Claim, requirement: Requirement) -> Optional[JudgeVerdict]:
+        if timeout_s is None:
+            return await ajudge_fn(claim, requirement)  # no wall-clock bound (the seam still bounds each call)
+        for attempt in range(timeout_retries + 1):
+            try:
+                async with asyncio.timeout(timeout_s):
+                    return await ajudge_fn(claim, requirement)
+            except (asyncio.TimeoutError, TimeoutError):
+                if attempt >= timeout_retries:
+                    return None  # give up -> conservative needs_review (a stalled provider never hangs the batch)
+        return None
+
+    async def _one(pair: tuple[Claim, Requirement]) -> ComplianceFinding:
+        claim, requirement = pair
+        async with semaphore:  # backpressure
+            ruling = await _rule(claim, requirement)
+        return assemble_finding(claim, requirement, ruling)
+
+    return list(await asyncio.gather(*(_one(pair) for pair in pairs)))
+
+
+def register_compliance_judgment(registry) -> None:
+    """Register `compliance_judgment` as an AGENT_SKILL (CC-4): a single grounded LLM judgment act, authored as
+    `skills/compliance_judgment/SKILL.md` and applied via the seam. Typed output = `JudgeVerdict`."""
+    registry.register(
+        "compliance_judgment",
+        contract=JudgeVerdict,
+        kind="agent_skill",
+        display_name="Compliance judgment (claim x requirement -> verdict; authored skill)",
+    )
+
+
+def register_compliance_finding_assembly(registry) -> None:
+    """Register `compliance_finding_assembly` (FUNCTION -- deterministic): the skill's raw verdict + the inputs
+    -> a cited `ComplianceFinding` (conservative default, both-sided citation from the inputs)."""
+    registry.register(
+        "compliance_finding_assembly",
+        contract=ComplianceFinding,
+        kind="function",
+        display_name="Compliance finding assembly (verdict + inputs -> cited finding)",
+    )