Skip to content

SPDX-License-Identifier: AGPL-3.0-or-later

Commercial license available

(c) Concepts 1996-2026 Miroslav Sotek. All rights reserved.

(c) Code 2020-2026 Miroslav Sotek. All rights reserved.

ORCID: 0009-0009-3560-0851

Contact: www.anulum.li | protoscience@anulum.li

SCPN Phase Orchestrator - Product boundaries

Product boundaries

SCPN Phase Orchestrator is organised around four product boundaries. Every boundary described here is production code: the split exists for convenience, maintainability, dependency ownership, and reviewability, not to divide the repository into older and newer quality tiers. Pre-split public import paths may remain during migration windows only when they are explicitly maintained and tested as production surfaces.

Core Engine

Core Engine contains the deterministic mathematical and phase-control substrate: binding, oscillators, coupling, UPDE engines, monitors, core actuation models, imprint state, SSGF primitives, reactor-semantic contracts and codecs, and the minimal supervisor types required to run phase-control decisions.

Reactor Semantics belongs to Core Engine because its canonical records, registries, validation, and serialization are dependency-light deterministic contracts. Producer-specific adapters decode supplied review envelopes without importing or executing sibling projects. This classification does not promote the records to control authority: reactor-semantic outputs remain review-only and non-actionable, and CONTROL admission and machine protection stay outside this package.

Core Engine must remain free of serving, tenancy, external system, notebook, bridge, and experimental runtime dependencies. Runtime, integrations, and research surfaces may depend on Core Engine; Core Engine must not depend on those surfaces.

Runtime and Serving

Runtime and Serving contains process orchestration and operator surfaces: CLI, HTTP, gRPC, replay, audit streams, state backends, authentication, tenancy, observability glue, Studio, QueueWaves serving, and generated transport code.

Runtime may depend on Core Engine and integrations, but Runtime owns process lifetime and request/response behaviour. Core Engine must not import Runtime.

Integrations

Integrations contains external system adapters: Redis, Modbus, OpenTelemetry, hardware IO, BCI/LSL, Prometheus, Remanentia, NeuroCore, Fusion Core, Plasma Control, and related bridge adapters.

Integrations must stay optional where their dependencies are optional. Missing external dependencies must fail with explicit, local errors instead of leaking into Core Engine import time. Integrations may depend on Core Engine contracts, but must not import Runtime/Serving or Research/Experimental modules.

Research and Experimental

Research and Experimental contains neural-network research modules, notebooks, experiments, Go/Julia/Mojo/WebGPU accelerator implementations, visualisation helpers, and special domain packs that are not required for the production Runtime surface. It also contains autotuning pipelines and public neural-network compatibility surfaces until those surfaces are split behind explicit optional package extras.

Experimental modules may depend on Core Engine for parity and validation, but Core Engine must not import arbitrary Experimental modules. Accelerator implementations live under scpn_phase_orchestrator.experimental.accelerators.{coupling,monitor,upde}. Core dispatch modules may import only the explicit accelerator-port modules listed in tools/check_product_boundaries.py; pre-split module paths under coupling, monitor, and upde are production boundary forwarding modules. The accelerator-port allowlist is self-auditing: full-tree runs fail if an entry becomes stale, forcing migrated dispatch ports to be removed from the exception set instead of leaving dead architecture debt behind.

Enforcement

tools/check_product_boundaries.py is the first enforcement rail. It parses Python imports and fails when Core Engine imports Runtime, Integrations, or Research/Experimental modules. It also fails when Integrations import Runtime/Serving or Research/Experimental modules, preserving the adapter layer as an optional boundary around external systems.

Every first-party top-level package must be assigned to one of the four boundaries. The checker fails on unclassified source modules and unclassified first-party imports, so new surfaces cannot bypass the architecture contract by landing outside the boundary map.

This guard deliberately starts with the highest-value invariant: Core Engine is the stable lower layer. Later migration batches should add stricter rules for Runtime-to-Experimental coupling and optional integration dependency isolation after those imports are inventoried and production forwarding surfaces are in place.

Why boundary enforcement protects release quality

The checker is intentionally strict because it is cheaper to reject a bad dependency edge at build time than to debug a production import path after a live rollout.

Operationally this gives:

  • bounded change impact for integration updates,
  • predictable CI outcomes across optional stack combinations,
  • and a clear escalation path when an experimental module must move toward production obligations.

Every boundary review cycle should end with a deliberate classification decision and explicit evidence that the decision is reflected in the checker configuration.

Why boundary splits are operationally required

The four-boundary model is not only a design diagram. It is the way release control avoids accidental coupling between optional experimental code and the stable runtime path.

For each lane:

  • production failures in one boundary should not require changes in unrelated boundaries,
  • optional adapter layers can be removed or replaced without changing Core Engine contracts,
  • and import violations are detected with the same checks used for every release.

Use the boundary map as the first step before adding a new module: classify it, add the ownership, then validate imports.