feat(helix-decisions): rename adr-search and implement HelixDB sync - #2
Merged
kevinmichaelchen merged 22 commits intoJan 17, 2026
Merged
Conversation
Expand scope from ADR-specific search to general decision graph infrastructure with semantic search. Key changes: - Rename crate: adr-search -> helix-decisions - Rename types: ADR -> Decision, ADRSearcher -> DecisionSearcher - Add uuid field for distributed safety across branches - Add content_hash and git_commit for immutability tracking - Update specs with ID scheme and immutability model - Update documentation with new vision
- Updated helix-decisions specs (design, tasks, requirements) with Phase 3 architecture - Added 10 critical HelixDB API corrections with working code examples - Added FR-9: Incremental Indexing requirement with 3-stage detection - Added Phase 3 performance targets (delta sync <50ms, search <100ms) - Updated shared/AGENTS.md with helix-storage deprecation path - Updated hbd/specs/design.md with HelixDB API patterns note
- helix-storage: Mark for removal, document why HelixDB replaces it - helix-config: Add HelixDB storage paths section - helix-embeddings: Add design and requirements specs with perf targets - helix-discovery: Add design and requirements specs - Update AGENTS.md with specs links for all crates
- Add ADR-004 establishing that shared crates don't depend on HelixDB - Each tool defines its own storage trait with HelixDB as implementation - Update shared/AGENTS.md to reflect architecture decision - Simplify helix-config specs (documents paths, no HelixDB dependency) - Update helix-embeddings specs (pure utility, returns Vec<f32>) This enables loose coupling, testability, and flexibility.
… stub Phase 1 of daemon implementation per specs/tasks.md: - Protocol structs: Request, Response, Command enum - Error types with codes matching spec - Client stub for Phase 2 IPC implementation - helixd binary placeholder
- hbd: rename hbd-d to helixd, add daemon integration section - helix-decisions: add IPC protocol, daemon lifecycle, rename/delete detection - helix-docs: add daemon integration section - Update tasks.md with daemon IPC tasks (Phase 3.4)
- Add Unix socket server with JSON line protocol - Add client with auto-start daemon and retry logic - Implement ping, status, shutdown commands - Stub enqueue_sync/wait_sync for Phase 3 - Add integration tests for client-server communication - 1MB message size limit for safety
- Add SyncQueue with per {repo_root, tool} queuing
- Implement request coalescing for duplicate enqueue_sync
- Add SyncJob state tracking (queued, running, done, error)
- Implement enqueue_sync and wait_sync command handlers
- Add broadcast-based state change notifications for wait_sync
- Integration tests for coalescing and status reporting
- Server tracks last activity timestamp - Auto-shutdown after idle_timeout_ms with no active queues - Add --idle-timeout CLI flag to helixd binary - Default: 5 minutes (configurable, 0 to disable)
- Add --sync flag to block until index is up to date - Wire CLI to enqueue_sync on invocation via daemon client - Show warning when daemon unavailable (graceful degradation) - Add tokio runtime for async daemon IPC
- Mark helix-daemon Phases 1-5 complete, add Phase 6 (Sync Worker) planned - Mark helix-decisions Phase 3.4 (Daemon Integration) complete - Update milestones table
- manifest.rs: ManifestEntry and IndexManifest for incremental indexing - Track file stats, content hash, vector ID for delta detection - JSON serialization, find by content hash (rename detection) - 11 unit tests - git_utils.rs: List decision files via git or directory walk - git ls-files with fallback to recursive directory walk - 4 unit tests
…ase 3.2) - Add helix_backend.rs with HelixDecisionBackend wrapping HelixGraphStorage - Replace JSON helix-storage backend with HelixDB in storage.rs - Fix get_chain to traverse incoming SUPERSEDES edges (toward current leaf) - Add node_id field to ManifestEntry for stable node IDs across re-indexes - Implement batch transaction semantics (nodes/vectors first, edges second) - Store normalized repo-relative paths in both manifest and node properties - Add pick_latest_superseding_node for deterministic chain traversal - Update DecisionSearcher::new() to require repo_root parameter - Remove helix-storage dependency from Cargo.toml
- Add path normalization and identity rules to design.md - Document batching and transaction semantics - Add edge update and vector update semantics - Rename decision_id to id in secondary index documentation - Add helix-daemon to shared AGENTS.md crate table - Update tasks.md with batch/edge requirements
- Split delta.rs to_add into to_add (new) and to_modify (changed) - Add unchanged_count to DeltaResult for complete stats - Return SyncStats from searcher.sync() with timing info - Print sync stats in CLI when changes occur
Add 11 integration test scenarios covering: - Initial indexing (10 decisions) - Delta detection (modify, add, delete) - Large repo performance (<100ms delta sync) - Chain traversal across supersedes edges - Related query with all edge types - Status filtering - Storage persistence Tests require embedding model and are marked #[ignore]. Run with: cargo test -p helix-decisions --test integration -- --ignored
…hip resolution Fix 4 critical issues in incremental sync: 1. Path normalization: normalize decision paths before comparing with manifest to prevent full re-indexing on every sync 2. Relationship resolution order: resolve relationships after node commit so same-batch references can be found 3. Edge removal logic: always remove outgoing edges before adding new ones to prevent stale edges when relationships are dropped 4. Rename detection: detect renames via content_hash + decision_id matching to preserve vector_id and avoid re-embedding
- tighten rename detection to content-hash + uuid and update tests - add strict check reporting for malformed frontmatter and missing uuid/title - expose loader report API with coverage for invalid files - update specs/docs to mark uuid required and document check
kevinmichaelchen
force-pushed
the
feat/rename-adr-search-to-helix-decisions
branch
from
January 16, 2026 23:58
49576de to
d189ca3
Compare
kevinmichaelchen
changed the title
- Import SecondaryIndex from helix_db::helix_engine::types - Use SecondaryIndex::Index() for secondary indices config - Access .0 on tuple to get Database from secondary_indices HashMap
kevinmichaelchen
deleted the
feat/rename-adr-search-to-helix-decisions
branch
January 17, 2026 00:34
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR renames
adr-searchtohelix-decisionsand implements the full HelixDB synchronization infrastructure.Core Changes
adr-searchtohelix-decisionsto expand scope from ADR-specific search to general decision graph infrastructureuuidfield for distributed safety across branches (via helix-id)content_hashandgit_commitfields for immutability trackinghelix-daemon (New Shared Crate)
HelixDB Integration (Phases 3.1-3.3)
Testing & Documentation
Test Plan
cargo test)