rag-wright 0.1.0__py3-none-any.whl

rag_wright/contracts/extraction.py

@@ -0,0 +1,130 @@
+"""The graph extraction contract and extractor seam (FR-C.6, FR-I.4).
+
+Graph extraction is a hybrid stack (FR-C.6): docling-graph contract extraction for schema entities,
+a lightweight NER-plus-dependency path for the bulk, an open-ended language-model escalation for
+hard cases, and later Open Information Extraction (OpenIE). This module is the *contract* those
+extractors conform to, not the extractors themselves (those are the graph-extraction capability,
+T23).
+
+The load-bearing part is the seam: `Extractor` is a real interface, and `run_extractors` iterates a
+list of extractors and merges their results. Adding a new extractor (the deferred OpenIE path) is
+just appending an `Extractor` to that list; neither `run_extractors` nor `ExtractionResult` is
+reopened. Every extractor yields an `ExtractionResult` whose facts conform to the ontology (T4) and
+are anchored to the originating `chunk_id` (FR-I.4).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from rag_wright.contracts.identifiers import ChunkId
+from rag_wright.contracts.ontology import ClauseFact, RelationshipFact
+from rag_wright.contracts.provenance import ConfidenceTag
+
+
+class EntityMention(BaseModel):
+    """A pre-resolution entity mention: a surface form, its ontology type, and a confidence tag.
+
+    Graph extraction produces typed mentions (NER labels); entity resolution (FR-C.7 / T24) later
+    maps the surface form to a canonical `entity_id` and creates the canonical `EntityNode`.
+
+    A mention IS an ontology-conforming graph fact (FR-S.4): it is read from the text, so a spaCy NER
+    or contract-extracted mention carries a `confidence` tag like any other fact (ADR-0012). Its
+    `chunk_id` provenance is the containing `ExtractionResult.chunk_id` (mentions are anchored by the
+    result, not individually provenanced, since resolution collapses many mentions to one node). This
+    is deliberately how the spaCy path satisfies "each path produces facts carrying chunk_id +
+    confidence" — by emitting confidence-bearing mentions, NOT by inventing edges: co-occurrence of
+    two organizations in legal text is frequently non-contractual (a non-compete, a governing-law or
+    payment-clause reference), so a proximity edge is a false-edge generator, and nothing downstream
+    filters edges (T26 surfaces confidence, it does not gate on it — FR-C.5/FR-Q.3). CONTRACTS_WITH
+    comes from signing-party structure (the contract extractor), never proximity (ADR-0012).
+
+    `text` here is the *same notion* as a `RelationshipFact`'s `source_ref` / `target_ref`: both are
+    pre-resolution entity surface forms. Standalone mentions and relationship endpoints are two
+    channels for the same entities, so entity resolution (T24) must resolve them as one mention
+    stream; an entity appearing as both must resolve to a single node, not a duplicate.
+    """
+
+    text: str
+    entity_type: str  # opaque domain entity type (DD-5); the caller/domain pack names it
+    confidence: ConfidenceTag
+
+    @field_validator("text")
+    @classmethod
+    def _text_non_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("entity mention text must be non-empty")
+        return v
+
+
+class ExtractionResult(BaseModel):
+    """What one extractor produces for one chunk: ontology-conforming facts plus typed mentions.
+
+    Every fact is anchored to `chunk_id`: its provenance must point at this chunk, so the extraction
+    result carries the originating `chunk_id` end to end (FR-I.4). Facts already conform to the
+    ontology (their type fields are the T4 enums), so a non-ontology fact cannot be built at all.
+    """
+
+    chunk_id: ChunkId
+    entity_mentions: list[EntityMention] = []
+    clause_facts: list[ClauseFact] = []
+    relationship_facts: list[RelationshipFact] = []
+
+    @model_validator(mode="after")
+    def _facts_anchored_to_chunk(self) -> ExtractionResult:
+        for fact in (*self.clause_facts, *self.relationship_facts):
+            if fact.provenance.chunk_id != self.chunk_id:
+                raise ValueError(
+                    "every fact in an ExtractionResult must be anchored to the result's chunk_id "
+                    "(fact provenance chunk_id does not match)"
+                )
+        return self
+
+    @classmethod
+    def merge(cls, chunk_id: ChunkId, results: Sequence[ExtractionResult]) -> ExtractionResult:
+        """Merge several extractors' results for one chunk into a single result.
+
+        All results must be for `chunk_id`; a result for another chunk is a defect and is rejected.
+        Merging is a union (dedup, if any, is entity resolution's and graph storage's concern).
+        """
+        for result in results:
+            if result.chunk_id != chunk_id:
+                raise ValueError("cannot merge extraction results from different chunks")
+        return cls(
+            chunk_id=chunk_id,
+            entity_mentions=[m for r in results for m in r.entity_mentions],
+            clause_facts=[f for r in results for f in r.clause_facts],
+            relationship_facts=[f for r in results for f in r.relationship_facts],
+        )
+
+
+@runtime_checkable
+class Extractor(Protocol):
+    """The extractor seam. Each extractor in the hybrid stack (FR-C.6) implements this, and the
+    graph-extraction capability (T23) iterates over a list of them. The deferred OpenIE path is a
+    future `Extractor` added to that list, behind this same contract, with no change here.
+
+    Note: `@runtime_checkable` makes `isinstance(x, Extractor)` a *presence* check only (it verifies
+    `extract` and `name` exist, not their signatures or return type). Signature and output
+    conformance are enforced downstream by `ExtractionResult` validation, which is what the
+    result-validation tests exercise, not `isinstance`.
+    """
+
+    name: str
+
+    def extract(self, chunk_id: ChunkId, text: str) -> ExtractionResult: ...
+
+
+def run_extractors(
+    extractors: Iterable[Extractor], chunk_id: ChunkId, text: str
+) -> ExtractionResult:
+    """Run every extractor over one chunk and merge into a single anchored `ExtractionResult`.
+
+    This is the seam the capability drives: registering a new extractor means adding it to
+    `extractors`, nothing here changes.
+    """
+    results = [extractor.extract(chunk_id, text) for extractor in extractors]
+    return ExtractionResult.merge(chunk_id, results)

rag_wright/contracts/function.py

@@ -0,0 +1,167 @@
+"""The retrieval FUNCTION taxonomy (T57, FR-C.6, ADR-0025).
+
+The set of clause types the FUNCTION classifier (T56) routes on. It is a SUPERSET of the 41 CUAD
+`ClauseCategory` (mirrored by value, so there is no drift) plus the three ACORD query families CUAD
+has no class for: Indemnification (14/57 test queries), the indirect/consequential damages waiver,
+and the warranty disclaimer (the bulk of the "Limitation of Liability" family beyond Cap/Uncapped).
+
+This is kept DISTINCT from `ClauseCategory` on purpose. `ClauseCategory` is the graph EXTRACTION
+ontology (ADR-0002): a closed vocabulary the knowledge graph conforms to, not reopened here. The
+FUNCTION taxonomy is a RETRIEVAL concern (which clause type a span is routed under). The two serve
+different layers even though 41 labels coincide by value, so extending function routing does not
+reopen the extraction ontology.
+
+`FUNCTION_LABELS` is the classifier's full label space and its retrain target (the T56 LegalBERT is
+retrained over these classes plus its own NONE sentinel; NONE is not a function type and is not listed
+here). ADR-0048 step 2 grew it 44 -> 52 with 8 taxonomy-gap functions the full-corpus classifier
+surfaced (curated LLM-assisted with human oversight), plus a curated FOLD alias map (`_FUNCTION_ALIASES`)
+that resolves recurring synonyms to their canonical label.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, field_validator
+
+from rag_wright.contracts.ontology import ClauseCategory
+
+
+class FunctionClassification(BaseModel):
+    """CAP-REG-2: the ranked FUNCTION_LABELS a span or query is classified into (most relevant first).
+    The shared output contract of the LegalBERT `clause_function_classification` (model) and the
+    taxonomy-constrained `query_function_classification` (agent_skill)."""
+
+    labels: list[str]
+
+
+class ExtendedFunction(str, Enum):
+    """The ACORD query families the 41 CUAD `ClauseCategory` has no class for (T57). Values are the
+    canonical function labels the classifier emits and the query-decomposer targets."""
+
+    INDEMNIFICATION = "Indemnification"
+    INDIRECT_DAMAGES_WAIVER = "Indirect/Consequential Damages Waiver"
+    WARRANTY_DISCLAIMER = "Warranty Disclaimer"
+
+
+class TaxonomyGapFunction(str, Enum):
+    """INGEST-LLM-CLASSIFIER step 2 (ADR-0048): 8 clause functions the full-corpus LLM classifier surfaced as
+    recurring OTHER (out-of-taxonomy) clause types across the unified CUAD+ACORD corpus, then curated LLM-assisted
+    with human oversight (`data/eval/taxonomy_gaps/curation_proposal.json`, my recommended 8-ADD delta approved).
+    Genuinely distinct from the 44 CUAD/ACORD labels: CUAD has no generic Confidentiality, Royalties, Payment
+    Terms, Force Majeure, Dispute Resolution, Record Retention, Security Interest, or Condition Precedent class."""
+
+    CONFIDENTIALITY = "Confidentiality"
+    ROYALTIES = "Royalties"
+    PAYMENT_TERMS = "Payment Terms"
+    DISPUTE_RESOLUTION = "Dispute Resolution"
+    RECORD_RETENTION = "Record Retention"
+    SECURITY_INTEREST = "Security Interest"
+    CONDITION_PRECEDENT = "Condition Precedent"
+    FORCE_MAJEURE = "Force Majeure"
+
+
+# The classifier's full label space: the 41 CUAD categories (by value, no drift), then the 3 ACORD
+# extensions, then the 8 ADR-0048 taxonomy-gap additions. Order is stable (CUAD, extension, gap) so a
+# retrain's label<->id map is reproducible. NONE is the off-taxonomy sentinel, not a function -> not listed.
+FUNCTION_LABELS: tuple[str, ...] = tuple(
+    [c.value for c in ClauseCategory]
+    + [f.value for f in ExtendedFunction]
+    + [f.value for f in TaxonomyGapFunction]
+)
+FUNCTION_LABEL_SET: frozenset[str] = frozenset(FUNCTION_LABELS)
+
+# The no-clause-function sentinel (the classifier's off-taxonomy NONE). NOT a function type, so NOT in
+# FUNCTION_LABELS. A `ClausePropertyRecord` carries it ONLY for a QUERY-constraint record (a query has no clause
+# function -- only its extracted properties matter); a real ingested clause never uses it (the ingest extracts
+# clauses only for canonical functions).
+NO_FUNCTION: str = "NONE"
+
+# The classifier was trained on CUAD's label strings, which differ in CASE from the canonical taxonomy for
+# a few labels (e.g. CUAD "Ip Ownership Assignment" vs the canonical "IP Ownership Assignment"). Normalize
+# the classifier output to the canonical label at the boundary (memory: normalize at the boundary), keyed
+# case-insensitively.
+_FUNCTION_BY_CASEFOLD: dict[str, str] = {label.casefold(): label for label in FUNCTION_LABELS}
+
+# ADR-0048 step 2: the curated FOLD map -- recurring synonyms/spelling/variant clause types the full-corpus
+# classifier surfaced, each mapped to its canonical `FUNCTION_LABELS` entry (LLM-proposed, human-reconciled:
+# the 3 LLM mis-folds were dropped, the royalty family retargeted to the new Royalties label, and RoFR +
+# Milestone Payment folded rather than dropped). Authored in code (no external map to drift), keyed by
+# canonical target for readability; inverted + casefolded into `_FUNCTION_ALIAS_BY_CASEFOLD` below.
+_FUNCTION_ALIASES: dict[str, tuple[str, ...]] = {
+    "Cap On Liability": ("Limitation of Liability", "Limitations of Liability", "Liability Limitation"),
+    "Anti-Assignment": ("Assignment", "Assignment of Capacity", "Non-Assignment"),
+    "Termination For Convenience": (
+        "Termination", "Termination For Cause", "Effect of Termination", "Termination Clause",
+        "Cancellation", "Termination Effects", "Rights and Obligations Upon Termination"),
+    "Expiration Date": ("Term",),
+    "Insurance": ("Insurance Requirement", "Insurance Type", "Insurance Coverage Details"),
+    "No-Solicit Of Employees": ("Non-Solicit Of Employees",),
+    "No-Solicit Of Customers": ("Non-Solicit Of Customers",),
+    "Warranty Duration": ("Warranty Grant", "Product Warranty", "Warranty"),
+    "Warranty Disclaimer": (
+        "Disclaimer of Warranty", "Disclaimer of Representations and Warranties", "Disclaimer",
+        "Liability Disclaimer"),
+    "Liquidated Damages": ("Penalty", "Make-Whole Payment"),
+    "Indemnification": ("Intellectual Property Indemnification", "Indemnity and Limitation of Liability"),
+    "License Grant": (
+        "Content License Restrictions", "Use Restrictions", "License Grant Restrictions", "Restriction Of Use"),
+    "Notice Period To Terminate Renewal": ("Notice Period To Terminate",),
+    "Non-Compete": ("Non-Compete Exception",),
+    "Governing Law": ("Jurisdiction",),
+    "Audit Rights": ("Inspection", "Inspection Rights"),
+    "IP Ownership Assignment": (
+        "Ownership", "Domain Name Assignment", "Intellectual Property Rights", "Patents",
+        "Intellectual Property Assignment"),
+    "Revenue/Profit Sharing": ("Revenue Sharing", "Payment/Revenue Sharing"),
+    "Competitive Restriction Exception": (
+        "Definition of Class C Breaches", "Other Restriction Exception", "Other Restriction"),
+    "Rofr/Rofo/Rofn": ("Right of First Refusal",),
+    # the royalty family consolidates into the new Royalties label; Milestone Payment -> the new Payment Terms
+    "Royalties": ("Royalty Grant", "Royalty", "Royalty Obligation", "Royalty Payment"),
+    "Payment Terms": ("Milestone Payment",),
+}
+_FUNCTION_ALIAS_BY_CASEFOLD: dict[str, str] = {
+    alias.casefold(): canon for canon, aliases in _FUNCTION_ALIASES.items() for alias in aliases
+}
+
+
+def canonical_function(label: str) -> str | None:
+    """Map a function label to its canonical `FUNCTION_LABELS` entry, or None if it matches none. Case-
+    insensitive, and resolves the ADR-0048 curated FOLD aliases (e.g. 'Limitation of Liability' -> 'Cap On
+    Liability', 'Royalty Grant' -> 'Royalties'). Exact/cased match wins over an alias."""
+    key = label.strip().casefold()
+    return _FUNCTION_BY_CASEFOLD.get(key) or _FUNCTION_ALIAS_BY_CASEFOLD.get(key)
+
+
+class FunctionConfidence(str, Enum):
+    """INGEST-LLM-CLASSIFIER (ADR-0048): the LLM clause classifier's coarse confidence in a function assignment.
+    Ordinal, not a float -- LLMs are not calibrated on numeric self-confidence; a floor (>= medium) filters weak
+    labels, so a clause with one clear function stays single while a genuinely mixed clause keeps 2-3."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class FunctionScore(BaseModel):
+    """INGEST-LLM-CLASSIFIER (ADR-0048): one function a clause is classified into, with coarse confidence. In a
+    ranked list the first is the PRIMARY (the label kept on `Clause.function` for the query legs). `function` is
+    normalized to its canonical `FUNCTION_LABELS` entry at the boundary; a non-canonical label (incl. the NONE
+    sentinel) is rejected (strict contract; normalize upstream)."""
+
+    function: str
+    confidence: FunctionConfidence
+
+    @field_validator("function")
+    @classmethod
+    def _canonicalize(cls, v: str) -> str:
+        canon = canonical_function(v)
+        if canon is None:
+            raise ValueError(f"function must be a canonical FUNCTION_LABELS label, got {v!r}")
+        return canon
+
+
+def primary_function(scores: list[FunctionScore]) -> str | None:
+    """The PRIMARY (highest-ranked) function of a ranked `FunctionScore` list (primary first), or None if empty."""
+    return scores[0].function if scores else None

rag_wright/contracts/function_routing.py

@@ -0,0 +1,91 @@
+"""KG-5e (FR-Q): the query-side FUNCTION ROUTER, driven by the granite-extracted DIMENSIONS.
+
+KG-5c found that query-side function routing is the dominant retrieval lever (the oracle->real gap is
+-0.22 recall@20, dwarfing every reranker lever) and that the clause-trained LegalBERT classifier is
+out-of-distribution on short query text. This routes instead from the query's typed DIMENSIONS -- which
+KG-5b showed the granite extraction gets right even where `clause_type` is unreliable -- through a
+corpus-derived `dimension -> function` co-occurrence prior. No extra LLM call, no clause-trained model:
+the typed extraction we already compute builds the pool.
+
+The prior is built from a HELD-OUT corpus (CUAD) so no ACORD eval data enters the router; the two corpora
+share the property-dimension schema and the CUAD-type function taxonomy, so the prior transfers.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from typing import Iterable
+
+
+def build_cooccurrence(clause_rows: Iterable[tuple[str, str, str]]) -> dict[str, dict[str, int]]:
+    """`dimension -> {function -> clause-count}` from `(clause_id, function, dimension)` typed-edge rows.
+
+    Counted once per (clause, dimension, function) so a clause with several values for one dimension does not
+    over-weight its function. An empty/`NONE` function is dropped (not a routable target). Pure -- no store.
+    """
+    seen: set[tuple[str, str, str]] = set()
+    cooc: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    for clause_id, function, dimension in clause_rows:
+        if not function or function == "NONE" or not dimension:
+            continue
+        key = (clause_id, dimension, function)
+        if key in seen:
+            continue
+        seen.add(key)
+        cooc[dimension][function] += 1
+    return {d: dict(fs) for d, fs in cooc.items()}
+
+
+def _function_marginal(cooc: dict[str, dict[str, int]]) -> dict[str, float]:
+    """P(function) proxy: each function's share of all edges in the prior -- the base rate that lift/PMI
+    divide out so a distinctive dimension beats a merely-common function."""
+    tot: dict[str, float] = defaultdict(float)
+    grand = 0.0
+    for col in cooc.values():
+        for fn, c in col.items():
+            tot[fn] += c
+            grand += c
+    return {fn: c / grand for fn, c in tot.items()} if grand else {}
+
+
+def route_functions(
+    query_dimensions: Iterable[str],
+    cooc: dict[str, dict[str, int]],
+    *,
+    k: int,
+    score: str = "conditional",
+    min_support: int = 1,
+) -> list[str]:
+    """The top-`k` functions for a query, scored by summing a per-dimension signal over the query's dimensions:
+
+    - ``conditional`` (default): ``P(function | dimension)`` -- biased toward high-frequency functions.
+    - ``lift``: ``P(function|dimension) / P(function)`` -- corrects for the function base rate (a dimension
+      routes to the function it is DISTINCTIVE of, not merely the most common one that has it).
+    - ``pmi``: ``log(P(function|dimension) / P(function))`` -- the log-odds form of lift.
+
+    `min_support` drops sparse `(dimension, function)` evidence (< that many clauses) so lift/PMI are not blown
+    up by a single-clause coincidence. A dimension with no corpus signal contributes nothing; no dimensions
+    (or none seen) -> ``[]``. Ties break on the function name so the routing is deterministic.
+    """
+    marginal = _function_marginal(cooc) if score in ("lift", "pmi") else {}
+    total_score: dict[str, float] = defaultdict(float)
+    for d in query_dimensions:
+        col = cooc.get(d)
+        if not col:
+            continue
+        total = sum(col.values())
+        if not total:
+            continue
+        for fn, c in col.items():
+            if c < min_support:
+                continue
+            p_f_given_d = c / total
+            if score == "conditional":
+                total_score[fn] += p_f_given_d
+            else:
+                p_f = marginal.get(fn, 0.0)
+                if p_f <= 0:
+                    continue
+                total_score[fn] += p_f_given_d / p_f if score == "lift" else math.log(p_f_given_d / p_f)
+    return [fn for fn, _ in sorted(total_score.items(), key=lambda x: (-x[1], x[0]))[:k]]

rag_wright/contracts/highlight.py

@@ -0,0 +1,74 @@
+"""The serve-side highlight response contract (CU-A1 / CU-C2, ADR-0029).
+
+What the pipeline returns for a query about a known contract: the SET of spans that pertain (possibly empty ->
+"not present"), each with its exact document location so an app can highlight it, plus provenance for citation.
+`HighlightResult` also carries the presence/absence and out-of-taxonomy/low-confidence signals the app/agent
+routes on. Offsets mirror `SpanRecord` (document-absolute char offsets; optional page/bbox).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, model_validator
+
+
+class HighlightSpan(BaseModel):
+    """One span to highlight, with its citation (location + parent-clause reference)."""
+
+    model_config = {"frozen": True}
+
+    span_id: str
+    contract_id: str
+    function: str  # the clause type this span was matched under
+    clause_ref: str  # human-readable parent-clause reference (heading/number or parent_chunk_id)
+    text: str
+    doc_start: int | None = None  # document-absolute char offsets (the highlight range)
+    doc_end: int | None = None
+    page: int | None = None  # optional PDF-overlay location (FIRST page; == pages[0] when known)
+    pages: list[int] = []  # issue 0032: ALL source pages this span overlaps (page-level click-through)
+    bbox: tuple[float, float, float, float] | None = None
+    extracted_value: str | None = None  # for value-type categories: the pinpointed value within the span
+    confidence: float = 1.0
+
+    @model_validator(mode="after")
+    def _check_offsets(self) -> "HighlightSpan":
+        if self.doc_start is not None and self.doc_end is not None and self.doc_end < self.doc_start:
+            raise ValueError(f"doc_end ({self.doc_end}) must be >= doc_start ({self.doc_start})")
+        return self
+
+
+class SpanLocation(BaseModel):
+    """Where one span sits in the ORIGINAL document, for a citation PREVIEW (EP-REF-1b): a location + the text
+    to confirm it landed, plus the clause ids extracted from it (so an answer's `citation_id` -- a span id OR a
+    clause id, two different spaces -- resolves either way). Lighter than `HighlightSpan` (no function / clause
+    ref / extracted value / confidence): a preview answers "show me this span", not "which spans pertain". `pages`
+    is a LIST (a span can cross a page break; the first page is where the preview opens) and `bbox` is best-effort
+    -- a page is nearly always known and a rectangle usually is, so a missing rectangle never costs the page."""
+
+    span_id: str
+    clause_ids: list[str] = []
+    pages: list[int] = []
+    bbox: tuple[float, float, float, float] | None = None
+    doc_start: int | None = None
+    doc_end: int | None = None
+    text: str = ""
+
+
+class HighlightResult(BaseModel):
+    """The full response to one query about one contract."""
+
+    model_config = {"frozen": True}
+
+    query: str
+    contract_id: str
+    clause_types: list[str] = []  # the types searched (from QueryIntent)
+    intent: str = "highlight"
+    spans: list[HighlightSpan] = []  # the pertaining set; empty => not present
+    present: bool = False  # spans is non-empty
+    in_taxonomy: bool = True
+    low_confidence: bool = False  # out-of-taxonomy semantic fallback used
+
+    @model_validator(mode="after")
+    def _check_present(self) -> "HighlightResult":
+        if self.present != bool(self.spans):
+            raise ValueError("`present` must equal whether `spans` is non-empty")
+        return self

rag_wright/contracts/identifiers.py

@@ -0,0 +1,153 @@
+"""Shared identifier contracts: `chunk_id` (FR-S.2) and `entity_id` (FR-S.3).
+
+These schemes are load-bearing and fixed here before anything is built. A re-chunk that changes
+a `chunk_id` breaks the link between a chunk and its extracted graph nodes, and a non-canonical
+`entity_id` fragments the graph across surface-form variants. Changing either scheme is an
+ask-first change (SPEC.md section 14; CLAUDE.md boundaries).
+
+Both identifiers are frozen Pydantic models, so they are immutable and hashable and can serve as
+dictionary keys and graph-node identity directly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+_SHA256_HEX = re.compile(r"^[0-9a-f]{64}$")
+_SOURCE_DOC_ID = re.compile(r"^[A-Za-z0-9._-]+$")
+_SOURCE_DOC_UNSAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def canonical_source_doc_id(raw: str) -> str:
+    """The ONE canonical filename/title -> `source_doc_id` slug (FR-S.2; HYG-1).
+
+    Every ingestion path MUST derive a `source_doc_id` through this function so the same document gets the
+    same id everywhere. Any run of characters outside the delimiter-safe set ``[A-Za-z0-9._-]`` (notably
+    spaces, ``&``, commas) collapses to a single ``_``; leading/trailing ``_`` are stripped. Existing safe
+    delimiters (``-``, ``.``, ``_`` -- e.g. inside ``EX-10.1`` / ``10-Q``) are preserved. Idempotent on an
+    already-canonical id.
+
+    The ``_`` replacement (never ``-``) is the fix for the HYG-1 divergence: two ingestion paths slugged the
+    same title with different characters (``FLEET_MAINTENANCE`` vs ``FLEET-MAINTENANCE``), breaking the
+    cross-graph join. An empty result raises rather than silently colliding every empty title into one id.
+    """
+    slug = _SOURCE_DOC_UNSAFE.sub("_", raw).strip("_") if isinstance(raw, str) else ""
+    if not slug:
+        raise ValueError(
+            f"source_doc_id slug is empty for {raw!r}; supply a non-empty, sluggable document id"
+        )
+    return slug
+
+
+class ChunkId(BaseModel):
+    """The stable identifier for a chunk (FR-S.2).
+
+    Scheme: source-document identifier, chunk index, and a content hash of the chunk text. The
+    content hash is what makes the identifier change when (and only when) the chunk content
+    changes, so an unchanged document re-chunks to the same ids (the content-hash gate in FR-I.1
+    and FR-I.5 relies on this).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    source_doc_id: str
+    chunk_index: int
+    content_hash: str  # lowercase hex SHA-256 digest of the chunk content
+
+    @field_validator("source_doc_id")
+    @classmethod
+    def _delimiter_safe_source(cls, v: str) -> str:
+        v = v.strip()
+        if not _SOURCE_DOC_ID.match(v):
+            raise ValueError(
+                "source_doc_id must be non-empty and use only [A-Za-z0-9._-], so the ':'-delimited "
+                "value string stays unambiguous for provenance and citation lookup; assign a "
+                "delimiter-safe id upstream (slugify the filename if needed)"
+            )
+        return v
+
+    @field_validator("chunk_index")
+    @classmethod
+    def _nonnegative_index(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError("chunk_index must be >= 0")
+        return v
+
+    @field_validator("content_hash")
+    @classmethod
+    def _valid_sha256(cls, v: str) -> str:
+        v = v.strip().lower()
+        if not _SHA256_HEX.match(v):
+            raise ValueError("content_hash must be a 64-character lowercase hex SHA-256 digest")
+        return v
+
+    @classmethod
+    def of(cls, source_doc_id: str, chunk_index: int, content: str | bytes) -> ChunkId:
+        """Build a `ChunkId`, computing the content hash deterministically (SHA-256).
+
+        This is where determinism lives (RAC-1): identical `(source_doc_id, chunk_index, content)`
+        always yield an identical `ChunkId`.
+        """
+        data = content.encode("utf-8") if isinstance(content, str) else content
+        return cls(
+            source_doc_id=source_doc_id,
+            chunk_index=chunk_index,
+            content_hash=hashlib.sha256(data).hexdigest(),
+        )
+
+    @property
+    def value(self) -> str:
+        """The canonical string form: ``<source_doc_id>:<chunk_index>:<content_hash>``.
+
+        Because ``source_doc_id`` is constrained to a delimiter-safe character set, this string is
+        safe to string-match and to parse back with ``rsplit(":", 2)`` for provenance and citation
+        lookup. Identity itself remains field-based (frozen-model equality and hashing), not
+        string-based.
+        """
+        return f"{self.source_doc_id}:{self.chunk_index}:{self.content_hash}"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class EntityId(BaseModel):
+    """The canonical entity identifier (FR-S.3): an opaque canonical-registry id string.
+
+    The engine is domain-agnostic (DD-4, ADR-0067/0117), so the FORMAT of a canonical id is owned by
+    the resolver / domain pack, NOT by this contract. The SEC pack resolves to a 10-digit zero-padded
+    EDGAR Central Index Key (CIK), e.g. ``"0000320193"`` (shaped in ``corpus/edgar.normalize_cik``); a
+    generic pack uses an exact-normalized surface-form key; another domain uses its own scheme. This
+    contract's only invariant is therefore the domain-neutral one: a non-empty string. That is still a
+    real invariant -- every downstream holder of an `EntityId` can trust it is a present, non-blank id --
+    while the format check lives at the one boundary that knows the domain (the resolver/loader), where
+    the world's mess actually arrives, per the "normalize at the boundary" rule.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    value: str  # an opaque canonical id; its FORMAT is the resolver/pack's concern, not this contract's
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def _nonempty(cls, v: object) -> str:
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError(
+                "EntityId.value must be a non-empty string. The canonical-id FORMAT is owned by the "
+                "resolver / domain pack (e.g. corpus/edgar.normalize_cik for SEC CIKs), not this contract."
+            )
+        return v
+
+    @classmethod
+    def of(cls, value: str) -> EntityId:
+        """Build an `EntityId` from an already-canonical id string.
+
+        This does not normalize or format-check beyond non-emptiness; shaping the raw domain form into
+        the canonical id is the resolver / domain pack's job (e.g. `corpus/edgar.normalize_cik`).
+        """
+        return cls(value=value)
+
+    def __str__(self) -> str:
+        return self.value