refactor: verify and reduce harmful dependency cycles before plugin-host split #32

New issue

Open

opened 2026-07-20 22:38:58 +02:00 by buildagent · 1 comment

buildagent commented

2026-07-20 22:38:58 +02:00

Member

From the 2026-07-20 brainstorm architecture lens (_prdoc/records/brainstorm-2026-07-20-index-data-catalog.md) — real cycles in the current codebase, verified over symbol_edges. Not bugs (declined for the v0.5.19 fix round), but each is a pair of files that cannot be edited independently:

crates/cli/src/main.rs ↔ crates/cli/src/link.rs
crates/cli/src/main.rs ↔ crates/cli/src/doctor.rs
crates/indexer/src/db.rs ↔ crates/indexer/src/migrations.rs
crates/daemon/src/access.rs ↔ crates/daemon/src/local_index.rs

(A fifth, in the ruby test fixtures user.rb ↔ post.rb, is intentional fixture content.)

Suggested direction: extract the shared surface each pair trades (e.g. cli main's arg structs vs subcommand entry points; db.rs's open/pragma helpers vs migrations' run) so the edges point one way. Once #28 (detect_cycles) ships, its conformance mode can enforce cycle-freedom in CI.

Runtime-plugin architecture relevance

#75 introduces new boundaries that make cycle ownership more consequential: package/ABI types (#76), resolver provenance (#77), generation state (#78), the plugin supervisor/host (#79), and conformance/reporting (#80).

Before refactoring, re-measure SCCs against the current tree; import capture is incomplete (#31), so absence is not proof. Classify each cycle as harmful ownership coupling or intentional facade/test coupling.

New constraint: the plugin-host crate must depend only on the ABI/runtime substrate, never daemon/indexer database/query crates. The parent supervisor may depend on #76 protocol types, but guest/package types must not import core resolver/schema implementation.

Acceptance adds a crate/file layering rule for the plugin architecture and a baseline proving the change removes a production SCC without creating another. Intentional fixture cycles remain explicitly labelled.

From the 2026-07-20 brainstorm architecture lens (`_prdoc/records/brainstorm-2026-07-20-index-data-catalog.md`) — real cycles in the current codebase, verified over `symbol_edges`. Not bugs (declined for the v0.5.19 fix round), but each is a pair of files that cannot be edited independently: 1. `crates/cli/src/main.rs ↔ crates/cli/src/link.rs` 2. `crates/cli/src/main.rs ↔ crates/cli/src/doctor.rs` 3. `crates/indexer/src/db.rs ↔ crates/indexer/src/migrations.rs` 4. `crates/daemon/src/access.rs ↔ crates/daemon/src/local_index.rs` (A fifth, in the ruby test fixtures `user.rb ↔ post.rb`, is intentional fixture content.) Suggested direction: extract the shared surface each pair trades (e.g. cli main's arg structs vs subcommand entry points; db.rs's open/pragma helpers vs migrations' run) so the edges point one way. Once #28 (detect_cycles) ships, its conformance mode can enforce cycle-freedom in CI. ## Runtime-plugin architecture relevance #75 introduces new boundaries that make cycle ownership more consequential: package/ABI types (#76), resolver provenance (#77), generation state (#78), the plugin supervisor/host (#79), and conformance/reporting (#80). Before refactoring, re-measure SCCs against the current tree; import capture is incomplete (#31), so absence is not proof. Classify each cycle as harmful ownership coupling or intentional facade/test coupling. New constraint: the plugin-host crate must depend only on the ABI/runtime substrate, never daemon/indexer database/query crates. The parent supervisor may depend on #76 protocol types, but guest/package types must not import core resolver/schema implementation. Acceptance adds a crate/file layering rule for the plugin architecture and a baseline proving the change removes a production SCC without creating another. Intentional fixture cycles remain explicitly labelled.

buildagent commented

2026-07-21 14:26:51 +02:00

Author

Member

Triage: P3 internal architecture backlog

Keep this as tech debt, separate from the agent-product roadmap. Do not refactor solely to satisfy a cycle metric: verify each direction represents harmful ownership coupling and that extraction produces a simpler one-way boundary.

After #28 exists, use it to record the baseline and prove each change removes a production SCC without creating another. The intentional Ruby fixture cycle should remain explicitly excluded/labeled.

### Triage: P3 internal architecture backlog Keep this as tech debt, separate from the agent-product roadmap. Do not refactor solely to satisfy a cycle metric: verify each direction represents harmful ownership coupling and that extraction produces a simpler one-way boundary. After #28 exists, use it to record the baseline and prove each change removes a production SCC without creating another. The intentional Ruby fixture cycle should remain explicitly excluded/labeled.

buildagent added the

tech-debt

label

2026-07-21 14:27:27 +02:00

dhoyer referenced this issue from a commit

2026-08-06 16:19:34 +02:00

ci: run the native-Windows gate on master (was stranded on a stale branch)

buildagent changed title from ~~refactor: resolve 4 file-level dependency 2-cycles (architecture backlog)~~ to refactor: verify and reduce harmful dependency cycles before plugin-host split

2026-08-26 13:41:58 +02:00

buildagent added the

Priority

Low

label

2026-08-26 13:42:32 +02:00

buildagent added a new dependency

2026-08-26 13:44:24 +02:00

#28 feat: generation-aware SCC and configured layering analysis