[enhancement] Define retrieval contracts and deliver deterministic data ingestion

[aotenjou]

Phase 1 of Parent epic: #863

Summary

Define the stable contracts and reproducible data foundation required by the GraphRAG engine.
This phase delivers the first executable vertical slice: a deterministic in-memory fixture and a versioned ingestion pipeline that can build a ready graph and its required indexes from HotpotQA and 2WikiMultiHopQA.

The retrieval API contract is frozen in this phase so that later retrieval and service work can replace implementations without changing the interface consumed by upper-layer applications.

Motivation

The current geaflow-ai memory search prototype does not define a common evidence schema, a
versioned data/index identity, or a repeatable ingestion process. Without these contracts, results cannot be compared across retrieval modes and a partially built graph could be exposed to clients.

Scope

• Define stable identities and schemas for source documents, text chunks, entities, vertices, edges, indexes, graph versions, and retrieval evidence.
• Define the versioned RetrievalRequest/RetrievalResponse protocol, error codes, budget fields, and trace fields used by the later REST adapter.
• Define a dataset manifest containing the release, split, download URL, SHA-256, preprocessing version, schema version, vector source, and random seed.
• Implement deterministic ingestion for the official HotpotQA distractor data and 2WikiMultiHopQA development/test data: download or local-cache loading, checksum verification, normalization, cleaning, chunking, entity extraction, stable ID generation, and graph writes.
• Persist versioned metadata and the import state machine (IMPORTING, INDEXING, READY, FAILED). Only a graph with all required indexes in READY may be published to retrieval.
• Build the initial Lucene/BM25 index and a replaceable offline vector index from the same versioned chunks. The vector producer must remain independent of the Java retrieval API.
• Provide a small, fixed in-memory graph fixture for unit and HTTP tests.

Suggested implementation locations

These are proposed locations; follow existing GeaFlow package and module conventions when creating
the actual files.

• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/model/ - request, response, evidence,
  version, and manifest models.
• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/config/ - ingestion and retrieval
  configuration properties.
• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/ingest/ - parser, normalizer, chunker,
  entity mapper, graph writer, and import state machine.
• geaflow-ai/src/main/java/org/apache/geaflow/ai/retrieval/index/ - versioned BM25/vector index
  builders and readiness metadata.
• geaflow-ai/src/test/java/org/apache/geaflow/ai/retrieval/ - deterministic fixtures and contract
  tests.
• tools/graphrag/ (or the repository-approved benchmark module) - dataset manifests and offline
  ingestion commands. Do not commit raw datasets or incompatible model artifacts.

Testing requirements

• Unit tests for normalization, chunk boundaries, stable IDs, manifest/checksum validation, and
  state transitions.
• Property or golden-file tests proving deterministic output and idempotent re-runs.
• Integration tests that import a small fixture, build both index types, and verify readiness gating.
• Contract tests that deserialize representative request, success, empty-result, and typed-error
  JSON without depending on natural-language string formatting.

Dependencies and follow-up

• No prerequisite project issue beyond Epic [Feature] Structure-Aware GraphRAG Retrieval Engine for GeaFlow #863.
• Later phases must preserve the request/response and versioning contracts established here.