rag-wright 0.14.1__tar.gz → 0.16.0__tar.gz

{rag_wright-0.14.1/src/rag_wright/.agents → rag_wright-0.16.0/.claude}/skills/building-a-product-frontend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-a-product-frontend
-description: The architecture and build ORDER for a product front end over a retrieval/agent engine - the core/product seam, generating the API client from the schema, the URL as state of record, one data-access layer, and the three test tiers in the order you need them. Load at the START of a new product's UI, and before changing the shape of an existing one. Craft (composition, a11y, states) is frontend-ui-engineering, which still applies.
+description: The architecture and build ORDER for a product front end over a retrieval/agent engine - the core/product seam, the shell's regions (rail, main, detail, a reserved run row), generating the API client from the schema, the URL as state of record, one data-access layer, and the three test tiers in the order you need them. Load at the START of a new product's UI, and before changing the shape of an existing one. Craft (composition, a11y, states) is frontend-ui-engineering, which still applies.
 ---
 
 # Building a product front end over an engine
@@ -47,8 +47,12 @@ src/product/   the domain. Entity names, the operation surfaces, the copy, the r
 ```
 
 **The core reads registries the product populates.** Navigation is the first one: the product declares its
-surfaces (path, label, icon, which ones appear in nav) and the shell renders whatever it is given. The core
-never imports from the product; the product imports from the core.
+surfaces, and ONE entry carries both the route and the navigation, so routes and menu cannot drift into two
+lists: `path`, the `element`, and an optional `nav` of `label` and `end`. **`end` is the field that governs
+correct highlighting**: without it a parent path (`/intake`) also matches its child (`/intake/saved`) and the
+parent stays lit while the child is open. A surface with no `nav` is routed but not advertised (reached from
+an account badge, or a link handed out after a job). The shell renders whatever it is given. The core never
+imports from the product; the product imports from the core.
 
 **Enforce it with a scan, not with intent.** A test that greps the core directory for the domain's own words
 -- comments and docstrings included -- and fails on any hit. Two properties make it work:
@@ -83,7 +87,57 @@ decisions from. Or it can express it, and the configuration is now a programming
 checker, no tests and no reviewer. **Generalise the shell, the plumbing and the primitives; write the result
 surfaces.** They are the cheapest part and the part that carries the meaning.
 
-## Decision 2: GENERATE the API client from the schema
+## Decision 2: the shell has regions, and they follow from the shape
+
+The six things above are functional, but three of them fix the frame's geometry. Draw it before the first
+surface:
+
+```
+  rail  |  main    detail
+  rail  |  run     run
+```
+
+- **`main | detail`** is item 3: a per-item view with the source rendered and its extracted records **beside**
+  it. The detail panel is a region of the SHELL, not a page's private layout, so every surface that selects
+  something shows it in the same place.
+- **The rail, not a top bar**, is item 2: workspace switching, the library and the account are persistent
+  chrome that **grows with the corpus**, and **a horizontal bar cannot grow.** Full height, beside the content.
+- **The run docked BELOW, spanning `main` and `detail`**, is item 5: the agent picks up from a deterministic
+  result, so a run must hold a conversation **while the surface it is about stays visible**, and must be able to
+  put results into `main` and `detail`, not only into its own transcript. A run that is a mode of `main` fails
+  both. A run in its own column fails on width: tool calls need room, and **rail + main + detail + run as four
+  columns does not fit at 1440px.** Below, it is a sibling of both.
+- **Reserve the run row from the first commit, though nothing renders there.** One grid line; it buys that no
+  surface is written assuming nothing can ever dock below it. The regions themselves are a per-product decision
+  to record in your child skill; the argument for them is not.
+
+**Mark the current surface, by more than colour, and guard it.** The current navigation item carries
+`aria-current="page"` (a router's `NavLink` sets it; a plain `Link` never does), and its visual echo is not a
+colour swap alone (a border, a weight), because colour alone is the half of a contrast requirement a palette
+cannot satisfy. The guard is a jsdom test: *the current surface has `aria-current="page"`, and a parent with
+`end` does not while its child is open.*
+
+**Start from the scaffold; a scan cannot produce a layout.** Every other rule here is checkable by a source
+scan; the frame is the one decision a scan cannot make, so it is the one that defaults to the framework's
+`<header><nav>` above `<main>`. This skill ships the frame as three files in its own folder, `scaffold/` beside
+this file, to copy into your core directory (React, `react-router`, Tailwind with shadcn token names; the tokens
+are yours, the structure is the point):
+
+- `scaffold/surfaces.tsx`: the registry type (`path`, `element`, `nav: { label, end }`) and `navigable`
+- `scaffold/ShellLayout.tsx`: the frame -- skip link, the rail (`complementary`, named) holding a named `nav`,
+  `main` as its own scroll container, `detail` rendered only when something fills it (an empty landmark sends a
+  screen-reader user nowhere), the run row reserved
+- `scaffold/ShellLayout.test.tsx`: the jsdom guards -- the current surface, `end`, the rail, one `main`, no
+  empty detail
+
+Two things only the browser tier can assert, so assert them there: **the detail panel is BESIDE `main`, not
+under it** (the grid declares a third column only when `detail` exists; with two columns declared, the panel
+auto-places into the run row, full width under `main`, and jsdom computes no grid to notice), and **`main` is
+wider than the panel beside it** (the panel's width is capped; uncapped, it measured 608px against `main`'s 576px
+at 1440px). Copy, then customise. **Do not make the shell configurable**: Decision 1's argument against
+config-driven surfaces applies unchanged one level up.
+
+## Decision 3: GENERATE the API client from the schema
 
 If the backend publishes a machine-readable schema -- and a modern Python or TypeScript backend does, for
 free -- **the client is generated, never hand-mirrored.**
@@ -103,7 +157,7 @@ The discipline that makes generation work in practice:
 - **Change the client type in the SAME commit as the backend type.** A field that became optional while the
   client still types it as required is a dereference that survives a full green suite and a clean build.
 
-## Decision 3: the URL is the state of record
+## Decision 4: the URL is the state of record
 
 Page, filters, sort, selection, which panel is open, which tab is active -- all of it in the URL, none of it
 in component state.
@@ -117,7 +171,7 @@ cannot hand back.
 guard; what fails is the deferral with a named trigger that nobody checks. If you defer, write the trigger
 down where the next person will look, not only in the ticket.
 
-## Decision 4: one data-access layer, two guards
+## Decision 5: one data-access layer, two guards
 
 A query-key factory is the only place keys are built; no component calls `fetch` directly. Both guards are a
 source scan, both take minutes, and both are provable by planting their violation:
@@ -128,7 +182,7 @@ source scan, both take minutes, and both are provable by planting their violatio
 A library's own `refetch()` goes *through* the layer and is the opposite of a violation -- make sure the
 guard knows the difference, or it will be disabled by the first person it annoys.
 
-## Decision 5: one table primitive, and the allow-list that must not grow
+## Decision 6: one table primitive, and the allow-list that must not grow
 
 Build the table once, and allow a raw `<table>` element in exactly that one file. Everything else that needs
 a table uses the primitive; if the primitive cannot do it, extend the primitive.
@@ -224,10 +278,12 @@ Doing these out of order is what costs the rework:
    component exists.
 2. **Generate the client.** Before any surface. Everything downstream types against it.
 3. **The data-access layer and its two guards.** Cheap now, an audit later.
-4. **Identity and tenancy surfaces.** They are the most portable code you will write and they exercise the
+4. **The shell: the regions (Decision 2, from the scaffold), the navigation registry, theme tokens.** Before
+   any surface hangs on it, or the surfaces invent minimal chrome and the shell step reads as already done.
+   Resist centring the content region, since a detail panel sits beside it -- make each surface constrain its
+   own measure, and assert it.
+5. **Identity and tenancy surfaces.** They are the most portable code you will write and they exercise the
    shell, routing and the session end to end.
-5. **The shell: regions, navigation registry, theme tokens.** Resist centring the content region if a detail
-   panel will ever sit beside it -- then make each surface constrain its own measure, and assert it.
 6. **The table primitive**, with its allow-list guard, before the second listing.
 7. **The browser-tier harness** -- own database, real provisioning, build, serve, rebuild per run.
 8. **The first corpus surface** (upload, progress, library, detail). This is where ingestion contracts get
@@ -245,6 +301,7 @@ reader cannot derive:
 - your locked decisions, with what a violation looks like, and the fact that changing one needs a recorded
   decision rather than a judgement call
 - your primitives, by path: the table, the shell, the query-key factory, the states helper
+- which regions your shell has and what fills `detail` and the run row, as a locked decision
 - the commands: how to run each tier, where specs live, what the e2e server script does
 - the defects that have actually recurred in **your** codebase, with the evidence that makes them stick
 - current debts: a guard that was deferred, a decision made but not yet built
@@ -258,6 +315,9 @@ an architecture document is a decision that gets violated with the document alre
 - [ ] Nothing in the core imports from the product
 - [ ] The API client is generated from the published schema, committed, and regenerated in CI
 - [ ] Any client type mirroring a backend contract changed in the SAME commit as the backend
+- [ ] The regions (rail, main, detail, the reserved run row) are the SHELL's, not a page's own layout
+- [ ] The current surface carries `aria-current="page"` and is marked by more than colour; a parent with `end`
+      is not lit while its child is open
 - [ ] Navigation-shaped state is in the URL, not component state
 - [ ] Reads go through the query-key factory; no `fetch(` in a component
 - [ ] No raw table outside the primitive; the allow-list did not grow

rag_wright-0.16.0/.claude/skills/building-a-product-frontend/scaffold/ShellLayout.test.tsx

@@ -0,0 +1,82 @@
+/**
+ * The shell's decisions, each with its guard (jsdom tier). What jsdom cannot see -- that the detail panel sits
+ * BESIDE `main` rather than under it, and the 44px hit areas -- is asserted in the browser tier.
+ */
+import { cleanup, render, screen } from '@testing-library/react'
+import { MemoryRouter, Route, Routes } from 'react-router'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import ShellLayout from './ShellLayout'
+import type { Surface } from './surfaces'
+
+// Explicit, so the file does not depend on the runner's `globals` setting for testing-library's auto-cleanup.
+afterEach(cleanup)
+
+const SURFACES: Surface[] = [
+  { path: '/alpha', element: <div>alpha surface</div>, nav: { label: 'Alpha', end: true } },
+  { path: '/alpha/saved', element: <div>saved surface</div>, nav: { label: 'Saved' } },
+  { path: '/beta', element: <div>beta surface</div>, nav: { label: 'Beta' } },
+  // No `nav`: routed, but reached from somewhere other than the navigation.
+  { path: '/hidden', element: <div>hidden surface</div> },
+]
+
+function renderShell(path: string, detail?: React.ReactNode) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <Routes>
+        <Route element={<ShellLayout surfaces={SURFACES} productName="Testproduct" detail={detail} />}>
+          {SURFACES.map((surface) => (
+            <Route key={surface.path} path={surface.path} element={surface.element} />
+          ))}
+        </Route>
+      </Routes>
+    </MemoryRouter>,
+  )
+}
+
+const current = (name: string) => screen.getByRole('link', { name }).getAttribute('aria-current')
+
+describe('navigation', () => {
+  it('renders a link for every surface that declares navigation, and none for one that does not', () => {
+    renderShell('/hidden')
+    const nav = screen.getByRole('navigation', { name: 'Surfaces' })
+    expect(nav.textContent).toContain('Alpha')
+    expect(nav.textContent).not.toContain('hidden')
+    expect(screen.getByText('hidden surface')).toBeTruthy()
+  })
+
+  it('marks the current surface with aria-current, not with colour alone', () => {
+    renderShell('/beta')
+    expect(current('Beta')).toBe('page')
+    expect(current('Alpha')).toBeNull()
+  })
+
+  it('does not leave a parent lit while its child is open (`end`)', () => {
+    renderShell('/alpha/saved')
+    expect(current('Saved')).toBe('page')
+    expect(current('Alpha')).toBeNull()
+  })
+})
+
+describe('the regions', () => {
+  it('puts navigation in the RAIL, beside the content rather than in a bar above it', () => {
+    renderShell('/alpha')
+    const rail = screen.getByRole('complementary', { name: 'Workspace' })
+    expect(rail.contains(screen.getByRole('navigation', { name: 'Surfaces' }))).toBe(true)
+  })
+
+  it('renders exactly one main landmark', () => {
+    renderShell('/alpha')
+    expect(screen.getAllByRole('main')).toHaveLength(1)
+  })
+
+  it('renders NO detail region until something fills it', () => {
+    renderShell('/alpha')
+    expect(screen.queryByRole('complementary', { name: 'Details' })).toBeNull()
+  })
+
+  it('renders the detail region a surface provides', () => {
+    renderShell('/alpha', <p>the selected object</p>)
+    expect(screen.getByRole('complementary', { name: 'Details' }).textContent).toContain('the selected object')
+  })
+})

rag_wright-0.16.0/.claude/skills/building-a-product-frontend/scaffold/ShellLayout.tsx

@@ -0,0 +1,90 @@
+import type { ReactNode } from 'react'
+import { NavLink, Outlet } from 'react-router' // `react-router-dom` on an older router: change this line only
+
+import { navigable, type Surface } from './surfaces'
+
+/**
+ * The application frame: `rail | main | detail`, with a fourth area reserved below.
+ *
+ *     rail  |  main    detail
+ *     rail  |  run     run
+ *
+ * Core, not product: it is given its surfaces and its name and knows neither, which is what lets a second
+ * application import this rather than copy it. The colour names are shadcn token names; the tokens are the
+ * product's, the structure is the point.
+ *
+ * **The run area is RESERVED, not built.** Nothing renders there until an agent run exists. Reserving costs
+ * one grid line; it buys that no surface is written assuming nothing can ever dock below it.
+ */
+export default function ShellLayout({ surfaces, productName, footer, detail }: {
+  surfaces: Surface[]
+  /** Supplied by the caller: the core must not know whose application it is drawing. */
+  productName: string
+  /** The foot of the rail: which account and workspace you are in is not a detail to drop. */
+  footer?: ReactNode
+  /**
+   * The panel for the currently selected object. **Absent until something fills it.** An empty landmark is
+   * worse than no landmark: a screen-reader user would find "Details", jump to it and arrive nowhere.
+   */
+  detail?: ReactNode
+}) {
+  return (
+    <div className={[
+      'min-h-screen lg:grid lg:grid-rows-[1fr_auto]',
+      // **The third column exists only when `detail` does, and that is not tidiness.** Row 2 is reserved for
+      // the run, so with two columns declared the detail panel -- the third child -- auto-places into the RUN
+      // slot: underneath `main`, full width, off-screen. jsdom computes no grid, so assert in the BROWSER that
+      // the panel is beside `main`.
+      detail === undefined
+        ? 'lg:grid-cols-[16rem_minmax(0,1fr)]'
+        // Capped, so `main` takes every pixel a wider viewport adds. An uncapped panel ends up wider than the
+        // content beside it (measured: 608px against 576px at 1440px).
+        : 'lg:grid-cols-[16rem_minmax(0,1fr)_minmax(20rem,26rem)]',
+    ].join(' ')}>
+      {/* The first tab stop, so a keyboard user is not forced through the whole navigation on every surface. */}
+      <a href="#main" className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-50 focus:rounded focus:bg-primary focus:px-3 focus:py-2 focus:text-sm focus:text-primary-foreground">
+        Skip to content
+      </a>
+
+      {/* **The RAIL.** Persistent, full height beside the content rather than a bar above it: it carries
+          workspace switching and the library, which GROW, and a horizontal bar cannot grow. `complementary`
+          rather than `navigation` because it holds more than links. */}
+      <aside aria-label="Workspace" className="flex flex-col gap-4 border-b border-border p-4 lg:row-span-2 lg:h-screen lg:overflow-y-auto lg:border-b-0 lg:border-r">
+        <span className="text-sm font-semibold tracking-tight">{productName}</span>
+
+        {/* Named, so it is a landmark a screen reader can jump to rather than an anonymous group. */}
+        <nav aria-label="Surfaces" className="flex flex-wrap gap-1 lg:flex-col lg:flex-nowrap">
+          {navigable(surfaces).map((surface) => (
+            <NavLink key={surface.path} to={surface.path} end={surface.nav?.end} className={navLinkClass}>
+              {surface.nav?.label}
+            </NavLink>
+          ))}
+        </nav>
+
+        {/* `mt-auto`: at the foot of a tall rail, simply after the navigation on a short one. */}
+        {footer === undefined ? null : <div className="lg:mt-auto">{footer}</div>}
+      </aside>
+
+      {/* Its own scroll container, so a long surface scrolls under a rail that stays put. */}
+      <main id="main" className="min-w-0 lg:h-screen lg:overflow-y-auto">
+        <Outlet />
+      </main>
+
+      {detail === undefined ? null : (
+        <aside aria-label="Details" className="min-w-0 border-t border-border p-4 lg:h-screen lg:overflow-y-auto lg:border-l lg:border-t-0">
+          {detail}
+        </aside>
+      )}
+    </div>
+  )
+}
+
+function navLinkClass({ isActive }: { isActive: boolean }): string {
+  // **The current surface is marked by `aria-current="page"`, which NavLink sets itself; this class is the
+  // visual echo.** The marker is a BORDER, not only a colour swap, so it stays legible in greyscale -- the half
+  // of a contrast requirement a palette cannot satisfy. `min-h-11` is 44px, the minimum hit area.
+  const base = 'inline-flex min-h-11 items-center rounded-md border-l-2 px-3 text-sm font-medium transition-colors'
+  return isActive
+    ? `${base} border-foreground bg-accent text-foreground`
+    : `${base} border-transparent text-muted-foreground hover:bg-accent/50 hover:text-foreground`
+}

rag_wright-0.16.0/.claude/skills/building-a-product-frontend/scaffold/surfaces.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react'
+
+/**
+ * One addressable surface of the application: the registry the PRODUCT populates and the shell only reads.
+ *
+ * One entry carries BOTH the route and the navigation, so the two cannot drift into separate lists that
+ * disagree about which pages exist. `nav` is optional: a surface reached from somewhere other than a menu
+ * (an account badge, a link handed out after a long-running job) is routed without being advertised.
+ */
+export type Surface = {
+  /** The address. Surfaces are addressable so a reload, a back button or an agent's link returns to it. */
+  path: string
+  element: ReactNode
+  nav?: {
+    label: string
+    /**
+     * `end` so a parent path does not stay highlighted while a child is open. Without it `/intake` matches
+     * `/intake/saved` too, and the wrong item stays lit beside the right one.
+     */
+    end?: boolean
+  }
+}
+
+/** The navigable subset, in registry order. */
+export function navigable(surfaces: Surface[]): Surface[] {
+  return surfaces.filter((surface) => surface.nav !== undefined)
+}

{rag_wright-0.14.1 → rag_wright-0.16.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`, `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 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`, `Contains`, 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.14.1/src/rag_wright/.agents → rag_wright-0.16.0/.claude}/skills/using-the-rag-wright-engine/SKILL.md

@@ -28,8 +28,8 @@ open-core and domain-neutral; your product brings the domain. Hard rules:
   (`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`, `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;
+  are equality, a list for membership, `NOT_NULL`, a `Range(gt=, ge=, lt=, le=)` or a `Contains(text, case_sensitive=False)` (a literal
+  substring; an empty field never matches) 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`,

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

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

{rag_wright-0.14.1 → rag_wright-0.16.0}/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.16.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.15.0...0.16.0) (2026-10-28)
+
+
+### Features
+
+* **PS-54:** a Contains where value matches a substring of a text field in the store ([e00b9e2](https://github.com/fzaidi-dai/RAG_Wright/commit/e00b9e271f7185cf5c15a0312d2e76c7c1eb68c6))
+
+
+### Bug Fixes
+
+* **PS-55:** only the BGE models run on Metal, one call at a time per process ([1cb1c90](https://github.com/fzaidi-dai/RAG_Wright/commit/1cb1c90ccc1d5e93421806c26862ab97d503bb72))
+* **PS-56:** the BGE reranker scores again on transformers 5 ([d06ec1b](https://github.com/fzaidi-dai/RAG_Wright/commit/d06ec1b97ad4ae457a232ba9f1bb5e89b033513b))
+
+## [0.15.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.14.1...0.15.0) (2026-10-28)
+
+
+### Features
+
+* **PS-51:** building-a-product-frontend draws the shell and ships its scaffold ([a16df0e](https://github.com/fzaidi-dai/RAG_Wright/commit/a16df0e8903cd43bf639ec3e2be11ae2bb242b08))
+
+
+### Bug Fixes
+
+* **PS-52:** a workspace builds one embedder however many threads use it first ([8e1617c](https://github.com/fzaidi-dai/RAG_Wright/commit/8e1617cee110fd909634b818ae2b6850d26a5a53))
+* **PS-53:** KG calls refuse a type or field name that is not an identifier ([12e55fa](https://github.com/fzaidi-dai/RAG_Wright/commit/12e55fa58739d22a3e01ee6187c7efd2a932cb27))
+
 ## [0.14.1](https://github.com/fzaidi-dai/RAG_Wright/compare/0.14.0...0.14.1) (2026-10-28)
 
 

{rag_wright-0.14.1 → rag_wright-0.16.0}/CLAUDE.md

@@ -55,7 +55,11 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 
 ## Start of every session
 
-> **CURRENT STATE (2026-10-17): the LangGraph ingestion workstream is RELEASED as `rag-wright` 0.14.0** (PR #16; LGI-1..5,
+> **CURRENT STATE (2026-10-28): `rag-wright` 0.15.0 is RELEASED** (PR #18; PS-51 the frontend skill draws the shell and
+> ships its scaffold, RuleWright's request; PS-52 one workspace embedder under concurrent first use and PS-53 KG calls refuse
+> a name that is not an identifier, TexWright's requests). Before it, **`rag-wright` 0.14.1 is RELEASED** (PR #17; TexWright's two requests: PS-49 a retried
+> ArcadeDB write conflict no longer prints as an error, PS-50 `ensure_pack_schema` declares a property a pack gains on an
+> existing type). Before it, **(2026-10-17): the LangGraph ingestion workstream is RELEASED as `rag-wright` 0.14.0** (PR #16; 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;

{rag_wright-0.14.1 → rag_wright-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.14.1
+Version: 0.16.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.16.0/docs/adr/0140-one-model-family-on-metal.md

@@ -0,0 +1,57 @@
+# ADR-0140: One model family on Metal, under one process lock
+
+**Status:** accepted · **Date:** 2026-10-29 · **Related:** PS-55, TexWright's request
+`2026-10-25-two-model-families-in-one-process-abort-on-metal.md`, RuleWright T-7.25 / T-7.46 (`_avoid_mps`), ADR-0076
+(issue 0016, the per-instance embedder lock), ADR-0138 (pdfium)
+
+## Context
+
+PyTorch's Apple Metal (`mps`) backend is not safe for concurrent use. Two threads running models on it abort the
+process inside Metal (`failed assertion _status < MTLCommandBufferStatusCommitted ... setCurrentCommandEncoder:`) or
+segfault it. Either way it is a native `abort()`, so nothing in Python can catch it.
+
+The engine reached Metal from three model families, each choosing its own device automatically:
+
+- the BGE-M3 embedder (`_resolve_device`);
+- the BGE reranker (FlagEmbedding's choice);
+- Docling's layout, table and RapidOCR-torch models (`AcceleratorOptions(device="auto")`).
+
+It also runs them on different threads: an ingest embeds one document while it parses another, and a server embeds
+a query while an upload parses. Issue 0016's per-instance locks do not help across instances or families.
+
+Reproduced with the BGE-M3 embedder in one thread and Docling in another, each run in a child process:
+
+- On torch 2.14.1 (TexWright's environment), 6 of 6 runs died within seconds: 5 SIGABRT with TexWright's
+  assertion, 1 SIGSEGV. Three of the runs OCR'd a screen image and three parsed PDFs.
+- On torch 2.12.1 the same shapes survived every run, so the failure depends on the torch version, and the newer
+  version makes it certain.
+- RuleWright measured it independently on their contract ingest: 4 crashes in about 8 runs on Metal, 0 in 6 on CPU.
+  They fixed it in their own seam (`_avoid_mps`), and the engine never adopted the fix.
+
+`docs/workspaces.md` claimed that concurrent calls in one process are safe without qualification.
+
+## Decision
+
+- **`rag_wright.util.devices`** owns the engine's device policy. Unless told otherwise, it uses CUDA when present.
+  On Metal it allows only the BGE family (the embedder and the reranker, the hot path, about 2x faster there).
+  Everything else goes to CPU.
+- **Docling** runs on CPU where its `auto` would pick Metal. The engine passes the device explicitly, because
+  Docling's default options are built once at import. Docling's output is identical on CPU and Metal (measured on
+  the engine's fixtures).
+- **The reference pack's classifiers** (SetFit, Laya) follow the same policy. Packs get it through
+  `pack_sdk.torch_device`, which never picks Metal unless asked.
+- **On Metal, every BGE call holds `METAL_LOCK`**, one re-entrant lock per process. Two embedders, or an embedder
+  and the reranker, never run on Metal at once. Off Metal each instance keeps its own lock (issue 0016), so a CUDA
+  host loses no concurrency.
+- **Explicit choices always win**, `mps` included: `EMBED_DEVICE` (the whole BGE family), `DOCLING_DEVICE`,
+  `RAG_SETFIT_DEVICE`, and any `device=` argument. This keeps the crash reproducible, and it means an operator who
+  puts a second family on Metal gives up the guarantee.
+
+## Consequences
+
+- A product needs no process-per-pipeline workaround. A server may stage an upload's ingest beside query traffic.
+  RuleWright can delete `_avoid_mps`, and TexWright can delete its spawned-process seed and the skipped browser test.
+- On Apple Silicon, Docling parses and the pack classifiers run on CPU (slower than Metal), and BGE calls from
+  different instances queue behind one another. A CUDA or CPU-only host is unchanged.
+- The rule holds only while engine code chooses the devices. A product's own torch model should take its device from
+  `pack_sdk.torch_device`, or it must stay off Metal.

{rag_wright-0.14.1 → rag_wright-0.16.0}/docs/adr/README.md

@@ -195,4 +195,5 @@ framing that still appears in older ADRs and the root `SPEC.md`/`plan.md`.
 0136 A spreadsheet table cut at its blank rows is glued back together after the parse ·
 0137 A generated answer states the evidence's support every time, and "none" is an abstention ·
 0138 PDF parses run one at a time, and the engine reaches pdfium through one locked door ·
-0139 The agent harness substrate is engine scope
+0139 The agent harness substrate is engine scope ·
+0140 One model family on Metal, under one process lock

{rag_wright-0.14.1 → rag_wright-0.16.0}/docs/api/README.md

@@ -88,6 +88,10 @@ A `where` value meaning a comparison, evaluated in the store (ER-1): `gt` (>), `
 
 `[(operator, bound), ...]`, lower bound first.
 
+### `Contains(text: 'str', case_sensitive: 'bool' = False) -> None`
+
+A `where` value meaning "this string field contains `text`", evaluated in the store (PS-54). The match is literal (`%`, `_` and `?` are ordinary characters), case-insensitive unless `case_sensitive=True`, and a field with no value never matches. It composes with equality, membership, `NOT_NULL` and `Range` on every KG call that takes `where`: `where={"composition": Contains("UHMWPE"), "gsm": Range(ge=250, le=320)}`.
+
 ### `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.
@@ -424,7 +428,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`). 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.
+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), a `Range` (comparisons, on any number of fields: `{"weight": Range(ge=180, le=220), "tensile": Range(gt=400)}`) or a `Contains` (a literal substring, case-insensitive unless `case_sensitive=True`; an empty field never matches: `{"composition": Contains("UHMWPE")}`); 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. Every name is checked, never interpolated unchecked (the module docstring): a request-chosen field is safe, but an unknown one matches nothing.
 
 ### `kg_write(ws: 'WorkspaceHandle', nodes: 'list', edges: 'Any' = ()) -> 'None'`
 
@@ -436,7 +440,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`); `where` as in `kg_read`, `Range` values included.
+The number of vertices or edges of `type_name` matching `where` / `key_range` (see `Store.kg_count`); `where` as in `kg_read`, `Range` and `Contains` values included.
 
 ### `kg_delete(ws: 'WorkspaceHandle', type_name: 'str', *, where: 'Optional[dict]' = None, key_range: 'Optional[tuple]' = None) -> 'int'`
 
@@ -456,7 +460,7 @@ Every span of `document` with its position provenance, ordered by document posit
 
 ### `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.
+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. Safe to call from several threads or requests at once: it shares the workspace's one embedder, which is thread-safe (PS-52).
 
 ### `aspan_search(ws: 'WorkspaceHandle', query: 'str', *, k: 'int' = 10, documents: 'Optional[list]' = None, tag: 'Optional[str]' = None, dense_floor: 'int' = 3) -> 'list'`
 

{rag_wright-0.14.1 → rag_wright-0.16.0}/docs/api/pack_sdk.md

@@ -116,11 +116,11 @@ Write the document's nodes/edges (one transaction), unless an unchanged run alre
 
 The graph query capability's output: candidate answers as evidence for fusion (FR-C.5, FR-Q.3).
 
-### `BGEReranker(model_name: 'str' = 'BAAI/bge-reranker-v2-m3', *, use_fp16: 'bool' = False, model: 'object | None' = None) -> 'None'`
+### `BGEReranker(model_name: 'str' = 'BAAI/bge-reranker-v2-m3', *, use_fp16: 'bool' = False, device: 'str | None' = None, model: 'object | None' = None) -> 'None'`
 
-The real reranker: `FlagEmbedding.FlagAutoReranker` (model loaded lazily).
+The real reranker: a `sentence_transformers.CrossEncoder` over `bge-reranker-v2-m3` (PS-56), scoring raw logits (no activation), 512 tokens per pair as before.
 
-THREAD-SAFE (engine issue 0016): FlagEmbedding mutates the model in place on every call (the same in-place `.to()`/`.eval()` conversions that segfault the shared BGE-M3 embedder under thread concurrency), so a shared reranker is guarded by an instance lock too -- defense-in-depth for any concurrent `score` caller.
+THREAD-SAFE (engine issue 0016): a shared reranker is guarded by an instance lock -- defense-in-depth for any concurrent `score` caller (its FlagEmbedding predecessor mutated the model in place on every call). It is in the BGE family: its device follows the embedder's (`EMBED_DEVICE`), and on Metal its lock is the process-wide one the embedders hold (PS-55), so a rerank never runs on Metal beside an embed.
 
 #### `BGEReranker.score(self, query: 'str', passages: 'list[str]') -> 'list[float]'`
 
@@ -358,6 +358,10 @@ True when at least one usage scope is active — the seam checks this to decide
 
 The models root (see the module docstring for the resolution order).
 
+### `torch_device(explicit: 'Optional[str]' = None, *, env: 'Optional[str]' = None, metal: 'bool' = False) -> 'str'`
+
+The device for one engine model: `explicit`, else the `env` variable, else CUDA when present, else Metal only for the family allowed on it (`metal=True`, the BGE family), else CPU.
+
 ### `business_span(name: 'str', **attributes: 'Any') -> 'Iterator[Any]'`
 
 A domain/business span on the AMBIENT tracer (never a new provider). No-op when OTel is absent.
@@ -494,7 +498,7 @@ Resolve a capability name to its invoke factory via the manifest `impl_ref`. Rai
 
 ### `workspace_embedder(ws: 'WorkspaceHandle') -> 'Any'`
 
-PS-38 (G22): the workspace's query embedder, built from its `EngineConfig.embeddings` profile on first use, so a pack capability embeds its queries with the model the corpus was indexed with. None when no embedder backend is available (the caller reports it).
+PS-38 (G22): the workspace's query embedder, built from its `EngineConfig.embeddings` profile on first use, so a pack capability embeds its queries with the model the corpus was indexed with. None when no embedder backend is available (the caller reports it). Thread-safe, as `WorkspaceHandle.embedder` (PS-52).
 
 ### `load_kg_schema(path: 'str') -> 'tuple[tuple[KgVertexType, ...], frozenset[str]]'`
 

{rag_wright-0.14.1 → rag_wright-0.16.0}/docs/configuration.md

@@ -294,7 +294,8 @@ Prefer config; use env for secrets and for non-API callers. The common ones the
 | `RAG_MODEL_DEADLINE_S` | total wall-clock limit for one model call across its retries (default: follows `RAG_STRUCTURED_TIMEOUT_S`, never under 180 s) |
 | `RAG_SPACY_MODEL` | the spaCy model name for the optional NER extra |
 | `RAG_MODELS_DIR` | the models root every trained classifier loads its weights from (default: the engine checkout's `data/models` when it exists, else `./data/models`); fill it with `scripts/fetch_reference_models.py` for the reference pack |
-| `EMBED_DEVICE` / `RAG_SETFIT_DEVICE` / `RAG_SETFIT_CLAUSE_DIR` / `RAG_SETFIT_THRESHOLD` / `RAG_SETFIT_TOPK` | embedder / classifier device + fleet knobs (`RAG_SETFIT_CLAUSE_DIR` overrides `<models root>/setfit_clause`) |
+| `EMBED_DEVICE` / `DOCLING_DEVICE` / `RAG_SETFIT_DEVICE` | where the local models run. Unset: CUDA when present; on Apple Silicon the BGE embedder and reranker (`EMBED_DEVICE`) run on Metal under one process lock and Docling and the classifiers on CPU, because Metal is not safe for concurrent use (PS-55, `docs/workspaces.md`). An explicit value, `mps` included, always wins |
+| `RAG_SETFIT_CLAUSE_DIR` / `RAG_SETFIT_THRESHOLD` / `RAG_SETFIT_TOPK` | classifier fleet knobs (`RAG_SETFIT_CLAUSE_DIR` overrides `<models root>/setfit_clause`) |
 | `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` / `LANGFUSE_HOST` / `RAG_TRACE_LEVEL` | observability (Langfuse tracing; see [`OBSERVABILITY.md`](OBSERVABILITY.md)) |
 | `RAG_EVAL_BACKEND` | `local` (default) or `langfuse`: where `arun_eval` runs when its `langfuse` argument is not given. `langfuse` needs the Langfuse keys and a gold set with `local_only=False`; a `local_only` gold set is refused before anything is sent |
 

{rag_wright-0.14.1 → rag_wright-0.16.0}/docs/specs/public-surface/plan.md

@@ -122,3 +122,10 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | PS-47 | The audit for PS-46: a parse cached before the fix keeps a blank page's invented text (the cache is keyed on content). `find_blank_pages_with_text(cache_dir, sources=(), *, progress)` and `BlankPageText` on `rag_wright.api` list every page blank in the source PDF (no ink, no text layer) with text in its cached parse, and the cache files to delete before re-ingesting. Searches the cache recursively (`aingest` keeps parses in `parsed/`); embedded files are audited from the cache's own copies; top-level sources are passed as paths or `(name, bytes)` | hermetic tests; a live `build_ingestion` of a workbook embedding a blank-tail PDF: clean, then a planted page found with nothing passed, then clean after delete and re-ingest | done 2026-10-15 |
 | PS-49 | TexWright's request (`docs/engine-requests/2026-10-17-concurrent-modification-printed-during-a-clean-ingest.md`, their repo): a clean keeper ingest printed `ArcadeDB Error Response ... ConcurrentModificationException` lines that read as failures. The retry is the engine's (`_retry_on_conflict`, every store write, since ING-5); the line is the client library's own ERROR log, printed before it raises. A log filter drops that line while the retry handles the call; the retry logs INFO `retried N times; the write landed`, or ERROR `gave up after 10 attempts` and raises | three hermetic tests (red before, green after); live 8-thread concurrent writes: 240/240 landed, 130 error lines before the fix, 0 after (62 INFO retried lines) | done 2026-10-17 |
 | PS-50 | TexWright's request (`docs/engine-requests/2026-10-28-ensure_pack_schema-does-not-declare-a-new-property-on-an-existing-type.md`, their repo): `ensure_pack_schema` declared a type's properties only when it created the type. It now creates every declared property the type lacks, on existing types too; a property whose declared type differs is logged and left as it is; a property the pack dropped stays; a non-STRING property declared over values stored before it is logged (they are not converted; a re-ingest rewrites them, and a value that does not convert fails its write) | a live test (red before, green after: added, mismatch reported, nothing dropped, the unconverted-values warning, a second run issues no DDL); live probe of a re-ingest over the new DOUBLE | done 2026-10-28 |
+| PS-51 | RuleWright's request (`docs/engine-requests/2026-10-28-the-frontend-skill-never-says-what-the-shell-looks-like.md`, their repo; TexWright shipped a top bar, no rail, no detail region, no current-surface state): `building-a-product-frontend` gains Decision 2, the shell's regions (`rail | main detail` over a reserved run row, entailed by the six things; a horizontal bar cannot grow; four columns do not fit at 1440px), the registry's real fields (`nav: { label, end }`, no `icon`), `aria-current` and more than colour with its test, the shell before the surfaces in the build order, two checklist items, and a shipped scaffold (`scaffold/surfaces.tsx`, `ShellLayout.tsx`, `ShellLayout.test.tsx`) | scaffold: strict `tsc`, 7/7 jsdom tests, the `end` and `aria-current` guards proved by planting; a production build measured in Chromium at 1440x900 (rail 256px, detail beside main, 44px links); `test_shipped_skills.py` checks the scaffold is named and ships in wheel + sdist | done 2026-10-28 |
+| PS-52 | TexWright's request (`docs/engine-requests/2026-10-24-workspace-embedder-is-not-thread-safe.md`, their repo): `WorkspaceHandle._embedder` was an unguarded check-then-set, so threads arriving at first use each built a model (`arun_eval(concurrency=4)`: four loads, then a SIGSEGV; each `BGEM3Embedder` locks only itself). A per-handle lock with a double check builds one; `ws.embedder`, `workspace_embedder` and `span_search` say the embedder may be called from several threads | a hermetic 8-thread first-use test (8 builds before, 1 after); live BGE-M3, 4 threads x 3 runs: 4 models in 12-18s before, 1 model in ~6s after; API reference regenerated | done 2026-10-28 |
+| PS-53 | TexWright's request (`docs/engine-requests/2026-10-21-identifiers-in-kg-queries-are-interpolated-unescaped.md`, their repo): KG calls escaped VALUES but interpolated NAMES raw (`where={"1=1 OR id": NOT_NULL}` returned every row). Every name a KG call puts into SQL is now checked first (types; `where` / `key_range` / `set` / `fields` / `distinct` fields; `order_by` terms; `kg_edges` select aliases and expressions; `KgNode` / `KgEdge` properties, key fields and types): an identifier, `@rid`/`@type`/`@in`/`@out` where read, `field [ASC|DESC]`, or a field on `c.`/`e.`/`v.`/`inV().`/`outV().`; else `ValueError`, nothing sent. Unknown fields still match nothing (undeclared properties are supported, the engine's own types carry them); the API docstrings say so | 29 hermetic cases (28 fail before); TexWright's payloads refused live; full hermetic (2327) and live store (67) suites green | done 2026-10-28 |
+| PS-54 | TexWright's request (`docs/engine-requests/2026-10-19-substring-match-in-the-kg-filter-grammar.md`, their repo): the KG filter grammar had no substring predicate ("composition contains UHMWPE" over free text). `Contains(text, case_sensitive=False)`, a `where` value beside `Range` on every KG call that takes `where`: a literal `indexOf` test (not `LIKE`, whose `%`, `_` and `?` are wildcards, measured live), case folded on both sides in the store, a field with no value never matches, empty text refused | 8 hermetic tests (red before) + a live test (case both ways, literal wildcards, quotes and backslashes, accents, missing values, with `Range`, `kg_count`, a `kg_edges` traversal filtered at all three points); full hermetic (2353) and live store (42) suites green | done 2026-10-29 |
+| PS-55 | TexWright's request (`docs/engine-requests/2026-10-25-two-model-families-in-one-process-abort-on-metal.md`, their repo): Metal is not safe for concurrent use and the engine put three families on it automatically (BGE-M3, the BGE reranker, Docling's layout/table/RapidOCR models), then ran them on different threads (an ingest embeds while it parses; a server embeds a query while an upload parses), so a process aborted in Metal. RuleWright had measured and pinned it in their own seam (T-7.25/T-7.46), never adopted here. `rag_wright.util.devices` (ADR-0140): only the BGE family on Metal, every call there under one process lock (`METAL_LOCK`); Docling and the pack classifiers on CPU where Metal would be picked (`pack_sdk.torch_device`); explicit device variables win; CUDA/CPU hosts unchanged; `docs/workspaces.md` corrected | red, torch 2.14.1 (TexWright's env, this engine tree): embedder + Docling in two threads, 6/6 child runs died in seconds (5 SIGABRT with their assertion, 1 SIGSEGV; OCR and PDF); torch 2.12.1 never failed. Green, same interpreter: 9/9 runs survived 150s each (OCR, PDF, two embedders). Full hermetic (2361) and live embed/parse/store (60) suites green. 8 hermetic tests (4 behaviour tests red before); Docling output identical CPU vs Metal | done 2026-10-29 |
+| PS-56 | Found during PS-55: `BGEReranker` failed on every call (`XLMRobertaTokenizer has no attribute prepare_for_model`): FlagEmbedding's `FlagAutoReranker.compute_score` calls a tokenizer method transformers 5 removed, so the reference pack's `intra_document_qa` rerank (and RuleWright's copy) and any product composing `BGEReranker` over `span_search` hits were broken. The reranker is now a `sentence_transformers.CrossEncoder` (already a dependency) over the same `bge-reranker-v2-m3`, raw logits, 512 tokens per pair; same `BGEReranker` API, device and lock (PS-55) | red: the live reranker test failed on the tokenizer error. Green: it passes, plus a one-pair and a >512-token case; CrossEncoder's logits equal the model card's plain-transformers recipe (max abs diff 0.0, truncated passage included); embedder + reranker on Metal under the shared lock, torch 2.14.1: 3/3 runs survived 150s, 590 reranks and 586 embeds, none failing (before: the rerank thread died on its first call); full hermetic (2361) green | done 2026-10-29 |
+| PS-48 | Port the agent harness's substrate behaviour tests from RuleWright onto the engine's fabric fixture (ADR-0139 handover): of RuleWright's 553 harness-touching tests, 314 test the substrate (port), 213 RuleWright's composition (stay), 25 live (1 substrate: OpenRouter cost accounting). Seven gated sub-tasks: **a** shared `tests/harness/fabric.py` + scripting/slow/hanging/failing fake models + `InMemorySaver` helpers, then events, skills, clarify (~23); **b** models and errors (~42); **c** runs, confirm, continuation (~32); **d** decisions and rules (~51); **e** grading (~32); **f** seen and memory (~41); **g** workers, batch, dispatch, tiers, agent wiring, filesystem, interpreter, withhold + the live accounting test (~93, may split). Ambiguous tests split, not moved whole; a ported test failing on engine code is a substrate defect fixed in that sub-task; deadline globals via monkeypatch; no new dependencies. Follow-up (owner RuleWright): retire its substrate duplicates once ported | each sub-task's ported tests green on the fabric fixture | todo (proposed; awaiting go-ahead) |