refactor: move CVDRole to vultron/enums/; config.py → config/ sub-package (#1342)

[sei-ahouseholder]

• Closes refactor: move CVDRole to vultron/enums/ and vultron/config.py to vultron/config/ sub-package #1342

Summary

Moves CVDRole (and helpers) to a new bottom-of-stack vultron/enums/ package, and converts vultron/config.py into a vultron/config/ sub-package that adds AppConfig.actor: ActorConfig for neutral actor-policy configuration — prerequisite for wiring actor config into the production dispatch path without a layering violation.

Changes

• vultron/enums/roles.py: CVDRole StrEnum + serialize_roles/validate_roles (moved from vultron/core/states/roles.py; deleted, no shim). validate_roles now raises ValueError for non-None non-list input instead of silently returning [].
• vultron/enums/__init__.py: public re-exports; MUST NOT import from vultron.core/config/adapters
• vultron/config/actor.py: ActorConfig Pydantic BaseModel (moved from vultron/core/models/actor_config.py; deleted, no shim); imports CVDRole from vultron.enums.roles
• vultron/config/app.py: AppConfig gains actor: ActorConfig field; get_config()/reload_config() unchanged; removed dead get_field_value() override (pydantic-settings 2.x dispatches via __call__() only — ABC requirement retained)
• vultron/config/__init__.py: public re-exports; vultron/config.py deleted, no shim
• ~99 source files: from vultron.core.states.roles import → from vultron.enums.roles import
• ~15 source files: from vultron.core.models.actor_config import ActorConfig → from vultron.config.actor import ActorConfig
• test/architecture/test_enums_import_graph.py: 5 AST-based import-graph invariant tests; refactored to shared helper (_assert_no_forbidden_imports), dead helpers removed, module-level imports
• test/test_config.py: reset_config fixture clears VULTRON_ACTOR__* env vars; 5 new AppConfig.actor coverage tests
• test/core/states/test_cvd_roles.py: update non-list test to match new raising behaviour
• test/core/models/test_actor_config.py: add scalar-string rejection test
• AGENTS.md: fix stale load_actor_config() reference → get_config().actor; fix section link
• notes/configuration.md: fix stale testing-pattern code snippet (_config_cache lives in app.py)
• notes/case-communication-model.md: fix stale CVDRole import path
• notes/two-actor-demo.md: fix stale vultron/core/states/roles.py reference

Verification

• 4718 tests pass (7 new), 38 skipped, 2 xfailed
• Black, flake8, mypy, pyright clean
• AC-1: vultron/enums/roles.py exports CVDRole, serialize_roles, validate_roles; all former vultron.core.states.roles import sites updated; no shim
• AC-2: vultron/config/ sub-package with app.py and actor.py; AppConfig has actor: ActorConfig; all former import sites updated; no shim
• AC-3: full linter + test suite passes
• AC-4: notes/configuration.md updated with current architecture, YAML schema, and env var reference

[sei-ahouseholder]

PR Review — refactor: move CVDRole to vultron/enums/; config.py → config/ sub-package

CI: All 12 checks pass (lint, type, tests, demo integration, CodeQL)

---

Phase 2 — Issue Linkage: PASS

• Closes #1342 — all 4 ACs addressed.
• load_actor_config() (CFG-07-005) correctly deferred to #1343 — out of scope for this PR.

Phase 3 — PR Body Format: PASS

Closing reference at top, Summary/Changes/Verification present, actual test count (4718, 7 new), all ACs checked, Co-authored-by trailer present.

Phase 5 — Spec and Notes Conformance: PASS

CFG-07-001 through CFG-07-006 satisfied. ADR-0031 written, accepted, and referenced throughout.

Phase 6 — ADR Check: PASS

ADR-0031 added, correctly formatted, listed in docs/adr/index.md.

Phase 8 — Code Review: PASS

• validate_roles() handles None, list, and non-list correctly; uppercase string inputs normalised via .lower().
• YamlConfigSource.get_field_value() satisfies the ABC correctly — __call__() is the pydantic-settings 2.x data path.
• Architecture ratchet tests in test/architecture/test_enums_import_graph.py use AST static analysis — well-designed.
• vultron/core/states/__init__.py re-exports CVDRole from vultron.enums.roles, preserving backward compatibility.

Phase 9 — Notes Currency: IMPROVE → FIXED

Four stale references not touched by the PR were found and fixed in review commit 7bbf3301:

• notes/bt-composability.md line 536: ActorConfig path updated from vultron/core/models/ (or vultron/config.py) → vultron/config/actor.py
• notes/codebase-structure.md line 49: Stale vultron/enums.py (backward-compat re-exports) entry replaced with correct vultron/enums/ package description per ADR-0031
• notes/configuration.md: "Module Structure" section annotated as historical/superseded; intro updated to reference sub-package rather than the flat file
• vultron/bt/roles/enums.py docstring: Stale vultron.core.states.roles path updated to vultron.enums.roles

Phase 10 — Test Coverage: PASS

7 new tests cover AppConfig.actor defaults/env-var overrides, validate_roles scalar rejection, and ActorConfig scalar string rejection. Import-graph ratchet enforces layer invariants statically.

Phase 11 — CI: PASS

All 12 checks green including FVV and Two-Actor demo integration.

---

Summary

Phase	Verdict
Issue linkage	PASS
PR body format	PASS
Spec conformance	PASS
ADR check	PASS
Code review	PASS
Notes currency	IMPROVE → FIXED (7bbf3301)
Test coverage	PASS
CI	PASS

Ready to merge. No FAIL findings. Four stale notes references fixed in follow-up commit.