feat: qp-vault v0.5.0 — governed knowledge store

Standalone Python package for governed knowledge storage.
Content-addressed (SHA3-256), trust-tiered, lifecycle-managed,
Merkle-verified, air-gap native.

24 source modules, 375 tests, 100/100 security score.
11 documentation guides, full CLI, FastAPI integration, plugin system.

Author: bradleygauthier

.github/workflows/python-ci.yaml

@@ -0,0 +1,45 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[sqlite,fastapi,integrity,cli,dev]"
+      - run: mypy src/qp_vault/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - run: pip install -e ".[sqlite,fastapi,integrity,cli,dev]"
+      - run: pytest tests/ -v --tb=short --cov=qp_vault --cov-report=term-missing

.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting & Type Checking
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Database
+*.db
+*.sqlite
+
+# Audit logs (generated at runtime)
+audit.jsonl

CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-04-06
+
+### Added
+- Plugin system with `@embedder`, `@parser`, `@policy` decorators
+- Air-gap plugin loading via `--plugins-dir` (drop .py files)
+- Entry point discovery for installed plugin packages
+- FastAPI routes via `create_vault_router()` (`[fastapi]` extra)
+- All REST endpoints: resources CRUD, search, verify, health, lifecycle, proof
+
+## [0.4.0] - 2026-04-06
+
+### Added
+- Memory layers: OPERATIONAL, STRATEGIC, COMPLIANCE with per-layer defaults
+- `vault.layer(MemoryLayer.OPERATIONAL)` returns scoped LayerView
+- COMPLIANCE layer audits every read operation
+- Integrity detection: staleness scoring, duplicate detection, orphan detection
+- `vault.health()` composite score (0-100): coherence, freshness, uniqueness, connectivity
+- `vault.status()` includes `layer_details` breakdown
+
+## [0.3.0] - 2026-04-06
+
+### Added
+- Knowledge lifecycle state machine: DRAFT, REVIEW, ACTIVE, SUPERSEDED, EXPIRED, ARCHIVED
+- `vault.transition()`, `vault.supersede()`, `vault.chain()`, `vault.expiring()`
+- Temporal validity: `valid_from`, `valid_until` on resources
+- `vault.export_proof()` for Merkle proof export (auditor-verifiable)
+- Supersession chain cycle protection (max_length=1000)
+
+## [0.2.0] - 2026-04-06
+
+### Added
+- `vault` CLI tool: init, add, search, inspect, status, verify
+- Capsule audit integration (`[capsule]` extra)
+- PostgreSQL + pgvector + pg_trgm storage backend (`[postgres]` extra)
+- WebVTT and SRT transcript parsers with speaker attribution
+- `Vault.from_postgres()` and `Vault.from_config()` factory methods
+
+### Security
+- FTS5 query sanitization (prevents injection via special characters)
+- Parameterized SQL queries in PostgreSQL backend (no string interpolation)
+
+## [0.1.0] - 2026-04-05
+
+### Added
+- Initial release
+- `Vault` (sync) and `AsyncVault` (async) main classes
+- 8 Pydantic domain models: Resource, Chunk, Collection, SearchResult, VaultEvent, VerificationResult, VaultVerificationResult, MerkleProof, HealthScore
+- 10 enumerations: TrustTier, DataClassification, ResourceType, ResourceStatus, Lifecycle, MemoryLayer, EventType
+- 5 Protocol interfaces: StorageBackend, EmbeddingProvider, AuditProvider, ParserProvider, PolicyProvider
+- SQLite storage backend with FTS5 full-text search (zero-config default)
+- Trust-weighted hybrid search: `relevance = (0.7 * vector + 0.3 * text) * trust_weight * freshness`
+- SHA3-256 content-addressed storage (CID per chunk, Merkle root per resource)
+- Semantic text chunker (token-aware, overlap, section detection)
+- Built-in text parser (30+ file extensions, zero deps)
+- JSON lines audit fallback (LogAuditor)
+- VaultConfig with TOML loading
+
+### Security
+- Input validation: enum values, resource names, tags, metadata
+- Path traversal protection (name sanitization, null byte stripping)
+- Max file size enforcement (configurable)
+- Content null byte stripping on ingest
+
+[unreleased]: https://github.com/quantumpipes/vault/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/quantumpipes/vault/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/quantumpipes/vault/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/quantumpipes/vault/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/quantumpipes/vault/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/quantumpipes/vault/releases/tag/v0.1.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at conduct@quantumpipes.io.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.0.

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to qp-vault
+
+Thank you for your interest in contributing to qp-vault. This document explains how to get involved.
+
+## Repository Structure
+
+```
+vault/
+├── src/qp_vault/       <- Source code
+│   ├── core/           <- Business logic (chunker, search, lifecycle)
+│   ├── storage/        <- Storage backends (SQLite, PostgreSQL)
+│   ├── processing/     <- File parsers (text, transcripts)
+│   ├── audit/          <- Audit providers (log, capsule)
+│   ├── integrity/      <- Health detection (staleness, duplicates)
+│   ├── plugins/        <- Plugin system (registry, decorators)
+│   ├── integrations/   <- Framework adapters (FastAPI)
+│   └── cli/            <- Command-line interface
+├── tests/              <- Test suite (375+ tests)
+├── docs/               <- Documentation
+└── examples/           <- Usage examples
+```
+
+## Getting Started
+
+```bash
+git clone https://github.com/quantumpipes/vault.git
+cd vault
+pip install -e ".[sqlite,cli,fastapi,integrity,dev]"
+make test
+```
+
+## Types of Contributions
+
+### Bug Fixes
+
+- Open an issue describing the bug
+- Include a minimal reproduction case
+- Submit a PR with a test that fails before the fix and passes after
+
+### New Storage Backends
+
+Implement the `StorageBackend` Protocol in `src/qp_vault/protocols.py`:
+
+```python
+class StorageBackend(Protocol):
+    async def initialize(self) -> None: ...
+    async def store_resource(self, resource: Resource) -> str: ...
+    async def get_resource(self, resource_id: str) -> Resource | None: ...
+    async def search(self, query: SearchQuery) -> list[SearchResult]: ...
+    # ... see protocols.py for full interface
+```
+
+### New Parsers
+
+Use the `@parser` decorator:
+
+```python
+from qp_vault.plugins import parser
+
+@parser("my-format")
+class MyParser:
+    supported_extensions = {".myf"}
+    async def parse(self, path: Path) -> ParseResult:
+        return ParseResult(text=extract(path))
+```
+
+### New Embedding Providers
+
+Use the `@embedder` decorator:
+
+```python
+from qp_vault.plugins import embedder
+
+@embedder("my-model")
+class MyEmbedder:
+    dimensions = 768
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        return my_model.encode(texts)
+```
+
+### Documentation
+
+Improvements to README, API docs, examples, and tutorials.
+
+## Code Standards
+
+- **Type hints** on all function signatures
+- **Docstrings** on all public classes and methods
+- **Tests** for all new functionality (target 100% coverage)
+- **No hardcoded values**: use VaultConfig for all configurable settings
+- **Async-first**: all I/O operations must be async
+- **No deprecated crypto**: SHA3-256 only, no MD5/SHA1/RSA
+
+## Running Tests
+
+```bash
+make test          # Run full test suite with coverage
+make lint          # Run ruff linter
+make typecheck     # Run mypy type checker
+make test-all      # All of the above
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Write tests alongside your code
+4. Ensure `make test-all` passes
+5. Submit a pull request
+
+## Security
+
+If you discover a security vulnerability, please report it privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0.