improve-modularity: split SDL core runtime-services 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_sdl/orchestration.py, is now raes/orchestration.py.
• 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. This issue covers the SDL core runtime-services modules.

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/composition.py	1110	raes.composition
implementations/python/packages/raes/orchestration.py	654	raes.orchestration
implementations/python/packages/raes/participant_behavior.py	826	raes.participant_behavior
implementations/python/packages/raes/runtime_mail_service.py	525	raes.runtime_mail_service

Note: raes/participant_behavior.py (this issue) is distinct from raes/semantics/participant_behavior.py (issue #51) — they are different modules at different paths.

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.orchestration|import raes.orchestration") 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-code, branch 52-split-sdl-runtime-modules, 2026-08-02T05:50:36.373Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #52). 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 #52). 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.

Implementation Plan — split SDL core runtime-services modules (#52)

Requirement-free structural refactor. Convert four oversized raes modules into same-named packages behind API-stable facades. No behavior change: public identities, signatures, Pydantic/enum metadata, validator registration order, error wording, insertion-ordered output, generated schemas, and the mail module's ordered __all__ are all preserved. Anchored on the binding preflight note docs/decisions/issue-52-core-runtime-services-package-split-preflight.md.

Current origin/dev sizes (the issue's 1110 for composition is stale): composition 1279, orchestration 654, participant_behavior 826, runtime_mail_service 525. Every file in each new package (including __init__.py) must be ≤ 500 lines (ADR-015 §2).

Facade convention (mirrors prior splits: module_registry, semantics/objective_semantics)

• raes/<module>.py → raes/<module>/ package; the dotted name stays the only supported caller import surface. Child modules are private (_-prefixed) implementation details; callers must never import them, and children import sibling foundations/owners directly — never back through their own __init__ (acyclic).
• Relative imports shift one level deeper (from ._base → from .._base, from .participant_action_semantics → from ..participant_action_semantics).
• composition/orchestration/participant_behavior had no __all__ → facades add none (adding one would narrow legacy import *). Intentional re-export F401 is suppressed with a narrow per-file-ignore in implementations/python/pyproject.toml (not inline, not broadened). runtime_mail_service keeps its exact ordered __all__.

Per-module subdomain split (by semantic ownership, not line ranges)

• composition/ — pure functional pipeline, 5 children: _references.py (rename/ref primitives + target-spec constants + variable-token rewrite), _sections.py (foundational/proposition/narrative/observation/content/stateful/account/deployment/relationship rewriters + descriptor-export validation), _behavior.py (mixed-control, tool-affordance, inject-delivery, agent, behavior-spec, resource-budget, behavior-reference maps), _terminal.py (time/objective/workflow/variation rewriters + namespacing), _expand.py (the single expand_sdl_modules coordinator + _rewrite_payload_with_symbols/_namespace_payload/_merge_sections). Facade re-exports expand_sdl_modules, _rewrite_payload_with_symbols, _namespace_payload (the externally-imported names) plus the full public surface. from __future__ import annotations retained in every child.
• orchestration/ — 4 children: _durations.py (parse_duration + duration tables), _events.py (Inject,Event,Script,Story), _steps.py (workflow step/predicate/policy models + enums + WorkflowStep), _workflow.py (Workflow). Facade re-exports all models/enums + parse_duration.
• participant_behavior/ — 2 independent children: _action_contracts.py (action-argument enums/aliases/scalars + ParticipantActionArgumentDefinition + ExternalMappingLoss + ParticipantInteractionDeclaration + ParticipantActionContract) and _view_boundaries.py (view/boundary enums + constants + ParticipantViewRule/ParticipantViewTransition + validation helpers + ParticipantObservationBoundary). Facade re-exports every model/enum/type-alias plus the existing ParticipantEffectClass/ParticipantFailureClass/ParticipantPreconditionClass (and other action/temporal) re-exports, preserving their object identity.
• runtime_mail_service/ — 2 children: _elements.py (address/domain helpers + the 9 element models Component/Listener/Domain/MailboxStore/Mailbox/Alias/RoutingRule/Queue/Setting) and _service.py (RuntimeMailService aggregate + RelationshipMailAccess). Facade preserves the exact ordered __all__. _runtime_service_family_registry.py (module=) and runtime_configuration.py import the module object and read RuntimeMailService off it — the facade exposes the same objects, so both keep working unchanged.

Whole-repo path retargeting (files reference these modules by path; several are policy-gated)

Every raes/<module>.py textual reference → raes/<module>/__init__.py. Gated consumers that require the cited path to be a real file:

• tools/policy/oversized_allowlist.yaml — remove the 4 entries (drains the allowlist; the frozen _ADR015_INITIAL_OVERSIZED_FILES baseline in repo_policy.py stays untouched — allowlist ⊆ baseline still holds). Gate: check_repo_policy.
• contracts/provenance/sdl-lineage-ledger-v1.json — repoint the 6 orchestration.py artifact refs. Gate: check_sdl_lineage (_validate_internal_paths → is_file()).
• contracts/profiles/scientific-completeness/delivery-assessment-2026-07-12.json — repoint the orchestration.py/participant_behavior.py implementation-evidence paths (claim text unchanged). Gate: check_scientific_scenario_completeness.
• docs/explain/reference/shared-semantic-integrity.md — repoint composition/orchestration/participant_behavior rows. Gate: check_semantic_coverage (ADR-016).
• tools/check_sdl_catalog_parity.py _BEHAVIOR_MODEL and the matching specs/sdl/references.md rows — repoint together (parity requires doc == constant).
• Docs kept link-valid: specs/formal/workflows/{goal-oriented-steps,compensation}.md, specs/formal/participant-semantics/README.md, docs/research/participant-io-control/current-state-assessment.md.
• docs/public/api/sdl.rst — targets stay raes.composition/raes.orchestration; add :imported-members: to those two automodule blocks so re-exported public members still render (Sphinx warnings-as-errors; conf.py has no global imported-members). Historical ADR/preflight prose is not rewritten.

Design review (FAANG L6+ lens)

• Security: no new auth/secret/env/argv/subprocess/socket/DB/filesystem surface. Mail credential unrepresentability + RuntimeSensitivityClassification/enforce_observed_value_redaction redaction, composition lock/trust/registry/budget/source bounds, and participant hidden/view/evidence separation all stay with their current owners. No payload/secret/traceback added to errors or logs.
• Maintainability: reuse canonical incumbents — _module_symbols/_composition_budget/_composition_provenance, runtime_mail_vocab/runtime_values, participant_action_semantics/participant_temporal_semantics, SDLModel(extra="forbid"). No common.py dumping ground, no duplicated tables/validators/enums/exceptions.
• Extensibility: preserve existing seams (_rewrite_payload_with_symbols single coordinator; closed WorkflowStep.type discriminator; owning participant enums/models; RuntimeServiceFamily.child_refs). No new plugin/registry/parameter.
• Whole-repo: canonical gates enumerated above plus generated-schema drift (schema_bundle() unchanged), Sphinx autodoc, and runtime-family invariant tests (already package-aware) are all reconciled.

Verification (per .gc/plan-rules.md)

implementations/python/.venv/bin/python tools/check_repo_policy.py, tools/check_requirement_governance.py, and tools/verify_all.py before completion; full nox -s verify in CI. Targeted first: git grep each module's import sites confirm zero external-import edits; import-resolution smoke test each facade; then the size-cap, lineage, scientific-completeness, semantic-coverage, catalog-parity, and Sphinx gates. No pre-existing test modified; no schema/CHANGELOG.md/version edit. PR title will be a non-releasing refactor: Conventional Commit (passes title-guard).

Acceptance-criteria mapping

Each .py → package dir with __init__.py ✔ · every package file ≤ 500 lines (verified after allowlist drain) ✔ · no external import line changed (diff-verified in clause check) ✔ · 4 allowlist entries removed ✔ · nox -s verify green ✔ · no pre-existing test modified ✔ · CHANGELOG item superseded by .gc/plan-rules.md (release-please owns it) — recorded as the one deliberate deviation.

[Brad-Edwards]

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

Core review

Verdict: ship

This is shaped correctly as a structural package split: the four established module facades remain the supported import boundaries, cohesive implementation concerns move into private child modules, and composition retains one ordered coordinator and one canonical rewrite seam. Existing validators, vocabulary owners, runtime contracts, and shared helpers remain in their incumbent layers; the mail aggregate keeps cross-element invariants centralized, while orchestration and participant authored models remain distinct from semantic and runtime layers. The change preserves facade exports, ordering-sensitive behavior, source references, documentation discovery, and policy evidence without introducing a parallel abstraction or foreclosing the obvious next variation. I would ship this.

No blocking findings.

Security review

Verdict: ship

This is shaped correctly as a package-boundary refactor: the public facades remain stable while composition admission, trust resolution, structural validation, participant information-boundary enforcement, and mail-setting redaction stay at their existing seams. The moved implementation preserves the ordering and substance of the security-sensitive validators and rewrite passes, introduces no new external input, authority, execution, logging, or persistence surface, and does not foreclose extending the existing typed child modules. I found no concrete, exploitable security regression introduced by the diff.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #52 on branch '52-split-sdl-runtime-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 #52)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: This is shaped correctly as a structural package split: the four established module facades remain the supported import boundaries, cohesive implementation concerns move into private child modules, and composition retains one ordered coordinator and one canonical rewrite seam. Existing validators, vocabulary owners, runtime contracts, and shared helpers remain in their incumbent layers; the mail aggregate keeps cross-element invariants centralized, while orchestration and participant authored models remain distinct from semantic and runtime layers. The change preserves facade exports, ordering-sensitive behavior, source references, documentation discovery, and policy evidence without introducing a parallel abstraction or foreclosing the obvious next variation. I would ship this.

Security reviewer: This is shaped correctly as a package-boundary refactor: the public facades remain stable while composition admission, trust resolution, structural validation, participant information-boundary enforcement, and mail-setting redaction stay at their existing seams. The moved implementation preserves the ordering and substance of the security-sensitive validators and rewrite passes, introduces no new external input, authority, execution, logging, or persistence surface, and does not foreclose extending the existing typed child modules. I found no concrete, exploitable security regression introduced by the diff.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #52

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 52-split-sdl-runtime-modules
Cycle: 1 / 1
Findings: 0 (clean run)