improve-modularity: split SDL security-monitoring, semantics & evidence 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/inspection.py, moved to improve-modularity: split runtime control-plane & MCP tooling modules (4 files) #49; this issue now covers the SDL runtime-security-monitoring, semantics, and operations-evidence 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/runtime_security_monitoring.py	515	raes.runtime_security_monitoring
implementations/python/packages/raes/semantics/objective_semantics.py	573	raes.semantics.objective_semantics
implementations/python/packages/raes/semantics/participant_behavior.py	1401	raes.semantics.participant_behavior
implementations/python/packages/raes_operations/_evidence_run_artifact.py	611	raes_operations._evidence_run_artifact

Note: raes/semantics/participant_behavior.py (this issue) is distinct from raes/participant_behavior.py (issue #52) — they are different modules at different paths. _evidence_run_artifact.py is a leading-underscore module; the package/__init__ re-export pattern applies to it unchanged.

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.semantics.participant_behavior|import raes.semantics.participant_behavior") 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 51-split-sdl-oversized-modules, 2026-08-01T19:21:56.778Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #51). 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 #51). 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 4 oversized SDL modules into re-export packages

Nature: pure, behavior-preserving refactor (no requirements in scope). Each <path>.py becomes a <path>/ package whose __init__.py re-exports the exact public surface; no external import line changes. Verified against the architecture preflight guardrails (docs/decisions/issue-51-...-preflight.md).

Per-file split design

1. raes/runtime_security_monitoring.py (515 → package)

• _enums.py — the 9 RuntimeSecurityMonitoring* enums.
• _models.py — _REDACTED_SENSITIVITIES, the 7 SDLModel classes, and _reject_duplicate_local_ref_ids; imports enums from ._enums, and RuntimeSecurityMonitoringDetectionDefinition from ..runtime_security_monitoring_definitions. Carries a module docstring (read by test_runtime_family_invariants._required_profile_signal via model.__module__).
• __init__.py — original docstring + re-export of the exact ordered __all__ (including the 5 detection-definition names re-exported from ..runtime_security_monitoring_definitions). The registry (_runtime_service_family_registry.py passes module=…) and runtime_configuration.py:357 (_runtime_security_monitoring.RuntimeSecurityMonitoringManager) resolve these as package attributes.

2. raes/semantics/objective_semantics.py (573 → package)

• _constants.py — _BOTH_ROLES + the 5 OBJECTIVE_*_DEPENDENCY_ROLES.
• _types.py — ObjectiveReferenceKind + the 6 dataclasses.
• _analysis.py — the _check_*/_analyze_*/_has_cycle/_objective_dependency_graph/_ordered_unique/_never_unresolved helpers.
• __init__.py — original docstring; defines partition_objective_dependencies and analyze_objective_semantics here so the constants they read live in the package namespace. This preserves test_semantics_objectives.py's monkeypatch.setattr(os_module, "OBJECTIVE_DEPENDENCY_DEPENDENCY_ROLES", …) semantics (the facade attribute the function reads). Re-exports the full public surface (no restrictive __all__ added — none existed).

3. raes/semantics/participant_behavior.py (1401 → package) — distinct from raes/participant_behavior.py (#52).

• _types.py — ParticipantBehaviorReference/Issue/Analysis + _BehaviorSpecificationReferenceContext.
• _references.py — agent/boundary/visibility helpers + shared _resolve_section_ref and _tool_affordance_participants.
• _behavior_spec.py — behavior-spec reference + vocabulary/feature/evidence/mode helpers.
• _autonomous_bindings.py — autonomous context dataclasses + _autonomous_issue + declaration/action/boundary/clock/constraint/time-binding helpers.
• _autonomous.py — progression/cadence/evaluation helpers + entry _autonomous_execution_reference_issues.
• _tool_affordance.py — tool-affordance helpers (imports tool_affordance_reference from ...participant_behavior_specification).
• _analysis.py — registries + reference-context builder + _behavior_specification_issues + analyze_participant_behavior.
• __init__.py — original docstring + re-export of the public dataclasses and analyze_participant_behavior (no restrictive __all__ added). Import graph is one-way (leaf→analysis), no cycles.

4. raes_operations/_evidence_run_artifact.py (611 → package) — leading-underscore module; package pattern applies unchanged. Uses only absolute imports, so section builders keep their imports verbatim.

• _backend.py, _topology.py, _participant.py, _evidence.py — cohesive section-builder groups (each self-contained; no cross-group helper calls).
• __init__.py — module docstring + EVIDENCE_RUN_SCHEMA + _NON_CLAIMS + the assemble_artifact coordinator (imports the section builders). EVIDENCE_RUN_SCHEMA and assemble_artifact stay at the facade for _evidence_run_validation.py / libvirt_evidence_run.py.

Each new .py will be ≤ 500 lines (verified after writing). The original 4 .py files cease to exist (converted to dirs) so _check_oversized_debt_consistency sees them as drained, not stale.

Cross-cutting consequences (in scope — direct results of the move)

• tools/policy/oversized_allowlist.yaml — remove the 4 drained entries (leave raes/participant_behavior.py, which is improve-modularity: split SDL core runtime-services modules (4 files) #52).
• docs/explain/reference/shared-semantic-integrity.md — check_semantic_coverage.py .exists()-checks each .py token; repoint the objective_semantics.py and semantics/participant_behavior.py tokens to their new .../__init__.py (4 occurrences).
• specs/sdl/references.md + tools/check_sdl_catalog_parity.py — the _OBJECTIVE_SEMANTICS / _PARTICIPANT_SEMANTICS / _BEHAVIOR_SEMANTICS source links: update both sides together (catalog + parity registry constant) to the new .../__init__.py paths so registry↔catalog parity holds and the links are live.
• tools/test/test_runtime_family_invariants.py — preserve enforcement across the packaging change (preflight guardrail): make the shared-helper glob package-aware (runtime_*.py + runtime_*/**/*.py) and relax _runtime_family_enums' __module__ filter to include a runtime_* package's submodules. Both changes extend discovery; no assertion is weakened.

CHANGELOG reconciliation

Acceptance criterion "CHANGELOG.md has an entry" predates the Release Please migration (#684, GC-P027). Per .gc/plan-rules.md and the preflight, CHANGELOG.md is not hand-edited — Release Please derives it from Conventional Commit history on main. The PR title will be a valid refactor: Conventional Commit (a no-behavior-change internal split correctly cuts no release) and will pass tools/check_pr_title.py.

Verification

tools/check_repo_policy.py (oversized/layering/drain), tools/check_semantic_coverage.py, tools/check_sdl_catalog_parity.py, tools/check_requirement_governance.py, and the full pinned nox -s verify (this is a UID-less branch, so requirement gates run with --skip-requirement). Diff-inspect that no external import line referencing the four modules changed. Equality of public API + equality of behavior under the existing suite is the contract; no pre-existing test is modified except the two enforcement-preserving discovery updates above.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #51 (branch 51-split-sdl-oversized-modules)
Diff mode: manifest — the complete diff exceeded one prompt and was reviewed as 2/2 inline slice(s) (file-slices) covering 29/29 file(s)

Core review

Verdict: ship

Slice 1/2: This slice is shaped correctly as a behavior-preserving module-to-package refactor. Each original dotted module remains the facade, implementation code is partitioned along cohesive domain seams, canonical validation, vocabulary, manifest, topology, and evidence helpers remain with their existing owners, and dependency direction stays acyclic and within the declared layers. The runtime invariant discovery is appropriately made package-aware, while objective dependency partitioning deliberately preserves the facade-level monkeypatch seam. The structure accommodates further internal decomposition without exposing child modules or introducing speculative abstractions; I would ship this slice.

Slice 2/2: This slice cleanly completes the module-to-package migrations at their documentation and policy seams: the SDL reference catalog and its parity checker point to the new canonical package entry points, while the oversized-file exemptions for the decomposed modules are retired. The changes preserve the existing catalog-checking mechanism rather than duplicating it, respect the package boundary by treating each init.py as the public semantic surface, and leave the internal package layout free to evolve. This is shaped correctly.

No blocking findings.

Security review

Verdict: ship

Slice 1/2: This slice is shaped correctly as a facade-preserving module-to-package refactor. It keeps the existing validation, semantic-analysis, controlled-vocabulary, redaction, and evidence-assembly seams intact while moving cohesive implementation details into private child modules. The security-sensitive boundaries—runtime secret redaction, fail-closed semantic registries, participant visibility checks, allowlisted evidence projection, and validated persistence remaining outside assembly—are neither bypassed nor weakened, and the package shape leaves room for further internal partitioning without expanding the public or filesystem-facing attack surface.

Slice 2/2: This slice is shaped correctly: it updates SDL catalog references and parity-check constants to follow the new package entry points, while removing obsolete oversized-file exemptions after the package split. The design seam remains the public package interface, and these documentation and policy changes introduce no executable input, authorization, secret-handling, data-exposure, or supply-chain path that creates a concrete security vulnerability.

No blocking findings.

[Brad-Edwards]

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

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: Slice 1/2: This slice is shaped correctly as a behavior-preserving module-to-package refactor. Each original dotted module remains the facade, implementation code is partitioned along cohesive domain seams, canonical validation, vocabulary, manifest, topology, and evidence helpers remain with their existing owners, and dependency direction stays acyclic and within the declared layers. The runtime invariant discovery is appropriately made package-aware, while objective dependency partitioning deliberately preserves the facade-level monkeypatch seam. The structure accommodates further internal decomposition without exposing child modules or introducing speculative abstractions; I would ship this slice.

Slice 2/2: This slice cleanly completes the module-to-package migrations at their documentation and policy seams: the SDL reference catalog and its parity checker point to the new canonical package entry points, while the oversized-file exemptions for the decomposed modules are retired. The changes preserve the existing catalog-checking mechanism rather than duplicating it, respect the package boundary by treating each init.py as the public semantic surface, and leave the internal package layout free to evolve. This is shaped correctly.

Security reviewer: Slice 1/2: This slice is shaped correctly as a facade-preserving module-to-package refactor. It keeps the existing validation, semantic-analysis, controlled-vocabulary, redaction, and evidence-assembly seams intact while moving cohesive implementation details into private child modules. The security-sensitive boundaries—runtime secret redaction, fail-closed semantic registries, participant visibility checks, allowlisted evidence projection, and validated persistence remaining outside assembly—are neither bypassed nor weakened, and the package shape leaves room for further internal partitioning without expanding the public or filesystem-facing attack surface.

Slice 2/2: This slice is shaped correctly: it updates SDL catalog references and parity-check constants to follow the new package entry points, while removing obsolete oversized-file exemptions after the package split. The design seam remains the public package interface, and these documentation and policy changes introduce no executable input, authorization, secret-handling, data-exposure, or supply-chain path that creates a concrete security vulnerability.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #51

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 51-split-sdl-oversized-modules
Cycle: 1 / 1
Findings: 1

Finding 1 — [warning] implementations/python/tests/test_runtime_family_invariants.py:383-397 (_runtime_family_enums)

Problem: For a runtime_* package family, enum discovery relies on vars(module) of the package's __init__.py, i.e. only enums the __init__.py explicitly imports/re-exports are seen. An enum class defined in a private submodule (e.g. runtime_security_monitoring/_enums.py) that is never imported into __init__.py is invisible to _runtime_family_enums() and therefore to test_runtime_enums_open_or_closed_not_single_sentinel, even though the sibling lint in this same diff (test_runtime_modules_do_not_redeclare_shared_validation_helpers) was fixed to walk the real files via ast.parse specifically to avoid this kind of file-shape blind spot.
Why it matters: A future engineer adding a single-sentinel enum (e.g. only unknown, no other) to a runtime_* package's private submodule but forgetting to add it to __init__.py's imports/__all__ would violate the open-or-closed sentinel convention and the drift lint would report zero offenders — exactly the drift this test suite exists to catch, and exactly the scenario its own docstring claims is covered ("Any future runtime enum introduced in a single-sentinel state fails here").
Fix: Discover runtime-family enums the same way the redeclaration check does: walk the family's actual .py files (flat module or runtime_*/**/*.py package files) with ast.parse and collect class definitions that subclass Enum, instead of trusting vars(module) on the re-exporting __init__. Alternatively, add an assertion (mirroring test_contracts_facade_exports.py's facade-manifest check) that every Enum subclass defined anywhere under a runtime_* package is present in that package's __all__, so an unexported enum fails loudly instead of silently opting out of the sentinel lint.

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #51 on branch '51-split-sdl-oversized-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 #51)

Reviewer: test-quality
Cycle: 1

Architectural read:

This is a narrow, mechanical adaptation of two existing structural-invariant lints (DSL-139) so they keep enforcing after runtime_security_monitoring.py becomes a package (runtime_security_monitoring/{__init__,_enums,_models}.py). The shape is right: rather than adding new lints, it widens the discovery surface of the two lints whose discovery logic was file-shape-coupled. The redeclaration check (test_runtime_modules_do_not_redeclare_shared_validation_helpers) is fixed the robust way — it now globs runtime_*/**/*.py and AST-parses every physical file, so it is agnostic to how many files a family is split across. The enum-sentinel check (_runtime_family_enums) is fixed the weaker way — it still discovers enums via vars(module) on the imported package, so for a package family it only sees what __init__.py re-exports, not what actually exists in the family's private submodules. That's an asymmetry within the same diff: one fix is shape-agnostic, the other trusts a convention (complete re-export) that nothing in this diff — or elsewhere in the suite except the unrelated raes_contracts.contracts facade check — actually verifies. For the one package this diff splits today, the re-export happens to be complete, so there's no live false-negative, but the mechanism itself is weaker than its neighbor and the module's own docstring overstates the guarantee ("Any future runtime enum introduced in a single-sentinel state fails here").

Blocking findings: 1

Finding 1 — one-off

• ID: F1
• Title: (no title)
• Decision: fix
• Rationale: Addressed by next cycle