rag-wright 0.12.0__tar.gz → 0.14.0__tar.gz

{rag_wright-0.12.0 → rag_wright-0.14.0}/.claude/skills/authoring-a-capability/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: authoring-a-capability
 description: >-
-  How to author a new RAG_Wright engine capability of any kind (subgraph, function, model, agent_skill, mcp_tool)
-  so it is registered, ARD-discoverable, and invokable by name through the engine API. Use it whenever you add a
-  new capability or a new-domain product/graph needs one: it gives the shared registration + ARD + invocation
+  How to author a new capability on RAG_Wright, in your product's own pack or in the engine, of any kind
+  (subgraph, function, model, agent_skill, mcp_tool), so it is registered, ARD-discoverable, and invokable by name
+  through the engine API. Use it whenever a product (or the engine) adds a capability: it gives the shared registration + ARD + invocation
   contract (the four surfaces + the definition of done), the per-kind implementation specifics, and the
   conformance guardrail that keeps the catalog honest. Grounded against the real code; keep it in step with it.
 ---
@@ -93,6 +93,12 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
   (the reference pack: `packs/contracts/subgraphs/typed_property_retrieval.py`). A `production_<slug>(*, store, ...) -> CompiledGraph` builder: `g = StateGraph(_State)`,
   add nodes/edges with `START`/`END`, `return g.compile()`. Nodes call functions/models (compose).
 - **Invoke:** the co-located `async def ainvoke(resources, inputs)` factory (impl_ref target) builds + awaits the graph.
+- **An ingestion capability already has its graph.** `build_ingestion(...)` compiles one (LGI, ADR-0124): its
+  `production_<slug>` returns `pipeline.graph(ws, cache_dir=...)` (the whole run: each source through the
+  per-document graph parse -> chunk -> segment -> index -> extract -> write -> hooks -> children), and its `ainvoke`
+  runs `await pipeline.aingest(resources, sources, cache_dir=...)`. Do not wrap it in a second `StateGraph`. For a
+  long ingest, pass your own LangGraph checkpointer and a `run_id` to `aingest` so an interrupted run resumes
+  (`building-an-ingestion-capability`).
 - Retry/dead-letter come from the graph scaffold, not the invoker. `CapabilityManifest` has no contract field (only
   the internal `CapabilityRegistry.register(contract=...)` takes one); where the typed I/O must be declared, set
   `capability_interface` on the manifest (`CapabilityInterface`, from `rag_wright.pack_sdk`).

{rag_wright-0.12.0 → rag_wright-0.14.0}/.claude/skills/building-an-ingestion-capability/SKILL.md

@@ -154,6 +154,10 @@ category.
 
 ## 5. Spreadsheets, tables and embedded files
 
+- **Blank PDF pages** are read as empty, never sent to the vision model (engine 0.13.0). On a parse cache built
+  by an earlier engine with `VISION_OCR` configured, run `find_blank_pages_with_text(cache_dir, sources)` once:
+  delete each finding's `cache_files` and re-ingest that document (its blank pages may hold invented text).
+
 - **Hidden sheets** are ingested by default; `IngestSource(include_hidden_sheets=False)` skips them (listed in
   `DocumentReport.skipped_hidden_sheets`).
 - **Blank rows inside a table**: the parse cuts a sheet's table at every blank row; the engine glues a piece back
@@ -193,6 +197,13 @@ category.
   whose continuation rows sit under its main row needs a `unit_grouper=` that keeps them together, or a
   `document_hook=` that reads the whole table with `table_rows` and writes the grouped record. An entity several units
   mention (a case its trial rows share) is emitted by its key from each unit and upserted by that key.
+- **Resume a long ingest instead of restarting it.** Pass a LangGraph checkpointer (yours, for example a Postgres
+  saver; the engine ships none) and a `run_id` naming the run:
+  `await pipeline.aingest(ws, sources, cache_dir=CACHE, checkpointer=saver, run_id=batch_id)`. If the process stops,
+  call it again with the same sources, `cache_dir`, checkpointer and `run_id`: each document carries on from its last
+  finished stage, and nothing that finished runs again (no repeat extractor calls). A finished `run_id`, or different
+  sources, raise `ValueError`: a new run gets a new id. The graph state is built-in values only, so it works under
+  LangGraph's strict msgpack mode; a tuple inside a record's free-form `props` comes back as a list after a resume.
 - **Re-ingest.** Parsing is cached by content hash, so re-running is cheap. The default writer upserts nodes by their
   key but is not fully idempotent for edges (engine gap G8): when a source is re-run, remove its previous records
   first (`kg_delete` on the provenance your records carry, such as a per-source property) and write again.
@@ -212,7 +223,9 @@ category.
    cost per document before a bulk run.
 5. **Register the pipeline as a capability** (`authoring-a-capability`): a subgraph whose `ainvoke(resources, inputs)`
    builds it with `build_ingestion` over the workspace and runs `aingest`, so your product's ingest workflow, an
-   agent and an eval all invoke it by name.
+   agent and an eval all invoke it by name. The pipeline IS a LangGraph graph: `pipeline.graph(ws, cache_dir=...)`
+   returns the compiled run (each source through the per-document graph), which is what your `production_<slug>`
+   returns; do not wrap it in another graph.
 6. **Field-level accuracy, not only structure**: `evaluate_ingestion` checks units; the records' values are checked
    against gold records (`creating-evals`, extraction scoring over what `kg_read` returns).
 

{rag_wright-0.12.0 → rag_wright-0.14.0}/.claude/skills/specifying-a-product-on-the-engine/SKILL.md

@@ -58,7 +58,7 @@ Every product item lands in one or more of these. The route column is where the
 | **Domain knowledge**: vocabulary, schema, constraints, synonyms, decision criteria | "controlled vocabularies", "the ontology", "mandatory fields", "valid ranges" | `EngineConfig(pack=...)` (the store creates the declared types on `open_workspace`); your capabilities read value sets and SHACL shapes with `rdflib` / `pyshacl` | `authoring-a-capability` | ontology authoring |
 | **Ingestion**: documents, spreadsheets, images, embedded files into the graph | "parse the forms", "load the lab reports", "idempotent re-runs" | `build_ingestion` (your extractor + optional hooks) → `aingest`; `IngestSource`, `IngestionTuning`, `table_rows` / `TableRow`, `evaluate_ingestion`, `check_extraction`; `KgNode` / `KgEdge` | `building-an-ingestion-capability` | KG construction |
 | **Entity and registry resolution** | "resolve against the yarn register", "queue unresolved mentions" | your `document_hook`; the entity-resolution building blocks on `rag_wright.pack_sdk` | `building-an-ingestion-capability` | entity resolution |
-| **A typed query or retrieval** | "find similar cases", "filter the table", "the dossier" | a query capability of your pack composing the primitives (`kg_read`, `kg_edges`, `NOT_NULL`, hybrid search from `rag_wright.pack_sdk`), registered with `CapabilityManifest` + `register_capability` / `load_pack`, invoked with `ainvoke_subgraph` | `authoring-a-capability` | authoring capabilities |
+| **A typed query or retrieval** | "find similar cases", "filter the table", "the dossier" | a query capability of your pack composing the primitives (`kg_read`, `kg_edges`, `NOT_NULL`, `Range`, hybrid span search with `span_search` from `rag_wright.api`), registered with `CapabilityManifest` + `register_capability` / `load_pack`, invoked with `ainvoke_subgraph` | `authoring-a-capability` | authoring capabilities |
 | **A cited answer, or a refusal** | "every answer cites its source", "say when it is not in the records" | `agenerate_answer` over `EvidenceItem`s (an answer states its support; "none" abstains), `ajudge_spans` | `authoring-a-capability` | concepts (answers) |
 | **A typed decision or classification** | "classify the structure", "which of these is it" | `classifier-opportunity-analysis` first; then rules, a trained classifier, or the decision model (`jev_decision` from `engine_capabilities()`, criteria in the pack) | `classifier-opportunity-analysis` → `setfit` / `laya` | classification and decision models |
 | **A deterministic workflow behind a button** (mode **D**) | "upload, confirm, save", "export CSV" | a product **operation** (one function per user operation) calling your capabilities; the route calls the operation | `building-a-product-backend` | domain-adaptation step 8 |

{rag_wright-0.12.0/src/rag_wright/.agents → rag_wright-0.14.0/.claude}/skills/using-the-rag-wright-engine/SKILL.md

@@ -27,8 +27,11 @@ open-core and domain-neutral; your product brings the domain. Hard rules:
   `EngineConfig`/`StoreConfig` (`StoreConfig.from_env()` reads `ARCADEDB_*`)/`open_workspace`
   (`temporary_workspace`/`drop_workspace` for disposable and removed databases), the invokers
   (`ainvoke_subgraph`/`invoke_model`/`ainvoke_model`), discovery (`capability_index`/`discover`), the KG accessors
-  (`kg_read` with `key_range`, `kg_write`, `kg_edges` with `NOT_NULL`, `kg_count`/`kg_delete`/`kg_update`,
-  `entities_by_name`, `span_positions`), `pack_store(ws, cls)` (build your pack's store extension over the
+  (`kg_read`, `kg_write`, `kg_edges`, `kg_count`/`kg_delete`/`kg_update`, all filtering by `where` values that
+  are equality, a list for membership, `NOT_NULL` or a `Range(gt=, ge=, lt=, le=)` on any number of fields,
+  evaluated in the store;
+  `entities_by_name`, `span_positions`), hybrid span search (`span_search` / `aspan_search`: cited spans from
+  the dense and sparse index, fused in the store), `pack_store(ws, cls)` (build your pack's store extension over the
   workspace's store; the store itself stays private), metering and tracing (`measure_usage`, `record_usage`,
   `traced_run`/`traced_step`, and for code emitting its own generations `tracing_on`/`trace_level`/
   `start_generation`/`finish_generation`/`flush_tracing`), the query embedder (`ws.embedder` where you hold a
@@ -38,7 +41,8 @@ open-core and domain-neutral; your product brings the domain. Hard rules:
   (`parse_document`/`aparse_document`, `parse_document_bytes`/`aparse_document_bytes` for uploads,
   `source_document`/`table_rows`, `decode_bbox`, `document_of`), and the **ingestion surface**: `build_ingestion`
   (returns an `IngestionPipeline`; `await pipeline.aingest(ws, sources, cache_dir=...)` returns an
-  `IngestionReport`), its hook contracts (`Segmenter`, `SpanTagger`, `UnitGrouper`, `BoundaryDecider`,
+  `IngestionReport`; the pipeline is a LangGraph graph, `pipeline.graph(ws, cache_dir=...)`, and `aingest` with
+  `checkpointer=` and `run_id=` resumes an interrupted run), its hook contracts (`Segmenter`, `SpanTagger`, `UnitGrouper`, `BoundaryDecider`,
   `UnitRepresentative`, `BoundaryDiscoverer` with `default_chunk_discoverer(guidance=...)`, `Extractor`,
   `RecordWriter`, `DocumentHook`, checked by `check_tiling`/`check_units`/`check_extraction`), `IngestionTuning`,
   `IngestSource` (a `path`, or `data` + `name` for bytes; `table_mode`, `include_hidden_sheets`, your own `metadata`

rag_wright-0.14.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.14.0"
+}

{rag_wright-0.12.0 → rag_wright-0.14.0}/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to RAG_Wright are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.13.0...0.14.0) (2026-10-17)
+
+
+### Features
+
+* **LGI-1:** each document is ingested through a LangGraph graph of the stages ([24c15df](https://github.com/fzaidi-dai/RAG_Wright/commit/24c15dfc692b463382f18b183c551127e7092c0c))
+* **LGI-2:** the whole ingest run is one LangGraph graph ([e38e9c8](https://github.com/fzaidi-dai/RAG_Wright/commit/e38e9c8733fb0bcb4da51e71e3e7093fbde4b9c3))
+* **LGI-3:** an interrupted ingest resumes from its last finished stage ([9970189](https://github.com/fzaidi-dai/RAG_Wright/commit/9970189d6d5759dc4a1eeaccb35d734cc05e886e))
+
+## [0.13.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.12.0...0.13.0) (2026-10-15)
+
+
+### Features
+
+* **PS-35:** migrate a pre-0.2.0 database's Span fields through rag_wright.api ([856f956](https://github.com/fzaidi-dai/RAG_Wright/commit/856f956f674c731d170878d44ec3fef980a10ba9))
+* **PS-44:** range filters on any number of KG fields, evaluated in the store (TexWright ER-1) ([cc62c49](https://github.com/fzaidi-dai/RAG_Wright/commit/cc62c49000161567869d46127bb158db16106c28))
+* **PS-45:** a public hybrid span search on rag_wright.api (engine gap G24) ([4aa802f](https://github.com/fzaidi-dai/RAG_Wright/commit/4aa802fdc6cf12a3c732aa7a41e4de6240dd05da))
+* **PS-47:** find cached parses holding text a VLM invented for a blank page ([ff92d81](https://github.com/fzaidi-dai/RAG_Wright/commit/ff92d81956590002418ef50f41dee54e0b0b6ef8))
+
+
+### Bug Fixes
+
+* **PS-46:** a page with no ink is blank, never escalated to the VLM (TexWright 2026-10-15) ([fc633a8](https://github.com/fzaidi-dai/RAG_Wright/commit/fc633a84aa52a89de5b79d90b50d80f7d622d792))
+
 ## [0.12.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.11.0...0.12.0) (2026-10-15)
 
 

{rag_wright-0.12.0 → rag_wright-0.14.0}/CLAUDE.md

@@ -55,9 +55,19 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 
 ## Start of every session
 
-> **CURRENT STATE (2026-10-15): `rag-wright` 0.11.0 is RELEASED** (PR #13: PS-40 the product-building skills ship,
+> **CURRENT STATE (2026-10-17): the LangGraph ingestion workstream is COMPLETE, unreleased** (LGI-1..5,
+> `docs/specs/langgraph-ingestion/plan.md`, ADR-0124 amended): `build_ingestion` is a LangGraph graph
+> (`IngestionPipeline.graph`, per-document `document_graph`), `aingest(..., checkpointer=, run_id=)` resumes an
+> interrupted run (built-in state, strict msgpack safe), `IngestionReport.from_dict`; live old-vs-new parity identical;
+> guide `rulewright-migration-0.14.0.md` (next release 0.14.0). Next: PS-48 (harness tests onto the fabric fixture,
+> proposed, not started), EV-7, PS-30, PS-33. Before it,
+> **(2026-10-15): `rag-wright` 0.13.0 is RELEASED** (PR #15): PS-35 `migrate_span_fields` on the API,
+> PS-44 `Range` KG filters (TexWright ER-1), PS-45 `span_search` (G24), PS-46 blank PDF pages never sent to the VLM
+> (TexWright's report; ADR-0062 amended), PS-47 `find_blank_pages_with_text` (audit of pre-fix parse caches); guide
+> `rulewright-migration-0.13.0.md`. Open: harness behaviour tests onto the fabric fixture, EV-7, PS-30, PS-33. Before it,
+> **`rag-wright` 0.11.0 is RELEASED** (PR #13: PS-40 the product-building skills ship,
 > PS-41 the skills audit, PS-42 by-slug registration; RuleWright's guide `docs/specs/public-surface/rulewright-migration-0.11.0.md`).
-> **PS-43 done, unreleased (next: 0.12.0)**: `worker_spec(definition=)`, `docs/harness.md` (tables generated by
+> **PS-43 RELEASED as 0.12.0 (2026-10-15, PR #14)**: `worker_spec(definition=)`, `docs/harness.md` (tables generated by
 > `scripts/build_harness_doc.py`), the harness source cleared of RuleWright's vocabulary with a guard; guide
 > `rulewright-migration-0.12.0.md`. Before it,
 > **(2026-10-14): PS-32 done: the agent harness is the engine's third public tier `rag_wright.harness`**

{rag_wright-0.12.0 → rag_wright-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.12.0
+Version: 0.14.0
 Summary: A domain-retargetable, open-core engine for hybrid retrieval + knowledge-graph RAG: parsing, chunking, embedding, hybrid search, reranking, graph extraction, entity resolution, ontology-driven knowledge, and a capability runtime.
 Project-URL: Homepage, https://github.com/fzaidi-dai/RAG_Wright
 Project-URL: Repository, https://github.com/fzaidi-dai/RAG_Wright

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/ArcadeDB_Local.md

@@ -60,7 +60,7 @@ typed edges, and `ComplianceStore` creates `Requirement`, so they appear the fir
 
 A database created before the `Span` field rename (`contract_id`, `function`, `functions` became `document_id`,
 `primary_tag`, `tags`) is refused by `ensure_schema` with a `RuntimeError`; migrate it once with
-`uv run python -u scripts/migrate_span_fields.py <database>`.
+`migrate_span_fields(config, corpus=...)` from `rag_wright.api` ([installation](installation.md)).
 
 ## Stop / reset
 

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/adr/0062-tiered-ocr-scan-quality-vlm-escalation.md

@@ -84,3 +84,14 @@ now, a self-hosted vLLM-Gemma-4 later for data sovereignty (only `base_url` chan
   as the escalation provider for data sovereignty; (3) routing the vision call **through the async model seam**
   for true thread cancellation (today `to_thread` unblocks the caller at the deadline but the docling thread
   runs on); (4) classical preprocessing stays available as a cheap first pass but is not the heavy-scan fix.
+
+## Amendment (2026-10-15, PS-46): a blank page is not degraded
+
+A page with no ink read as both "blurry" (a white page has Laplacian variance 0) and "faint" (no pixel below 128),
+so it was escalated, and a VLM asked to transcribe an empty page invents one (TexWright: meeting minutes in another
+language, kept in the parse). The gate now measures `ink_frac` (pixels below 200, faint grey included) and returns
+`ScanQuality.BLANK` for a page with no OCR text and `ink_frac` at most 1e-4: never escalated, never flagged
+needs-rescan, listed in `TieredOCRReport.blank_pages`. Measured margin: blank 0; the heavy faint scan 0.077-0.082
+(its `dark_frac` is 0.0025, which is why `dark_frac` alone cannot separate it); the sparsest real fixture page
+0.019. The post-escalation check stays a flag rather than dropping the VLM text: it is an English word-rate test,
+and a correct transcription of a page with few common words (a number-heavy table) fails it.

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/adr/0124-generic-ingestion-builder-and-hooks.md

@@ -253,3 +253,28 @@ writing to change one decision (engine gaps G3/G4).
   (7,297 blocks, 14,059 spans) fingerprint identically before and after; a live Aimmune re-ingest is record-identical
   to ING-8e. `tests/spans/test_segmentation_vocab.py` locks the vocabulary and checks the built patterns decide as the
   original literals did.
+
+## LGI-1 addendum (2026-10-17): each document runs through a LangGraph graph
+
+- **Context.** Products register their `build_ingestion` pipeline as a `subgraph` capability, but the generic path
+  was plain asyncio: no graph existed, so the capability kind's promise (a compiled `StateGraph`) did not hold, and
+  the graph version of ingestion (ADR-0050) lived only in the reference pack.
+- **Decision.** `IngestionPipeline.document_graph(ws, stages)` builds the per-document graph over the same
+  `IngestionStages`: parse -> chunk -> segment -> index -> extract -> write -> document_hook -> document_node ->
+  children, with every stage routing a failure to a `dead_letter` node (never raised). Embedded files run through the
+  same graph. `aingest` drives it, one compiled graph per run. Stages stay sequential per document (index before
+  extract), as before. Plan and ledger: `docs/specs/langgraph-ingestion/plan.md` (LGI-2 the run graph, LGI-3 resume).
+- **Consequences.** No public signature, report or progress line changed. Parity is held by a record captured from
+  the asyncio driver before the change (`tests/fixtures/ingestion/parity.json`, 11 scenarios: reports, store
+  contents, hook calls, progress lines), with the scenario inputs committed because freshly built PDFs and OOXML
+  files carry random ids and timestamps.
+- **LGI-2 (2026-10-17): the run is one graph.** `IngestionPipeline.graph(ws, *, cache_dir)` compiles the whole run:
+  `start` sends each source to `document` (the per-document graph; at most `document_concurrency` in flight, by a
+  semaphore in the node so a direct caller needs no config), `finish` builds the `IngestionReport`. `aingest` runs
+  it. The report's documents are now in source order (they were in completion order, which varied run to run).
+- **LGI-3 (2026-10-17): an interrupted run resumes.** `aingest(..., checkpointer=, run_id=)` checkpoints every stage
+  of every document (embedded children included) on the thread `run_id`; calling it again with the same sources and
+  `run_id` resumes from each document's last finished stage. A finished run, different sources, or only one of the
+  two arguments raise `ValueError`. The graph state holds built-in values only (each node loads the typed values it
+  needs), because LangGraph's strict msgpack mode blocks the engine's types; a tuple in a record's free-form `props`
+  comes back as a list after a resume. `IngestionReport.from_dict` rebuilds the report from `graph()`'s output.

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/api/README.md

@@ -68,6 +68,10 @@ Members: `STRUCTURED_REASONING` (`'structured_reasoning'`), `STRUCTURED_REASONIN
 
 One ranked capability match from `discover` — enough for an agent to pick and invoke it by `slug`.
 
+### `SpanHit(*, span_id: str, text: str, document_id: str, doc_start: Optional[int] = None, doc_end: Optional[int] = None, pages: list[int] = [], bbox: Optional[tuple[float, float, float, float]] = None, primary_tag: str = '', rank: int, found_by: tuple[str, ...]) -> None`
+
+One cited span from `span_search`, best first. `found_by` says which legs found it: `"hybrid"` (the fused dense + sparse search) and/or `"dense"` (the dense floor). `bbox` is `(l, t, r, b)` or None.
+
 ### `KgNode(type: 'str', key_field: 'str', props: 'dict[str, object]') -> None`
 
 A typed KG node to upsert (DD-1b, ADR-0117): `type` is the vertex type, `key_field` the identity field to upsert on, `props` the fields (including `key_field`) as DOMAIN-NATIVE values. The store encodes each prop by its pack-declared storage type -- the caller never serializes to the store's wire format.
@@ -76,6 +80,18 @@ A typed KG node to upsert (DD-1b, ADR-0117): `type` is the vertex type, `key_fie
 
 A typed KG edge to create between two nodes identified by (type, key_field, key). `props` are native values (edge properties are type-driven: edges declare no storage schema).
 
+### `Range(gt: 'Optional[object]' = None, ge: 'Optional[object]' = None, lt: 'Optional[object]' = None, le: 'Optional[object]' = None) -> None`
+
+A `where` value meaning a comparison, evaluated in the store (ER-1): `gt` (>), `ge` (>=), `lt` (<), `le` (<=), at most one lower and one upper bound, at least one bound. Bounds are scalars (numbers compare as numbers, strings lexically). Any number of fields may carry one, beside equality, membership and `NOT_NULL`, on every KG call that takes `where`: `where={"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`.
+
+#### `Range.terms(self) -> 'list[tuple[str, object]]'`
+
+`[(operator, bound), ...]`, lower bound first.
+
+### `BlankPageText(*, source: str, pages: dict[int, str], cache_files: list[str]) -> None`
+
+One cached parse with text on blank pages. `source` is the PDF's path (or the name given with its bytes), `pages` maps each blank page to the text the cached parse holds there, and `cache_files` are the cached parse(s) and their OCR sidecar: delete them, then re-ingest the document so it is parsed again.
+
 ### `EvidenceItem(*, chunk_id: str, text: str, confidence: Optional[str] = None, properties: Optional[list[dict]] = None) -> None`
 
 One piece of grounding evidence: a chunk's text, its `chunk_id` (the citation), and — for a graph-derived fact — its confidence tag (surfaced to the generator, FR-S.4).
@@ -170,10 +186,28 @@ Built by `build_ingestion`; run with `await pipeline.aingest(ws, sources, cache_
 
 Advanced: the individual stage functions bound to a workspace (its store, ingest embedder and tuning), for a domain that drives the stages itself (the reference contract pipeline does). Most domains only need `aingest`.
 
-#### `IngestionPipeline.aingest(self, ws: 'Any', sources: 'Sequence[Union[str, Path, IngestSource]]', *, cache_dir: 'Union[str, Path]') -> 'IngestionReport'`
+#### `IngestionPipeline.aingest(self, ws: 'Any', sources: 'Sequence[Union[str, Path, IngestSource]]', *, cache_dir: 'Union[str, Path]', checkpointer: 'Any' = None, run_id: 'Optional[str]' = None) -> 'IngestionReport'`
 
 Ingest every source (and its embedded children) into the workspace `ws` (from `open_workspace`). `sources` are file paths or `IngestSource`s (a path, or in-memory bytes with a file name); `cache_dir` holds the content-hash-gated parse and chunk caches (a re-ingest of an unchanged file re-uses them). Documents run concurrently up to `tuning.document_concurrency`; a document that fails is dead-lettered in its `DocumentReport`, never raised. Returns the `IngestionReport`. Every model role resolves through the workspace's `EngineConfig.models` (PS-14).
 
+LGI-3, resuming: pass a LangGraph `checkpointer` (yours, e.g. a Postgres saver) and a `run_id` naming the run. If the process stops mid-run, call `aingest` again with the same sources, `cache_dir`, checkpointer and `run_id`: it carries on from the last finished stage of each document, re-running none that finished. A `run_id` whose run finished raises `ValueError` (start a new run with a new id), as do different sources.
+
+#### `IngestionPipeline.graph(self, ws: 'Any', *, cache_dir: 'Union[str, Path]', checkpointer: 'Any' = None) -> 'Any'`
+
+LGI-2: the whole run as one compiled LangGraph `StateGraph`, bound to the workspace `ws`:
+
+start --(one Send per source)--> document --> finish
+
+`document` runs one source through `document_graph` (embedded files included); at most `tuning.document_concurrency` documents are in flight. The input is `{"sources": [...]}` (file paths or `IngestSource`s); the output's `report` is the `IngestionReport` as plain data (`IngestionReport.from_dict` rebuilds it), its documents in source order. This is what `aingest` runs (without `aingest`'s workspace model scoping: wrap the call in `use_workspace_models(ws)` when the workspace overrides model roles). Progress goes to the pipeline's `progress` callback. With a `checkpointer`, every stage of every document is checkpointed on the thread named by the call's `configurable.thread_id` (see `aingest` for resuming). The state holds only built-in values (dicts, lists, strings, numbers, bytes, dates), so it round-trips through any saver, including LangGraph's strict msgpack mode; a tuple inside a record's free-form `props` comes back from a checkpoint as a list.
+
+#### `IngestionPipeline.document_graph(self, ws: 'Any', stages: 'IngestionStages') -> 'Any'`
+
+LGI-1: the per-document ingestion graph, a compiled LangGraph `StateGraph` over `stages` (bound to `ws`):
+
+parse -> chunk -> segment -> index -> extract -> write -> document_hook -> document_node -> children
+
+A stage that raises routes to `dead_letter`, which ends the document with its `DocumentReport.dead_letter` set (never raised, so one bad document never stops the run). `children` ingests each embedded file through this same graph, then links it to its parent. The input is `{doc_id, source, parent_id, child, depth}`; the output's `reports` is the document's `DocumentReport` followed by its children's.
+
 ### `IngestionReport(documents: 'list[DocumentReport]' = <factory>) -> None`
 
 The result of `IngestionPipeline.aingest`: one `DocumentReport` per document (embedded children included). `failed` counts the dead-lettered documents and `succeeded` the rest (properties).
@@ -296,7 +330,7 @@ The semantic boundary-discovery seam: decide chunk boundaries as a partition of
 
 ### `open_workspace(config: 'EngineConfig', *, corpus: 'str', reset: 'bool' = False, create: 'bool' = True) -> 'WorkspaceHandle'`
 
-Resolve (and cache) the workspace for `corpus` (the backend database name) from `config`. Ensures the schema: the neutral engine types, plus `config.pack`'s declared types when set. Raises `RuntimeError` on a database whose `Span` type still has the pre-ING-8d field names (migrate it with `scripts/migrate_span_fields.py`). Returns an opaque `WorkspaceHandle`. `reset=True` drops + recreates the database (test/clean-slate) and bypasses the cache. A missing database is created (logged): that is how a new corpus is provisioned. `create=False` raises `LookupError` instead (PS-27) -- use it wherever the corpus must already exist, so a wrong name fails loudly rather than opening an empty graph.
+Resolve (and cache) the workspace for `corpus` (the backend database name) from `config`. Ensures the schema: the neutral engine types, plus `config.pack`'s declared types when set. Raises `RuntimeError` on a database whose `Span` type still has the pre-ING-8d field names (migrate it with `migrate_span_fields`). Returns an opaque `WorkspaceHandle`. `reset=True` drops + recreates the database (test/clean-slate) and bypasses the cache. A missing database is created (logged): that is how a new corpus is provisioned. `create=False` raises `LookupError` instead (PS-27) -- use it wherever the corpus must already exist, so a wrong name fails loudly rather than opening an empty graph.
 
 One handle per store and corpus is cached for the process. An equal `config` returns it; a different one (new models, options, credentials or pack) returns a new handle that replaces it from then on, so a configuration change takes effect without a restart (PS-16). The new handle reuses the store when the store settings and the pack are unchanged, and the query embedder when the embedding profile is unchanged; a call still holding the old handle finishes on the old config.
 
@@ -304,6 +338,10 @@ One handle per store and corpus is cached for the process. An equal `config` ret
 
 Drop the database `corpus` (PS-37): everything in it, the retrieval index and the knowledge graph, is deleted and cannot be recovered. Returns True if it existed, False if there was nothing to drop. A cached handle for it is closed and forgotten, so a later `open_workspace` starts fresh. A missing or blank `corpus` raises `ValueError`: the name is always explicit, never a default database.
 
+### `migrate_span_fields(config: 'EngineConfig', *, corpus: 'str', batch: 'int' = 5000, progress: 'Optional[Callable[[int, int], None]]' = None) -> 'int'`
+
+Migrate the database `corpus` from the pre-0.2.0 `Span` field names (`contract_id`, `function`, `functions`) to the generic ones (`document_id`, `primary_tag`, `tags`), the database `open_workspace` refuses until this has run (PS-35). Values are copied in batches of `batch` and the old properties dropped; `progress(done, total)` is called after each batch. Idempotent: returns the number of records moved, 0 when already migrated. The database must exist (`LookupError` otherwise; it is never created), and a missing or blank `corpus` raises `ValueError`. Afterwards the schema is checked, so a database this returns for opens with `open_workspace`.
+
 ### `temporary_workspace(config: 'EngineConfig', *, prefix: 'str' = 'tmp') -> 'Iterator[WorkspaceHandle]'`
 
 A workspace on a fresh database, `<prefix>_<12 hex>`, dropped when the block exits, whether it succeeds or raises (PS-37). For a probe or a measurement whose database must not outlive it: `with temporary_workspace(config, prefix="probe") as ws: ...`.
@@ -386,7 +424,7 @@ Rank the live ARD catalog by semantic match to `query`; return the top `k` (opti
 
 ### `kg_read(ws: 'WorkspaceHandle', node_type: 'str', *, where: 'Optional[dict]' = None, fields: 'Optional[list]' = None, distinct: 'Optional[str]' = None, order_by: 'Optional[str]' = None, limit: 'Optional[int]' = None, key_range: 'Optional[tuple]' = None) -> 'list[dict]'`
 
-Read typed nodes of `node_type` from the workspace (see `Store.kg_read`). Equality/`IN` filters, a `key_range=(field, lo, hi)` range, projection, distinct, order, limit; an empty list `where` value is scope-to-nothing -> `[]`.
+Read typed nodes of `node_type` from the workspace (see `Store.kg_read`). Each `where` value is a scalar (equality), a list (membership; an empty list is scope-to-nothing -> `[]`), `NOT_NULL` (presence) or a `Range` (comparisons, on any number of fields: `{"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`); all filters are AND-ed and evaluated in the store. `key_range=(field, lo, hi)` is the half-open shorthand (`lo <= field < hi`). Then projection, distinct, order and limit.
 
 ### `kg_write(ws: 'WorkspaceHandle', nodes: 'list', edges: 'Any' = ()) -> 'None'`
 
@@ -398,7 +436,7 @@ Generic edge TRAVERSAL over the workspace (see `Store.kg_edges`): node-start out
 
 ### `kg_count(ws: 'WorkspaceHandle', type_name: 'str', *, where: 'Optional[dict]' = None, key_range: 'Optional[tuple]' = None) -> 'int'`
 
-The number of vertices or edges of `type_name` matching `where` / `key_range` (see `Store.kg_count`).
+The number of vertices or edges of `type_name` matching `where` / `key_range` (see `Store.kg_count`); `where` as in `kg_read`, `Range` values included.
 
 ### `kg_delete(ws: 'WorkspaceHandle', type_name: 'str', *, where: 'Optional[dict]' = None, key_range: 'Optional[tuple]' = None) -> 'int'`
 
@@ -416,6 +454,14 @@ Resolve an entity NAME to every entity node it matches: `[{entity_id, name, enti
 
 Every span of `document` with its position provenance, ordered by document position. Each row: `span_id`, `parent_chunk_id`, `span_index`, `text`, `primary_tag` (the span tagger's primary tag, "" if untagged), `document_id`, `doc_start` / `doc_end` (document-absolute offsets), `pages`, and `bbox` DECODED to a `(l, t, r, b)` tuple or None. The engine MECHANISM behind a product's citation/highlight types -- the product wraps these rows into its own presentation type (e.g. `SpanLocation`).
 
+### `span_search(ws: 'WorkspaceHandle', query: 'str', *, k: 'int' = 10, documents: 'Optional[list]' = None, tag: 'Optional[str]' = None, dense_floor: 'int' = 3) -> 'list'`
+
+Hybrid search over the workspace's span index (every ingested span, embedded dense and sparse): the two legs fused by Reciprocal Rank Fusion in the store, with the top `dense_floor` pure-dense spans guaranteed a place, so a strong semantic match a common-token query would push out of the fused pool is kept (0 turns it off). Returns up to `k` `SpanHit`s, best first, each citation-ready: `span_id`, `text`, `document_id`, `doc_start` / `doc_end`, `pages`, `bbox`, `primary_tag`, `rank`, and `found_by` (`"hybrid"` and/or `"dense"`). `documents` scopes it to those source documents in the store (`None` = all, `[]` = nothing); `tag` keeps one primary tag. No reranking: compose `BGEReranker` over the hits if you want one. Raises `RuntimeError` when the workspace has no embedder.
+
+### `aspan_search(ws: 'WorkspaceHandle', query: 'str', *, k: 'int' = 10, documents: 'Optional[list]' = None, tag: 'Optional[str]' = None, dense_floor: 'int' = 3) -> 'list'`
+
+`span_search` off the event loop (the query embedding and the store calls block), for an async caller.
+
 ### `document_of(entity_id: 'str') -> 'str'`
 
 The source-document id embedded in a chunk/span/unit id (`<source_doc_id>:<idx>:<hash>` -> the first, delimiter-safe segment). Empty in -> empty out.
@@ -448,6 +494,10 @@ The number of pages in a PDF (a path or the PDF's bytes), read under the engine'
 
 The async, deadline-bounded twin of `parse_document_bytes` (ADR-0057): runs the docling parse off the event loop.
 
+### `find_blank_pages_with_text(cache_dir: 'Any', sources: 'Iterable[Source]' = (), *, progress: 'Optional[Callable[[int, int], None]]' = None) -> 'list[BlankPageText]'`
+
+Audit the parse cache under `cache_dir` (the one given to `parse_document`, or to `aingest`, which keeps its parses in `parsed/`; searched recursively) for text on blank pages. `sources` are the documents' PDFs, as paths or `(name, bytes)`; files embedded in a parsed package are stored in the cache and audited without being passed. A source that is not a PDF, or has no cached parse, is skipped. `progress(done, total)` is called after each PDF. Raises `FileNotFoundError` when `cache_dir` does not exist.
+
 ### `agenerate_answer(query: 'str', evidence: 'list[EvidenceItem]', *, ws: 'Any', guidance: 'Optional[str]' = None) -> 'GeneratedAnswer'`
 
 A grounded, cited answer to `query` over `evidence`, or an abstention. Empty evidence abstains without a model call; a citation not in the evidence is dropped, and an answer left with no valid citation becomes an abstention (no claim without a citation). `answer_kind` says whether the evidence fully supported the answer (`answered`), only partly (`partial`) or not at all (`abstained`). `guidance` adds your domain's wording to the domain-neutral method.

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/architecture.md

@@ -30,7 +30,7 @@ Everything a product touches is re-exported from `rag_wright.api`; the packages
 | `api/` | the stable, domain-agnostic public surface: config, workspace, invokers, KG accessors, ids, usage | **yes** (in the enforced source set) |
 | `pack_sdk/` | the pack-author tier (PS-8b): re-exports of the engine building blocks a domain pack's code needs beyond `api` (identifiers, the model seam, the LangGraph scaffold, the store protocol, the generic capabilities a pack composes); a pack imports only `api` and `pack_sdk` | **yes** |
 | `capabilities/` | the capability catalog + ARD runtime — `CapabilityManifest`, `registry`, `manifests`, the adapter-free `invoke` client; plus the generic primitives (graph query, retrieval core, embedding, disambiguation, entity resolution, the decision model) | **yes** |
-| `ingestion/` | the generic ingestion mechanism (ADR-0124): `build_ingestion` + the shared `IngestionStages`, the default layout segmenter and structural unit grouper, `table_rows`, `evaluate_ingestion` | **yes** |
+| `ingestion/` | the generic ingestion mechanism (ADR-0124): `build_ingestion` (a LangGraph graph over the shared `IngestionStages`, resumable), the default layout segmenter and structural unit grouper, `table_rows`, `evaluate_ingestion` | **yes** |
 | `subgraphs/` | the generic LangGraph scaffolding (`scaffold.py`), semantic chunking, graph extraction and observability; domain graphs live in their pack | **yes** |
 | `models/` | the model-profile seam: `ModelRole`, `profiles`, `seam`, `tag_structured`, usage/tracing | **yes** |
 | `store/` | the single ArcadeDB store behind the seam: `arcadedb` (only the engine types and generic reads/writes; a pack's own store methods live in the pack, e.g. `ContractKGStore`, `ComplianceStore`), `seam` (`KgNode`/`KgEdge`/`NOT_NULL`), `chunk_text` | **yes** |
@@ -76,7 +76,9 @@ expensive stages are content-hash gated so re-ingest is cheap. Entity extraction
 attachments become child documents linked by `EmbeddedIn` / `AttachedTo`).
 
 A new domain does not build this pipeline: it calls `build_ingestion(extractor, ...)` (in `rag_wright.ingestion`,
-re-exported from `rag_wright.api`) with its hooks. The engine owns parse, chunk, segment, index, group and write;
+re-exported from `rag_wright.api`) with its hooks. The pipeline is a LangGraph graph (`IngestionPipeline.graph`: one
+run graph sending each source to a per-document graph of the stages), so a product's ingestion capability is a real
+`subgraph`, and a run given a checkpointer and a `run_id` resumes where it stopped. The engine owns parse, chunk, segment, index, group and write;
 the domain supplies the extractor and overrides only the hooks it needs. The default segmenter follows the docling
 layout and the default unit grouper is structural. The reference `contract_ingestion_pipeline` drives the same
 shared `IngestionStages` with legal hooks (a legal segmenter, a clause-function span tagger, a provision grouper

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/concepts.md

@@ -106,6 +106,12 @@ pipeline = build_ingestion(extractor, segmenter=None, span_tagger=None, unit_gro
 report = await pipeline.aingest(ws, sources, cache_dir="cache/")
 ```
 
+- **It is a LangGraph graph.** `pipeline.graph(ws, cache_dir=...)` is the compiled run: each source goes through the
+  per-document graph (parse, chunk, segment, index, extract, write, the document hook, the `Document` node, then its
+  embedded files through the same graph), at most `document_concurrency` documents at a time; a stage that fails
+  dead-letters its document, never the run. `aingest` runs it, and with `checkpointer=` and `run_id=` an interrupted
+  run resumes from each document's last finished stage.
+
 - **The engine owns the mechanism:** parse (PDF, Office, spreadsheets incl. hidden sheets), chunk, segment each chunk
   into spans that tile it, index the spans (dense + sparse), group spans into extraction **units**, run the
   extractor on each unit concurrently, write, and record one `Document` node per document. Embedded files and PDF

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/configuration.md

@@ -109,6 +109,11 @@ and how to manage workspaces.
   deployment serves a single model; OCR resolves its endpoint and flags through the same profile as every other
   call. Override one role with `RAG_MODEL_<ROLE>` (e.g. `RAG_MODEL_VISION_OCR`, `RAG_MODEL_GENERAL`), or every
   role at once with `RAG_MODEL_ALL`; the role-specific variable wins.
+- **Blank PDF pages** are never sent to `VISION_OCR` (0.13.0, PS-46): a page with no ink has nothing to read, and a
+  vision model asked to transcribe one invents a page. A parse cached by an earlier engine with `VISION_OCR`
+  configured may still hold such text: `find_blank_pages_with_text(cache_dir, sources)` lists every page that is
+  blank in the source PDF but has text in its cached parse (files embedded in a parsed package are found in the
+  cache without being passed). Delete each finding's `cache_files`, then re-ingest the document.
 - **Structured output** is client-side tag-parse (ADR-0045); any provider flags live in the profile.
 - **A self-hosted Qwen server**: see [A self-hosted model server](#a-self-hosted-model-server-qwen-on-modal) below.
 - **Decision models** (e.g. Jev) are reached through a `DecisionModelProfile` (default `jev-1.13`;

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/domain-adaptation/README.md

@@ -42,7 +42,7 @@ ADR-0117/0118 engine API + capability runtime). Read [Concepts](../concepts.md)
    (segmenter, span tagger, unit grouper, boundary decider, writer, a per-document hook)
    → [KG construction](kg-construction.md) and the `building-an-ingestion-capability` skill. Your query graphs, domain functions, and skills **compose the engine's
    generic primitives from the public tiers** (graph reads and query, embedding, typed ranking, reranking,
-   answers, parsing, chunking; hybrid search and fusion are not public yet, gap G24) and register only your OWN domain graphs/models/skills via `register_capability(manifest)` with an
+   answers, parsing, chunking, and hybrid span search with `span_search`) and register only your OWN domain graphs/models/skills via `register_capability(manifest)` with an
    `impl_ref`, invocable (and MCP-exposable) with zero engine edits. Package them as a pack module that exposes
    `register()` and load it with `load_pack("<your module>")`.
    → [Authoring capabilities](authoring-capabilities.md).

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/domain-adaptation/_engine-gaps.md

@@ -190,7 +190,7 @@ they are the real "does a new customer benefit?" items. The genuine engine ones
 - **Table rows:** `table_rows(source_document)` returns every parsed table's rows as exact cells (`TableRow`), and a
   one-row unit carries its row as `Unit.table_row` (ING-7).
 
-### G24: No public hybrid search or fusion primitive
+### G24: No public hybrid search or fusion primitive (closed)
 - **Where:** the engine's own retrieval legs run hybrid (dense + sparse) span search and rank fusion internally, and
   the authoring guide used to say a capability composes them "by direct import"; neither is on `rag_wright.api` or
   `rag_wright.pack_sdk`.
@@ -199,6 +199,10 @@ they are the real "does a new customer benefit?" items. The genuine engine ones
   what it embeds itself, beside a structured leg (`kg_read`, `typed_constraint_match_rank`).
 - **Proposed:** a public hybrid span search over a workspace (query text, filters, k) returning cited spans, with the
   fusion and reranking it already applies; on `rag_wright.pack_sdk` for pack capabilities.
+- **Closed by PS-45:** `span_search(ws, query, *, k, documents, tag, dense_floor)` and `aspan_search` on
+  `rag_wright.api` (which pack code may also import): the store-side RRF fusion of the dense and sparse span
+  legs plus the dense floor (ADR-0104), returning citation-ready `SpanHit`s. Reranking stays the caller's
+  (`BGEReranker`), as it was in the engine's own leg.
 - Surfaced: the TexWright specification (2026-10-14).
 
 ## Prerequisites a domain provides (not engine gaps)

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/domain-adaptation/authoring-capabilities.md

@@ -114,9 +114,10 @@ slug. Write good `representative_queries` (2–5, phrased like real tasks) — t
 Your capabilities **compose the engine's generic primitives from the public tiers** (`rag_wright.api` and
 `rag_wright.pack_sdk`: the knowledge-graph reads `kg_read` / `kg_edges`, graph query, embedding (`ws.embedder`,
 `cosine`), typed ranking (`typed_constraint_match_rank`), reranking (`BGEReranker`), answers (`agenerate_answer`,
-`ajudge_spans`), parsing and chunking); you register only your OWN domain graphs/models/skills. Don't wrap or
-re-register an engine primitive. Hybrid (dense + sparse) span search and rank fusion are not public yet (engine gap
-G24): check a primitive is on a tier before designing around it.
+`ajudge_spans`), hybrid span search (`span_search` / `aspan_search`: the dense and sparse legs fused in the store,
+with a dense floor, returning cited spans), parsing and chunking); you register only your OWN domain
+graphs/models/skills. Don't wrap or re-register an engine primitive, and check a primitive is on a tier before
+designing around it.
 
 ## Definition of done
 

{rag_wright-0.12.0 → rag_wright-0.14.0}/docs/installation.md

@@ -131,13 +131,20 @@ To serve open models yourself instead, set `RAG_SERVING=vllm` with `VLLM_BASE_UR
 
 `open_workspace` (through `ensure_schema`) refuses a database whose `Span` type still has the old field names
 (`contract_id`, `function`, `functions`; renamed to `document_id`, `primary_tag`, `tags`) and raises a `RuntimeError`
-naming the fix. Migrate each such database once, in place (it connects with the `ARCADEDB_*` settings in `.env`; it
-is idempotent and streams `X/N` progress):
+naming the fix. Migrate each such database once, in place, with `migrate_span_fields` from `rag_wright.api`. It is
+idempotent (it returns the number of spans moved, 0 when already migrated), never creates a database, and reports
+progress after each batch:
 
-```sh
-uv run python -u scripts/migrate_span_fields.py <database>
+```python
+from rag_wright.api import EngineConfig, StoreConfig, migrate_span_fields
+
+config = EngineConfig(store=StoreConfig.from_env())
+moved = migrate_span_fields(config, corpus="my_corpus",
+                            progress=lambda done, total: print(f"[migrate] {done}/{total}"))
 ```
 
+From an engine checkout, `uv run python -u scripts/migrate_span_fields.py <database>` does the same.
+
 Every other breaking change since 0.1.0, with the exact change a consumer makes, is in
 [`specs/ingestion-hooks/ing8-breaking-changes.md`](specs/ingestion-hooks/ing8-breaking-changes.md).
 

rag_wright-0.14.0/docs/specs/langgraph-ingestion/plan.md

@@ -0,0 +1,77 @@
+# LangGraph ingestion: plan and ledger (LGI)
+
+Status: COMPLETE 2026-10-17 (LGI-1 to LGI-5); approved 2026-10-17 (decisions: sequential index then extract; run graph + document subgraph; serialization measured in LGI-3). Runs before PS-48 (the harness tests onto the fabric fixture).
+
+## Why
+
+`build_ingestion` (ADR-0124) is the engine's generic ingestion path, and every product's ingestion capability is
+built on it (TexWright's `texwright_ingestion` and `texwright_screen_ingestion`). It is plain asyncio: `aingest`
+runs `IngestionStages` per document with `asyncio.gather` and a semaphore. No LangGraph graph exists on that path.
+Yet the `authoring-a-capability` skill defines the `subgraph` kind as "a compiled LangGraph `StateGraph`", and
+`building-an-ingestion-capability` tells a product to register its pipeline as a `subgraph`. So every product
+registers a "subgraph" that has no graph, and gets none of what the graph gives: durable resume of a long ingest
+from a checkpointer, per-node streaming, and the substrate for a later `interrupt()` review step. The graph
+version (ADR-0050's async ingestion) exists only in the reference pack (`contract_ingestion_pipeline`,
+`async_ingestion`), not on the generic path.
+
+## Goal
+
+`build_ingestion` builds a LangGraph graph, and `aingest` runs it. A product's ingestion capability is then a real
+`subgraph`: its `production_<slug>` returns `pipeline.graph(...)`, its `ainvoke` stays `pipeline.aingest(...)`.
+
+**Nothing breaks.** `build_ingestion`'s parameters, `aingest(ws, sources, *, cache_dir)`, `IngestionReport` /
+`DocumentReport`, the `[ingest] i/N` progress lines, dead-letter semantics and `IngestionStages` (used directly by
+RuleWright's and the reference pack's contract pipelines) are unchanged. Additions only, so a `feat:` (0.14.0).
+
+## Design
+
+```
+run graph  (IngestionPipeline.graph(ws, *, cache_dir, checkpointer=None))
+  START --Send per source--> document (the per-document subgraph) --> END        report = reducer over documents
+                             at most tuning.document_concurrency documents in flight (a semaphore in the node)
+
+document subgraph
+  parse -> chunk -> segment -> index -> extract -> write -> document_hook -> document_node -> children --> END
+     |any stage raises: the document's DocumentReport.dead_letter = "<Type>: <message>" --> END (never raised)
+  children: each embedded file / attachment through the same document subgraph (depth cap 2, as today),
+            then its EmbeddedIn / AttachedTo links
+```
+
+- **The nodes ARE `IngestionStages`.** One implementation of each stage, now with three drivers' worth of reuse:
+  the generic graph, the reference pack's contract graph, and any product driving the stages itself.
+- **Order and semantics match today's driver exactly**: stages sequential per document (index before extract),
+  documents concurrent up to `document_concurrency`, children after their parent, same dead-letter strings, same
+  progress lines. Parity is the acceptance gate, measured, not assumed.
+- **State stays small and serializable.** The parse is not held in state: the `parse` node fills the
+  content-hash parse cache and later nodes reload from it (they already do, through `IngestionStages.parsed`).
+  State holds the chunks, tagged spans, units/extractions and the report fields.
+- **Durable resume is opt-in.** `checkpointer=` (any LangGraph saver; the product supplies its own, e.g. Postgres,
+  as with the harness: ADR-0139, no Postgres extra in the engine) plus a `run_id` used as the thread id. Re-running
+  an interrupted ingest with the same `run_id` skips documents and stages already checkpointed. Without a
+  checkpointer, behaviour is today's.
+- **No retry policy added.** Today a stage failure dead-letters the document; that stays (a `RetryPolicy` would
+  change behaviour and cost). The graph makes it a one-line addition later if a product asks.
+
+## Open questions (decide before LGI-1)
+
+1. **Parallel index and extract after segment?** The reference pack fans them out; on the generic path they are
+   independent (embedding vs the extractor). A wall-clock gain on model-backed extractors, but a change of order
+   in store writes. **Recommendation: keep sequential here (parity), measure the gain in a later task.**
+2. **Run graph or per-document graph only?** The run graph (one `aingest` call over its sources; a "run", named by `run_id`; not a `corpus`, which is the database name) (Send fan-out) makes the whole ingest one
+   compiled graph, so the capability is one graph and a checkpointer covers the run. **Recommendation: both, as
+   designed (the per-document subgraph is a node of the run graph).**
+3. **Checkpoint serialization of the stage values** (pydantic chunks/spans/units, dataclass `KgNode`/`KgEdge`):
+   LangGraph's serializer must round-trip them. Measured in LGI-3; if a type does not round-trip, it is converted
+   at the node boundary, never by changing the public contracts.
+
+## Ledger
+
+| Id | Task | Acceptance (verify) | Status |
+|---|---|---|---|
+| LGI-1 | The per-document subgraph over `IngestionStages` (nodes above, dead-letter route, children through the same subgraph); `aingest` drives it per document, documents still fanned out as today. Parity fixture recorded FIRST from the current driver: `IngestionReport`s and store contents for the existing hermetic ingestion fixtures (text, PDF, spreadsheet with embedded children and links, a failing extractor, a failing document) | the recorded parity fixture equal after the change; the whole existing ingestion suite green unchanged; ADR-0124 amended (and ADR-0050's note that the generic path is not a graph) | done 2026-10-17 (`document_graph`; parity 11/11 scenarios; suite 2297 passed) |
+| LGI-2 | The run graph: `IngestionPipeline.graph(ws, *, cache_dir)` public, Send fan-out per source, at most `document_concurrency` documents in flight (a semaphore inside the `document` node, so a direct `graph()` caller gets it without passing a config), the report reduced from the documents; `aingest` = run the run graph | parity fixture equal; a concurrency test (peak documents in flight = `document_concurrency`); progress lines identical (the `[ingest] start N=` / `i/N` / `done` lines asserted); API docs regenerated | done 2026-10-17 (`graph()`; parity 11/11; source-order report; suite 2304 passed) |
+| LGI-3 | Durable resume: `checkpointer=` and `run_id=` on `graph()` and `aingest`; state round-trips through the saver | hermetic, `InMemorySaver`: an ingest interrupted mid-run (a node raises a non-dead-letter interruption on document 2) resumed with the same `run_id` re-runs no completed stage (extractor and embedder call counts) and yields the same report as an uninterrupted run; without a checkpointer behaviour is unchanged | done 2026-10-17 (`checkpointer=`/`run_id=`; built-in state, strict serde green; suite 2311 passed) |
+| LGI-4 | The capability shape and docs: `authoring-a-capability` (the `subgraph` kind: an ingestion capability's `production_<slug>` returns `pipeline.graph(...)`), `building-an-ingestion-capability` step 5 (resume with the product's checkpointer, the run id), `docs/architecture.md` / `concepts.md` ingestion sections; the product-starter templates if they show the ingest | doc-reference, shipped-skills and ingestion-skill-example guards green; the skill example runs the graph | done 2026-10-17 (both skills, concepts, architecture, the consumer skill and the starter template) |
+| LGI-5 | Live parity and handover: a live `build_ingestion` run on real parses (the PS-47 workbook with an embedded PDF, and a PDF set) before and after: same `IngestionReport`, same store counts per type; a live resume with a real checkpointer; RuleWright and TexWright notes (nothing to change; the new optional resume) | live tests green; the migration notes written | done 2026-10-17 (live old-vs-new identical: 10 documents, 394 spans, 55 records, links; live crash-and-resume green; RuleWright guide 0.14.0) |
+
+Each task is one approval gate; one commit per approved task.