extend architecture enforcement to orchestration code (2.4.5) - #143
extend architecture enforcement to orchestration code (2.4.5)#143leynos wants to merge 24 commits into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Summary
Validation passed: 1030 tests passed, 3 skipped, alongside formatting, type checking, linting, markdown linting, Nixie and staged CodeRabbit reviews. WalkthroughThis change extends Hecate enforcement to orchestration modules, introduces provider-neutral payload DTOs and JSON checkpoint validation, splits graph nodes from assembly, centralizes structured logging, adds worker workload contracts, and expands documentation, fixtures, architecture tests, snapshots, and integration coverage. ChangesOrchestration architecture enforcement
Sequence Diagram(s)sequenceDiagram
participant Request
participant Planner
participant LangGraph
participant ToolExecutor
participant Checkpoint
participant CostRecorder
Request->>LangGraph: submit generation request
LangGraph->>Planner: plan request
Planner-->>LangGraph: planner result
LangGraph->>ToolExecutor: execute ordered actions
ToolExecutor-->>LangGraph: action results
LangGraph->>Checkpoint: suspend or persist checkpoint state
LangGraph->>CostRecorder: record provider usage
LangGraph-->>Request: orchestration result
Possibly related PRs
Suggested labels: Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 18 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (18 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning Your free Security trial is over. An organization admin can activate billing to continue. Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
d6ec9f0 to
ec44417
Compare
lodyai
Bot
changed the title
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph. If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced. Large Methodtests/test_architecture_hecate_config.py: test_fixture_config_writes_expected_toml_shape What lead to degradation?test_fixture_config_writes_expected_toml_shape has 85 lines, threshold = 70 Why does this problem occur?Overly long functions make the code harder to read. The recommended maximum function length for the Python language is 70 lines of code. Severity: Brain Method - Complex Method - Long Method. How to fix it?We recommend to be careful here -- just splitting long functions don't necessarily make the code easier to read. Instead, look for natural chunks inside the functions that expresses a specific task or concern. Often, such concerns are indicated by a Code Comment followed by an if-statement. Use the EXTRACT FUNCTION refactoring to encapsulate that concern. |
|
@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph. If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced. Complex Methodtests/test_checkpoint_payload_boundaries.py: _is_provider_neutral_origin What lead to degradation?_is_provider_neutral_origin has a cyclomatic complexity of 10, threshold = 9 Why does this problem occur?A Complex Method has a high cyclomatic complexity. The recommended threshold for the Python language is a cyclomatic complexity lower than 9. How to fix it?There are many reasons for Complex Method. Sometimes, another design approach is beneficial such as a) modeling state using an explicit state machine rather than conditionals, or b) using table lookup rather than long chains of logic. In other scenarios, the function can be split using EXTRACT FUNCTION. Just make sure you extract natural and cohesive functions. Complex Methods can also be addressed by identifying complex conditional expressions and then using the DECOMPOSE CONDITIONAL refactoring. Helpful refactoring examplesTo get a general understanding of what this code health issue looks like - and how it might be addressed - we have prepared some diffs for illustrative purposes. SAMPLE# complex_method.js
function postItem(item) {
if (!item.id) {
- if (item.x != null && item.y != null) {
- post(item);
- } else {
- throw Error("Item must have x and y");
- }
+ // extract a separate function for creating new item
+ postNew(item);
} else {
- if (item.x < 10 && item.y > 25) {
- put(item);
- } else {
- throw Error("Item must have an x and y value between 10 and 25");
- }
+ // and one for updating existing items
+ updateItem(item);
}
}
+
+function postNew(item) {
+ validateNew(item);
+ post(item);
+}
+
+function updateItem(item) {
+ validateUpdate(item);
+ put(item);
+}
+ |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
589a65e to
bd7312d
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
5cb6ed4 to
145a65f
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Draft the ExecPlan for roadmap item 2.4.5, which extends Hecate architecture enforcement to LangGraph orchestration code, Celery tasks, and checkpoint payloads. The plan reconciles the roadmap's "ports only" wording with the system design's "domain services and ports only", and proposes three new first-match Hecate groups (orchestration, orchestration_tasks, orchestration_checkpoint) plus two boundary fixes surfaced during research: extracting WorkloadClass out of the kombu-coupled worker topology module, and decoupling checkpoint DTOs from the application-tier generation DTO barrel. It also resolves the existing 400-line limit breach in langgraph.py via a node/builder split. Enforcement is validated through synthetic architecture fixtures (positive and negative), a structural reflection test and a Hypothesis property test for checkpoint payloads, a syrupy snapshot of Hecate output, a pytest-bdd feature, and a vidai-mock-backed behavioural test of the generation graph. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mark the 2.4.5 ExecPlan as in progress and record the clean rebase, post-rebase validation, PR title update, and active Lody session reference.
Extend the synthetic Hecate fixture config with orchestration node, task, and checkpoint groups so upcoming production rules have red harness coverage before the real `pyproject.toml` policy changes. Add positive and negative fixture packages for LangGraph nodes, Celery tasks, checkpoint payloads, and grouped adapter guard cases. Record M0 completion and validation evidence in the ExecPlan.
Update the 2.4.5 ExecPlan with the CodeRabbit result for the M0 fixture-harness milestone so the plan remains resumable.
Move LangGraph node functions and graph assembly into focused modules so architecture enforcement can target graph orchestration separately.
Note the zero-finding CodeRabbit review for the orchestration graph split milestone.
Move WorkloadClass into a provider-neutral worker module so task architecture enforcement no longer depends on the Kombu topology module.
Note the zero-finding CodeRabbit review for the worker workload contract milestone.
Add a provider-neutral orchestration payload DTO core and retarget checkpoint serialization away from the application-coupled DTO barrel. Group checkpoint payload modules under Hecate, add JSON-shape and structural payload boundary tests, and record the M3 decisions in the ExecPlan.
Record the clean CodeRabbit review result for the checkpoint payload boundary milestone before starting the final behavioural and documentation work.
Add behavioural and snapshot coverage for orchestration architecture boundaries, including Vidai Mock coverage for the direct LangGraph path. Record ADR-016, update maintainer documentation, and mark roadmap item `2.4.5` complete.
Update the orchestration enforcement execplan with the clean CodeRabbit review result after the M4 documentation and test coverage milestone.
Reconstruct the first-match architecture group ordering after the rebase silently duplicated the outbound adapter table. Preserve main’s updated LLM adapter prefix while restoring the branch’s orchestration, checkpoint, and worker task boundaries.
Apply the Oxford spelling forms required by the new repository spelling gate, regenerate the typos configuration, and remove a duplicated ingestion workflow block exposed by Markdown lint.
Replace conditional generic-origin validation with a validator dispatch table while preserving recursive payload-boundary semantics. Add direct parametrized coverage for every supported origin category and unsupported generics.
Separate base architecture expectations from orchestration-specific group expectations while keeping the fixture config test as the orchestration point.
Set the ExecPlan status to `COMPLETE` and remove the stale M4 outstanding-work statement while preserving the completed milestone and gate records.
Show the IO-bound workload member and its serialized value in both the module and class docstrings.
Document the dedicated `orchestration_nodes` boundary and its checkpoint DTO and domain-port dependencies. Use `episodic.worker.workloads.WorkloadClass` as the canonical task contract, while identifying the topology path as a compatibility alias only.
Mark the ExecPlan complete and replace stale M4 implementation claims with a completed outcome while retaining the milestone and final-gate evidence.
Give graph nodes their own strict Hecate group while allowing broader orchestration modules to assemble them. Align architecture documentation, fixture typing, diagnostics, and command-format coverage with the production policy.
Normalize non-JSON structured log fields and require checkpoint payloads to survive JSON round trips without data loss. Cover representative logging values and lossy checkpoint shapes.
Use slotted graph extensions, pass finish callbacks their DTO directly, and replace payload-boundary Any types with provider-neutral protocols. Guard Vidai Mock cleanup before process startup.
Preserve architecture fixture semantics while satisfying the stricter lint rules from `main`. Remove the obsolete command snapshot after parametrizing its text and JSON formats, and restore documentation required by current public-function checks.
d161200 to
5b1e8aa
Compare
There was a problem hiding this comment.
Gates Failed
(1 new file with code health below 10.00)
(1 file with Code Duplication)
Our agent can fix these. Install it.
Gates Passed
Reason for failure
| New code is healthy | Violations | Code Health Impact | |
|---|---|---|---|
| test_checkpoint_payload_boundaries.py | 1 rule | 9.39 | Suppress |
| Enforce advisory code health rules | Violations | Code Health Impact | |
|---|---|---|---|
| test_checkpoint_payload_boundaries.py | 1 advisory rule | 9.39 | Suppress |
Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.
1 participant
Summary
This pull request completes roadmap item 2.4.5 — Extend architecture
enforcement to orchestration code.
The branch extends Hecate architecture checks over orchestration-facing code,
splits LangGraph node logic from graph composition, extracts a provider-neutral
worker workload contract, and adds checkpoint payload boundary enforcement.
What changed
and an application-tier graph builder behind the existing public facade.
tasks, and checkpoint payload DTOs.
WorkloadClassinto a provider-neutral worker contract so Celerytasks can depend on domain/application contracts without importing Kombu.
coverage for the checkpoint serializer allow-list.
and a direct Vidai Mock-backed LangGraph
plan -> execute -> finishtest.plan documentation.
Validation
make check-fmtmake test(1030 passed, 3 skipped)make typecheckmake lintmake markdownlintmake nixiecoderabbit review --agentafter M0, M1, M2, M3, and M4; each completed with0 findings.
References
docs/execplans/2-4-5-extend-architecture-enforcement-to-orchestration-code.mddocs/roadmap.md→ 2.4.5docs/adr/adr-016-orchestration-architecture-enforcement.md