scpn-phase-orchestrator 1.0.0

Domain-agnostic synchronisation-analysis and honest-evaluation toolkit built on Kuramoto/UPDE phase dynamics

SCPN Phase Orchestrator

Many systems succeed or fail on timing. When thousands of microservices retry in the same instant, the synchronised surge takes the cluster down. When generators on a power grid drift out of step, the grid trips. When neurons fire in lockstep, it looks like a seizure. When fusion-plasma modes phase-lock, the reactor disrupts. These look like unrelated incidents, but they are one problem wearing different clothes: coupled rhythms drifting into — or out of — sync.

SCPN Phase Orchestrator (SPO) is an auditable assurance envelope for that problem — a Python library and CLI that wraps synchronisation analysis in sealed, replayable evidence with honest, false-alarm-controlled claim boundaries rather than one confident number. It takes the repeating signals a system already produces — waveforms, event streams, state changes — turns them into a shared language of phase (where each rhythm sits in its cycle), and gives operators a way to ask three questions, each answer bound to a reproducible record:

1. What is locking together, and is that lock useful or dangerous?
2. Is the system's damping falling toward a regime change? SPO estimates this where the signature is a physically deterministic mode — e.g. a grid oscillation, checked against small-signal eigenvalues. On noisier domains, generic early-warning detection is at chance at an honest operating point, and SPO is built to report that rather than overclaim (see Evidence status below).
3. Which single, bounded knob could steer it back — as a reviewable, replayable proposal, before anything touches hardware.

The same representation applies to a grid operator, an SRE chasing retry storms, a plasma physicist, or a neuroscientist, because underneath these are coupled-oscillator systems. SPO ships bindings for 36 such domains (power grids, fusion, cloud queues, cardiac and EEG rhythms, swarm robotics, traffic, markets, and more) — a binding is a reusable scaffold, not a validated detector for that domain — and it never actuates blindly: every proposed change is bounded, rate-limited, and audit-logged for human review.

For specialists, in one line: an auditable synchronisation-analysis and honest-evaluation toolkit built on Kuramoto/UPDE phase dynamics — every alarm and control proposal sealed as replayable evidence — with a review-only control-proposal surface. New here? Start with Use Cases and Value Map or the Executive Overview.

Prefer to run something first? pip install scpn-phase-orchestrator && spo quickstart evidence re-verifies a real sealed record's cryptographic seals in front of you and prints its honest, review-only verdict — you need not take our word for it. The whole honesty loop is four spo quickstart targets in about five minutes: simulate (power/eeg), re-verify real evidence, and auditor a detector against a null. See the Quickstart.

Stable release (v1.0.0) — The core UPDE engine, 3-channel oscillator extraction (P/I/S), supervisor with regime management, and Rust FFI acceleration are functional and guarded by local and CI verification gates. Public capability counts are generated from the manifest below rather than maintained by hand. The public Python API — the symbols exported from scpn_phase_orchestrator.__all__ — is now covered by semantic-versioning guarantees; backward-incompatible changes to it will bump the major version. Internal modules outside that surface may still evolve.

Version: 1.0.0 Status: first stable release; public API under semantic versioning; public inventory is generated below.

Badge notes: CI, CodeQL, Scorecard, docs, package, and coverage badges are status pointers. Capability counts are generated by tools/capability_manifest.py; benchmark, hardware, security, and release claims require their dedicated evidence pages and GitHub run records.

Current Release Boundary

Version 1.0.0 is the first stable release: the public Python API — the symbols exported from scpn_phase_orchestrator.__all__ — is now covered by semantic-versioning guarantees. It consolidates the operator, evaluation, and assurance surfaces built up to the 0.12.0 baseline — including the honest early-warning auditor (scpn_phase_orchestrator.evaluation and spo audit-detector): score any detector's event-vs-null skill at a matched false-alarm rate, with a label-permutation p-value and a hash-sealed record — the productised form of the matched-false-alarm methodology, judging the SCPN suite, an AR(1)/Kendall-τ baseline, or a black-box classifier on identical footing. The release keeps the downstream accelerator chain in a single documented review boundary:

Release surface	What is now reviewable
PHA-C and polyglot gates	spatial, Doppler, moving-frame, delay, PID, Hodge, E/I-balance, winding, Poincaré, Koopman, ordinal-entropy, twin-confidence, swarmalator, inertial, hypergraph, spectral, and real-grid rows keep Rust, Go, Julia, Mojo, and Python evidence explicit
Governance and assurance	control-barrier filtering, certification packages, conformity reports, formal package evidence, post-quantum audit seals, SLSA/cosign release evidence, and production audit-key enforcement remain review-only
Operator surfaces	spo doctor, spo quickstart power, spo twin-confidence, spo chaos, spo supervisor-candidate, spo pmu-ieee-adapt, spo pmu-ringdown, spo audit-detector, OPC-UA/MQTT ingestion, and the WASM playground provide bounded, replayable entry points
Documentation posture	public API docstrings, generated capability inventory, real-data validation pages, architecture maps, release hygiene, and the current benchmark pages are aligned with code and CI gates
Benchmark posture	canonical reference-suite rows remain labelled as local non-isolated regression evidence unless production isolation metadata is present

This release does not claim live accelerator, quantum, neuromorphic, PLC, or medical actuation. Those remain adapter-scoped and disabled until a separate operator-approved hardware evidence chain exists.

Why This Exists

SPO is for systems where cyclic processes either need to lock together or must be kept from locking together: power grids, fusion plasmas, cloud retry storms, industrial machines, biological rhythms, traffic networks, robotic swarms, digital twins, and differentiable oscillator research. It gives those systems a shared language of phase, coupling, coherence, regime, and bounded control.

The product value is not only simulation. The repository combines domain binding specs, physical/informational/symbolic phase extraction, Kuramoto/UPDE dynamics, supervisor and audit surfaces, optional Rust acceleration, bounded adapter bridges, and differentiable JAX layers for topology and coupling optimisation.

SPO is therefore useful in four commercial situations:

Situation	What SPO adds
A plant, grid, service, or biological system has repeated behaviour	converts raw cycles, events, and states into comparable phase variables
Synchrony is valuable in one subsystem and dangerous in another	separates R_good from R_bad instead of treating coherence as one scalar
Control proposals must be explainable before they reach hardware	emits bounded, rate-limited, replayable review artefacts rather than hidden automation
A team needs one language across physics, software, and operations	represents coupling, lag, forcing, and target phase with the same K, alpha, zeta, and Psi contract

Start with the Use Cases and Value Map if you need to understand what the software is for before choosing an API.

Executive overview (What SPO Is and What It Is Not)

SPO is a synchronisation-analysis toolkit for systems that can be expressed as coupled oscillatory processes, with a review-only control-proposal surface. It gives teams a single interface for turning telemetry into phase variables, evaluating coherence, and proposing bounded control updates with replay evidence for human review — it does not close a control loop on hardware.

In practical terms, SPO is useful when:

• A domain has reusable cycle structure (time-of-day shifts, wave timing, phase-locked loops, rhythm-driven events, spatially propagating oscillations).
• Operational teams need explainable interventions before actuation, not black-box controller outputs.
• Governance requires deterministic evidence trails, policy guardrails, and cross-language consistency checks.

SPO is not a universal AI controller, a live PLC hardening platform, or a ready-made certified hardware stack. It is a synchrony-aware simulation and control framework that can be embedded in those ecosystems after domain validation and adapter-specific evidence are attached.

The immediate commercial value is the reduction of uncertainty in phase-control projects: instead of asking whether a system is "stable" from a single metric, teams get shared, auditable artefacts for what was measured, what was proposed, what was bounded, and what was replayed.

For a compact business, operator, and technical orientation, read the Executive Overview. It explains where SPO creates value, how the pieces fit together, which surfaces are execution-ready, and which frontier tracks remain review-only until external evidence is attached.

Evidence status: what is externally validated (and what is not)

To avoid overstating what SPO can do, this separates what has been checked against an independent ground truth from what has not.

Externally validated (against an independent reference):

• Grid modal damping estimation. On the IEEE-39 and Kundur systems, SPO's estimate of the dominant electromechanical mode's growth rate matches the small-signal eigenvalue from the ANDES simulator (study §3.9) — a checkable physical quantity, not a proxy.
• The eigenvalue regime map. Across five systems (fold, pitchfork, Hopf, and the unimodal and bimodal Kuramoto transitions) the shipped detectors recover the analytic eigenvalue's real part, and the correct estimator is regime-dependent (study §3.10–3.14).
• Honest, false-alarm-controlled evaluation. A matched-false-alarm operating point plus a permutation significance test plus a hash-sealed evidence record — a reproducible way to test any early-warning claim (study §2). Shipped as the detector-agnostic scpn_phase_orchestrator.evaluation package and the spo audit-detector CLI, which audit any detector's event-vs-null skill from its per-segment scores alone (see the auditor API).

Empirically at chance on real data, stated plainly: across five real modalities (grid, EEG, ecological/climate, molecular), generic early-warning detectors at an honest operating point perform at chance under a permutation-controlled test (study §3.1–3.8), consistent with the wider literature. SPO does not claim to predict tipping points in these domains. The one place a detector clears the bar is the grid, where the signature is a physically deterministic growing mode.

Not yet validated (engineering surfaces): closed-loop control, hardware / PLC / quantum / neuromorphic actuation, and live deployment are review-only and carry no field evidence.

In one line: SPO is a synchronisation-dynamics and honest-evaluation toolkit whose one externally-validated detection niche is grid modal damping against eigenvalues; it is not a validated general tipping-point predictor.

Reader Map

Reader	What to read first	Why
Domain expert	Use Cases and Value Map	decide whether the system has real phase/coherence structure
Operator or buyer	Executive Overview	understand value, risk boundaries, and deployment posture
Engineer	Quickstart	validate a domainpack and run a deterministic simulation
Python integrator	Python Facade API	embed reviewed local simulation without shelling out to Click
ML researcher	Differentiable Kuramoto	use JAX layers, SAF loss, inverse coupling, and accelerator checks
Reviewer	Release Hygiene	verify docs, benchmarks, CI, security, and release evidence

Evaluate It in This Order

The repository is large because it covers modelling, supervision, evidence, and deployment boundaries. Use this short route when deciding whether SPO fits a project:

1. Confirm the domain has phase structure. Read the Use Cases and Value Map and reject static problems that do not contain cycles, events, waves, stages, or repeated decisions.
2. Run a deterministic baseline. Use the Quickstart or spo demo --domain minimal_domain --steps 20 before adding a custom binding.
3. Bind real assumptions. Move domain knowledge into binding_spec.yaml, then validate it with spo validate.
4. Preserve evidence. Run with an audit log and replay it before using benchmark, dashboard, or policy outputs for review.
5. Escalate only bounded proposals. Keep hardware, external services, and controller writes behind adapter-specific safety gates.

The PHA-C downstream chain now publishes review-only formal obligations for moving-frame merge safety. Those manifests keep observed replay evidence, predictive residual slack, and predictive phase-drift slack in separate fixed-point fields before the Lean-targeted margins are accepted, so downstream MIF/FRC consumers can review what was observed and what was explicitly budgeted. The phase side is bound to the Lean PhaseBudgetBounds.budgetCertificate predicate and phase_budget_certificate_discharges_phase_lock theorem, keeping phase-drift review inside the same fixed-point proof lane as the spatial merge-window budget. Acceptance benchmark records expose formal_obligation_phase_budget_discharged so theorem metadata and arithmetic discharge must agree before the PHA-C row passes.

This order keeps the first experience practical while making the evidence boundary visible from the start.

Security and Formal Boundary Notes

• FastAPI/Starlette surfaces require starlette>=1.0.1,<2.0; QueueWaves production endpoints authenticate the matched route dependency and do not use request.url.path for authorization decisions.
• Binding specs are declarative data. spo validate --security <spec> adds a stricter lint pass for production-facing specs and rejects duplicate YAML keys plus executable-looking configuration strings.
• Release automation emits a CycloneDX SBOM, Python dependencies install from hash-pinned lockfiles in CI, and Rust CI includes cargo audit, cargo deny, and Miri smoke coverage for pure-Rust boundaries.
• Lean proof artefacts prove fixed-point certificate predicates over review manifests. They do not prove live hardware, plant, QPU, neuromorphic, or PLC safety without separate deployment evidence and operator approval.

Value Chain

SPO is most useful when a team needs all four layers together:

Layer	Question answered	Evidence produced
Domain binding	What counts as an oscillator, boundary, driver, and objective?	reviewed binding_spec.yaml plus schema validation
Dynamics	How do phases, couplings, lags, and forcing evolve?	deterministic Kuramoto/UPDE trajectories and order metrics
Supervision	Which regime are we in, and which proposal is bounded?	policy, Petri, STL, projector, and audit records
Productisation	Can an operator reproduce, reject, or promote the result?	replay logs, benchmark snapshots, Studio panels, and docs routes

The key product distinction is the combination of physics-grounded synchrony models with review-first control surfaces. SPO does not hide control decisions inside a dashboard or notebook; it turns them into inspectable artefacts.

SCPN Phase Orchestrator Capability Inventory

Surface	Current inventory
Package version	1.0.0
Public API exports	24
Python package modules	714
Core Engine modules	325
Runtime/Serving modules	154
Integration modules	27
Research/Experimental modules	204
Domainpack files	36
Rust kernel files	97
Optional extras	23
Python test files	851
Public documentation pages	229
GitHub Actions workflows	12

Evidence boundary: this snapshot is a static inventory. Performance, coverage, hardware, and scientific-fidelity claims require their own committed evidence artifacts.

What It Does

Treats Kuramoto phase dynamics as a universal synchrony state-space. Any hierarchical coupled-cycle system — plasma, cloud infrastructure, traffic, power grids, factories, biology — maps onto the same engine.

In plain terms: if a system has repeating behaviour, SPO helps determine whether the repetitions are synchronising, whether that synchrony is useful or dangerous, and which bounded intervention should be reviewed next.

SPO then separates three questions that are often mixed together:

1. Observation: what cycles, events, and states are present?
2. Evidence: which phase relationships are coherent, unstable, causal, or unsafe?
3. Action: which bounded knob could change the regime without bypassing review, safety tier, or replay evidence?

Core Pipeline

Domain Binder → Oscillator Extractors (P/I/S) → UPDE Engine → Supervisor → Actuation Mapper

Each stage has a production reason to exist:

Stage	Production purpose	Failure mode it prevents
Domain Binder	makes assumptions explicit before execution	hidden notebook logic and unreviewed signal mappings
Extractors	normalise waves, events, and states into phase	comparing incompatible telemetry directly
UPDE Engine	evolves coupled dynamics under reproducible numerics	hand-tuned synchrony claims without equations
Supervisor	classifies regimes and proposes bounded actions	uncontrolled changes to sensitive knobs
Actuation Mapper	translates proposals into reviewed adapter contracts	direct hardware writes without replay or rate limits

3-Channel Oscillator Model

Channel	Source	Phase Extraction
Physical (P)	Continuous waveforms	Hilbert transform, zero-crossing
Informational (I)	Event/decision streams	Event-phase from message timing
Symbolic (S)	Discrete state sequences	Ring-phase θ=2πs/N, graph-walk

4 Universal Control Knobs

Knob	Meaning
K	Coupling strength (Knm matrix)
α	Phase lag (transport/actuator delays)
ζ	Driver strength (external forcing)
Ψ	Reference phase (control target)

Dual Objective

• R_good: Coherence to maintain (actuator ↔ target phase-lock)
• R_bad: Coherence to suppress (harmful mode-locking)

Capabilities

Differentiable Phase Dynamics (nn/ module, JAX)

nn/ is the primary API for ML users. It exposes JAX/equinox layers and runtime checks directly from scpn_phase_orchestrator.nn, and can run on GPU/TPU; require_accelerator() lets training jobs fail fast when no accelerator backend is visible.

from scpn_phase_orchestrator.nn import (
    KuramotoLayer,
    jax_runtime_info,
    require_accelerator,
)

print(jax_runtime_info())
device = require_accelerator()  # raises on CPU-only JAX runtimes

Module	What it does
KuramotoLayer	Phase-only oscillator layer (equinox), learnable K and ω
StuartLandauLayer	Phase + amplitude layer, bifurcation parameter μ
Simplicial Kuramoto	3-body higher-order coupling (Gambuzza 2023)
BOLD Generator	Balloon-Windkessel hemodynamic model for fMRI
Reservoir Computing	Kuramoto network as nonlinear reservoir + ridge readout
SAF Spectral Loss	Topology optimization via Laplacian eigenstructure
UDE-Kuramoto	Physics backbone sin(Δθ) + learned neural residual
Inverse Pipeline	Infer coupling K and frequencies ω from observed data
OIM Graph Coloring	Oscillator Ising machine for combinatorial optimization
Differentiable Supervisor	Equinox policy for closed-loop K/zeta proposals with ControlAction adapter

All functions are JIT-compilable, vmap-compatible, and differentiable. Install: pip install scpn-phase-orchestrator[nn] For CI and smoke tests on CPU-only hosts, use require_accelerator(allow_cpu=True) explicitly.

Advanced Dynamics (upde/ module, NumPy)

Module	What it does
Inertial Kuramoto	Second-order swing equation for power grid stability
Market Kuramoto	Financial regime detection via Hilbert phase + order parameter
Swarmalator	Coupled spatial + phase dynamics (O'Keeffe 2017)
Simplicial Engine	3-body coupling with explosive transitions
Stuart-Landau Engine	Amplitude dynamics with Hopf bifurcation
Stochastic Engine	Euler-Maruyama with optimal noise (D* auto-tuning)
Geometric Engine	Torus-preserving symplectic integrator
Delay Engine	Time-delayed coupling with circular buffer
Ott-Antonsen	Exact mean-field reduction (O(1) prediction)

Closed-Loop Control

Module	What it does
MPC Supervisor	Predicts R trajectory 10 steps ahead via OA reduction
Regime Manager	FSM with hysteresis (NOMINAL/DEGRADED/CRITICAL)
Petri Net FSM	Formal state machine with guard conditions
Plasticity	Three-factor Hebbian coupling adaptation
TE Adaptive	Transfer entropy-based causal coupling updates
Audit Trail	SHA256-chained JSONL for deterministic replay

Analysis Toolkit

Order parameter, PLV, PAC (cross-frequency coupling), chimera detection, EVS (entrainment verification), PID (redundancy/synergy), Lyapunov exponent, entropy production, winding number, ITPC, coupling estimation (including non-sinusoidal harmonics), HCP connectome generation.

Detector Auditing (evaluation/)

Surface	What it does
audit_detector	Scores any detector's event-vs-null skill from per-segment scores at a matched false-alarm rate, with a label-permutation p-value
seal_detector_audit	Binds a verdict to its corpus provenance under a SHA-256 canonical-JSON hash
spo audit-detector	Same audit from a JSON scores file, without writing Python

Detector-agnostic: it judges the SCPN suite, an AR(1)/Kendall-τ baseline, or a black-box classifier on identical footing. See the auditor API.

Hardware Deployment

Target	Status
Rust FFI	12 PyO3 bindings for native-speed core modules
FPGA	16-oscillator Zynq-7020 kernel, sub-15μs latency
WebAssembly	Browser-based Kuramoto visualization, no server needed
JAX GPU	Transparent GPU acceleration via XLA

See Documentation Coverage for the current repo-wide documentation inventory and the enforced API-reference policy.

Additional Analysis Modules

Module	What it does
Hodge Decomposition	Splits coupling K into gradient / curl / harmonic components
Transfer Entropy	Directed causal information flow between oscillators
Coupling Estimation	Infer K from data (least-squares + higher harmonics)

Quickstart

Use this path when evaluating the package for the first time. It keeps the first run deterministic and reviewable before you move to a domain-specific binding or hardware-adjacent adapter.

# Install from PyPI
pip install scpn-phase-orchestrator

# Or with optional extras
pip install scpn-phase-orchestrator[queuewaves]  # FastAPI cascade detector
pip install scpn-phase-orchestrator[plot]         # matplotlib visualisation
pip install scpn-phase-orchestrator[otel]         # OpenTelemetry export

# Scaffold a new domainpack
spo scaffold my_domain

# Scaffold from natural-language intent with a configured LLM provider
spo scaffold traffic_grid --llm \
  --description "I am modelling traffic lights in a 4-intersection grid"

# Validate a domain binding spec
spo validate domainpacks/minimal_domain/binding_spec.yaml

# Run a domain simulation
spo run domainpacks/queuewaves/binding_spec.yaml --steps 1000

# Run a real-data review demo from PhysioNet heart-rate-belt data
spo demo --dataset heartbeat.csv --target coherence --steps 100

# Replay from audit log
spo replay audit.jsonl --output report.json

Python applications can use the high-level facade without invoking Click:

from scpn import Orchestrator

orch = Orchestrator.from_yaml("domainpacks/minimal_domain/binding_spec.yaml")
state = orch.run(steps=100, seed=42)
print(state.order_parameter)

Reference Benchmarks

SPO keeps reference benchmarks as reproducible evidence, not as marketing claims. The checked-in snapshot is dated 2026-06-14 and was generated with:

PYTHONPATH=.:src python benchmarks/reference_suite.py

The snapshot is published at docs/galleries/reference_benchmark_snapshot.md. It records the command, Python/Numpy versions, platform metadata, acceptance flags, local non-isolated evidence labels, and steps/s values for each suite. Selected reference suites:

Suite	Reference contract	Snapshot steps/s
kuramoto_reference_strogatz_2000	Strogatz/Acebron synchronisation plus exact two-oscillator locking acceptance	13096.772262633993
stuart_landau_reference_pikovsky_2001	Stuart-Landau Hopf limit-cycle and subcritical-decay acceptance	9921.368080173932
petri_net_reachability	Petri-net exact reachability, token-conservation, and cycle-period acceptance	196485.20274453718
chimera_polyglot_parity_gate	Kuramoto-Battogtokh local-order parity and chimera invariants across Rust/Mojo/Julia/Go/Python slots	9.181678783030513
itpc_polyglot_parity_gate	Lachaux ITPC vector and pause-persistence parity across Rust/Mojo/Julia/Go/Python slots	12.85877096230649
spectral_polyglot_parity_gate	Dorfler-Bullo Laplacian spectral parity and exact graph spectra across Rust/Mojo/Julia/Go/Python slots	3.0281704851806226
hodge_polyglot_parity_gate	Jiang Hodge gradient/curl/harmonic reconstruction parity and topological-flow invariants across Rust/Mojo/Julia/Go/Python slots	709.996494491663
embedding_polyglot_parity_gate	Takens delay-indexing, Fraser-Swinney mutual information, and nearest-neighbour geometry parity across Rust/Mojo/Julia/Go/Python slots	1458.6900385685083
transfer_entropy_polyglot_parity_gate	Schreiber transfer-entropy causal-direction and exact histogram matrix parity across Rust/Mojo/Julia/Go/Python slots	1104.6939041889623
entropy_production_polyglot_parity_gate	Acebron overdamped-Kuramoto dissipation parity and thermodynamic invariants across Rust/Mojo/Julia/Go/Python slots	947.4613610264757
pha_c_handoff_polyglot_parity_gate	PHA-C moving-frame handoff parity for merge-window evidence, signed safety margins, source digests, order-parameter evidence, and non-actuating record hashes	1251.3495582891803
pha_c_timeline_polyglot_parity_gate	PHA-C trajectory timeline parity for first-lock, lock-loss, reset-count, minimum signed margin, transition-hash, and tolerance-profile evidence	349.89231022902277
pha_c_acceptance_polyglot_gate	PHA-C end-to-end acceptance parity across spatial modulation, Doppler correction, moving-frame propagation, kinematic residual evidence, timeline conversion, Lean proof-obligation discharge, maximum dispersion/minimum margin evidence, and aggregate subgate evidence	29.446807795968102

Physics invariants are also executable as focused tests:

PYTHONPATH=src pytest tests/test_physics_benchmarks.py

The Kuramoto reference suite now records acceptance fields for zero self-coupling, bounded R, identical-oscillator coherence, and the exact two-oscillator locking law theta_2 - theta_1 = asin((omega_2 - omega_1) / (2K)). Focused physics tests also cover weak-coupling desynchronisation, coupling monotonicity, external-drive entrainment, Stuart-Landau limit cycles, subcritical decay, amplitude consensus, and zero-coupling independence. The Stuart-Landau record now also checks the uncoupled Hopf radius sqrt(mu) and subcritical amplitude decay before publishing acceptance. The Petri-net record checks a four-place safety automaton as a formal mathematics reference: every run must conserve exactly one token, visit the four reachable markings, follow the deterministic transition cycle, and finish on the analytically expected marking. The ITPC polyglot record checks the Lachaux inter-trial phase-coherence estimator across every declared backend slot, including unit coherence for aligned trials, zero coherence for opposite-phase trials, bounded pause persistence, and explicit unavailable-toolchain evidence. The chimera polyglot record checks the Kuramoto-Battogtokh local-order vector across every declared backend slot, including global phase-gauge invariance, synchronised unit local order, disconnected zero local order, the exact uniform-circle all-to-all reference, and explicit unavailable-toolchain evidence. The spectral polyglot record checks the Dörfler-Bullo combinatorial graph Laplacian contract across every declared backend slot, including algebraic connectivity parity, Fiedler-vector direction parity, non-negative spectral gap, zero row sums, positive semidefiniteness, and exact uniform-path plus complete-graph spectra. The Hodge polyglot record checks the Jiang-style decomposition of coupling flow into gradient, curl, and harmonic components across every declared backend slot. It requires exact reconstruction of total phase-weighted flow, near-zero harmonic residual for the clean symmetric plus antisymmetric split, global phase-gauge invariance, zero curl for symmetric coupling, zero gradient for antisymmetric coupling, the two-node antisymmetric closed form, scale covariance, and explicit unavailable-toolchain evidence. The embedding polyglot record checks the Takens delay-coordinate construction used before nonlinear-state reconstruction. It requires exact delay indexing, time-shift row consistency, Fraser-Swinney mutual-information non-negativity and constant-signal zero behaviour, zero-lag information dominance over a distant lag, nearest-neighbour self-exclusion on a line lattice, direct primitive parity where a backend exposes the primitive, and public dispatch parity for the complete Rust/Mojo/Julia/Go/Python fallback chain. The transfer-entropy polyglot record checks the Schreiber histogram estimator used for directed information flow. It requires direct scalar parity, pairwise-matrix parity, scalar-matrix consistency for TE(i -> j), zero matrix diagonal, non-negative entropy-bounded scores, preservation of a known causal direction, phase-wrapping invariance, short-series zero behaviour, public fallback-dispatch parity, and explicit unavailable-toolchain evidence. The entropy-production polyglot record checks the Acebrón overdamped-Kuramoto dissipation rate. It requires exact formula parity against sum(dtheta_dt ** 2) * dt, non-negative rates, zero dissipation at fixed points and zero timestep, linear timestep scaling, quadratic scaling under the global coupling scalar when natural frequencies are zero, global phase-gauge invariance, oscillator permutation invariance, public fallback-dispatch parity, and explicit unavailable-toolchain evidence.

The PHA-C reference rows check the downstream accelerator acceptance chain: moving-frame handoff records, trajectory timeline records, and the aggregate spatial/Doppler/moving-frame/merge-window acceptance record. They keep the claim boundary review-only and non-actuating while making the full PHA-C chain visible in the canonical benchmark snapshot. The merge-window row now requires wrapped phase dispersion, axial spatial dispersion, consecutive joint locks, tolerance-profile evidence, and signed-margin equation replay before downstream handoff records consume the report. Each downstream PHA-C row now requires hash-replay validation of the canonical handoff, timeline, or acceptance payload before acceptance, so tampered scalar evidence and unsafe claim-boundary edits are rejected without needing the original raw arrays. The same rows also publish signed phase/spatial margins: per-sample margins in the handoff, minimum trajectory margins in the timeline, and aggregate maximum dispersion/minimum margin evidence in the acceptance record. Merge-window, handoff, timeline, and acceptance benchmark rows expose signed-margin equation validation so the reviewed margin must equal tolerance minus maximum dispersion for both phase and spatial evidence. Moving-frame and acceptance rows also sign the ballistic axial certificate z[t+1] = z[t] + v[t] * dt, max absolute velocity, and path-length evidence so polyglot phase parity cannot mask a mechanically invalid coordinate update; moving-frame rows now publish explicit equation validation for final position, maximum absolute velocity, and path length, and acceptance rows now require the same kinematic equation validation before the aggregate PHA-C chain can pass. Merge-window, handoff, and acceptance benchmark rows also publish phase_margin_equation_validated, spatial_margin_equation_validated, signed_margin_equations_validated, and margin_replay_tolerance; the gate fails unless every declared backend row proves min_margin = tolerance - max_dispersion for both phase and spatial evidence. Acceptance rows additionally emit and verify a PHACKinematicProofObligation manifest that maps the accepted runtime envelope onto SPOFormal.Kinematic.KinematicBounds and requires the Lean manifest to carry the acceptance record's kinematic equation replay status, so formal review remains bound to mechanically valid moving-frame summaries. The row must discharge the combined KinematicBounds.acceptanceCertificate predicate through acceptance_certificate_discharges_runtime_preconditions, which joins the spatial Gronwall budget, phase-budget certificate, and acceptance kinematic-equation replay certificate before the row can pass. The Rust, Go, Julia, and Mojo downstream rows are explicitly labelled as source-contract validation rows until native downstream kernels land; native_kernel_count remains zero in the current snapshot. The manifest carries the terminal Gronwall budget, signed Gronwall margin, and budget-trace hash, which keeps non-zero Lipschitz gain envelopes reviewable instead of forcing every PHA-C formal handoff into a zero-gain replay. It also carries the sampled time-step, horizon-time, velocity-rate, and residual-rate assumptions used to derive the discrete Lean drive bound. The residual lane now records explicit configured coupling-residual slack as separate provenance from the observed moving-frame kinematic residual, so MIF/FRC consumers can review predictive residual envelopes without overloading the relative-velocity term. The continuous-rate layer is explicit in every benchmark row. The formal manifest also targets SPOFormal.Continuous, where per-second drive rates are sampled over the full reviewed horizon and discharged by continuous_envelope_certificate_discharges_horizon before the row can pass.

Timing fields in the checked-in reference snapshot are local regression and parity evidence unless the run metadata states CPU/core isolation and host-load controls. They are not production throughput claims by themselves.

Hardware Integration Boundary

Real hardware access is adapter-scoped and opt-in:

Surface	Status	Safety boundary
BrainFlow sensor input	Optional real EEG/PPG/EMG read adapter	requires brainflow; no actuation writes
Modbus/TLS SCADA	Optional real PLC/DCS read/write adapter	mutual TLS client certs plus mandatory server verification
Plain Modbus TCP	Lab/isolated-network adapter	not for production writes across routable networks
Quantum/neuromorphic targets	Review artefact generation	execution and hardware writes remain disabled

Hardware deployment details are documented in docs/guide/adapters.md. Quantum and neuromorphic compiler outputs are intentionally handoff artefacts until a verified external hardware execution pipeline is attached.

For development, clone the repo and install in editable mode:

git clone https://github.com/anulum/scpn-phase-orchestrator.git
cd scpn-phase-orchestrator
pip install -e ".[dev]"

For a role-based first-hour path, see the Onboarding Handbook. For the full notebook, example, and interactive demo inventory, see Notebooks & Demos. For market-facing and domain-facing orientation, see the Use Cases and Value Map.

Release and Evidence Posture

Surface	Current posture	Where to verify
Documentation	MkDocs public site with onboarding, tutorials, API references, guides, notebooks, and roadmap	mkdocs build, docs/index.md, and mkdocs.yml
Capability inventory	generated static counts, not edited by hand	tools/capability_manifest.py and docs/_generated/
Benchmarks	regression gate and dated reference snapshots	bench/, benchmarks/, and docs/galleries/reference_benchmark_snapshot.md
Security	CodeQL, dependency scanning, secret scanning, ingress hardening, and safe config loaders	GitHub Security tab and security docs
Release	semantic versioned package metadata and changelog	pyproject.toml, CHANGELOG.md, tags, and GitHub releases

Production Judgement Checklist

Before presenting an SPO result as operational evidence, capture:

Requirement	Evidence
Domain assumptions	reviewed binding spec, source mapping, and safety tier
Numerical path	engine, solver, timestep, seed, and backend status
Replayability	hash-linked audit log plus spo replay --verify output
Benchmark context	command, platform, dependency versions, and isolation label
Human review	bounded ControlAction proposal and projector limits
Documentation route	guide, tutorial, notebook, or API page for the used surface

If one of these entries is missing, treat the result as exploratory until the evidence is attached.

Platform Support

Platform	Python engine	Rust FFI (optional)
Linux	Full	Full
macOS	Full	Full
Windows	Full	Experimental (requires MSVC toolchain)

The PyPI package is pure Python. Rust FFI provides optional acceleration and is built from source into the selected Python environment with python tools/install_spo_kernel.py --release or make bridge PYTHON=.venv/bin/python.

Domainpacks

Pack	Domain	Purpose
autonomous_vehicles	Vehicles	Platoon phase-locking, leader-follower sync (3 layers, 8 oscillators)
bio_stub	Biology	Multi-scale biological oscillators (4 layers, 16 oscillators)
cardiac_rhythm	Cardiology	Gap-junction coupling, arrhythmia (4 layers, 10 oscillators)
chemical_reactor	Process control	Hopf bifurcation, Semenov limit (4 layers, 10 oscillators)
circadian_biology	Chronobiology	SCN clock-gene coupled oscillators (4 layers, 10 oscillators)
digital_twin_nchannel	Digital twins	Six-channel plant/twin residual profile with derived TwinResidual
edge_consensus_nchannel	Edge orchestration	Six-channel gossip consensus with load/trust coupling
epidemic_sir	Epidemiology	Epidemic wave synchronisation (3 layers, 8 oscillators)
firefly_swarm	Ecology	Flash synchronisation, Mirollo-Strogatz (2 layers, 8 oscillators)
fusion_equilibrium	Fusion equilibrium	Grad-Shafranov + FusionCoreBridge (6 layers, 12 oscillators)
geometry_walk	Graph systems	Random-walk phase coupling (2 layers, 8 oscillators)
laser_array	Photonics	Semiconductor laser phase-locking (3 layers, 8 oscillators)
manufacturing_spc	Manufacturing	Statistical process control (3 layers, 9 oscillators)
metaphysics_demo 🔬	P/I/S showcase	Imprint + geometry ablation (3 layers, 7 oscillators)
minimal_domain	Synthetic	Minimal-but-complete pipeline example (2 layers, 4 oscillators)
network_security	Cybersecurity	Traffic anomaly detection, DDoS suppression (3 layers, 8 oscillators)
neuroscience_eeg	Neuroscience	EEG band->phase, seizure detection (6 layers, 14 oscillators)
plasma_control	Tokamak plasma	MHD/transport multi-scale control (8 layers, 16 oscillators)
pll_clock	Telecommunications	PLL network clock synchronisation (3 layers, 8 oscillators)
power_safety_nchannel	Power systems	Six-channel grid safety profile with derived Risk
power_grid	Power systems	Swing equation = Kuramoto (5 layers, 12 oscillators)
quantum_simulation	Quantum computing	Qubit register phase coupling (3 layers, 8 oscillators)
queuewaves	Cloud/queues	Retry storm desynchronisation (3 layers, 6 oscillators)
rotating_machinery	Vibration	Harmonics, ISO 10816 boundaries (4 layers, 10 oscillators)
satellite_constellation	Aerospace	Orbital slot synchronisation, beam handover (3 layers, 8 oscillators)
swarm_robotics	Robotics	Vicsek collective motion (3 layers, 8 oscillators)
traffic_flow	Transportation	Signal coordination = phase sync (4 layers, 10 oscillators)
financial_markets	Finance	Stock synchronization, crash detection
gene_oscillator	Synthetic biology	Repressilator quorum coupling
vortex_shedding	Fluid dynamics	Wake station Stuart-Landau
robotic_cpg	Robotics	Joint CPG locomotion
sleep_architecture	Sleep medicine	AASM sleep staging from R
musical_acoustics	Acoustics	Consonance = R, groove = alpha
brain_connectome	Neuroscience	HCP-inspired coupling
agent_coordination	Multi-agent coordination	Heartbeat, task, and topic synchronisation
identity_coherence 🔬	Consciousness	SSGF identity model (6 layers, 30 oscillators)

🔬 metaphysics_demo and identity_coherence are broader SCPN ecosystem — experimental research domains: they exercise the pipeline but make no empirical claim and are not part of the validated clinical/grid product surface.

Adding a Domain

1. Create domainpacks/<name>/binding_spec.yaml declaring layers, oscillator families, coupling, drivers, objectives, and boundaries.
2. Optionally add policy.yaml for declarative supervisor rules.
3. Validate: spo validate domainpacks/<name>/binding_spec.yaml
4. Run: spo run domainpacks/<name>/binding_spec.yaml --steps 1000

See metaphysics_demo for a full example exercising all three channels, imprint modulation, geometry projection, and policy-driven control. Spec format reference: binding_spec.schema.json.

Development

pip install -e ".[dev]"
ruff check src/ tests/
ruff format --check src/ tests/
pytest tests/ -v --tb=short
mkdocs build

License

AGPL-3.0-or-later. Commercial licensing available — contact [e-mail].

Citation

See CITATION.cff.

---

    
Developed by ANULUM / Fortis Studio