feat(vault): v1.3.0 — all technical gaps closed (government-grade)

5 remaining gaps from world-class roadmap, all implemented:

GAP-7a: Membrane CORRELATE stage
  - Cross-document contradiction detection
  - Searches vault for trusted (CANONICAL) content, uses LLM to check
    if new content contradicts existing knowledge
  - Prevents "poisoning by contradiction" attacks

GAP-7b: Membrane REMEMBER stage
  - Attack pattern registry with SHA3-256 fingerprinting
  - Learns from quarantined/flagged content automatically
  - Fast pre-check before regex/LLM stages
  - Export/import patterns for persistence
  - Bounded registry with LRU eviction

GAP-7c: Membrane SURVEIL stage
  - Query-time re-evaluation of search results
  - Penalizes SUSPICIOUS resources (0.3x relevance)
  - Adds explain metadata for verification status
  - Applied after trust weighting, before return

GAP-8: Embedding dimension mismatch detection
  - get_embedding_dimension() on StorageBackend Protocol + both backends
  - _ensure_initialized() checks dimension consistency
  - Raises VaultError if embedder dimensions don't match stored vectors

GAP-12: Resource version diff
  - vault.diff(old_id, new_id) returns unified diff
  - Counts additions/deletions, includes resource names
  - Sync wrapper included

Pipeline now runs 5 stages: REMEMBER -> INNATE -> ADAPTIVE -> CORRELATE -> RELEASE
SURVEIL applied at search time (post-search filter).

18 new tests. Verified: ruff 0, mypy strict 0, 681 tests passing.
All 12 roadmap gaps: CLOSED.

Author: bradleygauthier

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qp-vault"
-version = "1.2.0"
+version = "1.3.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.2.0"
+__version__ = "1.3.0"
 __author__ = "Quantum Pipes Technologies, LLC"
 __license__ = "Apache-2.0"
 

src/qp_vault/membrane/correlate.py

@@ -0,0 +1,144 @@
+# Copyright 2026 Quantum Pipes Technologies, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Correlate stage: cross-document contradiction detection.
+
+Checks whether incoming content contradicts existing trusted knowledge
+in the vault. Detects "poisoning by contradiction" attacks where an
+adversary submits content that conflicts with authoritative sources.
+
+Requires an LLMScreener for semantic contradiction analysis.
+Without one, the stage is skipped. Without a vault reference, skipped.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from qp_vault.enums import MembraneResult, MembraneStage
+from qp_vault.models import MembraneStageRecord
+
+if TYPE_CHECKING:
+    from qp_vault.protocols import LLMScreener, ScreeningResult
+
+_CONTRADICTION_PROMPT = """\
+Compare the NEW content against the EXISTING trusted content below.
+Determine if the NEW content contradicts the EXISTING content.
+
+<existing>
+{existing}
+</existing>
+
+<new>
+{new_content}
+</new>
+
+Respond with ONLY a JSON object:
+{{"risk_score": 0.0, "reasoning": "one sentence", "flags": []}}
+
+risk_score: 0.0 (no contradiction) to 1.0 (direct contradiction).
+flags: ["contradiction"] if contradictory, else [].
+reasoning: one-sentence explanation.\
+"""
+
+
+@dataclass
+class CorrelateConfig:
+    """Configuration for the correlate stage."""
+
+    screener: LLMScreener | None = None
+    vault: Any = None  # AsyncVault (avoid circular import)
+    max_trusted_docs: int = 5
+    max_content_chars: int = 2000
+    risk_threshold: float = 0.7
+    tenant_id: str | None = None
+
+
+async def run_correlate(
+    content: str,
+    config: CorrelateConfig | None = None,
+) -> MembraneStageRecord:
+    """Check if new content contradicts existing trusted knowledge.
+
+    Args:
+        content: The new text content to check.
+        config: Correlate configuration (includes screener + vault ref).
+
+    Returns:
+        MembraneStageRecord with PASS, FLAG, or SKIP result.
+    """
+    if config is None or config.screener is None or config.vault is None:
+        return MembraneStageRecord(
+            stage=MembraneStage.CORRELATE,
+            result=MembraneResult.SKIP,
+            reasoning="No screener or vault reference, stage skipped",
+        )
+
+    start = time.monotonic()
+
+    # Search vault for related trusted content
+    try:
+        related = await config.vault.search(
+            content[:500],
+            tenant_id=config.tenant_id,
+            top_k=config.max_trusted_docs,
+            min_trust_tier="canonical",
+        )
+    except Exception:
+        return MembraneStageRecord(
+            stage=MembraneStage.CORRELATE,
+            result=MembraneResult.SKIP,
+            reasoning="Vault search failed during correlate",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    if not related:
+        return MembraneStageRecord(
+            stage=MembraneStage.CORRELATE,
+            result=MembraneResult.PASS,  # nosec B105
+            reasoning="No trusted content found for comparison",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    # Build existing content summary from trusted docs
+    existing_texts = [r.content[:config.max_content_chars] for r in related]
+    existing_summary = "\n---\n".join(existing_texts)
+
+    # Ask LLM to check for contradictions
+    prompt = _CONTRADICTION_PROMPT.format(
+        existing=existing_summary,
+        new_content=content[:config.max_content_chars],
+    )
+
+    try:
+        screening: ScreeningResult = await config.screener.screen(prompt)
+    except Exception as e:
+        return MembraneStageRecord(
+            stage=MembraneStage.CORRELATE,
+            result=MembraneResult.SKIP,
+            reasoning=f"LLM screener error: {type(e).__name__}",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    duration_ms = int((time.monotonic() - start) * 1000)
+
+    if screening.risk_score >= config.risk_threshold:
+        contradicted_names = [r.resource_name for r in related[:3]]
+        return MembraneStageRecord(
+            stage=MembraneStage.CORRELATE,
+            result=MembraneResult.FLAG,
+            risk_score=screening.risk_score,
+            reasoning=f"Contradicts trusted content: {', '.join(contradicted_names)}",
+            matched_patterns=screening.flags or ["contradiction"],
+            duration_ms=duration_ms,
+        )
+
+    return MembraneStageRecord(
+        stage=MembraneStage.CORRELATE,
+        result=MembraneResult.PASS,  # nosec B105
+        risk_score=screening.risk_score,
+        reasoning=screening.reasoning,
+        duration_ms=duration_ms,
+    )

src/qp_vault/membrane/pipeline.py

@@ -4,9 +4,11 @@
 """Membrane Pipeline: orchestrates multi-stage content screening.
 
 Runs content through the Membrane stages:
-1. INNATE_SCAN: pattern-based detection (regex, blocklists)
-2. ADAPTIVE_SCAN: LLM-based semantic screening (optional, requires LLMScreener)
-3. RELEASE: risk-proportionate gating decision
+1. REMEMBER: check against known attack pattern registry (fast pre-check)
+2. INNATE_SCAN: pattern-based detection (regex, blocklists)
+3. ADAPTIVE_SCAN: LLM-based semantic screening (optional)
+4. CORRELATE: cross-document contradiction detection (optional)
+5. RELEASE: risk-proportionate gating decision
 
 Stages are sequential. Each produces a MembraneStageRecord. The release
 gate aggregates all prior results into a final pass/quarantine/reject decision.
@@ -23,6 +25,8 @@
 
 if TYPE_CHECKING:
     from qp_vault.membrane.adaptive_scan import AdaptiveScanConfig
+    from qp_vault.membrane.correlate import CorrelateConfig
+    from qp_vault.membrane.remember import AttackRegistry
 
 
 class MembranePipeline:
@@ -34,7 +38,8 @@ class MembranePipeline:
     Args:
         innate_config: Configuration for the innate scan stage.
         adaptive_config: Configuration for the adaptive (LLM) scan stage.
-                        If None or screener is None, adaptive scan is skipped.
+        correlate_config: Configuration for cross-document correlation.
+        attack_registry: Attack pattern registry for the REMEMBER stage.
         enabled: Whether Membrane screening is active. Default True.
     """
 
@@ -43,10 +48,14 @@ def __init__(
         *,
         innate_config: InnateScanConfig | None = None,
         adaptive_config: AdaptiveScanConfig | None = None,
+        correlate_config: CorrelateConfig | None = None,
+        attack_registry: AttackRegistry | None = None,
         enabled: bool = True,
     ) -> None:
         self._innate_config = innate_config
         self._adaptive_config = adaptive_config
+        self._correlate_config = correlate_config
+        self._attack_registry = attack_registry
         self._enabled = enabled
 
     async def screen(self, content: str) -> MembranePipelineStatus:
@@ -73,16 +82,26 @@ async def screen(self, content: str) -> MembranePipelineStatus:
 
         stages: list[MembraneStageRecord] = []
 
-        # Stage 1: Innate scan (regex patterns)
+        # Stage 1: REMEMBER (fast pre-check against known attack patterns)
+        from qp_vault.membrane.remember import run_remember
+        remember_result = await run_remember(content, self._attack_registry)
+        stages.append(remember_result)
+
+        # Stage 2: Innate scan (regex patterns)
         innate_result = await run_innate_scan(content, self._innate_config)
         stages.append(innate_result)
 
-        # Stage 2: Adaptive scan (LLM-based, optional)
+        # Stage 3: Adaptive scan (LLM-based, optional)
         from qp_vault.membrane.adaptive_scan import run_adaptive_scan
         adaptive_result = await run_adaptive_scan(content, self._adaptive_config)
         stages.append(adaptive_result)
 
-        # Stage 3: Release gate (aggregates all prior results)
+        # Stage 4: Correlate (cross-document contradiction, optional)
+        from qp_vault.membrane.correlate import run_correlate
+        correlate_result = await run_correlate(content, self._correlate_config)
+        stages.append(correlate_result)
+
+        # Stage 5: Release gate (aggregates all prior results)
         release_result = await evaluate_release(stages)
         stages.append(release_result)
 
@@ -97,6 +116,13 @@ async def screen(self, content: str) -> MembranePipelineStatus:
         risk_scores = [s.risk_score for s in stages if s.result != MembraneResult.SKIP]
         aggregate_risk = max(risk_scores) if risk_scores else 0.0
 
+        # Learn from flagged content (feed REMEMBER registry)
+        if overall in (MembraneResult.FAIL, MembraneResult.FLAG) and self._attack_registry:
+            all_flags = []
+            for s in stages:
+                all_flags.extend(s.matched_patterns)
+            self._attack_registry.learn(content, all_flags, aggregate_risk)
+
         return MembranePipelineStatus(
             stages=stages,
             overall_result=overall,