extend architecture enforcement to orchestration code (2.4.5)

[leynos]

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

• Split structured generation LangGraph orchestration into ports-only node code
  and an application-tier graph builder behind the existing public facade.
• Added Hecate groups for orchestration nodes, orchestration builders, Celery
  tasks, and checkpoint payload DTOs.
• Extracted WorkloadClass into a provider-neutral worker contract so Celery
  tasks can depend on domain/application contracts without importing Kombu.
• Added checkpoint payload boundary checks, including structural and property
  coverage for the checkpoint serializer allow-list.
• Added BDD architecture scenarios, normalized Hecate JSON snapshot coverage,
  and a direct Vidai Mock-backed LangGraph plan -> execute -> finish test.
• Recorded ADR-016 and updated architecture, developer, roadmap, and execution
  plan documentation.

Validation

• make check-fmt
• make test (1030 passed, 3 skipped)
• make typecheck
• make lint
• make markdownlint
• make nixie
• coderabbit review --agent after M0, M1, M2, M3, and M4; each completed with
  0 findings.

References

• ExecPlan: docs/execplans/2-4-5-extend-architecture-enforcement-to-orchestration-code.md
• Roadmap item: docs/roadmap.md → 2.4.5
• ADR: docs/adr/adr-016-orchestration-architecture-enforcement.md
• Lody session: https://lody.ai/leynos/sessions/a4bfa5ba-40b9-4ed7-84fa-2e98f541173b

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a6cb7bb6-0444-4b0f-9555-8a1640f2ec68

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 2-4-5-extend-architecture-enforcement-to-orchestration-code

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[leynos]

@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 Method

tests/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.

[leynos]

@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 Method

tests/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 examples

To 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);
+}
+

[codescene-access]

No quality gates enabled for this code.