@jcode.labs/ragmir 2.17.2 → 2.18.1

package/dist/workload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload.js","sourceRoot":"","sources":["../src/workload.ts"],"names":[],"mappings":"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"}

package/examples/document-evidence-benchmark/README.md

@@ -1,51 +1,36 @@
 # Document evidence benchmark
 
-A deterministic, public-safe benchmark for the retrieval and citation quality coding agents receive
-from Ragmir's confidential local RAG pipeline.
+A deterministic, public-safe benchmark for the retrieval and citation quality a coding agent
+receives from Ragmir. Six golden queries require the expected path and an exact file, line, chunk,
+or PDF-page citation. The fictional corpus runs offline with `local-hash`.
 
-Use this example when you want to prove more than "a relevant file appeared." Its six golden queries
-check that Ragmir retrieves the expected path and the exact file, line, chunk, or PDF-page citation.
-Every document is fictional and safe to commit. The benchmark keeps its corpus and generated index
-on the machine and runs the default `local-hash` retrieval offline.
+## What passes
 
-## What it measures
-
-| Signal | What a passing result means |
+| Signal | Requirement |
 | --- | --- |
-| `Recall@K` | An expected source path appears within the configured top K results |
-| Exact text citation | The expected `relative/path:Lx-Ly#chunkIndex` is returned |
-| Exact PDF citation | The expected `relative/path:pN:Lx-Ly#chunkIndex` is returned |
-
-The corpus is intentionally small enough for each source to fit in one chunk. That makes citation
-expectations stable while exercising the same ingestion and evaluation code used for private
-knowledge bases.
+| Recall@K | An expected source appears in the configured top K |
+| Text citation | Exact `relative/path:Lx-Ly#chunkIndex` |
+| PDF citation | Exact `relative/path:pN#chunkIndex`, with no invented source lines |
 
-## Corpus
+Each source fits in one chunk so citation expectations stay stable while exercising the production
+ingestion and evaluation pipeline.
 
-| Fictional source | Evidence type |
+| Fictional source | Evidence |
 | --- | --- |
 | `raw/contracts/master-services-agreement.md` | Contract and residency obligations |
-| `raw/contracts/pdf-control-evidence.pdf` | Embedded PDF text with a page citation |
+| `raw/contracts/pdf-control-evidence.pdf` | Embedded PDF text and page citation |
 | `raw/rfp/security-questionnaire.md` | Security and hosting requirements |
 | `raw/runbooks/incident-response-runbook.md` | Operational evidence collection |
 | `raw/specs/agent-integration-spec.md` | Agent and retrieval boundaries |
 | `raw/legal-tax/residency-review-note.md` | Professional-review disclaimer |
 
-[`golden-queries.json`](./golden-queries.json) maps each test query to its expected path and exact
-citation.
+[`golden-queries.json`](./golden-queries.json) maps questions to expected paths and citations.
 
-## Run the benchmark
-
-From the repository root, install dependencies and build the packages:
+## Run it
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm build
-```
-
-Then run the benchmark from this directory:
-
-```bash
 cd packages/ragmir-core/examples/document-evidence-benchmark
 node ../../dist/cli.js init
 node ../../dist/cli.js ingest --rebuild
@@ -53,40 +38,17 @@ node ../../dist/cli.js evaluate --golden golden-queries.json --json
 node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 1
 ```
 
-The last command exits non-zero unless every golden query succeeds at the configured threshold.
-Keep the JSON output when you need machine-readable evidence for CI or a retrieval-quality review.
-
-## Read a failure
-
-1. Check `rgr audit` for missing, stale, or skipped source files.
-2. Inspect the failed query's returned paths and citations in JSON output.
-3. Decide whether the corpus, expected citation, chunking, or retrieval mode changed.
-4. Update a golden expectation only when the intended product behavior changed.
-
-Do not lower `--fail-under` merely to make a regression pass.
-
-## Adapt it to a private corpus
-
-Copy the structure, not the fictional documents:
-
-```text
-private-evaluation/
-├── .ragmir/config.json
-├── golden-queries.json
-└── raw/
-```
-
-For each important question, record the smallest set of expected source paths. Add exact citations
-when the source is stable enough to make line, page, and chunk boundaries meaningful. Keep private
-contracts, RFPs, runbooks, tax notes, scans, golden queries, and evaluation reports outside Git or
-under ignored local state.
+The final command fails unless every query meets the threshold. Keep JSON output when CI or a
+retrieval review needs machine-readable evidence.
 
-## Safety
+On failure, run `rgr audit`, inspect returned paths and citations, then decide whether retrieval,
+chunking, the corpus, or the intended expectation changed. Update a golden query only for an
+intentional behavior change; never lower `--fail-under` to hide a regression.
 
-- The committed corpus contains no customer or production data.
-- The benchmark uses the offline `local-hash` provider and needs no model download.
-- Generated `.ragmir/storage` and evaluation output stay local and ignored.
-- A perfect synthetic score proves this fixture, not universal retrieval quality.
+For private evaluation, copy the `.ragmir/config.json`, `golden-queries.json`, and `raw/` structure
+into an ignored workspace. Record the smallest expected source set and exact coordinates only when
+the source is stable. Never commit private documents, queries, or reports.
 
-Return to the [Ragmir Core README](../../README.md) or try the
-[confidential local RAG demo](../sovereign-rag-demo/README.md) for a broader CLI walkthrough.
+A perfect score proves this fixture, not universal retrieval quality. Continue with the
+[confidential local RAG demo](../sovereign-rag-demo/README.md) or
+[Core README](../../README.md).

package/examples/document-evidence-benchmark/golden-queries.json

@@ -35,7 +35,7 @@
       "id": "pdf-embedded-text-page-citation",
       "query": "Synthetic confidential PDF",
       "expectedPaths": ["raw/contracts/pdf-control-evidence.pdf"],
-      "expectedCitations": ["raw/contracts/pdf-control-evidence.pdf:p1:L1-L1#0"]
+      "expectedCitations": ["raw/contracts/pdf-control-evidence.pdf:p1#0"]
     }
   ]
 }

package/examples/library-api-demo/README.md

@@ -1,50 +1,24 @@
 # Library API demo
 
-A runnable smoke test for the public `@jcode.labs/ragmir` TypeScript API behind confidential local
-RAG workflows for coding agents and scripts.
-
-Use this example when you are changing Ragmir Core or evaluating it as a library rather than as a
-CLI. It imports the same package name an external consumer uses, runs the full retrieval loop, and
-prints cited results from a fictional local corpus. The default `local-hash` path keeps the corpus
-and generated index on the machine and performs retrieval offline.
-
-## What it proves
-
-The demo opens one persistent client and exercises four public operations in order:
-
-1. `ragmir.ingest({ rebuild: true })` parses, redacts, chunks, embeds, and stores the corpus.
-2. `ragmir.search(query, { topK })` returns ranked source passages.
-3. `ragmir.ask(query, { topK })` returns retrieval-only cited context without LLM synthesis.
-4. `ragmir.status()` reports the active knowledge base and indexed coverage.
-
-Node's package self-reference resolves `@jcode.labs/ragmir` to this checkout's local
-`packages/ragmir-core/dist` build. It never falls back to the npm-published version, so the result
-reflects the code you are currently reviewing.
+A runnable smoke test for the public `@jcode.labs/ragmir` TypeScript API. It opens one persistent
+client, ingests a fictional local corpus, retrieves cited passages, returns retrieval-only context,
+and reports status through the same package name an external consumer imports.
 
 ## Run it
 
-From the repository root:
-
 ```bash
 pnpm install --frozen-lockfile
 pnpm example
 ```
 
-The root command builds the published packages required by Core and runs [`run.mjs`](./run.mjs). The
-output is organized into `ingest`, `search`, `ask`, and `status` sections so a reviewer can see each
-public step succeed.
-
-To rerun only the script after an existing build:
+The root command builds the packages and runs [`run.mjs`](./run.mjs). Package self-reference points
+to this checkout's `packages/ragmir-core/dist`, never the npm release. To rerun after a build:
 
 ```bash
 node packages/ragmir-core/examples/library-api-demo/run.mjs
 ```
 
-`dist/` is ignored, so a clean clone must be built at least once.
-
-## The public API pattern
-
-The essential integration is intentionally small:
+## Integration pattern
 
 ```js
 import { createRagmirClient } from "@jcode.labs/ragmir"
@@ -52,39 +26,25 @@ import { createRagmirClient } from "@jcode.labs/ragmir"
 const ragmir = await createRagmirClient({ cwd: projectRoot })
 try {
   await ragmir.ingest({ rebuild: true, timeoutMs: 30_000 })
-
   const results = await ragmir.search("offline retrieval approval", { topK: 3 })
-
   const context = await ragmir.ask("What evidence supports offline operation?", { topK: 3 })
-
   const status = await ragmir.status()
 } finally {
   await ragmir.close()
 }
 ```
 
-All project-relative state is resolved once from `cwd`. Reuse one client per project root in a
-long-running Node.js process and close it during shutdown. For one-shot scripts, the top-level
-`ingest`, `search`, `ask`, and `audit` functions remain available.
-
-## Data used by the demo
+The demo proves `ingest`, `search`, `ask`, and `status` in order. `ask` returns cited context without
+LLM synthesis. Reuse one client per project root in a long-running process; one-shot top-level
+functions remain available.
 
-The script reuses the sibling [confidential local RAG demo](../sovereign-rag-demo/README.md):
+The script shares the sibling demo's synthetic Markdown, CSV, JSONL, YAML, and custom-text corpus.
+It uses offline `local-hash`, writes only ignored `.ragmir/storage`, downloads no model, and contains
+no private documents. Keep committed changes deterministic and use a separate ignored corpus for
+private tests.
 
-- committed synthetic Markdown, CSV, JSONL, YAML, and custom text files;
-- an offline `local-hash` configuration;
-- gitignored `.ragmir/storage` output;
-- no private documents and no model download.
-
-Change the queries in `run.mjs` when testing a retrieval behavior, but keep the committed demo
-deterministic and public-safe. Use a separate ignored corpus for private evaluations.
-
-## When to use another example
-
-| Need | Example |
+| Need | Continue with |
 | --- | --- |
-| Learn the complete CLI workflow | [Confidential local RAG demo](../sovereign-rag-demo/README.md) |
-| Measure exact paths and citations | [Document evidence benchmark](../document-evidence-benchmark/README.md) |
-| Explore every exported function and option | [Complete TypeScript API reference](../../../../docs/api-reference.md) |
-
-Return to the [Ragmir Core README](../../README.md) for installation, MCP, OCR, and privacy guidance.
+| Complete CLI workflow | [Confidential local RAG demo](../sovereign-rag-demo/README.md) |
+| Exact path and citation gates | [Document evidence benchmark](../document-evidence-benchmark/README.md) |
+| Every exported option | [TypeScript API reference](../../../../docs/api-reference.md) |

package/examples/sovereign-rag-demo/README.md

@@ -1,42 +1,29 @@
 # Confidential local RAG demo
 
-A complete, fictional workspace for learning how agents and scripts retrieve cited local project
-context with Ragmir.
-
-Use this example to ingest several file types, search with citations, inspect privacy posture, find
-an unsupported file, evaluate golden queries, and prepare agent access. It keeps the fictional
-corpus and generated index on the machine, runs with offline `local-hash` retrieval, and contains no
-customer or production data.
+A complete fictional workspace for learning how agents and scripts retrieve cited project evidence
+with Ragmir. It covers multiple formats, privacy checks, unsupported files, golden queries, and
+agent access while keeping corpus and index local with offline `local-hash` retrieval.
 
 ## Scenario
 
-The corpus models an operations team reviewing whether an evidence workflow can stay local:
-
-| File | Role in the scenario |
+| File | Role |
 | --- | --- |
 | `raw/operations-brief.md` | Approval, ownership, and operating requirements |
 | `raw/dataset-inventory.csv` | Accepted and rejected datasets |
 | `raw/incident-timeline.jsonl` | Time-ordered operational evidence |
 | `raw/security-policy.yaml` | Model-loading and security rules |
-| `raw/review-notes.evidence` | Custom text extension configured for this project |
-| `raw/facility-scan.heic` | Deliberately unsupported file used by the audit example |
+| `raw/review-notes.evidence` | Project-configured text extension |
+| `raw/facility-scan.heic` | Deliberately unsupported audit fixture |
 
-## Run the full workflow
-
-From the repository root:
+## Run the workflow
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm build
-```
-
-Then enter this example and run the local CLI build:
-
-```bash
 cd packages/ragmir-core/examples/sovereign-rag-demo
 node ../../dist/cli.js init
 
-# POSIX only: this example deliberately uses a custom tracked rawDir.
+# POSIX only: Git and npm archives do not preserve this fixture's intended mode.
 chmod 700 raw
 
 node ../../dist/cli.js security-audit
@@ -49,101 +36,54 @@ node ../../dist/cli.js audit --unsupported
 node ../../dist/cli.js status
 ```
 
-`init` is idempotent. Git and npm archives cannot preserve the example's intended `0700` raw-folder
-mode, so the explicit `chmod` keeps the raw corpus owner-only on POSIX systems.
+`init` is idempotent. The security audit intentionally warns that `.ragmir/` is not fully ignored
+because this public fixture commits its configuration and source list. Generated storage, models,
+reports, audio, logs, and salts remain ignored. Private projects should ignore the complete
+`.ragmir/` directory.
 
-The security audit still reports that `.ragmir/` is not fully ignored. That warning is expected only
-for this public fixture because it deliberately commits `.ragmir/config.json` and
-`.ragmir/sources.txt`. Generated storage, models, reports, audio, logs, and salts remain ignored.
-Normal private projects should ignore the complete `.ragmir/` directory.
+Expected results:
 
-## What to look for
+- search and ask identify source paths and chunks;
+- `ask` returns evidence, not a generated answer;
+- `research` combines bounded queries and source diagnostics;
+- every golden query finds its expected source;
+- the audit explains why HEIC was skipped and suggests local OCR;
+- status confirms the active provider and local index.
 
-- Search and ask output identify the source path and chunk.
-- `ask` returns cited passages, not a generated answer from a hosted LLM.
-- `research` combines several retrieval queries and reports source diagnostics.
-- The audit surfaces the fixture-specific tracked-config warning described above.
-- The golden evaluation finds the expected sources for all four questions.
-- `audit --unsupported` explains why the HEIC fixture was skipped and recommends local OCR.
-- `status` confirms the active provider and local index state.
+Useful queries include `dataset residency`, `incident containment evidence`,
+`who owns the usage review`, and `what documents support sovereign deployment`.
 
-## Useful queries
+## Connect an agent
 
-```text
-offline retrieval approval
-dataset residency
-incident containment evidence
-who owns the usage review
-what documents support sovereign deployment
-```
-
-Try a precise query first, then compare it with `research --compact` when the question spans several
-files.
-
-## Give the demo to an agent
-
-In a real project, `rgr setup` generates an MCP helper under `.ragmir/`. After setup, an
-MCP-compatible agent can follow a prompt like:
+In a real project, `rgr setup` writes an ignored MCP helper. A compatible agent can then follow:
 
 ```text
-Use Ragmir to inspect the local knowledge base, search for "offline retrieval approval", and write a
-cited Markdown report under .ragmir/reports/demo-sovereign-rag.md. Mention any unsupported or stale
-files reported by the audit.
+Use Ragmir to search for "offline retrieval approval" and write a cited report under
+.ragmir/reports/demo-sovereign-rag.md. Mention unsupported or stale files reported by the audit.
 ```
 
-The report path stays under ignored local state. Do not commit generated reports that may contain
-retrieved project evidence.
+Keep retrieved reports under ignored local state.
 
 ## Compare semantic retrieval
 
-The committed configuration uses:
+The committed configuration uses offline lexical/hash retrieval:
 
 ```json
-{
-  "embeddingProvider": "local-hash"
-}
+{ "embeddingProvider": "local-hash" }
 ```
 
-This is offline lexical/hash retrieval, not model-semantic search. To run a deliberate semantic
-comparison, configure a Transformers.js model, preload it under `.ragmir/models`, and rebuild:
+For a deliberate semantic comparison, prepare a Transformers.js model locally, set
+`embeddingProvider`, `embeddingModel`, `embeddingModelRevision`, `embeddingModelPath`, and
+`transformersAllowRemoteModels: false`, then rebuild and rerun evaluation. Keep remote loading off.
+A lower semantic score is a tuning signal, never a reason to weaken a quality gate.
 
-```json
-{
-  "embeddingProvider": "transformers",
-  "embeddingModel": "intfloat/multilingual-e5-small",
-  "embeddingModelRevision": "main",
-  "embeddingModelPath": ".ragmir/models",
-  "transformersAllowRemoteModels": false
-}
-```
-
-```bash
-node ../../dist/cli.js ingest --rebuild
-node ../../dist/cli.js evaluate --golden golden-queries.json --json
-```
-
-Keep remote model loading disabled for an offline comparison. A lower semantic score may indicate
-that queries or thresholds need tuning, not that a gate should be weakened.
-
-## Generated state and cleanup
-
-All runtime state stays under the ignored directory:
-
-```text
-.ragmir/
-```
-
-Remove only the generated index when you want a clean rerun:
+All generated state stays under `.ragmir/`. Reset only the index with:
 
 ```bash
 node ../../dist/cli.js destroy-index --yes
 ```
 
-Never replace the fictional fixtures in this package with real confidential documents. Use a
-separate ignored workspace for private dogfooding.
-
-## Continue exploring
-
-- [Library API demo](../library-api-demo/README.md): call the public TypeScript API.
-- [Document evidence benchmark](../document-evidence-benchmark/README.md): require exact paths and citations.
-- [Ragmir Core README](../../README.md): installation, MCP, OCR, and privacy reference.
+Never replace the fictional fixtures with confidential documents. Continue with the
+[Library API demo](../library-api-demo/README.md),
+[Document evidence benchmark](../document-evidence-benchmark/README.md), or
+[Core README](../../README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcode.labs/ragmir",
-  "version": "2.17.2",
+  "version": "2.18.1",
   "description": "Confidential local RAG for coding agents, with offline cited retrieval through CLI, MCP, and TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "url": "https://github.com/jcode-works/jcode-ragmir/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "exports": {
     ".": {
@@ -48,9 +48,9 @@
     }
   },
   "bin": {
-    "ragmir": "dist/cli.js",
-    "kb": "dist/cli.js",
-    "rgr": "dist/cli.js"
+    "ragmir": "dist/cli-entry.js",
+    "kb": "dist/cli-entry.js",
+    "rgr": "dist/cli-entry.js"
   },
   "files": [
     "dist",
@@ -72,13 +72,14 @@
     "mammoth": "^1.12.0",
     "picocolors": "^1.1.1",
     "read-excel-file": "^9.2.0",
+    "safe-regex2": "^5.1.1",
     "unpdf": "^1.4.0",
     "yaml": "^2.9.0",
     "zod": "^4.1.13"
   },
   "peerDependencies": {
-    "@jcode.labs/ragmir-chat": "2.17.2",
-    "@jcode.labs/ragmir-tts": "2.17.2"
+    "@jcode.labs/ragmir-chat": "2.18.1",
+    "@jcode.labs/ragmir-tts": "2.18.1"
   },
   "peerDependenciesMeta": {
     "@jcode.labs/ragmir-chat": {
@@ -91,18 +92,42 @@
   "devDependencies": {
     "@types/html-to-text": "^9.0.4",
     "@types/node": "^24.10.1",
+    "apache-arrow": "^18.1.0",
     "publint": "^0.3.21",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15",
-    "@jcode.labs/ragmir-chat": "2.17.2",
-    "@jcode.labs/ragmir-tts": "2.17.2"
+    "@jcode.labs/ragmir-chat": "2.18.1",
+    "@jcode.labs/ragmir-tts": "2.18.1"
   },
   "scripts": {
+    "bench:compare": "node benchmarks/compare.mjs",
+    "bench:cli-startup": "pnpm build && node benchmarks/cli-startup.mjs",
+    "bench:concurrency": "pnpm build && node benchmarks/concurrency.mjs",
+    "bench:discovery": "pnpm build && node benchmarks/discovery.mjs",
+    "bench:ingest-memory": "pnpm build && node benchmarks/ingest-memory.mjs",
+    "bench:ingestion-metadata": "pnpm build && node benchmarks/ingestion-metadata.mjs",
+    "bench:local-hash-runtime": "pnpm build && node benchmarks/local-hash-runtime.mjs",
+    "bench:local-hash-experiment": "pnpm build && node benchmarks/local-hash-experiment.mjs",
+    "bench:reranker-experiment": "pnpm build && node benchmarks/reranker-experiment.mjs",
+    "bench:index-compression-experiment": "pnpm build && node benchmarks/index-compression-experiment.mjs",
+    "bench:content-dedup-experiment": "pnpm build && node benchmarks/content-dedup-experiment.mjs",
+    "bench:model-lifecycle": "pnpm build && node benchmarks/model-lifecycle.mjs",
+    "bench:observability": "pnpm build && node benchmarks/observability.mjs",
+    "bench:parsers": "pnpm build && node benchmarks/parsers.mjs",
+    "bench:runtime": "pnpm build && node benchmarks/runtime-reuse.mjs",
+    "bench:ocr": "pnpm build && node benchmarks/ocr-cache.mjs",
+    "bench:generations": "pnpm build && node benchmarks/generation-retention.mjs",
+    "bench:quality": "pnpm build && node benchmarks/quality.mjs",
+    "bench:scale": "pnpm build && node benchmarks/run.mjs --profile scale",
+    "bench:smoke": "pnpm build && node benchmarks/verify.mjs && node benchmarks/run.mjs --profile smoke",
+    "bench:storage": "pnpm build && node benchmarks/storage-maintenance.mjs",
+    "bench:status": "pnpm build && node benchmarks/status.mjs",
+    "bench:vector-index": "pnpm build && node benchmarks/vector-index.mjs",
     "build": "tsc -p tsconfig.json",
     "check": "pnpm --filter @jcode.labs/ragmir-tts build && pnpm --filter @jcode.labs/ragmir-chat build && tsc -p tsconfig.json --noEmit",
     "mcp:smoke": "pnpm build && node scripts/mcp-smoke.mjs",
     "package:check": "publint",
-    "test": "pnpm --filter @jcode.labs/ragmir-tts build && pnpm --filter @jcode.labs/ragmir-chat build && vitest run",
-    "test:coverage": "pnpm --filter @jcode.labs/ragmir-tts build && pnpm --filter @jcode.labs/ragmir-chat build && vitest run --coverage"
+    "test": "pnpm --filter @jcode.labs/ragmir-tts build && pnpm --filter @jcode.labs/ragmir-chat build && pnpm build && vitest run",
+    "test:coverage": "pnpm --filter @jcode.labs/ragmir-tts build && pnpm --filter @jcode.labs/ragmir-chat build && pnpm build && vitest run --coverage"
   }
 }