improve-modularity: split libvirt backend & workflow-contract modules (4 files)

[Brad-Edwards]

Part of #3 (modularity initiative tracker).

Context (re-scoped 2026-07-30)

Since this issue was filed the codebase moved out from under its original text, so it has been re-scoped:

• ACES → RAES rename (Rename ACES to RAES across repository surfaces #866). The old aces_* paths no longer exist; paths below use the current raes_* package names. This issue's original single target, aces_mcp/tools/authoring.py, moved to improve-modularity: split runtime control-plane & MCP tooling modules (4 files) #49; this issue now covers the libvirt backend + workflow-contract modules that fell under the cap after it was lowered.
• Size cap lowered 600 → 500 lines (ADR-015 §2 amendment, Lower ADR-015 source-file cap from 600 to 500 lines (align with SonarCloud S104) #561, aligned with SonarCloud S104). All files below are still over the current 500-line cap and still listed in tools/policy/oversized_allowlist.yaml.
• Re-balanced children. When the cap dropped, more files fell under it, so the tracker's original one-file-per-issue children improve-modularity: split runtime control-plane & MCP tooling modules (4 files) #49–improve-modularity: split SDL core runtime-services modules (4 files) #52 were rebalanced to cover the remaining 16 oversized files, ~4 per issue.

No behavior change. Each file becomes a package directory behind an API-stable re-export shim.

Files (this issue)

File	Lines (origin/dev)	Import module
implementations/python/packages/raes_backend_libvirt/drivers/libvirt.py	555	raes_backend_libvirt.drivers.libvirt
implementations/python/packages/raes_backend_libvirt/realization.py	571	raes_backend_libvirt.realization
implementations/python/packages/raes_backend_libvirt/techvault_native.py	563	raes_backend_libvirt.techvault_native
implementations/python/packages/raes_contracts/workflow.py	688	raes_contracts.workflow

Mechanics (per file)

1. Read the file. Identify cohesive subdomains by clustering classes/functions that share concepts, types, or call relationships.
2. Convert the file to a Python package: replace <path>.py with a directory of the same base name <path>/.
3. Move code into subdomain files <path>/<subdomain>.py. Each subdomain file MUST be ≤ 500 lines.
4. <path>/__init__.py re-exports the public API — every name imported from the original module anywhere else in the codebase, plus any names in __all__.
5. For each module, run git grep -E "from <module>|import <module>" (e.g. git grep -E "from raes_contracts.workflow|import raes_contracts.workflow") to enumerate every external import site. Confirm zero of those lines need to change.
6. Remove the file's entry from tools/policy/oversized_allowlist.yaml.

Acceptance criteria

• Each file above no longer exists as a .py; a package directory with __init__.py exists in its place.
• Every .py file under each new package directory is ≤ 500 lines (verified by tools/check_repo_policy.py after the paths are removed from the allowlist).
• No external import line referencing any of these four modules was modified by this PR (verified by diff inspection during clause verification).
• tools/policy/oversized_allowlist.yaml no longer contains any of the four files above.
• uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify passes.
• No pre-existing test was modified to make the suite pass.
• CHANGELOG.md has an entry for this change.

Out of scope

• Any behavior change. This is a pure refactor — equality of public API and equality of behavior under the existing test suite is the contract.

[Brad-Edwards]

🛠️ Picked up by /implement - driver claude, branch 50-split-libvirt-workflow-modules, 2026-08-01T19:21:34.186Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #50). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #50). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Plan — split 4 oversized modules into API-stable packages (#50)

Pure structural refactor. Zero behavior/API change; equality of public API and behavior under the existing suite is the contract. Requirement-free run. Architecture preflight guardrails (docs/decisions/issue-50-libvirt-workflow-package-split-preflight.md) are binding and reconciled below.

Each <module>.py becomes a same-named <module>/ package: a thin __init__.py facade re-exporting the exact prior surface, plus private child modules each ≤500 lines. The .py and package never coexist (atomic conversion). No external import line changes.

1. raes_backend_libvirt/drivers/libvirt.py (555) → drivers/libvirt/

• _native.py — native adapter seam: error-code classification (_error_code, _is_absence_error, _VIR_ERR_*, _ABSENCE_ERROR_CODES), deterministic UUID helpers (_raes_uuid, _filter_owner_uuid, _RAES_UUID_NAMESPACE), _existing_uuid, protocols (_NativeResource, _LibvirtModule), Connector, _default_connector, _call_libvirt, _lookup (define/convergence path) vs _find_native (teardown path) — kept distinct — _stop_native, _safe_name/_SAFE_NAME_RE, exceptions (_OwnershipConflict, _NativeLookupError).
• deployment.py — LibvirtDeploymentDriver + its diagnostics (_DOMAIN, _CODE_*, _DEFAULT_CONNECTION_URI, _WORKSPACE_PREFIX, _FAILURE_MESSAGES, _failure).
• __init__.py re-exports (redundant-alias, no __all__ added): LibvirtDeploymentDriver, Connector, _error_code, _existing_uuid, _raes_uuid, _filter_owner_uuid.
• _libvirt_xml, seed, cloudinit stay where they are (imported via ..).

2. raes_backend_libvirt/realization.py (571) → realization/

Preserve purity and dependency direction; no driver/IO/snapshot. DAG (no facade import by children):

• _common.py — _resource_name (shared by specs + cloud-init; breaks the specs↔cloud-init cycle).
• _diagnostics.py — _DOMAIN, _NETWORK_NAMESPACE_UNSUPPORTED, the 4 ordered diagnostic builders.
• _cloud_init.py — _CloudInitAccumulator, _aggregate_cloud_init, _merge_emit, _placement_target, _realize_{account,content,feature}, _content_descriptor, _descriptor_body, _ssh_authorized_keys, _truthy, _dirname.
• _specs.py — network/node/cidr lookups, _network_spec, _domain_spec, _services, _service, _memory_mib, _vcpus, _image_ref, _infrastructure_spec, _network_refs, _node_resources.
• _plan.py — Realization, interpret_provisioning_plan, _collect_supported_resources.
• __init__.py re-exports (redundant-alias, no __all__): Realization, interpret_provisioning_plan, plus the private projection seams techvault_plan_admission imports: _image_ref, _infrastructure_spec, _memory_mib, _node_resources, _resource_name, _services, _vcpus.

3. raes_backend_libvirt/techvault_native.py (563) → techvault_native/

Class stays one concrete class — no mixin split, MRO/override behavior for GuestCertifiedLibvirtDriver and the _material_binding test seam preserved. For headroom, extract the define-stage bodies behind unchanged method seams (guardrail: "narrow helper behind the same method seam"):

• _define.py — module helpers define_networks/define_network/define_domains/define_domain(driver, …); _define_domain calls driver._render_domain_xml so the subclass override still dispatches. Owns define-only imports (_ensure_name_available, _call, _NativeResource, copy_kernel_for_libvirt, make_libvirt_readable, network_observations, domain_observations, _network_xml).
• _driver.py — TechVaultNativeLibvirtDriver with all method seams intact (_define_* become thin delegators to _define), preserving stage order (admission→network→domain→daemon→guest→binding→snapshot) and ownership-checked rollback.
• __init__.py — __all__ = exact ordered 7 names; plain imports for those + redundant-alias re-export of DriverResult and _artifact_token (imported by guest_certified_driver, absent from __all__).

4. raes_contracts/workflow.py (688) → workflow/

One dependency direction, children never import the facade:

• enums.py — the 5 enums.
• provenance.py — WorkflowStepAttemptProvenance, _validate_provenance_string_tuple.
• contracts.py — WorkflowResultContract, WorkflowExecutionContract, validate_workflow_step_result_contract, contract helpers/validators.
• state.py — WorkflowHistoryEvent, WorkflowStepExecutionState, WorkflowExecutionState, WorkflowCancellationRequest, their validators, terminal-status sets, _workflow_steps_from_payload.
• __init__.py — __all__ = the exact ordered 13-name tuple, object-identical re-exports (keeps raes_processor.models DTO identity). Preserve field order/defaults, enum identity, from_*/to_payload shapes, __post_init__ order, exact TypeError/ValueError text; no tightening of iterable/compensation/timeout/cancellation handling.

5. Allowlist

Remove exactly the 4 converted paths from tools/policy/oversized_allowlist.yaml. Leave tools/policy/repo_policy.py::_ADR015_INITIAL_OVERSIZED_FILES (immutable reference superset) and adr_policy.yaml unchanged — the allowlist stays a subset; raes_backend_libvirt.techvault_native remains a valid public import path via the facade.

Testing

Existing suite is the behavioral oracle (issue: "no pre-existing test modified"). No new tests — adding tests for a no-op re-export refactor is noise. Faithful checks: after each conversion, git grep the module's import sites to confirm zero lines change; run the module's targeted tests; then full nox -s verify (requirement-free, so --skip-requirement) once at the end. ruff combine-as-imports=false → aliased re-exports each on their own statement; run ruff check/format to conform. No new ruff suppressions (redundant-alias re-exports need none).

Docs / plan-rules

docs/DEVELOPMENT_WORKFLOW.md was flagged (allowlist is a policy surface), but this is a routine shrink of the allowlist data — the size-cap mechanism it documents is unchanged, so no doc edit is warranted. Per .gc/plan-rules.md: CHANGELOG.md left untouched (release-please owns it; the issue's changelog acceptance item is stale, #684); no version edit; no new authority artifacts outside allowed dirs; PR title will be a valid Conventional Commit (refactor:). Completion gates: check_repo_policy.py, check_requirement_governance.py, verify_all.py / nox -s verify.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #50 (branch 50-split-libvirt-workflow-modules)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship

Architecture-fit: this is shaped correctly as an atomic module-to-package refactor. The thin facades preserve the declared import surfaces, child modules retain the existing dependency direction, and the extracted libvirt, realization, TechVault, and workflow responsibilities remain behind their incumbent lifecycle and validation seams without introducing parallel abstractions. Code-quality: the partitions are cohesive and comfortably address the size-policy constraint; delegation preserves subclass dispatch and behavior ordering, while the workflow split retains field order, coercion, validation, and payload contracts. The obvious next variation remains localized to its owning child module.

No blocking findings.

Security review

Verdict: ship

This is a mechanical module-to-package split shaped around the existing security boundaries: libvirt ownership and fail-closed teardown remain centralized in the native adapter, realization remains pure and preserves capability admission and path/command handling, TechVault retains staged admission, ownership checks, readback, and cleanup, and workflow contracts retain their validation order and public facade. The delegating seams preserve subclass dispatch without introducing new authenticated entry points, configuration sources, persistence paths, or unvalidated ingress. The package boundaries leave room for the obvious next internal variation without weakening the existing security controls. I would ship this.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #50 on branch '50-split-libvirt-workflow-modules'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #50)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: Architecture-fit: this is shaped correctly as an atomic module-to-package refactor. The thin facades preserve the declared import surfaces, child modules retain the existing dependency direction, and the extracted libvirt, realization, TechVault, and workflow responsibilities remain behind their incumbent lifecycle and validation seams without introducing parallel abstractions. Code-quality: the partitions are cohesive and comfortably address the size-policy constraint; delegation preserves subclass dispatch and behavior ordering, while the workflow split retains field order, coercion, validation, and payload contracts. The obvious next variation remains localized to its owning child module.

Security reviewer: This is a mechanical module-to-package split shaped around the existing security boundaries: libvirt ownership and fail-closed teardown remain centralized in the native adapter, realization remains pure and preserves capability admission and path/command handling, TechVault retains staged admission, ownership checks, readback, and cleanup, and workflow contracts retain their validation order and public facade. The delegating seams preserve subclass dispatch without introducing new authenticated entry points, configuration sources, persistence paths, or unvalidated ingress. The package boundaries leave room for the obvious next internal variation without weakening the existing security controls. I would ship this.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #50

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 50-split-libvirt-workflow-modules
Cycle: 1 / 1
Findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #50 on branch '50-split-libvirt-workflow-modules'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next gc_test_quality_review invocation to count cycles.

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #50)

Reviewer: test-quality
Cycle: 1
Blocking findings: 0 (clean run)