# Go filenames consistency design

## Context

The repository has inconsistent `.go` filename semantics in multiple areas (domain-oriented names, endpoint/history-oriented names, mixed singular/plural forms).
This slows code navigation because filenames do not consistently communicate data dimension or responsibility.

Goal: refactor `.go` filenames across the whole repository to a consistent naming model, and align declaration placement with filename responsibility, without changing runtime behavior.

## Scope

Applies to all `.go` files in the repository.

In scope:
- Rename `.go` files to consistent, responsibility-first names.
- Mechanical updates required by rename/move.
- Move declarations between files when needed so file responsibility is clear.

Out of scope:
- Any behavior or logic changes.
- Non-`.go` files.
- New feature work.

## Requirements

1. `.go` filename naming is consistent across the repository.
2. Filenames follow responsibility-first conventions:
   - data-dimension names where applicable (`spot_*`, `futures_*`, etc.)
   - pluralized collection-oriented files (`*_pairs.go`, `*_prices.go`)
   - avoid endpoint/history-oriented naming that obscures responsibility.
3. Declarations in each file match filename responsibility.
4. No public/package behavior change.
5. Resulting PR remains reviewable by grouping changes mechanically and keeping logic untouched.

## Design

### Naming model

Use a responsibility-first naming model for all `.go` files:
- A reader should infer the primary responsibility from filename alone.
- Prefer domain/data-dimension names over transport/implementation-history names.
- Use consistent singular/plural convention based on file content (entity vs collection).

### Refactor mechanics

1. Inventory `.go` files by package and classify naming inconsistencies.
2. Define target filename map package-by-package.
3. Rename files with git-aware rename operations.
4. Move declarations when file content does not match filename responsibility.
5. Keep signatures and bodies unchanged.
6. Apply only mechanical reference/import updates required by moves.

### Execution strategy for reviewability

- Use focused commits by package or subsystem.
- Keep each commit behavior-neutral.
- Separate any necessary declaration moves from broad rename waves when this improves diff readability.

## Error handling and behavior

No new error handling paths are introduced.
Existing control flow and error behavior remain unchanged.

## Testing and verification

1. Run project tests after each major package/subsystem batch.
2. Run full project test command before PR.
3. Confirm no functional diff beyond rename/move/mechanical updates.
4. Final check: each renamed file contains declarations aligned with its responsibility.

## Risks and mitigations

- Risk: accidental behavior change while moving declarations.
  - Mitigation: keep signatures/bodies unchanged and validate with tests per batch.
- Risk: review noise from repo-wide scope.
  - Mitigation: package-grouped commits, strict mechanical-only edits, and explicit PR summary.
- Risk: large PR becomes hard to review.
  - Mitigation: preserve commit structure and provide a clear rename map in PR description.

## Success criteria

- `.go` filenames are consistent and responsibility-first across the repo.
- Declarations in each file align with filename responsibility.
- Tests pass with no behavior regression.
- PR is understandable through structured, behavior-neutral commits.