rag-wright 0.11.0__tar.gz → 0.13.0__tar.gz

{rag_wright-0.11.0 → rag_wright-0.13.0}/.claude/skills/building-an-agent-harness/SKILL.md

@@ -161,9 +161,20 @@ them later and each one is a refactor with its own test fallout:
 | resuming a suspended run | the continuation renders ITSELF; the substrate asks |
 | the agent's chat model | from the engine's model profile, never a string in the substrate |
 
-**Collect them into ONE object the substrate is handed** -- we called it `AgentDefinition`, carrying the
-tool surface, the planning classification, the worker roster and the context type. Four declared facts, and
-**the substrate derives everything else**.
+**Collect them into ONE object the substrate is handed** -- `AgentDefinition`, with FIFTEEN required
+fields, and **the substrate derives everything else**. Four are the shape: the tool surface (`surface`), the
+planning classification (`planning`), the worker roster (`workers`) and the context type (`context_schema`).
+The other eleven are the customization surface, and an agent without them runs but is quietly less capable:
+`retry_on`, `message_for`, `model_id_for`, `prompts` (an `AgentPrompts`, eleven fields of its own: every word
+the model reads), `repeatable`, `question_argument`, `framings`, `carry_forward`, `rules`, `decision_points` and
+`read_framing`. The field-by-field reference, generated from the tier, is `docs/harness.md` in the engine
+repository.
+
+**Build every worker with `worker_spec(..., definition=...)`.** `worker_spec`'s policy parameters default to
+inert values, and all but the ledger are fields of the definition you already declared; a worker built
+without threading them ran with no retries, no repeat suppression and no decision recording while every test
+passed. With `definition=`, each parameter you leave at its default is taken from the definition, and a value
+you pass still wins.
 
 That last clause is the whole trick. The alternative -- let the product pass the derived sets too -- is a
 smaller diff and scores perfectly on every axis, and it exports an invariant as a convention the next

{rag_wright-0.11.0 → rag_wright-0.13.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

{rag_wright-0.11.0 → rag_wright-0.13.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.11.0/src/rag_wright/.agents → rag_wright-0.13.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

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

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

{rag_wright-0.11.0 → rag_wright-0.13.0}/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.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)
+
+
+### Features
+
+* **PS-43:** worker_spec(definition=), the harness design reference, and the harness source cleared of its originating product's vocabulary ([c19ff4d](https://github.com/fzaidi-dai/RAG_Wright/commit/c19ff4da006611383c6a7bca07ba633e345b44d8))
+
 ## [0.11.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.10.0...0.11.0) (2026-10-15)
 
 

{rag_wright-0.11.0 → rag_wright-0.13.0}/CLAUDE.md

@@ -55,7 +55,12 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 
 ## Start of every session
 
-> **CURRENT STATE (2026-10-14): PS-32 done: the agent harness is the engine's third public tier `rag_wright.harness`**
+> **CURRENT STATE (2026-10-15): `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 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`**
 > (ADR-0139 handover; with PS-39 `ws.embedder` / `api.query_embedder`; RuleWright's guide
 > `docs/specs/public-surface/rulewright-migration-0.10.0.md`; RELEASED as `rag-wright` 0.10.0 on 2026-10-14: PyPI + GitHub release `0.10.0`, PR #12). Before it,
 > **(2026-10-13): `rag-wright` 0.9.0 is RELEASED** (PS-36 `agent_chat_model`, PS-37 drop/temporary

{rag_wright-0.11.0 → rag_wright-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.11.0
+Version: 0.13.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
@@ -117,6 +117,8 @@ The whole doc set is under [`docs/`](docs/). Pick your path:
   product seam); a coding agent should drive it with the `using-the-rag-wright-engine` skill.
 - **Measuring a capability?** [Evals](docs/evals.md): gold sets from your experts' files, a scorer per capability
   kind, a runner with repeats, a report your backend can return, optional Langfuse runs.
+- **Building your product's agent?** [The agent harness](docs/harness.md): the third tier's design, every field a
+  product declares, and where it goes quiet rather than failing.
 - **Going deep?** [Architecture](docs/architecture.md), the generated [API reference](docs/api/), the
   [Reference pack](docs/reference-pack.md), and the [ADR index](docs/adr/README.md).
 - **Releases?** See the [CHANGELOG](CHANGELOG.md) and [how releases work](docs/releasing.md) (batched via

{rag_wright-0.11.0 → rag_wright-0.13.0}/README.md

@@ -59,6 +59,8 @@ The whole doc set is under [`docs/`](docs/). Pick your path:
   product seam); a coding agent should drive it with the `using-the-rag-wright-engine` skill.
 - **Measuring a capability?** [Evals](docs/evals.md): gold sets from your experts' files, a scorer per capability
   kind, a runner with repeats, a report your backend can return, optional Langfuse runs.
+- **Building your product's agent?** [The agent harness](docs/harness.md): the third tier's design, every field a
+  product declares, and where it goes quiet rather than failing.
 - **Going deep?** [Architecture](docs/architecture.md), the generated [API reference](docs/api/), the
   [Reference pack](docs/reference-pack.md), and the [ADR index](docs/adr/README.md).
 - **Releases?** See the [CHANGELOG](CHANGELOG.md) and [how releases work](docs/releasing.md) (batched via

{rag_wright-0.11.0 → rag_wright-0.13.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.11.0 → rag_wright-0.13.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.11.0 → rag_wright-0.13.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).
@@ -296,7 +312,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 +320,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 +406,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 +418,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 +436,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 +476,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.11.0 → rag_wright-0.13.0}/docs/api/harness.md

@@ -1,6 +1,6 @@
 # Agent harness reference — `rag_wright.harness`
 
-> **Generated** from the live `rag_wright.harness.__all__` by `scripts/build_api_docs.py` — do not edit by hand. The agent harness tier (ADR-0139): what a product builds its agent on. It reaches the rest of the engine only through `rag_wright.api`. See the package docstring.
+> **Generated** from the live `rag_wright.harness.__all__` by `scripts/build_api_docs.py` — do not edit by hand. The agent harness tier (ADR-0139): what a product builds its agent on. It reaches the rest of the engine only through `rag_wright.api`. The design reference, with what a product declares and why, is `docs/harness.md`.
 
 ## Types
 
@@ -20,11 +20,11 @@ Every word a product says to its model: the tier prompts, the memory line and th
 
 One user-initiated agent turn, and the scope it ran under.
 
-`run_id` is the run's identity: `run-contract.md` obligation 1 requires a run to outlive the view that started it, so it is returned rather than held in memory, and it is what `resume_run` addresses.
+`run_id` is the run's identity: a run must outlive the view that started it, so it is returned rather than held in memory, and it is what `resume_run` addresses.
 
 ### `RunOutcome(*values)`
 
-What became of a run, named in CODE because none of it is a judgement (T-5a.15).
+What became of a run, named in CODE because none of it is a judgement.
 
 **Every transition here is decidable from the state alone**, which is why it is not in a prompt: the project's own rule is that a warning in a prompt is not a constraint, and `read_the_question` was instructed in four places and obeyed zero times.
 
@@ -40,7 +40,7 @@ A memory operation reached the store with no run context.
 
 ### `WorkerReport(*, status: str, need: str = '') -> None`
 
-What every worker carries, whatever else it returns (`AR-16`).
+What every worker carries, whatever else it returns.
 
 **Structured, because the orchestrator chains it.** `status` lets a program branch; `need` is how a worker says it cannot finish without a person, since it has no way to ask.
 
@@ -54,7 +54,7 @@ One thing worth telling the client about.
 
 A model call passed a wall-clock ceiling. **Never raised directly** -- one of the two below is.
 
-There are two ceilings with OPPOSITE retry semantics, and they had one exception type between them until T-5a.12q. That cost a live run `compliance_worker` SEVEN identical dispatches: the whole-turn breach escaped the worker, arrived at the parent as a failed `task` tool call, and `ToolRetryMiddleware(retry_on=TRANSIENT)` re-ran the worker's entire job. Catch this base when you mean "some deadline fired"; never put it in a retry set.
+There are two ceilings with OPPOSITE retry semantics, and they had one exception type between them at first. That cost one worker in a live run SEVEN identical dispatches: the whole-turn breach escaped the worker, arrived at the parent as a failed `task` tool call, and `ToolRetryMiddleware(retry_on=TRANSIENT)` re-ran the worker's entire job. Catch this base when you mean "some deadline fired"; never put it in a retry set.
 
 ### `ModelAttemptTooSlow`
 
@@ -94,7 +94,7 @@ What a product offers an agent run, and the two things the substrate asks about
 
 The only thing the substrate needs to know about a run's tenancy.
 
-A product's own context type satisfies this by having the two members; it keeps whatever else it wants (`AgentContext` keeps typed ids, a user id and `for_tenant`).
+A product's own context type satisfies this by having the two members; it keeps whatever else it wants (typed ids, a user id, its own construction rule).
 
 ## Type aliases
 
@@ -138,13 +138,13 @@ Begin a run under `context`, and supply it to every invocation.
 
 The caller passes who is asking, what they asked, and the scope it runs under. **That scope is the PRODUCT's to derive** (engine ADR-0139): the substrate must not know what authenticated this run, so it takes the resolved scope rather than three identity rows it would have to re-read.
 
-**The obligation `AR-6` placed here therefore moves to the caller, and is not weaker for it**: the context must come from the authenticated session of THIS request, never from one remembered across requests. On the route that is structural -- `tenant: TenantDep` is a per-request dependency and the product's own `for_tenant` rule runs in the handler body -- which is why the door is still impossible to forget rather than merely documented.
+**The obligation to bind the context per invocation therefore moves to the caller, and is not weaker for it**: the context must come from the authenticated session of THIS request, never from one remembered across requests. On a route that is structural -- the tenant is a per-request dependency and the product's own construction rule runs in the handler body -- which is why the door is still impossible to forget rather than merely documented.
 
-A `run_id` is minted when the caller has none, so a run is addressable from the moment it exists rather than from whenever somebody remembers to name it (`run-contract.md` obligation 1).
+A `run_id` is minted when the caller has none, so a run is addressable from the moment it exists rather than from whenever somebody remembers to name it.
 
-**Tracing and accounting attach HERE, for the same reason the context does** (T-5a.4b): this is the only door, so it is the only place that cannot be forgotten. `settings=None` leaves both off and `accounting=None` is a no-op — the precedent `recording_usage` set, because accounting must never be the reason a user's work does not happen.
+**Tracing and accounting attach HERE, for the same reason the context does**: this is the only door, so it is the only place that cannot be forgotten. `settings=None` leaves both off and `accounting=None` is a no-op — the precedent `recording_usage` set, because accounting must never be the reason a user's work does not happen.
 
-**`continuation` must already be RESOLVED** (`AR-12`, T-5a.10). It is typed `Any` only because the harness must not import its own models into this module's signature dance; `render_continuation` refuses anything but a `ResolvedContinuation` by name, so a caller that skipped the workspace check gets `UnresolvedContinuation` here rather than a prompt full of the browser's claims.
+**`continuation` must already be RESOLVED.** It is typed `Any` only because the harness must not import its own models into this module's signature dance; `render_continuation` refuses anything but a `ResolvedContinuation` by name, so a caller that skipped the workspace check gets `UnresolvedContinuation` here rather than a prompt full of the browser's claims.
 
 ### `resume_run(agent: 'Any', context: 'RunScope', *, answer: 'Any', run_id: 'str', settings: 'Any' = None, accounting: 'Any' = None) -> 'RunResult'`
 
@@ -160,17 +160,17 @@ Begin a run and yield `(run_id, namespace, mode, chunk)` as it happens.
 
 **The streaming sibling of `start_run`, and it carries the same guarantees** — the context, the trace and both ledgers — because they attach here rather than at the call site. A surface that streamed through `agent.astream` directly would lose all three and look like it worked.
 
-`subgraphs=True` is what makes a subagent's output distinguishable from the main agent's; without it every event arrives flat and `AR-18`'s cards have nothing to index on. Two stream modes are requested, so langgraph yields **3-tuples** rather than 2 — verified, not assumed.
+`subgraphs=True` is what makes a subagent's output distinguishable from the main agent's; without it every event arrives flat and a client's per-subagent cards have nothing to index on. Two stream modes are requested, so langgraph yields **3-tuples** rather than 2 — verified, not assumed.
 
-**`continuation` is built the same way `start_run` builds it**, through `_opening_turn`. Two doors would mean two chances to forget the view, and the streaming one is the door the product actually uses — so a continuation that only worked on `start_run` would be a feature with no users (`AR-12`).
+**`continuation` is built the same way `start_run` builds it**, through `_opening_turn`. Two doors would mean two chances to forget the view, and the streaming one is the door the product actually uses — so a continuation that only worked on `start_run` would be a feature with no users.
 
 ### `read_run(agent: 'Any', context: 'RunScope', *, run_id: 'str') -> 'RunResult | None'`
 
-Where a run got to, by its id alone — or `None` if it is not this matter's (T-5a.4c-iii).
+Where a run got to, by its id alone — or `None` if it is not this scope's.
 
-**`run-contract.md` obligation 1, cashed:** *"the run is addressable, and its region renders from an id alone, never from in-memory state that a reload destroys."* A reload, a second tab, or a deploy all arrive here.
+**The run is addressable, cashed:** *"the run is addressable, and its region renders from an id alone, never from in-memory state that a reload destroys."* A reload, a second tab, or a deploy all arrive here.
 
-**`None` covers three cases deliberately** — no such run, another matter's run, and a run id that was never started. Not by comparing afterwards: the thread id is derived from the workspace, so another matter's run does not resolve to a thread at all. The checkpointer itself has no tenancy and cannot be given any, so the isolation has to be in the key.
+**`None` covers three cases deliberately** — no such run, another scope's run, and a run id that was never started. Not by comparing afterwards: the thread id is derived from the scope, so another scope's run does not resolve to a thread at all. The checkpointer itself has no tenancy and cannot be given any, so the isolation has to be in the key.
 
 **State, not replay.** This returns where the run got to; it does not re-emit the events that got it there. A reloading client renders the state and reconnects for what follows, which is enough for obligation 1 and is measurably cheaper than storing and replaying a transcript. If the surface turns out to need replay, the checkpointer keeps the history and `alist` is where that would come from — decided then, with a real surface to measure against, rather than guessed now.
 
@@ -186,37 +186,37 @@ What a run's stored state says became of it.
 
 ### `thread_for(context: 'RunScope', run_id: 'str') -> 'str'`
 
-The checkpointer thread a run lives in, **scoped to its matter**.
+The checkpointer thread a run lives in, **keyed by its scope**.
 
-**The checkpointer has no tenancy and cannot be given any.** `aget_tuple` keys on `thread_id` and `checkpoint_ns` alone — verified in the installed saver — so a bare run id is readable by anybody who can name it. That is exactly the hole T-2.4d closed on the jobs route, where a UUID in a URL was the whole access control and anybody holding a job id read its result across customers.
+**The checkpointer has no tenancy and cannot be given any.** `aget_tuple` keys on `thread_id` and `checkpoint_ns` alone — verified in the installed saver — so a bare run id is readable by anybody who can name it. That is exactly the hole a jobs route can have, where a UUID in a URL is the whole access control and anybody holding a job id reads its result across customers.
 
-So the workspace is part of the key rather than a comparison somebody must remember afterwards. Another matter's run id does not resolve to a thread at all, which makes "not yours" and "no such run" the same non-answer **by construction** — the non-oracle property this codebase applies to documents, jobs, workspaces, sessions and checks, arrived at structurally for once instead of by a check.
+So the scope is part of the key rather than a comparison somebody must remember afterwards. Another scope's run id does not resolve to a thread at all, which makes "not yours" and "no such run" the same non-answer **by construction** — the non-oracle property this codebase applies to documents, jobs, workspaces, sessions and checks, arrived at structurally for once instead of by a check.
 
 The run id stays the PUBLIC identity: it is what `usage_run.correlation_id` joins on and what a client keeps to reconnect. The thread id is ours and never leaves the process.
 
 ### `build_chat_agent(context: 'RunScope', resources: 'Any', settings: 'Any', *, model: 'Any' = None, definition: 'Any', checkpointer: 'Any' = None, store: 'Any' = None, ledger: 'Any' = None) -> 'Any'`
 
-The chat-manager for one run, holding the manifest bound to that run's matter.
+The chat-manager for one run, holding the manifest bound to that run's scope.
 
-**The model is resolved through DeepAgents**, not built here: `AGENT_MODEL_SPEC` plus a registered `ProviderProfile` is the only combination that applies our OpenRouter configuration (T-5a.4a-ii found that `init_chat_model` silently ignores the profile).
+**The model is resolved through DeepAgents**, not built here: `AGENT_MODEL_SPEC` plus a registered `ProviderProfile` is the only combination that applies the OpenRouter configuration (`init_chat_model` silently ignores the profile).
 
 **A `context_schema` is required, not conventional.** It comes from `definition.context_schema` -- the product's own context type, which the substrate never names -- and `start_run` refuses an agent without one, because an agent compiled with `context_schema=None` accepts `context=` and drops it silently.
 
-**The checkpointer defaults to in-memory, which is a real limitation.** `run-contract.md` obligation 1 says a run outlives the view that started it, and an in-memory saver does not outlive the process. A durable checkpointer is T-5a.4c's business, where re-attaching to a run by id is the requirement that forces it; passing one here is how that lands.
+**The checkpointer defaults to in-memory, which is a real limitation.** A run outlives the view that started it, and an in-memory saver does not outlive the process. A durable checkpointer is the caller's to pass, and re-attaching to a run by id is the requirement that forces it.
 
 ### `build_orchestrator(context: 'Any', resources: 'Any', settings: 'Any', *, model: 'Any' = None, tools: 'Any' = None, system_prompt: 'str | None' = None, extra_middleware: 'list | None' = None, definition: 'Any', checkpointer: 'Any' = None, store: 'Any' = None, ledger: 'Any' = None) -> 'Any'`
 
 The planning tier, compiled as an agent in its own right.
 
-**`context_schema` is declared rather than inherited.** A compiled child does receive the parent's context without declaring it — pinned in `test_harness_grounding.py` — but declaring it is what lets this be driven DIRECTLY, which T-5a.12 does and which `start_run` refuses without the schema.
+**`context_schema` is declared rather than inherited.** A compiled child does receive the parent's context without declaring it — pinned in `test_harness_grounding.py` — but declaring it is what lets this be driven DIRECTLY, which the orchestration eval does and which `start_run` refuses without the schema.
 
-`model`, `tools`, `system_prompt` and `extra_middleware` are overridable for tests and evals; **production passes none of them.** `system_prompt` and `extra_middleware` exist so T-5a.12b can run the two orchestration arms through the REAL builder rather than assembling its own agent -- an eval that builds its own would be measuring something the product does not ship.
+`model`, `tools`, `system_prompt` and `extra_middleware` are overridable for tests and evals; **production passes none of them.** `system_prompt` and `extra_middleware` exist so an eval can run the two orchestration arms through the REAL builder rather than assembling its own agent -- an eval that builds its own would be measuring something the product does not ship.
 
 ### `agent_chat_model(settings: 'Any', model_id: 'str') -> 'Any'`
 
 The agent's chat model, built by the engine and bounded by our clocks.
 
-**`model_id` is a PARAMETER (T-7.58).** It used to be read from one product's setting name, in the substrate, so a second product's model could not be reached at all. Which profile to reason with is the product's declaration; bounding the call with our clocks is the substrate's job and is all that is left here.
+**`model_id` is a PARAMETER.** It used to be read from one product's setting name, in the substrate, so a second product's model could not be reached at all. Which profile to reason with is the product's declaration; bounding the call with our clocks is the substrate's job and is all that is left here.
 
 **No `ProviderProfile`, and that removed a trap rather than just a dependency.** The old path handed DeepAgents a spec STRING and registered a profile to configure it. `deepagents._models.resolve_model` returns a pre-built `BaseChatModel` *unchanged* and applies its profile registry only to strings -- including, in its own words, "the OpenAI Responses API default". That default was ON, and with it on OpenRouter returns `object: "response"` and reports **no cost at all**, which is why this module carried `use_responses_api=False`. Passing an object retires the counter-measure with its cause.
 
@@ -226,7 +226,7 @@ The agent's chat model, built by the engine and bounded by our clocks.
 
 Time and trace one agent run, and hand it to `accounting` when it ends.
 
-`accounting` is anything with `collecting()`, `record(run_id=, since=, duration_ms=)` and `trace_metadata` -- the product supplies it (`operations.usage.AgentRunAccounting`). `None` disables recording without disabling the run.
+`accounting` is anything with `collecting()`, `record(run_id=, since=, duration_ms=)` and `trace_metadata` -- the product supplies it. `None` disables recording without disabling the run.
 
 **`collecting()` is opened OUTSIDE the trace and the timer is started before both**, which preserves the original order: the engine work a tool causes is collected through the caller's ContextVar for the whole run, including the setup the trace does not cover.
 
@@ -246,19 +246,19 @@ The run's thread id: its scope and its run id, composed.
 
 **Not the run id alone.** The run id is the PUBLIC identity a client keeps; the thread is ours and never leaves the process, and keying it by scope is what makes a guessed run id from another tenant resolve to nothing by construction.
 
-### `worker_spec(name: 'str', description: 'str', prompt: 'str', tools: 'list', report: 'type', ledger: 'Any' = None, *, retry_on: 'tuple[type[BaseException], ...]' = (), message_for: 'Any' = None, signposts: 'Any' = None, repeatable: 'frozenset[str]' = frozenset(), question_argument: 'dict[str, str] | None' = None, framings: 'tuple[str, ...]' = (), carry_forward: 'Any' = None, read_framing: 'Any' = None) -> 'dict[str, Any]'`
+### `worker_spec(name: 'str', description: 'str', prompt: 'str', tools: 'list', report: 'type', ledger: 'Any' = None, *, retry_on: 'tuple[type[BaseException], ...]' = (), message_for: 'Any' = None, signposts: 'Any' = None, repeatable: 'frozenset[str]' = frozenset(), question_argument: 'dict[str, str] | None' = None, framings: 'tuple[str, ...]' = (), carry_forward: 'Any' = None, read_framing: 'Any' = None, definition: 'Any' = None) -> 'dict[str, Any]'`
 
 A `SubAgent` spec, deliberately the opposite choice from the orchestrator's `CompiledSubAgent`.
 
 A worker has no middleware and no subagents of its own, so letting the parent build it keeps one model resolution and one place that knows how a tier is compiled.
 
-**No `ask_the_user` in any worker's tools**, and that absence is the mechanism (`AR-16`): a prompt saying "do not ask" is a suggestion; a tool the worker was never given is a fact.
+**Pass `definition=`, the product's `AgentDefinition`.** Every policy parameter after `ledger` defaults to something inert, and all of them but `signposts` are fields of that definition (`signposts` is its `prompts`). With a definition, each parameter left at its inert default is taken from it; a value passed explicitly still wins. Without one, a worker runs with no retries, no repeat suppression and no decision recording, and nothing fails to say so.
 
 ### `clarification_tool() -> 'BaseTool'`
 
 A tool whose entire body is a question.
 
-Returned from a factory for symmetry with the manifest's bindings, though it closes over nothing: a clarification has no tenancy to bind, because it touches no matter's data.
+Returned from a factory for symmetry with the manifest's bindings, though it closes over nothing: a clarification has no tenancy to bind, because it touches no scoped data.
 
 ### `translate(namespace: 'Any', mode: 'str', chunk: 'Any') -> 'list[RunEvent]'`
 
@@ -268,7 +268,7 @@ Turn one streamed item into zero or more events for the client.
 
 ### `what_was_finished(result: 'Any') -> 'list[RunEvent]'`
 
-What to tell the client about a run that did not finish (T-5a.15b).
+What to tell the client about a run that did not finish.
 
 **The route already stated the principle and did not honour it for failures:** *"a stream that stops is not a stream that finished. Without a terminal event a client cannot tell a completed answer from a dropped connection."* On a cut-off run the stream simply stopped -- no partial, no explanation, not even the terminating frame -- so it looked exactly like a dropped connection.
 
@@ -284,17 +284,17 @@ The stack, inner-first.
 
 `ToolRetryMiddleware` carries `on_failure="error"` so a failure that exhausts its retries becomes an exception the error middleware can see — rather than a message the model receives without anybody having retried.
 
-**Both arguments are the PRODUCT's and are required (T-7.58).** This imported one product's retry set and `message_for` directly, so the substrate held that product's judgement about what is recoverable -- and a greenfield product retrying a mill feed got the first product's client exception types and its domain errors. **No defaults**, deliberately: a default retry set is one a second product inherits without noticing, and `retry_on` defaulting to anything is how `Exception` creeps back in and a scope violation gets re-attempted with backoff.
+**Both arguments are the PRODUCT's and are required.** This imported one product's retry set and `message_for` directly, so the substrate held that product's judgement about what is recoverable -- and a greenfield product retrying a mill feed got the first product's client exception types and its domain errors. **No defaults**, deliberately: a default retry set is one a second product inherits without noticing, and `retry_on` defaulting to anything is how `Exception` creeps back in and a scope violation gets re-attempted with backoff.
 
 The deadline exceptions are the HARNESS's own (above in this module), because `ADeadlineForOneModelTurn` is what raises them. A product chooses whether its own `retry_on` includes `ModelAttemptTooSlow`; ours does, and deliberately omits `ModelTurnTooSlow`.
 
 ### `dispatched_more_than_once(recording: 'dict[str, Any]') -> 'str | None'`
 
-A worker covering the whole matter, run once per document.
+A worker covering the whole scope, run once per document.
 
 ### `reached_for_the_filesystem(recording: 'dict[str, Any]') -> 'str | None'`
 
-Tried to open the matter's documents as files.
+Tried to open the subject documents as files.
 
 ### `wrote_a_program_for_a_single_call(recording: 'dict[str, Any]') -> 'str | None'`
 

{rag_wright-0.11.0 → rag_wright-0.13.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`;
@@ -151,7 +156,8 @@ chat-manager tier, an orchestrator and dispatched workers on Deep Agents, with t
 retries, interrupts and resume, memory, metering and run grading. The product declares an `AgentDefinition` (its
 `ToolSurface`, planning split, workers, a context type satisfying `RunScope`, retry set, model id and `AgentPrompts`)
 and runs it with `start_run` / `resume_run` / `stream_run`; it passes its own checkpointer and memory store. The
-reference is `docs/api/harness.md`, and the `building-an-agent-harness` skill is the practice behind it.
+design reference, with every field a product declares, is [`harness.md`](harness.md); the generated
+signatures are `docs/api/harness.md`, and the `building-an-agent-harness` skill is the practice behind it.
 
 Its configuration is the engine's: the model by engine profile id (the definition's `model_id_for`), tracing by
 `RAG_TRACE_LEVEL` and the Langfuse keys (each agent turn is one generation, labelled `agent-llm`, grouped under the

{rag_wright-0.11.0 → rag_wright-0.13.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.11.0 → rag_wright-0.13.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.11.0 → rag_wright-0.13.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