NeuralRelay Modulator Messages

This reference defines the relay vocabulary used when RAS sends a modulator signal through Neuromodulators via a terminal registered to NeuralRelay.

The contract is transport-agnostic. It defines semantic payloads only, whether messages are carried via in-process relay, HTTP, WebSocket, NATS, or Kafka.

Communication defaults

These defaults are normative unless a future contract explicitly overrides them.

1. In this flow, all inter-component communication MUST be sent and received through terminals registered to NeuralRelay.
2. Interaction is asynchronous and transmission-driven; components delegate and react instead of synchronously waiting.
3. Broadcast fanout defaults to null outcome per receiver unless that receiver emits an explicit transmission.
4. Silent synthesizers are the expected default for non-matching broadcasts.

How the protocol works

RAS passes a single ModulatorSignal to Neuromodulators. From the outside, the black-box contract is just signal in, mediated transmission out through a terminal registered to NeuralRelay. Internal synthesis fanout is an implementation detail of the orchestrator and is not part of this section’s external contract.

sequenceDiagram
    participant RAS
    participant NM as Neuromodulators
    RAS->>NM: ModulatorSignal
    NM-->>RAS: ModulatorSuccess (artifact-ref: neuromodulators/dopamine-instance-42)

The outer protocol is contract-level metadata, not a transport for the live Python object itself. A synthesizer creates the concrete modulator instance in its local runtime and publishes it through Neuromodulators. Neuromodulators then emits a single external transmission carrying the runtime reference through its registered terminal into NeuralRelay for distribution. The registry and object-resolution step are handled elsewhere; this page stays focused on the relay message contract.

Scope

This contract standardizes the external message families visible between RAS and Neuromodulators:

1. ModulatorSignal — from RAS to Neuromodulators.
2. ModulatorResult as the base outcome type, with concrete ModulatorSuccess and ModulatorFailure subtypes from Neuromodulators back to RAS.

The internal broker-to-synthesizer messages are intentionally distinct: SynthesisBroadcast and SynthesisReply describe the internal work of producing the single signaled modulator and are not part of the external RAS contract.

Scope note: this contract documents the relay-bound modulation path. Axis-based direct substrate-to-substrate transport is outside this contract.

If you are reading this as a black-box boundary, stop here. The broadcast step belongs to the ModulatorOrchestrator implementation and should be understood as an internal mediation detail, not as part of the external message contract.

Interaction points

The protocol defines both logical addresses and code-level interaction points.

Logical addresses:

1. RAS signal destination: relay://neuromodulators.main (or environment-specific equivalent)
2. Neuromodulators reply destination: the external relay channel used for reply transmissions
3. Internal broker fanout destination (owned by ModulatorOrchestrator inside Neuromodulators): relay://synthesizers.broadcast using SynthesisBroadcast
4. Runtime object registry: reserved for the later Neuromodulators runtime contract and not part of this message reference

Orchestrator interaction notes:

1. ModulatorOrchestrator broadcasts a SynthesisBroadcast to all registered Synthesizer implementations.
2. Eligible synthesizers reply with a SynthesisReply on the relay channel; silent or late synthesizers are ignored.
3. ModulatorOrchestrator emits a single ModulatorSuccess or ModulatorFailure transmission onto the relay channel.
4. A downstream consumer may observe the returned artifact-ref and resolve it through a later runtime contract.

These names are the minimum vocabulary expected across package boundaries.

Broadcast and reply behavior:

1. SynthesisBroadcast has a null default outcome; non-matching synthesizers remain silent.
2. SynthesisReply is an explicit return-path transmission on the relay channel.

Ontology alignment

This vocabulary follows the Intent-Capability pattern and aligns with W3C semantic agent communication concepts.

Cerebel message role	Ontology concept	Meaning in this contract
ModulatorSignal	Intent	RAS declares the desired modulator outcome.
Synthesizer self-selection	Capability	Each synthesizer internally matches the signal against its own registered capability and only replies if it can contribute.
ModulatorResult	ExecutionRecord	Neuromodulators-issued result object for the signaled modulator, resolved to a concrete success or failure subtype.
Signal or reply envelope	CommunicativeAct	Atomic interaction carrying the signal or reply payload.

Relay envelope

Runtime messages in this flow use the NeuralRelay transmission models directly.

Common transmission fields:

Field	Type	Required	Constraints
transmission_id	str	yes	non-empty, globally unique
timestamp	RFC3339 datetime	yes	UTC required
source	str	yes	sender identity, for example ras.main or neuromodulators.main
link	str	conditional	correlation key tying related transmissions together
metadata	object	no	transport and tracing metadata
payload	object	yes	domain payload for the transmission kind

Signal-specific fields:

Field	Type	Required	Constraints
signal_type	str	yes	for this contract: modulator.signal

Broadcast-specific fields:

Field	Type	Required	Constraints
broadcast_type	str	yes	for internal synth fanout: synthesis.broadcast

Reply-specific fields:

Field	Type	Required	Constraints
success	bool	yes	true for success replies, false for failure replies
error	str	no	failure summary when success=false

Rules:

1. link MUST remain stable across the originating ModulatorSignal, subsequent SynthesisBroadcast, and all related SynthesisReply and external result replies.
2. Correlation to the originating ingress signal SHOULD be carried in payload.in_response_to when a producer needs explicit causality in addition to link.
3. Unknown top-level fields SHOULD be rejected for strict runtime contracts.

Message type: ModulatorSignal

Signal purpose

Signal from RAS to Neuromodulators stating the intent to obtain a single concrete modulator for a substrate lifecycle action. Neuromodulators broadcasts that signal to all registered synthesizers and reacts to explicit synthesis reply transmissions; silent receivers remain null by default.

Signal message-type

modulator.signal

Signal payload

ModulatorSignal.payload contains a single signal for one concrete modulator.

Field	Type	Required	Constraints
modulator-name	str	yes	concrete modulator name to produce; should already be validated by application layer and DomainBundle before dispatch to RAS
parameters	object mapping	no	signal-scoped hints passed to the synthesizer

Signal example

{
  "transmission_id": "4f9d7e12-89cf-4dd1-b4d6-4d8e7ea4c4f2",
  "signal_type": "modulator.signal",
  "timestamp": "2026-08-15T12:10:00Z",
  "source": "ras.main",
  "link": "c4d1b55d-3a08-41b8-b2af-7b21f8b13f42",
  "metadata": {},
  "payload": {
    "modulator-name": "dopamine",
    "parameters": {
      "window_tokens": 16000,
      "temperature": 0.2
    }
  }
}

Message type: ModulatorResult

Result purpose

Base outcome object emitted by Neuromodulators after a synthesize attempt. A successful child result indicates that a signaled modulator has been produced and published under an artifact-ref. A failure child result indicates the signal could not be satisfied. By the time a signal reaches RAS, the list of required modulators and the synthesizers registered to produce them have already been validated by the application layer and DomainBundle. Each synthesizer knows what it produces; Neuromodulators emits a result after it receives a produced modulator instance or an explicit failure.

Result message-type

Relay Reply transmission.

Result payload

ModulatorResult.payload is emitted through the concrete ModulatorSuccess or ModulatorFailure subtype.

ModulatorSuccess.payload fields:

Field	Type	Required	Constraints
synthesizer-id	str	yes	non-empty synthesizer identifier
artifact-ref	str	yes	resolves to the concrete Python instance stored in Neuromodulators

ModulatorFailure.payload fields:

Field	Type	Required	Constraints
code	str	yes	canonical Neuromodulators error code
synthesizer-id	str	no	origin synthesizer when known
diagnostics	object	no	machine-readable diagnostics payload

At envelope level, result replies carry success and optional error, consistent with the base Reply transmission contract.

Result example

{
  "transmission_id": "9a1c2d33-11ab-4ef2-a901-8f3b77cc1200",
  "timestamp": "2026-08-15T12:10:00Z",
  "source": "neuromodulators.main",
  "link": "c4d1b55d-3a08-41b8-b2af-7b21f8b13f42",
  "success": true,
  "error": null,
  "metadata": {},
  "payload": {
    "synthesizer-id": "cortex-lamina-synthesizer",
    "artifact-ref": "neuromodulators/dopamine-instance-42"
  }
}

Message type: ModulatorSuccess

Success result purpose

ModulatorSuccess is the concrete success subtype of ModulatorResult. It indicates that a synthesizer produced the signaled modulator and published it under an artifact-ref in Neuromodulators.

Success payload

ModulatorSuccess carries the same minimal result shape as its base, with the additional success-specific requirement that artifact-ref be present and resolvable.

Message type: ModulatorFailure

Failure result purpose

ModulatorFailure is the concrete failure subtype of ModulatorResult. It indicates that the signal could not be satisfied, either because no synthesizer matched or an explicit failure condition was raised.

Failure payload

ModulatorFailure carries the base Reply envelope with success=false, optional error, and a payload containing canonical failure code and diagnostics.

Diagnostics code convention:

1. payload.code MUST use the NM_ prefix for Neuromodulators canonical error codes.
2. NM_ is an explicitly approved abbreviation for Neuromodulators error namespaces.
3. Producers SHOULD emit these codes in upper-snake-case to match the Neuromodulators reference.

Runtime handoff model

The message contract does not carry the instantiated Python object directly. Instead, synthesizer runtimes create actual modulator instances and store them in Neuromodulators. Neuromodulators returns a ModulatorSuccess child result with an artifact-ref pointer. Each artifact-ref is resolved by RAS so the resulting transmission can arrive through a terminal registered to NeuralRelay before the concrete object instance is bound into the runtime cocktail for substrate consumption.

This keeps the transport layer minimal and lets RAS stay focused on the mediated result: it does not need a description of how the modulator was built, only the handle to the concrete result it was asked to produce.

Execution provenance and logging

This reference defines the minimum contract exchanged through terminals registered to NeuralRelay. It deliberately does not include the full synthesizer execution record; the base ModulatorResult is intentionally thin, while child classes carry the outcome details.

The synthesizer runtime SHOULD record richer provenance in its own execution log or audit trail, including:

• the concrete modulator name that was actually produced
• the version resolved during synthesis
• the actual parameter values used at runtime
• the synthesis strategy or factory path used to create the instance
• the source package or artifact metadata used to build it
• execution timing and diagnostics for success, failure, or partial synthesis

This information is operationally important for observability, debugging, and reproducibility, but it is not part of the minimal message contract because RAS only needs the runtime handoff reference to place the resolved result onto NeuralRelay and let the substrate consume it from the updated cocktail through its terminal.

In other words, the network contract answers the question: “did the synthesizer produce the signaled modulator and where is it?” The execution record answers the question: “what exactly was produced, with which version and configuration, and how did it happen?”

The two concerns should remain separate: the ModulatorResult message stays small and transport-focused, while the synthesizer’s execution log captures the full provenance trail.

Pydantic DTO readiness

This contract is intended to be directly representable as strict Pydantic models.

Recommended DTO set:

1. ModulatorSignalPayloadDTO
2. ModulatorSuccessPayloadDTO
3. ModulatorFailurePayloadDTO
4. SynthesisBroadcastPayloadDTO
5. SynthesisReplyPayloadDTO
6. Relay envelope models inherited from Signal, Broadcast, and Reply

Minimum validation rules to encode:

1. signal_type must be modulator.signal for ingress signals.
2. broadcast_type must be synthesis.broadcast for internal fanout broadcasts.
3. Reply envelopes must carry success and optional error as defined by the base Reply model.
4. artifact-ref must match ^neuromodulators/[A-Za-z0-9._:-]+$ for ModulatorSuccess.payload.
5. payload.code in failure payloads should be a canonical NM_ error code.
6. Unknown payload fields should be rejected with extra="forbid".

Example DTO sketch:

from datetime import datetime
from typing import Any, Literal

from pydantic import BaseModel, ConfigDict, Field, model_validator


class ResultDiagnosticsDTO(BaseModel):
  model_config = ConfigDict(extra="forbid")
  stage: str | None = None
  reason: str | None = None
  message: str | None = None


class ModulatorSuccessPayloadDTO(BaseModel):
  model_config = ConfigDict(extra="forbid")
  synthesizer_id: str = Field(alias="synthesizer-id", min_length=1)
  artifact_ref: str = Field(alias="artifact-ref", pattern=r"^neuromodulators/[A-Za-z0-9._:-]+$")


class ModulatorFailurePayloadDTO(BaseModel):
  model_config = ConfigDict(extra="forbid")
  code: str
  synthesizer_id: str | None = Field(default=None, alias="synthesizer-id")
  diagnostics: dict[str, Any] = Field(default_factory=dict)

With these DTOs and rules, the modulation message layer is strict enough for contract-first implementation.

Handoff readiness checklist

The flow is ready to hand off when all items below are true:

1. A RAS implementation publishes ModulatorSignalPayloadDTO through its terminal into NeuralRelay.
2. Neuromodulators validates the signal envelope and fans it out to registered synthesizers.
3. Synthesizers reply explicitly or remain silent.
4. Neuromodulators publishes Reply transmissions carrying ModulatorSuccess.payload or ModulatorFailure.payload back to RAS.
5. Failed response paths emit canonical diagnostics and stop affected modulation steps explicitly.
6. Envelope and payload DTOs run with strict validation (extra="forbid") in both request and response directions.
7. Integration tests cover RAS signal publication, Neuromodulators fanout, synthesizer self-selection, response handling, and failure paths.

Compatibility and evolution

1. semantic-version follows Semantic Versioning 2.0.0.
2. Minor version updates MAY add optional fields only.
3. Major version updates MAY remove or rename fields.
4. Producers and consumers MUST fail fast on unknown required semantics.

Security and trust recommendations

1. Require synthesizer identity verification before RAS accepts a response.
2. Use signed ModulatorResult entries where audit guarantees are required.
3. Scrub sensitive fields before long-term storage, consistent with NeuralRelay policy.

Relationship to other contracts

1. RAS Bridge Contract: launch handoff boundary where this modulation exchange occurs before the runtime is returned.
2. Substrate Core Contracts: substrate identity and lifecycle fields referenced by substrate-ref.
3. Substrate Package Requirements: package obligations for synthesizer behavior and modulation injection.
4. Naming Conventions: naming conventions for Signal, Response, Synthesizer, and Modulator roles.
5. Neuromodulators Contract: normative runtime registry contract and interfaces used by synthesizers and RAS.