[ISSUE-11] Implement lvl2 assembly stage and engineered-region blockers

[Gonza10V]

Motivation

• Add a deterministic level-2 assembly stage to resolve SBOL ModuleDefinition designs, select bounded lvl2 routes, promote missing engineered regions to lvl1 blockers, and invoke the AssemblyService only for complete routes.

Description

• New AssemblyLvl2Stage (added src/buildcompiler/stages/assembly_lvl2.py) that resolves the source ModuleDefinition, extracts engineered-region identities from region_order, planner constraints, or ModuleDefinition.functionalComponents, and delegates route enumeration/selection to CompatibilitySelector.select_lvl2_route(...).
• Converts selector output into stable route artifacts (selected_route + up to 3 rejected_routes) stored in StageResult.protocol_artifacts and promotes any missing_region_identities into MissingBuildInput records with missing_kind="engineered_region" and required_stage=BuildStage.ASSEMBLY_LVL1.
• Blocks on missing backbone/restriction-enzyme/ligase by returning structured MissingBuildInput records, and only calls AssemblyService.run(...) when the selected route is complete; on success it indexes generated products into Inventory while appending insert_identities and source_stage metadata and emits a compiler-only PUDU JSON intermediate via assembly_route_to_pudu_json(...).
• Exported AssemblyLvl2Stage from src/buildcompiler/stages/__init__.py and added unit tests in tests/unit/stages/test_assembly_lvl2.py covering success, empty-region failure, engineered-region promotion, large-order blocking, and hard region_order constraint behavior.

Testing

• Import smoke checks succeeded: python -c "from buildcompiler.stages import AssemblyLvl1Stage", python -c "from buildcompiler.inventory import CompatibilitySelector", python -c "from buildcompiler.inventory.compatibility import Lvl2Route, RouteSelection", python -c "from buildcompiler.sbol import AssemblyService, AssemblyJob, AssemblySbolResult", and python -c "from buildcompiler.adapters.pudu import assembly_route_to_pudu_json" all passed.
• Unit tests: pytest tests/unit/stages/test_assembly_lvl2.py passed, and the full unit test suite pytest tests/unit/domain tests/unit/api tests/unit/inventory tests/unit/planning tests/unit/sbol tests/unit/stages tests/unit/adapters passed (59 tests, all passed).
• Verification commands: uv run pytest tests/unit/stages/test_assembly_lvl2.py failed due to environment network restriction when attempting to fetch optional dependency SBOLInventory (HTTP 403), so local pytest was used as fallback and passed; ruff check . and ruff format --check . reported pre-existing repo-wide issues outside the scope of this change while the modified files pass ruff checks.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3fdcf3e0c9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve full region set when applying region_order

_extract_region_identities currently returns constraints["region_order"] directly, which drops any engineered regions not listed there and changes the requested region set before routing. That bypasses the hard validation in CompatibilitySelector.select_lvl2_route (which compares region_order against the requested regions) and can let lvl2 assembly proceed for only a subset of a ModuleDefinition when region_order is incomplete. In practice, a request with two module functional components and region_order containing one identity will assemble a partial product instead of blocking on a constraint mismatch.

Useful? React with 👍 / 👎.

[Gonza10V]

@codex good catch, fix this issue

[chatgpt-codex-connector]

Summary

• Fixed AssemblyLvl2Stage._extract_region_identities(...) so region_order is no longer treated as the requested engineered-region set. The method now only uses explicit identity constraints (engineered_region_identities / region_identities) or falls back to all ModuleDefinition.functionalComponents, which preserves full-region validation behavior. src/buildcompiler/stages/assembly_lvl2.pyL216-L229
• Added a regression test that verifies an incomplete region_order causes lvl2 to block (no selected route) instead of proceeding with a partial assembly. tests/unit/stages/test_assembly_lvl2.pyL194-L207

Testing

• ✅ pytest -q tests/unit/stages/test_assembly_lvl2.py

Committed to current branch:

• 1264eba

View task →