[RAG Projection] Add revision-aware derived indexing and rebuilds

[rica-v3]

Summary

• add deterministic bounded document chunking, revision-aware manifests, stable fragment/source/checkpoint identities, and truthful projection results
• implement incremental replace/delete orchestration plus an explicit destructive corpus rebuild through caller-owned embedder, writer, and resetter ports
• translate collaborator failures without claiming a completed checkpoint and preserve exact partial-progress receipts
• add 106 deterministic tests, clean-import/artifact checks, CI coverage for the fifth module, complete API/lifecycle/privacy documentation, and an executable projection guide

Boundary

This child implements projection only. The package remains standalone, synchronous, provider-neutral, runtime-dependency-free, and unaware of story-writing-agents, storage engines, vendors, credentials, or application lifecycle. Retrieval, fusion, and user/agent query composition remain Issue #4; the package root remains empty.

Applications authorize documents before constructing a complete ProjectionRequest, inject their own adapters through Borrowed, persist a successful manifest as application-owned state, use project_documents for compatible incremental updates, and reserve rebuild_projection for explicit destructive bootstrap or recovery.

Verification

• final modularity review: approved; source/index parity 5/5 and dependency graph acyclic
• full test suite: 106/106 passed on Python 3.14.2
• projection-focused documentation examples: executed successfully
• Ruff 0.16.4 lint and format: passed
• strict mypy 2.3.1 across source and tests: passed
• compile, wheel/sdist, rebuild, clean install, artifact inventory, and isolated import checks: passed
• no generated caches or unintended files in the commit

Refs #3

[Copilot]

Pull request overview

This PR introduces a new generic_rag.projection module that orchestrates deterministic, revision-aware document projection (chunking → embedding → replace/delete) and a destructive rebuild workflow (reset → replace-all), while keeping all resources caller-owned via Borrowed and maintaining the package’s provider-neutral boundary.

Changes:

• Add revision-aware projection orchestration APIs (project_documents, rebuild_projection) with content-free failure translation and truthful receipts/manifests.
• Extend contracts and ports to support bounded chunking/limits/state snapshots/results, plus a VectorIndexResetter port for corpus resets.
• Add extensive deterministic test coverage and update docs/module index/CI/artifact checks for the new module.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/generic_rag/projection.py	New projection orchestration module with incremental + rebuild workflows and deterministic planning/receipt behavior.
src/generic_rag/contracts.py	Add projection request/manifest/state/result value contracts and related validation.
src/generic_rag/ports.py	Add VectorIndexResetter protocol to support destructive corpus resets.
tests/test_projection.py	New end-to-end determinism/lifecycle/failure tests for projection workflows.
tests/test_projection_contracts.py	Add contract tests for new projection value types and state/result invariants.
tests/test_ports.py	Extend port export/protocol tests to cover VectorIndexResetter.
tests/test_package_boundaries.py	Include projection module in boundary/export/dependency checks and strengthen isolated import probing.
tests/support/clean_import_probe.py	Add --source-root support and verify imported modules originate from the expected source tree.
tests/support/verify_artifacts.py	Update expected artifact inventory to include generic_rag/projection.py.
README.md	Update README to document projection workflows and the new module boundary.
docs/projection.md	New projection lifecycle/behavior guide with state matrix and deterministic identity details.
docs/api.md	Extend API reference for projection values, ports, and workflows.
docs/lifecycle.md	Document projection call scope and reinforce Borrowed ownership semantics.
docs/security-and-privacy.md	Update privacy/security boundary to include projection adapter effects and limits.
PYTHON_MODULE_INDEX.md	Add the projection module to the module index with updated parity and responsibilities.
.github/workflows/ci.yml	Add generic_rag.projection to CI isolated-import checks.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.