feat(vault): v1.4.0 world-class grep engine

Single-pass FTS5 OR query (SQLite) and ILIKE+trigram query (Postgres)
replaces the previous N+1 per-keyword search loop. Three-signal blended
scoring: keyword coverage (Lucene coord factor as multiplier), native
text rank (FTS5 bm25 / pg_trgm), and term proximity (cover density
ranking). Includes snippet highlighting, explain_metadata with full
scoring breakdown, trust weighting, SURVEIL re-evaluation, telemetry,
and query timeout protection.

New: StorageBackend.grep() protocol, grep_utils.py shared utilities,
GrepMatch dataclass, VaultConfig grep scoring weights.

Fixed: encryption test skip guards across test_v1_features, test_encryption,
and test_coverage_gaps for missing [encryption] extra.

799 tests passing, 62 new grep tests, zero regressions.

Author: bradleygauthier

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-04-08
+
+### Added
+- **World-class grep engine**: Complete rewrite of `AsyncVault.grep()` with three-signal blended scoring
+  - **Single-pass FTS5 OR query** (SQLite): one database round-trip regardless of keyword count, replacing the previous N+1 per-keyword search loop
+  - **Single-pass ILIKE + trigram query** (PostgreSQL): per-keyword CASE expressions with `GREATEST(similarity(...))` scoring
+  - **Three-signal scoring**: keyword coverage (Lucene coord factor as multiplier), native text rank (FTS5 bm25 / pg_trgm), term proximity (cover density ranking)
+  - **Keyword highlighting**: `explain_metadata.snippet` with configurable markers
+  - **Scoring breakdown**: `explain_metadata` includes `matched_keywords`, `hit_density`, `text_rank`, `proximity`, and `snippet`
+- `StorageBackend.grep()` protocol method: dedicated storage-level grep for both SQLite and PostgreSQL backends
+- `grep_utils.py`: shared utilities for FTS5 query building, keyword sanitization, snippet generation, keyword matching, and proximity scoring
+- `GrepMatch` dataclass: lightweight intermediate result type for storage-to-vault layer communication
+- `VaultConfig.grep_rank_weight` and `VaultConfig.grep_proximity_weight`: configurable scoring weights
+- 62 new grep tests across `test_grep.py` (51 tests) and `test_grep_utils.py` (31 tests)
+
+### Fixed
+- Encryption test skip guards: `test_v1_features.py`, `test_coverage_gaps.py`, `test_encryption.py` now correctly skip when `[encryption]` extra is not installed
+
+### Changed
+- Grep scoring formula: `coverage * (rank_weight * text_rank + proximity_weight * proximity)` replaces flat density-only scoring
+- Coverage acts as a multiplier (Lucene coord factor pattern): 3/3 keywords = full score, 1/3 = 33% score
+
 ## [1.0.0] - 2026-04-07
 
 ### Added

README.md

@@ -142,7 +142,7 @@ pip install qp-vault
 | `pip install qp-vault[local]` | + Local embeddings (sentence-transformers, air-gap safe) | + sentence-transformers |
 | `pip install qp-vault[openai]` | + OpenAI embeddings (cloud) | + openai |
 | `pip install qp-vault[integrity]` | + Near-duplicate + contradiction detection | + numpy |
-| `pip install qp-vault[fastapi]` | + REST API (22+ endpoints) | + fastapi |
+| `pip install qp-vault[fastapi]` | + REST API (30+ endpoints) | + fastapi |
 | `pip install qp-vault[cli]` | + `vault` command-line tool (15 commands) | + typer, rich |
 | `pip install qp-vault[all]` | Everything | All of the above |
 
@@ -170,6 +170,9 @@ vault.add("Incident response: acknowledge within 15 minutes...",
 # Trust-weighted search (deduplicated, with freshness decay)
 results = vault.search("incident response")
 
+# Multi-keyword grep (single-pass FTS, three-signal scoring)
+results = vault.grep(["incident", "response", "P0", "escalation"])
+
 # Retrieve full content
 text = vault.get_content(results[0].resource_id)
 

docs/api-reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-Complete Python SDK for qp-vault v1.0.0.
+Complete Python SDK for qp-vault v1.4.0.
 
 ## Constructor
 
@@ -101,6 +101,24 @@ Reassembles chunks in order to return the full text content. Quarantined resourc
 
 <!-- VERIFIED: vault.py:406-420 -->
 
+### reprocess()
+
+```python
+vault.reprocess(resource_id: str) -> Resource
+```
+
+Re-chunks and re-embeds an existing resource. Useful when the embedding model changes or chunking parameters are updated. The resource content is preserved; only chunks and embeddings are regenerated.
+
+```python
+# After switching embedding models
+updated = vault.reprocess(resource.id)
+assert updated.status == "indexed"
+```
+
+Emits an `UPDATE` subscriber event with `details={"reprocessed": True}`.
+
+<!-- VERIFIED: vault.py:706-770 -->
+
 ### list()
 
 ```python
@@ -121,6 +139,26 @@ vault.list(
 
 <!-- VERIFIED: vault.py:373-400 -->
 
+### find_by_name()
+
+```python
+vault.find_by_name(
+    name: str,
+    *,
+    tenant_id: str | None = None,
+    collection_id: str | None = None,
+) -> Resource | None
+```
+
+Case-insensitive name lookup. Returns the first matching non-deleted resource, or `None`.
+
+```python
+resource = vault.find_by_name("STRATEGY.md")
+# Also matches "strategy.md", "Strategy.MD"
+```
+
+<!-- VERIFIED: vault.py:632-668 -->
+
 ### update()
 
 ```python
@@ -196,7 +234,9 @@ vault.search(
 ) -> list[SearchResult]
 ```
 
-<!-- VERIFIED: vault.py:558-648 -->
+When no embedder is configured, search automatically falls back to text-only mode (`vector_weight=0.0`, `text_weight=1.0`). This ensures search works on day one without requiring an embedding model.
+
+<!-- VERIFIED: vault.py:1051-1063 — text-only fallback -->
 
 ### search_with_facets()
 
@@ -208,6 +248,37 @@ Returns `{"results": [...], "total": N, "facets": {"trust_tier": {...}, "resourc
 
 <!-- VERIFIED: vault.py:650-687 -->
 
+### grep()
+
+```python
+vault.grep(
+    keywords: list[str],
+    *,
+    tenant_id: str | None = None,
+    top_k: int = 20,
+    max_keywords: int = 20,
+) -> list[SearchResult]
+```
+
+Multi-keyword OR search with three-signal blended scoring. Executes a single FTS5 OR query (SQLite) or ILIKE+trigram query (PostgreSQL) regardless of keyword count.
+
+**Scoring formula:** `coverage * (0.7 * text_rank + 0.3 * proximity)` where:
+- **Coverage** (Lucene coord factor): `matched_keywords / total_keywords`, applied as a multiplier. 3/3 = full score, 1/3 = 33%.
+- **Text rank**: native FTS5 bm25 or pg_trgm similarity (0.0-1.0).
+- **Proximity**: how close matched keywords appear to each other within the chunk.
+
+```python
+results = vault.grep(["revenue", "Q3", "forecast"])
+# Results sorted by blended relevance (coverage * text_rank + proximity)
+# explain_metadata includes: matched_keywords, hit_density, text_rank, proximity, snippet
+print(results[0].explain_metadata["snippet"])
+# "...discussed **Q3** **revenue** **forecast** projections..."
+```
+
+No embedder required. Single database query. Results deduplicated by resource and trust-weighted.
+
+<!-- VERIFIED: vault.py:1172-1266 -->
+
 **SearchResult fields:**
 
 | Field | Type | Description |
@@ -369,6 +440,50 @@ vault.status() -> dict[str, Any]
 
 ---
 
+## Event Subscription
+
+### subscribe()
+
+```python
+vault.subscribe(callback: Callable[[VaultEvent], Any]) -> Callable[[], None]
+```
+
+Register a callback for vault mutation events. Returns an unsubscribe function. Callbacks can be sync or async; async callbacks are awaited directly. Errors in callbacks are logged and never propagated to the caller.
+
+```python
+from qp_vault import AsyncVault, VaultEvent
+
+vault = AsyncVault("./knowledge")
+
+# Sync callback
+def on_change(event: VaultEvent) -> None:
+    print(f"{event.event_type}: {event.resource_name}")
+
+unsub = vault.subscribe(on_change)
+
+# Add a resource (callback fires with CREATE event)
+vault.add("Content", name="doc.md")
+
+# Stop receiving events
+unsub()
+```
+
+**Events emitted on:**
+
+| Operation | EventType |
+|-----------|-----------|
+| `add()` | `CREATE` |
+| `update()` | `UPDATE` |
+| `delete()` | `DELETE` |
+| `reprocess()` | `UPDATE` (with `details.reprocessed=True`) |
+| `transition()` | `LIFECYCLE_TRANSITION` |
+
+Multiple subscribers are independent. Unsubscribing one does not affect others. Calling `unsub()` twice is safe.
+
+<!-- VERIFIED: vault.py:289-336 — subscribe + _notify_subscribers -->
+
+---
+
 ## Plugin Registration
 
 ```python

docs/fastapi.md

@@ -1,6 +1,6 @@
 # FastAPI Integration
 
-qp-vault provides 22+ ready-made REST API endpoints.
+qp-vault provides 30+ ready-made REST API endpoints.
 
 ```bash
 pip install qp-vault[fastapi]
@@ -49,12 +49,14 @@ app.include_router(router, prefix="/v1/vault")
 | `GET` | `/resources/{id}/proof` | Export Merkle proof |
 | `GET` | `/verify` | Verify entire vault |
 
-### Search
+### Search & Retrieval
 
 | Method | Path | Description |
 |--------|------|-------------|
 | `POST` | `/search` | Trust-weighted hybrid search |
 | `POST` | `/search/faceted` | Search with facet counts |
+| `POST` | `/grep` | Multi-keyword OR search (hit-density scoring) |
+| `GET` | `/resources/by-name` | Find resource by name (case-insensitive) |
 
 ### Collections
 
@@ -63,12 +65,27 @@ app.include_router(router, prefix="/v1/vault")
 | `GET` | `/collections` | List collections |
 | `POST` | `/collections` | Create collection |
 
-### Batch & Export
+### Processing
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/resources/{id}/reprocess` | Re-chunk and re-embed a resource |
+
+### Batch, Import & Export
 
 | Method | Path | Description |
 |--------|------|-------------|
 | `POST` | `/batch` | Batch add (max 100 items) |
+| `POST` | `/resources/multiple` | Get multiple resources by ID (max 100) |
 | `GET` | `/export` | Export vault to JSON |
+| `POST` | `/import` | Import resources from export file |
+
+### Adversarial & Diff
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `PATCH` | `/resources/{id}/adversarial` | Set adversarial verification status |
+| `GET` | `/resources/{old_id}/diff/{new_id}` | Unified diff between two resources |
 
 ### Intelligence
 
@@ -78,7 +95,7 @@ app.include_router(router, prefix="/v1/vault")
 | `GET` | `/status` | Resource counts and metadata |
 | `GET` | `/expiring` | Resources expiring within N days |
 
-<!-- VERIFIED: integrations/fastapi_routes.py:118-310 — all endpoints -->
+<!-- VERIFIED: integrations/fastapi_routes.py:118-390 — all endpoints -->
 
 ## Input Validation
 
@@ -94,6 +111,9 @@ All endpoints validate inputs at the API boundary before reaching vault logic.
 | `offset` | 0-1,000,000 | `GET /resources` |
 | Batch sources | Max 100 items | `POST /batch` |
 | `as_of` | Valid ISO date | `POST /search` |
+| `keywords` | Max 20 items | `POST /grep` |
+| `name` | Max 255 characters | `GET /resources/by-name` |
+| `resource_ids` | Max 100 items | `POST /resources/multiple` |
 
 <!-- VERIFIED: integrations/fastapi_routes.py:40 — content max_length -->
 <!-- VERIFIED: integrations/fastapi_routes.py:51-53 — SearchRequest validators -->

docs/getting-started.md

@@ -80,6 +80,22 @@ for r in results:
 
 Results are deduplicated (one per resource), ranked by: `(vector + text) * trust * freshness * layer_boost`.
 
+## Multi-Keyword Grep
+
+```python
+# Find documents where multiple concepts converge
+results = vault.grep(["incident", "response", "P0", "escalation"])
+
+for r in results:
+    meta = r.explain_metadata
+    print(f"{r.resource_name} — {len(meta['matched_keywords'])}/{4} keywords matched")
+    print(f"  snippet: {meta['snippet']}")
+```
+
+Single-pass FTS5 query. Scored by keyword coverage (coord factor), text relevance, and term proximity. No embedder required.
+
+<!-- VERIFIED: vault.py:1172-1285 — grep method -->
+
 ## Retrieve Content
 
 ```python

docs/index.md

@@ -6,7 +6,7 @@ Governed knowledge store for autonomous organizations. Every fact has provenance
 
 | Guide | Description |
 |-------|-------------|
-| [Getting Started](getting-started.md) | Install, first vault, add, search, verify in 5 minutes |
+| [Getting Started](getting-started.md) | Install, first vault, add, search, grep, verify in 5 minutes |
 | [Architecture](architecture.md) | Package structure, layers, data flow, Protocol interfaces |
 | [API Reference](api-reference.md) | Complete Python SDK: Vault, AsyncVault, all methods |
 | [Trust Tiers](trust-tiers.md) | CANONICAL, WORKING, EPHEMERAL, ARCHIVED and search weighting |
@@ -20,7 +20,7 @@ Governed knowledge store for autonomous organizations. Every fact has provenance
 | [Security Model](security.md) | SHA3-256, Merkle trees, input validation, threat model |
 | [Streaming & Telemetry](streaming-and-telemetry.md) | Real-time events, operation metrics |
 | [CLI Reference](cli.md) | All 15 commands |
-| [FastAPI Integration](fastapi.md) | 22+ REST endpoints |
+| [FastAPI Integration](fastapi.md) | 30+ REST endpoints |
 | [Migration Guide](migration.md) | Breaking changes from v0.x to v1.0 |
 | [Deployment Guide](deployment.md) | PostgreSQL, SSL, encryption, production checklist |
 | [Troubleshooting](troubleshooting.md) | Error codes (VAULT_000-700), common issues |

docs/streaming-and-telemetry.md

@@ -2,9 +2,50 @@
 
 Real-time event streaming and operation telemetry for autonomous AI systems.
 
-## Event Streaming
+## Event Subscription (Recommended)
 
-Subscribe to vault mutations in real-time.
+The simplest way to react to vault mutations. Register a callback directly on the vault instance:
+
+```python
+from qp_vault import AsyncVault, VaultEvent
+
+vault = AsyncVault("./knowledge")
+
+def on_change(event: VaultEvent) -> None:
+    print(f"{event.event_type}: {event.resource_name}")
+    if event.event_type.value == "create":
+        trigger_indexing(event.resource_id)
+
+unsub = vault.subscribe(on_change)
+
+# Every mutation (add, update, delete, transition, reprocess) fires the callback
+await vault.add("New document", name="report.md")
+# Output: create: report.md
+
+# Stop receiving events
+unsub()
+```
+
+Async callbacks are also supported:
+
+```python
+async def on_change_async(event: VaultEvent) -> None:
+    await notify_downstream(event)
+
+vault.subscribe(on_change_async)
+```
+
+**Key behaviors:**
+- Multiple subscribers are independent
+- Errors in callbacks are logged, never propagated
+- Calling `unsub()` twice is safe (no error)
+- Events are delivered synchronously in mutation order
+
+<!-- VERIFIED: vault.py:289-336 — subscribe + _notify_subscribers -->
+
+## Event Streaming (Advanced)
+
+For async-iterator consumption patterns (e.g., WebSocket broadcasting), use `VaultEventStream`:
 
 ```python
 from qp_vault import AsyncVault

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qp-vault"
-version = "1.3.0"
+version = "1.4.0"
 description = "Governed knowledge store for autonomous organizations. Trust tiers, cryptographic audit trails, content-addressed storage, air-gap native."
 readme = "README.md"
 license = "Apache-2.0"

src/qp_vault/__init__.py

@@ -26,7 +26,7 @@
 Docs: https://github.com/quantumpipes/vault
 """
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 __author__ = "Quantum Pipes Technologies, LLC"
 __license__ = "Apache-2.0"