refactor(core): GraphRepository — complete RULE-ARCH-003 repository abstraction

[dgtalbug]

Summary

Completes RULE-ARCH-003 (repository pattern). The backend-stabilization PR confined the DuckDB driver to one adapter; this puts the storage + query operations behind a GraphRepository interface — the connection is held by the adapter and never appears in a method signature, so no domain code touches a connection. A narrow ForeignGraphReader covers the extension's read-only foreign-workspace access. DuckTreeIndexer now depends on the interface instead of a DatabaseHandle.

Behavior-preserving throughout; the public contract is unchanged. Full suite green at every phase (core 274 / exporters 161 / extension 640).

Linked spec / issue

• Spec: openspec/changes/graph-repository/ (OpenSpec change; openspec/ is gitignored)
• Closes: GraphRepository: complete RULE-ARCH-003 (repository abstraction over storage/query) #164

Slice classification

• refactor — internal architecture change, no behavior delta (one additive test fake)

Affected surfaces

• packages/core (interfaces, adapter, indexer, fake)
• packages/extension (foreign-reader call sites + one test mock)

Phases (commit-by-commit)

1. db52387 interfaces — GraphRepository + ForeignGraphReader, no GraphDbConnection in any signature
2. e5208f0 adapter — DuckDbGraphRepository delegating to the existing storage/query fns; delegation tests vs real in-memory DuckDB
3. d080618 indexer swap — DuckTreeIndexer holds this.repo; the 15 requireDatabaseHandle()/database.connection sites become this.repo.X(); index.ts is now connection-free
4. 594839a foreign reads + connection-free public API — extension's two foreign-read sites use DuckDbForeignGraphReader; core's public barrel drops the connection-first re-exports
5. c7d95ff test fake — FakeGraphRepository proves substitutability through the interface

Scope decisions (where the plan met reality)

• Connection-first fns are internalized, not deleted. After the indexer swap they're called only by the adapter and by core's own tests (via relative imports). Inlining ~17 SQL bodies into the adapter would be large churn with no behavioral gain, so they remain internal implementation the adapter delegates to. What was removed is their presence in core's public API — no GraphDbConnection-taking signature is exported anymore.
• No ~30-site test rewrite was needed. Core tests import the bare fns by relative path, not the dropped barrel exports, so they were unaffected. Only the one extension foreign-reader mock changed.
• The fake proves the contract, not a constructor seam. FakeGraphRepository is consumed through the GraphRepository type. Wiring it into the indexer via constructor injection would change the public createIndexer contract, so that's left as a future enhancement.

Test plan

• pnpm check green across all packages (forced/uncached): core 274, exporters 161, extension 640
• No GraphDbConnection appears in any GraphRepository method signature
• index.ts has zero database.connection references — the DIP boundary is real
• Public Indexer contract unchanged — extension suite passes with no consumer edits beyond the two foreign-reader sites
• Adapter delegation verified against a real in-memory DuckDB; FakeGraphRepository proves substitutability
• spec-tag guard + pnpm dedupe --check clean

Checklist

• PR title follows Conventional Commits
• Closes: references the tracking issue
• format / lint / typecheck / test pass
• No new any without justification
• No native deps added to packages/core
• Public contract preserved — additive/behavior-preserving; consumers + full suite unaffected

Notes for reviewers

• The headline: ARCH-003 is now complete — the connection is owned by the adapter and never escapes into domain code or the public API. A different store (or the in-memory fake) implements the same interface.
• The ForeignGraphReader split is deliberate (design D2): foreign reads open arbitrary DBs by path and are driven by the extension, so they don't belong on the connection-owning repository.
• Lens selectors are intentionally NOT repository methods — they operate on the in-memory graphology graph, not the DB.

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5ca6d4b0-ee31-4f8a-bee5-22130f5752ac

📥 Commits

Reviewing files that changed from the base of the PR and between a898290 and c7d95ff.

📒 Files selected for processing (10)

• packages/core/src/index.ts
• packages/core/src/storage/adapters/duckdbGraphRepository.test.ts
• packages/core/src/storage/adapters/duckdbGraphRepository.ts
• packages/core/src/storage/fakeGraphRepository.test.ts
• packages/core/src/storage/fakeGraphRepository.ts
• packages/core/src/storage/graphRepository.ts
• packages/core/src/storage/index.ts
• packages/extension/src/cache/workspaceRegistry.test.ts
• packages/extension/src/cache/workspaceRegistry.ts
• packages/extension/src/extension.ts

---

📝 Walkthrough

Summary

User-visible or reviewer-relevant changes:

• GraphRepository abstraction introduced — Hides database connection behind a new GraphRepository interface. DuckDbGraphRepository delegates to existing storage/query functions; DuckTreeIndexer now depends on the interface instead of DatabaseHandle, eliminating ~15 direct connection sites from indexer code.
• Separated foreign-workspace reads — New ForeignGraphReader interface (implemented by DuckDbForeignGraphReader) provides read-only, path-based access to external workspace databases. Extension code now instantiates this reader instead of calling removed barrel exports.
• Public API narrowed — Removed connection-first and repository-level exports from storage barrel (openDatabase, readRows, runInTransaction, applyMigrations, replaceFileGraph, initializeSchema). Only DatabaseHandle, migration types, the new interfaces, and DuckDB adapter classes remain public.
• No behavior changes — Adapter delegates transparently to existing functions; all tests pass (core 274, exporters 161, extension 640). Indexer and graph model contracts preserved.

Risks:

• Coverage gaps — Patch coverage at 77.35%; fakeGraphRepository.ts at 65.71%, duckdbGraphRepository.ts at 84.61%, and index.ts at 82.22% have uncovered branches.
• API breaking change — Removal of public query/storage exports (getPresentEdgeKinds, getCoverageReport, neighborhood, openDatabase, etc.) breaks any external direct usage. Extension tests required updating to use DuckDbForeignGraphReader instances.

Deferred or not validated:

• Test fake (FakeGraphRepository) added to validate interface contract but indexer construction seam left for future work.
• No mass rewrite of existing tests; tests continue to use real DuckDB instances via adapter.

Package boundaries & schema:

• No schema changes. Storage responsibility shifted from domain code to adapter; domain signatures no longer carry DatabaseHandle or connection objects.
• Extension boundary clarified: reads now routed through ForeignGraphReader rather than removed barrel helpers.

Walkthrough

This PR completes RULE-ARCH-003 by abstracting storage and query operations behind a GraphRepository interface. A new DuckDbGraphRepository adapter wraps the database handle and delegates operations to existing functions. The core indexer is refactored to use the repository instead of raw database handles across 15+ call sites. An in-memory FakeGraphRepository provides a test double. The extension migrates to use DuckDbForeignGraphReader for read-only cross-workspace access.

Changes

Graph Repository Abstraction

Layer / File(s)	Summary
Repository Interface Contracts and Storage Barrel packages/core/src/storage/graphRepository.ts, packages/core/src/storage/index.ts	GraphRepository and ForeignGraphReader interfaces define the contract for storage/query operations and cross-workspace read access. Storage barrel removes low-level connection-first function exports and exposes only repository types, adapters, and schema constants.
DuckDB Repository Adapter Implementation packages/core/src/storage/adapters/duckdbGraphRepository.ts	DuckDbGraphRepository wraps a DatabaseHandle and implements GraphRepository by delegating all operations to existing connection-first functions. DuckDbForeignGraphReader provides stateless foreign database read access.
DuckDB Adapter Integration Tests packages/core/src/storage/adapters/duckdbGraphRepository.test.ts	Verifies DuckDbGraphRepository against real DuckDB: file graph round-trips, symbol retrieval, workspace subgraph queries, clear operations with deletion summaries, and lifecycle disposal.
Fake Repository Implementation and Conformance Tests packages/core/src/storage/fakeGraphRepository.ts, packages/core/src/storage/fakeGraphRepository.test.ts	FakeGraphRepository provides in-memory storage for unit testing, storing files and symbols by relative path. Tests verify substitutability via schema initialization, file round-trips, cache lifecycle, and clear operations.
Core Indexer Migrated to Repository Delegation packages/core/src/index.ts	Refactored DuckTreeIndexer to hold a DuckDbGraphRepository instead of DatabaseHandle. All indexing, query, and lifecycle operations—initialization, file graph replacement, symbol retrieval, framework/edge resolution, workspace queries, cache validation, coverage/neighborhood reporting, and disposal—now delegate through repository methods. Exports simplified to surface only repository types and adapters.
Extension and Registry Updated for ForeignGraphReader packages/extension/src/cache/workspaceRegistry.ts, packages/extension/src/cache/workspaceRegistry.test.ts, packages/extension/src/extension.ts	Workspace registry and extension instantiate DuckDbForeignGraphReader to call its readWorkspaceIndexSummary and readWorkspaceGraph instance methods, replacing imported standalone helpers.

---

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

---

Possibly related PRs

• dgtalbug/dextree#118: Modifies replaceFileGraph invocation in the indexing flow to pass per-symbol classifications, intersecting with the layer that routes file graph replacement through DuckDbGraphRepository.
• dgtalbug/dextree#163: Updates extension workspace switching and registry to use DuckDbForeignGraphReader, the same new public API boundary that this PR exports and establishes.
• dgtalbug/dextree#137: Adds Logger and IndexerFactoryOptions plumbing through indexer initialization, overlapping with the new repository-based initialization flow in this PR.

---

Suggested labels

area:core, type:feat

---

Poem

🏗️ Abstraction rises, connection-free,
One repository to query thee,
Adapters hide the handle's grasp,
Fakes make testing less of a clasp,
Fifteen call sites now delegate with grace.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 77.35849% with 24 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/core/src/storage/fakeGraphRepository.ts	65.71%	8 Missing and 4 partials ⚠️
packages/core/src/index.ts	82.22%	5 Missing and 3 partials ⚠️
...core/src/storage/adapters/duckdbGraphRepository.ts	84.61%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!