Skip to content

arch: break 10 circular dependencies — session.ts involved in 5 of 10 #4489

@OneStepAt4time

Description

@OneStepAt4time

Architecture Audit — Circular Dependencies

Found by Argus code quality audit (May 29, 2026).

Circular Dependencies (source files, not tests)

  1. services/acp/session-service.tspause-intervention.ts
  2. services/acp/index.tsterminal-bridge.ts
  3. pipeline.tsservices/state/state-store.ts
  4. session.tsservices/session/permissions.ts
  5. services/state/state-store.tssession.tspersistence.ts (3-way)
  6. session.tssession-discovery.ts
  7. session.tssession-transcripts.ts
  8. channels/telegram/types.tstopic-persistence.ts

Worst Offender

session.ts (842 lines) — involved in 5 of 10 cycles. This is the same file flagged in #4227 (server.ts extraction). The cycles make it harder to test, refactor, and reason about session lifecycle.

Proposed Resolution

Extract interfaces/types into separate files to break import cycles:

  • session-types.ts — shared types currently imported from session.ts
  • session-interfaces.ts — service interfaces
  • Use dependency injection instead of direct imports where possible
  • Introduce event-driven communication to replace circular service references

Rules

  • One PR per cycle or group of related cycles
  • All tests must pass after each fix
  • No behavior changes — purely structural

Acceptance Criteria

  • npx madge --circular src/ reports 0 circular dependencies
  • All existing tests pass
  • No file over 500 lines grows significantly

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions