@graphorin/reranker-transformersjs 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @graphorin/reranker-transformersjs
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+### Patch Changes
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- Updated dependencies [[`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`c1af9c7`](https://github.com/o-stepper/graphorin/commit/c1af9c790757fbe82da6dd2b6c1fdc497b5c605e), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`73b19ca`](https://github.com/o-stepper/graphorin/commit/73b19caeda388bda628a48138cb7d70b1db839a3), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04)]:
+  - @graphorin/core@0.7.0
+  - @graphorin/memory@0.7.0
+
+## 0.6.1
+
+### Patch Changes
+
+- [#142](https://github.com/o-stepper/graphorin/pull/142) [`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430) Thanks [@o-stepper](https://github.com/o-stepper)! - Version constants and version-bearing strings now derive from each package's manifest at build time (`VERSION = pkg.version`; writer ids, client/server info, OTLP framework attributes, build-info metrics interpolate it). No behavioral change at the current version: the rendered strings are byte-identical. A release bump no longer edits source; the new `check-version-consistency` gate fails any reintroduced hardcoded framework version.
+
+- Updated dependencies [[`436d6ca`](https://github.com/o-stepper/graphorin/commit/436d6ca5ebbd16df094e915682d3915c279a8430)]:
+  - @graphorin/core@0.6.1
+  - @graphorin/memory@0.6.1
+
 ## 0.6.0
 
 ### Patch Changes

package/README.md

@@ -7,14 +7,14 @@
 > entirely in-process. Implements the `ReRanker` contract from
 > `@graphorin/memory/search`.
 >
-> Project Graphorin · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko ·
+> Project Graphorin · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko ·
 > <https://github.com/o-stepper/graphorin>
 
 ---
 
 ## Status
 
-- **Published:** v0.6.0 (optional sub-pack)
+- **Published:** v0.7.0 (optional sub-pack)
 - **Default model:** locale-aware (`Xenova/bge-reranker-base` for
   English, `BAAI/bge-reranker-v2-m3` for everything else).
 - **Default precision:** FP16 (`'fp16'` dtype).
@@ -120,4 +120,4 @@ MIT © 2026 Oleksiy Stepurenko
 
 ---
 
-**Project Graphorin** · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Project Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/index.d.ts

@@ -37,8 +37,7 @@ import { CrossEncoderRerankerOptions, RERANKER_ID, TransformersJsReRanker, creat
  *
  * @packageDocumentation
  */
-/** Canonical version constant. Mirrors the `package.json` version. */
-declare const VERSION = "0.6.0";
+declare const VERSION: string;
 //#endregion
 export { type ClassifierResult, CrossEncoderLoadError, type CrossEncoderPipeline, type CrossEncoderPipelineFactory, type CrossEncoderRerankerOptions, DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, type LocaleTag, type PassageExtractor, RERANKER_ID, type RerankerDtype, TransformersJsReRanker, VERSION, _resetPipelineFactoryCacheForTesting, createCrossEncoderReranker, defaultPassageExtractor, extractPairScores, loadDefaultPipelineFactory, mergeAndDedupe, pickRerankerModel };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa"}

package/dist/index.js

@@ -1,3 +1,4 @@
+import { version } from "./package.js";
 import { CrossEncoderLoadError, _resetPipelineFactoryCacheForTesting, extractPairScores, loadDefaultPipelineFactory } from "./cross-encoder.js";
 import { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, pickRerankerModel } from "./model-selection.js";
 import { defaultPassageExtractor } from "./text-extraction.js";
@@ -36,8 +37,8 @@ import { RERANKER_ID, TransformersJsReRanker, createCrossEncoderReranker, mergeA
 *
 * @packageDocumentation
 */
-/** Canonical version constant. Mirrors the `package.json` version. */
-const VERSION = "0.6.0";
+/** Canonical version constant, derived from `package.json` at build time. */
+const VERSION = version;
 
 //#endregion
 export { CrossEncoderLoadError, DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL, RERANKER_ID, TransformersJsReRanker, VERSION, _resetPipelineFactoryCacheForTesting, createCrossEncoderReranker, defaultPassageExtractor, extractPairScores, loadDefaultPipelineFactory, mergeAndDedupe, pickRerankerModel };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/reranker-transformersjs - cross-encoder reranker adapter\n * for the Graphorin framework.\n *\n * Wraps `@huggingface/transformers@^4.1.0` to score `(query, passage)`\n * pairs in-process. Plug into the memory hybrid-search pipeline as a\n * drop-in replacement for the built-in `RRFReranker`:\n *\n * ```ts\n * import { createMemory } from '@graphorin/memory';\n * import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';\n *\n * const memory = createMemory({\n *   store,\n *   embedder,\n *   reranker: createCrossEncoderReranker({ locale: 'en' }),\n * });\n * ```\n *\n * Locale-aware default model:\n *\n *  - `'en'` / `'en-*'` → `Xenova/bge-reranker-base` (278M parameters,\n *    FP16 quantized).\n *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M parameters,\n *    multilingual baseline).\n *\n * Operators that want a narrower / language-specific cross-encoder\n * pass an explicit `model` option - the package's defaults\n * deliberately avoid privileging any single language pair.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.6.0';\n\nexport {\n  _resetPipelineFactoryCacheForTesting,\n  type ClassifierResult,\n  CrossEncoderLoadError,\n  type CrossEncoderPipeline,\n  type CrossEncoderPipelineFactory,\n  extractPairScores,\n  loadDefaultPipelineFactory,\n  type RerankerDtype,\n} from './cross-encoder.js';\nexport {\n  DEFAULT_ENGLISH_MODEL,\n  DEFAULT_MULTILINGUAL_MODEL,\n  type LocaleTag,\n  pickRerankerModel,\n} from './model-selection.js';\nexport {\n  type CrossEncoderRerankerOptions,\n  createCrossEncoderReranker,\n  mergeAndDedupe,\n  RERANKER_ID,\n  TransformersJsReRanker,\n} from './reranker.js';\nexport {\n  defaultPassageExtractor,\n  type PassageExtractor,\n} from './text-extraction.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,MAAa,UAAU"}
+{"version":3,"file":"index.js","names":["VERSION: string","pkg.version"],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/reranker-transformersjs - cross-encoder reranker adapter\n * for the Graphorin framework.\n *\n * Wraps `@huggingface/transformers@^4.1.0` to score `(query, passage)`\n * pairs in-process. Plug into the memory hybrid-search pipeline as a\n * drop-in replacement for the built-in `RRFReranker`:\n *\n * ```ts\n * import { createMemory } from '@graphorin/memory';\n * import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';\n *\n * const memory = createMemory({\n *   store,\n *   embedder,\n *   reranker: createCrossEncoderReranker({ locale: 'en' }),\n * });\n * ```\n *\n * Locale-aware default model:\n *\n *  - `'en'` / `'en-*'` → `Xenova/bge-reranker-base` (278M parameters,\n *    FP16 quantized).\n *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M parameters,\n *    multilingual baseline).\n *\n * Operators that want a narrower / language-specific cross-encoder\n * pass an explicit `model` option - the package's defaults\n * deliberately avoid privileging any single language pair.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant, derived from `package.json` at build time. */\nimport pkg from '../package.json' with { type: 'json' };\n\nexport const VERSION: string = pkg.version;\n\nexport {\n  _resetPipelineFactoryCacheForTesting,\n  type ClassifierResult,\n  CrossEncoderLoadError,\n  type CrossEncoderPipeline,\n  type CrossEncoderPipelineFactory,\n  extractPairScores,\n  loadDefaultPipelineFactory,\n  type RerankerDtype,\n} from './cross-encoder.js';\nexport {\n  DEFAULT_ENGLISH_MODEL,\n  DEFAULT_MULTILINGUAL_MODEL,\n  type LocaleTag,\n  pickRerankerModel,\n} from './model-selection.js';\nexport {\n  type CrossEncoderRerankerOptions,\n  createCrossEncoderReranker,\n  mergeAndDedupe,\n  RERANKER_ID,\n  TransformersJsReRanker,\n} from './reranker.js';\nexport {\n  defaultPassageExtractor,\n  type PassageExtractor,\n} from './text-extraction.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAaA,UAAkBC"}

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.7.0";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/reranker-transformersjs\",\n  \"version\": \"0.7.0\",\n  \"description\": \"Cross-encoder reranker adapter for the Graphorin framework. Wraps `@huggingface/transformers@^4.1.0` to score query / passage pairs in-process via the BAAI BGE family of cross-encoder models. Automatic model selection from the agent locale: `'en'` defaults to `Xenova/bge-reranker-base` (278M); every other locale defaults to `BAAI/bge-reranker-v2-m3` (568M, multilingual). FP16 quantization default; FP32 / Q8 opt-in. Lazy-loaded with an optional idle-eviction timer to bound resident memory. Implements the `ReRanker` contract exposed by `@graphorin/memory/search`. Created and maintained by Oleksiy Stepurenko.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/reranker-transformersjs\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/reranker-transformersjs\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"rerank\",\n    \"reranker\",\n    \"cross-encoder\",\n    \"huggingface\",\n    \"transformersjs\",\n    \"bge\",\n    \"bge-reranker\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"sideEffects\": false,\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\",\n    \"@graphorin/memory\": \"workspace:*\"\n  },\n  \"peerDependencies\": {\n    \"@huggingface/transformers\": \"^4.1.0\"\n  },\n  \"peerDependenciesMeta\": {\n    \"@huggingface/transformers\": {\n      \"optional\": false\n    }\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  }\n}\n"],"mappings":";cAEa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/reranker-transformersjs",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Cross-encoder reranker adapter for the Graphorin framework. Wraps `@huggingface/transformers@^4.1.0` to score query / passage pairs in-process via the BAAI BGE family of cross-encoder models. Automatic model selection from the agent locale: `'en'` defaults to `Xenova/bge-reranker-base` (278M); every other locale defaults to `BAAI/bge-reranker-v2-m3` (568M, multilingual). FP16 quantization default; FP32 / Q8 opt-in. Lazy-loaded with an optional idle-eviction timer to bound resident memory. Implements the `ReRanker` contract exposed by `@graphorin/memory/search`. Created and maintained by Oleksiy Stepurenko.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -28,7 +28,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -37,19 +37,20 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/core": "0.6.0",
-    "@graphorin/memory": "0.6.0"
+    "@graphorin/core": "0.7.0",
+    "@graphorin/memory": "0.7.0"
   },
   "peerDependencies": {
     "@huggingface/transformers": "^4.1.0"

package/src/cross-encoder.ts

@@ -0,0 +1,148 @@
+/**
+ * Lazy `@huggingface/transformers` text-classification pipeline used to
+ * score query / passage pairs. The runner caches the first-loaded
+ * pipeline per `(model, dtype, device, revision, cacheDir)` tuple so
+ * repeated `rerank(...)` calls inside the same process do not pay the
+ * model-load cost twice.
+ *
+ * Tests inject a stub `pipelineFactory`; the production path lazily
+ * imports `@huggingface/transformers` so plain inspection of the
+ * package (e.g. for documentation generation) does not pull in the
+ * native ONNX runtime.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Numeric dtype hint. Default `'fp16'` per Phase 16 §
+ * `@graphorin/reranker-transformersjs`.
+ *
+ * @stable
+ */
+export type RerankerDtype = 'fp32' | 'fp16' | 'q8' | 'q4';
+
+/**
+ * Output shape returned by `@huggingface/transformers`'
+ * text-classification pipeline. Each pair returns either a single
+ * `{ label, score }` object (top-k = 1) or an array of them. We
+ * normalise on the array form upstream so the cross-encoder always
+ * sees a consistent shape.
+ *
+ * @internal
+ */
+export interface ClassifierResult {
+  readonly label: string;
+  readonly score: number;
+}
+
+/** @internal */
+export type CrossEncoderPipeline = (
+  pairs: ReadonlyArray<{ text: string; text_pair: string }>,
+  options?: { topk?: number; signal?: AbortSignal },
+) => Promise<ReadonlyArray<ClassifierResult> | ReadonlyArray<ReadonlyArray<ClassifierResult>>>;
+
+/** @internal */
+export type CrossEncoderPipelineFactory = (
+  task: 'text-classification',
+  model: string,
+  options: {
+    revision?: string;
+    cache_dir?: string;
+    dtype?: RerankerDtype;
+    device?: string;
+  },
+) => Promise<CrossEncoderPipeline>;
+
+/**
+ * Raised when the `@huggingface/transformers` peer is missing or the
+ * configured cross-encoder model fails to load.
+ *
+ * @stable
+ */
+export class CrossEncoderLoadError extends Error {
+  override readonly name = 'CrossEncoderLoadError';
+}
+
+/** @internal */
+let CACHED_PIPELINE_FACTORY: CrossEncoderPipelineFactory | null = null;
+
+/** @internal */
+export async function loadDefaultPipelineFactory(): Promise<CrossEncoderPipelineFactory> {
+  if (CACHED_PIPELINE_FACTORY !== null) return CACHED_PIPELINE_FACTORY;
+  try {
+    const mod = (await import('@huggingface/transformers')) as unknown as {
+      pipeline: CrossEncoderPipelineFactory;
+    };
+    CACHED_PIPELINE_FACTORY = mod.pipeline;
+    return CACHED_PIPELINE_FACTORY;
+  } catch (err) {
+    throw new CrossEncoderLoadError(
+      "[graphorin/reranker-transformersjs] required peer '@huggingface/transformers' is not installed.",
+      { cause: err },
+    );
+  }
+}
+
+/**
+ * Test-only helper. Drops the cached pipeline factory so the next
+ * loader call re-imports the peer.
+ *
+ * @internal
+ */
+export function _resetPipelineFactoryCacheForTesting(): void {
+  CACHED_PIPELINE_FACTORY = null;
+}
+
+/**
+ * True when a classifier label names the *positive* (relevant) class. Matches
+ * the conventional binary forms - `LABEL_1`, `positive`, `relevant`,
+ * `entailment`, `true`, `yes` - using exact words so it does not mis-fire on a
+ * negative label that merely contains one (`irrelevant` ⊃ `relevant`).
+ */
+function isPositiveLabel(label: string): boolean {
+  const l = label.toLowerCase().trim();
+  if (l === '1' || /(?:^|[_-])1$/.test(l)) return true; // '1', 'label_1', 'class-1'
+  return /^(?:positive|relevant|entailment|true|yes|pos)$/.test(l);
+}
+
+/**
+ * Normalises the raw pipeline output to a flat `score[]` aligned with the input
+ * pair order. Cross-encoder classifiers return either a single-best
+ * `{label, score}` per pair (the default single-logit bge exports) or an array
+ * of `topk` entries. For the array shape we read the POSITIVE label's
+ * confidence - NOT the max of any label (PS-16): an irrelevant pair's most
+ * confident class is the *negative* one, so taking the max would invert the
+ * ranking for any 2-label classifier. When no label looks positive (single-logit
+ * or unrecognised labels) we fall back to the top score.
+ *
+ * @internal
+ */
+export function extractPairScores(
+  raw: ReadonlyArray<ClassifierResult> | ReadonlyArray<ReadonlyArray<ClassifierResult>>,
+  pairCount: number,
+): number[] {
+  const out: number[] = new Array(pairCount).fill(0) as number[];
+  for (let i = 0; i < pairCount; i++) {
+    const cell = raw[i];
+    if (cell === undefined) continue;
+    if (Array.isArray(cell)) {
+      let best = Number.NEGATIVE_INFINITY;
+      let positive = Number.NEGATIVE_INFINITY;
+      let sawPositive = false;
+      for (const entry of cell) {
+        if (entry === undefined) continue;
+        if (entry.score > best) best = entry.score;
+        if (isPositiveLabel(entry.label)) {
+          sawPositive = true;
+          if (entry.score > positive) positive = entry.score;
+        }
+      }
+      const chosen = sawPositive ? positive : best;
+      out[i] = Number.isFinite(chosen) ? chosen : 0;
+    } else {
+      const single = cell as ClassifierResult;
+      out[i] = single.score;
+    }
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @graphorin/reranker-transformersjs - cross-encoder reranker adapter
+ * for the Graphorin framework.
+ *
+ * Wraps `@huggingface/transformers@^4.1.0` to score `(query, passage)`
+ * pairs in-process. Plug into the memory hybrid-search pipeline as a
+ * drop-in replacement for the built-in `RRFReranker`:
+ *
+ * ```ts
+ * import { createMemory } from '@graphorin/memory';
+ * import { createCrossEncoderReranker } from '@graphorin/reranker-transformersjs';
+ *
+ * const memory = createMemory({
+ *   store,
+ *   embedder,
+ *   reranker: createCrossEncoderReranker({ locale: 'en' }),
+ * });
+ * ```
+ *
+ * Locale-aware default model:
+ *
+ *  - `'en'` / `'en-*'` → `Xenova/bge-reranker-base` (278M parameters,
+ *    FP16 quantized).
+ *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M parameters,
+ *    multilingual baseline).
+ *
+ * Operators that want a narrower / language-specific cross-encoder
+ * pass an explicit `model` option - the package's defaults
+ * deliberately avoid privileging any single language pair.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export {
+  _resetPipelineFactoryCacheForTesting,
+  type ClassifierResult,
+  CrossEncoderLoadError,
+  type CrossEncoderPipeline,
+  type CrossEncoderPipelineFactory,
+  extractPairScores,
+  loadDefaultPipelineFactory,
+  type RerankerDtype,
+} from './cross-encoder.js';
+export {
+  DEFAULT_ENGLISH_MODEL,
+  DEFAULT_MULTILINGUAL_MODEL,
+  type LocaleTag,
+  pickRerankerModel,
+} from './model-selection.js';
+export {
+  type CrossEncoderRerankerOptions,
+  createCrossEncoderReranker,
+  mergeAndDedupe,
+  RERANKER_ID,
+  TransformersJsReRanker,
+} from './reranker.js';
+export {
+  defaultPassageExtractor,
+  type PassageExtractor,
+} from './text-extraction.js';

package/src/model-selection.ts

@@ -0,0 +1,40 @@
+/**
+ * Locale-aware default model selector. Mirrors ADR-024 / DEC-120 § BGE
+ * model family:
+ *
+ *  - English-only deployments → `Xenova/bge-reranker-base` (278M, FP16).
+ *  - Every other locale → `BAAI/bge-reranker-v2-m3` (568M, multilingual).
+ *
+ * The selector deliberately stays language-pair-agnostic outside the
+ * English fast path; operators that want a narrower / language-specific
+ * cross-encoder pass an explicit `model` to {@link
+ * createCrossEncoderReranker}.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * BCP 47 locale tag (e.g. `'en'`, `'en-GB'`, `'pt-BR'`, `'zh-Hans-CN'`).
+ *
+ * @stable
+ */
+export type LocaleTag = string;
+
+/** @stable */
+export const DEFAULT_ENGLISH_MODEL = 'Xenova/bge-reranker-base';
+/** @stable */
+export const DEFAULT_MULTILINGUAL_MODEL = 'BAAI/bge-reranker-v2-m3';
+
+/**
+ * Pick a reranker model from the agent locale. Pure function so callers
+ * (and tests) can pre-resolve the choice without constructing the
+ * reranker.
+ *
+ * @stable
+ */
+export function pickRerankerModel(locale: LocaleTag | undefined): string {
+  if (locale === undefined || locale.length === 0) return DEFAULT_MULTILINGUAL_MODEL;
+  const normalized = locale.toLowerCase();
+  if (normalized === 'en' || normalized.startsWith('en-')) return DEFAULT_ENGLISH_MODEL;
+  return DEFAULT_MULTILINGUAL_MODEL;
+}

package/src/reranker.ts

@@ -0,0 +1,318 @@
+/**
+ * Cross-encoder `ReRanker` implementation backed by
+ * `@huggingface/transformers`. Lazy-loaded, optional idle eviction,
+ * locale-aware default model.
+ *
+ * @packageDocumentation
+ */
+
+import type { MemoryHit, MemoryRecord } from '@graphorin/core';
+import type { ReRanker, ReRankOptions } from '@graphorin/memory/search';
+
+import {
+  CrossEncoderLoadError,
+  type CrossEncoderPipeline,
+  type CrossEncoderPipelineFactory,
+  extractPairScores,
+  loadDefaultPipelineFactory,
+  type RerankerDtype,
+} from './cross-encoder.js';
+import {
+  DEFAULT_ENGLISH_MODEL,
+  DEFAULT_MULTILINGUAL_MODEL,
+  type LocaleTag,
+  pickRerankerModel,
+} from './model-selection.js';
+import { defaultPassageExtractor, type PassageExtractor } from './text-extraction.js';
+
+/**
+ * Options accepted by {@link createCrossEncoderReranker}.
+ *
+ * @stable
+ */
+export interface CrossEncoderRerankerOptions<TRecord extends MemoryRecord = MemoryRecord> {
+  /** Override the auto-picked model. Default: derived from `locale`. */
+  readonly model?: string;
+  /** BCP 47 locale tag used to select the default model. Default `'en'`. */
+  readonly locale?: LocaleTag;
+  /** Default `'fp16'`. */
+  readonly dtype?: RerankerDtype;
+  /** Optional revision pin (`'main'` if unset). */
+  readonly revision?: string;
+  /** Optional cache directory. Honours `GRAPHORIN_CACHE_DIR` when unset. */
+  readonly cacheDir?: string;
+  /** Override device (`'cpu'`, `'webgpu'`, …). Default `'cpu'`. */
+  readonly device?: string;
+  /**
+   * Maximum batch size sent to the cross-encoder per inference call.
+   * Default `32`. Larger batches improve throughput at the cost of
+   * resident memory.
+   */
+  readonly batchSize?: number;
+  /**
+   * Optional idle-eviction timeout in milliseconds. When the reranker
+   * does not score a pair within this window, the loaded pipeline is
+   * dropped so the OS can reclaim the underlying ONNX session. Default
+   * `undefined` (eviction disabled).
+   */
+  readonly idleEvictionMs?: number;
+  /**
+   * Optional passage extractor - replaces the default heuristic that
+   * walks `text → summary → value → label → id`. Useful when a custom
+   * `MemoryRecord` schema attaches the canonical text elsewhere.
+   */
+  readonly passageExtractor?: PassageExtractor<TRecord>;
+  /**
+   * Inject a `pipelineFactory`. Used by tests to stub the underlying
+   * `@huggingface/transformers` pipeline. Production callers leave
+   * this unset so the package lazily loads the peer.
+   */
+  readonly pipelineFactory?: CrossEncoderPipelineFactory;
+  /**
+   * Override the wall-clock provider. Used by tests so the
+   * idle-eviction timer can be exercised deterministically.
+   *
+   * @internal
+   */
+  readonly now?: () => number;
+}
+
+/** @stable */
+export const RERANKER_ID = 'transformersjs-cross-encoder' as const;
+
+/**
+ * Build a cross-encoder reranker. Lazy: the pipeline is constructed on
+ * the first `rerank()` call so packaging the reranker pays no
+ * model-load cost.
+ *
+ * @stable
+ */
+export function createCrossEncoderReranker<TRecord extends MemoryRecord = MemoryRecord>(
+  options: CrossEncoderRerankerOptions<TRecord> = {},
+): TransformersJsReRanker<TRecord> {
+  return new TransformersJsReRanker<TRecord>(options);
+}
+
+/**
+ * `ReRanker` implementation. Matches the contract from
+ * `@graphorin/memory/search`.
+ *
+ * @stable
+ */
+export class TransformersJsReRanker<TRecord extends MemoryRecord = MemoryRecord>
+  implements ReRanker
+{
+  readonly id = RERANKER_ID;
+  readonly model: string;
+  readonly locale: LocaleTag;
+  readonly dtype: RerankerDtype;
+  readonly batchSize: number;
+  readonly idleEvictionMs: number | undefined;
+
+  readonly #revision: string | undefined;
+  readonly #cacheDir: string | undefined;
+  readonly #device: string | undefined;
+  readonly #pipelineFactory: CrossEncoderPipelineFactory | undefined;
+  readonly #passageExtractor: PassageExtractor<TRecord>;
+  readonly #now: () => number;
+  #pipeline: CrossEncoderPipeline | null = null;
+  #loading: Promise<CrossEncoderPipeline> | null = null;
+  #lastUsedAt: number = 0;
+  #idleTimer: ReturnType<typeof setTimeout> | null = null;
+  #invocationCount = 0;
+
+  constructor(options: CrossEncoderRerankerOptions<TRecord>) {
+    this.locale = options.locale ?? 'en';
+    this.model = options.model ?? pickRerankerModel(this.locale);
+    this.dtype = options.dtype ?? 'fp16';
+    this.batchSize = options.batchSize ?? 32;
+    if (!Number.isInteger(this.batchSize) || this.batchSize <= 0) {
+      throw new RangeError(
+        `[graphorin/reranker-transformersjs] batchSize must be a positive integer; got ${String(
+          options.batchSize,
+        )}.`,
+      );
+    }
+    this.idleEvictionMs = options.idleEvictionMs;
+    this.#revision = options.revision;
+    this.#cacheDir = options.cacheDir ?? process.env.GRAPHORIN_CACHE_DIR;
+    this.#device = options.device;
+    this.#pipelineFactory = options.pipelineFactory;
+    this.#passageExtractor =
+      options.passageExtractor ?? ((record: TRecord) => defaultPassageExtractor(record));
+    this.#now = options.now ?? Date.now;
+  }
+
+  /**
+   * Number of `rerank(...)` invocations since construction. Surfaced
+   * for observability + the test suite.
+   *
+   * @stable
+   */
+  get invocationCount(): number {
+    return this.#invocationCount;
+  }
+
+  /**
+   * Whether the underlying ONNX pipeline is currently loaded in
+   * memory. Surfaced for the idle-eviction integration test.
+   *
+   * @stable
+   */
+  get pipelineLoaded(): boolean {
+    return this.#pipeline !== null;
+  }
+
+  /**
+   * Drop the loaded pipeline. Equivalent to letting the idle-eviction
+   * timer fire. Idempotent.
+   *
+   * @stable
+   */
+  unload(): void {
+    this.#pipeline = null;
+    this.#loading = null;
+    if (this.#idleTimer !== null) {
+      clearTimeout(this.#idleTimer);
+      this.#idleTimer = null;
+    }
+  }
+
+  async rerank<TInputRecord extends MemoryRecord>(
+    query: string,
+    lists: ReadonlyArray<ReadonlyArray<MemoryHit<TInputRecord>>>,
+    options: ReRankOptions = {},
+  ): Promise<ReadonlyArray<MemoryHit<TInputRecord>>> {
+    if (options.signal?.aborted === true) {
+      throw new DOMException('TransformersJsReRanker aborted', 'AbortError');
+    }
+    this.#invocationCount += 1;
+    const merged = mergeAndDedupe(lists);
+    if (merged.length === 0) return [];
+    const pipeline = await this.#getPipeline();
+    const passages = merged.map((entry) =>
+      this.#passageExtractor(entry.hit.record as unknown as TRecord),
+    );
+    const scores = await this.#scoreInBatches(pipeline, query, passages, options.signal);
+    const fused: MemoryHit<TInputRecord>[] = merged.map((entry, idx) => {
+      const score = scores[idx] ?? 0;
+      const baseSignals = entry.hit.signals ?? {};
+      const signals: Record<string, number> = {
+        ...baseSignals,
+        cross_encoder: score,
+      };
+      return Object.freeze({
+        record: entry.hit.record,
+        score,
+        signals: Object.freeze(signals),
+      });
+    });
+    fused.sort((a, b) => b.score - a.score);
+    const topK = options.topK ?? 10;
+    return fused.slice(0, Math.max(0, topK));
+  }
+
+  async #scoreInBatches(
+    pipeline: CrossEncoderPipeline,
+    query: string,
+    passages: ReadonlyArray<string>,
+    signal: AbortSignal | undefined,
+  ): Promise<number[]> {
+    const out: number[] = [];
+    for (let i = 0; i < passages.length; i += this.batchSize) {
+      if (signal?.aborted === true) {
+        throw new DOMException('TransformersJsReRanker aborted', 'AbortError');
+      }
+      const batch = passages.slice(i, i + this.batchSize);
+      const pairs = batch.map((text_pair) => ({ text: query, text_pair }));
+      const raw = await pipeline(pairs, {
+        topk: 1,
+        ...(signal !== undefined ? { signal } : {}),
+      });
+      const scores = extractPairScores(raw, batch.length);
+      for (const s of scores) out.push(s);
+    }
+    return out;
+  }
+
+  async #getPipeline(): Promise<CrossEncoderPipeline> {
+    this.#lastUsedAt = this.#now();
+    this.#scheduleIdleEviction();
+    if (this.#pipeline !== null) return this.#pipeline;
+    if (this.#loading !== null) return this.#loading;
+    const factory = this.#pipelineFactory ?? (await loadDefaultPipelineFactory());
+    this.#loading = factory('text-classification', this.model, {
+      ...(this.#revision !== undefined ? { revision: this.#revision } : {}),
+      ...(this.#cacheDir !== undefined ? { cache_dir: this.#cacheDir } : {}),
+      ...(this.dtype !== undefined ? { dtype: this.dtype } : {}),
+      ...(this.#device !== undefined ? { device: this.#device } : {}),
+    })
+      .then((pipe) => {
+        this.#pipeline = pipe;
+        this.#loading = null;
+        return pipe;
+      })
+      .catch((err) => {
+        this.#loading = null;
+        throw new CrossEncoderLoadError(
+          `[graphorin/reranker-transformersjs] failed to load model '${this.model}'.`,
+          { cause: err },
+        );
+      });
+    return this.#loading;
+  }
+
+  #scheduleIdleEviction(): void {
+    if (this.idleEvictionMs === undefined) return;
+    if (this.#idleTimer !== null) {
+      clearTimeout(this.#idleTimer);
+    }
+    this.#idleTimer = setTimeout(() => {
+      const elapsed = this.#now() - this.#lastUsedAt;
+      if (elapsed >= (this.idleEvictionMs ?? 0)) {
+        this.#pipeline = null;
+        this.#loading = null;
+      }
+      this.#idleTimer = null;
+    }, this.idleEvictionMs);
+    this.#idleTimer.unref?.();
+  }
+}
+
+interface MergedEntry<TRecord extends MemoryRecord> {
+  readonly hit: MemoryHit<TRecord>;
+  readonly firstSeenOrder: number;
+}
+
+/**
+ * Merge the per-source lists into a single deduplicated array,
+ * preserving the **highest** initial score per record id and the
+ * **first-seen order** for stable tie-breaking. Pure function;
+ * exported for the unit test fixture.
+ *
+ * @stable
+ */
+export function mergeAndDedupe<TRecord extends MemoryRecord>(
+  lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>,
+): ReadonlyArray<MergedEntry<TRecord>> {
+  const out = new Map<string, MergedEntry<TRecord>>();
+  let order = 0;
+  for (const list of lists) {
+    for (const hit of list) {
+      const existing = out.get(hit.record.id);
+      if (existing === undefined) {
+        out.set(hit.record.id, { hit, firstSeenOrder: order++ });
+      } else if (hit.score > existing.hit.score) {
+        out.set(hit.record.id, {
+          hit,
+          firstSeenOrder: existing.firstSeenOrder,
+        });
+      }
+    }
+  }
+  const arr = Array.from(out.values());
+  arr.sort((a, b) => a.firstSeenOrder - b.firstSeenOrder);
+  return arr;
+}
+
+export { DEFAULT_ENGLISH_MODEL, DEFAULT_MULTILINGUAL_MODEL };

package/src/text-extraction.ts

@@ -0,0 +1,49 @@
+/**
+ * Heuristic text-extraction helpers. The reranker scores `(query,
+ * passage)` pairs; this module turns a `MemoryRecord` of any concrete
+ * tier into the best single-passage approximation.
+ *
+ * The defaults are conservative - text-bearing fields take precedence
+ * over IDs / labels - and operators may inject a custom
+ * `passageExtractor` when their schema attaches the canonical text
+ * elsewhere.
+ *
+ * @packageDocumentation
+ */
+
+import type { MemoryRecord } from '@graphorin/core';
+
+/**
+ * Returns the best-effort passage text for a {@link MemoryRecord}. The
+ * order of preference, top-down:
+ *
+ *   1. `text` - facts, rules, generic text-bearing tiers.
+ *   2. `summary` - episodes.
+ *   3. `value` - working-memory blocks.
+ *   4. `id` fallback so the reranker never sees an empty passage.
+ *
+ * @stable
+ */
+export function defaultPassageExtractor(record: MemoryRecord): string {
+  const obj = record as unknown as Record<string, unknown>;
+  const text = obj.text;
+  if (typeof text === 'string' && text.length > 0) return text;
+  const summary = obj.summary;
+  if (typeof summary === 'string' && summary.length > 0) return summary;
+  const value = obj.value;
+  if (typeof value === 'string' && value.length > 0) return value;
+  const label = obj.label;
+  if (typeof label === 'string' && label.length > 0) return label;
+  return record.id;
+}
+
+/**
+ * Caller-supplied passage extractor. Receives the record + the
+ * surrounding metadata (kind, sensitivity, tags) and returns the
+ * passage to feed into the cross-encoder.
+ *
+ * @stable
+ */
+export type PassageExtractor<TRecord extends MemoryRecord = MemoryRecord> = (
+  record: TRecord,
+) => string;