Orchestrata Ultimate › Plans › plan_subphase_0_2 › subplan-port-core-2026-04-12
Subplan: Sub-phase 0.2 — Port orchestrata-core (Steps 12-27)
Source: plans/plan_subphase_0_2/subplan-port-core-2026-04-12.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-04-12 · 148 lines.
Prose pending.
Plan text
Subplan: Sub-phase 0.2 — Port orchestrata-core (Steps 12-27)
Context
Sub-phase 0.1 bug fixes and coverage remediation are complete. 576 tests pass at 96% coverage on target files. This subplan ports 16 modules (~3,747 LOC) from orchestrata-core into orchestrata-ultimate.
Source (read-only): /home/mohamed/workspace/orchestrata/packages/orchestrata-core/src/orchestrata/core/
Target: /home/mohamed/workspace/orchestrata-ultimate/src/orchestrata_ultimate/
Coverage gate: --cov-fail-under=90 on all ported files. Every ported module must have tests.
Traceability: Every public class and method implementing a REQ must have @traces("REQ-0.2-XXX").
Coverage Targets
| File | Target | Scope |
|---|---|---|
| core/protocols.py | 90% | All Protocol classes importable, runtime_checkable verified |
| core/config/infra.py | 90% | All env defaults exercised |
| core/config/manager.py | 90% | Config loading, validation, defaults |
| core/redis.py | 90% | Factory + in-memory fallback |
| core/state.py | 90% | State manager operations |
| core/cache.py | 90% | LRU cache hit/miss/eviction |
| core/metrics/monitoring_engine.py | 90% | Engine start/stop/record |
| core/metrics/spans.py | 90% | Span creation/completion |
| core/domain/error.py | 90% | Error hierarchy |
| core/domain/repository.py | 90% | Base repository operations |
| core/domain/service.py | 90% | Base service lifecycle |
| core/standards.py | 90% | Standards constants accessible |
| core/enums.py | 90% | Enum members accessible |
Steps
Step 12: Create core/protocols.py from interfaces (1,231 + 45 LOC)
- Source:
interfaces/__init__.py+interfaces/volk.py - Dest:
core/protocols.py - Convert
class I<Name>(ABC)toclass <Name>Protocol(Protocol)with@runtime_checkable - Keep concrete classes (ComponentType, HealthStatus, etc.) as-is
- Fix Python 2 except syntax if present
- @traces("REQ-0.2-001") on each Protocol class
Step 13: Port traceability bridge to core/tracing/traceability.py
- Source:
traceability/__init__.py - Dest:
core/tracing/traceability.py(re-export bridge for import translation) - Do NOT overwrite existing
core/traceability/traceability_utils.py
Step 14: Create core/config/ subpackage
- Source:
config/__init__.py(19 LOC) +config/manager.py(788 LOC) - Dest:
core/config/__init__.py+core/config/manager.py - @traces("REQ-0.2-002") on ConfigManager
Step 15: Port infra_config.py to core/config/infra.py (177 LOC)
- CRITICAL: Fix ALL os.environ["X"] reads to .get() with defaults
- @traces("REQ-0.2-002") on InfraConfig
Step 16: Port adapters/claude/ (4 files)
- Source:
adapters/claude/(hooks.py, tool_interceptor.py, init.py files) - Dest:
adapters/claude/ - @traces("REQ-0.2-003") on public classes
Step 17: Merge monitoring/ into core/metrics/
- Source:
monitoring/engine.py(402 LOC) +monitoring/spans.py(93 LOC) - Dest:
core/metrics/monitoring_engine.py+core/metrics/spans.py - @traces("REQ-0.2-004") on MonitoringEngine, Span
Step 18: Port base/ into core/domain/
- Source:
base/error.py,base/repository.py,base/service.py - Dest:
core/domain/error.py,core/domain/repository.py,core/domain/service.py - Do NOT overwrite existing domain_entity.py or node.py
- Change BaseEntity references to DomainEntity
- @traces("REQ-0.2-005") on BaseService, BaseRepository
Step 19: Port redis_factory.py to core/redis.py (181 LOC)
- Fix os.environ reads
- Add in-memory fallback (InMemoryRedis class)
- @traces("REQ-0.2-006") on create_redis_client
Step 20: Port state/state_manager.py to core/state.py (170 LOC)
- @traces("REQ-0.2-007") on StateManager
Step 21: Port standards.py (190 LOC)
- @traces("REQ-0.2-007")
Step 22: Port lru_cache.py to core/cache.py (126 LOC)
- @traces("REQ-0.2-007") on LRUCache
Step 23: Port enums.py (10 LOC) + paths.py (30 LOC)
- @traces("REQ-0.2-007")
Step 24: Port domain/enums/ subdirectory
- @traces("REQ-0.2-008")
Step 25: Port graph_directives.py (43 LOC)
- @traces("REQ-0.2-008")
Step 26: Update core/init.py with new exports
Step 27: Gate check
- All imports verified
- Tests pass (>=576)
- Coverage gate: --cov-fail-under=90 on ported modules
- All @traces decorators present
Import Translation
Apply to every ported file:
from orchestrata.core.interfaces->from orchestrata_ultimate.core.protocolsfrom orchestrata.core.infra_config->from orchestrata_ultimate.core.config.infrafrom orchestrata.core.base.entity->from orchestrata_ultimate.core.domain.domain_entityfrom orchestrata.core.base->from orchestrata_ultimate.core.domainfrom orchestrata.core.redis_factory->from orchestrata_ultimate.core.redisfrom orchestrata.core.lru_cache->from orchestrata_ultimate.core.cachefrom orchestrata.core.monitoring->from orchestrata_ultimate.core.metricsfrom orchestrata.core.state.->from orchestrata_ultimate.core.state.from orchestrata.->from orchestrata_ultimate.
os.environ Defaults
| Key | Default |
|---|---|
| REDIS_HOST | "localhost" |
| REDIS_PORT | "6379" |
| NEO4J_URI | "bolt://localhost:7687" |
| NEO4J_USERNAME | "neo4j" |
| NEO4J_PASSWORD | "" |
| LOG_LEVEL | "INFO" |
Requirements
| REQ ID | Description |
|---|---|
| REQ-0.2-001 | protocols.py: ABC -> Protocol conversion, all importable |
| REQ-0.2-002 | config/: manager + infra, all os.environ safe |
| REQ-0.2-003 | adapters/claude/: hooks + tool_interceptor importable |
| REQ-0.2-004 | metrics/: monitoring_engine + spans importable |
| REQ-0.2-005 | domain/: error + repository + service importable |
| REQ-0.2-006 | redis.py: factory + in-memory fallback working |
| REQ-0.2-007 | state, standards, cache, enums, paths importable |
| REQ-0.2-008 | graph_directives + domain/enums importable |
| REQ-0.2-009 | All os.environ["X"] use .get() with defaults |
| REQ-0.2-010 | Tests pass (>=576), coverage >=90% on ported files |