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

[rica-v3]

Parent and project

• Parent: [RAG Runtime] Deliver a dependency-free generic RAG package #1
• Project: https://github.com/orgs/Kims-DeveloperGroup/projects/1
• Milestone: Generic RAG v1
• Iteration: Iteration 09
• Wave: 11
• Blocked by: [RAG API] Bootstrap the package and define generic contracts #2
• Owner: @rica-v3

Objective

Implement deterministic revision-aware document projection through injected embedding and vector-index ports so derived state can be checkpointed, rebuilt, replaced, and deleted without owning authoritative application data.

In scope

• Deterministic bounded chunking of immutable generic documents.
• Stable fragment identities derived from corpus/document/revision and chunk position.
• Projection receipts and checkpoints tied to schema and embedding identity.
• Create, replace, delete, stale-revision, wrong-model, partial-failure, and full rebuild behavior.
• Idempotent replay and explicit collaborator-failure translation.
• No rollback requirement for an external authoritative store; the caller decides when to project.
• Bounded text and batch sizes supplied through explicit policy values.

Out of scope

Story events/citations, filesystem/SQLite access, provider implementations, background workers, implicit retry, credentials, semantic ranking, or hybrid fusion.

Acceptance criteria

• Equal input and collaborators produce equal chunks, calls, and receipts.
• Revision replacement and deletion cannot leave current generic documents ambiguously addressable.
• Missing, stale, corrupt, wrong-schema, or wrong-embedding state is detectable and rebuildable.
• Partial collaborator failure returns an explicit receipt/failure without claiming a completed checkpoint.
• Runtime imports perform no external I/O and borrowed resources are never implicitly closed.
• Mandatory tests run with deterministic fakes and no network.

Verification

Chunk boundary/property cases, revision and deletion matrices, checkpoint/rebuild/idempotency tests, injected failure tests, clean imports, compileall, and module-index review.

Dependencies and risks

Blocked by #2 public contracts. Risks are unstable chunk identity, partial state claims, accidental raw-score semantics, and hidden lifecycle ownership.

Gates

github_planning_gate = pending until hierarchy, native dependency, Project metadata, milestone, and branch are verified. modularity_gate = required; implementation must preserve the accepted package boundary.

[rica-v3]

github_planning_gate = passed. Parent #1, closed prerequisite #2, native dependency removal, Project #1 membership, Iteration 09, Size L, Ready status, milestone Generic RAG v1, labels, assignee rica-v3, and Development-linked branch issue-3-projection at verified parent commit 688a10e07441fdfaada636211d841900918deedc are verified. modularity_gate = required and remains pending read-only boundary analysis; no writer has started.

[rica-v3]

modularity_gate = passed

Accepted Python boundary brief (policy: .codex/agents/modularity_maintainer/PYTHON_MODULARITY_POLICY.md; current PYTHON_MODULE_INDEX.md parity 4/4):

• Add generic_rag.projection as the sole workflow module; root __all__ = () and generic_rag.errors remain unchanged.
• Add immutable projection request/limits/chunking/manifest/state/result values to generic_rag.contracts; add only independent VectorIndexResetter.reset_corpus() to generic_rag.ports, preserving VectorIndexWriter.
• project_documents consumes a complete canonical target plus caller-supplied state; compatible identical state is UNCHANGED, stale state is incrementally reconciled, and missing/corrupt/schema/embedding-incompatible state fails before effects.
• rebuild_projection uses the separately injected resetter once, then rebuilds the complete target; persistence and collaborator lifecycle remain caller-owned.
• Use deterministic length-prefixed UTF-8/SHA-256 source, fragment, and checkpoint identifiers; opaque revisions are compared only for equality; chunks use explicit positive max/strictly smaller overlap and embedding calls use a separate item-count batch bound.
• Canonically order by document ID, replace changed revisions without delete-first, delete omitted manifest keys, validate all embedder output, never retry implicitly, and return a checkpoint only after complete success.
• Translate collaborator failures through projection-owned ProjectionOperationError with stage, affected key, and truthful failed/partial receipt; preserve provider exception only as the chained cause.
• No storage, adapters, state reader, filesystem, vendor, story, auth, ranking, packaging, dependency, or version changes.
• Post-implementation index delta is one generic_rag.projection entry plus updated contract/port exports (expected 5/5).

Production ownership is constrained to src/generic_rag/contracts.py, src/generic_rag/ports.py, and new src/generic_rag/projection.py. The writer will start only after the currently active production slice completes.