Skip to content

feat: multi-root repository support with root isolation and filtering - #17

Open
guifelix wants to merge 10 commits into
mainfrom
t3code/43524093
Open

guifelix wants to merge 10 commits into
mainfrom
t3code/43524093

Conversation

@guifelix

Copy link
Copy Markdown
Owner

Summary

  • Add multi-root repository support allowing multiple knowledge bases in a single database
  • Introduce RootConfig with stable root_id identifiers (auto-generated from path hash if not provided)
  • Database schema changes: new roots table, root_id columns on documents, links, headings, scan_errors tables with composite unique constraints
  • Update all document store operations to scope by root_id (upsert, get, delete, list)
  • Update search index to include root_id as UNINDEXED field in FTS5 for filtering
  • Update graph store with source_root_id and target_root_id for cross-root link resolution
  • Add per-root statistics in IndexStats.roots with document/error/link/heading counts
  • MCP tools (search, query_metadata, browse, get_document) now accept optional root_id filter
  • CLI adds --root-id/--root-path paired flags for explicit root configuration
  • Configuration supports both simple paths (backward compatible) and structured RootConfig objects
  • Environment variable OKC_ROOTS supports JSON array for structured config
  • Migration v3 handles upgrade from single-root to multi-root schema (assigns root_id=1 to existing data)
  • Cross-root link resolution: same-root links resolve within root, cross-root links require explicit target_root_id

Testing

  • Migration test: existing single-root index upgrades to multi-root schema
  • Integration test: multi-root scan with colliding paths verifies both stored separately
  • Integration test: filtered queries per root return correct scoped results
  • Integration test: cross-root link resolution behavior with target_root_id
  • Integration test: root removal cleanup
  • Integration test: single-root backward compatibility (no root filter = all roots)
  • Updated unit tests in config, document store, search index, graph store
  • Updated integration tests in tests/integration_tests.rs
  • Updated MCP E2E tests in tests/mcp_e2e_tests.rs
  • Property tests updated for multi-root scenarios
  • Search evaluation tests updated for new params

guifelix added 10 commits August 9, 2026 19:32
- Add roots table with stable root_id
- Add root_id column to documents with composite unique constraint
- Add root_id to links table with source_root_id/target_root_id
- Add per-root statistics (RootStats, IndexStats.roots)
- Migration v3 handles existing single-root data
- Update DocumentRecord, FileRecord, LinkInfo with root_id
- Add root_id to search Index (SearchableDocument, SearchFilters)
- RootConfig with optional id + path
- OkcConfig.roots changed from Vec<PathBuf> to Vec<RootConfig>
- FileRecord includes root_id string
- Scanner discovers files per-root with root_id
- ChangeDetector operates on (root_id, path) composite key
- Config validation and env overrides updated
- DocumentRecord, SearchableDocument include root_id (i64)
- DocumentStore methods accept optional root_id parameter
- RepositoryIndex.get_or_create_root_id for string-to-int mapping
- store_parsed_document uses root_id for upsert/search/index
- Change processing handles root_id in deletions
- Metadata/query/document lookup filters by root_id
- SearchFilters includes root_id
- Stats delegated to document_store with per-root breakdown
- GraphStore links table adds source_root_id, target_root_id
- store_links resolves target_root_id from target document
- get_links/get_backlinks return target_root_id in LinkInfo
- traverse_graph tracks current_root_id and marks cross-root edges
- SearchIndex includes root_id in FTS, filters by root_id
- SearchIndex.stats computes per-root breakdown
- OkcService.search accepts optional root_id
- RootConfig exported from config module
- CLI --root-path/--root-id paired flags for explicit roots
- MCP ScanParams supports root_configs array
- MCP SearchParams includes root_id
- MCP GetDocumentParams passes through to service
- LinkInfoOutput/LinkInfo includes target_root_id
- Integration tests use RootConfig with id/path
- Property tests include root_id in FileRecord
- Search evaluation updated for multi-root config
- MCP E2E tests updated for new ScanParams
- ChangeDetector tests pass with root_id composite key
- docs/architecture.md: add Multi-Root Repositories section
- docs/configuration.md: document RootConfig, CLI flags, TOML format
- Config tests updated for RootConfig path field
- Validation checks use root.path
- MCP LinkInfoOutput adds target_root_id
- Watcher handles RootConfig for canonical roots
- OKC-00105 task marked Done
- get_links and get_backlinks SELECT target_root_id
- LinkInfo populated with target_root_id from database
- Use RootConfig struct with id/path for roots configuration
- Add target_root_id parameter (None) to search calls in benchmarks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant