[RAG API] Bootstrap the package and define generic contracts

[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: 10
• Approved base: root integration branch created from main at 33ef381
• Owner: @rica-v3

Objective

Bootstrap the independently buildable generic-rag distribution and define the minimal immutable public values and injected protocols needed by projection and retrieval.

In scope

• Apply the approved repository-engineering bootstrap and add the project-owned README, Python package manifest, module index, source/test/docs layout, and CI.
• Publish immutable validated values for opaque corpus/document/revision/query/hit/result and projection receipts.
• Publish narrow injected protocols for embedding, vector indexing, lexical retrieval, clocks where needed, and explicit resource borrowing.
• Use tuple-based string attributes rather than application objects or unconstrained Any.
• Define generic typed exceptions and import-time side-effect guarantees.
• Provide deterministic test fakes owned by tests, never production.
• Document compatibility, lifecycle, privacy-neutral boundaries, and semantic versioning expectations.

Out of scope

Projection/chunking algorithms, semantic/hybrid retrieval, vendor adapters, network behavior, credentials, application-specific types, dynamic imports, or story integration.

Acceptance criteria

• python -m build produces a clean installable wheel and sdist.
• generic_rag imports in a clean Python 3.11+ process with no third-party dependency or I/O.
• Public values reject invalid types, unsafe empty identities, and inconsistent bounds deterministically.
• Protocols make resource ownership and synchronous behavior explicit.
• A guard proves production code cannot import story_writing_agents.
• Public exports, docs, tests, and PYTHON_MODULE_INDEX.md agree.

Verification

Focused public-contract tests, clean-install/import test, build metadata validation, dependency/import scan, compileall, and diff review.

Dependencies and risks

No implementation prerequisite. This is the first executable leaf. Public contract drift would propagate to every consumer, so additions remain minimal and intentional.

Gates

github_planning_gate = pending until Project metadata and a Development-linked task branch are verified. modularity_gate = required; the modularity maintainer owns this package bootstrap and index.

[rica-v3]

github_planning_gate = blocked at the required bootstrap approval checkpoint. The issue graph, native relationships/dependencies, Generic RAG v1 milestone, Project membership, Iteration 09, Priority Low, leaf Size L, and clean approved base 33ef381 are verified. Unblock condition: the maintainer replies exactly “Approve the generic-rag bootstrap dry run.” Owner/next action: @rica-v3 approval, then remove blocked, return this leaf to Ready, create the Development-linked parent/leaf branches, and apply only the reported dry run. No tracked generic-rag file has been changed.

[rica-v3]

Approval received on 2026-08-25 for the exact repository-engineering dry run.

Gate evidence:

• github_planning_gate = passed: root [RAG Runtime] Deliver a dependency-free generic RAG package #1 and leaves [RAG API] Bootstrap the package and define generic contracts #2-[RAG Retrieval] Implement semantic and deterministic hybrid retrieval #4, native hierarchy/dependencies, Project [RAG Runtime] Deliver a dependency-free generic RAG package #1 membership, Iteration 09, Low organization Priority, leaf Sizes, Generic RAG v1 milestone, and approved base 33ef3814aee3bfc4a1a13fc2cdba512c74a316f5 were freshly verified.
• [RAG API] Bootstrap the package and define generic contracts #2 is the first unblocked leaf and is assigned to @rica-v3.
• Root Development branch: issue-1-generic-rag at the approved base.
• Leaf Development branch: issue-2-bootstrap-contracts at the root branch head.
• modularity_gate = required; the modularity maintainer owns package structure and PYTHON_MODULE_INDEX.md.

The approved core+python+github bootstrap projection was checksum-verified and held as an uncommitted diff while the missing Development traceability was repaired. No production package implementation has started.

[rica-v3]

Repository-engineering bootstrap apply completed and pushed in dfef97175013a767ca77555311efc3e8b336e151.

• Action/phase: init / apply
• Approval evidence: explicit approval in the later 2026-08-25 user turn for the immediately preceding dry-run report
• Plugin: repository-engineering 0.2.0
• Selector: repository-engineering@repository-engineering-kit
• Profiles: core, github, python
• Source: https://github.com/Kims-DeveloperGroup/AI-engineering-kit.git at immutable ref 2cab4e6a2d0d7f693c4a65a9021622410bf23966
• Marketplace manifest: .agents/plugins/marketplace.json, SHA-256 6e0f44e7cf797eff7cdc73c06b25271f33c49915a1bc37dc0c554df06537b7db
• Distribution manifest: skills/repository-engineering-bootstrap/assets/distribution-manifest.json, SHA-256 71696a46bf80bfd733e52cbc9baca62eabfe584df4dc0c61bbf3ac5806b9813c
• Result: 12 selected projections created and verified; deterministic lock written last; 10 contract resources verified; no conflicts, drift, unsafe paths, or symlinks
• Project-owned files: existing README.md preserved byte-for-byte; PYTHON_MODULE_INDEX.md intentionally not projected and remains required for the package implementation pass
• Post-apply checks: every managed target and exact AGENTS marker block matched the lock checksum; lock provenance matched the approved report; diff check passed.