rag-wright 0.1.0__py3-none-any.whl

rag_wright/capabilities/ard.py

@@ -0,0 +1,286 @@
+"""RAG-side mirror of GraphWright's ARD `RegistryEntry` schema (GraphWright ADR-0005).
+
+This is a **shared wire-format contract**, mirrored here by **deliberate duplication** (see
+docs/adr/0003). RAG_Wright authors Agentic Resource Discovery (ARD) manifests as JSON that
+GraphWright's `RegistryStore` consumes; the capability half does not import the compiler half, so
+its schema is duplicated rather than imported. A change to GraphWright's ADR-0005 schema is a
+**cross-repo coordination point**: this mirror and GraphWright's `src/graphwright/registry/entry.py`
+must be updated together, or a manifest that validates on one side fails on the other. The
+conformance tests here catch a drift in RAG_Wright's own suite instead of only at GraphWright load.
+
+Field names, shapes, and validators mirror GraphWright's `entry.py` verbatim (ARD v0.9, camelCase on
+the wire via `to_camel`, `extra="forbid"`).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic.alias_generators import to_camel
+
+# The ARD identifier scheme (ARD v0.9 section 4.2.1, https://github.com/ards-project/ard-spec):
+# urn:air:<publisher>:<namespace>:<name>. Our vertical's publisher is the FQDN dreamai.io and the
+# namespace is rag_wright, so every capability we author carries `RAG_URN_PREFIX + <slug>`. The
+# generic schema mirror (ArdEnvelope, below) validates only the `urn:air:` prefix, matching
+# GraphWright's schema which accepts any publisher; the exact-publisher check is applied where we
+# author/write OUR manifests (write_manifest, and the emitter in registry.py).
+URN_PUBLISHER = "dreamai.io"
+URN_NAMESPACE = "rag_wright"
+RAG_URN_PREFIX = f"urn:air:{URN_PUBLISHER}:{URN_NAMESPACE}:"
+
+# The six governed kinds (GraphWright FR-5.1). `agent_skill` is loaded by an agent node; the others
+# are callables that declare response bounds (FR-5.2).
+EntryKind = Literal["agent_skill", "mcp_tool", "function", "model", "subgraph", "dagster_asset"]
+CALLABLE_KINDS: frozenset[str] = frozenset(
+    {"mcp_tool", "function", "model", "subgraph", "dagster_asset"}
+)
+
+# kind -> ARD `type` (an IANA media type). Standard types where one exists, vendor types otherwise.
+MEDIA_TYPE_BY_KIND: dict[str, str] = {
+    "agent_skill": "application/ai-skill+md",
+    "mcp_tool": "application/mcp-server-card+json",
+    "function": "application/vnd.dreamai.graphwright.function+json",
+    "model": "application/vnd.dreamai.graphwright.model+json",
+    "subgraph": "application/vnd.dreamai.graphwright.subgraph+json",
+    "dagster_asset": "application/vnd.dreamai.graphwright.dagster-asset+json",
+}
+
+
+class _ArdModel(BaseModel):
+    """Base for the ARD-shaped models: camelCase on the wire, snake_case in Python."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, extra="forbid")
+
+
+class Attestation(_ArdModel):
+    """An ARD trust attestation: a category, where the document lives, and an optional digest."""
+
+    type: str
+    uri: str
+    digest: Optional[str] = None
+
+
+class TrustManifest(_ArdModel):
+    """ARD trust manifest: a verifiable identity plus attestations. Attestations may be empty for a
+    new entry (GraphWright's control-level trust filter rejects an under-attested entry later)."""
+
+    identity: str
+    identity_type: str
+    attestations: list[Attestation] = Field(default_factory=list)
+
+
+class ArdEnvelope(_ArdModel):
+    """The ARD v0.9 publishable face of a capability. Only ARD fields; no internal governance."""
+
+    identifier: str  # domain-anchored URN: urn:air:<publisher>:<namespace>:<name>
+    display_name: str
+    type: str  # IANA media type; must match MEDIA_TYPE_BY_KIND[kind] (checked on the record)
+    representative_queries: list[str] = Field(min_length=2, max_length=5)
+    trust_manifest: TrustManifest
+    description: Optional[str] = None
+    tags: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _check_identifier_is_urn(self) -> ArdEnvelope:
+        if not self.identifier.startswith("urn:air:"):
+            raise ValueError(
+                "identifier must be a domain-anchored ARD URN "
+                f"(urn:air:<publisher>:<namespace>:<name>), got {self.identifier!r}"
+            )
+        return self
+
+
+class ResponseBounds(_ArdModel):
+    """Internal-only response bounds a callable entry declares (caps tool responses ~25,000 tokens)."""
+
+    max_tokens: int = 25_000
+    supports_pagination: bool = False
+    supports_filtering: bool = False
+
+
+class GovernanceBlock(_ArdModel):
+    """Internal-only governance the ARD envelope does not carry."""
+
+    owner: str
+    control_level_min: Literal["high", "moderate", "low"] = "moderate"
+
+
+class SkillRuntime(_ArdModel):
+    """An agent skill's intrinsic runtime requirements, so the compiler can hydrate an interpreter node
+    without fabricating anything (GraphWright RegistryEntry; mirrored per ADR-0003). Internal-only,
+    never the ARD envelope; `agent_skill` only (validated like `requires`); absent when a skill has no
+    special runtime needs. Intrinsic requirements only — the model is deployment config and stays out."""
+
+    needs_interpreter: bool = False  # the skill runs code in the interpreter
+    rlm: bool = False  # the auditable RLM-pattern marker (FR-1.4, FR-4.10)
+    granted_subagents: list[str] = Field(default_factory=list)  # sub-agent names it may dispatch to
+    # This skill's execution requires the interpreter's code-driven fan-out (task() dispatch) to be
+    # triggered. A TYPED flag, NOT the trigger phrasing: the exact word (langchain-quickjs's "workflow")
+    # is owned by GraphWright's runtime, which translates this flag into whatever the installed
+    # interpreter version expects — so the magic word never enters the wire contract (ADR-0017). Implies
+    # `needs_interpreter` (dynamic dispatch is exposed by the interpreter), but kept a distinct field:
+    # a future interpreter-using skill might not need dynamic-dispatch triggering.
+    requires_dynamic_dispatch: bool = False
+
+    @model_validator(mode="after")
+    def _dispatch_implies_interpreter(self) -> SkillRuntime:
+        if self.requires_dynamic_dispatch and not self.needs_interpreter:
+            raise ValueError(
+                "requires_dynamic_dispatch implies needs_interpreter (task() fan-out is exposed by the "
+                "interpreter); set needs_interpreter=True"
+            )
+        return self
+
+
+# The nominal type vocabulary GraphWright's lowering checker keys on (GraphWright ADR-0030 section 3). A
+# MIRROR of a shared cross-repo contract, like the RegistryEntry schema above and the canonical-slug set in
+# registry.py: the checker compares a port's type as an OPAQUE NAME string (two ports chain iff their type
+# names are equal, no field-level reasoning), so the producer and the consumer of a chain-compatible shape
+# MUST use the same name, and a typo silently breaks a chain check on GraphWright's side. We validate every
+# declared type name against this set so the drift is caught in our own suite (the same discipline as the ARD
+# schema mirror). Changing this set is a cross-repo coordination point with GraphWright's checker vocabulary.
+NOMINAL_TYPE_VOCABULARY: frozenset[str] = frozenset(
+    {
+        # --- retrieval -> answer (T43) ---
+        "text",  # a natural-language string (a query, an answer)
+        "chunk_id",  # a chunk reference WITHOUT its text (id, plus provenance like source_doc_id)
+        "chunk_with_text",  # a chunk reference WITH its text attached (only chunk_read produces it)
+        "scored_chunk",  # a chunk reference carrying a relevance score (reranking's output)
+        "graph_answer",  # the graph leg's cited answer ({answer?, evidence:[{entity_id, chunk_ids[]}]})
+        "cited_extract",  # a citation: a chunk reference paired with the cited extract text ({chunk_id, extract})
+        # --- ingestion -> graph (T44); the ingestion data shapes the retrieval names don't cover ---
+        "document",  # a raw source document (a file/scan to parse) — parsing's input
+        "parsed_doc",  # a handle to the cached structured parse (DoclingDocument) — parsing out -> chunking in
+        "chunk",  # the ingestion chunk: id + full text + SUMMARY + index (distinct from chunk_with_text,
+        # which is the query-side rehydrated id+text; embedding needs the summary this carries)
+        "embedding",  # a chunk's dense+sparse vector record — embedding's output
+        "extraction",  # chunk-anchored extracted facts (entity mentions + relationship facts) — graph_extraction out
+        "entity_cluster",  # canonical mention clusters (human-verifiable proposals) — disambiguation's output
+        "resolved_entity",  # entities + relationships linked to a canonical id (the knowledge graph) — resolution out
+        "image",  # a raw image/scan (bytes) — vision_to_text's input
+    }
+)
+
+
+class CapabilityInterface(BaseModel):
+    """The governed typed I/O interface GraphWright's lowering checker verifies a realization against
+    (GraphWright ADR-0030; our T43). A GraphWright VENDOR EXTENSION, not part of the ARD envelope: it rides
+    on the `RegistryEntry` beside the internal governance blocks, so ARD-standard consumers ignore it. It is
+    the DATA that flows between orchestration steps as named channels (the query, chunk references, the
+    answer) — NOT the callable's config (model, keys, thresholds, top-k), which is deployment config.
+
+    Nominal typing: the checker compares the SET of input/output type NAMES (opaque strings from
+    `NOMINAL_TYPE_VOCABULARY`); port names are for readability only. So `inputs`/`outputs` are flat
+    `port -> typeName` maps, and cardinality (list vs scalar) is NOT encoded — a port carrying many
+    candidates and one carrying a single value both use the element name (`chunk_id`, never `chunk_id[]`).
+
+    Plain `BaseModel`, NOT `_ArdModel`: the inner keys stay snake_case (`success_criterion`) even though the
+    surrounding manifest is camelCase, because GraphWright's mirror (`TypedInterface`) carries no ARD alias
+    and its `extra="forbid"` loader rejects camelCased inner keys. `extra="forbid"` here mirrors that —
+    exactly the three keys, nothing else (GraphWright ADR-0030 section 2).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    inputs: dict[str, str]
+    outputs: dict[str, str]
+    success_criterion: str
+
+    @model_validator(mode="after")
+    def _check_ports(self) -> CapabilityInterface:
+        if not self.success_criterion.strip():
+            raise ValueError("success_criterion must be a non-empty one-line purpose")
+        for role, ports in (("inputs", self.inputs), ("outputs", self.outputs)):
+            for port, type_name in ports.items():
+                if not port.strip():
+                    raise ValueError(f"{role} contains a blank port name")
+                if type_name not in NOMINAL_TYPE_VOCABULARY:
+                    raise ValueError(
+                        f"{role} port {port!r} has type {type_name!r}, not in the agreed nominal type "
+                        f"vocabulary {sorted(NOMINAL_TYPE_VOCABULARY)} (GraphWright ADR-0030 section 3); "
+                        "strip any list sugar like '[]' and use the agreed element name"
+                    )
+        return self
+
+
+class RegistryEntry(_ArdModel):
+    """A governed registry record: the ARD envelope plus internal-only governance and eval fields.
+
+    `kind` is the internal discriminator; the envelope's ARD `type` media-type is the interoperable
+    face, kept consistent with `kind` here.
+    """
+
+    kind: EntryKind
+    envelope: ArdEnvelope
+    golden_eval_ref: Optional[str] = None
+    response_bounds: Optional[ResponseBounds] = None  # required for callable kinds
+    requires: list[str] = Field(default_factory=list)  # closure; agent_skill only
+    skill_runtime: Optional[SkillRuntime] = None  # intrinsic runtime; agent_skill only (like requires)
+    # GraphWright vendor extension (ADR-0030), optional: the governed typed I/O the compiler's lowering
+    # checker verifies a realization against. `capability_interface` -> `capabilityInterface` on the wire
+    # (to_camel), while the nested block keeps its snake_case keys (CapabilityInterface has no alias).
+    capability_interface: Optional[CapabilityInterface] = None
+    governance: GovernanceBlock
+
+    @model_validator(mode="after")
+    def _check_record_invariants(self) -> RegistryEntry:
+        if self.envelope.type != MEDIA_TYPE_BY_KIND[self.kind]:
+            raise ValueError(
+                f"envelope type {self.envelope.type!r} does not match kind {self.kind!r} "
+                f"(expected {MEDIA_TYPE_BY_KIND[self.kind]!r})"
+            )
+        if self.kind in CALLABLE_KINDS:
+            if self.response_bounds is None:
+                raise ValueError(f"callable kind {self.kind!r} requires response_bounds")
+        elif self.response_bounds is not None:
+            raise ValueError(f"kind {self.kind!r} is not callable and carries no response_bounds")
+        if self.requires and self.kind != "agent_skill":
+            raise ValueError(f"a requires closure is only valid on an agent_skill, not {self.kind!r}")
+        if self.skill_runtime is not None and self.kind != "agent_skill":
+            raise ValueError(f"skill_runtime is only valid on an agent_skill, not {self.kind!r}")
+        return self
+
+
+# --- the shared ARD registry root (GraphWright docs/authoring/registry-root.md) ------------------
+#
+# One shared registry root, config-addressed by the ARD_REGISTRY_ROOT env var that GraphWright's
+# RegistryStore also reads. RAG_Wright writes its manifests here; the compiler discovers them from
+# the same directory. We never create a second or project-local root and never hardcode a path.
+
+_DEFAULT_REGISTRY_ROOT = Path("~/.air/registry")  # `.air` mirrors the urn:air: scheme (registry-root.md)
+
+
+def registry_root() -> Path:
+    """Resolve the shared ARD registry root from `ARD_REGISTRY_ROOT`, creating it if absent.
+
+    Defaults to `~/.air/registry` when the env var is unset (same default as GraphWright). A leading
+    `~` is expanded; no absolute path is baked into source. An empty root is a valid, zero-entry
+    catalog, so this always returns a usable directory.
+    """
+    raw = os.environ.get("ARD_REGISTRY_ROOT", "").strip()
+    root = Path(raw).expanduser() if raw else _DEFAULT_REGISTRY_ROOT.expanduser()
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def write_manifest(entry: RegistryEntry, *, root: Optional[Path] = None) -> Path:
+    """Write an authored manifest to `<root>/<slug>.json`, the flat top-level ARD layout.
+
+    The identifier must be one of our own URNs (`urn:air:dreamai.io:rag_wright:<slug>`) — this is the
+    exact-publisher check for what we author, distinct from `ArdEnvelope`'s generic `urn:air:` schema
+    mirror. The file is named after the URN's final segment; identity is the `identifier` field
+    inside. Serialized ARD-shaped (camelCase on the wire) per ADR-0005.
+    """
+    identifier = entry.envelope.identifier
+    if not identifier.startswith(RAG_URN_PREFIX):
+        raise ValueError(
+            f"manifest identifier {identifier!r} is not one of ours; expected it to start with "
+            f"{RAG_URN_PREFIX!r} (urn:air:dreamai.io:rag_wright:<slug>)"
+        )
+    slug = identifier.rsplit(":", 1)[-1]
+    target = (root if root is not None else registry_root()) / f"{slug}.json"
+    target.write_text(entry.model_dump_json(by_alias=True, indent=2), encoding="utf-8")
+    return target

rag_wright/capabilities/assertion_extraction.py

@@ -0,0 +1,79 @@
+"""SEG-3: the DOMAIN-NEUTRAL verbatim assertion extractor -- subject text -> `CheckableFact[]`.
+
+The generic analog of `claim_extraction` (which is the ADVERTISING specialization): the SAME docling-graph
+extraction act with a domain-neutral template (`ExtractedAssertions`, no `claim_type`), plus a deterministic
+adaptation (`to_facts`). One LLM act reads the CHECKABLE ASSERTIONS out of a chunk of subject text, quoted
+VERBATIM so each can be cited faithfully and mapped back to its source element (SEG-4). Used by the subject
+compliance pipeline; `claim_extraction` remains the ad path (typed `Claim`s).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rag_wright.capabilities.dg_extraction import aextract_parties, edge
+from rag_wright.contracts.compliance import CheckableFact
+
+__all__ = ["ExtractedAssertion", "ExtractedAssertions", "to_facts", "aassertion_extraction"]
+
+
+class ExtractedAssertion(BaseModel):
+    """One checkable assertion the LLM reads out of a subject document (a docling-graph child entity)."""
+
+    model_config = ConfigDict(graph_id_fields=["assertion_text"], extra="ignore", populate_by_name=True)
+
+    assertion_text: str = Field(
+        description=("One checkable factual assertion / claim / statement the document makes, quoted VERBATIM "
+                     "from the source text -- the exact words (one assertion per entry), so it can be cited "
+                     "faithfully. Do NOT paraphrase, summarize, or merge multiple assertions."))
+    actor: str = Field(
+        default="",
+        description=("DEON-5: the ROLE of the party this assertion involves -- a role word, NOT a person's or "
+                     "company's name. Choose the general role: advertiser, endorser, expert, manufacturer, "
+                     "seller, employer, or party. (E.g. 'Dr. Miller recommends ...' -> endorser, not 'Dr. "
+                     "Miller'.) Lets a rule that binds a role be gated to documents where that role appears. "
+                     "Empty if no clear actor."))
+
+
+class ExtractedAssertions(BaseModel):
+    """The subject document and the distinct checkable assertions it makes (the docling-graph root entity)."""
+
+    model_config = ConfigDict(graph_id_fields=["subject"], extra="ignore", populate_by_name=True)
+
+    subject: str = Field(description="A short label for the subject (a headline phrase or the document topic)")
+    assertions: list[ExtractedAssertion] = edge(
+        "MAKES_ASSERTION", default_factory=list,
+        description="The distinct checkable assertions the document makes (one entry per assertion, verbatim)")
+
+
+def to_facts(extracted: ExtractedAssertions, *, source_doc: str) -> list[CheckableFact]:
+    """DETERMINISTIC (no model): adapt extracted assertions to `CheckableFact`s. Blank assertion skipped;
+    `fact_id` = content-hash. Domain-neutral -- no `claim_type` (that is the `claim_extraction` specialization).
+    The structural locator (section / ¶ / bullet) is attached later, in SEG-4. DEON-5: an extracted `actor` rides
+    as a dimension-agnostic `Constraint("actor", ...)` on the fact's `scope`."""
+    from rag_wright.contracts.compliance import Constraint
+
+    out: list[CheckableFact] = []
+    for index, item in enumerate(extracted.assertions):
+        text = (item.assertion_text or "").strip()
+        if not text:
+            continue
+        actor = (getattr(item, "actor", "") or "").strip().lower()
+        scope = [Constraint(dimension="actor", value=actor)] if actor else []
+        out.append(CheckableFact(
+            fact_id=CheckableFact.make_id(source_doc, index, text), source_doc=source_doc, assertion_text=text,
+            scope=scope))
+    return out
+
+
+async def aassertion_extraction(text: str, *, model: Any, source_doc: str,
+                                aextract_fn: Any = aextract_parties) -> list[CheckableFact]:
+    """Extract the checkable assertions (verbatim) from a chunk of subject text -> `CheckableFact`s: the
+    docling-graph verbatim-binding extraction act fills `ExtractedAssertions`, then `to_facts` adapts.
+    Returns [] if extraction yields nothing. `aextract_fn` is injected for hermetic tests."""
+    extracted = await aextract_fn(text, model, template=ExtractedAssertions, extraction_contract="direct")
+    if extracted is None:
+        return []
+    return to_facts(extracted, source_doc=source_doc)

rag_wright/capabilities/chunk_read.py

@@ -0,0 +1,58 @@
+"""chunk_read (FR-Q, T38): the governed text-rehydration step between fusion and synthesis.
+
+Fusion (FR-Q.4) produces a capped evidence set of `chunk_id`s; synthesis (FR-Q.5) extracts over full
+chunk text. But the retrieval index does not hold the text (it is dense-over-summary), so the `chunk_id`s
+must be rehydrated to their text first. `chunk_read` is that step: it reads the chunk-text sidecar (T40,
+`store/chunk_text.py`) and returns the full text per `chunk_id`, in the requested order.
+
+It is a governed, discovered, bound capability, not caller-side plumbing: the compiler binds it as an
+in-process `function` node under the `chunk_read` slug, so rehydration is a real registered capability with
+its own contract, discoverable by representative queries. It drops nothing — a `chunk_id` that cannot be
+rehydrated (an orphan, or an id the sidecar never received) is a pipeline inconsistency, raised loud,
+never a silent evidence drop (the same no-silent-drop discipline as FR-Q.6's no-claim-without-a-citation).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from rag_wright.store.chunk_text import ChunkTextStore
+
+
+class ChunkText(BaseModel):
+    """One rehydrated chunk: its id, full text (from the T40 sidecar), and its source document.
+
+    `source_doc_id` is provenance, derived from the `chunk_id` (`<source_doc_id>:<index>:<hash>`), so it
+    travels with the text into synthesis without a second store read.
+    """
+
+    chunk_id: str
+    text: str
+    source_doc_id: str
+
+
+class ChunkReadResult(BaseModel):
+    """The rehydrated evidence for synthesis: full text per `chunk_id`, in the requested order."""
+
+    chunks: list[ChunkText]
+
+
+def chunk_read(chunk_ids: list[str], *, text_store: ChunkTextStore) -> ChunkReadResult:
+    """Rehydrate `chunk_ids` to their full text via the sidecar, order-preserving, dropping nothing.
+
+    A `chunk_id` with no persisted text raises `KeyError`: rehydration cannot silently drop evidence, so
+    a chunk that retrieval surfaced but the sidecar cannot supply is surfaced as an error, not skipped.
+    """
+    chunks: list[ChunkText] = []
+    for chunk_id in chunk_ids:
+        text = text_store.get(chunk_id)
+        if text is None:
+            raise KeyError(
+                f"chunk_read: no persisted text for chunk_id {chunk_id!r} — cannot rehydrate "
+                "(orphaned chunk or an id the ingest sidecar never received); evidence is not dropped"
+            )
+        source_doc_id = chunk_id.rsplit(":", 2)[0]  # <source_doc_id>:<chunk_index>:<content_hash>
+        chunks.append(ChunkText(chunk_id=chunk_id, text=text, source_doc_id=source_doc_id))
+    return ChunkReadResult(chunks=chunks)
+
+

rag_wright/capabilities/chunk_write.py

@@ -0,0 +1,163 @@
+"""Chunk write + incremental upsert (FR-I.3, FR-I.5): assemble chunk records and write them, gated.
+
+This is the ingestion write leg: it assembles a `ChunkRecord` (T3) from a chunk (T17, summary +
+text) and its embedding (T19, dense + sparse), then upserts it into the store by `chunk_id` (a
+re-write updates in place, never duplicates). Ingestion is incremental, resumable, and idempotent: a
+content-hash gate skips an unchanged document (effectively no work); per-document and per-chunk
+checkpoints let a run resume where it stopped; and a document whose write fails lands in a
+dead-letter queue.
+
+Chunk write is a seam-bound pipeline node, not a capability discovered by representative queries, so
+it registers nothing and authors no ARD manifest (SPEC section 5). It talks to the store only through
+the swappable `Store` seam (T13), so it works against ArcadeDB or the LanceDB fallback unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Mapping, Optional
+
+from rag_wright.capabilities.embedding import ChunkEmbedding
+from rag_wright.capabilities.rlm_chunking import Chunk
+from rag_wright.contracts.chunk import ChunkRecord, MetadataValue
+from rag_wright.contracts.identifiers import ChunkId
+from rag_wright.store.chunk_text import ChunkTextStore
+from rag_wright.store.seam import Store
+
+WriteStatus = Literal["written", "skipped", "dead_lettered"]
+
+
+@dataclass(frozen=True)
+class DocumentWriteResult:
+    """The outcome of writing one document's chunks."""
+
+    source_doc_id: str
+    status: WriteStatus
+    written_count: int
+    error: Optional[str] = None
+
+
+def to_chunk_record(
+    chunk: Chunk,
+    embedding: ChunkEmbedding,
+    *,
+    source_doc_id: str,
+    source_metadata: Optional[dict[str, MetadataValue]] = None,
+) -> ChunkRecord:
+    """Assemble a `ChunkRecord` from a chunk and its embedding, checking the ids agree.
+
+    The `chunk_id` is recomputed deterministically from `(source_doc_id, chunk_index, text)` (T1) and
+    must match both the chunk's and the embedding's `chunk_id`. Keywords and entity mentions are empty
+    here; they are added by the metadata/extraction stages, not the write.
+    """
+    chunk_id = ChunkId.of(source_doc_id, chunk.chunk_index, chunk.text)
+    if chunk_id.value != chunk.chunk_id or embedding.chunk_id != chunk.chunk_id:
+        raise ValueError(
+            f"chunk_id mismatch: recomputed {chunk_id.value!r}, chunk {chunk.chunk_id!r}, "
+            f"embedding {embedding.chunk_id!r}"
+        )
+    return ChunkRecord(
+        chunk_id=chunk_id,
+        summary=chunk.summary,
+        dense_vector=embedding.dense_vector,
+        sparse_vector=embedding.sparse_vector,
+        source_metadata=source_metadata or {},
+    )
+
+
+class ChunkWriter:
+    """Writes chunk records to the store, content-hash gated with checkpoints and a dead-letter queue.
+
+    Checkpoints and the dead-letter queue are files under `checkpoint_dir`; the store holds the chunk
+    records (summary + vectors). The full chunk text the index omits is persisted to `text_store`, the
+    chunk-text sidecar (T40), under the SAME content-hash gate, so the index and the sidecar are driven
+    by one decision and never diverge. On resume, chunks already recorded in a document's checkpoint are
+    skipped for both.
+    """
+
+    def __init__(self, store: Store, *, text_store: ChunkTextStore, checkpoint_dir: Path) -> None:
+        self._store = store
+        self._text_store = text_store
+        self._checkpoints = Path(checkpoint_dir) / "checkpoints"
+        self._dead_letter = Path(checkpoint_dir) / "dead_letter"
+        self._checkpoints.mkdir(parents=True, exist_ok=True)
+        self._dead_letter.mkdir(parents=True, exist_ok=True)
+
+    def write_document(
+        self,
+        source_doc_id: str,
+        content_hash: str,
+        records: list[ChunkRecord],
+        *,
+        texts: Mapping[str, str],
+    ) -> DocumentWriteResult:
+        """Write a document's chunk records, upserting by `chunk_id`. Gated, resumable, dead-lettered.
+
+        `texts` maps each record's `chunk_id` to its full chunk text, persisted to the sidecar alongside
+        the index upsert. A record without a matching text is rejected before any write, so a chunk can
+        never land in the index without its text in the sidecar (the lifecycle-coupling guard).
+        """
+        missing = [r.chunk_id.value for r in records if r.chunk_id.value not in texts]
+        if missing:
+            raise ValueError(f"no sidecar text supplied for chunk_ids: {missing}")
+
+        checkpoint = self._load_checkpoint(source_doc_id)
+        same_content = checkpoint is not None and checkpoint["content_hash"] == content_hash
+        if same_content and checkpoint["status"] == "complete":
+            return DocumentWriteResult(source_doc_id, "skipped", 0)  # content-hash gate: no work
+
+        written = set(checkpoint["written"]) if same_content else set()  # resume, or start fresh
+        newly = 0
+        try:
+            for record in records:
+                chunk_id = record.chunk_id.value
+                if chunk_id in written:
+                    continue  # already written on an earlier run (per-chunk checkpoint)
+                self._store.upsert_chunk(record)
+                self._text_store.put(record.chunk_id, texts[chunk_id])  # sidecar, same gate as the index
+                written.add(chunk_id)
+                newly += 1
+                self._save_checkpoint(source_doc_id, content_hash, written, "in_progress")
+        except Exception as exc:  # noqa: BLE001 — a failed document is dead-lettered, not raised
+            self._save_checkpoint(source_doc_id, content_hash, written, "in_progress")
+            self._write_dead_letter(source_doc_id, content_hash, str(exc))
+            return DocumentWriteResult(source_doc_id, "dead_lettered", newly, error=str(exc))
+
+        self._save_checkpoint(source_doc_id, content_hash, written, "complete")
+        self._clear_dead_letter(source_doc_id)
+        return DocumentWriteResult(source_doc_id, "written", newly)
+
+    def dead_letter_ids(self) -> set[str]:
+        """The source-doc ids currently in the dead-letter queue."""
+        return {path.stem for path in self._dead_letter.glob("*.json")}
+
+    # --- checkpoint / dead-letter files ---------------------------------------------------------
+
+    def _checkpoint_path(self, source_doc_id: str) -> Path:
+        return self._checkpoints / f"{source_doc_id}.json"
+
+    def _load_checkpoint(self, source_doc_id: str) -> Optional[dict]:
+        path = self._checkpoint_path(source_doc_id)
+        return json.loads(path.read_text(encoding="utf-8")) if path.exists() else None
+
+    def _save_checkpoint(
+        self, source_doc_id: str, content_hash: str, written: set[str], status: str
+    ) -> None:
+        self._checkpoint_path(source_doc_id).write_text(
+            json.dumps(
+                {"content_hash": content_hash, "written": sorted(written), "status": status},
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+
+    def _write_dead_letter(self, source_doc_id: str, content_hash: str, error: str) -> None:
+        (self._dead_letter / f"{source_doc_id}.json").write_text(
+            json.dumps({"content_hash": content_hash, "error": error}, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    def _clear_dead_letter(self, source_doc_id: str) -> None:
+        (self._dead_letter / f"{source_doc_id}.json").unlink(missing_ok=True)