Split received/case.py and received/actor.py into subpackages

[sei-ahouseholder]

• Closes Split large received use-case modules (received/case.py and received/actor.py) #881

Summary

Splits two 800+ line use-case modules into focused subpackages, each
submodule under 500 lines, with re-exporting __init__.py files that
preserve all existing import paths.

Addresses review feedback:

1. Test split (AC-4): test_create.py (807 lines) and
   test_update.py (559 lines) have been split into focused per-concern
   modules that mirror the source submodule they exercise.
2. BT-migration debt marked (BT-06-001, BT-15-001): Inline protocol
   mutations in AcceptInviteActorToCaseReceivedUseCase and
   _ensure_reporter_participant are explicitly marked as debt with
   TODO(#943) comments. Comment language no longer presents inline as the
   architectural solution. Tracking issue: Migrate received use-case procedural protocol behavior to BT nodes (BT-06-001, BT-15-001) #943.

Changes

Source subpackages (unchanged from original split)

• vultron/core/use_cases/received/case/ (new package):
  _helpers.py, create.py, update.py, engage_defer.py,
  lifecycle.py, validate.py, __init__.py (re-exports all public
  names)
• vultron/core/use_cases/received/actor/ (new package):
  suggest.py, case_manager_role.py, ownership.py, invite.py,
  announce.py, __init__.py (re-exports all public names)

BT-debt markers added

• received/actor/invite.py: AcceptInviteActorToCaseReceivedUseCase
  — replaced inline-as-solution comment with TODO(#943) on RM transitions,
  participant creation, case events, and dl.save
• received/case/_helpers.py: _ensure_reporter_participant —
  added TODO(#943) on direct ParticipantStatus(rm_state=RM.ACCEPTED)
  creation/upgrade

Test layout (per-concern split)

• test/core/use_cases/received/case/test_create.py (reduced to
  CBT-05-001..004 bootstrap use-case tests only)
• test/core/use_cases/received/case/test_bootstrap_participants.py
  (new): CBT-05-005/006 — embedded participant storage and M4 regression
  (EngageCaseBT fails on finder replica: CheckParticipantExists cannot find vendor CaseParticipant #561/AddParticipantStatusBT fails on finder replica: vendor CaseParticipant UUID not in DataLayer #562/Two-actor demo M4 timeout: finder returns 404 for vendor vfd_state polling #563)
• test/core/use_cases/received/case/test_helpers.py (new):
  CBT-05-006/007 — _ensure_reporter_participant seeding and RM.ACCEPTED
  upgrade (SvcAddParticipantStatusUseCase sends RM.START status after notify-published — vendor rejects as backwards transition #589/bug: vendor BT fails on inbound post-publish activity — M6/M7 timeout (EM not reaching EXITED) #624); includes TODO(#943) class notes
• test/core/use_cases/received/case/test_update.py (reduced to
  use-case behavior tests only)
• test/core/use_cases/received/case/test_update_bt.py (new):
  UpdateCaseBT tree-structure and no-post-BT-broadcast assertions
• test/core/use_cases/received/actor/ (unchanged): per-module
  test files migrated from flat files

Verification

• 3205 passed, 36 skipped in 42s
• Black, flake8, mypy, pyright clean

[sei-ahouseholder]

I’m requesting changes, not because CI is failing, but because this PR is meant to set the structural precedent for future use-case splits and it currently leaves two important expectations weaker than issue #881 requires.

1. AC-4 is only partially satisfied. The source files were split well, but the test split is mostly directory-level. test/core/use_cases/received/case/test_create.py is still 807 lines and includes bootstrap create, participant storage, AddParticipantStatus-after-bootstrap, reporter seeding, and reporter upgrade scenarios. test/core/use_cases/received/case/test_update.py is still 559 lines and mixes use-case behavior with BT tree-structure assertions. Issue Split large received use-case modules (received/case.py and received/actor.py) #881 asks for the test layout to mirror the source split, and CS-18-004 / the BUILD_LEARNINGS entry for Split large received use-case modules (received/case.py and received/actor.py) #881 point toward per-submodule test files. Please split the helper/bootstrap-participant cases into a focused test_helpers.py / test_bootstrap_participants.py (or equivalent), and split the update BT-structure tests from the update use-case tests if they stay in this package.

2. The split canonizes non-BT procedural protocol behavior unless it is explicitly marked as debt. I agree PCR-08-010 means AcceptInviteActorToCaseReceivedUseCase must not spoof the invitee by executing an engage-case BT under the wrong actor identity. But BT-06-001 / BT-06-006 still say protocol-significant state transitions and domain object mutations should live in reusable BT nodes/subtrees, not use-case bodies or reusable procedural helpers. This split now gives _ensure_reporter_participant() a reusable home while it directly creates/upgrades ParticipantStatus(rm_state=RM.ACCEPTED), and AcceptInviteActorToCaseReceivedUseCase directly appends RM states and case events. If those transitions are intentionally preserved scope-wise, please avoid test/comment language that presents “inline” as the architectural solution, and add a tracked TODO/issue reference making clear this is preserved BT-migration debt rather than precedent for future use-case splits.

What looks good: the new source submodules are under 500 lines, the public use-case classes are preserved through package re-exports, and CI is green.

[sei-ahouseholder]

Follow-up / strengthening my second point above: this should be treated as blocking, not optional debt.

The identity-spoofing constraint is real: a received-side use case must not run a BT as another actor. But that does not justify doing protocol-significant work procedurally in the use case. The correct architecture is: the receiving actor runs a BT as itself, and that BT contains the reusable leaf nodes/subtrees for the state it is authorized to record in its own DataLayer.

So the direct DataLayer/domain mutations in received use-case execute() bodies are not acceptable precedent:

• AcceptInviteActorToCaseReceivedUseCase directly creates a participant, appends RM states, records case events, saves the case, and queues outbox work.
• _ensure_reporter_participant() directly creates/upgrades participant RM state to RM.ACCEPTED.
• Other received use cases still directly mutate cases or outbox state.

Per BT-06-001 and BT-06-006, use cases should be infrastructure glue only: construct the tree, set up blackboard/context, execute through BTBridge, inspect result, and surface errors. They should not make direct dl.create / dl.save / state-transition / outbox calls. This PR should move those operations into BT nodes/subtrees as part of the split.