rag-wright 0.1.0__py3-none-any.whl

rag_wright/subgraphs/relational_qa.py

@@ -0,0 +1,165 @@
+"""LG-3a: `relational_qa` as a composite LangGraph subgraph -- the REFERENCE composite.
+
+Answers an entity question with a grounded, cited answer built from the GRAPH STRUCTURE itself (the standing
+rule: the graph is the relationship layer). No chunk-text rehydration: a relational fact IS the traversed edge.
+
+    START --> traverse [RetryPolicy]  (graph_query: entity -> cited relationship evidence, FR-C.5)
+                 |
+                 v
+             assemble  (graph_structural_evidence: each reached entity -> a cited relationship statement)
+                 |
+                 v
+             generate  (generate_answer: grounded/cited/abstaining answer, FR-Q.6)  --> END
+
+Why graph-structural, not chunk text: the CONTRACTS_WITH edges are co-party facts extracted from the contract
+preamble; their provenance `chunk_id` is a whole-document id whose text is not stored for retrieval. Rehydrating
+it would need a throwaway text store, and citing "a" same-relationship span would be a one-to-many guess. Instead
+the evidence is the relationship + the target entity, cited by the SOURCE CONTRACT (parsed from the edge's
+provenance chunk_id) -- verifiable and faithful, with nothing to rehydrate (A2, MCP-PROTO Phase A).
+
+Query-side posture (matches `query_constraint_extraction`, LG-2a): hardening applied JUDICIOUSLY.
+  - **traverse** is the only retried node (a graph/store IO blip is transient). On retry exhaustion it DEGRADES
+    to empty evidence rather than dead-lettering -- the generator then abstains, so the query survives.
+  - **assemble** is a pure, deterministic graph->evidence step (no store read -> no orphan, no dead_letter).
+  - **generate** enforces no-claim-without-a-citation in code (FR-Q.6): empty evidence abstains with no model
+    call; fabricated citations are dropped. Confidence tags surfaced by graph_query (FR-S.4) thread through.
+
+`traverse_fn` / `generate_fn` are dependency-injected so the graph is hermetically testable with stubs.
+`production_relational_qa` wires the real `graph_query` + `generate_answer`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Optional, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.runtime import Runtime
+
+from rag_wright.capabilities.answer_generator import EvidenceItem, GeneratedAnswer
+from rag_wright.capabilities.graph_query import GraphAnswer
+from rag_wright.ontology.contract_taxonomy import CONTRACTS_WITH  # this is a CONTRACT-reference leg (DD-5)
+from rag_wright.subgraphs.scaffold import DEFAULT_RETRY, business_span
+from rag_wright.subgraphs.typed_clause_extraction import TransientExtraction  # shared retryable-blip signal
+
+# traverse_fn: (start_entity_id, relationship_type, max_hops) -> GraphAnswer (must raise on a transient blip).
+# DD-5: relationship_type is an opaque edge-type string the caller names (graph_query is domain-free).
+TraverseFn = Callable[[str, str, int], GraphAnswer]
+# ASYNC-C1 (ADR-0057): generate_fn is async (the model call gets a true wall-clock deadline via the seam).
+GenerateFn = Callable[[str, list[EvidenceItem]], Awaitable[GeneratedAnswer]]
+
+DEFAULT_RELATIONSHIP = CONTRACTS_WITH  # the contract co-party edge (this is the contract-reference leg)
+
+
+class RelationalQAState(TypedDict, total=False):
+    query: str
+    start_entity_id: str
+    relationship_type: str
+    max_hops: int
+    graph_answer: GraphAnswer
+    evidence: list[EvidenceItem]
+    answer: GeneratedAnswer
+    dead_letter: Optional[dict]
+
+
+def graph_structural_evidence(graph_answer: GraphAnswer) -> list[EvidenceItem]:
+    """The relational evidence IS the graph structure. Each reached entity yields one cited fact per source
+    contract: "<start> <rel> <target> (per <contract>)", cited by the CONTRACT id parsed from the edge's
+    provenance chunk_id (`<source_doc_id>:<index>:<hash>` -> source_doc_id = contract_id) -- verifiable, with no
+    chunk text to rehydrate. Confidence = the path's first surfaced edge tag. Falls back to citing the target
+    entity_id when an edge carries no chunk provenance. First-wins/dedup on (target, citation)."""
+    start = graph_answer.start_entity_id
+    rel = graph_answer.relationship_type
+    items: list[EvidenceItem] = []
+    seen: set[tuple[str, str]] = set()
+    for ev in graph_answer.evidence:
+        conf = ev.confidences[0] if ev.confidences else None
+        contracts = sorted({cid.split(":")[0] for cid in ev.chunk_ids if cid}) or [ev.entity_id]
+        for cite in contracts:
+            key = (ev.entity_id, cite)
+            if key in seen:
+                continue
+            seen.add(key)
+            items.append(EvidenceItem(
+                chunk_id=cite,
+                text=f"{start} {rel} {ev.name} (entity {ev.entity_id}; per {cite})",
+                confidence=conf))
+    return items
+
+
+def build_relational_qa(traverse_fn: TraverseFn, generate_fn: GenerateFn, *, retry_policy: Any = DEFAULT_RETRY):
+    """Compile the `relational_qa` subgraph. `traverse_fn` / `generate_fn` are injected for hermetic testing;
+    the graph->evidence assembly is a pure deterministic node. `retry_policy` is the traverse node's policy."""
+    max_attempts = int(getattr(retry_policy, "max_attempts", 3))
+
+    def traverse(state: RelationalQAState, runtime: Runtime) -> RelationalQAState:
+        # node_attempt is 1-indexed; a transient blip re-raises so the RetryPolicy retries, EXCEPT on the
+        # final attempt where it degrades to EMPTY evidence (the generator abstains -- the query is never lost).
+        attempt = runtime.execution_info.node_attempt
+        start = state["start_entity_id"]
+        rel = state.get("relationship_type", DEFAULT_RELATIONSHIP)
+        with business_span("relational_qa.traverse", start_entity_id=start):
+            try:
+                graph_answer = traverse_fn(start, rel, state.get("max_hops", 1))
+            except Exception as exc:  # noqa: BLE001 - transient -> retry, or degrade to empty on exhaustion
+                if attempt >= max_attempts:
+                    return {"graph_answer": GraphAnswer(
+                        start_entity_id=start, relationship_type=rel, evidence=[])}
+                raise TransientExtraction(str(exc)) from exc
+        return {"graph_answer": graph_answer}
+
+    def assemble(state: RelationalQAState) -> RelationalQAState:
+        with business_span("relational_qa.assemble"):
+            return {"evidence": graph_structural_evidence(state["graph_answer"])}
+
+    async def generate(state: RelationalQAState) -> RelationalQAState:
+        with business_span("relational_qa.generate"):
+            return {"answer": await generate_fn(state["query"], state.get("evidence", []))}
+
+    g = StateGraph(RelationalQAState)
+    g.add_node("traverse", traverse, retry_policy=retry_policy)
+    g.add_node("assemble", assemble)
+    g.add_node("generate", generate)
+    g.add_edge(START, "traverse")
+    g.add_edge("traverse", "assemble")
+    g.add_edge("assemble", "generate")
+    g.add_edge("generate", END)
+    return g.compile()
+
+
+def production_relational_qa(*, store: Any, answer_model: Any):
+    """Wire the real `graph_query` + `generate_answer` into the composite (no text_store: the evidence is
+    graph-structural). Imports are lazy so the module stays import-light and hermetic (tests inject stubs)."""
+    from rag_wright.capabilities.answer_generator import agenerate_answer
+    from rag_wright.capabilities.graph_query import graph_query
+
+    def traverse(start: str, rel: str, max_hops: int) -> GraphAnswer:
+        # graph_query is domain-free and takes a generic edge-type string; this contract-reference leg passes the
+        # contract edge value (the contract vocab stays on the caller side, not in the generic primitive).
+        return graph_query(start, store=store, relationship_type=rel, max_hops=max_hops)
+
+    async def generate(query: str, evidence: list[EvidenceItem]) -> GeneratedAnswer:
+        return await agenerate_answer(query, evidence, model=answer_model)
+
+    return build_relational_qa(traverse, generate)
+
+
+def register_relational_qa(registry) -> None:
+    """LG-3a: register `relational_qa` (composite subgraph; graph_query -> graph-structural evidence ->
+    generate_answer)."""
+    registry.register(
+        "relational_qa",
+        contract=GeneratedAnswer,
+        kind="subgraph",
+        display_name="Relational QA (cited answer from graph traversal)",
+    )
+
+
+async def ainvoke(resources, inputs: dict):
+    """EP-CORE-2 (ADR-0118): the capability invoke factory (impl_ref target)."""
+    from rag_wright.capabilities.answer_generator import answer_model_for
+    from rag_wright.models.profiles import ModelRole
+
+    graph = production_relational_qa(store=resources._store,
+                                     answer_model=answer_model_for(resources.model_id(ModelRole.GENERAL)))
+    return await graph.ainvoke({"query": inputs["query"], "start_entity_id": inputs["start_entity_id"],
+                                "max_hops": inputs.get("max_hops", 1)})

rag_wright/subgraphs/requirement_extraction.py

@@ -0,0 +1,137 @@
+"""CC-2 (compliance §13), SKILL-SPLIT: the `requirement_extraction` SUBGRAPH.
+
+`requirement_extraction` is a SUBGRAPH, not a single-shot skill, because its docling-graph `auto/dense`
+extraction is MULTI-LLM-call (skeleton-then-fill) and the extract -> adapt chaining is a deterministic workflow
+(the rubric's rationale for a subgraph). A hardened LangGraph on `scaffold.py`:
+
+    START --> extract [RetryPolicy]   (the extraction ACT: docling-graph fills the skill's template.py schema)
+                |                       transient failure -> retry, exhaustion -> dead_letter
+                v
+              adapt --> END            (the requirement_adaptation FUNCTION: raw section -> validated Requirement[])
+
+`extract`/`adapt` are DI'd for hermetic tests. `run_requirement_extraction` invokes the compiled graph for a
+single section (used by the `compliance_ingestion` corpus driver, CC-5).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.runtime import Runtime
+
+from rag_wright.capabilities.requirement_extraction import aextract_regulation_section, to_requirements
+from rag_wright.contracts.compliance import Requirement
+from rag_wright.subgraphs.scaffold import DEFAULT_RETRY, business_span, dead_letter
+from rag_wright.subgraphs.typed_clause_extraction import TransientExtraction
+
+# extract_fn: section text -> raw ExtractedRegulationSection | None; adapt_fn: (extracted, source, section) -> Requirement[]
+ExtractSectionFn = Callable[[str], Any]
+AdaptFn = Callable[[Any, str, str], list]
+
+
+class RequirementExtractionFailed(Exception):
+    """COMP-ASYNC-1 (PROD-3 lossless, ADR-0050): the per-section requirement extraction FAILED (its subgraph
+    dead-lettered after retries) -- distinct from a genuine section with no requirements. Raised so the compliance
+    corpus driver can dead-letter the SECTION (visible in the report/job) instead of silently writing 0
+    requirements. `section`/`reason` carry the citation + the underlying error."""
+
+    def __init__(self, section: str, reason: str) -> None:
+        super().__init__(f"requirement extraction failed for section {section}: {reason}")
+        self.section = section
+        self.reason = reason
+
+
+class ReqExtractState(TypedDict, total=False):
+    text: str
+    source: str
+    section: str
+    pages: list  # issue 0043: the section's source page(s), stamped onto each extracted Requirement
+    bbox: Any  # issue 0043: best-effort (l, t, r, b) for a single-item section, else None
+    extracted: Any
+    requirements: list
+    dead_letter: Optional[dict]
+
+
+def build_requirement_extraction(
+    extract_fn: ExtractSectionFn, adapt_fn: AdaptFn, *, retry_policy: Any = DEFAULT_RETRY
+):
+    """Compile the requirement-extraction subgraph: extract[retry] -> adapt -> END. Both nodes DI'd for tests.
+    A transient extraction failure retries, then dead-letters the section (never raised) -> an empty result."""
+    max_attempts = int(getattr(retry_policy, "max_attempts", 3))
+
+    async def extract(state: ReqExtractState, runtime: Runtime) -> ReqExtractState:
+        section = state.get("section", "")
+        attempt = runtime.execution_info.node_attempt
+        with business_span("requirement_extraction.extract", section=section):
+            try:
+                return {"extracted": await extract_fn(state["text"])}  # ASYNC (ADR-0057): async extract seam
+            except Exception as exc:  # noqa: BLE001 - transient -> retry, or dead-letter on exhaustion
+                if attempt >= max_attempts:
+                    return {"dead_letter": dead_letter(
+                        "extract_failed", section=section, stage="extract", error=str(exc))}
+                raise TransientExtraction(str(exc)) from exc
+
+    async def adapt(state: ReqExtractState) -> ReqExtractState:
+        extracted = state.get("extracted")
+        if state.get("dead_letter") or extracted is None:
+            return {"requirements": []}
+        with business_span("requirement_extraction.adapt"):
+            reqs = adapt_fn(extracted, state["source"], state["section"])  # adapt is sync/CPU
+            # issue 0043: stamp the section's page provenance onto each Requirement (pages/bbox are not part of the
+            # requirement_id, so this never affects identity/idempotency). Empty pages when the corpus has no parse.
+            pages, bbox = list(state.get("pages") or []), state.get("bbox")
+            if pages or bbox is not None:
+                reqs = [r.model_copy(update={"pages": pages, "bbox": bbox}) for r in reqs]
+            return {"requirements": reqs}
+
+    g = StateGraph(ReqExtractState)
+    g.add_node("extract", extract, retry_policy=retry_policy)
+    g.add_node("adapt", adapt)
+    g.add_edge(START, "extract")
+    g.add_edge("extract", "adapt")  # adapt handles the dead-letter/None case (-> [])
+    g.add_edge("adapt", END)
+    return g.compile()
+
+
+def production_requirement_extraction(
+    *, model: Any, extraction_contract: str = "auto", extract_override: Optional[ExtractSectionFn] = None
+):
+    """Wire the real capabilities: extract = the docling-graph extraction ACT (skills/requirement_extraction/),
+    adapt = the `to_requirements` FUNCTION. `extract_override` injects a stub for hermetic driver tests."""
+    async def _extract(text: str) -> Any:
+        return await aextract_regulation_section(text, model=model, extraction_contract=extraction_contract)
+
+    return build_requirement_extraction(
+        extract_override or _extract,
+        lambda extracted, source, section: to_requirements(extracted, source=source, section=section),
+    )
+
+
+async def run_requirement_extraction(
+    text: str, *, model: Any, source: str, section: str, extract_override: Optional[ExtractSectionFn] = None,
+    pages: Optional[list] = None, bbox: Any = None, raise_on_failure: bool = False,
+) -> list[Requirement]:
+    """Invoke the requirement-extraction subgraph for one § section -> its `Requirement[]`.
+
+    Default (`raise_on_failure=False`, back-compat): `[]` whether the section genuinely has no requirements OR the
+    extraction dead-lettered. COMP-ASYNC-1 lossless: with `raise_on_failure=True`, a dead-letter (a real FAILURE,
+    not a genuine-empty section) RAISES `RequirementExtractionFailed` so the compliance corpus driver dead-letters
+    the section instead of silently writing 0 requirements. A genuine-empty section still returns []."""
+    graph = production_requirement_extraction(model=model, extract_override=extract_override)
+    result = await graph.ainvoke({"text": text, "source": source, "section": section,
+                                  "pages": pages or [], "bbox": bbox})  # issue 0043: policy page provenance
+    if raise_on_failure and result.get("dead_letter"):
+        raise RequirementExtractionFailed(section, str(result["dead_letter"].get("error", "extraction failed")))
+    return result.get("requirements", [])
+
+
+def register_requirement_extraction(registry) -> None:
+    """Register `requirement_extraction` as a SUBGRAPH (CC-2): the extract -> adapt workflow over one section.
+    Contract = `Requirement`."""
+    registry.register(
+        "requirement_extraction",
+        contract=Requirement,
+        kind="subgraph",
+        display_name="Requirement extraction (regulatory section -> deontic rules; subgraph)",
+    )

rag_wright/subgraphs/scaffold.py

@@ -0,0 +1,65 @@
+"""LG-0: the reusable pattern + primitives for hardened subgraph capabilities (LangGraph).
+
+A `subgraph` capability is a compiled `StateGraph` invoked as a subagent under a contract. Every RAG_Wright
+subgraph is built the same way so hardening is uniform and hermetic-testable:
+
+  - **Dependency-injected model/store** (no global clients) -> tests inject fakes, no live LLM/DB.
+  - A **RetryPolicy** (`DEFAULT_RETRY`) on LLM / IO nodes for transient failures (network, rate limit, 5xx).
+    Configure `retry_on` per node for that node's real transient exceptions -- LangGraph's default retry_on
+    does NOT retry `ValueError`/`OSError`/etc., so a provider error mapped to one of those needs an explicit
+    `retry_on` (or a dedicated transient exception).
+  - A conditional **ESCALATION** edge (cheap model -> stronger model, ADR-0028 Flash->Pro), bounded by an
+    attempt counter in state -- this is a routing decision, distinct from a retry of the same node.
+  - An optional `interrupt()`-based **HUMAN GATE** for low-confidence / high-stakes items.
+  - A **DEAD-LETTER** terminal: a bad item is dropped with a reason (never raised), so one item never kills a
+    batch (the "17% dead-lettered" lesson).
+
+**Observability (GraphWright contract, `temp/observability-contract.md`).** We do NOT build tracing, token
+counting, or a Langfuse client -- GraphWright installs global OpenTelemetry instrumentation (exporting to
+Langfuse or any swappable OTLP backend). Requirements every subgraph MUST meet to be observable for free:
+  - construct EVERY model through the LangChain seam (`models/seam.py::build_model`/`build_structured` ->
+    `ChatOpenAI`); those calls are auto-captured with token counts + latency;
+  - a **raw-SDK** call that bypasses LangChain (notably **docling-graph / LiteLLM** in `dg_extraction`, or any
+    sandboxed model call) is INVISIBLE to tracing -- wrap it in `observability.raw_llm_span(...)` +
+    `record_tokens(...)` on the ambient tracer (never a new provider);
+  - use `observability.business_span(...)` for optional domain spans; never manually span a LangChain call;
+  - propagate context across a boundary you introduce (separate process/worker/queue/custom async loop) with
+    `observability.inject_context` / `attach_context` -- std-lib threads are already carried by GraphWright.
+See `rag_wright.subgraphs.observability` (a dependency-free no-op seam when OTel is absent, e.g. in tests).
+
+`typed_clause_extraction` (LG-1) is the reference implementation; other subgraphs follow this shape.
+Grounding: the LangChain docs MCP (`mcp__docs-langchain__*`) + the framework index (langgraph AST); OTel via
+GraphWright's runtime.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langgraph.types import RetryPolicy
+
+# Re-exported so a subgraph author imports the pattern from one place. These wrap the AMBIENT OTel tracer per
+# the GraphWright observability contract; they never construct a provider/exporter or a Langfuse client.
+from rag_wright.subgraphs.observability import (  # noqa: F401
+    attach_context,
+    business_span,
+    inject_context,
+    otel_active,
+    raw_llm_span,
+    record_tokens,
+)
+
+# The shared retry for LLM / IO nodes. Backoff on transient failures; bounded attempts. Note LangGraph's
+# default `retry_on` already skips programmer errors (TypeError/ValueError/ImportError/...) and only retries
+# 5xx for requests/httpx -- so a node whose transient error surfaces as one of those must pass its own
+# `retry_on` when it adds the node (see the reference subgraph / LG-1).
+DEFAULT_RETRY = RetryPolicy(max_attempts=3, initial_interval=1.0)
+
+
+def dead_letter(reason: str, **fields: Any) -> dict:
+    """A terminal dead-letter record: the item is dropped with a `reason` (not raised) so the batch survives.
+
+    Put it on the subgraph state's `dead_letter` key; the caller filters out items that carry one. Extra
+    `fields` capture context (the offending id, the exception text, the node) for diagnosis.
+    """
+    return {"reason": reason, **fields}

rag_wright/subgraphs/semantic_chunking.py

@@ -0,0 +1,183 @@
+"""LG-2: `semantic_chunking` as a hardened, GRANULAR LangGraph subgraph.
+
+The single-call (non-agentic) chunker, expressed as explicit nodes -- the multi-step pipeline is the graph,
+not a hidden orchestrator:
+
+    gate --cached--> END
+      | (miss: load_document)
+      v
+    discover [RetryPolicy + error_handler -> dead-letter]  --dead_letter--> END
+      v
+    finalize (validate partition + _finalize_chunks)  --dead_letter--> END
+      v
+    summarize (async, concurrent per-chunk summaries)
+      v
+    manifest (build chunks + validate boundaries + write cache) --> END
+
+- **gate**: content-hash short-circuit -- a cached manifest is returned with no LLM call.
+- **discover**: the ONE LLM step (single-call boundary discovery). A transient blip is retried
+  (`TransientExtraction` -> DEFAULT_RETRY); on retry exhaustion the `error_handler` dead-letters the document
+  (skip it -- never lose the batch) rather than raising.
+- **finalize / manifest**: the deterministic layer, reused verbatim from `rlm_chunking` (`_finalize_chunks`,
+  `_validate_partition`, `_validate_boundaries`, `ChunkManifest`).
+- **summarize**: a sync node using `asyncio.run` for the concurrent per-chunk summaries (matches
+  `rlm_chunking.chunk`). `asyncio.run` copies the current contextvars context, so the OTel trace context is
+  preserved (it is NOT a context-detached loop); the summarizer goes through the LangChain seam
+  (auto-captured), and its `to_thread` fan-out is carried by GraphWright's threading instrumentation.
+- **observability**: `discover` is wrapped in `raw_llm_span` (raw-SDK), `summarize` in `business_span`.
+
+`discoverer` / `summarizer` are the same injected seams as `rlm_chunking.chunk`, so the graph is hermetically
+testable with the existing stubs. The default discoverer is the deterministic single-call one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any, Optional, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.runtime import Runtime
+
+from rag_wright.capabilities.parsing import ParsedDocument, load_document
+from rag_wright.capabilities.rlm_chunking import (
+    DEFAULT_SUMMARY_CONCURRENCY,
+    DEFAULT_TOKEN_CAP,
+    BoundaryDiscoverer,
+    BoundaryValidationError,
+    Chunk,
+    ChunkManifest,
+    SeamSummarizer,
+    SingleCallBoundaryDiscoverer,
+    Summarizer,
+    _chunk_offsets,
+    _estimate_tokens,
+    _finalize_chunks,
+    _summarize_all,
+    _validate_boundaries,
+    _validate_partition,
+)
+from rag_wright.contracts.identifiers import ChunkId
+from rag_wright.subgraphs.scaffold import DEFAULT_RETRY, business_span, dead_letter, raw_llm_span
+from rag_wright.subgraphs.typed_clause_extraction import TransientExtraction
+
+
+class SemanticChunkingState(TypedDict, total=False):
+    parsed: ParsedDocument
+    cache_dir: Path
+    token_cap: int
+    max_concurrency: int
+    document: Any
+    spans: list
+    texts: list
+    offsets: list
+    summaries: list
+    manifest: Optional[ChunkManifest]
+    dead_letter: Optional[dict]
+
+
+def _manifest_path(state: SemanticChunkingState) -> Path:
+    parsed = state["parsed"]
+    return state["cache_dir"] / f"{parsed.source_doc_id}.{parsed.content_hash[:16]}.chunks.json"
+
+
+def build_semantic_chunking(
+    discoverer: Optional[BoundaryDiscoverer] = None,
+    summarizer: Optional[Summarizer] = None,
+    *,
+    model_id: Optional[str] = None,
+    retry_policy: Any = DEFAULT_RETRY,
+):
+    """Compile the `semantic_chunking` subgraph. `discoverer` / `summarizer` are injected (defaulting to the
+    live single-call discoverer + seam summarizer), matching `rlm_chunking.chunk`. `retry_policy` is the
+    discover node's policy (overridable for fast tests)."""
+
+    discoverer = discoverer if discoverer is not None else SingleCallBoundaryDiscoverer(model_id)
+    summarizer = summarizer if summarizer is not None else SeamSummarizer()
+    max_attempts = int(getattr(retry_policy, "max_attempts", 3))
+
+    def gate(state: SemanticChunkingState) -> SemanticChunkingState:
+        path = _manifest_path(state)
+        if path.exists():  # content-hash gate: reuse, no LLM
+            return {"manifest": ChunkManifest.model_validate_json(path.read_text(encoding="utf-8"))}
+        state["cache_dir"].mkdir(parents=True, exist_ok=True)
+        return {"document": load_document(state["parsed"])}
+
+    def discover(state: SemanticChunkingState, runtime: Runtime) -> SemanticChunkingState:
+        # node_attempt is 1-indexed; on the FINAL attempt a failure dead-letters the document (skip it, never
+        # lose the batch) instead of raising; earlier attempts re-raise so the RetryPolicy retries.
+        attempt = runtime.execution_info.node_attempt
+        with raw_llm_span("semantic_chunking.discover", model=str(model_id or "single-call")):
+            try:
+                spans = discoverer.discover(state["document"])
+            except Exception as exc:  # noqa: BLE001
+                if attempt >= max_attempts:
+                    return {"dead_letter": dead_letter(
+                        "boundary_discovery_failed", source_doc_id=state["parsed"].source_doc_id, error=str(exc))}
+                raise TransientExtraction(str(exc)) from exc
+        return {"spans": spans}
+
+    def finalize(state: SemanticChunkingState) -> SemanticChunkingState:
+        document, spans = state["document"], state["spans"]
+        token_cap = state.get("token_cap", DEFAULT_TOKEN_CAP)
+        try:
+            _validate_partition(spans, len(document.texts))
+            texts = _finalize_chunks(document, spans, token_cap)
+        except BoundaryValidationError as exc:
+            return {"dead_letter": dead_letter(
+                "boundary_validation_failed", source_doc_id=state["parsed"].source_doc_id, error=str(exc))}
+        return {"texts": texts, "offsets": _chunk_offsets(texts)}
+
+    def summarize(state: SemanticChunkingState) -> SemanticChunkingState:
+        # Sync node using asyncio.run (matches rlm_chunking.chunk). asyncio.run copies the current contextvars
+        # context, so the OTel trace context is preserved; the to_thread summary fan-out is carried by
+        # GraphWright's threading instrumentation. Works under both invoke and ainvoke (a sync node runs in a
+        # worker thread with no live loop during ainvoke).
+        with business_span("semantic_chunking.summarize", chunk_count=len(state["texts"])):
+            summaries = asyncio.run(_summarize_all(
+                state["texts"], summarizer, state.get("max_concurrency", DEFAULT_SUMMARY_CONCURRENCY)))
+        return {"summaries": summaries}
+
+    def manifest(state: SemanticChunkingState) -> SemanticChunkingState:
+        parsed = state["parsed"]
+        texts, summaries, offsets = state["texts"], state["summaries"], state["offsets"]
+        token_cap = state.get("token_cap", DEFAULT_TOKEN_CAP)
+        chunks = [
+            Chunk(
+                chunk_id=ChunkId.of(parsed.source_doc_id, i, text).value,
+                chunk_index=i,
+                text=text,
+                summary=summary,
+                token_estimate=_estimate_tokens(text),
+                doc_start=offsets[i][0],
+                doc_end=offsets[i][1],
+            )
+            for i, (text, summary) in enumerate(zip(texts, summaries))
+        ]
+        _validate_boundaries(chunks, token_cap)
+        result = ChunkManifest(
+            source_doc_id=parsed.source_doc_id, content_hash=parsed.content_hash, token_cap=token_cap, chunks=chunks)
+        _manifest_path(state).write_text(result.model_dump_json(indent=2), encoding="utf-8")
+        return {"manifest": result}
+
+    g = StateGraph(SemanticChunkingState)
+    g.add_node("gate", gate)
+    g.add_node("discover", discover, retry_policy=retry_policy)
+    g.add_node("finalize", finalize)
+    g.add_node("summarize", summarize)
+    g.add_node("manifest", manifest)
+
+    g.add_edge(START, "gate")
+    g.add_conditional_edges("gate", lambda s: "end" if s.get("manifest") else "discover",
+                            {"discover": "discover", "end": END})
+    g.add_conditional_edges("discover", lambda s: "end" if s.get("dead_letter") else "finalize",
+                            {"finalize": "finalize", "end": END})
+    g.add_conditional_edges("finalize", lambda s: "end" if s.get("dead_letter") else "summarize",
+                            {"summarize": "summarize", "end": END})
+    g.add_edge("summarize", "manifest")
+    g.add_edge("manifest", END)
+    return g.compile()
+
+
+# (EP-CORE-1a/ADR-0118: register_semantic_chunking_subgraph removed — semantic_chunking is de-registered from ARD;
+# it's a core helper now. The LangGraph runnable + ChunkManifest contract stay; they're just not ARD-catalogued.)