Feat: Shared Repository Index Service

[marco0560]

#Shared Repository Index Service

Summary

Introduce an optional shared index service capable of hosting and serving Codira indexes for multiple repositories within a single persistent storage backend.

The service shall support both related and unrelated repositories and provide a centralized retrieval and indexing infrastructure.

Motivation

As documentation retrieval, embeddings, and semantic search capabilities expand, the cost of repeatedly loading, parsing, embedding, and indexing repositories increases.

A shared service can provide:

• centralized storage
• shared memory utilization
• shared vector indexes
• shared retrieval infrastructure
• reduced indexing duplication
• faster startup times
• centralized administration

This deployment model is particularly attractive for:

• servers with large memory capacity
• developer teams
• self-hosted environments
• AI-assisted development platforms
• repository collections

The shared service is intended as an optional deployment topology.

The canonical Codira workflow remains local deterministic batch indexing.

Design Principles

• Local indexing remains canonical.
• The service is optional.
• The service must not change analyzer behavior.
• The service must not change repository facts.
• The service must not introduce hidden state into analysis.
• Repository provenance must remain explicit.
• Deterministic outputs remain mandatory.

Scope

Provide an optional long-running service capable of:

• hosting multiple repository indexes
• hosting multiple embedding collections
• serving retrieval requests
• supporting incremental updates
• supporting daemon-mode indexing
• supporting repository registration and removal

Repository Model

The service shall support:

Related Repository Collections

Examples:

codira
codira-analyzer-python
codira-analyzer-go
codira-analyzer-rust

Unrelated Repository Collections

Examples:

codira
llvm-project
cpython
postgres

The service shall not assume repositories are related.

Deliverables

• Shared repository catalog
• Repository registration mechanism
• Repository isolation model
• Shared retrieval interface
• Shared embedding storage
• Shared vector index support
• Administrative tooling
• Service documentation

Acceptance Criteria

• Multiple repositories can coexist within a single service.
• Repository provenance remains preserved.
• Retrieval can be constrained to specific repositories.
• Retrieval can span multiple repositories.
• Deterministic indexing behavior remains unchanged.
• Local batch mode and service mode produce equivalent repository facts.

Non-Goals

• Mandatory client/server architecture
• Distributed indexing
• Distributed consensus
• Multi-node clustering
• Automatic repository discovery
• Authentication and authorization systems

Dependencies

• feat(query): add a documentation retrieval channel to ctx #3 Documentation retrieval channel
• feat(embeddings): Add embeddings calibration script (hardware-aware auto-tuning) #28 Embeddings calibration
• Feature: Similarity-index plugins and first-party FAISS backend #20 Optional vector database backend
• Feature: Daemon Mode for Incremental File Watching and Automatic Reindexing #22 Daemon mode

Architectural Constraints

• Deterministic indexing
• Immutable validated facts
• Explicit provenance
• No hidden analyzer state
• Local mode remains fully supported

[marco0560]

Planning update: #51 remains blocked and is scheduled in v2.0 only after #15, #20, #22, and #68. Its gate requires stable MCP, verified clients, benchmark corpus, and demonstrated multi-repository/local-index adoption. A failed gate converts it to deferred with the explicit adoption criteria.

[marco0560]

Continuation of #58: deferred MCP service scope

This issue owns the work intentionally deferred from #58 after the local read-only stdio MCP milestone.

Required MCP continuation

• Register multiple repositories under stable repository identifiers; MCP requests must select repositories by identifier, never arbitrary filesystem path.
• Provide repository metadata, index status, freshness, and provenance per registered repository.
• Route MCP retrieval to one selected repository and, where explicitly requested, across registered repositories while preserving deterministic ordering and source provenance.
• Reuse warm indexes through the optional shared service without changing the authoritative local batch-index workflow.
• Integrate daemon-backed incremental freshness only after Feature: Daemon Mode for Incremental File Watching and Automatic Reindexing #22 supplies the optional watcher, state visibility, deterministic isolation, and failure model.
• Keep local stdio MCP fully usable without the service or daemon.

Deferred semantic evaluation

Evaluate optional service exposure for documentation retrieval, embeddings, index health, embedding inventory, and deferred-embedding status through their owning subsystem issues. These are not required for the completed local-MCP scope.

Blocker

#22 is the explicit blocker for daemon-backed freshness and warm-index lifecycle. #51 must preserve its existing backend, vector, and deterministic-provenance constraints while implementing this continuation.

Closes the deferred Phase 2 and Phase 4 scope from #58; the #58 local read-only MCP contract, direct tools, safety controls, compact map, and client setup remain independent of this service.